前言¶
用 DeepSeek Harness（DSH）跑长对话或高频调用时，官网账单往往有几小时延迟，进程内的 token 用量又分散在流式响应里，很难在一屏里对照「账户还剩多少、官网最近花了多少、当前会话大概多少钱」。社区插件 dsh-billing-compass（维护者 wwu328763-netizen，分类：联网工具）把余额、官网用量/消费、按模型拆分和本地实时估算收进输入框下方的统计条，点开后弹出与输入卡片同宽的面板。下面介绍它的能力边界、安装方式与凭据配置。
这是什么¶
计费罗盘 · Billing Compass 是 DSH 的账单面板插件：余额、官网用量与消费、按模型花费、实时费用估算，目标是一屏看清。数据来自 DeepSeek 官方 HTTP 接口与 Harness 本地只读会话日志；不写盘、不上传内容，外部请求仅指向官方三个接口。插件以 MIT 许可发布，当前 npm 包版本为 1.0.0，要求 DeepSeek Harness 0.2.x（需 conversation.composer.dock 槽位与 useProjection），Node ≥ 20；若 Node 低于 22.15，「本对话消费(整段)」会退化为「本次运行」（缺少内置 zlib.zstdDecompressSync）。
核心功能¶
统计条常驻在输入框下方，点击后展开面板。各区域与数据来源如下（与 README 一致）：
| 区域 | 内容 | 数据来源 |
|---|---|---|
| 账户余额 | 充值 / 赠送 / 是否可用 | api.deepseek.com/user/balance |
| 官网消费 | 最近两个月消费合计，按模型拆分 | platform.deepseek.com/api/v0/usage/export（zip 内 cost-*.csv） |
| 综合每亿 token | 官网消费 ÷ tokens | 由上面两项推导 |
| 按模型 | tokens、缓存命中率、消费、每亿 token 单价、消费占比条 | platform.deepseek.com/api/v0/usage/amount |
| 本对话消费(整段) | 整个会话从开始到现在的估算费用 | 只读解析本地会话日志 |
| 本次运行 | 本次进程启动以来的调用次数 / tokens / 估算费用 | 本地拦截 llm/stream 的 usage |
触发行示例形态：● 余额 ¥9.56 · 官网消费 ¥252.48 · 本对话 $8.47 · 263.8M tokens ▼。面板宽度与位置与输入框卡片一致；当前使用的模型在列表中高亮。
实现上的要点：
- 零依赖：HTTP 用
node:https，ZIP 与 zstd 用node:zlib，无需 curl、unzip 或额外 npm 包。 - 不落盘：实时调用记录仅在内存（最近 3000 条），进程重启清零；会话日志只读。
- 凭据三级回退：环境变量 → Harness
credentials服务 →<DSH_HOME>/.credentials.yaml。 - 失败自愈：官网接口失败或凭据后补时，约 30 秒自动重试。
本地估算口径（USD / 1M tokens）：
单次/整段费用 ≈ (未缓存输入 + 缓存写) × input
+ 缓存读 × cacheHit
+ 输出 × output
官网数据以官网为准，可能有数小时延迟且约覆盖最近两个月；「本次运行 / 整段对话」按内置单价表估算，与账单可能有偏差。
安装与启用¶
插件在 DSH 进程内以 Node 模块运行，安装前应自行查看 GitHub 仓库 源码与 MIT 许可证。推荐通过 npm 安装：
dsh plugin add dsh-billing-compass
或在 Harness 内：
plugin_manager action=install_bundle target=dsh-billing-compass
国内网络会走已同步的 registry.npmmirror.com。装完后必须重启 Harness（宿主 JS 模块在进程内缓存，改代码或首次安装都要重启；客户端改动刷新页面即可）。
无需 npm 时，可从 Releases 下载 dsh-billing-compass.tgz，例如：
plugin_manager action=install_bundle target=https://github.com/wwu328763-netizen/dsh-billing-compass/releases/latest/download/dsh-billing-compass.tgz
也可在启用实验性市场 bundle @deepseek-ai/dsh-experimental-plugin-market-bundle 后，于 Discover 添加索引
https://raw.githubusercontent.com/wwu328763-netizen/dsh-billing-compass/main/market/index.json 再安装。DSH 目前没有集中托管的官方市场，market 只是读索引的客户端。
配置凭据¶
DEEPSEEK_API_KEY（必需）：用于余额，在 platform.deepseek.com/api_keys 创建，sk- 开头。
DEEPSEEK_USER_TOKEN（可选）：登录态 token，用于官网用量与消费；从浏览器登录 platform 后，在 Local Storage 的 userToken 取值。缺省时对应区域显示「未配置」，余额与本地统计仍可用。该接口可能随官网改版失效，仅影响官网相关区块。
写入 <DSH_HOME>/.credentials.yaml 或使用同名环境变量：
version: 1
refs:
DEEPSEEK_API_KEY: sk-xxxxxxxxxxxxxxxx
DEEPSEEK_USER_TOKEN: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
可选插件配置（写入 profile 的 cordis.patch.yml）包括刷新间隔、sessionLog 开关及按模型的 pricing 单价覆盖，字段见仓库 README 中的 cordis.patch.yml 示例。
典型用法¶
- 安装并重启 Harness，配置
DEEPSEEK_API_KEY（需要官网消费时再配DEEPSEEK_USER_TOKEN）。 - 打开对话页，在输入框下方查看统计条；点击展开面板，对照余额、官网两月消费与按模型明细。
- 调试完整快照：
GET http://127.0.0.1:<port>/api/dsh-billing?sessionId=<id>。
常见问题对照：无「余额 …」→ 检查是否安装成功并重启、profile 的 cordis.patch.yml 与 profiles/node_modules；「余额 未配置」→ 缺 API key；官网 HTTP 401 → token 过期需重取；整段对话与本次运行相同 → Node < 22.15 或 sessionLog: false。
适用场景与注意¶
适合长期在 DSH 里开发、需要进程内实时估算并与官网近两个月用量对照的开发者。不适合把插件当作唯一财务对账工具：官网延迟与估算口径差异 README 已说明。
插件以当前 DSH 进程的权限访问凭据与本地会话日志，并请求 DeepSeek 官方 API；安装前请确认信任维护者与代码。隐私方面：不写文件、不采集上传内容；实时统计仅内存；会话日志只读汇总 token。
结尾¶
计费罗盘把 Harness 输入框下方的空白变成可点的账单条：官方余额与用量、按模型花费、本地会话与本次运行的估算在同一面板里。社区目录页：skillhub.cn/plugins/wwu328763-netizen/dsh-billing-compass；源码与完整说明：github.com/wwu328763-netizen/dsh-billing-compass。
