全机用量统计 satan9394/dsh-usage-unified

dsh-usage-unified

DeepSeek Harness（dsh）的全机 Token 统计。 一个仪表盘统管本机所有会话日志：趋势、按模型拆分、会话排行、调用明细、导出，以及可选的本机成本估算。全部本地运行——插件从不联网。

目录

- 这是什么
- 功能
- 环境要求
- 安装
- 使用
- 配置
- 数据与隐私
- 成本估算（可选）
- 已知边界
- 架构
- 开发
- 兼容性
- 跨 Agent 排行榜（可选）
- 致谢

这是什么

dsh 为每个会话写一份日志。想知道「这台机器到底花了多少、花在哪」，只能去读这些日志—— harness 自带的投影只覆盖它当前运行的那个 home。

本插件把两个上游插件在数据层合并（而不是并排两套），所以一份索引喂一个仪表盘，各处数字一致：

| 上游 | 贡献 |
| lanlandeli/dsh-usage-stats | 界面：侧边栏入口与全屏浮层、按天趋势、逐调用明细表（筛选 + 分页）、CSV/JSON 导出、工作区与任务范围筛选、中英双语、主题自适应。 |
| zoyluoblue/deepseek-harness-token | 数据核心：发现全部 dsh home、直接读 zstd 原始日志、纯函数可续算折叠、增量持久索引、连续天数、高峰时段、模型四桶拆分、覆盖度披露、设置分区。 |

功能

- 全部 dsh home、两代日志格式。 ~/.dsh、~/.dsh_desktop/<version>、$DSH_HOME，外加你自列的额外根。
同时读旧格式 session.jsonl[.zstd] 与版本化 session.v<N>.jsonl[.zstd]，不依赖 harness 的私有解码器。
- 一个区间贯穿全页。 今天 / 近 7 天 / 近 14 天 / 近 30 天 / 全部，外加自定义区间，同时决定顶部卡片、趋势图、模型面板、会话排行、调用明细与成本。自定义有两种模式：起止，或起 → 至今——后者由宿主按「今天」解析上界，窗口随日历自然延长。只有「连续天数」是全时属性，那两张卡会明确标注。
- 一个模型面板。 每行给出：占比、输入/缓存读/缓存写/输出的堆叠条、调用数，以及（有定价时）成本；长尾模型默认收起。
- 会话排行 + 下钻。 按所选区间的 Token 排序；点一行即把调用明细筛到该会话。
- 平滑多序列趋势（总 / 输入 / 输出 / 缓存读），图例可点开关、悬停读数，任何区间（含全部）都渲染。
「今天」只有一个天桶，因此改画宿主的 24 个小时桶；小时桶只带总量，所以该视图只给总量一条线。
- 面板打开时每 60 秒自动刷新。
- 调用明细：时间、响应耗时、输入、输出、缓存率、模型、思考程度，支持模型/提供商/阈值筛选、分页与可配置条数上限。
- CSV / JSON 导出当前区间。
- 面板可折叠、中英双语、浅深色；页脚披露被跳过/被替换的内容，而不是悄悄丢掉。
- 可选成本估算（本机定价表，含峰谷加权，见下）。

环境要求

- dsh 插件 API 0.1.5-rc.1 或更新（见兼容性）。
- Node ^22.19.0 || >=24.0.0——即 harness 自身使用的运行时。
- 无运行时依赖。react 与 @deepseek-ai/ 均为 peer，由 harness 提供。

安装

从 GitHub
dsh plugin --profile web add github:satan9394/dsh-usage-unified

从本地检出
dsh plugin --profile web add E:\path\to\dsh-usage-unified

然后重启 Web profile。仪表盘出现在侧边栏底部的「使用统计」，以及设置里的一个分区。

DSH STORE 收录状态。 商城里本插件显示为 blocked。它的自动准入策略拒绝任何「运行时代码会触碰文件系统 / 网络 / 命令 / 凭据」的插件，而本插件必然触碰：宿主半侧要从磁盘读会话日志，浏览器半侧要取自己的回环路由。商城保留了上面这条手动安装入口，而 docs/SECURITY.md 逐条写明了运行时对这些能力的使用方式。插件的行为与本文描述一致，没有额外动作。

更新

运行时（lib/）是在 harness 启动时加载的，所以新构建必须重启 Web profile 才生效。

- 从检出或 link: 安装——在该目录 git pull，源码变了就重新构建（npm run build），然后重启。
link: 依赖是目录联接，没有副本需要刷新：profile 直接读这个检出目录。
- 从 GitHub 或 npm 安装——再执行一次 dsh plugin --profile web add <同一个目标>。那种安装会钉住某个 commit，重新 add 才是移动它的方式。

无论哪种，只有运行时变更需要重启；文档与 scripts/ 的改动不需要。

使用

打开侧边栏底部入口（或 设置 → 使用统计）。选一个区间——区间控件下方的说明行与趋势图标题栏都会写明当前统计的确切窗口。

宿主在 /usage-unified/v1 下提供四个同源、仅回环的路由：/snapshot、/calls、 /export.csv、/export.json。非回环调用返回 403。

配置

在 profile 的插件行里设置（形状见 cordis.patch.yml）。

| 键 | 类型 | 默认值 | 含义 |
| extraSessionRoots | string[] | [] | 额外扫描的 dsh home 目录。home 发现是启发式的，只能通过未设置的 $DSH_HOME 到达的 home 必须在这里列出。 |
| includeCompaction | boolean | true | 是否计入生成 compaction 摘要的 Token。设为 false 可与 harness 自带投影 1:1 对账。 |
| refreshIntervalMs | number | 30000 | 多久重扫一次追加的会话。 |
| indexChunkYieldMs | number | 16 | 扫描时的协作让出间隔，保证冷启动期间仍可响应。 |
| indexConcurrency | number | 4 | 并行解码的会话数。实测：2–4 最佳，8 以上反而退化。 |
| apiPath | string | /usage-unified/v1 | 同源只读 API 前缀。 |
| cachePath | string | $DSH_HOME/usage-unified/index-v1.json | 索引缓存位置。 |
| pricingPath | string | $DSH_HOME/usage-unified/pricing.json | 成本表。文件不存在则不显示成本。 |
| cacheWriteDelayMs | number | 1000 | 索引写盘的防抖延迟。只在索引真的变化时才写。 |

数据与隐私

全部事实如下；细节与失败边界见 docs/SECURITY.md。

- 读取——所有已发现 dsh home 下的会话日志，以及（用于成本估算的）一个可选定价文件。只读：从不写入会话，也不写入其它 home。
- 写入——只有一个文件：$DSH_HOME/usage-unified/index-v1.json，原子写（临时文件 + rename）、权限 0600，且仅在索引发生变化时写。
- 网络——零。运行时不发任何外部请求、不自行开监听套接字。它只在 harness 提供的 web server 上注册一条路由，且仅响应回环调用（其它一律 403）。其导入仅 node:fs/promises、node:path、 node:os、node:zlib 与 @deepseek-ai/。
- 进程与凭据——无。不用 child_process、不起 shell、不用 eval；不读、不写、不记录任何密钥。
- 工具面——无。插件不注册任何面向模型的工具、不追加任何会话事件，所以挂载它对对话零开销。

成本估算（可选）

dsh 本身不带价目表，所以本插件默认不算钱。当定价表存在时，会多出一张「估算成本」卡片与每行模型的成本；没有定价的模型计入「未定价」而不是当作免费，卡片与页脚都会披露已定价比例。

npm run pricing:setup # 写 $DSH_HOME/usage-unified/pricing.json

两个来源合并，后者覆盖前者：

1. 主来源——CC Switch 的 ~/.cc-switch/model-pricing.json（--source 可换成任意本项目 { models: { id: {...} } } 格式的文件）。
2. 覆盖表——scripts/pricing.override.json（入 git）：主表缺的模型与峰谷两档费率。放在这里而不是 CC Switch 里，是因为 CC Switch 的 models.dev 自动同步可能冲掉手工条目；每次 pricing:setup 都会重新合并。

峰谷计价。 DeepSeek 全系按官方时段计价：高峰 = UTC 周一至周五 01:00–04:00 与 06:00–10:00 （占全周 35/168 小时）。条目可同时声明空闲表与 peak 档，插件按 空闲 × (1 − peakShare) + 高峰 × peakShare 折算有效费率，peakShare 默认 0.2083，并在卡片上披露该比例——既不按乐观的空闲价低估，也不按高峰价高估。随包取值与 DeepSeek 官方定价页、 OpenCode Go、 Command Code 一致。

已知边界

一律披露而非隐藏——页脚会重复当前数据真正命中的那几条。

- 重试步骤只保留最终用量。 某一步的用量上报被替换过，说明两次尝试都计费了，而日志只留下存活的那条。
页脚以 retried 披露。
- 有界区间可能小于全时总量。 时间戳未通过时钟偏移校验的 Token 应进总量但不该上日历，因此全时读会话的权威计数器，有界区间由按天切片求和。
- 「天」按宿主进程时区切，在建立索引那一刻定死。若机器系统时区与使用者所在时区不同，「今天」指的是 那个时区的今天；改时区会触发全量重建。
- 调用明细有上限，由可配置的明细上限控制（默认 1,000，最大 10,000）。
- 冷启动建立索引需要数分钟（本机约 1,380 个日志文件、约 790MB 压缩日志）。面板会渲染部分结果并报告进度。
- 活跃热力图已移除——它与趋势图重复。

架构

src/
index.ts 宿主入口：Config、挂载索引 + 路由 + 刷新循环 homes.ts 发现全部 dsh home（按 sessions realpath 去重） reader.ts 遍历会话日志；两种磁盘格式都能解码（不依赖私有 API） zstd-frames.ts 扫描拼接的 zstd 帧（续读游标按帧对齐） fold.ts 纯函数可续算折叠：会话 → 总量、按天/小时切片、调用 aggregate.ts 快照 + 会话排行 + 调用行 + 连续天数/高峰时段 + CSV pricing.ts 可选定价表：读取、按模型 id 匹配、成本与覆盖度 index-store.ts 增量索引（并行解码），缓存在 DSH_HOME 下的文件 transport.ts /snapshot、/calls（含 ?session= 下钻）、/export.（仅回环） types.ts 两半共享的传输契约 client/ index.tsx 侧边栏 + 浮层 + 设置三处注册，仪表盘 i18n.ts 中英词典 source.ts 唯一传输层 styles.ts 仪表盘样式

值得知道的设计决策（完整论证见 PLAN.md）：

- 读取层与 harness 版本无关。 旧格式是 JSONL 存储记录，流式内容被打包且没有 seq；新格式是纯事件。
计费只需要带序号的记录，所以读取层保留「字符串 type + 数字 seq」的行——不依赖会改名的私有 decodeStorageRecord。
- 每个 (turn, step) 一条调用。 用量每步上报两次（流式块 + 最终消息），折叠采用替换而非累加，并为明细表保留每步一条；compaction 摘要单独成条。
- 文件缓存，不依赖可选服务。 索引写入 $DSH_HOME 下的普通文件而非 ctx.storageDomain，所以「可选服务缺失」永远不会导致面板加载不出来。
- 不猜数字。 未定价的模型标为未定价；覆盖度、重试步骤、跳过日志一律披露。

开发

npm install # .npmrc 设 legacy-peer-deps（@deepseek-ai peer 树）
npm run typecheck # tsc --noEmit
npm run test # vitest（68 项）
npm run build # tsdown → lib/index.js + lib/client.js
npm run check # typecheck + test + build
npm run verify:realdata # 只读扫本机真实 dsh home
npm run smoke:local # 本地起 HTTP 路由跑真实数据自测（不装载）
npm run smoke:serve # 同上并常驻，打印查看器 URL
npm run pricing:setup # 由本机 CC Switch 生成成本估算用的定价表
npm run report # 生成静态自包含报告（全部时间）并打开
npm run report:30d # 同上，近 30 天

smoke:local 就是「在工作区里跑、指向真实数据」的路径：不碰 DSH profile。它用普通 Node 服务器把同一批宿主路由挂到空闲回环端口、索引指向真实 ~/.dsh，跑九项 HTTP 断言。verify:realdata 遍历每份真实会话日志，把折叠总量与独立编码的用量重建逐位核对（本机为精确相等、delta 0）。

lib/ 已提交进仓库，因为 DSH STORE 要求运行时产物存在于固定 commit 内。因此 CI 会断言「提交的构建产物与源码一致」，源码改了没重建就不可能被当成旧代码装出去。

静态报告与插件同源同口径：--range 决定头部卡片，并带同样的合并版模型面板、会话排行与成本卡；热力图同样被移除。

scripts/ 下的脚本只在源码检出里可用，不随 npm 包发布。

兼容性

- 插件 API：@deepseek-ai/ 的 peerDependencies（当前 ^0.1.5-rc.1）；Node ^22.19.0 || >=24.0.0。
- 会话日志：旧格式 session.jsonl[.zstd] 与版本化 session.v<N>.jsonl[.zstd]。
- 平台：Windows / macOS / Linux。仅可选的排行榜任务使用 Windows 计划任务，其余脚本跨平台。
- package.json 的 dsh.compatibility 只声明实际验证过的版本：>=0.1.5-rc.2 <0.1.6，且
dshReleases["0.1.5-rc.2"] = "compatible"。刻意不用 ^——那会顺带声称 rc.3+ 也兼容，而它们没被验证过。

各条声明背后的证据见 docs/COMPATIBILITY.md。

跨 Agent 排行榜（可选）

本仪表盘只统计 DSH，且完全离线。把机器上所有 Agent（DSH、Claude Code、Codex、OpenCode……）汇成一个数字并提交到 tokscale 排行榜是可选的，只有你从仓库克隆后运行引导脚本才会发生：

git clone https://github.com/satan9394/dsh-usage-unified && cd dsh-usage-unified
npm install
npm run leaderboard:setup # 引导：安装/登录 tokscale、导出、首次提交
npm run leaderboard:off # 撤销：删除每日任务、停止提交

leaderboard:setup 遵循 docs/LEADERBOARD.md，其中逐条说明离开本机的数据，并在上传前征求确认。一次提交只带聚合数据——按天的 Token 桶、估算成本、消息数、client 与模型名、 MCP server 名、会话时长指标、随机设备键与 CLI 版本。绝不带提示词、回复、源码或工作目录路径。
有两项在上传端无法脱敏：模型/provider 名与 MCP server 名（介意就改 MCP 配置里的名字）。

致谢

MIT —— 见 LICENSE 与 NOTICE。衍生自两个 MIT 许可的插件 lanlandeli/dsh-usage-stats 与 zoyluoblue/deepseek-harness-token，其源码保留在 _upstream/ 供对照。

变更历史：CHANGELOG.md。