pi-subagents 插件使用指南：把工作委托给子代理的六种执行模式

📝

pi-subagents（nicobailon/pi-subagents，2.9k⭐）让 Pi 主会话把工作委托给独立子代理——内置 scout/researcher/planner/worker/reviewer/oracle 等 9 个代理，支持单代理/链式/并行/后台/分支上下文/工作树隔离六种执行模式，含看门狗对抗性审查与模型分层策略。v0.40.0 完整使用指南。

原文链接：https://mp.weixin.qq.com/s/aQa9_kQ_h7_Syr_zHMQ9FQ ｜作者：糖醋鱼哈

本文记录 pi-subagents 插件（v0.40.0）的整体使用方式，以及如何为子代理指定模型，覆盖大多数使用场景。

1. 概述

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

1	pi install npm:pi-subagents

支持模式：

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

2. 内置子代理一览

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

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

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

3.1 自然语言

帮我 review 这个 diff
用 oracle 给我当前的方案提供第二意见
并行跑三个 reviewer：一个检查正确性，一个检查测试，一个检查复杂度
后台运行这个实现，完成后通知我

3.2 斜杠命令

/run scout "扫描代码库"
/run scout[model=anthropic/claude-sonnet-4] "扫描"          # 运行时指定模型
/chain scout "扫描" -> planner "规划" -> worker "实现"       # 链式执行
/parallel reviewer "A" -> reviewer "B"                       # 并行执行
/subagents [agent]                                           # 查看/编辑代理配置
/subagents-models [agent]                                    # 查看运行时模型映射
/subagents-watchdog [status|on|off|check]                    # 看门狗配置
/subagents-fleet                                             # 查看活跃子代理舰队
/subagents-doctor                                            # 诊断
/subagent-cost                                               # token 用量和费用
/subagents-detach [run-id]                                   # 分离前台运行而不终止

链式进阶：/chain scout[output=context.md] "扫描" -> planner[reads=context.md] "分析"（带输出和读取）、--bg 后台运行、--fork 分支上下文、组合使用 /run reviewer "审查" --fork --bg。

3.3 工具调用（编程式）

// 单代理
subagent({ agent: "worker", task: "重构 auth 模块" })

// 并行
subagent({ tasks: [
  { agent: "scout", task: "扫描前端" },
  { agent: "reviewer", task: "审查后端" }
]})

// 链式 + checkpoint
subagent({ chain: [
  { agent: "scout", task: "收集上下文" },
  { agent: "planner" },
  { checkpoint: "审批", message: "批准再实施？" },
  { agent: "worker" },
  { agent: "reviewer" }
]})

// 后台
subagent({ agent: "worker", task: "实现...", async: true })

// 工作树隔离
subagent({ tasks: [
  { agent: "worker", task: "实现 auth" },
  { agent: "worker", task: "实现 API" }
], worktree: true })

// 管理操作
subagent({ action: "list" })          // 列出可用代理
subagent({ action: "models" })        // 查看模型映射
subagent({ action: "interrupt", id: "<run-id>" })  // 软中断
subagent({ action: "steer", id: "<run-id>", message: "方向调整" })  // 引导

4. 执行模式详解

4.1 单代理

最简单的模式，一个子代理执行一个任务：/run scout "分析 auth 模块"。

4.2 链式（Chain）

顺序执行，上一步的输出通过 {previous} 传递给下一步：/chain scout "扫描代码库" -> planner "制定实现计划" -> worker "实现"。

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

4.3 并行（Parallel）

多个子代理同时执行，适合独立任务。链式中可内联并行组：/chain scout "扫描" -> (reviewer "审查 A" | reviewer "审查 B") -> writer "修复"。

4.4 后台（Async）

子代理后台独立运行，不阻塞主会话：/run scout "审计代码库" --bg，完成后收到通知，通过 subagent({ action: "status" }) 查看状态。

4.5 分支上下文（Fork）

从父会话当前节点创建真正的分支会话，子代理能看到父会话历史对话：/run reviewer "审查" --fork。

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

4.6 工作树隔离（Worktree）

每个子代理在独立 git worktree 中工作，避免并行编辑冲突。要求：在 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": {
      "enabled": true,
      "main": { "model": "anthropic/claude-opus-4-8", "thinking": "high" },
      "scope": { "enabled": true },
      "cadence": { "everyNTools": 10 },
      "autoFollow": { "blockers": true, "maxAttempts": 3, "stalemateRepeats": 3 }
    }
  }
}

6. 原生监督协调

子代理可以通过 contact_supervisor 工具向父会话发送消息（决策请求/进度更新）；父会话通过 subagent_supervisor 查看待处理请求并回复。实现”Pi 是决策者”的监督模式。

7. 指定模型

7.1 单次运行时指定

/run reviewer[model=anthropic/claude-sonnet-4:high] "审查"，或工具调用 subagent({ agent: "reviewer", task: "审查", model: "anthropic/claude-sonnet-4:high" })。

7.2 全局默认模型

1	{ "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 优先级更高。覆盖字段：model、fallbackModels（限流/超时自动切换）、thinking（off/low/medium/high/xhigh/max）、description、systemPrompt、systemPromptMode（replace/append）、inheritProjectContext、inheritSkills、disabled、tools、skills。

7.4 Agent 文件 frontmatter 指定

---
name: scout
model: claude-haiku-4-5
thinking: low
fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
---

用 /subagents eject reviewer 把内置代理弹出到用户空间再编辑。

7.5 看门狗模型独立配置

看门狗模型独立于子代理模型：/subagents-watchdog model anthropic/claude-opus-4-8:high，或 settings.json 中 subagents.watchdog.main.model。子代理看门狗（children）也可独立配置。

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（chorus-proposal-reviewer / chorus-task-reviewer / chorus-code-reviewer）是安装在 ~/.pi/agent/agents/ 下的独立 agent 文件，frontmatter 没有 model 字段，默认继承父会话模型。推荐用 agentOverrides 单独配置（如 chorus-code-reviewer 用 gpt-5-sol + high thinking）。

9. 推荐代理分层策略

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

10. 常用工作流

实施 + 审查：scout 了解代码 → planner 制定计划 → worker 实现 → 并行跑 reviewers（正确性/测试/简洁性）→ 汇总反馈 → worker 修复
审查循环：/parallel-review（或 /parallel-review autofix 自动应用修复）
研究 + 侦察：/parallel-research
收集上下文 + 澄清：/gather-context-and-clarify

关键设计原则

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

📊 GitHub 数据验证（2026-08-05 实测）

项目	数据
仓库	nicobailon/pi-subagents
Stars	2,889
Forks	456
语言	TypeScript
License	MIT
创建时间	2026-01-07
最近推送	2026-08-05（活跃维护中）
定位	Pi extension for async subagent delegation with truncation, artifacts, and session sharing

nicobailon 是 Pi 生态最主要的三方扩展作者（pi-web-access、pi-messenger、pi-interactive-shell、pi-mcp-adapter、pi-powerline-footer 均出自其手）。插件版本 v0.40.0，迭代很快，建议关注仓库 Release。