ParticleLight/dsh-all-usage

dsh-all-usage

awesome · DSH plugin

中文 · English

中文

DeepSeek Harness 全量用量看板：按模型、供应商、工作区和时间范围分析 Token、缓存与账户余额。

功能

- 热力图：53 周使用热力图；按工作区筛选并查看每日回合与 Token 明细
- 模型统计：支持混合查看、按模型合并、按供应商汇总三种维度，展示调用次数、各类 Token 与缓存命中率；模型行与筛选下拉显示真实厂商品牌 SVG 图标（未知/混牌保持中性）
- 摘要与工作区：Token 用量、缓存命中、估算成本、账户余额、连续使用、工作区 Token 分布和明细
- 成本统计：从 models.dev 同步模型价格；按输入、输出、缓存读取和缓存写入四个桶计算，保存价格快照，明确区分已计价、免费模型和未计价调用
- 导出：按当前时间范围和模型聚合方式导出 CSV
- 时间范围：今日、近 30 天、近 90 天、全部，或在全部可扫描历史日数据中自定义起止日期；热力图始终展示最近 53 周
- 工作区别名：在侧栏入口打开看板后管理，持久化保存到 $DSH_HOME/storages 的 KV 单元 all_usage_aliases
- 界面语言：在看板顶部切换中文与 English；选择会保存到浏览器本地
- 完整历史与增量重建：基线扫描全部可读历史会话；独立用量账本同时作为每会话游标——未变化的会话直接复用账本，新增事件只增量回填，长历史重启不再全量重建
- 重启免读：用持久化日志的 revision 作为每会话的变更信号（只读头部行 + stat，不读全量）——日志未变的会话重启时连事件都不读，直接从账本复用；仅日志变化（新增/修改）的会话才做增量读取
- 数据健康与按需刷新：扫描完成后浏览器只检查轻量状态版本，只有用量、别名或同步状态变化时才拉完整历史；显示本次数据更新时间、历史扫描健康、revision 免读、实际读取、账本恢复和失败，网络异常保留上次成功数据并可重试
- 工作区注册同步：监听 DSH 的 domain/changed 事件自动跟随工作区注册表——注册表一有改动（创建/删除/重命名/重排/归档/成员变化）就重读 workspaceRegistry.list()；只对新增/删除的工作区做增量处理，未变化的已有工作区直接复用已计算账本（零重扫）。统计严格限定已注册工作区：未注册 cwd（含存在但未登记目录）一律忽略
- 性能优化：Host 在 ingest 时维护 local/UTC 的日期、工作区、模型身份日级 cube 与单日小时桶；scope 查询按 bucket 合并，成本使用精确 BigInt 小数累加，53 周热力图只生成实际需要的字段，并继续使用 revision-scoped snapshot/records 缓存和可回收的实时事件队列；Client 将热力图、tooltip、趋势、环形图、请求日志和定价对话框隔离为 memoized 边界，指针坐标通过 ref + requestAnimationFrame 更新，不再触发整页重渲染；浏览器入口在打包前确定性压缩
- 趋势折线图：按当前范围、时区、工作区、供应商和模型显示输入、缓存读写、输出、推理及总处理量；单日范围按小时聚合并显示小时轴，跨日范围按日聚合；使用平滑单调曲线与入场动画，悬停查看精确值，图例可切换曲线，点击点位进入当日明细
- 统一筛选与审计：工作区、供应商、模型和日期筛选贯穿摘要、热力图、趋势、表格与 CSV；工作区、供应商、模型三个筛选维度可独立自由组合，工作区、供应商和模型选项只展示当前日期范围内实际使用过的值；切换范围后失效筛选会自动清除；请求日志以紧凑分页表常驻显示，选择单条后查看分组 Token 详情
- Token 口径：输入按「未含缓存命中」计，缓存命中 / 写入与推理独立成桶；全 0 用量的重放事件不会覆盖已记录的真实用量，仅缓存命中的请求也会计入
- 成本口径：模型价格来自 models.dev 的 USD / 1M Token 目录；成本快照按 DSH 已归一化的 fresh input 和四类价格桶计算，倍率只作用于最终总价，已有正成本历史不会因价格更新重算；只按模型选择官方厂商条目，未找到官方价格时显示为未计价

兼容性与已知限制

- 运行环境：需要 Node.js >=22 =0.1.1-rc.1 =0.1.5-rc.1 =22 =22 =22 =22 =22 =22 '
~~~

2. 在 $DSH_HOME/profiles/web/cordis.patch.yml 添加一行：

~~~yaml
- insert:
- id: all-usage
name: dsh-all-usage
~~~

用户 patch 层会被热重载：保存后刷新页面即可。

架构

- Host 端（入口 lib/index.js，组装 lib/plugin.js）：按职责拆分为 aggregation.js（聚合与查询）、ledger.js（持久账本）、session-sync.js（历史/实时同步）、pricing-runtime.js（运行时定价）、balance.js（余额）、http.js（安全路由）；扫描 turn/end、assistant/chunk usage 和最终 assistant/message.usage，监听 session/event 实时折叠，并通过 webServer 服务注册数据路由：
- GET /api/all-usage — 兼容统计快照
- GET /api/all-usage/status — 轻量 revision 与同步健康状态
- GET /api/all-usage/query — 按 scope 返回聚合、daily/hourly 趋势和 heatmap 数据；单日 scope 填充 hourly，跨日 scope 的 hourly 为空
- GET /api/all-usage/records — 按 scope 分页返回脱敏 canonical usage rows
- GET /api/all-usage/balance?force=1 — 账户余额（复用 llm-deepseek 的 API Key 配置）
- POST /api/all-usage/alias — 设置工作区别名
- GET /api/all-usage/pricing — 查看 models.dev 同步状态、已用模型匹配和显式覆盖
- GET /api/all-usage/pricing/models?q=... — 检索官方模型 ID 与名称匹配结果
- POST /api/all-usage/pricing — 保存同步、mapping 和显式价格覆盖（含 context tier 档位）
- POST /api/all-usage/pricing/sync — 手动同步 models.dev 并回填未计价调用
- Client 端：可读源码位于 src/client.js，npm run build:client 使用固定版本 Terser 生成 window.__ModuleLoader__ 工厂格式的 lib/client.js 浏览器 bundle，并注册侧边栏「用量统计」入口（sidebar.footer.action 槽位）。所有 API 仅接受本机 loopback 请求并拒绝显式跨域请求；余额读取与别名写入还要求插件启动时生成、仅在当前进程有效的令牌（余额 GET 兼容浏览器省略 Origin）。英文模式的日期分桶、范围筛选、连续使用、热力图和导出时间统一按 UTC；中文模式按本地时区。

数据说明

- 使用次数与 Token 来自 DSH 会话日志；session/flush 只在存在新的相关事件时重建并将派生账本写入异步队列，同一 session 的 pending record 会合并，插件退出时 drain；插件激活时会回填日志与账本历史，插件卸载/重启后已成功持久化的数据不丢
- 按日范围统计会保留全部可读取历史会话的有使用记录日期；热力图仅作为最近 53 周的固定视图窗口
- 会话删除后，已成功 flush 的用量仍从独立账本恢复；工作区删除同样不会丢数据——其历史用量汇总为一行「已删除」（含未落账的实时用量）。会话销毁提示和周期对账只负责触发重建，不会删除账本记录
- 同一会话的同一 turn / step 只保留一份最终 usage；重试或替换消息会替换旧贡献，不重复累计
- 输入 Token 按「未含缓存命中」计（缓存命中 / 写入独立成桶）；全 0 用量的重放事件不会覆盖已记录的真实用量，纯缓存命中的请求仍会计入
- 轻量状态接口只公开 Host 实例、统计 revision、扫描进度与同步计数，不公开会话 ID、工作区路径、提示词或回复正文；完整快照仅在状态变化或手动刷新时获取
- scope query 将回合（turns）、模型调用（calls）和去重会话（sessions）分开统计；Provider/模型筛选缺少路由信息时明确归为 Unknown，不从展示字符串猜测
- records 接口只返回短 hash、时间、工作区 ID、结构化模型身份、turn/step、Token buckets 和当前物化来源，不返回原始 session ID、路径、提示词、回复或凭据
- 看板中的总处理量 = 输入 + 输出 + 缓存读写 + 推理；缓存命中表示复用的上下文 Token，不等于新生成 Token 或实际费用
- 成本计算沿用 cc-switch 的四桶公式：输入、输出、缓存读取和缓存写入分别乘每百万价格，四项相加后再乘倍率；context tier 在输入上下文严格大于阈值时为整次请求切换四项费率，不做渐进分段；DSH 的 reasoning 字段不再次加到 output，避免底层 completion/thoughts 已含推理时重复计费
- 历史账本中带 tiered 标志的旧 flat 成本会在加载升级时迁移为 unsupported（tiered-pricing-not-modeled），不再继续显示为当前精确 priced；Token 统计不受影响。
- 价格同步默认关闭；models.dev 不可用时保留最近一次成功目录，未匹配模型不会套用默认价格；成本设置可展开查看官方档位，并为显式 override 增删 context tier；看板范围与明细视图保存在浏览器本地，6 小时自动同步开关会立即写入受保护的 pricing API
- Mapping 语义：带 identityKey 的 mapping 只对精确路由身份生效；不带身份键的 mapping 才按模型做全局回退；旧配置中的 usageIdentityKey 会在加载时归一化。
- 余额查询走 DeepSeek 官方 /user/balance 接口；未配置 API Key 时卡片显示引导文案
- 账本按 session ID 稳定 hash 到 32 个 JSON shard，单次 flush 只重写对应 shard；旧的 all_usage_ledger.json 会在首次加载时迁移，异步写失败或退出前未落盘不会丢失内存统计，只会让下次启动重新扫描
- 仅统计能归属到已注册工作区（按会话 cwd 匹配）的会话

开发

- 修改 src/client.js 后先运行 npm run build:client，再让 DSH 重载客户端模块并刷新页面；lib/client.js 是生成产物，不直接编辑。修改 lib/plugin.js 或其他 Host 模块后，需由 DSH 重载该包或重启进程
- 插件无第三方运行时依赖：Host 端只使用 Cordis 服务，Client 端只使用 runtime 提供的 React 模块；Terser 仅作为固定版本开发依赖生成浏览器产物
- 手动恢复 npm 发布时，GitHub Actions 要求输入目标 v tag 和完整 commit SHA，并在 checkout 后校验 tag、SHA 与包版本一致；Release 事件同样执行 commit 校验。

English

A full usage dashboard for DeepSeek Harness. Analyze tokens, cache behavior, estimated cost, account balance, and activity by model, provider, workspace, and time range.

Features

- Heatmap: a 53-week activity heatmap with workspace filters and daily turn/token details
- Model analytics: mixed view, model-merged view, and provider summary with calls, token categories, and cache hit rate; model rows and the model filter dropdown render vendor brand SVG icons (neutral for unknown or mixed brands)
- Summary and workspaces: processed tokens, cache hits, estimated cost, account balance, usage streaks, workspace distribution, and details
- Cost statistics: sync model prices from models.dev, calculate four cost buckets, persist price snapshots, and distinguish priced, free, ambiguous, and unpriced calls
- CSV export: export data using the selected time range and aggregation mode
- Time ranges: today, last 30 days, last 90 days, all time, or a custom start/end date across all available historical daily data; the heatmap always shows the latest 53 weeks
- Workspace aliases: manage aliases from the sidebar dashboard; values persist in the $DSH_HOME/storages KV cell all_usage_aliases
- Interface language: switch between Chinese and English from the dashboard header; your choice persists locally in the browser
- Full history & incremental rebuild: the baseline scans every readable historical session; the durable usage ledger doubles as a per-session cursor, so unchanged sessions are reused straight from the ledger and only newly appended events are folded — long histories restart without a full rebuild
- 重启时不重新读取：持久化的日志修订版本（通过 sessionPersistence.listSnapshots() 获取的标题行 + 统计信息）充当每个会话的变更信号——日志未发生变化的会话在重启时直接从账本应用，完全不读取其事件；只有发生变化/新增的会话才会增量读取
- 工作区注册表同步：跟随 DSH 的 domain/changed 事件，使工作区注册表自动保持最新——任何持久化的注册表写入（创建/删除/重命名/重新排序/归档/成员变更）都会触发重新读取 workspaceRegistry.list()，仅对新增/移除的工作区进行增量重新处理，而未变化的工作区则复用其已计算的聚合结果和账本（零重新扫描）。使用严格限于已注册的工作区：未注册的 cwd，包括注册表中不存在的现有目录，均被忽略。
- 数据健康与按需刷新：扫描完成后，浏览器仅轮询轻量级状态修订版本，并仅在使用量、别名或同步状态发生变化后才获取完整历史记录；它会显示最新的全量数据更新、历史扫描健康状况、修订版本跳过、重新读取、账本恢复以及失败情况，同时在网络错误时保留最后一次有效数据
- 性能：Host 在摄取时维护本地/UTC 日期、工作区、模型标识立方体和单日小时桶；范围查询合并桶，精确成本使用 BigInt 十进制累加器，53 周热力图仅输出其消费的字段，同时保留按修订版本作用域的 snapshot/records 缓存和可回收的实时事件队列。Client 通过 memoized 边界隔离热力图、工具提示、趋势、环形图、请求记录和定价对话框；指针坐标通过 refs 加 requestAnimationFrame 更新，而不是重新渲染页面，并且浏览器入口在打包前确定性地压缩
- 趋势折线图：显示活动范围、时区、工作区、提供商和模型范围内的输入、缓存读取/写入、输出、推理和总处理 token；单日范围使用小时桶，跨日范围使用日桶，具有平滑单调曲线、分阶段入场动画、悬停查看精确值，以及点击某个点以检查该日
- 统一筛选与审计：工作区、提供商、模型和日期筛选器适用于摘要、热力图、趋势、表格和 CSV；工作区、提供商和模型筛选器保持独立，可以自由组合，而工作区、提供商和模型选项仅限于所选日期范围内使用过的值，过期的选择会自动清除；请求日志以紧凑的分页表格形式保持可见，并为所选行提供分组的 Token 详情
- Token 计量语义：输入 token 是全新的（不包括缓存命中/写入，它们与推理一起位于单独的桶中）；全零使用量的重放永远不会覆盖已记录的使用量，而仅缓存的请求仍然计入
- 成本语义：价格来自 models.dev 的每 100 万 token 美元价目表；DSH 归一化后的新输入以及四个成本桶在计算时进行快照，乘数仅应用于最终总计，已有的正历史成本不会被重新计算；匹配使用模型的官方供应商条目并忽略 DSH 提供商，而缺失的官方价格则保持未定价状态

兼容性与已知限制

- 运行时：需要 Node.js >=22 =0.1.1-rc.1 =0.1.5-rc.1 =22 =22 =22 =22 =22 =22 '
~~~

2. 将以下条目添加到 $DSH_HOME/profiles/web/cordis.patch.yml：

~~~yaml
- insert:
- id: all-usage
name: dsh-all-usage
~~~

profile 补丁层会热重载；保存文件并刷新页面。

架构
- Host（入口 lib/index.js，由 lib/plugin.js 组装）：按职责拆分到 aggregation.js（聚合/查询）、ledger.js（持久化账本）、session-sync.js（历史/实时同步）、pricing-runtime.js（运行时定价）、balance.js（余额）和 http.js（受保护路由）；聚合 turn/end、assistant/chunk 用量以及最终的 assistant/message.usage，折叠实时 session/event 更新，并通过 webServer 暴露数据路由：
- GET /api/all-usage — 兼容的用量快照
- GET /api/all-usage/status — 轻量级修订版本和同步健康状态
- GET /api/all-usage/query — 范围聚合、按日/按小时趋势和热力图数据；单日范围会填充 hourly，而跨日范围返回空的 hourly 数组
- GET /api/all-usage/records — 分页的隐私安全规范用量行
- GET /api/all-usage/balance?force=1 — 使用配置的 llm-deepseek API 密钥获取账户余额
- POST /api/all-usage/alias — 更新工作区别名
- GET /api/all-usage/pricing — 检查 models.dev 同步状态、已用模型匹配情况和显式覆盖
- GET /api/all-usage/pricing/models?q=... — 搜索官方模型 ID 和显示名称匹配项
- POST /api/all-usage/pricing — 保存同步、映射和显式价格覆盖，包括上下文分层区间
- POST /api/all-usage/pricing/sync — 同步 models.dev 并回填未定价的调用
- Client：可读源码位于 src/client.js；npm run build:client 使用固定版本的 Terser 在 lib/client.js 生成 window.__ModuleLoader__ 包，该包通过 sidebar.footer.action 插槽注册“Usage statistics”侧边栏条目。所有 API 路由接受回环请求，并拒绝显式的跨源 Origin；余额读取和别名写入还需要插件启动时生成的进程级令牌（余额 GET 容忍浏览器省略 Origin）。

数据语义

- 调用和 token 来自 DSH 会话日志；session/flush 仅在相关事件为脏时重建并排队派生账本，按会话合并最新的待处理记录，并在插件销毁时排空。可读日志和账本历史在插件激活时回填，因此成功持久化的数据在重新加载或会话删除后仍然存在；删除工作区同样保留其历史，将其与尚未进入账本的用量汇总到一行“Deleted”中
- 日级范围数据保留每个有跟踪用量的可读历史会话日期；热力图仅为固定的最近 53 周视图
- 会话删除后，成功刷写的用量会从单独的账本中恢复；销毁提示和定期对账会触发重建，但不会删除账本行
- 对于每个会话和逻辑 turn / step，仅保留最终用量贡献；重试或被替换的消息不会重复计数
- 输入 token 是新增的（不包括缓存命中/写入，它们位于各自的桶中）；全零用量的重放不会覆盖已记录的用量，纯缓存读取请求仍然计数
- 轻量级状态端点仅暴露 Host 实例、统计修订版本、扫描进度和同步计数器。它不暴露会话 ID、工作区路径、提示词或回复正文；完整快照仅在状态变化或手动刷新后获取
- 作用域结果将会话轮次、模型调用和不同会话保留为独立的指标；缺失的路由标识明确标记为 Unknown，而不是从显示标签推断
- 记录端点仅返回短哈希、时间、工作区 ID、结构化模型标识、轮次/步骤、token 桶以及当前物化来源。它省略原始会话 ID、路径、提示词、回复和凭据
- 已处理 token = 输入 + 输出 + 缓存读取/写入 + 推理；缓存命中意味着复用了上下文，而不是新生成的 token 或实际成本
- 成本遵循 cc-switch 四桶公式：输入、输出、缓存读取和缓存写入 token 分别定价，求和，然后乘以最终乘数；当输入上下文严格大于某个上下文层级阈值时，整个请求的四个费率都会切换，而不是进行渐进式分段拆分，并且 DSH 推理不会再次加到输出中
- 带有 tiered 的旧版账本成本在加载时迁移为 unsupported（tiered-pricing-not-modeled），而不是继续被错误标记为当前的固定价格估算；token 统计保持不变。
- 定价同步默认关闭；当 models.dev 不可用时，继续使用上一个良好目录，未匹配的模型永远不会获得猜测的默认价格；成本统计可以展开官方层级计划，并在显式覆盖时添加或移除上下文层级；仪表盘范围和详情视图偏好存储在浏览器存储中，而 6 小时同步开关通过受保护的定价 API 立即保存
- 映射语义：带有 identityKey 的映射仅适用于该确切的路由标识；没有标识键的映射是模型范围的回退。旧版 usageIdentityKey 值在加载时会被规范化。
- 余额数据来自 DeepSeek 官方的 /user/balance 端点；未配置 API 密钥时，卡片会显示指引
- 英文模式对日期分桶、范围筛选、连续天数、热力图日期和导出时间戳使用 UTC；中文模式使用本地时间
- 账本将会话 ID 分配到 32 个稳定哈希 JSON 分片之一，因此一次刷新只重写其分片；旧的 all_usage_ledger.json 在首次加载时迁移。异步写入失败或未刷新的关闭不会丢失内存中的统计信息；下次启动只需再次扫描该会话
- 只有能够通过其工作目录映射到已注册工作区的会话才会被包含

开发
- 编辑 src/client.js 后，运行 npm run build:client，重新加载 DSH 客户端模块，并刷新页面；lib/client.js 是生成的文件，不应直接编辑。编辑 lib/plugin.js 或其他 Host 模块后，通过 DSH 重新加载包或重启进程
- 该插件没有第三方运行时依赖：Host 使用 Cordis 服务，Client 使用运行时提供的 React 模块；固定版本的 Terser 仅是用于生成浏览器产物的开发依赖
- 手动 npm 恢复发布需要目标 v 标签和完整提交 SHA；GitHub Actions 会对照检出的标签和包版本检查两者。发布事件执行相同的提交检查。

License / 许可证

MIT