前言¶
用 DeepSeek Harness（DSH）走 OpenRouter 做推理时，会话里常见的 token 统计只能反映用量，不能直接对应 OpenRouter 账户里「实际扣了多少钱」。本地按价目表估算也会和账单有偏差。下面介绍社区插件 dsh-openrouter-spend：它通过 OpenRouter 自带的 Analytics API 拉取 total_usage（USD 实扣），在 Composer 下方和 Settings 里展示当日花费、按 key / 模型拆分，以及预付余额等汇总信息。
这是什么¶
dsh-openrouter-spend 是 DeepSeek Harness 的 Web 侧插件，维护者为 RyabykinIlya，在 SkillHub 目录 中归类为「模型推理」。当前 npm 版本为 0.6.0，许可证 MIT，依赖 Node >= 22.19。
插件声明的数据来源是 OpenRouter 官方接口上的计费结果，而不是本地 token 乘单价。数字含义在 README 中有明确定义：花费来自 POST /api/v1/analytics/query 按 UTC 日、API key、模型分组的 total_usage；「今天」指当前 UTC 日；余额来自 GET /api/v1/credits 的 total_credits − total_usage。
核心功能¶
Composer 下方的 spend chip¶
输入框下方会出现一块 spend chip，展示 session/day：当前会话在今天、在所选 API key 上的花费，以及该 key 在今天同一 key 维度上的总花费。两者始终对应同一把 key（见仓库 ADR 0006）。chip 与会话的 token、上下文统计并列显示。
Popover 明细¶
点击 chip 打开 popover，可设置时间范围与 API key 筛选，查看当日各模型花费、窗口内按日柱状图，以及预付余额与 lifetime spend。0.4.0 起增加了额度相关提示与刷新失败时的展示；README 中附有 limit-notice 的 mockup 说明。
Settings → OpenRouter spend¶
在此保存或清除 Management API key，选择展示货币（USD，或按 cbr.ru 汇率换算的 RUB），设置刷新间隔，并按 API key 过滤。查看类偏好（展示货币、按 key 过滤、刷新间隔覆盖、额度警告开关）保存在浏览器 localStorage；额度警告默认关闭，需在 Settings 中手动开启。
额度与余额警告（可选）¶
开启额度警告后，popover 会显示被跟踪 key 的限额剩余：已消耗比例、按当前节奏剩余可用时长、以及 cap 何时重置。chip 上的圆点会在接近上限时由琥珀色变为红色，并在等级升高时 toast 一次。
账户预付余额按「跑道」判断：当余额按账户中位节奏买不到三天（不足一天或按最近三天均值处于 critical）时，圆点告警；popover 余额区块会给出类似 $6.58 left · under a day at this rate · shared by all keys 的表述，并 toast 提示充值（见 ADR 0007、0010）。
一键提高 key 限额¶
popover 中的 limit 区块与相关 toast 支持通过同一 Management key 提高该 key 的 spend limit：仅允许提高且最多为当前 cap 的 10 倍；无 limit 的 key 需先在 OpenRouter 侧设置。建议金额随消耗节奏变化；展示货币为只读 echo（cbr.ru 不可达时不显示 RUB echo）。见 ADR 0008。
刷新与多标签¶
宿主侧按 refreshSeconds 缓存摘要并合并并发刷新，多标签在同一刷新窗口内只向 OpenRouter 发起一次查询。刷新失败时保留上次成功数据，popover 显示原因、下次自动重试倒计时（首次失败后 15 秒，再 30 秒，之后为常规定时），并提供 Retry now。
安装与启用¶
运行环境需为 DeepSeek Harness web profile；插件依赖 credentials、webServer、connection 服务，在无这些服务的 profile（例如 headless）中保持未激活。
除 Management API key 外，普通推理 key 不能用于管理接口；错误示例：403 Only management keys can perform this operation。Management key 在 OpenRouter 控制台 Settings → Management API Keys → Create New Key 创建（见 OpenRouter 文档）。
从 npm 安装（web 为默认 Web GUI profile；若使用其他 profile 请替换名称）：
dsh plugin --profile web add dsh-openrouter-spend
从 GitHub 安装指定标签（纯 JavaScript，无需构建）：
dsh plugin --profile web add github:RyabykinIlya/dsh-openrouter-spend#v0.6.0
安装完成后打开 Settings → OpenRouter spend，粘贴 Management API key。
配置说明¶
各字段可在 profile 的 cordis.patch.yml 中覆盖；激活时 schema 会校验并指出非法字段。下表摘自 README，默认与边界以仓库为准。
| 字段 | 默认 | 含义（摘要） |
|---|---|---|
credentialRef |
OPENROUTER_MGMT_API_KEY |
存放 Management key 的 credentials 引用 |
apiBase |
https://openrouter.ai/api/v1 |
OpenRouter REST 根 URL |
refreshSeconds |
60（10–3600） |
OpenRouter 摘要刷新间隔（秒） |
historyDays |
30（2–366） |
摘要窗口历史天数（含今天） |
cbrUrl |
https://www.cbr.ru/scripts/XML_daily.asp |
RUB 汇率来源 |
rateRefreshSeconds |
3600（60–86400） |
汇率读取间隔 |
timeoutMs |
15000（1000–120000） |
对 OpenRouter / cbr.ru 的单请求超时 |
warnConsumedFraction |
0.4 |
周期 cap 消耗比例达此值进入 warning |
criticalConsumedFraction |
0.8 |
达此值进入 critical |
burnWindowDays |
7（1–30） |
估算 runway 时读取的 trailing 天数 |
burnWindowDays 按小时、按 key 读取；超过 5000 行会拒绝读取而非截断，runway 估算会报告拒绝并指向该设置，缩小 burnWindowDays 为修复方式。7 天、30 天范围最多覆盖 historyDays 天；若要完整 30 天窗口，需保持 historyDays ≥ 30。
适用场景与注意¶
适合已经在 DSH Web 里用 OpenRouter、且希望 Composer 旁就能看到与账单一致的当日花费、模型与 key 维度分析，并在 Settings 里管理 Management key 与展示偏好的开发者。
安装前建议自行查看 GitHub 仓库 源码与 MIT 许可证。DSH 插件在当前 dsh 进程权限下运行；Management key 具备账户管理能力，应通过 credentials 引用妥善存放，勿提交到版本库。
SkillHub 等社区目录与 DeepSeek / 幻方无官方从属关系，插件由维护者独立发布；DeepSeek Harness 本身遵循「一切皆插件」的扩展方式，本插件是其中面向 OpenRouter 计费可视化的一个实现。
