用途：为选定分析构建隔离的 Python 环境、显式依赖记录和机器可读的验证报告。仅安装实际需要的公共科学库与加载器。验证新环境时参考验证清单，安装、导入、输出或加载器探测失败时参考故障排查指南。
适用场景：新机器或新项目上手体育分析；诊断导入失败、解释器错误或包冲突；在正式建模前锁定可复现环境；验证所选技能辅助脚本与加载器在离线 --help 下可用。不适用：安装可选仓库工具链/桥接（见 sports-ds-bridge）、选择公开数据源（见 data-sources）、环境可用后运行 EDA 或建模。
安装前需记录：操作系统/架构、Python 版本与可执行文件、分析任务、命名加载器、所需文件/图表格式、CPU/内存/存储与网络/代理限制、是否需要精确复现或灵活的最低版本。区分核心包与可选加载器、开发工具。
创建隔离环境（命令保持原样）：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。仅在源计划要求时安装公共加载器：python -m pip install nflreadpy；python -m pip install pybaseball；python -m pip install sportsdataverse。不要“以防万一”安装全部加载器。
验证阶梯（从最廉价/本地到有界/联网，遇首个无法解释的失败即停）：1) 记录 python --version、解释器路径、平台、python -m pip --version；2) 确认 Python 与 pip 在同一环境解析；3) 导入最小科学包并记录解析版本；4) 对每个所选辅助脚本或加载器运行 --help，且不得联网；5) 测试所需本地输出（JSON、Parquet、图片等）；6) 若网络获授权，运行一个小规模有界公共数据样本；7) 保存验证报告，成功后再冻结依赖；8) 高风险复现场景下在干净环境中按锁文件重建。
验证器用法：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，其他环境管理器可能无法识别。其余阶梯步骤需另行运行并记录。探测完成时 stdout 恰为一个 JSON 文档；使用 --out 时同一 JSON 也写入该路径，stdout 不混入人工状态行。
验证矩阵分层：解释器（版本、路径、前缀）；安装器（python -m pip --version，须由该解释器调用）；核心导入（最小包列表与解析版本，由验证器覆盖）；技能辅助脚本（--help，用法文本、状态 0、不联网）；文件格式（小规模往返，用户自有路径下可读输出）；加载器导入（轻量导入并记录模块/版本）；网络样本（有界查询，合理行数与来源）；复现（干净重装后同一批检查通过）。
故障排查按层：ModuleNotFoundError→检查活动解释器与精确导入名，在 venv 中安装指定发行包；安装成功但导入失败→比较 Python/pip 路径与架构，重新激活并使用 python -m pip；Parquet 写入失败→检查引擎与输出权限，安装 pyarrow 并测试有界路径；加载器请求失败→检查网络、提供方、速率限制与请求覆盖，重试有界记录探测；原生库错误→检查 OS/CPU、wheel、原生运行时，选择兼容版本或安装前置条件；笔记本导入陈旧→检查内核解释器与进程状态，选择 venv 内核并重启；解析器冲突→隔离可选加载器或显式修订版本固定；空加载→检查赛季/状态/筛选语义与提供方覆盖。更改依赖前先捕获完整错误、命令、解释器、包版本与最小复现；不要默默替换包或放宽版本直到安装成功。
可复现性策略：人工编辑的依赖规格与解析后的锁分开保存；记录 Python 次要版本、OS/架构、包版本、加载器版本及相关环境变量（不含机密）；缓存属性能产物而非来源，数据快照需自带来源元数据。锁文件对平台敏感，支持多平台时需维护并测试明确的平台锁或可复现解析工作流。来自受污染环境的 freeze 不算依赖设计。
示例：新 NFL 分析中创建 .venv、安装科学包与 nflreadpy、对 numpy,pandas,sklearn,nflreadpy 运行验证器、运行每个所选辅助脚本的 --help、执行一赛季或更小的授权样本、写出 environment.json 并检查、冻结依赖，然后在干净环境重复本地检查后再声称可复现。
输出契约与完整性：完整签核应报告 Python 版本/可执行文件、平台、请求的发行包与导入名、解析版本、辅助脚本/加载器探测、跳过的网络检查、输出往返、确切失败与补救、报告与锁路径。始终使用隔离环境与 python -m pip；绝不隐藏导入失败、跳过检查或平台限制；--help 必须保持离线，网络样本须有界且获授权；仅在验证后冻结，必要时通过重建验证锁。签核用 verify_checklist.md，失败路由用 troubleshooting.md。