{"_id":"@aidan200/pi-helix","name":"@aidan200/pi-helix","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aidan200/pi-helix","version":"0.1.0","type":"module","description":"Helix package for pi: vibe coding runtime, todo, plan mode, multi-agent collaboration, tracing, and Claude Code plugin compatibility.","keywords":["pi-package","pi-extension","helix","vibe-coding-runtime","claude-code-plugin","multi-agent","plan-mode"],"pi":{"extensions":["./extensions/index.ts"]},"peerDependencies":{"@earendil-works/pi-agent-core":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*","typebox":"*"},"gitHead":"91be267c3300f4b8c994eaa0e4330eccab1e0258","_id":"@aidan200/pi-helix@0.1.0","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-F8BOnPELLCXmUn6c/TSOadBddMNpXc08N2iC7gnJynGp7xF08XWm7AUIV0ljeav7hRPOlRi6HM1YAbrIUqcxxg==","shasum":"4f126c5cad8b914c89144772bae94fa6281129e9","tarball":"https://registry.npmjs.org/@aidan200/pi-helix/-/pi-helix-0.1.0.tgz","fileCount":46,"unpackedSize":182434,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCUA5c4U+Ie7jxY8koP+I+m8hfTQ3vU97UtZDIrQ+mL/AIhAMVC9dPT7FeOc02Sm0QYq/PDo/tKKHg9Z1NIJse013y1"}]},"_npmUser":{"name":"aidan200","email":"ve_master@sina.com"},"directories":{},"maintainers":[{"name":"aidan200","email":"ve_master@sina.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-helix_0.1.0_1780906662370_0.8224290575789619"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-08T08:17:42.225Z","0.1.0":"2026-06-08T08:17:42.503Z","modified":"2026-06-08T08:17:42.711Z"},"maintainers":[{"name":"aidan200","email":"ve_master@sina.com"}],"description":"Helix package for pi: vibe coding runtime, todo, plan mode, multi-agent collaboration, tracing, and Claude Code plugin compatibility.","keywords":["pi-package","pi-extension","helix","vibe-coding-runtime","claude-code-plugin","multi-agent","plan-mode"],"readme":"# Helix\n\nHelix 是一个 PI package，用来补齐更接近 Claude Code 的 agentic coding 工作流：\n\n- 主 agent runtime：阶段管理、策略约束、workspace 变更追踪、验证状态、final gate、进度提示\n- Todo list：`todo_read`、`todo_write`、`todo_update`、`todo_clear`\n- Web search：`web_search`，使用 Brave Search API 的本地 Helix 工具\n- 意外发现：`finding_report`、`finding_read`、`finding_update`、`finding_clear`\n- Plan mode：`/plan`、`/plan exec`、`--plan`、`Ctrl+Alt+P`\n- 多 agent：`multi_agent`，支持 single、parallel、chain、collaborate\n- 协作任务队列：`collab_task`\n- 工作流 trace：`/collab-trace`\n- Claude Code/Codex skills 插件兼容层：`/plugin`、`skill`\n- Project 初始化、依赖同步与文档同步：`/helix-project init`、`/helix-project sync`、`/helix-project docs`\n- Agent loop trace：`/helix-trace on`、`/helix-trace status`，记录系统提示词、provider 请求、工具调用等调试信息\n- 命令说明：`/helix help`\n\n## 启动\n\n开发调试：\n\n```bash\npi -e ./helix\n```\n\n安装到 PI：\n\n```bash\npi install ./helix\n```\n\n进入 PI 后查看所有 Helix 命令：\n\n```text\n/helix help\n```\n\n## Tauri 客户端\n\n仓库内提供了一个最小桌面客户端原型：\n\n```bash\ncd ../helix-client\nnpm install\nnpm run tauri:dev\n```\n\n客户端会启动父 PI RPC 进程：\n\n```text\npi --mode rpc -e <helix-path>\n```\n\nHelix 会通过 PI extension context 的 `ctx.mode` 区分运行环境：\n\n- `ctx.mode === \"rpc\"`：视为 Helix Client / RPC 前端场景。Helix 会通过 `ctx.ui.setStatus(key, JSON.stringify(payload))` 推送机器可读状态，供 helix-client 同步 runtime、tools、auth、proxy 等状态。\n- `ctx.mode === \"tui\"`：普通 `pi -e ./helix` 终端场景。Helix 保留人类可读的 `notify` 反馈，但不会把给 helix-client 使用的 JSON 状态写进 TUI 状态栏。\n- `ctx.hasUI === false`（print/json）：不会发送交互 UI；OAuth login 等需要用户输入的命令要求 TUI 或 RPC 模式。\n\n因此 `/helix-state`、`/helix-clear` 这类命令主要是 Helix Client RPC 前端的状态同步/调试命令；普通 TUI 下通常不需要使用。\n\n第一版只展示父 PI RPC 的消息、工具调用和 extension UI 事件；`multi_agent` 的子进程细节后续需要通过 Helix monitor bridge 转发。\n\n## 配置层级\n\nHelix 有自己的配置文件，不复用 package 源码目录。\n\n默认用户级配置：\n\n```text\n~/.pi/helix/config.json\n~/.pi/helix/plugins/\n~/.pi/helix/trace/\n```\n\n项目级配置：\n\n```text\n<project>/.pi/helix/config.json\n<project>/.pi/helix/plugins/\n<project>/.pi/helix/trace/\n```\n\n加载规则：\n\n- 用户级配置先加载。\n- 项目级配置后加载，并覆盖同名插件和 trace 字段。\n- 插件数组按 `name` 合并，项目级同名插件优先。\n- 手动管理时，只要把插件目录放到指定位置，并在 `config.json` 中登记即可。\n\n初始化配置：\n\n```text\n/helix-config init user\n/helix-config init project\n/helix-config path\n/helix-config show\n```\n\n## 配置示例\n\n完整配置说明见项目内 `config_example.json`。\n\nBrave Search 可配置在用户级或项目级配置中；API key 也可用环境变量 `BRAVE_SEARCH_API_KEY` 提供：\n\n```json\n{\n  \"version\": 1,\n  \"braveSearch\": {\n    \"apiKey\": \"...\",\n    \"count\": 10,\n    \"country\": \"US\",\n    \"searchLang\": \"en\",\n    \"uiLang\": \"en-US\",\n    \"safesearch\": \"moderate\"\n  }\n}\n```\n\nTrace 用于观察 agent loop 的真实执行细节。开启后会写 JSONL 文件，内容可能包含 system prompt、用户输入、工具参数/结果、provider header 等敏感信息，只建议调试时启用：\n\n```json\n{\n  \"version\": 1,\n  \"trace\": {\n    \"enabled\": false,\n    \"dir\": \"trace\",\n    \"includeSystemPrompt\": true,\n    \"includeProviderPayload\": false,\n    \"maxStringLength\": 20000\n  }\n}\n```\n\n常用命令：\n\n```text\n/helix-trace status\n/helix-trace on project\n/helix-trace off project\n/helix-trace path\n/helix-trace prompt-options\n```\n\n```json\n{\n  \"version\": 1,\n  \"runtime\": {\n    \"enabled\": true,\n    \"progress\": {\n      \"enabled\": true,\n      \"statusBar\": true,\n      \"workingMessage\": true,\n      \"activityWidget\": true,\n      \"activityLimit\": 8,\n      \"notifyPhaseChanges\": false\n    },\n    \"policy\": {\n      \"mode\": \"guided\",\n      \"requireTodosForMultiStep\": true,\n      \"requirePlanBeforeEdits\": true,\n      \"requireVerificationAfterEdits\": true,\n      \"appendToolResultAdvisories\": true,\n      \"maxToolFailuresBeforeBlocked\": 3\n    }\n  },\n  \"trace\": {\n    \"enabled\": false,\n    \"dir\": \"trace\",\n    \"includeSystemPrompt\": true,\n    \"includeProviderPayload\": false,\n    \"maxStringLength\": 20000\n  },\n  \"plugins\": [\n    {\n      \"name\": \"superpowers\",\n      \"enabled\": true,\n      \"root\": \"plugins/superpowers\",\n      \"adapter\": \"claude\",\n      \"trust\": \"trusted\",\n      \"skillPaths\": [\"skills\"],\n      \"bootstrapSkill\": \"using-superpowers\",\n      \"toolMapping\": \"claude-to-pi\"\n    }\n  ]\n}\n```\n\n相对路径都以当前 `config.json` 所在目录为基准。\n\n## 源码分层\n\nHelix 源码按功能模块组织：\n\n```text\nsrc/\n  core/       # 模块共用能力：语言策略、共享状态、命令参数解析、JSON 工具\n  config/     # Helix 配置路径、加载和合并\n  modules/\n    helix/      # /helix 与 /helix-config\n    project/    # /helix-project 与项目脚手架初始化、文档同步\n    plan-mode/  # plan mode 的 commands/tools/hooks/controller\n    runtime/    # 主 agent runtime、final gate、验证状态\n    todo/       # todo tools 与状态\n    findings/   # finding tools 与状态\n    agents/     # multi_agent、collab_task、agent discovery\n    plugins/    # plugin bridge、skill tool、插件命令\n    trace/      # collab trace\n```\n\n`extensions/index.ts` 只负责创建共享状态并注册模块；每个模块的 `index.ts` 负责本模块初始化和注册。\n\n## Project 初始化\n\n项目根目录可以通过 `.helix/scaffold.json` 声明前后端脚手架来源。`.helix` 是项目脚手架自身携带的协议目录，适合随基础项目脚手架一起迭代；`.pi/helix` 仍用于 PI/Helix 运行期配置。\n\n```json\n{\n  \"version\": 1,\n  \"components\": [\n    {\n      \"name\": \"backend\",\n      \"kind\": \"backend\",\n      \"runtime\": \"java-gradle\",\n      \"repo\": \"git@github.com:company/spring-boot-starter.git\",\n      \"mount\": \"backend\",\n      \"projectName\": \"spring-boot-starter\",\n      \"git\": {\n        \"auth\": {\n          \"mode\": \"token\",\n          \"username\": \"\",\n          \"token\": \"\",\n          \"usernameEnv\": \"BACKEND_GIT_USERNAME\",\n          \"tokenEnv\": \"BACKEND_GIT_TOKEN\"\n        }\n      }\n    },\n    {\n      \"name\": \"frontend\",\n      \"kind\": \"frontend\",\n      \"repo\": \"git@github.com:company/react-vite-starter.git\",\n      \"mount\": \"frontend\",\n      \"projectName\": \"react-vite-starter\",\n      \"git\": {\n        \"auth\": {\n          \"mode\": \"token\",\n          \"username\": \"\",\n          \"token\": \"\",\n          \"usernameEnv\": \"FRONTEND_GIT_USERNAME\",\n          \"tokenEnv\": \"FRONTEND_GIT_TOKEN\"\n        }\n      }\n    }\n  ]\n}\n```\n\n执行：\n\n```text\n/helix-project init\n```\n\nHelix 会把组件拉取到 `backend/<projectName>`、`frontend/<projectName>`，读取每个组件自己的 `.helix/commands.json`，并同步生成项目级 `.helix/commands.json`。项目级 commands 会记录每个组件的 `root`/`cwd`，命令本身仍保持“在组件根目录执行”的形式。已有组件目录默认复用；需要覆盖时使用 `/helix-project init --force`。\n\n如果组件声明了 `git.auth`，Helix 会通过 `GIT_ASKPASS` 使用配置中的 `token`，或 `tokenEnv` 指向的环境变量。缺少 token 时会直接报错，不会让 git 进入交互式用户名/密码输入。\n\n`ref` 是可选字段；不写时使用远端默认分支。只有需要固定分支或 tag 时再配置 `ref`。\n\n初始化完成后，执行依赖同步和验证：\n\n```text\n/helix-project sync\n```\n\n`sync` 会读取项目级 `.helix/commands.json`，在每个组件自己的 `cwd` 下执行依赖初始化和验证。依赖初始化优先使用组件命令中的 `sync`、`install`、`bootstrap` 或 `setup`；没有声明时会按组件 `packageManager`、lock 文件和项目文件推断 `npm install`/`npm ci`、`pnpm install`、`yarn install`、`bun install` 或 Gradle `dependencies`。验证优先执行 `requiredVerification` 引用的命令，例如 `test`、`check`；没有声明时再尝试 `verify`、`validate`、`test`、`check`、`typecheck`、`lint`、`build`，或根据 `package.json` scripts/Gradle 项目推断。\n\n可以只同步某个组件，或跳过某个阶段：\n\n```text\n/helix-project sync --component=frontend\n/helix-project sync --component=frontend,backend --skip-install\n/helix-project sync --skip-verify\n```\n\n初始化完成后会生成 `.helix/scaffold.lock.json`，记录每个组件实际落盘路径、脚手架来源、ref 和 commit。项目文档同步命令只根据这个 lock 文件读取已经初始化好的组件目录：\n\n```text\n/helix-project docs\n```\n\n该命令会从每个组件的约定文档目录中复制 `.md`、`.mdx`、`.txt` 文件到项目级 `.helix/doc/components/<component>/`，并生成：\n\n```text\n.helix/doc/README.md\n.helix/doc/manifest.json\n```\n\n`.helix/doc/README.md` 是 Helix 主流程的项目文档入口，会说明各文档路径和用途，也会写明 `.helix/doc` 是后续 vibe coding 的权威上下文。除执行 `/helix-project docs` 进行同步外，Helix runtime 不再读取前后端脚手架仓库里的原始 doc；如果脚手架文档上游变化，重新运行 `/helix-project docs` 刷新同步副本。\n\nJava Gradle 后端脚手架内的 `.helix/commands.json` 可以这样写：\n\n```json\n{\n  \"version\": 1,\n  \"runtime\": \"java-gradle\",\n  \"packageManager\": \"gradle\",\n  \"commands\": {\n    \"clean\": \"./gradlew clean\",\n    \"test\": \"./gradlew test\",\n    \"check\": \"./gradlew check\",\n    \"build\": \"./gradlew build\",\n    \"bootRun\": \"./gradlew bootRun\"\n  },\n  \"requiredVerification\": [\"test\", \"check\"]\n}\n```\n\n## Main Agent Runtime\n\nHelix Runtime 会把 PI 的通用 agent 底座增强成更结构化的 vibe coding 工作流：\n\n```text\nexploring -> planning -> implementing -> verifying -> summarizing\n```\n\n它会：\n\n- 在每轮开始时注入当前阶段、todo、变更文件、验证状态和 finalization 状态。\n- 根据工具调用更新阶段，例如 `read/grep/ls` 进入 exploring，`edit/write` 进入 implementing，测试/检查命令进入 verifying。\n- 在可能修改 workspace 的工具前后读取 `git status --porcelain`，把 `bash`、`multi_agent`、`edit/write` 造成的变更统一纳入 runtime 状态。\n- 通过 `finding_report` 记录执行途中发现的非当前任务问题，例如格式错误、不合理代码、潜在 bug 或后续优化；非阻塞 finding 不会污染 todo 完成 gate。\n- 提供 `finalize_task` 工具作为完成/阻塞的最终提交入口；完成前会检查未完成 todo、验证状态和连续工具失败。\n- 标记为 `blocking=true` 的 finding 会进入 final gate；如果未解决，完成态 finalization 会被阻止，应该用 blocked 说明。\n- 验证失败后，如果没有新的代码变更或环境修复，再次运行验证命令会被阻止；环境缺失时应通过 `finalize_task` 的 `outcome: \"blocked\"` 收束。\n- 在 guided/strict 策略下，给工具结果追加模型可见的 runtime advisory，提醒维护 todo、运行验证、处理失败。\n- 在 strict 策略下，对多步任务中“没有 todo/计划就编辑文件”、有未完成 todo 但没有 `in_progress` 就修改 workspace 的行为进行阻断。\n- 在 agent 结束时兜底检查 final gate；guided 模式会把未完成项追加到最终答复，strict 模式会自动追加 follow-up 修正轮。\n- 状态快照按当前 session branch 重建，配合 PI 的 session tree 回退时不会读取另一条分支的最后状态。\n- 用 PI 的 status bar 和 working message 显示当前阶段，不污染 LLM 上下文。\n- 用统一的 runtime UI presenter 渲染实时活动面板，避免各模块分散调用 UI。\n\n命令：\n\n```text\n/helix-runtime status\n/helix-runtime on\n/helix-runtime off\n/helix-runtime observe\n/helix-runtime guided\n/helix-runtime strict\n/helix-runtime notify on\n/helix-runtime notify off\n/helix-runtime activity on\n/helix-runtime activity off\n/helix-runtime reload\n/findings [open|resolved|dismissed|promoted]\n```\n\n策略模式：\n\n- `observe`：只记录状态和显示进度，不追加工具建议。\n- `guided`：默认模式，追加工具建议；如果 final gate 未满足，在最终答复显示未完成项，但不自动补轮。\n- `strict`：对多步任务启用更强约束，例如没有 todo/计划时阻止编辑，或者有打开的 todo 但没有当前执行项时阻止 workspace 修改；final gate 未满足时自动追加修正轮。\n\nPlan mode 也提供结构化计划入口：\n\n- `plan_submit`：计划模式下直接写入 session todo state，避免只依赖自然语言计划解析。\n- `/plan exec`：没有结构化 todos 时会阻止进入执行模式。\n- 执行模式下会注入当前 todo 列表，并要求最后通过 `finalize_task` 结束。\n\n## 插件安装\n\n安装到用户级，文件会复制到 `~/.pi/helix/plugins/<name>`：\n\n```text\n/plugin install ../superpowers\n```\n\n`install` 也可以写成 `add`，如果来源是 Git URL，Helix 会先 clone 再安装。\n\n安装到项目级：\n\n```text\n/plugin install ../superpowers --project\n```\n\n也可以写成：\n\n```text\n/plugin install ../superpowers --scope=project\n```\n\n只登记现有目录，不复制文件：\n\n```text\n/plugin install ../superpowers --link\n```\n\n`--link` 也可以写成 `--manual`。如果目标目录已经存在并希望覆盖复制，可以加：\n\n```text\n/plugin install ../superpowers --force\n```\n\n查看和检查插件：\n\n```text\n/plugin list\n/plugin ls\n/plugin doctor superpowers\n/plugin check superpowers\n```\n\n移除插件登记，不删除插件目录：\n\n```text\n/plugin remove superpowers\n/plugin rm superpowers --project\n```\n\n`/helix-plugin` 是 `/plugin` 的同功能别名。\n\nHelix 会识别：\n\n- `.claude-plugin/plugin.json`\n- `.codex-plugin/plugin.json`\n- `skills/`\n- `.claude/skills/`\n- `prompts/`\n- `.claude/commands/`\n\n对于 Superpowers 这类插件，Helix 会自动尝试加载 `skills/using-*/SKILL.md` 作为 bootstrap，并注入 Claude Code 到 PI 的工具映射。\n\n## 手动安装插件\n\n完全手动也可以。比如把插件放到：\n\n```text\n~/.pi/helix/plugins/superpowers\n```\n\n然后编辑：\n\n```text\n~/.pi/helix/config.json\n```\n\n加入：\n\n```json\n{\n  \"name\": \"superpowers\",\n  \"enabled\": true,\n  \"root\": \"plugins/superpowers\",\n  \"adapter\": \"claude\",\n  \"skillPaths\": [\"skills\"],\n  \"bootstrapSkill\": \"using-superpowers\",\n  \"toolMapping\": \"claude-to-pi\"\n}\n```\n\n重载 PI 资源：\n\n```text\n/reload\n```\n\n## Trace\n\n命令：\n\n```text\n/collab-trace on\n/collab-trace all\n/collab-trace show 80\n/collab-trace path\n/collab-trace clear\n```\n\n也可以在 Helix 配置中默认开启：\n\n```json\n{\n  \"trace\": {\n    \"enabled\": true,\n    \"mode\": \"all\",\n    \"dir\": \"trace\"\n  }\n}\n```\n\n`mode: \"collab\"` 会保留 agent/turn 生命周期、prompt/system prompt、Helix 相关工具和 skill 审计事件，并过滤普通工具调用；`mode: \"all\"` 会额外记录全部工具调用和工具结果。\n\nSkill trace 只记录能被 runtime 观察到的事实：\n\n- `skill_available`：skill 出现在 PI 原生 `<available_skills>` 清单中，模型可以选择读取。\n- `skill_loaded`：skill 内容已经进入上下文，例如 PI 原生 `read` 读取 `SKILL.md`、Helix `skill` 工具返回内容，或 bootstrap skill 被拼入 system prompt。\n\nHelix 不会从工具调用模式反推 `skill_applied`。同一个工具可能被多个 skill 描述，模型最终是否遵循某个 skill 也不是插件层能硬判定的事实。\n\n## 多 Agent 协作\n\n`multi_agent` 支持四种模式：\n\n- Single：`{ \"agent\": \"scout\", \"task\": \"...\" }`\n- Parallel：`{ \"tasks\": [{ \"agent\": \"scout\", \"task\": \"...\" }] }`\n- Chain：`{ \"chain\": [{ \"agent\": \"planner\", \"task\": \"...\" }] }`\n- Collaborate：`{ \"collaborate\": { \"objective\": \"...\", \"tasks\": [], \"workers\": [] } }`\n\nCollaborate 模式会创建 `.pi/collab-tasks/<taskListId>.json`，子 agent 通过 `collab_task` claim、update、complete 任务。\n\n协作流程中的硬约束：\n\n- `scout`、`planner`、`reviewer` 内置标记为 read-only；Helix 会用 `--plan` 和工具白名单限制它们的子进程。\n- 父会话处于 plan mode 时，所有子 agent 自动继承只读约束。\n- Chain 模式任一步失败会停止后续步骤。\n- Parallel 模式有最大任务数和并发数限制。\n- Collaborate 模式返回前会读取最终任务队列；只要有任务不是 `completed`，`multi_agent` 结果会标记为 error。\n\n## 验证工作流\n\n```text\n/collab-trace all\n```\n\n然后让主 agent 执行一个协作任务：\n\n```text\nUse multi_agent collaborate mode. Objective: inspect this repo and report the package structure. Create three tasks: scout files, summarize extension entrypoints, review task queue behavior. Use scout, planner, and reviewer workers.\n```\n\n检查：\n\n```text\n/collab-trace show 120\n/collab-tasks <taskListId>\n```\n","readmeFilename":"README.md","_rev":"1-21f1ca3a4b1cf76163d299244c44d4ff"}