dsh-budget-handoff
给 DeepSeek Harness 的会话设个预算上限：花完就停，并留下一份能接着干活的交接单。
用法
装（一条命令，装完重启 DSH）：
dsh plugin --profile <你的profile> add github:ZiOstudio/dsh-budget-handoff
想固定在某个版本（不随主分支漂移，便于复现同样的行为），在末尾加
#v0.2.0：dsh plugin --profile <你的profile> add github:ZiOstudio/dsh-budget-handoff#v0.2.0
然后在会话里直接发这三条：
| 你发 | 作用 |
|---|---|
/budget 5 |
本会话预算设为 5 元 |
/budget |
查还剩多少 |
/budget 20 |
不够了，提到 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
打开快照可以看到「干到哪了 / 动过哪些文件 / 怎么接着干」。
停住之后 —— 打开那份交接单
在你自己的工作目录里找 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 元
## 这个任务要做什么
<你在会话里说的第一句话>
## 干到哪了
- 工作目录：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看一眼。
/budget 的完整语法
| 你发 | 结果 |
|---|---|
/budget |
查询当前预算与已用 |
/budget 5 |
本会话预算设为 5 元 |
/budget 0.5 / /budget 12.75 |
小数可以 |
/budget 5 |
中间多打空格无所谓 |
/Budget 5 / /BUDGET 5 |
大小写随便混 |
/budget abc |
明确告诉你格式不对，并给出用法 |
/budget 0 / /budget -1 |
拒绝（低于下限 0.0001） |
/budgetx 5、预算 5 |
不是命令 —— 前缀必须独立，或后面跟一个空格 |
账户余额耗尽怎么办
如果账户余额先于会话预算耗尽，DeepSeek 会拒绝请求。插件认得出这个信号，并走同一套收尾：
[预算] 账户余额已耗尽，任务已停止
不需要任何配置，也不需要插件去查询余额。这一步零成本：不用凭据、不发网络请求、不调模型。
为什么需要它
让 Agent 长时间干活，最后往往是两种结局：
- 预算失控 —— 你不知道这个会话已经烧了多少钱，等发现时额度已经用完。
- 钱照付，活没了 —— 任务被硬中断，上下文里没留下任何「干到哪了」的记录。接手的人 （或下一次会话）只能从头再来，于是又烧一遍钱。
这个插件处理的是第二种：它不只是在钱花完时踩刹车，更是在踩刹车的那一刻，把进度抢救成一份可继承的资产。
「超预算了给我发个邮件没什么用，我睡了，它还在跑。」—— 事后通知在结构上是无效的， 因为通知到达时损失已经发生。所以这里不留通知，留交接单。
配置（一般不用动）
默认预算是 10 元。要改全局默认值，在 profile 的 cordis.patch.yml 里给插件加 config:：
- insert:
- id: dsh-budget-handoff
name: dsh-budget-handoff
config:
budgetCNY: 20.0
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
budgetCNY |
number | 10.0 |
每会话预算，单位人民币元；下限 0.0001。单个会话的临时覆盖请用 /budget，不要改这里。 |
verbose |
boolean | false |
打开后把逐笔用量与计费打进 stdout。默认关闭 —— 一次普通任务一行都不打，只留启动横幅、拦截提示和卸载证明 |
也可以完全不给 config: —— schema 会回填默认值。
价格表
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 虚报，而是明确告诉你保护失效了：
[预算] ⚠️ 预算保护已失效
原因：价目表里没有 <provider>/<model> 的价格，本插件无法为它计费
后果：本会话的消费不再累计，也不会在超支时拦停
怎么修：改用价目表里已有的模型，或把该模型的价格补进 src/pricing.json
（同一会话里同一个模型只提示一次。）
已知限制
- 单步会话不会触发拦截：闸门在「下一步开始前」，如果会话只有一步，那一步执行完就没有「下一步」可拦。
- 拦截后 CLI 退出码为 1：任务被拒绝，CLI 以非零码结束。
- 只覆盖
deepseek-official：其他 provider 走「价格未知 → 保护失效 → 明确告知」。 - 跨进程不累计：累计消费与
/budget设的预算都是内存值，进程重启即归零，也不跨会话共享。 - 法定节假日未建模：节假日仍按工作日窗口判高峰（见上文警告）。
- 价格不会自动更新：官方调价需要手动改
src/pricing.json并重新构建。
开发
pnpm install
pnpm run build # tsc → dist/
node dist/command.test.js # /budget 口令解析与回执
node dist/harvest.test.js # 交接痕迹采集
node dist/ledger.test.js # 账本累加
node dist/pricing.test.js # 价格/时段
node dist/snapshot.test.js # 快照渲染与写盘
自测不依赖任何测试框架：编译后直接 node 运行，读 PASS / FAIL 行。
内部时钟（给改代码的人看）
session/event → 只记录：记账、攒任务痕迹、排队待发通知
⚠️ 不要在这里 session.append()：实测发不出去
agent/pre-step → 口令处理 / 拦停 / 80% 预警
agent/turn-stopping → 80% 预警兜底（单步会话或停在最后一步时）
agent/request-error → 余额耗尽兜底
Star
如果这个插件帮你省下过真金白银——尤其是那种「一觉醒来，发现钱烧完了、活也停了」的场景——点个 Star，让更多正在踩这个坑的人看到它。
它不需要你花钱，也不需要你注册账号，就是让这个仓库在搜索和推荐里更容易被找到。
License
MIT © 2026 ZiOstudio
No comments yet. Be the first to write one.