dsh-cost-meter

一句话定位

为 DeepSeek Harness 实时统计本会话与历史模型调用费用、官方账户余额、预算进度与峰谷计价档位，可选接入 OpenCode Go 订阅与多厂 Coding Plan 额度，并支持官方定价页一键同步。

核心能力

• 实时累计本会话费用：插件捕获每次模型调用的输入、缓存读 / 缓存写、输出与推理 token，按价格表逐次计费；徽章位置可在输入区下方与会话标题栏之间切换
• 全局账本与历史：按天聚合费用、调用次数与会话明细，保留最近 N 天（默认 180），今日 / 本月 / 累计卡片与类 Codex 的 26 周每日用量方格热图
• 预算图框与超支提醒：侧边栏底部圆角图框显示预算、已用百分比、今日费用与占预算百分比；≥80% 进度条变黄、≥100% 变红，仅提醒不阻断调用
• 官方账户余额：调用官方开放平台余额接口，复用模型请求同一把 API Key；侧边栏顶部或设置页可显示总余额 / 赠送 / 充值拆分，进程内缓存按刷新间隔过期
• 多档额度查询：OpenCode Go 滚动 5 小时 / 本周 / 本月三档用量百分比，叠加 Anthropic Claude、Z.ai / 智谱、MiniMax、Kimi / Moonshot、OpenRouter、SiliconFlow 六家 Coding Plan 额度
• 官方价格一键同步：抓取官方定价页解析基础价与峰谷两档，自动写入价表并保留历史价；提供 AI 提示词文档用于第三方厂商价格的人工核对流程

技术实现

• 语言: JavaScript（ESM，未启用 TypeScript；lib/ 下 5 个 .js 源文件 + 单文件浏览器 bundle）
• 关键依赖: zod（配置 / 状态 schema 校验）、@deepseek-ai/dsh-credentials（OpenCode Go / Coding Plan / 余额 Key 解析）、@deepseek-ai/dsh-home-paths（账本根目录解析）
• 架构模式: dual-half 宿主插件。Host half 通过 ctx.on('llm/stream', ...) 包裹模型流拦截 usage 块，按价格表写入账本；ctx.inject(['sessionProjections']) 注册 costUsage 会话投影（客户端按当前价表计价）；ctx.provide('costMeter', service) 暴露账本快照 / 配置 / 刷新 / 同步 / 重置 RPC，手写 typertRemote 绑定以匹配 Typert 网关校验。Client half 为单文件 bundle，注入 conversation.composer.dock、conversation.session.header.actions、sidebar.footer.action、settings.section 四个插槽；样式全部基于 --dsw-* 主题变量跟随亮 / 暗主题
• 入口文件: host 入口 lib/index.js（apply / name = 'cost-meter'）；客户端入口 lib/client.js；挂载声明 cordis.patch.yml（在 web profile 插入 1 行 Loader）+ package.json#dsh.bundle.patch

适用场景

当 DSH 用户希望对模型开销有可见的"账本感"——实时看到本会话与历史的费用走势、设置月度预算并被进度条预警、在设置页核对官方价格表、一次性查看 OpenCode Go 与多家 Coding Plan 的剩余额度。本插件把所有可计量面统一收口在一个"费用"设置分节内，免去在多个官方控制台之间反复切换。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Han-1413141/dsh-cost-meter

配置项

默认在 设置 → 费用 全部分节内可视化编辑；下方为可调字段一览（节选自 lib/store.js:27-95，所有字段均在 updateConfig RPC 中按 zod schema 校验后即时自动保存，600ms 防抖）。

常见问题

Q: 界面是中文还是英文？可以切换吗？

A: 简体中文 / English / 跟随浏览器（自动）三种。默认跟随浏览器（zh* → 中文、其余 → 英文），探测结果不持久化。在 设置 → 费用 → 显示设置 → 界面语言 中切换，整套界面即时生效并自动保存；服务端返回的余额、价格同步提示同样按当前语言展示。

Q: 安装后侧边栏没看到余额 / 显示异常怎么办？

A: 余额依赖 DSH 模型设置里的 DeepSeek API Key；首次启动请在 设置 → 模型 配好 Key 或导出 DEEPSEEK_API_KEY。余额端点强制只发往官方域名 api.deepseek.com，baseURL 指向非官方域名时余额查询会被拒绝（不影响模型调用）。余额默认 5 分钟自动刷新，可在 设置 → 费用 → 余额 显示位置关闭。

Q: OpenCode Go 或 Coding Plan 额度自动消失 / 显示"未启用"？

A: Go 额度需 DSH 凭据库或环境变量 OPENCODE_GO_API_KEY，未配置会在设置页以中性提示告知，不会变红。打开 设置 → 费用 → OpenCode Go 面板后即可启用；未订阅可关闭"启用"开关。各家 Coding Plan 类似：在对应面板填 Key 或配置环境变量，关闭"启用"即停用。

Q: 如何把官方最新价同步进来？同步会覆盖我的自定义价格吗？

A: 在 设置 → 费用 → 数据与同步 区域点 "从官方文档同步"，插件会抓取官方定价页解析后写入。只覆盖官方页面列出的同名模型条目，自定义模型条目不受影响；解析失败时同步会报错并保留原价格表，可手动编辑兜底。

Q: 预算到 100% 会停止模型调用吗？

A: 不会。预算与超支提示仅提醒，不阻止调用；≥80% 进度条变黄、≥100% 变红并在侧边栏底部预算图框显示超支徽章。需要硬性限制请自行在模型层处理。

Q: 数据存哪里？怎么清除全部历史？

A: 账本文件在 $DSH_HOME/storages/cost-meter/ledger.json，按 historyDays（默认 180 天）保留，每日最多 200 个会话明细；写入采用临时文件 + 原子重命名 + 2 秒防抖。清除：在 设置 → 费用 → 数据与同步 点 "清除全部历史"；也可手动删除 ledger.json。

Q: 如何卸载？

A: dsh plugin --profile web remove dsh-cost-meter，重启 dsh web 即可。插件不引入额外后台进程、不改 host 文件；账本文件留在 $DSH_HOME/storages/cost-meter/ledger.json，需要时手动删除。

Q: 安装 / 更新后页面没变化？

A: 安装或更新插件后必须重启 dsh web，插件行、Typert 清单与客户端 bundle 均在启动时扫描；只刷新浏览器不会重新装载服务端插件。

上手难度

入门 — 一条 dsh plugin add + 重启 dsh web 即在侧边栏与设置页看到费用面板；想体验官方价格同步需可访问 api-docs.deepseek.com。进阶处在于阅读 价格表 / 拓展价格表 / 多 provider 模型适配（参考 docs/model-and-plan-adaptation.md）并按厂商手动核对非 DeepSeek 模型价格。

已知问题与限制

• 官方定价页解析依赖当前页面结构：官方改版后"从官方文档同步价格"会报错并保留原价格表，可手动编辑价格表兜底
• 会话徽章按当前价格档位估算：精确费用以账本为准；历史调用的费用在 ledger 中已按调用时刻的价档精确记录
• 价格同步只覆盖官方页面列出的同名模型价格：自定义模型条目不受影响
• 余额查询强制官方域名白名单：仅 api.deepseek.com 接受，baseURL 指向非官方域名时余额查询被拒绝，模型请求不受影响
• OpenCode Go 额度接口为 opencode.ai/zen/go/v1/usage（社区文档）：接口结构变化时设置页会显示错误，可在 显示设置 中关闭该显示
• 安装 / 更新插件后必须重启 dsh web 生效：插件行、Typert 清单与客户端 bundle 均在启动时扫描
• 第三方 Coding Plan 部分仅余额可用：Anthropic OAuth、Z.ai / 智谱、MiniMax Token Plan 已实测有 usage 端点；Kimi Code 订阅周窗 / 5 小时窗暂无 API-Key 化公开端点，目前以 PAYG 余额窗口显示；百炼 Coding Plan / OpenAI Codex / Gemini Code Assist / GitHub Copilot 个人版暂无 API-Key 化用量端点，未接入

---

功能总览

自定义 Provider 余额配置示例(NewApi 模板)

自定义 Provider 余额的 extract 规则支持四种形式:数字常量、点路径字符串、add/subtract 多路径加减、divide 按 by 除数缩放。divide 适用于 NewApi 等以 quota 整数计量的端点(1 USD = 500000 quota,与 cc-switch 同款换算)。

以 NewApi 的 GET /api/usage/token 为例(响应 { "code": 200, "data": { "total_granted": ..., "total_used": ..., "total_available": ..., "unlimited_quota": false } }):

{
  "enabled": true,
  "display": "both",
  "refreshMinutes": 15,
  "label": "NewApi",
  "labelEn": "NewApi",
  "unit": "USD",
  "request": {
    "url": "https://你的NewApi域名/api/usage/token",
    "method": "GET",
    "headers": { "Authorization": "Bearer {{NEWAPI_API_KEY}}" }
  },
  "extract": {
    "remaining": { "op": "divide", "path": "data.total_available", "by": 500000 },
    "maxBudget": { "op": "divide", "path": "data.total_granted", "by": 500000 },
    "spend": { "op": "divide", "path": "data.total_used", "by": 500000 },
    "unit": "USD"
  }
}

• {{NEWAPI_API_KEY}} 从 DSH 凭据库或环境变量解析(仅请求头支持占位符,URL 需写死完整地址);
• 无限额度 token(unlimited_quota: true)没有 total_available,无法提取 remaining,查询会报「remaining is missing or not numeric」——请改用有限额度 token,或在中间层端点换算;
• 配置入口:设置 → 费用(额度标签)→「自定义 Provider 余额」展开配置;或直接改 storages/cost-meter/ledger.json 的 config.customBalance。

双语界面

插件界面(会话徽章、侧边栏余额与预算图框、设置页全部文案)支持简体中文与English:

• 语言可选 简体中文 / English / 跟随浏览器(自动);
• 默认「跟随浏览器」:自动探测浏览器语言(zh* → 中文,其余 → 英文),并把探测结果写回配置,服务端消息(余额查询、价格同步等)与界面语言保持一致;
• 在 设置 → 费用 → 显示设置 → 界面语言 中切换,切换后整个插件界面即时生效并自动保存;设置页左侧的分节标签也随之切换(费用 / Cost);
• 服务端返回的提示(余额刷新、官方价格同步、配置校验错误等)同样按当前语言输出。

图文演示

截图均取自真实 DeepSeek Harness 实例,默认以中文界面展示;插件界面本身中英双语,可在设置中切换为 English。

主页面

侧边栏底部(自上而下:官方余额 → 额度 / 预算图框 → 设置按钮):

• 余额行显示官方开放平台总余额,悬停可见赠送/充值拆分;开启「余额进度条」后以三段图框展示(蓝=余额,橙=当日,灰=已用);
• 自定义 Provider 余额(如 LiteLLM)可配置 HTTP 查询,侧边栏与设置页同图框样式;
• 未启用预算时,该位置显示「今日 ¥x」徽章。

余额进度条与自定义 Provider 配置:

• 显示设置 →「余额进度条」全局开关;可选「额度上限」覆盖 API 的 max_budget;
• 设置 → 费用 →「自定义 Provider 余额」:展开后编辑 URL / Headers(JSON) / extract(JSON)、中/英名称与币种。

额度 / 预算图框三态(OpenCode Go 额度与预算各自独立开关,同款圆角图框;两者同时开启时自动合并为一张卡片,Go 在上、预算在下,细分隔线、各自保留预警色;「图框详细信息」开关可收起次要行,只保留 标签 + 已用% + 进度条):

• 预算图框显示「预算 · 已用% · 进度条 · 今日费用与占预算% · 已用/额度」,≥80% 预警、≥100% 超支;窄栏(rail)模式收窄为百分比方块;
• 峰谷计价时段显示 UTC 峰时段 01:00–04:00、06:00–10:00 与当前档位;预算框与今日费用区域显示单行紧凑时段条——细轨道左橙右蓝、标记线指向当前时段,右侧文字为当前时段与距下次切换的倒计时(30 秒刷新),不显示价格;可在设置中单独关闭,并在「峰谷时段条样式」中切换简洁/经典两种样式;rail 窄栏显示同构的竖向时段条,下方横排短词「峰时 / 平价」,倒计时与完整文案悬停可见;

峰时/平价时段条与收起态竖向进度条:

时段条与收起态竖向条真实 DSH 侧边栏实拍(现行样式),按 UI 类型分组(图示为峰时):

不收起(展开态)——预算框 / 今日费用区域显示单行时段条:

• 简洁:细轨道左橙右蓝、标记线指向当前时段,右侧短文案「峰时 · N小时后进入平价」;
• 经典:同款轨道与标记线,右侧完整文案「峰时 · 距平价 HH:MM:SS」倒计时(30 秒刷新),不显示价格。

收起(rail 窄栏)——侧边栏底部堆叠竖向时段条,与百分比方块居中对齐:

• 简洁:竖向条下方仅横排短词「峰时 / 平价」;

• 经典:竖向条下方竖排完整文案,含距下次切换的倒计时;两种样式下完整文案均悬停可见。

• 提示遵循 peakNotice / peakEnabled / peakEffectiveAt / peakWindows 门控,按 UTC 峰时窗口显示;

• 设置 → 费用 → 峰谷计价 下可单独开关「峰时高价时段显著提示」,关闭后展开态时段条与收起态竖向条同时隐藏;

• 上方第一张为设置页峰谷面板截图(提示开关、样式切换与实时预览);时段条与收起态竖向条的实拍效果见上述分组配图;右下角(dock)各项开关与图框详细信息开关见第二张截图。

• Go 图框按主档位(默认滚动 5 小时,可在显示设置切换周/月)显示已用% 与进度条,下方一行展示其余两档与重置时间:

右下角(dock)额度 / 预算 chips(显示设置中开启,四项独立开关:5h / 周 / 月额度 + 预算已用%):

本会话费用(两个位置,可在设置中切换):

上图:本会话 ¥5.5939 · 输入 321K · 缓存 119M · 输出 235K;右图:标题栏徽章「费用 ¥6.1606」(真实会话截图)

设置 → 费用

概览(OpenCode Go 额度 → 预算 → 余额 → 汇总卡片 → 今日会话 → 历史记录 → 显示设置 → 价格表 → 数据与同步):

OpenCode Go 额度面板(设置页最顶部:三档进度条,主档位高亮,手动刷新;未订阅时为中性提示,可一键关闭):

预算面板(含自定义日期区间):

余额面板(总余额/赠送/充值 + 手动刷新):

显示设置(Go 主档位与 Key、右下角 chips、图框详细信息等):

汇总卡片:

Token 用量统计(历史累计总量 + 类 Codex 的 26 周方格热图,横向铺满设置页宽度;无用量日为半透明玻璃格):

今日会话 / 历史记录(输入、缓存、输出 token 分列):

价格表(谷时/峰时两档,支持 input/output 简写,美元 / 1M tokens):

数据与同步(配置即时自动保存 + 官方价格同步 + 清除历史):

安装

需求:Node.js ≥ 20 + DeepSeek Harness(带 dsh plugin 命令的版本,npm install -g @deepseek-ai/dsh)。

一键安装(推荐)

npm 包名安装(已发布到 npm registry,始终跟随最新版本;无需 git):

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

PowerShell 一键脚本(复制整行粘贴回车;自动补齐 pnpm、自动探测 git,无需克隆仓库;安装链固定到发布 tag v1.5.31,建议先下载审阅再运行):

irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.5.31/install.ps1 | iex

或直接命令行(机器上需已有 pnpm 与 git;同样固定到 tag):

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

没有 git 时可用 GitHub tag 打包直链:

dsh plugin --profile web add https://github.com/Han-1413141/dsh-cost-meter/archive/refs/tags/v1.5.31.tar.gz

安装后重启 dsh web(插件行、Typert 清单与客户端 bundle 均在启动时扫描):

dsh web

更新 / 卸载

# 更新:发布新版后用新版 install.ps1 重跑(脚本内固定版本随之更新)
dsh plugin --profile web remove dsh-cost-meter  # 卸载

开发者本地调试

git clone https://github.com/Han-1413141/dsh-cost-meter.git
cd <克隆目录的父目录>
dsh plugin --profile web add link:./dsh-cost-meter  # 符号链接,改 lib/client.js 后刷新页面即生效

计费规则

• 价格单位与官方文档一致:美元 / 1M tokens;
• 成本 = 未命中输入 × cache-miss + 输出 × output + (缓存读 + 缓存写) × cache-hit(缓存写沿用官方历史规则按命中价计费);
• 纯峰谷两档计价(2026-08 起官方方案):峰时段(01:00–04:00、06:00–10:00 UTC)按峰时价,其余按谷时价(谷时价 = 峰时价的一半);基础档与谷时档同价,未启用峰谷时按谷时价计;设置页实时显示当前档位(峰时段/谷时段);预算与今日费用区域显示峰时/平价时段条(当前/下一时段与倒计时),收起态显示竖向峰谷进度条;
• 历史计费正确性:2026-08-16 16:00 UTC(峰谷时代分界)之前的调用按当时的基础价计费,之后的调用按峰谷两档;
• 账本金额恒以美元存储,币种/汇率仅影响显示(默认 1 USD = 7.2 CNY,可改);
• 会话徽章与当日/月度/累计、预算一样,按每次调用的实际时刻精确计费(宿主导出的逐次成本);
• 计费来源为每次模型调用的 usage 块(含子代理、压缩、标题等辅助调用),与账单口径一致;
• 预算与超支提示仅提醒,不阻止调用。

数据存储

• 账本:$DSH_HOME/storages/cost-meter/ledger.json(原子写入 + 2 秒防抖;按 historyDays 保留,每日最多 200 个会话明细);
• 所有设置修改即时自动保存(600ms 防抖),无需手动保存;
• 删除账本文件即可清零,或使用设置页「清除全部历史」。

架构

dsh-cost-meter
├── cordis.patch.yml        # bundle 补丁:向 web profile 插入 cost-meter 行
├── install.ps1             # 一键安装/更新脚本(irm … | iex)
├── .github/workflows/      # CI:install-smoke 一键安装冒烟验证
├── package.json            # dsh.bundle 补丁声明 + dsh.client 浏览器声明
└── lib/
    ├── index.js            # 宿主插件:llm/stream 计费包裹、costUsage 会话投影、
    │                       #   costMeter 服务(手写 typertRemote 绑定)、余额查询
    ├── backfill.js         # 历史账本按模型回填:回放会话日志重建旧账本缺失的
    │                       #   byProviderModel(拼接 zstd frame 扫描 + 逐帧解压)
    ├── pricing.js          # 官方价格表、官方页面 HTML 解析、峰谷计费数学
    ├── store.js            # 账本持久化与配置管理($DSH_HOME/storages/cost-meter)
    ├── typert.host.js      # ./typert 导出:Typert 清单(typert-loader 自动注册)
    └── client.js           # ./client 导出:浏览器单文件 bundle(徽章/图框/设置页)

数据通道:

• 本会话费用:宿主注册 costUsage 会话投影(纯 token 桶 + 按模型拆分),浏览器经 useProjection('costUsage') 读取并按当前价格表计价;
• 全局账本 / 预算 / 余额 / 配置:costMeter/getState | updateConfig | fetchPrices | refreshBalance | resetHistory,经 Typert 网关 RPC(remote.costMeter.*);
• 余额:调用官方 GET {baseURL}/user/balance,复用模型请求的同一把 API Key(凭证服务/环境变量),进程内缓存按 refreshMinutes 过期。

插件不导入 cordis/dsh 的 Service/Context 运行时类(仅 Node 内建模块、zod、dsh-home-paths、dsh-credentials 的纯函数),与宿主共享同一运行时实例,无重复依赖风险。

官方价格同步原理

fetchPrices 抓取官方定价页(Docusaurus 服务端预渲染),解析:

1. 基础价格表(转置布局:首行 MODEL + 模型 id,价格行标签后紧跟价格);
2. 峰谷价格表(每模型两行:OFF-PEAK / PEAK);
3. 生效时间(take effect at …)与峰时段窗口(Peak hours are …)。

解析结果写入价格表并持久化;页面结构变化时同步报错并保留原价格,可手动编辑兜底。

AI 价格同步

docs/AI-PRICE-SYNC-PROMPT.md(中文)与 docs/AI-PRICE-SYNC-PROMPT.en.md(English) 提供可直接复制给任意 AI 的提示词: AI 自主读取官方定价 → 输出多模型、分时(基础/谷时/峰时 + 生效时间)价格 JSON → 人工核对后应用(设置页 / RPC / 文件三选一)。适合官方价格变动时自主同步。

开发与验证

corepack pnpm install                                   # 依赖
node --check lib/index.js && node --check lib/pricing.js \
  && node --check lib/store.js && node --check lib/typert.host.js \
  && node --check lib/client.js                         # 语法检查
node test/verify.mjs                                    # 纯模块验证(解析/计费/账本/配置)
node test/mock-balance.mjs                              # (可选)本地余额接口模拟:3101
dsh --profile web --dump-config                         # 组合树校验
dsh --profile web --port 3099                           # 真机启动(观察启动日志与 UI)

已知限制

• 历史按模型回填依赖宿主会话日志仍在盘:日志已被清理的早期调用无法逐模型重建,只能以「未分模型」残差行计入当日合计;
• 官方页面解析依赖当前页面结构;改版后「从官方文档同步价格」会报错,可手动编辑价格表兜底;
• 会话徽章按当前价格档位估算,精确费用以账本为准;
• 价格同步会覆盖官方页面列出的同名模型价格,自定义模型条目不受影响;
• 余额查询需要可访问 api.deepseek.com 的网络与有效 API Key;API Key 只会发往官方域名(baseURL 指向非官方域名时余额查询拒绝请求,模型请求不受影响);
• OpenCode Go 额度接口为 opencode.ai 官方端点(社区文档);接口结构变化时设置页会显示错误,可在显示设置中关闭该显示;
• 安装/更新插件后需重启 dsh web 生效。

更新历史

各版本更新总览与社区 issue 处理记录见 docs/UPDATE-HISTORY.md;逐条开发记录见 CHANGELOG.md。

License

MIT © 2026 dsh-cost-meter contributors