# @ferris1225/pi-subagents 中文文档

规范地址：https://npmcn.com/package/%40ferris1225/pi-subagents/

版本：6\.0\.5
npm 元数据更新时间：2026-11-04T03:05:14.589Z
中文译文更新时间：2026-11-14T14:52:45.867Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ferris1225/pi-subagents
原文对照：https://npmcn.com/package/%40ferris1225/pi-subagents/?lang=original
项目主页：https://github.com/MCapricorns/pi-subagents#readme
源码仓库：https://github.com/MCapricorns/pi-subagents

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：425 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：0 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \>=1\.5\.0，@earendil-works/pi-tui \>=1\.5\.0，@earendil-works/pi-coding-agent \>=1\.5\.0
- 首次发布：2026-08-02T00:55:37.250Z
- 最新版本发布：2026-11-04T03:05:14.211Z
- 近 30 天下载量：4913（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：124（近 12 个月 124 个）

## 中文简介

Pi管理的子代理团队:研究,执行,独立审查,互动后续,和Git工作树隔离.

## 安装

```sh
npm install @ferris1225/pi-subagents
```

也可以使用：`pnpm add @ferris1225/pi-subagents`、`yarn add @ferris1225/pi-subagents`、`bun add @ferris1225/pi-subagents`

## README

# 亲水师

用于 [Pi](https://github.com/earendil-works/pi):研究、执行、, 独立审查,互动跟进,和Git工作树隔离.

## 安装

要求数 **Pi 1.5.0** 财务报告和审定财务报表 **节点.js**发展与土著 集成测试采用Pi 1.5.0 SDK.

```bash
pi install npm:@ferris1225/pi-subagents
```

运行 `/subagents-setup` 打开独立的中心模式面板,而不是 将菜单挤入输入编辑器码头。 宽面板放置角色登记册 和焦点角色的并排设置; 窄面板堆叠它们 。 @% /% 改变角色, \\\\\\\\\\\\\\ 选择 **型号**, (中文(简体) ), **思考**,或 **重设**输入 在一个可搜索的模式拾取器中编辑它。 选中的角色显示其完整的模式 参考、有效推理级别、夹住时要求的级别,以及 默认/ 覆盖源 。 每个选择立即保存; Esc 不返回 应用拾取器选择并保持焦点。 模式采取者支持搜索, 贴相并呼. 在短终端上,PgUp/PgDn滚动设置,同时 选择的角色和现场保持固定 .

所有角色默认遵循主模式;思维默认为 `low` 侦察兵 财务报告和审定财务报表 `high` 为工匠和哨兵。 面板区分默认值与覆被和 显示模型能力夹住偏好时的有效级别。 变化 一个模型保留了思维偏好。 设置在 `~/.pi/agent/pi-subagents.json` 作为 `agentModels` 财务报告和审定财务报表 `agentThinkingLevels`。 。 。 . 会话开始删除一个没有认证的提供者要约的模型 ; 保留会话模型范围外的覆盖并只跳过 并引导会话.

## 探员

| 探员 | 用于 | 访问 |
| --- | --- | --- |
| `scout` | 代码、文件和引文网络研究 | 只读工具; 没有命令或编辑 |
| `artisan` | 实施和通过测试和检查修正 | 父工具表面, 包括代码 |
| `sentinel` | 检查执行情况或对缺陷和回归的索赔或假设提出质疑 | 父工具表面; 指示不要编辑 |

主模型从这些角色描述中选择;单是名称不会路由 a 任务。 使用 `sentinel` 检查执行情况/进展或质疑具体索赔 或带有反例和重点检查的假设.

哨兵可能进行重点检查,所以它的无编辑边界是一个指令,而不是 工具强制限制。 改革审查侧重于引入的缺陷;范围更广 审计需要一份明确的简介。 所有角色重新利用现有事实和有效检查, 填补空白,而不是重复主要或上游工作.

仅 `scout`, (中文(简体) ), `artisan`,以及 `sentinel` 是有效的运行时角色名. 现有模型/思维设置和运行中断的记录在负载时迁移 (单位:千美元)`reviewer`, (中文(简体) ), `critic`,以及 `skeptic` 地图到 `sentinel`并用 当前名称。 在当前名称下明确有效的设置胜出 。 自定义角色 不支持。 留存的旧释放记录仍可供取回.

儿童接受自足的简要说明和项目指导,但没有父母 谈话 他们不能授权或释放。 主要拥有规划,整合, 和最终结果。 保持一个固定和它的回归测试 一个所有者.

## 代表

Pi 主动寻找有用的限定阶段来授权; 没有特别请求 需要时间。 重点自主权、孤立的背景、平行进展和 独立检查可以证明每个孩子是合理的。 实质性的自足固定可以 去一个工匠 及其回归测试, 即使没有 以平行方式进行。 快速源码检查和小理解编辑主要停留. 从独立的工作中选择团队大小. 主要工作或 避免亚剂优先.

每个交付品使用一个所有者,包括其回归测试. 向儿童介绍情况 与结果、完成的条件、相关路径、既定证据、书写 边界,需要检查,以及紧凑的预期结果。 童子军检索 源; 手工业工具, 而哨兵可以执行重点检查。 这项政策采用上下文隔离, 重点作用和协调成本指导 [编码子剂](https://developers.openai.com/codex/subagents) 财务报告和审定财务报表 [克劳德密码子剂](https://code.claude.com/docs/en/sub-agents) 给Pi的文档 一发叶跑起.

审查请求产生结果。 更改时的主要应用修正 只有在重大不确定性时才予以核准和要求重点确认 遗体。 在报告成功之前,主要检查都完成了条件和任何 在孩子的回答和综合的diff.

请 Pi 明确授权, 或者直接调用工具 :

```ts
subagent({
  agent: "artisan",
  task: "Fix cache invalidation in src/cache, add regression tests, and run the checks.",
});
```

独立的任务可以一起运行:

```ts
subagent({
  tasks: [
    {
      agent: "artisan",
      task: "Fix config validation and its regression tests.",
    },
    {
      agent: "artisan",
      task: "Update docs/providers.md from the established API citations.",
    },
  ],
});
```

使用 `wait: true` 当下一步需要结果时. `subagent` 并完成运行 `subagent_message` 后续默认在一发中等待 `pi -p` /JSON会议, 所以,家长要活到工作结束 TUI 和 RPC 会话默认 提供背景资料; `wait: false` 明确选择任何模式。 每个 结果在集成后在等待工具呼叫中或 作为背景完成。 等待失败是保留证据的工具错误. 超过40行或8 000个字符的答案没有内含;其交付 指定全部结果文件.

一份发射收据仅确认代表团,并列出每个开始运行的ID。 主要 继续独立工作或暂停工作,直到完成,然后 完成所要求的结果和最后检查。 它不投票或治疗 成功发射作为任务完成. 相同的 cwd 中相同的正态任务在活动时被拒绝为重复 或在本届会议上解决。 重用结果或使用 `subagent_message` 用于一个额外的有界限的步骤.

## 状况、取消和追回

| 工具 | 使用 |
| --- | --- |
| `subagent_status({ id: 12 })` | 检查运行进度、结果和恢复路径 |
| `subagent_message({ id: 12, message: "Check the caller too" })` | 引导一个运行中的孩子,或者继续完成运行,在有其会话时使用其会话和其他摘要 |
| `subagent_message({ id: 12, message: "Add the test", context: "summary" })` | 启动下一个新步骤, 只需对先前运行进行限定摘要 |
| `subagent_stop({ id: "12" })` | 停止运行并退出保留会话 |
| `subagent_stop({ all: true })` | 在此会话中停止所有活动运行 |

部件是一个终端任务板, 封顶在10行: 静静的概览, 然后 右侧带有状态/时间的任务行。 失败在可选位置前获得空间 遥测;狭长的终端保持任务身份可见. 模型,思维,符号 使用和工作树状态作为次要细节出现。 工作失败一直持续到 下一个任务。 完成信息和状态检查保留了结果. 重叠报告隐藏任务 。 正在准备其子进程显示 `starting`。 。 。 . 刷新定时器只在可见活性工作需要时运行. 没有 进程计数限制或共享检查出启动锁定:独立运行启动 包括单独发送电话,而另一个电话则等待结果.

通常省略 `isolation`: 执行任务使用分离的 Git 工作树 单次呼叫和平行批次。 阅读和审查使用当前目录. 没有 Git 仓库或承诺 `HEAD`,自动隔离使用 来电目录和报告原因 意外设置或集成失败 仍然是失败; 明确 `isolation: "worktree"` 需要隔离 永远不要 掉头. `isolation: "shared"` 对于需要完成的任务来说,是高级的覆盖 直接写在打电话者的离职单上.

每个工作树都从呼叫者的当前跟踪文件开始 并且没有污名化 未跟踪文件,包括未承诺的更改 。 它的最初的快照也是 集成基础,因此依赖性任务可以看到更早的结果而无需重新应用. 打电话者的指数,分支,和 `HEAD` 保持不变。 孩子被告知 原始的检出及其工作树路径, 因此它将路径从简介映射到 工作树。 Worktrees 隔离 Git 更改,而非工具权限 。 独立任务 一起开始; 只有工作树的最后应用更改为原始 离职是连载的. 整合使你的指数没有受到影响,失败保留了回收文物.

取消父运行 Escape 停止未完成的工作而不唤醒 亲子关系。 在下个用户转弯时提供注销收据 运行 ids,所以主机知道没有额外的 `subagent_stop` 这是需要的。 已取消的工作 不可自动重新启动。 对话- 树木导航也停止 尚未完成的工作。 新的/再生/叉/再装填结束年老子女并保留中断 手工回收工作。 运行不自动恢复; 主完成 部分改动和文物的不完全的作品.

引导呼叫等待孩子的 RPC 频道确认 匹配请求ID。 工具卡显示 **已经收到** 当皮确认 队列中, **已处理** 当一个输入钩子消耗信件时,或 **接受... 队列状态未确认** 在无法处置的情况下. `subagent_status` 保留最新的识别、请求身份、年龄和信件 总结。 拒绝或缺失确认是一个错误,而不是收据. 排队在 Pi 方向盘边界上交付;不能证明模型 已经执行指令.

要继续成功完成运行,请选择适合后续的上下文:

-   `context: "auto"` (默认)继续保留会话的私人副本 当可用时。 如果清理已删除, 后续从一个界限开始 简要和明确地报告说,没有完整的历史。 没有重试 用于过期会话.
-   `context: "session"` 需要完整的历史来重修之前的工作 细节。 如果会话不可用, 调用失败而不启动运行 .
-   `context: "summary"` 总是开始新的下一步, 与早期 客观、最终结果和被触碰的文件。 它不能依赖省略的细节 或重用早先的提供者缓存.

会话续作保留了先前的历史和提供者即时缓存键 (单位:千美元)`sessionId`) (中文(简体) ). 他们的私人副本 绑在新运行的工作目录, 包括之前的临时工作树已被移除。 儿童 启动和复制的会话头使用相同的物理目录, 所以 macOS 路径化名和 Windows 界面不会触发跨项目叉提示. 续作被指示在编辑当前 cwd 的文件前重新阅读.

每一个后续行动都维护作用和工作空间,并经过正常的工作 招生和隔离. 设定 `wait: true` 获得最终结果 调用; 此等待选项适用于新开始的后继工作, 而引导 a 正在运行的孩子返回其确认. `subagent_status` 是否报告a 已完成的运行有可用的会话,或者只有摘要上下文。 成果和摘要保持不变 在当前父运行时间中可用; 未恢复已完成运行 重新装入后。 无法引导等待运行.

孩子们用的是皮的土生土长 `--mode rpc` 具有管式输入/输出、回转和 会期持续。 在 Windows 上, 隐藏控制台覆盖 Pi 孩子和节点 其工具和扩展程序,包括: `pi.exec`, (中文(简体) ), `pwsh`, (中文(简体) ), 财务报告和审定财务报表 `powershell`。孩子在 Pi 开始并通过它之前会预先加载此政策 通过 `NODE_OPTIONS`,保留现有选项。 一个 为没有节点的运行时间安装相同的策略 预装。 Windows的发射会保持连接,所以分解无法打开控制台. 在 macOS 和 Linux 上, 策略保留 shell 选项不变; Pi 子使用 用于取消的单独的处理组,而不启动终端应用程序. RPC通讯和进程树取消活动仍然活跃. 儿童启动 错误报告为运行失败 。 如果 Windows 不能启动 `taskkill`, (中文(简体) ), 终止会直接杀死儿童。 明确命令 打开终端或图形界面控制自己的窗口. 解决的供应商故障可以在同一模式中一次交给主型号 届会。 国家档案和全面成果档案 `~/.pi/agent/ferris-pi-subagents/`按项目分组. `PI_CODING_AGENT_DIR` 覆盖代理目录.

## Pi 代码兼容性

打电话 `subagent` 和直接控制工具。 他们用Pi的 `model-only` 接触和故意不作为巢穴 `tools.subagent(...)` 电话 在代码中。 孩子们仍然可以使用代号 和他们继承的可调用 工具。 间接工具保留其曝光率;侦察员促进核准的只读 直接使用的工具。 它等待最多10秒的启动注册和 在转弯之间激活后到达。 只读分类使用 Pi 工具 元数据.

需要确认、选择或文本输入的儿童 RPC 对话框是 取消了匹配的回复和解释, 所以一个无人照顾的孩子 不挂等隐形对话框。 不核准确认 自动.

## 储存和清理

每个项目根都持有 `sessions/`, (中文(简体) ), `worktrees/`, (中文(简体) ), `tmp/` 财务报告和审定财务报表 `results/`启动 卫生已经减少 临时剩余, 艺术品的Pi过程已经消失,结果 文件通过保存窗口,项目根闲置三天。 已停放 在这些扫荡过程中保护恢复工作和明显参考. 在没有记录的所有人或儿童30天后,中断的检查站将失效 从当前靴子活下来;过期的检查站在恢复前被挤出. 缺少会话文件不会擦去已验证的恢复路径 。 无法读取或 货物清单不整齐,无法自动回收; 明确的清理报告错误。 启动警告回收检查失败 并继续初始化进度部件.

回收是自动的:一个定居点可能会引发一次步入的扫荡(大多数情况下每一次) 5分钟),将死主的文物,过期的结果文件,并结算 超过30分钟的会话副本,然后修剪最老的已解决会话 直到项目符合1.5GB的预算。 在预算压力下,会议安排 超过5分钟可被取出。 现场直播、停放的恢复工作,以及 明显参考文献仍然受到保护。 自动后续使用保留 完成运行记录已过期时的摘要。 会话关闭等待 防止新的定居点扫荡.

`/subagents-cleanup` 立即收回无人认领的死尸和闲置文物 项目根、报告使用和释放字节. `/subagents-cleanup dry-run` 措施,而不删除任何内容; 任何其他论点均在不删除的情况下被驳回 删除。 开庭年龄和开垦预算在结算时自动运行.

## 发展

运行时代码 : `src/`; 软件包没有技能和工作流程资源 目录. 内建提示随着代码及其测试而改变.

| 模块 | 责任 |
| --- | --- |
| `delegation/` | 内建角色,父路径快捷,重复发送录用 |
| `configuration/` | 模型和思维设置,加上独立的设置模式面板 |
| `presentation/` | 运行任务委员会、活动、状况和结果格式 |
| `execution/`, (中文(简体) ), `lifecycle/`, (中文(简体) ), `isolation/` | 儿童过程、持久状态、取消、工作树木和恢复 |

```bash
npm ci
npm run check
```

将未发布的软件包版本推向 `main` 运行 Windows 的检查, macOS 和 Linux 启动前 [发布和 GitHub 发布](https://npmcn.com/package/%40ferris1225/pi-subagents/.github/workflows/publish.yml)。 。 。 .

[更改日志](https://npmcn.com/package/%40ferris1225/pi-subagents/CHANGELOG.md) • 妇女 [麻省理工学院许可证](https://npmcn.com/package/%40ferris1225/pi-subagents/LICENSE)

## 常见问题

### @ferris1225/pi-subagents 是什么？

Pi管理的子代理团队:研究,执行,独立审查,互动后续,和Git工作树隔离\.

### 如何安装 @ferris1225/pi-subagents？

在项目目录运行 npm install @ferris1225/pi-subagents，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\*）、@earendil-works/pi-ai（\>=1\.5\.0）、@earendil-works/pi-tui（\>=1\.5\.0）、@earendil-works/pi-coding-agent（\>=1\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ferris1225/pi-subagents 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ferris1225\_\_pi-subagents 是否存在。

### @ferris1225/pi-subagents 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ferris1225/pi-subagents 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ferris1225/pi-subagents 可以商用吗？

@ferris1225/pi-subagents 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ferris1225/pi-subagents 的下载量有多少？

根据 npm 官方下载统计，@ferris1225/pi-subagents 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,913 次，日均约 164 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ferris1225/pi-subagents 还在维护吗？

最新版本 6\.0\.5 发布于 2026/11/04（10 天前）；至今共发布 124 个版本，其中过去 12 个月发布了 124 个；首次发布于 2026/08/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。