前言¶
DeepSeek Harness (DSH) 的自动压缩机制在触发“压力”路径时存在一个具体问题：没有尝试上限，导致一个徒劳的“快速填充”循环，即一个过大的文件读取或工具输出会在每一步都消耗一次总结调用。dsh-zcode-breaker 旨在通过在总结浪费之前停止这个循环来解决这个问题。
核心功能¶
该插件扩展了 BasicCompactionEngine 并包装了 compactIfNeeded 方法。它提供以下能力：
- 会话级状态：状态是按会话管理的，防止会话之间互相污染。
- 日志驱动检测：从持久会话日志（携带至少一个工具调用的助手消息）读取工具轮次，而不是在内部使用计数器。这是压缩缝用于平衡计算的单位。
- 快速填充检测：如果在少于
toolTurnThreshold个工具轮次后请求压缩，则视为快速填充。 - 提前拒绝：当达到
maxConsecutiveRapidRefills时，尝试在总结调用运行前被拒绝。这种拒绝是锁定的；一旦触发，会话将保持拒绝状态直到被重置。 - 错误处理：抛出
CompactionRapidRefillError，并附带可操作的建议。 - 可见性：由于 DSH 的主机捕获来自
compactIfNeeded的错误并继续执行轮次，插件在锁定期间注入一个提示部分，以确保停止可见。 - 管理命令：提供
/compaction-breaker命令来报告状态和重置断路器。
安装与配置¶
安装该插件需要满足以下依赖条件：
- DSH 版本 >= 0.1.5-rc.2 和 >= 0.1.6-alpha.1
- @deepseek-ai/cordis ^4.0.2
- @deepseek-ai/dsh-compaction-basic
- @deepseek-ai/schemastery ^3.18.2
安装命令如下：
dsh plugin --profile web add dsh-zcode-breaker
典型用法¶
安装后，可以使用以下命令检查插件状态：
/compaction-breaker status
/compaction-breaker reset
插件包含测试套件用于验证状态机逻辑和包装器行为：
node --test test/tracker.test.js
node --test test/engine.test.js
node tools/boot-check.mjs --port 32100
实现细节¶
该插件从 ZCode 实现中获取快速填充状态机逻辑，但进行了改进：
- 日志读取：不像 ZCode 那样在循环中维护计数器，此插件从 DSH 的持久会话日志读取工具轮次，以匹配压缩缝使用的测量单位。
- 锁定时机：拒绝逻辑在总结调用运行之前发生（锁定），而不是之后。
- 可配置性：阈值（
toolTurnThreshold、maxConsecutiveRapidRefills）作为行配置提供，而不是编译时常量。 - 不实现 microcompact：该插件明确不实现 ZCode 的
microcompact.ts逻辑，因为它不重新实现该逻辑。
注意事项¶
- Node 版本：虽然 package.json 声明
>=20，但使用 npm install 在 Node 20 上会带来 10 个包且没有 dsh 二进制文件，而在 Node 24 上则是 488 个包。徽章显示测量值为 Node >=22.19。
总结¶
dsh-zcode-breaker 通过防止压缩-填充-压缩循环浪费总结资源，直接解决了 DSH 自动压缩中的一个具体问题。它通过在调用运行之前拒绝快速填充，并从持久日志中读取工具轮次来提供准确的状态跟踪。
