花费管家 121212165/dsh-plugin-price-aware

dsh-plugin-price-aware

🧩 dsh 插件家族（22 件）：总目录 dsh-plugin-family ｜ 明星插件：ide-hub 跨 IDE 统一管理 · task-forge 跨窗口无损交接 · quota 实时用量仪表

让你的编码智能体知道自己在花多少钱。

dsh 把 token 算得很准，钱却一分不算。整个 harness 里没有价格表，没有 /cost，没有余额查询，也没有消费上限——tokenUsage 投影只统计 uncachedInput / output / cacheRead / cacheWrite，账单最后落到账号主人头上。

这个插件补上这块空白：

- 模型每一轮都会读到自己的单价、账户余额和本会话的实时账单；
- 遇到昂贵的步骤，它先报三档价——A 最小 / B 做完 / C 做透——每档都给出 token 估算、金额和诚实的误差范围；
- 钱要花到肉疼时，它停下来问你，给出继续 / 降级到 flash / 缩小范围 / 推迟到错峰 / 停止；
- 它知道 DeepSeek 的高峰与错峰定价（工作日北京时间 09:00–12:00 和 14:00–18:00 是 2 倍价），也知道缓存命中价（flash 每 1M 是 0.02 对 1 CNY），所以「大批量任务放到 18:00 之后跑」是个数字，不是感觉。

MIT · TypeScript · 除 @deepseek-ai/cordis 外零运行时依赖。

安装

dsh plugin add github:121212165/dsh-plugin-price-aware

或者从本地检出安装（dsh plugin add ./dsh-plugin-price-aware），也可以锁定某个 commit：

dsh plugin add github:121212165/dsh-plugin-price-aware#main

社区插件的发现入口是 GitHub 话题 dsh-plugin。从本地检出安装：

dsh plugin add ./dsh-plugin-price-aware

然后重启 dsh。/money 应该能打印出价格。挂载配置在 cordis.patch.yml 里，每个字段都在该文件和 配置 一节有说明。

模型看到什么

injectIntoPrompt: true 每轮注入一个动态上下文块——110 token，按高峰 pro 价算是 ¥0.0005，一旦超过 260 就有测试失败：

钱: deepseek-v4-pro 单价(每百万 token, CNY) 输入 4.5/9 · 缓存命中 0.15 · 输出 13.5/27【当前高峰，价×2】钱: 大批量动作等 1h30m 后（错峰可省一半）钱: 账户余额 ¥41.20 · 本会话已花 ¥3.84/¥10.00（模式 normal） · 34 轮 · 缓存命中 71% 纪律: 单步预计 ≥ ¥1.50 时，先给 A/B/C 三档让用户选档再开工；不重复读大文件，保持前缀稳定以命中缓存；能用 flash 解决就别用 pro。

如果模型不在价格表里，这个块会明说，并禁止自己编数字。站不住脚的估算，比没有估算更糟。

命令与工具

| 名称 | 谁调用 | 做什么 |
| /money | 你 | 单价、余额、会话账单、剩余预算 |
| /budget [5] | 你 | 读取策略；改策略时打印配置修改内容，而不是悄悄改掉你的上限 |
| /estimate <kind> [turns] [residentK] | 你 | 按任务形态给出 A/B/C 报价 |
| price_status | 模型 | 同样的事实，任务中途可调用，在投入昂贵操作前先查 |
| quote_task | 模型 | 为即将开始的任务给出 A/B/C 报价 |

估算怎么算（以及哪里会算错）

智能体一轮对话的成本，不是「你敲进去的提示词」。它要把整段历史重新发一遍，再乘以轮数：

promptTokens = turns × resident + growth × turns × (turns − 1) / 2

真正烧钱的是 resident（系统提示词 + 工具 schema + 历史）：一次 14 轮的重构，resident 有 20k token，就要重发约 462k 提示词 token，其中只有走缓存折扣的那部分便宜。估算器按这个形状计价，拆成缓存 / 未缓存 / 输出三块，再套用模型当前的计费规则。

默认误差带是 ±35–60%。超过 reconThresholdMajor（默认 ¥0.5）时，插件会提议先花一次很小的只读侦察，把误差带收窄到 ±12%，成本不到它正在估价那项任务的四分之一。低于这个阈值，花钱去估算就是亏本买卖，它也会直说。

只有模型肯停下来，报价才是上界。 实测发现，一次整文件生成把给它的每个上限都顶满了，4320 → 6263 token，连顶两次。所以 quoteTrust() 会根据该模型实测的 selfFinishedRate，把每个数字标成上界或下界；escalateCap() 则把重试变成一次明码标价的实验，而不是假估算。

calibrate() 从你自己的历史里学习：喂给它 {predicted, actual} 对，它返回中位数修正（用中位数不用均值，这样单个 5 倍离群值不会带偏以后的报价）。

配置

price-aware:
mode: normal # economy ¥2 · normal ¥10 · max uncapped · custom below sessionCapMajor: 10 # whole currency units; only read when mode: custom warnPercent: 75 # this fraction of the cap triggers the ask taskAskMajor: 1.5 # one step above this gets an A/B/C quote first balanceFloorMajor: 3 # stop before draining the account below this
holidays: ['2026-10-01'] # Beijing dates billed off-peak
prices:
- id: jiyuan/deepseek-v4-flash # provider-scoped rows beat generic ones
currency: CNY
perMillion: { cacheRead: 0.5, uncachedInput: 3, output: 12 }

中转站和分销商的端点同样支持：你的服务商价格不是 DeepSeek 的价格，prices 行就是用来声明这一点的。在你声明之前，插件拒绝用货币报价。

不装 dsh 也能用核心

src/pricing、ledger、gate 和 estimate 都是纯模块。import { costOf, resolveModel, DEEPSEEK_CATALOG } from 'dsh-plugin-price-aware/pricing'，你自己的 harness、看板或 CI 预算检查就能用上同一套算钱逻辑。

开发

npm install # dsh types land in node_modules so the wiring typechecks for real
npm run check # typecheck + 74 tests + build
插件的 apply() 能针对真实的 @deepseek-ai/dsh- 声明文件编译通过，lib/index.js 导入也没有报错。挂载本身并非未经验证：这台机器上 28 份真实的 dsh 会话日志里都能看到本插件每轮的费用块，说明 apply()、事件接口和 systemPrompt.context() 这条路径都已实际跑通。

已修复：预算提示曾导致会话中止

tools/post-execute 提示原先用 source: { kind: 'plugin', plugin: <name> } 构造，而会话格式 v4 已废弃这层包装——消息一落盘，@deepseek-ai/dsh-session-format-v3-to-v4 的 source() 就会抛出 format v4 message requires a producer-owned source kind。于是预算建议第一次真正触发时，整个会话就挂了。现在提示改用生产者自有的 kind（plugin:price-aware），与官方 v3→v4 的 producerKind() 迁移旧记录时写入的值一致。

这条 kind 路径已在本仓库做过实际 A/B 测试，不是推断：在 dsh 0.1.7-alpha.1（headless 配置档、一次工具调用、相同配置）上，旧包装产生

dsh: format v4 message requires a producer-owned source kind

会话日志停在 tool/call——没有 tool/result，没有 step/end，没有 turn/end。同一任务换到修复后的构建则正常完成（27 个事件，以 turn/end 收尾），提示以 {kind: "plugin:price-aware", form: "notice", summary: "预算提示"} 落盘，模型也在回答里引用了预算文本。

已对真实付费端点验证

5 轮，真金白银，真实网关（TokenRhythm / 基元律动，¥18 额度），全程只走本插件自己的代码：

| | 结果 |
| 花费 | 59 次计费调用实测 ¥2.95，直到网关返回 402 余额不足，而本地账本仍以为还剩 ¥15.05 |
| 价格来源 | /v1/models 公布人民币费率 → catalogFromProviderModels() 可接入任何自报价格的网关 |
| 按官方价目表假设会出错 | 中转的 deepseek-v4-flash-0731 = 每 1M ¥3/9/0.1，而 DeepSeek 自家是 ¥1/4/0.02——按名字匹配会少计 3 倍 |
| 缓存 | 每次调用的 cached_tokens 都是 0，包括 3 个完全相同的 3.7k token 前缀 → 这个网关不给前缀折扣；此处 cacheableShare 必须为 0 |
| 推理 | 最多 100% 的 completion_tokens 不可见；第 2 轮有几次调用按满额计费却返回 0 个字符 |
| 每份有效产出的成本 | 最好 ¥0.0032/千可见字符，最差 ¥9.53/千——约 3000 倍差距，单看 token 价格表根本发现不了 |
| 交付物 | report/content.js，10 287 字符，通过 vm.Script，覆盖全部 6 项 F1 子要求 |
| 按每个可解析*文件的成本排名 | deepseek-v4-flash-0731 ¥0.048 · minimax-m2.7 ¥0.077 · qwen3.7-max ¥0.090 · deepseek-v4-pro-0813 ¥0.148——另有 8 个模型收了钱却交付零个可解析文件 |
| 最终校准 | 中位偏差 ×0.858，余量按报价而非账单报告 |
核心结论是：提示词纪律就是成本控制。同一个模型、同样的上限（6263）、同样的任务，第 4 轮就填满上限并截断；第 5 轮在系统提示词禁止围栏和散文之后，模型自己用 2904 token 完成，花费 ¥0.028。复现命令：node examples/live-run.ts && node examples/live-run2.ts && node examples/live-run3.ts && node examples/live-run4.ts && node examples/live-run5.ts；每次运行都会写入 report/。

已知限制

- 内置价格表是带日期的快照（src/pricing/catalog.ts 里的 asOf，DeepSeek 页面截至 2026-09-21）。超过 45 天后，该区块会提示可能已过期。对于在 /v1/models 上公布费率的网关，改用 catalogFromProviderModels()，不要用快照——实际测试走的就是这条路径。
- 中国法定节假日默认是空列表。 工作日的峰时时段是对的；本该按谷时计费的节假日，在你把节假日加进去之前会按峰时计费。把猜测出来的节假日日历塞进计费路径，比老老实实留个缺口更糟。
- 峰时窗口可配置，但不感知服务商。 任何峰时规则不同的服务商，都需要在规则层改 peakMinutes。
- 本地账本不等于余额。 服务商没有额度查询端点时，每一次未定价的调用、每一次折扣、每一条我们不知道的计费规则，都会让 spentMicros 偏离真实值。实际测试中，网关因余额不足拒绝请求，而我们的账本显示还剩 84% 的预算。插件在说明剩余金额时，必须加上「就我所见」；/money 会显示有多少事件未定价。

- dsh 是开发者预览版，不承诺 ABI 稳定。@deepseek-ai/dsh-base 已锁定版本用于类型检查；alpha 标签之间预计会有变动。
- 缓存写入 token 按零计价，因为 DeepSeek 的提示词缓存是自动的、不单独计费。Anthropic 风格的服商按 1.25× 计费缓存写入，需要设置 perMillion.cacheWrite。
- 闸门只能在 dsh 允许的地方说话。 目前是 tools/pre-execute；要硬性限制单次请求，需要模型调用否决权，而 harness 把这项权力留给了自己的循环。

关于额度纪律，说清楚

这个插件没法让 harness 拒绝请求，也不会假装能。它做的是尽早把价格摆出来，让模型能选更省钱的方案，让你能选更便宜的档位，赶在 token 花光之前。

License

MIT