前言¶
在 DeepSeek Harness（DSH）里做多项目、多会话开发时，每个会话都会留下 provider 回报的 tokenUsage 投影，但数字分散在各项目的会话日志里。子代理、fork 会话还会复制父会话历史，若把各会话「记录值」直接相加，同一笔计费调用会被重复统计。下面介绍社区插件 dsh-token-ledger（维护者 u-fw，分类 admin-security）：它按安装内全部会话语料汇总各项目的真实计费口径，并在设置页与侧边栏提供图形面板。
这是什么¶
dsh-token-ledger 是一个 DSH profile bundle，不是独立程序。安装进某个 profile 后，它读取该 profile 的持久化会话语料，按需推导统计结果，不维护单独数据库。宿主注册 HTTP 路由 GET /token-ledger/summary，面板为 Web 客户端，因此 DSH Web 服务必须处于运行状态 才能看到界面。包声明 Node >=22.15（语料测试依赖 Node 22.15 起的 zstd 解码能力）。
核心功能¶
统计口径¶
每个会话的 tokenUsage 包含四类计费桶（来自 provider 每次调用的 usage，非启发式估算）：
| 字段 | 含义 |
|---|---|
uncachedInputTokens |
未命中缓存的输入 |
cacheReadTokens |
从缓存读取的输入 |
cacheWriteTokens |
写入缓存 |
outputTokens |
模型输出 |
插件按会话工作目录 header.cwd 分组为「项目」，再汇总会话数、输入/输出、缓存率等。
精确模式与快速模式¶
面板顶部可在两种模式间切换：
-
精确（默认）
对每个会话只累计seq >= inheritedEventCount的事件，跳过从父会话继承的日志前缀，避免 fork / 子代理导致的重复计费。首次全量统计在 README 示例规模（约 120 会话）下约 3 秒；之后按sessionPersistence.revision增量重读，通常一百多毫秒。点「重新统计」会清空缓存并全量重读。 -
快速
直接读ctx.sessionProjectionCache，不读日志，约 60 毫秒返回；无法去重，也没有按模型路由归属，数字偏高，面板会标明。
README 在示例语料中给出对比：直接相加约 30.0 亿 token（虚高约 70%），去重后约 17.5 亿 token。
表格与视图¶
- 项目表：项目、会话、子代理、继承历史、输入、输出、消耗 token（快速模式下为「记录 token」）、缓存率、占比；点击项目名可展开最多 50 条会话明细。
- 按模型路由：仅在精确模式下可用，按实际服务的 provider/model 归属每笔调用。
- 时间筛选：全部时间 / 近 30 天 / 近 7 天（按会话创建时间）。
- 导出 CSV：当前视图的会话级长表，带 BOM，便于 Excel 打开。
「继承历史」列依据 header 的 isSeeded，与「子代理」列含义不同：手动 fork 也会计入继承历史。
入口¶
| 入口 | 位置 |
|---|---|
| 侧边栏图标 | 全局面板行（Plugins 下方），左上角「返回对话」 |
| 设置 | 侧边栏 → 设置 → 「Token 统计」（在 Models / Plugins / Agent Presets 之后） |
两处为同一组件；设置弹窗内容区较窄（约 564px），插件用容器查询隐藏部分列以避免裁切，完整数据仍在悬停提示与 CSV 中。
安装与启用¶
前提：本机已有可用的 DSH（提供 plugin_manager 与 dsh plugin），以及 本仓库的一份本地检出（见 GitHub 仓库）。
安装到某个 profile，两种方式等价：
- 插件管理器 — 在 DSH 中通过
plugin_manager的install_bundle，目标指向检出目录；或在 Web 设置 → Plugins 完成同样操作。 - 手动 — 将该包目录加为 profile 依赖（包管理器写成
link:），并在 profile 的package.json的dsh.profile.bundles中列出。
装好后出现在 设置 → Plugins，可停用或卸载。宿主半边通过 cordis.patch.yml 注册；客户端由 package.json 的 dsh.client 声明加载。修改宿主代码后需重启 DSH（ESM 模块缓存）。
当前 package 版本为 0.1.0，许可证 MIT。
典型用法¶
- 安装并启用 bundle，确认 DSH Web 服务已启动。
- 打开 设置 → Token 统计，或点击侧边栏 Token 统计图标。
- 默认使用 精确 模式查看各项目去重后的 Input / Output / 消耗 token 与缓存率；需要快速概览时切 快速（注意数字未去重）。
- 用 近 7 天 / 近 30 天 缩小范围；怀疑缓存不准时点 重新统计（5 秒内重复点击会被节流）。
- 精确模式下查看 按模型路由 表，对比不同路由的缓存率差异。
- 需要离线分析时 导出 CSV。
开发者在仓库内可运行测试（需本地检出）：
npm test # node --test test/*.test.mjs
npm run verify:live # 对运行中的 DSH 做端到端验收
verify:live 会检查宿主是否已重载、会话折叠是否与语料一致、增量缓存是否生效等；地址优先 --url，其次环境变量 DSH_WEB_URL。
适用场景与注意¶
适合：在同一 DSH 安装下管理多个工作目录（项目），需要按项目汇总 provider 计费 token、排查 fork/子代理重复统计、对比模型路由与缓存命中率的管理员或重度用户。
务必注意：
- 插件以 当前 DSH profile / 进程权限 运行，读取该安装的全部持久化会话；安装前应阅读源码与 MIT 许可证，确认可信。
- 统计 不是账单：仅反映 provider 回报的 usage，不含价格换算。
- 只统计日志仍在磁盘上的会话；无
cwd的会话归入「(no project directory)」。 - 路由
GET /token-ledger/summary不受 DSH/api鉴权闸门保护（与 DSH 自定义路由的一般行为一致）；README 说明强制刷新有 5 秒冷却，以限制误用与循环请求。 - 精确模式复杂度与全部日志字节数成正比，会话规模很大时全量冷读耗时会线性上升。
DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-token-ledger 把分散在多项目、多会话里的 provider 计费 token 收到一块面板里，并在精确模式下对继承历史做去重，便于看清真实消耗与缓存利用。进一步了解与获取代码：
- 目录页：https://www.skillhub.cn/plugins/u-fw/dsh-token-ledger
- GitHub：https://github.com/u-fw/dsh-token-ledger
