前言¶
DeepSeek Harness (DSH) 的理念是“一切皆插件”。在使用 DSH 进行智能体开发或运行时，追踪 API 调用的实际成本是一个常见需求。通常的日志记录往往不够精确，或者依赖估算，容易导致计费偏差。
为了解决这个问题，需要一种机制，能够将使用情况报告转换为可引用的、仅追加的 JSONL 费用收据。dsh-spend-receipt 插件正是为此设计，它解决了传统计费方式中缺乏透明度和浮点数精度问题。
插件简介¶
这是一个 DeepSeek Harness 函数插件，由用户 jwilson411 维护。它的核心作用是将 Harness 的使用情况报告转化为一个可引用的、仅追加的 JSONL 费用收据，并提供一个 spend_receipt 工具来读取回这些数据（包括最后 N 行、总计和缓存命中率）。
核心功能¶
该插件主要解决以下问题：
-
可验证的计费记录
每一条记录都包含实际报告的 token 数、定价信息、时间窗口以及来源。阅读者可以独立重新计算成本，无需信任此包。它不进行任何文本分词或估算，缺失的定价不会填补为零，而是记录为usd: null。 -
仅追加的 JSONL 格式
收据文件采用 JSONL 格式，且只追加不修改。即使发生崩溃，也不会导致数据损坏。 -
精确的定价与计算
使用nano_usd整数进行总计计算，避免浮点漂移。定价基于 2026-08-29 的 DeepSeek 公开价格表，并区分高峰（Peak）和低谷（Off-peak）窗口。 -
会话日志同步
支持从会话日志同步使用情况，读取 JSONL 日志并提取其中的 usage 事件。
安装与配置¶
在安装之前，请确保环境满足依赖要求：Node.js >= 22.14.0。
1. 安装插件
执行以下命令将插件添加到 web 配置文件中：
dsh plugin --profile web add github:jwilson411/dsh-spend-receipt
dsh plugin 命令会将插件包 manifest 中的 dsh.bundle.patch 追加到配置中，并应用 cordis.patch.yml 层。
2. 配置插件
插件需要在 cordis.patch.yml 中进行配置。注意，目标配置项（id: spend-receipt）会替换整行配置，因此需要重新声明所有需要保留的字段。
- id: spend-receipt
config:
receiptPath: ~/.dsh/spend-receipt.jsonl
sessionLog: ~/.dsh/sessions/current.jsonl
| 配置项 | 环境变量回退 | 默认值 |
|---|---|---|
receiptPath |
DSH_SPEND_RECEIPT_PATH |
./spend-receipt.jsonl |
sessionLog |
DSH_SPEND_RECEIPT_SESSION_LOG |
未设置（仅读模式） |
sessionId |
DSH_SPEND_RECEIPT_SESSION_ID |
未设置（行记录 null） |
limit |
— | 20 |
使用方法¶
安装并配置完成后，可以通过 spend_receipt 工具来查看费用收据。
1. 基本用法
该工具支持两个参数：
* limit：返回最近 N 条记录，默认为配置的 limit。
* sync：是否先扫描会话日志同步新数据，默认为 true。设为 false 则仅报告已记录的数据。
2. 示例输出
工具会返回收据路径、使用的费率表、具体行数据、总计以及缓存命中率。示例 JSONL 记录如下：
{
"ts": "2026-08-29T09:00:12.000Z",
"session_id": "sess-7c2",
"model": "deepseek-v4-pro",
"input_tokens": 12000,
"cache_hit_tokens": 9000,
"output_tokens": 800,
"usd": 0.007524,
"currency": "USD",
"nano_usd": 7524000,
"rate_table": "deepseek-v4@2026-08-29",
"rate_tier": "peak",
"ts_source": "event",
"source": { "kind": "session-log", "path": "…/session.jsonl", "line": 3 }
}
适用场景与注意¶
适用场景：
* 需要精确核算成本的开发者和团队。
* 需要审计 API 调用详情和缓存命中率的场景。
* 希望避免浮点数计算误差的财务统计。
注意事项：
* 依赖版本：插件依赖 @deepseek-ai/cordis (^4.0.1) 和 @deepseek-ai/dsh-tools (^0.1.1-rc.2)。
* 定价逻辑：定价基于 2026-08-29 的价格表。高峰窗口为 UTC 01:00-04:00 和 06:00-10:00（周一至周五），其他时间为低谷期。定价依赖模型名称、缓存分割或时间戳，缺失任一条件将导致无法定价。
* 权限与安全：插件以 DSH 进程的权限运行。在安装前，建议检查源码和许可证（MIT）。
结语¶
dsh-spend-receipt 插件为 DeepSeek Harness 提供了一个透明、可验证的费用追踪方案。通过将使用情况记录为仅追加的 JSONL 文件，并利用整数运算保证精度，它能够有效解决成本估算不准确的痛点。
插件详情与源码可参考：GitHub
