前言¶

在 DeepSeek Harness（DSH）里跑智能体会话，token 会按轮次、按模型持续累加。宿主可能提供用量摘要，但若你想在本地长期对照「安装前累计」与「安装后逐轮记录」、按周/月/天筛出明细，并坚持四桶口径与逐位精确数字，往往还需要单独记账或导出后再处理。

下面介绍的 dsh-token-ledger（维护者 6600788，社区分类 admin-security）是 DSH 侧边栏插件：在左侧栏增加「Token 账本」入口，打开完整统计页。数据只写在当前机器，不上报、不联网。当前版本 1.2.0（MIT），仓库地址：github.com/6600788/dsh-token-ledger；插件目录页：skillhub.cn/plugins/6600788/dsh-token-ledger。

插件定位¶

dsh-token-ledger 订阅 DSH 会话侧的 token 事件，落盘为本地账本，并通过回环 HTTP 接口供统计页查询。它与 DSH 官方无绑定关系；社区插件目录为独立站点，启用方式遵循 profile 里的 bundle 注册，而非「官方应用商店」一键安装。

前置条件（摘自 README 与 package.json）：

• Node >= 18
• DSH >= 0.1.5-rc.1
• 一个已配置、可正常启动的 DSH profile

核心功能¶

两个独立账本（之前 / 现在）¶

顶部两张卡片对应彼此独立的账本，点击可只查看其中一本：

baselineAt 默认是插件首次启动时刻，写在 ~/.dsh/token-ledger/ledger.json（DSH_HOME 可覆盖路径）。分界在读取时计算，不改写、不删除事件，可随时移动或恢复默认；两本相加始终等于合计。

页面顶部按钮支持：刷新、暂停刷新、补导历史、导出账本；还可通过接口移动分界或清空实时记录（见下文 HTTP 路由）。

四桶口径与精确数值¶

合计按 DSH 官方 tokenUsage 四桶相加：

total = inputTokens + cacheReadTokens + cacheWriteTokens + outputTokens

• inputTokens 与 uncachedInputTokens 为别名，只取其一。
• reasoningTokens 属于 outputTokens 子集，单独展示、不重复累加。
• 安装前 whale 历史往往只有总量、无四桶拆分，故「之前」账本书的四桶显示可能为 0 而总量有值；「现在」从第一条实时记录起四桶齐全。页面构成条会注明「四桶之和可能小于合计」。

页面上 token 数一律使用账本原始整数，仅加千分位分隔符，不用 K/M/B 缩写，不做四舍五入或估算。

全局筛选与页面区块¶

筛选对 KPI、构成条、趋势图、按会话/模型/周月表、消耗明细同步生效：

• 快捷：全部时间、今天、本周、上周、本月、上月、近 7 天、近 30 天
• 自定义日期区间、任选 ISO 周或自然月
• 「清除筛选」回到全部

统计页还包含两本账卡片、消耗构成与趋势、按会话/按模型/按周月汇总、可搜索的消耗明细，以及「统计口径」说明区。明暗主题跟随宿主，样式使用 --dsw-alias-* 变量。

轮询、ETag 与本地回退（v1.2.0）¶

页面默认每 5 秒轮询，可暂停。宿主对 data.json / query.json 按 revision 缓存并生成强 ETag；客户端带 If-None-Match 时，数据未变可返回 304 且无 body，避免重复下载大 JSON。标签页不可见时跳过定时请求，重新可见时立即刷新一次。

若宿主版本较旧、/query.json 返回 404，client.js 会改拉 /export.json 在浏览器本地做与宿主相同的聚合，并在筛选栏标注「页面本地统计」。宿主重启后自动切回服务端聚合。

数据与隐私¶

• 账本：~/.dsh/token-ledger/ledger.json（原子写：先 .tmp 再 rename）
• 事件超过 20000 条时，前半归档到 events.archive.json
• 会话数上限 4000，超出按最久未活跃淘汰
• 全部本地保存；HTTP 路由仅回环 + 同源放行，并受 DSH_TOKEN_LEDGER_HOSTS 等信任栅栏约束

安装与启用¶

官方 README 给出的步骤如下：先把仓库放到 profile 的 plugins 目录，再在 package.json 里以 link: 注册 bundle。

# 1) 把仓库放到 profile 的 plugins 目录
git clone https://github.com/6600788/dsh-token-ledger.git \
  ~/.dsh/plugins/dsh-token-ledger

# 2) 在 profile 的 package.json 里注册（路径按实际位置调整）
#    dependencies:
#      "dsh-token-ledger": "link:../plugins/dsh-token-ledger"
#    dsh.profile.bundles:
#      - "dsh-token-ledger"

也可通过 DSH 插件管理命令启用已安装的 bundle；启用后 profile 的 dsh.profile.bundles 会追加 dsh-token-ledger，依赖以 link: 指向插件目录。

启动行为：

• 仅 client 变更：刷新 GUI 即可看到新界面。
• host（lib/index.js）变更：完全退出 DSH（含托盘）再重启，使 /query.json、/baseline 等路由生效。

典型用法¶

打开统计页¶

启用 bundle 并启动 DSH 后，在左侧栏点击「Token 账本」进入统计页。可用顶部快捷筛选查看「本周」或「近 30 天」消耗，或在「消耗明细」中按会话、模型搜索。

从现在重新起账¶

需要把「现在」账单独清零分界、又保留历史总量时，可在页面操作中移动分界（等价于 POST /dsh-token-ledger/baseline）。恢复默认分界则回到首次启动时刻。

补导安装前 whale 历史¶

若首次导入不完整，可点「补导历史」，或调用：

# 需通过 GUI 同源或回环访问，具体 Origin 以宿主打印的 GUI 地址为准
curl -X POST "${GUI_ORIGIN}/dsh-token-ledger/import-history"

导出与自检接口¶

curl "${GUI_ORIGIN}/dsh-token-ledger/health.json"
# 示例字段：ok、plugin、version、revision、baselineAt

curl "${GUI_ORIGIN}/dsh-token-ledger/query.json?group=all"
# 含 groups / weeks / months / facets 的聚合 JSON

条件请求轮询示例（摘自 README）：

curl -i "${GUI_ORIGIN}/dsh-token-ledger/health.json"

curl -i -H 'If-None-Match: "<etag>"' \
  "${GUI_ORIGIN}/dsh-token-ledger/query.json?group=all"

开发者在仓库根目录可运行 npm test 做语法检查与 exact / mock-host / parity 等套件回归。

适用场景与注意¶

适合谁： 需要在 DSH 内长期核对 token、区分安装前后两段用量、按周月复盘模型与会话消耗，且希望数字与官方四桶口径一致、不做缩写的开发者或团队。

安全与权限： 插件以当前 DSH 进程权限运行，能读写 ~/.dsh 下账本与会话相关数据。安装前应阅读 lib/index.js、lib/client.js 与 LICENSE，确认路由信任栅栏与数据来源（仅 whale 账本导入路径等）符合你的环境策略。POST /dsh-token-ledger/reset 清空实时记录需 {"confirm":true}，操作前建议先 export.json 备份。

生态说明： DSH 倡导「一切皆插件」；本插件为社区贡献，星标与活跃度以仓库现况为准，本文不引用未在资料中出现的用户案例或反馈数据。

结尾¶

dsh-token-ledger 把 token 用量做成可筛选、可导出、双账本划分的本机账本，并强调四桶精确计数与 304 条件轮询。若你在用 DSH 做智能体开发，可从目录页与 GitHub 获取源码与更新说明：

• 目录页：https://www.skillhub.cn/plugins/6600788/dsh-token-ledger
• 仓库：https://github.com/6600788/dsh-token-ledger