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

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

安装前，请按照[为智能体创建访问权限](/zh/guides/administrator-setup/)创建一个智能体密钥。

## 推荐：自动配置

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

```sh
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 智能体：

```sh
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：导出环境变量

```bash
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`

```bash
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`。

等效的全局配置如下：

```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 包

```bash
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` 是想法与提案技能调用的简短事实调研流程，也是想法的[**调研**操作](/zh/guides/capture-an-idea/#在开发之前请求调研)所运行的流程。
- **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](https://www.npmjs.com/package/@chorus-aidlc/chorus-pi)。
- **会话感知扩展**，订阅 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 模式](/zh/guides/openspec-mode/)与 [Spec-lite 模式](/zh/guides/spec-lite-mode/)。
评审开关仍是 `CHORUS_ENABLE_{PROPOSAL,TASK,CODE}_REVIEWER`（默认 `true`）。

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

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

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

```bash
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 行为](#0200-的-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 中导出的变量。[管理后台服务](/zh/guides/daemon-operations/)
说明了模型与思考参数、每智能体 env、服务凭据和重启要求。

### 0.20.0 的 daemon 行为

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

```bash
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 评审兼容性。评审智能体除发布结论外仍保持只读。

通用连接问题见[排查智能体连接故障](/zh/guides/troubleshooting/)。