它是什么
TokenLedger 回答的是多数用量面板答错的一个问题：不只是烧了多少 token，而是这次请求实际由哪个中转站服务。它按 provider 的 baseURL 归一化出 origin 再分组——同一个站的多把 key 合成一行，站名就是域名，而不是你自己起的路由别名——在此之上再按项目、按模型各归一遍。
卖点是零配置：中转站从宿主自己的 provider 设置里发现，只读 baseURL，绝不碰旁边那把凭据。Web GUI 侧栏底部出现「用量账本」面板；/tokenledger 命令族在对话里回答同样的问题，两边读的是同一批查询，不存在第二套聚合口径。
面板里有什么
- 三个时间窗 —— 今日 / 本月 / 累计，可按站点、按模型下钻，带缓存命中率，以及一年的活跃度热力图（悬停可看当天的模型构成）。
- 余额 —— DeepSeek 官方、New API 系（One API、VoAPI 等分支）、Sub2API、Moonshot/Kimi 与 Z.ai/GLM，每家用路由上已配好的那把普通 API key 即可。OpenRouter 是例外：它的额度接口只认 Management Key，面板会直接说明要哪一把，而不是丢给你一个 401。
- 订阅配额 —— 对卖套餐不卖余额的家数（OpenCode Go、Kimi For Coding、MiniMax Coding Plan、Z.ai Coding Plan，以及 Sub2API 的套餐形态）：每个滚动窗口——5 小时 / 每日 / 每周 / 每月——各有一条进度条、一个百分比和一个重置时刻。钱包与套餐可以同时存在（Z.ai 就是两样都有），两边各读各的。
- 费用估算 —— 可配置的费率表，支持生效日期分段、分桶计价与峰谷时段。没定价的模型显示破折号，而不是猜一个 0。
- 导出与诊断 —— CSV / JSON 导出、索引健康度，以及归因不上的行数单独列出，而不是悄悄并进某个桶。
按项目归组的键是会话启动时所在的目录，不是工作区 id，所以在子目录里起的会话照样算进去；没有 cwd 的会话单独列一行「未记录目录」，不会被丢弃——这样按项目的几行加起来才对得上总数。
隐私架构
这是 README 工程上最用心的部分，值得单独一读：
- 从不读取内容。 只有计数与标识符：token 数、模型名、provider 路由名、站点域名。提示词、工具参数、响应正文既不读也不存。
- 凭据只在宿主侧。 key 由宿主的 credentials 服务按
apiKeyEnv引用在请求时解析、用完即弃，只走Authorization头，绝不进 URL 查询串。浏览器永远拿不到 key。 - 回环防护。 两个 HTTP 端点（
/api/tokenledger/usage、/api/tokenledger/balance）注册为 exact 路由，因此位于 RPC 信任边界之外；处理器拒绝非 GET 方法，并同时校验 peer socket 地址（不可伪造）与 Host 头。 - 自定义端点的边界写死在代码里，不靠自觉。 你可以为内置表覆盖不到的供应商声明余额接口，但请求只能发往某个已配置 provider 的同源地址；
path必须是单斜杠开头的绝对路径，构造完还会再校验一次；只发 GET、没有请求体；凭据仍然只从那条 provider 自己的apiKeyEnv取；跨源重定向直接失败不跟随；响应体有大小上限与超时；声明也不能覆盖内置读法。 - 中转站指纹识别不用凭据 —— 靠路由的 404/401 特征，探测一次并记住。
运行要求
- 需要 DeepSeek Harness 的
webprofile。README 要求@deepseek-ai/dsh >= 0.1.0-rc.6，徽章口径一致。需要说清依据：包清单没有dsh.compatibility块，也没有engines.dsh，这个下限只来自 README 的文字，而非机器可校验的元数据。 - Node 需
>=22，来自engines字段。 - 客户端平台为
web，注入dsh-client-locale与dsh-client-ui-primitives；浏览器半边没有构建步骤（手写的__ModuleLoader__bundle，React 由宿主提供）。peer 依赖是@deepseek-ai/cordis ^4.0.2与可选的@deepseek-ai/schemastery。无安装期生命周期脚本——package.json里只有测试脚本。 - 同一个包还带了 Blue 宿主清单（
blue.plugin.json）：检测到 Blue host 时会挂载原生 dashboard 并以 overlay 命令替换文本命令；在普通 Harness/Web 安装里这些都不会激活。 - README 以中文为主，面板文案同样如此。
已知限制
- 安装来源分叉。 README 从 GitHub 安装（
github:zh667/TokenLedger，采集时仓库版本为0.1.1-blue.0）；npm 上也有dsh-tokenledger，但发布版本落后于仓库。请跟 README 走 GitHub spec——那是作者实测过的路径。 - 钉版本必须用完整 40 位 commit SHA。 README 的 spec 表显示短 SHA 会因
git ls-remote匹配不到而直接报Could not resolve。 - 订阅接口没有公开 schema。 厂商动了字段位置时，卡片会说出它去哪儿找过——但在适配跟上之前，那个数字就是缺席的。
- 「未知路由」行的意思是：服务过这些请求的路由，现在的 provider 配置里找不到了（改过名、删掉了，或当时用的是另一台机器）。数据没丢——路由名一直在记录里——把同名路由配回去，索引重建后历史流量自动归位。
- 天按宿主进程的本地时区切分，面板上会标出是哪个时区。
- 费用是按你的费率表估算的，不等于账单。
- 归属在折叠时写死进记录，历史永不重写——中转站集合变化时会丢弃索引并从头全量重建。
什么时候用它、什么时候不要用
流量走一个或多个中转站、想知道每个站点 / 项目 / 模型各烧了多少 token，同时希望在同一个面板里看余额与订阅窗口，又不想把 key 交给面板——用它。自定义声明端点的逃生口也让它能覆盖内置表之外的供应商。
不要指望它做管控：它只观测与报告，不拦截、不限速任何东西。headless 或纯 CLI 环境请跳过（面板是 Web GUI）；如果你不愿意让任何插件读你的 provider baseURL 列表，也请三思——那次读取就是发现机制本身，没有离线模式。
安装
按 README，从 GitHub 安装：
dsh plugin --profile web add "github:zh667/TokenLedger"装完完整重启正在运行的 dsh web，浏览器硬刷新，侧栏底部会出现「用量账本」入口。装好后如果发现某个中转站没显示，先跑 /tokenledger diagnostics——它会把当前路由归属和索引里的路由对照打印出来。