dsh-tool-headroom 🧠

English | 中文

为 DeepSeek Harness (DSH) 打造的语义级智能大输出防爆插件。 灵感源自 Headroom 设计哲学：告别机械硬截断，拥抱保全语法与关键错误的高密度精炼输出。

💡 为什么需要 Headroom？

在 LLM Agent 开发与日常编码中，工具（如 bash、glob、测试运行器、网络请求）经常吐出几万甚至几十万字符的庞大输出。传统 Harness 的处理方式往往是首尾硬截断（Dumb Truncation），这导致三大痛点：

1. 打碎数据语法：截断 JSON 时丢失闭合标签（}、]），导致模型解析 JSON 语法直接崩溃。
2. 切掉关键报错：编译器报错、单测失败、npm 构建异常通常隐藏在中后段日志中，硬截断直接切除核心堆栈（FATAL / Stacktrace），模型成了“睁眼瞎”。
3. 浪费海量 Token：进度条（1% ... 100%）和心跳轮询行无意义地占满上下文窗口，剧烈拉长推理延迟。

dsh-tool-headroom 通过 AST 级结构感知与语义去噪，让工具输出在进入模型前完成精炼，减少 30%~80% 无效 Token 消耗，同时确保 100% 关键错误与语法保全！

✨ 核心特性

1. 智能 JSON 压缩 (SmartCrusher)

• 语法绝对有效：压缩后的 JSON 依然完全符合标准 JSON 规范，可正常 JSON.parse()。
• 大数组折叠：保留数组首尾样本项与 Schema 定义，中间重复项折叠为形如 _headroom_omitted: { count: 120 } 的紧凑节点。
• 异常项零丢失（Anomaly Guardian）：中段中任何带有 error、failed、statusCode >= 400、exitCode != 0 的项都会被强制识别并完整保留！
• Blob 脱水：自动截断长 Base64 图片或哈希大字符串，避免无意义的字符刷屏。

2. 日志去噪与堆栈守卫 (Log Denoising & Stacktrace Guardian)

• ANSI 颜色脱水：自动剥离终端 ANSI 转义码（\x1b[31m 等），还给模型最干净的纯文本。
• 进度条消除：将多行刷屏的下载/构建进度条（如 [==> ] 20%）智能折叠，只保留最终完成态。
• 连续重复行折叠：将大量轮询日志（如 ping: ok x 100）折叠为 ping: ok (repeated 100 times)。
• 堆栈绝对保护（Immunity Window）：无论日志长达多少千行，遇到 FATAL、ERROR、TypeError、panic、Traceback 等报错时，自动建立上下文保护区（前后 N 行完全免疫截断），确保模型永远能看到最真实的报错行和调用链！

3. 可逆检索机制 (CCR - Content-Cache-Retrieval)

• 每次触发实质性压缩时，插件会自动将未压缩的 100% 原始全文落盘到本地缓存区。
• 在输出末尾附加轻量找回凭证：

  [Headroom: compressed from 48.2KB to 3.1KB (-93%). Full raw output cached at: /path/to/cache.txt. Use 'read' to inspect if needed.]

• 模型若对中间被折叠的数据有精细需求，只需使用自带的 read 工具读取缓存文件即可，零学习成本，完全可逆！

4. 极致 KV 缓存友好 (Live-Zone 独占拦截)

• 挂载于 DSH 原生 tools/post-execute 洋葱中间件。
• 只处理当前最新一轮工具输出，绝不回溯改写历史 Prompt，确保 DeepSeek / Claude 的 Prefix KV Cache 命中率保持在 90% 以上！

🚀 安装与配置

1. 安装插件

在你的 DSH Profile 目录下安装：

pnpm add dsh-tool-headroom

2. 启用插件 (cordis.patch.yml)

在配置清单或 Preset 中加入本插件：

- insert:
    - id: headroom
      name: 'dsh-tool-headroom'

3. 可选配置项 (支持 Web UI 动态修改)

本插件提供标准 @deepseek-ai/schemastery 配置模型：

| 配置项 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | enabled | boolean | true | 是否全局启用智能输出压缩 | | thresholdBytes | number | 3072 (3KB) | 触发分析的输出最小体积阈值 | | maxTargetBytes | number | 12288 (12KB) | 压缩目标体积上限 | | jsonCompression | boolean | true | 是否启用 JSON SmartCrusher | | logDenoising | boolean | true | 是否启用日志去噪与堆栈守护 | | stripAnsi | boolean | true | 是否清理终端 ANSI 转义码 | | collapseRepetitions | boolean | true | 是否折叠连续重复日志行 | | preserveErrorContext | number | 8 | 报错堆栈前后强制保留的上下文行数 | | cacheRawOutput | boolean | true | 是否落盘保存原始数据 (CCR) | | cacheDir | string | "" | CCR 自定义缓存目录 (留空为系统临时目录) | | excludedTools | string[] | ["read", "read_image"] | 免于压缩的工具白名单 |

🧪 自动化测试验证

本项目拥有严格的单元测试覆盖：

• 巨大 JSON 数组折叠与异常节点保留
• Base64 自动脱水与语法闭合校验
• 进度条折叠与重复行计数
• 千行日志中关键堆栈（Stacktrace）免疫窗口测试
• CCR 本地缓存读写与精确还原
• Cordis tools/post-execute 拦截与工具白名单穿透

运行测试：

pnpm test
pnpm typecheck

📄 开源许可证

MIT License © 2025 Jaylor-Wang