前言¶
在 DeepSeek Harness（DSH）里跑智能体时，ctx.tokenMeter 只能反映请求压力：Harness 不把 Token 换算成金额，也不内置价目表。你真正关心的三件事往往分散在不同地方——账户余额在 DeepSeek 官方接口，当天实际扣款在本地余额账本，按小时的 Token 则在会话日志里。要对齐「花了多少钱」和「Token 花在哪段时间」，需要把这三路数据拼起来。dsh-token-bill 是社区插件，维护者为 SanChou0627，分类为联网工具；它向模型暴露两个只读工具，汇总余额、账本观测到的当日费用、按小时 Token 统计，并写出 Markdown / HTML / JSON 账单。
这是什么¶
dsh-token-bill（GitHub：SanChou0627/dsh-token-bill，当前 package 版本 0.1.0，MIT 许可证）的定位是：在 DSH Web 配置下，用 token_status 查实时状态，用 token_bill 生成带柱状图与明细表的账单。不需要额外 UI 或常驻守护进程；插件不写入账本、会话日志或凭据文件。
设计原则在 README 里写得很清楚：金额以观测为准，Token 以计量为准。当日总费用优先来自 $DSH_HOME/.dshw-usage.json 余额账本（由 dsh-whale-widget 写入）；各小时费用则在账本总额已知时，用价目表做分摊校准，保证 sum(小时金额) === 当日金额（金额以 1e-8 元整数存储）。
核心功能¶
数据来源¶
| 需求 | 来源 | 说明 |
|---|---|---|
| 实时余额 | GET https://api.deepseek.com/user/balance |
API Key 鉴权；失败时可回退到账本最后一次观测（会标注） |
| 当日实际支出 | $DSH_HOME/.dshw-usage.json |
账本缺失时降级为价目表估算并明确标注 |
| 按小时 Token | $DSH_HOME/sessions/**/session.v*.jsonl.zstd（及旧版未压缩 jsonl） |
使用 provider 上报的四个互斥桶：inputTokens、cacheReadTokens、cacheWriteTokens、outputTokens |
API Key 从环境变量 DEEPSEEK_API_KEY（或 DSH_DEEPSEEK_API_KEY、DEEPSEEK_KEY）或 $DSH_HOME/.credentials.yaml 中的 refs.DEEPSEEK_API_KEY 读取。
两个模型工具¶
token_status：返回当日日期、余额、币种、balanceSource（api 或 ledger）、是否 stale、账本观测的当日费用、Token 汇总与调用次数等；可选参数 includeLedger（默认 true）、includePricing（默认 false）。
token_bill：按北京时区日期（默认当天）生成账单；支持 days 汇总最近 N 天、costMode（ledger | token | both，默认 ledger）、write（默认 true）、formats（默认 ["html","md"]）。输出包含按小时 Token / 费用条、峰谷拆分、峰值时段等；文件默认写到 $DSH_HOME/token-bill/ 下的 token-bill-<day>.{html,md,json}，可通过环境变量 DSH_TOKEN_BILL_DIR 或配置项 outDir 覆盖。
账单支持峰谷电价思路：北京时区峰段、周末与法定假日谷段，并在报告中区分 peak / valley Token。
安装与启用¶
环境要求：Node ≥ 22.12（插件通过 require(esm) 解析 DSH 同级依赖）；DSH 的 Web profile 需挂载 tools 服务。
下面介绍官方 README 中的安装方式。从 registry 安装（文档注明发布可用后）：
dsh plugin --profile web add dsh-token-bill
本地开发或自管副本时，使用 link 指向绝对路径：
dsh plugin --profile web add link:/absolute/path/to/dsh-token-bill
安装后，新会话中模型即可看到上述两个工具。若 profile 未自动重载，需重启 DSH Web 服务。
典型用法¶
用法由智能体在对话中调用工具完成，无需单独 CLI。常见流程如下。
- 先调用
token_status，快速确认余额来源、当日账本观测费用与 Token 桶分布（含 cache 命中率相关统计）。 - 需要归档或分享时，调用
token_bill，按需设置day、costMode与formats；默认会写入 HTML（内联 SVG 柱状图）与 Markdown，也可只要 JSON 供脚本消费。 - 若已运行 dsh-whale-widget 并产生
.dshw-usage.json，将costMode保持为ledger，使日总额与账户余额变动一致；无账本时接受带「估算」标注的token模式。
token_bill 返回的 text 字段即人类可读的完整渲染，与落盘文件内容一致；files 列出已写入路径。
适用场景与注意¶
适合在 DSH 中长期跑 Web 智能体、需要把 官方余额、账本观测扣款 与 会话级 Token 计量 对齐的开发者与团队。按小时柱状图便于对照高峰时段与费用分摊；只读设计适合纳入日常巡检，而不改变 Harness 自身的计量语义。
安装前请注意：插件以当前 DSH 进程权限运行，会读取 API Key、账本与会话日志，并可能请求 api.deepseek.com；安装前应自行审阅 GitHub 仓库 源码与 MIT 许可证。社区目录 SkillHub 插件页 与 DeepSeek / 幻方无官方从属关系，属 DSH「一切皆插件」生态中的第三方条目。
未运行 dsh-whale-widget 时，账本不存在，当日费用只能依赖价目表估算；余额仍可从 live API 获取。充值记入账本的 creditUnits，不会虚增「支出」；账本行无法闭合时，插件会说明而非静默报错。
结尾¶
dsh-token-bill 把分散在三处的余额、账本与 Session 日志接到同一套规则下，用两个 agent 工具输出可存档的账单。目录页：https://www.skillhub.cn/plugins/SanChou0627/dsh-token-bill；源码与完整参数说明：https://github.com/SanChou0627/dsh-token-bill。
