pi-subagents

Pi 扩展，提供聚焦的进程内子代理核心——在同一 pi 运行时内运行的自主代理（无需生成子进程），外加类型化 API 和生命周期事件供其他扩展构建。

功能

• 进程内原生 — 代理共享同一 pi 运行时：相同的工具名、调用约定和 UI 模式
• 并行后台代理 — 同时启动多个代理，自动排队（可配置并发数，默认 4）
• 实时 Widget UI — 持久化的编辑器上方组件，带动态旋转指示器、实时工具活动、token 计数和彩色状态图标
• 自定义代理类型 — 在 .pi/agents/<name>.md 中通过 YAML frontmatter 定义：系统提示词、模型、思考等级、工具限制
• 运行中转向 — 向运行中的代理注入消息，无需重启即可改变工作方向
• 会话恢复 — 从上次中断处继续，保留完整对话上下文
• 优雅轮次限制 — 代理在硬中止前收到"收尾"警告
• 大小写不敏感 — "explore"、"Explore"、"EXPLORE" 均可
• 模糊模型选择 — 按名称（"haiku"、"sonnet"）而非完整 ID 指定模型
• 上下文继承 — 可选择将父对话分叉给子代理
• 风格化通知 — 后台结果渲染为主题化通知框
• 事件总线 — 通过 pi.events 发出生命周期事件（subagents:created、started、completed、failed、steered、compacted）

安装

pi install npm:@yandy0725/pi-subagents

快速开始

父代理使用 subagent 工具启动子代理：

subagent({
  subagent_type: "Explore",
  prompt: "Find all files that handle authentication",
  description: "Find auth files",
  run_in_background: true,
})

前台代理阻塞直到完成。后台代理立即返回 ID，完成后通知。

默认代理类型

| 类型 | 工具 | 模型 | 描述 | |------|------|------|------| | general-purpose | 全部 | 继承父级 | 完整父级系统提示词——相同规则、相同约定 | | Explore | read, bash, grep, find, ls | haiku（回退：继承） | 快速代码库探索（只读） |

自定义代理

在 .pi/agents/<name>.md 中创建 .md 文件定义自定义代理类型：

---
description: 安全代码审查
tools: read, grep, find, bash
model: anthropic/claude-opus-4-6
thinking: high
max_turns: 30
---

你是一名安全审计员。审查代码漏洞...

代理从 .pi/agents/<name>.md（项目级）和 ~/.pi/agent/agents/<name>.md（全局）发现。项目级覆盖全局。

工具

subagent

启动子代理。

| 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | prompt | string | 是 | 代理要执行的任务 | | description | string | 是 | 3-5 词简短描述（UI 中显示） | | subagent_type | string | 是 | 代理类型（内置或自定义） | | model | string | 否 | 模型覆盖（provider/modelId 或模糊名称） | | thinking | string | 否 | off / minimal / low / medium / high / xhigh | | max_turns | number | 否 | 最大代理轮次（默认无限制） | | run_in_background | boolean | 否 | 后台运行不阻塞 | | resume | string | 否 | 恢复之前会话的代理 ID | | inherit_context | boolean | 否 | 将父对话分叉给子代理 |

get_subagent_result

检查后台代理的状态并获取结果。

| 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | agent_id | string | 是 | 要检查的代理 ID | | wait | boolean | 否 | 等待完成 | | verbose | boolean | 否 | 包含完整对话日志 |

steer_subagent

向运行中的代理发送转向消息。

| 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | agent_id | string | 是 | 要转向的代理 ID | | message | string | 是 | 注入代理对话的消息 |

命令

| 命令 | 描述 | |------|------| | /subagents:settings | 配置并发数、轮次限制 | | /subagents:sessions | 查看子代理的会话记录 |

并发控制

后台代理受可配置并发限制约束（默认 4）。超出限制的代理自动排队。前台代理绕过队列。

持久化设置

通过 /subagents:settings 设置的参数持久化到 <cwd>/.pi/subagents.json（项目级），也可在 ~/.pi/agent/subagents.json 中设置全局默认值。

事件

通过 pi.events 发出的生命周期事件，供其他扩展消费：

| 事件 | 触发时机 | |------|----------| | subagents:created | 后台代理已注册 | | subagents:started | 代理转入运行状态 | | subagents:completed | 代理成功完成 | | subagents:failed | 代理出错/停止/中止 | | subagents:steered | 转向消息已发送 | | subagents:compacted | 代理会话已压缩 | | subagents:settings_loaded | 持久化设置已应用 | | subagents:settings_changed | 设置变更已生效 |

权限系统集成

当安装了 @yandy0725/pi-permission-system 时，本包自动集成：

• 通过 YAML frontmatter 为各代理类型设置权限策略
• Agent 启动前过滤工具
• ask 状态从子代理转发到父级 UI

开发

npm run typecheck        # tsc --noEmit
npm run lint             # biome lint
npm test                 # vitest run

致谢

本项目是 @gotgenes/pi-subagents（作者 Chris Lasher）的友好分支，后者源自 tintinweb/pi-subagents。感谢所有原作者的工作使本包成为可能。

许可证

MIT