dsh-plugin-usage-report

DeepSeek Harness（DSH）的用量报表插件：按本地自然日/月汇聚 token（输入 / 缓存读 / 缓存写 / 输出）、轮数、步数与估算费用（USD），提供月度报表、预算告警，以及 Claude Code / Codex 式每日贡献格子与趣味统计。

English: README.en.md

功能

• 用量账本：对照 sessionPersistence 的 revision 增量重折叠变更会话日志，按日累计 token / 轮 / 步 / 估算费用（USD），按模型分账（provider:model 键）；数据持久化于 storage-domain，重启无需全量重扫
• 预算告警：月度预算（monthlyBudgetUsd）按阈值（默认 50/80/90/100%）触发告警，按「月份|阈值」去重、跨月自动重置
• 命令 /usage：/usage（今日/本月/预算进度/每日贡献格子/趣味统计）、/usage month [YYYY-MM]（月度明细）、/usage budget （0 关闭）、/usage export [dir]（导出 Markdown 报表）、/usage rescan（全量重扫）、/usage pricing（生效单价审计：每个已出现模型的价格来源 config / 内置 / 兜底）
• 设置页「用量」页签：Claude Code / Codex 式每日贡献格子（近 13 周）、预算进度条（可编辑）、趣味统计卡与告警列表（中英双语，每 15 秒自动刷新）

配置

插件行（cordis.patch.yml 的 usage-report insert 行）支持以下可选 config：

键	默认	说明
monthlyBudgetUsd	0	月度预算（USD）；0 = 不启用预算告警
alertThresholds	[50, 80, 90, 100]	触发告警的消耗百分比阈值（0-100，升序去重）
reconcileMinutes	10	会话日志对账间隔（分钟）；0 = 关闭自动对账
keepDays	400	每日账本保留天数
gridDays	91	每日贡献格子覆盖天数（91 = 13 周）
pricing	{}	模型单价覆盖（USD/百万 token），键为 provider:model 或 model
exportDir	''	/usage export 输出目录；空 = 当前工作区 .dsh-reports

内置 DeepSeek 官方单价（USD/百万 token）：deepseek-chat 0.27/0.07/1.10、deepseek-reasoner 0.55/0.14/2.19（输入/缓存读/输出；缓存写缺省按缓存读计）。未命中配置的模型回退到 deepseek-chat 兜底价。

安装

前置：Node.js >= 22、pnpm、本机 deepseek-harness 源码检出（依赖以 link: 指向 ../../../deepseek-harness）。

git clone https://github.com/csiroqa/dsh-plugin-usage-report.git
cd dsh-plugin-usage-report
pnpm install
pnpm build

## 配置

插件行（`cordis.patch.yml` 的 `usage-report` insert 行）支持以下可选 config：

| 键 | 默认 | 说明 |
| --- | --- | --- |
| `monthlyBudgetUsd` | `0` | 月度预算（USD）；0 = 不启用预算告警 |
| `alertThresholds` | `[50, 80, 90, 100]` | 触发告警的消耗百分比阈值（0-100，升序去重） |
| `reconcileMinutes` | `10` | 会话日志对账间隔（分钟）；0 = 关闭自动对账 |
| `keepDays` | `400` | 每日账本保留天数 |
| `gridDays` | `91` | 每日贡献格子覆盖天数（91 = 13 周） |
| `pricing` | `{}` | 模型单价覆盖（USD/百万 token），键为 `provider:model` 或 `model` |
| `exportDir` | `''` | `/usage export` 输出目录；空 = 当前工作区 `.dsh-reports` |

内置 DeepSeek 官方单价（USD/百万 token）：`deepseek-chat` 0.27/0.07/1.10、`deepseek-reasoner` 0.55/0.14/2.19（输入/缓存读/输出；缓存写缺省按缓存读计）。未命中配置的模型回退到 `deepseek-chat` 兜底价。

# 安装进 web profile（link: 指向 plugins/usage-report）
dsh plugin --profile web add link:$(pwd)/plugins/usage-report        # POSIX
dsh plugin --profile web add link:E:\path\to\dsh-plugin-usage-report\plugins\usage-report   # Windows

重启 dsh web，浏览器 Ctrl+F5 硬刷新。

使用

1. 会话里输入 /usage 查看今日/本月/预算进度/每日贡献格子/趣味统计；/usage month [YYYY-MM] 查看月度明细
2. /usage budget 设置月度预算；/usage export [dir] 导出当月报表；/usage rescan 全量重扫
3. /usage pricing 核对每个已出现模型的生效单价与来源（配置覆盖 / 内置官方价 / 兜底价）
4. 设置 > 插件 > 用量：每日贡献格子、预算进度（可编辑）与告警列表

开发

## 使用

1. 会话里输入 `/usage` 查看今日/本月/预算进度/每日贡献格子/趣味统计；`/usage month [YYYY-MM]` 查看月度明细
2. `/usage budget ` 设置月度预算；`/usage export [dir]` 导出当月报表；`/usage rescan` 全量重扫
3. `/usage pricing` 核对每个已出现模型的生效单价与来源（配置覆盖 / 内置官方价 / 兜底价）
4. 设置 > 插件 > **用量**：每日贡献格子、预算进度（可编辑）与告警列表

## 许可与使用声明

**MIT License**（见 [LICENSE](https://github.com/csiroqa/dsh-plugin-usage-report/blob/1d5d07eb8b830db2ec290e3ea20d35da1a08cb8f/plugins/usage-report/LICENSE)）。

欢迎任何人**使用、修改、引用、或把本项目收录进自己的插件合集**，只需：

- 保留 `LICENSE` 文件与版权声明
- 标明出处（本仓库链接）