dsh-usage-plugin

一句话定位

DeepSeek Harness 的用量与消耗统计插件。装好后在 WebUI 顶部多出「用量与消耗」「剩余余额查询」两个 Tab，自动记录每次模型调用的 token 与费用。

核心能力

• 自动记录每次模型调用的输入、输出、缓存命中、缓存写入、推理 token，以及结束原因
• 按 DeepSeek 官方峰谷价格（北京时间 9:00–12:00 / 14:00–18:00 为高峰）自动计算消耗，2026-08-17 后切换到峰谷价
• 提供按模型、按「服务商 × 模型」的聚合表，支持今天 / 近 7 天 / 近 30 天 / 全部 / 自定义日期区间筛选
• 月度用量日历热力图，可按日查看明细
• 查询 DeepSeek / SiliconFlow / DigitalOcean 账户余额；面板内可管理 DigitalOcean 账户级 Token
• 导出 CSV / JSON / PNG 长图（最多含最近 2000 条），可选默认目录或使用系统原生文件夹选择器，导出后自动打开目录
• 导入 CSV / JSON 与已有记录按时间戳去重合并；价格表可在面板内编辑持久化

技术实现

• 语言: JavaScript（ES Module，"type": "module"，无 TypeScript）
• 关键依赖: @deepseek-ai/cordis（peer，^4.0.1）、宿主提供的 webServer / fs / subprocess / credentials / settings / sandboxPolicy / agents Cordis 服务；无第三方运行时依赖
• 架构模式: 双半包（Host + Client）一体：lib/index.js 是宿主页 Cordis 插件，订阅 llm/stream 事件抓取 usage chunk 并暴露 POST /usage/api；lib/client.js 是浏览器页 React 组件，通过 slots.inject("conversation.view") 与 slots.inject("settings.section") 挂载两个 Tab；通过 dsh.bundle.patch（cordis.patch.yml）+ dsh.client 声明被 DSH 自动识别与加载
• 入口文件: lib/index.js（host，exports.default 为 Cordis 插件对象）、lib/client.js（client，通过 exports["./client"] 暴露）

适用场景

需要持续追踪 DeepSeek / SiliconFlow / DigitalOcean 等多服务商账户余额与 token 消耗的 DSH 用户。尤其适合按月核对账单、估算高峰期与空闲期费用差异、做团队成本分摊，以及把历史用量数据带到外部分析工具（导 CSV/JSON）的人。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:feiyang-dev/dsh-usage-plugin

配置项

本插件无需额外配置。所有行为由包内 PRICING / 路径解析逻辑与宿主 settings.llm-pi-ai 提供商配置共同决定，价格可在面板内「价格表」Tab 调整并持久化到 <数据根>/dsh-usage/pricing.json，必要时可用 DSH_USAGE_DATA_DIR 环境变量覆盖默认数据目录。

常见问题

Q: 装好后看不到「用量与消耗」和「剩余余额查询」两个 Tab 怎么办？

A: 一般是插件行的 inject 列表缺失或被截断。看数据根（默认 Windows %LOCALAPPDATA%\dsh-usage-plugin\dsh-usage\，macOS/Linux ~/dsh-usage-data/dsh-usage/）下是否生成 dsh-usage-boot.log，里面会标注激活失败的具体步骤；正常情况应能看到 route-registered 一行。如果 patch 文件被手工编辑丢字段，按 npm run wire 跑一次 scripts/wire.js 重新接线即可。

Q: 数据存在哪里？切换工作区会不会丢？

A: 自 v1.9.2 起数据落到独立目录，v1.9.4 改用宿主进程 node:fs 直接写，完全绕开工作区沙箱：默认 Windows 写到 %LOCALAPPDATA%\dsh-usage-plugin\dsh-usage\、macOS/Linux 写到 ~/dsh-usage-data/dsh-usage\。切换工作区不再丢失，更不会因卸载 DSH 桌面版而一并清空。旧版本散落在用户主目录或旧工作区的记录会在首次启动本版本时按 time 去重合并进来。可用 DSH_USAGE_DATA_DIR 环境变量强制指定到任意路径。

Q: 怎么查 DeepSeek / SiliconFlow / DigitalOcean 的账户余额？

A: 进「剩余余额查询」Tab，选服务商再点查询。DeepSeek 用「设置 → 模型」里配置的 DEEPSEEK_API_KEY；SiliconFlow 复用「设置 → 模型」中以 siliconflow 为 Provider ID 或显示名的服务商所引用的 API Key；DigitalOcean 需要先在面板里保存以 dop_v1_ 开头的账户级 Personal Access Token（不能用 DO AI 推理 Key）。AMD GPU Cloud 标注为「当前未公开余额查询端点」。

Q: 提示「持久化未启用」是什么情况？

A: 这是环境变量、AppData、用户主目录下的 dsh-usage-data 三条候选路径全部都不可写才会出现的回退提示，并把数据落到当前工作区。属于权限或磁盘空间异常，多发生在受限容器中。看到后请检查上述目录的写入权限，或直接用 DSH_USAGE_DATA_DIR 指向一个可写目录。

Q: 能导出哪些格式？导出后会自动打开目录吗？

A: CSV、JSON、PNG 长图三种。导出目录可选默认目录（数据根下 csv/、json/、images/）或点「导出目标目录 / 选择目录…」，Linux/macOS/Windows 都会调起各自系统的原生文件夹选择器，导出完成后再用 open / xdg-open / explorer.exe 自动打开所在目录。PNG 长图最多展示最近 2000 条，超出会给出提示。

Q: 能从别的设备或旧版本迁移记录吗？

A: 选 CSV 或 JSON 文件导入即可，按 time 字段去重合并；如果只是想换台机器继续用，把旧数据根下的 usage-records.json 拷到新机器同位置即可，无需导入。

Q: 峰谷价什么时候生效？怎么改？

A: 峰谷价自北京时间 2026-08-17 00:00 起自动启用；之前的历史调用按基础价计费。高峰时段为北京时间 9:00–12:00 / 14:00–18:00。面板「价格表」Tab 可在运行时修改并立即持久化，点「恢复默认」一键还原。

Q: 怎么卸载？

A: 推荐 dsh plugin --profile web remove @feiyang666/dsh-usage-plugin。如果是手工安装，请从 cordis.patch.yml 删掉 usage-plugin 行再 pnpm remove / npm uninstall 该包。卸载不会删除数据目录，如不再需要请手动清理。

上手难度

入门 — 一条命令安装、无配置文件，余额查询前在「设置 → 模型」里填好对应 Provider 的 API Key 即可。

已知问题与限制

• AMD GPU Cloud 当前未公开可由推理 API Key 调用的余额查询端点，面板里点查询只会给出提示并引导去 AMD Developer Cloud 控制台查看（lib/balance.js:31-40）
• DigitalOcean 余额查询只能用账户级 dop_v1_... Personal Access Token，DigitalOcean AI 推理 Key 不能用于此接口（lib/index.js:749-751, lib/balance.js:21-30）
• 旧 npm 包名 @feiyang666/deepseekharnessdesktop 已不再维护，新装请使用 @feiyang666/dsh-usage-plugin（README.zh.md:19-26）
• 不要手动修改 ~/.dsh/profiles/<名>/node_modules/@feiyang666/dsh-usage-plugin/ 下的文件，每次 pnpm update / 升级都会从 npm 重新解包覆盖，本地改动会被静默丢弃（README.zh.md:230）
• 仅 DeepSeek 官方与 SiliconFlow、DigitalOcean（美元）有计费价格表，其它第三方 Provider 调用（amd / aliyun / qwen 等）的消耗按 0 统计（lib/index.js:107-148）