dsh-deepseek-usage-dashboard

简体中文 | English

一个独立、可安装的 DeepSeek Harness（DSH）Web UI 插件，用于：

• 从会话日志统计本 DSH 实例每日 DeepSeek Token 用量（仅精确 usage：缓存命中/未命中输入、输出、推理）；
• 基于用户可编辑的分模型价格表估算今日费用；
• 监控 DeepSeek 账户余额（仅 Host 端调用，默认每 10 分钟刷新，支持手动刷新）；
• 在 Web GUI 中以仪表盘、composer 底部统计行与设置卡片展示。

效果预览

仅基于官方 @deepseek-ai/* NPM SDK 开发；不修改任何 DSH 源码；通过 cordis.patch.yml + profile 插件机制安装。插件全程不调用任何 LLM 接口：统计、刷新、展示、余额查询零模型调用，空闲运行与刷新页面产生的 Token 为 0。

功能

• 每日统计（Asia/Shanghai 自然日）：缓存命中输入、缓存未命中输入、输出、推理（存在时）、输入合计、Token 合计、请求数、失败请求数、缓存命中率。
• 只统计真实的 DeepSeek 流量：provider 路由为 deepseek-official（可配置）且有效 base URL 主机为 api.deepseek.com——自定义网关不会污染统计。
• 流式安全：只有最终 usage 到达才落库；流式估算值从不写入每日精确统计。
• 幂等 + 持久化：SQLite（Node 24 运行时内置 node:sqlite），UNIQUE (session_id, turn, step) 约束 + INSERT OR IGNORE——投影重放、流式 usage 重复到达、重启后重扫、重复提交均不会重复累计；跨重启保留；损坏文件自动移出并重建。
• Decimal 金额：费用以整数最小单位（1e-6 币种单位）BigInt 累计，禁止浮点直接累计。时间感知计价：请求按开始时间选择生效的 PricingSchedule（effectiveFrom <= requestTime，含边界），支持分时段 band（如 peak/off-peak 窗口，start 含 / end 不含、可跨午夜）；历史请求不会被后来新增的价格计划重算。未知模型明确记为「未计价」（不静默套用兜底价），显式配置 * 兜底仍可用；界面显示价格版本、更新时间与计价来源，所有金额明确标注为「估算费用，非官方账单」。
• 余额：仅 Host 端 GET https://api.deepseek.com/user/balance（base URL 固定、10 秒超时、401/402/429/5xx/超时/畸形响应分别处理）；失败时保留最后一次成功数据并显示 stale 状态；支持手动刷新。API Key 绝不进入浏览器、日志或请求参数。
• Host HTTP 接口：/api/deepseek-usage/stats 与 /api/deepseek-usage/refresh，复用 DSH 浏览器信任篱笆（Host / Origin / Sec-Fetch-Site 校验，按官方 api-request-trust 语义实现）+ loopback 套接字校验；余额明细仅限 loopback；POST 要求 application/json；限制请求体大小；不提供任意 URL/文件/命令代理。
• Web UI：侧边栏「API 用量」入口；仪表盘（今日卡片、缓存命中/未命中对比条、命中率、今日估算费用、余额（总额/赠送/充值）、最近 7 天趋势、最后更新时间、数据来源说明）；conversation.composer.dock 紧凑统计行（今日：命中 X · 未命中 X · 输出 X · 估算 ¥X · 余额 ¥X）；完整中英文 locale；仅使用 DSH CSS Token（适配亮/暗主题）；不使用 dangerouslySetInnerHTML。

安装

dsh plugin --profile web add https://github.com/izz-BLUE/dsh-deepseek-usage-dashboard.git

重启 dsh web 后，侧边栏出现「API 用量」入口，composer 下方出现今日统计行。

本地开发可安装仓库检出目录：

dsh plugin --profile web add link:<本仓库路径>

如需纳入 dsh-web-ui-all 聚合包：把本包追加到 packages/dsh-web-ui-all/aggregate.yml（patchFrom 与 deps 两段），再运行 node scripts/aggregate.mjs。

验证

pnpm typecheck
pnpm test
pnpm build

配置

设置命名空间 deepseek-usage（设置页 → 插件配置，或直接编辑 ~/.dsh/settings.yaml）：

字段	默认值	说明
enabled	true	总开关
providerId	deepseek-official	被统计为 DeepSeek 的 provider 路由
balanceRefreshMinutes	10	余额刷新间隔（分钟）
pricingSchedules	内置两套（见下）	分时段价格计划（time-aware pricing，优先于 prices；未配置时使用内置 legacy + 2026-08-17 官方价）
prices	—	旧版分模型价格表（legacy）。仅真正自定义的 prices 会覆盖默认分时定价引擎：旧版 0.1.0 设置系统持久化的内置默认表（结构比对、与行序无关）会被识别为隐式默认，自动切换到 DEFAULT_SCHEDULES，升级用户无需手动删除 prices

计价（Pricing）

• 时间感知：每个请求按其请求开始时间（step/start）所属的 schedule 计价；schedule.effectiveFrom <= requestTime 生效（含边界）。价格变更只影响生效时刻之后的请求，历史请求不会被新价格重算。
• 分时段：schedule 可按本地时间窗口（如 09:00 → 12:00，start 含 / end 不含；end < start 跨午夜；start === end 为全天）划分 band；未落入任何窗口的时间自动归入隐式 off-peak band。多个窗口可共享一个 band（bandId，如上午/下午高峰共用 peak，价格只写一次）。
• 未知模型 = 未计价（UNPRICED）：内置默认表不提供 * 兜底——未知模型明确显示为「部分用量未计价」，其 token 不进入估算金额；只有你在配置中显式配置 * 行时才启用兜底。
• 金额：仍以整数微单位（1e-6 币种单位）BigInt 累计；SQLite 只存 token/模型/时间戳，金额一律读取时推导，配置纠错后历史重算即可。
• 币种：同一 pricingSchedules 集合必须统一币种，混合币种会在配置校验时被拒绝（避免把不同币种静默加成一个 ¥ 数字）。

内置默认 schedule（未配置 pricingSchedules / prices 时生效）：

…