返回目錄

dsh-token-saver

精選清單收錄維護狀態: 活躍

shaw529/dsh-token-saver

DeepSeek Harness token 節省外掛,激進壓縮上下文而不損失任務質量。

前往 GitHub
$ dsh plugin add dsh-token-saver

安裝

dsh 沒有統一的安裝指令 —— 把該外掛 README 中的設定行加入你的 profile / patch 設定,然後重啟即可。

查看安裝教學

7

星數

1

Fork

TypeScript

語言

MIT

授權條款

2026-09-02

建立於

2026-09-07

最近推送

README

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 来自两类内容:

  1. 被读出来的大文件 —— 一次性 read 一个 1MB 的迁移 SQL 就要吃掉 250k tokens。
  2. 被反复搜索出来的命中结果 —— 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 Plugins 是獨立的 DeepSeek Harness 外掛目錄,與 DeepSeek 官方無關,也不代表官方背書。第三方外掛未經安全稽核,安裝前請審查原始碼。

每週取得最新的 DeepSeek Harness 外掛,絕不濫發。