DSH Token Ledger

中文 | English

为 DeepSeek Harness 提供跨提供商的全局累积 token 用量账本：实时捕获、历史回填、可拖拽悬浮面板与本地 HTTP API。

账本采用与官方 dsh-token-meter 相同的 usage 事件契约，因此与具体 API 提供商无关。

• 实时：订阅 session/event，增量消费所有活跃会话。同一 (turn, step) 的重复样本会被替换而非累加，llm/retry-started 用于关闭当前样本窗口。
• 历史：启动时异步回填 sessions 根目录下所有 session.jsonl.zstd——拼接 zstd 帧、逐帧解压、按 seq 去重。因此安装插件之前产生的用量同样会被计入。
• 面板：左下角 FAB 打开悬浮面板，可拖拽且位置持久化在 localStorage，每 5 秒轮询一次 API；统计以「亿」（1e8 tokens）为单位展示。
• 持久化：~/.dsh/token-ledger/ledger.json，采用 tmp + rename 原子写与定时防抖。
• 失败自闭合：全部路径都有 try/catch，统计异常绝不影响会话主流程。

快速开始

dsh plugin --profile web add github:wakeup595626-cmyk/dsh-token-ledger

该包尚未发布到 npm，请使用上面的 GitHub 安装方式。安装或更新后重启 dsh web，左下角会出现账本入口。

使用

点击左下角 FAB 打开面板。HTTP API 位于 /@dsh-external/dsh-token-ledger/api。

环境要求

• 已安装 DeepSeek Harness
• host 侧可用的 Node.js zstd 支持

数据与边界

• 账本只读取 DSH 会话记录，并把聚合结果写入 ~/.dsh/token-ledger/ledger.json；不会修改原始会话。
• 面板与 API 由本机 DSH host 提供，插件不向外部服务上传用量。
• “全局”指本机 DSH 数据根下的全部会话；多个独立的 DSH_HOME 不会被合并。

开发与验证

npm run build
npm run typecheck

升级 DSH 日志格式后，至少检查一次实时统计、历史回填、刷新页面后的累计值和重复计数。

第三方声明

无第三方运行时依赖，zstd 解压交由 host 运行时完成。

详见 THIRD_PARTY_NOTICES.zh.md（English）。

社区与支持

• 通过 GitHub Issues 报告问题与提问。
• 在 awesome-dsh-plugin.com 浏览更广阔的插件生态。

参与贡献

参见 CONTRIBUTING.zh.md（English）。

引用

@misc{dsh-token-ledger,
  title={dsh-token-ledger},
  author={wakeup595626-cmyk},
  year={2026},
  publisher={GitHub},
  howpublished={\url{https://github.com/wakeup595626-cmyk/dsh-token-ledger}},
}

许可证

BSD-3-Clause