npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@zhz8888/dsh-token-ledger

v1.2.0

Published

Transparent, auditable token accounting for DeepSeek Harness: a restart-safe ledger over the durable session log, a CLI that recomputes it from raw logs and diffs the result, and a bill — by workspace, session, model or provider, exportable as CSV or JSON

Readme

dsh-token-ledger

为 DeepSeek Harness 提供透明、可审计的 token 记账。

CI npm license DSH last commit

English | 中文


本仓库是一个 fork。 原项目是 chenmiao8563/dsh-token-ledger, 它在 v1.1.2 之前以 @chenmiao8563/dsh-token-ledger 这个包名发布。本 fork 以 @zhz8888/dsh-token-ledger 延续这份工作,保留上游的 MIT 声明并在其旁边加上自己的, 同时把原仓库作为 upstream 这个 git remote 保留下来。详见许可证。

这是一本账本,不是一块仪表盘。它把 DSH 的持久会话日志折叠成 token 用量,保证重启不丢, 而且——这是关键——允许你从原始日志重算同一批数字并与之对账。

$ dsh-token-ledger audit
scanned 139 session log(s), 344203 events, 29 forked session(s), 0 unreadable

  stored      6901 calls  1205685663 tokens
  recomputed  6901 calls  1205685663 tokens

  audit: match — the stored ledger equals a fresh fold of the raw logs

只想看漂亮的图表,市面上有十几个同类插件。这个插件是给你需要为这个数字辩护的时候用的。

设置页有四个页签:概览(账本本身,含每档区间的预计花费)、费率(各厂商模型的价格表 ——默认列出最新几个,每个厂商都能展开看全部——与实时美元汇率)、账单(把同一批用量折算成钱 ——按工作区 / 会话 / 模型 / 供应商四个分组自上而下展开,每个分组各配五个时间段)、备份 (把账本导出成 CSV 或 JSON,以及把 MySQL / MariaDB / PostgreSQL 的数据库导出成 .sql 文件); 另有一个完全不依赖宿主的 CLI。

目录

快速上手

# 1. 把插件装进某个 profile
dsh plugin --profile web add @zhz8888/dsh-token-ledger

# 2. 重启 DSH,然后确认那一行进去了
dsh --profile web --dump-config | grep token-ledger

# 3. 在对话里问账本
/tokens

或者完全不启动宿主——CLI 自己直接读原始日志:

dsh-token-ledger summary   # 已存的账本
dsh-token-ledger audit     # 从原始日志重算并对比

账本写在 <DSH_HOME>/token-ledger/ledger.json,全新安装会先把磁盘上已有的历史折叠进来, 而不是从今天开始记。它需要 DSH ^0.2.0-rc.1(实测针对 0.2.1-rc.3)与 Node ≥ 22.15.0, 其余条件都是可选的。

需要什么

| | 要求 | 说明 | | --- | --- | --- | | DSH | ^0.2.0-rc.1 | 实测针对 0.2.1-rc.3。这一条是有约束力的:DSH 会跳过区间不覆盖当前宿主的插件。详见兼容性。 | | Node | ≥ 22.15.0 | CLI 需要解码 Zstandard 帧。宿主端本身没有版本相关要求。 | | Profile | 任意 | 设置页需要带 web 服务器的 profile(web 或 desktop);/tokens 与 CLI 在任何 profile 下都可用。 | | 网络 | 可选 | 只有价目表与美元汇率需要联网。rates: false 会去掉全部请求。 | | 磁盘 | 一个可写的 <DSH_HOME>/token-ledger/ | 除了你主动要求的导出,它只写这一个目录。 |

界面截图

设置页各页签的实机截图:

概览:本月总计、今日实时,以及一年的活跃度:

概览页:本月总计、今日实时与年度活跃度热力图

日历视图:一个月的形状在这里——最忙的一天、最轻松的一天、工作到最晚的一天, 下面是同一批用量按模型拆分:

日历视图:本月热力图与最忙、最轻松、最晚的一天,以及按模型的用量

近 7 天的柱状图,以及同样的按模型拆分:

近 7 天 Token 柱状图与按模型的用量

费率:实时美元汇率与各厂商公布的价目表:

费率页:美元汇率与各厂商模型价格

为什么别的插件装不上时它能装上

| 特性 | 为什么重要 | | --- | --- | | 没有任何东西会被装给你 | 无运行时依赖;声明的 peer 全都是可选宿主包——DSH 内部包的版本漂移不可能把第二份 harness 拖进你的 profile。 | | 零安装脚本 | 直接用 git URL dsh plugin add 即可——pnpm 没有构建要拦,你也不必去 allowBuilds 里加白名单。 | | 只 import node: | 宿主端可以从任意 profile(web / desktop / headless / TUI)加载,不需要解析任何包。 | | 不碰模型可见面 | 它不注册任何提示词段、消息或工具,因此不会改变请求前缀,也不会损害 KV cache 复用。 | | 故障降级 | 每个钩子都有保护。账本出问题只记一条警告,绝不让会话失败。 |

安装

# 从 npm
dsh plugin --profile web add @zhz8888/dsh-token-ledger

# 从 git URL(不涉及任何构建步骤)
dsh plugin --profile web add github:zhz8888/dsh-token-ledger

# 从本地仓库
dsh plugin --profile web add /absolute/path/to/dsh-token-ledger

npm 包名带 scope,是因为 npm 会把分隔符归一化后比较,无 scope 的 dsh-token-ledger 被判为与已有包过于相似而拒绝发布。CLI 命令名仍然是 dsh-token-ledger。

重启 DSH,然后确认那一行进去了:

dsh --profile web --dump-config | grep token-ledger

在对话里用 /tokens:

/tokens
/tokens export     # 把 CSV 与 JSON 写到 <DSH_HOME>/token-ledger/exports/
/tokens json       # 原始快照
/tokens path       # 账本文件位置

账本写在 <DSH_HOME>/token-ledger/ledger.json。

命令行

不需要 DSH 在运行——它直接读原始日志。

dsh-token-ledger [summary] [选项]     打印已存账本(默认)
dsh-token-ledger audit   [选项]       从原始日志重算并对比
dsh-token-ledger rebuild [选项]       从原始日志重算
dsh-token-ledger export  [选项]       导出 CSV 与 JSON
dsh-token-ledger help    [选项]       打印用法说明

--home <path>    DSH home(默认读 DSH_HOME 环境变量,其次 ~/.dsh)
--ledger <path>  要读写的账本文件
--out <path>     导出目录
--days <n>       摘要显示天数(默认 7)
--models <n>     摘要显示模型数(默认 5)
--write          配合 rebuild:覆盖已存账本
--json           机器可读输出
--quiet          抑制人类可读摘要,只保留退出码
-h, --help       打印用法说明
-v, --version    打印版本号

退出码:0 成功或审计通过,1 审计发现真实差异,2 用法错误或输入不可读。 因此它可以挂进定时任务。

设置页

浏览器端会在设置侧边栏注册一个 用量账本 分区,顶部有 概览 / 费率 / 账单 / 备份 四个按钮。 它自己的文案会注册到宿主的语言服务上,因此跟随宿主的语言。

  • 概览 —— 本月总计、今日实时、用量热力图与按模型拆分,每档区间都给出预计花费。
  • 费率 —— 实时美元汇率与各厂商公布的价目表,每个厂商都能展开看它的全部模型,每一项都能手改, 以应对联网不可用的时候。
  • 账单 —— 同一批用量折算成钱:工作区、会话、模型、供应商自上而下堆叠,每个分组各有自己的 时间段。
  • 备份 —— 账本的 CSV / JSON 导出,以及数据库备份:填一个 MySQL、MariaDB 或 PostgreSQL 的连接,就能把这个库导出成 .sql 文件。导出由数据库自带的工具完成,因此那台机器上要能找到它。

设置页完整说明——每个页签展示什么,以及页面上的每个价格分别来自哪里。

页面自己的中英文文案在 locale/zh.json 与 locale/en.json,是纯数据:改完刷新页面 即可,不必重启宿主。两种语言共用同一套键。

计数规则

| 规则 | 行为 | | --- | --- | | 只认成功锚点 | 用量取自已完成的步与一次压缩调用。失败或被取消的尝试不会追加这两种事件,因此永远不计入。 | | 流式样本是替换,不是相加 | 同一步先出 usage chunk、后出最终消息时,最终值替换早期样本——无论哪种情况都算一次调用。 | | totalTokens 是推导出来的 | 它是四个桶之和,绝不采信提供方自己的总量字段。 | | 推理 token 是子集 | 单独报告,绝不相加进总量,因为它本来就在 outputTokens 里面。 | | 按本地日历日 | 是你所在时区的日,不是 UTC 日。 | | fork 切、resume 不切 | fork 的前缀属于父会话;resume 的前缀是这个会话自己的。 |

这些数字是怎么数出来的——计数规则、fork 与 resume 的区分, 以及审计那两类差异分别意味着什么。

配置

按 id 覆盖组合条目:

- id: token-ledger
  config:
    ledgerPath: 'D:/dsh/ledger.json'   # 默认 <DSH_HOME>/token-ledger/ledger.json
    backfill: false                     # 默认 true——启动时折叠已存历史
    backfillLogs: false                 # 默认 true——同时读取磁盘上的会话日志
    rates: false                        # 默认 true——false 时完全不发网络请求

完整配置——每一个配置项、它改变什么,以及历史从哪里来。

它刻意不做的事

  • 概览页给出写明口径的预计花费,账单页给出逐行明细。 两者都会写明价格来源、换算用的汇率、 每一个靠名字匹配上的价格,以及每一个没能定价的模型,因此这些数字是用来核对的,不是用来信的。 它们都不是厂商开给你的账单,也不声称是。
  • 不内置价目表。 价格要么从一个可选的源联网取(默认是各家官方价目),要么你自己填。 内置一份价目表几周内就会过期,而且每次更新都得发一个版本。
  • 不注册面向模型的工具。 工具 schema 会在每次请求上花提示词 token 并改变缓存前缀—— 对一个 token 记账插件来说这很荒唐。人类场景由 /tokens 与 CLI 覆盖。

权限

它对运行它的机器做了什么——写清楚,好让它可以被核对,而不是被猜测:

| 能力 | 实际行为 | | --- | --- | | 文件 | 以只读方式读取 <DSH_HOME>/sessions/ 下的会话日志;读取 <DSH_HOME>/settings.yaml 只为拿到账单上显示的供应商名称。写入只发生在它自己的目录里——<DSH_HOME>/token-ledger/ 下的 ledger.json、rates.json、databases.json 与 backups/——以及你主动要求的导出。该目录之外既不写也不删。 | | 网络 | 只在费率功能开启时发起普通 HTTPS GET:价格目录、美元汇率,以及最多 3 个厂商定价页。rates: false 会去掉全部请求。浏览器半边不发起任何外部请求。备份页会连上你自己配置的数据库服务器,走的是数据库自己的协议(3306 / 5432),而且只在你按下「测试连接」或「备份」时才会。 | | 命令 | 没有 shell——任何东西都不会交给 sh -c。备份页在你按下「备份」时会启动数据库自带的导出工具(mysqldump / mariadb-dump / pg_dump)作为子进程,参数以数组形式传入,而不是拼成一行命令。除此之外没有子进程,安装时与运行时都没有。它对外提供的是通过宿主自身 commands 服务注册的 /tokens 斜杠命令,以及你自己运行的 dsh-token-ledger 可执行文件。 | | 凭据 | 不读取任何提供方的凭据:process.env 只在未显式传入 home 时用来解析 DSH_HOME;不读任何提供方 API key、不碰 keychain、不做 OAuth。备份页会保存你自己填的数据库密码,写在 <DSH_HOME>/token-ledger/databases.json,只有当前用户可读;密码通过一个文件交给数据库自己的客户端工具,导出一结束就删掉,绝不出现在命令行里。 |

以上每一条都可以对着源码核对——import、URL 与状态目录都在 lib/ 里, 而保证"安装侧"成立的那些打包不变式由 pnpm run verify 断言。完整版本见 兼容性。

排查

插件根本没挂载。 DSH 会跳过区间不覆盖当前宿主的插件,而且只在宿主自己的日志里说明。这里的区间是 ^0.2.0-rc.1,0.1.x 宿主装不上——见兼容性。

账本是空的。 全新安装本该显示磁盘上已有的历史,所以空账本通常是两种原因:磁盘折叠被关了, 或者日志不在插件要找的位置。CLI 读的是和宿主同一批文件,可以从它这一侧核对:

dsh-token-ledger rebuild --home ~/.dsh --write
dsh-token-ledger audit --home ~/.dsh

backfillLogs: false 关掉磁盘折叠,backfill: false 两个都关,账本就从头开始。

审计报 "mismatch"。 它会区分"会话还在跑、只是还没落盘"与真正的分歧,只有后者算失败——见 这些数字是怎么数出来的。

费用显示短横线,或者页面写着"还没有价格"。 本包不内置价目表——内置一份几周内就会过期。价格要么从一个你选定的源联网取, 要么在费率页上手填;宿主还没拿到价格时会明说,而不是给出一个理直气壮的 ¥0.00。 完全离线的宿主仍会提供上次已取回的结果,并显示它有多旧。

/tokens 没有注册。 这个命令通过宿主自身的 commands 服务注册,而本包把它声明为可选 peer。 没有该服务的 profile 根本没有斜杠命令;CLI 不受影响,照样能读账本。

数字和厂商后台对不上。 账单是估算值:会话日志记下的 Token × 路由真正指向的那个模型的公开价目。 它不是发票,也不掌握厂商的折扣、额度、套餐与失败重试的情况。

想从头来过。 删掉 <DSH_HOME>/token-ledger/ 再重启;下次启动会重新折叠磁盘上的历史。

卸载

dsh plugin --profile web remove @zhz8888/dsh-token-ledger

账本文件是故意不删的——要清空历史请自行删除 <DSH_HOME>/token-ledger/。

文档

README 讲的是怎么用这个插件;其余细节都在 docs/ 里:

| 文档 | 内容 | | --- | --- | | 这些数字是怎么数出来的 | 计数规则、fork 与 resume、以及审计。 | | 设置页 | 三个页签的完整说明。 | | 配置 | 插件会读到的每一个配置项。 | | 兼容性 | 需要哪个 DSH,以及它会碰什么。 | | 开发与发布 | 怎么改这个插件,以及怎么发布它。 | | 发布到 npm | 手动发布那条路,用于一个 scope 下的第一次发布。 | | 验证记录 | 实际验证了什么,以及哪些没有验证。 |

每一篇都有中英两个版本,语言切换在每篇的开头。英文索引在 README.md。

参与贡献

欢迎提 issue 与 pull request。

git clone https://github.com/zhz8888/dsh-token-ledger
cd dsh-token-ledger
pnpm install
pnpm test          # 297 个测试,14 个文件
pnpm run verify    # 打包不变式

两道门禁都通过、且 diff 里没有夹带无关改动,就算可以了。本仓库有两条约定:README 是这个包 契约的一部分;新的说法要么带着证据进 docs/VERIFICATION.md,要么就不要进来。其余见 开发与发布。

安全

这个插件会读会话日志、读 settings.yaml 里账单要显示的供应商名,并且只写 <DSH_HOME>/token-ledger/ 目录。它不读取任何提供方凭据;备份页会保存你自己填的数据库 密码,写在同一个目录里、只有当前用户可读。它到底碰了哪些东西,逐条列在 权限里,可以对着源码核对,不必只听它说。

报告安全问题请不要开公开 issue。 用本仓库 Security 标签页里的私有报告 (Report a vulnerability)通道,它能在不公开细节的情况下联系到维护者; 如果你的账号看不到这个选项,直接用 package.json 里的邮箱联系维护者。

支持

带上 DSH 版本、profile 类型,以及 dsh-token-ledger audit 的输出(它会打印自己扫了什么), 通常一个来回就能定位。

致谢

  • 本项目是 chenmiao8563/dsh-token-ledger 的 fork,那才是原项目。这里的每一行都源自它,它的 MIT 声明随代码同行,upstream 这个 remote 指向的就是它。
  • 它绑定的槽位注册表、语言服务与设置外壳都来自 DeepSeek Harness。
  • 厂商标识是各家官方的那一套,取自它们自己的官网与 Simple Icons,商标权仍属各自权利人。
  • 不公布机器可读价格的那些厂商,其价目来自 models.dev; DeepSeek、Z.ai 与腾讯的价格则当场读自它们自己的定价页。

许可证

MIT —— 见 LICENSE。

本仓库是 chenmiao8563/dsh-token-ledger 的 fork,那才是原项目,它在 v1.1.2 之前以 @chenmiao8563/dsh-token-ledger 这个包名发布。 上游的 MIT 声明是被保留而不是被替换的——MIT 要求原始声明随代码同行——本 fork 的权利人 声明则加在旁边。

代码采用 MIT 许可证。包内附带的厂商标识(OpenAI、Anthropic、Google、DeepSeek、Qwen、 xAI、Z.ai、Kimi、MiniMax、腾讯、小米、字节跳动)属于各自权利人的商标,仅用于标识 这一行价格属于谁,不在本许可证覆盖范围内。