前言¶
在 DeepSeek Harness（DSH）里跑智能体，模型调用会不断产生 token 消耗。面板里偶尔能看到用量，但要把「每次用了什么模型、花了多少钱」留下来、按时段汇总、再和平台账单对一下，往往还得自己拼脚本或表格。
社区里已有侧重余额监控与可视化的插件（例如 dsh-damage-pulse）。dsh-cost-ledger 走的是另一条路：逐次记录、本地价目表估算、手填官方账单并并列差异，支持 JSON/CSV 导出与 dry-run。下面介绍它是什么、怎么装、怎么用，以及使用时需要接受的边界。
这是什么¶
dsh-cost-ledger 由维护者 dingchenhui0618-arch 发布，在 SkillHub 目录中归类为 admin-security。当前 GitHub 星标为 0；许可证为 MIT；package.json 标明依赖 DSH 版本 >=0.2.1-rc.2 <0.3.0。
一句话定位：给 DSH 的可核对 token 成本账——每次模型调用记下 provider、model、各类 token 与按本地价目表算出的 CNY；按小时、日、会话聚合；支持导出与 dry-run；并把用户手填的平台账单与本地估算并列，直接看差多少。
它不查余额、不发通知、不做角色动画；灵感来自 wssfk12138/dsh-damage-pulse 的「成本应该被看见」这一问题意识，但是独立实现，不是 fork，两者可各自安装、互不依赖。
核心功能¶
捕获与记账¶
插件在 host 端用 llm/stream waterfall 包住每次流式调用，从 adapter 的 usage chunk 读取用量；流结束时向 append-only 账本写一行 JSONL。
每条记录包含：时间、hour / day（默认北京时间）、session（无会话时记为 purpose:<purpose> 或 unattributed）、provider、model、purpose、各类 token 字段、usageSource（adapter / estimated / missing）、价目表命中项、峰/谷档位、分项与总费用（整数 nano-CNY，1 CNY = 10⁹ nano-CNY）、status / finish / ms / error。
不记录 prompt、回复正文、工具参数或凭据，账本里只有计费元数据。
两种数字，不混写¶
- 本地估算：adapter 上报的 token ×
$DSH_HOME/cost-ledger-prices.json（或内置表）中的费率；无 usage 时按官方文档字符比例估算，并标为estimated。 - 实际账单：在面板或 CLI 手填的平台金额，只进入
actual_cny，不覆盖估算。 - 差异：
diff = actual − estimated；未手填的时段留空，不补零。
价目表与未定价¶
默认读 $DSH_HOME/cost-ledger-prices.json；不存在则用内置表。内置表仅覆盖 DeepSeek 官方 provider（deepseek-official、deepseek-account）的公开价格（README 注明 2026-10-19 自官方文档抓取），并含北京时间峰谷与 2026 年法定节假日。
中转 provider 不会自动套官方价：没有显式 provider + model 条目则记为 unpriced，费用为 0，避免「看起来像算对了其实是错的」。自定义价目表结构见仓库 examples/prices.example.json。
面板¶
安装并重启 profile 后，对话视图会出现「成本账」Tab：合计与分档聚合、填/改账单、最近调用明细、导出 JSON/CSV、dry-run、重载价目表等。表格只展示元数据。
导出与 CLI¶
面板操作与命令行等价。仓库内示例：
node bin/cost-ledger.mjs export --json --scope day
node bin/cost-ledger.mjs export --csv --scope session --out ledger.csv
node bin/cost-ledger.mjs export --json --detail
node bin/cost-ledger.mjs export --dry-run --scope hour
node bin/cost-ledger.mjs export --json --since 2026-10-18 --until 2026-10-19
装成 npm bin 后命令名为 dsh-cost-ledger。
手填账单示例：
node bin/cost-ledger.mjs bill set --scope day --key 2026-10-19 --amount 12.34 --note "平台账单页"
node bin/cost-ledger.mjs bill list
node bin/cost-ledger.mjs bill delete --scope day --key 2026-10-19
key 口径：hour 为 YYYY-MM-DDTHH（北京时间），day 为 YYYY-MM-DD，session 为会话 id。
数据文件（本机）¶
| 文件 | 默认路径 | 说明 |
|---|---|---|
| 调用账本 | $DSH_HOME/cost-ledger.jsonl |
一行一次调用 |
| 手填账单 | $DSH_HOME/cost-ledger-bills.json |
官方金额与备注 |
| 价目表 | $DSH_HOME/cost-ledger-prices.json |
可选 |
插件不联网；账本不会自动轮转，需自行归档。README 说明账本文件在用户目录，同权限进程可改，用于核对而非防篡改。
安装与启用¶
从 GitHub 安装（README 写明当前没有 npm 发布）：
dsh plugin --profile <你的 profile> add github:dingchenhui0618-arch/dsh-cost-ledger
本地开发目录安装：
dsh plugin --profile <你的 profile> add D:\Projects\dsh-cost-ledger
装好后重启对应 profile。README 注明：新插件主要在开发机跑过测试与构建，未宣称在每个 DSH 版本上都验证；slot 契约变化时面板可能降级消失，host 端记录仍会继续。
DSH 生态是「一切皆插件」；SkillHub 目录页 是社区站点，与 DeepSeek / 幻方无官方从属关系。
典型用法¶
- 按上文命令安装并重启 profile，正常对话产生
llm/stream调用。 - 打开对话视图「成本账」，按小时/日/会话查看本地估算合计；在平台账单出来后，用「填账单」或
bill set写入实际金额，对照差异列。 - 使用中转或自建 provider 时，在
cost-ledger-prices.json中为对应provider+model补条目，避免大量unpriced。 - 需要报表或外部分析时，用
export --json|--csv或--detail；改价目表前可用--dry-run预览聚合结果。
适用场景与注意¶
适合：需要在本机留痕、按会话/日核对 token 与 CNY、要把本地估算与平台账单并排对比的 DSH 用户；需要可导出、可脚本化的成本元数据，而不是余额动画或微信提醒。
注意：
- 本地估算不是官方结算凭据；优惠、赠送余额、缓存计费差异等都会体现在
diff上。 - usage 缺失时只能
estimated，勿与 adapter 事实混谈。 - 内置价目表与 2026 年节假日会过期，改价后请更新
prices.json或自定义holidays。 - 插件以当前 DSH 进程的权限运行，安装前应自行查看 GitHub 源码 与 MIT 许可证，确认符合你的安全与合规要求。
结尾¶
dsh-cost-ledger 把「每次调用花了多少」写成可导出、可对账的本机账本，并把估算与手填账单分开列示。若要安装或看完整参数，可访问目录页 skillhub.cn/plugins/dingchenhui0618-arch/dsh-cost-ledger 与仓库 github.com/dingchenhui0618-arch/dsh-cost-ledger。
