余额监视器 its0din-ai/harness-accountant

harness-accountant

harness-accountant 是一个简单的插件，用于监控你实时的 DeepSeek 代币余额和使用情况，并告诉你当前小时是按高峰时段还是非高峰时段费率计费。

Accountant 卡片位于 DSH 侧边栏中，紧挨在 Settings 行上方

一句话概括： 实时的 DeepSeek 余额、由此推导出的支出，以及当前高峰时段状态，仅在 DSH Web GUI 中显示，别处不显示。

目录

- harness-accountant
- 目录
- 概述
- 语言和货币
- 语言：仅英语
- 货币：同时支持美元和人民币
- 它不做什么
- 两个界面
- 侧边栏卡片
- 设置面板
- 工作原理
- 金额绝不用浮点数
- 高峰时段由浏览器中的时钟决定
- 要求
- 安装
- 安装该行
- 提供你的 API 密钥
- 检查是否生效
- 回滚
- 配置
- 故障排除
- 安全
- 开发
- 针对工作副本进行开发

概述

该插件做三件事，而且三件事都是实时的：

| | 显示内容 | 来源 |
| 余额 | 账户当前的 DeepSeek 余额 | GET /user/balance，默认每分钟轮询一次 |
| 用量 | 已花费的金额，以 1 天 / 7 天 / 1 个月窗口以及每日列表呈现 | 各次读取之间余额的变动，归入一个小型每日账本 |
| 高峰时段状态 | 当前小时是按高峰费率还是非高峰费率计费，带名称和颜色标识 | DeepSeek 公布的 UTC 时间表，在浏览器中根据墙上时钟计算 |

高峰时段显示为黄色指示器，非高峰时段显示为绿色指示器，位于余额上方。该时间表是 DeepSeek 的，不是猜测：高峰时段为 UTC 时间周一至周五 01:00 - 04:00 和 06:00 - 10:00，其他所有小时——包括周末——均为非高峰时段。

语言和货币

这是两件不同的事，两者都值得说清楚。

语言：仅英语

本项目仅支持英语。 完全没有多语言支持：没有翻译文件、没有区域设置检测、没有语言设置，也没有从右到左处理。每个面向用户的字符串都直接写在 lib/client.js 中，因此添加第二种语言将意味着引入一个字典以及相应的设置，在两者之间进行选择。这是该插件目前不具备的功能，在具备之前，界面将保持英文。

货币：同时支持 USD 和 CNY

货币是另一个问题，而在这方面该插件不受限制。支持两种货币——USD 和 CNY——并且两者都不会被当作对方的默认值。

该插件从不假设货币。在每次探测时，它都会读取 DeepSeek 为账户报告的 wallets，并以实际发现的货币来记账：

- 报告一个 wallet 的账户会被跟随，无论它是哪种货币，包括 CNY；
- 报告两者的账户会按照响应本身列出的顺序采用，没有内置偏好，除非你通过 currency 设置固定其中一种。

插件中没有任何汇率，也从不进行任何换算。报告为 4.58 的余额会渲染为 $4.58，或者渲染为带有人民币符号的相同数字，完全取决于响应内容。两者绝不会相加：更改货币会丢弃累积的每日序列，而不是混合不可比较的单位。

因此，设置语言和设置货币是互不相关的：一个固定为英文，另一个已经处理 DeepSeek 报告的两种货币。

它不做什么

没有编码计划配额，没有按提供商区分的适配器，没有凭证图案，没有会话切换，没有多语言词典，没有构建步骤。大约 2,500 行代码，涵盖宿主端和浏览器端，以及四个运行时文件。

两个界面

该插件只向 GUI 添加两样东西，而且两者都可以选择是否查看。

侧边栏卡片

一张直接位于 Settings 行上方的卡片，显示当前计费层级（高峰或非高峰，带名称和颜色编码）、带眼睛切换按钮可将其遮罩的余额，以及今日支出。

折叠侧边栏后，56px 的窄栏没有空间容纳带标签的行，因此卡片会将层级保留为今日支出上方一个缓慢呼吸的彩色圆圈，并将余额移入其工具提示中。

设置面板

Settings 模态框中的一个详细面板：相同的余额，带有 1 天 / 7 天 / 1 个月的细分、总计，以及每日支出条形列表。它在设置导航中的行带有一个硬币堆叠图标，而不是外壳为每个它不认识的区段绘制的齿轮图标。

工作原理

lib/ledger.js 纯逻辑：以整数微单位表示金额、每日折叠、修剪 lib/probe.js 唯一接触密钥或网络的文件 lib/index.js 宿主：轮询循环、磁盘上的原子账本、两条回环路由 lib/client.js 浏览器：侧边栏卡片 + 设置面板，无打包器，无 JSX

宿主向 DeepSeek 请求余额，将每次读数折叠到 $DSH_HOME/harness-accountant/ledger.json 下的一个小型每日账本中，并将结果作为 JSON 提供。浏览器端只会接收格式化后的数字——它永远不会看到 API 密钥、凭据引用或账本路径。
消费是两次读数之间账户余额的变动。这意味着它涵盖该账户上的每个会话和客户端，而不仅仅是当前窗口。余额上升会被记录为充值，而不是与消费相抵。

金额绝不是浮点数

/user/balance 返回的是一个十进制字符串。用浮点数相减会产生漂移，因此每个金额都会被解析为有符号整数微单位（1 单位 = 货币的 1e-6），并且只在边界处才格式化回字符串。

高峰由时钟决定，在浏览器中

DeepSeek 对高峰时段的计费是非高峰费率的两倍，并公布时间表为“UTC 周一至周五 01:00 - 04:00 和 06:00 - 10:00，中国法定节假日除外”；其他所有时段，包括周末，都是非高峰。

主机不评估该时间表。它发布该时间表——/overview 载荷中的 peak，窗口以 UTC 午夜起的分钟数给出——而浏览器这一半拥有时钟，因为档位是墙上时钟的纯函数，往返一次严格来说比读取浏览器已有的时钟更差。它不为此轮询，也不为此消耗固定的定时器：只武装一个 setTimeout，用于档位下一次变化的时刻，并且档位始终从 Date.now() 重新计算，而不是由定时器推进，因此被节流、合并或睡眠延迟的唤醒只能延迟修正，绝不会让读数过时。visibilitychange 刷新则覆盖了完全睡过边界的标签页。

只有档位的彩色圆圈会移动——它旁边的文字绝不会动——而且它移动得很慢：一个合成的透明度循环持续三秒，读起来像状态灯而不是警报。在 prefers-reduced-motion 下它会被完全去掉，此时圆圈只是保持点亮。

由于时间表以 UTC 表示，比较也在 UTC 中进行，因此该指示器在任何时区都是正确的——读者自己的时钟从不参与判断。只有工具提示以本地时间渲染，它会指出边界，并且当该边界不是今天时，还会指出星期几。这正是让星期五变得可读的原因：下一次高峰是星期一早上。

中国法定节假日被有意不建模，因为此插件不携带节假日日历。在这些日子里，它会报告高峰，而 DeepSeek 按非高峰计费。这一省略并非无声：holidays_modelled: false 会传到客户端，工具提示会显示“public holidays not modelled”。时间表本身不可配置——它是 DeepSeek 公布的时间表，是 lib/index.js 中的一个冻结常量。

不可用的时间表——缺失、处于另一个参考系、窗口格式错误、星期几超出星期范围——会降级为非高峰，且完全没有定时器，这是声明的默认值，且不产生任何成本。一个什么都不说的指示器胜过猜测的指示器。

要求

- 一个启动 Web GUI（dsh web）的 DSH 配置文件。此插件不自带窗口——它在侧边栏中放置一张卡片，并在设置中放置一个区块
- modal——所以它需要带有这些内容的 shell。
- Node 20 或更高版本，这正是 engines.node 所声明的，也是 CI 所运行的版本。
- 一个 DeepSeek API key。余额端点需要认证，而密钥是你唯一需要自己提供的东西；请参阅下面的给它你的 API key。
- dsh CLI，因为 dsh plugin 正是用来安装该行的。

界面仅支持英文；账户可以以美元或人民币计价，两者都受支持。

安装

托管在 github.com/its0din-ai/harness-accountant。
该包刻意不发布到 npm：受支持的渠道是 git 安装，也就是下面命令所使用的方式。

安装该行

1. 先备份 profile 接线——这同时也是回滚方案
cp ~/.dsh/profiles/web/package.json ~/.dsh/profiles/web/package.json.bak
cp ~/.dsh/profiles/web/cordis.patch.yml ~/.dsh/profiles/web/cordis.patch.yml.bak

2. 将该包添加到 web profile
dsh plugin --profile web add \
git+https://github.com/its0din-ai/harness-accountant.git

3. 重启 web 应用：停止正在运行的 dsh web，然后再次启动它

然后在 http://127.0.0.1:3080 重新加载 GUI。

安装后必须重启，因为插件的行会在启动时组合进 profile，而正在运行的进程看不到在其下方新增的行。设置更改后则不需要重启：保存设置页面会将新值重新读入活动 fiber。

要固定某个修订版本，请在 URL 后附加标签或提交：

dsh plugin --profile web add \
git+https://github.com/its0din-ai/harness-accountant.git#v1.0.1

给它你的 API key

该插件从不向你索要密钥，也从不存储密钥。每次探测时，它都会向平台的凭据接缝请求名称 DEEPSEEK_API_KEY，而该接缝按以下顺序解析该名称：

1. 运行 dsh web 的进程的环境变量，
2. ~/.dsh/.credentials.yaml 中的存储，
3. 一个 .env 文件。

因此，要么在启动 web 应用之前导出它：

export DEEPSEEK_API_KEY=sk-...
dsh web

要么将其写入存储，这样重启后仍然有效：

~/.dsh/.credentials.yaml - 将此文件权限保持为 0600 version: 1 refs: DEEPSEEK_API_KEY: sk-...

不要将密钥放入 cordis.patch.yml。 该文件接受的是名称（api_key_env: DEEPSEEK_API_KEY），绝不是值。值保留在凭据存储中，这样配置就可以被复制、共享或在设置 UI 中渲染而不会泄露它。空值视为不存在，因此空的 DEEPSEEK_API_KEY 的行为与完全没有密钥完全一样，而不是在 API 处静默失败。

检查它是否正常工作

在重启后大约一分钟内——一个轮询间隔——你应该会看到：

- 侧边栏中直接位于 Settings 行上方的一张卡片，显示层级、余额和今日支出。第一次读数就是期初余额，因此在第二次读数到来之前，今日支出会保持为 0.00；
- 在设置模态框中新增一行 Accountant，带有 1 天 / 7 天 / 1 个月标签页。

~/.dsh/harness-accountant/ledger.json 由第一次成功的探测创建，权限为 0600，位于 0700 目录内。如果它不存在，说明探测没有成功；请参阅故障排除。

回滚

第 1 步中备份的两个 .bak 文件就是回滚的全部内容：

cp ~/.dsh/profiles/web/package.json.bak ~/.dsh/profiles/web/package.json
cp ~/.dsh/profiles/web/cordis.patch.yml.bak ~/.dsh/profiles/web/cordis.patch.yml
then restart the web app

这不会删除 ~/.dsh/harness-accountant/ 下的账本，该账本可以单独删除；它只保存每日余额和当天的读数。

配置

schema 位于 lib/index.js 中，默认值写在 cordis.patch.yml 中，因此设置页面会显示真实、可编辑的值。

| key | default | notes |
| enabled | true | false 会停止所有后台探测；路由仍会提供账本，显式刷新仍会进行探测 |
| poll_interval_sec | 60 | 健康状态下的轮询节奏，无论配置为何，都会被限制为 >= 30。连续失败会拉长该间隔：见下文 |
| retain_days | 400 | 被限制为 [7, 730] |
| accounting_utc_offset_minutes | 480 | 日界线，作为相对于 UTC 的固定偏移量。480 是 UTC+08:00，即 DeepSeek 的计费日。设为 0 表示 UTC，或设为自己的偏移量表示本地日。它是偏移量，不是时区：它不建模夏令时 |
| currency | auto | 要跟踪哪个钱包。auto 按余额响应列出钱包的顺序取第一个可用的钱包——适合只报告单一币种的账户。设为 CNY 或 USD 可固定；读取时不区分大小写，其他任何值都表示 auto |
| api_key_env | DEEPSEEK_API_KEY | 一个凭据引用，每次探测时解析 |
| api_base_url | https://api.deepseek.com | 必须是裸 https: 源；纯 http: 会被拒绝 |
| max_response_bytes | 65536 | 探测将从响应体缓冲的字节数上限，schema 限制为 [1024, 1048576]。余额负载只有几百字节，所以这纯粹是余量；它的存在是为了让恶意或损坏的源无法无限制地分配内存 |

API key 来自 ctx.credentials（即 ~/.dsh/.credentials.yaml 或启动环境）。它在每次探测时都会重新解析，从不缓存。

账本中的日是 accounting_utc_offset_minutes 下的日历日，而不是主机时区下的日历日，因此该服务和任何其他进程都会将同一时刻归入同一天。默认值遵循 DeepSeek 的计费日，而不是运营者的本地日，因为要核算的账单是 DeepSeek 的。

该文件带有 schema version 以及最后一次写入时生效的 accounting_utc_offset_minutes，因此它自身说明了其日键是如何分桶的。版本较旧的文件会在加载时就地升级，并且 /overview 将其报告为 ledger_notice。此构建无法读取的文件——更新的 version，或无法通过校验的结构——绝不会被猜测，也绝不会被覆盖：它会被移到同一 0700 目录下的 ledger.json.incompatible，并保持相同的 0600 模式，插件会启动一个新的账本，原因会出现在 ledger_notice 中。

一个账本一次只跟踪一种货币，它已知的两种货币绝不会混在一起：CNY 和 USD 微单位不可比较，因此货币变更会丢弃当日序列，而不是跨货币求和。具体是哪一种来自余额响应。在默认的 auto 下，插件会按响应列出它们的顺序取第一个可用钱包——对两者都没有内置偏好，因为一个同时报告两者的账户，正是猜测会决定记录什么的地方。只报告单一货币的账户始终遵循它，包括 CNY。将 currency 设为 CNY 或 USD 可改为固定选择；账户不再报告的固定项会按名称使探测失败（account reports no CNY wallet），而不是悄悄跟随另一个钱包，因为这种替换恰恰会丢弃历史记录。插件不持有汇率，也从不转换：4.58 的余额会按响应所报告的货币符号渲染，而数字本身则原样传递。

失败的探测不会以相同频率永远重试。前三次连续失败保持配置的节奏，因为只闪断一次的服务应正常重试；此后每次进一步失败都会使等待时间加倍，最多达到配置间隔的十六倍。一次成功读取会清除连续失败计数，等待时间会直接回到基准值。退避等待不可配置——这三个数字是 lib/index.js 中的常量。当前连续失败次数和待定等待时间都在 /overview 负载中（consecutive_failures、next_probe_in_sec），如果你想查看循环所处的状态。

故障排除

插件关于自身健康状况所知道的一切都在 /overview 负载中，卡片会显示同一个 error 字符串的简短形式。常见故障：

| 你看到的内容 | 它意味着什么 |
| credentials service unavailable | 凭据接缝未挂载在此配置文件中。丢弃凭据服务的自定义组合必须将其加回 |
| no credential stored for DEEPSEEK_API_KEY | 该名称未解析到任何内容：未导出、不在 ~/.dsh/.credentials.yaml 中、不在进程可见的 .env 中——或者存在但为空 |
| request failed: ... | 未访问到 API。文本在输出时会被脱敏，因此形似密钥的片段会显示为 sk-** |
| http 401 或 http 403 | 已访问到 API，但密钥被拒绝 |
| account reports no CNY wallet | 你固定了 currency: CNY，而账户不再报告该币种钱包。这里刻意不做任何替代——币种变更会丢弃当日序列。清除该固定项，或设置为你实际使用的币种 |
| 侧边栏中没有任何内容出现 | 浏览器端已提供但未就位。检查浏览器控制台，并确认标签页是在重启之后重新加载的 |
| Settings 行显示的是齿轮，而不是硬币 | shell 重命名了它的行标签或其 css-module 类。硬币被绘制到 shell 已经绘制的齿轮上，通过标签 Accountant 和 navIcon 类后缀进行匹配，因此重命名会使默认样式保留在原位 |
| 整个周末层级都显示为非高峰 | 正确——周末全程为非高峰 |
| 在中国法定节假日层级显示为高峰 | 对本插件来说同样正确：未携带节假日日历，工具提示也如此说明 |
| 当 DeepSeek 在非高峰时段收费时，层级显示为黄色 | 该时间表是 DeepSeek 以 UTC 发布的。检查偏移量，而不是本地时钟：比较始终以 UTC 进行，因此只有已发布时间表发生变化才能解释这一点 |
| 7 天和 30 天的数字看起来很少 | 账本是从第一次探测开始向前构建的，没有任何回填，因为 DeepSeek 不暴露余额历史。这些窗口需要数天的正常运行时间才有意义 |
| 所有文本都是英文 | 没有多语言支持；界面仅支持英文。货币是独立的，并且已经同时处理 USD 和 CNY |

此构建无法读取的账本绝不会被覆盖。它会被移到一旁，保存为 ledger.json.incompatible，并且 /overview 会在 ledger_notice 中携带原因。

安全

阅读 THREAT.md。它列出了此设计考虑过的每一种威胁，说明是否已缓解，并且在未缓解之处——陈述了权衡。

简而言之：密钥从不离开宿主进程，只传输到经过验证的 https: 源且拒绝重定向，在所有错误路径中都会被脱敏，并且这两个路由被限制为同源回环调用者。

开发

node --test test/.test.js

干净的检出无法按原样运行该命令。test/host.test.js 导入了 lib/index.js，后者导入了 @deepseek-ai/schemastery，而 lib/probe.js 导入了 @deepseek-ai/dsh-credentials。两者都被声明为可选对等依赖，因此不会安装它们，第一次导入就会失败。安装宿主运行的两个固定版本，然后运行测试套件：

npm install --no-save --no-package-lock \
@deepseek-ai/schemastery@3.18.4 \
@deepseek-ai/dsh-credentials@0.1.7-rc.2

node --test test/.test.js

CI 在每次推送和每次拉取请求时都会在 Node 20 和 Node 24 上执行此操作（.github/workflows/test.yml）。

测试套件以 node --test test/.test.js 运行，而不是 node --test test/。
Node 24.x 不再搜索传给 --test 的目录：它将路径视为单个测试文件，尝试将该目录作为模块加载，并失败并显示 Cannot find module '.../test'，同时报告一个通过的测试和一个失败的测试。
Node 20 仍会搜索，而 Node 26 恢复了搜索（nodejs/node#64637），因此这个故障只会在矩阵中的一条分支上出现。在 shell 中展开 glob 会把真实文件路径传给运行器，而所有受支持的版本都接受这些路径。

87 个测试：22 个用于账本，18 个用于探针，29 个用于宿主路由和请求围栏，18 个用于客户端。宿主测试将真实插件挂载到一个假上下文、一个打桩的 fetch 和一个一次性的 DSH_HOME 上；客户端测试驱动一个桩 DOM 和一个固定时钟，因为峰值层级是墙钟时间的函数。

针对工作副本进行开发

link: 安装会从工作副本的 realpath 解析，因此 @deepseek-ai/schemastery、@deepseek-ai/dsh-credentials 和 @deepseek-ai/cordis 必须能在那里找到——而不是从配置文件的 node_modules 中。这仅影响本地开发；从 GitHub 安装时会通过配置文件树解析它们，不需要任何额外操作。

git clone https://github.com/its0din-ai/harness-accountant
cd harness-accountant

mkdir -p node_modules/@deepseek-ai
for pkg in cordis schemastery dsh-credentials; do
ln -s ~/.dsh/profiles/web/node_modules/@deepseek-ai/"$pkg" \
node_modules/@deepseek-ai/"$pkg"
done

dsh plugin --profile web add link:"$PWD"