外观
📖 关于本翻译
本文是 pi-subagents 官方文档的非官方社区中文翻译，仅为方便中文读者阅读而整理。
- 英文原文： https://github.com/nicobailon/pi-subagents/tree/v0.67.0/README.md
- 原项目： https://github.com/nicobailon/pi-subagents（作者 Nico Bailon）
- 许可证： MIT
- 本翻译与原作者无任何隶属或背书关系；如与英文原文存在出入或滞后，一律以官方英文文档为准。
pi-subagents 让 Pi 能把工作委派给专注的子智能体（subagent）。它适用于代码评审、代码勘察、功能实现、并行审计、保存的工作流、后台任务，以及任何能从第二双、第三双「模型之眼」中获益的场景。
安装
bash
pi install npm:pi-subagents这是唯一必需的步骤。后台子智能体使用宿主的 SDK：npm 版 Pi 会保留其独立的 Node 运行器；官方 Pi 0.85.1 Linux x64 独立发行版则通过 Pi 内嵌的 SDK 加载同一个运行器，无需单独安装 SDK。关于受支持的边界与校验门槛，参见独立后台执行。
先试试这个
你无需创建 agent、编写配置或学习斜杠命令。安装完成后，用大白话对 Pi 说就行：
text
用 reviewer 评审这个 diff。text
让 oracle 就我当前的方案给出第二意见。质疑其中的假设，告诉我可能遗漏了什么。text
让 scout 结合我们的讨论理解这段代码，然后向我提出澄清问题。text
并行运行多个 reviewer：一个查正确性，一个查测试，一个查是否有不必要的复杂度。这些就足以上手了。是否调用 subagent 工具、用哪个 agent、以及如何编排这些工作，都由 Pi 自行决定。
工作原理
Pi 是父会话。子智能体则是一个专注于自身任务的子 Pi 会话。
当你请求一个子智能体时，Pi 会启动这个子会话、把任务交给它，再把结果带回来。前台子会话运行在父 Pi 进程内部，并在对话中实时输出。后台子会话则运行在一个独立的运行器进程中，会持续工作，之后可随时查看。
安装该扩展并不会在后台自动启动一个 reviewer。它只是给了 Pi 一个委派工具。如果你希望每次实现都经过评审，就在你的提示词或项目指令里明确说明：
text
实现完成后，先运行一个 reviewer 子智能体，再做总结。内置 Agent
该扩展内置了一批可以立即使用的 agent：
| Agent | 适用场景（你想要……时用它） |
|---|---|
scout | 快速在本地代码库做勘察：相关文件、入口点、数据流、风险点。 |
researcher | 带来源的网络/文档调研，并输出简洁的调研简报。需要在子会话中启用 pi-web-access。 |
evidence-auditor | 独立核查重要的调研结论是否有其来源支撑。需要在子会话中启用 pi-web-access。 |
worker | 实现类工作。编辑文件、做校验，遇到未经批准的决策会上报，而不是擅自猜测。 |
reviewer | 对照任务/计划、测试、边界情况与简洁性做代码评审并做小幅修复。 |
oracle | 行动前的第二意见。质疑假设，但不改动代码。 |
delegate | 一个轻量的通用委派者，行为接近父会话。 |
经验法则：在你还不了解代码时用 scout，在你要采信外部事实前用 researcher，在你要依赖重要调研结论前用 evidence-auditor，实现用 worker，检查用 reviewer，而当决策本身让你感到有风险时用 oracle。
常见工作流
该扩展包内置了 /council 与 council-mode，还提供了有文档说明的、基于模型的 council-* 配置示例，供你添加到自己的 agent 目录中。
| 想做什么 | 用自然语言这样说 |
|---|---|
| 获取第二意见 | 「让 oracle 评审这个方案并质疑其中的假设。」 |
| 解决难题 | 「在动手改之前，用 oracle 调查这个 bug。」 |
| 评审一个 diff | 「用 reviewer 评审这个 diff。」 |
| 并行运行多个 reviewer | 「分别针对正确性、测试和清理运行多个 reviewer。」 |
| 就一项重大决策展开辩论 | 「用 /council 召集基于模型的顾问来比较这个决策。」 |
| 先实现再评审 | 「把这个实现出来，然后评审它。」 |
| 反复评审直到干净 | 「对这处改动运行评审循环，最多 3 轮。」 |
| 谨慎执行一个计划 | 「让 worker 实现这个已批准的计划，然后运行 reviewer 并采纳反馈。」 |
| 规划前先勘察 | 「在规划前，用 scout 检查一下认证流程。」 |
| 在后台运行 | 「把这个放到后台运行。」 |
| 使用保存的工作流 | 「在这个分支上运行评审链。」 |
| 浏览 agent | 「给我看看有哪些可用的子智能体。」 |
| 查看运行中的任务 | 「显示正在进行的异步运行。」或「显示子智能体舰队。」 |
| 检查配置 | 「检查一下子智能体是否配置正确。」 |
对于实现类工作，推荐的循环是 clarify → scout → worker → fresh reviewers → worker（澄清 → 勘察 → 实现 → 全新评审 → 再实现）。像 /parallel-review 和 /review-loop 这样打包好的提示词快捷方式让这些模式可复用——参见工作流。
运行中的任务在哪里查看
前台运行会在对话中实时输出进度。后台运行则在控制权交还给你之后仍继续工作。
在 TUI 中，编辑器下方常驻的 FleetView（舰队视图）会让进行中的任务始终可见。/subagents-fleet 会打开一个实时检查器，你可以在其中浏览子会话、阅读对话记录、引导正在运行的子会话，或停止某次运行。你也可以直接问：「给我看看当前的异步运行。」
更多细节、按键绑定以及机器可读的运行产物，见可观测性。
为了给编排设定边界，maxSubagentSpawnsPerRun 会限制单个运行树中累计的逻辑子会话数量。它默认为 64，且与活跃并发数、以及会话级的累计派生预算相互独立。参见配置。
如果感觉有点不对劲
text
/subagents-doctor或者直接问：「检查一下 subagents 和 intercom 是否配置正确。」
要查看已安装版本的帮助，使用 /subagents-guide [topic] 或 subagent({ action: "guide", topic: "workflows" })。默认主题是 overview；可用主题有 overview、workflows、agents、missions、observability、tool-reference、configuration、models、watchdog 和 extension-api。
文档
| 文档 | 内容简介 |
|---|---|
| Agents | 自定义 agent、frontmatter 参考、覆盖内置 agent、工具、扩展、技能、按 agent 隔离的记忆。 |
| Models | 默认模型、按角色覆盖、推荐的分层策略、回退、思考级别、模型作用域约束、配置档（profiles）。 |
| Workflows | 编排模式、提示词快捷方式、脚本化工作流、工作树隔离、子到父的协调、递归防护。 |
| Watchdog | 可选启用的对抗式改动评审器、作用域监控、LSP 检查，以及子会话的工具权限。 |
| Tool reference | 每一个 subagent 参数、管理类操作、状态/控制类操作、验收门槛，以及外部 CLI 运行器。 |
| Observability | FleetView、舰队检查器、生命周期产物、事件、日志、会话共享。 |
| Missions and schedules | 持久化的任务记录、投递回执、定时与周期性运行。 |
| Configuration | 每一个 config.json 键与环境变量。 |
| Extension API | RPC、委派 API、预检、能力上限、受信任的工作流资源、后台工作提供方、Herdr 集成。 |
版权与许可
「pi-subagents」等名称、商标归其各自所有者所有；本项目仅作翻译引用。如原作者认为本翻译存在不当之处，欢迎通过 issue 联系，我们会及时调整或移除。
pi-subagents 及其文档以 MIT 许可证发布。本翻译为衍生作品，同样以 MIT 许可证提供，并按其要求保留原始版权与许可声明：
Copyright (c) 2026 Nico Bailon — Licensed under the MIT License. 原始许可证见 nicobailon/pi-subagents · LICENSE，完整全文见下方折叠内容。
展开查看 MIT License 全文
text
MIT License
Copyright (c) 2026 Nico Bailon
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.