前言¶
在 DSH（DeepSeek Harness）里配合 dsh-our-free-model（Our Free Model，OFM）使用时，多个免费与协付渠道的积分各自独立，聚合面板上往往看不到「还剩多少」。额度用尽时，一线常见是 HTTP 429 或 QUOTA_EXHAUSTED，对话卡在中间，只能手动去模型选择器里换下一个接口。一天下来各渠道吃了多少 token，也缺少可对账的汇总。
dsh-ofm-quota（维护者 dx906，GitHub 仓库）是架在 OFM 旁边的配额管理插件：旁听每次真实派发、统计 token/积分消耗，额度耗尽时在同名模型族内自动切换备用接口，并在右侧栏用卡片展示各渠道剩余余额。它不是 OFM 的替代品，只读 OFM 与渠道包的落盘文件，不修改 OFM，两者可独立升级。插件为零运行时依赖，仅使用 Node 内置模块。
需要事先说明：DSH 内核自带的 deepseek-account（DeepSeek 官方账号）是按量计费，与 OFM 免费车道是两套体系。默认不会在用户不知情时切到官方；额度用尽且没有可用备用接口时会如实报错。只有显式配置 officialFallback 才会兜底到官方；面板里官方路由单独标为「官方 · 计费」并沉底。
这是什么¶
- 名称：dsh-ofm-quota（包名
dsh-ofm-quota，当前版本 0.1.0，MIT） - 平台：web 与 desktop（共用同一 profile，一次安装两边生效）
- 前置：DSH（profile / bundle / cordis 插件机制）、dsh-our-free-model、Node.js
^22.19.0 || >=24.0.0
核心功能¶
用量检测¶
插件旁听内核的 llm/stream 水位，记录每次请求实际派发到的 provider/model 与适配器回报的 token 用量（输入、输出、思考、缓存读）。
界面上会交叉展示两类数据：
| 来源 | 含义 |
|---|---|
本进程旁听 llm/stream |
实时，仅覆盖安装后本进程内的请求 |
渠道包台账 token-ledger.json |
按 direct\|provider\|accountId\|model 逐日累计，含历史，为权威值 |
「模型用量明细」里可看到旁听次数与渠道包权威次数的对照；差异通常表示插件安装前已有请求。
额度耗尽自动切换¶
触发条件覆盖内核码与 OFM 生态码（如 QUOTA_EXHAUSTED、QUOTA、ACCOUNT_QUOTA、RATE_LIMIT 等）。命中后沿同名模型族（归一化时剥掉 -free / -preview 等后缀）寻找仍有额度的备用接口；找到则通过 agent/request-error 与 agent/request 水位重跑本 step，对话不中断。官方路由不作为「同名备用」，只能是显式配置的兜底。
默认行为：找不到备用接口即报错，不自动切到按量计费的官方账号。失败接口进入冷却（默认 15 分钟），每 step 切换次数有上限（默认 3）。换路时会丢弃源路由的 reasoningEffort，避免目标适配器不认该档位。
结合刷新余额后写入的 quotaRemaining，可在触发 429 之前就提前换走仍有余额的接口。
侧边栏「接口额度」卡片¶
DSH 右侧栏新增卡片，按渠道展示剩余积分（同一渠道下多模型共享一池积分，不为每个模型重复同一数字）。可展开账号；「模型用量明细」默认收起。某渠道未配凭据时显示「余额未知」，不伪造为 0。
安装与启用¶
本包不打到 npm（private: true）。官方文档建议从源码打 tarball 装进 profile，使安装字节与审过的源码一致。桌面端的 desktop profile 由 Electron 独占，CLI 直接 dsh plugin add 可能报 profile "desktop" is managed exclusively by the Electron application，因此 README 给出的是手工装包步骤。
下面按仓库 README 的安装流程说明（需先取得源码目录，再在 profile 中引用打好的包）：
# 在已 clone 的 dsh-ofm-quota 源码目录内执行
mkdir -p "$DSH_HOME/profiles/desktop/vendor"
pnpm pack --pack-destination "$DSH_HOME/profiles/desktop/vendor"
在 $DSH_HOME/profiles/desktop/package.json 中：
dependencies增加："dsh-ofm-quota": "file:./vendor/dsh-ofm-quota-0.1.0.tgz"dsh.profile.bundles末尾追加："dsh-ofm-quota"
然后在 profile 目录解析依赖：
cd "$DSH_HOME/profiles/desktop"
pnpm install --frozen-lockfile --offline --ignore-scripts
若更新了 tarball，需同步 pnpm-lock.yaml 里该包的 integrity（sha512-base64），否则 --frozen-lockfile 会失败；同版本号时可能需要先 rm -rf node_modules/dsh-ofm-quota 再 --force。
装完后从托盘退出并重开 DSH。运行中的宿主仍是旧代码；启动日志中应出现 [ofm-quota] loaded build=<hash> 用于确认版本。
典型用法¶
- 重开 DSH，在右侧栏打开接口额度。
- 点同步——从本机落盘文件读取接口清单与历史用量，主要依赖：
| 数据 | 路径 |
|---|---|
| OFM catalog | $DSH_HOME/our-free-model/catalog.json |
| 渠道包账号 | $DSH_HOME/channel-pack/state.json |
| 渠道包用量（权威） | $DSH_HOME/channel-pack/token-ledger.json |
- 点刷新余额——查询各渠道真实剩余积分（host 侧通过进程内 owner Peer 调用渠道包
credits.balancesRPC，避免非 owner 访问/api/channel-pack的 403）。 - 正常对话；开启自动切换后，额度耗尽会在同名族内换接口。
配置写在 $DSH_HOME/ofm-quota/settings.json，也可通过卡片或 HTTP（/api/ofm-quota，插件自行做准入检查）修改。示例：
{
"enabled": true,
"autoSwitch": true,
"maxSwitchesPerStep": 3,
"cooldownMs": 900000,
"windowHours": 24,
"officialFallback": null,
"syncCatalog": true,
"manualQuota": {}
}
officialFallback 默认为 null，即不启用官方计费兜底；需要兜底时需显式配置该项（具体取值以仓库文档为准）。enabled 为总开关，autoSwitch 控制是否自动换路。
适用场景与注意¶
适合谁：已在 DSH 中使用 Our Free Model、多渠道混用，希望看清剩余积分、对账 token、并在单渠道用尽时少打断对话的开发者。
权限与安全：插件在 DSH 进程内运行，可读 $DSH_HOME 下 OFM 与 channel-pack 的落盘文件，并注册 HTTP 与 Cordis 钩子。安装前应阅读 源码 与 MIT 许可证，确认与自身环境一致。
与线索表述的差异：社区简介里常写「全部第三方不可用时兜底 DeepSeek 官方」；仓库明确默认不自动切官方计费，只有配置 officialFallback 后才兜底。以 README 为准。
其他：查询余额失败时不会把 balance: null 当成 0；宿主无 createSharedFetchHandler 时余额能力降级为 no-connection，不抛错拖垮宿主。
结尾¶
dsh-ofm-quota 把 OFM 分散在各控制台的积分与 token 消耗拉到 DSH 右侧栏，并在配额类失败时按同名模型自动换路，默认不把用户悄悄导到按量计费官方路由。目录与文档入口：
- 社区目录页：https://www.skillhub.cn/plugins/dx906/dsh-ofm-quota
- GitHub：https://github.com/dx906/dsh-ofm-quota
