القائمة
询问 pixi 用法时使用。 适用于环境管理、依赖安装、任务运行、shell 交互、清理环境等。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | pixi-usage |
| description | 询问 pixi 用法时使用。 适用于环境管理、依赖安装、任务运行、shell 交互、清理环境等。 |
本技能记录 SPONGE 项目中 pixi 的使用方式和注意事项。当前使用的 pixi 版本为 0.65.0。
pixi 是基于 conda 生态的开发工作流工具，用于管理依赖、环境和任务。SPONGE 项目通过 pixi.toml 定义所有环境和任务，取代手动 conda/mamba 操作。
curl -fsSL https://pixi.sh/install.sh | bash
SPONGE 镜像（国内推荐）：
curl -fsSL https://conda.spongemm.cn/pixi/install.sh | bash
安装脚本会将 pixi 放到 ~/.pixi/bin/ 并自动添加到 shell 的 PATH 中。
powershell -ExecutionPolicy ByPass -c "irm https://pixi.sh/install.ps1 | iex"
SPONGE 镜像（国内推荐）：
powershell -ExecutionPolicy ByPass -c "irm https://conda.spongemm.cn/pixi/install.ps1 | iex"
pixi self-update # 更新到最新版本
pixi self-update --version 0.65.0 # 更新到指定版本
环境由 feature 组合而成，在 pixi.toml 的 [environments] 中定义。每个环境有独立的依赖集和任务集。环境安装在 .pixi/envs/<环境名>/ 下。
大多数 pixi 命令通过 -e <环境名> 指定环境，不指定时使用 default 环境。
Feature 是可组合的依赖和任务单元，环境由一个或多个 feature 组成。例如 dev-cuda13 = ["dev", "cuda", "cuda13"] 组合了开发工具、CUDA 通用依赖和 CUDA 13 特有依赖。
任务在 pixi.toml 中定义，通过 pixi run 执行。任务可以是简单字符串命令，也可以带参数模板。
pixi install -e dev-cuda13 # 安装指定环境的依赖
pixi install -a # 安装所有环境
pixi run 会自动触发 install，但显式执行可以提前发现依赖问题。
pixi run -e dev-cuda13 configure # 在指定环境中运行任务
pixi run -e dev-cuda13 compile # 编译
pixi run -e dev-cuda13 perf-amber # 运行 benchmark
pixi task 支持通过 {{ arg_name }} 模板定义参数。以 SPONGE 项目中的 task 为例：
# pixi.toml 中的定义
configure = { cmd = "cmake ... -DPARALLEL='{{ parallel }}'", args = [{ arg = "parallel", default = "none" }] }
compile = { cmd = "cmake --build ... --parallel {{ jobs }}", args = [{ arg = "jobs", default = "4" }] }
调用时，参数按位置直接跟在 task 名后面传值：
pixi run -e dev-cpu configure avx2 # avx2 替换 {{ parallel }}
pixi run -e dev-cuda13 compile 8 # 8 替换 {{ jobs }}
pixi run -e dev-cuda13 compile # 不传则使用默认值 4
如果 task 定义了多个参数，按定义顺序依次传入。
以下写法都是错误的，不要使用：
pixi run -e dev-cpu configure --parallel avx2 # 错误：被当作额外参数，报错
pixi run -e dev-cpu configure parallel=avx2 # 错误：被当作字面字符串传给 cmake
pixi run -e dev-cpu configure -- avx2 # 错误：-- 后面被当作额外参数
注意：以上规则仅适用于定义了 args 的 task。如果 task 没有定义 args（即简单字符串命令），后面附加的内容会直接拼接到命令末尾：
# 没有定义 args 的 task
perf-amber = "python -X utf8 -m pytest benchmarks/performance/amber/tests -s --tb=short"
pixi run -e dev-cuda13 perf-amber -k test_rdf
# 实际执行：python -X utf8 -m pytest benchmarks/performance/amber/tests -s --tb=short -k test_rdf
pixi shell -e dev-cuda13 # 进入环境的交互式 shell
进入后所有环境变量（PATH、CONDA_PREFIX 等）已设置好，可以直接调用环境内的工具。用 exit 退出。
pixi run -e dev-cuda13 python script.py # 运行非 task 的命令
pixi run -e dev-cuda13 pip install -e ./plugins/prips
pixi run -e dev-cuda13 which SPONGE
pixi run 后面如果不是已定义的 task 名，会当作普通 shell 命令在环境中执行。
pixi add numpy # 添加 conda 依赖到 default feature
pixi add numpy -f dev # 添加到 dev feature
pixi add numpy -p linux-64 -f dev # 指定平台
pixi add --pypi xponge -f dev # 添加 PyPI 依赖
添加后会自动更新 lockfile 和 pixi.toml。
pixi info # 显示系统和工作区信息
pixi list -e dev-cuda13 # 列出环境中的包
pixi task list -e dev-cuda13 # 列出可用任务
pixi clean -e dev-cuda13 # 清理指定环境
pixi clean # 清理所有环境
pixi clean cache # 清理全局缓存
pixi reinstall -e dev-cuda13 # 重装整个环境
pixi reinstall -e dev-cuda13 numpy # 只重装指定包
pixi run --clean-env -e dev-cuda13 configure # 隔离系统环境变量运行任务
--clean-env 会忽略当前 shell 的环境变量，只使用 pixi 环境自身的变量。适用于排查系统环境污染问题。
注意：如果任务本身依赖 pixi 环境外部的工具链（如 HIP/ROCm、MSVC），使用 --clean-env 会导致找不到这些工具。
pixi run --frozen -e dev-cuda13 compile # 使用 lockfile 原样安装，不更新
pixi run --locked -e dev-cuda13 compile # 检查 lockfile 是否最新，不一致则报错
--frozen：适用于 CI 或确定不想更新依赖时--locked：适用于确保 lockfile 和 manifest 一致format-check = "GITHOOK_MODIFY=0 ... python -X utf8 scripts/pre-commit"
compile = { cmd = "cmake --build ... --parallel {{ jobs }}", args = [{ arg = "jobs", default = "4" }] }
task 可以定义在不同的 section 下，按平台和 feature 区分：
[feature.cuda.target.linux-64.tasks] # CUDA + Linux x86_64
[feature.cpu.target.osx-arm64.tasks] # CPU + macOS ARM
[feature.dev.tasks] # dev feature（跨平台）
同名 task 在不同 section 下定义时，实际使用的版本取决于当前环境包含哪些 feature 和当前平台。
.pixi/
envs/
dev-cuda13/ # 环境安装目录
dev-cpu/
...
pixi.toml # 项目配置
pixi.lock # lockfile
pixi.lock 应提交到版本控制，确保团队和 CI 使用一致的依赖版本。
确认命令在指定环境中可用。用 pixi run -e <env> which <cmd> 检查。如果是非 dev 环境，可能缺少 python、pytest 等工具。
检查 pixi.toml 中的版本约束是否存在冲突。用 pixi add <pkg> -f <feature> --no-install 可以只更新 lockfile 不安装，方便调试。
pixi.toml 修改后 lockfile 会自动在下次 run/install 时更新。如果只想更新 lockfile 不安装环境，用 pixi lock。
询问 SPONGE benchmark 新建 或 调整 时 使用 - comparison validation performance 分类 - benchmark 目录 组织 - benchmark 测试 编写 - utils 复用 - pixi task 接入
询问 SPONGE 构建、编译、环境配置、构建排错时使用。 适用于 pixi 环境选择、CMake 配置、多后端编译、格式化、打包。
询问 SPONGE 代码风格、命名规范、格式化工具时使用。 适用于 C++、Python、CMake 的编码规范和格式化流程。
询问 SPONGE 输入文件（mdin.spg.toml）的参数配置时使用。 适用于模拟参数设置、模块配置、输入输出文件指定等。
询问为 SPONGE 安装、链接、修复或检查 skills 时使用。 适用于 AI 助手的本地或全局 skills 配置。
询问使用 SPONGE 的 PRIPS 对接机器学习/神经网络势场时使用。 适用于 Python plugin 编写、环境准备、力回填。