environment-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Environment Setup

环境搭建

Outcome

预期结果

Produce an isolated environment, explicit dependency record, and machine-readable verification report for the selected analysis. Install only the public scientific libraries and loaders the work actually requires.

Read the verification checklist while verifying a new environment and the troubleshooting guide when an install, import, output, or loader probe fails.

为选定的分析任务生成隔离环境、明确的依赖记录以及机器可读的验证报告。仅安装工作实际所需的公开科学库和加载器。

验证新环境时，请阅读验证清单；当安装、导入、输出或加载器探测失败时，请查阅故障排除指南。

When to Use This Skill

使用场景

Use when:

onboarding a new machine or project for sports analysis;
diagnosing broken imports, wrong interpreters, or conflicting packages;
locking a reproducible environment before serious modeling;
verifying that selected skill helpers and loaders work offline at
```
--help
```
.

Do not use this skill to:

install the optional repository toolkit / bridge path →
```
sports-ds-bridge
```
;
choose a public data source →
```
data-sources
```
;
run EDA or modeling once the environment already works.

Need	Go instead
Optional toolkit bridge	`sports-ds-bridge`
Source selection	`data-sources`
Analysis after setup	the relevant modeling skill

在以下场景中使用此技能：

为体育分析配置新机器或新项目；
诊断导入失败、解释器错误或包冲突问题；
在正式建模前锁定可复现的环境；
验证选定的技能助手和加载器在离线状态下运行
```
--help
```
是否正常。

请勿使用此技能进行以下操作：

安装可选的仓库工具包/桥接路径 →
```
sports-ds-bridge
```
；
选择公开数据源 →
```
data-sources
```
；
环境正常运行后执行探索性数据分析（EDA）或建模。

需求	替代方案
可选工具包桥接	`sports-ds-bridge`
数据源选择	`data-sources`
环境搭建后的分析	相关建模技能

Plan before installing

安装前规划

Record operating system/architecture, Python version and executable, analysis tasks, named loaders, required file/plot formats, CPU/memory/storage constraints, network/proxy constraints, and whether exact reproduction or flexible minimum versions are needed. Separate core packages from optional loaders and dev tools.

记录操作系统/架构、Python版本和可执行文件、分析任务、指定加载器、所需文件/图表格式、CPU/内存/存储限制、网络/代理限制，以及是否需要精确复现或灵活的最低版本。将核心包与可选加载器和开发工具分开。

Create an isolated environment

创建隔离环境

bash

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install numpy pandas scipy scikit-learn statsmodels matplotlib pyarrow

On Windows PowerShell use

.venv\Scripts\Activate.ps1

. Use

python -m pip

so the installer follows the active interpreter. Do not modify the system Python.

Install public loaders only when the source plan requires them:

bash

python -m pip install nflreadpy
python -m pip install pybaseball
python -m pip install sportsdataverse

Do not install every loader “just in case”; optional native/transitive dependencies add conflicts and weaken reproducibility.

bash

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install numpy pandas scipy scikit-learn statsmodels matplotlib pyarrow

在Windows PowerShell中使用

.venv\Scripts\Activate.ps1

。使用

python -m pip

确保安装器遵循当前激活的解释器。请勿修改系统Python。

仅当源计划需要时才安装公开加载器：

bash

python -m pip install nflreadpy
python -m pip install pybaseball
python -m pip install sportsdataverse

请勿“以防万一”安装所有加载器；可选的原生/传递依赖会增加冲突并降低可复现性。

Verification ladder

验证步骤

Work from cheapest/local to bounded/networked. Stop at the first unexplained failure; later successes do not erase it.

Record
```
python --version
```
, executable path, platform, and
```
python -m pip --version
```
.
Confirm Python and pip resolve inside the same environment.
Import the minimum scientific packages and record resolved versions.
Run every selected helper or loader's
```
--help
```
; help must not make a network call.
Test required local outputs: JSON, Parquet, and images as applicable.
If network is authorized, run one small bounded public-data sample.
Save the verification report; freeze dependencies only after success.
Recreate from the lock in a clean environment for high-stakes reproducibility.

bash

python /path/to/environment-setup/scripts/verify_install.py
python /path/to/environment-setup/scripts/verify_install.py \
  --packages numpy,pandas,sklearn --out data/environment.json
python -m pip freeze > requirements-lock.txt

The portable verifier accepts comma-separated import names through

--packages

. Import names can differ from distribution names (

sklearn

versus

scikit-learn

); document both when that matters.

The verifier checks the current interpreter,

python -m pip

, and the requested imports only. Its JSON lists helper, output, network, and lock-recreation checks as not run;

OK

is therefore not full environment sign-off. A standard-library venv is detected from Python prefixes, but other environment managers may not be. Run and document the remaining ladder steps separately. On a completed probe, stdout is exactly one JSON document; package import output is captured inside the relevant package result. With

--out

, the same JSON is also written to that path, and no human status line is mixed into stdout.

从成本最低/本地的检查逐步过渡到受限/联网的检查。遇到第一个无法解释的失败时停止后续检查；后续成功无法抵消之前的失败。

记录
```
python --version
```
、可执行文件路径、平台以及
```
python -m pip --version
```
。
确认Python和pip在同一环境中解析。
导入最小化的科学包并记录解析后的版本。
运行每个选定助手或加载器的
```
--help
```
；帮助信息不得发起网络调用。
测试所需的本地输出：JSON、Parquet和图像（如适用）。
如果允许联网，运行一个小型的受限公开数据样本。
保存验证报告；仅在成功后冻结依赖项。
为了高可信度的可复现性，在干净环境中从锁定文件重新创建环境。

bash

python /path/to/environment-setup/scripts/verify_install.py
python /path/to/environment-setup/scripts/verify_install.py \
  --packages numpy,pandas,sklearn --out data/environment.json
python -m pip freeze > requirements-lock.txt

可移植验证器通过

--packages

接受逗号分隔的导入名称。导入名称可能与分发名称不同（例如

sklearn

与

scikit-learn

）；当这种差异重要时，请同时记录两者。

验证器仅检查当前解释器、

python -m pip

以及请求的导入项。其生成的JSON会将助手、输出、网络和锁定重建检查列为未运行；因此

OK

并不代表环境完全合格。验证器会通过Python前缀检测标准库venv，但可能无法检测其他环境管理器。请单独运行并记录剩余的验证步骤。完成探测后，标准输出将恰好是一个JSON文档；包导入输出会被捕获到相关的包结果中。使用

--out

参数时，相同的JSON也会写入指定路径，且标准输出中不会混入人工状态行。

Verification matrix

验证矩阵

Layer	Probe	Pass evidence
Interpreter	version, executable, prefixes	intended environment path/version
Installer	`python -m pip --version`	pip invoked by that exact interpreter
Core imports	minimal package list	import + resolved versions (covered by verifier)
Skill helpers	`--help`	usage text, status 0, no network
File formats	tiny round trip	readable output in user-owned path
Loader import	lightweight import	module/version recorded
Network sample	bounded query	plausible rows + provenance
Reproduction	clean reinstall	same checks pass from lock

层级	探测内容	通过依据
解释器	版本、可执行文件、前缀	符合预期的环境路径/版本
安装器	`python -m pip --version`	pip由指定的解释器调用
核心导入	最小包列表	导入成功并记录解析后的版本（由验证器覆盖）
技能助手	`--help`	显示使用文本，状态码0，无网络调用
文件格式	小型往返测试	在用户自有路径中生成可读输出
加载器导入	轻量导入	记录模块/版本
网络样本	受限查询	生成合理的行数据及来源信息
可复现性	干净环境重新安装	从锁定文件重建后相同检查项通过

Troubleshooting by layer

分层故障排除

Symptom	Diagnose	Remediation
`ModuleNotFoundError`	active executable and exact import name	install named distribution in venv
install succeeds, import fails	compare Python/pip paths and architecture	reactivate; use `python -m pip`
Parquet write fails	engine and output permissions	install `pyarrow` ; test bounded path
loader request fails	network, provider, rate limit, requested coverage	retry bounded documented probe
native-library error	OS/CPU, wheel, native runtime	choose compatible version/install prerequisite
stale notebook import	kernel executable and process state	select venv kernel; restart
resolver conflict	incompatible constraints	isolate optional loader or revise pins explicitly
empty load	season/status/filter semantics	inspect request and provider coverage

Capture the complete error, command, interpreter, package versions, and minimal reproduction before changing dependencies. Never silently substitute a package or broaden versions until something happens to install.

症状	诊断方向	修复方案
`ModuleNotFoundError`	当前激活的可执行文件和精确的导入名称	在venv中安装指定的分发包
安装成功但导入失败	对比Python/pip路径和架构	重新激活环境；使用 `python -m pip`
Parquet写入失败	引擎和输出权限	安装 `pyarrow` ；测试受限路径
加载器请求失败	网络、提供商、速率限制、请求覆盖范围	重试受限的已记录探测
原生库错误	操作系统/CPU、wheel包、原生运行时	选择兼容版本/安装前置依赖
笔记本导入过时	内核可执行文件和进程状态	选择venv内核；重启内核
解析器冲突	不兼容的约束	隔离可选加载器或显式修订版本锁定
加载结果为空	赛季/状态/过滤语义	检查请求和提供商覆盖范围

在更改依赖项之前，捕获完整的错误信息、命令、解释器、包版本以及最小复现步骤。除非安装成功，否则请勿静默替换包或放宽版本限制。

Reproducibility policy

可复现性政策

Keep a human-edited dependency specification separate from a resolved lock. Record Python minor version, OS/architecture, package versions, loader versions, and relevant environment variables without secrets. Treat caches as performance artifacts, not provenance; data snapshots need their own source metadata.

Lock files are platform-sensitive. For multiple supported platforms, maintain and test explicit platform locks or a reproducible resolver workflow. A freeze from a contaminated environment is not a dependency design.

将人工编辑的依赖规范与解析后的锁定文件分开保存。记录Python次要版本、操作系统/架构、包版本、加载器版本以及相关环境变量（不含敏感信息）。将缓存视为性能优化产物，而非来源凭证；数据快照需要单独的源元数据。

锁定文件具有平台敏感性。对于多个支持的平台，请维护并测试明确的平台锁定文件或可复现的解析器工作流。受污染环境生成的冻结文件不能作为依赖设计的依据。

Worked example

示例演示

For a new NFL analysis: create

.venv

; install scientific packages and

nflreadpy

; run the verifier for

numpy,pandas,sklearn,nflreadpy

; run every selected helper's

--help

; perform a one-season or smaller authorized sample; write

environment.json

; inspect it; freeze dependencies; then repeat the local checks in a clean environment before claiming setup is reproducible.

针对新的NFL分析任务：创建

.venv

；安装科学包和

nflreadpy

；运行验证器检查

numpy,pandas,sklearn,nflreadpy

；运行每个选定助手的

--help

；执行一个赛季或更小范围的授权样本；生成

environment.json

；检查该文件；冻结依赖项；然后在干净环境中重复本地检查，之后才能确认环境搭建具备可复现性。

Output contract and integrity rules

输出合约与完整性规则

The complete sign-off should report Python version/executable, platform, requested distributions and import names, resolved versions, helper/loader probes, skipped network checks, output round trips, exact failures/remediations, and paths to report and lock. The portable verifier emits only the subset stated above and enumerates the checks it did not run.

Use an isolated environment and
```
python -m pip
```
.
Never hide failed imports, skipped checks, or platform limitations.
```
--help
```
must remain offline; network samples must be bounded and authorized.
Freeze only after verification; verify the lock by recreation when required.
Use
```
verify_checklist.md
```
for sign-off and
```
troubleshooting.md
```
for failure routing.

完整的验收报告应包含Python版本/可执行文件、平台、请求的分发包和导入名称、解析后的版本、助手/加载器探测结果、跳过的网络检查、输出往返测试结果、具体失败/修复措施，以及报告和锁定文件的路径。可移植验证器仅输出上述内容的子集，并列出未运行的检查项。

使用隔离环境和
```
python -m pip
```
。
不得隐藏导入失败、跳过的检查或平台限制。
```
--help
```
必须保持离线；网络样本必须受限且经过授权。
仅在验证通过后冻结依赖项；必要时通过重建环境验证锁定文件。
使用
```
verify_checklist.md
```
进行验收，使用
```
troubleshooting.md
```
排查故障。