前言¶
DeepSeek Harness (DSH) 采用插件化架构，允许开发者扩展核心功能。在进行智能体开发或长时间运行任务时，追踪 Token 消耗、精确计费以及管理预算是常见需求。dsh-billing 插件旨在解决这些问题，它提供了一套完整的账本系统，支持持久化存储、官方余额同步以及峰谷计价策略。
核心功能¶
该插件主要提供以下能力：
-
持久化账本
所有费用记录存储在$DSH_HOME/storages/dsh-billing/ledger.json中。写入采用原子操作并带有防抖机制，确保数据一致性。 -
精确计费
插件监听llm/stream瀑布链尾的 usage 块，捕获每次模型调用的实际消耗。成本计算公式（单位：美元 / 1M tokens）为：
成本 = 未命中输入 × cacheMiss + 输出 × output + (缓存读 + 缓存写) × cacheHit
账本金额恒以美元存储，展示币种默认为人民币（汇率固定为 7.2）。 -
官方余额与预算
利用有效的 API Key 调用官方接口查询账户余额。余额数据按refreshMinutes缓存，支持手动强制刷新。预算管理提供预警（≥80%）和超支（≥100%）提示，但仅提醒不阻止调用。 -
峰谷计价
支持峰谷时段计价，时间窗口由官方同步维护（默认生效时间 2026-08-16 16:00 UTC，峰时窗口为 UTC 01:00-04:00 和 06:00-10:00）。插件在启动时会自动同步官方价格表。 -
会话统计与历史
在会话统计行展示实时估算费用，在侧边栏和设置页展示今日/本月/累计汇总。历史记录按保留天数（默认 180 天）修剪，并按天汇总。
安装与启用¶
安装插件需要 Node.js ≥ 20 以及已安装 DeepSeek Harness CLI。
- 执行以下命令从 GitHub 安装：
dsh plugin --profile web add github:mahiro6/dsh-billing
或使用本地路径（开发调试时推荐）：
dsh plugin --profile web add link:<本仓库绝对路径>
- 安装完成后，必须重启
dsh web服务才能使插件生效：
dsh web
配置与使用¶
插件配置主要持久化在 ledger.json 文件中。除 budget 外，大部分配置项（如货币符号、汇率、价格表、峰谷时间）均由插件自动维护或固定默认值，不建议手动修改。
- 预算配置：可在界面设置页修改，包含启用状态、额度、周期（今日/本月/累计/自定义）。
- 余额查询：点击界面中的“刷新余额”按钮可强制重新查询，该操作不依赖定时器，由客户端触发。
- 价格同步：插件启动时会自动抓取官方定价页。若需跳过启动时的同步（例如离线环境），可设置环境变量
DSH_BILLING_SKIP_STARTUP_SYNC=1。
技术实现与限制¶
- 运行机制：插件不依赖 Cordis 的 Service 或 Context 运行时类，仅使用 Node.js 内置模块及特定依赖，与宿主共享同一运行时实例。
- 数据精度：会话统计行的费用为当前档位的估算值；今日/月度/累计费用以账本为准。
- 价格覆盖：官方价格同步操作会替换整个模型集，官方页面不存在的旧模型会被移除。
- 权限要求：余额查询需要有效的 API Key 且能访问
api.deepseek.com；API Key 仅发送至官方域名。
总结¶
dsh-billing 为 DeepSeek Harness 提供了从微观（单次调用）到宏观（账户预算）的完整成本控制视角。对于需要精细化运营和成本监控的开发者，该插件提供了可靠的解决方案。
