python-env-manager

Python Env Manager

检测环境管理器，并使用正确的命令安装。作为 data-science-python-stack 和工作流技能添加依赖时的唯一权威来源。

下一步指引 — 使用此技能后该做什么

从哪里来到这里…	安装后，下一步是…
organize-ml-workspace § 脚手架	→ organize-ml-workspace § 可编辑工作区包；继续搭建脚手架
audit-ml-pipeline § agent-feature-missing	→ 返回 audit-ml-pipeline；放置 audit/<stem>.py
build-ml-pipeline / evaluate-ml-pipeline § 缺少依赖	→ 返回调用此技能的技能；从失败的预检框继续
data-science-python-stack § 缺少依赖	→ 返回调用方；现在应该可以成功导入之前缺少的模块

在宣布此轮完成之前，务必重新列出预检清单并附上证据。

停止条件 — 请先阅读

• 描述歧义并不等于解决歧义。 仅指出冲突（“conda myenv 处于激活状态，但根目录中有 pixi.toml”），然后替用户做出选择，并不等于询问。当检测到两个管理器时，必须由用户选择：通过 AskUserQuestion 提出问题。如果该工具不可用，且已检测到两个管理器，则报告 BLOCKED: manager ambiguity needs a user decision (<why the tool did not run>) 并停止——擅自宣称一方只是“上下文，而非选择”就此关闭问题，这是武断的做法。尚未配置任何管理器的空文件夹不属于这种情况：仍需列出 G-ENV-MGR 选项。
• BLOCKED 适用于缺少输入，而不适用于你已经可以完成的工作。 如果某个工具无法调用，或某项事实尚不明确，可以阻塞。如果当前轮次已包含所需信息——例如已记录管理器、工作区状态中已给出功能布局——就不算受阻；对本可完成的工作加上 BLOCKED 标记属于拒绝，而非保护措施。不适用的行应标记为 [n/a] — <why>，而不是将未勾选的复选框升级为阻塞事项。
• 禁止使用错误的管理器安装。 如果项目使用 pixi，就不要运行 pip install。如果使用 poetry，就不要运行 uv add。混用管理器会产生清单未跟踪的状态，后续运行 pixi install / poetry install / uv sync 时会悄无声息地撤销安装。
• 禁止静默引导初始化。 如果检测不到管理器，请询问用户。默认的建议是 pixi，但必须获得用户批准。
• 依赖路由是固定的，不需要询问。 强制使用 3 项功能布局（default / dev / agent）。Agent 不会逐次询问安装范围。只有遇到有歧义的额外依赖（optuna、xgboost、mlflow 等）时，才触发 G-ENV-SCOPE。
• 没有理由就不要锁定版本。 默认不锁定版本。只有用户要求或已知存在兼容性问题时才锁定版本。
• 不要自行运行引导安装程序。 缺少 pixi（或任何管理器）时，提供安装命令并让用户运行。curl | sh 属于系统级操作。
• Harness 的“不要提出澄清问题”提示不免除 AskUserQuestion 的强制要求。 管理器选择和范围选择属于操作约定的关卡，不是澄清问题。
• 事后审计 — 结束此轮前必须完成。 检查预检清单，确认每个已勾选项都有对应的 Evidence: 行。安装命令成功并不能证明完成；审计才可以。

禁止走捷径

捷径	错误原因
pixi 位于 PATH 上 → 直接运行 pixi init / pixi add	PATH 上的检测结果只是上下文，不是选择结果。如果没有 Workspace decisions 条目，仍会触发 G-ENV-MGR
用户说“安装 ruff” → 触发 G-ENV-SCOPE	路由规则固定：ruff / pytest / ipykernel / jupyterlab → dev。对于三个已知类别，禁止询问范围
用户请求 xgboost → 默默归入 default	有歧义的额外依赖必须询问：使用二进制选项 default，还是新建命名特性
调用的技能自行写入 pixi add --feature agent ...	安装命令由本技能负责。调用方技能提出请求；本技能负责安装
安装 Agent 特性 → 同时注册 Jupyter 内核	进程内运行器不使用内核；注册内核会产生孤立的内核规范
紧急情况（“快点”“你来选”）可以跳过 G-ENV-MGR	绝不可以。紧急情况不能跳过关卡
本次对话之前打开过 python-env-manager → 假定已通过关卡	阅读 SKILL.md ≠ 触发关卡。AskUserQuestion（或查询 JOURNAL.md）才是通过关卡的方式

预检 — 任何命令之前先输出

证据格式：参见 references/preflight_evidence.md。

Pre-flight (python-env-manager):
- [ ] Sibling SKILL.md files opened this turn:
      data-science-python-stack, iterate-ml-experiment,
      organize-ml-workspace
      Evidence: Read .agents/skills/<each>/SKILL.md (this turn)
- [ ] `journal/JOURNAL.md` Status `Workspace decisions` block read
      this turn for `env manager:` and `agent feature:` rows.
      Evidence: lists each row's value or "not recorded yet" |
                "n/a — JOURNAL.md does not exist yet"
- [ ] Detection done; manager identified: <pixi | uv | poetry | hatch
      | conda | pip+venv | none>
      Evidence: ls / Glob on project root + matched signal from § "Detection"
- [ ] G-ENV-MGR resolved: <pixi | uv | poetry | hatch | conda | pip+venv>
      Evidence: AskUserQuestion id=<id> | JOURNAL.md Status (recorded YYYY-MM-DD) |
                "detection returned a single manager; manifest commits the project"
- [ ] Dep category determined for each package:
      runtime → default | dev → dev | agent → agent |
      ambiguous → G-ENV-SCOPE binary ask
      Evidence: explicit categorization in this turn's response
- [ ] G-ENV-SCOPE resolved ONLY for ambiguous extras
      Evidence: AskUserQuestion id=<id> | user quote turn N |
                "n/a — package routes automatically"
- [ ] (Agent-feature installs only) G-AGENT-FEATURE resolved: install | skipped
      Evidence: AskUserQuestion id=<id> | JOURNAL.md Status (recorded YYYY-MM-DD) |
                "n/a — not an agent-feature install"
- [ ] Install command syntax confirmed for that manager (see § "Install commands")
      Evidence: cite the matching subsection
- [ ] Package list ready: <pkg-1, pkg-2, ...>
      Evidence: explicit list in this turn's response
- [ ] (Agent-feature installs only) `pyrightconfig.json` drop step queued
      Evidence: Read templates/pyrightconfig.json (this turn) + Write to project root
                | "n/a — not an agent-feature install"
                | "n/a — pyrightconfig.json already at project root"
- [ ] (Agent-feature installs only) Verification commands queued
      Evidence: commands quoted in this turn's response | "n/a"
- [ ] Pre-flight re-emitted with evidence before final message.
      Evidence: this same checklist appears in the end-of-turn summary.

检测 — 首个信号优先

项目根目录中的信号	管理器	备注
pixi.toml 或 pixi.lock	pixi	此技术栈的默认选择
uv.lock，或 pyproject.toml 中的 [tool.uv]	uv	基于 Rust，速度快
poetry.lock，或 pyproject.toml 中的 [tool.poetry]	poetry	较旧项目中常见
hatch.toml，或 pyproject.toml 中的 [tool.hatch]	hatch	声明式；流程各异——需要询问
environment.yml + PATH 上有 conda / mamba	conda / mamba	科学计算技术栈
requirements.txt + .venv/ 或 venv/	pip + venv	集成度最低
以上均无	（未检测到任何项）	询问用户；默认建议：pixi

备注：

• pyproject.toml 仅包含 [build-system] / [project]，且没有 [tool.X] 时，情况不明确——需要询问，不要推断。
• 存在多个信号（例如 pixi.toml + [tool.poetry]）时：先说明 存在歧义，再进行选择。

关于环境中管理器的边缘情况（PATH 上有 2 个或更多管理器、可复用的现有 conda 环境）：→ references/ambient_detection.md。

→ 下一步：G-ENV-MGR（下文）。

本技能负责的关卡

G-ENV-MGR — 选择哪个管理器

触发条件：检测结果为 (nothing detected) 且项目是新建项目；或检测到单个管理器，但尚不存在针对 env manager 的 Workspace decisions 条目。

AskUserQuestion：单选——管理器。选项来自检测表。未检测到任何项时，默认建议： pixi。始终列出：pixi（默认）+ uv / poetry / hatch / conda / pip+venv。如果没有 AskUserQuestion 界面，仍须列出 这些选项并等待——不要以“尚未选择管理器”为由返回 BLOCKED。 仅当自由文本明确写出某个已列出的管理器时，才可据此确定选择。

持久化：在 journal/JOURNAL.md 的 Status Workspace decisions 中记录 env manager: <pick> — recorded: <date>。

→ 下一步：§“安装命令 — 按管理器分类”。

G-ENV-SCOPE — 仅用于有歧义的额外依赖

触发条件：请求的依赖项不符合下文 §“自动路由表”（例如 optuna、xgboost、mlflow）。

AskUserQuestion（二选一）：

1. default — 并入运行时依赖。依赖项属于运行时需求时选此项。
2. 新的命名特性 <X> — 根据用户的措辞提出名称（mlflow 对应 tracing，optuna 对应 tuning，torch 对应 dl）。依赖项需要提升到特性标记层级时选此项。

自由文本解析：明确写出 default 或特性名称即可确定选择； “你来选” / “无所谓”不可以。

选择 default 时

一步完成：pixi add <pkg>（不加 --feature 标志 → 加入 default）。

→ 下一步：返回调用方技能。

选择新的命名功能 <X> 时——6 个步骤，缺一不可

这是承重流程，较小的模型容易忘记。 第 3 步尤其关键，漏掉会在不知不觉中破坏 LSP 集成。

1. 安装到新功能中：pixi add --feature <X> <pkg> （对应的包管理器命令：uv add --group <X> <pkg>、 poetry add --group <X> <pkg>）。
2. 确认清单中存在该功能块。
3. 将 <X> 追加到 lsp 环境的 features 列表中 — 各包管理器的操作如下：
   • pixi：编辑 pixi.toml [environments]， lsp = { features = [..., "<X>"], ... }。
   • uv / poetry：无需额外操作（--all-groups / --with 已涵盖）。
   • hatch / conda / pip+venv：重新编写 lsp 环境的依赖列表。
4. 重新同步 lsp 环境：pixi → pixi install -e lsp；uv → uv sync --all-groups；poetry → poetry install --with <X>； 其他 → 重新创建环境。
5. 更新 JOURNAL.md：将 <X> 追加到 optional features: 行。
6. 验证：bash .agents/skills/python-env-manager/scripts/verify_layout.sh。 退出码 0 = 一致。退出码 1 = 存在偏差，并附有修复步骤。

跳过第 3 或第 4 步 → 包会安装到 <X>，但 pyright 不会索引它，因为 lsp 未组合 <X>。用户会在合法代码中看到 “unresolved import”。

→ 下一步：返回调用方技能。

G-AGENT-FEATURE — 安装 ipython + pyright

触发条件：仅供 Agent 使用的使用方（审计文件使用 audit-ml-pipeline，或 data/eda.py 使用 explore-ml-data）需要 ipython / pyright，而清单未提供它们。对于 explore-ml-data，最早可在引导阶段 触发（基线之前的 G-EDA 运行路径），不必等到首次审计时才触发。

AskUserQuestion（二选一）：install | skip。

• install → 运行随附的对应包管理器脚本（参见 §“Agent 功能安装”）。对于任何使用审计或 EDA 流程的工作区，建议默认选择此项。
• skip → 阻止调用方技能；提示“安装 Agent 功能之前，审计 / EDA 步骤不可用”。不得静默降级。（explore-ml-data 随后会回退到跳过 EDA 的路径；audit-ml-pipeline 会阻止执行。）

持久化：agent feature: <installed | skipped> — recorded: <date>。

无需注册内核。审计运行器在进程内运行。 新工作区不再收集 Workspace decisions 中的 agent kernel: 行；旧行仅供参考。

→ 下一步：若选择 install，转到 §“Agent 功能安装”。

持久化状态查询 — 任何门控触发前先读取 JOURNAL.md

先读取 Workspace decisions：

• env manager: <pixi | uv | poetry | hatch | conda | pip+venv> — recorded: <date>
• agent feature: <installed | skipped> — recorded: <date>
• optional features: <name1, name2, ... | none> — recorded: <date>

如果某行已有记录，不要再次询问 — 在预检中引用 JOURNAL.md Status (Workspace decisions, recorded YYYY-MM-DD)， 作为该行的依据。

如果 journal/JOURNAL.md 尚不存在（即项目确实全新，且尚未运行 organize-ml-workspace），则重新触发门控；待 iterate-ml-experiment 写入 JOURNAL 后，将答案写入 Workspace decisions。

该把包放在哪里？——3 功能布局

固定分组

分组	内容	组合方式	用途
default	scikit-learn、skrub、skore、表格数据处理库、可编辑安装的 <pkg>	（自身）	运行时
dev	ruff、pytest、jupyterlab、ipykernel	default + dev	lint / 测试 / 交互式笔记本
agent	ipython、pyright	default + agent	审计运行器 + pyright 命令行
lsp	（无自有依赖）	default + dev + agent + <所有可选功能>	LSP 集成

Pixi 组合环境声明：

[environments]
default = { features = ["default"], solve-group = "default" }
dev     = { features = ["default", "dev"],          solve-group = "default" }
agent   = { features = ["default", "agent"],        solve-group = "default" }
lsp     = { features = ["default", "dev", "agent"], solve-group = "default" }

自动路由表——无需询问

包	路由到
scikit-learn、skrub、skore（或 skore[hub]）	default
pandas + pyarrow 或 polars	default
ruff、pytest、jupyterlab、ipykernel	dev
ipython、pyright	agent
可编辑工作区包（<pkg> @ .）	default

存在歧义时 → 触发 G-ENV-SCOPE。

原理（为何将 lsp 分开，采用可选功能增长模型）： → references/composition_model.md。

安装命令——按包管理器分类

检测到包管理器后，只使用相应的命令。各包管理器的扩展说明（每行的“原因”与注意事项）见 references/install_commands_anatomy.md。

pixi

操作	命令
添加到默认环境	pixi add <pkg>
添加到功能	pixi add --feature <feature> <pkg>
添加到环境	pixi add -e <env> <pkg>
移除	pixi remove <pkg>（或 --feature <feature>）
升级	pixi upgrade <pkg>
在环境中运行	pixi run -e <env> <command>
根据清单同步	pixi install

uv

default → [project] dependencies；dev → --group dev； agent → --group agent；可选功能 → --group <name>。

操作	命令
添加运行时依赖	uv add <pkg>
添加开发依赖	uv add --dev <pkg>
添加到分组	uv add --optional <group> <pkg>
移除	uv remove <pkg>
升级	uv lock --upgrade-package <pkg>
在环境中运行	uv run <command>
同步	uv sync（使用 --all-groups 以涵盖 dev+agent+optional）

poetry

default → [tool.poetry.dependencies]；dev → --group dev； agent → --group agent；可选依赖 → --group <name>。

操作	命令
添加运行时依赖	poetry add <pkg>
添加开发依赖	poetry add --group dev <pkg>
添加到分组	poetry add --group <name> <pkg>
移除	poetry remove <pkg>
升级	poetry update <pkg>
运行	poetry run <command>
同步	poetry install

hatch

声明式配置——没有通用的 hatch add。编辑 pyproject.toml:[project] dependencies 或 [tool.hatch.envs.<env>.dependencies]，随后任何 hatch run -e <env> <command> 命令都会重新创建环境。注意：hatch 环境之间不会组合；每个非默认环境都需要重复配置运行时依赖。

conda / mamba

没有原生的功能概念；将各类依赖映射到命名环境 （<project>、<project>-dev、<project>-agent）。

操作	命令
添加（conda-forge）	conda install -n <env> -c conda-forge <pkg>
使用 mamba	mamba install -n <env> -c conda-forge <pkg>
移除	conda remove -n <env> <pkg>
根据 yml 同步	conda env update -f environment.yml --prune

pip + venv

集成度最低。不更新清单——pip install 会直接修改 当前环境，且不会跟踪变更。建议迁移到受管理的替代方案。

各包管理器的可编辑工作区安装（src/<pkg>/）： → references/editable_workspace.md。

Pixi（复制此内容）：

pixi add --pypi "<pkg> @ ."
# pixi.toml:
<pkg> = { path = ".", editable = true }
pixi install

之后，从任意 CWD 执行 from <pkg>.pipeline import build_learner 均可正常工作。

Agent 功能安装

agent 功能 = 项目范围内安装 ipython + pyright

• 随附的 pyrightconfig.json（将 <PYTHON_PATH> 替换为 lsp 环境的解释器路径）。

捆绑脚本——每种管理器一个

管理器	调用方式	参数
pixi	bash .agents/skills/python-env-manager/scripts/install_agent_feature_pixi.sh	无
uv	bash .agents/skills/python-env-manager/scripts/install_agent_feature_uv.sh	无
poetry	bash .agents/skills/python-env-manager/scripts/install_agent_feature_poetry.sh	无
hatch	bash .agents/skills/python-env-manager/scripts/install_agent_feature_hatch.sh	无（需要用户编写 [tool.hatch.envs.agent] + [tool.hatch.envs.lsp]）
conda	bash .agents/skills/python-env-manager/scripts/install_agent_feature_conda.sh <project-name>	项目名称
pip+venv	bash .agents/skills/python-env-manager/scripts/install_agent_feature_pip_venv.sh <requirements-file>	requirements 文件

运行脚本，不要重新输入命令。 每个脚本都封装了各管理器特有的易错点（poetry 的 virtualenvs.in-project、hatch 的不支持组合、conda 的机器本地路径）。手动重新输入是明确禁止的捷径。

各脚本的结构（内部的 4 个操作、安装后的运行器调用、清理、验证）： → references/agent_feature_anatomy.md。

各管理器特有的易错点： → references/per_manager_footguns.md。

→ 下一步：返回调用方（通常是 audit-ml-pipeline）。

Tier 1 安装：按模式选择 skore 变体

从 journal/JOURNAL.md Status Workspace decisions 中读取 skore mode:（由 organize-ml-workspace § G-SKORE-MODE 设置）。该变体包含两个相互独立的维度：模式 （local / hub / mlflow）和包来源（pixi / conda+mamba 使用 conda-forge，uv / poetry / hatch / pip+venv 使用 PyPI）。 PyPI 安装需要额外添加 jupyter extra；conda-forge 安装 已包含 jupyter 集成。

skore mode:	conda-forge 管理器（pixi、conda / mamba）	PyPI 管理器（uv、poetry、hatch、pip+venv）
local	pixi add skore / conda install -c conda-forge skore	uv add "skore[jupyter]" / poetry add "skore[jupyter]" / pip install "skore[jupyter]"
hub	pixi add "skore[hub]" / conda install -c conda-forge "skore[hub]"	uv add "skore[hub,jupyter]" / poetry add "skore[hub,jupyter]" / pip install "skore[hub,jupyter]"
mlflow	pixi add "skore[mlflow]" "mlflow>=3" / conda install -c conda-forge "skore[mlflow]" "mlflow>=3"	uv add "skore[mlflow,jupyter]" "mlflow>=3" / poetry add "skore[mlflow,jupyter]" "mlflow>=3" / pip install "skore[mlflow,jupyter]" "mlflow>=3"

mlflow 变体必须显式指定 mlflow>=3（如上方命令所示）。 skore[mlflow] extra 对 mlflow 的最低版本要求较宽松，因此求解器可能会解析出 skore MLflow 后端不支持的旧版 mlflow（2.x）——无论是 conda-forge 还是 PyPI，都要在安装命令中添加 mlflow>=3。

如果缺少该行（工作区尚未通过 organize-ml-workspace 引导初始化），请返回该技能的 G-SKORE-MODE。 不要猜测。

禁止：

• 为了“保险”而悄悄选择 skore[hub] / skore[mlflow]。[hub] / [mlflow] extras 会引入网络依赖和基础设施，而本地模式用户并未要求这些；应遵循记录的 skore mode:，而不是猜测。
• 安装 mlflow 变体时未显式指定 mlflow>=3。单独使用 skore[mlflow] 可能会解析出 mlflow 2.x；skore MLflow 后端需要 mlflow 3+。务必同时安装 mlflow>=3。
• 因为安装命令“看起来更短”而在 PyPI 安装中省略 jupyter extra。在 uv / poetry / hatch / pip+venv 上，audit 流程和 evaluate-ml-pipeline 依赖的 TableReport / report.* 小组件若未启用该 extra，就无法渲染。
• 在 pixi / conda 安装中添加 jupyter extra。这样是多余的——conda-forge 的 skore 已经会引入 jupyter 集成。

有关该变体的重要性、切换模式的步骤，以及 [jupyter] extra 的原因： → references/skore_variant.md。

skrub 安装 — macOS 安装后处理

当 skrub 正在安装（或刚刚安装完成）且 平台为 macOS 时，在安装完成后于项目环境中运行一次 dot -c。这会重建 graphviz 的插件／格式缓存；跳过此步骤会导致首次调用 .skb.draw_graph()／ .skb.full_report() 时打印格式警告，或在查找字体时出错。

# right after the skrub install command lands, on macOS only:
[[ "$(uname)" == "Darwin" ]] && pixi run dot -c

根据环境管理器，替换环境运行前缀：pixi run／uv run／ poetry run／hatch run／conda run -n <env>／已激活的 venv → 直接运行 dot -c。Linux 和 Windows：不执行任何操作，跳过此调用。 只需运行一次——除非重新安装了 graphviz，否则后续会话无需重新运行。

引导设置 — 未检测到环境管理器时

如果检测没有发现任何环境管理器，且用户通过 G-ENV-MGR 选择了 pixi：

1. 检查 command -v pixi；如果未安装，显示安装 URL。

2. pixi init。

3. 编辑 pixi.toml：声明 3 个 feature（default／dev／ agent）和 4 个环境（default／dev／agent／lsp）。dev 包含 ruff、pytest、jupyterlab、ipykernel；agent 包含 ipython、pyright。

4. 将 Tier 1 依赖添加到 default（参照上方 G-SKORE-MODE 表格 — pixi 使用 conda-forge，因此运行 pixi add skore、pixi add "skore[hub]" 或 pixi add "skore[mlflow]" "mlflow>=3"；pixi 上不要添加 [jupyter] extra）。

5. 添加表格数据处理库（参照 G-TABULAR：pandas pyarrow 或 polars）。

6. 配置可编辑的工作区包 — 复制以下内容：

   pixi add --pypi "<pkg> @ ."
   # then in pixi.toml:
   <pkg> = { path = ".", editable = true }
   pixi install
   

   然后，从任何 CWD 中运行 from <pkg>.pipeline import build_learner 都能正常工作，无需使用 PYTHONPATH=src 变通，也无需在每次 修改源代码后重新安装。

7. 使用 sed 将 <PYTHON_PATH> 替换为 .pixi/envs/lsp/bin/python，生成 pyrightconfig.json。

8. 同步全部 4 个环境：运行 pixi install，然后运行 pixi install -e dev / -e agent / -e lsp。

包含精确 pixi.toml 代码块、等效环境管理器流程及 pixi 版本兼容性说明的完整分步指南： → references/bootstrap.md。

→ 下一步：返回 organize-ml-workspace § scaffold。

配套技能

技能	关系
data-science-python-stack	负责确定要安装什么；此技能将其转化为命令
organize-ml-workspace	Scaffold 在此交接可编辑安装；G-TABULAR / G-SKORE-MODE 为此技能的引导设置提供信息
audit-ml-pipeline / explore-ml-data	G-AGENT-FEATURE 从那里触发（审计文件；data/eda.py）
build-ml-pipeline / evaluate-ml-pipeline	缺失依赖的 Stop 条件会重定向到此处
iterate-ml-experiment	负责此技能读取／写入的 Workspace decisions 块

约定

• 每条回复只执行一项安装操作。 不要将无关的包批量安装。 可以将相关项分组（Tier 1 引导设置，或单个功能的依赖），并在继续前确认。
• 默认不使用 --no-deps 或版本固定。 仅在用户要求或已知存在兼容性问题时固定版本。
• 显示错误，不要绕过。 如果安装失败，显示错误信息 和命令。不要尝试改用其他环境管理器来变通 — 这违反了 Stop 条件。