@jsonstudio/rcc 0.90.876 → 0.90.1270

package/docs/design/servertool-unified-skeleton.md

@@ -0,0 +1,202 @@
+# Servertool 统一骨架设计（收敛草案）
+
+## 目标
+- 把 servertool 收敛成**单一骨架**：统一请求注入、统一响应收割、统一续轮决策。
+- internal servertool 绝不泄露到客户端。
+- malformed tool_call 绝不在 finalize 阶段伪装成 `stop + 空回复`；应保留错误闭环，让客户端或上层显式报错。
+
+## 现状问题
+1. **followup 特判旁路**
+   - `serverToolFollowup=true` 目前会让部分响应编排直接 bypass。
+   - 但 internal RCC/tool_call 往往在 governance 之后才结构化出来，导致“注入统一、收割失效”。
+2. **双命运系统**
+   - 一部分走 `reenterPipeline`。
+   - 一部分走 `clientInjectOnly`（tmux/client 注入）。
+3. **pendingInjection 侧路**
+   - mixed tools 通过 session 文件把 servertool 结果滞后注入到下一轮请求。
+4. **finalize 错误吞并**
+   - malformed tool_call 被清洗后可能降成 `stop + placeholder`，破坏错误闭环。
+
+## 统一骨架（目标态）
+
+### 阶段 0：请求入口归一
+- 入口：`HTTP server -> llmswitch-core Hub Pipeline -> Provider`
+- 责任：
+  - 采集 `capturedChatRequest / sessionId / conversationId / runtime metadata`
+  - 注入 request-side servertool state（如 stopless/clock/session scopes）
+- 约束：
+  - 不在这里做响应级推断
+  - 不引入 provider-specific followup 旁路
+
+### 阶段 1：响应预处理（provider -> canonical）
+- 责任：
+  - decode / format parse / semantic map
+  - 保留 provider 原始 text/tool intent
+- 约束：
+  - 不消费 internal tool_call
+  - 不替客户端“修”错误命令
+
+### 阶段 2：tool governance（唯一结构化入口）
+- 责任：
+  - 把文本 RCC/XML wrapper 收敛成 canonical `tool_calls`
+  - 修复**外层形状**，不猜正文语义
+- 约束：
+  - 只修 wrapper/container
+  - 允许 malformed arguments 原样保留，交给客户端校验报错
+
+### 阶段 3：servertool orchestration（唯一消费入口）
+- 责任：
+  - 统一消费 internal servertool：
+    - `reasoning.stop`
+    - `review`
+    - `clock`
+    - `continue_execution`
+    - `stop_message_auto`
+  - 统一决定：
+    - `reenter`
+    - `clientInjectOnly`
+    - `mixed tools pending injection`
+- 约束：
+  - followup 响应也必须进入该阶段
+  - **必须支持 post-governance pass**
+  - internal tool 一旦执行，必须在 finalize 前被 strip
+
+### 阶段 4：finalize（只做形状收口，不做语义吞并）
+- 责任：
+  - shape normalize
+  - reasoning policy
+  - strip executed internal tool calls
+- 禁止：
+  - 禁止把 malformed tool_call 洗成 `stop + empty assistant`
+  - 禁止把 internal tool 泄露到 client `required_action/output`
+
+### 阶段 5：client remap / outbound
+- 责任：
+  - 转成 openai-responses / chat / anthropic 客户端协议
+  - 对 client tools 做最终 allowlist + args validation
+- 结果：
+  - malformed client tool arguments -> 显式 `CLIENT_TOOL_ARGS_INVALID`
+  - unknown tool -> 显式 `CLIENT_TOOL_NAME_MISMATCH`
+
+## 统一骨架的硬规则
+1. **tool governance 是唯一结构化入口**
+   - 不在多个阶段重复 harvest。
+2. **servertool orchestration 是唯一 internal tool 消费入口**
+   - 不允许 followup bypass 后再期待 finalize 兜底。
+3. **finalize 不负责“掩盖错误”**
+   - finalize 只能收口形状，不能伪造成 stop。
+4. **clientInjectOnly 是命运分支，不是响应编排分支**
+   - 允许存在，但必须在统一 orchestration 阶段产生命运决定。
+5. **pendingInjection 仅作为 mixed tools 过渡机制**
+   - 长期目标是缩减；短期必须加强 session/conversation 绑定与 stale 清理。
+
+## 收敛实施顺序
+### P0
+1. followup 响应补 post-governance servertool pass
+2. finalize 禁止把坏 tool_call 清洗成空回复
+3. executed internal tool 在 finalize 前统一 strip
+
+### P1
+4. 把 `reasoning_stop_guard / stop_message_auto` 从 dedicated skeleton 逐步压回统一 orchestration 骨架
+5. 明确 `clientInjectOnly` 只是一种 execution outcome
+
+### P2
+6. 审计并缩减 `pendingInjection`
+7. 把 servertool flow graph 文档化，形成单一真源
+
+## 当前决策
+- malformed tool_call 的正确处理：**保留到客户端错误闭环**，而不是服务端伪装成成功 stop。
+- servertool followup 的正确处理：**按正常响应统一编排**，而不是走 followup 特判旁路。
+
+## 2026-04-16 审计实锤（本轮新增）
+
+### 已确认的结构问题
+1. **request 标准化双实现**
+   - `src/server/runtime/http-server/executor-response.ts`
+   - `src/server/runtime/http-server/executor/provider-response-converter.ts`
+   - 两边都各自维护：
+     - `backfillAdapterContextSessionIdentifiersFromOriginalRequest(...)`
+     - `seedReasoningStopStateFromCapturedRequest(...)`
+   - 这会导致 session / conversation / stopless 进入骨架不是单点真源。
+
+2. **response wrapper 双实现**
+   - 两边都各自手拼 `__sse_responses` wrapper
+   - 各自挂 `finish_reason`
+   - 之前都**没有**把 `reasoning.stop finalized` 状态变成统一 wrapper 元数据
+
+3. **stopless 对 streamed wrapper 漏校验**
+   - `RequestExecutor.detectStoplessTerminationWithoutFinalization(...)`
+   - 之前一旦看到 `__sse_responses` 就直接跳过
+   - 导致 `finish_reason=stop` + 无 finalized marker 的 wrapper 仍可 200 透传
+
+4. **engine 仍是超大聚合体**
+   - `sharedmodule/llmswitch-core/src/servertool/engine.ts` ≈ 2317 行
+   - `sharedmodule/llmswitch-core/src/servertool/server-side-tools.ts` ≈ 1037 行
+   - `sharedmodule/llmswitch-core/src/servertool/handlers/reasoning-stop-guard.ts` ≈ 705 行
+   - `sharedmodule/llmswitch-core/src/servertool/handlers/stop-message-auto.ts` ≈ 665 行
+   - 当前并非“薄骨架”，而是 trigger / execution outcome / followup dispatch / finalize / loop guard 混在一起。
+
+5. **历史残留仍在 servertool 真路径**
+   - `server-side-tools.ts.bak~bak6`
+   - `handlers/memory/cache-writer.ts.bak`
+   - 说明该区域长期热修，但没有完成真正骨架化。
+
+### 本轮已先落的第一刀
+1. 新增 host 壳层共享 helper：
+   - `src/server/runtime/http-server/executor/servertool-request-normalizer.ts`
+   - `src/server/runtime/http-server/executor/servertool-response-normalizer.ts`
+
+2. 已把 request 侧共享逻辑先抽单点：
+   - session / conversation backfill
+   - stopless seed
+
+3. 已把 SSE wrapper 共享逻辑先抽单点：
+   - `buildServerToolSseWrapperBody(...)`
+   - 统一挂：
+     - `__sse_responses`
+     - `__routecodex_finish_reason`
+     - `__routecodex_reasoning_stop_finalized`
+
+4. stopless streamed wrapper 漏检已修：
+   - 若 wrapper `finish_reason=stop`
+   - 且缺 finalized flag
+   - `RequestExecutor` 现在统一抛：
+     - `STOPLESS_FINALIZATION_MISSING`
+
+### 下一刀切点（按顺序）
+1. **Host 壳层继续单点化**
+   - 收掉 `executor-response.ts` / `provider-response-converter.ts` 里剩余的 request/followup metadata 组装重复逻辑
+
+2. **engine 按四段骨架拆分**
+   - `trigger detect`
+   - `execution outcome decide`
+   - `followup dispatch`
+   - `finalize + strip`
+
+3. **清历史侧路**
+   - pending injection 过渡逻辑
+   - followup bypass / post-governance 不一致点
+   - `.bak` 残留文件
+
+## 2026-04-16 第二刀（host followup dispatch/error helper 落地）
+
+### 已收口
+1. **nested followup dispatch 单点化**
+   - 新增 `src/server/runtime/http-server/executor/servertool-followup-dispatch.ts`
+   - 统一承接：
+     - followup nested metadata 组装
+     - `clientInjectOnly` 预处理
+     - nested request execute
+   - `executor-response.ts` 与 `provider-response-converter.ts` 不再各自手拼一套 `reenterPipeline` / `clientInjectDispatch`。
+
+2. **followup 错误标记单点化**
+   - 新增 `src/server/runtime/http-server/executor/servertool-followup-error.ts`
+   - 统一承接：
+     - `SERVERTOOL_*` → `provider.followup` stage marker
+     - followup reason compact/logging
+     - 缺省 HTTP status（当前 converter 路径默认补 502）
+
+### 这一步的意义
+- followup 进入 host 壳层后，不再有两份“长得差不多但不完全一样”的 nested dispatch。
+- followup 错误不再由多个 callsite 各自猜测和打印，开始收敛到单点 helper。
+- 这是把 **followup 当普通请求重进统一链路** 的继续落地，而不是再给 followup 开一条特判旁路。

package/docs/design/websearch-servertool-orchestration.md

@@ -0,0 +1,190 @@
+# Web Search ServerTool Orchestration 设计文档
+
+## 索引概要
+- L1-L30 `background`: 背景、目标、原则
+- L31-L60 `current-state`: 当前架构现状
+- L61-L100 `gap-analysis`: 未实现/缺失部分
+- L101-L150 `change-plan`: 最小改动计划
+- L151-L180 `file-list`: 文件改动清单
+- L181-L200 `execution-order`: 执行顺序
+- L201-L220 `verification`: 验证点
+
+---
+
+## 背景
+
+RouteCodex 需要支持 web search 作为标准工具能力，让所有 text-guidance 模式的 provider（qwen、deepseek、tabglm、ali-coding-plan）都能通过 heredoc 格式调用 web search。
+
+**目标**：
+1. 用户请求默认带 `websearch` 工具（和 `exec_command`/`apply_patch` 一样）
+2. 模型通过 heredoc 格式调用 `websearch` 工具
+3. Hub 收割工具调用 → 按 provider 适配原生 web search API
+4. 直路由 web_search 时剥离其他工具
+
+**原则**：
+1. 日常工具列表都需要注入 — `websearch` 作为标准工具
+2. text guidance 基于标准工具列表动态创建 — 不写 dead code
+3. search followup 按 provider 适配原生 API — qwen/deepseek/tabglm 各自有实现
+4. 直路由 web_search 时剥离其他工具 — forceWebSearch=true 移除 tools
+
+---
+
+## 当前架构现状
+
+### 已实现
+
+| 层 | 文件 | 功能 |
+|---|---|---|
+| 搜索意图检测 | `chat_web_search_intent.rs` | 中英文关键词检测 |
+| servertool 编排计划 | `chat_servertool_orchestration.rs` | `resolve_chat_web_search_plan()` 判断是否注入 |
+| forceWebSearch 元数据 | `hub_pipeline_target_utils.rs` | target 带 `forceWebSearch: true` 时注入 metadata |
+| qwen search 模式 | `qwen provider runtime` | `shouldUseSearchMode()` → `chatType: 'search'` |
+| 直路由 bypass | `should_bypass_servertool_web_search()` | direct engine 时跳过 servertool 注入 |
+| 响应工具名归一化 | `hub_resp_outbound_client_semantics.rs:1857` | `websearch`/`web-search` → `web_search` |
+| heredoc 收割 | `hub_reasoning_tool_normalizer.rs:1723` | `<<RCC_TOOL_CALLS_JSON` 正则收割所有工具调用 |
+| text guidance 动态生成 | `shared_tool_text_guidance.rs` | `build_tool_text_instruction(tools)` 从 tools 数组生成引导 |
+
+### 未实现/缺失
+
+| 层 | 问题 | 影响 |
+|---|---|---|
+| **websearch 工具定义注入** | `chat_servertool_orchestration.rs` 没有注入 `websearch` 工具的 `append_tool_if_missing` | 模型不知道有 websearch 工具可用 |
+| **search followup 路径** | 收割到 `websearch` 调用后，没有触发 provider 原生 search API 的 followup | 搜索结果无法正确回注 |
+| **直路由剥离工具** | `forceWebSearch=true` 只注入 flag，没有移除 tools | 进入 web_search 路由后仍带所有工具 |
+| **provider 适配层** | qwen/deepseek/tabglm 没有 `handleWebSearchFollowup()` | 无法调用原生 search API |
+
+---
+
+## 改动计划
+
+### Step 1: 在 servertool orchestration 中注入 `websearch` 工具定义
+
+**文件**: `chat_servertool_orchestration.rs`
+
+**改动**: 新增 `build_websearch_operations()` 函数
+
+```rust
+fn build_websearch_operations(server_tool_followup: bool) -> Value {
+    if server_tool_followup {
+        return Value::Array(Vec::new());
+    }
+    let parameters = json!({
+        "type": "object",
+        "properties": {
+            "query": { "type": "string", "description": "Web search query" }
+        },
+        "required": ["query"],
+        "additionalProperties": false
+    });
+    let websearch_tool = json!({
+        "type": "function",
+        "function": {
+            "name": "websearch",
+            "description": "Search the web for current information",
+            "parameters": parameters,
+            "strict": true
+        }
+    });
+    json!([
+        { "op": "append_tool_if_missing", "toolName": "websearch", "tool": websearch_tool }
+    ])
+}
+```
+
+并在 `resolve_chat_web_search_plan` 或 bundle 输出中合并 operations。
+
+---
+
+### Step 2: text guidance 自动包含 websearch
+
+**文件**: `shared_tool_text_guidance.rs` — **无需改动**
+
+`build_tool_text_instruction(tools)` 已是动态生成，Step 1 注入后自动包含。
+
+---
+
+### Step 3: search followup 按 provider 适配
+
+**架构流程**:
+```
+模型 heredoc 输出 websearch 调用
+  → hub_reasoning_tool_normalizer 收割
+  → resp_process_stage1_tool_governance 识别为 servertool
+  → provider-response-converter 触发 serverToolFollowup
+  → 按 providerKey 路由到原生 search handler
+  → 搜索结果作为工具执行结果回注
+  → followup 请求带所有工具继续对话
+```
+
+**改动点**:
+
+| Provider | 文件 | 改动 |
+|---|---|---|
+| **qwen** | `qwen provider runtime` | 新增 `handleWebSearchFollowup(query)` |
+| **deepseek-web** | `deepseek-http-provider.ts` (待确认) | 新增 `handleWebSearchFollowup(query)` → deepseek 原生 search |
+| **tabglm** | TBD | 待适配 |
+| **ali-coding-plan** | TBD | 待适配 |
+
+---
+
+### Step 4: 直路由 web_search 时剥离其他工具
+
+**文件**: `hub_pipeline_target_utils.rs` 或 `req_process_stage2_route_select.rs`
+
+**改动**: `forceWebSearch=true` 时移除 `tools` 和 `tool_choice`
+
+```rust
+if force_web_search {
+    if let Some(body_obj) = request.as_object_mut() {
+        body_obj.remove("tools");
+        body_obj.remove("tool_choice");
+    }
+}
+```
+
+---
+
+## 文件改动清单
+
+### Rust (llmswitch-core)
+
+| 文件 | 改动类型 | 说明 |
+|---|---|---|
+| `chat_servertool_orchestration.rs` | 新增函数 | `build_websearch_operations()` |
+| `hub_pipeline_target_utils.rs` | 新增逻辑 | `forceWebSearch` 时移除 tools |
+| `req_process_stage2_route_select.rs` | 可能改动 | 确认 forceWebSearch 处理位置 |
+
+### TypeScript
+
+| 文件 | 改动类型 | 说明 |
+|---|---|---|
+| `qwen provider runtime` | 新增函数 | `handleWebSearchFollowup()` |
+| `deepseek-http-provider.ts` | 新增函数 | `handleWebSearchFollowup()` |
+| `provider-response-converter.ts` | 可能改动 | 确认 serverToolFollowup 路径 |
+
+---
+
+## 执行顺序
+
+1. **Rust Step 1** — 注入 `websearch` 工具定义 → `cargo build --release` → 复制 `.node`
+2. **Rust Step 4** — 直路由剥离工具 → 同上
+3. **TS Step 3** — qwen/deepseek provider 适配 → `npm run build:dev`
+4. **重启 5520** — 验证 heredoc 引导 → 工具调用 → followup → 原生 search
+
+---
+
+## 验证点
+
+1. **引导注入** — 请求默认带 `websearch` 工具，text guidance 中有 `websearch` schema
+2. **heredoc 调用** — 模型输出 `<<RCC_TOOL_CALLS_JSON\n{"tool_calls":[{"name":"websearch","input":{"query":"..."}}]}\nRCC_TOOL_CALLS_JSON`
+3. **收割识别** — `hub_reasoning_tool_normalizer` 正确收割，`finish_reason=tool_calls`
+4. **followup 触发** — `serverToolFollowup=true`，按 provider 调用原生 search
+5. **直路由剥离** — `forceWebSearch=true` 时请求不带 tools
+
+---
+
+## 待确认
+
+1. deepseek 原生 web search API 调用方式（是否和 qwen 类似有 `chatType` 参数）
+2. `serverToolFollowup` 的触发点在 `resp_process_stage1_tool_governance` 还是 `provider-response-converter`
+3. tabglm / ali-coding-plan 的原生 search 能力是否存在

package/docs/error-handling-v2.md

@@ -1,8 +1,117 @@
-# RouteCodex 错误中心机制（V2）
-
-本页记录当前 RouteCodex V2 的统一错误处理与熔断策略，覆盖 HTTP Server、Hub Pipeline、Provider 以及 Virtual Router 健康管理。所有细节以此为准，后续规则变动需同步更新此文档并在 `AGENTS.md` 追加引用。
-
-## 1. 统一流程
+# RouteCodex 错误策略收口（Router Policy SSOT）
+
+> 2026-04-15 决策更新  
+> **不再保留独立 `error-handling center` / event engine 作为中心。**  
+> 当前实现里，独立 center 仅承担 `emit/subscribe/normalize`，不掌握 retry/reroute/backoff/fail/cooldown policy，继续保留只会制造第二中心。  
+> **目标真源改为：`Virtual Router policy`。** 所有 provider/runtime/send/convert/followup 执行期错误，统一进入 Router policy 判定；`RequestExecutor` 与 `servertool engine` 只消费 Router 输出的 decision / policy state。
+
+本页记录 RouteCodex 错误处理的**目标收口架构**与实现边界。历史 V2 机制中凡是“独立错误中心 / event bus”语义，均以本页的新决策为准，后续实现需同步删除旧中间层。
+
+## 0a. 2026-04-16 当前已验证收口状态
+
+- **provider 执行期错误主链已切到 `Virtual Router policy`**
+  - Host `emitProviderError` 不再双上报 `RouteErrorHub`
+  - 当前主路径：`provider/runtime/send/convert/followup error -> provider-error-reporter -> reportProviderErrorToRouterPolicy -> Virtual Router policy`
+- **HubPipeline 已不再把 legacy center 当主订阅中心**
+  - TS `HubPipeline` bridge wrapper 会先拆掉旧的 `providerErrorCenter/providerSuccessCenter.subscribe(...)`
+  - 再把 runtime router hooks 直接挂到 `routerEngine.handleProviderError/Success`
+- **legacy `providerErrorCenter/providerSuccessCenter` 现阶段只保留 compat adapter 角色**
+  - 残留 `emit(...)` 会在 bridge 层被 patch 后继续 forward 到 runtime ingress
+  - 即：它们仍物理存在，但**不再主导策略**
+- **RouteErrorHub / ErrorHandlingCenter 现阶段只保留 Host 边界职责**
+  - 适用：HTTP / server / CLI / 外层错误映射与统一返回
+  - 不再承担 provider runtime retry/reroute/backoff 主决策
+- **stopless 静默停已加硬校验**
+  - 若 `stopless=on/endless` 且响应完成时缺少 `reasoning.stop` finalized marker，直接抛 `STOPLESS_FINALIZATION_MISSING`（502、retryable）
+- **429 止血已落地**
+  - `RequestExecutor` 不再因为“当前 tier 是 singleton”就抱着当前 provider 死重试
+  - 当前 provider 出错会优先被排除并 reroute
+- **provider error reporting 前置装配已收口到单点 helper**
+  - `runtime_resolve` / `provider.send` 不再分支内手拼 `errorCode/upstreamCode/statusCode/stageHint`
+  - 当前统一入口：`resolveRequestExecutorProviderErrorReportPlan(...) -> reportRequestExecutorProviderError(...)`
+  - `resolveRequestExecutorProviderErrorReportPlan(...)` 现在会自己优先解析 `requestExecutorProviderErrorStage`（含 `details`）；外层只需要给默认 stage，不再先手动 resolve fallback
+  - 已覆盖 `provider.runtime_resolve` / `provider.sse_decode` / `provider.followup` 的阶段判定
+- **converted retryable HTTP status 不再双上报**
+  - 之前 `converted 401/429/5xx` 会在 try 内先报一次 `provider.http`，外层 catch 再报一次
+  - 现改为只给错误打 `provider.http` stage marker，统一由外层 `reportRequestExecutorProviderError(...)` 上报一次
+- **provider.followup 不再污染 provider 健康**
+  - servertool/client-inject/followup payload 这类 followup orchestration 错误统一视为 health-neutral
+  - `RequestExecutor` 会按 `provider.followup` stage 直接给 `affectsHealth=false`
+  - `emitProviderError(...)` 现在会显式尊重调用方传入的 `affectsHealth=false`，不再把所有 non-recoverable 一律强改为 `true`
+- **followup stage marker 前移到 converter 源头**
+  - `provider-response-converter` 对 `SERVERTOOL_*` followup 错误会直接打 `requestExecutorProviderErrorStage='provider.followup'`
+  - request-executor 优先读 marker，再回退到 code/stage 推断
+- **SSE decode stage marker 也开始前移**
+  - SSE wrapper / bridge SSE remap 错误会直接打 `requestExecutorProviderErrorStage='provider.sse_decode'`
+  - legacy `executor-response` 也已同步，减少新旧链路阶段口径漂移
+  - request-executor 继续保留 fallback 推断，但优先使用显式 marker
+- **client injection host 源头也已接入 followup marker**
+  - `client-injection-flow` 创建的 strict tmux / inject 失败错误会直接打 `requestExecutorProviderErrorStage='provider.followup'`
+  - 这样 host 内部已知的 followup/internal error 不必再等外层按 code/message 推断
+
+## 0. 唯一真源与待删除项
+
+### 唯一策略真源
+- `Virtual Router policy`
+  - classify error
+  - decide retry / reroute / backoff / fail
+  - manage cooldown / health / quota / exclusion
+  - output unified error decision / policy state
+
+### Consumer
+- `RequestExecutor`
+  - 只执行 Router 返回的 decision plan
+- `servertool engine`
+  - 只保留 followup 编排前 / internal error 边界
+  - provider/runtime/send/convert 类错误不得再自定义第二套语义
+
+### 待移除
+- 独立 `error-handling center`
+- 独立 event engine / event bus
+- `RequestExecutor` 内部自带的第二套 retry/reroute/backoff 决策语义
+
+## 1. 统一流程（目标态）
+
+1. **HubPipeline** 做编排与向上抛错，不定义最终错误策略。
+2. **Virtual Router policy** 接收执行期错误输入，产出统一 decision：
+   - `retry_same_provider`
+   - `exclude_and_reroute`
+   - `wait_for_cooldown`
+   - `fail`
+3. **RequestExecutor** 消费该 decision 并执行实际 retry / reroute / sleep / fail。
+4. **servertool followup** 的 provider 类错误也走同一套 Router policy；只有 payload 缺失、reenter 不可用、client inject dispatcher 缺失等编排前/internal error 保留在 servertool 自身边界。
+
+## 2. 分层职责
+
+| 层 | 职责 | 不该做什么 |
+| --- | --- | --- |
+| HubPipeline | request/chat-process 编排、标准化、向上抛错 | 不定义最终 retry/reroute/backoff 策略 |
+| Virtual Router policy | 错误分类、路由/冷却/健康/额度策略、统一 decision 输出 | 不负责具体 sleep/retry 执行循环 |
+| RequestExecutor | 执行 Router decision、驱动 provider runtime/send/convert | 不再独立发明第二套 error policy |
+| servertool engine | followup 编排前/internal error 边界、followup reenter orchestration | 不再包一层独立 provider retry/error 语义 |
+
+## 3. 当前剩余遗留问题（继续收口项）
+
+- legacy `providerErrorCenter/providerSuccessCenter` 仍是**物理残留模块**，虽然已降级为 compat adapter，但后续仍应继续物理去除中转角色
+- followup 的编排前/internal error 与 provider 执行期错误边界还需继续压实，避免 `SERVERTOOL_*` 语义再次外溢
+- provider-switch 日志仍需继续核对，确保不再出现误导性的“下一跳/回退”观感
+- Host 边界的 `RouteErrorHub / ErrorHandlingCenter` 文档与调用面还需继续缩小到“外层映射”职责，避免再次被误当策略中心
+
+## 4. 收口验收信号
+
+- followup 与普通请求共用同一套 Router error policy
+- 不再存在独立 event bus / error center 中转层
+- `RequestExecutor` 只消费 Router decision
+- `SERVERTOOL_FOLLOWUP_FAILED` 只保留编排失败语义
+- provider-switch 不再出现 `7/6` 之类越界假下一跳
+
+---
+
+## Historical Reference: V2 旧机制（待迁出/待删除）
+
+以下内容保留为历史参考，帮助识别旧实现；如与上文冲突，以**上文 Router Policy SSOT** 为准。
+
+## H1. 统一流程
 
 1. **HTTP Server / CLI / Pipeline** 捕获异常后调用 `reportRouteError(payload)`，由 `RouteErrorHub` 统筹。
 2. `RouteErrorHub` 负责：
@@ -10,10 +119,10 @@
    - 根据构建模式自动裁剪堆栈：`release` 构建默认移除 stack（可通过 `ROUTECODEX_RELEASE_ERROR_VERBOSE=1` 恢复详细日志）。
    - 将错误交给 `ErrorHandlerRegistry`，触发挂载的处理 Hook（含 429 回退调度、快照写入等）。
    - 可选返回 HTTP 映射结果，确保客户端仅收到统一格式的错误体。
-3. Provider 侧在 `emitProviderError` 同时上报 `providerErrorCenter`（供 Virtual Router 熔断）与 `ErrorHandlingCenter`。
+3. （旧）Provider 侧曾在 `emitProviderError` 同时上报 `providerErrorCenter` 与 `ErrorHandlingCenter`。
 4. `llmswitch-core` 的 Virtual Router 根据 `ProviderErrorEvent` 执行健康状态变更（回退、降级、拉黑）。
 
-## 2. 错误策略矩阵
+## H2. 错误策略矩阵
 
 | 错误来源 | 状态 / 错误码 | Error Center 处理 | Virtual Router / ProviderHealth 策略 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -25,13 +134,13 @@
 
 > ⚠️ RateLimitTracker 只针对**相同 providerKey（provider.key / provider.key::model）**的连续 429 生效，中间出现成功或其他错误即会自动清零；冷却结束后会再次尝试，具体 TTL 由 `virtualrouter.health` 配置决定，且与使用的 route/routePool 无关。
 
-## 3. 日志与可观测性
+## H3. 日志与可观测性
 
 - **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. 回调挂载点
+## H4. 回调挂载点
 
 - `ErrorHandlerRegistry` 默认挂载以下 Hook，可按需扩展：
   - `rate_limit_error`：提供回退调度（切换 pipeline 或延迟重放）。
@@ -40,7 +149,7 @@
 
 如需新增策略（例如特定 provider 的 4xx 也触发冷却），建议在 `docs/error-handling-v2.md` 补充矩阵，并在 `virtualrouter.health` 配置中增加自定义参数。
 
-## 5. 工具协议错误（ProviderProtocolError）
+## H5. 工具协议错误（ProviderProtocolError）
 
 ServerTool 与工具调用相关的后端错误统一通过 `ProviderProtocolError` 表达，类型定义位于
 `sharedmodule/llmswitch-core/src/conversion/shared/errors.ts`。
@@ -68,7 +177,7 @@ ServerTool 与工具调用相关的后端错误统一通过 `ProviderProtocolErr
 2. 在此文档补充该错误 code 的含义与触发条件；
 3. 确保 provider runtime 捕获到该错误时仍通过 `emitProviderError` 上报，并映射为明确的 HTTP 错误响应。
 
-### 5.1 粗粒度错误类别（EXTERNAL / TOOL / INTERNAL）
+### H5.1 粗粒度错误类别（EXTERNAL / TOOL / INTERNAL）
 
 为方便统计与路由策略，`ProviderProtocolError` 还暴露一个粗粒度错误类别 `category`：