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

用 Pi 学习 Agent 怎么运行

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

pi 是学习 harness 的好帮手

想搞懂一个 agent 到底怎么跑起来，最好的办法不是读别人的文章，而是拿一个真正可观察的 agent 自己跑一遍。

agent = model + harness。

model 做的事很单纯——收到一个 messages 列表，返回一段文本。它不知道文件系统在哪、不知道你项目里有什么、不知道上一次对话发生了什么。
harness（中文是缰绳还是线束什么的，随便把，反正是把模型和外部环境连起来的那一层）是让模型"变聪明"的关键：它把模型包进一个循环，负责拼装上下文、调用工具、把结果塞回下一轮对话。

harness 的核心是一个循环：

拼装 system prompt + 历史消息 → HTTP 请求体
发给模型 API，拿到响应
解析响应——是普通文本还是 tool call？是 tool call 就执行
把执行结果塞进下一轮的 messages，回到第 1 步
模型不再调工具，结束

想理解 agent，就得理解这个循环。而 pi 是学这个最好的工具。

例如可以让它帮你理解 harness 过程，因为它极度透明

大多数 agent 工具把和模型的对话过程藏起来，你只能看到最终输出的文本。pi 不一样：它把整个生命周期都暴露成事件——session 启动、消息拼装、API 请求发出去之前、响应回来之后、工具执行……每一个节点你都能插手。

换句话说，harness 在 pi 里不是黑盒，而是一组你能监听的事件。理解 agent 怎么运行，本质上就是理解 harness 在那个循环里做了什么——而 pi 让你直接看见它，甚至改写它。

比如我们可以让它展示在请求大模型时发送的 HTTP 内容

一个直接的例子：让 pi 展示它发给大模型 API 的完整请求。我写了一个 extension model-api-inspector 做这件事——监听 provider 的请求 / 响应事件，把每次调用的 request body 和 response body 都渲染到终端里：