前言¶
在 DeepSeek Harness（DSH）里走 OpenCode Go 订阅时，常见做法是只配一个 OPENCODE_API_KEY，额度用尽后整段会话都切到 DeepSeek 账户余额。OpenCode 对每种模型单独计量 5 小时、周、月窗口；某一型号（例如 DeepSeek V4 Pro）打满后，不应把同计划里仍有额度的 DeepSeek V4.1 Flash 一并拖回账户扣费。多账号场景下，一个账号窗口耗尽也不应让仍有 allowance 的账号无法继续服务。
下面介绍的 dsh-opencode-quota-router 是维护者 2869949486 发布的 DSH 插件（分类：模型推理），在 agent/request 与 agent/request-error 瀑布流里做路由：优先消耗当前活跃账户的 OpenCode Go 额度，按账户池顺序 failover，并在单模型耗尽时只让该模型回退到 DeepSeek 账户。
这是什么¶
插件全名 dsh-opencode-quota-router，仓库：https://github.com/2869949486/dsh-opencode-quota-router。社区目录页：https://www.skillhub.cn/plugins/2869949486/dsh-opencode-quota-router。
一句话定位：在多个 OpenCode Go 账户之间按配额自动切换，并对每个模型单独决定是否回退到 DeepSeek 账户（DeepSeek account fallback），而不是一耗尽就全局切账户。
核心功能¶
路由优先级与账户池¶
- 每条被路由的请求优先走当前活跃账户上的 OpenCode Go 路线（
opencode-go）。 - 账户按配置顺序尝试。当活跃账户的 5 小时、周或月窗口用尽（或密钥无法通过认证），路由器会将该账户暂挂至窗口重置，切换到下一个已启用账户，并在同一 turn 内重试失败步骤。
- 仅当所有账户都不可用时，才进入计划级回退（plan-wide fallback），所有主路线模型统一走 DeepSeek 账户。
按模型隔离¶
OpenCode 对每个模型独立计量（5 小时约为月限的 20%，周约为 50%，月为 100%）。当只有某一个模型报告耗尽而计划仍有空间时，仅该模型回退到 DeepSeek 账户对应模型；其余模型继续使用 OpenCode Go。
默认主路线与回退对应关系如下：
| Primary（OpenCode Go） | Fallback（DeepSeek 账户） |
|---|---|
opencode-go/deepseek-v4.1-flash |
deepseek-account/deepseek-flash |
opencode-go/deepseek-v4-pro |
deepseek-account/deepseek-v4-pro |
插件 bundle 还声明 opencode-go 目录路线（按线上 endpoint 裁剪）以及 opencode-free（含 beam-free、iceman-contributor-free 等免费模型）。
探测与无会话重载¶
账户被暂挂或处于回退期间，插件会以零 token 的 GET /inference/go/v1/usage 探测（默认每 30 分钟，或在滚动窗口重置时），额度恢复后自动回到主路线。切换发生在步骤边界，不中断进行中的流式请求与其他 agent。
密钥如何生效¶
pi-ai 按 apiKeyEnv（默认 OPENCODE_API_KEY）在每次 stream 调用前解析一次凭证，没有 per-request 覆盖。路由器把各账户密钥存在凭证库 OPENCODE_API_KEY_<ID> 下，在 agent/request 改写之后、resolveApiKey 之前，把活跃账户密钥镜像写入 OPENCODE_API_KEY，无需改 DSH 核心。
两个监听器以 prepend: true 注册，避免后挂载的 observer 覆盖改写结果。
账户管理与设置页¶
账户 UI 在 sibling 插件 dsh-opencode-usage-settings 中：Settings → OpenCode 账户与用量 → 账户。状态行（正常 / 全量回退 及原因、当前账户、下次探测、立即探测 / 清空隔离）与账户表（掩码密钥、官方 5 小时 / 周 / 月百分比、排序与启停等）在同一页，避免两个 Settings 区块维护同一账户池。
本插件拥有账户池，对外提供：
GET /opencode-quota-router.json：快照（账户、掩码提示、状态、用量、隔离）。POST /opencode-quota-router.json：{ action: add|update|remove|activate|move|probe|reset, ... }。
密钥写入凭证库，响应中不回显明文（仅类似 oc_sk_5…_cGU 的掩码）。
安装与启用¶
在目标 profile 下执行官方安装命令：
dsh plugin --profile <profile> add dsh-opencode-quota-router
安装后在上述 Settings 页添加账户。若环境中已有 OPENCODE_API_KEY，首次启动会自动采纳为第一个账户（OPENCODE_API_KEY_A1），从旧版单密钥升级无需重新录入。
插件声明依赖 DSH ^0.2.0-rc.1（见仓库 package.json，当前版本 1.2.1），许可证 MIT。
配置¶
bundle patch 带默认值；可在 profile patch 中覆盖 opencode-quota-router 行：
- id: opencode-quota-router
config:
usageUrl: https://opencode.ai/inference/go/v1/usage
apiKeyRef: OPENCODE_API_KEY
path: /opencode-quota-router
probeIntervalMs: 1800000
modelQuarantineMs: 1800000
authCooldownMs: 1800000
routes:
- primary: { provider: opencode-go, model: deepseek-v4.1-flash }
fallback: { provider: deepseek-account, model: deepseek-flash }
可选字段包括：minProbeDelayMs、unconfirmedDelayMs、modelQuarantineMs、authCooldownMs、statePath。
状态文件¶
运行时状态位于 $DSH_HOME/opencode-quota-router.json，例如：
{
"version": 3,
"mode": "primary",
"active": "a1",
"accounts": [
{ "id": "a1", "label": "主账号", "keyRef": "OPENCODE_API_KEY_A1", "enabled": true, "exhaustedUntil": 0, "usage": {} }
],
"quarantine": {},
"updatedAt": 0
}
mode: "fallback"表示无账户可用，所有主路线模型走回退。quarantine记录单模型耗尽，仅该模型回退直至until。accounts[].exhaustedUntil为账户窗口重置时刻，0表示可用。
下一步之前会读取该文件，也可手动编辑作覆盖（README 给出了 mode: "fallback" 等示例）。
典型用法与自测¶
日常用法：安装插件 → 在 OpenCode 账户与用量 添加多个账户并调整顺序 → 正常在 DSH 里选用已声明的 OpenCode Go 模型；路由器在步骤边界自动切换账户或单模型回退。
仓库内可用 Node 跑集成测试：
node test.mjs
测试覆盖双向路由、按模型隔离、隔离过期、账户 failover 与密钥镜像、Settings API、计划级回退，以及「瞬时 rate limit 不进入隔离」等规则（假 Cordis 上下文、假凭证库、本地 usage endpoint）。
适用场景与注意¶
适合：持有多个 OpenCode Go 订阅、希望在 DSH 智能体开发中尽量先消耗计划额度、且希望 V4 Pro 与 V4.1 Flash 等模型配额互不影响的用户。
注意：
- DSH 生态是「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。安装前请自行阅读仓库源码与 MIT 许可证，插件以当前
dsh进程权限运行，会读写凭证库与$DSH_HOME状态。 - 完整账户管理 UI 依赖 dsh-opencode-usage-settings，仅装本插件时需通过
GET|POST /opencode-quota-router.json或编辑状态文件维护池子。 - 配置与行为以 README 与
cordis.patch.yml为准；勿假设未在文档出现的 CLI 或安装路径。
结尾¶
dsh-opencode-quota-router 把 OpenCode Go 的多账户顺序 failover、按模型 DeepSeek 回退和定时 usage 探测收进 DSH 插件，并与 OpenCode 用量设置页共用同一账户池。需要细节时可直接查阅 GitHub 仓库 与 SkillHub 目录页。
