giter00/dsh-headroom

dsh-headroom

适配 DeepSeek Harness (dsh) 的上下文自动压缩插件，思路参考 Headroom。

工具输出在进入模型之前先被压缩：JSON、搜索、日志、表格与长文本各自走专用压缩器； 所有有损压缩都会把原文存入本地 CCR store，并在压缩结果里注入一个短 marker， 模型需要精确原文时调用 headroom_retrieve(id=…) 即可逐字节取回。

 tool body settles
        │
        ▼
 tools/post-execute   ← dsh-headroom 在此压缩
        │
        ▼
 tool/result 进入 session log / 模型历史（压缩后内容 + CCR marker）
        │
        ▼
 模型需要原文时调用 headroom_retrieve(id=…)

特性

• 自动压缩工具输出：挂载 tools/post-execute，在工具结果物化之前替换文本内容。

• 内容路由，专用压缩器：

  内容类型	压缩策略
  JSON 数组/对象	SmartCrusher 风格透视：_keys + _rows + _common，长单元格截断
  grep/ripgrep 结果	按文件折叠：file (N matches) + line[:col]: rest
  构建/测试/日志	连续重复行折叠 + 保留 error/fail/exception/assert 上下文
  CSV/TSV/markdown 表格	保留表头与首尾行，中间行 offload
  长文本	Kompress 风格 ML 压缩（默认）：逐词打分 + must-keep 保护 + CCR 可逆取回；textStrategy: 'head-tail' 可切回首尾截断
  代码	默认不压缩（JS 端口不做 AST 压缩，避免破坏可补丁字节；read/str_replace_editor 的行号前缀会先剥离再识别）
  文件工具	默认不压缩（read/str_replace_editor/edit/write 及其匹配 *.js/*.ts/*.json/*.yml 的路径）

Kompress 文本压缩（参考 Headroom 的 Kompress-v2-base ML 模型）： 文本按词切分 → 每词打分（score = keep概率 × (0.5 + 0.5 × span分数)，模拟模型的 token 分类头 + span CNN 双头）→ score > 0.5 保留（或 targetRatio 取 top-k）→ 数字 / hex / 全大写标识符 / 路径 / 扩展名 / CLI flag / CamelCase 等语义脆弱词强制保留 → 保留词重组。默认评分器是确定性纯 JS 启发式；也可启用真实 Kompress-v2-base ONNX 模型打分（kompress.scorer: 'onnx'，见下文「真实模型压缩」）。

• 可逆压缩（CCR）：所有有损压缩都保存原文，headroom_retrieve 按 id 精确取回； headroom_stats 查看节省量；headroom_compress 压缩任意文本。
• 持久化：CCR store 默认写入 <DSH_HOME>/storages/dsh-headroom-ccr.json （1 秒去抖、原子替换、TTL + 最大条目数可配）。
• 无害跳过：短文本、代码、错误输出、excludeTools 命中的工具、本插件自身工具 都不会被压缩。
• 跨平台：纯 JavaScript + Node 内置模块，无原生编译依赖；路径全部通过 node:path 处理，DSH_HOME 支持环境变量覆盖，Windows / macOS / Linux 行为一致。 CI 矩阵见 .github/workflows/ci.yml。

实现方式

flowchart LR
  A[ToolRuntime 工具执行完成] --> B[tools/post-execute]
  B --> C{文本块总长 >= minChars?}
  C -- 否 --> Z[原样返回]
  C -- 是 --> D[ContentRouter 类型检测]
  D --> E[json] --> E1[SmartCrusher 透视]
  D --> F[search] --> F1[按文件折叠]
  D --> G[log] --> G1[重复折叠 + 错误保留]
  D --> H[tabular] --> H1[首尾行保留]
  D --> I[text] --> I1[Kompress 逐词打分 + must-keep 保护]
  I1 -. 无收益 .-> I2[回退首尾截断]
  D --> J[code] --> Z
  E1 & F1 & G1 & H1 & I1 & I2 --> K{压缩后 + marker 更小?}
  K -- 否 --> Z
  K -- 是 --> L[写入 CCR store]
  L --> M[替换 decision.content]
  M --> N[模型看到压缩内容 + headroom_retrieve marker]