pixi

Pixi — 为 Agent 提供可复现的环境和任务

使用 Pixi 管理 conda 和 PyPI 依赖、多语言环境及工作区任务。根据当前目标选择操作说明；每一步只加载所需的工作流和参考章节。

仅加载当前工作流

链接相对于此技能目录解析，而非用户的工作区。任务进入另一工作流时，再加载相应内容。

当前目标	阅读	范围
初始化或导入工作区	initialize	清单格式、渠道、平台、现有 Python 项目
添加、移除、更新或升级软件包	dependencies	Conda/PyPI 规格、功能归属、锁定策略
组合功能和环境	environments	默认功能、隔离环境、求解组
运行代码或管理任务	run	项目执行、任务定义、临时执行
检查软件包或排查问题	inspect	诊断、反向依赖、定向修复
安装或管理全局 CLI 工具	global	隔离的全局工具、公开、更新、卸载

分阶段加载示例：

• **运行现有脚本：**阅读 run；仅在需要更改软件包时加载 dependencies。
• **向命名环境添加软件包：**阅读 dependencies；如果需要更改其功能组合，则加载 environments。
• **检查故障：**阅读 inspect；仅在诊断要求时重新安装或更新。

通用规则

• 更改配置前，先阅读现有清单和相关项目说明。除非任务要求更改，否则保留其格式、渠道、受支持的平台和工具链。如果发现机制可能选中其他工作区，请使用 --manifest-path。
• 通过 Pixi 声明依赖。使用 pixi add 或 pixi add --pypi，不要在 Pixi 环境中使用 pip、conda 或 mamba 安装未声明的依赖。
• 功能负责管理依赖；环境负责组合功能。 添加或移除时使用 --feature；运行、安装或列出时使用 --environment。更改被多个环境共享的功能前，先检查其组合方式。
• 项目命令优先使用 pixi run。它会按需安装或同步所选环境，因此通常不需要单独执行安装步骤。仅在有意使用与工作区无关的临时设置时，才使用 pixi exec。
• Pixi 会生成 pixi.lock；不要手动编辑。对于可复现的应用或研究工作区，应在版本控制中同时保留清单和锁文件。更改依赖后检查两者的差异。
• 有意选择锁定行为：常规执行可能刷新过期的锁文件；--locked 要求锁文件与清单一致；--frozen 使用锁文件，但不检查两者是否一致。不要同时使用 locked 和 frozen。
• 优先使用便于人阅读的输出；只有程序需要解析时才使用 JSON。进行大范围更新、清除缓存或重新安装之前，先诊断所选环境。
• 示例已使用 Pixi 0.71.1 检查。使用 pixi --version 和已安装命令的 --help 确认特定版本的选项。

常见用法指南（少样本）

以 example- 或 example_ 开头的名称是用于软件包、功能、环境和路径的虚构占位符。阅读工作区清单后，将其替换为实际名称。

1. 直接运行现有项目代码

用户：“在现有的 example-analysis 环境中运行测试。”

回复：“我会直接使用项目环境；必要时 run 会准备好环境，因此通常不需要单独执行安装步骤。”

pixi run -e example-analysis python -m unittest discover -s tests -p 'test_*.py' -v

**原因：**run 接受可执行程序和任务。将测试模式用引号括起来，以免外层 shell 对其展开。只有在要检查安装本身时，才显式执行安装。

2. 解决包来源不匹配

用户：“我们的 conda 渠道中没有 example-package 1.2.3 候选版本。在 example-analysis 中使用该版本。”

回复：“我会验证 PyPI 是否提供所请求的版本，确定哪个功能拥有此依赖项，并替换其 conda 声明。这里，example-tools 功能属于 example-analysis 环境。”

pixi remove --feature example-tools example-package
pixi add --feature example-tools --pypi 'example-package==1.2.3'
pixi run -e example-analysis python -c 'from importlib.metadata import version; print(version("example-package"))'
git diff -- pixi.toml pixi.lock

**原因：**缺少候选版本时，应检查包的可用性、来源和约束。选择已验证的来源，并检查最终更改。

3. 声明具名的可编辑依赖项

用户：“在 example-analysis 中，将本地 example-local-package 检出作为可编辑依赖项使用。”

回复：“我会在 example-tools 中添加具名本地需求项，该功能供此环境使用。”

pixi add --feature example-tools --pypi --editable 'example-local-package @ ./packages/example-local-package'
pixi run -e example-analysis python -c 'import example_local_package; print(example_local_package.__file__)'

**原因：**本地 PyPI 需求项需要在 @ 前提供包名。add 用于选择功能；run 用于选择环境。发行版名称和导入名称来自本地包的元数据和源码。

4. 显式选择隔离的工作区

用户：“在现有临时工作区中运行比较，不更改主项目的依赖项。”

回复：“我会显式选择其清单，并检查其解释器。”

pixi run --manifest-path temp/example-comparison/pixi.toml python -c 'import sys; print(sys.executable)'

**原因：**显式选择清单可将命令限定到目标工作区。使用报告的解释器路径，包括环境已分离的情况。常规 run 可能会更新所选工作区的锁文件和安装状态。

5. 保留锁文件，或要求其与清单一致

用户：“使用现有锁文件运行验证，不刷新它。”

回复：“我会使用 frozen 来保留该锁文件。如果还要求它与清单一致，请改用 locked。”

pixi run --frozen -e example-analysis python scripts/example_validate.py

**原因：**locked 会检查清单与锁文件是否一致；frozen 使用现有锁文件而不进行此检查。如果所选环境需要安装软件包，两者仍可能安装软件包。

6. 有意使用 exec 添加一次性依赖项

用户：“使用 example-helper-package 运行这个一次性辅助工具，不要将其添加到项目中。”

回复：“我会使用单独的临时环境，其中包含 Python 和此辅助工具的依赖项。”

pixi exec --spec python --spec example-helper-package -- python scripts/example_helper.py

**原因：**exec 提供独立于项目锁文件的临时依赖项。对于需要维护的项目代码，应在功能中声明依赖项并使用 run。将辅助工具引发的异常视为应用程序错误进行诊断。

依赖项更改链失败时

先前的 add 可能已经成功；&& 不会回滚更改。重试前检查 git diff -- pixi.toml pixi.lock。区分无法满足的求解、安装失败和执行脚本引发的异常。成功运行 pixi lock 只能确定锁文件状态，并不代表环境已安装。

值得查阅的命令帮助

选择不熟悉的选项时，运行已安装命令的帮助。对于嵌套命令，请在要使用的子命令处请求帮助。

决策	帮助命令
初始化或导入工作区	pixi init --help、pixi import --help
选择依赖项来源和功能	pixi add --help、pixi remove --help
运行项目代码	pixi run --help
安装或解析依赖项	pixi install --help、pixi lock --help
更新版本或需求项	pixi update --help、pixi upgrade --help
组合环境	pixi workspace environment add --help
定义任务	pixi task add --help
运行一次性工具	pixi exec --help
修复或清理环境	pixi reinstall --help、pixi clean --help
管理全局工具	pixi global --help，然后查阅相关子命令的帮助

官方参考文档

先查看参考索引，了解易读的主题名称、本地快照和上游来源。未经修改的官方 llms.txt提供了更全面的文档索引。

按需阅读清单文件了解架构详情，多环境了解功能组合方式， 锁定文件了解可复现性，conda/PyPI了解混合依赖项，以及 任务了解高级任务行为。

对于不常用的命令，请运行 pixi <command> --help。官方 llms.txt 中列出了构建、发布、 身份验证、编辑器和 CI 相关说明；仅在任务需要时查阅相应页面。