用量与消耗 feiyang-dev/dsh-usage-plugin

DeepSeek Harness 用量与费用追踪器（dsh-usage-plugin）

English · 简体中文

GitHub · npm · MIT License

DeepSeek Harness 社区插件 —— 记录每次模型调用的 token 用量与费用，支持高峰/低谷计费、余额查询、日历热力图，以及 CSV / JSON / PNG 导出。

🔔 重要通知（2026-08-16）：npm 包已改名

npm 包已从 @feiyang666/deepseekharnessdesktop 改名为 @feiyang666/dsh-usage-plugin（与 GitHub 仓库 feiyang-dev/dsh-usage-plugin 保持一致）。

- 安装 / 升级请使用新包名：dsh plugin --profile web add @feiyang666/dsh-usage-plugin
- 旧包 @feiyang666/deepseekharnessdesktop 还会保留一段时间，但不再维护，也不会再收到更新 —— 请尽快迁移。
- 桌面客户端（DeepSeek Harness Desktop）同时支持两个包名，会自动识别用旧包名安装的版本，并支持一键更新到新包名。

概述

dsh-usage-plugin 是 DeepSeek Harness 生态里的用量与费用追踪器插件（DSH 插件，以 Host + Client 二合一包的形式发布）。安装后，Web UI 中「对话」和「Trace」之后会多出「用量与费用」和「余额查询」两个标签页：

支持 Windows / macOS / Linux：路径按平台处理（node:path），文件夹选择器和「在文件管理器中显示」使用各系统的原生机制（macOS：osascript / open；Linux：zenity / xdg-open）。余额查询与导出不依赖 Windows 专有命令。
- 用量与费用：记录每次模型调用的 token 用量与缓存命中情况（输入未命中 / 缓存命中 / 缓存写入 / 输出 / 推理 / 结束原因），并按 DeepSeek 的高峰/低谷价或基础价计算费用（工作日高峰时段按北京时间 09:00–12:00、14:00–18:00 自动计价；自 2026-08-23 起周末全部按低谷价计费；自北京时间 2026-09-10 12:00 起适用 V4.1-Flash 之后的高峰/低谷价 —— deepseek-flash 低谷缓存命中 0.02 / 输入 1 / 输出 4 元，高峰翻倍）。模型名取自实际请求参数，所以非 DeepSeek 模型会如实显示，而不是「unknown model」；没有官方定价的模型按 0 计。总览里有按模型分组的表格，还有按 API 服务商 × 模型的钻取（每个服务商下汇总各模型的调用次数与高峰/低谷费用拆分），以及一行总计。总览还支持日期筛选（今天 / 最近 7 天 / 最近 30 天 / 全部，外加自定义起止范围），可以把聚合统计限定到任意一天或任意日期区间。
- 用量日历：按月展示每日用量热力图（按费用或调用次数着色），悬停查看详情，包括高峰/低谷费用拆分；点击某天查看当天调用列表与高峰/低谷合计，还有按天统计表，含高峰费用 / 低谷费用 / 总计三列与汇总行。支持日期范围筛选（今天 / 7 天 / 30 天 / 全部，外加自定义起止日期）：范围生效时，每日统计表会跨月显示范围内每一天，顶部卡片切换为「范围内调用次数 / 范围内费用」并显示范围合计，热力图也只给范围内的日期着色。
- 缓存命中列表：最新在前，可完整滚动，带快捷筛选（今天 / 7 天 / 30 天 / 全部）和自定义日期范围；摘要行与页脚合计会拆分高峰与低谷消耗，并给出费用总计。列表分页显示（每页 100 行），数据量再大也很流畅。
- 中断的调用如实展示：被中止 / 出错 / 超时的调用（比如手动停止生成、流中断）会显示红色 「已中断」 徽标、结束原因（Interrupted / Error / Timeout）以及 — 费用。官方控制台仍把这些算作 API 请求并按其实际 token 计费，但 harness 不会把它们的用量上报给插件 —— 所以插件按 0 token 记录，从而让调用次数与官方控制台保持一致，费用也不受影响。总览的「调用次数」卡片会多一行 · interrupted N (not billed) 提示。
- 本地统计 vs 官方控制台：面板顶部有固定提示条，说明这个面板只反映插件在本地捕获的调用（官方价格 + 高峰/低谷时段），而官方控制台（platform.deepseek.com 用量页面）显示金额可能更高，原因有三：① 中断、失败、超时的调用官方控制台照样计费，插件记为 0；② 你账号下其他 API key 的调用（其他应用、脚本）不经过 DeepSeek Harness——控制台算进去，插件不算；③ 想精确对账，导出官方月度账单 CSV 再比对。检测到中断调用时，提示条还会多出一行红色文字「当前记录包含 N 次中断调用（未计费）」。
- 价格表：官方 DeepSeek API 价格表（覆盖 deepseek-flash = DeepSeek-V4.1-Flash 和 deepseek-v4-pro；旧 id deepseek-v4-flash / deepseek-v4-flash-vision-exp 仍可调用，归入 Flash 档）——基础单价与高峰/低谷单价并排展示（高峰 vs 低谷）。高峰/低谷价格表按日期分段：第一版从 2026-08-17 起生效，V4.1-Flash 之后的新版从北京时间 2026-09-10 12:00 起生效（deepseek-flash 低谷价降为缓存命中 0.02 / 输入 1 / 输出 4 元，高峰价翻倍；deepseek-v4-pro 不变）——历史调用一律按当时生效的版本计费。可在面板内编辑，保存到 pricing.json，并提供恢复默认值选项。
- 余额查询：用配置好的 DEEPSEEK_API_KEY 查询你的 DeepSeek 账号余额。
- 导出：CSV / JSON / PNG 长图（最新在前，最多 2000 条记录，超出会提示；PNG 报告包含高峰/低谷费用列），可导出到任意目录（系统原生选择器），导出后自动打开所在文件夹。
- 导入：合并导入 JSON / CSV 文件，按时间去重。
- 持久化：记录实时写入 <session workspace>/dsh-usage/usage-records.json，重启后自动恢复（上限 100000 条）。
- 界面适配：面板字号跟随应用的显示大小设置缩放（em 相对字体）；宽表格在桌面端横向滚动（max-content + overflow-x），移动端适配屏幕宽度（≤900px，无横向滚动条）；弹窗卡片自适应视口。
- 英文界面（i18n）：面板跟随 harness 自身的语言设置（General Settings → Language）——在那里切换，插件立即跟随，无需单独开关，也不用 localStorage 覆盖。双语词典覆盖整个面板、高峰/低谷计费时段提示、余额查询和 PNG 报告；宿主层的 Conversation/Settings 标签文字每次渲染都重新读取，因此能实时跟随语言切换。
- 每条消息的 token 弹窗：一轮结束后，助手消息的底部操作栏会显示 「Turn tokens」 按钮；点击打开 Token Details 弹窗，分两层——Conversation total（整个会话的总 token / 总费用 / 运行时长 / 缓存命中率）和 This turn（本次输出的 token、本轮 token、本轮费用、本轮耗时、本轮缓存命中率、缓存命中条，以及按模型分组的卡片，展示每个模型的输入·未命中 / 缓存命中 / 输出（+ 推理）及其高峰 / 低谷费用拆分）。时长显示为 Xm Ys。每条用量记录都带会话标记（sessionId），所以按轮统计和按会话统计各自独立计算。
- 内部 / 工具调用单独分组：内部调用 / 占位调用（例如 dsh2shell-*，模型为 fake）不计入模型费用明细，而是收在明细下方一个可折叠的 「Tool calls (internal)」 分组里，这样费用表里只统计真正的模型调用。
- 移动端适配：屏幕宽度 ≤900px 时表格自适应屏幕宽度（没有横向滚动条）；宽表格会折叠中间列；弹窗及其统计卡片 / 按模型分组的卡片都随视口自适应。

截图

用量与消耗

用量与消耗

余额查询

余额查询

推荐安装方式

两种方式都可用，效果一样。推荐用桌面应用——全图形界面，不需要命令行。

方式一（推荐）：用桌面应用一键安装

安装 DeepSeek Harness Desktop，打开后进入 「Install Plugins」→ Recommended → Usage & Cost Tracker → Install，再点 「Restart Service Now」 即可生效。

方式二：命令行

Prerequisite: install dsh (npm install -g @deepseek-ai/dsh)
dsh plugin --profile web add @feiyang666/dsh-usage-plugin

或者装到其他配置档：

dsh plugin --profile web add @feiyang666/dsh-usage-plugin
dsh plugin --profile headless add @feiyang666/dsh-usage-plugin

安装后重启 dsh web 服务。下面还有详细的手动安装 / 接线 / 卸载 / 排错说明。

包里有什么

一个 npm 包 = 一个宿主端（Node 侧 Cordis 插件：记录、计费、余额查询、导出——见 lib/index.js）+ 一个客户端（浏览器侧面板——见 lib/client.js，通过 /usage/api 与宿主端通信）。

这个包通过两项声明接入 DSH：

| 声明 | 用途 |
| dsh.bundle.patch（cordis.patch.yml） | 让 DSH 把它识别为标准 bundle 插件包：dsh plugin --profile <name> add <package> 一条命令即可安装并接线，不用手动改配置 |
| dsh.client + exports["./client"] | 让 web 客户端自动加载浏览器面板，路径为 /plugins/<package>/client.js |
对用户来说，安装只需一条命令 —— 不用编辑 YAML，不用手动复制文件。

安装（面向用户）

0. 前置条件

- 已安装 DeepSeek Harness（npm install -g @deepseek-ai/dsh，或基于它构建的桌面应用，或 npx @deepseek-ai/dsh web）。
- 方式 A（推荐）需要 pnpm：npm install -g pnpm（或 corepack enable）。
- 确认 dsh 在 PATH 中（桌面应用请在其内置终端里运行）。

1. 方式 A（推荐）：一条命令

dsh plugin --profile web add @feiyang666/dsh-usage-plugin

这条命令做三件事（全自动）：

1. 用 pnpm 把包安装到 ~/.dsh/profiles/web（首次使用时自动初始化配置档）；
2. 检测包里的 dsh.bundle 声明，把包名写入配置档的 dsh.profile.bundles 层列表；
3. 重启后，DSH 读取包里的 cordis.patch.yml，把插件行挂载到应用树中 —— 不用手动改配置。

其他配置档同理（把 web 换成你的配置档名，例如 dsh plugin --profile headless add ...；dsh web 等价于 dsh --profile web）。

测试本地 tarball：dsh plugin --profile web add C:\path\to\feiyang666-dsh-usage-plugin-1.9.0.tgz

2. 方式 B：手动安装（没有 pnpm / 不用 dsh plugin）

只在你没有 pnpm，或想完全手动控制时使用。不要在 ~/.dsh/profiles 直接 npm install（那个目录没有 package.json；npm 会把整个 node_modules 当成残留清掉）。

B1. 用 pnpm 但不用 dsh plugin：

cd ~/.dsh/profiles/web
pnpm add @feiyang666/dsh-usage-plugin
then manually append the plugin row to web/cordis.patch.yml (see B3) and restart

B2. 或者用 npm： 先给配置档加一个最小 package.json，再安装：

cd ~/.dsh/profiles/web
if no package.json exists there yet (only after dsh plugin init):
echo '{"name":"dsh-profile-web","private":true,"dependencies":{}}' > package.json
npm install @feiyang666/dsh-usage-plugin

B3. 接好线（一次即可，幂等）： 追加到 ~/.dsh/profiles/web/cordis.patch.yml：

- insert:
- id: usage-plugin
name: '@feiyang666/dsh-usage-plugin'
inject:
- fs
- webServer
- subprocess
- credentials
- sandboxPolicy
- agents

或者直接运行包内置的接线脚本（自动找到配置档并追加，幂等）：

node node_modules/@feiyang666/dsh-usage-plugin/scripts/wire.js

⚠️ inject 列表是必需的：它让 Cordis 等到 fs / webServer / subprocess / credentials / sandboxPolicy / agents 就绪后再激活插件。少了它，/usage/api 路由永远不会注册，面板会报 Unexpected end of JSON input。

3. 方式 C：桌面应用

桌面应用（比如 DeepSeek Harness Desktop）底层用的也是同一个 ~/.dsh/profiles。在任意终端里跑一遍方法 A 的命令，重启应用，插件就会自动生效（应用启动的也是同一个 dsh web）。

4. 重启并验证

重启 DeepSeek Harness web 应用（命令行：杀掉旧进程，重新跑 dsh web；桌面端：完全退出再打开）。然后：

- 刷新 http://127.0.0.1:3080 —— 在「Conversation」和「Trace」之后，你应该能看到 「Usage & Cost」 和 「Balance Query」 两个标签页；设置里也会多出对应条目。
- 「Usage & Cost」面板里有 Overview / Usage Calendar / Cache Hit List / Price Table 几个子标签。
- 发一条消息，「Usage & Cost」面板应该会显示这次调用的 token / 费用记录。

5. 配置（余额查询用）

「Balance Query」用的是配置好的 DEEPSEEK_API_KEY：在 Settings → Models 里填好 API Key（跟聊天用的是同一个 key），然后打开「Balance Query」标签页，点「Query Balance」。

卸载

dsh plugin --profile web remove @feiyang666/dsh-usage-plugin

（等同于 pnpm remove；dsh plugin 会自动把包名从 dsh.profile.bundles 层列表里删掉。）之后重启应用。

手动安装的（方法 B）就反过来操作：先从 cordis.patch.yml 里删掉 usage-plugin 那一行，再 pnpm remove / npm uninstall 这个包，然后重启。

从 1.0.x 手动接线安装升级到 1.1.x：先删掉 cordis.patch.yml 里旧的 usage-plugin 那一行（或者按卸载流程走），再用方法 A 重装，免得插件被挂载两次。

如何更新

发布走的是 npm，所以更新就是拉最新发布的包。你的使用历史是安全的 —— 从 v1.9.2 起它存在固定的专用目录里（不在任何 profile / workspace 里），更新永远不会把它清掉。

桌面应用

打开 「Install Plugins」 → 找到 Usage & Cost Tracker → 点 Update（或 Re-install）→ 「Restart Service Now」。如果没有 Update 按钮，就先移除再重新添加。

命令行（方法 A）

重跑 add 是幂等的，会拉最新版本：

dsh plugin --profile web add @feiyang666/dsh-usage-plugin
dsh web # restart

锁定某个版本：

dsh plugin --profile web add @feiyang666/dsh-usage-plugin@1.9.3

手动安装（方法 B）

在 profile 目录里：

cd ~/.dsh/profiles/web
pnpm update @feiyang666/dsh-usage-plugin # or: npm update @feiyang666/dsh-usage-plugin

查看已安装的版本

npm ls @feiyang666/dsh-usage-plugin --prefix ~/.dsh/profiles/web
⚠️ 不要手动编辑 ~/.dsh/profiles/web/node_modules/@feiyang666/dsh-usage-plugin/ 下的文件（例如 lib/index.js / lib/client.js）。每次更新都会从 npm 重新解压这个包，覆盖掉这些文件，本地改动会悄无声息地丢失。想改行为，就 fork 仓库发布你自己的版本，或者向上游提贡献。

数据与位置

从 v1.9.2 起，记录存放在固定的专用数据目录里（修复了 #4）。路径不再跟着会话工作区 / ~/.dsh / 桌面应用安装目录走，所以工作区一变，你的历史记录也不会「消失」（被算成 0），界面上显示的路径和磁盘上的路径也一致。

- 记录：/dsh-usage/usage-records.json
- data root 的解析顺序（数据总是落在下面列表里第一个可写的目录，绝不会落在工作区，除非下面全部不可写）：
1. 环境变量 DSH_USAGE_DATA_DIR（如果设置了）—— 覆盖一切；
2. Windows：%LOCALAPPDATA%\dsh-usage-plugin（LOCALAPPDATA 未设置时回退到 %APPDATA%）；
3. 用户主目录：~/dsh-usage-data（Windows 为 %USERPROFILE%\dsh-usage-data，macOS/Linux 为 ~/dsh-usage-data）；
4. 兜底（少见）：当前工作区 <workspace>/dsh-usage —— 只有上面所有系统/用户目录都不可写时才用，面板会显示「持久化已禁用」警告。
- 写入绕过模型沙箱：持久化由宿主插件进程自己的文件系统完成，不受 workspace-write 沙箱约束，所以固定目录总是可写，切换工作区也不会丢数据。
- Windows 默认路径：%LOCALAPPDATA%\dsh-usage-plugin\dsh-usage\usage-records.json
- 旧数据自动合并：首次启动时，原先散落在 %USERPROFILE%\dsh-usage、~/.dsh/dsh-usage 以及各工作区 dsh-usage（或 .dsh-usage-records.json）里的记录会合并进固定根目录，按记录身份去重 —— 新记录用 recordId，旧记录用复合指纹（会话 + 时间戳 + 模型 + 用途 + 四个 token 桶 + 结束原因）。这不再是只比毫秒，所以同一毫秒内的两个不同请求不会再互相覆盖。旧版本写入的记录依然完全可读：缺失的 recordId / pricingTime / unit 之类都是可选项。
- 写入是原子的：先在同目录写一个临时文件，刷盘，再原子重命名覆盖目标；失败则原文件保持不动。
- 文件损坏绝不会被悄悄清零：如果数据文件存在但解析不了，插件不再把它当成空数据（旧版本会这样 —— 然后用那个空数组覆盖掉整段历史）。它会把原文件重命名为 usage-records.json.corrupt-<timestamp>.json，然后继续启动，这样数据还能手工恢复。
- 价格配置（在面板中编辑并保存）：/dsh-usage/pricing.json
- 默认导出目录：/dsh-usage/{csv,json,images}/
- 自定义导出目录：在面板的「Export target directory」中设置，或点击「Choose directory…」
- 启动诊断（插件激活失败时）：数据根目录旁的 dsh-usage-boot.log

计量范围

这里的用量与费用逐次调用记录，来源是 DeepSeek Harness 的 llm/stream 事件，另外还有一个 session/event 监听器，用来捕获搜索后端的请求。依赖这些数字之前，请先读下面的边界说明。

精确计量（服务商上报的值）

| 来源 | 说明 |
| 主智能体对话 | 每次调用记录四个 token 桶、缓存命中次数和结束原因 |
| 会话标题生成 | purpose: session-title |
| 上下文压缩 | purpose: compaction |
| 进程内子代理 | 它们共用主智能体的 ctx.llm，因此同样会被拦截 |

计费公式与官方一致：uncached input × miss price + cache hit × hit price + output × output price。没有单独的缓存写入价格（DeepSeek 从不上报这个字段；写入缓存按 miss 价格计费），而 reasoning 已经包含在 output 里，所以绝不会重复计费。

非精确计量（在界面中单独标记）

| 来源 | 为什么取不到 | 插件怎么做 |
| web_search 发起的 DeepSeek 搜索后端调用 | web-search-deepseek 在 Harness 内部直接向 api.deepseek.com/anthropic/v1/messages 发起原生 fetch，刻意绕开 ctx.llm；上游只持久化请求（web/deepseek-search-llm-request），响应里的 usage 被完全丢弃（它的响应类型甚至没有声明 usage 字段）。没有任何数据源能暴露这笔开销。 | 记录精确的调用次数，并从请求体推导输入侧的下界，全部标记为 estimated。输出侧绝不猜测。概览显示「预估费用 ≥ ¥X（N 次调用）」。 |
| 外部命令行子代理（claude-code / codex） | 独立的子进程，完全在 ctx.llm 之外，不发出任何事件 | 不计入 |
| 请求中止前已产生的输出 | 中止时适配器不发出 usage 块 | 记为一次零 token 的「中断调用」，这样调用次数仍与控制台一致 |
| 官方计费按 HTTP 请求计数；插件按流计数 | Harness 层的重试不会开启新流 | 调用次数可能与官方的 request_count 不同 |

结论

- 日常聊天 / 编码负载下，插件的总计与官方账单贴合得很紧；
- 大量使用 web_search 时，插件的总计会明显低于官方账单——差额就是搜索后端，面板对此有明确说明；
- 任何情况下，都以 DeepSeek 控制台的账单为准。

历史价格永不改写

每条记录都会冻结写入时的三个单价（即它的 unit 字段）。因此：

- 之后修改价格表（在面板里改，或手动改 pricing.json）只影响未来的记录；过去的花费不会重算；
- 旧版本写入或手动导入的记录没有冻结快照，所以它们的费用使用当前价格表，并跟随之后的修改 —— 概览页和价格页会报告这类记录有多少条；
- 想刻意用当前价格表重算全部历史，用价格页上的 「Reprice all history with the current table」（或调用 API {"action":"repriceAll"}）。这是唯一会改写历史费用的入口。

FAQ

| 现象 | 原因 / 修复 |
| 面板报 Unexpected end of JSON input | 插件那一行缺少 inject 列表，路由没注册。按方式 B3 补上 inject 列表并重启 |
| 面板空白 / 没有顶部标签页 | 插件未激活。查看 dsh-usage-boot.log；确认 cordis.patch.yml 里那一行存在且 name 正确 |
| 余额查询失败，提示 "DEEPSEEK_API_KEY not configured" | 在「设置 → 模型」里配置 API Key |
| 余额查询网络错误 | 确认能访问 api.deepseek.com（必要时配置代理） |
| dsh plugin 报 pnpm not found | 安装 pnpm：npm install -g pnpm |
| 安装时连不上 npm registry | 设置镜像：npm config set registry https://registry.npmmirror.com（或 pnpm config set registry ...）后重试 |
| 卸载后仍报 Cannot find package '@feiyang666/...' | 配置档里还残留包引用。从 cordis.patch.yml 删掉对应行，并从 dsh.profile.bundles 删掉包名，然后重启 |

相关项目

| 项目 | 说明 | 安装 |
| DeepSeek Harness Desktop | Windows 桌面控制台：一键安装 / 启动 / 停止 / 重启 dsh web 服务，内置插件管理 —— 从它的「推荐」区安装本插件 | 下载桌面应用，点几下按钮 |
| Data Vault (dsh-vault) | 自动备份 / 检测清空 / 一键恢复 —— 保护聊天记录和工作区数据 | 从桌面应用一键安装，或 dsh plugin add @feiyang666/dsh-vault |
| DeepSeek-Harness | 官方命令行 / Web 服务 | 见下方快速开始 |

运行 DeepSeek Harness

快速开始（通过 npm）

安装 Node.js，然后运行：

npx @deepseek-ai/dsh web

这条命令会在默认地址 http://127.0.0.1:3080 启动 Web UI。详见 Web UI Guide。

从源码运行

从仓库源码运行：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

致谢

- @ayleen：实现了完整的英文 UI 层（i18n），支持语言响应式切换，并把余额展示改为语义化键（#7）。
- @wuhuqif176：在余额面板中加入了百炼（Qwen）Token Plan 额度查询（#8）。
- @Martin-soaring-dev：为插件做好了公开贡献的准备（打包、插件契约检查、文档与 CI），并提交了贡献分支，这个分支后来成为开源版本的基础（#6）。
- @mumuer1024：报告并定位了跨工作区的持久化路径漂移问题（历史记录「消失」／被计为 0），并提出把数据存到固定的专用目录（#4）；还报告了 DeepSeek 搜索后端调用未被计量、可能把成本低估一个数量级，并给出了可与官方账单完整交叉核对的线索（#12）。
- @liu3734：报告并定位了 macOS（POSIX）上仅适用于 Windows 的路径处理／spawn 问题，并提出了跨平台修复方案（#1）。
- @zhiqiangme：提交了一个大型 PR，加入历史回填和侧边栏余额入口（#14）。其中三项发现——cacheWriteTokens 回退把四个桶重复计数、仅按毫秒去重会覆盖记录、非原子写入会静默把损坏文件清零——成为 v1.18.0 计量修复的基础（见 CHANGELOG）。

Changelog

- CHANGELOG.md — 每个版本的详细说明。

License

MIT © dsh-usage-plugin