@gfgghgftgffg/pi-subagents-lean

中文文档
0.1.21发布于 2026/11/14MITES Module构建来源已验证近 30 天下载 3657

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

中文使用文档
文档目录8 节
  1. 优点
  2. 功能
  3. 来源
  4. 使用方法
  5. 安装
  6. 重要提醒:检查 Agent 定义
  7. 上下文占用(字符代理)
  8. 开发

@gfgghgftgffg/pi-subagents-lean

English

优点

为 @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。运行时是 tintinweb/pi-subagents。本包跟随上游发布,不复制引擎。两者都是 MIT,本包保留原始 LICENSE。它属于 amox-pi-extensions-lean。

使用方法

启动一个 Agent:

{
  "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。保存的结果会在有完成时间时显示该时间及距今时长:

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

给还在跑的 Agent 发新指令:

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

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

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

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

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

安装

这是公开的 npm 包,安装时不固定版本:

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

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

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。

重要提醒:检查 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 见上游文档;集成使用它的事件和 RPC。改了 Agent 定义、发现范围或 trust 设置后重新加载。行为说明在更新日志。

上下文占用(字符代理)

PackageRegistered character proxy
@gfgghgftgffg/pi-subagents-lean270
@tintinweb/pi-subagents8417

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

开发

开发检查与维护策略;适配细节见 MAINTENANCE.md。

版本与发布记录

@gfgghgftgffg/pi-subagents-lean 共发布 19 个版本,首次发布于 2026/10/17;过去 12 个月发布了 19 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.1.21latest2026/11/142 天前
0.1.202026/11/133 天前
0.1.192026/11/123 天前
0.1.182026/11/115 天前
0.1.172026/11/115 天前
0.1.162026/11/0511 天前

关于 @gfgghgftgffg/pi-subagents-lean 的常见问题

@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 和提交记录判断。