Pi Subagent
为 pi 编码代理提供的轻量子代理扩展，可将任务委派给专门的子代理，支持命名会话延续与并行执行。
按维度查看评分与理由
文档层面做了不少安全设计：默认空上下文、项目代理需显式信任或 --approve、starter 代理只读工具、深度/循环守卫、0600 临时文件；但本次审查仅提供 README/LICENSE/package.，未提供 index.ts、runner.ts 等实现代码，所有安全声明均无法在源码中核实，故扣分。敏感数据处理仅有 0600 一处提及，无系统说明，得 1。无卸载/回滚说明，得 1。归属信息完整（Attribution 章节、MIT、版权人），但不扣满因无代码佐证其与文档一致性，得 2。
文档内部自洽：package. 版本、peer 依赖与 README 的 Pi 0.80.5 要求一致，得 2。失败路径文档详细（不活跃超时、绝对超时、部分输出保留、stale lock 处理），但均未在代码中验证，得 2。依赖以可选 peer 形式声明、运行时零硬依赖，可用性风险低，得 2。
面向日常用户与高级扩展作者的分层文档清晰，得 2。能力边界有说明（工具上限、调用数 1–8、输出 50KB/2000 行、命名会话限制），得 2。触发精度依赖 description 字段与 sessionPreference/sessionHint 机制，文档化了但未验证，得 2。考虑了 Unix/Windows、PI_CODING_AGENT_DIR、--no-session 等环境差异，得 2。
信息架构出色：用户指南与高级技术参考分层明确，得 3。安装说明覆盖 npm/git/手动三种方式且含版本要求，得 3。示例丰富（oracle/explore/review 及工具 API 用例），得 3。许可为标准 MIT 且与 package. 一致，得 3。命名稳定但无兼容性政策，得 2。局限性散落在注释中而非集中章节，得 2。版本号 3.0.3 但无 CHANGELOG 或发布历史，得 1。无维护者/贡献/支持声明，得 1。
输出格式统一（成功/失败计数加逐项结果）、超限时保留细节并落盘，文档化良好但未验证，得 2。在众多 Pi 子代理扩展中，其差异化在命名会话与守护机制，属中等边际价值，得 2。轻量、无运行时依赖、开销主要在子进程模型本身，成本收益合理但有 parent 快照克隆的开销提示，得 2。
所有核心声明（隔离进程、锁机制、深度守卫、信任门控）均无法在提供的源码中追踪到实现，得 1。README 与 package. 之间可交叉印证（名称、版本、仓库、许可、peer 依赖），得 2。文档基本区分了默认行为、可配置项与建议性提示，事实与推断分离尚可，得 2。
- 本评估为静态审查，仅见 README/LICENSE/package.；隔离、锁与守卫等安全声明未经源码核实，建议人工审阅 index.ts 与 runner.ts 后再采用。
- 项目代理文件是仓库可控配置并以与用户代理等同的权限执行；复制任何示例代理（如 oracle.md）前务必先审查其模型与工具白名单。
- initialContext: parent 会继承父会话的全部指令权威，仅在确有必要时使用。
- 无 CHANGELOG 与维护者声明，升级到 3.x 需自行验证兼容性；进程被杀后需手动清理会话锁目录。
- 命名会话需要持久化的父会话；在 --no-session 下会静默退化为仅临时委派，请据此设计工作流。
这个 Agent 能做什么，适合哪些场景？
Pi Subagent 是 pi 编码代理的一个扩展（mjakl/pi-subagent，MIT 许可），让主代理把提示词委派给专用的子代理，例如代码审查、代码库探索或测试审计。子代理以 Markdown 文件加 YAML frontmatter 定义，存放在 ~/.pi/agent/agents/*.md 或项目目录 .pi/agents/*.md，首次运行时若无代理会自动创建只读的 explore 起始代理。每个子代理运行在独立的 pi 进程中，通过 Pi 的无头 RPC 模式传输提示词，与父进程无共享状态。该扩展支持一次性或最多 8 个并行调用、跨多轮的命名持久会话、按调用覆盖模型，以及深度与循环递归防护、无活动看门狗、流式 TUI 展示等运行时安全机制。
安装后向 pi 的系统提示注入可用代理列表；主代理通过名为 subagent 的工具发起委派，工具接收一个 calls 数组（1–8 个调用），每个调用包含 agent、prompt，可选 model、cwd、initialContext（empty/parent）、session、inactivityTimeout、timeout。子代理在独立 pi 进程中运行（以 PI_OFFLINE=1 启动），按 frontmatter 配置继承或覆盖模型、思考级别、工具白名单（如 tools: read,grep,find,ls 或 noTools: true）。命名会话通过 pi-subagent/v1 + 父会话 ID + 工作目录 + 代理名 + 会话句柄派生出不透明的子会话 ID，并有跨进程的会话锁防止并发冲突。结果以统一格式返回（如 2/2 succeeded），受 50KB/2000 行上限约束，超限内容写入临时文件；扩展还强制深度上限（默认 3）和循环防护（默认开启），并通过 PI_SUBAGENT_DEPTH 等环境变量向子进程传递委派栈信息。
- 开发者在 pi 中审查当前 diff，让主代理委派给 thinking: high 的 review 子代理做正确性与回归风险评估
- 探索陌生代码库时使用 explore 子代理定位认证等功能实现位置并返回带行号引用的摘要
- 多步专项工作（如 API 变更审查）通过命名会话（session: api-review）在后续对话中延续同一专家上下文
- 需要同时从多个角度分析（审查 + 测试覆盖）时，用一次 subagent 调用并行运行多个子代理
- 团队通过项目目录 .pi/agents/*.md 共享仓库内的专用代理配置，配合 Pi 的信任存储控制启用
- 希望给特定代理换更强模型（如 anthropic/claude-sonnet-4）时，在代理文件或单次调用中覆盖默认模型
这个 Agent 有哪些优点和局限？
- 统一工具接口同时支持单次委派与最多 8 个并行调用，主代理无需为并行场景使用不同扩展
- 命名持久会话（通过派生会话 ID 与跨进程会话锁）支持多轮专家对话，可迭代地延续同一审查或探索上下文
- 运行时安全机制完整：深度守卫（默认 3 层）、循环防护、按调用可覆盖的无活动看门狗与绝对超时，防止递归失控与静默挂起
- 代理定义即 Markdown 文件，可按用户/项目分层，项目代理仅在显式信任记录后生效，避免不可信仓库配置自动执行
- 上下文控制精细：子代理默认全新启动，仅在明确指定 initialContext: parent 时才克隆父快照，降低成本与权限外泄风险
- 强依赖 pi 编码代理运行时（要求 0.80.5+），不能脱离 pi 在其他代理框架（如 Claude Code、Codex）中直接使用
- 子代理运行在独立 pi 进程中，每次委派都有进程启动与 RPC 开销；initialContext: parent 的克隆被明确标注为代价高昂
- 结果输出受 50KB/2000 行限制，超限内容需从临时文件或 TUI 展开视图获取完整摘要
- 长运行的子代理若被强制终止可能留下会话锁，需要用户手动确认并删除锁目录
- 命名持久会话要求父 pi 会话已持久化，使用 --no-session 或临时父会话时不可用
- 除了仓库自述外，缺少独立的采用案例、性能基准或社区规模数据佐证
如何安装或部署这个 Agent？
前提：Pi 0.80.5 或更新版本。三种方式任选其一：
1) npm 安装（推荐）：pi install npm:@mjakl/pi-subagent
2) git 安装：pi install git:github.com/mjakl/pi-subagent
3) 手动安装：cd ~/.pi/agent/extensions && git clone https://github.com/mjakl/pi-subagent.git && cd pi-subagent && npm install
安装后首次运行 pi 时，如无任何子代理，扩展会自动创建起始代理 explore.md。可选：从仓库检出安装示例代理 oracle.md（复制 agents/oracle.md 到用户代理目录，安装前请审查其模型与工具配置）。
如何使用这个 Agent？
安装后正常使用 pi 即可：直接提出适合专家处理的问题（如"审查这个 diff"或"找出认证在哪里实现"），主代理会自行决定委派、运行子代理并把结果合并回对话，无需手动调用 subagent、编写 JSON 或直接操作工具。委派过程在 TUI 中以流式进度和可展开详情呈现。需要自定义专家时，在 ~/.pi/agent/agents/*.md 或 .pi/agents/*.md 中编写带 YAML frontmatter（name、description，可选 model、thinking、tools、sessionPreference 等）的 Markdown 代理定义，Markdown 正文即该代理的附加系统提示。高级用户可通过 CLI 标志 --subagent-max-depth 或环境变量 PI_SUBAGENT_MAX_DEPTH 调整递归深度上限。
这个 Agent 与同类方案有什么区别？
README 自述"Pi 有许多子代理扩展"并将 vaayne/agent-kit 与 mariozechner/pi-mono（badlogic）列为灵感来源，但未做具体功能对比；选择本扩展的差异化点是其小面积安装面、命名会话与委派防护的组合。