@jsonstudio/rcc 0.89.1205 → 0.89.1457

package/docs/plans/transparent-429-failover.md

@@ -0,0 +1,89 @@
+# Transparent 429 Failover Strategy Plan
+
+## Objective
+Implement a transparent failover strategy for 429 (Too Many Requests) and other recoverable errors within the `RouteCodexHttpServer`. Instead of returning the error to the client and relying on client-side retries, the server should automatically switch to the next available provider and retry the request internally.
+
+## Current Behavior
+1. `executePipeline` runs the Hub Pipeline to select a provider.
+2. It attempts to send the request via `handle.instance.processIncoming`.
+3. If the provider returns a 429 error, the error is caught, reported via `emitProviderError`, and then re-thrown.
+4. The Express error handler catches the re-thrown error and sends an error response to the client.
+5. The Virtual Router updates its state (via `emitProviderError`), so the *next* client request is routed differently, but the *current* request fails.
+
+## Proposed Strategy
+Modify `executePipeline` in `src/server/runtime/http-server/index.ts` to implement an internal retry loop.
+
+### implementation Details
+
+#### 1. Retry Loop in `executePipeline`
+Wrap the pipeline execution and provider sending logic in a loop that allows for a configurable number of retries (e.g., 3 attempts).
+
+```typescript
+// Conceptual Logic
+let attempts = 0;
+const maxAttempts = 3;
+const excludedProviders = new Set<string>();
+
+while (attempts < maxAttempts) {
+  attempts++;
+  try {
+    // 1. Run Pipeline (Selection)
+    // Pass excludedProviders to metadata to hint the router to avoid them
+    // (Requires verification that HubPipeline respects 'excludedProviders' or 'blacklist' in metadata)
+    const pipelineResult = await this.runHubPipeline(input, { 
+      ...metadata,
+      excludedProviders: Array.from(excludedProviders) 
+    });
+
+    // 2. Prepare Provider
+    // ... (existing preparation logic) ...
+
+    // 3. Send to Provider
+    const response = await handle.instance.processIncoming(providerPayload);
+    
+    // Success - return response
+    return convertedResponse;
+
+  } catch (error) {
+    // 4. Error Handling & Failover Decision
+    const status = this.extractResponseStatus(error) || error.status;
+    const isRateLimit = status === 429 || error.code === '429';
+
+    // Verify if we should retry
+    if (isRateLimit && attempts < maxAttempts) {
+      // Log the internal failover
+      this.logStage('provider.failover', input.requestId, { ... });
+      
+      // Report error to update Router health state
+      emitProviderError({ ... });
+      
+      // Add current provider to exclusion list for next iteration
+      if (target?.providerKey) {
+        excludedProviders.add(target.providerKey);
+      }
+      
+      // Continue to next loop iteration
+      continue;
+    }
+    
+    // If not retryable or exhausted, re-throw (existing behavior)
+    throw error;
+  }
+}
+```
+
+#### 2. Metadata Handling
+Ensure that `runHubPipeline` and the underlying `llmswitch-core` Hub Pipeline can accept an exclusion list. If direct support is missing, we rely on the `emitProviderError` call, which should update the Virtual Router's health state (marking the node as unhealthy/rate-limited). The subsequent `runHubPipeline` call should then naturally pick a different healthy provider.
+
+#### 3. Circuit Breaking
+The `emitProviderError` function already integrates with `providerErrorCenter`. We must ensure that 429 errors trigger a temporary "unhealthy" status in the router's load balancer so that the failing provider is skipped in the immediate retry.
+
+### Risks & Mitigations
+*   **Infinite Loops**: Strict `maxAttempts` counter prevents indefinite loops.
+*   **Latency**: Retries add latency. We should ensure the `attempts` cap is low (e.g., 3) to fail fast if all providers are busy.
+*   **State Propagation**: If `emitProviderError` is async or slow to update the Router state, the retry might pick the same provider. Passing `excludedProviders` in metadata is the robust fix, assuming Router support.
+
+## Next Steps
+1.  Verify if `HubPipeline.execute` supports `excludedProviders` or `blacklist` in input metadata.
+2.  Implement the retry loop in `src/server/runtime/http-server/index.ts`.
+3.  Test with a mock provider simulating 429s to verify failover behavior.

package/docs/plans/unified-hub-framework-v1.md

@@ -0,0 +1,245 @@
+# Unified Hub Framework V1（单一路径 + 强制白名单 + 协议注册表）设计文档
+
+本文档是一个“逐步迁移”的架构改造计划，目标是把当前 llmswitch-core 的入站/出站/工具治理/ServerTool followup 等逻辑，收敛到**一套不可绕过的骨架**（single execution path），并把协议差异从“各处散落实现”改造成“表驱动 + 注册表 + 强制策略（policy）”。
+
+## 0. 背景与约束（不可违背）
+
+来自 RouteCodex V2 Working Agreement 的硬约束：
+
+- **单一执行路径**：`HTTP server → llmswitch-core Hub Pipeline → Provider V2 → upstream AI`。
+- **llmswitch-core 负责工具与路由**：host/server/provider 不得“修补工具调用/重写参数/决定路由”；只能使用 Hub Pipeline APIs。
+- **Provider 层仅做传输**：auth/HTTP/retry/compat hook，不做 payload 语义检查与修补。
+- **Fail fast**：上游错误必须经 providerErrorCenter + errorHandlingCenter 冒泡，无静默 fallback。
+- **Config-driven**：host 只消费 `bootstrapVirtualRouterConfig` 的输出。
+
+本文档的方案会把这些约束“制度化”为框架级别的强制机制，而不是依赖开发习惯。
+
+## 0.1 当前落地状态（截至 2026-01-18）
+
+- Host 已默认注入 `hubConfig.policy.mode="enforce"`（Phase 1：Responses-first provider outbound policy），可通过 `ROUTECODEX_HUB_POLICY_MODE=off` 显式关闭。
+- llmswitch-core PolicyEngine 已支持 Responses 的 provider outbound wrapper 清理（例如扁平化 `request`/`parameters` wrapper）。
+
+## 1. 问题陈述（为什么会反复回归）
+
+现状并不是“没有骨架”，而是：
+
+1) **协议差异分散在多处，形成多套“局部骨架”**
+- 同一类规则（参数白名单/字段位置/工具形态）在 semantic-mapper、bridge、servertool followup builder 等地方各写一份。
+- 这些模块在实践中具备“独立执行能力”（自己组包/自己变更结构），导致出现“绕过骨架”的第二路径。
+
+2) **白名单不是中心化的“契约/政策”，而是若干实现片段**
+- 改动时很容易只改到一处，漏掉其它分支（例如 wrapper/字段位置差异导致的 400/502）。
+- CI 难以系统性捕获：因为没有统一的策略验证点，违规不会在边界处被观测/阻断。
+
+3) **语义治理（tools/servertools/stopMessage/web_search）仍然夹杂在协议实现里**
+- 导致协议越多，分叉越多；新增功能时会在多个协议上重复做“相同语义”的实现与修补。
+
+## 2. 目标（V1 的“完成态”）
+
+V1 的完成态强调“可被强制执行”的工程结构：
+
+- **HubPipeline 是唯一可执行入口**：任何入站、出站、followup 都必须通过同一条 pipeline 路径。
+- **协议实现不可独立执行**：协议代码只允许提供 `ProtocolSpec`（表/纯函数），不允许直接拼装可出站 payload。
+- **白名单/字段位置/映射规则由 PolicyEngine 统一执行**：协议实现不能绕过；CI 可以强约束。
+- **语义统一到 ChatSemantics 的 Operation Table**：协议只负责“wire ↔ ops”的映射；所有行为由统一的 ops 执行器完成。
+
+## 3. 核心方案（架构组件）
+
+### 3.1 ProtocolSpec：协议规格注册表（不可执行）
+
+为每个协议定义一个“规格对象”，用于描述差异，而不是承载执行逻辑。
+
+建议结构（概念）：
+
+- `id`: 协议标识（如 `openai-responses` / `anthropic-messages` / `gemini-chat` …）
+- `wireShape`: 入站/出站字段布局约束
+  - 允许出现在哪些层级（top-level / metadata.extraFields / internal carrier）
+  - streaming 字段优先级与限制（followup 必须 non-stream 等）
+- `parameterPolicy`: 参数白名单与映射
+  - allowlist（按方向：client_in / provider_out / provider_in / client_out）
+  - key remap（如 `max_tokens -> max_output_tokens`）
+  - container/layout（例如 Responses：禁止 `parameters:{...}` wrapper，只能 flatten）
+- `toolSurface`: 工具定义/调用/结果的形态规范
+  - tool definition shape（function tools / builtin tools）
+  - tool call shape（chat 的 tool_calls vs responses 的 output.function_call）
+  - tool result shape（submit_tool_outputs 形态）
+- `compatProfiles`: 可选的兼容 profile（仅做字段 remap/cleanup；禁止做语义修复/路由决策）
+
+实现原则：
+
+- ProtocolSpec 只允许“表 + 纯函数”，不得访问网络/环境/路由状态。
+- ProtocolSpec 不能调用 Provider；所有出站必须由骨架统一负责。
+
+### 3.2 PolicyEngine：强制白名单/字段位置/映射执行器（骨架所有）
+
+PolicyEngine 是 HubPipeline 内部组件，负责把 ProtocolSpec 转化为“不可绕过的边界政策”。
+
+PolicyEngine 在每个边界执行三类动作：
+
+1) `sanitize`：不允许字段一律转入 `metadata.extraFields`
+- 不丢上下文，但**绝不让违规字段出站**。
+
+2) `normalize`：按 spec 做 key remap + 字段布局标准化
+- 解决“同语义不同字段位置/命名”导致的协议不兼容问题。
+
+3) `assert`：在 CI/调试模式下硬断言
+- “违规字段/布局/工具形态”直接抛错（fail fast）。
+- 生产环境可采用 “采样断言 + 快照上报”，先观测再逐步收紧。
+
+PolicyEngine 的关键要求：
+
+- **所有出站（含 servertool followup）必须经 PolicyEngine**。
+- 协议实现不得自行做白名单过滤/布局变更；否则将形成多套政策源。
+
+### 3.3 Operation Table：统一语义到 ChatSemantics（配置驱动）
+
+把“行为”从协议实现里抽离，迁移到 chat process 的统一语义表上：
+
+- `ChatSemantics.ops: Operation[]`（或分域后最终归并为 Operation 表）
+- 每个 Operation 是可组合的执行单元（已有能力应尽量复用现存实现）：
+  - tool governance（形态校验/归一化/透传策略）
+  - web_search（注入 tool result / 或其它注入策略）
+  - stopMessage（停下/继续的 followup 生成）
+  - streaming 决策
+  - route hints / sticky / clear 等路由指令（仍属于 core）
+
+协议差异将变为：
+
+- “wire → ops 的映射表” + “ops → wire 的渲染表”
+
+而不是：
+
+- “每协议一套 if/else 行为实现”。
+
+### 3.4 Canonical Builders：收口所有“组包”入口（尤其 followup）
+
+在 V1 里必须明确禁止以下行为：
+
+- 在 servertool handler 内自行 build provider payload（协议分支拼装）
+- 在 bridge 内部自行决定字段布局（绕过政策）
+
+替代方案：
+
+- `buildProviderRequestFromChat(envelope, spec, ctx)`：唯一出站组包入口
+- `buildClientResponseFromChat(envelope, spec, ctx)`：唯一回包入口
+- `buildFollowupFromCapturedEntry(capture, injection, ctx)`：唯一 followup 入口
+  - followup 必须复用入口 capture（深拷贝），只做 injection
+  - `disableStickyRoutes: true` / `preserveRouteHint: false` / entry endpoint meta 等策略由框架统一注入，而不是散落在各 handler
+
+## 4. 迁移路线（逐步收敛、可回滚）
+
+### Phase 0（观测）：只记录不改写
+
+目标：建立“可量化的违规清单”，不破坏现有行为。
+
+- 在 HubPipeline 关键边界插入 PolicyEngine 的 observe 模式：
+  - req inbound 完成后
+  - provider outbound 发送前
+  - provider inbound 解析后
+  - client outbound 回包前
+- 输出：
+  - 每协议的违规字段统计
+  - 违规快照（含 requestId/endpoint/protocol）
+
+验收标准：
+
+- 不改变任何线上行为（只加日志/快照）。
+- 能得到一份“每协议整改 checklist”。
+
+### Phase 1（政策收口）：统一参数白名单 + 字段位置（收益最大、风险最低）
+
+目标：解决大部分 “400/字段不认/位置不对” 类问题，并防止复发。
+
+- 建立 `ProtocolSpec.parameterPolicy` 并把所有协议的 allowlist/映射/容器规则收口。
+- 所有 provider outbound（含 followup）必须走：
+  - `sanitize → normalize → buildProviderRequestFromChat`
+- CI 新增断言：
+  - “禁止出现未允许字段”
+  - “禁止出现错误容器/布局（例如 parameters wrapper）”
+
+验收标准：
+
+- 通过错误样本回归（errorsamples）与现有 e2e。
+- 违规字段数量显著下降，且新增协议不会引入新路径。
+
+### Phase 2（工具形态收口）：统一 tools 的 definition/call/result 骨架
+
+目标：工具循环不再因为“形态改写/历史与本次不一致”反复出错。
+
+- 将工具表述抽象为 `ProtocolSpec.toolSurface`，并在 PolicyEngine/ToolGovernance 边界统一治理：
+  - “形态归一”与“透传模式”都必须可由 spec/policy 配置（支持 A/B）。
+- 明确规则：
+  - **任何情况下回包格式必须正确**（内容不一定正确，但结构不得静默失败）。
+  - 禁止 silent catch：需要结构化记录 + 可定位快照。
+
+验收标准：
+
+- 新增工具/新增协议不会导致工具循环分叉。
+- tool governance 的行为可配置、可回放、可回归。
+
+### Phase 3（followup 收口）：ServerTool followup 彻底统一
+
+目标：stopMessage/web_search/apply_patch_guard 等 followup 都走同一条路径。
+
+- 强制：所有 handler 只负责“决定 injection”，不得自行构造 payload。
+- `FollowupRequestBuilder` 从 capture 构造（深拷贝）并注入：
+  - entry endpoint meta（保证回路正确）
+  - disableStickyRoutes / preserveRouteHint 等框架策略
+  - route hint/stopMessage 状态推进策略
+
+验收标准：
+
+- servertools 之间只允许注入内容不同，结构生成逻辑完全复用。
+- 任意协议下 followup 构建一致，差异由 spec 控制。
+
+### Phase 4（语义迁移）：把协议逻辑迁移到 Operation Table
+
+目标：把“协议分支中的语义实现”迁出，协议只保留映射表。
+
+- 从通用语义开始迁移：streaming、tool choice、web_search、stopMessage。
+- 再迁移协议特殊字段为 ops 映射（保持兼容 profile 仅做字段清理）。
+
+验收标准：
+
+- semantic-mapper 逻辑显著减少，主要是字段搬运+映射。
+- 新增语义能力只需新增 Operation（无需改多协议分支）。
+
+### Phase 5（删旧路径）：删除独立执行逻辑，保证“只有一个执行路径”
+
+目标：结构性保证不再回到“各自实现”的状态。
+
+- 标记旧的 builders/bridges 为 deprecated。
+- 删除/封装所有允许绕过骨架的入口函数，仅保留：
+  - ProtocolSpec 注册
+  - PolicyEngine 执行
+  - Operation 执行器
+
+## 5. 测试与回归策略（保证可控演进）
+
+建议把回归分为三层，确保每一层都有“格式必正确”的断言：
+
+1) **PolicyEngine 单元测试**：每协议的 allowlist/layout/映射测试（可表驱动）。
+2) **HubPipeline 快照回归**：errorsamples（输入/输出/快照 meta）覆盖典型失败场景。
+3) **端到端（可选但建议）**：启动 mock upstream（如 antigravity）对 provider 直接请求，覆盖工具循环与 followup 行为。
+
+## 6. 风险与控制（如何避免“大改崩盘”）
+
+- 风险：一次性收口会影响多协议行为。
+  - 控制：Phase 0 先观测，Phase 1 只动白名单与布局，逐步收紧断言。
+- 风险：协议特殊 case 被误当作“违规字段”移入 extraFields。
+  - 控制：spec 明确声明允许字段；extraFields 仅作为保留槽，不应出站。
+- 风险：开发绕过框架继续写独立逻辑。
+  - 控制：CI 增加“边界断言 + 禁止导入/调用某些 builder”的 lint 规则（后续实现）。
+
+## 7. 需要你审批的“下一步落地切入点”
+
+为了最小风险、最大收益，建议优先落地：
+
+- **Phase 0**：PolicyEngine observe-only（不改行为）
+- **Phase 1**：参数白名单与字段位置收口（把出站组包入口统一）
+
+审批点建议：
+
+- ProtocolSpec 的最小字段集合（V1 先覆盖 parametersPolicy + wireShape 的关键布局规则）。
+- PolicyEngine 的运行模式（CI hard assert / prod 采样）。
+- followup 的统一 builder 是否在 Phase 1 还是 Phase 3 再收口（取决于当前回归压力）。

package/docs/provider-config-v2-ui-design.md

@@ -0,0 +1,181 @@
+# Provider 管理视图（基于 Config V2）的 UI 设计草案
+
+> 目标：在现有 Daemon / Token 管理 UI 之外，增加一层 **“基于 Config V2 的 Provider 管理视图”**。  
+> 前端完全通过 API 读取 Config V2 的声明性配置，只读展示，不直接改 runtime，也不在 UI 内做 routing / tool 语义。
+
+---
+
+## 1. 数据来源与边界
+
+- **数据来源**
+  - Config V2 中的 provider 定义（未来的 `provider-v2-loader` + `virtual-router-builder` 的输出），预期字段包括：
+    - `providerId` / `runtimeKey`
+    - `providerFamily`（`openai` / `anthropic` / `gemini` / `glm` / `antigravity` …）
+    - `protocol`（`openai-chat` / `openai-responses` / `gemini-chat` / `anthropic-messages` …）
+    - 绑定的 `targetRuntime` / route key
+    - 默认模型 / model aliases / series（`thinking` / `claude` / `gemini-pro` …）
+    - quota 策略 / cooldown 策略（如果在 V2 里挂）
+    - flags：`enabled` / `disabled`、`beta`、`internal-only` 等
+
+- **边界约束**
+  - UI 只读 Config V2 的**声明性配置**，不直接操作虚拟路由 runtime。
+  - 真正的合并 / 组装仍然走 `bootstrapVirtualRouterConfig`，UI 只是把结果可视化。
+  - 不在这个视图里做工具语义或 routing 逻辑，只展示：
+    - “有哪些 provider”
+    - “它们绑定到哪些 runtime / route / credential”
+
+---
+
+## 2. UI 入口：Providers (Config V2) 子视图
+
+- 顶层 Tab 仍然是 `Providers`（复用 daemon/token 管理 UI）。
+- 在 `Providers` Tab 内增加二级切换：
+  - `Runtime health`：现有视图，展示虚拟路由 runtime 的健康状态（metrics、429 冷却等）。
+  - `Config V2`：**新视图**，只从 Config V2 读取 provider 定义，做表格 + 详情的只读展示。
+
+> 设计原则：Runtime health = “实际运行状态”；Config V2 = “声明性配置视图”。两者同屏，但逻辑解耦。
+
+---
+
+## 3. Config V2 Providers 视图布局
+
+### 3.1 顶部 Summary 区
+
+- **聚合统计**
+  - Providers 总数：`N`（从 Config V2 统计）
+  - 各 family 数量：OpenAI / Anthropic / Gemini / Antigravity / GLM …
+  - Enabled vs Disabled：`N_enabled` / `N_disabled`
+- **Config 路径信息**
+  - 显示 Config V2 的主配置文件路径（只读），例如：
+    - `config/virtualrouter.v2.json`
+    - 或其它 V2 入口文件（如 modules 配置）
+
+### 3.2 Provider 列表（主表格）
+
+- 建议列：
+  - **Provider ID**：如 `antigravity.jasonqueque.gemini-3-pro-low`
+  - **Family**：`Gemini` / `OpenAI` / `Anthropic` / `GLM` / `Antigravity` …
+  - **Protocol**：`gemini-chat` / `openai-responses` / `anthropic-messages` …
+  - **Runtime**：虚拟路由 runtime key（如 `antigravity.jasonqueque`）
+  - **Default route / series**：如 `default/thinking-primary`、`default/claude-series`
+  - **Enabled**：`Yes` / `No`
+  - **Source**：Config 文件标识（例如 `virtualrouter.v2.json#providers[3]`）
+  - **Bound credential**：从 daemon/credentials 关联过来的 credential 名称（只读，展示非敏感信息）
+
+- 行级操作（设计层面，仅发起只读 API 调用）：
+  - **Preview route**
+    - 调用 `/config/providers/v2/:id/preview-route`
+    - 展示该 provider 在虚拟路由中的匹配规则 / fallback 方案（人类可读文本）
+  - **View health**
+    - 切换到 `Runtime health` 子视图并带过滤条件，只看该 provider 的健康 + 429 情况
+  - **不提供直接 enable/disable**
+    - 避免在 UI 中直接修改 Config V2，保持“配置文件是唯一真相”的原则。
+    - 如果未来需要变更，可考虑“生成 patch 文件”而不是在线修改。
+
+### 3.3 Provider 详情（侧边栏 / Modal）
+
+点击表格某行，右侧弹出详情区域，包含：
+
+- **基础信息**
+  - Provider ID / Runtime / Family / Protocol
+  - 所属 route / series（如 `route: "default"`, `series: "gemini-pro"`）
+
+- **模型配置**
+  - 默认模型：如 `defaultModel: "gemini-3-pro-low"`
+  - 允许模型列表：`allowedModels: [...]`
+  - 模型别名映射：如 `thinking`, `fast`, `long-context` 等到具体 model 的映射
+
+- **Quota / Cooldown 策略（如果在 Config V2 中声明）**
+  - per-minute / per-hour 限额（静态配置）
+  - series cooldown 策略（与 virtual router 概念对齐，但数据来自 config）
+
+- **Credentials 绑定**
+  - 展示关联的 credential 引用（例如 `credentialsRef: "antigravity-oauth-2-jasonqueque.json"`）
+  - 只显示文件名 / project_id 等非敏感字段。
+  - 提供“查看凭证详情”按钮：
+    - 切换到 `Credentials` Tab，并自动筛选对应 credential。
+
+- **只读说明**
+  - 在详情底部加一行固定提示：
+    - `All fields are read-only; edits must go through Config V2 files and a full RouteCodex reload.`
+
+---
+
+## 4. 后端 API 规划（只读，供 UI 使用）
+
+> 仅为 UI 设计预留接口，不在本任务中实现。  
+> 真正实现时需要同时满足：本地访问安全 + 不泄露敏感字段（例如密钥）。
+
+- `GET /config/providers/v2`
+  - 返回 provider 列表，示例形态：
+  ```jsonc
+  [
+    {
+      "id": "antigravity.jasonqueque.gemini-3-pro-low",
+      "family": "gemini",
+      "protocol": "gemini-chat",
+      "runtimeKey": "antigravity.jasonqueque",
+      "route": "default",
+      "series": "gemini-pro",
+      "enabled": true,
+      "source": "virtualrouter.v2.json#providers[3]",
+      "defaultModels": ["gemini-3-pro-low"],
+      "credentialsRef": "antigravity-oauth-2-jasonqueque.json"
+    }
+  ]
+  ```
+
+- `GET /config/providers/v2/:id`
+  - 返回单个 provider 的完整配置，包括：
+    - 基础信息
+    - 模型列表 / 别名
+    - quota 配置
+    - override 标记
+    - 可选 notes / description
+
+- `GET /config/providers/v2/:id/preview-route`
+  - 返回该 provider 在虚拟路由中的匹配 / fallback 逻辑（已经由后端渲染为人类可读文本）。
+  - 用于前端详情中的 “Preview route” 区块。
+
+> 暂不设计任何 `POST` / `PATCH` API，未来若需要可以扩展为“生成配置 patch 文件”而不是直接改动 Config V2。
+
+---
+
+## 5. 与现有 Daemon / Token UI 的关系
+
+- **Daemon / Token 管理 UI**
+  - 负责 token、credentials、health、quota 的运行时视图：
+    - Daemon 状态（进程 / uptime / 监听端口）
+    - Token / Quota 使用情况、429 冷却
+    - Credentials 列表与验证
+    - Runtime health（per provider / per series）
+
+- **Config V2 Provider 管理视图**
+  - 负责 “有哪些 provider 以及它们在 Config V2 中如何声明”：
+    - Provider ID / family / protocol / runtime / route / series
+    - Config 来源文件
+    - 声明性的 quota / cooldown 策略
+    - 绑定到哪个 credential
+
+- **两者的关联方式**
+  - 通过 `runtimeKey` + `credentialsRef` 进行关联：
+    - 在 Providers (Config V2) 视图中展示绑定的 credential 名称。
+    - 在 Credentials 视图中可以反查“这个 credential 被哪些 provider 使用”。
+  - Runtime 健康信息仍然来自虚拟路由实际状态，Config V2 视图不直接读 health，而是通过跳转 / filter 进行联动。
+
+---
+
+## 6. 后续实现路线（高层 TODO，仅做规划）
+
+1. **后端只读 API 草案实现**
+   - 在 daemon / host 中实现 `/config/providers/v2*` 只读接口。
+   - 确保敏感字段（密钥、token 值）不会出现在返回数据中。
+2. **在现有 `daemon-admin-ui.html` 里接入 Providers(Config V2) 子视图**
+   - 添加二级 Tab 切换。
+   - 用静态假数据先跑通布局，再替换为 API 请求。
+3. **与 Credentials / Runtime health 联动**
+   - Providers 视图中点击 credential / health 操作时，跳转到对应 Tab 并带筛选条件。
+4. **Config V2 ready 之后对齐实际 schema**
+   - 一旦 Config V2 schema 固定，更新此文档中的字段命名与示例。
+   - 清理临时字段，保持“Config 驱动”原则：UI 只读配置，不干预 llmswitch-core 的路由 / 工具逻辑。
+

package/docs/provider-quota-design.md

@@ -0,0 +1,129 @@
+# Provider Quota / Health 管理（文件落盘设计草案）
+
+> 目标：把 provider 健康与流控统一抽象为 quota，通过 daemon 维护一份落盘快照；virtual-router 只读快照决定是否进入路由池与调度优先级。
+
+## 1. 文件结构
+
+- 根目录：`~/.routecodex/quota/`
+  - `provider-quota.json`：当前生效的 quota 快照（virtual-router 只读）。
+  - `provider-errors.ndjson`：错误事件流水（daemon 可选使用，用于恢复 / 调试）。
+
+### 1.1 `provider-quota.json`
+
+```jsonc
+{
+  "version": 1,
+  "updatedAt": "2026-01-15T09:30:12.345Z",
+  "providers": {
+    "antigravity.alias1.gemini-3-pro-high": {
+      "providerKey": "antigravity.alias1.gemini-3-pro-high",
+      "providerId": "antigravity.alias1",
+      "inPool": false,
+      "reason": "cooldown",          // ok|cooldown|blacklist|quotaDepleted|fatal
+      "priorityTier": 100,
+      "rateLimitPerMinute": null,    // null = 不限制
+      "tokenLimitPerMinute": null,
+      "totalTokenLimit": null,
+      "windowStartMs": 1768439400000,
+      "requestsThisWindow": 12,
+      "tokensThisWindow": 8200,
+      "totalTokensUsed": 120000,
+      "cooldownUntil": 1768439700000,   // ms since epoch，null 表示无
+      "blacklistUntil": null,
+      "lastErrorSeries": "E429",
+      "consecutiveErrorCount": 2
+    }
+  }
+}
+```
+
+- 静态 quota：
+  - `priorityTier`：优先级，未配置统一为 `100`。
+  - `rateLimitPerMinute`：每分钟请求数，默认不限制。
+  - `tokenLimitPerMinute` / `totalTokenLimit`：默认不限制。
+- 动态状态：
+  - `inPool` + `reason`：是否参与路由池以及原因。
+  - `cooldownUntil` / `blacklistUntil`：冷却与锁定窗口。
+  - `consecutiveErrorCount` / `lastErrorSeries`：用于“连续多次同类错误”的判定（默认第 4 次进入黑名单）。
+
+### 1.2 `provider-errors.ndjson`
+
+每行一条错误事件，供 daemon 消费或调试：
+
+```json
+{"ts":"2026-01-15T09:14:20.123Z","providerKey":"antigravity.alias1.gemini-3-pro-high","errorCode":"429","series":"E429","route":"thinking","requestId":"...","httpStatus":429,"retryable":true}
+```
+
+## 2. 逻辑规则摘要
+
+### 2.1 错误到 quota 的映射
+
+- 错误 series：`seriesKey = providerKey + ':' + normalizedErrorCode`
+  - `E429`：HTTP 429 / rate-limit。
+  - `E5xx`：稳定性问题（5xx）。
+  - `ENET`：网络 / 超时。
+  - `EFATAL`：不可恢复（配置错误、认证失败、非法模型等）。
+
+#### 429 与其它可恢复错误
+
+- 单一 series 内，连续错误次数 `n`：
+  - 第 1 次：`cooldownUntil = now + 1min`，`inPool=false`。
+  - 第 2 次：`cooldownUntil = now + 3min`。
+  - 第 3 次：`cooldownUntil = now + 5min`。
+- 同一 series 连续 4 次错误：
+  - `blacklistUntil = now + 6h`，`inPool=false`，`reason='blacklist'`。
+- 任意成功事件：
+  - 清零该 provider 的所有 `consecutiveErrorCount`；
+  - 若无有效 `blacklistUntil` 且 `cooldownUntil` 已过期，则恢复 `inPool=true, reason='ok'`。
+
+#### 不可恢复错误（EFATAL）
+
+- 直接：
+  - `blacklistUntil = now + 6h`；
+  - `inPool=false, reason='fatal'`。
+- 恢复依赖时间到期或管理操作，成功事件不会自动解除。
+
+### 2.2 静态 quota（apikey provider）
+
+- 优先级：
+  - 由配置文件提供 `priorityTier`，未配置统一为 `100`。
+  - virtual-router 构建池时按 tier 从小到大分组，同一 tier 内做轮询或加权轮询。
+- 时间流控：
+  - `rateLimitPerMinute`：按 1 分钟窗口统计 `requestsThisWindow`，超过则标记 `reason='quotaDepleted'`，直到窗口翻转。
+- token 控制：
+  - `tokenLimitPerMinute`：按 1 分钟窗口统计 `tokensThisWindow`。
+  - `totalTokenLimit`：累加 `totalTokensUsed`，超过后可直接锁定或标记 `quotaDepleted`。
+
+## 3. 分阶段落地路线（先测试再接线）
+
+### Phase 1：纯逻辑（无 I/O）
+
+- 新增 `provider-quota-center`（纯函数，不依赖文件）：
+  - `applyErrorEvent` / `applySuccessEvent` / `applyUsageEvent` / `tickWindow`。
+- 在 tests 中为上述规则写完整单元测试：
+  - 429 / 其它错误的 1/3/5 分钟与三连错 6 小时；
+  - 成功会清零“连续”错误计数；
+  - 静态 `priorityTier` 默认 100，quota 默认无限制。
+
+### Phase 2：文件存储层
+
+- 实现 `provider-quota-store`：
+  - `loadSnapshot` / `saveSnapshot` 基于 `provider-quota.json`，原子写入。
+  - `appendErrorEvent` 追加写 `provider-errors.ndjson`。
+- 提供一个 `scripts/quota-dryrun.mjs`：
+  - 从事件 fixture 读入，驱动 quota center，输出 `provider-quota.json` 供人工检查。
+
+### Phase 3：Quota Daemon（独立运行）
+
+- 在 daemon 进程中集成 quota center 与 store：
+  - 从错误 / 成功 / usage 事件源消费消息；
+  - 周期性更新内存状态并写回 `provider-quota.json`。
+- 提供 `--dry-run` / `--once` 模式，仅读取 `provider-errors.ndjson` 和 config，生成一次快照后退出，用于验证逻辑。
+
+### Phase 4：virtual-router 接线（可通过 feature flag 控制）
+
+- 在 virtual-router 构建 provider 池时：
+  - 可选读取 `~/.routecodex/quota/provider-quota.json`：
+    - 过滤 `inPool !== true` 或 `cooldownUntil/blacklistUntil > now` 的 provider。
+    - 按 `priorityTier` 做 tier 调度。
+- 初期通过环境变量开启（例如 `ROUTECODEX_QUOTA_ENABLED=1`），待稳定后再作为默认路径。