@jsonstudio/rcc 0.89.1205 → 0.89.1457

package/docs/pipeline-routing-report.md

@@ -0,0 +1,209 @@
+# 请求路由 – 当前状态报告
+
+## 概览
+
+本报告梳理本项目中“请求从 HTTP 进入到外部服务”的实际执行路径，聚焦已有的服务器/路由/Provider 组件与 `src/modules/pipeline` 下的模块化流水线代码，指出当前生效路径、尚未接入的能力、存在的差距与风险，并给出可落地的改进建议与关键文件定位。
+
+要点摘要：
+- 目前生效的是“直通转发”路径：HTTP Server → OpenAI Router → Pass‑Through Provider → 外部 OpenAI API。
+- 模块化流水线（LLM Switch、Compatibility、Provider、Pipeline Manager）代码已存在于 `src/modules/pipeline`，但尚未被 HTTP 服务实际调用。
+- Anthropic 端点已挂载但返回 501（占位占位符）。
+- Virtual Router 与配置驱动分类逻辑存在，但未接入到 HTTP 请求链路中。
+
+---
+
+## 实际运行路径
+
+1) 启动与 HTTP Server 挂载
+- 程序入口初始化并启动 HTTP Server：
+  - `src/index.ts:69`, `src/index.ts:70`, `src/index.ts:76`
+- 将 OpenAI 路由挂载到 `/v1/openai/*`：
+  - `src/server/http-server.ts:518`
+
+2) OpenAI Chat Completions（非流式）
+- 路由注册：
+  - `src/server/protocol-handler.ts:139`
+- 处理函数直接调用“直通 Provider”（未经过 LLM Switch / Compatibility）：
+  - `src/server/protocol-handler.ts:244`
+- 将返回值直接写回客户端：
+  - `src/server/protocol-handler.ts:269`
+
+3) Pass‑Through Provider（直通转发）
+- 目标地址为 `targetUrl + path`，默认 `targetUrl` 指向 OpenAI 官方 API（如未通过构造参数覆盖）：
+  - 默认取值位置：`src/server/protocol-handler.ts:89`
+- Chat 请求通过 Provider 层 `forwardRequest('/chat/completions', ...)` 直接转发：
+  - `src/providers/core/runtime/chat-http-provider.ts:154`
+- 实际发起 HTTP 请求与头处理：
+  - `src/providers/core/runtime/chat-http-provider.ts:520`
+- 如果原始请求头中带授权信息，会被透传。
+
+4) 流式（SSE）
+- 当前在 Router 内为“本地模拟流式”，并非真实上游 SSE 透传：
+  - `src/server/protocol-handler.ts:812`
+
+5) Anthropic 端点
+- 已挂载 `/v1/anthropic/*`，但固定返回 501：
+  - `src/server/http-server.ts:521`
+
+---
+
+## 模块化流水线能力 vs. 当前使用
+
+目标链路（概念）：LLM Switch → Compatibility → Provider → 外部服务
+
+- LLM Switch（分类/协议识别与转换）
+  - 已有：OpenAI→OpenAI 规范化、Anthropic→OpenAI 映射。
+    - `src/modules/pipeline/modules/llmswitch/openai-normalizer.ts`
+    - `src/modules/pipeline/modules/llmswitch/anthropic-openai-converter.ts`
+  - 现状：HTTP 服务未调用。
+
+- Compatibility（格式转换）
+  - 已有：LM Studio 等兼容模块与 JSON 规则驱动的变换引擎（现全部驻留在 llmswitch-core compat profiles 中）。
+> ⚠️ 2025-12 更新：`src/providers/compat/*` 已下线；兼容行为现由 `sharedmodule/llmswitch-core/src/conversion/compat/` 提供，旧行号仅供历史排查参考。
+  - 历史辅助引擎：`src/modules/pipeline/utils/transformation-engine.ts`
+  - 现状：HTTP 服务未调用。
+
+- Provider（标准 HTTP 通信、无格式转换）
+  - 已有：统一的 Chat/Responses Provider 实现。
+    - `src/providers/core/runtime/chat-http-provider.ts:15`
+    - `src/providers/core/runtime/responses-http-provider.ts:15`
+  - 现状：HTTP 路径应直接复用上述 Provider（由 Hub Pipeline 装配器管理），避免额外的直连/PassThrough 实现。
+
+- 流水线编排
+  - 已有：`BasePipeline` 将 LLM Switch → Workflow → Compatibility → Provider 串联，并在响应端做反向处理：
+    - `src/modules/pipeline/core/base-pipeline.ts:119`
+  - 管理/注册器存在，但未接入 HTTP Server：
+    - `src/modules/pipeline/core/pipeline-manager.ts`
+    - `src/modules/pipeline/core/pipeline-registry.ts`
+
+---
+
+## 配置情况
+
+- 用户 `~/.routecodex/config.json`（或 `ROUTECODEX_CONFIG_PATH` 指定的文件）由 `bootstrapVirtualRouterConfig` 直接解析，得到 `virtualRouter` + `targetRuntime`，HTTP 服务按该结果构造 Hub Pipeline 与 Provider。
+- OpenAI Router 中的 `targetUrl` 由构造参数/默认值直接决定，并非来自 `modules.json`：
+  - `src/server/protocol-handler.ts:89`
+
+---
+
+## Virtual Router 与分类（未接入 HTTP 路径）
+
+- Virtual Router 模块提供：
+  - 配置驱动的请求分类（default/longContext/thinking/coding/webSearch 等）。
+  - 基于 provider.model 与 key 的负载均衡。
+- 代表性位置：
+  - 模块入口：`src/modules/virtual-router/virtual-router-module.ts:19`
+  - 分类与路由选择：`src/modules/virtual-router/virtual-router-module.ts:288`
+  - 分组/负载均衡：`src/modules/virtual-router/virtual-router-module.ts:646`
+
+这些逻辑目前未与 `/v1/openai` 路径串联。
+
+---
+
+## 响应返回结构
+
+- 直通路径下，Router 将 `PassThroughProvider.processChatCompletion` 的返回对象直接 `res.json` 给客户端。该对象是 Provider 自定义的 `ProviderResponse` 包装，含 `success/data/error/usage` 等字段，真实上游的 OpenAI JSON 在 `data` 字段内：
+  - 写回位置举例：`src/server/protocol-handler.ts:269` 等
+
+如需“完全 OpenAI 兼容”输出，应考虑在最终响应前去掉外层包装或改用严格对齐的响应结构。
+
+---
+
+## 差距与风险
+
+- 模块化流水线未接入：请求未经过 LLM Switch / Compatibility 模块，Provider 也非模块化 Provider。
+- Anthropic 端点仅为占位（501），多协议/多提供商能力未成闭环。
+- 流式为本地模拟，缺少真实上游 SSE 透传。
+- OpenAI `targetUrl` 未配置化读取 `modules.json`，多环境/多 Provider 的灵活性受限。
+- Virtual Router 与分类未与 HTTP 链路整合，7 类路由能力无法在运行时发挥作用。
+
+---
+
+## 建议
+
+1) 将 HTTP Server 接入流水线管理器
+- 在请求进入时交给 `PipelineManager`，调用 `BasePipeline.processRequest`，串联 LLM Switch →（Workflow 可选）→ Compatibility → Provider。
+
+2) 引入“智能选择”
+- 使用 `HttpServer` 中的配置驱动 `RouteResolver`（`src/server/http-server.ts`），根据分类器与路由表选择合适的 LLM Switch（如 OpenAI→OpenAI 或 Anthropic→OpenAI）。
+
+3) `targetUrl` 与 Provider 选择配置化
+- 将 Provider 基础地址、鉴权、模型路由统一由 `config/modules.json`（合并配置）驱动，而非在 Router 中硬编码默认值。
+
+4) 完成 Anthropic 端到端闭环
+- 通过模块化链路完成 `anthropic →（LLM Switch）→ Compatibility → Provider` 的全链路调用，以验证多协议能力。
+
+5) 升级流式为真实上游透传
+- 在 Provider 层对接真实流式，并在 Router 层进行透传，输出严格兼容的 OpenAI SSE。
+
+6) 激活 Virtual Router 智能路由
+- 可选：在流水线选择前加入 Virtual Router 的分类逻辑，将请求映射到 7 类路由，并选择相应的流水线配置。
+
+---
+
+## 关键文件参考
+
+- 服务器与路由
+  - HTTP Server 挂载：`src/server/http-server.ts:518`
+  - Anthropic 占位：`src/server/http-server.ts:521`
+  - OpenAI Chat 路由：`src/server/protocol-handler.ts:139`
+  - 直通调用位置：`src/server/protocol-handler.ts:244`
+  - 响应写回：`src/server/protocol-handler.ts:269`
+
+- 直通 Provider
+  - 转发与 fetch：`src/providers/core/runtime/chat-http-provider.ts:520`
+
+- 流水线（已实现但未接入 HTTP 路径）
+  - BasePipeline 主链路：`src/modules/pipeline/core/base-pipeline.ts:119`
+  - LLM Switch（OpenAI 直通）：`src/modules/pipeline/modules/llmswitch/openai-passthrough.ts:15`
+- 历史兼容层（LM Studio）：`src/providers/compat/lmstudio-compatibility.ts:16`
+  - Provider（Chat/Responses）：`src/providers/core/runtime/chat-http-provider.ts:15`
+- 智能选择（格式识别/选择）：`src/server/http-server.ts` 提供的 `ConfigRequestClassifier` + RR 组合逻辑
+
+- Virtual Router 与分类
+  - 模块：`src/modules/virtual-router/virtual-router-module.ts:19`
+  - 路由选择与转换：`src/modules/virtual-router/virtual-router-module.ts:288`
+  - 负载均衡：`src/modules/virtual-router/virtual-router-module.ts:646`
+
+- 配置
+  - 模块配置：`config/modules.json`
+  - 虚拟路由引导：`src/config/routecodex-config-loader.ts` + `llmswitch-core/v2/router/virtual-router/bootstrap.ts`
+
+---
+
+## 附录：端到端路径示意
+
+- 当前生产路径（非流式）：
+```
+HTTP Server → OpenAI Router → Pass‑Through Provider → OpenAI API → OpenAI Router → Client
+```
+
+- 目标模块化路径（OpenAI 直通示例）：
+```
+HTTP → PipelineManager → BasePipeline
+  → LLM Switch（openai‑passthrough）
+  → Workflow（可选）
+  → Compatibility（按 Provider 适配）
+  → Provider（标准 HTTP）
+  → 外部服务
+  ← 反向转换 → Client
+```
+
+- 目标模块化路径（Anthropic → OpenAI 转换示例）：
+```
+HTTP → PipelineManager → BasePipeline
+  → LLM Switch（anthropic‑openai‑converter）
+  → Compatibility（工具/字段格式适配）
+  → Provider（标准 HTTP）
+  → 外部服务
+  ← 反向转换 → Client
+```
+
+---
+
+## 下一步（可选）
+如需，我可以：
+- 将 Router 的直通处理切换为经由 PipelineManager（同时保留“直通模式”作为可配置选项）。
+- 引入 SmartPipelineFactory/Selector，按 URL/请求体自动选择 LLM Switch。
+- 将 Provider 端点、鉴权、模型与路由统一改为配置驱动。
+- 实现真实流式透传与 Anthropic 的完整模块化链路。

package/docs/plans/manager-daemon/PLAN.md

@@ -0,0 +1,86 @@
+# Manager Daemon 规划（Routing / Health / Token）
+
+## 目标
+
+- 用单一 `ManagerDaemon` 进程内模块，统一管理：
+  - Token 生命周期（原 token daemon）。
+  - Virtual Router 路由状态（sticky / session 级指令）。
+  - Provider / 系列级健康与冷却（429 / quota / 熔断）。
+- 支持按 **server + session** 维度持久化状态，server 重启后仍能继承冷却/黑名单与 sticky 配置。
+- 每个子模块完全解耦，可独立启停与测试。
+
+## 模块划分
+
+- `TokenManager`（模块 id: `token`）
+  - 继承现有 token daemon 职责：监控 `~/.routecodex/auth/`、刷新 OAuth token、触发重新认证。
+  - API：供 CLI / HTTP server 查询 token 状态与触发刷新。
+   - 通过 host 级 leader lock（基于 PID 的锁文件）保证 **全局仅有一个 Token 刷新器**（server 内置 TokenManager 与外部 `token-daemon` 互斥）。
+
+- `RoutingStateManager`（模块 id: `routing`）
+  - 负责 session / conversation 级路由指令状态：
+    - sticky target（`forcedTarget` / `stickyTarget`）。
+    - `disabledProviders` / `disabledKeys` / `disabledModels`。
+    - stopMessage 状态（仅路由层视角）。
+  - 与 `VirtualRouterEngine` 的 `RoutingInstructionState` 做双向同步：
+    - 启动时从持久化快照恢复；
+    - 运行时在指令变更时落盘。
+
+- `HealthManager`（模块 id: `health`）
+  - 消费 `providerErrorCenter` / Virtual Router Health 相关事件，维护：
+    - `ProviderKeyState`：单个 providerKey 的健康 / 冷却窗口 / 错误计数。
+    - `SeriesState`：如 claude / gemini 系列的整段熔断与配额冷却。
+  - 对 Virtual Router 暴露 `VirtualRouterHealthStore`：
+    - 启动时提供初始 snapshot（只包含未过期条目）。
+    - 运行时持久化 series cooldown / trip 事件。
+
+## 文件结构（src）
+
+```text
+src/manager/
+  index.ts                # ManagerDaemon 实现
+  types.ts                # ManagerContext / ManagerModule 等公共类型
+  storage/
+    base-store.ts         # StateStore 抽象接口
+    file-store.ts         # JSONL 文件落盘占位实现（后续补全）
+  modules/
+    token/
+      index.ts            # TokenManagerModule 占位（后续迁移现有 token-daemon 实现）
+    routing/
+      index.ts            # RoutingStateManagerModule 占位
+    health/
+      index.ts            # HealthManagerModule 占位
+```
+
+> 当前阶段只创建结构和最小占位实现，确保 TypeScript 能编译，通过后再分阶段迁移逻辑与测试。
+
+## 对外集成关系（之后阶段）
+
+- HTTP server 启动：
+  - 构造 `ManagerDaemon({ serverId })`，按配置注册 `token/routing/health` 模块并调用 `start()`。
+  - 构造 Virtual Router 时，将 `HealthManager` 暴露出的 `VirtualRouterHealthStore` 注入 HubPipeline。
+- 错误与健康事件：
+  - Provider / Hub 通过 `emitProviderError` → `providerErrorCenter` → VirtualRouter → `HealthManager`。
+  - 所有冷却 / 熔断 / 黑名单只在 Virtual Router & HealthManager 合作下维护，Provider/HTTP server 不再各自维护本地状态。
+
+## 交付步骤
+
+1. **阶段 1：骨架搭建**（当前阶段）
+   - 建立 `src/manager/**` 文件结构与基础类型，不改变现有行为。
+   - 将规划文档落盘（本文件），并在 `task.md` 中新增 Manager Daemon 任务。
+
+2. **阶段 2：TokenManager 迁移**
+   - 把现有 `src/token-daemon/*` 逻辑抽取为 `TokenManagerModule` 内部实现。
+   - 保持 CLI/脚本行为不变，只调整内部依赖路径。
+
+3. **阶段 3：HealthManager ↔ VirtualRouter 对接（内存版）**
+   - 在 sharedmodule 中定义 `VirtualRouterHealthStore` 接口和事件模型。
+   - 由 `HealthManagerModule` 提供内存实现，仅反映当前进程的健康状态。
+
+4. **阶段 4：RoutingStateManager 替换 sticky-session 持久化**
+   - 用 RoutingStateManager 接管 `sticky-session-store.ts` 的落盘逻辑，统一 SessionRoutingState schema。
+
+5. **阶段 5：HealthManager 持久化**
+   - 在 file-store 基础上实现 providerKey / series 级 JSONL 落盘与 snapshot 恢复。
+
+6. **阶段 6：接线 & 调试接口**
+   - HTTP server 接入 ManagerDaemon，并提供 `/manager/state/*` 调试端点查看路由池拉黑与 session 状态。

package/docs/plans/provider-config-v2-plan.md

@@ -0,0 +1,176 @@
+# Provider v2 配置与路由拆分落地计划
+
+## 目标与约束
+
+- 将现有「virtualrouter 内联 providers + routing」改为：
+  - Provider 配置：按 provider 维度拆分到 `~/.routecodex/provider/<id>/config.v2.json`。
+  - Routing 配置：保留在主配置（或单独 routing 文件）中，仅描述 route → pool → providerKey 关系。
+- v2 配置通过 `version: "2.0.0"` 与 v1 完全区分，不影响已有 v1 配置（`config.v1.json` / `config.json.virtualrouter.providers`）。
+- 正式运行路径**不做 v1/v2 兼容合并**：v2 模式只读 provider v2 配置；v1 配置仅供迁移脚本和回溯分析使用。
+- 不改动 llmswitch-core 的 VirtualRouter 接口：仍然通过 `bootstrapVirtualRouterConfig(virtualrouter)` 喂入统一的 VirtualRouterInput。
+
+---
+
+## 目录与文件布局（Provider 侧）
+
+1. 顶层 Provider 目录
+
+- 路径：`~/.routecodex/provider`
+- 启动行为：
+  - 若目录不存在：启动时自动创建。
+  - 若存在：每个子目录代表一个 provider 实例（`<providerId>` 或 `<providerId>-<profile>`）。
+
+2. 单个 Provider 目录结构（示例：`~/.routecodex/provider/antigravity`）
+
+- 静态配置（v2）：
+  - 文件：`config.v2.json`
+  - 样例：
+    ```json
+    {
+      "version": "2.0.0",
+      "providerId": "antigravity",
+      "type": "gemini-cli-http-provider",
+      "providerType": "gemini",
+      "baseURL": "https://daily-cloudcode-pa.sandbox.googleapis.com",
+      "auth": {
+        "mode": "oauth",
+        "oauthProviderId": "antigravity",
+        "tokenFile": "~/.routecodex/auth/antigravity-oauth-1-geetasamodgeetasamoda.json"
+      },
+      "models": [
+        {
+          "id": "claude-sonnet-4-5-thinking",
+          "maxTokens": 64000,
+          "maxContext": 148000,
+          "supportsStreaming": true
+        }
+      ],
+      "compat": {
+        "profile": "chat:gemini",
+        "options": {}
+      },
+      "tags": ["gemini", "cli", "antigravity"]
+    }
+    ```
+- 本地 runtime 状态（后续阶段接入）：
+  - `runtime-state.json`：当前 providerKey 级别的健康 / 拉黑 / 冷却状态快照。
+  - `events.jsonl`：ProviderErrorEvent / 手动操作事件流。
+
+3. 与现有 provider 配置的关系
+
+- 如目录下存在 `config.v1.json`，它只在 v1 模式或迁移脚本中使用；v2 模式**只读 `config.v2.json`**。
+- v1 → v2 的对齐由独立脚本完成（例如 shadow/对比脚本），正式 server/CLI 代码不包含自动迁移或合并逻辑。
+
+---
+
+## 主配置（config.json）与 Routing 拆分
+
+1. config.json 角色简化
+
+- 保留：
+  - server 端口、日志选项等 host 级配置。
+  - virtualrouter 的 routing 结构或指向 routing 文件的引用。
+- 不再要求在 `config.json` 内联 provider 列表：
+  - v2 模式下忽略 `virtualrouter.providers` 字段（如存在，仅用于 v1 fallback）。
+- 新增模式开关（示例）：
+  ```json
+  {
+    "virtualrouterMode": "v2",
+    "virtualrouter": {
+      "routing": {
+        "default": {
+          "pools": [
+            { "id": "primary", "targets": ["antigravity.claude-sonnet-4-5-thinking"] }
+          ]
+        }
+      }
+    }
+  }
+  ```
+
+2. VirtualRouterInput 组合逻辑（v2 模式）
+
+- 启动时步骤：
+  1. 扫描 `~/.routecodex/provider`：
+     - 如不存在则创建空目录。
+     - 对每个子目录：若存在 `config.v2.json`：解析为 `ProviderConfigV2`；否则跳过（无隐式迁移）。
+  2. 从 `config.json` / routing 文件读取 routing 配置。
+  3. 组合为 VirtualRouterInput：
+     - `providers`: 仅来自上述 ProviderConfigV2 集合。
+     - `routing`: 来自 routing 配置（route → pools[] → targets[]）。
+  4. 调用 `bootstrapVirtualRouterConfig(input)`，生成 VirtualRouterConfig 交给 HubPipeline。
+
+---
+
+## Provider v2 CLI 管理（rcc provider …）
+
+> 仅定义接口与交互流程，具体实现另行分阶段落地。
+
+1. 命令结构
+
+- `rcc provider list`
+- `rcc provider add`
+- `rcc provider change <providerId>`
+- `rcc provider delete <providerId>`
+
+2. add/change 交互流程（统一）
+
+- 询问 providerId（例如 `antigravity`），检查对应目录是否存在。
+- 选择 provider 类型：
+  - `gemini-http-provider` / `gemini-cli-http-provider` / `responses-http-provider` / `openai-http-provider` / `anthropic-http-provider` / `mock-provider` 等。
+- baseURL 与 endpoint 区分说明，并询问 baseURL（针对常见类型给默认值）。
+- 选择认证方式：
+  - `api_key`：输入 key 名称（env 名或 token 文件路径），选择新增/覆盖。
+  - `oauth`：选择/输入 `oauthProviderId`，说明会复用现有 OAuth 流程。
+- 模型列表配置：
+  - 至少一个模型：输入 modelId，设置 maxTokens / maxContext / supportsStreaming 等，可回车接受默认建议值。
+  - 支持追加多个模型。
+- compat 配置：
+  - 从已支持的 compat profile 列表中选择（例如 `none` / `chat:gemini` / `chat:responses` 等）。
+- 预览：
+  - 在终端打印拟写入的 `config.v2.json`，高亮关键字段。
+- 确认：
+  - 用户确认后写入/覆盖 `~/.routecodex/provider/<id>/config.v2.json`。
+
+3. list/delete 行为
+
+- list：
+  - 扫描所有 `config.v2.json`，输出 providerId/type/baseURL/模型数量等摘要。
+- delete：
+  - 询问确认后：
+    - 仅删除 `config.v2.json`（保留 runtime-state 调试），或
+    - 删除整个 `~/.routecodex/provider/<id>` 目录（可作为高级选项，默认不做）。
+
+---
+
+## 落地阶段计划
+
+> 实际执行顺序将写入 `task.md`，这里给出高层分期。
+
+1. 阶段 1：定义 VirtualRouterInput 与 ProviderConfigV2 schema
+   - 在 host 层显式定义 VirtualRouterInput 类型（providers + routing），抽离出当前 loader 中的隐式结构。
+   - 定义 `config.v2.json` 的 TypeScript 接口与基础校验逻辑。
+
+2. 阶段 2：Provider v2 loader（只读，不接入 runtime）
+   - 实现扫描 `~/.routecodex/provider` 的 ProviderConfigV2 loader（**只读取显式 `config.v2.json`**，不做自动迁移）。
+   - 编写单元测试：确保 loader 对合法 v2 配置的读取行为稳定、可预期；迁移逻辑由单独脚本负责。
+
+3. 阶段 3：Routing loader 与 VirtualRouterInput 组合器
+   - 提取/实现 routing loader（从 config.json 或独立 routing 文件读取 route → pools → targets）。
+   - 实现组合器：从 ProviderConfigV2 + routing 构造 VirtualRouterInput。
+   - 在测试中以 “shadow 模式” 对比 v1 与 v2 VirtualRouterInput，确保结构一致。
+
+4. 阶段 4：接入 runtime（v2 模式开关）
+   - 在 `routecodex-config-loader` 中添加 `virtualrouterMode` 分支：
+     - `v1`：保持现有 monolithic 行为。
+     - `v2`：调用新组合器构建 VirtualRouterInput。
+   - 在 dev 环境下以 v2 模式运行全部现有验证脚本（e2e toolcall / routing-instructions / errorsamples 等），确认行为等价。
+
+5. 阶段 5：CLI 支持（rcc provider …）
+   - 实现 `rcc provider list/add/change/delete` 子命令。
+   - 将 CLI 与 ProviderConfigV2 loader 共用同一 schema/校验。
+   - 编写基础交互测试，确保 CLI 对配置文件的读写与 loader 保持一致。
+
+6. 阶段 6：默认切换与清理
+   - 在确认 v2 模式稳定后，将默认 `virtualrouterMode` 切换为 `v2`，保留 v1 fallback 若干版本。
+   - 在文档和 config 模板中标记 v1 provider 配置为 deprecated，但不立即删除实现，以便回退。 

package/docs/plans/provider-runtime-manager-plan.md

@@ -0,0 +1,209 @@
+# Provider Runtime Manager & Virtual Router 协作设计
+
+> 本文在 Provider v2 配置与路由拆分基础上，细化「全局 Provider 运行时状态管理」与 Virtual Router/Provider 的职责分工。
+
+## 1. 角色与边界
+
+### 1.1 Virtual Router（调度者）
+
+- 只负责：
+  - 根据请求上下文、路由配置和历史错误信息，**决定**哪些 providerKey 需要进入冷却/拉黑窗口。
+  - 在每次路由选择时，读取当前 Provider 运行时视图，过滤掉不可用的 providerKey。
+- 不再持有权威的黑名单/冷却状态：
+  - 不直接维护可写的 `providerCooldowns` 映射。
+  - 不持久化 provider 健康状态，只消费 ProviderRuntimeManager 暴露的只读视图。
+
+### 1.2 ProviderRuntimeManager（状态持有者）
+
+- 作为 ManagerDaemon 下的一个模块（暂定 `ProviderManagerModule` 或对现有 `HealthManagerModule` 的扩展），负责：
+  - 维护全局 Provider 运行时状态（对所有 providerKey）。
+  - 接收 Virtual Router 的「状态决策事件」（例如建议冷却/拉黑），并将其应用到状态表。
+  - 接收 providerErrorCenter 的事件流，更新统计信息和健康状态。
+  - 将状态持久化到磁盘，并在 server 启动时恢复。
+  - 对 Virtual Router 和 Provider runtime 暴露统一的只读视图。
+
+### 1.3 Provider Runtime（执行者）
+
+- 每个 provider 的 HTTP/runtime 实现，在真正发起上游请求前：
+  - 可选地查询 ProviderRuntimeManager 的视图（例如 `isAvailable(providerKey)`）。
+  - 如果被标记为 blacklisted/cooldown，可快速短路（本地 4xx/5xx）或让 Virtual Router 在选路阶段直接排除。
+- 可以在内部增加额外防御逻辑，但**全局生效**的冷却/拉黑以 ProviderRuntimeManager 的状态为准。
+
+---
+
+## 2. 状态模型
+
+### 2.1 ProviderRuntimeState
+
+> 仅示意核心字段，实际实现可根据需要扩展。
+
+```ts
+type ProviderStatus = 'healthy' | 'cooldown' | 'blacklisted' | 'degraded';
+
+interface ProviderRuntimeState {
+  providerKey: string;            // 例如 antigravity.geetasamodgeetasamoda.claude-sonnet-4-5
+  providerId: string;             // 例如 antigravity
+  modelId?: string;               // 例如 claude-sonnet-4-5
+
+  status: ProviderStatus;
+  cooldownExpiresAt?: number;     // ms since epoch
+  blacklistExpiresAt?: number;    // ms since epoch
+
+  lastErrorCode?: string;         // 例如 HTTP_400 / TOOL_PROTOCOL_ERROR
+  lastErrorAt?: number;           // ms since epoch
+
+  errorCounters?: {
+    http4xx?: number;
+    http5xx?: number;
+    timeout?: number;
+    auth?: number;
+    protocol?: number;
+  };
+
+  lastUsedAt?: number;            // 最近一次成功命中的时间
+}
+```
+
+### 2.2 全局快照与本地文件
+
+- 内存视图：
+  ```ts
+  type ProviderRuntimeTable = Map<string, ProviderRuntimeState>; // key = providerKey
+  ```
+- 磁盘持久化：
+  - 全局快照（可选）：`~/.routecodex/state/providers/<serverId>/providers.jsonl`
+  - 每 provider 本地状态（推荐）：
+    - `~/.routecodex/provider/<id>/runtime-state.json`
+    - `~/.routecodex/provider/<id>/events.jsonl`（ProviderErrorEvent / 手动操作日志）
+- TTL 约束：
+  - 所有 `cooldownExpiresAt` / `blacklistExpiresAt` 必须**硬性截断**在 24 小时以内：
+    - 写入前：`expiresAt = min(now + requestedTtl, now + 24h)`。
+  - 启动恢复时，自动丢弃 `expiresAt <= now` 的条目。
+
+---
+
+## 3. 接口设计
+
+### 3.1 Virtual Router → ProviderRuntimeManager（决策与通知）
+
+Virtual Router 不直接改写内部 cooldown map，而是发送「运行时控制事件」：
+
+```ts
+type ProviderRuntimeAction =
+  | { type: 'propose_cooldown'; providerKey: string; ttlMs: number; reason?: string }
+  | { type: 'propose_blacklist'; providerKey: string; ttlMs: number; reason?: string }
+  | { type: 'clear_runtime_state'; providerKey: string; reason?: string };
+
+interface ProviderRuntimeController {
+  applyAction(action: ProviderRuntimeAction): void;
+}
+```
+
+特性：
+
+- Virtual Router 只负责「建议」：
+  - 比如在 series 冷却策略决定某 providerKey 需要 300 秒冷却时，发出 `propose_cooldown`。
+  - 若需要手动清理某个 providerKey 的状态，可发送 `clear_runtime_state`。
+- ProviderRuntimeManager 是唯一实际更新 ProviderRuntimeTable 的组件：
+  - 可以合并多条建议（例如连续的冷却提案，只保留 TTL 更长者或使用统一策略）。
+  - 可以将自动冷却与手动拉黑整合在同一份状态中。
+
+### 3.2 ProviderErrorEvent 流
+
+ProviderRuntimeManager 同时需要直接消费 ProviderErrorEvent，用于统计与自动动作：
+
+```ts
+interface ProviderErrorConsumer {
+  reportError(event: ProviderErrorEvent): void;
+}
+```
+
+行为示例：
+
+- `reportError` 更新 `lastErrorCode` / `lastErrorAt` / `errorCounters`。
+- 根据规则（例如连续 N 次 5xx）自动发起 `propose_cooldown` 或 `propose_blacklist`。
+
+### 3.3 ProviderRuntimeManager → Virtual Router & Provider runtime（视图）
+
+对 Virtual Router 和 Provider runtime 只暴露只读视图接口：
+
+```ts
+interface ProviderRuntimeView {
+  getState(providerKey: string): ProviderRuntimeState | undefined;
+  isRoutable(providerKey: string): boolean;
+}
+```
+
+约定：
+
+- `isRoutable` 判定逻辑至少包含：
+  - 如果 `status === 'blacklisted'` 且 `blacklistExpiresAt > now` → false。
+  - 如果 `status === 'cooldown'` 且 `cooldownExpiresAt > now` → false。
+  - 其他情况视为 true（或根据 `status==='degraded'` 加权处理，具体策略可后续扩展）。
+
+Virtual Router 在选路时只调用 `isRoutable` / `getState`，不直接改写状态。
+
+Provider runtime 可以在发起请求前调用 `isRoutable` 做一次最终检查（可选）。
+
+---
+
+## 4. 事件流与调用时序
+
+### 4.1 错误 → 状态更新 → 下一次选路
+
+1. Provider 发生错误，上报 `emitProviderError({ ..., providerKey, error })`。
+2. `providerErrorCenter` 将 `ProviderErrorEvent` 广播给：
+   - Virtual Router（用于路由统计、series 策略等）。
+   - ProviderRuntimeManager（用于统计与状态更新）。
+3. Virtual Router 根据当前策略计算出建议动作：
+   - 例如：series 熔断认为 `antigravity.*.claude-sonnet-4-5` 需要冷却 60s。
+   - 调用 `ProviderRuntimeController.applyAction({ type: 'propose_cooldown', providerKey, ttlMs: 60000, reason })`。
+4. ProviderRuntimeManager：
+   - 根据 `reportError` 和 `applyAction` 更新 `ProviderRuntimeTable`。
+   - 将更新后的状态写回对应 provider 的 `runtime-state.json`，并按需写全局 snapshot。
+5. 下一次请求到达 Virtual Router：
+   - 从 routing 得到候选 providerKey 列表。
+   - 对每个候选调用 `runtimeView.isRoutable(providerKey)`，过滤掉不可用的 provider。
+   - 在剩余集合上做负载均衡与路由选择。
+
+### 4.2 手动拉黑 / 解除拉黑
+
+1. CLI/HTTP 调用（例如 `rcc provider blacklist ...`）：
+   - 转换为 `ProviderRuntimeAction`，调用 `ProviderRuntimeController.applyAction`。
+2. ProviderRuntimeManager 更新 ProviderRuntimeTable 并持久化。
+3. 后续所有路由命中前都会通过 `isRoutable` 看到新的状态，无需 Virtual Router 知晓具体操作来源。
+
+---
+
+## 5. 持久化与重启行为
+
+1. Server 启动时：
+   - ProviderRuntimeManager：
+     - 扫描 `~/.routecodex/provider/*/runtime-state.json`。
+     - 合并为全局 `ProviderRuntimeTable`，丢弃所有 `expiresAt <= now` 的条目。
+   - Virtual Router Engine：
+     - 通过注入的 `ProviderRuntimeView` 在首次构造时就能看到恢复后的状态。
+
+2. 运行中：
+   - 每次状态变化（自动冷却/手动拉黑/解除）：
+     - 更新内存 map。
+     - 异步保存到对应 provider 目录的 `runtime-state.json`（best-effort）。
+     - 可选保存全局 snapshot（用于快速对比或调试）。
+
+3. 关闭时：
+   - ManagerDaemon 停止各模块：
+     - ProviderRuntimeManager 可选择做一次 `compact()`，清理过期事件并写入最新快照。
+
+---
+
+## 6. 渐进式接线计划（概述）
+
+> 具体执行任务写入 `task.md`，这里只列高层步骤。
+
+1. 在 sharedmodule 中定义 `ProviderRuntimeView` / `ProviderRuntimeAction` 类型（仅接口，不改现有逻辑）。
+2. 在 host 侧实现 ProviderRuntimeManager（内存版 + 基本落盘，不影响当前健康/冷却逻辑）。
+3. 将 Virtual Router Engine 内部的 providerCooldowns 写入逻辑迁移为对 ProviderRuntimeManager 的 action 调用：
+   - Engine 只发出 `propose_cooldown` / `propose_blacklist`，不直接改写本地 map。
+4. 在 Virtual Router 选路路径中改用 `ProviderRuntimeView.isRoutable` 过滤候选 providerKey。
+5. 将持久化逻辑从 sharedmodule 的 healthStore 挪到 host 的 ProviderRuntimeManager（engine 只消费 view，不再直接持久化 health snapshot）。 
+