dsh-token-diet: DeepSeek Harness 事前 token 节约工具集

前言¶

在 DeepSeek Harness (DSH) 的开发中，当输入内容（如日志、API 响应、数据报表）体积过大时，往往在模型处理指令之前就已经占满了上下文窗口。现有的 dsh-compaction-tool-result-pruner 属于事后裁剪，而 dsh-token-diet 则是在内容进入上下文前进行结构保留摘要的纯函数工具集。它通过零依赖的方式，在源头减少 token 消耗。

核心功能¶

插件提供五个主要工具，根据输入类型选择使用：

diet_text：用于日志、文档、爬取正文。提取头部 + 尾部 + 行数 + 高频关键词 + token 估算。
diet_json：用于 API 响应、配置文件。提取 key 骨架 + 类型/键数/数组长度 + 抽样值。
diet_csv：用于数据文件、报表导出。统计列类型/distinct/min/max/avg + 抽样行。
diet_estimate：用于任意文本。估算 token + 进上下文建议（决定读全文、瘦身或跳过）。
diet_stats：累计节约统计。跨调用汇总 savedTotal。

节约反馈¶

每次调用瘦身工具（diet_text/json/csv）都会返回 saved 字段，提供真实节约数据：

{
  "kind": "csv",
  "rowCount": 8000,
  "colStats": [...],
  "saved": {
    "originalTokens": 38563,
    "outputTokens": 196,
    "savedTokens": 38367,
    "savedPercent": 99.5
  }
}

调用 diet_stats 可查看累计：

{
  "calls": 3,
  "originalTotal": 110272,
  "outputTotal": 1102,
  "savedTotal": 109170,
  "savedPercent": 99
}

压缩配置¶

插件注册 settings 命名空间 token-diet。支持三档预设和手动压缩比例。

三档预设¶

在 Web UI 或 settings 文件中设置 preset：

light：保留更多细节，适合代码评审。headChars: 2000, maxKeys: 25。
balanced（默认）：平衡骨架完整性与 token 减少。headChars: 800, maxKeys: 12。
aggressive：极致省 token，适合长会话。headChars: 300, maxKeys: 6。

手动压缩比例¶

设置 compression: 0-99 直接指定压缩强度：

0：不压缩（mode: "raw"），用于对比基线。
99：极致压缩。
系统在区间内线性插值覆盖 headChars、maxKeys 等参数。

优先级链：工具显式参数 > 工具 compression > settings compression > settings 逐项覆盖 > 档位默认值。

安全模型¶

纯函数：不读文件、不联网、不执行 eval。
输入上限：512KB，超限直接报错，不截断处理。
输出格式：紧凑结构化 JSON 字符串。
Unicode 安全：按码点截断，不切开代理对，支持 emoji/生僻字。

安装与启用¶

在 cordis.yml 或 dsh.profile 中引入：

plugins:
  - id: tool-token-diet
    name: 'dsh-token-diet'

若需轻量级版本（单工具、无 settings 依赖），可使用 dsh-token-diet/lite：

plugins:
  - id: tool-token-diet-lite
    name: 'dsh-token-diet/lite'

技术要求¶

Node 版本：^22.19.0 || >=24.0.0。
依赖：@deepseek-ai/cordis、@deepseek-ai/dsh-tools。

总结¶

dsh-token-diet 通过结构保留摘要替代全量文本，实现了大文本/JSON/CSV 在进入上下文前的主动瘦身，配合真实的 token 节约反馈和可配置的压缩策略，适合需要处理大量结构化数据或长日志的 DSH 场景。