README
dsh-token-saver
一个为 DeepSeek Harness (dsh) 设计的 Cordis 插件。激进节省 token、绝不破坏任务效果。
一个为 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
安装方式(按发布状态)
| 来源 | 命令 | 说明 |
|---|---|---|
| npm registry(推荐) | dsh plugin --profile web install dsh-token-saver@0.1.0 |
待 npm publish 后可用;目前走 GitHub tarball 或本地 pack |
| GitHub Release tarball | dsh plugin --profile web install https://github.com/Shaw529/dsh-token-saver/releases/download/v0.1.0/dsh-token-saver-0.1.0.tgz |
预构建 tarball,16.8KB,跳过 allowBuilds |
| 本地 tarball(开发中版本) | pnpm run build && pnpm pack → dsh plugin --profile web install ./dsh-token-saver-0.1.0.tgz |
本地 build 后打包 |
| 源码仓库(不推荐) | dsh plugin --profile web install https://github.com/Shaw529/dsh-token-saver |
走源码构建,需要 allowBuilds 授权 |
v0.1.0 release 已发布到 GitHub,附预构建 tarball。npm publish 暂未完成(待
npm login),预期下个版本时一并发布。
本地开发模式:
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
[在 GitHub 阅读完整 README →](https://github.com/shaw529/dsh-token-saver)更多「用量与计费」插件
dsh-cost-meter
作者 han-1413141
DeepSeek Harness 会话与当日 API 费用、预算与官方余额统计插件:历史看板、峰谷计价与官方价格一键同步。
dsh-usage-stats
作者 ychris12138
为 DeepSeek Harness Web GUI 提供提供方余额、订阅额度与 Token 用量分析。
dsh-plugin-langfuse
作者 linyp
Langfuse 可观测性插件:以 OpenTelemetry 追踪树导出会话至 Langfuse OTLP 端点
dsh-token-usage
作者 laoyuehanni
贴近 DSH 原生设计风格的 token 用量统计插件:实时记录每次请求的用量与费用,在 Web UI 中提供趋势图表、按模型定价明细和供应商配额显示。
