dsh-opencode-routing 2.2.0 → 2.3.0

package/README.ru.md

@@ -0,0 +1,166 @@
+# dsh-opencode-routing
+
+[English](README.md) · [简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · **Русский**
+
+Плагин для [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`), который объединяет два
+прежних плагина в один пакет: **пул аккаунтов OpenCode с автоматическим переключением A→B и маршрутизацией по
+квоте**, а также **панель использования по аккаунтам и моделям**. И то и другое живёт на одной странице Settings —
+«Аккаунты и использование OpenCode».
+
+- **Клиент**: одна `settings.section`, обновляемая каждые 60 с; аккаунты можно добавлять, редактировать,
+  переставлять и проверять; карточки моделей несут теги возможностей; обе таблицы прокручиваются перетаскиванием;
+  интерфейс говорит на 10 языках (язык браузера имеет приоритет).
+- **Хост**: два эндпоинта — `GET /opencode-usage.json` (использование, `?refresh=1` принудительно обновляет) и
+  `GET|POST /opencode-quota-router.json` (пул и маршрутизация; действия ниже).
+
+## Установка
+
+```bash
+npm i dsh-opencode-routing
+```
+
+Пакет поставляется со своим `cordis.patch.yml`: он объявляет провайдеров `opencode-go` / `opencode-free` и
+**единственную** вставку (`id: opencode-router`). Подобъекты `usage:` и `router:` хранят настройки каждой половины
+(у обеих есть `path`, поэтому они не могут делить одно плоское пространство имён).
+
+```yaml
+- insert:
+    - id: opencode-router
+      name: 'dsh-opencode-routing'
+      config:
+        usageUrl: https://opencode.ai/inference/go/v1/usage
+        apiKeyRef: OPENCODE_API_KEY
+        usage:
+          path: /opencode-usage
+          plan: go
+        router:
+          path: /opencode-quota-router
+          routes:
+            - primary: { provider: opencode-go, model: deepseek-v4.1-flash }
+              fallback: { provider: deepseek-account, model: deepseek-flash }
+```
+
+Ключи верхнего уровня применяются к обеим половинам (`usageUrl`, `apiKeyRef`, `probeIntervalMs`, …); ключи внутри
+подобъекта переопределяют только свою половину.
+
+## Пул аккаунтов и переключение при отказе
+
+Порядок пула — это порядок использования. В любой момент «текущим» является ровно один аккаунт, и его ключ
+зеркалируется в ссылку на учётные данные, которую читает провайдер (по умолчанию `OPENCODE_API_KEY`). Поэтому
+переключение аккаунтов не требует изменения конфигурации провайдера: `resolveApiKey` выполняется после хука
+`agent/request`, при каждом потоковом вызове.
+
+- **A исчерпан — B подхватывает**: при `QUOTA` / `ACCOUNT_QUOTA` / 429, когда официальный лимит подтверждённо
+  израсходован, или при ошибке класса аутентификации (`AUTH`, `INVALID_CREDENTIAL`, `MISSING_CREDENTIAL`,
+  `ACCOUNT_SIGN_IN_REQUIRED`, `CLIENT_UPGRADE_REQUIRED`) текущий аккаунт помечается непригодным (до сброса окна, а
+  при сбое аутентификации — на 30 минут), маршрутизация переходит к следующему включённому аккаунту и **повторяет
+  тот же шаг** — ход никогда не деградирует.
+- **Карантин одной модели**: когда лимит исчерпан только у одной модели, а в пуле ещё есть бюджет, карантин
+  применяется только к этой модели (по умолчанию 30 минут); все остальные модели продолжают работать по плану.
+- **Пул исчерпан целиком**: только тогда маршрут откатывается на свой `fallback` (по умолчанию — аккаунт
+  DeepSeek), с пробой `GET /inference/go/v1/usage`, не тратящей токены, каждые 30 минут (или при сбросе
+  скользящего окна), которая автоматически возвращает на план.
+- **Сброс**: «Сбросить метки блокировки» в Settings очищает все метки исчерпания и аутентификации и немедленно
+  возвращает в пул. Аккаунты и ключи не затрагиваются.
+
+## Панель использования
+
+Официальный эндпоинт `/inference/go/v1/usage` возвращает только округлённые проценты по скользящему / недельному /
+месячному окну и **без разбивки по моделям**, тогда как план тарифицирует каждую модель отдельно (5 ч = 20 %
+месячного лимита, неделя = 50 %, месяц = 100 %). Поэтому страница показывает два набора чисел:
+
+- **Официальные проценты** (одна строка на аккаунт): прямо из API — реальное использование аккаунта, включая другие
+  клиенты и другие машины.
+- **Деньги по моделям** (таблица моделей): локальная оценка. Она пересканирует `$DSH_HOME/sessions` за последние
+  40 дней и учитывает только события `assistant/message`, у которых provider начинается с `opencode`, по публичным
+  тарифам (включая 2× пиковое окно DeepSeek). У использования из других инструментов нет локальной записи.
+
+«Посмотреть использование» открывает диалог по аккаунту с тремя окнами, их временами сброса и результатом пробы
+(проверяется только этот аккаунт, модели при этом не переключаются).
+
+«Изменить ключ» получает текущий ключ аккаунта из `GET /opencode-quota-router.json?key=<account id>` и заполняет
+поле ввода (эндпоинт только локальный; снимок списка всегда несёт лишь маску). Названия моделей следуют регистру
+вендора (`deepseek-v4.1-flash` → `DeepSeek V4.1 Flash`); вендоры с опубликованным фирменным знаком отображаются
+встроенным SVG, остальные — буквенным бейджем. «Следующая проба» — настоящий таймер (по умолчанию 30 минут), и
+страница перерисовывается каждую секунду, поэтому он идёт обратным отсчётом; открытие страницы только читает
+снимок и никогда не запускает пробу.
+
+«Что сейчас выгоднее» выводится из выгоды подписки: Go берёт $10 за $100 лимита по прайс-листу (≈ ¥710), поэтому
+OpenCode всегда стоит 10 % официальной цены — на 90 % дешевле. Реальные данные никогда не в пользу официального
+API; кнопка в углу карточки переключает на демонстрационные данные, чтобы увидеть, как выглядел бы такой случай.
+
+Столбец возможностей берётся из того же каталожного эндпоинта (`/inference/go/v1/models`): `modalities.input` и
+`capabilities` отображаются как текст / изображение / видео / аудио / PDF, вызовы инструментов, рассуждения, плюс
+длина контекста. Модели с нулевой ценой показывают «безлимит».
+
+### Пиковые / непиковые часы и праздники
+
+Непиковое окно DeepSeek — всё время вне пекинских понедельника–пятницы 09:00–12:00 и 14:00–18:00 (включая
+обеденный перерыв, ночи, выходные и **официальные государственные праздники**) ровно по половине пиковой цены.
+OpenCode считает пиковыми только UTC понедельник–пятницу 01–04 и 06–10 и **игнорирует китайские государственные
+праздники** (anomalyco/opencode#53071, мейнтейнер: *"Go pricing follows our own schedule, not DeepSeek's holiday
+calendar."*).
+
+Плагин поставляет таблицу китайских государственных праздников на 2026–2031 годы. Она применяется к официальной
+стороне только при `holidayAware: true` (`usage.holidayAware`); по умолчанию выключено, поскольку OpenCode в эти дни
+продолжает брать пиковую цену. Таблица живёт в `usage.js` как `HOLIDAYS`, а `isChinaHoliday()` можно вызывать
+отдельно.
+
+Цену подписки и её лимит можно переопределить через `usage.planPriceUsd` / `usage.planAllowanceUsd`; скидка на
+странице выводится из этих двух чисел, поэтому изменение плана со стороны OpenCode — это правка конфигурации, а не
+патч.
+
+## API настроек
+
+`GET /opencode-quota-router.json` возвращает `{mode, reason, active, accounts[], quarantine[], routes[],
+lastFailure}`; ключи аккаунтов всегда маскируются (`hint`). `POST` на тот же путь с `{action, ...}`:
+
+| action | аргументы | эффект |
+| --- | --- | --- |
+| `add` | `label?`, `key` | создать аккаунт (ключ ≥ 8 символов), сохранить и проверить |
+| `update` | `id`, `label?` / `enabled?` / `key?` | переименовать, отключить/включить, сменить ключ |
+| `remove` | `id` | удалить аккаунт и его ключ (один всегда остаётся) |
+| `activate` | `id` | переключиться на него сейчас |
+| `move` | `id`, `direction: up\|down` | изменить порядок |
+| `probe` | `id?` | проверить все аккаунты или только один |
+| `reset` | — | очистить метки исчерпания/аутентификации и вернуться в пул |
+
+`GET /opencode-usage.json` возвращает `{plan, configuredPlan, detectedPlan, holidayAware, peak, usage,
+accounts[], activeAccount, models[], totals}`; `?refresh=1` сначала принудительно запрашивает свежий официальный
+снимок.
+
+## Языки
+
+Строки интерфейса лежат в `DICT` в `client.js`: `zh` (исходный), `zh-tw`, `en`, а также `es` / `fr` / `de` / `pt` /
+`ja` / `ko` / `ru` (встраиваются из файлов переводов скриптом `scripts/merge-i18n.mjs`; отсутствующий ключ
+откатывается к `en`, затем к самому ключу). `localeOf()` сопоставляет префикс языка браузера и различает
+упрощённый и традиционный китайский.
+
+## Тесты
+
+```bash
+node test.mjs
+```
+
+Квота модели не требуется: поддельный контекст, поддельное хранилище учётных данных, поддельный webServer и
+локальный эндпоинт использования, отвечающий по каждому API-ключу. Покрытие: составное монтирование, принятие
+аккаунта, карантин одной модели, переключение A→B с зеркалированием ключей, проба по аккаунту, откат на весь пул,
+сброс, валидация действий настроек, представление использования (теги возможностей, безлимитные модели, расчёт
+пик/непик, строки биллинга) и деградация до одного аккаунта.
+
+## Связь со старыми пакетами
+
+`dsh-opencode-quota-router` и `dsh-opencode-usage-settings` — его предшественники; всё, что они умели, объединено
+здесь. Оба помечены на npm как deprecated и указывают на этот пакет. Репозитории:
+[`2869949486/dsh-opencode-routing`](https://github.com/2869949486/dsh-opencode-routing) (текущий),
+[`dsh-opencode-quota-router`](https://github.com/2869949486/dsh-opencode-quota-router),
+[`dsh-opencode-usage`](https://github.com/2869949486/dsh-opencode-usage).
+
+## Участие
+
+Issues и pull requests приветствуются — см. [CONTRIBUTING.md](CONTRIBUTING.md). Перед открытием PR запустите
+`node test.mjs`.
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,141 @@
+# dsh-opencode-routing
+
+[English](README.md) · **简体中文** · [繁體中文](README.zh-TW.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Русский](README.ru.md)
+
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）插件，把原先分开的两个插件合成一个：
+**OpenCode 账户池 + 额度路由** 和 **用量看板** 现在装在同一个包里，设置里也只有一个页面
+「OpenCode 账户与用量」。
+
+- **客户端**：`settings.section` 槽位，60 秒自动刷新；账户池可增删改、模型表带能力标签、两张表都能按住左右拖动；界面支持 10 种语言（跟随浏览器语言）。
+- **Host**：两个只读/管理接口 —— `GET /opencode-usage.json`（用量，`?refresh=1` 强制刷新）与 `GET|POST /opencode-quota-router.json`（账户池与路由，动作见下）。
+
+## 安装
+
+```bash
+npm i dsh-opencode-routing
+```
+
+包自带 `cordis.patch.yml`：里面同时声明 `opencode-go` / `opencode-free` 两个 provider 和**一条** insert
+（`id: opencode-router`）。`usage:` 与 `router:` 两个子对象分别对应看板与路由各自的配置项（两边都有 `path`，
+所以必须分开写）。
+
+```yaml
+- insert:
+    - id: opencode-router
+      name: 'dsh-opencode-routing'
+      config:
+        usageUrl: https://opencode.ai/inference/go/v1/usage
+        apiKeyRef: OPENCODE_API_KEY
+        usage:
+          path: /opencode-usage
+          plan: go
+        router:
+          path: /opencode-quota-router
+          routes:
+            - primary: { provider: opencode-go, model: deepseek-v4.1-flash }
+              fallback: { provider: deepseek-account, model: deepseek-flash }
+```
+
+顶层键对两半都生效（`usageUrl`、`apiKeyRef`、`probeIntervalMs` 之类），子对象里的键只覆盖自己那一半。
+
+## 账户池与轮替
+
+账户顺序就是使用顺序。任何时候只有一个「当前账户」，它的密钥会被镜像到 provider 读取的那个凭据引用
+（默认 `OPENCODE_API_KEY`），因此切换账户不需要改任何 provider 配置：`resolveApiKey` 是在
+`agent/request` 钩子之后、每次流式请求时现取的。
+
+- **A 用完自动用 B**：出现 `QUOTA` / `ACCOUNT_QUOTA` / 429 且官方额度确认耗尽，或出现鉴权类错误
+  （`AUTH`、`INVALID_CREDENTIAL`、`MISSING_CREDENTIAL`、`ACCOUNT_SIGN_IN_REQUIRED`、`CLIENT_UPGRADE_REQUIRED`）时，
+  当前账户被标记为不可用（额度用尽到窗口重置，鉴权失败 30 分钟），路由切到下一个启用账户并在**同一步重试**，
+  不会把整轮对话降级。
+- **单模型隔离**：只有一个模型报耗尽、池里还有额度时，只隔离这个模型（默认 30 分钟），其它模型继续走套餐。
+- **整池耗尽**：才把这条路整体回退到 `fallback`（默认 DeepSeek 账户），并每 30 分钟（或 rolling 窗口重置时刻）
+  用零 token 的 `GET /inference/go/v1/usage` 探测，恢复后自动回到套餐。
+- **重置**：设置页的「重置封禁标记」清空所有「额度用尽 / 鉴权失败」标记并立刻回到账户池，不动账户与密钥。
+
+## 用量看板
+
+官方 `/inference/go/v1/usage` 只给一组四舍五入的 rolling / weekly / monthly 百分比，**没有按模型明细**；
+而套餐是按模型各自计额度（5 小时 = 月额度 20%、周 = 50%、月 = 100%）。所以页面有两套数：
+
+- **官方百分比**（每个账户一行）：来自接口，是账户真实用量，别的客户端、别的机器用了也算进去。
+- **按模型金额**（模型表）：本机估算 —— 回扫 `$DSH_HOME/sessions` 近 40 天的会话日志，只统计 provider 以
+  `opencode` 开头的 `assistant/message`，按公开单价（含 DeepSeek 峰谷 2×）折算。别的工具用掉的额度没有本地记录。
+
+「查看用量」按钮按账户弹窗展示三个窗口的百分比、重置时间与探测结果（只探测该账户，不切换模型）。
+
+「编辑密钥」直接用 `GET /opencode-quota-router.json?key=<账户 id>` 取回该账户的当前密钥并预填输入框
+（本机端点；列表快照始终只给掩码）。模型名按厂商习惯大写（`deepseek-v4.1-flash` → `DeepSeek V4.1 Flash`），
+能取到品牌图标的厂商显示 SVG 图标，取不到的保留字母徽标。「下次探测」是真实的定时器（默认 30 分钟一次），
+页面每秒重绘一次，所以会像倒计时一样走；打开页面本身只读快照，不会触发探测。
+
+「此刻用哪个更划算」按套餐杠杆算：Go 付 $10 拿到 $100 官方价额度（≈¥710），所以走 OpenCode 恒为官方价的
+10%（便宜 90%）。真实数据里不会出现官方更便宜，卡片右下角的按钮可以切到示例数据，看那种情况长什么样。
+
+表里每个模型拆成三行：**缓存命中输入 / 缓存未命中输入 / 输出**（按百万 token 折算），缓存命中那行高亮，
+因为大多数请求落在这条线上。官方单价（人民币/百万 token，低谷价）：
+Flash 0.02 / 1 / 4，Pro 0.15 / 4.5 / 13.5；高峰期正好翻倍。
+
+套餐价与额度可以覆盖：`usage.planPriceUsd`（默认 $10）与 `usage.planAllowanceUsd`（默认按 `LIMITS` 的
+Flash 月额度 $100）。页面上的折扣是从这两个数推出来的 —— OpenCode 哪天改价或改额度，改配置即可，
+不需要改代码。
+
+模型表的「能力」列来自同一个模型目录接口（`/inference/go/v1/models`）的
+`modalities.input` 与 `capabilities`，标出 文本 / 图像 / 视频 / 音频 / PDF、工具调用、推理，以及上下文长度；
+价格为 0 的模型显示「无限」。
+
+### 峰谷与节假日
+
+官方 API 的空闲时段是北京周一至周五 09:00–12:00、14:00–18:00 之外（含午休、夜间、周末、**法定节假日**），
+价格正好是峰价一半。OpenCode 只照 UTC 周一至周五 01–04、06–10 两个窗口算峰，**不认中国法定节假日**
+（anomalyco/opencode#53071 维护者原话：*"Go pricing follows our own schedule, not DeepSeek's holiday calendar."*）。
+
+插件里带 2026–2031 的中国法定节假日表，只有把 `holidayAware: true` 写进配置（`usage.holidayAware`）才会计入
+官方侧折算；默认关闭，因为 OpenCode 侧照旧按峰计费。表在 `usage.js` 的 `HOLIDAYS`，`isChinaHoliday()`
+可单独调用。
+
+## 设置接口
+
+`GET /opencode-quota-router.json` 返回 `{mode, reason, active, accounts[], quarantine[], routes[], lastFailure}`，
+账户里的密钥永远是掩码（`hint`）。`POST` 同一路径，body `{action, ...}`：
+
+| action | 参数 | 作用 |
+| --- | --- | --- |
+| `add` | `label?`, `key` | 新建账户（密钥≥8 字符），写入凭据库并探测 |
+| `update` | `id`, `label?` / `enabled?` / `key?` | 改名、停用/启用、换密钥 |
+| `remove` | `id` | 删除账户并清掉它的密钥（至少留一个） |
+| `activate` | `id` | 立刻切到该账户 |
+| `move` | `id`, `direction: up\|down` | 调整顺序 |
+| `probe` | `id?` | 探测全部账户；带 `id` 只探测这一个 |
+| `reset` | — | 清空封禁标记，回到账户池 |
+
+`GET /opencode-usage.json` 返回 `{plan, configuredPlan, detectedPlan, holidayAware, peak, usage, accounts[],
+activeAccount, models[], totals}`；`?refresh=1` 先强制刷新官方快照再返回。
+
+## 多语言
+
+界面文案在 `client.js` 的 `DICT` 里：`zh`（源）、`zh-tw`、`en`，以及 `es` / `fr` / `de` / `pt` / `ja` / `ko` / `ru`
+（由 `_merge_i18n.mjs` 从翻译文件内联，缺键回退到 `en`，再回退到键名）。`localeOf()` 按浏览器语言前缀匹配，
+中文区分简繁。
+
+## 测试
+
+```bash
+node test.mjs
+```
+
+不需要任何模型额度：假 context、假凭据库、假 webServer，本地起一个 usage 端点按 API key 返回不同百分比，
+覆盖组合插件挂载、账户收养、单模型隔离、A→B 切换与密钥镜像、按账户探测、整池耗尽回退、重置、设置动作校验、
+用量视图（能力标签、无限额度、峰谷换算）与单账户退化。
+
+## 与旧包的关系
+
+`dsh-opencode-quota-router` 与 `dsh-opencode-usage-settings` 是它的前身，功能已全部并入本包；
+旧包在 npm 上标记为 deprecated，指向这里。仓库分别是
+[`2869949486/dsh-opencode-routing`](https://github.com/2869949486/dsh-opencode-routing)（当前）、
+[`dsh-opencode-quota-router`](https://github.com/2869949486/dsh-opencode-quota-router)、
+[`dsh-opencode-usage`](https://github.com/2869949486/dsh-opencode-usage)。
+
+## License
+
+MIT

package/README.zh-TW.md

@@ -0,0 +1,111 @@
+# dsh-opencode-routing
+
+[English](README.md) · [简体中文](README.zh-CN.md) · **繁體中文** · [日本語](README.ja.md) · [한국어](README.ko.md) · [Русский](README.ru.md)
+
+一個 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）外掛，把兩個較早的外掛合併成單一套件：具備 **A→B 自動容錯切換與額度路由的 OpenCode 帳戶池**，加上**依帳戶／依模型的使用量儀表板**。兩者都位於同一個設定頁面「OpenCode 帳戶與用量」上。
+
+- **用戶端**：一個 `settings.section`，每 60 秒刷新；帳戶可以新增、編輯、重排與探測；模型卡片帶有能力標籤；兩張表格都可拖曳平移；介面說 10 種語言（瀏覽器語言優先）。
+- **宿主端**：兩個端點 —— `GET /opencode-usage.json`（用量，`?refresh=1` 強制刷新）與
+  `GET|POST /opencode-quota-router.json`（池與路由；動作見下）。
+
+## 安裝
+
+```bash
+npm i dsh-opencode-routing
+```
+
+套件自帶 `cordis.patch.yml`：它宣告 `opencode-go` / `opencode-free` 兩個 provider，以及**單一** insert（`id: opencode-router`）。`usage:` 與 `router:` 兩個子物件分別裝載各自那一半的設定（兩半都擁有自己的 `path`，因此無法共用同一個平面命名空間）。
+
+```yaml
+- insert:
+    - id: opencode-router
+      name: 'dsh-opencode-routing'
+      config:
+        usageUrl: https://opencode.ai/inference/go/v1/usage
+        apiKeyRef: OPENCODE_API_KEY
+        usage:
+          path: /opencode-usage
+          plan: go
+        router:
+          path: /opencode-quota-router
+          routes:
+            - primary: { provider: opencode-go, model: deepseek-v4.1-flash }
+              fallback: { provider: deepseek-account, model: deepseek-flash }
+```
+
+頂層鍵同時套用到兩半（`usageUrl`、`apiKeyRef`、`probeIntervalMs` 等）；子物件內的鍵只覆寫該半邊。
+
+## 帳戶池與容錯切換
+
+池的順序就是使用順序。任一時刻只有一個帳戶是「當前」帳戶，它的金鑰會被鏡射到 provider 讀取的憑證參考（預設 `OPENCODE_API_KEY`）。因此切換帳戶不需要更改 provider 設定：`resolveApiKey` 在 `agent/request` 勾子之後、每一次串流呼叫時執行。
+
+- **A 用盡，B 接手**：當官方額度確認用完時遇到 `QUOTA` / `ACCOUNT_QUOTA` / 429，或遇到驗證類錯誤（`AUTH`、`INVALID_CREDENTIAL`、`MISSING_CREDENTIAL`、`ACCOUNT_SIGN_IN_REQUIRED`、`CLIENT_UPGRADE_REQUIRED`），當前帳戶會被標記為不可用（直到視窗重置，驗證失敗則為 30 分鐘），路由移到下一個已啟用的帳戶並**重試同一個步驟** —— 該回合永遠不會被降級。
+- **單一模型隔離**：當只有一個模型超出額度而池仍有預算時，只有該模型被隔離（預設 30 分鐘）；其他每個模型繼續使用方案。
+- **整個池用盡**：只有到那時，路由才退回到它的 `fallback`（預設為 DeepSeek 帳戶），並每 30 分鐘（或在滾動視窗重置時）以零 token 的 `GET /inference/go/v1/usage` 探測一次，成功後自動回到方案。
+- **重置**：設定中的「重置封鎖標記」會清除所有用盡／驗證標記並立即回到池。帳戶與金鑰不受影響。
+
+## 使用量儀表板
+
+官方的 `/inference/go/v1/usage` 端點只回傳四捨五入的滾動／每週／每月百分比，且**沒有依模型拆分**，而方案對每個模型分別計量（5 小時 = 月額度的 20 %，週 = 50 %，月 = 100 %）。因此頁面顯示兩組數字：
+
+- **官方百分比**（每個帳戶一行）：直接來自 API —— 真實帳戶用量，包含其他用戶端與其他機器。
+- **依模型的金額**（模型表格）：本地估算。它會重新掃描 `$DSH_HOME/sessions` 最近 40 天，只計算 provider 以 `opencode` 開頭的 `assistant/message` 事件，並按公開費率計價（包含 DeepSeek 的 2 倍尖峰時段）。其他工具的使用量沒有本地記錄。
+
+「檢視用量」會開啟一個依帳戶的對話框，顯示三個視窗、它們的重置時間與探測結果（它只探測該帳戶，且從不切換模型）。
+
+「編輯金鑰」會從 `GET /opencode-quota-router.json?key=<account id>` 取得帳戶目前的金鑰並預先填入輸入框（這是僅限本地的端點；清單快照只會帶遮罩值）。模型名稱依廠商的大小寫呈現（`deepseek-v4.1-flash` → `DeepSeek V4.1 Flash`）；有公開品牌標誌的廠商會渲染成內嵌 SVG，其餘則保留字母徽章。「下次探測」是真正的計時器（預設 30 分鐘），頁面每秒重新渲染，因此會倒數；開啟頁面只會讀取快照，永遠不會觸發探測。
+
+「現在用哪個更划算」由訂閱槓桿推導而來：Go 以 $10 換取定價 $100 的額度（≈ ¥710），所以 OpenCode 的價格永遠是官方價格的 10 % —— 便宜 90 %。真實資料永遠不會偏向官方 API；卡片角落的按鈕會切換到範例資料，讓你看見那種情況會長什麼樣子。
+
+能力欄位來自同一個目錄端點（`/inference/go/v1/models`）：`modalities.input` 與 `capabilities` 會渲染成 text / image / video / audio / PDF、工具呼叫、推理，以及上下文長度。零定價的模型顯示「無限」。
+
+### 尖峰／離峰與假日
+
+DeepSeek 的離峰視窗是北京時間週一至週五 09:00–12:00 與 14:00–18:00 之外的所有時間（含午休、夜間、週末與**法定假日**），價格正好是尖峰的一半。OpenCode 只把 UTC 週一至週五 01–04 與 06–10 視為尖峰，並**忽略中國法定假日**（anomalyco/opencode#53071，維護者：*「Go 的定價遵循我們自己的排程，而不是 DeepSeek 的假日行事曆。」*）。
+
+外掛內建 2026–2031 年的中國法定假日表。只有在設定 `holidayAware: true`（`usage.holidayAware`）時才會套用到官方那一邊；預設為關閉，因為 OpenCode 在那些日子仍按尖峰計費。該表位於 `usage.js` 中的 `HOLIDAYS`，而 `isChinaHoliday()` 可以單獨呼叫。
+
+訂閱價格與其額度可用 `usage.planPriceUsd` / `usage.planAllowanceUsd` 覆寫；頁面上的折扣由這兩個數字推導而來，因此 OpenCode 變更方案只是改設定，而不是打補丁。
+
+## 設定 API
+
+`GET /opencode-quota-router.json` 回傳 `{mode, reason, active, accounts[], quarantine[], routes[], lastFailure}`；帳戶金鑰一律遮罩（`hint`）。對同一路徑 `POST` 並帶 `{action, ...}`：
+
+| 動作 | 參數 | 效果 |
+| --- | --- | --- |
+| `add` | `label?`, `key` | 建立帳戶（金鑰 ≥ 8 字元）、儲存並探測 |
+| `update` | `id`, `label?` / `enabled?` / `key?` | 重新命名、停用／啟用、輪換金鑰 |
+| `remove` | `id` | 刪除帳戶及其金鑰（永遠保留一個） |
+| `activate` | `id` | 立即切換到它 |
+| `move` | `id`, `direction: up\|down` | 重新排序 |
+| `probe` | `id?` | 探測所有帳戶，或只探測一個 |
+| `reset` | — | 清除用盡／驗證標記並回到池 |
+
+`GET /opencode-usage.json` 回傳 `{plan, configuredPlan, detectedPlan, holidayAware, peak, usage, accounts[], activeAccount, models[], totals}`；`?refresh=1` 會先強制取得最新的官方快照。
+
+## 語言
+
+介面字串位於 `client.js` 的 `DICT` 中：`zh`（來源）、`zh-tw`、`en`，加上 `es` / `fr` / `de` / `pt` / `ja` / `ko` / `ru`（由 `scripts/merge-i18n.mjs` 從翻譯檔內嵌；缺少的鍵會退回 `en`，再退回該鍵本身）。`localeOf()` 會比對瀏覽器語言前綴，並區分簡體與繁體中文。
+
+## 測試
+
+```bash
+node test.mjs
+```
+
+不需要模型額度：偽造的 context、偽造的憑證儲存、偽造的 webServer，以及一個依 API 金鑰回應的本地用量端點。涵蓋範圍：複合掛載、帳戶採用、單一模型隔離、A→B 容錯切換與金鑰鏡射、依帳戶探測、整池回退、重置、設定動作驗證、用量檢視（能力標籤、無限模型、尖峰／離峰計算、計費列）以及單一帳戶降級。
+
+## 與舊套件的關係
+
+`dsh-opencode-quota-router` 與 `dsh-opencode-usage-settings` 是它的前身；它們所做的一切都合併到這裡。兩者在 npm 上都標記為已棄用並指向這個套件。儲存庫：
+[`2869949486/dsh-opencode-routing`](https://github.com/2869949486/dsh-opencode-routing)（目前版本）、
+[`dsh-opencode-quota-router`](https://github.com/2869949486/dsh-opencode-quota-router)、
+[`dsh-opencode-usage`](https://github.com/2869949486/dsh-opencode-usage)。
+
+## 貢獻
+
+Issue 與 pull request 都歡迎 —— 參見 [CONTRIBUTING.md](CONTRIBUTING.md)。開 PR 前請先執行 `node test.mjs`。
+
+## 授權
+
+MIT —— 參見 [LICENSE](LICENSE)。