子智能体压缩 08mamba24/dsh-subagent-compactor

DSH 子智能体上下文压缩插件

状态：1.1.0 为未发布候选。 下文的冷压缩能力已通过代码复审但尚未发布：它依赖候选宿主维护能力（ctx.subagents.runMaintenance，见 host-patch/）。在原版 DSH 0.2.1-rc.2 运行时上，插件会明确拒绝冷压缩（host-capability-missing），只有 live 窗口压缩可用。当前已发布版本为 1.0.1（仅 live 窗口）。

在 DSH Desktop 的父会话中，手动压缩直接子智能体的历史——子智能体仍在运行时可以压缩，已经结束的 continuable 子智能体也可以按 session id 直接压缩。插件复用子智能体自己的压缩引擎，提供斜杠命令和模型工具。

候选版本： 1.1.0（未发布）· 包名： @local/dsh-subagent-compactor · 验证环境： Desktop 0.12.1 / Harness 0.2.1-rc.2（live 窗口为发布版运行时验证；冷路径与批量入口已在独立补丁版 Desktop 副本验收）。

真实 Desktop 批量验收记录：命令与模型工具均成功压缩两个已结束成员；原 ID 续接保留事实，完整重启后两份回执仍可查询。此结论验证候选宿主补丁，原版 Desktop 仍缺少冷维护能力。

1.1.0 变化

在候选补丁宿主上，结束后的 continuable 子智能体可以按 session id 压缩，无需再派任务或抢 live 窗口。插件调用 ctx.subagents.runMaintenance，由管理器恢复子成员组合、执行压缩，并负责结算和释放写入句柄；插件不持有恢复句柄。鉴权、pending 输入与并发规则见 TECHNICAL.md。

安装

已发布版本（1.0.1，live 窗口压缩）

1. 打开 DSH Desktop → 插件 → 添加插件。
2. 在“包名或地址”中粘贴：

https://github.com/08mamba24/dsh-subagent-compactor.git#v1.0.1

3. 点击 安装 → 立即启用，确认 @local/dsh-subagent-compactor 1.0.1 正在运行。
4. 替换已有安装后，完整退出并重新打开 Desktop。实测版本中，仅刷新界面可能保留旧命令定义。

如果之前从本地目录安装过同名包，先卸载旧来源，再安装 GitHub 版本。安装由 Desktop 插件管理器处理，无需手动修改 profile，也无需发布 npm 包。private: true 限制的是 npm 发布，不影响 Git 来源安装。

1.1.0 候选（没有可安装的发布 tag）

1.1.0 候选源码和 CI 已合入本仓库 main，但没有 1.1.0 tag 或发布包。在原版 Harness 0.2.1-rc.2 上，仅安装插件仍不能压缩已结束的子会话；完整能力需要插件与候选宿主补丁一起使用。

宿主补丁修改的是 Desktop 内置运行时，插件安装器不会自动应用它。现有验收通过的是独立制作的补丁版 Desktop 副本；本仓库尚未提供通用的一键补丁安装器。具体改动、验收副本如何制作，以及正式安装还缺什么，见宿主补丁中文说明。自动测试的隔离树见 host-patch/README.md。引用源码请使用完整 commit，不要引用不存在的 v1.1.0 tag。

使用

在创建子智能体的父会话中输入：

/subagent-compact

命令列出持久化的直接子成员目录。每行结尾标注 — live（已加载的 agent）或 — persisted (not loaded)（仅持久化记录；列表是即时观察，不是预留）。复制完整 session ID，再执行：

/subagent-compact <子智能体的session-id>

两种合法情形：

- 子智能体仍 live —— 在它运行时发起即可；默认 waitForIdle: true 会等本轮结束再压缩。
- 子智能体已结束（已结算、被回收的 continuable 子智能体）—— 之后任意时刻按 id 调用。插件恢复子会话、压缩一次、释放句柄；不会发送新任务。压缩后同一 id 仍可正常续接。

批量：一次压缩全部直接子成员

/subagent-compact --all

对调用父会话启动时刻的持久化目录快照中的每个直接子成员逐个压缩（快照之后新增的成员属于下一次运行；不递归孙成员、不涉及其他父会话的成员）。各项串行执行并沿用同一 per-target 锁——并发的单项压缩同一目标会得到 busy-target。每一项都单独报告结果与原因（压缩成功含 summary seq / 替换条目数 / 被替换历史 token 估算、无可压历史、one-shot 或 pending 被拒、引擎失败等）；单项失败不会吞掉其余项。批量结果只有在每个子成员都压缩成功或无可压历史时才是 completed；全部未成功为 all-failed，部分失败为 partial-failure，被取消为 batch-cancelled——包括取消落在目录读取尚未结束时的情形；这些非干净结果都会让命令报错，绝不报成功。取消（或卸载插件）会停止尚未开始的项（记为 not-started）并保留已完成的结果；取消落地时目录已读出的，已知的全部目标都会逐项记为 not-started，目录真未读出的则明确报告快照未知。每个被压缩的子成员仍会在自己的模型路由上多一次摘要请求。原版运行时上冷路径项会被拒（host-capability-missing 计入 failed），live 项照常压缩。

每个完成的批量都会持久化一条回执——插件自有版本化存储域（subagent_compactor_batch_receipts，经组合的 storageDomain 设施打开）中一条经 schema 校验的记录。回执显式携带所属父会话 id，该 id 即授权边界：其他父会话读不到也覆盖不了，fork 继承的历史不会冒充本会话自己创建的回执。写入在后端确认落盘的那一刻即持久（每批次一条、绝不覆盖），插件重载、宿主重启后仍在。宿主的 abort 语义会丢弃被取消命令自身的结果——回执必须持久化正是为此。裸 /subagent-compact 列表会附上本父最近一条未干净完成的回执（干净批次的结果当时已正常送达）；任意回执（干净与否）都可按 id 取回：

/subagent-compact report <batch-id>

回执写入失败会在返回文本中如实写明（NOT persisted: …），绝不谎称已持久化；记录形状由域的 zod schema 在打开时强制校验——外来载荷根本进不了域。

父智能体也可以在回合内调用工具：

compact_subagent({ "session_id": "<子智能体的session-id>" })
compact_all_subagents({}) // 上述批量入口，附结构化计数

例如告诉父智能体：“调用 compact_subagent 压缩子会话 X，并报告工具返回结果。”工具执行遵循宿主权限设置。批量工具的计数——total、compacted、nothing_to_compact、failed、cancelled、not_started——是批量结果的结构化数值，绝不从报告文本反向解析（错误行里可能出现任意数字）。

怎么确认压缩成功

带参命令应显示为真正的命令卡片。成功结果会给出子会话 ID、摘要序号和被替换的历史条目数；工具返回 outcome、target_session_id、summary_seq、replaced_items、replaced_tokens。

replaced_tokens 是被替换旧历史的估算量，不是加入摘要后的净节省量。要衡量上下文下降，应比较压缩前后的上下文估算或实际请求总输入。生成摘要会在子智能体自己的路由上多用一次模型请求。

拒绝都是显式 outcome，不会静默失败：unknown-session（无此会话）、not-authorized（他人子成员 / 孙成员 / 自身）、unsupported-target（one-shot、external、缺失或不受支持的 descriptor）、pending-input（存在持久化未处理输入——应先续接子智能体）、busy-target（并发压缩或他人持有写入句柄；稍后重试）、restore-failed、query-unavailable，以及引擎的六个手动压缩错误码（busy、cancelled、changed、summary、commit、persistence）。

环境与边界

- 组合需要 commands、tools、agents、subagents 服务，以及子成员对应的压缩引擎；冷压缩另需 sessionQuery 与会话持久化（同类组合中通常已具备）。批量回执存放在插件自有的存储域（@deepseek-ai/dsh-storage-domain，新增必需 peer；域内记录经 schema 校验、不进模型可见面），经组合的 storageDomain 设施打开；设施缺失或写入失败时，批量文本会如实写 NOT persisted，绝不谎称已持久化。
- 只允许运行时直接父级操作。live 目标按运行时所有权拒绝他人；已结束目标按子会话持久化 header 的父级血缘与其持久 descriptor 拒绝他人子成员、自身和孙成员。
- preset 组合通过 agentPresets.serviceFor 解析子成员引擎（绝不回退 Host 平面）；无该注册表的组合使用 Host 引擎。
- 冷压缩依赖宿主的管理器侧维护能力（ctx.subagents.runMaintenance）。在原版 0.2.1-rc.2 运行时上，插件会明确拒绝冷压缩（host-capability-missing）；host-patch/ 中的隔离候选宿主补丁提供该能力：已接受输入不丢失、正常续接全程可用、仅卸载插件不损滞留输入。live 窗口压缩在两种运行时上都可用。
- 支持列目录和手动压缩；删除、handoff、自动触发不在此版本范围内。
- 已验证 Desktop 0.12.1 / Harness 0.2.1-rc.2；其他版本需要另行验证。

技术说明见 TECHNICAL.md，验证口径见 docs/VALIDATION.md。测试依赖与命令见 英文说明。

源码与许可

本仓库提供插件源码和安装说明，尚未指定许可证。本次通过 GitHub 分发，包保留 private: true，未发布 npm。