@jsonstudio/rcc 0.89.3 → 0.89.164

package/README.md

@@ -1,216 +1,251 @@
-# RouteCodex - 多提供商OpenAI代理服务器
+# RouteCodex – 多提供商 AI 代理
 
-[![npm version](https://badge.fury.io/js/routecodex.svg)](https://badge.fury.io/js/routecodex)
+[![npm version](https://badge.fury.io/js/%40jsonstudio%2Frcc.svg)](https://www.npmjs.com/package/@jsonstudio/rcc)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
 
-RouteCodex是一个功能强大的多提供商OpenAI代理服务器，基于配置驱动的V2架构，支持原生dry-run调试能力、动态路由分类、4层管道架构和实时监控。提供统一的API接口，无缝集成多个AI服务提供商。
-
-当前开发版本：`0.87.1`
-
-## LLM Switch（前后半段）总览
-
-- 前半段（Conversion）
-  - Chat：保持 OpenAI Chat 标准；删除 stream，统一非流
-  - Responses：instructions + input → Chat.messages（仅形状转换，不做工具治理/兜底）
-  - Anthropic：Claude → Chat（仅形状转换）
-  - SSE：默认不上游直通；需要时前半段合成为非流 JSON
-
-- 后半段（Chat Pipeline，唯一治理点）
-  - 请求：canonicalize + arguments 修复 + MCP 两步暴露
-  - Provider：仅 HTTP 转发与快照
-  - 响应：统一 Chat 形状，工具结果与 tool_call_id 配对
-  - Responses：从 Chat 反向映射 required_action/items（仅映射，不治理）
-
-文档与代码参考：
-- 核心实现与详细说明：`sharedmodule/llmswitch-core/`
-- 源码文档：`sharedmodule/llmswitch-core/README.md`
-
-### Hub Pipeline 架构（唯一入口）
-
-- **唯一入口**：HTTP handler 直接调用 `sharedmodule/llmswitch-core/dist/conversion/hub/pipeline/hub-pipeline`，本仓库不再维护自研 pipeline/blueprint。
-- **配置流**：`routecodex-config-loader` 读取用户配置，传给 `bootstrapVirtualRouterConfig`，由 llmswitch-core 输出 `VirtualRouterConfig + targetRuntime` 并注入 Hub Pipeline。
-- **节点链路（由 llmswitch-core 内部维护）**
-  - `SSE Input`：SSE ↔ JSON 转换、旁路透传。
-  - `Input Nodes`：解析 Chat / Responses / Messages 请求，生成 canonical `standardizedRequest`。
-  - `Chat Process`：唯一工具治理点，处理 tool_calls、MCP 规则、上下文压缩。
-  - `Virtual Router Process`：分类、熔断、挑选 provider，并覆写 `request.model`、写入 `target.runtimeKey`。
-  - `Output/SSE Nodes`：把 `processedRequest` 还原为目标协议，生成 usage、SSE 流和最终响应。
-- **Host 职责**：`RouteCodexHttpServer` 只负责 HTTP/SSE 封装与 Provider runtime 映射，工具治理与路由决策全部在 llmswitch-core 完成。
-
-### Reasoning / Tool 骨架
-
-- **入站统一拆分**：`sharedmodule/llmswitch-core/src/conversion/shared/reasoning-normalizer.ts` 会在 Chat/Responses/Anthropic/Gemini 入站阶段，把 `<think>/<reasoning>` 段落剥离到 `reasoning_content`，并同步处理 instructions/input/required_action。
-- **工具/理由写回**：`reasoning-tool-normalizer.ts` 与 `tool-call-utils.ts` 负责把 reasoning 文本中的工具片段转换为 `tool_calls`，处理 placeholder、capturedToolResults、metadata.extra-fields 等动作由 `bridge-actions.ts` 统一驱动。
-- **协议中性命名**：所有共享动作均使用 `messages.*`、`tools.*` 等协议无关名称（如 `messages.inject-system-instruction`、`tools.ensure-response-placeholders`）。兼容层不得新增带协议前缀的 helper。
-- **兼容层职责切换**：GLM/iFlow 等 compat hook 仅处理 usage、finish_reason、schema 轻量标准化，Reasoning 拆分/清理禁止下沉到 compat；若 Provider 需特殊字段，必须通过 JSON config 描述。
-
-## 快照排查指南（命令行）
-
-- 快速查看某个请求 RID 在各阶段的顶层键/消息概况/可疑字段：
-  - 运行：`npm run snapshot:inspect -- --rid <RID> [--endpoint openai-responses|openai-chat|anthropic-messages]`
-  - 输出：
-    - http-request / llmswitch.request.post / compatibility.request.post / provider.request.pre 的顶层键
-    - messages 统计（条数、角色覆盖、是否存在 user）
-    - 是否出现 data/metadata/stream 等可疑顶层键
-    - 简要差异（哪个阶段新增了可疑键）
-
-## 🔄 V2 架构特性
-
-本仓库已完成面向生产的 V2 重构并默认启用，基于9大核心架构原则：
-
-### 🏗️ V2 核心组件
-
-- **Compatibility V2（配置驱动）**
-  - 位置：`src/providers/compat/glm/*`（模块化 + Hook 系统）
-  - 职责：仅做 Provider 特定的最小字段标准化；reasoning/tool 清理统一由 conversion 骨架完成
-  - 特性：配置驱动字段映射、GLM 专用最小清理与 1210/1214 错误兼容
-  - 工具治理：统一在 llmswitch-core v2 处理；兼容层不进行工具语义修复/文本收割
-
-- **Provider V2（统一OpenAI标准）**
-  - 位置：`src/providers/*`
-  - 能力：统一 HTTP 发送、认证管理、请求/响应快照
-  - 支持服务：OpenAI、GLM、Qwen、iFlow、LM Studio
-  - 策略：Fail Fast 原则，无隐藏兜底机制
-
-- **LLM Switch Core（工具处理中心）**
-  - 位置：`sharedmodule/llmswitch-core/`
-  - 职责：工具调用统一处理（唯一入口）、文本意图收割、系统工具指引
-  - 特性：三端一致性（Chat/Responses/Messages）；arguments 三段式修复（JSON→JSON5→安全修复→"{}"）；必要时从文本块收割重建 tool_calls；（可选）SSE 参数聚合
-
-## 📐 模块职责边界（Do / Don't）
-
-### llmswitch-core（唯一工具入口）
-- Do
-  - 统一工具规范：`canonicalizeChatResponseTools()` 保证 `content=null`、`finish_reason='tool_calls'`
-  - arguments 统一修复：`jsonish.repairArgumentsToString()`（JSON/JSON5 容错 + 安全修复）
-  - 文本收割：在“可疑+存在文本工具块”时，用 `harvestTools()` 重建标准 `tool_calls`
-  - （可选）SSE 聚合：吞掉参数增量，在工具完成时一次性下发完整 arguments（默认关闭）
-- Don't
-  - 进行 Provider 特定修复/HTTP 通信/配置管理
-  - 将同样逻辑复制到兼容层或 Provider 层
-
-### Compatibility（最小兼容层）
-- Do
-  - Provider 字段标准化（usage/finish_reason 等）、配置驱动映射，遵守 shared 骨架输出
-  - 1210/1214 最小兼容（GLM）
-  - 请求侧最小黑名单（例如 GLM 删除 `tools[].function.strict`；无 tools 删除 `tool_choice`）
-  - 响应侧最小黑名单（仅非流式）：默认仅删 `usage.prompt_tokens_details.cached_tokens`
-    - 配置：`src/providers/compat/<provider>/config/response-blacklist.json`
-    - 关键字段保护：status/output/output_text/required_action/choices[].message.content/tool_calls/finish_reason
-- Don't
-  - 工具语义修复、reasoning 拆分或文本收割（统一由 llmswitch-core 骨架处理）
-
-### Provider V2（HTTP 通信）
-- Do
-  - 统一 HTTP 发送、认证管理、快照记录
-  - 配置驱动（baseUrl/timeout/retry/headers）
-- Don't
-  - 工具语义修复/参数归一（如改写 `shell.command`）
-  - 业务逻辑或格式转换
-  - 默认不上游真流式（Responses 直通）
-    - 开关（默认关闭）：`ROUTECODEX_RESPONSES_UPSTREAM_SSE=1` 或 `RCC_RESPONSES_UPSTREAM_SSE=1`
-
-### Server Endpoints（HTTP 协议层）
-- Do
-  - SSE 预心跳/错误帧、HTTP 协议处理、委托到管道
-- Don't
-  - 工具处理/格式转换/业务逻辑
-
-### 🎯 9大核心架构原则
-
-1. **统一工具处理** - 所有工具调用通过 llmswitch-core 统一入口
-2. **最小兼容层** - Compatibility层仅处理provider特定字段
-3. **统一工具引导** - 系统工具指引集中管理
-4. **快速死亡** - Fail Fast，无隐藏fallback
-5. **暴露问题** - 结构化日志，完整错误上下文
-6. **清晰解决** - 单一处理路径，确定性行为
-7. **功能分离** - 模块职责单一，边界清晰
-8. **配置驱动** - 无硬编码，外部化配置管理
-9. **模块化** - 文件大小控制，功能导向拆分
-
-### 🔧 构建与调试
-
-**构建顺序（重要）**：
-```bash
-# 1. 先编译共享模块
-npm --prefix sharedmodule/llmswitch-core run build
+RouteCodex 是 JSON Studio 推出的多提供商 AI 代理，提供统一的 OpenAI / Anthropic / Responses / Gemini 入口，自动完成协议转换、工具治理、速率控制与快照审计。项目包含两个分发形态：
 
-# 2. 再编译根包
-npm run build
+- **Release CLI (`@jsonstudio/rcc`)**：给终端用户的 npm 包，自带 `rcc` 命令。
+- **Dev Worktree (`routecodex`)**：本仓库源码，开发者可修改、构建并贡献。
+
+本文档面向 release 使用者与贡献者，覆盖架构、安装、配置与常见操作。
+
+---
+
+## 架构总览
 
-# 3. 安装或发布
-npm pack && npm i -g ./routecodex-*.tgz
+### 单一执行路径
+
+```
+HTTP Server → llmswitch-core Hub Pipeline → Provider V2 Runtime → 上游 AI API
 ```
 
-**调试与快照**：
-- 环境变量：`ROUTECODEX_HOOKS_VERBOSITY=verbose`
-- 快照路径：`~/.routecodex/codex-samples/{openai-chat|openai-responses|anthropic-messages}`
-- 完整链路：raw-request → pre-llmswitch → post-llmswitch → compat-pre → provider-request → provider-response → compat-post
-- 回放样本：`npm run replay:codex-sample -- --sample <sample.json>`（详见 `docs/codex-samples-replay.md`）可将 codex-samples 请求重新送入本地 RouteCodex，并生成对应的 JSON/SSE 日志。
+- **Hub Pipeline（llmswitch-core）**：唯一的工具治理点，完成协议归一、tool call 修复、路由决策、SSE 处理。
+- **Provider V2**：纯运输层，只负责认证、重试和兼容性 hook；不解析或修改用户语义。
+- **Compatibility**：按 upstream 协议最小字段映射，确保 usage / finish_reason / required_action 一致。
+- **Host (RouteCodexHttpServer)**：只做 HTTP/SSE 封装、配置加载与 provider 生命周期管理。
+
+### 模块职责矩阵
+
+| 模块 | 代码位置 | 职责 | 禁止行为 |
+| --- | --- | --- | --- |
+| HTTP Server | `src/server/runtime/http-server` | Express 路由、SSE 包装、调用 Hub Pipeline | 工具决策、路由逻辑、配置拼装 |
+| Hub Pipeline | `sharedmodule/llmswitch-core` | 请求标准化、tool_calls 统一处理、虚拟路由 | 进行 HTTP 请求、处理认证 |
+| Provider V2 | `src/providers` | 请求签名、HTTP 发送、快照输出 | 解析/修复工具调用、修改配置 |
+| Compatibility | `src/providers/compat/*` | 上下游字段映射、最小清理 | 工具解码、兜底 try/catch |
+
+更多细节请参考 `docs/ARCHITECTURE.md` 与 `docs/CONFIG_ARCHITECTURE.md`。
 
-## 🔀 选择静态/动态流水线（V1/V2）
+---
+
+## 安装与升级
+
+### 环境要求
+- Node.js 20.x（20.11 及以上，<26）
+- npm 9.x 或 10.x
+- macOS / Linux：bash 或 zsh
+- Windows：PowerShell 5.1+ 或 Windows Terminal
 
-- 开关：`ROUTECODEX_PIPELINE_MODE`
-- 取值：`dynamic`（动态流水线，V2，默认）或 `static`（静态流水线，V1）
-- 兼容：历史 `ROUTECODEX_USE_V2` 已弃用，请迁移至 `ROUTECODEX_PIPELINE_MODE`
+### Release CLI（推荐）
 
-示例：
+> CLI 名称：`rcc`，包名：`@jsonstudio/rcc`
 
+**macOS / Linux**
 ```bash
-# 动态流水线（V2，默认）
-ROUTECODEX_PIPELINE_MODE=dynamic routecodex
+npm install -g @jsonstudio/rcc
+rcc --version
+```
 
-# 静态流水线（V1）
-ROUTECODEX_PIPELINE_MODE=static routecodex
+**Windows（PowerShell）**
+```powershell
+npm install -g @jsonstudio/rcc
+rcc --version
 ```
 
-## 🖥️ CLI：`rcc code` 参数透传到 Claude
+安装成功后，`rcc --version` 会显示形如 `0.89.xxx (release)` 的版本信息；可通过 `npm update -g @jsonstudio/rcc` 升级，`npm uninstall -g @jsonstudio/rcc` 卸载。
+
+### Dev CLI（本仓库）
+开发者仍可直接在仓库根目录执行 `npm run install:global`，该脚本会构建源码并把 `routecodex` 命令安装到全局 `$PATH`，供本地调试使用。
+
+---
+
+## 默认目录结构
+
+| 系统 | 主配置 | Provider 配置 | 日志 / 快照 |
+| --- | --- | --- | --- |
+| macOS / Linux | `~/.routecodex/config.json`（或 `ROUTECODEX_CONFIG_PATH` 指定路径） | `~/.routecodex/provider/<name>/config.v1.json` | `~/.routecodex/logs`、`~/.routecodex/codex-samples/*` |
+| Windows | `%USERPROFILE%\.routecodex\config.json` | `%USERPROFILE%\.routecodex\provider\<name>\config.v1.json` | `%USERPROFILE%\.routecodex\logs` 等 |
+
+RouteCodex 会按以下优先级查找配置：
+
+1. CLI 参数 `--config <path>`
+2. 环境变量 `ROUTECODEX_CONFIG_PATH`
+3. 默认路径（见上表）
 
-`rcc code` 会把紧跟在子命令 `code` 之后的参数默认传递给 Claude（Claude Code 可执行文件）。这使你可以无缝使用 Claude 自身的命令行参数，同时由 RouteCodex 代理请求到本地服务。
+---
+
+## 无密钥配置样本
 
-- 透传规则
-  - `rcc code` 自身会消费的选项（不会透传）：
-    - `-p/--port`、`-h/--host`、`-c/--config`、`--claude-path`、`--model`、`--profile`、`--ensure-server`
-  - 除上述选项外，`code` 后的其它参数会按原顺序透传给 Claude。
-  - 若使用分隔符 `--`，则 `--` 之后的所有参数将不做解析、原样透传。
+仓库附带了一份不含真实密钥的示例：`samples/configs/openai-chat-sample.json`。复制到本地后，只需提供环境变量即可启动。
 
-- 环境与代理
-  - `rcc code` 会为子进程设置：`ANTHROPIC_BASE_URL/ANTHROPIC_API_URL=http://<host>:<port>` 与 `ANTHROPIC_API_KEY=rcc-proxy-key`，并清理 `ANTHROPIC_AUTH_TOKEN/ANTHROPIC_TOKEN`，确保经由 RouteCodex 代理。
-  - 可用 `--ensure-server` 在启动 Claude 前探测并尝试启动本地 RouteCodex 服务。
+```json
+{
+  "httpserver": { "host": "127.0.0.1", "port": 5555 },
+  "virtualrouter": {
+    "providers": {
+      "demo.glm": {
+        "providerType": "openai",
+        "protocol": "openai-chat",
+        "baseUrl": "https://api.example.com/v1",
+        "auth": { "type": "apikey", "env": "GLM_API_KEY" },
+        "models": {
+          "glm-4.6": {
+            "supportsStreaming": true,
+            "profiles": ["glm-default"]
+          }
+        }
+      }
+    },
+    "routing": {
+      "default": ["demo.glm.glm-4.6"]
+    }
+  }
+}
+```
 
-- 使用示例
-  ```bash
-  # 直接传递 Claude 自身参数（无分隔符）
-  rcc code --model claude-3-5 -- --project ~/my/repo --editor vscode
+使用步骤：
 
-  # 显式使用分隔符 -- 强制原样传参（推荐在复杂参数场景）
-  rcc code -p 5506 -- --project ~/src/foo --some-claude-flag value
+1. **复制样本**
+   ```bash
+   mkdir -p ~/.routecodex
+   cp samples/configs/openai-chat-sample.json ~/.routecodex/config.json
+   ```
+2. **提供密钥（示例为环境变量）**
+   - macOS / Linux：`export GLM_API_KEY="sk-your-key"`
+   - Windows：`setx GLM_API_KEY "sk-your-key"`
+3. **启动**
+   ```bash
+   rcc start --config ~/.routecodex/config.json
+   ```
+4. **验证**
+   - 健康检查：`curl http://127.0.0.1:5555/health`
+   - Chat API：`curl http://127.0.0.1:5555/v1/chat/completions ...`
 
-  # 指定 Claude 可执行文件路径
-  rcc code --claude-path /usr/local/bin/claude -- --project ~/repo
-  ```
+> 样本仅用于演示。请把 `baseUrl` / `routing` 更新为真实 provider，再通过环境变量、`authfile-*` 或 Secret 管理工具提供密钥。
 
-> 提示：若透传参数与 `rcc code` 自身选项名冲突，建议使用 `--` 分隔，避免被 CLI 解析。
+### 自定义路由关键字
 
-## 🚀 核心特性
+虚拟路由器内置了一组默认关键字（如 `思考/think` → `thinking` 路由，`vision/image` → `vision` 路由）。若希望在不覆盖默认词表的前提下追加命中词，可以在用户配置中加入 `virtualrouter.classifier.keywordInjections`：
 
-### 🏗️ 双向4层管道架构
-- **LLM Switch Workflow层**: 动态路由分类、协议转换、llmswitch-core工具处理统一入口
-- **Compatibility层**: Provider特定字段标准化、reasoning_content处理、双向修剪转换
+```json
+{
+  "virtualrouter": {
+    "classifier": {
+      "keywordInjections": {
+        "thinking": ["慢慢分析", "stepwise"],
+        "vision": ["截图如下"],
+        "background": ["context dump please"]
+      }
+    }
+  }
+}
+```
+
+- 字段名对应路由类别（`thinking` / `background` / `vision` / `coding`），只需写新增词条即可，默认常量会自动保留。
+- 若同一词出现在多个路由，将沿用 `ROUTE_PRIORITY`（`longcontext → thinking → vision → ...`）顺序做匹配。
+- 更新配置文件后重启服务即可生效。
+
+---
+
+## 快速使用
+
+1. **准备配置**：如上所述放置 `config.json` 或使用 `--config` 指定文件。
+2. **启动 release server**
+   ```bash
+   rcc start --config ~/.routecodex/config.json
+   ```
+   CLI 会输出健康检查地址、配置文件路径和当前版本。
+3. **调用 API**
+   - OpenAI Chat：`POST /v1/chat/completions`
+   - OpenAI Responses：`POST /v1/responses`
+   - Anthropic：`POST /v1/messages`
+4. **开发者模式**
+   - `rcc code ...`：启动 Claude Code 并把所有请求代理到本地 RouteCodex。
+   - `rcc start --exclusive`：独占端口，自动终止旧实例。
+
+---
+
+## 配置与密钥管理
+
+- **AuthFile 引用**：在配置中使用 `authfile-<name>`，RouteCodex 会读取 `~/.routecodex/auth/<name>`。适用于多账号切换。
+- **环境变量**：将 `auth.type` 设为 `apikey` 且 `env` 字段指定变量名，server 会在启动时解析。
+- **provider profiles**：`src/providers/profile/` 定义了各 provider 允许的协议、Auth 方式及兼容 profile，可在配置中通过 `profiles` 字段引用。
+
+更多细节见 `docs/CONFIG_ARCHITECTURE.md`。
+
+---
+
+## 开发者工作流
+
+1. **克隆仓库并安装依赖**
+   ```bash
+   git clone https://github.com/jsonstudio/routecodex.git
+   cd routecodex
+   npm install
+   ```
+2. **构建 sharedmodule（必要）**
+   ```bash
+   npm --prefix sharedmodule/llmswitch-core run build
+   ```
+3. **编译与验证**
+   ```bash
+   npm run build:dev              # 生成 dist 并执行工具链验证
+   npm run install:global         # 安装本地版 routecodex CLI
+   ```
+4. **与 release 区分**
+   - Release：使用 npm 安装 `@jsonstudio/rcc`
+   - Dev：仓库内 `routecodex` CLI，支持 `npm run start:bg` 等脚本
+
+---
+
+## 故障排查
+
+| 症状 | 检查点 |
+| --- | --- |
+| `config:core:run` 提示缺失 | Release CLI 默认跳过动态 pipeline 生成；自定义流程可设置 `config:core:run` 脚本。 |
+| SSE 变为 JSON | 检查入口 `stream` 字段与客户端 `Accept` 头；RouteCodex 会根据 inbound 请求保持一致。 |
+| usage 始终 100% | 确保配置启用了对应 provider 的 `supportsStreaming`，并检查 `~/.routecodex/codex-samples/*` 快照确认 usage 字段已写入。 |
+| Release install 验证失败 | 查看 `/tmp/routecodex-release-verify-*.log`；脚本位于 `scripts/install-verify.mjs`，可单独执行 `node scripts/install-verify.mjs --launcher cli --cli-binary rcc ...`。 |
+
+---
+
+## 参考文档
+
+- `docs/ARCHITECTURE.md` – 全量架构细节与数据流
+- `docs/CONFIG_ARCHITECTURE.md` – 配置解析、authfile、虚拟路由
+- `docs/pipeline-routing-report.md` – Hub Pipeline 节点详解
+- `docs/codex-samples-replay.md` – 快照与回放说明
+
+如需提交问题或贡献代码，请查看 `CONTRIBUTING.md`（若不存在可参考 Issues 模板）并遵守 `AGENTS.md` 中的 V2 工作约定。
 - **Provider层**: 统一HTTP通信、认证管理、连接池优化、双向请求响应处理
 - **External AI Service层**: 多提供商AI模型支持、性能监控、双向数据流
 
 ### 🔧 智能路由系统
 支持7种动态路由类别，自动选择最优处理流水线：
 - `default`: 标准请求路由
-- `longcontext`: 长文本处理请求
+- `longcontext`: 长文本处理请求（tiktoken 统计超过 180k token 时切向 ≥256k provider，例如 fai/c4m）
 - `thinking`: 复杂推理请求
 - `background`: 后台处理请求
 - `websearch`: 网络搜索请求
 - `vision`: 图像处理请求
 - `coding`: 代码生成请求
 
+**强制路由/模型标签（请求文本内插入 `<**...**>`）**
+- `<**thinking|coding|tools|vision|websearch|longcontext|background**>`：强制命中对应路由，忽略其它关键词。
+- `<**provider.model**>`：强制命中某个 provider 模型（如 `<**c4m.gpt-5.1-codex**>`，当 provider 存在并健康时直接命中）。
+- 标签在路由阶段被剥离，真实请求不会把控制标签透传给上游。
+
 ### 🛠️ Provider V2架构
 完全重构的Provider系统，提供：
 - 统一的OpenAI标准接口（支持5大提供商）
@@ -509,12 +544,16 @@ curl -X POST http://localhost:5506/v1/chat/completions \
       "longcontext": {
         "targets": [
           {
-            "providerId": "anthropic-provider",
-            "modelId": "claude-3-5-sonnet-20241022"
+            "providerId": "fai-provider",
+            "modelId": "gpt-5.1-codex"
+          },
+          {
+            "providerId": "c4m-provider",
+            "modelId": "gpt-5.1-codex"
           }
         ],
         "triggers": [
-          {"type": "token_count", "threshold": 100000},
+          {"type": "token_count", "threshold": 180000},
           {"type": "content_type", "value": "document"}
         ]
       },
@@ -969,6 +1008,12 @@ npm run test:coverage
 
 # 运行性能测试
 npm run test:performance
+
+# 黄金样本 + Mock 回归（覆盖 chat/responses/anthropic）
+npm run test:golden
+
+# 将 ~/.routecodex/golden_samples/new/** 同步到仓库内的 samples/ci-goldens/**
+npm run sync:ci-goldens
 ```
 
 #### Provider 专项测试
@@ -982,6 +1027,22 @@ npm run test:performance
 
 > 建议在跑专项测试前设置 `RCC_TEST_FAKE_OPENAI_COMPAT=1` 等 mock 环境变量，以避免真实兼容模块加载 import.meta。
 
+#### 黄金样本库与 Mock 测试
+
+`samples/ci-goldens/<entry>/<provider>/` 随仓库提供一套最小聊天请求，确保在完全离线的 CI
+环境也能复现工具字段、system 块与 streaming 行为。`npm run test:golden` 会：
+
+1. 执行 `scripts/tools/capture-provider-goldens.mjs --custom-only --update-golden`，把
+   `~/.routecodex/golden_samples/new/**` 或 `samples/ci-goldens/**` 中的最新请求复制到
+   `~/.routecodex/golden_samples/provider_golden_samples/`；
+2. 执行 `scripts/mock-provider/run-regressions.mjs`，通过 mock provider 跑完整的
+   chat/responses/anthropic 回归。
+
+若本地存在 `~/.routecodex/codex-samples`，脚本会提示额外运行
+`node scripts/mock-provider/capture-from-configs.mjs` 把真实 provider 录制转成 mock
+样本。若需要把最新的 `~/.routecodex/golden_samples/new/**` 同步进仓库，执行
+`npm run sync:ci-goldens`；更多细节参见 `docs/golden-ci-library.md`。
+
 ### 代码规范
 
 - **TypeScript**: 严格模式，完整类型定义

package/config/modules.json

@@ -27,17 +27,7 @@
         "classificationConfig": {
           "confidenceThreshold": 60,
           "enableSmartRouting": true,
-          "longContextThresholdTokens": 100000,
-          "thinkingKeywords": [
-            "思考",
-            "深度思考",
-            "逐步思考",
-            "一步一步思考",
-            "先思考再回答",
-            "推理",
-            "逻辑推理",
-            "分析"
-          ],
+          "longContextThresholdTokens": 180000,
           "backgroundKeywords": [
             "background",
             "上下文"

package/dist/build-info.js

@@ -1,6 +1,6 @@
 export const buildInfo = {
     mode: 'release',
-    version: '0.89.3',
-    buildTime: '2025-12-12T04:09:13.943Z'
+    version: '0.89.164',
+    buildTime: '2025-12-17T10:31:24.219Z'
 };
 //# sourceMappingURL=build-info.js.map

package/dist/build-info.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-info.js","sourceRoot":"","sources":["../src/build-info.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,SAAS,GAAc;IAClC,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,QAAQ;IACjB,SAAS,EAAE,0BAA0B;CACtC,CAAC"}
+{"version":3,"file":"build-info.js","sourceRoot":"","sources":["../src/build-info.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,SAAS,GAAc;IAClC,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,UAAU;IACnB,SAAS,EAAE,0BAA0B;CACtC,CAAC"}

package/dist/client/gemini-cli/gemini-cli-protocol-client.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Gemini CLI Protocol Client
+ *
+ * 处理 Gemini CLI API 的协议层逻辑
+ * - 请求体构建
+ * - Endpoint 解析
+ * - Header 最终化（添加 OAuth Bearer token）
+ */
+import type { HttpProtocolClient, ProtocolRequestPayload } from '../http-protocol-client.js';
+export declare class GeminiCLIProtocolClient implements HttpProtocolClient<ProtocolRequestPayload> {
+    buildRequestBody(request: ProtocolRequestPayload): Record<string, unknown>;
+    resolveEndpoint(request: ProtocolRequestPayload, defaultEndpoint: string): string;
+    finalizeHeaders(headers: Record<string, string>, _request: ProtocolRequestPayload): Record<string, string>;
+    private extractPayload;
+}
+export default GeminiCLIProtocolClient;

package/dist/client/gemini-cli/gemini-cli-protocol-client.js

@@ -0,0 +1,56 @@
+/**
+ * Gemini CLI Protocol Client
+ *
+ * 处理 Gemini CLI API 的协议层逻辑
+ * - 请求体构建
+ * - Endpoint 解析
+ * - Header 最终化（添加 OAuth Bearer token）
+ */
+function hasDataEnvelope(payload) {
+    return typeof payload === 'object' && payload !== null && 'data' in payload;
+}
+export class GeminiCLIProtocolClient {
+    buildRequestBody(request) {
+        const payload = this.extractPayload(request);
+        // 保持原生 Gemini CLI 格式
+        const body = { ...payload };
+        // 移除不必要的字段
+        delete body.stream;
+        return body;
+    }
+    resolveEndpoint(request, defaultEndpoint) {
+        const payload = this.extractPayload(request);
+        const action = payload.action || 'generateContent';
+        // 根据 action 返回对应的 endpoint
+        // generateContent, streamGenerateContent, countTokens
+        return `/v1internal:${action}`;
+    }
+    finalizeHeaders(headers, _request) {
+        const normalized = { ...headers };
+        // 确保包含必需的 headers
+        if (!normalized['User-Agent']) {
+            normalized['User-Agent'] = 'google-api-nodejs-client/9.15.1';
+        }
+        if (!normalized['X-Goog-Api-Client']) {
+            normalized['X-Goog-Api-Client'] = 'gl-node/22.17.0';
+        }
+        if (!normalized['Client-Metadata']) {
+            normalized['Client-Metadata'] = 'ideType=IDE_UNSPECIFIED,platform=PLATFORM_UNSPECIFIED,pluginType=GEMINI';
+        }
+        if (!normalized['Accept']) {
+            normalized['Accept'] = 'application/json';
+        }
+        return normalized;
+    }
+    extractPayload(request) {
+        if (hasDataEnvelope(request)) {
+            const envelopeData = request.data;
+            if (envelopeData && typeof envelopeData === 'object') {
+                return envelopeData;
+            }
+        }
+        return { ...request };
+    }
+}
+export default GeminiCLIProtocolClient;
+//# sourceMappingURL=gemini-cli-protocol-client.js.map

package/dist/client/gemini-cli/gemini-cli-protocol-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-cli-protocol-client.js","sourceRoot":"","sources":["../../../src/client/gemini-cli/gemini-cli-protocol-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH,SAAS,eAAe,CAAC,OAA+B;IACtD,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,MAAM,IAAI,OAAO,CAAC;AAC9E,CAAC;AAED,MAAM,OAAO,uBAAuB;IAClC,gBAAgB,CAAC,OAA+B;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAE7C,qBAAqB;QACrB,MAAM,IAAI,GAAqB,EAAE,GAAG,OAAO,EAAE,CAAC;QAE9C,WAAW;QACX,OAAQ,IAAY,CAAC,MAAM,CAAC;QAE5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,eAAe,CAAC,OAA+B,EAAE,eAAuB;QACtE,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAI,OAAO,CAAC,MAAiB,IAAI,iBAAiB,CAAC;QAE/D,2BAA2B;QAC3B,sDAAsD;QACtD,OAAO,eAAe,MAAM,EAAE,CAAC;IACjC,CAAC;IAED,eAAe,CACb,OAA+B,EAC/B,QAAgC;QAEhC,MAAM,UAAU,GAA2B,EAAE,GAAG,OAAO,EAAE,CAAC;QAE1D,kBAAkB;QAClB,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC9B,UAAU,CAAC,YAAY,CAAC,GAAG,iCAAiC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACrC,UAAU,CAAC,mBAAmB,CAAC,GAAG,iBAAiB,CAAC;QACtD,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACnC,UAAU,CAAC,iBAAiB,CAAC,GAAG,yEAAyE,CAAC;QAC5G,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,UAAU,CAAC,QAAQ,CAAC,GAAG,kBAAkB,CAAC;QAC5C,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAEO,cAAc,CAAC,OAA+B;QACpD,IAAI,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7B,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;YAClC,IAAI,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;gBACrD,OAAO,YAAgC,CAAC;YAC1C,CAAC;QACH,CAAC;QACD,OAAO,EAAE,GAAI,OAAmC,EAAsB,CAAC;IACzE,CAAC;CACF;AAED,eAAe,uBAAuB,CAAC"}

package/dist/client/openai/chat-protocol-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"chat-protocol-client.js","sourceRoot":"","sources":["../../../src/client/openai/chat-protocol-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chat-protocol-client.js","sourceRoot":"","sources":["../../../src/client/openai/chat-protocol-client.ts"],"names":[],"mappings":"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"}

package/dist/config/modules.json

@@ -27,17 +27,7 @@
         "classificationConfig": {
           "confidenceThreshold": 60,
           "enableSmartRouting": true,
-          "longContextThresholdTokens": 100000,
-          "thinkingKeywords": [
-            "思考",
-            "深度思考",
-            "逐步思考",
-            "一步一步思考",
-            "先思考再回答",
-            "推理",
-            "逻辑推理",
-            "分析"
-          ],
+          "longContextThresholdTokens": 180000,
           "backgroundKeywords": [
             "background",
             "上下文"

package/dist/core/provider-health-manager.d.ts

@@ -0,0 +1,17 @@
+export type ProviderBlockInfo = {
+    reason: string;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+};
+export declare class ProviderHealthManager {
+    private readonly blocked;
+    private readonly rateLimitHits;
+    block(providerKey: string | undefined, reason: string, metadata?: Record<string, unknown>): void;
+    isBlocked(providerKey: string | undefined): boolean;
+    getBlockInfo(providerKey: string | undefined): ProviderBlockInfo | undefined;
+    clear(providerKey: string | undefined): void;
+    recordRateLimitHit(providerKey: string | undefined): number;
+    resetRateLimit(providerKey: string | undefined): void;
+}
+export declare function setProviderHealthManager(manager: ProviderHealthManager): void;
+export declare function getProviderHealthManager(): ProviderHealthManager;