pi-subagents

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

功能

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

模型分层

除了直接写模型 ID，还可以在 subagents.json 中把能力档位映射到真实模型。映射会生成 subagent 工具的 prompt guidelines，告诉代理每个档位应通过 model 参数传哪个模型—— 不存在 model_tier 工具参数。

档位	定位
fast	最便宜、最快，能力最弱（flash / mini / haiku 级）
standard	均衡的默认档（sonnet 级）
advanced	能力最强、最贵（opus 级）

映射写在 subagents.json：全局 ~/.pi/agent/subagents.json，项目 <cwd>/.pi/subagents.json。 两层按档位合并，项目只改一档时无需重复其余档位：

{
  "modelTiers": {
    "fast": "deepseek-flash",
    "standard": "deepseek-flash",
    "advanced": "qwen3.8-max"
  }
}

代理会把映射值复制到 model，因此与普通 model 值走同一套解析：provider/modelId 与 模糊名称（如 "haiku"）都可以。未配置的档位不会出现在提示里——不会有其他模型被静默 顶替。若代理类型的 frontmatter 固定了 model，该模型始终优先。

命令

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

会话查看器以只读方式复用 Pi 自身的逐条消息组件渲染会话记录，并实时跟随运行中的代理。 工具结果按 Pi 的折叠形态显示（摘要与预览），因此 read 调用只显示其调用行。 查看器没有展开键，部分工具调用行里提示的"to expand"键在此不适用。

查看器跟随实时尾部：未滚动时最新行始终贴在底部。向上键（↑/k、PgUp/shift+up、Home）会 无条件暂停跟随 —— 流式输出可能在按键与渲染之间新增行，用那个已经过期的值去判断"我是不是在底部" 会把刚刚离开的视口又拽回底部。向下键落到底部（↓/j、PgDn/shift+down）即恢复跟随，end 直接跳到底部并强制恢复；q/Esc 关闭。暂停状态没有可视指示（footer 始终显示 <n> lines · <pct>% 与键位提示）。

并发控制

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

持久化设置

通过 /subagents:settings 设置的参数持久化到 <cwd>/.pi/subagents.json（项目级），也可在 ~/.pi/agent/subagents.json 中设置全局默认值。同一批文件也保存 modelTiers 映射；保存其他设置时会保留它。

事件

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

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

开发

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

致谢

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

许可证

MIT