Subagents on yzchen.space

PiAgent 系列 7：pi-subagents 工作流编排

Sun, 19 Jul 2026 12:00:00 +0800

上篇介绍了如何自定义 agent 以及 pi-subagents 的三个设计约束：systemPromptMode: replace、子 agent 不能自由嵌套、以及 contact_supervisor 反向通道。这些约束决定了 pi-subagents 的编排风格，多 agent 协作主要靠文件交接，复杂流程由父 session 显式编排。本文在此基础上，介绍两种核心编排模式：Parallel 并行与 Chain 链式，以及工作流的保存、复用、管理和诊断。

Parallel：并行编排

Parallel 是最简单的编排形式：多个 agent 同时跑，互不干扰。

基础并行

/parallel \
  reviewer "审查安全性" \
  -> reviewer "审查性能" \
  -> reviewer "审查可维护性"

三个 reviewer 同时开始，互不干扰。所有结果汇总后一条消息返回主会话。

共享任务

/parallel scout researcher -- 深度分析支付模块

scout 扫代码 + researcher 线上搜，同一个任务，两种角度，并行完成。

差异化配置

/parallel \
  reviewer[model=deepseek-v4-pro,skills=security] "审查安全性" \
  -> reviewer[model=deepseek-v4-flash] "审查代码风格"

同一个 agent 类型，不同模型和技能承担不同子任务。

并行结果的传递

并行步骤的子 agent 结果按以下格式汇总，用分隔线区分：

=== Parallel Task 1 (reviewer) ===
...审查结果...

=== Parallel Task 2 (reviewer) ===
...审查结果...

如果 parallel 是 chain 里的一步，汇总文本会作为整步的 {previous} 传给下一步。

PiAgent 系列 6：pi-subagents 自定义子智能体

Sat, 18 Jul 2026 12:00:00 +0800

上篇介绍了 pi-subagents 的概念、8 个内置角色、fork/fresh 机制与模型/技能继承。本文继续深入：如何定制 agent，以及 pi-subagents 为什么要这样设计——理解这些底层约束，是后续编排工作流的前提。

自定义 Agent

内置的 8 个角色已经覆盖了大多数场景，但实际项目中往往要微调：让 reviewer 用更强的模型、给 scout 关掉网络搜索、或者加一个只负责安全审计的专属角色。pi-subagents 提供了两类自定义方式：一类是通过配置项 agentOverrides 覆盖内置 agent 的元数据；另一类是通过 .md 文件创建或覆盖 agent 定义，同名文件会覆盖内置角色，新名字则作为补充角色。

通过配置覆盖：agentOverrides

agentOverrides 是 Pi settings 中 subagents 下的一个配置对象，写在项目 .pi/settings.json 或用户 ~/.pi/agent/settings.json 里。它用来覆盖内置 agent 的元数据，不需要新建 agent 文件。其特点是：不改 prompt，只调模型、thinking、默认上下文等配置。适合快速对齐不同项目的需求。

{
  "subagents": {
    "agentOverrides": {
      "reviewer": { "model": "deepseek-v4-pro", "thinking": "high", "defaultContext": "fork" },
      "scout": { "model": "deepseek-v4-flash" },
      "researcher": { "disabled": true }
    }
  }
}

disabled: true 隐藏不需要的内置 agent。subagents.disableBuiltins: true 一次性禁用所有内置 agent（如果只用自定义角色）。

通过 .md 文件创建或覆盖

在项目或用户目录创建 .md 文件即可定义 agent。如果文件名与内置 agent 同名，就会覆盖内置角色；如果取新名字，就会新增一个补充角色。

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

Thu, 16 Jul 2026 12:00:00 +0800

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 串行执行，然后坐等结果。