helix-npm

helix-npm 是一个自包含的 Helix OpenCode 插件，用自然语言管理 Ascend NPU 上的 Triton / TileLang 算子转换、测试、基准测试、验证和多轮优化。

它安装后会自动提供：

• helix-npm 专用 Agent；
• Helix MCP 工具和异步任务管理；
• Helix CLI、运行时源码和完整 Skills；
• helix-orchestrator 工作流知识；
• 面向中文用户的中文说明、确认提示、进度和结果总结。

用户无需克隆 triton-agent、设置 HELIX_REPO、复制 Agent/Skills，或手动编辑 opencode.json。

前置条件

• OpenCode 1.17.8 或兼容版本；
• Node.js 20+ 与 npm；
• Python 3.10+；
• 容器已经配置 Ascend NPU、torch、torch_npu 和相应设备环境变量；
• 首次安装可以访问 Python 包源以安装 fastmcp==3.2.4，或具有可用的 pip 缓存。

Node.js 20 可以运行插件，但 npm 10 在安装 OpenCode 插件依赖时可能对间接依赖 ini@7 显示 EBADENGINE 警告；只要安装完成且 helix-npm doctor 全部为 true，该警告不影响运行。希望无警告安装时，使用 Node.js 22.22.2+。

安装器通过 --system-site-packages 创建独立 Python 环境，因此能复用容器已有的 torch、torch_npu 和 NPU 驱动环境，而不会在系统 Python 中安装 Helix 依赖。

安装

从 npm Registry 安装

推荐命令：

npm exec --yes --package=helix-npm -- helix-npm install

也可使用简写：

npx --yes helix-npm install

安装器会：

1. 将包持久安装到 ~/.config/opencode/node_modules/helix-npm；
2. 在包内创建 Python 虚拟环境；
3. 安装固定版本的 FastMCP；
4. 注册 ~/.config/opencode/plugins/helix-npm.js；
5. 让 OpenCode 自动发现 helix-npm Agent、Helix MCP 工具和工作流知识。

使用本地 .tgz 包安装

HELIX_NPM_PACKAGE_SPEC=/path/to/helix-npm-0.2.1.tgz \
  npm exec --yes --package=/path/to/helix-npm-0.2.1.tgz -- \
  helix-npm install

验证与使用

helix-npm doctor
opencode debug agent helix-npm

doctor 应显示：

{
  "pythonReady": true,
  "torchNpuReady": true,
  "pluginRegistered": true
}

随后启动 OpenCode：

opencode

选择 helix-npm Agent。所有会启动或修改任务状态的 Helix 命令都会先展示工具、完整参数、默认值来源、执行位置和作用范围，并等待用户明确确认。

更新

npm exec --yes --package=helix-npm@latest -- helix-npm install

每次发布必须使用新的 npm 版本号，便于复现与回退。

与 triton-agent 原仓库同步

本插件位于 triton-agent/helix-npm，因此同步脚本从自身位置推导原仓库路径，不依赖电脑上的绝对路径。

原仓库更新后，先预览再同步：

npm run sync:runtime:check
npm run sync:runtime

脚本同步 src/、helix_mcp/、skills/、Python 依赖定义，以及 helix-orchestrator 工作流知识到插件的 runtime/ 与 assets/skills/。它会排除插件自身，避免递归复制。

assets/agents/helix-npm.md、插件 src/ 与 scripts/install.mjs 是 OpenCode 专用适配层，不会被自动覆盖；需要根据原仓库变更人工合并。

可选环境变量

| 变量 | 说明 | | --- | --- | | HELIX_NPM_PYTHON | 指定用于创建虚拟环境的 Python 3.10+ 解释器。 | | OPENCODE_CONFIG_DIR | 覆盖 OpenCode 配置目录，适合测试隔离环境。 | | HELIX_NPM_RUNTIME_DIR | 开发/测试时覆盖内置 Helix runtime 路径。 | | HELIX_NPM_MCP_COMMAND | 开发/测试时覆盖 MCP 进程命令。 | | HELIX_NPM_MCP_ARGS | 开发/测试时覆盖 MCP 进程参数，值为 JSON 数组。 |

开发与发布前检查

npm install --ignore-scripts
npm run check
npm test
npm run pack:check
npm pack

完整发布步骤见 RELEASING.md。