nicobailon/pi-subagents

来源: https://github.com/nicobailon/pi-subagents

pi-subagents

pi-subagents 让 Pi 能够将任务委托给专注的子代理。适用于代码审查、侦查、实现、并行审计、保存的工作流、后台任务，以及任何需要第二或第三双“模型眼睛”的场景。

https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1

安装

pi install npm:pi-subagents

这是唯一必需的步骤。后续可以按需添加可选组件。

先试试这个

你不需要创建代理、编写配置或学习斜杠命令。安装后，直接用自然语言告诉 Pi 进行委托：

用 reviewer 审查这个 diff。

让 oracle 对我的当前计划给出第二意见。

用 scout 根据我们的讨论理解这段代码，然后向我提出澄清性问题。

并行运行评审：一个检查正确性，一个检查测试，一个检查不必要的复杂性。

这就够了，可以开始使用了。

发生了什么

Pi 是父会话。子代理是一个具有自身任务的专注子 Pi 会话。当你要求使用子代理时，Pi 会启动子会话，为其分配任务，并将结果带回。前台运行会实时在对话中显示进度。后台运行会持续工作，稍后可查。

安装扩展程序不会自动启动后台评审功能。它只是为 Pi 提供了一个委托工具。如果你希望每次实现都经过审查，可以在提示词或项目说明中加入：

当你完成实现后，在总结之前先运行一个 reviewer 子代理。

适合初次使用的提示词

这些涵盖了大部分日常使用场景：

让 oracle 对我当前的计划给出第二意见。挑战假设，并告诉我可能遗漏的地方。

用 oracle 帮助解决这个棘手的 bug。让它检查代码，并在我们改动之前提出最佳下一步。

对这个 diff 并行运行评审。我希望一个专注于正确性，一个专注于测试，一个专注于不必要的复杂性。

让 worker 实现这个已批准的计划。之后，并行运行评审，汇总反馈，并应用有意义的修正。

对这个改动运行评审循环，直到评审者不再发现值得修复的问题，最多 3 轮。

用 scout 理解认证流程，然后让 planner 将其转化为实现计划。

这些都是普通的 Pi 请求。Pi 决定是否调用 subagent、使用哪个代理，以及顺序或并行运行是否合理。

常见工作流

该扩展内置了可直接使用的代理。

内置代理的通俗解释

一个简单的经验法则：在理解代码前使用 scout，在信任外部事实前使用 researcher，在进行较大改动前使用 planner，使用 worker 实现，使用 reviewer 检查，当决策本身有风险时使用 oracle。

更改内置代理的模型

默认情况下，内置代理继承你当前的 Pi 默认模型。这可以避免新安装依赖于你可能未配置的提供商。如果你希望某个角色使用特定模型，可以设置覆盖，而不是复制捆绑的代理文件。

单次运行，在命令中放入覆盖：

/run reviewer[model=anthropic/claude-sonnet-4:high] "审查这个 diff"

持久覆盖则编辑设置。以下示例将 reviewer 固定到一处，为提供商故障添加备份模型，并让其他内置代理保持默认模型：

{
  "subagents": {
    "agentOverrides": {
      "reviewer": {
        "model": "anthropic/claude-sonnet-4",
        "thinking": "high",
        "fallbackModels": ["openai/gpt-5-mini"]
      }
    }
  }
}

使用 ~/.pi/agent/settings.json 进行用户级覆盖，或使用 .pi/settings.json 进行项目级覆盖。同样的 agentOverrides 块可以更改 tools、skills、继承上下文、提示文本，或禁用内置代理。如果你想要一个完全不同的代理，可以创建同名的用户或项目代理；对于普通微调，推荐使用覆盖。

运行中的子代理显示在哪里

前台运行在运行时会在对话中流式显示进度。后台运行在控制权交还给你后会继续工作。使用 subagent({ action: "status" }) 检查活动运行，或使用 subagent({ action: "status", id: "..." }) 检查特定运行。它们还会显示一个紧凑的异步小部件，并发送完成通知。

并行后台运行显示每个代理的进度，而不是伪造的链式步骤。带有并行组的链在进度和结果中保持其分组形状，因此失败或暂停的代理会与完成的代理一样可见。当子进程被明确允许使用 tools: subagent 进行展开时，其嵌套运行会显示在主状态树中该子代理下，而不是隐藏在子进程内部。

你也可以自然地问：

显示当前的异步运行。

如果感觉配置有问题，运行：

/subagents-doctor

或询问：

检查子代理和 intercom 是否设置正确。

推荐的编排模式（脚手架）

将编排用作父代理的指导，而不是运行时的流程模式。对于实现工作，推荐的循环是：

clarify → planner → worker → fresh reviewers → worker

当你希望模式可重复时，可以使用下面的可选提示快捷方式。打包的 planner、worker 和 oracle 在启动时若省略 context，默认使用分叉上下文；若有意使用全新的子运行，则传递 context: "fresh"。

子安全边界在运行时强制实施。生成的子会话不会接收捆绑的 pi-subagents 技能，分叉的子上下文过滤会移除仅父代拥有的子代理工件（包括旧的隐藏编排指令消息、斜杠/状态/控制消息以及先前的父代 subagent 工具调用/结果），同时保留普通散文和无关的工具调用/结果。默认情况下，子代理不注册 subagent 工具，并收到边界指令：它们不是父编排器，不得提议或运行子代理。显式例外是解析后的内置 tools 中包含 subagent 的代理；该子代理会获得一个安全的 subagent 工具，用于父代分配的分支工作，仍受 maxSubagentDepth 限制。

可选快捷方式

包中包含常见工作流的可重用提示模板。你不需要它们，但当你希望每次保持相同结构时，它们很方便：

在 /parallel-review 或 /parallel-cleanup 中添加 autofix，以便在评审返回后仅应用当前值得做的综合修复。

可选的 pi-intercom 伴侣

pi-subagents 不依赖 pi-intercom。仅当你想让子代理在运行时与父 Pi 会话通信时才安装 pi-intercom。

pi install npm:pi-intercom

大多数用户不会直接调用 intercom。安装 pi-intercom 后，pi-subagents 可以自动为子代理提供一个回到父会话的私有协调通道。桥接器识别正常的 pi install npm:pi-intercom 包安装以及旧式的本地扩展检出版本。

用于子代理可能需要决策而不是猜测的工作：

在后台运行这个实现。如果 worker 被阻塞或需要产品决策，让它通过 intercom 问我。

让 oracle 审查这个计划。如果它看到需要我做的决策，让它问我而不是假设。

子代理可以使用一个专用的协调工具：

• contact_supervisor：子代理联系委托任务的父/监督会话。对于阻塞决策或澄清使用 reason: "need_decision"；对于当发现改变了计划时的简短非阻塞更新使用 reason: "progress_update"。当唯一的冲突是仅审查/不编辑与进度写入或工件写入指令时，不要请求澄清；不编辑获胜。子侧常规完成交接仍不期望。

启用 intercom 桥接后，父侧 pi-subagents 通过 pi-intercom 发送分组完成结果：每个前台父 subagent 运行一个分组消息，每个完成的异步结果文件一个。确认的前台交付返回一个包含工件/会话路径的紧凑回执；若未确认，则保留正常完整输出。分组消息包括子 intercom 目标、完整子摘要以及启动它们的子代理下的紧凑嵌套子摘要。

如果子代理似乎停滞，父会话中会出现需要注意的通知，其中包含有用的下一步操作，例如检查 subagent({ action: "status" })、中断运行或推动子代理。

如果消息没有出现，运行：

/subagents-doctor

对于正常使用，你不需要配置任何东西。高级用户可以在下面的配置部分使用 intercomBridge 调整桥接器。

至此，你已经了解如何使用该插件。README 的其余部分是参考材料，涵盖精确命令语法、自定义代理、保存的链、工作树和配置。

直接命令

在需要精确语法之前，可以跳过此部分。

命令会在本地验证代理名称，支持 Tab 补全，并将结果发送回对话中。

每步任务

使用 -> 分隔步骤，并为每个步骤指定其任务：

/chain scout "扫描代码库" -> planner "创建实现计划"
/parallel scanner "查找安全问题" -> reviewer "检查代码风格"

双引号和单引号都可以使用。你也可以使用 -- 作为分隔符：

/chain scout -- 扫描代码 -> planner -- 分析认证

没有任务的步骤会从执行模式继承行为。链步骤会获得 {previous}，即上一步的输出。并行步骤会使用第一个可用任务作为后备。

/chain scout "分析认证" -> planner -> worker
# scout 获得 "分析认证"；planner 获得 scout 输出；worker 获得 planner 输出

对于共享任务，列出代理并在任务前放置一个 --：

/chain scout planner -- 分析认证系统
/parallel scout reviewer -- 检查安全问题

内联每步配置

在代理名称后附加 [key=value,...] 以覆盖该步骤的默认值：

/chain scout[output=context.md] "扫描代码" -> planner[reads=context.md] "分析认证"
/run scout[model=anthropic/claude-sonnet-4] 总结此代码库
/parallel reviewer[skills=code-review+security] "审查后端" -> reviewer[model=openai/gpt-5-mini] "审查前端"

设置 output=false、reads=false 或 skills=false 以显式禁用该行为。不要使用 output=false 来实现仅文件返回；应使用带有 output 路径的 outputMode=file-only。

后台运行和分叉运行

添加 --bg 以在后台运行：

/run scout "审计代码库" --bg
/chain scout "分析认证" -> planner "设计重构" -> worker --bg
/parallel scout "扫描前端" -> scout "扫描后端" --bg

添加 --fork 以从父代当前叶子创建的真实分支会话启动每个子代理：

/run reviewer "审查这个 diff" --fork
/chain scout "分析这个分支" -> planner "规划下一步" --fork
/parallel scout "审计前端" -> reviewer "审计后端" --fork

你可以按任意顺序组合它们：

/run reviewer "审查这个 diff" --fork --bg
/run reviewer "审查这个 diff" --bg --fork

后台运行是分离的。如果父代理有其他独立工作，它应继续工作。如果直到后台结果到达之前没有有用的事情可做，它应结束本轮，而不是运行睡眠或状态轮询循环。Pi 会在运行完成时交付结果。

oracle 和 worker 内置代理设计用于显式决策循环。一个典型模式是要求 oracle 对计划进行审