@jsonstudio/rcc 0.89.1205 → 0.89.1457

package/docs/CODEX_AND_CLAUDE_CODE.md

@@ -0,0 +1,69 @@
+# Codex / Claude Code 接入 RouteCodex
+
+## 1) Codex（~/.codex/config.toml）
+
+Codex 支持在 `~/.codex/config.toml` 里声明多个 `model_providers`。你可以把 RouteCodex 当作“上游 base_url”，让 Codex 的所有请求走本地代理。
+
+一个参考写法（与当前常见的 `tc/tcm` 命名保持一致）：
+
+```toml
+[model_providers.tc]
+name = "rc"
+base_url = "http://127.0.0.1:5555/v1"
+wire_api = "chat"
+env_key = "ROUTECODEX_APIKEY"
+
+[model_providers.tcm]
+name = "rc"
+base_url = "http://127.0.0.1:5555/v1"
+wire_api = "responses"
+env_key = "ROUTECODEX_APIKEY"
+
+[profiles.tc]
+model_provider = "tc"
+model = "gpt-5.2"
+
+[profiles.tcm]
+model_provider = "tcm"
+model = "gpt-5.2"
+```
+
+如果你在 `~/.routecodex/config.json` 中设置了服务端访问密钥（`httpserver.apikey`），则需要在环境变量里提供同样的值：
+
+```bash
+export ROUTECODEX_APIKEY="your-server-apikey"
+```
+
+> RouteCodex 会接受 `Authorization: Bearer ...` 与 `x-api-key: ...` 等多种 header；Codex 侧如何出 header 取决于其实现与 `wire_api` 行为。
+
+## 2) RouteCodex 启动建议
+
+### 标准启动
+
+```bash
+rcc start
+```
+
+### 针对 Codex / Claude 的系统提示词与 UA（可选）
+
+```bash
+rcc start --codex
+# 或
+rcc start --claude
+```
+
+## 3) Claude Code（rcc code）
+
+RouteCodex CLI 内置了 `rcc code` 来启动 Claude Code，并把 Claude Code 的请求代理到本地 RouteCodex：
+
+```bash
+rcc code --ensure-server
+```
+
+常用参数：
+
+- 指定 Claude Code 可执行文件：`rcc code --claude-path /path/to/claude`
+- 指定模型：`rcc code --model <model>`
+- 指定 profile：`rcc code --profile <profile>`
+- 指定 server apikey：`rcc code --apikey <your-server-apikey>`
+

package/docs/CONFIG_ARCHITECTURE.md

@@ -0,0 +1,517 @@
+# RouteCodex 配置系统架构设计
+
+## 1. 系统架构概述
+
+### 1.1 配置层次结构
+```
+用户配置层 (~/.routecodex/config.json)
+    ↓
+系统模块默认 (./config/modules.json)
+    ↓
+配置解析器 (routecodex-config-loader)
+    ↓
+虚拟路由引导 (bootstrapVirtualRouterConfig)
+    ↓
+VirtualRouterArtifacts (virtualRouter + targetRuntime)
+    ↓
+模块初始化 (Hub Pipeline + Provider Runtime)
+```
+
+### 1.2 核心设计原则
+1. **用户优先**: 用户配置覆盖系统默认配置
+2. **模块化**: 每个模块独立配置，支持深度合并
+3. **协议兼容**: 支持OpenAI和Anthropic协议输入/输出
+4. **密钥安全**: 支持AuthFile机制，密钥存储在用户目录
+5. **路由灵活**: 支持多目标负载均衡和协议转换
+
+## 2. 配置文件结构
+
+### 2.1 用户配置文件 (~/.routecodex/config.json)
+
+```json
+{
+  "version": "1.0.0",
+  "description": "RouteCodex User Configuration",
+  "user": {
+    "name": "Default User",
+    "email": "user@example.com"
+  },
+
+  "virtualrouter": {
+    "inputProtocol": "openai",    // openai | anthropic
+    "outputProtocol": "openai",   // openai | anthropic
+
+    "providers": {
+      "openai": {
+        "type": "openai",
+        "baseURL": "https://api.openai.com/v1",
+        "apiKey": [
+          "sk-your-openai-key-here",
+          "authfile-openai-main",
+          "authfile-openai-backup"
+        ],
+        "models": {
+          "gpt-4": {
+            "maxContextTokens": 128000,  // 可选（tokens），不配置使用默认 200000
+            "maxTokens": 32000           // 可选，不配置使用默认值
+          }
+        }
+      }
+    },
+
+    "routing": {
+      "default": [
+        "openai.gpt-4.sk-your-openai-key-here",
+        "openai.gpt-4.authfile-openai-main"
+      ],
+      "longContext": [
+        "anthropic.claude-3-5-sonnet-20241022.sk-ant-your-anthropic-key-here"
+      ]
+    }
+  },
+
+  "httpserver": {
+    "port": 8080,
+    "host": "0.0.0.0"
+  }
+}
+```
+
+##### 2.1.x 路由池（主/备）配置
+
+`virtualrouter.routing` 现在支持“池子”对象，用于声明优先级与备份策略。旧写法（字符串数组）仍被视为单一主池，无须改动。要显式声明主/备池，可使用下列结构：
+
+```jsonc
+"routing": {
+  "default": [
+    { "id": "primary", "priority": 200, "targets": ["glm.glm-4.7", "tab.gpt-5.2-codex"] },
+    { "id": "backup", "backup": true, "targets": ["iflow.kimi-k2"] }
+  ],
+  "thinking": [
+    { "id": "thinking-main", "priority": 300, "targets": ["iflow.kimi-k2-thinking"] },
+    { "id": "thinking-secondary", "priority": 100, "targets": ["tab.gpt-5.2-codex"] },
+    { "id": "thinking-backup", "backup": true, "targets": ["glm.glm-4.7"] }
+  ]
+}
+```
+
+- `priority`：数字越大优先级越高，未显式配置时按声明顺序自动递减。
+- `backup: true`：标记备用池，仅在所有主池耗尽后才会命中（即便 priority 较高，也会自动排在主池之后）。
+- `targets`：与旧写法一致，为 `providerId.modelId`（可选 `providerId.alias.modelId`）列表。
+
+Virtual Router 会在一次请求中依次尝试高优先级池；当前池所有 provider 临时不可用（如 429、健康熔断）时才会降级到下一池，并在下一次请求重新从最高优先级开始检查。
+
+#### 2.1.1 Provider `process` 模式
+- `process` 是 provider 节点的顶层字段，控制 RouteCodex 是否需要介入编解码。
+- 取值 `chat`（默认）：进入 Chat → Virtual Router → Provider 的标准链路，允许跨协议转换（如 `/v1/messages` → Responses）。
+- 取值 `passthrough`：RouteCodex 仅负责路由/鉴权/日志，**请求与响应会原样透传**。为了避免协议错配，要求入口协议必须与 provider 类型一致（例如 providerType=`responses` 只能在 `/v1/responses` 入口透传），否则启动时直接抛错。
+- Passthrough 模式仍然会写入 `client-request` / `provider-request` / `provider-response` 快照，便于审计，但不会再注入模型、stream、instruction 等治理字段。
+
+#### 2.1.2 `contextRouting` 运行策略
+
+`virtualrouter.contextRouting` 用于告诉引擎如何在“上下文接近耗尽”时调整路由。字段如下：
+
+| 字段 | 含义 | 默认值 |
+|------|------|--------|
+| `warnRatio` | 当 `estimatedTokens / maxContextTokens` 高于该阈值时，会把 provider 归入 `risky`/`overflow` 候选，只有当前优先级池全部落入这些档位后才会尝试下一优先级池 | `0.9` |
+| `hardLimit` | 为 `true` 时禁止使用 `maxContextTokens` 以内无法满足的 provider（即拒绝 overflow 候选）| `false` |
+
+> `maxContextTokens` 由 provider 模型配置决定，未显式配置时默认为 **200000 tokens**（tiktoken 估算值）。旧字段 `maxContext` 仍支持，但建议迁移到 `maxContextTokens`。
+
+### 2.2 系统模块默认 (./config/modules.json)
+
+```json
+{
+  "modules": {
+    "virtualrouter": {
+      "enabled": true,
+      "config": {
+        "moduleType": "virtual-router",
+        "timeout": 30000,
+        "inputProtocol": "openai",
+        "outputProtocol": "openai",
+        "userConfigDefaults": {
+          "maxContextTokens": 128000,
+          "maxTokens": 32000
+        }
+      }
+    },
+    "httpserver": {
+      "enabled": true,
+      "config": {
+        "moduleType": "http-server",
+        "port": 5506,
+        "host": "localhost"
+      }
+    }
+  }
+}
+```
+
+### 2.3 虚拟路由产物 (VirtualRouterArtifacts)
+
+`bootstrapVirtualRouterConfig` 输出对象包含两部分：
+
+```ts
+type VirtualRouterArtifacts = {
+  config: {
+    routing: Record<string, Array<{ id: string; targets: string[]; priority: number; backup?: boolean }>>;
+    providers: Record<string, any>;
+    classifiers?: Record<string, any>;
+  };
+  targetRuntime: Record<string, ProviderRuntimeProfile>;
+};
+```
+
+- `config`: 由 Hub Pipeline 消费，包含虚拟路由、分类器、provider 描述等。
+- `targetRuntime`: host 初始化 Provider 实例所需的资料（baseUrl、headers、auth、compatProfile、runtimeKey）。
+
+该对象在内存中直接传递，**不再写入旧版“合并配置”蓝图文件**。任何磁盘快照仅用于调试，不参与运行时决策。
+
+## 3. 配置解析和合并机制
+
+### 3.1 用户配置解析
+
+#### 3.1.1 路由字符串解析
+```typescript
+// 路由字符串格式: "provider.model.key"
+const routeString = "openai.gpt-4.sk-your-openai-key-here";
+
+// 解析结果
+interface RouteTarget {
+  providerId: string;
+  modelId: string;
+  keyId: string;
+  actualKey: string;
+  inputProtocol: "openai" | "anthropic";
+  outputProtocol: "openai" | "anthropic";
+}
+```
+
+#### 3.1.2 AuthFile解析
+```typescript
+// AuthFile格式: "authfile-{filename}"
+// 密钥文件位置: ~/.routecodex/auth/{filename}
+interface AuthFileResolver {
+  resolveAuthKey(keyId: string): string;
+}
+```
+
+#### 3.1.3 模型配置补充
+```typescript
+// 用户配置 + 系统默认值 = 完整配置
+interface ModelConfig {
+  maxContextTokens: number;  // 用户配置或系统默认 (200000 tokens)
+  maxTokens: number;   // 用户配置或系统默认(32000)
+}
+```
+
+### 3.2 配置合并策略
+
+#### 3.2.1 深度合并
+```typescript
+interface ConfigMerger {
+  merge(
+    systemConfig: ModulesConfig,
+    userConfig: UserConfig
+  ): MergedConfig;
+}
+```
+
+#### 3.2.2 优先级规则
+1. 用户配置 > 系统默认配置
+2. 具体配置 > 通用配置
+3. 运行时配置 > 文件配置
+
+### 3.3 虚拟路由配置生成
+
+#### 3.3.1 路由目标池表
+```typescript
+interface RouteTargetPool {
+  [routeName: string]: RouteTarget[];
+}
+
+// 用途: 路由器快速查找目标
+{
+  "default": [
+    {
+      "providerId": "openai",
+      "modelId": "gpt-4",
+      "keyId": "sk-your-openai-key-here",
+      "actualKey": "sk-your-openai-key-here",
+      "inputProtocol": "openai",
+      "outputProtocol": "openai"
+    }
+  ]
+}
+```
+
+#### 3.3.2 流水线配置表
+```typescript
+interface PipelineConfigs {
+  [providerModelKey: string]: PipelineConfig;
+}
+
+// 用途: 流水线执行详细配置
+{
+  "openai.gpt-4.sk-your-openai-key-here": {
+    "provider": {
+      "type": "openai",
+      "baseURL": "https://api.openai.com/v1"
+    },
+    "model": {
+      "maxContextTokens": 128000,
+      "maxTokens": 32000
+    },
+    "keyConfig": {
+      "keyId": "sk-your-openai-key-here",
+      "actualKey": "sk-your-openai-key-here"
+    },
+    "protocols": {
+      "input": "openai",
+      "output": "openai"
+    }
+  }
+}
+```
+
+## 4. 模块适配
+
+### 4.1 虚拟路由模块
+
+#### 4.1.1 配置接口
+```typescript
+interface VirtualRouterConfig {
+  routeTargets: RouteTargetPool;
+  pipelineConfigs: PipelineConfigs;
+  inputProtocol: "openai" | "anthropic";
+  outputProtocol: "openai" | "anthropic";
+  timeout: number;
+}
+```
+
+#### 4.1.2 初始化流程
+```typescript
+class VirtualRouterModule {
+  async initialize(config: VirtualRouterConfig): Promise<void> {
+    // 1. 加载路由目标池
+    this.routeTargetPool = config.routeTargets;
+
+    // 2. 初始化流水线配置
+    this.pipelineConfigs = config.pipelineConfigs;
+
+    // 3. 设置协议转换
+    this.protocolManager.setProtocols(
+      config.inputProtocol,
+      config.outputProtocol
+    );
+  }
+}
+```
+
+### 4.2 配置管理模块
+
+#### 4.2.1 配置文件管理
+```typescript
+class ConfigManagerModule {
+  async loadVirtualRouterArtifacts(): Promise<VirtualRouterArtifacts> {
+    const { userConfig } = await loadRouteCodexConfig();
+    return bootstrapVirtualRouterConfig(userConfig.virtualrouter ?? userConfig);
+  }
+}
+```
+
+## 5. 密钥管理
+
+### 5.1 AuthFile机制
+
+#### 5.1.1 密钥文件位置
+```
+~/.routecodex/auth/
+├── openai-main
+├── openai-backup
+└── anthropic-main
+```
+
+#### 5.1.2 密钥文件格式
+```bash
+# ~/.routecodex/auth/openai-main
+sk-your-actual-openai-key-here
+
+# ~/.routecodex/auth/anthropic-main
+sk-ant-your-actual-anthropic-key-here
+```
+
+### 5.2 密钥安全
+
+#### 5.2.1 文件权限
+```bash
+chmod 600 ~/.routecodex/auth/*
+```
+
+#### 5.2.2 密钥缓存
+```typescript
+interface KeyCache {
+  get(keyId: string): string | null;
+  set(keyId: string, value: string): void;
+  clear(): void;
+}
+```
+
+## 6. 协议支持
+
+### 6.1 输入协议
+
+#### 6.1.1 OpenAI协议
+- 格式: OpenAI Chat Completions API
+- 版本: v1
+- 内容类型: application/json
+
+#### 6.1.2 Anthropic协议
+- 格式: Anthropic Messages API
+- 版本: v1
+- 内容类型: application/json
+
+### 6.2 输出协议
+
+#### 6.2.1 协议转换
+```typescript
+interface ProtocolConverter {
+  convertOpenAItoAnthropic(request: OpenAIRequest): AnthropicRequest;
+  convertAnthropicToOpenAI(request: AnthropicRequest): OpenAIRequest;
+}
+```
+
+## 7. 负载均衡和容错
+
+### 7.1 路由策略
+
+#### 7.1.1 轮询策略
+```typescript
+interface RoundRobinStrategy {
+  getNextTarget(routeName: string): RouteTarget;
+}
+```
+
+#### 7.1.2 负载均衡
+```typescript
+interface LoadBalancer {
+  selectTarget(targets: RouteTarget[]): RouteTarget;
+  updateMetrics(targetId: string, success: boolean): void;
+}
+```
+
+### 7.2 错误处理
+
+#### 7.2.1 密钥失效处理
+```typescript
+interface KeyFailureHandler {
+  handleKeyFailure(keyId: string): void;
+  isKeyBlacklisted(keyId: string): boolean;
+}
+```
+
+#### 7.2.2 目标切换
+```typescript
+interface TargetSwitcher {
+  switchTarget(currentTarget: RouteTarget): RouteTarget;
+  getAvailableTargets(routeName: string): RouteTarget[];
+}
+```
+
+## 8. 实施计划
+
+### Phase 1: 配置解析器
+1. **UserConfigParser** - 解析用户配置
+2. **AuthFileResolver** - 处理AuthFile
+3. **RouteTargetParser** - 解析路由字符串
+
+### Phase 2: 配置合并器
+1. **ConfigMerger** - 合并系统配置和用户配置
+2. **MergedConfigGenerator** - 生成合并后配置文件
+3. **ConfigFileManager** - 管理配置文件
+
+### Phase 3: 虚拟路由模块
+1. **VirtualRouterModule** - 重构虚拟路由模块
+2. **RouteTargetPool** - 路由目标池管理
+3. **PipelineConfigManager** - 流水线配置管理
+
+### Phase 4: 协议和密钥管理
+1. **ProtocolManager** - 协议转换管理
+2. **KeyManager** - 密钥管理和缓存
+3. **LoadBalancer** - 负载均衡实现
+
+### Phase 5: 测试和优化
+1. **配置解析测试** - 验证配置正确性
+2. **路由功能测试** - 验证路由逻辑
+3. **性能优化** - 优化配置加载和路由性能
+
+## 9. 配置示例
+
+### 9.1 基础配置
+```json
+{
+  "virtualrouter": {
+    "providers": {
+      "openai": {
+        "apiKey": ["sk-your-key"],
+        "models": {
+          "gpt-4": {}
+        }
+      }
+    },
+    "routing": {
+      "default": ["openai.gpt-4.sk-your-key"]
+    }
+  }
+}
+```
+
+### 9.2 多供应商配置
+```json
+{
+  "virtualrouter": {
+    "providers": {
+      "openai": {
+        "apiKey": ["sk-openai-key"],
+        "models": {
+          "gpt-4": {}
+        }
+      },
+      "anthropic": {
+        "apiKey": ["sk-ant-key"],
+        "models": {
+          "claude-3-sonnet": {}
+        }
+      }
+    },
+    "routing": {
+      "default": [
+        "openai.gpt-4.sk-openai-key",
+        "anthropic.claude-3-sonnet.sk-ant-key"
+      ]
+    }
+  }
+}
+```
+
+### 9.3 协议转换配置
+```json
+{
+  "virtualrouter": {
+    "inputProtocol": "anthropic",
+    "outputProtocol": "openai",
+    "providers": {
+      "anthropic": {
+        "apiKey": ["sk-ant-key"],
+        "models": {
+          "claude-3-sonnet": {}
+        }
+      }
+    },
+    "routing": {
+      "default": ["anthropic.claude-3-sonnet.sk-ant-key"]
+    }
+  }
+}
+```

package/docs/GCLI2API_PARITY_GAPS.md

@@ -0,0 +1,98 @@
+# gcli2api 对齐缺口（RouteCodex / llmswitch-core）
+
+日期：2026-01-22
+
+本文用于把 `gcli2api`（Python）里已验证过的“兼容/风控”经验点，和 RouteCodex V2 的单一路径架构做一次对齐盘点：
+
+`HTTP server → llmswitch-core Hub Pipeline → Provider V2 → upstream AI`
+
+目标是：不在 Host/Provider 做语义修复、不绕过 Hub Pipeline，缺口优先落到 `llmswitch-core` 的 conversion/compat 层，或通过 `ProviderQuotaView`/健康度机制落到路由层。
+
+---
+
+## 1) gcli2api 最新关键行为（与本仓库相关）
+
+### 1.1 thoughtSignature 的“往返保留”
+
+`gcli2api` 在把 Gemini/Antigravity 的 `functionCall` 变成 OpenAI 工具调用时，会把 `thoughtSignature` 编码进 `tool_call_id`（分隔符 `__thought__`），随后在 OpenAI→Gemini 的方向再解码出来：
+
+- 目的：有些客户端（尤其是工具链/SDK）会丢弃 OpenAI tool_call 上的“非标准字段”（例如 `thought_signature` 或 `extra_content`），导致二次回传时无法恢复签名，从而触发上游校验失败。
+- 策略：有签名则编码到 ID；没有签名则仍能正常工作（回落到 dummy/skip 签名）。
+
+### 1.2 thinking 块签名校验与清理
+
+`gcli2api` 对历史消息里的 thinking 块做：
+
+- `MIN_SIGNATURE_LENGTH = 10`
+- 无效签名：有内容则降级为 text；空内容则丢弃
+- 额外：移除尾部未签名 thinking
+
+（本仓库已在 llmswitch-core 增加对应 validator，但“ID 编码保留”目前未实现。）
+
+### 1.3 Antigravity 429 处理（倾向于“先自救、再失败”）
+
+`gcli2api` 在 Antigravity 上游返回 429/禁用码时：
+
+- 记录错误与冷却
+- 在允许范围内重试，并在重试前预热下一凭证（不阻塞）
+- 达到最大重试或不可重试才把原始错误回给客户端
+
+此处的核心思想是：**不要把可恢复的短暂上游容量波动过早暴露给客户端**（尤其是 Codex CLI 对 429 处理会“直接中断”）。
+
+---
+
+## 2) 当前 RouteCodex/llmswitch-core 对应现状
+
+### 2.1 已覆盖点
+
+- `llmswitch-core/src/conversion/shared/thought-signature-validator.ts`：thinking 块签名校验/清理（与 gcli2api 的逻辑一致）
+- Gemini ↔ OpenAI 转换中已存在 `skip_thought_signature_validator` dummy 签名兜底（用于满足上游结构要求）
+
+### 2.2 仍缺口点（需要补齐/确认）
+
+#### A) thoughtSignature 的“tool_call_id 编码保留”缺失
+
+当前 llmswitch-core 在 OpenAI tool_call 上会尝试携带 `thought_signature` / `extra_content.google`，但**如果客户端丢弃这些字段**，下一轮回传后就只能回落到 dummy 签名；在部分上游/模式下可能会触发兼容问题。
+
+建议引入与 gcli2api 相同的 **可配置** 编码策略：
+
+- 编码：`<id>__thought__<signature>`
+- 解码：按分隔符 split 一次
+- 仅在“需要跨客户端往返保留签名”的协议/compat profile 下开启（默认关闭，避免污染普通 OpenAI 调用的 tool_call_id 语义）。
+
+#### B) Antigravity 429 容量耗尽的分类冷却
+
+日志里出现的 429 形态（`MODEL_CAPACITY_EXHAUSTED / No capacity available`）本质不是“quota 不足”，更像上游的临时容量波动。
+
+需要补的行为（建议在路由/健康度层处理，而不是 provider 语义层）：
+
+- 从 429 payload 中提取“容量耗尽”原因
+- 对整个 model 系列施加短冷却（例如 60 秒）
+- 冷却优先级 > quota（quota 视图显示有额度但仍报错时，应按错误退避走）
+
+#### C) “同一 key 先用到底，再换 key”的 Antigravity 轮询策略
+
+为了避免多 key 轮询导致被 server 侧识别为异常（或更容易触发拒绝），Antigravity 可采用：
+
+- 正常阶段：保持单 key 连续命中（直到出现错误/冷却）
+- 出错后：快速切到当前最健康 key
+- 恢复后：再按健康权重 RR 在健康 key 间均衡
+
+该策略必须保证 **alias 之间隔离（不误伤）**，并避免“永远命中同一个健康 key / 有 key 永远命不中”的极端情况（需要测试覆盖）。
+
+---
+
+## 3) 建议落地方式（不违反 V2 约束）
+
+1. **thoughtSignature ID 编码**：实现到 `llmswitch-core` conversion/shared（工具函数）并在 Gemini/Antigravity 相关 codec/mapper 中通过 profile 开关启用。
+2. **429 分类冷却**：落到 quota/health 视图（`ProviderQuotaView` 或路由健康度模块）里；Provider 只负责 transport 级错误透传与重试。
+3. **Antigravity key 选择策略**：落到路由池选择/健康权重 RR；不在 provider 层“语义路由”。
+
+---
+
+## 4) 待确认（实现前需要你审批的点）
+
+1. 是否默认对 `gemini-chat`/`antigravity` 开启 tool_call_id 的 thoughtSignature 编码？还是仅在 `ROUTECODEX_PRESERVE_THOUGHT_SIGNATURE=1` 时开启？
+2. 分隔符是否固定为 `__thought__`（与 gcli2api 对齐），还是做成 profile 可覆盖？
+3. 429 容量耗尽的“model 系列”归并规则：按 `providerKey::model` 归并，还是按 `providerId::modelFamily`（例如 `claude-sonnet-4-5-*`）归并？
+