pi-matt-subagent

English: README.md

一个 pi 插件，负责把 Matt Pocock 的 skills 里「spawn sub-agents」这类指令变成真实可跑的动作。当某个 skill 写着 "spawn sub-agents in parallel" 或 "fire the research subagents" 时，这个插件就是执行层：它启动真正的 pi 子代理——blocking 用独立子进程，后台 research 用进程内第二会话（ADR 0013）——阻塞等待（后台场景则不等待），然后把结果交回给你。

这个插件本身就是 dogfooding 的产物：上游 skills 有子代理需求，插件才存在。它的两个工具与这些 skill 描述的子代理模式一一对应。

为什么会有这个插件

Matt Pocock 的 skills 到处都在要求子代理，却没说明 pi 里具体怎么做。翻一遍就会发现同样的话反复出现：

• code-review —— Standards 和 Spec 两轴要作为 并行子代理 运行，互不污染上下文。
• codebase-design（DESIGN-IT-TWICE.md）—— 派生 3+ 个子代理，各自为同一个模块设计 截然不同 的接口。
• improve-codebase-architecture —— 子代理走查代码库并报告架构摩擦；最后一步就是上面的 design-it-twice。
• research / wayfinder —— 起一个 后台 代理读一手资料，把结论写进文件，主会话继续干活。

这个插件把这几句话变成工具调用。它内置的角色与这些 skill 描述的任务同名（standards-reviewer、spec-reviewer、design-explorer、architecture-scout、researcher、fact-finder），词汇原样沿用。

装了什么

两个工具，对应上游 skills 需要的两种语义：

工具	语义	做什么
subagent	blocking	运行 single / parallel / chain 子代理。所有子代理跑完才返回，完整结果一次拿回。chain 支持 {previous} 占位符，把上一步输出传给下一步。
research	background	在进程内第二会话（ADR 0013）里运行，把带引用的结论写进文件，立即返回 handle，并把完成状态（succeeded / failed / terminated / aborted）推送进你的上下文——无需轮询。

六个内置角色：standards-reviewer、spec-reviewer、design-explorer、architecture-scout、researcher、fact-finder。~/.pi/agent/agents/ 下的用户代理和 .pi/agents/ 下的项目代理按名字覆盖内置角色；项目代理需要信任确认。

两个工具都接受一个可选的 input 字段：JSON 对象字符串，携带公开 schema 未暴露的高级参数——subagent 接受 model（本次运行的模型覆盖）和 thinkingOverride（本次运行的思考档位），research 接受 model 和 maxWallClockMs（隐藏的墙钟上限，只能把 60 分钟默认值收得更紧）。直接字段覆盖 JSON 同名键；非法 JSON 或非对象值会抛清晰的模型可见错误；合并后的参数在派发前按完整契约校验（ADR 0011）。

共存声明：本插件注册名为 subagent 的工具，类似的 subagents 扩展也会注册同名工具。请避免与本插件同时使用其他 subagents 扩展——同名工具会冲突，二选一安装，不要同时装（ADR 0012）。

每条运行都会反映在 footer 计数器（⧗ N subagents running）上，blocking 运行期间也能看到。/subagents 列出完整快照并管理运行：无参弹菜单（查看运行 / 终止 run / 清理已结束 / 查看日志末尾），带参直接操作（kill <id> / tail <id> / prune / snapshot）。停止一条 background research 运行会中止其进程内子会话，并把运行记作 aborted（和每个终态一样推送结果），而不是 failed 或 terminated。每条 research 运行都由单一的墙钟上限约束（默认 60 分钟；可按次用隐藏 maxWallClockMs 收紧）：findings 在每轮搜索前检查点落盘，所以上限击杀最多损失一轮工作；墙钟击杀会在 findings 文件末尾追加精简的 research-terminated 标记，并把运行记作 terminated。blocking 运行期间命令排队，中途只能用 Esc 整体中止。

四个 slash command——前三个各直通一个上游模式：

• /code-review <ref> —— 对 <ref> 以来的 diff 做两轴审查（Standards + Spec），两个并行 blocking 子代理。适合审一个 commit、分支或 merge-base。对应 code-review skill。
• /design-it-twice <candidate> —— 为一个深化候选并行生成 3-4 个差异显著的接口设计，再从深度、局部性、接缝位置比较。对应 codebase-design 的 DESIGN-IT-TWICE 模式（也是 improve-codebase-architecture 的最后一步）。
• /research <question> —— 起一个后台研究者查一手资料，主会话继续干活；完成状态（succeeded / failed / terminated / aborted）会连同 findings 路径推送给你。对应 research skill（以及 wayfinder 的 research 工单）。
• /subagents —— 运行总览与管理：跟踪进度、终止 runaway 的 researcher、清理已结束记录、读 background run 日志。

安装

从 npm 安装：

pi install npm:pi-matt-subagent

或从本地仓库安装：

pi install <本仓库路径>

两种方式都会安装扩展（两个工具）和 prompt 模板（四个 slash command 中的三个——/code-review、/design-it-twice、/research；/subagents 随扩展内置）。用 pi list 确认；prompts 会出现在 TUI 的 / 补全里。

快速上手

装完开一个会话就能用。工具面向模型：你描述任务，主 agent 负责调用。

• 审你最近的提交 —— /code-review HEAD~1 用两个并行 blocking 子代理分别跑 Standards 和 Spec 两轴，并排报告。
• 后台研究，同时继续干活 —— /research "验证某个论断…" 立即返回 handle；run 结束时 findings 路径会推送给你。
• 直接调工具 —— 对主 agent 说 "run a subagent review of src/lib.ts with standards-reviewer"，或 "start a research on ADR 0013 and write findings to docs/research-0013.md"。

每次运行换模型

两个工具默认沿用主会话的模型，都支持通过隐藏的 input 字段按次覆盖：

工具	隐藏 input 键	作用
subagent	model、thinkingOverride	本次运行的模型（provider/id）与思考档位
research	model、maxWallClockMs	模型覆盖；墙钟上限——只能收紧，默认 60 分钟

不用手写 input——直接说 "run that review with deepseek-v4-pro" 或 "research this with a 30-second cap"，主 agent 会在工具调用里带上。手写时形如：

{
  "task": "review the diff since HEAD~1 for standards compliance",
  "agent": "standards-reviewer",
  "input": "{\"model\": \"sensenova/deepseek-v4-pro\", \"thinkingOverride\": \"high\"}"
}

模型名按 provider/id 对照 ~/.pi/agent/models.json 注册表解析；解析不了的名字在工具层大声报错，run 不会启动。直接字段优先于 JSON 同名键，合并结果派发前按完整契约校验（ADR 0011）。

项目结构

extensions/subagent.ts   pi 扩展：注册 subagent + research 两个工具，并提供进程内 research
                         子会话工厂（ADR 0013）
src/lib.ts               纯逻辑——角色定义、工具 schema（单一事实源）、input 合并/校验、
                         工具名解析、派发参数、research runner（子会话工厂 seam）；零 pi
                         运行时依赖，用 node --test 测
src/lib.test.ts          单元测试
scripts/                 token 基准（Seam E）+ 测量扩展 + push-e2e 脚本（仅开发用）
prompts/                 四个 slash command 模板
docs/adr/                决策记录：双通道、工具名归一化、research 重构（推送交付、墙钟上限）、
                         运行注册表 + 运行管理、input 逃生舱、共存立场
CONTEXT.md               领域词汇表（subagent、role、blocking、background、push、input-JSON……）

两个值得知道的决策：

• 工具名归一化（docs/adr/0002）：角色声明的工具在派发前会对照当前环境的注册表解析。环境里没有的名字回退到内置名（ffgrep → grep），解析不了的名字直接剔除，而不是让子进程静默缺工具。能适应 fff 模式切换，又不耦合 fff 本身。
• 双通道（docs/adr/0001）：blocking 是默认心智模型；只有 research/wayfinder 走后台通道。
• Research 重构（docs/adr/0013）：后台研究者作为进程内第二会话运行；每个终态都经 push 推进主上下文；预算机制坍缩为单一墙钟上限 + 检查点 findings。
• input 逃生舱（docs/adr/0011）：按次的高级参数（model、thinkingOverride）走 input JSON 字段——直接字段覆盖 JSON 键、非法输入大声失败、合并后按完整契约校验再派发。参数 schema 以 src/lib.ts 为单一事实源。

Token benchmark（token 基准）

单独启用本扩展时，模型可见的常驻初始化贡献如下：

工具	构成	Tokens
subagent	description + 参数 schema	630
research	description + 参数 schema	517

测量环境：pi 0.87.0，2026-09-22（ADR 0013 表面变更后重测），独立临时进程、空白工作目录与空白配置（排除其他扩展、Skills、上下文文件与 slash commands；计入 before_agent_start 表面）。Token 按 ceil(字符数 / 4) 的固定字符代理估算，并非 provider tokenizer 实际计费值。用 node scripts/benchmark-tools.ts 复测；npm test 断言序列化表面不超过基线 × 1.2（token 回归守卫），footprint 膨胀会被测试套件拦下。

开发

npm test          # 单元测试，不需要 pi 运行时——src/lib.ts 保持零运行时依赖
npm run typecheck # 扩展 + lib + scripts 类型检查（tsconfig.json，需要已安装的 pi 包）

扩展只是 src/lib.ts 的薄消费者；纯函数（派发参数装配、工具解析、带可注入子会话工厂 seam 的后台 runner、input 合并/校验、契约面）就是测试覆盖的对象。注册表面变化时用 node scripts/benchmark-tools.ts 刷新 token 基准数字与守卫基线。

上游同步后重打 skill 补丁

已安装的 skills 跟随 mattpocock 上游，一次 sync 会覆盖 research/SKILL.md 和 wayfinder/SKILL.md 里的 ADR 0013 补丁文本（补丁文本保存在 docs/design/research-redesign/）。每次 sync 后运行：

node scripts/apply-skill-patch.ts                 # 重打到 ~/.pi/agent/skills
node scripts/apply-skill-patch.ts --skills-dir X  # 自定义 skills 目录
node scripts/apply-skill-patch.ts --dry-run       # 只预览不写

脚本直接从设计文档重打两个补丁：幂等（已打补丁的目标是 no-op，CRLF 安全）；缺目标时 all-or-nothing（任一文件缺失即视为 sync 未跑——一个文件都不动，exit 1）；参数错误报 usage 提示而不是崩溃栈。