pi-subagents 插件使用指南

"
本文档记录 pi-subagents 插件（v0.40.0）的整体使用方式，以及如何为子代理指定模型。覆盖了大多数使用场景，内容较多请耐心阅读。

我个人的 pi agent 插件清单可以参考这篇文档：我的 Pi Agent 插件清单

#目录

概述
内置子代理一览
使用方式（三种入口）

3.1 自然语言
3.2 斜杠命令
3.3 工具调用（编程式）

执行模式详解

4.1 单代理
4.2 链式（Chain）
4.3 并行（Parallel）
4.4 后台（Async）
4.5 分支上下文（Fork）
4.6 工作树隔离（Worktree）

看门狗（Watchdog）
原生监督协调
指定模型

7.1 单次运行时指定
7.2 全局默认模型
7.3 按代理覆盖（agentOverrides）
7.4 Agent 文件 frontmatter 指定
7.5 看门狗模型独立配置
7.6 优先级总结

Chorus Reviewer 的模型配置
推荐代理分层策略
常用工作流

#1. 概述

pi-subagents 是一个 Pi 扩展，让主 Pi 会话可以把工作委托给子代理（child agent）。子代理是独立的 Pi 子进程，有明确的任务描述、工具白名单和能力边界。

安装命令：pi install npm:pi-subagents

支持模式：

单代理（Single）- 一个子代理执行一个任务
链式（Chain）- 顺序执行，上一步输出传递给下一步
并行（Parallel）- 多个子代理同时执行
后台（Async）- 子代理后台独立运行，不阻塞主会话
分支上下文（Fork）- 从父会话当前节点创建真正的分支会话
工作树隔离（Worktree）- 每个子代理在独立 git worktree 中工作

#2. 内置子代理一览

代理	用途	关键工具	思维方式
scout	快速代码库侦察：入口点、类型、数据流、风险	read, grep, find, ls, bash, write, intercom	low
researcher	网络/文档研究，返回来源明确的研究简报	需要 `pi-web-access` 扩展	—
planner	生成实现计划，不修改代码	read, grep, find, ls, bash, write, intercom	high
worker	实现任务，编辑文件，验证结果	read, grep, find, ls, bash, edit, write, contact_supervisor	high
reviewer	代码审查、差异检查、计划验证	read, grep, find, ls, bash, edit, write, intercom	high
oracle	第二意见，挑战假设，建议最优下一步	read, grep, find, ls, bash, write, intercom	high
advisor	oracle 的同义词（兼容 Claude Code 命名）	同 oracle	high
delegate	轻量级通用委托代理，行为接近父会话	继承父会话	—
context-builder	更强的上下文构建传递	read, grep, find, ls, bash, write, intercom	—

简单规则：

scout — 理解代码之前
researcher — 信任外部事实之前
planner — 开始大的变更之前
worker — 实现时
reviewer — 检查时
oracle — 决策本身有风险时

#3. 使用方式（三种入口）

3.1 自然语言

帮我 review 这个 diff用 oracle 给我当前的方案提供第二意见用 scout 理解这个代码库并行跑三个 reviewer：一个检查正确性，一个检查测试，一个检查复杂度后台运行这个实现，完成后通知我用 worker 实现这个批准的计划，然后并行跑 reviewer，汇总反馈后应用修复让 scout 先理解代码，然后 planner 制定计划，最后 worker 实现

3.2 斜杠命令

命令	说明
`/run scout "扫描代码库"`	运行单个代理
`/run scout[model=anthropic/claude-sonnet-4] "扫描"`	运行时指定模型
`/chain scout "扫描" -> planner "规划" -> worker "实现"`	链式执行
`/chain scout "扫描" -> (reviewer "A" \| reviewer "B") -> writer "修复"`	链式中内联并行组
`/parallel reviewer "A" -> reviewer "B"`	并行执行
`/run-chain <chainName> -- <task>`	运行保存的工作流
`/subagents [agent]`	交互式查看/编辑代理配置
`/subagents-models [agent]`	查看运行时模型映射
`/subagents-watchdog [status\|on\|off\|check]`	看门狗配置
`/subagents-fleet`	查看活跃子代理舰队
`/subagents-doctor`	诊断检查
`/subagent-cost`	查看 token 用量和费用
`/subagents-profiles`	列出保存的代理配置文件
`/subagents-detach [run-id]`	分离前台运行而不终止

链式命令进阶：

# 带输出和读取/chain scout[output=context.md] "扫描代码" -> planner[reads=context.md] "分析"# 后台运行/chain scout "分析" -> planner "设计" -> worker "实现" --bg# 分支上下文/run reviewer "审查这个 diff" --fork# 组合使用/run reviewer "审查" --fork --bg

3.3 工具调用（编程式）

// ── 单代理 ──────────────────────────────────────subagent({ agent: "worker", task: "重构 auth 模块" })subagent({ agent: "scout", task: "扫描代码", output: false })subagent({ agent: "scout", task: "输出到大文件", output: "reports/scout.md", outputMode: "file-only" })// ── 并行 ────────────────────────────────────────subagent({ tasks: [  { agent: "scout", task: "扫描前端" },  { agent: "reviewer", task: "审查后端" }]})// 并行 + 分支上下文subagent({ tasks: [  { agent: "scout", task: "审计前端" },  { agent: "reviewer", task: "审计后端" }], context: "fork" })// ── 链式 ────────────────────────────────────────subagent({ chain: [  { agent: "scout", task: "收集上下文" },  { agent: "planner" },  { checkpoint: "审批", message: "批准再实施？" },  { agent: "worker" },  { agent: "reviewer" }]})// 链式 + 并行展开subagent({ chain: [  { agent: "scout", task: "收集上下文", phase: "Context", as: "context" },  { parallel: [    { agent: "worker", task: "实现功能 A", as: "featureA" },    { agent: "worker", task: "实现功能 B", as: "featureB" }  ], concurrency: 2, failFast: true },  { agent: "reviewer", task: "审查 {outputs.featureA} 和 {outputs.featureB}" }]})// ── 后台 ────────────────────────────────────────subagent({ agent: "worker", task: "实现...", async: true })subagent({ chain: [...], async: true })// ── 工作树隔离 ──────────────────────────────────subagent({ tasks: [  { agent: "worker", task: "实现 auth" },  { agent: "worker", task: "实现 API" }], worktree: true })// ── 管理操作 ────────────────────────────────────subagent({ action: "list" })                        // 列出可用代理subagent({ action: "get", agent: "scout" })          // 查看代理详情subagent({ action: "models" })                       // 查看模型映射subagent({ action: "models", agent: "reviewer" })    // 查看特定代理模型subagent({ action: "doctor" })                       // 诊断// ── 状态与控制 ──────────────────────────────────subagent({ action: "status" })                       // 查看状态subagent({ action: "status", id: "<run-id>" })       // 查看特定运行subagent({ action: "status", view: "fleet" })        // 舰队视图subagent({ action: "interrupt", id: "<run-id>" })    // 软中断subagent({ action: "stop", id: "<run-id>" })         // 停止subagent({ action: "resume", id: "<run-id>", message: "继续" })  // 恢复subagent({ action: "steer", id: "<run-id>", message: "方向调整" })  // 引导

#4. 执行模式详解

4.1 单代理

最简单的模式，一个子代理执行一个任务。

# 自然语言用 scout 扫描这个代码库# 斜杠命令/run scout "分析 auth 模块"# 工具调用subagent({ agent: "scout", task: "分析 auth 模块" })

4.2 链式（Chain）

顺序执行，上一步的输出通过 {previous} 传递给下一步。

# 自然语言先用 scout 理解代码，然后用 planner 制定计划，最后用 worker 实现# 斜杠命令/chain scout "扫描代码库" -> planner "制定实现计划" -> worker "实现"# 带有输出引用的链式/chain scout[output=context.md] "扫描" -> planner[reads=context.md] "计划" -> worker "实现"# 工具调用subagent({ chain: [  { agent: "scout", task: "收集上下文" },  { agent: "planner" },  { agent: "worker" },  { agent: "reviewer" }]})

链式变量：

变量	说明
`{task}`	第一个步骤的原始任务
`{previous}`	上一步的输出
`{chain_dir}`	链式产物目录路径
`{outputs.name}`	通过 `as: "name"` 标记的步骤输出

4.3 并行（Parallel）

多个子代理同时执行，适合独立的任务。

# 自然语言并行跑三个 reviewer，一个检查正确性，一个检查测试，一个检查简洁性# 斜杠命令/parallel scout "扫描前端" -> reviewer "审查后端"# 链式中内联并行组/chain scout "扫描" -> (reviewer "审查 A" | reviewer "审查 B") -> writer "修复"# 工具调用subagent({ tasks: [  { agent: "scout", task: "扫描前端" },  { agent: "reviewer", task: "审查后端" }], concurrency: 2 })

4.4 后台（Async）

子代理在后台独立运行，不阻塞主会话。

# 自然语言后台运行这个实现，完成后通知我# 斜杠命令/run scout "审计代码库" --bg/chain scout "分析" -> planner "设计" -> worker "实现" --bg# 工具调用subagent({ agent: "worker", task: "实现...", async: true })

后台完成后会收到通知。通过 subagent({ action: "status" }) 查看状态。

4.5 分支上下文（Fork）

从父会话的当前节点创建真正的分支会话，子代理能看到父会话的历史对话。

# 斜杠命令/run reviewer "审查" --fork/chain scout "分析" -> planner "计划" --fork# 工具调用subagent({ agent: "reviewer", task: "审查", context: "fork" })

"
注意：如果父会话使用了 Anthropic 模型的 thinking 块，分支上下文会强制子代理关闭 thinking。需要 thinking 的子代理应使用 context: "fresh"。

4.6 工作树隔离（Worktree）

每个子代理在独立的 git worktree 中工作，避免并行编辑冲突。

# 工具调用subagent({ tasks: [  { agent: "worker", task: "实现功能 A" },  { agent: "worker", task: "实现功能 B" }], worktree: true })

要求：

在 git 仓库内运行
工作区必须干净
node_modules/ 会自动符号链接到 worktree 中

#5. 看门狗（Watchdog）

可选的对抗性审查机制，在 agent_end 边界自动审查代码变更。

# 开启看门狗/subagents-watchdog on# 推荐看门狗模型/subagents-watchdog recommend-model# 设置特定模型/subagents-watchdog model anthropic/claude-opus-4-8:high# 检查状态/subagents-watchdog status# 手动触发检查/subagents-watchdog check

配置：

{"subagents":{"watchdog":{"enabled":true,"main":{"model":"anthropic/claude-opus-4-8","thinking":"high"},"scope":{"enabled":true},"cadence":{"everyNTools":10},"autoFollow":{"blockers":true,"maxAttempts":3,"stalemateRepeats":3}}}}

子代理看门狗（独立配置）：

{"subagents":{"watchdog":{"children":{"model":"anthropic/claude-sonnet-4","overrides":{"worker":{"model":"anthropic/claude-opus-4-8"}}}}}}

#6. 原生监督协调

子代理可以通过 contact_supervisor 工具向父会话发送消息：

// 子代理侧 — 需要决策时contact_supervisor({reason: "need_decision",message: "架构方案有两个选择，需要决策..."})// 子代理侧 — 进度更新contact_supervisor({reason: "progress_update",message: "发现了一个预期之外的问题..."})

父会话回复：

// 查看待处理请求subagent_supervisor({ action: "pending" })// 回复特定子代理subagent_supervisor({action: "reply",replyTo: "<request-id>",message: "选择方案 B..."})

#7. 指定模型

7.1 单次运行时指定

自然语言：

/run reviewer[model=anthropic/claude-sonnet-4] "审查这个 diff"/run reviewer[model=anthropic/claude-sonnet-4:high] "审查"/chain scout[model=openai-codex/gpt-5-mini:low] "扫描" -> planner[model=anthropic/claude-sonnet-4:high] "计划"

工具调用：

subagent({ agent: "reviewer", task: "审查", model: "anthropic/claude-sonnet-4" })subagent({ agent: "reviewer", task: "审查", model: "anthropic/claude-sonnet-4:high" })

链式中指定：

subagent({ chain: [  { agent: "scout", task: "扫描", model: "openai-codex/gpt-5-mini:low" },  { agent: "planner", task: "计划", model: "anthropic/claude-sonnet-4:high" },  { agent: "worker", task: "实现" }]})

7.2 全局默认模型

所有未指定模型的子代理使用同一个默认模型：

{"subagents":{"defaultModel":"deepseek-v4-flash"}}

同时设置默认 thinking 级别：

{"subagents":{"defaultModel":"deepseek-v4-flash","defaultThinking":"medium"}}

7.3 按代理覆盖（agentOverrides）

推荐方式。为特定子代理指定模型，其他代理不受影响。

用户级配置~/.pi/agent/settings.json：

{"subagents":{"agentOverrides":{"reviewer":{"model":"anthropic/claude-sonnet-4","thinking":"high","fallbackModels":["openai/gpt-5-mini"]},"scout":{"model":"openai-codex/gpt-5-mini","thinking":"low"},"worker":{"model":"openai-codex/gpt-5-terra","thinking":"medium"},"planner":{"model":"openai-codex/gpt-5-sol","thinking":"high"},"oracle":{"model":"anthropic/claude-opus-4-8","thinking":"high"}}}}

项目级配置.pi/settings.json（优先级更高）：

{"subagents":{"agentOverrides":{"reviewer":{"model":"anthropic/claude-sonnet-4","thinking":"high"}}}}

agentOverrides 支持的覆盖字段：

字段	说明
`model`	指定模型
`fallbackModels`	备用模型列表（限流/超时/认证失败时自动切换）
`thinking`	thinking 级别：`off` / `low` / `medium` / `high` / `xhigh` / `max`
`description`	覆盖代理描述
`systemPrompt`	覆盖系统提示词
`systemPromptMode`	`replace` 或 `append`
`inheritProjectContext`	是否继承项目指令
`inheritSkills`	是否继承技能
`disabled`	设为 `true` 隐藏该代理
`tools`	覆盖工具白名单
`skills`	覆盖技能列表

7.4 Agent 文件 frontmatter 指定

直接编辑 agent 文件的 YAML frontmatter：

---name: scoutmodel: claude-haiku-4-5thinking: lowfallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4---

eject 内置代理到用户空间再编辑：

/subagents eject reviewer/subagents eject reviewer scope:project

然后编辑 ~/.pi/agent/agents/reviewer.md 或 {project}/.pi/agents/reviewer.md。

7.5 看门狗模型独立配置

看门狗模型的配置独立于子代理模型：

{"subagents":{"watchdog":{"enabled":true,"main":{"model":"anthropic/claude-opus-4-8","thinking":"high"}}}}

斜杠命令方式：

# 推荐模型/subagents-watchdog recommend-model# 设置特定模型/subagents-watchdog model anthropic/claude-opus-4-8:high# 使用推荐模型（仅当前会话）/subagents-watchdog session model recommended# 持久化推荐模型到 settings.json/subagents-watchdog model recommended

7.6 优先级总结

单次运行时指定 (model 参数)        ← 最高优先级  │  ├── agent 文件 frontmatter  │     └── model 字段  │  ├── agentOverrides.<name>.model  │     └── settings.json 中的按代理覆盖  │  ├── subagents.defaultModel  │     └── 全局默认模型  │  └── 父会话当前模型               ← 最低优先级（内置代理默认）

模型 ID 匹配规则：不区分大小写，支持多种分隔符变体：

anthropic/claude-sonnet-4
anthropic:claude-sonnet-4
anthropic.claude-sonnet-4
Claude-Sonnet-4
claude-sonnet-4-20251001

#8. Chorus Reviewer 的模型配置

Chorus 的三个 reviewer 是安装在 ~/.pi/agent/agents/ 下的独立 agent 文件：

代理	文件
`chorus-proposal-reviewer`	`~/.pi/agent/agents/chorus-proposal-reviewer.md`
`chorus-task-reviewer`	`~/.pi/agent/agents/chorus-task-reviewer.md`
`chorus-code-reviewer`	`~/.pi/agent/agents/chorus-code-reviewer.md`

这些 agent 的 frontmatter 没有model 字段，默认继承父会话的模型。

#9. 推荐代理分层策略

层级	代理	推荐模型	用途
🏃 快速	scout, researcher	最便宜的模型 + low thinking	代码侦察、查找、研究
🛠️ 标准	worker, reviewer, delegate	中端模型 + medium thinking	常规实现、审查
🧠 深度	oracle, planner	顶级推理模型 + high thinking	复杂分析、规划
🎯 品味	设计/UX/决策代理	理解人类意图好的模型	模糊需求、产品权衡

示例配置

{"subagents":{"defaultModel":"openai-codex/gpt-5-mini","agentOverrides":{"scout":{"model":"openai-codex/gpt-5-mini","thinking":"low"},"researcher":{"model":"openai-codex/gpt-5-mini","thinking":"low"},"worker":{"model":"openai-codex/gpt-5-terra","thinking":"medium"},"reviewer":{"model":"openai-codex/gpt-5-terra","thinking":"medium"},"planner":{"model":"openai-codex/gpt-5-sol","thinking":"high"},"oracle":{"model":"openai-codex/gpt-5-sol","thinking":"high"},"chorus-task-reviewer":{"model":"openai-codex/gpt-5-terra","thinking":"medium"},"chorus-proposal-reviewer":{"model":"openai-codex/gpt-5-terra","thinking":"medium"},"chorus-code-reviewer":{"model":"openai-codex/gpt-5-sol","thinking":"high"}}}}

#10. 常用工作流

实施 + 审查

用 scout 了解代码 → 用 planner 制定计划 → 用 worker 实现 →并行跑 reviewers（正确性/测试/简洁性）→ 汇总反馈 → worker 修复

审查循环（支持多轮）

/parallel-review# 或带 autofix 自动应用修复/parallel-review autofix

研究 + 侦察

/parallel-research

收集上下文 + 澄清

/gather-context-and-clarify

#关键设计原则

Pi 是决策者：父会话始终是编排者和最终决策者，子代理不能擅自做架构/产品决策
一个写入者：同一工作目录下只允许一个写入代理，防止冲突（除非使用 worktree 隔离）
安全边界：子代理默认不能启动子代理（除非显式配置 tools: subagent），深度限制默认 2 层
Fresh 上下文优于 Fork：审查/验证类工作使用 fresh 上下文，避免上下文污染
不接受即失败：子代理遇到未批准的决策必须通过 contact_supervisor 上报，不能自己猜测
不要给写入代理设置硬预算：turnBudget、hard toolBudget、usageBudget 不应设置在写入代理上，可能导致不完整的修改

pi-subagents 插件使用指南

pi-subagents 插件使用指南

#目录

#1. 概述

#2. 内置子代理一览

#3. 使用方式（三种入口）

3.1 自然语言

3.2 斜杠命令

3.3 工具调用（编程式）

#4. 执行模式详解

4.1 单代理

4.2 链式（Chain）

4.3 并行（Parallel）

4.4 后台（Async）

4.5 分支上下文（Fork）

4.6 工作树隔离（Worktree）

#5. 看门狗（Watchdog）

#6. 原生监督协调

#7. 指定模型

7.1 单次运行时指定

7.2 全局默认模型

7.3 按代理覆盖（agentOverrides）

7.4 Agent 文件 frontmatter 指定

7.5 看门狗模型独立配置

7.6 优先级总结

#8. Chorus Reviewer 的模型配置

推荐配置方式

#9. 推荐代理分层策略

推荐模型分层

示例配置

#10. 常用工作流

实施 + 审查

审查循环（支持多轮）

研究 + 侦察

收集上下文 + 澄清

#关键设计原则