单脑变军团pi-subagents 异步子代理委托完整上手指南从安装到反向提问一次讲透【免费下载链接】pi-subagentsPi extension for async subagent delegation with truncation, artifacts, and session sharing项目地址: https://gitcode.com/GitHub_Trending/pi/pi-subagents想象一下深夜十一点你让 Pi 重构一个认证模块然后盯着进度条干等了二十分钟。这不是效率问题是架构问题——单会话只能串行做事。pi-subagents 正是为异步子代理委托而生的 Pi 编码代理扩展它把大任务拆给专注的子代理去跑支持后台运行、任务链、并行审查与跨进程通信。读完本文你能在 5 分钟完成 pi-subagents 安装教程掌握并行与链式编排的异步子代理使用指南还能学会让子代理通过 intercom 反向问你问题最后带走一份可直接照抄的多代理常见问题清单。先讲三个让你血压升高的真实场景场景 A你让 Pi重构登录模块它闷头把代码全改了然后告诉你已验证。你打开 diff 一看测试没跑、边界条件漏了——但你已经没法拦着它了。场景 B你想让 Pi 先扫一遍代码库再动手它却一边读文件一边改文件把侦察和施工混在一起结果半途发现前提假设错了全部推翻重来。场景 C你让它改完自己复查一遍。它回答已经检查过了。可你心里清楚让同一个大脑既当运动员又当裁判等于没检查。这三个场景的共同病根是没有分工就没有质量与效率的杠杆。一个会话进程只能在一根时间线上前进而真实工程任务天然可以拆成侦察、设计、施工、验收四个阶段。你需要的是一个AI 干团队而不是一个AI 全能单兵。一次委托四件套pi-subagents 到底解决了什么用项目经理的视角理解 pi-subagents 会非常顺。Pi 是你的主会话也就是项目经理你通过它派出去的每个子代理都是一个拥有独立职责的领域专家跑在独立的 Pi 子会话里。项目经理负责拆任务、定验收标准、收结果专家负责闷头干自己的活。这个设计围绕四个能力展开官方描述是 delegation、truncation、artifacts、session sharing我把它翻译成委托四件套能力大白话解释你得到的实际好处Delegation父会话派发子代理并回收结果一个任务拆成多个专家并行或串行Truncation子代理自带独立的精简上下文主会话上下文不被海量中间过程撑爆Artifacts每个子代理产出可复用的结果文件下游代理直接消费上游产出不用重跑Session sharing可基于父会话上下文分叉子代理知道你们聊过什么不必从零解释派活不等于乱派。扩展内置了六个开箱即用的专家它们就是普通 Markdown 文件你可以随意改写见agents/目录scout做代码侦察、researcher做外部资料调研、worker动手实现、reviewer审查挑刺、oracle在动手前挑战你的方案、delegate当轻量通用替身。记住这个口诀就能选对角色先 scout 再动手先 researcher 再信外网worker 施工reviewer 验收拿不准就问 oracle。5 分钟装好并用起来pi-subagents 安装三步法 ⚡安装比你想象中简单因为扩展会自注册subagent工具你不需要写任何配置。第一步安装pi install npm:pi-subagents第二步验证。在对话里跑一句诊断命令看到一切正常的结论就说明桥接已就绪/subagents-doctor第三步用自然语言派第一个活不用学任何命令格式Use reviewer to review this diff.Ask oracle for a second opinion on my current plan. Challenge assumptions and tell me what I might be missing.你很快会看到子代理在前台流式输出进度跑完后把结论收回到主会话。注意一个反直觉的点安装扩展并不会自动开启每改必审的后台审查员它只是给了 Pi 一把委托工具。想让每次实现都被审一遍你需要在提示词里说清楚比如When you finish implementing, run a reviewer subagent before summarizing.从等一个到管一群异步子代理编排的三种打开方式装好只是开始真正的威力来自编排。这里给出三种由易到难的方式这也是异步子代理使用指南里含金量最高的部分。方式一后台派活控制权立刻归还。前台运行会在对话里流式刷屏适合短任务长任务请加--bg把控制权还给你/run scout 扫描 auth 模块的入口点与数据流 --bg/run worker 实现购物车接口 --bg控制权归还后你可以继续聊天、写文档、干别的活运行状态会常驻在 TUI 底部的 FleetView 面板里随时可查。方式二一句话启动并行审查。让多个 reviewer 从不同角度同时开审再汇总成一份修复清单Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity.方式三用脚本精确编排流水线。当自然语言不够精确时直接在subagent工具里写一段 JavaScript。下面这段先让 scout 侦察再让两个 reviewer 并行复查最后把两个审查结论一起返回subagent({ workflowScript: const scan await runs.run(scan, { agent: scout, task: Scan the codebase }); const reviews await runs.all([ { key: correctness, agent: reviewer, task: Review correctness: scan.output }, { key: tests, agent: reviewer, task: Review tests: scan.output } ]); return reviews.map(result result.output); });如果多个写子代理要同时改同一个仓库记得给每个runs.run加上worktree: true让它们在独立的 git worktree 里干活避免互相踩文件。关于这里的单写者原则后面踩坑清单还会再提一次。社区验证过的最稳循环是clarify → scout → worker → fresh reviewers → worker先澄清需求再侦察现状worker 施工换一批全新 reviewer 挑刺最后 worker 按反馈修一遍。扩展还打包了几个一键模板——/parallel-review、/review-loop、/parallel-research、/gather-context-and-clarify——直接复用即可。—— 中间有一段关键转折你发现了吗前面所有流程都是父管子子代理永远在被动执行。接下来的玩法会让整个协作反过来。pi-intercom 集成当子代理卡住让它直接回头问你 背景任务跑着跑着子代理遇到一个只有你才能拍板的决策点怎么办以前它只能猜猜错了整个任务链白跑。现在它有了一个专门的协调工具contact_supervisor叫反向提问再贴切不过。用法分两类通过reason区分reason: need_decision阻塞型提问子代理卡住了等你决策或澄清然后留在原地等你回复。reason: progress_update非阻塞型更新子代理发现某个事实改变了计划给你发一条简短播报然后继续干活。你不需要在子代理的配置里做任何事因为delegate等内置代理已经把contact_supervisor写进了工具白名单见agents/delegate.md的 frontmatter。你只需在派活时给一句授权Run this implementation in the background. If the worker gets blocked or needs a product decision, have it ask me through intercom.当子代理发起提问时主会话里会收到一条需要你回应的消息。你可以用工具确认有哪些待回复的提问然后回话subagent_supervisor({ action: pending }) subagent_supervisor({ action: reply, replyTo: session-id, message: 用方案 B邮箱为空时走注册页。 })这里有个很多人不知道的细节这条父-子双向通道是原生支持的未必需要安装 pi-intercom。pi-subagents 自己实现了contact_supervisor子侧和subagent_supervisor父侧只有当外部pi-intercom存在时intercom工具才会作为兼容后备出现。所以 pi-intercom 集成配置方法其实是可选但推荐——装了它你对消息投递和外部监听会有更完整的控制。想微调桥接行为编辑配置文件~/.pi/agent/extensions/subagent/config.json{ intercomBridge: { mode: always, instructionFile: ./intercom-bridge.md, resultDelivery: true } }三个字段的含义mode默认always每次派活都注入协调指令改成fork-only就只在分叉运行时注入off彻底关闭instructionFile可以放一个自定义 Markdown 模板替换默认指令里面的{orchestratorTarget}会被自动替换成父会话地址resultDelivery打开后分组完成结果会以一条条消息投递给外部监听者。实战复盘一个后台实现 反向提问 并行审查的完整项目 ️纸上谈兵到此为止我们跑一个真实小项目给一个仓库新增一条 CLI 命令全程不阻塞你的主对话。第 1 步派活并授权反向提问。把整件事交给后台 worker明确告诉它决策点找谁后台实现新增 --json 输出选项开工前先让 scout 摸清现有 CLI 入口。如果实现中需要我拍板比如参数命名或默认行为通过 intercom 问我别猜。第 2 步控制权立即归还你继续做自己的事。FleetView 面板会显示两个后台任务scout 和 worker的状态。第 3 步收到提问。几分钟后worker 发来need_decision默认输出格式是保持纯文本还是直接改成 JSON你用subagent_supervisor回复保持纯文本JSON 仅在加参时输出worker 继续施工。第 4 步等 worker 收工跑一轮并行审查。直接问用三个 reviewer 并行审这次改动一个查正确性一个查测试覆盖一个查过度设计。第 5 步打开监控面板看全过程。在对话里运行/subagents-fleet你能浏览每个子代理的实时状态、读取结构化 transcript、甚至从面板里直接 steer 或停止某个还在跑的任务一个值得养成的习惯是审查通过后给这一轮派活补一句记录任务的意图。扩展会把运行沉淀成持久的 mission 记录并附带投递回执下次同类任务可以直接复用或定时重跑。高频踩坑清单七个问题与对应解法 子代理说没有权限改文件检查该代理 frontmatter 的tools白名单是否包含edit、write。内置代理默认白名单很严格这是特性不是 bug。自定义工具在子代理里神秘失踪白名单写工具名不等于加载了工具提供方。需要把提供方加进extensions或subagentOnlyExtensions只适用于子会话的扩展用后者更干净。子代理发来消息却看不到先跑/subagents-doctor诊断桥接确认父会话的 session id 是否仍指向派活时的那个会话——消息只投递到当初派出它的那个 Pi 会话。子代理卡住不干活用subagent({ action: status })看状态必要时interrupt打断或subagent({ action: stop })停掉重排。子代理原则上不应做常规完成交接所以卡住通常是任务描述不清先检查任务文本。子代理无限嵌套变套娃默认递归上限是两层主会话 → 子代理 → 孙代理超了会被拦截。想放宽启动前设置PI_SUBAGENT_MAX_DEPTH3。多个 worker 并行改同一仓库打架要么遵守同时只保留一个写者要么给写子代理加worktree: true做 git worktree 隔离。researcher 报错抓不到网页researcher依赖web_search、fetch_content这类工具需要额外装pi install npm:pi-web-access。这是扩展自身不带外网能力的常见误判。收尾从能派活到会带队 ✅最后帮你把收获串一遍pi-subagents 的本质是给 Pi 装上一个委托中枢让你从单会话的串行泥潭里上岸5 分钟安装即可用六个内置代理覆盖侦察、调研、施工、审查、咨询全流程后台--bg归还控制权workflowScript精确编排并行与链式流水线contact_supervisor让子代理在决策点反向找你配合 FleetView 实时监控一个可落地的多代理协作闭环就此成型。下一步建议你挑一个真实仓库先跑一次gather-context-and-clarify感受先侦察后提问再尝试把一段自己最常做的检查流封装成/parallel-review这样的固定模板。遇到坑就跑/subagents-doctor并把你的踩坑经验沉淀成项目里的自定义代理配置——这才是把工具变成团队的正确姿势。【免费下载链接】pi-subagentsPi extension for async subagent delegation with truncation, artifacts, and session sharing项目地址: https://gitcode.com/GitHub_Trending/pi/pi-subagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考