前言¶
用 DeepSeek Harness（DSH）跑智能体时，token 消耗分散在大量会话日志里，平台账单又和「若按公开 API 牌价计费会是多少」不是同一套口径。想快速回答「账户还剩多少钱」「这几天哪个模型在吃预算」，往往要在控制台和本地日志之间来回切换。
dshx-token-cost 是维护者 callaumyan-design 发布的客户端类 DSH 插件（当前版本 v2.1.0，MIT 许可证）。它在 DSH 设置里增加 用量与费用 页面：一侧读 DeepSeek 平台接口展示账户余额，另一侧扫描本机 ~/.dsh/sessions 会话日志，按天、按模型汇总 token，并按各厂商公开价目估算费用。社区目录见 SkillHub，源码在 GitHub。
这是什么¶
一句话：dshx-token-cost 是 DSH 设置页插件，同时回答两个问题——账户里还剩多少钱（平台余额），以及本机每天、每个模型消耗了多少 token、按 API 牌价折算是多少钱（本地日志统计）。
打开路径：设置 → 用量与费用。插件以当前 DSH 进程权限运行；安装或启用前建议自行查看仓库源码与许可证，确认符合你的环境策略。
核心功能¶
面板能回答的问题¶
| 问题 | 面板位置 |
|---|---|
| 账户还剩多少？ | 顶部「账户余额」卡片 |
| 这段时间花了多少钱（估算）？ | 区间汇总 → 估算费用 |
| 哪一天最贵？ | 每日用量表（点行展开当天模型明细） |
| 哪个模型在吃预算？ | 按模型汇总表 |
| 缓存命中情况？ | 区间汇总 → 缓存命中率；每日/按模型表中的缓存读写列 |
| 同一模型经过几条 provider 路由？ | 模型名后「N 条路由」标签（悬停看详情） |
| 每小时 token 与估算费用？ | 「按小时用量」图表（v2.1.0） |
账户余额与货币¶
余额来自 DeepSeek 平台接口。平台按币种返回多条钱包记录，且顺序不稳定，插件会按你在页面上选的 ¥ / $ 挑选对应钱包展示，不做跨币种换算；其他币种列在「另有 …」一行。
区间选择与记忆¶
可选 当月 / 当天 / 7 / 14 / 30 / 90 天，或通过「自定义」指定起止日期（最长 365 天）。「当月」指日历整月（每月 1 日至月末），状态行会回显实际覆盖的日期范围。区间与货币保存在 localStorage 的 dshx-token-cost/prefs；不可用时回落为默认（30 天 / 人民币）。
费用估算口径¶
显示的是估算，不是官方账单。 计算式为：
费用 = 输入 × 输入价 + 输出 × 输出价
+ 缓存读 × 缓存读价 + 缓存写 × 缓存写价
价目依据各厂商公开 API 牌价（pricing.js，README 记载核对于 2026-10-11）。人民币定价模型按公布的人民币价计；美元定价模型按美元价再经汇率折算。美元兑人民币汇率每天最多更新一次，来源依次为 open.er-api.com 与 api.frankfurter.app，缓存于 ~/.dsh/dshx-token-cost/rate.json；失败时用上次的已知汇率，否则内置默认 7.1。
需注意的口径：DeepSeek 统一按空闲时段价计，工作日高峰价为空闲价 2 倍，白天使用场景的估算可能偏低；部分 Gemini Flash 系列使用当前 introductory 价（官方计划 2027-01-01 调整）。
日志统计与性能¶
v2.0.0 起直接解压 zstd 读会话日志并维护持久化索引（~/.dsh/dshx-token-cost/index.json，保留 400 天），替代通过 harness sessionQuery 重放整份日志的方式；README 称冷启动约 2.5 秒，稳态刷新在毫秒级。扫描不读取凭据，只解析日志中的 request/header 与 assistant/message usage 字段，按日志顺序归属 provider/model。
状态目录（索引与汇率缓存）可用环境变量 DSHX_TOKEN_COST_STATE 覆盖。
HTTP 报表端点¶
Host 侧提供报表接口，供设置页或其它集成调用：
GET /dshx-token-cost/report?days=30[&force=1]
GET /dshx-token-cost/report?from=2026-10-01&to=2026-10-11[&force=1]
from/to 优先于 days，两端均含；force=1 会强制刷新索引与余额缓存。返回结构包含 balance 与 usage（含逐日 days、按模型汇总、v2.1.0 的 usage.hours 等字段）。
安装与启用¶
资料中未给出统一的 CLI 安装命令句式；可从 SkillHub 插件页 按 DSH 客户端的插件安装流程安装（package.json 中 dsh.marketplace.profiles 为 web 与 desktop，requiresRestart: true）。
安装后，副本位于：
~/.dsh/profiles/<profile>/node_modules/dshx-token-cost/
桌面 profile 的注册位置（本地 file: 开发时同理）：
~/.dsh/profiles/desktop/package.json→dependencies与dsh.profile.bundles~/.dsh/profiles/desktop/cordis.patch.yml→- id: dshx-token-cost
修改 host 路由或 bundle 后需重启 DSH 桌面端。用 file: 依赖开发时，pnpm 安装的是拷贝而非软链，改源码后需重新安装或拷贝才会生效。
典型用法¶
在设置页查看¶
- 启动 DSH 桌面端（或已安装插件的 web profile）。
- 打开 设置 → 用量与费用。
- 选择统计区间与货币；需要忽略短期缓存时可点「重新统计」（等价于请求带
force=1）。 - 在每日用量、按模型汇总、按小时图表中查看 token 与估算费用；窄屏下数字会压缩显示，完整值在 tooltip。
离线核对与自测¶
仓库提供 Node 脚本，便于在不打开 UI 的情况下核对统计结果：
node test.mjs 30 # 近 30 天逐日逐模型费用表
node test-endpoint.mjs # 端点断言
node test-client.mjs # 客户端渲染断言（需 react、jsdom）
node test-layout.mjs # 排版断言（需 Chrome/Edge）
客户端与排版测试的依赖可按 README 用 npm install --no-save 安装，并通过 NODE_PATH 或 DSHX_TEST_NODE_MODULES 指向 node_modules。
适用场景与注意¶
适合谁： 长期在单机 DSH 上跑多模型、多会话的开发者，需要在设置里一眼看到平台余额，并把本地 token 用量按模型拆成可比较的「若按公开 API 计费」估算。
不适合当作： 财务对账或官方消费明细；高峰/促销/企业协议价未完全建模时，估算与实扣会有偏差。
权限与安全： 插件读取本机会话日志并请求平台余额接口，以安装时 DSH 进程的权限执行。启用前请阅读 源码仓库 中的 index.js、usage.js、rate.js 等实现。
生态说明： DSH 采用「一切皆插件」的扩展方式；SkillHub 等社区目录由社区维护，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dshx-token-cost 把「平台还剩多少钱」和「本机日志里每天、每个模型烧了多少 token、按牌价估多少钱」收进同一设置页，并用持久化索引把大会话量下的刷新时间压到可用范围。需要安装说明与版本信息时，可看 SkillHub 目录页；实现细节、价目表与测试命令以 GitHub README 为准。
