dsh-resume-budget

恢复一个长会话时，在第一个请求发出之前检查预计输入；超过阈值就先压缩一次，再发请求。

> English: A DeepSeek Harness (DSH) plugin that puts a configurable input ceiling on the first request of a restored session. When the projected prompt is at or above thresholdTokens (default 100000), it compacts the history through the harness's official overflow path before that request is assembled. The check runs once per session per process, is skipped for sessions created in this process, and never fails a turn. It adds no storage, no background work, and no model calls of its own. MIT licensed, Node.js >= 22.

兼容性

实际验证环境：Windows 11 22H2 + Node 24.19.0（engines 下限是 22）。macOS/Linux 走的是同一套 node:path/node:os/node:fs API，但仓库没有 CI 矩阵，这两条是兼容性承诺而非实测记录。

Node 版本：package.json 的 engines 要求 node >= 22（脚本只用了 node: 内置模块，无第三方依赖）。

DSH 版本：本包没有 engines.dsh，四个 peer 依赖都写成 "*" 且全部 optional：

"peerDependencies": {
"@deepseek-ai/cordis": "*",
"@deepseek-ai/dsh-compaction": "*",
"@deepseek-ai/dsh-token-meter": "*",
"@deepseek-ai/schemastery": "*"
}

所以 dsh plugin add 不会因为版本号拒绝安装；真正的门槛是 API 是否存在：插件需要宿主提供 agent/pre-step 事件、ctx.tokenMeter.measure()、ctx.compaction.compactIfNeeded()。本仓库在 dsh 0.2.1-rc.2 上实测（dsh --version）。harness 若缺少 compaction 或 tokenMeter 服务，插件会挂载不上而不是报错——见排错。

安装

1. 确认工具链（两个平台一样）：

node --version    # 需要 v22 或更高
dsh --version

2. 装进你要用的 profile（web 是最常见的；profile 不存在时 dsh plugin 会初始化它）：

dsh plugin --profile web add github:xingzoudefengye/dsh-resume-budget

这条命令把包装进 $DSH_HOME/profiles/web，并把它加进该 profile 的 dsh.profile.bundles。首次安装需要能访问 GitHub（pnpm 拉取 github: 依赖）。

3. 重启宿主进程（完全退出再启动）。插件是在宿主启动时被 import 的，装完不会热加载：

dsh web

4. 按下一节验证，或直接恢复一个历史很长的会话看效果。

安装命令唯一的系统差异是 DSH_HOME 的写法，dsh plugin add 本身完全一样：

设置了 DSH_HOME 的话以它为准，check.mjs 也读同一个变量。

验证

在仓库 checkout 里运行（用仓库里的这一份；脚本本身不依赖 lib/）：

node scripts/check.mjs

装好插件后不想 clone 的话，profile 里安装的副本也有同一份脚本：

# PowerShell
node "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-resume-budget\scripts\check.mjs"

# zsh
node ~/.dsh/profiles/web/node_modules/dsh-resume-budget/scripts/check.mjs

它做两件事，和 scripts/check.sh 完全一致：

1. 在 dsh --profile --dump-config 的组合树里找 id: resume-budget；
2. 找 thresholdTokens: <期望值>。

默认 profile 是 web，默认期望阈值是 100000（即 bundle 自带的默认值）。安装正常时应看到：

$ node scripts/check.mjs
ok:   resume-budget is in the composed tree
ok:   thresholdTokens is 100000

如果你在 profile 的 cordis.patch.yml 里改过阈值，把期望值作为第二个参数传进去，否则第二条会变成 WARN：

node scripts/check.mjs web 150000
# ok:   resume-budget is in the composed tree
# ok:   thresholdTokens is 150000

两个参数的含义：

输出约定：ok: 表示通过；FAIL: 写到 stderr 且退出码 1（行缺失、profile 不存在、dsh 起不来）；WARN: 写到 stderr 但退出码仍是 0（只是阈值对不上，组合树里可能仍然是可用配置）。常见错误：

FAIL: no such profile: C:\Users\you\.dsh\profiles\nope
WARN: thresholdTokens 100000 not found in the composed tree

DSH_HOME 不在默认位置时：

# PowerShell
$env:DSH_HOME = 'D:\dsh-home'; node scripts/check.mjs web 150000

# zsh
DSH_HOME=~/dsh-home node scripts/check.mjs web 150000

macOS / Linux 也可以用原来的 bash scripts/check.sh web 150000，两者输出一致。

配置

只有一个配置键，定义在 lib/index.js 的 Config（schemastery）：

几处边界行为：0 关闭检查；预计输入小于阈值不压缩，等于阈值会触发（>=）。lib/decision.js 的 normaliseThreshold() 对 undefined、null、负数、NaN、Infinity 一律回退到默认 100000 而不是 0；但走 YAML 配置时，Config 的 min(0) 和 step(1) 会让负数、小数在校验阶段就被拒绝。

改阈值要改 profile 的用户层 patch，不是改这个仓库里的 cordis.patch.yml（那是 bundle 的默认值，重装会被覆盖）。在你的 profile patch 里加一段按 id 覆盖的配置：

# $DSH_HOME/profiles/web/cordis.patch.yml
- id: resume-budget
config:
thresholdTokens: 150000

• id 必须正好是 resume-budget（lib/index.js 里 export const name = "resume-budget"）。写错了宿主启动时只会打印 patch: entry "..." not found 然后继续，组合树里仍是 100000——这是最容易“以为改了其实没改”的地方。
• 改完保存：profile 的 patchReload 为 live 时宿主会热加载 patch；否则重启宿主。
• 想临时关掉整条策略，把值设成 0。

卸载

dsh plugin --profile web remove dsh-resume-budget

它会移除依赖、dsh.profile.bundles 里的对应项和该 profile node_modules 里的副本。然后重启宿主，插件不再被 import。

不会自动消失的东西：

• 你自己在 profile cordis.patch.yml 里加的 - id: resume-budget 覆盖块（如果你加过）。pnpm 不管这个文件；留着它每次启动都会打印 patch: entry "resume-budget" not found 的警告，手动删掉即可。
• 已经写进会话的压缩检查点。压缩是把历史遮罩/摘要后落盘的，卸载插件不会把旧历史恢复回来。
• profile 目录里的 *.bak-* 备份和 pnpm 缓存，按需自行清理。

排错

行为

• 默认阈值 100000 token（thresholdTokens）。
• 每个会话、每个进程生命周期只判一次。
• 子代理的新会话天然不触发。
• 不新增存储、不新增后台任务、自己不发起任何模型调用（压缩那一次调用由压缩后端发起，和压力压缩、/compact 完全一样）。

设计

要解决的问题

harness 自带的 compaction-basic 有压力压缩：一轮里预计输入超过窗口的某个比例就压缩。但它在回合进行中才度量，所以一个 300k token 的会话恢复后，第一发仍然要付 300k —— 那是这个会话一生中最贵的一次请求，而且你正等着它。

这个插件把这一次判断提前到恢复后的第一个 step，并且把触发条件从「模型窗口的百分比」换成一个可以自己设的绝对 token 数。

为什么「有没有可压缩历史」不参与判断

预计输入里混着系统前缀、工具 schema 和历史，插件分不清哪部分能压。唯一有资格回答的是压缩后端本身 —— 它在没有可压缩区间时返回 null。在这里猜，要么错过真正的机会，要么为了凑数字去删掉当前请求。

度量与压缩都用官方的口子

• 度量：ctx.tokenMeter.measure(session).totalTokens（和压力压缩同一套，不传 request header）。
• 压缩：ctx.compaction.compactIfNeeded(agent, "context-overflow", signal)。

为什么不是 compactNow()。 它是 /compact 那个显式入口，把工作包在 agent.runMaintenance 里 —— 而 runMaintenance 要求 agent 空闲，回合进行中会直接抛 manual compaction requires an idle agent with no waking queued work。agent/pre-step 恰好就是回合进行中的状态，所以那个入口在这里必然失败（实测踩到的坑，不是推测）。

"context-overflow" 是官方压力压缩在同一个接缝上用的分支：先跑 tool-result 剪枝，再选出可压缩区间，走同一条 compactRegion 路径 —— 不用 runMaintenance，也不会拿窗口比例阈值覆盖本插件自己的绝对阈值。

证据边界

• 阈值是触发线，不是服务商的精确 tokenizer 结果，也不是绝对的请求上限；measure() 是启发式估算。
• 本插件不声称能定位恢复开销的根因，也不保证省下具体多少钱 —— 它只保证「超过这条线时先压缩」这件事发生一次。
• 单测覆盖：node --test（决策分支 + 接线流程，全部用假 ctx，不调用真实模型）。

开发

从仓库里跑测试前，先把它 import 的 harness 包链进本地 node_modules（否则 import "@deepseek-ai/schemastery" 解析失败，npm test 会挂）：

node scripts/dev-link.mjs        # macOS/Linux 也可以 bash scripts/dev-link.sh
npm test                         # node --test，22 个用例
npm run check -- web 100000      # 等价于 node scripts/check.mjs web 100000

dev-link.mjs 会从小到大依次尝试 dsh 包旁边的 @deepseek-ai 目录、其父目录、npm 前缀的 node_modules，也可以显式传目录或设 DSH_PACKAGE_DIR。它只在本地 link 安装时才有必要，正常的 github: 安装不需要。

相关插件

同一作者维护的 DSH 插件：

• dsh-browser
• dsh-web-search-failover
• dsh-compaction-local-handoff
• dsh-project-memory
• dsh-session-recall

许可

MIT。