# dsh-usage-plugin

> 记录 DSH 每次大模型调用的 token 用量与消耗，按 DeepSeek 峰谷价格计算费用，支持余额查询、用量日历与 CSV/JSON/PNG 导出，数据自动落盘到固定目录。

## Metadata

- Author: [@feiyang-dev](https://github.com/feiyang-dev)
- Repo: <https://github.com/feiyang-dev/dsh-usage-plugin.git>
- GitHub: [feiyang-dev/dsh-usage-plugin](https://github.com/feiyang-dev/dsh-usage-plugin)
- Stars: 33
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek`, `deepseek-harness`, `deepseek-v4`, `deepseek-v4-pro`, `dsh`, `dsh-plugin`
- Forks: 2
- Open Issues: 2
- Last push: 2026-08-20T11:44:54.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
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（DeepSeek Harness） | 未声明 | 通过 `@deepseek-ai/cordis` ^4.0.1 接口对接，需宿主支持 `webServer` / `fs` / `subprocess` / `credentials` / `settings` / `sandboxPolicy` / `agents` 七项服务 |
| Node | >= 18 | `package.json#engines.node` 声明 |
| 操作系统 | macOS / Windows / Linux | 目录选择器走系统原生：macOS 用 `osascript`，Linux 用 `zenity` 或 `kdialog`，Windows 用 PowerShell `FolderBrowserDialog` |
| 原生模块 | 无 | 不依赖任何 `node-gyp` 原生扩展，持久化经宿主进程 `node:fs` 直接读写 |

## 安装方式
```bash
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）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-usage-plugin](https://deepseek-plugin.org/plugins/feiyang-dev/dsh-usage-plugin)
Wiki generated by AI (model: `MiniMax-M3`)