前言¶
在 DeepSeek Harness（DSH）里跑多供应商、多模型时，token 消耗分散在会话事件里，账户余额和编程套餐又在各家开放平台或登录态里。单靠宿主自带的界面，很难在同一块屏幕上看到「今天用了多少」「当前对话花了多少」「余额和套餐还剩多少」。
社区插件 dsh-abacus（算盘，维护者 SereneJi）把每次模型调用的用量记成本地账本，并在 Web GUI 与官方桌面客户端的三个位置展示同一份数据；同时按配置查询供应商余额与套餐，并在余量偏低时做界面标记。下面介绍它的定位、功能、安装与使用注意。
这是什么¶
dsh-abacus 是 DSH 的用量统计与账户监控插件，分类为 admin-security。当前版本为 2.0.0，要求 DSH ≥ 0.2.0-rc.2，许可证 MIT。
数据只有两个来源：DSH 会话事件（用量）和供应商接口（余额与套餐）。余额与套餐不做本地估算，查不到会在界面写明原因。
2.0.0 之前插件名为 dsh-usage-stat；插件 id、HTTP 路由前缀与状态目录均已从 usage-stat 改为 abacus，不能就地升级，需先卸载旧版再安装新版。
界面与入口¶
同一份账本会出现在三处：
| 位置 | 形态 |
|---|---|
| 侧边栏左下角 | 折叠时一行「今日用量 + 总量」，展开后按供应商与模型列出；余量偏低时在对应供应商前显示红点 |
| 输入框下方 | 「本次对话 N tokens」胶囊，点开可见本段对话的分供应商、分模型明细 |
| 设置 → 用量统计 | 四个标签页：用量、金额、账户、设置 |
设置入口固定为 设置 → 用量统计。
核心功能¶
用量统计¶
- 用量页：合计总 tokens、输入、输出、缓存读、调用次数（缓存写仅在窗口内出现过时才显示）；按供应商与模型的明细；所选时间范围内的每日柱状图。顶部可切换今天、近 7 天、近 30 天、全部或自选起止日期。
- 柱状图纵轴：多日窗口为相对刻度（窗口内用量最高日为满格），卡片右上角标注锚点；选「今天」或单日时改为按小时的 24 列图。
- 本次对话：启用插件之后的对话才有分供应商明细；更早的对话仅保留总量时，面板会说明「只有总量记录」。
账户与套餐¶
- 账户页：各供应商的账户余额与套餐窗口合并展示；余额按币种显示，套餐显示 5 小时 / 本周 / 本月窗口的已用百分比与重置时间。未配置 Key、账号登录、非官方地址或供应商未提供数据等情况会折叠在卡片底部并说明原因。
- 余额与套餐仅覆盖 README 中说明的已知端点；其余供应商不会用本地 token 数折算余额。
金额参考¶
- 金额页：按价目表将所选窗口的 token 折算为金额，范围可选全部、某供应商或某模型；单日窗口支持按小时折算。未定价模型单独列出未计入的 token 数，不会按 0 计入合计。
- 金额为标准价参考，不含折扣、套餐或中转加价。内置 DeepSeek 两档模型的空闲时段价；北京时间工作日 9:00–12:00、14:00–18:00 按两倍计，周末与法定节假日按空闲价，按每次调用发生时刻判定。价目表支持带
from生效日期的多行价格；改价后历史金额按当前价目表重算（不写进账本）。 - 内置价目表与节假日表会定期从官方页面拉取并缓存在本机；拉取失败则沿用上次或内置数据。
余量提醒与历史补录¶
- 余量提醒：可为余额及三个套餐窗口分别设阈值，低于阈值时在左下角卡片与账户页标红点；阈值为
0表示该项不提醒。判定为「低于」而非「等于」；无凭据或查不到数字的供应商不会标红点。仅为界面标记，不弹窗、不发声。 - 历史补录：插件只记录运行期间的用量；首次启用会自动从 DSH 磁盘上的过往会话补录；中途关闭插件后可在设置页手动再补一次。补录按调用发生日入账。仅能补回 DSH 日志仍存在的会话。
安装与启用¶
要求 DSH 0.2.0-rc.2 或更高，Web GUI 与官方桌面客户端均可。--profile 使用你当前的 profile 名（桌面客户端一般为 desktop，dsh web 一般为 web）。
从 GitHub 安装：
dsh plugin --profile desktop add git+https://github.com/SereneJi/dsh-abacus.git
卸载：
dsh plugin --profile desktop remove dsh-abacus
宿主端改动需重启一次 DSH；此后界面改动刷新页面即可。
从 dsh-usage-stat 迁移¶
dsh plugin --profile desktop remove dsh-usage-stat
dsh plugin --profile desktop add git+https://github.com/SereneJi/dsh-abacus.git
若 $DSH_HOME/abacus/ 尚不存在，首次启动会把 $DSH_HOME/usage-stat/ 整目录复制为新账本目录，旧目录保留作备份。浏览器中的界面偏好会从 dsh-usage-stat.* 一次性迁移到 dsh-abacus.*。
配置与数据路径¶
设置页各项对应 $DSH_HOME/abacus/config.json（$DSH_HOME 默认为 ~/.dsh）。常用键包括：
| 键 | 默认 | 含义 |
|---|---|---|
enabled |
true |
总开关；关闭后不记账、不探测、界面消失 |
pollIntervalSec |
60 |
界面刷新用量间隔（5–600 秒） |
probeEnabled |
true |
是否查询供应商余额与套餐 |
probeIntervalSec |
300 |
余额与套餐查询间隔（60–3600 秒） |
alertEnabled |
true |
余量提醒总开关 |
alertBalanceBelow 等 |
0 |
余额或各套餐窗口低于阈值时提醒；0 表示不提醒 |
prices |
DeepSeek 官方两档（空闲价） | 价目表，可按模型配置每百万 token 的 input / output / cacheRead / cacheWrite（CNY） |
价目表也可直接在配置文件中编写，例如：
"prices": {
"deepseek-flash": { "input": 2, "output": 8, "cacheRead": 0.04, "cacheWrite": 2 }
}
本地数据文件：
| 路径 | 内容 |
|---|---|
$DSH_HOME/abacus/usage.json |
用量账本 |
$DSH_HOME/abacus/providers.json |
余额与套餐快照 |
$DSH_HOME/abacus/upstream.json |
抓取的价目表与节假日表 |
$DSH_HOME/abacus/config.json |
配置 |
供应商 API Key 由 DSH 凭据服务保管，仅在宿主端读取，不会进入浏览器。
典型用法¶
- 按上文命令安装并重启 DSH，打开 设置 → 用量统计，确认用量页时间范围与明细是否符合预期。
- 若需要余额与套餐展示，保持
probeEnabled为 true，并在 DSH 中为对应供应商配置可查询余额的 API Key；账号登录类供应商可能无法显示开放平台余额，以界面说明为准。 - 在设置页配置余量提醒阈值与自定义价目表；金额页仅作参考，勿与官方账单混为一谈。
- 首次安装或曾关闭插件时，在设置页查看历史补录状态，必要时手动触发补录。
适用场景与注意¶
适合需要在 DSH 侧边栏和设置里长期查看 token 台账、对话级用量、账户余量，并愿意在本地保留完整历史（账本不设时间与体积上限，仅有会话行数兜底上限）的用户。
安装前请注意：插件以当前 dsh 进程权限运行，会读写 $DSH_HOME/abacus/ 并可能向供应商发起余额查询；安装前应自行查看 GitHub 仓库 源码与 MIT 许可证。社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。
其他已知限制包括：图表每日视图最多回溯 366 天；界面文案按浏览器语言在插件自带 zh/en 间选择；侧边栏卡片依赖 DSH DOM 结构，注入失败时会退化为追加到侧边栏底部。
结尾¶
dsh-abacus 把用量、金额参考、账户与套餐收进同一套本地账本与设置页，适合作为 DSH 日常开发的用量台账。更多信息见 SkillHub 目录页 与 GitHub：SereneJi/dsh-abacus。
