dsh-usage-stats

在 DeepSeek Harness 的界面里看这台 harness 花了多少 token：按 Today / 近 7 天 / 近 30 天 / 全部统计，并拆出服务方上报的四个桶（未缓存输入 / 输出 / 缓存读取 / 缓存写入）。

它的重点是「删了也不丢」：用量按会话逐个备份进一份只增不减的台账，所以删除会话（dsh-session-cleanup、手删目录、归档清理）不会把它那部分用量从统计里抹掉。

适配 dsh 0.1.6-alpha.1 ～ 0.2.1-rc.2（含桌面版 0.2.1-rc.2）：会话日志的代际（0.1.6 写 v3、0.1.7 写 v4，升级后两代可以并存）在磁盘上按代际识别，而不是写死一个文件名；页脚会写出这次到底读到了哪几代。逐条实测见 docs/compatibility.md。

只读会话日志、不持有凭据、不联系 provider、不改模型路由；除了自己那份台账，不写任何东西。

一、这个插件解决什么问题

DSH 已经在 $DSH_HOME/sessions/ 下为每个会话精确记录了服务方上报的 token 用量，但那是一个每会话累计值 —— 它回答不了「我今天花了多少」。本插件折叠那些日志，把它变成按天、按供应商、按模型的报告。

而会话日志是可以被删掉的（dsh-session-cleanup 就是 rm -rf 会话目录）。日志一没，按日志现场折叠出来的统计就跟着少一块 —— 用户清理一次侧边栏，历史用量就凭空下降一次，这种数字没法用来做判断。

所以 0.3.0 起：每次扫描折叠出来的结果会按会话备份到

$DSH_HOME/storages/dsh-usage-stats/usage-ledger.json

规则只有两条：

规则	含义
只增不减	同一个会话、同一个 (天, 供应商, 模型) 格子，取「台账里记的」与「日志现在说的」中较大的一份。日志被压缩、截断、改写，都不能把已经计过费的数字降下来
从不删除	记录写进去就只被向上更新。没有淘汰、没有 TTL、没有上限。想清空统计就删掉那个目录，下次扫描以当前日志为基线重新开始

后台每 30 秒巡检一次（只对 mtime/size 变过的日志重新折叠），所以不需要有人打开设置页，用量也会被记下来：会话建了又删、中间没人看过页面，同样不丢。

二、安装

项	值
包名	`dsh-usage-stats`
版本	`0.4.1`
dsh 基线	`0.1.6-alpha.1` ～ `0.2.1-rc.2`（`engines.dsh` 按 0.1.6 / 0.1.7 / 0.2.0 / 0.2.1 四条已测发布线声明）
源码与分发	本仓库（`github.com/HaydenSmith1121/dsh-usage-stats`）

方式 A（推荐，也是以后的默认路径）：装一次插件市场面板（dsh-plugins-market），在左侧「插件市场」里点安装。市场里的这一条就是本仓库的 github: 规格 —— 不经过任何中间产物仓库（dsh-plugin-collection 已停止维护、将被丢弃）。

方式 B（手动，等价）：直接从本仓库安装：

dsh plugin --profile web add github:HaydenSmith1121/dsh-usage-stats        # dsh web
dsh plugin --profile desktop add github:HaydenSmith1121/dsh-usage-stats    # 桌面版

profile 选哪个：dsh web 用 web，桌面版（DeepSeek Harness 应用）用 desktop —— 桌面版的 profile 里带着 @deepseek-ai/dsh-web-app 与它自己的 bundle 清单（$DSH_HOME/profiles/desktop/package.json），插件装错 profile 就不会被加载。不确定时看一眼 $DSH_HOME/profiles/ 下有哪些目录。

lib/（构建产物）是提交进仓库的，所以 git 安装不需要跑任何构建脚本 —— 本包也故意没有 prepare：有它的话 pnpm 10+ 会以 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 拦下安装，逼每个用户手改 allowBuilds （0.3.1 修的就是这个）。要自己从源码打包：npm run pack。

方式 C（离线 tarball）：npm run pack 自己打一个，或从可信副本取 —— 装法同上，把参数换成 .tgz 的绝对路径。

装完重启（dsh web，或直接退出再打开桌面版）：设置页是客户端半，重启后立刻出现； 读会话日志并维护台账的路由由宿主半注册，只在启动时加载 —— 重启之前页面会明说这一点，而不是给一个裸 404。

三、配置

没有配置项：没有 API Key、没有设置项、没有环境变量。

唯一的路径约定是台账的位置（由 DSH 主目录推导）：

文件	说明
`$DSH_HOME/storages/dsh-usage-stats/usage-ledger.json`	用量台账（只增不减）
`$DSH_HOME/storages/dsh-usage-stats/usage-ledger.json.corrupt.json`	台账损坏时被挪到这里的原件

$DSH_HOME 未设置时用 ~/.dsh（与 DSH 自己的解析顺序一致）。

四、页面显示什么

总 tokens，以及构成它的四个桶；
缓存读占比（有缓存的 harness 上它常远超其它桶，只给裸总数会显得吓人）；
该范围内的模型调用次数；
页脚老实交代：读到几个会话日志、几个读不到、几个已删除会话的用量是从台账保留的，以及读到的是哪几代会话日志格式（· 读到的日志格式：v4 × 12）。

最后那一项是 0.4.0 加的：harness 给会话日志的文件名和表头都打了格式代际，而这个代际在发布线之间会动（0.1.6 是 v3，0.1.7 是 v4）。把读到的代际印出来，「它在这台机器上到底读懂了没有」才是一个可以自己核对的事实，而不是一句承诺。表头读不出代际时显示「未标版本 × N」—— 不猜。

范围是含端点的本地日历窗口且以今天结束，所以它们嵌套：7 天的数字必然包含 1 天的。

台账本身的状态也从不暗示，而是直接写出来：

状态	页面怎么写
`ok`	「删除会话不会丢用量：各会话的用量已逐个备份，只增不减。」
`rebuilt`	「用量台账曾不可用，已重建（原因）—— 重建之前保留的用量不再计入。」
`unavailable`	「用量台账 <路径> 写不进去（原因），删除会话会同时删掉它的用量。」并给出该路径

会话目录整体读不到时（临时故障），页面明说「本次读不到会话目录 —— 所有数字都来自备份」，并且不会把在场会话谎报成「已删除」。

五、数字从哪来（口径）

折叠刻意复刻 DSH 自己的 tokenUsage 投影（@deepseek-ai/dsh-token-meter），而不是自己发明一套看起来合理的规则 —— 一份和框架对不上的报告，比没有报告更糟。三个 load-bearing 的细节：

#	细节	不这么做会怎样
1	同一步骤内最后一条样本胜出	一个流式步骤会为同一个 `(turn, step)` 记录多条 usage 样本，每条替换前一条。朴素求和会把一个流式步骤重复计很多遍
2	一次重试开一个新槽	`llm/retry-started` 为它自己的 `(turn, step)` 关闭当前槽，所以被重试的那一次会与它替换掉的那次并存相加 —— 它确实被计费了两次
3	`assistant/message` 与 `assistant/attempt` 都带 usage	后者是它内嵌流里最后一条 `usage` chunk

node scripts/verify-fold.mjs --reference <0.2.0 的 lib/index.js> 会重新推导每个会话的合计，并与上一个发布的真实产物逐字节比对（npm test 用仓库内冻结的那份参考实现）。

磁盘格式：按代际识别，不按版本号

折叠规则在两条发布线上没变，但读日志这件事会变，所以它是单独一层（src/usage/format.js），并且只认磁盘上的事实：

代际	文件名	表头	fork 继承切点
0–1	`session.jsonl[.zstd]`	扁平，带 `seedLength`	表头里的 `seedLength`
2、3、4	`session.v<N>.jsonl[.zstd]`	扁平，只有 `isSeeded`	最后一条带 `inherited: true` 的 `session/end-seed` 事件的 `seq`

一个会话目录里有多代文件时（升级后就是如此），读数值最高的那一代 —— 与 harness 自己的选择一致。声明了 isSeeded 却找不到继承标记的日志，记为读不到，而不是猜一个切点：harness 自己的解码器对这种日志同样抛错，而猜错的代价是把父会话的整段前缀再计一次费。逐条实测见 docs/compatibility.md。

已知统计边界（诚实登记）

边界	说明
标题生成不计入	`session/title-llm-request` 会消耗 token 但不记录 usage 样本，任何折叠都看不见。DSH 自己的投影有同样的盲点
fork 的会话不向父会话重复计费	继承前缀（`session/end-seed { inherited: true }` 之前的事件）被跳过，因为那些事件保留父会话的时间戳、已经随父会话计过。0.4.0 之前这一条实际上没生效（切点读错了字段），fork 会话的父前缀被重复计费
台账启用之前的删除救不回来	0.3.0 第一次运行之前就被删掉的会话，日志已经没了，任何实现都无法复原。台账从第一次扫描开始积累
删除前最后 ≤30 秒的用量	极端情况下（会话在被折叠之前就被删掉）可能来不及记账。巡检间隔是 30 秒，它决定这个窗口
读失败会被报出来，不会被藏起来	页脚显示读了多少个日志、点名几个读不到；不完整的数字永远不会被当成完整的呈现
未知代际的日志	事件形状没变时照常折叠（并在页脚标出代际）；连表头都读不出来时按「未 fork」折叠并标为「未标版本」。没有为将来可能出现的形状变化做预测
同一个会话 id 出现在两个工作区目录下	台账按会话 id 记账（这是「删了也不丢」的前提），所以两处同名目录会被合并成一条记录（格子取较大者），而报告会把两份相加 —— 两者不一致。dsh 自己把这种布局判为损坏（`duplicate JSONL session id`），本插件不额外处理，也不假装它不会发生

六、卸载 / 回滚

dsh plugin --profile web remove dsh-usage-stats          # dsh web
dsh plugin --profile desktop remove dsh-usage-stats      # 桌面版
# 然后重启（dsh web / 重开桌面版）

卸载不会删掉台账：那是你花掉的用量的记录，删不删由你决定。想清空统计：删掉 $DSH_HOME/storages/dsh-usage-stats/（整目录或那一个 json），下次扫描会以当前在场的会话日志为基线重建 —— 报告会随之下降，这是预期行为。

回滚到旧版：dsh plugin --profile <profile> add <上一版的 tarball> 即可 —— 本插件不迁移、不改写任何 DSH 数据，所以降级只是换回旧代码，台账原样留着（旧版不认识它，忽略）。 注意 0.3.1 及更早的版本在 0.1.7 上读不到会话日志（写死了 v3 文件名），回滚到它们只会看到全 0 —— 需要旧版就在 0.1.6 那侧用。（dsh-plugin-collection 停止维护后，0.3.0 及更早的 tarball 不再有公开托管点；需要旧版就 git checkout 0.3.0 的提交 && npm run pack 自己打一个。）

⚠️ 与 dsh-workbuddy-quota 的关系：本包是它的继任者（改名 + 只保留用量统计）。两者不要同时装 —— 它们注册的设置分区 id 不同（usage-stats / token-usage），同时装会出现两个 Token 用量页。旧包仍然可用，但不再维护。

七、开发

npm run build                 # src/ → lib/（无打包器：宿主半是拷贝，客户端半加外壳）
npm run build:check           # 校验 lib/ 与 src/ 一致（CI 用）
npm test                      # 六个套件：构建一致 / 折叠一致 / 跨版本格式 / 删除保留 / 宿主路由 / 客户端渲染
npm test -- --sessions <dir>  # 再加上真实会话日志的逐字节比对与代际核对

npm test -- --reference <解包后的 0.2.0 包目录>   # 折叠比对改用真实产物作参考

# 声明面：本包的 peer 范围、客户端 inject、bundle patch 对得上这棵 harness 树吗
node scripts/compat-check.mjs --tree <放着 @deepseek-ai/* 包的目录>

src/
├─ index.js                 宿主半入口：注册路由 + 启动巡检
├─ shared/buckets.js        桶运算与日历窗口（构建时内联进客户端半，两边不会漂移）
├─ usage/
│  ├─ decode.js             zstd 多帧 + JSONL 解码
│  ├─ format.js             会话日志的磁盘格式：代际文件名 + 表头 + fork 切点
│  ├─ fold.js               折叠算法（复刻 DSH 的 tokenUsage 投影）+ 只增不减的合并
│  ├─ ledger.js             台账：读取 / 校验 / 原子写入 / 损坏隔离
│  ├─ scan.js               扫描会话目录（按代际选日志，按 mtime+size+文件名记忆化）
│  ├─ report.js             合并「在场日志」与「台账」，产出报告（含读到的日志代际）
│  └─ host.js               扫描→对账→落盘→报告，外加那条 HTTP 路由
└─ client.js                客户端半（ModuleLoader 工厂体：设置页）
scripts/                    构建、六个校验套件、声明面审计、打包
test/                       合成会话日志构造器（逐代真实形状）+ 冻结的 0.2.0 折叠参考实现
docs/compatibility.md       harness 版本兼容：实测矩阵与边界
docs/verification.md        验证记录

lib/ 是提交进仓库的：本包也支持 github: 直接安装，而 git 安装不会跑我们的构建步骤； npm run build:check 是保证它与 src/ 不脱节的那道闸门。

八、许可

MIT（见 LICENSE）。作者：HaydenSmith1121。

dsh-usage-stats

只读会话日志、不持有凭据、不联系 provider、不改模型路由；除了自己那份台账，不写任何东西。

一、这个插件解决什么问题

所以 0.3.0 起：每次扫描折叠出来的结果会按会话备份到

$DSH_HOME/storages/dsh-usage-stats/usage-ledger.json

规则只有两条：

规则	含义
只增不减	同一个会话、同一个 (天, 供应商, 模型) 格子，取「台账里记的」与「日志现在说的」中较大的一份。日志被压缩、截断、改写，都不能把已经计过费的数字降下来
从不删除	记录写进去就只被向上更新。没有淘汰、没有 TTL、没有上限。想清空统计就删掉那个目录，下次扫描以当前日志为基线重新开始

二、安装

项	值
包名	`dsh-usage-stats`
版本	`0.4.1`
dsh 基线	`0.1.6-alpha.1` ～ `0.2.1-rc.2`（`engines.dsh` 按 0.1.6 / 0.1.7 / 0.2.0 / 0.2.1 四条已测发布线声明）
源码与分发	本仓库（`github.com/HaydenSmith1121/dsh-usage-stats`）

方式 B（手动，等价）：直接从本仓库安装：

dsh plugin --profile web add github:HaydenSmith1121/dsh-usage-stats        # dsh web
dsh plugin --profile desktop add github:HaydenSmith1121/dsh-usage-stats    # 桌面版

profile 选哪个：dsh web 用 web，桌面版（DeepSeek Harness 应用）用 desktop —— 桌面版的 profile 里带着 @deepseek-ai/dsh-web-app 与它自己的 bundle 清单（$DSH_HOME/profiles/desktop/package.json），插件装错 profile 就不会被加载。不确定时看一眼 $DSH_HOME/profiles/ 下有哪些目录。

lib/（构建产物）是提交进仓库的，所以 git 安装不需要跑任何构建脚本 —— 本包也故意没有 prepare：有它的话 pnpm 10+ 会以 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 拦下安装，逼每个用户手改 allowBuilds （0.3.1 修的就是这个）。要自己从源码打包：npm run pack。

方式 C（离线 tarball）：npm run pack 自己打一个，或从可信副本取 —— 装法同上，把参数换成 .tgz 的绝对路径。

三、配置

没有配置项：没有 API Key、没有设置项、没有环境变量。

唯一的路径约定是台账的位置（由 DSH 主目录推导）：

文件	说明
`$DSH_HOME/storages/dsh-usage-stats/usage-ledger.json`	用量台账（只增不减）
`$DSH_HOME/storages/dsh-usage-stats/usage-ledger.json.corrupt.json`	台账损坏时被挪到这里的原件

$DSH_HOME 未设置时用 ~/.dsh（与 DSH 自己的解析顺序一致）。

四、页面显示什么

总 tokens，以及构成它的四个桶；
缓存读占比（有缓存的 harness 上它常远超其它桶，只给裸总数会显得吓人）；
该范围内的模型调用次数；
页脚老实交代：读到几个会话日志、几个读不到、几个已删除会话的用量是从台账保留的，以及读到的是哪几代会话日志格式（· 读到的日志格式：v4 × 12）。

范围是含端点的本地日历窗口且以今天结束，所以它们嵌套：7 天的数字必然包含 1 天的。

台账本身的状态也从不暗示，而是直接写出来：

状态	页面怎么写
`ok`	「删除会话不会丢用量：各会话的用量已逐个备份，只增不减。」
`rebuilt`	「用量台账曾不可用，已重建（原因）—— 重建之前保留的用量不再计入。」
`unavailable`	「用量台账 <路径> 写不进去（原因），删除会话会同时删掉它的用量。」并给出该路径

会话目录整体读不到时（临时故障），页面明说「本次读不到会话目录 —— 所有数字都来自备份」，并且不会把在场会话谎报成「已删除」。

五、数字从哪来（口径）

#	细节	不这么做会怎样
1	同一步骤内最后一条样本胜出	一个流式步骤会为同一个 `(turn, step)` 记录多条 usage 样本，每条替换前一条。朴素求和会把一个流式步骤重复计很多遍
2	一次重试开一个新槽	`llm/retry-started` 为它自己的 `(turn, step)` 关闭当前槽，所以被重试的那一次会与它替换掉的那次并存相加 —— 它确实被计费了两次
3	`assistant/message` 与 `assistant/attempt` 都带 usage	后者是它内嵌流里最后一条 `usage` chunk

磁盘格式：按代际识别，不按版本号

折叠规则在两条发布线上没变，但读日志这件事会变，所以它是单独一层（src/usage/format.js），并且只认磁盘上的事实：

代际	文件名	表头	fork 继承切点
0–1	`session.jsonl[.zstd]`	扁平，带 `seedLength`	表头里的 `seedLength`
2、3、4	`session.v<N>.jsonl[.zstd]`	扁平，只有 `isSeeded`	最后一条带 `inherited: true` 的 `session/end-seed` 事件的 `seq`

已知统计边界（诚实登记）

边界	说明
标题生成不计入	`session/title-llm-request` 会消耗 token 但不记录 usage 样本，任何折叠都看不见。DSH 自己的投影有同样的盲点
fork 的会话不向父会话重复计费	继承前缀（`session/end-seed { inherited: true }` 之前的事件）被跳过，因为那些事件保留父会话的时间戳、已经随父会话计过。0.4.0 之前这一条实际上没生效（切点读错了字段），fork 会话的父前缀被重复计费
台账启用之前的删除救不回来	0.3.0 第一次运行之前就被删掉的会话，日志已经没了，任何实现都无法复原。台账从第一次扫描开始积累
删除前最后 ≤30 秒的用量	极端情况下（会话在被折叠之前就被删掉）可能来不及记账。巡检间隔是 30 秒，它决定这个窗口
读失败会被报出来，不会被藏起来	页脚显示读了多少个日志、点名几个读不到；不完整的数字永远不会被当成完整的呈现
未知代际的日志	事件形状没变时照常折叠（并在页脚标出代际）；连表头都读不出来时按「未 fork」折叠并标为「未标版本」。没有为将来可能出现的形状变化做预测
同一个会话 id 出现在两个工作区目录下	台账按会话 id 记账（这是「删了也不丢」的前提），所以两处同名目录会被合并成一条记录（格子取较大者），而报告会把两份相加 —— 两者不一致。dsh 自己把这种布局判为损坏（`duplicate JSONL session id`），本插件不额外处理，也不假装它不会发生

六、卸载 / 回滚

dsh plugin --profile web remove dsh-usage-stats          # dsh web
dsh plugin --profile desktop remove dsh-usage-stats      # 桌面版
# 然后重启（dsh web / 重开桌面版）

⚠️ 与 dsh-workbuddy-quota 的关系：本包是它的继任者（改名 + 只保留用量统计）。两者不要同时装 —— 它们注册的设置分区 id 不同（usage-stats / token-usage），同时装会出现两个 Token 用量页。旧包仍然可用，但不再维护。

七、开发

npm run build                 # src/ → lib/（无打包器：宿主半是拷贝，客户端半加外壳）
npm run build:check           # 校验 lib/ 与 src/ 一致（CI 用）
npm test                      # 六个套件：构建一致 / 折叠一致 / 跨版本格式 / 删除保留 / 宿主路由 / 客户端渲染
npm test -- --sessions <dir>  # 再加上真实会话日志的逐字节比对与代际核对

npm test -- --reference <解包后的 0.2.0 包目录>   # 折叠比对改用真实产物作参考

# 声明面：本包的 peer 范围、客户端 inject、bundle patch 对得上这棵 harness 树吗
node scripts/compat-check.mjs --tree <放着 @deepseek-ai/* 包的目录>

src/
├─ index.js                 宿主半入口：注册路由 + 启动巡检
├─ shared/buckets.js        桶运算与日历窗口（构建时内联进客户端半，两边不会漂移）
├─ usage/
│  ├─ decode.js             zstd 多帧 + JSONL 解码
│  ├─ format.js             会话日志的磁盘格式：代际文件名 + 表头 + fork 切点
│  ├─ fold.js               折叠算法（复刻 DSH 的 tokenUsage 投影）+ 只增不减的合并
│  ├─ ledger.js             台账：读取 / 校验 / 原子写入 / 损坏隔离
│  ├─ scan.js               扫描会话目录（按代际选日志，按 mtime+size+文件名记忆化）
│  ├─ report.js             合并「在场日志」与「台账」，产出报告（含读到的日志代际）
│  └─ host.js               扫描→对账→落盘→报告，外加那条 HTTP 路由
└─ client.js                客户端半（ModuleLoader 工厂体：设置页）
scripts/                    构建、六个校验套件、声明面审计、打包
test/                       合成会话日志构造器（逐代真实形状）+ 冻结的 0.2.0 折叠参考实现
docs/compatibility.md       harness 版本兼容：实测矩阵与边界
docs/verification.md        验证记录

lib/ 是提交进仓库的：本包也支持 github: 直接安装，而 git 安装不会跑我们的构建步骤； npm run build:check 是保证它与 src/ 不脱节的那道闸门。

八、许可

MIT（见 LICENSE）。作者：HaydenSmith1121。

DPH-1121/dsh-usage-stats

dsh-usage-stats

一、这个插件解决什么问题

二、安装

三、配置

四、页面显示什么

五、数字从哪来（口径）

磁盘格式：按代际识别，不按版本号

已知统计边界（诚实登记）

六、卸载 / 回滚

七、开发

八、许可

Community comments

DPH-1121/dsh-usage-stats

dsh-usage-stats

一、这个插件解决什么问题

二、安装

三、配置

四、页面显示什么

五、数字从哪来（口径）

磁盘格式：按代际识别，不按版本号

已知统计边界（诚实登记）

六、卸载 / 回滚

七、开发

八、许可

Community comments