@jsonstudio/rcc 0.89.1189 → 0.89.1348

package/docs/error-handling-v2.md

@@ -0,0 +1,92 @@
+# RouteCodex 错误中心机制（V2）
+
+本页记录当前 RouteCodex V2 的统一错误处理与熔断策略，覆盖 HTTP Server、Hub Pipeline、Provider 以及 Virtual Router 健康管理。所有细节以此为准，后续规则变动需同步更新此文档并在 `AGENTS.md` 追加引用。
+
+## 1. 统一流程
+
+1. **HTTP Server / CLI / Pipeline** 捕获异常后调用 `reportRouteError(payload)`，由 `RouteErrorHub` 统筹。
+2. `RouteErrorHub` 负责：
+   - 归一化错误元数据（requestId、endpoint、providerKey、model 等）。
+   - 根据构建模式自动裁剪堆栈：`release` 构建默认移除 stack（可通过 `ROUTECODEX_RELEASE_ERROR_VERBOSE=1` 恢复详细日志）。
+   - 将错误交给 `ErrorHandlerRegistry`，触发挂载的处理 Hook（含 429 回退调度、快照写入等）。
+   - 可选返回 HTTP 映射结果，确保客户端仅收到统一格式的错误体。
+3. Provider 侧在 `emitProviderError` 同时上报 `providerErrorCenter`（供 Virtual Router 熔断）与 `ErrorHandlingCenter`。
+4. `llmswitch-core` 的 Virtual Router 根据 `ProviderErrorEvent` 执行健康状态变更（回退、降级、拉黑）。
+
+## 2. 错误策略矩阵
+
+| 错误来源 | 状态 / 错误码 | Error Center 处理 | Virtual Router / ProviderHealth 策略 | 说明 |
+| --- | --- | --- | --- | --- |
+| Provider 客户端错误 | 4xx（排除 429） | 记录并透传，`affectsHealth=false` | 不触发健康计数 | 用户参数错误，可重试但不熔断 |
+| Provider 429 限流 | HTTP 429 / `retryable=true` | `rate_limit_error` Hook 启动回退：10s → 30s → 60s 共三次 | BaseProvider 内置 RateLimitTracker：**同一 providerKey（通常为 `provider.key` 或 `provider.key::model` 维度）连续 4 次 429** 会以 `affectsHealth=true` 向 Virtual Router 上报，触发熔断；任意一次成功即清零；不区分 route/routePool | 回退期间可切换同模型 pipeline，必要时返回 429 给客户端 |
+| Provider 5xx / 不可恢复 | HTTP ≥ 500、`affectsHealth=true` | 立即触发 `emitProviderError`，带 `fatal=true` | `tripProvider`，按 `fatalCooldownMs` 冷却 | 兼容层错误（stage=compat）同样视为 fatal |
+| Host/Server 内部错误 | pipeline/router 抛出的 500 | `RouteErrorHub` 归档并映射 HTTP 500；原始错误号写入 `code` 字段 | 同步 `providerErrorCenter`（若具备 provider 上下文） | 保证 release 输出简单错误号，dev 模式保留堆栈 |
+| CLI/工具链错误 | CLI command / debug harness | `reportCliError`（同 `RouteErrorHub`） | 仅记录，不影响路由池 | CLI 运行期错误不触发 provider 熔断 |
+
+> ⚠️ RateLimitTracker 只针对**相同 providerKey（provider.key / provider.key::model）**的连续 429 生效，中间出现成功或其他错误即会自动清零；冷却结束后会再次尝试，具体 TTL 由 `virtualrouter.health` 配置决定，且与使用的 route/routePool 无关。
+
+## 3. 日志与可观测性
+
+- **Release 输出最小化**：`error-center-payload` 会在 release 构建中移除 `stack`、`details.stack`，仅保留 message/code/requestId 等必要字段。若需排查，可在运行时设置 `ROUTECODEX_RELEASE_ERROR_VERBOSE=1`。
+- **OAuth 噪音削减**：所有 `[OAuth] ...` 信息级日志默认通过 `ROUTECODEX_OAUTH_DEBUG=1` 才会打印，错误（`console.error`) 仍保持输出。
+- **SSE 预览日志禁用**：Server 不再将 SSE chunk 内容写入 `stage-logger`，仅保留流开始/结束事件与统计，避免泄露响应片段。
+
+## 4. 回调挂载点
+
+- `ErrorHandlerRegistry` 默认挂载以下 Hook，可按需扩展：
+  - `rate_limit_error`：提供回退调度（切换 pipeline 或延迟重放）。
+  - `provider_error`：可注入通知/报警逻辑。
+  - 自定义 Hook 通过 `ErrorHandlerRegistry.registerErrorHandler` 挂载，RouteErrorHub 会自动转发。
+
+如需新增策略（例如特定 provider 的 4xx 也触发冷却），建议在 `docs/error-handling-v2.md` 补充矩阵，并在 `virtualrouter.health` 配置中增加自定义参数。
+
+## 5. 工具协议错误（ProviderProtocolError）
+
+ServerTool 与工具调用相关的后端错误统一通过 `ProviderProtocolError` 表达，类型定义位于
+`sharedmodule/llmswitch-core/src/conversion/shared/errors.ts`。
+
+- `ProviderProtocolErrorCode` 目前包含：
+  - `TOOL_PROTOCOL_ERROR`：工具调用/结果与 upstream 协议不一致，例如：
+    - provider 返回 `finishReason=UNEXPECTED_TOOL_CALL` 但响应中并无有效 tool calls；
+    - 工具结果缺少与请求中 tool call 对应的 `tool_outputs`。
+  - `SSE_DECODE_ERROR`：SSE → JSON 解码阶段发现非法事件序列或结构。
+  - `MALFORMED_RESPONSE`：provider 返回的响应在语义或结构上与声明的协议不符。
+  - `MALFORMED_REQUEST`：我们构造的请求违反了目标协议的约束（通常视为开发错误，需要修复代码）。
+
+统一约定：
+
+- **工具相关错误不得静默吞掉**：一旦判定为工具/协议层错误，必须：
+  - 在 provider 侧通过 `emitProviderError({ ..., error })` 上报 `providerErrorCenter`；
+  - 让错误沿着 `RouteErrorHub → ErrorHandlerRegistry` 流转，最终映射为 HTTP 错误返回客户端；
+  - 禁止“返回 200 + 空回答/占位内容”来掩盖错误。
+- 在 conversion/compat/codec 层，遇到协议违约时应抛出 `new ProviderProtocolError(message, { code, protocol, providerType, details })`，
+  由上游统一捕获与分类，而不是直接 `throw new Error(...)`。
+
+文档规则：若新增一种协议级错误（例如新的 SSE 解析场景或特定 provider 的工具约束），需要同时：
+
+1. 在 `errors.ts` 中补充新的 `ProviderProtocolErrorCode`（或复用已有 code）；
+2. 在此文档补充该错误 code 的含义与触发条件；
+3. 确保 provider runtime 捕获到该错误时仍通过 `emitProviderError` 上报，并映射为明确的 HTTP 错误响应。
+
+### 5.1 粗粒度错误类别（EXTERNAL / TOOL / INTERNAL）
+
+为方便统计与路由策略，`ProviderProtocolError` 还暴露一个粗粒度错误类别 `category`：
+
+- `EXTERNAL_ERROR`：外部载荷/协议错误
+  - 典型来源：SSE 解析失败（`SSE_DECODE_ERROR`）、上游返回的响应结构不合法（`MALFORMED_RESPONSE`）、
+    请求体与协议约束不符（`MALFORMED_REQUEST` 且原因在 provider / 用户输入侧）。
+- `TOOL_ERROR`：工具/ServerTool 协议错误
+  - 典型来源：工具调用/结果与 contract 不匹配（`TOOL_PROTOCOL_ERROR`）、工具 result 缺失对应 tool_call 等。
+- `INTERNAL_ERROR`：内部实现/配置错误
+  - 不直接用 `ProviderProtocolErrorCode` 区分，通常由 Host / Hub 在捕获异常时显式设置，用于标记
+    我们自己的实现/配置 bug（例如错误拼装 ChatEnvelope、必填字段缺失等）。
+
+约定：
+
+- `ProviderProtocolError.category` 默认会根据 `code` 自动推导：
+  - `TOOL_PROTOCOL_ERROR` → `TOOL_ERROR`；
+  - 其它（目前为 `SSE_DECODE_ERROR` / `MALFORMED_RESPONSE` / `MALFORMED_REQUEST`）→ 默认 `EXTERNAL_ERROR`。
+- 当上层明确知道错误是“内部实现错误”时，可以在构造时显式传入 `category: 'INTERNAL_ERROR'` 覆盖默认推导。
+- Host 在将错误映射为 `ProviderErrorEvent` 时，可将 `category` 映射到统一的 `event.code`（例如
+  `TOOL_ERROR` / `EXTERNAL_ERROR` / `INTERNAL_ERROR`），而把细粒度 `ProviderProtocolErrorCode` 放入
+  `event.details.reason`，从而同时兼顾统计与排障信息。

package/docs/exec-command-guard-policy.example.v1.json

@@ -0,0 +1,42 @@
+{
+  "version": 1,
+  "allowedProjectRoots": [
+    "~/Documents/github"
+  ],
+  "defaults": {
+    "denyOutsideProjectDestructive": true,
+    "gitSingleFileOnly": true,
+    "denyMassKill": true
+  },
+  "rules": [
+    {
+      "id": "deny-git-reset",
+      "type": "regex",
+      "pattern": "\\bgit\\s+reset\\b",
+      "flags": "i",
+      "reason": "git reset is not allowed"
+    },
+    {
+      "id": "deny-rm-rf-anywhere",
+      "type": "regex",
+      "pattern": "\\brm\\b[^\\n]*\\s(-rf|-fr)\\b",
+      "flags": "i",
+      "reason": "rm -rf is not allowed"
+    },
+    {
+      "id": "deny-find-delete-anywhere",
+      "type": "regex",
+      "pattern": "\\bfind\\b[^\\n]*\\s-delete(\\s|$)",
+      "flags": "i",
+      "reason": "find -delete is not allowed"
+    },
+    {
+      "id": "deny-loop-or-batch-delete",
+      "type": "regex",
+      "pattern": "\\b(xargs\\s+rm\\b|for\\s+[^;\\n]+;\\s*do\\s+rm\\b|while\\s+[^;\\n]+;\\s*do\\s+rm\\b)",
+      "flags": "i",
+      "reason": "Loop/batch deletion is not allowed"
+    }
+  ]
+}
+

package/docs/fixes/gemini-protocol-mapping.md

@@ -0,0 +1,57 @@
+# Gemini CLI Protocol Mapping Implementation
+
+## Overview
+Implemented proper protocol mapping for Gemini CLI responses to OpenAI-compatible format, ensuring tool calls, thinking/reasoning, and other metadata are preserved and correctly transformed.
+
+## Problem
+Previously, `GeminiSseNormalizer` would silently drop any SSE events that didn't match the expected format:
+- Tool calls (`functionCall`, `functionResponse`) were discarded
+- Thinking/reasoning content was lost
+- Code execution events were ignored
+- Stream would terminate prematurely (showing only 8 events instead of complete response)
+
+## Solution
+Rewrote `emitCandidateParts` method in `src/providers/core/runtime/gemini-cli-http-provider.ts` to map all Gemini part types to OpenAI/Chat-compatible semantics:
+
+### Mapping Rules
+
+| Gemini Part Type | Target Format | Description |
+|-----------------|---------------|-------------|
+| `text` | `type: 'text', content: string` | Regular text content → delta text |
+| `functionCall` | `type: 'tool_call', tool_call: {...}` | Tool invocation → OpenAI `tool_calls` |
+| `functionResponse` | `type: 'tool_response', tool_response: {...}` | Tool result → tool message |
+| `thought` | `type: 'reasoning', reasoning_content: string` | Thinking process → reasoning content (o1-style) |
+| `executableCode` | `type: 'code', code_content: {...}` | Code to execute → code_interpreter |
+| `codeExecutionResult` | `type: 'code_result', code_result: {...}` | Execution output → code output |
+| Unknown types | `type: 'metadata', metadata: {...}` | Preserve in metadata for outbound processing |
+
+### Implementation Details
+
+1. **Tool Calls**: Maps `functionCall` to OpenAI `tool_calls` format with generated call IDs
+2. **Reasoning**: Maps `thought` to `reasoning_content` for models with thinking capability
+3. **Code Execution**: Preserves code and execution results for code_interpreter tools
+4. **Metadata Preservation**: Unknown part types are wrapped in metadata for downstream processing
+
+### Outbound Processing
+The response outbound layer (in `llmswitch-core`) will:
+- Transform these typed events to target protocol format (OpenAI/Anthropic/etc)
+- Drop metadata fields not supported by target protocol
+- Preserve chat-compatible fields in final response
+
+## Benefits
+- ✅ Complete streaming responses (no premature termination)
+- ✅ Tool calls work correctly with Gemini providers
+- ✅ Thinking/reasoning preserved for Advanced Reasoning models
+- ✅ Extensible to future Gemini part types
+- ✅ No data loss - all events properly mapped or logged
+
+## Testing
+After restarting the server with v0.89.371+:
+- Tool call requests should show complete responses
+- Thinking models should stream reasoning content
+- No more "8 events then stop" issues
+- Logs will show any unmapped part types (for debugging)
+
+## Version
+- Fixed in: v0.89.371
+- Files modified: `src/providers/core/runtime/gemini-cli-http-provider.ts`

package/docs/fixes/oauth-portal-timing-fix.md

@@ -0,0 +1,202 @@
+# OAuth Portal 启动时序问题修复
+
+## 问题描述
+
+在项目启动时，当需要检查 token 有效性并打开浏览器进行 OAuth 认证时，浏览器无法访问 Portal 页面 (`/token-auth/demo`)，导致 404 错误。
+
+### 根本原因
+
+**时序问题**: OAuth 认证流程在服务器 HTTP 路由注册之前就已经开始尝试打开浏览器。
+
+具体流程：
+1. Provider 初始化阶段（在路由注册之前）
+   - `cli.ts` → `index.js` → 服务器初始化
+   - Provider 初始化时检查 token 有效性
+   - `ensureValidOAuthToken()` 被调用
+   - 此时尝试打开浏览器访问 Portal URL
+
+2. HTTP 路由注册阶段（在所有 provider 初始化完成之后）
+   - `RouteCodexHttpServer.initialize()` 中调用 `registerHttpRoutes()`
+   - 这时 `/token-auth/demo` 路由才被注册
+
+3. **问题**: 浏览器打开的时候，`/token-auth/demo` 路由还不存在！
+
+## 解决方案
+
+采用 **方案 1 + 方案 2 组合**:
+
+### 方案 1: 提前注册 OAuth Portal 路由
+
+将 `/token-auth/demo` 路由从 `registerHttpRoutes()` 中分离出来，并在服务器构造函数中提前注册。
+
+**修改的文件**:
+- `src/server/runtime/http-server/routes.ts`
+  - 新增 `registerOAuthPortalRoute()` 函数
+  - 从 `registerHttpRoutes()` 中移除 Portal 路由注册
+  
+- `src/server/runtime/http-server/index.ts`
+  - 在构造函数中调用 `registerDefaultMiddleware()` 和 `registerOAuthPortalRoute()`
+  - 确保在任何 provider 初始化之前，这些关键路由已经可用
+
+### 方案 2: 添加智能等待机制
+
+在 OAuth 流程中，当使用 Portal URL 时，先检查服务器是否已就绪，再打开浏览器。
+
+**修改的文件**:
+- `src/providers/core/config/oauth-flows.ts`
+  - 新增 `waitForPortalReady()` 方法
+  - 在 `activateWithBrowser()` 中，如果使用 Portal URL，先调用 `waitForPortalReady()`
+  - 最多等待 3 秒（15 次 × 200ms），通过 `/health` 端点检查服务器状态
+
+## 实现细节
+
+### 1. 分离 OAuth Portal 路由 (`routes.ts`)
+
+```typescript
+/**
+ * Register OAuth Portal route early to support token authentication flow
+ * This route must be available before provider initialization
+ */
+export function registerOAuthPortalRoute(app: Application): void {
+  app.get('/token-auth/demo', (req: Request, res: Response) => {
+    // ... Portal 页面实现 ...
+  });
+}
+```
+
+### 2. 提前注册路由 (`index.ts` 构造函数)
+
+```typescript
+constructor(config: ServerConfigV2) {
+  // ... 其他初始化 ...
+  
+  // Register critical routes early (before provider initialization)
+  // This ensures OAuth Portal is available when providers check token validity
+  registerDefaultMiddleware(this.app);
+  registerOAuthPortalRoute(this.app);
+  console.log('[RouteCodexHttpServer] OAuth Portal route registered (early initialization)');
+}
+```
+
+### 3. 智能等待机制 (`oauth-flows.ts`)
+
+```typescript
+protected async activateWithBrowser(...): Promise<void> {
+  // ... 生成 Portal URL ...
+  
+  if (options.openBrowser !== false) {
+    // If using Portal URL, ensure server is ready before opening browser
+    if (portalUrl) {
+      await this.waitForPortalReady(portalUrl);
+    }
+    
+    // ... 打开浏览器 ...
+  }
+}
+
+protected async waitForPortalReady(portalUrl: string): Promise<void> {
+  const healthUrl = `${baseUrl}/health`;
+  const maxAttempts = 15; // 最多尝试 15 次
+  const delayMs = 200;    // 每次等待 200ms，总计最多 3 秒
+  
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    // 尝试访问 /health 端点
+    if (healthCheckSuccess) {
+      console.log('[OAuth] Portal server is ready');
+      return;
+    }
+    await delay(delayMs);
+  }
+  
+  // 超时但继续执行（路由可能已经可用）
+  console.warn('[OAuth] Portal server health check timed out, continuing anyway...');
+}
+```
+
+## 效果
+
+修复后的启动流程：
+
+1. ✅ 服务器构造函数执行
+   - 注册默认中间件
+   - **提前注册 OAuth Portal 路由** ← 关键修复
+   
+2. ✅ Provider 初始化
+   - 检查 token 有效性
+   - 需要 OAuth 认证时：
+     - **检查服务器是否就绪** ← 关键修复
+     - 打开浏览器访问 Portal URL
+     - ✅ Portal 路由已存在，用户看到认证页面
+
+3. ✅ 其他 HTTP 路由注册
+   - 注册业务路由（/v1/chat/completions 等）
+
+4. ✅ 服务器监听端口
+
+## 测试方法
+
+### 手动测试
+
+1. 启动服务器:
+   ```bash
+   routecodex start
+   ```
+
+2. 观察日志中是否有:
+   ```
+   [RouteCodexHttpServer] OAuth Portal route registered (early initialization)
+   ```
+
+3. 如果有 token 需要认证，观察日志中是否有:
+   ```
+   [OAuth] Portal server is ready
+   Opening browser for authentication...
+   Portal URL: http://127.0.0.1:5555/token-auth/demo?...
+   ```
+
+4. 浏览器应该能正常打开 Portal 页面，显示 token 信息
+
+### 自动化测试
+
+创建测试脚本验证路由可用性（需要服务器先启动）:
+
+```bash
+# 测试 health 端点
+curl http://127.0.0.1:5555/health
+
+# 测试 Portal 端点
+curl "http://127.0.0.1:5555/token-auth/demo?provider=test&alias=test&oauthUrl=https://example.com&sessionId=test-123"
+```
+
+## 向后兼容性
+
+- ✅ 完全向后兼容
+- ✅ 不影响现有的 OAuth 流程
+- ✅ 不影响现有的路由注册
+- ✅ 只是提前了 Portal 路由的注册时机
+- ✅ 增加了可选的服务器就绪检查（失败也不影响后续流程）
+
+## 相关文件
+
+### 修改的文件
+1. `src/server/runtime/http-server/routes.ts` - 分离 OAuth Portal 路由
+2. `src/server/runtime/http-server/index.ts` - 提前注册路由
+3. `src/providers/core/config/oauth-flows.ts` - 添加就绪检查
+
+### 影响的功能
+- OAuth 认证流程
+- 多 token 支持
+- Token Portal 页面
+
+## 注意事项
+
+1. **中间件注册**: `registerDefaultMiddleware()` 也移到了构造函数中，避免重复注册
+2. **健康检查**: 使用 `/health` 端点作为服务器就绪的判断标准
+3. **超时处理**: 即使健康检查超时，也会继续打开浏览器（防止误报）
+4. **日志输出**: 添加了详细的日志，便于调试时序问题
+
+## 未来改进
+
+1. 可以考虑将所有"关键路由"（如 `/health`, `/config`）也提前注册
+2. 可以添加更精确的服务器启动状态跟踪
+3. 可以在 Portal 页面上显示"等待服务器就绪"的进度提示

package/docs/fixes/web-search-hop3-fix.md

@@ -0,0 +1,265 @@
+# Web Search Server-side Tool 第三跳修复
+
+**修复日期:** 2025-12-30  
+**影响范围:** `src/server/runtime/http-server/request-executor.ts`  
+**问题类型:** Server-side tool 第三跳请求构建错误
+
+---
+
+## 问题描述
+
+在实现 `web_search` server-side tool 时,第三跳(将搜索结果返回给主模型)的请求构建不正确,导致:
+- 消息历史混乱
+- 工具执行结果配对失败
+- 主模型无法正确处理搜索结果
+
+### 正确的三跳流程
+
+1. **第一跳 (主模型调用):**
+   - 用户请求 → Chat Process → 主模型
+   - 主模型识别需要 web_search → 返回 tool_call
+
+2. **第二跳 (执行 web_search):**
+   - 拦截 tool_call → 调用搜索后端(如 GLM)
+   - **单独执行**(不带原始请求上下文,走特殊通道)
+   - 返回搜索结果
+
+3. **第三跳 (返回主模型):**
+   - **在 Chat Process 层面**显式组装:
+     - 原始用户请求(来自 `__chat_process_raw`)
+     - + Assistant 的 tool_call 消息
+     - + Tool 执行结果
+   - 重新发送到虚拟路由器 → 主模型生成最终答案
+
+---
+
+## 根本原因
+
+### 1. **原始请求克隆位置错误**
+
+**错误实现:**
+```typescript
+// 在 Chat Process 循环中克隆 input.body
+const originalRequestSnapshot = this.cloneRequestPayload(input.body);
+```
+
+**问题:**
+- `input.body` 已经被预处理过(如注入系统提示词)
+- 不是"干净"的 chat 协议版本请求
+- 导致第三跳重复应用修改
+
+### 2. **缺少 Chat Process Raw 的概念**
+
+需要区分两个不同的"原始请求":
+- `__raw_request_body`: handler 入口的原始协议(chat/responses/messages)
+- **`__chat_process_raw`**: Chat Process 入口已转换为 **chat 协议** 的请求 ← **新增**
+
+### 3. **第三跳消息组装逻辑不完整**
+
+**错误实现:**
+```typescript
+// 直接使用 core 返回的 body,没有显式控制消息历史
+body: reenterOpts.body
+```
+
+**问题:**
+- 依赖 `llmswitch-core` 内部逻辑组装 messages
+- 如果 core 的实现有问题或使用了错误的 base,第三跳就会出错
+- 没有显式保证"原始消息 + tool_call + tool_result"的顺序
+
+---
+
+## 修复方案
+
+### 改动 1: 在 Chat Process 入口克隆 `__chat_process_raw`
+
+**位置:** `HubRequestExecutor.execute()` 循环开始处
+
+**实现:**
+```typescript
+// 在第一次迭代时克隆 chat 协议版本的请求
+if (attempt === 0 && !iterationMetadata.__chat_process_raw) {
+  const isChatEndpoint = 
+    input.entryEndpoint.includes('/v1/chat/completions') ||
+    input.entryEndpoint.includes('/v1/responses') ||
+    input.entryEndpoint.includes('/v1/messages');
+  
+  if (isChatEndpoint) {
+    // 克隆当前的 input.body (此时已经是 inbound 转换后的 chat 协议格式)
+    iterationMetadata.__chat_process_raw = this.cloneRequestPayload(input.body);
+    this.logStage('chat.process.raw.cloned', providerRequestId, {
+      endpoint: input.entryEndpoint,
+      hasMessages: Boolean(input.body && typeof input.body === 'object' && 'messages' in input.body)
+    });
+  }
+}
+
+// 获取原始请求快照 (优先使用 chat_process_raw)
+const originalRequestSnapshot = iterationMetadata.__chat_process_raw && 
+  typeof iterationMetadata.__chat_process_raw === 'object'
+    ? (iterationMetadata.__chat_process_raw as Record<string, unknown>)
+    : this.cloneRequestPayload(input.body);
+```
+
+**关键点:**
+- ✅ 只在 **第一次迭代** (`attempt === 0`) 克隆
+- ✅ 只对 chat 相关端点生效
+- ✅ 克隆的是 **inbound 转换后的 chat 协议格式**
+- ✅ 通过 `iterationMetadata` 传递,支持多轮循环
+
+### 改动 2: 第三跳显式组装消息历史 (仅 chat 协议)
+
+**位置:** `convertProviderResponseIfNeeded()` 内的 `reenterPipeline` 回调
+
+**实现:**
+```typescript
+const reenterPipeline = async (reenterOpts) => {
+  const targetEndpoint = reenterOpts.entryEndpoint || options.entryEndpoint || entry;
+  const isChatEndpoint = targetEndpoint.includes('/v1/chat/completions');
+  
+  let finalBody = reenterOpts.body;
+  
+  // Chat 协议的第三跳显式组装逻辑
+  if (isChatEndpoint) {
+    const chatProcessRaw = metadataBag?.__chat_process_raw;
+    
+    if (chatProcessRaw && typeof chatProcessRaw === 'object') {
+      const rawRequest = chatProcessRaw as Record<string, unknown>;
+      const incomingBody = reenterOpts.body;
+      
+      // 从 core 返回的 body 中提取 assistant 和 tool 消息
+      const incomingMessages = Array.isArray(incomingBody?.messages)
+        ? incomingBody.messages : [];
+      
+      const assistantMessages = incomingMessages.filter(
+        (msg: any) => msg && msg.role === 'assistant' && msg.tool_calls
+      );
+      const toolMessages = incomingMessages.filter(
+        (msg: any) => msg && msg.role === 'tool'
+      );
+      
+      const originalMessages = Array.isArray(rawRequest.messages)
+        ? rawRequest.messages : [];
+      
+      // 重新组装: 原始消息 + assistant tool_call + tool result
+      const reconstructedMessages = [
+        ...originalMessages,
+        ...assistantMessages,
+        ...toolMessages
+      ];
+      
+      // 构建第三跳的请求体(基于 chat_process_raw)
+      finalBody = {
+        ...rawRequest,  // 保留原始的 model 等字段
+        messages: reconstructedMessages
+      };
+      
+      this.logStage('chat.process.hop3.assembled', reenterOpts.requestId, {
+        originalMessageCount: originalMessages.length,
+        assistantMessageCount: assistantMessages.length,
+        toolMessageCount: toolMessages.length,
+        finalMessageCount: reconstructedMessages.length
+      });
+    }
+  }
+  
+  // 传递 __chat_process_raw 到下一跳,支持多轮 tool 调用
+  const nestedMetadata = {
+    ...metadataBag,
+    ...reenterOpts.metadata,
+    serverToolFollowup: true,
+    __chat_process_raw: metadataBag?.__chat_process_raw
+  };
+  
+  return await this.execute({
+    ...nestedInput,
+    body: finalBody  // 使用显式组装的 body
+  });
+};
+```
+
+**关键点:**
+- ✅ **仅对 `/v1/chat/completions` 生效**(其他协议走标准转换)
+- ✅ 基于 `__chat_process_raw` 重新组装完整消息历史
+- ✅ 明确提取 assistant tool_call 和 tool result
+- ✅ 保留原始请求的其他字段(如 `model`)
+- ✅ 传递 `__chat_process_raw` 到下一跳,支持多轮工具调用
+
+---
+
+## 新增日志
+
+### `chat.process.raw.cloned`
+- **触发时机:** Chat Process 第一次迭代,成功克隆 chat_process_raw
+- **用途:** 确认克隆时机和内容
+- **字段:**
+  - `endpoint`: 入口端点
+  - `hasMessages`: 是否包含 messages 字段
+
+### `chat.process.hop3.assembled`
+- **触发时机:** 第三跳成功组装消息历史
+- **用途:** 验证消息组装正确性
+- **字段:**
+  - `originalMessageCount`: 原始用户消息数量
+  - `assistantMessageCount`: assistant tool_call 消息数量
+  - `toolMessageCount`: tool result 消息数量
+  - `finalMessageCount`: 最终消息总数
+
+### `chat.process.hop3.fallback`
+- **触发时机:** 缺少 `__chat_process_raw`,降级使用 core 提供的 body
+- **用途:** 诊断异常情况
+- **字段:**
+  - `reason`: 降级原因(如 `missing_chat_process_raw`)
+
+---
+
+## 验证要点
+
+### 1. 检查日志顺序
+正常流程应该看到:
+```
+[chat.process.raw.cloned] endpoint=/v1/chat/completions hasMessages=true
+[chat.process.hop3.assembled] originalMessageCount=1 assistantMessageCount=1 toolMessageCount=1 finalMessageCount=3
+```
+
+### 2. 验证第三跳请求
+- messages[0]: 原始用户请求(role=user)
+- messages[1]: assistant tool_call(role=assistant, 包含 tool_calls)
+- messages[2]: tool result(role=tool, tool_call_id 匹配)
+
+### 3. 确认协议隔离
+- `/v1/chat/completions`: 走显式组装逻辑
+- `/v1/responses`, `/v1/messages`: 走标准 inbound/outbound 转换
+
+---
+
+## 影响范围
+
+### ✅ 修复的场景
+- `/v1/chat/completions` 端点的 `web_search` 工具调用
+- 多轮工具调用场景(连续的 tool_call)
+
+### ⚠️ 不受影响的场景
+- `/v1/responses` 端点(依赖 llmswitch-core 的标准转换)
+- `/v1/messages` (Anthropic) 端点(依赖标准转换)
+- 客户端侧工具调用(submit_tool_outputs)
+
+---
+
+## 后续优化建议
+
+1. **扩展到其他端点:**
+   - 考虑为 `/v1/responses` 实现类似的显式组装逻辑
+   - 需要适配 responses 协议的消息历史格式
+
+2. **增强错误处理:**
+   - 如果第三跳组装失败,记录详细的诊断信息
+   - 提供降级机制,避免整个请求失败
+
+3. **性能优化:**
+   - `__chat_process_raw` 的克隆可以惰性执行(只在检测到 tool_call 时克隆)
+   - 减少不必要的 JSON 序列化/反序列化
+
+4. **单元测试:**
+   - 添加第三跳消息组装的单元测试
+   - 覆盖边界情况(如空消息、多个 tool_call 等)