# @tintinweb/pi-subagents

English · 简体中文 · 日本語 · 한국어

> 本文是英文 README 的部分翻译(机器翻译,欢迎指正),仅包含简介、功能、安装、快速开始和 `/agents` 命令。UI、自定义代理、工具参数、设置与默认值、事件、RPC 等其余内容仅提供英文版:[完整英文 README](README.md)。 > > *Partial translation of the English README. Full reference: [README.md](README.md) · https://github.com/tintinweb/pi-subagents/blob/master/README.md*

@tintinweb/pi-subagents

npm 版本 npm 下载量 CI 许可证:MIT

需要 pi >= 1.1.0 pi.dev 包 兼容 Claude Code 最近提交

为 pi 提供 Claude Code 风格的子代理与工作流编排。

安装 · 快速开始 · UI (EN) · 自定义代理 (EN) · 工具 (EN) · 设置 (EN) · 工作流 (EN) · 更新日志 (EN)

pi install npm:@tintinweb/pi-subagents

一个 [pi](https://pi.dev) 扩展,为 pi 带来 **Claude Code 风格的自主子代理与工作流编排**。启动在独立会话中运行的专用代理,每个代理都有自己的工具、系统提示词、模型和思考级别。你可以让它们在后台运行(默认),也可以阻塞等待;可以在运行中引导它们、恢复已完成的会话,还可以定义自己的代理类型。当编排不应临场发挥时,可以把一段确定性的 JavaScript 脚本交给 `SubagentWorkflow` 工具(`agent()`、`parallel()`、`pipeline()`),为 Claude Code 的 `Workflow` 工具编写的脚本也能在这里运行,只有少数[差异](https://github.com/tintinweb/pi-subagents/blob/master/docs/workflows.md#coming-from-claude-code)。 pi-subagents 截图 https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543 pi-color-badges-white ## 功能 - **与 Claude Code 一致的外观与体验**:相同的工具名、调用约定和 UI 模式(`Agent`、`get_subagent_result`、`steer_subagent`),用起来就像原生功能 - **并行后台代理**:启动多个并发运行的代理,自动排队(并发上限可配置,默认 10)。完成通知会在父代理的下一个边界送达;多个代理同时完成时,通知会一起送达 - **实时小组件 UI**:编辑器上方常驻的小组件,带动画加载指示、实时工具活动、token 计数和彩色状态图标。通过 `/agents → Settings → Widget` 配置:`all`(所有代理)、`background`(默认,隐藏前台运行的代理,因为它们已作为 `Agent` 工具结果内联显示)或 `off` - **FleetView**:在编辑器下方显示的 Claude Code 风格的可导航列表,包含 `main` 和所有正在运行的子代理(最早启动的排在最前)。在空提示符下按 `↓`(或 `←`)进入,`↑`/`↓` 移动选择,`Enter` 打开所选代理的实时自动更新对话,`Esc` 返回。已完成的代理会短暂保留后再移出列表;查看器在代理完成后仍保持打开,方便你阅读最终输出。通过 `/agents → Settings → Fleet view` 开关 - **对话查看器**:在 `/agents` 中选择任意代理,即可打开实时滚动的浮层,显示其完整对话(自动跟随新内容,向上滚动即暂停)。在 pi 的全屏模式下,它是一个无边框、占满整个终端、支持鼠标的查看器。按 `Enter` 打开输入框,输入内容后再按 `Enter` 发送,即可内联引导正在运行的代理(`Esc` 或提交空内容则返回)。这条消息会作为用户消息显示,并在代理当前的工具调用结束后调整其工作方向。在正在运行的前台 `Agent` 调用上按 `b`,可将该运行转到后台(参见[将前台代理转到后台](#将前台代理转到后台))。按 `x`(再按一次 `x` 确认)可停止仍在运行的代理;引导和停止同样适用于后台代理。工具调用的显示方式与 pi 自身的对话记录一致,使用代理会话中注册的渲染器:bash 调用显示命令和输出,`read` 显示行号,`edit` 显示 diff,扩展工具使用自己的渲染器,没有渲染器的工具则回退为显示参数和截断后的输出预览。`ctrl+o`(或 `app.tools.expand` 绑定的任意按键)可展开被折叠的工具输出。助手文本以 Markdown 渲染;按 `m` 可在关闭、仅助手、全部三种模式之间循环切换(参见 [Viewer markdown](README.md#persistent-settings)) - **自定义代理类型**:在 `.pi/agents/.md` 或 `.agents/agents/.md`(项目级)或全局位置定义代理,使用 YAML frontmatter:自定义系统提示词、模型选择、思考级别、工具限制,以及兼容 Claude Code 的彩色名称徽标 - **随包分发的代理**:pi 包可以在其 `package.json` 中用 `"pi": { "subagents": { "agents": ["./agents"] } }` 声明自己的子代理(以及工作流脚本),这样只需 `pi install` 即可完成全部配置:无需在每台机器或每次容器启动时把文件复制到 `.pi/agents/`。只读取 pi 实际安装的包(绝不读取 `node_modules`),包中定义的代理优先级低于你自己编写的所有代理,`/agents` 以只读方式显示它们,并提供 Eject 和 Disable。用 `packageAgents` / `packageWorkflows` 缩小范围或关闭此功能。**[完整指南](https://github.com/tintinweb/pi-subagents/blob/master/docs/packages.md)** - **嵌套子代理**:内置的 `general-purpose` 代理可以把任务委派给它自己的子代理,与 Claude Code 一致;`Explore` 和 `Plan` 不能委派,自定义代理需设置 `allowed_subagents` 才能开启。进行委派的代理会获得自己的 `Agent`、`get_subagent_result` 和 `steer_subagent` 工具(作用范围仅限它自己的子代理),嵌套深度从主会话起算有上限(默认 2)。它只能控制自己的子代理;它结束时,这些子代理会被停止,其对话记录和 token 开销也会汇总到它名下。该允许列表是一道权限边界:子代理使用自己的工具运行,因此要像选择 `tools:` 本身一样谨慎地选择它 - **代理提及**:子代理是一等公民:在提示符中输入 `@explore also check the RPC path`,这段话会发给该代理而不是主模型,且不会有任何内容进入聊天。同一种语法覆盖整个生命周期:在它运行时给它发消息,在它完成后恢复它,很久以后再从磁盘重新打开它的会话,或者在它从未运行过时启动它。提及一个未在运行的代理时,会通过一个不在界面上显示的克隆对话来启动它,因此它能获得 Claude Code 那种根据上下文编写的提示词和一次真正的 `Agent` 工具调用,同样不会有任何内容进入聊天;`direct` 模式则直接用你的文本启动它,完全不调用模型。编排者可以给代理设置 `name`,这样你就能用 `@auth-audit` 指代它,`steer_subagent`/`get_subagent_result` 也接受这类名称。`@` 会与 pi 的文件补全一起补全正在运行的代理、可恢复的代理和可启动的类型;`@main` 强制把文本发回主模型。通过 `/agents → Settings → Agent mentions` 开关 - **脚本化工作流**:`SubagentWorkflow` 工具运行一段确定性的 JavaScript 脚本来编排多个子代理:`agent()`、`parallel()`、`pipeline()`、`phase()`、`log()` 和 `args`,并用一个纯字面量的 `meta` 块声明各阶段。`pipeline()` 的各阶段之间没有屏障,因此一个条目可能已进入后面的阶段,而另一个还在第一阶段;`parallel()` 则不同,它会让所有较快的代理空等,直到最慢的那个完成。工作流在后台运行并显示实时卡片,可通过 `/agents → Workflows` 或在 FleetView 中选择该运行来查看。`agent()` 还接受 `gate: "npm test"`,通过运行一条命令(隔离时在其 worktree 中运行)来验证子代理,而不是询问另一个模型;`resume: "