waygate-open 1.6.20 → 1.6.22

package/README.md

@@ -8,7 +8,7 @@
 [![NestJS](https://img.shields.io/badge/NestJS-12-E0234E?style=flat-square)](https://nestjs.com)
 [![SQLite](https://img.shields.io/badge/SQLite-better--sqlite3-003B57?style=flat-square)](https://github.com/WiseLibs/better-sqlite3)
 [![Node](https://img.shields.io/badge/Node-%E2%89%A522.9-3C873A?style=flat-square)](https://nodejs.org)
-[![version](https://img.shields.io/badge/version-1.6.20-4A38C0?style=flat-square)](https://github.com/zhanghaojie513/waygate-open/releases)
+[![version](https://img.shields.io/badge/version-1.6.22-4A38C0?style=flat-square)](https://github.com/zhanghaojie513/waygate-open/releases)
 [![tests](https://img.shields.io/badge/tests-754%20passed-0A7247?style=flat-square)](./server)
 
 ![途关 · Waygate](docs/img/intro.png)
@@ -32,9 +32,13 @@
 | --- | --- |
 | ![概览](docs/img/console-overview.png) | ![积分与用量](docs/img/console-usage.png) |
 
-| 请求日志（逐条留痕，SSE 流也在） |
-| --- |
-| ![请求日志](docs/img/console-requests.png) |
+| 请求日志（逐条留痕，SSE 流也在） | 提供商管理（导入授权 / 健康 / 签到） |
+| --- | --- |
+| ![请求日志](docs/img/console-requests.png) | ![提供商管理](docs/img/console-clients.png) |
+
+| API Keys（绑定优先级 / 权限范围 / 配额） | 设置（上游 / 限额 / 日志） |
+| --- | --- |
+| ![API Keys](docs/img/console-keys.png) | ![设置](docs/img/console-settings.png) |
 
 ## 功能
 
@@ -45,27 +49,40 @@
 - **请求日志**：提供商列按「模型 id → 目录归属」解析（`requests` 无 provider_id，绑定名只代表路由偏好）；SSE 流也留痕；**游标（keyset）分页**——翻页期间的新写入不产生重复行；按 `logs.retainDays` 每日自动清理过期日志（启动即补跑停机期间欠的账）
 - **积分与用量**：趋势图（Token / 请求数双口径，**等距时间轴**，空桶补零）、按模型 / 按提供商拆分、缓存命中率、缓存 token 计量（Anthropic 口径：prompt = input + cache_creation + cache_read）
 - **积分账本**：MiniMax `credit/details` 真实余额（精确到 0.01）；凭证 refresh token 自动续期 + 每日签到（专用账号后即可代签）；WorkBuddy 资源包聚合余额（`get-user-resource` POST 实测口径）
-- **Qoder 签到与积分**（v1.6.0，积分口径 v1.6.1 更正）：`campaigns` 签到代领（每日 100 Credits，进**资源包**）+ 积分账本并入概览。走 `openapi.qoder.com.cn`，Bearer 令牌鉴权（**无需 COSY 签名**——那套只用于聊天路径），不顶掉桌面登录。**余额口径**：`v2/me/usage` 给真实余额（`userQuota` 套餐内 + `addOnQuota` 资源包），账本「发放/剩余/已消耗」为真实值；该端点**不提供到期时刻**，故「最近过期」列显示 `—`。另注意 `credits-summary.totalCredits` 是**历史累计消耗**（等于逐日用量之和），与余额不是一回事，单列展示不混算
+- **Qoder 签到与积分**（v1.6.0，积分口径 v1.6.1 更正）：`campaigns` 签到代领（每日 100 Credits，进**资源包**）。走 `openapi.qoder.com.cn`，Bearer 令牌鉴权（**无需 COSY 签名**——那套只用于聊天路径），不顶掉桌面登录。**余额口径**：`v2/me/usage` 给真实余额（`userQuota` 套餐内 + `addOnQuota` 资源包），展示为「发放/剩余/已消耗」；该端点**不提供到期时刻**，故「最近过期」显示 `—`。另注意 `credits-summary.totalCredits` 是**历史累计消耗**（等于逐日用量之和），与余额不是一回事，单列展示不混算
 - **WorkBuddy 领取域**（v1.4.0；v1.6.11 起与转发统一）：签到代领 + 成长任务 + 连登兑换走**用户会话域**（OAuth，`providers/<id>.oauth`，多会话共存不互踢）——正是这条链路让 `ck_` 得以整体退役。诚实边界：任务多为「体验 XX」型，前置条件不满足就如实记 `skipped`，**绝不伪造行为去凑任务**；补登卡/抽奖等资源消耗型操作不自动化
-- **容错**：Qoder 零内容断流**自动重试一次**（对客户端无感）；上游 11128 渠道校验自动降级重试
+- **容错**：Qoder 零内容断流**自动重试一次**（对客户端无感）；上游 11128 渠道校验自动降级重试；**11128 渠道熔断**（连续 3 次「降级重试也 11128」即开闸，冷却期内未打上游、未占并发槽、未计费，毫秒级 502 + `retry-after`，阵发过去自动半开放行探测）——上游阵发期每个失败要烧 ~65s，并发槽是全局单计数，不加熔断会烧满槽饿死其他提供商；**只计渠道级信号**（内容级 11128 降级能过的不计入），避免一个客户端的请求特征变成全提供商的闸门
+- **审计不丢行**：流式请求在途期间密钥被删时，落库撞 `key_id` 外键会丢整行 —— 现自动降级 `key_id = NULL` 重试保住整行（tokens / 积分 / 状态 / 耗时照常），`client_id` / `key_hint` 快照仍在，note 标记 `key_deleted_inflight`
 - **控制台**：React 19 单页，明暗双主题（跟随系统/手动，侧栏底部切换；官网与控制台同套主题——棱镜场景浅色下以 `multiply` 显形、深色下以 `screen`），CSS 伪元素 tooltip 体系，同形状骨架屏；页间数据先旧后新（SWR：重进页面即刻渲染上次数据、后台刷新无缝替换，自己的写操作写穿缓存不闪旧态）；「提供商健康」只读总览
 - **性能**：路由级代码分割：官网与控制台互不加载对方代码，首屏 gzip <100K；vendor 独立 chunk 享 30d `immutable` 长缓存（发版只重下业务 chunk）；概览 5s TTL 缓存（写操作即清）、SQL 语句按文本缓存复用、凭证文件 stat 失效缓存、last_seen 节流落库——同进程转发 SSE，省下的每次查询/写库都是还给流的事件循环时间；Nginx gzip（level 5）压缩传输
 
 ## 快速开始
 
-### 方式一：npm 包（推荐，一条命令）
+### 方式一：npm 包（推荐）
+
+**试用 / 一次性运行** —— `npx` 首次会自动下载到缓存并执行，不必先全局安装：
 
 ```bash
 npx waygate-open
 ```
 
-起本地服务并**自动打开浏览器**到控制台（默认 <http://127.0.0.1:8787/console>）。
+**长期使用** —— 装成全局命令，之后直接敲 `waygate-open`（不再经 npx，启动更快、版本可控）：
+
+```bash
+npm install -g waygate-open
+waygate-open
+```
+
+想看固定版本而不是跟着 `latest` 走：`npx waygate-open@1.6.22`。
+
+两种方式行为一致：起本地服务并**自动打开浏览器**到控制台（默认 <http://127.0.0.1:8787/console>）。
 首次启动的管理口令默认是 **`waygate`** —— 仅当只监听回环（`127.0.0.1`）时套用这个
 默认值；对外监听时改为随机生成并打印在启动日志里。登录后建议去「设置 → 管理口令」改掉。
 
-数据默认落在 `~/.waygate/open/`（库与密钥都在那里）。
+数据默认落在 `~/.waygate/open/`（库与密钥都在那里）—— 与工作目录无关，
+所以全局安装后在任意目录启动都读同一份数据。
 
-常用参数（都有等价环境变量）：
+常用参数（都有等价环境变量；全局安装后把 `npx waygate-open` 换成 `waygate-open` 即可）：
 
 ```bash
 npx waygate-open --port 9000          # 换端口（RELAY_PORT）
@@ -104,9 +121,27 @@ npm run dev:mock          # 或：纯前端开发，内置 Mock 数据（口令
 | `RELAY_UPSTREAM_KEY` | 可选：无 OAuth 时代的全局出站凭证（**v1.6.11 起 WorkBuddy 走 OAuth，不再需要**） |
 | `RELAY_SECRET` | HMAC：密钥哈希 + 会话令牌签名，丢失等于全部密钥作废 |
 | `RELAY_ADMIN_PASSWORD_HASH` | 管理口令 scrypt 哈希（不设则四级回落，首启打印一次性口令） |
-| `RELAY_DATA_DIR` / `RELAY_PORT` | 数据目录（默认 `./data`）与端口（默认 8787） |
+| `RELAY_DATA_DIR` / `RELAY_PORT` | 数据目录与端口（默认 8787）。**数据目录默认值随形态不同**：源码模式 = `./data`（相对启动目录）；npm 包（`npx` / 全局）由 bin 传 `~/.waygate/open`，与工作目录无关 |
+
+### 第一步：导入客户端凭证
+
+三家凭证都来自各客户端的**官方授权**（用户拿不到、也无法手填），入口只有一个：
+控制台「提供商管理 → 导入客户端」（或某一行上的「重新导入授权」用于换账号 / 刷新令牌）。
+
+| 客户端 | 授权方式 | 你需要做什么 |
+| --- | --- | --- |
+| **WorkBuddy** | 官方 OAuth 设备授权 | 弹窗里点「打开授权页」→ 在浏览器确认 → 回来自动落盘 |
+| **MiniMax Code** | PKCE 设备码 | 同上（授权页显示设备码时确认即可） |
+| **Qoder CN** | PKCE 设备授权 | 同上（未授权时上游回 404，属正常等待态） |
+
+> [!NOTE]
+> 私有状态（`device_code` / `code_verifier`）**只存服务端**，绝不回传浏览器。
+> 授权窗口最多等 2 分钟；超时后可用命令续上（`--help` 看对应命令名）。
+
+**同一个客户端出现在两台机器**（例如 relay 跑在服务器、客户端在你本机）时，
+服务端读不到本机登录态 —— 这是正常的，按弹窗提示用「本机推送命令」从你的机器推上去即可。
 
-**Qoder CN 凭证**（若要用第三家）：从本机 Qoder 客户端登录态一键导入，无需手抄令牌：
+**Qoder CN 凭证**（若要用第三家）：也可从本机 Qoder 客户端登录态一键导入，无需手抄令牌：
 
 ```bash
 cd server && node tools/qoder-import-credential.mjs <provider_id>
@@ -170,7 +205,7 @@ curl http://127.0.0.1:8787/v1/chat/completions \
 | 提供商 | 协议 | 凭证形态 | 目录来源 | 积分口径 |
 | --- | --- | --- | --- | --- |
 | **WorkBuddy** | `openai`（`/v2/chat/completions`） | **官方 OAuth 设备授权**（转发与领取域同一凭证，v1.6.11 起；原 `ck_` 密钥已退役） | 上游拉取 + 逐项实测 | 按次回报 `usage.credit`（实扣）+ 资源包聚合余额 |
-| **MiniMax Code** | `anthropic`（`/mavis/api/v1/llm/v1/messages`） | OAuth refresh token（`mmort_`，自动换新） | 内置种子（网关无清单端点） | **独立账本** `credit/details`（精确到 0.01）；单次不回报 → 记 `null` 不编造 |
+| **MiniMax Code** | `anthropic`（`/mavis/api/v1/llm/v1/messages`） | OAuth refresh token（`mmort_`，自动换新） | **上游真拉取** `/mavis/api/v1/models`（失败回落内置种子） | **独立账本** `credit/details`（精确到 0.01）；单次不回报 → 记 `null` 不编造 |
 | **Qoder CN** | `qoder`（COSY 协议，`/algo/…/agent_chat_generation`） | 客户端登录态身份 JSON（`dt-`/`drt-`） | 网关 `/model/list` 真拉取（13 模型） | SSE `usage.credits` × `billable`（免费档实扣 0）；余额走 `openapi` 的 `v2/me/usage`（套餐内 + 资源包，Bearer 无 COSY 签名）；到期时刻上游不提供 |
 
 **路由规则**：模型 id 先跨全部生效提供商**精确匹配（大小写敏感）**，再按提供商内模糊回落。声明行（seed/upstream/manual）优先于 observed 行——observed 泄漏曾导致幽灵目录行抢走别家请求（已修）。
@@ -297,7 +332,7 @@ mindmap
 
 ```bash
 cd server
-npm test            # 727 项单测（vitest）：路由优先级、口径不变式、三种方言翻译、失败落库、趋势桶补齐…
+npm test            # 754 项单测（vitest）：路由优先级、口径不变式、三种方言翻译、失败落库、趋势桶补齐…
 npm run typecheck   # tsc --noEmit
 npm run smoke:boot  # 真起 dist：healthz / 登录 / 目录 / 设置四关
 ```
@@ -353,10 +388,11 @@ npm run dev                 # 联调：代理到 127.0.0.1:8787（推荐）
 ```
 server/                    NestJS + Fastify + better-sqlite3（单文件 SQLite）
   src/proxy/               转发核心：路由解析、三种方言出口（openai/anthropic/qoder）、失败落库
+    channel-breaker.ts     11128 渠道熔断状态机（按提供商独立、内存态、时钟可注入）
     anthropic-upstream/    MiniMax Code 出站（oauth 令牌、账本、SSE 解码、签到）
     qoder-upstream/        Qoder CN 出站（COSY 会话/签名/自定义 base64、SSE 解码、签到与积分账本）
   src/api/                 控制台 API：概览聚合、密钥、目录、提供商、设置（含设置元数据目录）
-  src/catalog/             目录同步（上游拉取 / observed 并入 / 幽灵行防护 / Qoder 拉取）
+  src/catalog/             目录同步（上游拉取 / observed 并入 / 幽灵行防护 / Qoder 与 MiniMax 拉取）
   src/store/               迁移、仓储与日志留存清理（schema.sql 即迁移事实源）
   src/common/              跨模块小件（凭证文件的 stat 失效进程内缓存等）
   tools/                   运维与验收脚本（smoke:boot、凭证导入、迁移…）
@@ -391,4 +427,4 @@ tools/                     仓库级工具（lint 门禁、token 合并、截图
 
 ---
 
-版本约定：`1.0.0` 起 API 契约稳定（当前 `1.6.20`，见 `server/src/version.ts`；历史版本见 [Releases](https://github.com/zhanghaojie513/waygate-open/releases)）。
+版本约定：`1.0.0` 起 API 契约稳定（当前 `1.6.22`，见 `server/src/version.ts`；历史版本见 [Releases](https://github.com/zhanghaojie513/waygate-open/releases)）。

package/docs/architecture.html

@@ -0,0 +1,358 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>途关 Waygate · 技术架构</title>
+<style>
+  /* ── Theme tokens: every color goes through these ─────────────── */
+  :root {
+    --bg: #fafafa;
+    --surface: #ffffff;
+    --fg: #1a1d21;
+    --muted: #6b7280;
+    --faint: #9aa3af;
+    --line: #e2e5ea;
+    --accent: #2563eb;
+    --accent-soft: rgba(37, 99, 235, .10);
+    --shadow: 0 1px 2px rgba(16, 24, 40, .06), 0 4px 12px rgba(16, 24, 40, .05);
+    --edge: #9aa3af;
+    --edge-hl: #2563eb;
+    --band-label: #98a1ad;
+    --store: #0a6a87;
+  }
+  [data-theme="dark"] {
+    --bg: #101317;
+    --surface: #181c22;
+    --fg: #e8ebef;
+    --muted: #98a1ad;
+    --faint: #5f6a77;
+    --line: #2a3038;
+    --accent: #60a5fa;
+    --accent-soft: rgba(96, 165, 250, .12);
+    --shadow: 0 1px 2px rgba(0, 0, 0, .4), 0 4px 14px rgba(0, 0, 0, .35);
+    --edge: #4b5563;
+    --edge-hl: #60a5fa;
+    --band-label: #5f6a77;
+    --store: #3fb6de;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      --bg: #101317; --surface: #181c22; --fg: #e8ebef; --muted: #98a1ad; --faint: #5f6a77;
+      --line: #2a3038; --accent: #60a5fa; --accent-soft: rgba(96,165,250,.12);
+      --shadow: 0 1px 2px rgba(0,0,0,.4), 0 4px 14px rgba(0,0,0,.35);
+      --edge: #4b5563; --edge-hl: #60a5fa; --band-label: #5f6a77; --store: #3fb6de;
+    }
+  }
+
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--fg);
+    font: 400 15px/1.55 system-ui, -apple-system, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+    -webkit-font-smoothing: antialiased;
+  }
+  .page { max-width: 1080px; margin: 0 auto; padding: 40px 24px 72px; }
+
+  header { display: flex; align-items: baseline; gap: 12px; margin-bottom: 8px; }
+  h1 { font-size: 26px; font-weight: 650; margin: 0; letter-spacing: -.01em; }
+  .chip {
+    font: 500 12px/1 ui-monospace, Consolas, monospace;
+    color: var(--accent); background: var(--accent-soft);
+    padding: 4px 8px; border-radius: 6px;
+  }
+  .sub { color: var(--muted); margin: 0 0 8px; font-size: 14px; }
+  .legend { display: flex; gap: 16px; flex-wrap: wrap; margin: 0 0 28px; color: var(--muted); font-size: 12px; }
+  .legend i { display: inline-block; width: 24px; height: 0; border-top: 2px solid var(--edge-hl); vertical-align: middle; margin-right: 6px; }
+  .legend i.dash { border-top: 2px dashed var(--edge); }
+  .theme-toggle {
+    margin-left: auto; border: 1px solid var(--line); background: var(--surface);
+    color: var(--muted); border-radius: 8px; padding: 5px 10px; font-size: 12px; cursor: pointer;
+  }
+  .theme-toggle:hover { color: var(--fg); }
+  :focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+  h2.sec {
+    font-size: 12px; font-weight: 700; letter-spacing: .1em; color: var(--accent);
+    text-transform: uppercase; margin: 0 0 3px;
+  }
+  p.sec-note { color: var(--faint); font-size: 12px; margin: 0 0 24px; }
+  .divider { height: 1px; background: var(--line); margin: 48px 0 40px; }
+
+  /* ── Bands & nodes（标签在左，与模板一致）────────────────────── */
+  #diagramA, #diagramB { position: relative; }
+  .band { display: grid; grid-template-columns: 84px 1fr; gap: 16px; align-items: start; margin-bottom: 40px; }
+  .band:last-child { margin-bottom: 0; }
+  .band-label {
+    color: var(--band-label); font-size: 11px; font-weight: 650; letter-spacing: .06em;
+    padding-top: 14px; text-align: right; line-height: 1.35;
+  }
+  .nodes { display: flex; flex-wrap: wrap; gap: 12px; }
+  .node {
+    flex: 1 1 200px; min-width: 178px;
+    background: var(--surface); border: 1px solid var(--line); border-radius: 10px;
+    padding: 12px 14px; box-shadow: var(--shadow); cursor: pointer;
+    transition: opacity .18s ease, border-color .18s ease;
+  }
+  .node b { display: block; font-size: 14px; font-weight: 600; }
+  .node span { display: block; color: var(--muted); font-size: 12px; margin-top: 2px; line-height: 1.45; }
+  .node.hl { border-color: var(--accent); }
+  .node.dim { opacity: .35; }
+  .node.store b { color: var(--store); }
+
+  /* ── Connector overlay ─────────────────────────────────────────── */
+  #edgesA, #edgesB { position: absolute; inset: 0; width: 100%; height: 100%; pointer-events: none; }
+  #edgesA path, #edgesB path { fill: none; stroke: var(--edge); stroke-width: 1.4; transition: opacity .18s ease, stroke .18s ease; }
+  #edgesA path.hl, #edgesB path.hl { stroke: var(--edge-hl); stroke-width: 2; }
+  #edgesA path.dim, #edgesB path.dim { opacity: .25; }
+  .detail { color: var(--muted); font-size: 12px; margin-top: 6px; min-height: 18px; }
+
+  @media (max-width: 480px) {
+    .band { grid-template-columns: 1fr; }
+    .band-label { text-align: left; padding-top: 0; }
+    #edgesA, #edgesB { display: none; }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .node, #edgesA path, #edgesB path { transition: none; }
+  }
+</style>
+</head>
+<body>
+<div class="page">
+  <header>
+    <h1>途关 Waygate · 技术架构</h1>
+    <span class="chip">v1.6.28</span>
+    <button class="theme-toggle" id="themeToggle" type="button">切换主题</button>
+  </header>
+  <p class="sub">自托管订阅反代：把按客户端订阅计费的服务，转成 OpenAI / Anthropic 兼容接口。</p>
+  <div class="legend">
+    <span><i></i>请求主链路</span>
+    <span><i class="dash"></i>支撑与数据流</span>
+  </div>
+
+  <h2 class="sec">A · 请求链路</h2>
+  <p class="sec-note">调用端 → 鉴权 → 翻译 → 反代管线 → 上游三家（按模型 id 路由，可同时生效）。三家凭证均由控制台「官方授权」导入后落盘服务端。</p>
+  <div id="diagramA">
+    <svg id="edgesA" aria-hidden="true"></svg>
+
+    <div class="band">
+      <div class="band-label">调用端</div>
+      <div class="nodes">
+        <div class="node" id="a-agent" tabindex="0" role="button" aria-pressed="false"><b>编码 Agent / 工具</b><span>OpenAI 兼容 · sk-waygate-*</span></div>
+        <div class="node" id="a-claude" tabindex="0" role="button" aria-pressed="false"><b>Claude 系客户端</b><span>Anthropic /v1/messages</span></div>
+      </div>
+    </div>
+
+    <div class="band">
+      <div class="band-label">网关 · 8787</div>
+      <div class="nodes">
+        <div class="node" id="a-guard" tabindex="0" role="button" aria-pressed="false"><b>KeyGuard 鉴权</b><span>密钥 · IP 策略 · 配额 · 模型范围</span></div>
+        <div class="node" id="a-trans" tabindex="0" role="button" aria-pressed="false"><b>协议翻译</b><span>OpenAI ↔ Anthropic ↔ 三种上游方言</span></div>
+        <div class="node" id="a-pipe" tabindex="0" role="button" aria-pressed="false"><b>反代管线</b><span>模型路由 · 并发闸 · SSE 透传 · usage 累计</span></div>
+        <div class="node" id="a-retry" tabindex="0" role="button" aria-pressed="false"><b>容错</b><span>断流重试 · 11128 渠道降级 · 渠道熔断（快速失败不占槽）</span></div>
+      </div>
+    </div>
+
+    <div class="band">
+      <div class="band-label">上游</div>
+      <div class="nodes">
+        <div class="node" id="a-wb" tabindex="0" role="button" aria-pressed="false"><b>WorkBuddy</b><span>openai 方言 · 官方 OAuth 授权（ck_ 已退役）</span></div>
+        <div class="node" id="a-mm" tabindex="0" role="button" aria-pressed="false"><b>MiniMax Code</b><span>anthropic 方言 · OAuth 自动换 token</span></div>
+        <div class="node" id="a-qd" tabindex="0" role="button" aria-pressed="false"><b>Qoder CN</b><span>COSY 协议 · 客户端登录态身份</span></div>
+      </div>
+    </div>
+  </div>
+  <p class="detail" id="detailA" aria-live="polite">悬停或点击任意模块，查看它的直接链路。</p>
+
+  <div class="divider"></div>
+
+  <h2 class="sec">B · 控制与数据面</h2>
+  <p class="sec-note">控制台经 Admin API 读写；模型目录喂给路由，聚合与账本落在同一个 SQLite 文件。</p>
+  <div id="diagramB">
+    <svg id="edgesB" aria-hidden="true"></svg>
+
+    <div class="band">
+      <div class="band-label">管理面</div>
+      <div class="nodes">
+        <div class="node" id="b-web" tabindex="0" role="button" aria-pressed="false"><b>Web 管理控制台</b><span>React 19 + Vite · 明暗双主题 · 6 页</span></div>
+      </div>
+    </div>
+
+    <div class="band">
+      <div class="band-label">Admin API</div>
+      <div class="nodes">
+        <div class="node" id="b-api" tabindex="0" role="button" aria-pressed="false"><b>控制台 API</b><span>概览 · 用量 · 提供商 · 密钥 · 设置</span></div>
+      </div>
+    </div>
+
+    <div class="band">
+      <div class="band-label">数据服务</div>
+      <div class="nodes">
+        <div class="node" id="b-catalog" tabindex="0" role="button" aria-pressed="false"><b>模型目录</b><span>三家真拉取（WB / Qoder / MiniMax）· seed 回落 · observed 并入</span></div>
+        <div class="node" id="b-agg" tabindex="0" role="button" aria-pressed="false"><b>用量聚合</b><span>requests + aggregates 双写 · 留存清理</span></div>
+        <div class="node" id="b-quota" tabindex="0" role="button" aria-pressed="false"><b>额度采集</b><span>MiniMax 账本 · Qoder 余额 · WB 额度真值</span></div>
+        <div class="node" id="b-claim" tabindex="0" role="button" aria-pressed="false"><b>签到与领取</b><span>三家代签 · WB 成长任务 / 连登兑换</span></div>
+      </div>
+    </div>
+
+    <div class="band">
+      <div class="band-label">凭证来源<br />v1.6.12+</div>
+      <div class="nodes">
+        <div class="node" id="b-import" tabindex="0" role="button" aria-pressed="false"><b>官方授权导入</b><span>三家设备授权（WB 业务码 / MiniMax PKCE / Qoder PKCE+404）· 私有状态只存服务端</span></div>
+      </div>
+    </div>
+
+    <div class="band">
+      <div class="band-label">存储</div>
+      <div class="nodes">
+        <div class="node store" id="b-store" tabindex="0" role="button" aria-pressed="false"><b>SQLite · 单文件</b><span>requests · aggregates · client_keys · model_catalog · providers</span></div>
+      </div>
+    </div>
+  </div>
+  <p class="detail" id="detailB" aria-live="polite">悬停或点击任意模块，查看它的直接链路。</p>
+</div>
+
+<script>
+(function () {
+  var IDLE = '悬停或点击任意模块，查看它的直接链路。';
+
+  function makeDiagram(diagramId, svgId, detailId, EDGES) {
+    var diagram = document.getElementById(diagramId);
+    var svg = document.getElementById(svgId);
+    var detail = document.getElementById(detailId);
+    var paths = [];
+
+    function rel(el) {
+      var r = el.getBoundingClientRect(), d = diagram.getBoundingClientRect();
+      return { x: r.left - d.left, y: r.top - d.top, w: r.width, h: r.height };
+    }
+
+    /* 正交折线：上者底边中点 → 下者顶边中点，中途横移。
+       同层（y 区间重叠）走水平直线，避免绕一圈。 */
+    function elbow(a, b) {
+      var overlapY = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
+      if (overlapY > Math.min(a.h, b.h) * 0.6) {
+        var acx = a.x + a.w / 2, bcx = b.x + b.w / 2;
+        var acy = a.y + a.h / 2;
+        var sx = bcx > acx ? a.x + a.w : a.x;
+        var ex = bcx > acx ? b.x : b.x + b.w;
+        return 'M' + sx + ',' + acy + ' H' + ex;
+      }
+      if (b.y < a.y) { var t = a; a = b; b = t; }
+      var x1 = a.x + a.w / 2, y1 = a.y + a.h, x2 = b.x + b.w / 2, y2 = b.y;
+      var my = (y1 + y2) / 2;
+      if (Math.abs(x1 - x2) < 2) return 'M' + x1 + ',' + y1 + ' V' + y2;
+      return 'M' + x1 + ',' + y1 + ' V' + my + ' H' + x2 + ' V' + y2;
+    }
+
+    function draw() {
+      svg.innerHTML = '';
+      paths = [];
+      var d = diagram.getBoundingClientRect();
+      svg.setAttribute('viewBox', '0 0 ' + d.width + ' ' + d.height);
+      EDGES.forEach(function (e) {
+        var ea = document.getElementById(e.from), eb = document.getElementById(e.to);
+        if (!ea || !eb) return;
+        var p = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+        p.setAttribute('d', elbow(rel(ea), rel(eb)));
+        if (e.dash) p.setAttribute('stroke-dasharray', e.dash);
+        p.dataset.from = e.from; p.dataset.to = e.to;
+        svg.appendChild(p);
+        paths.push(p);
+      });
+    }
+
+    var pinned = null;
+    function label(id) {
+      var el = document.getElementById(id);
+      return el ? el.querySelector('b').textContent : id;
+    }
+    function highlight(id) {
+      var nodes = diagram.querySelectorAll('.node');
+      nodes.forEach(function (n) { n.classList.remove('hl', 'dim'); });
+      paths.forEach(function (p) { p.classList.remove('hl', 'dim'); });
+      if (!id) return;
+      var linked = {};
+      paths.forEach(function (p) {
+        if (p.dataset.from === id || p.dataset.to === id) {
+          p.classList.add('hl'); linked[p.dataset.from] = 1; linked[p.dataset.to] = 1;
+        } else { p.classList.add('dim'); }
+      });
+      nodes.forEach(function (n) {
+        if (n.id === id) n.classList.add('hl');
+        else if (!linked[n.id]) n.classList.add('dim');
+      });
+    }
+    function describe(id) {
+      var el = document.getElementById(id);
+      var inc = EDGES.filter(function (e) { return e.from === id || e.to === id; });
+      var dirs = inc.map(function (e) { return e.from === id ? '→ ' + label(e.to) : '← ' + label(e.from); });
+      detail.textContent = label(id) + '（' + inc.length + ' 条链路）：' + (dirs.join('；') || '无');
+    }
+
+    diagram.querySelectorAll('.node').forEach(function (n) {
+      n.addEventListener('mouseenter', function () { if (!pinned) highlight(n.id); });
+      n.addEventListener('mouseleave', function () {
+        if (!pinned) { highlight(null); detail.textContent = IDLE; }
+      });
+      function toggle() {
+        if (pinned === n.id) {
+          pinned = null; n.setAttribute('aria-pressed', 'false');
+          highlight(null); detail.textContent = IDLE;
+        } else {
+          if (pinned) {
+            var prev = document.getElementById(pinned);
+            if (prev) prev.setAttribute('aria-pressed', 'false');
+          }
+          pinned = n.id; n.setAttribute('aria-pressed', 'true');
+          highlight(n.id); describe(n.id);
+        }
+      }
+      n.addEventListener('click', toggle);
+      n.addEventListener('keydown', function (ev) {
+        if (ev.key === 'Enter' || ev.key === ' ') { ev.preventDefault(); toggle(); }
+      });
+    });
+
+    draw();
+    requestAnimationFrame(draw);
+    if (document.fonts && document.fonts.ready) document.fonts.ready.then(draw);
+    var rt;
+    window.addEventListener('resize', function () { clearTimeout(rt); rt = setTimeout(draw, 120); });
+  }
+
+  makeDiagram('diagramA', 'edgesA', 'detailA', [
+    { from: 'a-agent',  to: 'a-guard' },
+    { from: 'a-claude', to: 'a-guard' },
+    { from: 'a-guard',  to: 'a-trans' },
+    { from: 'a-trans',  to: 'a-pipe' },
+    { from: 'a-pipe',   to: 'a-retry', dash: '3 4' },
+    { from: 'a-pipe',   to: 'a-wb' },
+    { from: 'a-pipe',   to: 'a-mm' },
+    { from: 'a-pipe',   to: 'a-qd' }
+  ]);
+
+  makeDiagram('diagramB', 'edgesB', 'detailB', [
+    { from: 'b-web',    to: 'b-api' },
+    { from: 'b-api',    to: 'b-catalog' },
+    { from: 'b-api',    to: 'b-agg' },
+    { from: 'b-api',    to: 'b-quota' },
+    { from: 'b-api',    to: 'b-import', dash: '4 4' },
+    { from: 'b-catalog', to: 'b-store', dash: '4 4' },
+    { from: 'b-agg',    to: 'b-store', dash: '4 4' },
+    { from: 'b-quota',  to: 'b-store', dash: '4 4' },
+    { from: 'b-claim',  to: 'b-store', dash: '4 4' },
+    { from: 'b-import', to: 'b-store', dash: '4 4' }
+  ]);
+
+  var toggle = document.getElementById('themeToggle');
+  toggle.addEventListener('click', function () {
+    var root = document.documentElement;
+    var dark = root.getAttribute('data-theme') === 'dark';
+    root.setAttribute('data-theme', dark ? 'light' : 'dark');
+  });
+  var prefersDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
+  document.documentElement.setAttribute('data-theme', prefersDark ? 'dark' : 'light');
+})();
+</script>
+</body>
+</html>