@jsonstudio/rcc 0.89.1205 → 0.89.1457

package/docs/ARCHITECTURE.md

@@ -0,0 +1,402 @@
+# RouteCodex 系统架构文档
+
+## 概述
+
+RouteCodex 是一个多 Provider OpenAI 代理服务器，支持动态路由、负载均衡和兼容性处理。系统采用模块化设计，支持主题订阅、错误处理、调试中心等高级功能。
+
+## 与 sharedmodule/llmswitch-core 的职责边界
+
+| 责任层 | RouteCodex Host (本仓库) | sharedmodule/llmswitch-core |
+| --- | --- | --- |
+| 配置解析 | 读取用户配置文件，调用 `bootstrapVirtualRouterConfig`，将 `virtualRouterArtifacts.config` 传给 `HubPipeline` | 验证 routing/providers/classifier，展开 provider.keyAlias.model，输出 `targetRuntime` |
+| HTTP 请求 | `/v1/chat`/`/v1/responses`/`/v1/messages` handler 将 HTTP/SSE 载荷封装为 `HubPipelineRequest` | SSE Input → Chat Process → Virtual Router → Output，生成 `providerPayload` + `target` |
+| Provider 初始化 | 根据 `virtualRouterArtifacts.targetRuntime` 初始化 Provider 实例，绑定 auth/baseURL/compat profile | 不直接创建 Provider 客户端，仅输出 runtime 元数据 |
+| Provider 调用 | 使用 runtimeKey 查找 Provider 实例，向上游发送请求，记录日志/快照 | 输出 `target.runtimeKey`，供 host 查表；捕获 `ProviderErrorEvent` 以管理熔断 |
+| 错误处理 | Provider/Compatibility 抛错 → `errorHandlingCenter.handleError` → 上报 `providerErrorCenter`，并映射为 HTTP 响应 | Virtual Router 接收 `ProviderErrorEvent`、执行熔断/降级；Hub Pipeline 将错误冒泡给 host |
+| 热更新 | 监听配置变更 → 调用 `hubPipeline.updateVirtualRouterConfig(newArtifacts.config)`，并刷新 Provider runtime | 在内部替换 Virtual Router 配置并继续输出最新的 routing/runtime 状态 |
+
+> **落地要求**：Host 不再解析旧的“合并配置”蓝图，也不在 Provider 层做“模型选择”；所有模型替换/目标决策由 Virtual Router 执行，Host 仅负责“把 HTTP/SSE 转交给 Hub Pipeline + 根据 runtimeKey 调用 Provider”，从而保证单一职责和无兜底策略。
+
+## 系统架构
+
+### 核心组件
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        RouteCodex 架构                           │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │   HTTP Server   │  │   Config Mgr    │  │   Provider Mgr  │  │
+│  │                 │  │                 │  │                 │  │
+│  │  • 请求处理      │  │  • 配置管理      │  │  • Provider管理  │  │
+│  │  • 路由分发      │  │  • 验证器        │  │  • 负载均衡      │  │
+│  │  • 响应格式化    │  │  • 热重载        │  │  • 故障转移      │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│           │                     │                     │         │
+│           └─────────────────────┼─────────────────────┘         │
+│                                 │                               │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │   Core Logic    │  │   MessageCenter │  │   DebugCenter   │  │
+│  │                 │  │                 │  │                 │  │
+│  │  • 请求转发      │  │  • 主题订阅      │  │  • 调试记录      │  │
+│  │  • 响应处理      │  │  • 消息路由      │  │  • 性能监控      │  │
+│  │  • 错误处理      │  │  • 模块通信      │  │  • 会话管理      │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│           │                     │                     │         │
+│           └─────────────────────┼─────────────────────┘         │
+│                                 │                               │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │    Utilities    │  │   ErrorHandling  │  │     Patches     │  │
+│  │                 │  │                 │  │                 │  │
+│  │  • 日志工具      │  │  • 错误处理      │  │  • 兼容性补丁    │  │
+│  │  • 负载均衡      │  │  • 重试机制      │  │  • 响应转换      │  │
+│  │  • 故障转移      │  │  • 异常恢复      │  │  • 格式适配      │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 主题订阅系统
+
+#### MessageCenter 架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        MessageCenter                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │   Module Mgr    │  │TopicSubscription │  │MessageProcessor │  │
+│  │                 │  │      Manager     │  │                 │  │
+│  │  • 模块注册      │  │  • 主题订阅      │  │  • 消息验证      │  │
+│  │  • 生命周期      │  │  • 通配符支持    │  │  • 消息处理      │  │
+│  │  • 状态管理      │  │  • 订阅管理      │  │  • 路由分发      │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│           │                     │                     │         │
+│           └─────────────────────┼─────────────────────┘         │
+│                                 │                               │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │Request Mgr     │  │Statistics Mgr   │  │ Broadcast Mgr   │  │
+│  │                 │  │                 │  │                 │  │
+│  │  • 请求管理      │  │  • 性能统计      │  │  • 消息广播      │  │
+│  │  • 响应处理      │  │  • 监控指标      │  │  • 多播分发      │  │
+│  │  • 超时控制      │  │  • 报告生成      │  │  • 订阅通知      │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+#### 主题订阅特性
+
+1. **主题订阅**
+   - 支持模块订阅特定主题
+   - 动态订阅/取消订阅
+   - 订阅状态管理
+
+2. **通配符支持**
+   - 支持通配符订阅所有主题
+   - 灵活的消息路由
+   - 订阅者过滤
+
+3. **消息路由**
+   - 基于主题的消息分发
+   - 多播消息传递
+   - 订阅者隔离
+
+4. **统计监控**
+   - 订阅统计信息
+   - 消息传递统计
+   - 性能指标收集
+
+### 调试中心集成
+
+#### DebugCenter 主题订阅集成
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     DebugCenter                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │   Event Bus     │  │   Session Mgr   │  │   Topic Sub     │  │
+│  │                 │  │                 │  │                 │  │
+│  │  • 事件总线      │  │  • 会话管理      │  │  • 主题订阅      │  │
+│  │  • 事件处理      │  │  • 状态跟踪      │  │  • 消息发布      │  │
+│  │  • 订阅管理      │  │  • 生命周期      │  │  • 跨模块通信    │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│           │                     │                     │         │
+│           └─────────────────────┼─────────────────────┘         │
+│                                 │                               │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │   Pipeline      │  │   Message Ctr  │  │   Statistics    │  │
+│  │                 │  │                 │  │                 │  │
+│  │  • 流水线处理    │  │  • 消息中心      │  │  • 统计信息      │  │
+│  │  • 事件记录      │  │  • 集成通信      │  │  • 性能监控      │  │
+│  │  • 协调调度      │  │  • 全局实例      │  │  • 报告生成      │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 模块依赖关系
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       模块依赖关系                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐  │
+│  │   RouteCodex    │    │  rcc-errorhandling │  │
+│  │                 │    │                 │    │                 │  │
+│  │  • 主应用        │    │  • 调试中心      │    │  • 错误处理      │  │
+│  │  • 服务器        │    │  • 主题订阅      │    │  • 异常管理      │  │
+│  │  • 路由管理      │    │  • 会话跟踪      │    │  • 重试机制      │  │
+│  └─────────────────┘    └─────────────────┘    └─────────────────┘  │
+│           │                       │                       │         │
+│           └───────────────────────┼───────────────────────┘         │
+│                                   │                               │
+│  ┌─────────────────────────────────────────────────────────────────┐  │
+│  │                    rcc-basemodule                              │  │
+│  │                                                                 │  │
+│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │  │
+│  │  │  MessageCenter  │  │   Interfaces    │  │   Utilities     │  │  │
+│  │  │                 │  │                 │  │                 │  │
+│  │  │  • 主题订阅      │  │  • 类型定义      │  │  • 工具函数      │  │
+│  │  │  • 消息路由      │  │  • 接口规范      │  │  • 辅助方法      │  │
+│  │  │  • 模块通信      │  │  • 数据结构      │  │  • 通用模块      │  │
+│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘  │  │
+│  │                                                                 │  │
+│  └─────────────────────────────────────────────────────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Hub Pipeline 集成（llmswitch-core）
+
+RouteCodex 现在完全依赖 sharedmodule/llmswitch-core 的 Hub Pipeline，实现“HTTP ↔ 标准化请求 ↔ Virtual Router ↔ Provider”全链路处理：
+
+- **唯一入口**：服务器通过 `RouteCodexHttpServer` 调用 `sharedmodule/llmswitch-core/dist/conversion/hub/pipeline/hub-pipeline`，禁止旁路加载核心模块。
+- **配置来源**：`routecodex-config-loader` 读取用户配置后调用 `bootstrapVirtualRouterConfig`。该工具会校验 routing/providers、展开 `provider.keyAlias.model`、生成 `targetRuntime` 映射（endpoint、headers、auth、compat profile），Hub Pipeline 构造函数直接接受该结果。
+- **节点链路**：Hub Pipeline 在内部组成 `SSE Input → Input Node → Chat Process → Virtual Router → (Compatibility，可选) → Output/SSE`。Host 不关心节点细节，只需要把 HTTP 请求封装成标准化的 Hub 请求。
+- **工具治理**：唯一的工具治理点位于 `chat-process-node`。Compatibility 层已完全下沉到 llmswitch-core（`sharedmodule/llmswitch-core/src/conversion/compat`），仅做 Provider 特定的最小字段修剪。
+- **Provider 调度**：Virtual Router 负责分类、熔断、负载均衡，并把 `target.runtimeKey` 写入请求。Host 使用 `bootstrapVirtualRouterConfig` 输出的 `targetRuntime` 把 runtimeKey 映射到具体 Provider 实例（包含 OAuth/apiKey 配置、baseURL、compat profile）。
+- **错误流**：Provider/Compatibility 报错后调用 `errorHandlingCenter.handleError`，同时通过 `providerErrorCenter.emit` 把 `ProviderErrorEvent` 交还给 Virtual Router，以便执行熔断和健康统计。
+
+借助 Hub Pipeline，HTTP 层只需关注请求封装与 Provider runtime 生命周期，核心能力全部收敛在 sharedmodule 中，实现“入口单一、无兜底”的目标。
+
+## 技术栈
+
+### 核心技术
+
+- **Node.js**: 运行时环境
+- **TypeScript**: 类型安全的JavaScript
+- **ESM**: 纯ES模块系统
+- **Rollup**: 模块打包工具
+
+### 构建工具
+
+- **TypeScript**: 编译时类型检查
+- **Rollup**: ESM模块打包
+- **Jest**: 单元测试框架
+- **ESLint**: 代码质量检查
+
+### 发布工具
+
+- **NPM**: 包管理器
+- **Semantic Versioning**: 版本管理
+- **CI/CD**: 自动化构建和发布
+
+## 消息流程
+
+### 主题订阅消息流程
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      主题订阅消息流程                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Publisher → MessageCenter → TopicSubscription → Subscribers   │
+│      │             │                   │             │          │
+│      │             │                   │             │          │
+│  ┌─────┐      ┌──────┐          ┌──────┐      ┌──────┐         │
+│  │Publish│      │Route │          │Topic │      │Receive│       │
+│  │Message│      │Message│          │Match │      │Message│       │
+│  └─────┘      └──────┘          └──────┘      └──────┘         │
+│      │             │                   │             │          │
+│      │             │                   │             │          │
+│      ▼             ▼                   ▼             ▼          │
+│  ┌─────┐      ┌──────┐          ┌──────┐      ┌──────┐         │
+│  │Create│      │Validate│          │Filter│      │Process│       │
+│  │Message│      │Message│          │Subs  │      │Message│       │
+│  └─────┘      └──────┘          └──────┘      └──────┘         │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 错误处理流程
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        错误处理流程                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Error → ErrorHandling → Recovery → Retry/Fallback → Success     │
+│    │         │              │          │            │          │
+│    │         │              │          │            │          │
+│  ┌───┐   ┌─────┐      ┌─────┐     ┌─────┐     ┌─────┐   ┌─────┐ │
+│  │Cap│   │Class│      │Analyze│   │Retry│     │Fallback│ │Result│ │
+│  │ture│   │ify │      │Error │   │Logic│     │Handler │ │Log  │ │
+│  └───┘   └─────┘      └─────┘     └─────┘     └─────┘   └─────┘ │
+│    │         │              │          │            │          │
+│    │         │              │          │            │          │
+│    ▼         ▼              ▼          ▼            ▼          │
+│  ┌───┐   ┌─────┐      ┌─────┐     ┌─────┐     ┌─────┐   ┌─────┐ │
+│  │Log │   │Track│      │Recover│   │Attempt│   │Alternative││End  │ │
+│  │Error│   │Error│      │State  │   │Count │   │Solution│ │Flow │ │
+│  └───┘   └─────┘      └─────┘     └─────┘     └─────┘   └─────┘ │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 配置管理
+
+### 系统配置
+
+```json
+{
+  "server": {
+    "port": 5506,
+    "host": "localhost",
+    "cors": {
+      "enabled": true,
+      "origins": ["*"]
+    }
+  },
+  "providers": {
+    "openai-provider": {
+      "type": "openai",
+      "enabled": true,
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "your-api-key",
+      "models": {
+        "gpt-4": {
+          "maxTokens": 8192,
+          "temperature": 0.7
+        }
+      }
+    }
+  },
+  "messageCenter": {
+    "enableTopicSubscription": true,
+    "topics": {
+      "debug-events": "Debug events topic",
+      "system-events": "System events topic"
+    },
+    "wildcardSubscription": true
+  },
+  "debugCenter": {
+    "outputDirectory": "./debug-logs",
+    "enableTopicSubscription": true,
+    "topicSubscriptionConfig": {
+      "debugTopic": "debug-events",
+      "systemTopic": "system-events",
+      "enableWildcardSubscription": true
+    }
+  }
+}
+```
+
+### 主题订阅配置
+
+```json
+{
+  "topicSubscription": {
+    "enabled": true,
+    "topics": {
+      "debug-events": {
+        "description": "Debug events topic",
+        "subscribers": ["monitoring"]
+      },
+      "system-events": {
+        "description": "System events topic",
+        "subscribers": ["errorhandler"]
+      },
+      "user-events": {
+        "description": "User events topic",
+        "subscribers": ["analytics", "monitoring"]
+      }
+    },
+    "wildcardEnabled": true,
+    "wildcardSubscribers": []
+  }
+}
+```
+
+## 部署架构
+
+### 开发环境
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        开发环境                                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │   Development   │  │   Testing       │  │   Debugging     │  │
+│  │                 │  │                 │  │                 │  │
+│  │  • 热重载        │  │  • 单元测试      │  │  • 调试工具      │  │
+│  │  • 源码映射      │  │  • 集成测试      │  │  • 性能分析      │  │
+│  │  • 开发日志      │  │  • 端到端测试    │  │  • 日志查看      │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 生产环境
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        生产环境                                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │   Load Balancer │  │   RouteCodex    │  │   Monitoring    │  │
+│  │                 │  │                 │  │                 │  │
+│  │  • 负载均衡      │  │  • 多实例        │  │  • 性能监控      │  │
+│  │  • 健康检查      │  │  • 容器化        │  │  • 日志收集      │  │
+│  │  • 故障转移      │  │  • 自动扩展      │  │  • 告警通知      │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│           │                       │                       │         │
+│           └───────────────────────┼───────────────────────┘         │
+│                                   │                               │
+│  ┌─────────────────────────────────────────────────────────────────┐  │
+│  │                     Infrastructure                             │  │
+│  │                                                                 │  │
+│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │  │
+│  │  │   Database      │  │   Cache         │  │   Queue         │  │  │
+│  │  │                 │  │                 │  │                 │  │
+│  │  │  • 数据存储      │  │  • 缓存管理      │  │  • 消息队列      │  │
+│  │  │  • 会话存储      │  │  • 性能优化      │  │  • 异步处理      │  │
+│  │  │  • 配置存储      │  │  • 数据同步      │  │  • 任务调度      │  │
+│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘  │  │
+│  │                                                                 │  │
+│  └─────────────────────────────────────────────────────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 版本信息
+
+- **当前版本**: 0.0.1
+- **最后更新**: 2025-01-22
+- **维护团队**: RouteCodex 开发团队
+- **文档版本**: 1.0.0
+
+## 相关文档
+
+- [README.md](./README.md) - 项目概述和快速开始
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - 贡献指南
+- [CHANGELOG.md](./CHANGELOG.md) - 变更日志
+- [API 文档](./docs/api/) - API 接口文档
+- [部署指南](./docs/deployment/) - 部署相关文档

package/docs/CHAT_PROCESS_PROTOCOL_AND_PIPELINE.md

@@ -0,0 +1,221 @@
+# Chat Process 协议与流水线契约（processMode=chat）
+
+> 目的：把“请求/响应都必须进入 chat process（且只走 chat 扩展协议）”写成可执行、可 fail-fast 的契约，并给出**命名统一**与**修改点清单**，供审阅后再落地。
+
+## 1) 术语（统一口径）
+
+- **Chat 扩展协议（Chat Extension Protocol）**：llmswitch-core 内部的统一载体。
+  - 请求载体：`ChatEnvelope` / `StandardizedRequest`
+  - 响应载体：`ChatCompletionLike`（必须是 *OpenAI-chat-like*：`choices[0].message` 存在）
+- **Chat Process**：对 chat 载体执行的“必经处理段”，包括但不限于：
+  - 工具治理/收割/规范化（tool governance + response tool harvesting）
+  - 路由选择（VirtualRouter）
+  - 兼容动作（compat actions）只能通过 Hub Pipeline 阶段触发
+- **metadata**：仅允许承载**不可映射**的运行时提示/诊断信息；任何“可映射语义（mappable semantics）”严禁滞留在 metadata。
+
+## 2) 刚性不变量（processMode=chat）
+
+### 2.1 请求侧
+
+在 `processMode=chat` 下，请求必须满足：
+
+1. **inbound 必须产出 chat 扩展协议语义**（语义映射完成后才允许进入 chat process）。
+2. **必须进入 chat process**（除非明确 `processMode=passthrough`）。
+3. **outbound 仅使用白名单语义重建客户端协议**（clientRemap），不允许把“可映射语义”回塞到 metadata/透传到客户端。
+
+代码事实（当前实现骨架）：
+- 正常入口：`sharedmodule/llmswitch-core/src/conversion/hub/pipeline/hub-pipeline.ts`（`executeRequestStagePipeline` 内部）
+- servertool followup 重入入口：`sharedmodule/llmswitch-core/src/servertool/engine.ts:468`（`__hubEntry = 'chat_process'`，进入 `executeChatProcessEntryPipeline`）
+
+### 2.2 响应侧
+
+在 `processMode=chat` 下，响应必须满足：
+
+1. **provider → compat → inbound → 语义映射（chat 形态）**是必经步骤。
+2. **进入响应侧 chat process 前，必须是 canonical chat completion**（`choices[0].message` 存在）。
+3. **outbound 仅产出客户端协议白名单字段**；内部 metadata 只用于转换过程，不可泄露到客户端 payload。
+
+代码事实（当前实现骨架）：
+- `sharedmodule/llmswitch-core/src/conversion/hub/response/provider-response.ts:343`（resp inbound SSE decode）
+- `sharedmodule/llmswitch-core/src/conversion/hub/response/provider-response.ts:401`（resp inbound semantic map → `chatResponse`）
+- `sharedmodule/llmswitch-core/src/conversion/hub/response/provider-response.ts:426`（servertool orchestration）
+- `sharedmodule/llmswitch-core/src/conversion/hub/response/provider-response.ts:464`（resp process tool governance）
+- canonical chat completion 强制归一（hard gate）：`sharedmodule/llmswitch-core/src/conversion/hub/response/provider-response.ts`（servertool orchestration 后、resp process 前）
+- canonical chat completion 兜底归一（best-effort bridge）：`sharedmodule/llmswitch-core/src/conversion/hub/pipeline/stages/resp_process/resp_process_stage1_tool_governance/index.ts`
+
+## 3) “强制语义映射”规则（进入 chat process 前）
+
+### 3.1 原则
+
+- **同一语义在不同协议出现 → 必须映射到同一 chat 字段**（而不是塞进 metadata）。
+- **chat 本身已有字段**（如 `messages/tools/toolOutputs/parameters`）→ 直接落入这些字段。
+- **chat 没有但属于“跨协议可复用语义”** → 进入 `ChatSemantics` 的稳定字段（优先 `semantics.session/system/tools`，其次协议命名空间 `semantics.responses/anthropic/gemini`）。
+- **仅“暂时无法映射/无语义对齐”的残余**，才允许进入 `semantics.providerExtras`（并要求逐步清空）。
+
+### 3.2 禁入字段（fail-fast）
+
+进入 chat process 的最后一刻，必须 fail-fast 校验：任何**可映射语义**不得存在于 metadata。
+
+代码事实：当前请求侧在 chat_process entry 有 strict gate：
+- `sharedmodule/llmswitch-core/src/conversion/hub/pipeline/hub-pipeline.ts:1714`（`assertNoMappableSemanticsInMetadata`）
+- 当前禁入键（含 snake_case 同义键）：`responsesResume`, `clientToolsRaw`, `anthropicToolNameMap`, `responsesContext`, `responseFormat`, `systemInstructions`, `toolsFieldPresent`, `extraFields`
+
+你拍板（A1）：禁入采用“已知具体键枚举”，并持续把同义字段/旧字段补全进黑名单；不禁掉 legacy catch-all 容器本身。
+
+> 落地要求：把 legacy `extraFields/*Context/*Format` 这种“同义字段/旧字段”逐条枚举到禁入表（而不是靠一个大范围禁掉容器）。
+
+#### A1 协议扫描结果（第一版：哪些键属于“可映射语义”，因此应被纳入禁入枚举/或迁移出 metadata）
+
+> 说明：这里把“可映射语义”按**来源协议**归类，并标出当前代码的落点（metadata vs semantics）。
+> 目标是：最终 chat process 只读 chat 字段与 `chat.semantics`，而不是靠 metadata 透传语义。
+
+**OpenAI Chat（openai-chat）**
+- legacy `metadata.systemInstructions`：可映射 → `chat.semantics.system.textBlocks`（当前主路径不再依赖 metadata；若仍出现应视为 legacy 注入并被 fail-fast gate 拦截）。
+- legacy `metadata.toolsFieldPresent`：可映射 → `chat.semantics.tools.explicitEmpty`（当前主路径不再依赖 metadata；若仍出现应视为 legacy 注入并被 fail-fast gate 拦截）。
+- legacy `metadata.extraFields`：可映射 → `chat.semantics.providerExtras.openaiChat.extraFields`（当前主路径以 semantics 为准；若仍出现应视为 legacy 注入并被 fail-fast gate 拦截）。
+
+**Gemini（gemini-chat）**
+- legacy `metadata.toolsFieldPresent`：可映射 → `chat.semantics.tools.explicitEmpty`（当前主路径不再依赖 metadata；若仍出现应视为 legacy 注入并被 fail-fast gate 拦截）。
+
+**Anthropic（anthropic-messages）**
+- legacy `anthropicToolNameMap`：可映射 → `chat.semantics.tools.toolNameAliasMap`（当前主路径已写入 semantics，见 `.../anthropic-mapper.ts:176`；禁入枚举保留是为了阻止旧路径把它塞回 metadata）。
+
+**Responses（openai-responses）**
+- legacy `responsesContext` / `responseFormat`：可映射 → `chat.semantics.responses.context` / `chat.semantics.responses.responseFormat`（当前主路径已走 semantics；禁入枚举用于阻止旧路径回流到 metadata）。
+- `responsesResume`（submit_tool_outputs resume）：可映射 → `chat.semantics.responses.resume`（已落地到 inbound semantic gate，见 `.../req_inbound_stage2_semantic_map/index.ts:57`）。
+
+### 3.3 已落地的语义映射（作为基线）
+
+（当前代码已做，符合“可映射语义不得滞留 metadata”的方向）
+
+- `/v1/responses` tool-loop 恢复语义：
+  - `responsesResume`（host side 临时注入）→ **必须**在 inbound semantic map 前提升为 `chat.semantics.responses.resume`
+  - 并在需要时提升为 `chat.toolOutputs`（统一工具输出面）
+  - 位置：`sharedmodule/llmswitch-core/src/conversion/hub/pipeline/stages/req_inbound/req_inbound_stage2_semantic_map/index.ts:57`
+
+- 客户端 tools raw schema：
+  - `tools` 原始数组 → `chat.semantics.tools.clientToolsRaw`
+  - 位置：`sharedmodule/llmswitch-core/src/conversion/hub/pipeline/stages/req_inbound/req_inbound_stage2_semantic_map/index.ts:51`
+
+- Anthropic tool alias：
+  - `payload.tools` → `chat.semantics.tools.toolNameAliasMap`
+  - 位置：`sharedmodule/llmswitch-core/src/conversion/hub/operation-table/semantic-mappers/anthropic-mapper.ts:176`
+
+## 4) ServerTool followup 契约（你选的方案：override → canonical chat）
+
+目标：servertool followup **不允许破坏“响应进入 chat process 必须 canonical chat completion”** 的不变量。
+
+### 4.1 请求重入（followup request）
+
+代码事实：目前 followup 通过设置 `__hubEntry='chat_process'` 直接从 chat_process 入口重入：
+- `sharedmodule/llmswitch-core/src/servertool/engine.ts:468`
+
+你拍板（B）：followup 重入入口仍为 `__hubEntry='chat_process'`，并明确 hop 编号：
+
+- **H1**：第一次请求命中（例如图像 meta / web_search 关键词等）。
+- **H2**：模型调用工具被截获后进入工具执行：
+  - web_search：发起工具请求；
+  - vision：直接路由到第二跳进行 vision 工具调用；
+  - 这里发生一次路由与一次 reenter（进 chat process）。
+- **H3**：第二次请求的响应回来后拦截并注入结果，再次 reenter 到 chat process 继续请求。
+
+### 4.2 响应 override（followup response）
+
+你拍板（C）：followup 对 provider 来说就是正常请求；响应回来后与正常响应一致：
+- 成功/失败都按正常响应返回给客户端；
+- 429 等错误按正常策略截获重发（reenter 处）/VirtualRouter 重试；不引入“followup 特判”的异常路径。
+
+因此，这里所谓“响应 override”不是“在 Host/Provider 绕开响应流水线”，而是强调**响应侧统一约束**：
+- 无论该响应来自 H1/H2/H3 中的哪一跳，只要进入响应侧 chat process（response tool harvesting/governance），就必须先完成 “provider→compat→inbound→semantic_map_to_chat→(必要时 canonicalize_chat_completion)” 的统一处理；
+- canonicalize 失败时，按正常错误流返回（fail-fast / bubble up），而不是在 Host/Provider 做 payload 语义修补或旁路输出。
+
+代码事实（当前实现的 canonicalize 约束点）：
+- servertool orchestration 后、进入 resp process 前：hard gate（必须 canonical，否则抛错）：
+  - `sharedmodule/llmswitch-core/src/conversion/hub/response/provider-response.ts`
+- resp process 内部保留 best-effort bridge（仅作为安全网；原则上不应再依赖它）：
+  - `sharedmodule/llmswitch-core/src/conversion/hub/pipeline/stages/resp_process/resp_process_stage1_tool_governance/index.ts`
+
+## 5) StageId 命名规范（你要求的点分风格）
+
+### 5.1 新命名（提案）
+
+> 你要求：`chat_process.req.stage1_*`（点分）——下面给出 request/response 的对齐命名。
+
+**请求侧（direction=request）**
+- `chat_process.req.stage1.format_parse`
+- `chat_process.req.stage2.semantic_map`
+- `chat_process.req.stage3.context_capture`
+- `chat_process.req.stage4.tool_governance`
+- `chat_process.req.stage5.route_select`
+- `chat_process.req.stage6.outbound.semantic_map`
+- `chat_process.req.stage7.outbound.format_build`
+- `chat_process.req.stage8.outbound.compat`
+
+**响应侧（direction=response）**
+- `chat_process.resp.stage1.sse_decode`
+- `chat_process.resp.stage2.format_parse`
+- `chat_process.resp.stage3.compat`
+- `chat_process.resp.stage4.semantic_map_to_chat`
+- `chat_process.resp.stage5.servertool_orchestration`
+- `chat_process.resp.stage6.canonicalize_chat_completion`
+- `chat_process.resp.stage7.tool_governance`
+- `chat_process.resp.stage8.finalize`
+- `chat_process.resp.stage9.client_remap`
+- `chat_process.resp.stage10.sse_stream`
+
+### 5.2 现有命名 → 新命名（已落地）
+
+你补充的约束：目前只有 **chat process 相关**命名会混淆，所以只改 chat process 范围内的 stageId/keys，不扩大到全链路。
+
+下面这些已统一改名（stageId 仅用于 stageRecorder/snapshot，不更改目录结构）：
+
+- 请求 inbound：
+  - `req_inbound_stage1_format_parse` → `chat_process.req.stage1.format_parse`
+  - `req_inbound_stage2_semantic_map` → `chat_process.req.stage2.semantic_map`
+  - `req_inbound_stage3_context_capture` → `chat_process.req.stage3.context_capture`
+- 请求 process/outbound：
+  - `req_process_stage1_tool_governance` → `chat_process.req.stage4.tool_governance`
+  - `req_process_stage2_route_select` → `chat_process.req.stage5.route_select`
+  - `req_outbound_stage1_semantic_map` → `chat_process.req.stage6.outbound.semantic_map`
+  - `req_outbound_stage2_format_build` → `chat_process.req.stage7.outbound.format_build`
+  - `req_outbound_stage3_compat` → `chat_process.req.stage8.outbound.compat`
+- 响应 inbound/process/outbound：
+  - `resp_inbound_stage1_sse_decode` → `chat_process.resp.stage1.sse_decode`
+  - `resp_inbound_stage2_format_parse` → `chat_process.resp.stage2.format_parse`
+  - `resp_inbound_stage_compat` → `chat_process.resp.stage3.compat`
+  - `resp_inbound_stage3_semantic_map` → `chat_process.resp.stage4.semantic_map_to_chat`
+  - `resp_process_stage0_chat_normalize` → `chat_process.resp.stage6.canonicalize_chat_completion`
+  - `resp_process_stage1_tool_governance` → `chat_process.resp.stage7.tool_governance`
+  - `resp_process_stage2_finalize` → `chat_process.resp.stage8.finalize`
+  - `resp_outbound_stage1_client_remap` → `chat_process.resp.stage9.client_remap`
+  - `resp_outbound_stage2_sse_stream` → `chat_process.resp.stage10.sse_stream`
+
+## 6) 待你审阅确认的“修改点清单”
+
+已拍板项（A/B/C/D/E 的决议已合入上文）之外，剩余需要你继续拍板的只有两类“落地细节”：
+
+1. **禁入字段清单的扩展范围**：以 A1 为原则，把哪些 legacy 同义字段逐条加入黑名单（给一个首批 list 即可）。
+2. **环境相关 metadata 的清扫实现策略**：你不想维护名单，所以我建议采用“内部注入字段统一使用 `__*` 前缀，并在 provider/client 边界统一剥离 `__*`”的约束；你确认是否接受这个前缀约束（否则只能回到枚举清扫）。
+
+metadata 生命周期决议（E，需落地到清扫点）：
+- protocol 相关的“可映射语义”：必须进入 chat 字段/`chat.semantics`，不得出现在 outbound 后（请求/响应都一样）。
+- 环境相关的内部注入变量：到 provider 前与 client 前都必须清理掉，不允许出现在 provider request / client response。
+
+你拍板（E1）：环境相关内部注入变量采用 `__*` 前缀约束，并在 provider/client 边界统一剥离所有 `__*`。
+
+实现约束（落地口径）：所有内部 runtime/env 注入变量统一放入 `metadata.__rt`（`__rt` 作为唯一 runtime carrier，天然满足 `__*` 前缀规则），严禁散落为 `metadata.serverToolFollowup/webSearch/clock/...` 这类顶层键。
+
+E1 落地点（已实现）：
+- client→provider（上游请求体）：各协议 `*ProtocolClient.buildRequestBody(...)` 在返回 body 前统一执行 `__*` 剥离（同时这些 client 本身也会移除 `metadata` 字段）。
+  - `src/client/openai/chat-protocol-client.ts`
+  - `src/client/responses/responses-protocol-client.ts`
+  - `src/client/gemini/gemini-protocol-client.ts`
+  - `src/client/gemini-cli/gemini-cli-protocol-client.ts`
+- server→client（JSON 响应体）：HTTP handler 在 `res.json(...)` 前统一剥离 `__*`（SSE carrier `__sse_responses` 走专用分支，不会 JSON 编码）。
+  - `src/server/handlers/handler-utils.ts`
+
+---
+
+关联文档（现有）：
+- `docs/chat-semantic-expansion-plan.md`（语义扩展分阶段计划，和本契约的 3.x 规则一致）
+- `docs/V3_INBOUND_OUTBOUND_DESIGN.md`（inbound/outbound 设计背景）