会话预算刹车 ZiOstudio/dsh-budget-handoff

dsh-budget-handoff

给 DeepSeek Harness 的会话设个预算上限：花完就停，并留下一份能接着干活的交接单。

用法

安装（一条命令，装完重启 DSH）：

推荐：装 npm 上的预构建包（免构建脚本，也不需要 allowBuilds 批准）
dsh plugin --profile <你的profile> add dsh-budget-handoff

或者：直接装源码仓库
dsh plugin --profile <你的profile> add github:ZiOstudio/dsh-budget-handoff

想固定在某个版本（不随主分支漂移，便于复现同样的行为），在末尾加版本号：

dsh plugin --profile <你的profile> add dsh-budget-handoff@0.4.0
dsh plugin --profile <你的profile> add github:ZiOstudio/dsh-budget-handoff#v0.4.0

源码安装会从 npm 拉开发依赖来跑构建；若被 pnpm 拦下，按提示把该包加进 profile 的 allowBuilds，或直接改用上面的 npm 包。

然后在会话里直接发这三条：

| 你发 | 作用 |
| /budget 5 | 本会话预算设为 5 元 |
| /budget | 查还剩多少 |
| /budget 20 | 不够了，提到 20 元（要填比已花掉的钱更大的数） |
| /budget tokens 200000 | 本会话 Token 上限设为 20 万（只有金额算不出来时才管用，见下文） |

发出去会立刻回你一句：

[预算] 本会话预算已设为 5.0000 元（已用 0.0000 元）

四条要记住的：

- 大小写随便混 —— /Budget 5、/BUDGET 5 都认
- 空格随便打 —— /budget 5 也行；数字可以是小数，比如 /budget 0.5
- 不花 Token —— 这三条不经过模型，改预算本身零成本
- 每个会话各自独立 —— A 会话设 5 元、B 会话设 20 元，互不影响

你不设的话，每个会话默认给 10 元预算。（想改掉这个默认值，见下面的「配置」）

写错了它也会说话 —— /budget abc 会明确告诉你格式不对并给出用法，不会装没听见。

装的过程可能看到若干条 missing peer 告警 —— 那些 peer 由宿主提供，属结构性噪音，不影响使用。
本包自身的 peer 已声明为 optional，剩下的告警都来自宿主侧的其它包，与本插件无关。

它会怎么管你

花到 80% —— 提醒一句，不拦你

[预算] 已用 4.0234 元，达到本会话预算 5.0000 元的 80% 剩余 0.9766 元。钱花完时任务会被停下，并写一份交接快照。
要提高预算：/budget <金额>

任务照常往下跑，一个会话只提醒一次。

如果某一轮把消费从 80% 以下直接顶到超过 100%，这条提醒就没有机会单独出现 ——那种情况下，下面那条拦停通知里会多一行说明。

花到 100% —— 任务当场停住

那一步不会再执行，所以界面上看起来就是「突然不出字了」。这是正常的。

同时会出现一条通知：

[预算] 预算已耗尽，任务已停止注意：本次消费越过了 80% 预警线，但直到耗尽才停下。
累计消费：5.0234 元 / 预算：5.0000 元交接快照已写入：
1. <你的工作目录>\BUDGET-STOPPED-handoff-snapshot.md
2. <$DSH_HOME>\storages\dsh-budget-handoff\last-stop.md
打开快照可以看到「干到哪了 / 动过哪些文件 / 怎么接着干」。

价目表里没有这个模型 —— 改用 Token 把关

金额是靠价目表算出来的。会话一旦切到价目表没收录的 provider/model（自建中转、新模型、别人家的 provider），金额就永远不再增长 —— 它不涨，也就永远不会超支，金额闸门等于没了。

这时候插件不会装死，而是换一把尺子：Token 数。它对每一笔调用都存在，不需要任何价格。

- 它平时是关着的。 只有当本会话真的出现过「算不出价」的调用，Token 闸门才会启动 ——所以全程都有价的正常会话，不会因为这条规则被提前掐断。
- 默认上限 500 万 Token（约等于 10 元按 Flash 输出价算出来的量级，再放宽一倍）。
要调：/budget tokens 200000。
- 缓存命中的 Token 按十分之一计。 DeepSeek 的缓存命中价是未命中价的 1/50，如果按原样计数，一段长对话会把 500 万这个额度迅速顶满，而实际只花了几分钱。所以判闸门时缓存读取按 0.1 折算；回执和通知里会把「折算后」和「原始」两个数一起写出来，对账时不会觉得插件少算了。
- 换尺子这件事会在会话里明确告诉你：

[预算] 价目表里没有 workbuddy-ai/deepseek-v4.1-flash-sg 的价格后果：本会话的金额不再累计（它不涨，也就不会再拦停），但 Token 数照记现在的保护：Token 上限 5,000,000，已用 128,400（折算后 34,200，缓存读取按 0.1 计）要调上限：/budget tokens <数量>；想恢复金额把关：补 dist/pricing.json 或换已知模型
- 停下来的通知也会换说法，不会让你去调金额（调了也没用）：

[预算] Token 用量已达上限，任务已停止累计 Token：5,120,000 / 上限 5,000,000（折算后；原始 6,300,000，缓存读取按 0.1 计）（金额因 37 次调用无价目表而未累计）

想彻底恢复「按钱管」，两条路：把该模型的价格补进 dist/pricing.json，或者换回价目表里的模型。
补价之后金额闸门立刻恢复，Token 闸门对新会话不再启动。

停住之后 —— 打开那份交接单

在你自己的工作目录里找 BUDGET-STOPPED-handoff-snapshot.md。它长这样：

DSH 预算交接快照

- 生成时间：2026-10-08 04:12:07.518 (UTC+8)
- 会话 ID：session-…
- 触发位置：turn=8, step=2
- 触发口径：金额（5.0234 元 / 5.0000 元）
- 累计消费：5.0234 元 / 预算 5.0000 元
- 累计 Token：812,345 / 上限 5,000,000

这个任务要做什么 <你在会话里说的第一句话>

干到哪了
- 工作目录：D:\…
- 模型已回复：12 次
- 最近动作（旧的在上，最新的在下）：
- pwsh — List files in current directory
- edit — snapshot.test.ts

动过哪些文件
- E:\repo\src\snapshot.ts

怎么接着干
1. 先看上面的「动过哪些文件」，逐个确认改动是否完整。
2. 把本会话预算调大。
3. 说一句「继续」——本快照已同时注入模型上下文，模型能看到断点。

详细事件（最近 10 条，供排查）

它是写给「第二天醒来的你」的，不是给排查用的日志。 取不到的字段会写成「本次没有观察到文件改动」这类明确说明，不会出现 null 字样。

想接着干 —— 提高上限，说「继续」

规则只有一条：新上限要大于已经花掉的钱。

/budget 10

[预算] 本会话预算已设为 10.0000 元（已用 5.0234 元）

然后说一句：

继续

交接单已经同时交给了模型，所以它知道上次干到哪，不用从头再来。

⚠️ 上面那个例子能成立，是因为原来设的是 5 元、花掉了 5.0234 元 —— 提到 10 元就够接着跑。

如果你是用默认的 10 元跑光的，那 /budget 10 等于没提，得填一个比 10 大的数。

不确定花了多少？先发一个 /budget 看一眼。

如果是 Token 闸门停的，调金额没用 —— 那种情况下通知里会直接告诉你 累计 Token：… / 上限 …，照那个数发 /budget tokens <更大的数>，再说「继续」。快照的「怎么接着干」一节也会写对是哪一条。

/budget 的完整语法

| 你发 | 结果 |
| /budget | 查询当前预算与已用（金额 + Token 两行） |
| /budget 5 | 本会话预算设为 5 元 |
| /budget 0.5 / /budget 12.75 | 小数可以 |
| /budget 5 | 中间多打空格无所谓 |
| /Budget 5 / /BUDGET 5 | 大小写随便混 |
| /budget tokens 200000 | 本会话 Token 上限设为 200,000 |
| /budget tokens | 查询（等同于 /budget） |
| /budget tokens 10 | 拒绝（低于下限 1000，一次调用就超了） |
| /budget abc | 明确告诉你格式不对，并给出用法 |
| /budget 0 / /budget -1 | 拒绝（低于下限 0.0001） |
| /budgetx 5、预算 5 | 不是命令 —— 前缀必须独立，或后面跟一个空格 |

重启之后 —— 账不会清零

关掉 DSH 再打开，同一个会话接着聊时，已经花掉的钱和 Token 都还在。

- 存在哪：<$DSH_HOME>\storages\dsh-budget-handoff\sessions.json，一个会话一条记录。
- 存什么：累计消费、四个 Token 桶、折算后的 Token、未计价调用次数，以及你给这个会话设的金额上限与 Token 上限。
- 什么时候写：每记一笔账后最多等 2 秒（连续记账只写一次），进程正常退出时再补一次。
- 什么时候清：超过 30 天的会话、以及只留最新 50 个会话，其余在下次启动时被丢掉。
- 坏处也要说清楚：这个文件是明文的，里面有会话 ID 和花费数字，没有对话内容。想从零开始，删掉它即可。

账户余额耗尽怎么办

如果账户余额先于会话预算耗尽，DeepSeek 会拒绝请求。插件认得出这个信号，并走同一套收尾：

[预算] 账户余额已耗尽，任务已停止

不需要任何配置，也不需要插件去查询余额。这一步零成本：不用凭据、不发网络请求、不调模型。

为什么需要它

让智能体长时间干活，最后往往是两种结局：

1. 预算失控 —— 你不知道这个会话已经烧了多少钱，等发现时额度已经用完。
2. 钱照付，活没了 —— 任务被硬中断，上下文里没留下任何「干到哪了」的记录。接手的人（或下一次会话）只能从头再来，于是又烧一遍钱。

这个插件处理的是第二种：它不只是在钱花完时踩刹车，更是在踩刹车的那一刻，把进度抢救成一份可继承的资产。

「超预算了给我发个邮件没什么用，我睡了，它还在跑。」—— 事后通知在结构上是无效的，因为通知到达时损失已经发生。所以这里不留通知，留交接单。

配置（一般不用动）

默认预算是 10 元，默认 Token 上限 500 万。要改全局默认值，在配置档的 cordis.patch.yml 里给插件加 config:：

- insert:
- id: dsh-budget-handoff
name: dsh-budget-handoff
config:
budgetCNY: 20.0
tokenBudget: 10000000

| 字段 | 类型 | 默认 | 说明 |
| budgetCNY | number | 10.0 | 每会话预算，单位人民币元；下限 0.0001。单个会话的临时覆盖请用 /budget，不要改这里。 |
| tokenBudget | number | 5000000 | 每会话 Token 上限；下限 1000。只在价目表算不出价时生效，全程有价的会话不受影响。临时覆盖用 /budget tokens。 |
| verbose | boolean | false | 打开后把逐笔用量与计费打进 stdout。默认关闭 —— 一次普通任务一行都不打，只留启动横幅、拦截提示和卸载证明 |

也可以完全不给 config: —— schema 会回填默认值。

500 万这个默认值怎么来的：10 元按 Flash 输出价（4 元 / 百万 token）约合 250 万输出 token，再按「输入输出大致 1:1」的常见比例放宽一倍。它是量级估计，不是精确换算 —— 真按这个数管预算时，请按你的实际模型和用量自己定。

价格表

dist/pricing.json（注意是 dist/，不是 src/：发到 npm 的包里只有 dist，运行时读的也是 dist/pricing.json；src/pricing.json 是它的源，改完要重新构建才生效），结构 provider → model → { cacheRead, cacheMiss, output }，每个桶含 offPeak / peak 两档。单位：人民币元 / 百万 token。

覆盖范围（只覆盖 DeepSeek 官方）：

| provider | model | 备注 |
| deepseek-official | deepseek-flash | 在售主力 |
| deepseek-official | deepseek-v4-pro | 在售 |
| deepseek-official | deepseek-v4-flash | 旧名别名，按 Flash 价计费 |
| deepseek-official | deepseek-v4-flash-vision-exp | 旧名别名，按 Flash 价计费 |

空闲时段的价格是高峰时段的一半。

高峰时段＝北京时间（UTC+8）周一至周五 09:00–12:00、14:00–18:00（半开区间， 12:00 与 18:00 整点算空闲）；其余时间（含周末）为空闲。

⚠️ 与官方定义有一处偏差，说清楚：官方规定高峰时段为「周一至周五不含中国法定节假日」，也就是说法定节假日全天算空闲。本插件没有建模节假日 —— 节假日的白天会被按高峰价（2 倍）计费，于是消费被高估、预算提前用完。

偏差方向是保守的（不会超支），但节假日跑长任务会被提前拦停。需要精确时，改 src/pricing.ts 的 isPeakHour()，把节假日日期一并纳入判断。

表里查不到的 provider/model 不会按 0 虚报，也不会静默失效 —— 它改用 Token 把关，并明确告诉你：

[预算] 价目表里没有 <provider>/<model> 的价格后果：本会话的金额不再累计（它不涨，也就不会再拦停），但 Token 数照记现在的保护：Token 上限 5,000,000，已用 128,400 要调上限：/budget tokens <数量>；想恢复金额把关：补 dist/pricing.json 或换已知模型

（同一会话里同一个模型只提示一次。）

已知限制

1. 单步会话不会触发拦截：闸门在「下一步开始前」，如果会话只有一步，那一步执行完就没有「下一步」可拦。
2. 拦截后 CLI 退出码为 1：任务被拒绝，CLI 以非零码结束。
3. 金额只覆盖 deepseek-official：其他 provider 的调用不计金额，改由 Token 闸门兜底（见上文）。
4. 跨会话不共享：累计消费、Token 用量、/budget 与 /budget tokens 设的上限都按会话隔离，A 会话花的钱不算进 B 会话。
重启 DSH 后这些数会从磁盘恢复（见下文「重启之后」），但只恢复最近 30 天、最多 50 个会话，更旧的会被清掉。
5. 法定节假日未建模：节假日仍按工作日窗口判高峰（见上文警告）。
6. 价格不会自动更新：官方调价需要手动改 dist/pricing.json（改 src/pricing.json 则要重新构建）并重新安装插件。
7. Token 上限是量级而非精确等值：默认 500 万按 Flash 的价折算放宽，换成 Pro 或别的模型时，同一个 Token 数对应的钱可能差好几倍。要按钱管，请补价目表而不是依赖 Token 上限。

开发

pnpm install
pnpm run build # tsc → dist/

node dist/command.test.js # /budget 口令解析与回执
node dist/gate.test.js # 闸门判定：哪个口径在管、超没超
node dist/harvest.test.js # 交接痕迹采集
node dist/ledger.test.js # 账本累加与缓存折算
node dist/persist.test.js # 跨重启状态：读写、原子写、裁剪
node dist/pricing.test.js # 价格/时段
node dist/snapshot.test.js # 快照渲染与写盘

自测不依赖任何测试框架：编译后直接 node 运行，读 PASS / FAIL 行。

内部时钟（给改代码的人看）

session/event → 只记录：记账（金额 + Token）、攒任务痕迹、排队待发通知 ⚠️ 不要在这里 session.append()：实测发不出去 agent/pre-step → 口令处理 / 拦停（金额或 Token）/ 80% 预警 agent/turn-stopping → 80% 预警兜底（单步会话或停在最后一步时） agent/request-error → 余额耗尽兜底

闸门只有一个：src/gate.ts 的 judge(state, limits) 是纯函数，同时看金额与 Token，返回「哪个口径在管、比例多少、超没超」。80% 预警和拦停都问它 —— 两者不可能对「还剩多少」给出不同答案。
Token 口径由 unpricedCalls > 0 点火：会话出现过算不出价的调用，才启用。

变更日志

每个版本改了什么、为什么改，见 CHANGELOG.md。

Star

如果这个插件帮你省下过真金白银——尤其是那种「一觉醒来，发现钱烧完了、活也停了」的场景——点个 Star，让更多正在踩这个坑的人看到它。

它不需要你花钱，也不需要你注册账号，就是让这个仓库在搜索和推荐里更容易被找到。

License

MIT © 2026 ZiOstudio