DeepSeek Harness 压缩能力缝的包边界设计:为何拒绝折叠 `dsh-compaction` 与 `dsh-compaction-basic`

原创2026-09-20 10:36:561,644 阅读
文章标签:人工智能AI AgentAgent 框架代码智能体工具调用MCP 服务MCP ClientsAgent 沙箱插件系统浏览器控制GUI 自动化CLI桌面应用DeepSeekdsh-plugin

DeepSeek Harness 压缩能力缝的包边界设计:为何拒绝折叠 dsh-compaction 与 dsh-compaction-basic

导读

本文剖析 DeepSeek Harness 中"压缩(compaction)"能力缝(capability seam)的包边界设计:@deepseek-ai/dsh-compaction(Service Definition)与 @deepseek-ai/dsh-compaction-basic(Service Provider)为何分为两个包,以及仓库中一份提出"将唯一的压缩后端折叠进服务定义包"的 Agent Note 为何被标记为 rejected。读完本文,你将理解该仓库"接口 / 实现 / 消费方三角色独立演进"的架构原则如何在压缩模块落地、单实现时代为什么仍保留双包边界,以及未来引入第二个后端时边界应如何演进。

背景:压缩能力缝的双包结构

在 DeepSeek Harness 中,长会话的事件日志会持续累积,最终逼近模型的上下文窗口。压缩(compaction) 是缓解手段:把一段旧历史替换为一条简明摘要,保留最近的上下文。为了让"决定压什么、产出摘要"的后端可以替换,compaction 能力缝决策 将压缩按 能力缝架构决策 拆成三个角色:

  • Service Definition:@deepseek-ai/dsh-compaction,拥有 ctx.compaction 键、抽象 CompactionEngine、CompactionResult 词汇表、compaction/* 会话事件、手动压缩失败分类与标准检查点消息源;
  • Service Provider:@deepseek-ai/dsh-compaction-basic,提供具体实现 BasicCompactionEngine;
  • Consumer:@deepseek-ai/dsh-command-compact(人类 /compact 命令)与模型侧消费方。

能力缝决策明确写道:"不要预先拆分——一个能力在只存在一个可想象的提供方和一个消费方时,应保持单包,直到第二个出现。" 而压缩的独立消费方(dsh-command-compact)当时已被推迟。这正是被拒提案的出发点:拆分先于需求落地,且没有后端替换的实际用例来支撑它。

问题陈述:单实现时代的包边界成本

被拒提案(2026-07-19-fold-compaction-package-split.md)开篇列出的"问题"非常具体:当时压缩被拆在两个包中——dsh-compaction 拥有一个仅含两个方法(compactIfNeeded、compactNow,外加面向显式调用的 compactRegion,共三个抽象方法)的抽象服务和共享类型,而 dsh-compaction-basic 拥有唯一完整的提供方。交付配置只加载 basic 包,除该提供方外,没有生产包独立消费 Service Definition 包。

提案把拆分带来的纯开销逐项点出:

  • 一份额外的包 manifest(package.json);
  • 一份额外的 README;
  • 一个项目边界(workspace / tsconfig);
  • 一条依赖边(basic → compaction 的 peerDependency);
  • 一个抽象转发类(BasicCompactionEngine extends CompactionEngine);
  • 生成的目录项(generated catalogs)与模块图条目;
  • 组合接线(preset 中的 compaction-basic 行)。

这些都可以从源码中得到印证:compaction-basic/package.json 声明了对 @deepseek-ai/dsh-compaction、@deepseek-ai/dsh-agent、@deepseek-ai/dsh-session 等一长串 workspace peerDependencies;standard preset 中 compaction 组加载 @deepseek-ai/dsh-compaction-basic、@deepseek-ai/dsh-command-compact 与 @deepseek-ai/dsh-compaction-tool-result-pruner 三个插件;而 dsh-compaction 的 index.ts 中 CompactionEngine 的全部三个操作都是 abstract——接口只声明"做什么",不声明"怎么做"。

提案的结论是:这些成本在没有后端替换用例的前提下,属于预支的架构税。

提案内容:折叠为单包 + 保留 summarize() 钩子

折叠提案的核心内容包含三个动作:

1. 把 basic 实现移入 dsh-compaction,删除 dsh-compaction-basic

提案要求将以下内容归入一个包:

  • ctx.compaction(服务标识);
  • CompactionResult(结果词汇表);
  • 共享 transcript 与工具配对辅助方法(toolPairingBalancedBefore/After);
  • 现有配置;
  • 具体压缩算法。

从源码看,这些正是 BasicCompactionEngine 当前承载的内容:region.ts 中的 selectCompactableRange(尾部保留 + 工具配对平衡的头锚定范围选择)与 compactSurfaceRegion(compaction/start → summarize → compaction/summary → user/message(replace) → compaction/end 的完整事务),config.ts 中的配置解析与路由策略解析,summarizer.ts 中的 LLM 摘要调用。折叠后这些文件整体迁移即可,算法本身无需改动。

2. 保留 summarize() 作为受保护的自定义钩子

提案特别强调:summarize() 是 BasicCompactionEngine 唯一允许子类定制的钩子。部署专用的摘要器可以通过继承 BasicCompactionEngine 并覆写 summarize(),或拦截 ctx.llm.stream() 调用来完成定制,无需第二个能力包。

源码印证:compaction-basic/src/index.ts 中 summarize() 被声明为 protected,其 JSDoc 明确写道 "Override this sole hook for a template or remote summarizer",且 regionDependencies() 通过动态分发把 summarize 绑定进区域事务——这意味着子类覆写在事件时点(event time)被诚实尊重。这也是"折叠不牺牲可扩展性"的关键论据:定制点只需一个受保护方法,而不是一个包边界。

3. 同步修订既有决策文档

提案要求:若获准,应同步修订已实现的 compaction 能力缝决策 与 可回忆压缩提案,使"包所有权"只有一处持久说明——避免仓库中多个 Agent Note 描述互相矛盾的包结构。

备选方案剖析

提案记录了两种被考虑但未采纳的备选路线:

备选一:为可能出现的远程或回忆后端保留拆分

直觉上,既然"远程摘要器"或"可回忆压缩"已在计划中,保留边界似乎合理。但提案的回应很有说服力:

  • 一种可能的未来实现不足以支撑当前的包边界——能力缝决策的原则是"接口、实现、消费方都必须真实存在,而不能预先拆分";
  • 回忆(recall)增加的是压缩结果的消费方,不一定是另一种实现——回忆功能读取 compaction/summary 的 shadowedRange 与 shadowedSeqs 来渲染/检索历史,它消费的是词汇表,而不是替换后端;
  • 远程摘要器可以走受保护钩子——即继承 summarize(),同样不需要第二个包。

这一论据与 可回忆压缩提案 的措辞呼应:该提案规划的是新后端 dsh-compact-recallable(在 ctx.compaction 缝上),同时明确"compaction-basic 保留为参考实现和缝的设计孪生,模式类似于成对的 LLM 适配器"——也就是说,回忆功能恰恰预定了第二个后端的存在,这是折叠提案最终被拒的决定性反证。

备选二:让 compaction-basic 作为幸存包名

另一个思路是把提供方包名"顶替"到 Service Definition 包上——保留 compaction-basic 名称、内容换成整个合并包。提案否决了这一选项,理由涉及产品语义:compact 是 ctx.compaction 使用的稳定服务标识,若把产品服务命名为"basic",会让产品服务看起来像一个可选后端。这是命名与身份(identity)的取舍——服务的真实身份是 ctx.compaction 键,而不是某个具体实现的名字。

拒绝的理由:原则、计划与证据链

Agent Note 头部直接给出了拒绝状态与一句话理由:"More compaction backends are planned, so the Service Definition and basic provider packages remain separate."(计划增加更多压缩后端,因此 Service Definition 包与 basic 提供方包继续分离。)结合仓库证据,拒绝理由可拆成三层:

1. 原则层:能力缝决策的"不预先拆分"

能力缝决策 的核心主张是:拆包的目的不是"形式上的整洁",而是让变化速率不同的三件事(契约、实现、消费方 API)独立演进。当三者仍是一个关注点时,拆包只会增加 package.json、tsconfig、README 与注入接线的样板成本,却没有换来任何独立发布或替换能力。折叠提案自己承认了这一点——它列出的每一条"成本"都恰好是拆分理应换来的价值的反面。

2. 事实层:消费方从未落地

折叠提案成立的前提是"没有生产包独立消费 Service Definition 包"。但 compaction 能力缝决策 的 Consequences 部分记录了完整的四件套:dsh-compaction(接口)、dsh-compaction-basic(后端)、dsh-compaction-tool-result-pruner(模型无关的辅助服务)、dsh-command-compact(人类 /compact 消费方)。人类消费方已经以 compactNow() 的形式消费 ctx.compaction,且 preset 中三者总是同时装配。折叠提案声称"独立消费方被推迟"依据的是更早的中间状态,而仓库当前的组合接线已经证明 Consumer 角色真实存在。

3. 计划层:第二个后端已在路线图上

拒绝的最强证据来自 可回忆压缩提案:它明确规划 dsh-compact-recallable 作为 ctx.compaction 缝上的第二个完整后端。该提案的验收标准还要求"对长会话 bench 套件:任务成功率在同等预算下不劣于 compaction-basic"——这说明 compaction-basic 被当作对照基线长期保留。一旦第二个实现落地,"唯一完整实现"的折叠前提即告失效,届时再合并边界将需要重新提取,代价更高。因此拒绝是时间敏感的决策:在第二个后端落地前不折叠,比折叠后重新拆开更便宜。

若提案落地:从源码看影响面

虽然提案被拒,但其验收标准完整描述了"折叠是否安全"的判定维度,逐条对应仓库中的实现事实:

  • dsh-compaction-basic 及其工作区/包元数据被删除——涉及 compaction-basic/package.json、README、tsconfig,以及 preset(如 standard/agent.cordis.yml)中的装配行;
  • dsh-compaction 拥有配置、插件类、算法、类型、事件与共享辅助方法——即 index.ts、types.ts(CompactionResult 与 compaction/* 事件声明合并)、tool-pairing.ts、checkpoint.ts 将与 basic 的 config.ts、region.ts、summarizer.ts 并置;
  • 现有部署可用等效配置加载幸存包,模型可见行为等效——这是对配置兼容性的硬性要求(见下节);
  • 行为保真项:取消(AbortSignal)、锁(compaction/start…end 括号)、token 用量(shadowedTokenCount 启发式价格 + shadowedRouteTokenCount 路由价格)、工具配对(toolPairingBalancedBefore/After)、持久事件、引用的来源事件 seq(sourceEventSeqs)、重试收敛(compactionRetries/maxOverflowRetries)、transcript 渲染;
  • 测试门:loader 组合、单元、失控轮次(runaway-turn)、取消、快照、真实模型压缩测试全部通过,生成目录与模块图保持最新。

其中"失控轮次"是一个值得展开的细节:能力缝决策指出压缩在每个成功 step 之后检查(而非每轮),使工具密集的 ReAct 轮次能在轮内压缩早期已关闭的工具对。selectCompactableRange 的范围选择在保留尾部预算后按工具配对平衡回退,compactRegion 拒绝切割工具调用与结果对的边界——这些行为都集中在 region.ts,折叠只会移动文件位置,不会改变算法逻辑。

配置与组合:理解"等效配置"到底指什么

折叠提案多次强调"现有部署可以使用等效配置",那么 compaction-basic 的配置到底是什么?从 config.ts 与 types.ts 可整理出完整配置面:

配置项 默认值 含义与校验
thresholdRatio 0.8 触发压缩的压力阈值,取模型上下文窗口的该比例;必须是 (0, 1]
retainRatio 0.16 保留的最近上下文比例(相对上下文窗口);与 retainTokens 互斥
retainTokens 无 绝对保留预算(token 数),替代比例式保留;必须小于阈值 token
summarizationProvider / summarizationModel 空串 摘要调用目标;必须成对设置(同为空的"继承会话目标"或同为非空),否则加载失败
maxTokens 8192 摘要调用的生成上限;正整数
compactionRetries 1 首次压缩后压力仍超阈值时的额外尝试次数;非负整数
maxOverflowRetries 1 规范上下文溢出(CONTEXT_WINDOW_EXCEEDED_CODE)后的最大重试次数;0 关闭恢复
modelPolicies [] 精确 provider/model 覆盖表;重复目标导致加载失败
auto true 是否注册 agent/pre-step 压力与 agent/request-error 溢出恢复监听

值得注意的实现细节:resolveConfig 使用 deepFreeze 返回不可变配置,且拒绝未知键(validateKeys)——这防止拼写错误被默认值掩盖。resolveCompactSpec 把比例按路由模型的 contextWindow(来自 LLM 适配器的能力元数据)缩放为具体 token 预算,并校验 retainTokens < thresholdTokens。配置解析、目标策略合并、容量缩放是 basic 包的核心资产,折叠后这些逻辑与行为完全不变,"等效配置"指的就是这份契约保持字节级兼容。

风险:有意的预发布包名收缩

提案在 Risks 部分对自身代价做了诚实评估,这部分在折叠提案中属于"反对证据",也因此成为拒绝理由的一部分:

  • 嵌入方迁移成本:加载 @deepseek-ai/dsh-compaction-basic 的嵌入方必须切换到新包名。这是有意的预发布(pre-release)包名收缩——利用 0.1.x 阶段用户基数小、破坏成本可控的窗口;
  • 未来重新提取成本:一旦未来出现第二个后端,又需要把边界重新拆出来。提案承认"只有在仍然只有一个完整实现时,这项代价才可接受";
  • 触发条件:如果第二个后端先行落地,应重新评估是否接纳本提案——而这恰恰发生了:可回忆压缩提案已把 dsh-compact-recallable 提上日程。

从工程决策方法论看,这份 note 的价值在于它把拒绝条件写成了可执行的规则:"单实现 → 可折叠;第二后端落地 → 重新评估。" 这使得包边界不是一个拍脑袋的决定,而是一个可随仓库状态自动翻转的判定。

结论:架构原则如何在一次拒绝中自我验证

这份被拒的 Agent Note 与其说是"失败的提案",不如说是能力缝架构的一次压力测试:它精准指出了单实现时代拆分的真实成本,其论据(manifest、README、依赖边、转发类、目录项、接线)全部可以逐条对照源码验证;而它的拒绝同样精准——能力缝决策的"不预先拆分"原则、已经落地的 Consumer 角色、以及路线图上的第二个后端,共同构成了反证。最终,"更多后端在计划中"这一条理由胜出。

对 DeepSeek Harness 的读者(尤其是插件作者)来说,这一案例给出了三层可操作的启示:

  1. 包边界服务于替换需求,而不是预支需求——当 ctx.compaction 只有一个实现时,扩展点应该是受保护方法(summarize()),而不是包;
  2. 能力缝的完整形态是 Service Definition + Service Provider + Consumer 三件套,缺一不可;dsh-shell 的 bash 三件套是参考模板,dsh-compaction 的四个包(含 pruner 与 command-compact)是压缩域的对应物;
  3. 决策文档应当可证伪——"第二个后端落地则重新评估"这样的显式触发条件,让架构决策可以随代码演进被复核,而不是沦为僵化的教条。

当前仓库中,压缩域保持四包结构(dsh-compaction、dsh-compaction-basic、dsh-compaction-tool-result-pruner、dsh-command-compact),preset 按零配置默认装配,算法、配置与事务语义集中在 packages/compaction 目录下。若未来 dsh-compact-recallable 落地,读者可以对照本案例验证"第二后端出现后边界是否重新演进"——这正是该 Agent Note 留给仓库的最大遗产。

登录后查看全文
deepseek-harness