nicobailon/pi-subagents

什么是 pi‑subagents？

pi‑subagents 是 Pi AI 助手平台的扩展，允许单个 Pi 会话生成专注的子代理（称为 subagents）来处理特定工作。可以把它想象成给你的 AI“助手”一个专家团队，可以在前台或后台运行，报告结果，并通过自然语言命令进行编排。

---

核心概念

• 父会话（Pi） 保持对对话的控制。
• 当你请求一个 subagent（例如，“使用 reviewer 审查此 diff”），Pi 会启动一个具有特定角色的子 Pi 会话。
• 子代理执行其任务（代码审查、研究、实现等），并将结果返回给父会话。
• 子代理可以内联（前台）运行——直接在聊天中流式传输输出——或分离（后台）运行——在你返回主对话后继续。

---

内置代理（即用型）

代理	典型用途
scout	快速映射代码库：列出相关文件、入口点、数据流和风险。
researcher	从网络或文档中提取信息，引用来源，并生成简洁简报。
evidence‑auditor	验证研究声明是否确实有引用来源支持。
worker	执行实现：编辑文件、运行验证，并在猜测前请求批准。
reviewer	代码审查——检查正确性、测试覆盖、边界情况和简洁性；可选地应用小修复。
oracle	对计划提供第二意见，挑战假设，并指出盲点（不编辑文件）。
delegate	轻量级通用助手，行为类似于父会话。

---

如何与之交互

你不需要编写配置文件或学习特殊的斜杠命令。安装包后：

pi install npm:pi-subagents

只需用自然语言向 Pi 提问，例如：

• 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, and one for unnecessary complexity. Pi 决定启动哪个子代理，它应该在前台还是后台运行，以及如何组合结果。

---

典型工作流

目标	自然语言提示
获取第二意见	Ask oracle to review this plan and challenge assumptions.
解决难题	Use oracle to investigate this bug before we edit.
审查拉取请求 diff	Use reviewer to review this diff.
同时运行多个审查者	Run reviewers for correctness, tests, and cleanup.
在多个顾问之间进行辩论	Use /council with model‑based advisors to compare this decision.
实现然后验证	Implement this, then review it.
持续审查循环	Run a review loop on this change with a max of 3 rounds.
后台执行	Run this in the background.
检查正在运行的工作	Show me the current async runs.

扩展还附带快捷命令，如 /parallel‑review 和 /review‑loop，用于可重复使用这些模式。

---

可观测性与控制

• 前台运行 在聊天中实时流式传输。
• 后台运行 出现在编辑器下方的持久 FleetView 面板中。你可以使用 /subagents‑fleet 打开实时检查器，浏览子代理、阅读其记录、引导或停止它们。
• 内置看门狗可以监控对抗性更改，强制执行 LSP 检查，并限制单次运行可生成的子代理数量（maxSubagentSpawnsPerRun，默认 64）。
• 辅助命令：
  • /subagents‑doctor – 对子代理系统运行健康检查。
  • /subagents‑guide [topic] – 显示有关 workflows、agents、observability 等主题的文档。

---

配置

所有设置都位于 config.json（或环境变量）中。重要旋钮包括：

• toolActivation – 控制 subagent 工具是立即加载，还是在模型提示缓存刷新后加载。
• bg_wait – 父会话在报告状态前等待后台子代理的时间。
• maxSubagentSpawnsPerRun – 限制单个编排可能创建的总逻辑子代理数。

完整细节在仓库的 docs/ 文件夹中。

---

谁可能受益？

• 开发者 希望在不离开编辑器的情况下获得 AI 辅助代码审查、自动化实现或研究。
• 团队 需要可重复、可审计的 AI 工作流（例如，“运行审查者，然后运行工作者，再运行另一个审查者”）。
• Pi 平台的高级用户 希望将多个专门的 AI 代理组合成单一、连贯的管道。

---

快速入门清单

1. 安装扩展：pi install npm:pi-subagents。
2. 在 Pi 聊天中，输入自然语言请求，如 Use reviewer to review this diff.
3. 在对话中观看结果流式传输，或检查后台舰队视图。
4. 使用 /subagents‑guide 探索更高级的工作流和配置选项。

---

底线： pi‑subagents 将单个 Pi AI 助手转变为一个小型、编排良好的专用代理团队，使复杂任务——代码审查、研究、实现、审计——更容易运行、监控和重复。