DeepSeek Harness 压缩能力缝的包边界设计:为何拒绝折叠 `dsh-compaction` 与 `dsh-compaction-basic`
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 的读者(尤其是插件作者)来说,这一案例给出了三层可操作的启示:
- 包边界服务于替换需求,而不是预支需求——当
ctx.compaction只有一个实现时,扩展点应该是受保护方法(summarize()),而不是包; - 能力缝的完整形态是 Service Definition + Service Provider + Consumer 三件套,缺一不可;
dsh-shell的 bash 三件套是参考模板,dsh-compaction的四个包(含 pruner 与 command-compact)是压缩域的对应物; - 决策文档应当可证伪——"第二个后端落地则重新评估"这样的显式触发条件,让架构决策可以随代码演进被复核,而不是沦为僵化的教条。
当前仓库中,压缩域保持四包结构(dsh-compaction、dsh-compaction-basic、dsh-compaction-tool-result-pruner、dsh-command-compact),preset 按零配置默认装配,算法、配置与事务语义集中在 packages/compaction 目录下。若未来 dsh-compact-recallable 落地,读者可以对照本案例验证"第二后端出现后边界是否重新演进"——这正是该 Agent Note 留给仓库的最大遗产。