PiAgent 系列 5：用 pi-subagents 召唤子智能体

Pi 的 README 里有一段说明他们的 Philosophy，其中关于 sub-agent 的态度明确：

No sub-agents. There’s many ways to do this. Spawn pi instances via tmux, or build your own with [extensions], or install a package that does it your way.

翻译过来就是：核心不内置 sub-agent，因为做法有很多，有人想要 tmux 协同，有人想自己写扩展，有人喜欢树状分解。Pi 不替用户做选择，而是把扩展系统作为土壤，让社区或者用户长出自己想要的方案。

pi-subagents 就是其中一个实现，它的下载量跟 pi-web-access 差不多是安装量最多的几个 pi 社区插件之一，一是说明虽然 pi 故意留了白但是社区确实有这方面的需求，另一方面也是因为它的设计足够优秀。

举一个实际工作中的场景，在进行某个项目的开发中通常包括：

理解代码 → 制定计划 → 实施 → 审查 → 修复

每一步的输出是下一步的输入，每一步都可能需要不同的"专长"：理解代码要快准狠（低 thinking），审查要严谨全面（高 thinking），实施要精确改动（会写文件但不会越权做决策）。

这就是子 agent 的用武之地：把每一步交给最合适的"分身"去跑，主 agent 负责编排和决策。

实际效果：你只需要说一句「分析 auth 模块，制定重构方案，然后实施」，Pi 就会自动调起 scout → planner → worker 三条 agent 串行执行，然后坐等结果。

pi-subagents 里的子 Agent 是怎么设计的

从技术上看，一个子 agent 就是一个独立的 Pi 子进程，拥有：

• 自己独立的 session 文件
• 自己独立的系统提示（角色定义）
• 受限的工具集（只拿到完成角色所需的最少工具）
• 与父 session 的明确边界，中间过程不污染主历史

父 session 调用子 agent 的过程，在主历史里只留下两条记录：

① subagent 工具调用  →  agent: "reviewer", task: "审查本次改动"
② subagent 工具结果  →  reviewer 的完整审查输出

子 agent 的中间操作（读了哪些文件、执行了哪些 bash 命令）全部留在它自己的 session 文件里。主历史干净，子 session 可追溯。

安装

pi install npm:pi-subagents

重启 Pi 或 /reload 即可。researcher 内置 agent 需要网络搜索，建议顺手装：

pi install npm:pi-web-access

唤起方式

唤起方式分为自然语言和命令两种。日常用自然语言就够了，通常主 Agent 会根据需求自动唤起预置的子 Agents，不过需要精确控制是也可以使用命令唤起。

自然语言

不需要记任何命令。Pi 拿到 subagent 工具后，当你用自然语言描述需要分工的任务时，会自动规划调用链路：

Use reviewer to review this diff.
Ask oracle for a second opinion on my current plan.
Run parallel reviewers: one for correctness, one for tests, one for unnecessary complexity.
Have worker implement this approved plan, then run parallel reviewers, summarize their feedback, and apply the fixes.
Run a review loop on this change until reviewers stop finding fixes worth doing, with a max of 3 rounds.

只需要描述意图，Pi 决定用哪个 agent、fork 还是 fresh、串行还是并行。

命令

需要精确控制时用 /run：

/run reviewer "审查这次改动"
/run scout "分析 auth 模块的入口点和数据流"
/run worker "实现支付接口的参数校验"

/run 是更精确的调用方式，指定一个 agent，给它一个 task，它跑完返回结果。它还支持几个运行时 flag：

--fork 和 --bg 可以组合。更复杂的编排（Parallel 并行、Chain 串行、保存工作流）在下一篇文章再展开介绍。以下先简单介绍 --bg、--fork、[key=value] 的几个机制。

内置的 8 个角色

安装后自带 8 个预配置 agent，覆盖从侦查到实施到审查的完整链路：

• scout：low thinking，不编辑源码，默认 fresh，产出 context.md
• researcher：medium thinking，不编辑源码，默认 fresh，产出 research.md
• planner：high thinking，不编辑源码，默认 fork，产出 plan.md
• worker：high thinking，可编辑源码，默认 fork，产出 progress.md
• reviewer：high thinking，可编辑源码，默认 fresh
• oracle：high thinking，不编辑源码，默认 fork
• delegate：继承主模型 thinking，可编辑源码，默认 fresh
• context-builder：medium thinking，不编辑源码，默认 fresh，产出 context.md

注：scout、planner 等有 write 工具，但只用于写自己的输出文件（context.md、plan.md），不改项目源码。

Scout——快速侦查兵

设计哲学：求快不求全。 用最低 thinking 级别，不做深度推理。精准搜索 + 选择性阅读，不读大文件，不穷举所有引用。目标是产出下一个 agent 需要的最少上下文。

工具集：read, grep, find, ls, bash, write, intercom
默认输出：context.md（被 planner 和 worker 读取）
适用场景：了解一个模块的结构、数据流、外部依赖、风险点

它的系统提示第一句就是 “Move fast, but do not guess.”，要快，但不能瞎猜。

Researcher——网络研究员

设计哲学：多角度搜索，精确引用。 拿到一个问题后，拆成 2-4 个角度分别搜索，用 web_search 的 queries 参数并行收集，筛选到权威源，产出研究简报。

工具集：read, write, web_search, fetch_content, get_search_content, intercom
默认输出：research.md
适用场景：查最新 API 文档、找最佳实践、验证技术方案的社区反馈

需要 pi-web-access。没有这个包的话 researcher 能注册但没法干活。

Planner——规划师

设计哲学：只读不改，计划要具体到文件和验证方法。 拿到上下文后，规划出能在 worker 手里直接执行的分步计划，不给模糊的"优化性能"这种废话。

工具集：read, grep, find, ls, write, intercom
默认输入：context.md（自动读取）
默认输出：plan.md（被 worker 读取）

它的约束里有句话很关键：“Do not make code changes. Read, analyze, and write the plan only.”，约定规划师不能改代码。

Worker——主要的实施者

设计哲学：最小改动，不做未授权的决策。 这是整个体系里主要的实施角色。它的系统提示是所有内置 agent 里最长的，因为职责最重，约束最多。

工具集：read, grep, find, ls, bash, edit, write, contact_supervisor
默认输入：context.md + plan.md（自动读取）
自动维护：progress.md

核心约束：

• single writer thread——它是唯一的写入线程，不同时跑多个 worker 改同一个文件
• 最小的、一致的正确改动——禁止大范围重写，禁止加"可能以后会用到"的脚手架
• 未授权决策必须升级——发现实施过程中有一个 plan 没覆盖到但必须做的产品决策？用 contact_supervisor 问主 agent，不准猜测，不准静默做掉
• 不准留 TODO——"// TODO: handle edge case" 这样的代码不准出现。要么处理掉，要么升级问

worker 的输出格式也被约束成了固定模板：

Implemented X.
Changed files: Y.
Validation: Z.
Open risks/questions: R.
Recommended next step: N.

Reviewer——审查员

设计哲学：用证据说话，不只是代码风格检查。 审查代码 diff、计划、方案。检查正确性、测试覆盖、边界情况、简洁性。可以做小修复。

工具集：read, grep, find, ls, bash, edit, write, intercom

它的审查清单包括：实现是否匹配意图和需求？代码是否正确且一致？测试是否覆盖改动且通过？有没有未处理的边界情况？有没有更简单的等效写法？

Oracle——决策守护神谕

设计哲学：质疑假设，防止偏移，不动手只动嘴。 这是最特别的一个角色——它不是做事的，而是质疑做事方向的。当你说"我感觉方向不太对"或者"帮我看看这个方案有没有坑"，就该 oracle 出场。

工具集：read, grep, find, ls, bash, intercom

oracle 的系统提示开篇就要求建立"基线合约"，从 fork 来的对话历史里重建之前做过的所有决策、约束和开放问题。然后它的任务是检测"当前方向是否与已有决策不一致"。如果发现不一致，它应该推荐安全的下一步和对应的执行 prompt，让主 agent 决策。

Delegate——轻量通用代表

设计哲学：我不改你的系统提示，我就加一段角色说明。 它是唯一用 systemPromptMode: append 的 agent。其他 agent 都是 replace——完全替换 Pi 默认系统提示，子 agent 不知道自己是 Pi。而 delegate 保留了 Pi 的完整系统提示，只在后面追加了一段角色说明。

工具集：read, grep, find, ls, bash, edit, write, contact_supervisor
适用场景：不太特化的任务，或者你不确定该用哪个角色时的兜底选择

Context-Builder——厚重的上下文构建器

设计哲学：不让下一个 agent 重新发现同一件事。 比 scout 更重——scout 只扫描代码，context-builder 还可以联网搜索需求背景、读外部文档、跟踪 import 链路直到彻底理解问题。适合复杂任务的前置分析。

工具集：read, grep, find, ls, bash, write, web_search, intercom
默认输出：context.md
适用场景：复杂需求的前置分析，需要同时查代码和外部的场景

预置 Agent 预置了什么

上面逐个介绍了 8 个预置 agent ，这里按差异维度汇总：

thinking 级别：scout low / researcher medium / planner high / worker high / reviewer high / oracle high / delegate 继承主模型 / context-builder medium

defaultContext（fork/fresh）：scout fresh / researcher fresh / planner fork / worker fork / reviewer fresh / oracle fork / delegate fresh / context-builder fresh

可编辑源码（有 edit+write）：scout ❌ / researcher ❌ / planner ❌ / worker ✅ / reviewer ✅ / oracle ❌ / delegate ✅ / context-builder ❌

systemPromptMode：全部 replace，仅 delegate 用 append

inheritProjectContext（继承 AGENTS.md）：全部 ✅

inheritSkills（继承 Pi 技能）：全部 ❌

自动读文件：planner 读 context.md / worker 读 context.md + plan.md / reviewer 读 plan.md + progress.md / 其余无

自动写文件：scout → context.md / researcher → research.md / planner → plan.md / worker → progress.md / context-builder → context.md / 其余无

协调通道：worker、delegate 用 contact_supervisor / 其余用 intercom

差异来自三个层面：

1. 系统提示（核心差异）——每个 agent 的角色定位、行为准则、输出格式都由 system prompt 定义。比如 planner 强调「只读不改」，oracle 强调「重建基线合约」，worker 约束固定输出模板。这是最不可替代的部分——改个 thinking 级别或者加个工具，不会改变 agent 的行为取向。

2. 工具集——工具决定 agent 能做什么事。有没有 edit 决定了能不能改代码（只有 worker 和 reviewer 有），有没有 web_search 决定了能不能联网（researcher 和 context-builder 有），有没有 contact_supervisor 决定了能不能反向呼叫主 agent（worker 和 delegate 有）。intercom 是更通用的反向通道，其余 agent 用这个。

3. frontmatter 参数——thinking 级别、defaultContext、读写文件、systemPromptMode。这些在自定义 agent 时都可以按需覆盖。

Subagents 常见使用场景

同步 vs 异步

对应 --bg flag。

后台任务用 /subagents-fleet 查看所有运行中任务。完成后 Pi 弹出通知。如果主 agent 必须等结果才能继续，用 wait 工具而不是 sleep 轮询。

fork vs fresh：子 Agent 能看到对话历史吗？

对应 --fork flag。这是影响子 agent 行为最核心的开关。

fork： 子 agent 从父 session 的当前位置分叉，继承完整对话历史
      它能读到之前的讨论、改了哪些文件、为什么改、项目的约束

fresh：子 agent 启动一个空白 session，只拿到你给的 task 文本
      不知道任何背景，像是一个刚进项目的新人只被安排了一件事

预置 agent 有自己的默认值：

任务需要对话上下文才能正确执行，就默认 fork；任务是自包含的独立工作，就默认 fresh。

默认值可以被覆盖

# 1. 运行时 --fork 覆盖（最高优先级）
/run reviewer "审查改动" --fork      # 强制继承历史
/run reviewer "审查改动"             # 不加就走默认（fresh）
# 注意：没有 --no-fork 反向 flag，不加就是走默认

子 Agent 的模型与技能

可以通过对应 [key=value] 内联配置。

模型：默认继承父 session

内置 agent 的 frontmatter 里都没有写 model，所以默认全部继承你 Pi 当前用的模型。你切模型，子 agent 跟着切。除非通过内联配置覆盖

优先级链：

内联 [model=xxx]  >  agentOverrides  >  agent frontmatter  >  subagents.defaultModel  >  父 session 模型

典型的分层策略——强模型给思考类角色，快模型给执行类角色：

{
  "subagents": {
    "defaultModel": "deepseek-v4-flash",
    "agentOverrides": {
      "oracle":   { "model": "deepseek-v4-pro", "thinking": "high" },
      "planner":  { "model": "deepseek-v4-pro", "thinking": "high" },
      "reviewer": { "model": "deepseek-v4-pro", "thinking": "high" }
    }
  }
}

scout 和 worker 走默认的 flash，oracle/planner/reviewer 走 pro。运行时用 [model=xxx] 临时覆盖。

Skills：默认不继承

所有内置 agent 的 inheritSkills 都是 false。这是刻意设计——审查员不需要看到你的视频处理技能，侦察兵不需要你的文章生成系统提示。子 agent 是专注角色，工具集越窄越可控。

三种加法：

# 运行时（单次生效）
/run worker[skills=security-checklist] "实现支付接口"

# agent frontmatter（持久生效）
skills: security-checklist, custom-lint

# 或全部开启（谨慎）
inheritSkills: true

当 agent 有显式 tools 约束且有技能时，read 会自动加入工具集，以便按需加载 SKILL.md。