模型用量仪表盘 ZSN12/DSH-model-usage

DSH-model-usage

npm 包名：dsh-model-usage（npm 要求小写）· 仓库名：DSH-model-usage

DeepSeek Harness 模型用量仪表盘 —— 设置页「模型用量」

像 Codex 用量页一样查看你的 DSH Token 消耗 —— 按模型 API 逐次采集、本地持久化、浏览器端聚合展示，全程不经过任何第三方服务。

✨ 功能一览

- 📊 顶部统计栏：累计 Token 数 / 峰值 Token 数 / 最长聊天时长 / 当前连续天数 / 最长连续天数
- 🔥 Token 活动热力图：GitHub/Codex 风格 7×N 网格，近 30 天 / 90 天 / 6 个月 / 1 年 可切，悬停显示每日用量
- 📋 用量明细：真实消耗 Tokens / 总请求数 / 总成本(估算) / 缓存命中 / 推理 Tokens 五张 KPI 卡
- 🛡 缓存命中率：cache read token 占比进度条
- 🤖 模型列表：按 provider/model 聚合，显示总 token、调用、输入、输出、推理
- 🔄 5s 自动刷新 + 手动刷新 + 模型筛选下拉
- 💾 本地持久化：每次调用 append 写入 ~/.dsh/storages/model-usage.jsonl，重启不丢

📦 安装

要求：DeepSeek Harness（含 web profile）与 pnpm。

方式一：源码构建 + 挂载（推荐）

1. 克隆并构建
git clone https://github.com/ZSN12/DSH-model-usage.git
cd DSH-model-usage
pnpm install
pnpm build # 产出 lib/index.js + lib/client.js + lib/types
pnpm pack # 产出 tarball

2. 装进 web profile
dsh plugin --profile web add file:dsh-model-usage-0.1.0.tgz

方式二：profile 直挂（开发用）

// ~/.dsh/profiles/web/package.json
{
"dsh": { "profile": { "bundles": [ /* ..., / "dsh-model-usage" ] } },
"dependencies": { "dsh-model-usage": "link:/path/to/dsh-model-usage" }
}

cordis.patch.yml 会注册 model-usage 插件，设置页出现「模型用量」分区。改完重启 dsh web（host 半路由随之加载）；浏览器端改动需重新 pnpm build 后刷新页面。

🔌 架构

| 半 | 文件 | 职责 |
| Host | src/index.ts | 包装 llm/stream waterfall 采集每次调用的 usage chunk；持久化到 jsonl；注册 HTTP 路由 |
| Host | src/report.ts | 共享的 wire contracts（记录结构 / 聚合行 / 单价表） |
| Client | src/client/index.ts | 注册 settings.section 分区（模型用量, order 12） |
| Client | src/client/UsageSection.tsx | 仪表盘 UI：统计栏 / 热力图 / KPI / 命中率 / 模型列表 |
| Client | src/client/UsageSection.module.css | 样式（CSS Modules, 随皮肤令牌适配） |

Host 采集原理

ctx.on('llm/stream', async function (options, next) {
// 透传流,同时捕获 type === 'usage' 的 chunk for await (const chunk of next()) {
if (chunk?.type === 'usage' && chunk.usage) captured = chunk.usage
yield chunk
}
// 调用结束后 append 一条 UsageRecord 到 jsonl })

记录字段：{ ts, provider, model, inp, out, cr, cw, rsn, dur }。启动时回放 jsonl（上限 50,000 条），内存聚合出报告。

HTTP 端点

| 端点 | 说明 |
| GET /api/model-usage?days=&model= | 聚合报告 JSON（rows / totals / daily / summary / debug） |
| POST /api/model-usage/reset | 清空记录与 jsonl（⚠️ 无鉴权，仅限本机使用） |

💰 成本估算说明

KPI 卡里的「总成本(估算)」按 src/report.ts 内嵌的公开单价表（美元/百万 token）关键词匹配计算，不是官方账单。各模型价格会变动，如有偏差请自行更新单价表。

🔒 隐私与数据

- 所有用量数据仅写入本机 ~/.dsh/storages/model-usage.jsonl（纯本地，无任何上传）
- 单价表与代码均为静态数据，不读取 API key、聊天内容或会话内容
- MAX_CALLS = 50_000 内存上限，超出后裁剪最旧记录（磁盘文件仍 append，重启回放时截断）

🧑💻 开发

pnpm install
pnpm build # tsc 类型声明 + tsdown 双 bundle
pnpm watch # tsdown watch
pnpm typecheck # tsc --noEmit

lib/ 为构建产物（已 gitignore），发布走 pnpm pack（prepublishOnly 自动构建）。

📄 License

MIT

灵感来自 openai/codex 的用量页设计。本项目非 DeepSeek 官方出品。