用量账本 xie-tj/dsh-token-usage-ledger

dsh Usage Ledger 插件

dsh-plugin-usage-ledger 为 DeepSeek Harness Web profile 提供持久化的模型用量账本和 Usage 仪表盘。它记录每次 provider dispatch，包括失败和重试，保存输入、输出和缓存 token。

账本不会进入当前 session 的 flush barrier。模型请求、session durability 和页面打开都不等待历史统计完成。

运行方式

插件使用独立低优先级 worker。worker 以单 session 串行方式读取日志，并在每个小批次后让出执行权。主 dsh 进程只发送压缩后的 live 事件，读取小批量 SQLite 查询结果；它不保留历史 assistant 内容或完整 call 账本。

SQLite 是唯一账本存储：

- 使用固定的 dsh home 路径 storages/usage-ledger-v4.sqlite，插件版本变化不更换账本文件；
- 每个 session 只在 worker 内加载当前 replay cursor 和仍然活跃的 request；
- 已完成 call 与回放游标留在 SQLite，不会进入常驻 Map；schema 5 在同一文件里添加源检查点，原地接纳 schema 4 并保留既有记录，不支持降级；
- Snapshot 使用分页数据库扫描和事件循环让出，聚合值完整，逐条 events 有固定上限；
- 旧 usage_ledger.json、usage-ledger-v2.sqlite 和 usage-ledger-v3.sqlite 不读取、不删除、不迁移。v4 从 retained session 日志重新统计。

这让历史规模主要增加磁盘占用和后台耗时，不会线性增加当前 dsh 任务的内存。

自适应历史回填

默认策略是完整历史，最近 30 天优先。最近窗口完成后，worker 自动继续较早的 retained sessions；进程重启后根据 SQLite cursor 断点恢复。

主进程每隔 1 秒观测自身的事件循环延迟、事件循环利用率、RSS 和电源状态：

- 事件循环压力需要连续 backfillPauseSamples 个采样都超过上限才暂停；单次尖峰只降低处理占比；
- 中度繁忙时降低处理占比，连续两个空闲采样后逐步提高；
- RSS 或可用内存越界时仍然立即暂停；
- 只有配置 backfillPowerMode: ac-only 时才在确认使用电池后暂停；默认 always，电源 probe 不可用（例如非 macOS）不再暂停；
- live usage 事件始终优先于历史扫描。

Usage 页面以独立状态面板显示统计中、暂停原因、异常或历史完成状态，并展示已处理／总会话数、已处理事件数、待处理会话数和扫描进度。百分比只按已完成会话计算，不代表 token 处理量或预计剩余时间；会话总数尚未发现时显示扫描中的不定进度，不标记为 100%。进度每两秒自动更新；状态读取失败时保留上次的计数并提示数据暂未刷新。因资源或电源暂停时，已有统计仍可阅读和刷新。限流恢复允许运行时，Host 立即解除资源暂停；等待下一条 worker 状态期间显示“恢复统计中”。已知会话全部完成后，后续限流不能把完成状态变成暂停；读取异常和不支持的提供方仍明确报告，不按进度或 pace 隐藏错误。

读取历史有两条路径：提供方若暴露 backgroundReaderSpec，继续使用其独立读取模块；发布版 DSH 0.2.0-rc.2 的 JSONL 提供方不暴露该接口，插件改由自身的 JSONL adapter 在低优先级 worker 内挂载同一提供方、同一 root 与 compression，只调用 list、open(id, read) 与 handle.read。解压、格式迁移的只读投影、校验和 inheritedEventCount 均由官方公开接口处理，插件不直接解析物理日志，不打开 write handle，也不发布迁移或修改源日志。目录枚举也在 worker 内完成，主进程不先创建全量会话列表。

公开 read handle 接口可能在打开时解码单个完整会话；事件批次限制的是 reducer 每次处理量，不是提供方解码峰值。adapter 在 worker 内复用提供方实例并关闭每个读取 handle，提供方的有界日志缓存限制正文保留。特别大的单会话仍受 workerMaxHeapMiB 限制。新建但尚未物化的日志等待后续 rescan。源检查点把已经读到末尾的源元数据和已提交游标一起保存：排队前，使用新鲜源元数据和当前磁盘游标核对同一源配置的持久化 EOF 检查点。匹配的已完成会话从本轮任务和待扫描总数中排除，不创建回放 reducer，不打开日志解码；追加、新增、失败未完成或游标不匹配的会话才排队，并从已有游标继续。每轮仅枚举一次选定会话的头信息来发现变化，不重复执行计数和前后两轮完整枚举。记录检查点前再次核对元数据，读取中变动、被抢占或失败的扫描不能标记为完整。源标识包含存储根、压缩模式和提供方版本，不包含插件安装目录或插件版本。当前格式使用文件身份、大小与纳秒时间戳；旧格式逻辑投影还依赖选中的语料元数据，相关文件变化会保守失效。SDK 的进程内 revision 不作为跨进程的持久化凭据。worker 按 reader options 复用一个提供方实例：released 提供方把根目录编码校验的遍历缓存挂在实例上，若按会话新建实例，就会为每个会话重走整棵会话目录，会话数一多就退化成 O(N²) 的元数据开销；解码只保留该实例有界的日志缓存。

变化发现只用一次提供方列表调用：每个会话的持久化指纹随列表一起返回，不再逐个 stat。released 提供方每次 stat 都会重走整个会话根目录（本机 3137 个会话时约 200 毫秒一次），逐个调用会让发现阶段超过十分钟；一次列表即可在约 2 秒内报告全部会话。指纹取提供方版本号的前 5 段（设备、inode、大小、纳秒 mtime 与 ctime），已实测跨进程一致；提供方附加的进程内摘要段被丢弃，只有 5 段的版本同样可用。读取中源发生变化的会话不写检查点。

检查点标识 released-jsonl-checkpoint-v2 是持久化凭据的一部分：改动它会让全部已存检查点失效，下次启动必须重新核对全部历史，所以只有在指纹编码本身不兼容时才能改，并有回归测试断言发布产物里只有一个标识。
单会话读取失败分两类。存储代被当前 DSH 版本拒绝迁移时（发布版抛 SessionFormatUnsupportedError，例如日志含迁移不认识的历史事件类型，或旧版 subagent/descriptor），adapter 先用拒绝对象携带的 location.path 定位物理日志并自行读取：zstd 日志是拼接帧，Node 只解第一帧，所以按帧头与块头逐个找出帧边界后逐帧解压，只保留 reducer 认得的事件类型，跨帧拆开的记录留到下一帧再拼。内存只与存储字节数和单帧大小有关，不与解码后的会话成正比；该回退只在提供方拒绝时启用，可读会话的数字完全不变，读完照常写源检查点，后续每轮直接跳过。拒绝未给出可用路径、或压缩不是 zstd 时，仍按“无法读取”只结算一次并写进 unreadable_sources（按来源 revision 记忆，不重试、不计入 unresolvedFailures、不发 error 帧），文件被重写（指纹变化）后才重新尝试。其余读取失败仍先重试一次，仍失败则记为未解决并保持异常状态直到该会话真正读到末尾；账户本体的失败不会被后续 idle 覆盖，也不会因为别的会话成功而被清除。资源限流只影响未完成的历史任务，不改变异常状态。

首次从 schema 4 升级时，已有请求和游标立即保留；源检查点尚未建立，需要一次尾部核对来建立证明，不从零重算旧请求。后续启动只枚举元数据并读取新增或变更的会话。状态显示“本轮已扫描会话”“本轮处理事件”、从持久化检查点跳过的会话数、无法读取的历史会话数，以及回填 worker 当前 RSS（workerRssMiB）。数据库 schema 升到 6 并新增 unreadable_sources 表；旧库按 IF NOT EXISTS 原地升级，4 及以上版本都能打开。

内存只由 worker 承担：workerMaxHeapMiB（默认 512）是它的 V8 堆上限，实测一轮历史统计的 worker 峰值 RSS 约 287 MiB，Host 主进程另计。已写检查点或已记入 unreadable_sources 的会话不再解码，所以重启不会重跑旧日志；统计结束后 worker 保持空闲，不再持续占用 CPU。需要更小的常驻占用时调低 workerMaxHeapMiB。全部未变的启动显示完成、0 / 0 待扫描；发现变化的元数据检查阶段仍显示运行。本轮事件数或待扫描总数为零不表示历史账本丢失。计数由最新源观测和持久化证明共同派生，不保存一个可能漏掉外部追加日志的静态剩余数字。

自定义 persistence 若提供 reader、未提供 lister，仍使用一次 Host 兼容性 listing；没有可用独立 reader 且不是受支持 JSONL 实例时仅启用 live ledger，并明确报告历史回填不可用。提供方启动异常会保留实际错误，不再替换为缺少接口的泛化消息。

安装与启动

从 Git 安装到 Web profile；生产环境固定到 commit SHA：

dsh plugin --profile web add github:xie-tj/dsh-token-usage-ledger#<commit-sha>
pnpm dsh web

本版本面向 DSH 0.2.0-rc.2 及以上的 0.2.x（peerDependencies 为 ^0.2.0-rc.2）。安装包已包含 Host、Client、Typert 和 worker 的编译产物，不依赖安装时构建。

打开 Settings → Usage 查看最近 7 天或 30 天的数据。页头按钮等高并保持成组，说明文字独占一行；提供方、模型和时间范围采用等宽筛选布局，按设置面板的内容宽度自适应而不是按整个 app 窗口宽度。筛选提供方或模型时，页面向 Host 请求该筛选的数据库聚合，而不是把全部 request 明细传入浏览器。

同一个仪表盘也挂在插件页里本包自己的行上（plugins.row.config，键为 dsh-plugin-usage-ledger#usage-ledger-plugin）。plugins.item 属于官方设置页，本包不占用它，因此不会出现在官方分组里。

设置导航栏里「用量」行的图标：已发布的外壳按 section id 固定映射图标，插件无法注册，因此本插件在客户端适配——按自己的导航文案（当前语言）找到自己的那一行并打上标记，由本插件样式表隐藏外壳的兜底图标、改画本插件的柱状图。适配只作用于本插件自己的行；找不到对应行时不产生任何影响，卸载时标记与观察器一并撤销。较新的外壳若提供 settings.section.glyph seat，则由外壳直接渲染插件图标，标记逻辑检测到之后自动让位，不重复绘制。

页面默认显示全部历史的汇总。每个快照关联它对应的时间范围、提供方和模型；切换筛选时，在新快照完成前显示该范围的加载状态，不把旧范围的数据当成新范围。失败时保留筛选控件和重试入口；只有同一筛选的手动刷新失败才继续显示上次成功快照。全部历史模式的指标、模型表和两张图表都覆盖最早匹配记录至所选结束日期的完整历史，不截取最近 30 天。图表最多绘制 60 个日历区间：较短范围按日，较长范围依次按周（周一至周日）、月、年合计；极长范围合并相邻年份，每个源日期和所有计数均参与汇总。首尾区间按实际起止日期裁切，图表下方标明范围与粒度，悬停或键盘焦点提示完整日期区间。合并只减少绘制节点，不抽样、不删旧数据，图表标题合计仍是完整筛选范围的合计。Export CSV 会把当前筛选的完整 call 记录按 SQLite 页流式写入 owner-only 文件，完成后显示保存路径；导出不会把整份 CSV 或整本账本装入浏览器内存。

配置

bundle patch 默认提供 databasePath，通常不需要手动配置。需要调整部署策略时，可在 usage-ledger-plugin 的 Cordis config 中设置：

| 字段 | 默认值 | 含义 |
| databasePath | profile patch | 私有 v4 SQLite 文件 |
| backfillMode | process | process 启用 worker；off 停止历史回填 |
| backfillScope | all | all 为全历史；recent 只处理优先窗口 |
| backfillDays | 30 | 优先处理的最近天数 |
| workerMaxHeapMiB | 512 | worker V8 堆上限 |
| workerMaxActiveAttempts | 256 | 单个 session 可保留的未完成 request 上限 |
| workerBatchEvents | 512 | 每次解析的最大事件数 |
| workerSliceMs | 50 | 处理后主动让出的最长时间片 |
| backfillPowerMode | always | always 忽略电源状态；ac-only 仅接电回填 |
| loadSampleIntervalMs | 1000 | 主进程负载采样间隔 |
| backfillMaxDelayMs | 15000 | 暂停或强退让的最长间隔 |
| backfillInitialWorkShare | 0.25 | worker 初始处理时间占比 |
| backfillMinWorkShare | 0.10 | worker 的最低处理时间占比 |
| backfillMaxWorkShare | 0.80 | worker 的最高处理时间占比 |
| backfillAimdIncrease | 0.10 | 健康窗口后的线性增量 |
| backfillAimdDecrease | 0.50 | 繁忙采样时的乘性降幅 |
| backfillPauseRssMiB | 2048 | 暂停回填的 dsh RSS 阈值 |
| snapshotEventLimit | 256 | 单次 Snapshot 返回的明细行上限 |
| snapshotScanBatchRows | 256 | Snapshot 每个 event-loop 回合读取的行数 |

高级阈值也可配置：backfillRecoverySamples、backfillPauseSamples、backfillBusyEventLoopUtilization、backfillPauseEventLoopUtilization、backfillBusyEventLoopDelayMs、backfillPauseEventLoopDelayMs 和 backfillPauseAvailableMemoryMiB。AIMD 的 work share 会转换为每个 worker slice 之间的等待时间。

Snapshot API

Remote 方法为 usageLedgerPlugin/snapshot：

interface UsageLedgerSnapshotRequest {
workspace?: string | null
provider?: string | null
model?: string | null
days?: number
all?: boolean
timeZone?: string
}

返回值保留 events、models 和 daily。all 为 true 时，models 与 daily 覆盖最早匹配 call 至今天的完整历史；页面图表使用完整 daily 序列，指标和模型表也使用完整匹配范围。eventsTruncated 表示逐条明细达到 snapshotEventLimit；models 和 daily 始终基于完整匹配范围计算。days 的范围是 1 到 366，timeZone 决定日边界和 daily 分组。

usageLedgerPlugin/status 返回 idle、running、paused 或 failed，以及处理进度、最近错误和当前 pace。pace 的 reason 为 battery、event-loop 或 memory 时，说明历史扫描正退让；live 记录仍会继续进入 worker。

统计语义

- 一个 provider dispatch 计为一次 request；success、failure、aborted 与 retry attempt 分别计数。
- retryRequests 标记随后被 retry 的失败或中断 attempt，不额外生成 request。
- provider 和 model 从 request/header 或 request/context 恢复；无法恢复时为 unknown。
- final assistant-message usage 优先于最后一个 provisional usage chunk。
- 未报告 usage 的 attempt 仍计入 request，token 为 0，并标记为 unmetered。
- inputTokens 为 provider 报告的非缓存输入；outputTokens 包含 provider 报告的 reasoning token；cache read/write 分别保存。

构建与验证

pnpm install
pnpm run typecheck
pnpm run test
pnpm run pack:check

License

MIT