工具输出压缩 w2829562572-dev/dsh-tool-squeeze

dsh-tool-squeeze

为 DeepSeek Harness 打造的证据保留型工具输出压缩插件。

DeepSeek Harness
Tests
License: MIT
Local first

把巨型日志、JSON、HTML 和文本转换为紧凑、可供模型直接推理的关键证据——在嘈杂的工具输出吞掉 Agent 上下文窗口之前完成压缩。

dsh-tool-squeeze 是一个确定性、本地优先的 DeepSeek Harness 插件。它在公开的 tools/post-execute 生命周期中，对超大的日志、JSON、HTML 和普通文本进行内容感知压缩。它不是 Skill，不修改 Harness Core，也不调用其他 LLM。

合成 Maven 失败 fixture

未安装 安装 dsh-tool-squeeze 约 22,998 estimated tokens 约 1,736 estimated tokens

↓ 92.5%
关键证据：PASS

安全优先：小输出和混合媒体输出保持不变；错误、失败测试和首尾信息优先保留；每次省略都会明确说明；完整格式化原文默认保存到 DSH 官方 spill store。

为什么值得安装

- 把上下文留给推理：压缩重复内容，优先保留错误、失败测试、堆栈根因、警告、退出信息和结构化样本；
- 零额外模型调用：完全确定性的本地处理，延迟、成本和数据流都可预测；
- 不是粗暴截断：每次省略均透明说明，完整原文通过 DSH 官方 spill store 保留并可按需读取；
- 安全接入：只使用公开的 tools/post-execute 生命周期，不修改 Harness Core；无法安全保存或处理时自动 fail-open；
- 结论可复现：仓库内置 fixtures、关键证据断言、原始 benchmark 结果和完整测试套件。

它解决什么问题

巨型工具输出常常只有少量真正有用的信息。简单截断可能恰好删掉位于中间的失败根因，而把完整结果直接放进会话，又会在后续请求中反复消耗上下文。

DSH rc.8 已经提供官方 spill policy：超过 50KB 的纯文本会保存原文并显示 head/tail 预览；compaction 时还会剪枝旧结果。本插件不替代它们，而是在原生 spill 上限之前做结构化压缩，让模型优先看到错误、失败测试、JSON 异常记录和 HTML 文档语义，而不是只有首尾。

安装

GitHub bundle：

dsh plugin --profile web add github:w2829562572-dev/dsh-tool-squeeze

本地开发：

pnpm install --ignore-scripts
pnpm build
dsh plugin --profile web add -w .
dsh --profile web --dump-config

DSH 尚处于 developer preview，建议安装时固定已审查的 commit。

工作流程

Tool Result
→ 检查大小、类型和工具名 → 阈值与 bypass 判断 → Log / JSON / HTML / Text Processor → 证据保护与 Token 预算 → 用官方 spillStore 保存完整原文 → 压缩提示 + 压缩内容 → 官方 spill-policy 硬上限兜底 → 模型上下文

插件只返回替换后的 content，绝不替换 canonical value。详细结论见 docs/research.md 和 docs/architecture.md。

支持类型

| 类型 | V0.1 行为 |
| Log | 首尾、错误/警告上下文、stack root、失败测试、退出信息、重复行/块精确计数 |
| JSON | 结构、代表性索引、异常记录、嵌套摘要、精确 omitted 数量 |
| HTML | 规则型 Markdown；保留标题、段落、表格、列表、链接和代码，删除 script/style/SVG/comment |
| Text | 保守清理空白并折叠完全重复行/段；仍超预算时保留证据与首尾 |

混合非文本 content block 原样通过。

安全原则

Safety > Information preservation > Compression ratio

- 默认小于 4000 estimated tokens 不处理；
- 加上透明提示后仍须比原文小，且不得超过 maxTokens；
- error、exception、failed、traceback、assert、caused by、warning 和非零 exit 信息优先保留；
- 默认先通过 DSH 官方 spill store 保存完整格式化原文；保存不可用或失败时 fail-open，返回原始结果；
- parser/compressor 异常不会让工具调用失败；
- enabled: false 可完全关闭，excludeTools 可按工具 bypass。

完整安全模型见 docs/safety.md。

配置

enabled: true
minTokens: 4000
targetTokens: 6000
maxTokens: 12000

processors:
log: true
json: true
html: true
text: true

preserve:
headLines: 80
tailLines: 120
errors: true
warnings: true

report:
enabled: true

excludeTools: []
retainOriginal: true

可在 profile 的 cordis.patch.yml 中覆盖同一个 row：

- id: dsh-tool-squeeze
config:
minTokens: 6000
targetTokens: 5000
excludeTools: [database_export]

仅当你接受“格式化原文不可检索”时才应设置 retainOriginal: false。

Benchmark

pnpm benchmark 会重新生成并运行提交到仓库的确定性 fixtures：

| Fixture | 原始 Tokens | 压缩后 | Reduction | 关键证据 |
| Maven failure | 22,998 | 1,736 | 92.5% | PASS |
| Gradle failure | 60,943 | 123 | 99.8% | PASS |
| npm build | 44,527 | 3,028 | 93.2% | PASS |
| pytest | 42,732 | 2,669 | 93.8% | PASS |
| JSON API | 159,459 | 352 | 99.8% | PASS |
| HTML page | 57,321 | 145 | 99.7% | PASS |
| Generic log | 85,027 | 106 | 99.9% | PASS |

这些是为了验证处理器和证据保护而设计的高重复合成数据，不代表真实业务一定能节省 90% 以上。Token 为 V0.1 近似估算并包含压缩提示，不等同于供应商计费 Token。原始数据见 benchmark/results.json。

兼容性与限制

V0.1 针对 DSH / dsh-tools 0.1.0-rc.8、Cordis 4.0.1 和 Node.js 22.19+ 开发并验证。它使用近似 Token 估算；HTML 不是正文识别器；没有 Web dashboard、/squeeze 命令、几十种命令专用 parser 或单次临时 bypass；嵌套 run_code durable copy 继续由官方 spill policy 处理。

压缩本质上是有损的，即使原文可检索，也仍需用真实 Agent 任务评估回答质量。

贡献与许可证

新增行为必须配套 fixture 和关键证据门，并通过：

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm benchmark

项目采用 MIT。运行时不调用外部服务，不 vendoring 第三方源码。