English | 简体中文

Pi Subagent

基于官方 Pi SDK 的子 Agent 扩展：创建独立会话、观察执行、追加消息或停止任务。支持前台结果返回与后台完成通知。

使用官方包 @earendil-works/pi-coding-agent，当前验证基线为 1.0.0。需要 Node.js 22.19+。

使用

三个工具统一注册为 exposure: "deferred"，不默认向模型暴露定义；通过 tool_search 按需发现、加载。插件仍正常初始化。这不要求将 subagent 工具加入 defaultTools；需保持 tool_search 可用。

// 异步派发，执行结束后通知当前主会话。
subagent_start({
  task: "只读检查 src/cart.js 和 test/cart.test.js，报告缺陷、证据和缺失测试，不修改文件。",
  name: "审查", mode: "background"
})

subagent_observe({ id: "返回的子会话 ID" }) // 立即返回
subagent_observe({ id: "...", timeoutSeconds: 60 }) // 等本轮结束，最多 60 秒

// running：steer 受理后返回；idle：沿用创建时的 mode 开始下一轮。
subagent_send({ id: "...", action: "message", message: "重点检查 quantity=0，不得当作缺省值。" })

subagent_send({ id: "...", action: "stop" })

• start：必填 task，应包含必要背景、限制和完成依据；可选 name（同时写入 Pi 会话标题；不传时保留界面从首条消息生成的标题）、cwd（相对主项目或绝对路径）、model（provider/modelId）。默认当前项目、主 Agent 模型；mode 为 foreground / background（默认），创建时固定为会话属性，后续不可切换。
• send：必填 id/action；message 动作必填 message；stop 不接受消息。没有 start.notify 或 send.mode 参数，也没有 silent 模式。
• observe：不传 ID 列出当前主会话所有子任务；默认截取最近 assistant 正文前 2000 字符。用 detail: "output" 获取最多 16000 字符，offset/limit 分页，单次上限 32000。nextOffset 非 null 时还有内容。

timeoutSeconds 默认 0；大于 0 时必须指定 id，上限由 manager.mjs 的 OBSERVE_MAX_TIMEOUT_SECONDS = 240 统一配置，工具 schema 与运行时校验共用。单任务观察返回 timedOut；到期返回当前快照，不停止子任务。取消观察同样不停止子任务。等待使用结束事件与单个定时器，不轮询。

工具返回正文为纯 JSON，并同时提供 structuredContent；结束通知也是纯 JSON，额外带 event: "subagent_run_ended"，不混入自然语言前缀。字段示例（省略其余字段）：

{
  "status": "idle",
  "lastRunOutcome": "ended",
  "lastRunStopReason": "length",
  "lastOutput": "当前输出……"
}

这表示当前未执行、上一轮达到输出上限，不表示任务已完成。

只有两种状态：

• running：包括模型执行、工具调用、自动重试、压缩和已接受的排队指令。
• idle：当前没有执行，不保证用户目标已经达成。

其他信息不作为状态：

| 字段 | 含义 | | --- | --- | | mode | 创建时固定的 foreground / background，决定 idle 续发的等待方式及每轮通知 | | lastOutput | 最近 assistant 正文；流式执行时可能只是部分内容，不含思考或工具日志 | | lastOutputRun / run | 输出来源轮次 / 当前轮次；新一轮尚未输出时，可能显示旧输出 | | lastOutputAt | 最近正文更新时间 | | lastActivity | 最近正文或工具活动 | | queuedMessages | SDK 尚未消费的排队消息数，不是“要求已完成”的确认 | | lastRunOutcome / lastRun | 最近结束的一轮及结果：ended / failed / stopped | | lastRunStopReason | 模型实际结束原因，例如 stop、length、error、aborted；length 表示模型输出达到上限 | | error | 最近运行错误；工具返回 isError 则表示调用自身未受理 | | stopRequested | 已请求停止；仍 running 时不能假定工具或外部进程已结束 | | sessionFile | 子会话完整 JSONL 记录，可供排查 |

run 记录一次连续执行区间，而非模型底层 turn 数或每次 UI 提交：工具提交从受理开始，外部 SDK 调用从可观察的 agent_start 开始，均到执行收束结束。期间加入的消息、收束前紧邻的续跑属于同一轮。SDK 手动压缩可以显示 running，但不额外增加业务轮次。

子 Agent 输出问题后正常结束也只是 idle。主 Agent 查看文本，自行判断是否通过 message 回答、追加要求或收取结果；没有 ask、reply、等待回复状态或文本分类器。

等待与通知

| 操作 | foreground 会话 | background 会话（默认） | | --- | --- | --- | | start | 等待本轮收束后返回 | 受理后返回 | | idle 时 send(message) | 等待新一轮收束后返回 | 受理后返回 | | running 时 send(message) | steer 受理后返回，不等待本轮 | steer 受理后返回，不等待本轮 | | 每轮结束通知 | 不通知父会话 | 有等待观察者则通过观察返回，否则主动通知父会话 |

• running 消息使用 SDK prompt(..., { streamingBehavior: 'steer' })，不改变会话 mode。受理不代表消息已执行或任务已完成；需等结果或查询状态。
• 每轮真正收束统一走 finish；等待观察在收束时直接收到结果，避免重复后台通知。立即观察、超时或取消不抑制后续后台通知；stop 不改变交付，关闭会话的资源清理仍抑制通知。
• 插件通过 Pi sendMessage(..., { deliverAs: 'steer', triggerTurn: true }) 交付结束事件：主 Agent 忙时在 SDK 可处理边界进入，空闲时唤醒。不依赖子模型调用通知工具。
• 前台启动或 idle 续发的等待调用取消时请求停止子任务；后台受理后及 running 消息受理后，不把已返回调用的取消信号绑定到子执行。
• 通知是进程内尽力交付，没有重启恢复和严格 exactly-once 保证；Pi API 的异步投递失败由 Pi 报告。可以随时通过 observe 取回结果。

停止不撤销文件修改，不删除已有上下文。停止后改变目标，应明确说明“旧任务已取消，接下来做……”。主模型仍需核对输出，不能把 ended 当成业务成功。

运行边界

• 本工具每个主会话最多受理 16 个并行子会话、保留 1024 个子会话。状态结合内存记录与 SDK 状态，查询不扫描磁盘或解析历史。
• 子会话只启用 read/bash/edit/write；加载目标项目的规则和本地发现的 Skills，不复制主会话聊天历史。
• 不加载主 Agent 的扩展、包资源、MCP 或通知工具，不自动注册递归派发工具。仅支持本机模型配置可解析的模型，不继承仅由主扩展临时注册的模型。
• 不是安全沙箱：共享文件系统、进程权限和模型服务；不继承主会话扩展提供的确认/权限钩子。“只读”是任务约束，不是强制文件权限。并行写任务必须划分文件范围。需要依靠扩展强制审批的项目不应直接使用此默认工具集。
• 默认不跨主会话共享任务。切换、分叉、关闭会话时取消子执行并释放资源；5 秒内未确认停止则保留 running，切换/分叉会被取消，可稍后重试。
• 子会话记录使用 Pi 默认目录 ~/.pi/agent/sessions/<工作目录分组>/（遵循 PI_CODING_AGENT_DIR），与普通会话相同，保留父会话关联，默认会话列表和 pi-snap 可直接发现。进程退出后不恢复后台执行或任务 ID。
• 模型服务只有一个推理 slot 时，多个 Agent 请求仍可能由服务端串行处理；后台执行不等于 GPU 并行推理。

会话发现与状态归属

子会话使用官方 SDK 默认的会话文件布局和父会话关联，供 Pi 会话列表或 pi-snap 发现。列表发现不等于接管执行：运行状态、消息、取消和结果交付由本扩展管理。

不注册 WebUI 共享 SDK 实例或主会话保活接口，不向上游交付运行时状态。上游如何刷新文件列表不属于本扩展职责。不要同时从其他进程恢复一个仍由本扩展执行的会话。

安装

从 npm 安装：

pi install npm:@arkkwang/pi-subagent

也可以克隆仓库后，在仓库目录内安装本地包：

pi install .

重启 Pi 后加载扩展。无独立 CLI、常驻服务或第二份 Pi SDK；SDK 由 Pi 扩展加载器提供。三个工具按需暴露，主 Agent 使用前需通过 tool_search 发现。

验证

npm ci
npm test
# 完整集成测试：实际 SDK + 本地模拟 HTTP 模型，不调用外部模型。
PI_SDK_ENTRY=/absolute/path/to/pi/dist/index.js npm test
PI_SDK_ENTRY=/absolute/path/to/pi/dist/index.js node test/benchmark.mjs

未设置 PI_SDK_ENTRY 时跳过真实 SDK 测试。test/local-smoke.mjs 是需要显式授权的真实本地模型演练，不包含在默认测试中。

Windows Git Bash / Node 22.23.2 / 官方 Pi 1.0.0 为本次验证环境；macOS/Linux 和其他 Pi 版本尚未实测。性能脚本对照带/不带扩展的资源加载，并测量大输出状态查询；不代表完整冷启动或模型推理耗时。

相关项目

• pi-cron：定时执行 Agent 任务。
• pi-snap：帮助人和 Agent 快速定位会话问题。

License

MIT