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 包。

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

发出去会立刻回你一句：

[预算] 本会话预算已设为 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 的完整语法

重启之后 —— 账不会清零

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

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

账户余额耗尽怎么办

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

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

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

---

为什么需要它

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

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

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

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

---

配置（一般不用动）

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

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

也可以完全不给 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 官方）：

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

高峰时段＝北京时间（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