# dsh-tool-squeeze

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

[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek_Harness-0.1.0--rc.8-4c6fff)](https://github.com/deepseek-ai/DeepSeek-Harness)
[![Tests](https://img.shields.io/badge/tests-21_passing-22c55e)](#benchmark)
[![License: MIT](https://img.shields.io/badge/license-MIT-0f172a.svg)](LICENSE)
[![Local first](https://img.shields.io/badge/runtime-local--first-f59e0b)](#安全原则)

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

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

```text
合成 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：

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

本地开发：

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

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

## 工作流程

```text
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 原样通过。

## 安全原则

```text
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)。

## 配置

```yaml
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：

```yaml
- 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 和关键证据门，并通过：

```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm benchmark
```

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