Pi Subagents 多智能体编排框架
为 Pi 代理框架打造的多代理扩展：让一个代理把工作交给另一个代理，支持交互/后台、同步/异步、编排者模式与多种终端复用器。
证据显示较完善的最小权限设计：spawning 默认 false、spawn-depth/width 限制、tools/extensions/skills 可白名单化、后台子进程强制 --no-approve、trust-project 默认 false；README 明确说明子进程继承全部环境变量（含 API key）并提供 deny-env 与 PI_SUBAGENT_ENV_DENY 缓解，故敏感数据处理给 2 而非更高。但扣分点：无用户确认环节（启动子代理不需显式确认）、task-expansion: shell 会把父任务文本作为 shell 执行（虽为显式 opt-in 且有警告，仍是高风险面）、无依赖安全策略（locked 文件或审计说明未提供）、无回滚/撤销机制说明、flags 字段可覆盖安全参数（文档自认 last-wins）。
测试文件显示大量行为契约（会话模式解析、名称校验、超时加载失败即报错而非静默无限制），错误信息带具体修复提示（如 lineage-only 无父会话的提示）。扣分：依赖为松散 >=/^ 范围的 pi 生态包，无锁定版本，依赖可用性无法静态保证；提交信息外的运行时稳定性仅靠测试源码推断，未执行验证。
面向 power-user 的定位极其明确（5 种 mux 后端、交互/后台、同步/异步、编排模式、适用/不适用场景说明），audience 给 3。扣分：环境依赖外部二进制（tmux/zellij/wezterm/herdr/cmux）需自行安装，README 提到失败有 setup hint 但未见完整降级路径；触发精度依赖 description 字段质量，文档承认环境检测可能失败。
命名规范严格（kebab-case 名称校验有测试）、License 完整且正确归属上游 HazAT 与 edxeth 双版权、安装一行命令、字段参考表详尽。扣分：README 在 timeout-warn-threshold 段落被截断（'not a queued advisory steer' 处戛然而止），文档不完整；无 CHANGELOG 文件、版本仅 package. 的 2.9.0；无 FAQ、无独立示例目录（仅外链 gist）；维护者责任与更新路径无明确说明（未验证发布者）；README 中含 Discord 推广及折扣营销内容，与文档主体混杂。
输出可用性有细节：上下文用量报告、wrap-up 标记防止父代理误判失败、防 resume 浪费；编排模式解决真实的多代理浪费问题，边际价值明确。扣分：成本面（best-of-N verifier、多子进程并行）无成本估算指引；实际效果完全未执行验证，收益声明不可静态确认。
声明大多可追溯到具体 frontmatter 字段与测试断言（如 spawning 默认、后台 --no-approve 均有测试对应）；文档对风险（env 继承、shell 展开）的警示与事实区分清晰。扣分：README 引用外部权威（Anthropic COORDINATOR_MODE、OpenAI Codex issue、ADCS 规范）作为设计佐证，本次证据集内无法交叉核实；orchestrator/verifier 等行为无法从提供的 src 代码核对（源码未附），只能依赖测试与文档互证。
- 子进程默认继承父进程全部环境变量（含 API key/token）；未配置 deny-env 或 PI_SUBAGENT_ENV_DENY 时密钥会进入子进程环境，项目级 agent 文件由他人提供时尤其危险。
- task-expansion: shell 会把父任务文本当作 shell 输入执行，仅应在任务内容完全可信的 agent 上启用。
- flags 字段可覆盖生成参数（含 --approve/--no-approve，last-wins），是绕过安全默认的通道；审慎审查任何第三方 agent 文件中的 flags。
- README 在 timeout-warn-threshold 一节被截断，文档不完整，使用相关功能前应阅读源码确认行为。
- 无 CHANGELOG 且发布者未经验证，升级前应 diff 检查；README 含社区营销内容，与产品文档混合，注意甄别。
- 对 Anthropic/Codex/ADCS 的类比声明为作者论述，本仓库证据内无法核实，不应作为采用依据。
这个 Agent 能做什么，适合哪些场景？
pi-subagents 是面向 Pi 代理框架（pi）的多智能体扩展，fork 自 HazAT/pi-interactive-subagents 并深度重构。它让父代理通过 subagent 工具将任务委托给按 Markdown 前置元数据（frontmatter）定义的具名子代理，子代理以独立 Pi 进程运行。子代理可在 Herdr、cmux、tmux、zellij 或 WezTerm 中以可见交互面板运行，也可作为无界面的后台 pi -p 进程运行；启动可为异步（父代理稍后收到结果）或同步（阻塞等待）。编排者模式将父会话限制为只能委派——移除 read/bash/edit 等工具并替换系统提示词。框架还提供子代理生命周期管理（auto-exit、subagent_done、caller_ping、subagent_resume）、会话分叉（fork 继承父上下文）、时间与上下文窗口限制、嵌套生成控制，以及基于 git worktree 的 LLM-as-a-Verifier Best-of-N 机制。MIT 许可，通过 pi install 安装。
父代理调用 subagent 工具（需 name 与 title）启动子代理。代理定义文件位于 .pi/agents/ 或 ~/.pi/agent/agents/，frontmatter 控制模式（interactive/background）、异步性（async）、模型与思考级别（model/thinking、allow-model-override、allowed-models）、工具与技能白名单（tools、deny-tools、skills、inject-skills）、环境变量（env、deny-env）、超时（timeout、idle-timeout、timeout-warn-threshold）、上下文警告（context-warn-threshold）、嵌套生成（spawning、spawn-depth、spawn-width、visible-to）以及 parent-close-policy。交互式子代理在检测到的或 PI_SUBAGENT_MUX 指定的复用器中打开面板；后台子代理以 pi -p 无头进程运行。子代理结果（含会话路径、上下文用量）返回给父代理，可用 subagent_resume 恢复。编排者模式通过 /subagents 面板或 Alt+S 开启，或设 PI_ORCHESTRATOR_MODE=1，仅保留 subagent、subagent_kill、subagent_resume 工具。llm-as-a-verifier 模式为每次启动在独立 git worktree 中并行运行多个尝试，由配置的验证模型（需支持 OpenAI logprobs 格式）按 criteria 评分并选出最佳结果。
- 多代理工作流用户：希望父代理只做规划与协调，把读文件、改代码、跑测试分别交给具名子代理，编排者模式强制这种分工
- 并行研究场景：把独立的研究问题拆给多个后台子代理异步运行，结果稍后回传
- 写后验证循环：用 llm-as-a-verifier 在多个 git worktree 中并行尝试实现，由验证模型选出最佳方案
- 长任务风险控制：为子代理配置 timeout/idle-timeout 与上下文窗口警告，避免失控子代理或上下文溢出
- 终端重度用户：在 tmux、zellij、Herdr、cmux 或 WezTerm 中以可见面板监督每个交互式子代理的实时工作
- 需要上下文继承的任务：用 fork 会话模式让子代理看到父代理转录中的决策与先验结果
这个 Agent 有哪些优点和局限？
- 配置粒度极高：数十个 frontmatter 字段精细控制子代理的模型、工具、技能、环境变量、超时与嵌套生成权限
- 编排者模式借鉴 Claude Code 的 COORDINATOR_MODE，通过工具限制与提示词替换强制父代理只做协调，避免两个代理互相竞争
- llm-as-a-verifier 提供基于 git worktree 隔离的 Best-of-N 尝试加独立验证模型评分的完整实现
- 支持五种终端复用器自动检测，交互式子代理以带标题的可见面板运行，TUI 小部件实时展示子代理状态与上下文用量
- 强依赖 Pi 代理框架生态，非 Pi 用户无法直接使用
- 交互式子代理必须在一个受支持的终端复用器（Herdr、cmux、tmux、zellij、WezTerm）中运行，否则启动失败
- llm-as-a-verifier 要求验证后端返回 OpenAI logprobs 格式，Anthropic 及多数代理/聚合器不可用，且一次 3 候选运行约产生 72 次 API 调用，成本需预算
- 文档明确说明工具与扩展限制不是安全沙箱，不受信代码需依赖操作系统或容器隔离
- 配置面庞大（环境变量、frontmatter 字段众多），新用户学习成本高
如何安装或部署这个 Agent？
需要已安装 Pi 代理框架。运行：
bash
pi install git:github.com/edxeth/pi-subagents若要在交互面板中运行子代理，请在 Herdr、cmux、tmux、zellij 或 WezTerm 之一内启动 pi。仓库描述未列出其他依赖（如 Node.js 版本），安装前请查阅仓库确认。
如何使用这个 Agent？
- 在项目的 .pi/agents/ 或全局 ~/.pi/agent/agents/ 下创建 Markdown 代理文件，例如 scout.md：
md
---
name: scoutdescription: Inspect the codebase and report the relevant files.
mode: background
auto-exit: true
tools: read,grep,find,ls
---You are a codebase scout. Find the relevant files and return a concise map.
- 在 Pi 会话中让父代理调用 subagent 工具并指定该代理名称，或按 Alt+S 打开 /subagents 面板。交互式代理在当前复用器中开面板；后台代理无头运行。
- 可选：设
export PI_ORCHESTRATOR_MODE=1让父会话只能委派；设PI_SUBAGENT_MUX=tmux等强制指定复用器。 - 用 subagent_resume 恢复子会话，subagent_kill 终止运行中子代理，/subagents 面板查看运行状态。
这个 Agent 与同类方案有什么区别？
README 将其定位与 Anthropic Claude Code 的 COORDINATOR_MODE 类比：同样采用受限工具集、替换系统提示词与工作者隔离的协调者机制。区别在于 pi-subagents 运行在 Pi 代理框架之上，并增加了可视化终端面板、会话分叉与 LLM-as-a-Verifier 等能力。