# @gfgghgftgffg/pi-subagents-lean 中文文档

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

版本：0\.1\.21
npm 元数据更新时间：2026-11-14T02:34:47.338Z
中文译文更新时间：2026-11-16T07:25:35.746Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：65.7 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：1 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \>=1\.1\.0，@earendil-works/pi-tui \>=1\.1\.0，@earendil-works/pi-coding-agent \>=1\.1\.0
- 首次发布：2026-10-17T10:04:24.673Z
- 最新版本发布：2026-11-14T02:34:47.049Z
- 近 30 天下载量：3657（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

@tintinweb/pi-subagents:一个子代理工具.

## 安装

```sh
npm install @gfgghgftgffg/pi-subagents-lean
```

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

## README

# @gfgghgftgffg/pi-subagents-lean

[English](https://npmcn.com/package/%40gfgghgftgffg/pi-subagents-lean/README.md)

## 优点

为 [`@tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) 提供更轻量的封装。Agent、取结果、中途改向和 Workflow 收成一个 `subagent`，首轮就要带上的工具注册文本大约少 97%。

## 功能

-   `run`、`result`、`steer`、`workflow` 和 `help` 都走这一个工具。后台任务、workflow、日程和原来的结果卡片仍用上游运行时。
-   冷门参数放在 `input` 里，是一段 JSON 对象字符串。调用前按真实上游 schema 校验。`help` 返回这份 schema。
-   `subagent_type` 列出扩展启动时启用的 Agent 类型。改了 Agent 文件后要重新加载。上游描述无法解析时，用 `help`，`input` 设为 `"run"`。
-   FleetView 将嵌套 Agent 列在父 Agent 下，显示各自的 token 用量。`❯` 标记光标，`●` 标记当前打开的视图；开启 `showModel` 时，列表也显示模型和思考级别。
-   提供只读子会话识别接口，让 `pi-goal-x-lean` 将目标管理留在父 Agent。

## 来源

门面来自 [kunkun9527/pi-subagents-lean](https://github.com/kunkun9527/pi-subagents-lean)。运行时是 [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)。本包跟随上游发布，不复制引擎。两者都是 MIT，本包保留原始 `LICENSE`。它属于 [amox-pi-extensions-lean](https://github.com/gfgghgftgffg/amox_pi_extensions_lean/blob/main/README.zh-CN.md)。

## 使用方法

启动一个 Agent：

```json
{
  "op": "run",
  "prompt": "Find the implementation of the cache key.",
  "description": "Locate cache key",
  "subagent_type": "Explore",
  "run_in_background": true
}
```

读取已完成的结果。用 `run` 返回的 `agent_id`；重新加载后也可以用保存的 handle。保存的结果会在有完成时间时显示该时间及距今时长：

```json
{ "op": "result", "agent_id": "agent-id" }
```

给还在跑的 Agent 发新指令：

```json
{ "op": "steer", "agent_id": "agent-id", "message": "Also check the tests." }
```

运行 workflow。参数写成 JSON 文本放进 `input`：

```json
{ "op": "workflow", "input": "{\"name\":\"review-panel\"}" }
```

查看某个操作的全部参数：

```json
{ "op": "help", "input": "run" }
```

## 安装

这是公开的 npm 包，安装时不固定版本：

```bash
pi install npm:@gfgghgftgffg/pi-subagents-lean
pi update --extensions
```

需要 Git 回退安装时，在仓库 checkout 根目录执行：

```bash
node scripts/install-extension.mjs pi-subagents-lean
```

本地 Git 安装通过拉取 checkout 并重跑安装脚本更新，`pi update` 不更新本地内容。只保留一种安装来源。迁移时先备份 settings，移除 `pi list` 显示的精确旧来源，再安装 npm 来源。请勿同时加载其它 `pi-subagents` 包装扩展。

需要 goal 联动时，通过 `pi install npm:@gfgghgftgffg/pi-goal-x-lean` 安装或更新配套的 [`pi-goal-x-lean`](https://npmcn.com/package/%40gfgghgftgffg/pi-goal-x-lean/README.zh-CN.md)。

## 重要提醒：检查 Agent 定义

上游会扫描全局、工作区和项目目录里的内置及自定义 Agent。本包不附带私有 Agent、会话或记忆。安装后检查每个 Agent 的 `model`，删掉不需要的类型，并避开与 `general-purpose`、`Explore`、`Plan` 重名。内置 Explore 默认继承会话模型，除非 Agent 文件自己指定。内置 `general-purpose` 在 workflow 之外可以继续委派，受上游深度和并发限制约束；同名自定义文件未设置 `allowed_subagents` 时仍禁用委派。Settings 默认保存到全局文件，项目已有 `.pi/subagents.json` 时保存到项目文件；Tab 可切换目标文件。

带过改动、后来被删掉的 worktree 不能重新打开；干净的 worktree 会在主 checkout 里打开。后台任务结束时通知父会话。配置了 `allowed_subagents` 的 Agent 共享默认最多 10 个运行中嵌套子 Agent 的限制，超限派生会失败，不会排队；顶层和 workflow Agent 不受此限制。通过 `/agents → Settings → Max nested concurrency` 配置（`0` 表示不限）。Agent 文件、workflow、worktree 和 `subagents.json` 见[上游文档](https://github.com/tintinweb/pi-subagents)；集成使用它的[事件](https://github.com/tintinweb/pi-subagents#events)和 [RPC](https://github.com/tintinweb/pi-subagents/blob/master/docs/rpc.md)。改了 Agent 定义、发现范围或 trust 设置后重新加载。行为说明在[更新日志](https://github.com/tintinweb/pi-subagents/blob/master/CHANGELOG.md)。

## 上下文占用（字符代理）

| Package | Registered character proxy |
| --- | --: |
| @gfgghgftgffg/pi-subagents-lean | 270 |
| @tintinweb/pi-subagents | 8417 |

Fixed ceil(characters / 4), not provider billing tokens.

## 开发

[开发检查与维护策略](https://github.com/gfgghgftgffg/amox_pi_extensions_lean/blob/main/docs/maintenance.md)；适配细节见 [MAINTENANCE.md](https://npmcn.com/package/%40gfgghgftgffg/pi-subagents-lean/MAINTENANCE.md)。

## 常见问题

### @gfgghgftgffg/pi-subagents-lean 是什么？

@tintinweb/pi-subagents:一个子代理工具\.

### 如何安装 @gfgghgftgffg/pi-subagents-lean？

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

### @gfgghgftgffg/pi-subagents-lean 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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

