pi-subagent

English | 中文

从 pi 启动隔离的 sub-agent。每个 sub-agent 都是一个完整 pi 实例、拥有独立上下文——主对话保持干净。

你： 调研一下这个项目的数据库 schema
  → pi 调用 Agent，spawn 一个常驻的 `pi --mode rpc` 子进程
  → 子 agent 在独立上下文窗口里独立工作
  → 结果返回；你继续聊天

为什么需要它？

Pi 没有内置 sub-agent。当一个任务会产生大量中间输出（搜索结果、日志、测试输出）污染你的上下文，或者你想并行跑独立任务而不阻塞主对话时——这就是本扩展的用武之地。

安装

# npm（推荐）
pi install npm:@everyx/pi-subagent

# git
pi install git:github.com/everyx/pi-subagent

开发期软链接：

ln -sf /path/to/pi-subagent ~/.pi/agent/extensions/subagent

重启 pi 后直接说"让子 agent 去…"。

工具

两个最小原语：

• Agent — spawn 一个隔离的 sub-agent：{ prompt, title, model?, thinking?, tools?, run_in_background? }。title（3-5 词，必填）作为工具头、通知卡片、widget 行和会话名的标识——对齐 Claude Code 的 description / Codex 的 task_name。前台（默认）阻塞到结果就绪；run_in_background: true 立即返回 agent_id，完成时投递携带最终输出的通知。
• AgentControl — 干预运行中的后台 agent：steer（注入重定向消息）或 stop（终止）。

LLM 通过 promptSnippet + promptGuidelines（系统提示注入）获得使用指南：何时委派、prompt 必须自包含、绝不轮询。

用法

发起一个任务

对 pi 说：

让一个子 agent 分析 src/ 下的认证逻辑

Pi 调用 Agent（前台），子 agent 隔离运行，结果返回。

后台并行跑多个

同时起三个子 agent 分别看 auth 模块、数据库层和 API 路由

Pi 调用三次 Agent（run_in_background: true）。每个完成通知携带对应 agent 的最终输出——无需轮询、无需额外的取结果工具。

干预运行中的 agent

那个数据层子 agent——方案行不通，改用组合式重写

Pi 调用 AgentControl 的 steer 重定向运行中的 agent。要停掉失控的 agent："干掉那个后台子 agent" → stop。

进阶

指定模型

用 claude-sonnet 起一个子 agent 分析数据库设计

不指定模型 → 继承当前会话模型。指定但注册表中找不到 → 报错，不静默降级。thinking 同理：省略时继承当前推理强度，传 "off"…"max" 可覆盖。

限制工具

让子 agent 调研项目结构，但只允许用 read 和 grep

子 agent 看不到其他任何工具。只读探索 + 便宜模型是调研任务的推荐模式。

工作原理

每个 sub-agent 都是带持久化 session 的常驻 pi --mode rpc 子进程：

• 前台 — Agent 等待子进程 settled，取最终输出，然后关闭 stdin（优雅退出）。
• 后台 — Agent 立即返回；agent_settled 时扩展投递 subagent-notification（JSON 内容给 LLM、渲染卡片给用户），子进程优雅退出。
• Steer/stop — AgentControl.steer 向子进程 stdin 写 steer 命令（在当前 turn settled 后投递）；stop 关闭 stdin 优雅退出。
• Attach / 复盘 — sub-agent 会话存储在 <agent 目录>/subagent-sessions/（默认 ~/.pi/agent/subagent-sessions/；可用 PI_SUBAGENT_SESSION_DIR 覆盖，agent 目录同样尊重 PI_CODING_AGENT_DIR，与 pi 一致），刻意放在 pi 标准会话树之外，让 pi -r 保持干净。永不删除。要 resume/复盘：在主会话里找到 session 路径（Agent 调用结果或完成通知卡片），执行 pi --session <path>——通知里也带 path，直接问 LLM 也行。
• Graceful turn limits（默认不限，opt-in） — 不对子 agent 施加隐藏 deadline；可选 timeoutMs 参数（Codex 的 timeout_ms 风格）。不做 token 限制——用量仅通知卡统计。

嵌套 sub-agent

Sub-agent 是完整 pi 实例，若你全局安装了本扩展，它天然能再 spawn sub-agent——嵌套开箱即用，不做深度控制。每一层都是独立进程、独立上下文，嵌套深度会倍增启动时间和 token 成本。是否值得嵌套由你（或模型）判断。

成本与注意

• Headless（pi -p）下后台 agent 随主进程退出。 主 agent 响应结束即进程退出，后台子 agent 通过 stdin EOF 被清理（不会泄漏为孤儿进程）。后台工作流（等通知、steer、stop）是为常驻的 TUI 会话设计的。
• 一 agent 一进程。 前台和后台都是常驻 rpc 子进程。后台开多了 = 进程开多了——请节制。
• 通知一次性投递。 后台结果只投递一次；若投递前主会话崩溃，结果只存在于 session 文件（用 pi --session <path> attach 恢复）。
• Steer 需要活的 agent。 AgentControl 只在 agent 运行中（完成通知之前）有效。

清理

pi 退出时，运行中的 sub-agent 收到优雅的 stdin-EOF 关闭。session 保留在磁盘供 attach/复盘；不 kill、不删除。