前言¶
DeepSeek Harness 的投影缓存主要用于展示，数据可能滞后或覆盖不全。对于需要精确核算成本或监控使用量的场景，直接读取会话日志是更可靠的选择。dsh-token-ledger 正是基于这个需求开发，它不依赖投影缓存，而是直接解析本地会话日志，提供基于本地日期的每日 Token 消耗统计。
是什么¶
这是一个由 doremifaso12345 维护的插件，用于监控 DeepSeek Harness 的每日 token 消耗。它提供设置页卡片、输入框徽标、聊天命令和模型工具四个入口，帮助用户直观地了解 Token 使用情况。
核心功能¶
仪表盘与数据视图¶
仪表盘展示四个互不重叠的用量桶，全部基于 Provider 真实上报值：
* 未缓存输入：未命中前缀缓存的输入。
* 缓存读取：命中缓存的输入。
* 缓存写入：写入缓存的输入。
* 输出：补全输出（已含 reasoning，不重复计）。
除此之外，还提供以下指标：
* 合计：四者之和。
* 缓存命中率：计算公式为 缓存读取 / (未缓存输入 + 缓存读取 + 缓存写入)。
* 累计 Token 数：全部历史四桶之和。
* 峰值 Token 数：单日最高值。
* 最长聊天时长：定义为“连续活动时长”，即相邻事件间隔不超过 30 分钟的累积时间，而非首尾时间差。
* 活动热力图：GitHub 贡献图样式，展示 52 周 × 7 天的消耗情况。
* 工具排行：按调用次数和成功率排序。
交互入口¶
- 设置页卡片：设置 → Token 账本。支持选择 7/14/30/90/180/365 天窗口，支持一键导出 CSV（带 BOM）。
- 输入框徽标：显示今日合计（如
1.23M）与近 7 天累计，每 60 秒刷新，悬停显示明细。 - 聊天命令：通过
/tokens命令快速查看报表。 - 模型工具：
token_usage工具，允许 Agent 直接查询用量数据。
安装¶
插件无需构建，直接通过命令安装。请确保使用正确的 Profile 名称（默认为 web）。
dsh plugin --profile web add github:doremifaso12345/dsh-token-ledger
安装后请重启 dsh web。
典型用法¶
聊天命令¶
在聊天框中使用以下命令：
* /tokens：查看近 7 天的日报表与总览。
* /tokens 30：查看近 30 天的数据。
* /tokens today：只看今日数据。
* /tokens csv [days]：导出 CSV 到 harness home。
* /tokens help：查看帮助。
模型工具¶
调用 token_usage 工具，传入 days 和 includeSessions 参数。
环境与依赖¶
运行环境¶
- Node.js：必须满足
^22.15.0 || >=23.8.0。此版本范围包含了 Node 内置zlib.zstdDecompressSyncAPI，用于解压多帧 zstd 会话日志。如果版本过低（如 23.0–23.7），插件会直接报错，避免显示错误的 0 数据。 - DeepSeek Harness：目标版本
0.1.5-rc.2。 - 数据源：
<DSH_HOME>/sessions/<workspace>/<session>/session.v3.jsonl.zstd。插件会自动处理多帧 zstd 容器，并复刻官方投影的语义（如重试场景下的折叠计费）。
配置¶
在 cordis.patch.yml 中可调整：
- insert:
- id: dsh-token-ledger
name: 'dsh-token-ledger'
config:
enabled: true # 总开关
cacheTtlMs: 5000 # 结果缓存时间（毫秒）
root: null # 显式指定 harness home
注意事项¶
- 零第三方依赖：插件仅使用 Node 内置模块，不依赖
@deepseek-ai/*包，这意味着宿主版本升级时，只要不破坏契约依赖，插件仍能正常工作。 - 数据完整性：如果
sessions目录不存在或日志解压失败，仪表盘会显示空数据，不会静默报错。 - 契约依赖：安装前请确保宿主已挂载
commands、tools、webServer等服务，否则部分入口将不可用。
总结¶
dsh-token-ledger 提供了一套完整的 Token 消耗监控方案，从数据源（会话日志）到展示形式（仪表盘、热力图、导出）都经过了针对性设计。它解决了投影缓存可能缺失或不准确的问题，适合需要精细化管理和成本核算的开发者使用。
