pi-subagent-feather

基于 @eggmasonvalue/pi-subagent 2.0.1 的独立 MIT 派生版。 npm 包名 pi-subagent-feather，本地目录 D:\Work\pi-subagent-lite。 版本 0.2.0。MIT 授权，见 LICENSE / NOTICE。

目标：保留独立上下文、子会话存档、resume、并行、超时与实时进度；减少父会话重复数据和额外提示词。

改了什么

不是“零 token”：工具 schema、任务、答案、Pi 本身系统提示词、用户 AGENTS 和项目资源仍会消耗 token。 没有自动摘要模型调用，没有新增检索工具，没有静默删旧会话。 去掉隐藏 details 的重复内容主要节省父会话磁盘/内存；它本来不送给模型，不应算成模型 token 节省。

实测

Windows / Node 24.18.1 / Pi 0.99.1：

• 两个工具的声明 JSON（含 schema 和原来的额外提示词字段）UTF-8 体积 3238 → 1513 字节，减少 53.3%。 这是声明字节数，不是特定提供商的精确 token 数，更不是整段会话的 token 节省率。
• 真实 DeepSeek 新子会话 + resume：两次 details 分别 602 / 616 字节；答案只出现在 content 一次。
• 多 MB 工具参数/输出、图片、思考块不会进入父会话回执。

父会话内容形式仍很简单：

[status=done session=C:\...\child.jsonl]
子代理答案

长答案会有 [Truncated; full text is in the child session.]。用已有 read/bash 按需查看 JSONL，或 resume 要求返回所需部分。 不另外创建一份全文输出日志。

启用与冲突

与原插件使用相同工具名：subagent 和 subagent_models，因此不能同时加载两版。

本机路径：D:\Work\pi-subagent-lite。 正式切换时，把 ~/.pi/agent/settings.json 的 packages 中：

"npm:@eggmasonvalue/pi-subagent"

替换为：

"D:\\Work\\pi-subagent-lite"

其余配置与包顺序不变；所有窗口 /reload 或重启。不要只添加新路径而保留旧插件一起加载。 这是替换加载源，不是修改第三方 node_modules。回退时恢复旧的 packages 项并 reload。 项目创建过程没有执行上述切换。

接口与使用

subagent({ task: "自包含任务和预期结果", model: "deepseek/deepseek-flash", thinking: "low", tools: ["read", "bash"] })
subagent({ task: "继续指令", resume: "C:\\...\\child.jsonl" })
subagent_models({})

• tools 未指定：继承父代理当前活动工具，排除 subagent/subagent_models；[]：无工具。
• 要允许递归，在 tools 里明确加入 subagent。并行调用是普通并行工具调用；子代理写不同文件。
• model/thinking/tools/cwd 只用于新子会话，不能与 resume 同时指定。
• timeout / cancellation 会停止子进程树，保留已写入的子会话供 resume。
• 超时后如何检查进度/继续，由父代理和用户决定，不再自动注入固定监督流程。
• 进度最多每100ms更新一次，最后一批数据即使没有后续 stdout 也会发布；只显示短进度/当前工具名与数量。
• 展开父工具结果显示答案与统计，不再展开完整中间轨迹；完整过程看子会话。
• session_shutdown（含 reload/会话替换）会取消并等待活动子代理。执行器不在扩展工厂中启动资源。

模型策略与旧会话

沿用现有 ~/.pi/agent/pi-subagent/models-allowlist.json，无需重写模型白名单。 PI_CODING_AGENT_DIR 改变 agent-dir 基路径。默认模型、thinking、支持等级和 resume 策略仍会校验。 模型清单保留短用户 description，省略 AA / DeepSWE benchmark 输出；policy 文件内容不被改写。

新会话在 <agent-dir>/sessions/subagent-lite/<run-id>/ 下。 继续使用上游 version 2 的 .jsonl.subagent.json metadata；可 resume 上游正常保存的旧子会话。 旧父会话已保存的重复详情不会被这版自动清除；需要新会话或核心存储优化才能甩掉旧历史。 若 metadata 缺失/损坏、模型被白名单撤销、thinking 不再允许，会明确拒绝恢复，不擅自换模型。

大小预算

可选配置：<agent-dir>/pi-subagent-feather/config.json。每次调用读取，缺省无需文件。

{
  "resultBytes": 8192,
  "resultLines": 200,
  "progressBytes": 2048,
  "stderrBytes": 4096,
  "eventBytes": 1048576
}

• result 上限作用于答案正文，状态/路径/错误说明占少量额外空间；长答案仍完整存在子会话。
• 支持多字节 Unicode；截断不切断代理对，有界子串会脱离巨大原字符串的 backing store。
• stdout 单个 JSON 事件超过 eventBytes 会丢弃该事件并在下一行恢复；子 JSONL 不受此限制。 极大最终事件被丢弃时，使用已流出的有界正文，并标记截断；统计可能仅有已流出 usage。
• 所有预算必须是正整数；最大 resultBytes 51200 / resultLines 2000 / eventBytes 64MiB。
• stderr 是运行期最多4KiB的尾部，失败且没有正文时供模型看；不保存在 details。

其他可选键（同一 config.json，未知键直接报错防拼写）：

• "offlineChildren": true：子进程附加 --offline，跳过启动时的模型目录网络刷新（更快）。适合 API key 型 provider；OAuth 型子代理凭证过期时可能需要先在主会话刷新凭证。
• "defaultTimeoutMs": 30000：调用未传 timeoutMs 时的兜底超时，防失控子进程。
• "resultKeep": "tail"：完成的答案超预算时保留结尾（结论常在末尾）；默认 "head"。流式进度始终保留头部。
• eventBytes 默认已降为 1MiB（真实子进程事件被 Pi 自身截断在 50KiB/2000 行内，1MiB 足够），单事件超限仍丢弃并在下一行恢复。
• 收集器解析前按事件类型做廉价预过滤，不关注的事件类型跳过 JSON.parse。

/subagents 命令

/subagents 列出最近的子会话（时间、大小、模型、路径），纯人看界面，不进入模型上下文、零 token。 有 UI 时可选择一条并复制其 resume 路径；无 UI（或 RPC 降级）时以通知列出。

开发 / 验证

npm install --legacy-peer-deps
npm run typecheck
npm test
node --experimental-strip-types scripts/measure-prompts.mjs <upstream-index.ts>

普通测试不调用模型/网络/麦克风，使用自己的临时目录和假子进程；覆盖大量输出、UTF-8、输出预算、metadata、 resume、timeout、abort、并行、流事件恢复、usage、生命周期清理、schema 和宽窄 TUI。

npm run smoke

smoke 会用现有 DeepSeek 认证发起两次极小请求，验证真实 Pi 加载/新会话/resume； 认证和 models 只复制到私有临时目录，测试后删除，不打印凭证、不改主设置、不使用 Codex/火山额度。 没有 DeepSeek 认证时不要运行此项。

插件没有 runtime dependencies，宿主模块仅声明 peerDependencies；开发依赖用于类型检查和离线测试。 npm audit --omit=dev 为零告警。固定 Pi 0.99.1 的开发依赖树目前有 brace-expansion 的已知告警， 不会随本插件打包，且不应通过修改用户全局 Pi 来消除本仓库的开发依赖告警。

保留上游 MIT 授权与出处，见 LICENSE / NOTICE。