前言¶
用 DeepSeek Harness（DSH）跑智能体，路由往往不止一条：官方 API、New API 系中转、Sub2API、各家 Coding Plan……会话一多，账单就散在各家控制台里，很难回答两个朴素的问题——这个月到底烧了多少 Token？又是哪条线路、哪个项目在花钱？
社区插件 TokenLedger（zh667/TokenLedger）就是冲着这个痛点来的：在 dsh web 的 Web GUI 里挂一块「用量账本」，把每次请求的 Token 用量归属到实际服务请求的中转站，并按工作目录做项目分组。装完就能看汇总，零配置、不需要额外填凭据；查余额时才复用宿主里已有的 API Key。项目在 GitHub 上约 138 stars（MIT 许可），维护者为 zh667，在 SkillHub 插件库 中归类为模型推理。
需要说明的是：DSH 的核心理念是「一切皆插件」，SkillHub 等社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系；TokenLedger 本身也是第三方社区项目。
这是什么¶
一句话：TokenLedger 是面向 DSH Web GUI 的 Token 用量统计与归属插件（npm 包名 dsh-tokenledger）。
它从 Harness 的事件流里折叠用量数据，按 provider 的 baseURL 归一化出的 origin（域名） 把流量归到对应中转站——同站多把 key 合并成一行，站名是域名而不是你起的路由别名。同时按会话启动时的工作目录做项目归属：工作区登记过的显示标题，没登记过的用目录名，子目录里起的会话也不会漏掉。
用量统计、余额查询、费用估算、导出诊断，面板和命令行读的是同一套查询，不存在两套口径。
核心功能与亮点¶
- 中转站归属：自动从宿主 provider 配置发现
baseURL，只读地址、不碰凭据；同一 origin 下的多路由合并统计。 - 按项目归属：以 cwd 为键分组，可选关联 workspace 标题；无目录的会话单独标为「未记录目录」，不会被静默丢弃。
- 余额与订阅配额：支持 DeepSeek 官方、New API 系、Sub2API、Moonshot/Kimi、智谱 GLM、OpenRouter（需 Management Key）、OpenCode Go、Kimi For Coding、MiniMax / Z.ai Coding Plan 等；订阅型按 5 小时 / 日 / 周 / 月滚动窗口展示进度条与重置时间。
- 用量分析：今日 / 本月 / 累计三窗口，可按站点、模型下钻，含缓存命中率与一年活跃度热力图。
- 费用估算：支持分段费率表与峰谷计价；未定价模型显示破折号，不猜价格。
- 导出与诊断：CSV / JSON 导出，
/tokenledger diagnostics查看路由归属与索引健康度；归因不上的行数单独列出。 - 隐私与安全：只记录 token 数、模型名、路由名、站点域名，不读取提示词、工具参数或响应正文；HTTP 端点仅限本机回环 GET，并校验 peer socket 地址。
项目在用量折叠上处理了若干容易算错的边界：请求失败后仍可能从 assistant/chunk 流出 usage；同一 (turn, step) 的重复报告做替换而非累加；孤儿 usage chunk 回退到最近一次 request/header，归不上的记为 unknown 而不猜测。
安装与启用¶
需要 DSH 的 web profile，宿主版本 @deepseek-ai/dsh >= 0.1.0-rc.6。
在终端执行（命令以 GitHub README 与目录页为准）：
dsh plugin --profile web add "github:zh667/TokenLedger"
安装后重启正在运行的 dsh web，浏览器硬刷新。侧边栏底部会出现「用量账本」入口。
升级或卸载：
dsh plugin --profile web update dsh-tokenledger
dsh plugin --profile web remove dsh-tokenledger
若要钉死版本，须使用完整的 40 位 commit SHA，短 SHA 会解析失败：
# 跟踪 main 分支（默认）
dsh plugin --profile web add "github:zh667/TokenLedger#main"
# 钉版本示例（SHA 以仓库当前提交为准）
dsh plugin --profile web add "github:zh667/TokenLedger#87b3d1806ac4d204a9195fc04ae8af6d6ebdd3ee"
装完后可用 /tokenledger diagnostics 排查「中转站为什么不显示」——无需猜配置。
典型用法示例¶
Web 面板：侧边栏进入「用量账本」，查看三窗口合计、按天/模型/站点分布、账户余额与热力图。
命令行（与面板同源数据）：
/tokenledger # 全部时间
/tokenledger 7 # 最近 7 天
/tokenledger 30 api.example.com # 某中转站最近 30 天
/tokenledger site # 列出发现到的中转站
/tokenledger site add <路由名> <地址>
/tokenledger site rm <路由名>
/tokenledger export csv 30 # 导出最近 30 天 CSV
/tokenledger diagnostics # 索引与路由诊断
/tokenledger reindex # 丢弃索引后全量重建
可选配置（写入 settings.yaml，改完热更新）——多数场景不需要：
tokenledger:
relays:
my-route: https://relay.example.com/v1
rates: [] # 费用估算费率表，不配则显示破折号
fingerprint: false # 中转站程序指纹探测，默认首次查余额时自动探一次
内置表覆盖不到的供应商，还可通过 tokenledger.endpoints 声明余额接口路径（须与已配置 provider 同源，只发 GET，密钥仍只从该 provider 的 apiKeyEnv 读取）。
包也可作为库被其他消费者引用：
import { foldUsage, bySite, byModel } from "dsh-tokenledger";
import { LedgerStore } from "dsh-tokenledger/store";
import { readBalance } from "dsh-tokenledger/balance";
适用场景与注意事项¶
适合谁用：
- 同时配置多条 API 路由 / 中转站，需要看清「哪一站、哪一模型、哪一项目」在消耗 Token；
- 使用 New API、Sub2API 等中转，想在一个面板里对照额度与用量；
- 需要导出 CSV/JSON 做团队对账或月度复盘。
注意事项：
- 仅面向 web profile：插件通过
dsh web注入侧边栏与回环 API，TUI / CLI-only 场景不适用。 - 插件权限：TokenLedger 以当前
dsh进程权限运行，安装前建议阅读源码与 MIT 许可证，确认可接受其行为边界。 - 「未知路由」：若历史请求的路由已从 provider 配置中删除或改名，用量会暂归「未知路由」——数据未丢，把同名路由配回去并触发索引重建即可归位。
- 余额查询例外：用量统计零凭据即可；余额接口会复用宿主已存的 key（OpenRouter 需 Management Key），浏览器侧拿不到密钥。
- 社区目录星标：SkillHub 与 GitHub 的 stars 会随时间变化，以你安装时打开的页面为准。
结尾¶
如果你已经在 DSH 里接了好几条线路，却还在为 Token 去向发愁，TokenLedger 值得一试：装一条命令、刷新页面，就能把用量拉到中转站和工作目录两个维度上。它是社区里把「算清楚」这件事做得比较完整的一块拼图，和官方 Harness 无隶属关系，但和「一切皆插件」的生态方向很合拍。
- 目录页：https://www.skillhub.cn/plugins/zh667/TokenLedger
- GitHub：https://github.com/zh667/TokenLedger
- npm：
dsh-tokenledger
