Token 预算管家 13162563982/dsh-token-planner

dsh-token-planner

面向 DeepSeek Harness (DSH) 的 Token 与成本规划器 —— 预算提醒管家:实时核算、档位提醒、任务前预估,全程不干预你的任务。

独立开源项目,与 DeepSeek 无隶属关系;插件从不自动干预(不切换模型、不压缩上下文、不中断任务),决定权永远在你手上。

特性

- 峰谷感知计价 —— 按事件时刻区分高峰/空闲,报告拆分两档并给出错峰节省估算;
- 档位提醒 —— 60% / 80% / 90% / 100% 升档与回落都提醒,即时上屏、不积压、不产生僵尸轮次;
- 任务 token 预估 —— 任务开始前给出消耗范围、金额区间与预算占比(结构预估 × 确定性 token 数学 × conformal 校准,目标覆盖率 80%);计划模式经 exit_plan_mode 批准后,执行阶段再以批准的计划为据给出独立的「计划执行预估」;
- 双维度预算 —— token 数量与金额(默认 CNY)双维度,任一超限即升档;
- 热重载 —— settings.yaml 随时调整预算/阈值/定价,下一轮自动生效;
- 零侵入 —— 只挂载 DSH 文档化扩展点,不改写会话日志;校准只存统计量,不存任务文本。

实测验证

232 轮真实会话端到端黑盒验证(模型真实调用 DeepSeek,数据取自会话日志独立重算与官方 tokenUsage 投影):

图1:历史 token 花费计算

图1(历史 token 花费计算):232 个报告点 + 31 个历史点,插件累计 vs 实际累计相对误差均值 1.36%、中位 1.29%(残差全部来自插件自身预估调用,诚实记账)。

图2:任务 token 预估收敛

图2(任务 token 预估收敛):265 个预估点,实测覆盖率 94.3%(Wilson 95% CI [90.9%, 96.5%],目标 80%,区间偏保守);随校准样本量增加,区间持续收窄(全部 5 个分桶宽度-样本量相关 r ≤ −0.68),预估偏差向 0 收敛(马拉松会话 e: −0.218 → −0.001)。

完整方法与复现脚本见 benchmark/README.md。

安装

npm install dsh-token-planner # 或 pnpm add

在你的 DSH 部署的 cordis.yml 中追加:

- id: budget
name: dsh-token-planner
config:
tokenBudget: 1000000 # 每会话 token 预算(0 = 禁用该维度) budgetAmount: 10 # 每会话金额预算(单位 = currency,0 = 禁用) currency: CNY

本地开发调试可直接用相对路径:name: ../dsh-token-planner(需先 npm run build)。

配置(常用)

| 字段 | 默认 | 说明 |
| tokenBudget / budgetAmount | 1000000 / 10 | 会话 token/金额预算,0 禁用对应维度 |
| peakHours / timezone | [[9,12],[14,18]] / Asia/Shanghai | 高峰时段(半开区间,支持跨天)与时区 |
| thresholds | {l1:0.6, l2:0.8, l3:0.9, l4:1} | 提醒阈值(须 l1≤l2≤l3≤l4) |
| priceOverrides | {} | 按 provider → model → {offPeak, peak} 覆盖内置定价 |
| report.everyTurn / report.appendToSession | true / true | 每轮成本报告开关与是否注入会话 |
| estimate.* | — | 任务预估:路由/超时/目标覆盖率/开关等,详见 DESIGN.md |

文档与许可

- 技术细节(预估原理、统计口径、提醒行为、出厂先验来源、已知限制):docs/DESIGN.md
- 基准测试工具与方法:benchmark/README.md
- 许可:LICENSE(MIT)· 版权与数据声明:NOTICE· 第三方依赖:THIRD_PARTY_NOTICES.md