Pi

Pi 编码智能体是 Chorus 的官方集成，以已发布的 npm 包 @chorus-aidlc/chorus-pi 形式分发。它通过 Pi 原生的扩展、技能和智能体机制，提供 Chorus 工作流技能、只读评审子智能体、 Pi 官方的 subagent 工具，以及会话感知的扩展钩子，只需一条 pi install 即可安装。

Pi 还可以作为可唤醒的 --agent pi 后台服务后端运行：有工作被远程发给 Pi 时，Chorus 后台服务会唤醒一个 无头 Pi 会话，因此 Pi 能像 Claude Code、Codex 和 Kiro 一样参与反向对话循环。

安装前，请按照为智能体创建访问权限创建一个智能体密钥。

推荐：自动配置

运行以下命令，按提示输入 Chorus 网址和智能体密钥：

chorus agents add --agents pi

对受支持的稳定版 Pi，它会安装 chorus-pi，并自动写好 MCP 配置：原生 MCP 写入 ~/.pi/agent/mcp.json，旧版适配器写入 ~/.pi/agent/mcp-adapter.json，两者都遵循 PI_CODING_AGENT_DIR。原生 Pi 使用内置 MCP 能力，无需安装适配器，也无需另行执行 pi mcp add。自动配置成功后，不用再做下文手动步骤 1–3。

要在交互会话中也免去手动导出凭据，可先列出已配置的智能体，再按名称或 UUID 启动 Pi 智能体：

chorus agents
chorus agents run <name-or-uuid>

启动器会从已保存的智能体配置注入 CHORUS_URL、CHORUS_API_KEY 和 CHORUS_AGENT_PROFILE，之后直接验证连接。只有直接运行 pi 时，才需在启动它的 shell 中提供密钥；后台唤醒同样会自动注入凭据。如果已有旧适配器或禁用了内置 MCP，仍需按下文迁移说明清理冲突。

选择 MCP 后端

安装前运行 pi --version，确认使用稳定版。Chorus 0.21.1 的 chorus agents add --agents pi 会按版本选择后端：

Pi 版本	MCP 后端	安装的包
>=0.99.0 <2.0.0	原生 MCP	仅 @chorus-aidlc/chorus-pi
0.84.4–0.98.x	旧版适配器	pi-mcp-adapter@5.0.0 和 @chorus-aidlc/chorus-pi

不支持更早版本或 Pi 2.x，安装器不会对它们执行包操作。版本未知或为预发布版时，不会变更适配器，也不会宣称 MCP 配置完成。请先安装受支持的稳定版。远程后台唤醒还要求在该范围内使用 Pi 0.85.0 或更新版本。

无需单独安装子智能体包，chorus-pi 已捆绑 Pi 官方的 subagent 工具。另需准备 Chorus API 密钥。以下步骤用于手动配置。

手动步骤 1：导出环境变量

export CHORUS_URL="http://localhost:8637"
export CHORUS_API_KEY="cho_REDACTED"

在启动交互式 Pi 的 shell 中设置这些值，安装器不会把它们存入 Pi 的 env 文件。CHORUS_URL 可为根 URL 或完整的 /api/mcp 端点。要选择已配置的智能体，还可设置 CHORUS_AGENT_PROFILE。后台唤醒会自动注入这些变量。

显式环境变量优先。Chorus 扩展也会从下文对应的全局 MCP 文件读取会话和签到凭据，但不会发现原生项目级 .pi/mcp.json，因此仅配置项目文件时仍需导出上述两个变量。

手动步骤 2：按 Pi 版本配置 MCP

原生 MCP：稳定版 Pi >=0.99.0 <2.0.0

pi mcp add chorus --url "http://localhost:8637/api/mcp" --bearer-token-env-var CHORUS_API_KEY
pi mcp list

该命令写入 ~/.pi/agent/mcp.json，可用 PI_CODING_AGENT_DIR 覆盖智能体目录。项目级配置使用 pi mcp add --local，文件为 .pi/mcp.json，需要信任项目，不是根目录的 .mcp.json。

等效的全局配置如下：

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "http://localhost:8637/api/mcp",
      "headers": { "Authorization": "Bearer ${CHORUS_API_KEY}" }
    }
  }
}

原生 MCP 默认使用 codemode，无需强制直接暴露工具。pi mcp list 检查内置 MCP，而已安装的适配器仍可能接管交互式 /mcp 命令。

旧版适配器：Pi 0.84.4–0.98.x

运行 pi install npm:pi-mcp-adapter@5.0.0。将上述 JSON 写入 ~/.pi/agent/mcp-adapter.json（或 $PI_CODING_AGENT_DIR/mcp-adapter.json），并在 mcpServers.chorus 中添加 "directTools": true。修改 toolPrefix 仅改变名称，不会启用直接工具。

两种后端都能解析 ${CHORUS_API_KEY}，请把真实密钥留在环境变量中。旧版 adapter5 也支持发现或导入旧配置，但全局 mcp.json 已不是其主配置文件。

chorus agents add 保留已有的直接工具选择、其他服务器和设置。旧版主配置不存在时，会复制旧全局 mcp.json 到新主配置并保留原文件；主配置已存在时以它为准，不覆盖格式错误或不可读的文件。生成的 Chorus 请求头引用环境变量，不写入真实密钥。

升级与迁移已有适配器

chorus upgrade --plugins 以及在 chorus agents add 中接受的插件更新只更新符合条件的 Chorus 组件，不更新所有扩展或 Pi 本身。旧版保留已验证的适配器 5.0.0 固定版本，不追随 latest。其他适配器约束及 Chorus 固定版本或范围也会保留，可能导致配置或最新版本刷新未完成。

在原生宿主上，Chorus 只对已有适配器或 -builtin:mcp 扩展过滤器发出警告。若选择原生 MCP，请检查全局 ~/.pi/agent/settings.json（遵循 PI_CODING_AGENT_DIR）与项目 .pi/settings.json，仅在原配置作用域移除适配器和该过滤器，保留其他设置。pi remove npm:pi-mcp-adapter 用于全局 npm 安装，不适用于项目级条目。重启 Pi 后验证实际工具，写入配置本身并不证明连接已恢复。

手动步骤 3：安装 chorus-pi 包

pi install npm:@chorus-aidlc/chorus-pi

这就是全部安装步骤。subagent 工具随包内置，三个评审智能体直接从包自带的 agents/ 目录中发现， 既无需单独的子智能体依赖，也无需手动把智能体文件复制到 ~/.pi/agent/agents/。重启 Pi （/reload 或开启新会话），以便加载扩展、技能和评审智能体。

在本地开发 chorus-pi？改从仓库检出安装：pi install ./packages/chorus-pi。

验证连接

重启 Pi，查看 /mcp，并请求 Pi 调用 chorus_checkin。确认返回结果显示预期的智能体身份和权限，并且 首个回合报告了包含你签到信息的 # Chorus Plugin — Active 上下文。输入 /skill:chorus 确认技能已加载， 并在 /subagents 中查看是否有 chorus-proposal-reviewer。

能力

• 14 个技能，驱动每个 AI-DLC 阶段：/skill:chorus、/skill:idea、/skill:proposal、 /skill:develop、/skill:review、/skill:quick-dev、/skill:yolo、/skill:brainstorm、 /skill:orchestrate、/skill:docs、/skill:chorus-cli，外加 openspec-aware、spec-lite 与 research 子流程。 research 是想法与提案技能调用的简短事实调研流程，也是想法的调研操作所运行的流程。
• 3 个只读评审子智能体：chorus-proposal-reviewer、chorus-task-reviewer、 chorus-code-reviewer，从包内目录发现（无需复制），通过 subagent 工具派生； 它们发布一条 VERDICT 评论后停止。使用社区的 pi-subagents 包时，调用中直接点名的 Chorus 评审 子智能体和 worker 一律在后台运行（即使调用要求 async: false），扩展会把它们固定在后台运行路径上。
• 子智能体的按角色划分 Chorus 工具（Chorus 0.22.1 及以上）：每个评审子智能体只通过自己的 chorus_review 工具访问 Chorus（查询、签到和评论操作）；内置的 chorus-worker 使用 chorus_work， 在此基础上增加任务认领、释放、更新、汇报、自检、提交验证，以及会话签入/签出操作。两者在原生 MCP 和旧版适配器宿主上都能使用，无需任何 MCP 网关工具，也无需修改配置。两种角色都不允许管理操作、 创建实体或创建与关闭会话。调用 chorus_review({ action: "discover" }) 或 chorus_work({ action: "discover" }) 可列出允许的操作。这是工具策略，不是沙箱：bash、网络访问和 继承的凭据都不受隔离。
• Pi 官方的 subagent 工具，内置于 extensions/subagent/（Pi 的参考实现），无需任何第三方 子智能体包。它同时与社区的 pi-subagents 包（nicobailon）共存：两者都注册名为 subagent 的工具，因此需通过 settings.packages 过滤器排除内置的那一个；chorus-pi 的会话生命周期既支持 该包的异步 / detached subagent 运行，也支持内置的阻塞式运行。过滤器与配置详见 chorus-pi README。
• 会话感知扩展，订阅 Pi 的原生事件（session_start → chorus_checkin + 规格模式解析， subagent 上的 tool_call → 每个 worker 的 Chorus 会话，tool_result → 关闭 worker 会话 + 评审 提示，session_shutdown → 清理）。

该扩展通过环境变量配置（Pi 没有插件设置界面）。CHORUS_SPEC_MODE 可指定 openspec、lite 或 off；未指定时，优先使用可用的 OpenSpec，否则使用 spec-lite。旧的 CHORUS_OPENSPEC_MODE=off 只禁用 OpenSpec，回退结果是 lite 而非自由格式。不想生成本地规格文件时，请设 CHORUS_SPEC_MODE=off。 详见 OpenSpec 模式与 Spec-lite 模式。 评审开关仍是 CHORUS_ENABLE_{PROPOSAL,TASK,CODE}_REVIEWER（默认 true）。

可选的提交前回读检查

chorus-pi 扩展提供可选的调用顺序提醒，默认关闭。在启动 Pi 的进程环境中设置变量，然后重启 Pi：

CHORUS_SUBMIT_GATE=warn pi

• off（未设置或无法识别的值也一样）：不执行检查。
• warn：显示警告，但仍执行工具调用。
• block：阻止识别到的提交调用，直到补齐或刷新回读。

后台服务唤醒时，在 ~/.chorus/daemon.json 中 Pi 智能体现有的 env 对象里加入 "CHORUS_SUBMIT_GATE": "block"，然后重启后台服务。这是 Pi 进程环境设置，不是 MCP 服务器配置项，也不是 CHORUS_ENABLE_*_REVIEWER 开关。无人值守时不要依赖可见警告，需要阻止提交就使用 block。

在 chorus_submit_for_verify 前，必须在该任务最近一次变更后用 chorus_get_task 回读同一个任务，确认是 in_progress；列表或指派查询不算回读。在 chorus_pm_submit_proposal 前调用 chorus_pm_validate_proposal，之后编辑草稿会使校验凭据失效。返回 valid: false 会触发检查失败，建议性警告仍需自行判断。带 status 的工作报告会使任务回读失效，不带则不会。提交会消耗凭据，再次提交需要重新回读。变更前启动的读取即使稍后完成，也不能证明变更后的状态。

这只是本地调用顺序追踪，不是服务器校验、授权边界或验收评审。它监听 Pi 事件中可识别的外层工具名，包括原生 MCP（mcp__chorus__…）和旧版直接工具（chorus_chorus_…），不检查 shell 命令或通用分发器内嵌的调用，也无法感知其他客户端的修改。状态检查依赖可解析的结果，最终仍由服务器判定。它不会自动修复状态、自检验收标准或启动评审者。汇报 → 自检 → 回读 → 显式提交的顺序，以及误改状态后的恢复方法，参阅运行任务。

将 Pi 作为可唤醒的后台服务后端运行

Pi 是完整支持的可唤醒后台服务后端，有工作被远程发给它时（分配给你的智能体的想法/任务、 一次 @提及、一个提案决策），Chorus 后台服务会唤醒一个无头 Pi 会话。

最简单的方式是运行 chorus agents add --agents pi：按 Pi 版本选择原生 MCP 或已验证的旧版适配器，安装 chorus-pi，并在 ~/.chorus/daemon.json 中登记 Pi。经你同意后，还会安装后台开机服务。手动启动后端可运行：

chorus daemon --agent pi

• 后台服务从 PATH 解析 pi 可执行文件（可用 CHORUS_PI_PATH 覆盖），每次唤醒启动一个无头的 pi --mode rpc 进程，并把 CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE 导出到被唤醒 的会话中。后台唤醒需要 Pi 0.85.0 或更新版本，详见 0.20.0 的 daemon 行为。
• Pi 没有权限系统，因此不涉及沙箱 / 跳过权限的标志，chorus 与 yolo 两种后台服务模式运行 Pi 的方式完全一致。
• 请在后台服务唤醒的环境中保留 chorus-pi 和对应版本的 MCP 配置；原生 Pi 不需要适配器。

后台服务提供 Chorus 连接（CHORUS_URL、CHORUS_API_KEY 和 CHORUS_AGENT_PROFILE），但不会 替你获取模型提供方凭据。可通过 ~/.chorus/daemon.json 中该智能体的 env 提供，也可使用后台服务继承的环境或 提供方支持的凭据存储。systemd --user 服务不会继承登录 shell 中导出的变量。管理后台服务 说明了模型与思考参数、每智能体 env、服务凭据和重启要求。

0.20.0 的 daemon 行为

从 Chorus 0.20.0 起，每次 Pi 唤醒都通过 Pi 的 RPC 模式运行，不再回退到之前的无头模式。因此请在每台运行 后台服务的主机上升级 Pi：

pi --version                                                # 需要 0.85.0 或更新版本
npm install -g "@earendil-works/pi-coding-agent@>=0.85.0 <2.0.0"       # 升级 pi 本身

chorus upgrade --plugins 更新符合条件的 Chorus 组件，不升级 Pi 本身；旧版 adapter5 按上文保留固定版本。RPC 传输已在 Linux 上用 Pi 0.85.1 验证。

• Pi 版本过旧：后台服务会跳过这次唤醒，并在日志中给出上面的升级命令。如果读取不到 Pi 版本， 后台服务会记录警告并照常尝试唤醒。
• 会话连续性：每个想法保留自己的 Pi 会话，升级前创建的会话也一样。如果 Pi 无法恢复之前会话的 历史，唤醒会在新会话中继续，对话中会显示一条提示，说明之前的历史无法恢复。
• 打断：在 Chorus 中点击打断会通过 RPC abort 停止 Pi 当前的运行（包括正在执行的工具）；即使 Pi 进程以退出码 0 结束，该轮仍记录为 已中断。如果 sigintTimeoutMs 到期时 Pi 仍在运行，后台服务会像以前一样强制停止它。
• 扩展对话框：唤醒期间没有人在终端前，因此扩展弹出的对话框（select、confirm、input 或 editor）会被立即取消，后台服务日志记录 cancelled pi extension <method> dialog。请改用 Chorus 评论或需求细化提问。
• 查找进程：Pi 会把进程名改为 pi，所以在 Linux 上 pgrep -f 'pi --mode rpc' 找不到它。请使用 pgrep -x pi -P <daemon-pid>。

常见问题

• 找不到 MCP 服务器：检查上文对应版本的配置文件。原生 Pi 可运行 pi mcp list；若交互工具不同，还需检查项目是否受信任、旧适配器及 -builtin:mcp 过滤器。
• 技能或评审智能体未加载：确认已安装 chorus-pi 并重启 Pi。评审智能体随包提供，无需手动复制或另装子智能体包。
• 连接未授权：检查启动 shell 的 CHORUS_URL、CHORUS_API_KEY，然后重启 Pi。不要把真实密钥写入共享配置。
• 工具名称不同：先发现实际工具，不要猜测。原生 MCP 使用 mcp__chorus__chorus_checkin 等名称，旧版直接工具常用 chorus_chorus_checkin。toolPrefix: "none" 只改变旧版名称，不启用直接工具。
• 评审子智能体或 worker 无法访问 Chorus 工具：升级 Chorus 至 0.22.1 或更新版本。该版本在原生 MCP 和适配器宿主上恢复了按角色划分的 chorus_review 与 chorus_work 工具。如果你把内置的智能体文件复制到了其他位置，请更新其中的 subagentOnlyExtensions 提供者路径。不同 MCP 前缀下的工作流提醒需要 0.21.1 或更新版本。评审智能体除发布结论外仍保持只读。

通用连接问题见排查智能体连接故障。