@Shaw529

dsh-token-saver

Name: dsh-token-saver
Availability: InStock
Author: Shaw529

DeepSeek Harness plugin: aggressive token savings, no task-quality loss

Stars: 0
Language: TypeScript
Created: Sep 2, 2026
Updated: Sep 2, 2026

Auth

GitHub repo

Introduction

dsh-token-saver

一个为 DeepSeek Harness (dsh) 设计的 Cordis 插件。激进节省 token、绝不破坏任务效果。

dsh-token-saver 通过挂载三个扩展点节约 token：tools/post-execute（无损头尾裁剪 / grep 折叠）、agent/pre-step（委托官方 ctx.compaction）、以及可选的 prompt-cache 段稳定排序。所有改写都走 dsh 的事件流，不会触发"model-visible 与 logged 不一致"不变式。

为什么需要它

DeepSeek 这类 agent 在长任务里 80%+ 的 prompt tokens 来自两类内容：

被读出来的大文件 —— 一次性 read 一个 1MB 的迁移 SQL 就要吃掉 250k tokens。
被反复搜索出来的命中结果 —— grep 几十个文件，回填全部 grep 结果，模型根本没读完。

dsh-token-saver 默认 conservative 档只做一件事：完整保留头/尾，中间的部分用一行 metadata 替换。这是一种"lossless"折叠 —— 模型仍然知道"中间被截断了"，但实际送进 model 的字符数降到几千。

更激进的 balanced/aggressive 档再叠加：

delegate 给 dsh 官方 ctx.compaction.compactIfNeeded() 在压力阈值被触发时自动滑窗
替换 dsh-compaction-basic 为我们自己的 LLM-summary engine（用户接入 LLM 调用函数即可）

详见测试效果章节的真实数据。

四种模式

模式	`tools/post-execute` 头尾裁剪	grep 折叠	`agent/pre-step` 触发 `ctx.compaction`	替换 `dsh-compaction-basic`	LLM-summary engine
`off`	❌	❌	❌	❌	❌
`conservative` (默认)	✅	✅	❌（保留 dsh 默认行为）	❌	可选
`balanced`	✅（更紧的 budget）	✅	✅	❌	推荐
`aggressive`	✅（更紧的 budget）	✅	✅	✅	推荐

默认 conservative：完全不替换 dsh 原生链路，只对读出来的工具结果做无损头尾折叠，任务效果零损失风险。

安装

dsh 安装好后，在你的 harness home 里执行：

dsh plugin --profile web install dsh-token-saver

要锁定版本：

dsh plugin --profile web install dsh-token-saver@0.1.0

本地开发模式：

pnpm add dsh-token-saver

配置参考

cordis.yml 插件行示例：

- name: 'dsh-token-saver'
  config:
    mode: balanced
    headBytes: 16384
    tailBytes: 8192
    grepMaxMatches: 30
    grepContextLines: 2
    grepHeadBytes: 8192
    grepTailBytes: 4096
    pressureThreshold: 0.5
    compactPressureThreshold: 0.5
    llmSummaryEnabled: false
    llmSummaryMaxInputTokens: 16000
    replaceBasicCompaction: false
    includeToolNames: []
    excludeToolNames: ['interaction.ask_user', 'interaction.confirm']
    cacheStableSections: ['agent-identity', 'user-instructions', 'tool-list']
    telemetry:
      onFold: |
        (event) => logger.info({ kind: 'fold', ...event })
      onCompact: |
        (event) => metrics.histogram('tokens.saved', event.savedTokens, ['engine', event.engine])

字段说明

字段	类型	默认	含义
`mode`	`'off' \| 'conservative' \| 'balanced' \| 'aggressive'`	`'conservative'`	模式选择器
`preserveStructure`	`boolean`	`true`	截断时按行边界切，避免在行中间断
`headBytes`	`number`	`16384`	工具结果保留的头字节数
`tailBytes`	`number`	`8192`	工具结果保留的尾字节数
`grepMaxMatches`	`number`	`30`	grep 匹配最大保留条数（带上下文）
`grepContextLines`	`number`	`2`	每条匹配保留的上下文行数
`grepHeadBytes` / `grepTailBytes`	`number`	`8192` / `4096`	grep 折叠后的最终头/尾预算
`pressureThreshold`	`number` (0..1)	`0.5`	pre-step 副作用生效的压力比
`compactPressureThreshold`	`number` (0..1)	`0.5`	触发 `ctx.compaction.compactIfNeeded` 的压力比（balanced+ 生效）
`llmSummaryEnabled`	`boolean`	`false`	启用 LLM-summary engine（balanced/aggressive）
`llmSummaryPrompt`	`string`	内置	自定义摘要 prompt
`llmSummaryMaxInputTokens`	`number`	`16000`	单次摘要调用的输入 token 上限
`replaceBasicCompaction`	`boolean`	`false`	替换 `dsh-compaction-basic`（仅 aggressive 推荐）
`includeToolNames`	`string[]`	`[]`	白名单（空 = 所有工具）
`excludeToolNames`	`string[]`	`[]`	黑名单（优先级高于 include）
`cacheStableSections`	`string[]`	`[]`	需要钉住的稳定段 id，用于 prompt-cache 命中率
`telemetry.onFold`	`function`	`undefined`	每次 fold 后触发的同步钩子
`telemetry.onCompact`	`function`	`undefined`	每次 compaction 后触发的同步钩子

测试效果

基准方法

测试集见 benchmark/fixtures/index.ts，覆盖以下 8 个真实场景：

场景	模拟内容	原始 tokens
`big-read-2k-lines`	读 2 千行生成的 TS 代码	58,223
`huge-read-migration`	读一份 60k 行的 SQL 迁移	1,562,272
`grep-match-heavy`	grep 80 个匹配带上下文	44,924
`grep-sparse`	grep 8 个稀疏匹配	43,574
`stack-trace-1500`	1500 帧的栈追踪	17,917
`json-dump-800`	800 条嵌套 JSON dump	31,225
`code-search-TODO`	在 5k 行里搜索 `TODO\|FIXME\|XXX`	53,064
`mixed-session-12-tools`	一个 12 步混合工具会话	2,016,552
合计		3,827,751

Token 估算遵循业内常用的 4 chars/token 规则（surrogate-pair aware）；绝对值因模型分词器而异，但 ratio 在普通拉丁/CJK 文本上稳定。

对比结果

场景	原 tokens	conservative	balanced	conservative 节省	balanced 节省
`big-read-2k-lines`	58,223	6,169	3,094	89.4%	94.7%
`huge-read-migration`	1,562,272	6,174	3,095	99.6%	99.8%
`grep-match-heavy`	44,924	2,507	2,507	94.4%	94.4%
`grep-sparse`	43,574	3,102	3,102	92.9%	92.9%
`stack-trace-1500`	17,917	6,167	3,091	65.6%	82.7%
`json-dump-800`	31,225	6,115	3,050	80.4%	90.2%
`code-search-TODO`	53,064	3,101	3,101	94.2%	94.2%
`mixed-session-12-tools`	2,016,552	57,394	35,883	97.2%	98.2%
合计	3,827,751	90,729	56,923	97.6%	98.5%

读出来再现一遍：

$ pnpm run bench:compare

分场景 token 对比（离线估算：4 chars/token，surrogate-pair aware）
所有场景使用合成的工具结果。插件以默认设置运行。

+----------------------------+--------------+--------------+--------------+--------------+--------------+
| scenario                   |     original | conservative |     balanced |  cons. saved |   bal. saved |
+----------------------------+--------------+--------------+--------------+--------------+--------------+
| big-read-2k-lines          |        58223 |         6169 |         3094 | 89.4%        | 94.7%        |
| huge-read-migration        |      1562272 |         6174 |         3095 | 99.6%        | 99.8%        |
| grep-match-heavy           |        44924 |         2507 |         2507 | 94.4%        | 94.4%        |
| grep-sparse                |        43574 |         3102 |         3102 | 92.9%        | 92.9%        |
| stack-trace-1500           |        17917 |         6167 |         3091 | 65.6%        | 82.7%        |
| json-dump-800              |        31225 |         6115 |         3050 | 80.4%        | 90.2%        |
| code-search-TODO           |        53064 |         3101 |         3101 | 94.2%        | 94.2%        |
| mixed-session-12-tools     |      2016552 |        57394 |        35883 | 97.2%        | 98.2%        |
+----------------------------+--------------+--------------+--------------+--------------+--------------+

合计：original=3827751  conservative=90729  balanced=56923
节省 (conservative)：3737022 tokens (97.6%)
节省 (balanced)：    3770828 tokens (98.5%)

说明：
 - 估算规则与模型侧 token 计数器一致；绝对数值因分词器差异可能不同，但 ratio 在常见拉丁/CJK 文本上稳定。
 - "conservative" 匹配插件默认：16KB 头 + 8KB 尾，grep 折叠为前 30 个匹配 + 2 行上下文。
   对 session log 里的 model-visible 流无损失。
 - "balanced" 把 budget 收紧到 8KB 头 + 4KB 尾。仍无损失；折叠更多。

关键观察

栈追踪（stack-trace-1500）节省率最低 65.6%：因为栈帧本身已经是紧凑的"一行一帧"结构，没有冗余信息可以扔掉，反而头/尾 24KB 的固定 budget 占满了原始的 18KB 之后只省出一小段。
混合会话（mixed-session-12-tools）节省率最高 97.2%：因为它包含多个大工具结果，会被叠加压缩；同样输入下，保存下来的 inline 工具结果只剩 5.7%。
balanced 与 conservative 差距 0.9 个百分点（98.5% vs 97.6%）：差距是 conservative 的 16k/8k → balanced 的 8k/4k 砍头砍尾更狠；在 grep-matched 场景两者持平，因为 grep 折叠后的内容已经远小于头尾 budget。
无损性：conservative 和 balanced 都改的是 tool/result.content —— 通过 tools/post-execute waterfall 走的就是 dsh 标准的 tool result 事件流，session log 里完整保留被替换前的原 content（通过 surfaceOp 替换标记），可回放可重建，对模型的推理依赖关系不变。

跑你的机器上的真实对比

pnpm run bench:compare —— 跑 8 个合成场景的离线估算，无需 API key。
pnpm exec vitest run test/bench —— 跑永久回归基线（11 个 assertion，每个场景至少节省 X%）。

接入 dsh 后的真实对比：详见根目录 BENCHMARK.md ，里面给出了一份两份 DSH home + 8 个任务 + 自动 parse + 验收表的可复现模板。一键命令：

# 1) 准备两个 profile home（one-shot）
pnpm run smoke               # 先验 mock 链路
pnpm run build               # emit 插件产物

# 2) 在真实 dsh 上跑两个 profile × 8 任务
#    需要 DEEPSEEK_API_KEY
export DEEPSEEK_API_KEY=sk-...
pnpm exec tsx benchmark/run-real-bench.ts \
  --dsh-home-baseline ~/.dsh-bench-baseline \
  --dsh-home-plugin   ~/.dsh-bench-with-plugin \
  --tasks benchmark/tasks.json \
  --out ./runs

# 3) 把两次跑的 session metrics 拼成 markdown 对比表
pnpm exec tsx benchmark/parse-results.ts \
  --baseline ./runs/sessions-baseline \
  --plugin   ./runs/sessions-with-plugin \
  --text-dir ./runs \
  --output   bench-results.md

bench-results.md 直接给出每任务的输入/输出 tokens、节省率、输出比对、时长变化，以及验收 checklist。

如何保证不影响任务效果

dsh-token-saver 的所有削减都遵循 dsh 的两条硬性约束：

"Model-visible means logged." 任何送进模型的输入都必须能从 session log 重建出来。
- 我们的削减全部走事件：要么通过 tools/post-execute 返回新的 accept 决策（dsh 自动落 tool/result），要么通过 agent/pre-step 委托给 ctx.compaction（官方 compaction/* 事件记录了替换区间）。我们从不在 plugin 内部直接 mutate session，因此 deriveMessages() 仍然能在任何节点重新投射一致的模型可见流。
"Waterfall listeners must call next()."
- 我们的每个 listener 都先 await next() 拿到上游决策，再在此基础上修改 messages 或 content；从不短路 dsh 的默认链路。

附加安全保障：

风险点	缓解措施
错误结果被截断丢掉诊断信息	`decidePostTool` 里 `payload.result.isError === true` 时直接 passthrough，永不裁剪错误结果
极小工具结果被过度折叠	budget = `headBytes + tailBytes + 256`，超过这个 budget 才会折叠
关键工具（如 `ask_user`、`confirm`）被裁剪	`excludeToolNames` 默认建议保留交互类工具
`replaceBasicCompaction` 误开	仅 `aggressive` 模式默认 `true`；开就是显式接管，warn log 提示
LLM-summary 调用失败	我们的 `LlmSummaryCompactionEngine.compactIfNeeded` 失败会 catch 并 fallback 到官方基础实现，warn log 提示

开发

要求：

Node.js >= 22.19
pnpm >= 10（仓库用 pnpm@11.7.0，我们是独立 monorepo 但 root range 提到 10）

pnpm install
pnpm run typecheck       # tsc --noEmit
pnpm run lint            # oxlint src test
pnpm run test            # vitest run — 51 测试
pnpm run build           # tsc emit 到 lib/
pnpm run bench:compare   # 合成场景 token 对比输出 ASCII 表

tsconfig.json 跑 typecheck 走 noEmit: true + allowImportingTsExtensions: true；tsconfig.build.json 覆盖 noEmit: false + 关闭 .ts 扩展名导入，用于 emit 到 lib/。

架构

src/
  lib/
    truncate.ts          # 字节预算头尾截断，按行边界切
    fold-grep.ts         # 匹配保留型 grep 折叠
  strategies/
    tool-result-trim.ts  # tools/post-execute: 按工具名路由、content 改写
    context-pressure.ts  # agent/pre-step: 查 tokenMeter、调 ctx.compaction
    llm-summary.ts       # CompactionEngine 子类（replaceBasicCompaction=true 时启用）
    prompt-cache.ts      # systemPrompt 段重排 utility，稳顺序提 cache 命中
  config.ts              # ResolvedConfig + schema 元数据
  types.ts               # 最小 dsh 形状类型（不硬依赖内部包）
  internal.ts            # 跨策略 import 桶
  index.ts               # Cordis 插件：name / Config / inject / apply
test/                    # vitest，含 test/bench/compare.test.ts（11 cases）
benchmark/               # 离线基准 + 真实 e2e 入口
  fixtures/index.ts      # 8 个合成场景
  compare/index.ts       # 估算 + simulate 函数 + CompareRow
  compare-run.ts         # tsx 直接跑、输出 ASCII 表格
  run.ts                 # 真实 dsh 子进程接入（需 DEEPSEEK_API_KEY）

设计原则：

不替换 dsh 默认行为，除非显式 mode: 'aggressive' + replaceBasicCompaction: true。
所有 fold 都走 dsh 的事件，不进私有字段 → 重放/快照不变。
不硬依赖 dsh 私有 —— @deepseek-ai/cordis、@deepseek-ai/schemastery、@deepseek-ai/dsh-compaction 都是 peerDependencies（可 optional），编译期类型用 import type，运行时通过动态 trait 适配。

License

MIT