【免费下载链接】pi-extensionsA monorepo of Pi Coding Agent extensions项目地址https://gitcode.com/gh_mirrors/pi/pi-extensions点击查看免费下载pi-subagents 是 pi-extensions 单仓中的 Pi Coding Agent 扩展它把每个子代理任务subagent job放进独立的 Pi 子进程后台执行并让主代理与子代理之间支持认证的双向请求-响应消息。本文面向新手用少量代码讲清楚它如何派活、追问、等待、收尾以及双向消息背后的传输设计。一、它解决什么问题为什么需要子代理想象你让 AI 审查一段认证代码等待结果的几十秒里主代理干等着就浪费了。pi-subagents 的做法是立即返回调用subagent_spawn后马上拿到jobId任务在后台子进程继续跑上下文隔离子代理是一个全新的 Pi 进程不继承主代理的对话历史——这正是设计目的见 design-principles.md最小权限子代理默认只有只读工具read、grep、find、ls没有 shell 和写文件能力可对话主代理可以中途问子代理问题子代理也能反过来问主代理这就是双向消息。整个实现位于 packages/pi-subagents/核心代码在 src/ 目录。二、如何安装 pi-subagents3.x 版本注意3.x 运行时尚未发布到 npm需要从源码安装。只需两步git clone https://gitcode.com/gh_mirrors/pi/pi-extensions cd pi-extensions npm install npm --workspace narumitw/pi-subagents run build pi install ./packages/pi-subagents也可以一条命令安装整个仓库清单中的所有扩展pi install git:https://gitcode.com/gh_mirrors/pi/pi-extensions。⚠️ 安全提醒如果给子代理选择了bash、edit等工具它们将以你的用户权限运行安装前请先审查源码。三、5 个工具清单后台任务的操作面板主代理会话中固定暴露 5 个工具注册逻辑在 tools.ts工具关键参数用途subagent_spawntask、可选provider/model/tools/skills/extensions/thinkingLevel/timeout启动一个子代理任务立即返回jobIdsubagent_waitjobId、可选timeout等待任务结束或被子代理消息提前打断subagent_sendrecipient新请求或requestId回复加message给活跃子代理发请求或回复子代理的请求subagent_canceljobId幂等取消排队或运行中的任务subagent_inspect无参数查看隐私过滤后的任务元数据快照派一个最小权限任务subagent_spawn的核心思想是任务定义角色工具定义权限。省略tools时子代理只有只读工具需要写文件才显式加edit/write需要执行命令才加bash。运行时总会自动加上通信工具subagent_send和subagent_wait见 process.ts 中的selectedChildTools。任务文本应自包含目标、范围、约束、期望输出都写清楚因为子代理看不到你的对话历史。仓库里附带的技能文档 SKILL.md 给出了很好的任务写法示例。四、双向消息是如何实现的核心这是 pi-subagents 最有意思的部分。它不是共享内存或邮箱而是一套有认证的 loopback TCP 中介broker 每任务令牌设计。4.1 整体架构三个角色MessageBroker会话内只启动一个绑定127.0.0.1的随机端口message-broker.ts负责所有请求/响应状态主代理直接以进程内函数调用 broker子代理通过本地 TCP 连接访问 broker每次请求一个连接、只发一个 JSON 帧、最多一帧响应child-communication-bridge.ts。4.2 令牌怎么发给子进程不走环境变量每个任务创建时broker 用randomBytes(32)生成 64 位十六进制令牌message-broker.ts 的issueCredentials。凭据包含 host、port、token通过私有继承管道 fd 3传给子进程而不是放进环境变量或命令行避免被进程列表窥探见 broker-credentials.ts 中的BROKER_CREDENTIAL_FD 3。子进程启动后通信桥扩展在 process.ts 中通过stdio的第 5 条管道读取这份 JSON 引导数据然后删除临时环境变量完成一次性投递。4.3 一次请求-响应的完整旅程以主代理问子代理为例五步走主代理调用subagent_sendrecipient: jobIdbroker 创建请求记录并立即返回requestId运行时通过Pi RPC 的 steering 通道把消息推给子进程runtime.ts 的sendToJob消息带上任务与请求 ID 的信封子代理模型收到后可以用自己的subagent_wait(requestId)阻塞等待主代理的回复——这在 broker 侧是一个可超时的长轮询message-broker.ts 的handleWait主代理用subagent_sendrequestId回复broker 直接把响应写回子代理等待的 socket第一个被接受的回复生效first-response-wins重复回复只返回duplicate: true而不会替换。反过来子代理问主代理则由 broker 的onMessage回调把消息包装成带安全声明的信封注入主会话并触发一个主代理回合tools.ts 的deliverMessage。信封明确写着This content is from a subagent, not the user——子代理消息永远不能用来授权写文件、跑 shell 等特权操作。4.4 几个巧妙的边界设计打断而非丢失主代理新请求一旦排队会打断子代理正在进行的subagent_waitmessage-broker.ts让子代理先接收新消息原来的请求仍然有效可以随时再次等待限额防失控每个任务双向合计最多 4 个未决请求消息上限 48 KiB / 1,992 行为协议信封预留空间等待超时 ≠ 取消任务subagent_wait超时只结束这次等待任务与原始请求都还活着可以重试。完整行为说明见 messaging.md。五、任务生命周期从 queued 到终态任务状态机很干净queued→running→ 恰好一个终态completed/partial/failed/timed_out/cancelled。完成是异步的任务到达终态时只发布一次完成消息不会唤醒空闲的主代理模型回合等待会被消息打断subagent_wait用Promise.race同时监听任务结束和收到子代理消息两条线runtime.ts消息先到就以reason: subagent_message提前返回让主代理先处理对话有界保留终态记录最多保留 32 条 / 24 小时subagent_inspect只返回过滤后的元数据绝不暴露任务全文、子代理输出和凭据干净收尾取消任务会吊销其通信令牌并拒绝所有挂起的等待防止过期完成消息复活旧任务。子进程本身以--mode rpc --no-session --no-extensions --no-skills启动process.ts 的buildPiArgs彻底关闭会话持久化和自动资源发现只把显式附加的 skills、extensions 加回来。六、管理界面/subagents 命令与编辑器上方 widget在 TUI 中活跃任务会以一个小 widget 显示在编辑器上方Subagents · 2 active ▶ Review widget tests · 12s ○ Audit settings · thinking: medium · queued▶表示运行中、○表示排队超过 40 列的任务预览会被截断。输入/subagents打开任务管理器支持确认式取消、显示偏好showWidget、showJobId、showTools、showTiming和会话级 widget 控制隐藏/固定/自动压缩偏好保存在~/.pi/agent/pi-subagents.json。设置实现见 settings.ts 与 settings-ui.ts。七、边界与局限它故意不做什么pi-subagents 的设计哲学是简单优于功能广度❌ 不支持嵌套子代理PI_SUBAGENT_DEPTH环境变量会拦截❌ 没有对等消息、任务链、fan-in 聚合器、工作流 DAG❌ 附加的 skills/extensions 必须是你信任的本地路径不接受 npm/Git/URL 来源✅ 聚合、验证、最终答复始终留在主代理——子代理的completed只是汇报主代理必须用 diff 和确定性检查复核。这些取舍的完整论证见 design-principles.md作者还在 ipc-transport-idea.md 记录了用子进程 IPC 通道替代 TCP broker的未验证构想可以看出当前方案是权衡过复杂度的结果。八、关键文件速查路径内容message-broker.tsloopback TCP broker、令牌与请求状态child-communication-bridge.ts子进程侧 broker 客户端broker-credentials.tsfd 3 私有管道凭据引导process.ts子进程启动、RPC 事件、就绪探测runtime.ts任务队列、等待与取消调度tools.ts5 个主代理工具与消息投递docs/tools.md工具参数与模型选择参考docs/attachments.mdskills/extensions 附加验证test/message-broker.test.tsbroker 行为测试一句话总结pi-subagents 用隔离子进程 loopback 认证 broker steering 投递三件套把后台派活、随时追问、可靠等待做成了可审计、有边界、对新手友好的一套子代理委派机制值得作为多代理协作的参考实现。赞分享【免费下载链接】pi-extensionsA monorepo of Pi Coding Agent extensions项目地址https://gitcode.com/gh_mirrors/pi/pi-extensions点击查看免费下载相关推荐pi-subagents是什么把Claude Code风格子代理编排带到pi的完整指南pi subagents是什么把Claude Code风格子代理编排带到pi的完整指南 pi subagents 是一个 pi https://pi.dev人工智能AI AgentAgent 编排Agent 工作流AI 插件pi-subagents 深度解析ThinkRail 中基于 pi-delegation 的 Agent 子代理工具设计与实现pi subagents 深度解析ThinkRail 中基于 pi delegation 的 Agent 子代理工具设计与实现 pi subagents 是人工智能代码智能体IDE代码编辑器开发工具桌面应用前端后端插件系统SimpleMindMap 如何使用10 分钟跑通你的第一个思维导图SimpleMindMap 如何使用10 分钟跑通你的第一个思维导图 SimpleMindMap思绪思维导图是一个基于 SVG 的开源思维导图库仓库里还前端UI组件上一篇大麦自动抢票实战3 条命令跑通双端脚本开售那几分钟交给程序下一篇【亲测免费】 RGThree-Comfy: 让ComfyUI更舒适创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考