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 init --update-installed 只更新符合条件的 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 工具。
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）。

将 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" 只改变旧版名称，不启用直接工具。
旧插件的工作流提醒或原生评审异常：升级 Chorus 至 0.21.1 或更新版本。该版本修复 Pi/dsh 在不同 MCP 前缀下的工作流提醒及 Pi 原生 MCP 评审兼容性。评审智能体除发布结论外仍保持只读。

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

Pi