Helix

Helix 是一个 PI package，用来补齐更接近 Claude Code 的 agentic coding 工作流：

• 主 agent runtime：阶段管理、策略约束、workspace 变更追踪、验证状态、final gate、进度提示
• Todo list：todo_read、todo_write、todo_update、todo_clear
• Web search：web_search，使用 Brave Search API 的本地 Helix 工具
• 意外发现：finding_report、finding_read、finding_update、finding_clear
• Plan mode：/plan、/plan exec、--plan、Ctrl+Alt+P
• 多 agent：multi_agent，支持 single、parallel、chain、collaborate
• 协作任务队列：collab_task
• 工作流 trace：/collab-trace
• Claude Code/Codex skills 插件兼容层：/plugin、skill
• Project 初始化、依赖同步与文档同步：/helix-project init、/helix-project sync、/helix-project docs
• Agent loop trace：/helix-trace on、/helix-trace status，记录系统提示词、provider 请求、工具调用等调试信息
• 命令说明：/helix help

启动

开发调试：

pi -e ./helix

安装到 PI：

pi install ./helix

进入 PI 后查看所有 Helix 命令：

/helix help

Tauri 客户端

仓库内提供了一个最小桌面客户端原型：

cd ../helix-client
npm install
npm run tauri:dev

客户端会启动父 PI RPC 进程：

pi --mode rpc -e <helix-path>

Helix 会通过 PI extension context 的 ctx.mode 区分运行环境：

• ctx.mode === "rpc"：视为 Helix Client / RPC 前端场景。Helix 会通过 ctx.ui.setStatus(key, JSON.stringify(payload)) 推送机器可读状态，供 helix-client 同步 runtime、tools、auth、proxy 等状态。
• ctx.mode === "tui"：普通 pi -e ./helix 终端场景。Helix 保留人类可读的 notify 反馈，但不会把给 helix-client 使用的 JSON 状态写进 TUI 状态栏。
• ctx.hasUI === false（print/json）：不会发送交互 UI；OAuth login 等需要用户输入的命令要求 TUI 或 RPC 模式。

因此 /helix-state、/helix-clear 这类命令主要是 Helix Client RPC 前端的状态同步/调试命令；普通 TUI 下通常不需要使用。

第一版只展示父 PI RPC 的消息、工具调用和 extension UI 事件；multi_agent 的子进程细节后续需要通过 Helix monitor bridge 转发。

配置层级

Helix 有自己的配置文件，不复用 package 源码目录。

默认用户级配置：

~/.pi/helix/config.json
~/.pi/helix/plugins/
~/.pi/helix/trace/

项目级配置：

<project>/.pi/helix/config.json
<project>/.pi/helix/plugins/
<project>/.pi/helix/trace/

加载规则：

• 用户级配置先加载。
• 项目级配置后加载，并覆盖同名插件和 trace 字段。
• 插件数组按 name 合并，项目级同名插件优先。
• 手动管理时，只要把插件目录放到指定位置，并在 config.json 中登记即可。

初始化配置：

/helix-config init user
/helix-config init project
/helix-config path
/helix-config show

配置示例

完整配置说明见项目内 config_example.json。

Brave Search 可配置在用户级或项目级配置中；API key 也可用环境变量 BRAVE_SEARCH_API_KEY 提供：

{
  "version": 1,
  "braveSearch": {
    "apiKey": "...",
    "count": 10,
    "country": "US",
    "searchLang": "en",
    "uiLang": "en-US",
    "safesearch": "moderate"
  }
}

Trace 用于观察 agent loop 的真实执行细节。开启后会写 JSONL 文件，内容可能包含 system prompt、用户输入、工具参数/结果、provider header 等敏感信息，只建议调试时启用：

{
  "version": 1,
  "trace": {
    "enabled": false,
    "dir": "trace",
    "includeSystemPrompt": true,
    "includeProviderPayload": false,
    "maxStringLength": 20000
  }
}

常用命令：

/helix-trace status
/helix-trace on project
/helix-trace off project
/helix-trace path
/helix-trace prompt-options

{
  "version": 1,
  "runtime": {
    "enabled": true,
    "progress": {
      "enabled": true,
      "statusBar": true,
      "workingMessage": true,
      "activityWidget": true,
      "activityLimit": 8,
      "notifyPhaseChanges": false
    },
    "policy": {
      "mode": "guided",
      "requireTodosForMultiStep": true,
      "requirePlanBeforeEdits": true,
      "requireVerificationAfterEdits": true,
      "appendToolResultAdvisories": true,
      "maxToolFailuresBeforeBlocked": 3
    }
  },
  "trace": {
    "enabled": false,
    "dir": "trace",
    "includeSystemPrompt": true,
    "includeProviderPayload": false,
    "maxStringLength": 20000
  },
  "plugins": [
    {
      "name": "superpowers",
      "enabled": true,
      "root": "plugins/superpowers",
      "adapter": "claude",
      "trust": "trusted",
      "skillPaths": ["skills"],
      "bootstrapSkill": "using-superpowers",
      "toolMapping": "claude-to-pi"
    }
  ]
}

相对路径都以当前 config.json 所在目录为基准。

源码分层

Helix 源码按功能模块组织：

src/
  core/       # 模块共用能力：语言策略、共享状态、命令参数解析、JSON 工具
  config/     # Helix 配置路径、加载和合并
  modules/
    helix/      # /helix 与 /helix-config
    project/    # /helix-project 与项目脚手架初始化、文档同步
    plan-mode/  # plan mode 的 commands/tools/hooks/controller
    runtime/    # 主 agent runtime、final gate、验证状态
    todo/       # todo tools 与状态
    findings/   # finding tools 与状态
    agents/     # multi_agent、collab_task、agent discovery
    plugins/    # plugin bridge、skill tool、插件命令
    trace/      # collab trace

extensions/index.ts 只负责创建共享状态并注册模块；每个模块的 index.ts 负责本模块初始化和注册。

Project 初始化

项目根目录可以通过 .helix/scaffold.json 声明前后端脚手架来源。.helix 是项目脚手架自身携带的协议目录，适合随基础项目脚手架一起迭代；.pi/helix 仍用于 PI/Helix 运行期配置。

{
  "version": 1,
  "components": [
    {
      "name": "backend",
      "kind": "backend",
      "runtime": "java-gradle",
      "repo": "[email protected]:company/spring-boot-starter.git",
      "mount": "backend",
      "projectName": "spring-boot-starter",
      "git": {
        "auth": {
          "mode": "token",
          "username": "",
          "token": "",
          "usernameEnv": "BACKEND_GIT_USERNAME",
          "tokenEnv": "BACKEND_GIT_TOKEN"
        }
      }
    },
    {
      "name": "frontend",
      "kind": "frontend",
      "repo": "[email protected]:company/react-vite-starter.git",
      "mount": "frontend",
      "projectName": "react-vite-starter",
      "git": {
        "auth": {
          "mode": "token",
          "username": "",
          "token": "",
          "usernameEnv": "FRONTEND_GIT_USERNAME",
          "tokenEnv": "FRONTEND_GIT_TOKEN"
        }
      }
    }
  ]
}

执行：

/helix-project init

Helix 会把组件拉取到 backend/<projectName>、frontend/<projectName>，读取每个组件自己的 .helix/commands.json，并同步生成项目级 .helix/commands.json。项目级 commands 会记录每个组件的 root/cwd，命令本身仍保持“在组件根目录执行”的形式。已有组件目录默认复用；需要覆盖时使用 /helix-project init --force。

如果组件声明了 git.auth，Helix 会通过 GIT_ASKPASS 使用配置中的 token，或 tokenEnv 指向的环境变量。缺少 token 时会直接报错，不会让 git 进入交互式用户名/密码输入。

ref 是可选字段；不写时使用远端默认分支。只有需要固定分支或 tag 时再配置 ref。

初始化完成后，执行依赖同步和验证：

/helix-project sync

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 项目推断。

可以只同步某个组件，或跳过某个阶段：

/helix-project sync --component=frontend
/helix-project sync --component=frontend,backend --skip-install
/helix-project sync --skip-verify

初始化完成后会生成 .helix/scaffold.lock.json，记录每个组件实际落盘路径、脚手架来源、ref 和 commit。项目文档同步命令只根据这个 lock 文件读取已经初始化好的组件目录：

/helix-project docs

该命令会从每个组件的约定文档目录中复制 .md、.mdx、.txt 文件到项目级 .helix/doc/components/<component>/，并生成：

.helix/doc/README.md
.helix/doc/manifest.json

.helix/doc/README.md 是 Helix 主流程的项目文档入口，会说明各文档路径和用途，也会写明 .helix/doc 是后续 vibe coding 的权威上下文。除执行 /helix-project docs 进行同步外，Helix runtime 不再读取前后端脚手架仓库里的原始 doc；如果脚手架文档上游变化，重新运行 /helix-project docs 刷新同步副本。

Java Gradle 后端脚手架内的 .helix/commands.json 可以这样写：

{
  "version": 1,
  "runtime": "java-gradle",
  "packageManager": "gradle",
  "commands": {
    "clean": "./gradlew clean",
    "test": "./gradlew test",
    "check": "./gradlew check",
    "build": "./gradlew build",
    "bootRun": "./gradlew bootRun"
  },
  "requiredVerification": ["test", "check"]
}

Main Agent Runtime

Helix Runtime 会把 PI 的通用 agent 底座增强成更结构化的 vibe coding 工作流：

exploring -> planning -> implementing -> verifying -> summarizing

它会：

• 在每轮开始时注入当前阶段、todo、变更文件、验证状态和 finalization 状态。
• 根据工具调用更新阶段，例如 read/grep/ls 进入 exploring，edit/write 进入 implementing，测试/检查命令进入 verifying。
• 在可能修改 workspace 的工具前后读取 git status --porcelain，把 bash、multi_agent、edit/write 造成的变更统一纳入 runtime 状态。
• 通过 finding_report 记录执行途中发现的非当前任务问题，例如格式错误、不合理代码、潜在 bug 或后续优化；非阻塞 finding 不会污染 todo 完成 gate。
• 提供 finalize_task 工具作为完成/阻塞的最终提交入口；完成前会检查未完成 todo、验证状态和连续工具失败。
• 标记为 blocking=true 的 finding 会进入 final gate；如果未解决，完成态 finalization 会被阻止，应该用 blocked 说明。
• 验证失败后，如果没有新的代码变更或环境修复，再次运行验证命令会被阻止；环境缺失时应通过 finalize_task 的 outcome: "blocked" 收束。
• 在 guided/strict 策略下，给工具结果追加模型可见的 runtime advisory，提醒维护 todo、运行验证、处理失败。
• 在 strict 策略下，对多步任务中“没有 todo/计划就编辑文件”、有未完成 todo 但没有 in_progress 就修改 workspace 的行为进行阻断。
• 在 agent 结束时兜底检查 final gate；guided 模式会把未完成项追加到最终答复，strict 模式会自动追加 follow-up 修正轮。
• 状态快照按当前 session branch 重建，配合 PI 的 session tree 回退时不会读取另一条分支的最后状态。
• 用 PI 的 status bar 和 working message 显示当前阶段，不污染 LLM 上下文。
• 用统一的 runtime UI presenter 渲染实时活动面板，避免各模块分散调用 UI。

命令：

/helix-runtime status
/helix-runtime on
/helix-runtime off
/helix-runtime observe
/helix-runtime guided
/helix-runtime strict
/helix-runtime notify on
/helix-runtime notify off
/helix-runtime activity on
/helix-runtime activity off
/helix-runtime reload
/findings [open|resolved|dismissed|promoted]

策略模式：

• observe：只记录状态和显示进度，不追加工具建议。
• guided：默认模式，追加工具建议；如果 final gate 未满足，在最终答复显示未完成项，但不自动补轮。
• strict：对多步任务启用更强约束，例如没有 todo/计划时阻止编辑，或者有打开的 todo 但没有当前执行项时阻止 workspace 修改；final gate 未满足时自动追加修正轮。

Plan mode 也提供结构化计划入口：

• plan_submit：计划模式下直接写入 session todo state，避免只依赖自然语言计划解析。
• /plan exec：没有结构化 todos 时会阻止进入执行模式。
• 执行模式下会注入当前 todo 列表，并要求最后通过 finalize_task 结束。

插件安装

安装到用户级，文件会复制到 ~/.pi/helix/plugins/<name>：

/plugin install ../superpowers

install 也可以写成 add，如果来源是 Git URL，Helix 会先 clone 再安装。

安装到项目级：

/plugin install ../superpowers --project

也可以写成：

/plugin install ../superpowers --scope=project

只登记现有目录，不复制文件：

/plugin install ../superpowers --link

--link 也可以写成 --manual。如果目标目录已经存在并希望覆盖复制，可以加：

/plugin install ../superpowers --force

查看和检查插件：

/plugin list
/plugin ls
/plugin doctor superpowers
/plugin check superpowers

移除插件登记，不删除插件目录：

/plugin remove superpowers
/plugin rm superpowers --project

/helix-plugin 是 /plugin 的同功能别名。

Helix 会识别：

• .claude-plugin/plugin.json
• .codex-plugin/plugin.json
• skills/
• .claude/skills/
• prompts/
• .claude/commands/

对于 Superpowers 这类插件，Helix 会自动尝试加载 skills/using-*/SKILL.md 作为 bootstrap，并注入 Claude Code 到 PI 的工具映射。

手动安装插件

完全手动也可以。比如把插件放到：

~/.pi/helix/plugins/superpowers

然后编辑：

~/.pi/helix/config.json

加入：

{
  "name": "superpowers",
  "enabled": true,
  "root": "plugins/superpowers",
  "adapter": "claude",
  "skillPaths": ["skills"],
  "bootstrapSkill": "using-superpowers",
  "toolMapping": "claude-to-pi"
}

重载 PI 资源：

/reload

Trace

命令：

/collab-trace on
/collab-trace all
/collab-trace show 80
/collab-trace path
/collab-trace clear

也可以在 Helix 配置中默认开启：

{
  "trace": {
    "enabled": true,
    "mode": "all",
    "dir": "trace"
  }
}

mode: "collab" 会保留 agent/turn 生命周期、prompt/system prompt、Helix 相关工具和 skill 审计事件，并过滤普通工具调用；mode: "all" 会额外记录全部工具调用和工具结果。

Skill trace 只记录能被 runtime 观察到的事实：

• skill_available：skill 出现在 PI 原生 <available_skills> 清单中，模型可以选择读取。
• skill_loaded：skill 内容已经进入上下文，例如 PI 原生 read 读取 SKILL.md、Helix skill 工具返回内容，或 bootstrap skill 被拼入 system prompt。

Helix 不会从工具调用模式反推 skill_applied。同一个工具可能被多个 skill 描述，模型最终是否遵循某个 skill 也不是插件层能硬判定的事实。

多 Agent 协作

multi_agent 支持四种模式：

• Single：{ "agent": "scout", "task": "..." }
• Parallel：{ "tasks": [{ "agent": "scout", "task": "..." }] }
• Chain：{ "chain": [{ "agent": "planner", "task": "..." }] }
• Collaborate：{ "collaborate": { "objective": "...", "tasks": [], "workers": [] } }

Collaborate 模式会创建 .pi/collab-tasks/<taskListId>.json，子 agent 通过 collab_task claim、update、complete 任务。

协作流程中的硬约束：

• scout、planner、reviewer 内置标记为 read-only；Helix 会用 --plan 和工具白名单限制它们的子进程。
• 父会话处于 plan mode 时，所有子 agent 自动继承只读约束。
• Chain 模式任一步失败会停止后续步骤。
• Parallel 模式有最大任务数和并发数限制。
• Collaborate 模式返回前会读取最终任务队列；只要有任务不是 completed，multi_agent 结果会标记为 error。

验证工作流

/collab-trace all

然后让主 agent 执行一个协作任务：

Use 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.

检查：

/collab-trace show 120
/collab-tasks <taskListId>