前言¶
DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”。在长时间运行智能体任务时，预算失控或任务突然中断且无记录是常见痛点。ziostudio/dsh-budget-handoff 是一个 Session budget brake 插件，它根据官方价目表实时计算消费，在预算耗尽时停止运行，并留下一份可恢复的交接快照。
安装与启用¶
安装该插件需要指定 profile。安装完成后需重启 DSH。
dsh plugin --profile <你的profile> add dsh-budget-handoff
安装过程中若看到 missing peer 告警，属于结构性噪音，不影响使用。若需要固定版本，可在命令末尾添加版本号。
核心功能¶
该插件提供以下能力：
- 按官方价目表计费：监控每一次调用，对照官方价格表计算成本。
- 预算耗尽拦截：当会话预算用完时，立即停止任务执行。
- 交接快照：拦截时生成一份包含上下文、文件改动和进度的快照文件，便于后续恢复。
- 预算管理：支持设置、查询和临时提高预算。
- 80% 预警：当消费达到预算的 80% 时发出提醒，但不会停止任务。
使用方法¶
基础命令¶
在 DSH 会话中发送以下命令（大小写与空格不敏感）：
/budget 5：将本会话预算设为 5 元。/budget：查询当前剩余预算与已用金额。/budget 20：提高预算上限（需大于已花掉的金额）。
如果不设置，每个会话默认预算为 10 元。
预算管理细节¶
- 格式校验：
/budget abc会明确提示格式错误并给出用法。 - 下限限制：
/budget 0或/budget -1会被拒绝，下限为0.0001元。 - 跨会话隔离：不同会话的预算互不影响。
预警与拦截机制¶
- 80% 预警：当已用金额达到预算的 80% 时，插件会发送一条提醒，说明剩余金额和预计拦截点。任务会继续运行，此提醒仅在会话中触发一次。
- 100% 拦截：当预算真正耗尽时，任务执行会被停止。此时 CLI 的退出码为 1。
预算耗尽后的处理¶
1. 生成交接快照¶
当预算耗尽时，插件会在本地生成两个文件：
<你的工作目录>\BUDGET-STOPPED-handoff-snapshot.md<$DSH_HOME>\storages\dsh-budget-handoff\last-stop.md
快照包含以下信息：
- 生成时间与会话 ID。
- 触发位置（turn/step）。
- 累计消费与预算对比。
- 任务目标描述。
- 干到哪了（工作目录、回复次数、最近动作）。
- 动过哪些文件。
- 怎么接着干（恢复步骤）。
2. 恢复任务¶
要继续之前的工作，需满足以下条件：
- 提高预算：使用
/budget <新金额>提高上限，新金额必须大于已花掉的金额。 - 输入指令：发送指令
继续。
由于交接快照已注入模型上下文，模型可以基于此断点继续执行，无需从头开始。
配置¶
若需修改全局默认预算，可在 profile 的 cordis.patch.yml 中添加配置：
- insert:
- id: dsh-budget-handoff
name: dsh-budget-handoff
config:
budgetCNY: 20.0
配置项说明：
* budgetCNY：每会话预算，单位人民币元，默认 10.0，下限 0.0001。
* verbose：是否将逐笔用量输出到 stdout，默认 false。
计费规则与限制¶
计费覆盖范围¶
插件仅覆盖 deepseek-official provider 下的特定模型：
* deepseek-flash
* deepseek-v4-pro
* deepseek-v4-flash
* deepseek-v4-flash-vision-exp
如果使用其他 provider 或模型，插件无法计费，提示预算保护失效。
价格表与时段¶
价格基于 src/pricing.json，单位为人民币元 / 百万 token。包含缓存命中/未命中、高峰/空闲两档价格。
- 高峰时段：北京时间（UTC+8）周一至周五
09:00–12:00、14:00–18:00。 - 空闲时段：除高峰时段外的时间（含周末）。
- 节假日处理：插件未建模法定节假日。节假日白天会被按高峰价（2 倍）计费，可能导致预算提前用完。
已知限制¶
- 单步会话不会触发拦截：闸门在“下一步开始前”生效。如果会话只有一步，执行完即结束，不会触发拦截。
- 跨进程不累计：累计消费与预算均为内存值，进程重启后归零。
- 价格不自动更新：官方调价需手动修改配置文件并重新构建。
目录与源码¶
- 技能Hub 目录：ziostudio/dsh-budget-handoff
- GitHub 仓库：ZiOstudio/dsh-budget-handoff
