dsh-tool-squeeze

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

![DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) ![Tests](#benchmark) ![License: MIT](LICENSE) ![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/research.md) 和 [docs/architecture.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](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](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](LICENSE)。运行时不调用外部服务，不 vendoring 第三方源码。

来源信息

安装

检查来源文件

dsh-tool-squeeze

为什么值得安装

它解决什么问题

安装

工作流程

支持类型

安全原则

配置

Benchmark

兼容性与限制

贡献与许可证

更多相关插件

dsh-hooks-claude-code

dsh-hooks-codex

WeKnora#dsh-weknora