dsh-cost-meter 使用指南: Token 计费、预算与价格校准

Agent 的费用很难靠“对话次数”判断。一次请求可能包含大量缓存输入、少量新输入、推理 token、输出 token，还可能触发标题生成、上下文压缩和子代理。不同 provider 对相同模型名的价格也可能不同。只看聊天窗口里的 token 总数，很容易把“用量高但缓存便宜”和“输出少但输入昂贵”混为一谈。

dsh-cost-meter 是 DeepSeek Harness 的本地费用与额度插件。它记录每次模型调用的 usage，按 provider 与 model 匹配价格，维护本地账本，并在 Web UI 显示会话费用、日/月累计、预算、余额、价格档位和 Coding Plan 额度。本文基于 Han-1413141/dsh-cost-meter 的 v1.6.11。

本轮对该版本执行了真实仓库验证：依赖锁定检查通过，官方价格页能够抓取和解析，计费数学、峰谷窗口、账本、历史回填、provider 匹配、Plan/API 分类、凭据脱敏和多家额度适配的测试全部通过。测试通过不代表你的账单一定一致。网络、账号币种、代理 provider、历史日志完整度和自定义价格都会改变最终结果。因此，教程重点是建立“插件账本—官方账单—调用日志”的三方对账流程。

它解决什么，不解决什么

插件适合回答：

• 当前会话花了多少按量费用。
• 今天、本月和累计用了多少。
• 输入、缓存读取、缓存写入、输出和 reasoning token 各有多少。
• 哪个 provider 与 model 贡献了主要成本。
• 预算使用到什么位置。
• 已启用的 Coding Plan 额度还剩多少。
• 官方价格变化后，历史账本如何换基准。

它不负责限制模型调用。预算达到 80% 或 100% 时可以提示，但不会强制阻断请求。它也不是官方账单系统。插件记录的是 DSH 能看到的 usage；同一 API Key 在其他机器和工具上的消耗不会自动进入本地账本。

如果你还在搭 Harness 基础环境，先看 DeepSeek Harness 桌面版、DeepSeek Harness 部署故障 和 DeepSeek Provider 配置指南。费用插件应在模型调用已经稳定之后安装。

安装前备份

仓库要求 Node.js 至少为 20，DSH 兼容范围从 0.1.0-rc.5 起。先检查：

node --version
dsh --version
dsh --profile web --dump-config

再备份 DSH 配置与账本目录：

$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$dshHome = Join-Path $HOME '.dsh'
$backup = Join-Path $HOME ".dsh-backup-$stamp"
Copy-Item $dshHome $backup -Recurse

安装脚本和插件都可能更新 profile。账本一旦开始记录，也需要独立备份。不要等出现数据异常后才第一次复制。

选择可审计的安装方式

首选已发布的 npm 包：

dsh plugin --profile web add dsh-cost-meter

如果你要固定版本，使用发布 tag：

dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.6.11

仓库也提供远程 PowerShell 一键脚本。远程脚本会执行安装操作，不应直接盲跑。至少先下载、审阅，再执行。对长期环境，固定 tag 比跟随 main 更容易回滚。

安装后重启 dsh web。刷新页面后，“设置 → 费用”应出现费用、用量、价格和显示设置。侧边栏底部会出现本会话或今日费用组件，具体位置由配置决定。

安装失败：minimum release age

如果 pnpm 报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION，说明 profile 的供应链策略拒绝过新的依赖版本。v1.6.11 已把运行时依赖改成精确版本，正常不应再触发旧问题。如果错误来自其他插件，不要关闭整个供应链保护。应根据错误指向，在 profile 的 pnpm-workspace.yaml 中只排除必要条目，然后重试。

第一步：先建立正确的价格口径

不要一安装就相信金额。先进入“设置 → 费用 → 价格表”，决定三个口径：

1. 官方价格币种用美元还是人民币。
2. 模型匹配用 auto 还是 exact。
3. 当前 provider/model 属于按量 API 还是订阅 Plan。

官方价格同步

插件可以抓取 DeepSeek 官方定价页，解析基础价格、峰谷价格和时间窗口。同步失败时会保留原价格，不会用空表覆盖。

同步后检查三个字段：

• 当前模型 id 是否与实际请求一致。
• 缓存命中、未命中和输出价格是否齐全。
• 当前显示币种是否与官方账户账单币种一致。

不要把本文中的任何价格数字抄进配置。官方价格会变。正确做法是从官方页同步，再人工核对一笔请求。

provider + model 双键

同一个模型名可能通过官方 API、OpenRouter、OpenCode 或内部网关调用。插件按 provider + model 查价格，避免不同渠道串价。

自动匹配顺序包括精确匹配、手动覆盖、归一化、去版本后缀、前缀和模型家族。它方便，但也可能在自定义网关下选到不符合合同价格的条目。发现“金额不是零但模型未配置”时，检查最近未精确命中的模型列表，手工指定价格条目。

生产环境建议：

• 已知固定模型使用 exact。
• 模型 id 经常带日期和路由后缀时使用 auto，并审查未精确命中列表。
• 本地模型应明确归类为零成本或手工覆盖，不要让它套用云端默认价。

第二步：用一笔最小请求校准

新建空会话，只发一个短问题。记录请求前后的官方余额或账单增量，再看插件的会话徽章。

校准顺序：

1. 确认调用次数增加 1。
2. 确认 provider 和 model 正确。
3. 确认 input、cacheRead、cacheWrite、output 与接口 usage 基本对应。
4. 确认请求发起时刻落在正确价格档位。
5. 以金额对账，不要求 token 三列与官方页面逐字相同。

Reasoning token 可能单独上报但不计费。流式请求跨过峰谷边界时，插件按请求发起时刻计价。账本有 2 秒防抖写入，官方账单也可能有分钟级延迟。短时间的小差异不等于计算错误。

如果你同时使用多个模型，可参考 DeepSeek 与 Gemini 代码审查对比 和 DeepSeek 与 Grok 工具调用对比，但价格必须回到各自 provider 的真实账单核对。

第三步：设置预算，但别把提醒当限流

预算可按今天、本月、累计或自定义日期区间设置。建议先用“本月”，并把额度设为真实可接受的按量支出。

界面会显示预算已用百分比，达到 80% 进入预警，达到 100% 显示超支。这个状态只用于提醒。模型调用不会被阻止。

真正的硬上限应在 provider、网关或账户侧设置。插件预算适合做可见性层：

• 让你发现某个会话突然变贵。
• 让你看到缓存策略是否有效。
• 让你比较不同模型或工作流。
• 在共享屏幕时隐藏余额和今日消耗。

如果你正在设计长链路 Agent，可结合 多智能体高 Token 消耗案例 和 Agent 上下文压缩修复 判断成本来自循环、上下文还是模型单价。

第四步：分开 Plan 等值与 API 真金白银

订阅制 Coding Plan 没有逐请求扣费，但仍消耗额度。插件用两套金额：

• cost：按参考价格计算的等值金额。
• apiCost：实际按量 API 口径。

预算、今日费用和概览默认只统计 apiCost。打开“含 Plan 总额”后，才把订阅等值加入汇总。

分类优先级是模型级覆盖、provider 级配置、自动判断。混合使用最容易出错。例如同一家同时有订阅 Key 和 PAYG Key，自动归类可能无法知道某一条请求走哪种合同。此时应按 provider:model 手工覆盖。

Coding Plan 百分比来自厂商接口或本地估算。插件可以估算每 1% 额度对应的 token 与等值金额，但它受百分比量化和外部工具消耗影响。结果适合横向比较，不适合当财务结算。

站内的 Claude Code 用量计算 和 Codex 额度对比 可以帮助理解订阅窗口，但插件显示仍应以当前账户接口为准。

第五步：理解账本和历史回填

账本默认位于：

$DSH_HOME/storages/cost-meter/ledger.json

写入采用原子替换和 2 秒防抖。配置也保存在账本结构中。首次安装会回放 DSH 会话日志，把安装前的历史调用导入账本。已有日期只补未知会话，避免重复计费。

历史回填有边界：

• 会话日志已经删除时，早期数据只能进入“未分模型”残差。
• 旧事件按历史价格还是当前价格，取决于回填与换基准规则。
• 切换官方价格币种后，日志完整的日期会按新基准重算。
• Fork 会话和包装路由存在重复 usage 风险，插件有去重逻辑，但仍应抽查异常大额会话。

建议每天备份一次 ledger.json，保留最近 7 份。不要用同步工具同时在两台机器写同一个账本文件。

如果需要归零，优先在设置页使用“清除全部历史”。直接删除文件也能重建，但会同时失去预算、价格覆盖和部分配置。操作前必须备份。

余额与凭据边界

DeepSeek 官方余额查询只接受官方域名。Base URL 指向非官方域名时，插件会拒绝余额请求，模型调用本身不受影响。

各 Coding Plan 的凭据只发往代码中的官方域名白名单。API Key 保存在 DSH 凭据库，不写入账本，设置页输入框保存后不回显。

“自定义 Provider 余额”不同。它允许用户配置任意 HTTP 端点和请求头。你把密钥放进 {{ENV_VAR}} 后，它会发往你填写的地址。使用前应检查：

1. URL 是否是你控制或信任的域名。
2. 是否必须发送完整 Key。
3. 响应是否包含不应进入前端的数据。
4. extract 路径是否可能把错误响应解析成 0。

可配置不等于安全。内部网关建议提供一个只读余额 Token，不要复用拥有模型调用权限的主 Key。

常见问题排查

会话费用为零

先看调用是否有 usage。再检查 provider/model 是否命中价格表、本地模型是否被零成本规则识别、该渠道是否被归为 Plan。不要先手工填一个默认高价。

金额突然翻倍

检查是否存在包装路由与直连两条 usage 记录、是否切换币种后重复换算、同一会话是否被历史回填和实时流重复计入。查看按会话明细比看总额更容易定位。

官方价格同步失败

官方页面结构可能变化。插件会保留旧价格。先手工核对价格表，再等上游解析器更新。不要在同步失败时清空账本。

今日费用不更新

确认页面可见、Web UI 与 host 连接正常、插件版本和客户端 bundle 一致。页面从后台恢复后应触发刷新。仍冻结时，重启前先记录账本修改时间。

账本与官方账单有差异

检查分钟级延迟、币种、峰谷时刻、其他机器共享 Key、在途流式请求和日志缺失。对账优先看金额，再看 token 桶。

更新与卸载

更新前先复制账本。固定 tag 安装时，升级到新 tag 后重启 Web profile，并用一笔最小请求重新校准。

卸载：

dsh plugin --profile web remove dsh-cost-meter

卸载插件不会自动证明账本已删除。若计划重装，应保留账本。若要彻底清理，确认备份后再删除 storages/cost-meter。不要递归删除整个 DSH_HOME。

相关阅读

• DeepSeek Harness 插件管理器
• DeepSeek Harness 插件目录
• DeepSeek Harness Rust 插件
• DeepSeek Harness AgentOS
• DeepSeek Harness Diff 插件
• DeepSeek Harness Tavily 搜索插件
• DSH MCP 管理面板
• DeepSeek Harness 插件市场

一手资料

• dsh-cost-meter GitHub 仓库
• 模型与 Coding Plan 适配说明
• DeepSeek Harness 官方仓库

dsh-cost-meter 最有价值的不是界面上的金额，而是把调用、价格、账本和预算放进同一条可核对链路。先校准一笔，再逐步开启历史回填、余额和 Coding Plan，得到的数据会比一开始把所有开关都打开更可靠。