pi-subagents：Pi 的异步子代理委派扩展

pi-subagents 如何将工作委派给子 Pi 会话 · nicobailon-pi-subagents-deep-analysis

pi-subagents 是 Pi 助手的 TypeScript 扩展。它允许父 Pi 会话启动专注于特定任务的子会话，称为子代理，每个子代理都有自己的任务。README 列出的预期用途包括代码审查、侦察、实现、并行审计、保存的工作流和后台作业。安装扩展不会启动自动审查器；它给 Pi 一个委派工具。子会话运行自己的任务并返回结果，前台运行在对话中流式传输，后台运行则继续工作。

專案核對 0：請在 nicobailon-pi-subagents-deep-analysis 的 README、設定檔或命令輸出中確認這一節描述的具體行為，並把檔案路徑、參數名稱、平台條件與錯誤結果分開記錄。這些觀察可用來判斷功能是否真的符合目前流程，也能在升級後定位差異。素材未列出的性能或安全承諾，不應自行補上。

安装和首次委派提示 · nicobailon-pi-subagents-deep-analysis

安装只需一条命令：`pi install npm:pi-subagents`。之后，你可以用自然语言要求 Pi 进行委派，无需创建代理、编写配置或学习斜杠命令。README 中的示例包括"Use reviewer to review this diff."和"Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity."。Pi 决定是否调用 `subagent` 工具、使用哪个代理，以及如何用 `workflowScript` 表达组合工作。扩展自带内置代理，可以立即使用。

專案核對 1：請在 nicobailon-pi-subagents-deep-analysis 的 README、設定檔或命令輸出中確認這一節描述的具體行為，並把檔案路徑、參數名稱、平台條件與錯誤結果分開記錄。這些觀察可用來判斷功能是否真的符合目前流程，也能在升級後定位差異。素材未列出的性能或安全承諾，不應自行補上。

内置代理清单 · nicobailon-pi-subagents-deep-analysis

该包捆绑了八个代理。`scout` 进行快速的本地代码库侦察。`researcher` 收集网络和文档来源。`planner` 制定实现计划而不编辑代码。`worker` 编辑文件并验证更改。`reviewer` 检查实现是否符合任务和测试。`context-builder` 编写交接材料，如 `context.md` 和 `meta-prompt.md`。`oracle` 挑战假设并推荐下一步而不编辑。`delegate` 是一个轻量级通用子代理，行为接近父会话。除非你设置不同的默认值，否则内置代理继承你当前的 Pi 默认模型。

專案核對 2：請在 nicobailon-pi-subagents-deep-analysis 的 README、設定檔或命令輸出中確認這一節描述的具體行為，並把檔案路徑、參數名稱、平台條件與錯誤結果分開記錄。這些觀察可用來判斷功能是否真的符合目前流程，也能在升級後定位差異。素材未列出的性能或安全承諾，不應自行補上。

模型路由、覆盖和模糊匹配 · nicobailon-pi-subagents-deep-analysis

你可以设置 `subagents.defaultModel` 为所有没有显式模型的子代理提供默认值。每个代理的覆盖位于 `agentOverrides` 中，可以更改模型、思考级别、工具、技能、提示文本或禁用内置代理。`subagents.defaultThinking` 和 `subagents.defaultExtensions` 为未设置这些字段的代理提供共享默认值。模型 ID 与注册表模糊匹配，因此提供者分隔符变体、大小写差异和尾随日期戳解析为同一模型；精确的 `provider/id` 匹配仍然优先。项目设置从最近的包含 `.pi` 或 `.agents` 的父目录解析，除非 `projectRootResolution` 设置为 `git-root`。

專案核對 3：請在 nicobailon-pi-subagents-deep-analysis 的 README、設定檔或命令輸出中確認這一節描述的具體行為，並把檔案路徑、參數名稱、平台條件與錯誤結果分開記錄。這些觀察可用來判斷功能是否真的符合目前流程，也能在升級後定位差異。素材未列出的性能或安全承諾，不應自行補上。

可选的看门狗和权限门 · nicobailon-pi-subagents-deep-analysis

子代理看门狗是一个可选择加入的对抗性更改审查器，与 `reviewer` 代理分开。它仅在最终仓库状态改变时在 `agent_end` 边界审查仓库编辑，将多次编辑合并为一次审查，并跳过生成的工件。它可以在更改的 TypeScript 和 JavaScript 文件上运行新的语言服务器诊断，并通过 `subagents.watchdog.cadence.everyNTools` 支持 Scopey 风格的范围监控。原生子代理权限也是可选择加入的：`permissions.rules` 中的 `allow`、`ask` 和 `deny` 规则门控非 bash 工具调用，`ask` 会暂停调用以让看门狗模型仲裁。Bash 始终通过，外部 CLI 配置文件对原生权限不透明。

專案核對 4：請在 nicobailon-pi-subagents-deep-analysis 的 README、設定檔或命令輸出中確認這一節描述的具體行為，並把檔案路徑、參數名稱、平台條件與錯誤結果分開記錄。這些觀察可用來判斷功能是否真的符合目前流程，也能在升級後定位差異。素材未列出的性能或安全承諾，不應自行補上。

异步运行、Fleet 视图和生命周期工件 · nicobailon-pi-subagents-deep-analysis

前台运行在对话中流式传输进度，并且当调用和代理都没有提供超时时，默认有 30 分钟的挂钟超时。后台运行在控制权返回后继续工作。TUI 在编辑器下方显示持久的 FleetView，`/subagents-fleet` 打开实时检查器。异步运行写入机器可读的生命周期工件：`status.json`、`events.jsonl`、`output-<index>.log`，以及结果目录中的最终摘要。生命周期工件 v3 添加了进程终止证明，只有在实时父进程看到分离运行器的 `close` 事件时才标记为 `observed`。其他 Pi 扩展可以使用进程内事件总线 RPC，方法包括 `ping`、`status`、`spawn`、`steer`、`interrupt`、`stop` 和 `resume`。

專案核對 5：請在 nicobailon-pi-subagents-deep-analysis 的 README、設定檔或命令輸出中確認這一節描述的具體行為，並把檔案路徑、參數名稱、平台條件與錯誤結果分開記錄。這些觀察可用來判斷功能是否真的符合目前流程，也能在升級後定位差異。素材未列出的性能或安全承諾，不應自行補上。

编排、监督者协调和 workflowScript · nicobailon-pi-subagents-deep-analysis

推荐的编排循环是 `clarify`、`planner`、`worker`、`fresh reviewers`、`worker`。运行时强制执行子代理安全边界：生成的子代理不会收到捆绑的技能，分叉上下文过滤会移除仅父级的子代理工件，并且默认情况下子代理不会注册 `subagent` 工具，除非其解析的工具包含它。原生监督者协调允许子代理使用 `contact_supervisor` 向父级请求决策，父级通过 `subagent_supervisor({ action: "reply" })` 回复。多代理编排通过 `subagent` 工具中的 `workflowScript` 表达；传统 `/chain`、`/parallel` 和 `/run-chain` 命令未注册。README 以精确命令语法、自定义代理 frontmatter、脚本化工作流和配置键的参考资料结尾。

專案核對 6：請在 nicobailon-pi-subagents-deep-analysis 的 README、設定檔或命令輸出中確認這一節描述的具體行為，並把檔案路徑、參數名稱、平台條件與錯誤結果分開記錄。這些觀察可用來判斷功能是否真的符合目前流程，也能在升級後定位差異。素材未列出的性能或安全承諾，不應自行補上。

編輯結論

README 以精确命令语法、自定义代理 frontmatter、脚本化工作流和配置键的参考资料结尾。该仓库以 MIT 许可证发布，该许可证授予使用、修改和再分发权利，但不提供任何担保。

官方來源

1. Official README
2. Project repository
3. Release notes