@jsonstudio/rcc 0.89.1205 → 0.89.1348

package/docs/refactoring/workflow-compatibility-refactoring-design.md

@@ -0,0 +1,361 @@
+# Workflow & Compatibility 模块重构设计方案
+
+## 📋 执行摘要
+
+基于Sysmem架构分析，当前workflow和compatibility模块存在严重的架构违规，包括巨型文件、代码重复、职责不清等问题。本重构方案遵循RouteCodex 9大核心架构原则，将复杂的单体模块拆分为职责明确的小模块。
+
+## 🎯 重构目标
+
+### 核心问题解决
+- **巨型文件拆分**: GLM兼容层从643行拆分为4个专职模块（每个<150行）
+- **代码去重**: 移除与llmswitch-core冲突的工具处理逻辑
+- **简化实现**: Streaming Control从252行简化到50行以内
+- **类型精简**: Field Mapping从10种转换类型减少到3种核心类型
+- **错误处理**: 应用"快速死亡"原则，移除过度try-catch包装
+
+### 架构原则对齐
+- ✅ **原则1**: 确保llmswitch-core作为工具调用唯一入口
+- ✅ **原则2**: 兼容层仅处理provider特定最小功能
+- ✅ **原则4**: 快速死亡，错误立即暴露
+- ✅ **原则7**: 功能分离，模块职责唯一
+- ✅ **原则9**: 模块化，杜绝巨型文件
+
+## 🏗️ 详细设计
+
+### 1. GLM兼容层拆分设计 (643行 → 4个专职模块)
+
+#### 当前问题分析
+```typescript
+// glm-compatibility.ts (643行) - 违规内容
+❌ thinking配置处理 (lines 45-89)
+❌ 响应标准化 (lines 123-278)
+❌ 字段清理 (lines 279-318)
+❌ 过度错误处理 (lines 319-394)
+❌ 工具调用处理 (lines 395-489) - 与llmswitch-core冲突
+```
+
+#### 拆分方案
+
+##### 1.1 GLM Thinking配置模块
+**历史文件**: `src/providers/compat/glm-specialized/thinking-config.ts`
+**职责**: 仅处理GLM特有的thinking模式配置
+**行数**: ~80行
+
+```typescript
+export class GLMThinkingConfig {
+  // 仅处理thinking配置注入
+  applyThinkingConfig(request: any): any;
+
+  // 验证thinking参数
+  validateThinkingParams(config: any): boolean;
+
+  // 生成thinking提示词
+  buildThinkingPrompt(config: any): string;
+}
+```
+
+##### 1.2 GLM响应标准化模块
+**历史文件**: `src/providers/compat/glm-specialized/response-normalizer.ts`
+**职责**: 处理GLM特有的响应字段标准化
+**行数**: ~120行
+
+```typescript
+export class GLMResponseNormalizer {
+  // 字段映射标准化
+  normalizeUsageFields(response: any): any;
+
+  // 时间戳标准化
+  normalizeTimestamps(response: any): any;
+
+  // 模型信息标准化
+  normalizeModelInfo(response: any): any;
+}
+```
+
+##### 1.3 GLM字段清理模块
+**历史文件**: `src/providers/compat/glm-specialized/field-cleaner.ts`
+**职责**: 清理GLM响应中的冗余和特殊字段
+**行数**: ~60行
+
+```typescript
+export class GLMFieldCleaner {
+  // 清理冗余字段
+  removeRedundantFields(response: any): any;
+
+  // 处理特殊字符
+  sanitizeSpecialChars(content: string): string;
+
+  // 字段重命名
+  renameFieldNames(response: any, mapping: Record<string, string>): any;
+}
+```
+
+##### 1.4 GLM兼容性协调器
+**历史文件**: `src/providers/compat/glm-specialized/glm-compatibility-coordinator.ts`
+**职责**: 协调各个GLM专用模块，保持向后兼容
+**行数**: ~90行
+
+```typescript
+export class GLMCompatibilityCoordinator {
+  private thinkingConfig: GLMThinkingConfig;
+  private responseNormalizer: GLMResponseNormalizer;
+  private fieldCleaner: GLMFieldCleaner;
+
+  // 统一的入口点
+  processRequest(request: any): any;
+  processResponse(response: any): any;
+}
+```
+
+### 2. Streaming Control简化设计 (252行 → 50行以内)
+
+#### 当前问题
+```typescript
+// streaming-control.ts (252行) - 过度复杂
+❌ 复杂的状态管理 (lines 23-89)
+❌ 多重转换逻辑 (lines 90-167)
+❌ 过度日志记录 (lines 168-252)
+```
+
+#### 简化方案
+**文件**: `src/modules/pipeline/modules/workflow/streaming-control.ts`
+**行数**: 45行
+
+```typescript
+export class StreamingControl {
+  // 简单的流式判断
+  isStreamingRequest(request: any): boolean {
+    return request.stream === true;
+  }
+
+  // 直接转换，无复杂逻辑
+  convertToStreaming(response: any): any {
+    if (!this.isStreamingRequest(response)) return response;
+    return { ...response, stream: true };
+  }
+
+  // 直接转换，无复杂逻辑
+  convertToNonStreaming(response: any): any {
+    return { ...response, stream: false };
+  }
+
+  // 清理资源，快速失败
+  cleanup(): void {
+    // 直接清理，无try-catch包装
+  }
+}
+```
+
+### 3. 工具处理逻辑移除设计
+
+#### 当前冲突问题
+```typescript
+// glm-compatibility.ts 中的违规实现 (lines 395-489)
+❌ 工具调用格式转换
+❌ 工具文本收割
+❌ 重复调用去重
+// 这些都应该在llmswitch-core中统一处理
+```
+
+#### 移除方案
+1. **删除所有工具处理相关代码** (lines 395-489)
+2. **保留最小provider特定处理**
+```typescript
+// ✅ 允许保留：仅处理GLM特有字段
+export class GLMCompatibility {
+  processResponse(response: any): any {
+    // 仅字段标准化，不处理工具调用
+    return this.normalizeGLMFields(response);
+  }
+}
+```
+
+### 4. Field Mapping类型精简设计 (10种 → 3种核心类型)
+
+#### 当前过度复杂问题
+```typescript
+// field-mapping.ts - 10种转换类型
+❌ 'direct-copy'
+❌ 'type-conversion'
+❌ 'array-mapping'
+❌ 'nested-extraction'
+❌ 'conditional-mapping'
+❌ 'format-conversion'
+❌ 'value-transformation'
+❌ 'default-filling'
+❌ 'validation-mapping'
+❌ 'custom-function'
+```
+
+#### 精简方案
+**历史文件**: `src/providers/compat/field-mapping.ts`（现由 llmswitch-core compat engine 承接）
+**保留3种核心类型**:
+
+```typescript
+// 1. 直接映射 (最常用)
+export interface DirectMapping {
+  type: 'direct';
+  source: string;
+  target: string;
+}
+
+// 2. 类型转换 (必要时)
+export interface TypeConversion {
+  type: 'convert';
+  source: string;
+  target: string;
+  convert: (value: any) => any;
+}
+
+// 3. 默认填充 (兼容性)
+export interface DefaultFill {
+  type: 'default';
+  target: string;
+  defaultValue: any;
+}
+
+// 简化的映射引擎
+export class SimplifiedFieldMapper {
+  applyMappings(data: any, mappings: FieldMapping[]): any {
+    return mappings.reduce((result, mapping) => {
+      switch (mapping.type) {
+        case 'direct': return this.applyDirect(result, mapping);
+        case 'convert': return this.applyConversion(result, mapping);
+        case 'default': return this.applyDefault(result, mapping);
+      }
+    }, data);
+  }
+}
+```
+
+### 5. 快速死亡原则应用设计
+
+#### 当前过度防护问题
+```typescript
+// glm-compatibility.ts (lines 319-394) - 过度try-catch
+try {
+  // 业务逻辑
+} catch (error) {
+  // 复杂的错误恢复逻辑
+  // 静默失败
+  // 状态回滚
+}
+```
+
+#### 快速死亡方案
+```typescript
+export class FailFastGLMCompatibility {
+  processRequest(request: any): any {
+    // 直接验证，失败即终止
+    this.validateRequest(request); // 抛出错误，不捕获
+
+    // 直接处理，不包装
+    return this.transformRequest(request);
+  }
+
+  private validateRequest(request: any): void {
+    if (!request.model) {
+      throw new Error('GLM request must specify model');
+    }
+    // 其他验证...
+  }
+}
+```
+
+## 📊 重构效果预测
+
+### 代码量对比
+| 模块 | 重构前 | 重构后 | 减少比例 |
+|------|--------|--------|----------|
+| GLM兼容层 | 643行 | 350行 (4个模块) | -45% |
+| Streaming Control | 252行 | 45行 | -82% |
+| Field Mapping | 180行 | 80行 | -56% |
+| **总计** | **1075行** | **475行** | **-56%** |
+
+### 架构合规性
+- ✅ 消除所有巨型文件 (>500行)
+- ✅ 模块职责单一明确
+- ✅ 无重复功能实现
+- ✅ 错误处理快速直接
+- ✅ 符合9大架构原则
+
+### 维护性提升
+- **可读性**: 小模块易于理解和维护
+- **可测试性**: 独立模块便于单元测试
+- **可扩展性**: 新功能可独立模块实现
+- **调试友好**: 错误定位更精确
+
+## 🚀 实施计划
+
+### 第一阶段：GLM兼容层拆分 (3天)
+1. 创建4个专职模块文件
+2. 迁移thinking配置逻辑
+3. 迁移响应标准化逻辑
+4. 迁移字段清理逻辑
+5. 创建协调器模块
+6. 更新调用方引用
+
+### 第二阶段：Streaming Control简化 (1天)
+1. 简化streaming-control.ts
+2. 移除复杂状态管理
+3. 移除过度日志记录
+4. 更新相关测试
+
+### 第三阶段：工具处理清理 (1天)
+1. 移除compatibility层工具处理逻辑
+2. 确保llmswitch-core统一处理
+3. 更新配置映射
+4. 验证工具调用流程
+
+### 第四阶段：Field Mapping精简 (1天)
+1. 简化转换类型定义
+2. 重构映射引擎
+3. 更新现有映射配置
+4. 测试兼容性
+
+### 第五阶段：快速死亡应用 (1天)
+1. 移除过度try-catch包装
+2. 实现快速错误抛出
+3. 更新错误处理文档
+4. 验证错误流程
+
+## ⚠️ 风险评估
+
+### 高风险项
+- **向后兼容性**: 模块拆分可能影响现有调用
+- **缓解措施**: 保持协调器模块，API不变
+
+### 中风险项
+- **测试覆盖**: 重构可能影响现有测试
+- **缓解措施**: 同步更新测试，确保覆盖率
+
+### 低风险项
+- **性能影响**: 模块化可能带来微小性能开销
+- **缓解措施**: 基准测试，性能监控
+
+## ✅ 验收标准
+
+### 功能验收
+- [ ] 所有现有功能正常工作
+- [ ] GLM兼容性完全保持
+- [ ] 工具调用流程无变化
+- [ ] 流式处理正常
+
+### 架构验收
+- [ ] 无文件超过500行
+- [ ] 模块职责单一明确
+- [ ] 无重复功能实现
+- [ ] 符合9大架构原则
+
+### 质量验收
+- [ ] 测试覆盖率 > 90%
+- [ ] 无性能回归
+- [ ] 错误处理清晰
+- [ ] 文档更新完整
+
+---
+
+**设计完成时间**: 2025-11-01
+**设计负责人**: Claude Code
+**预计实施时间**: 7天
+**预计代码减少**: 56%

package/docs/reports/routing-classification-report.json

@@ -0,0 +1,24 @@
+{
+  "scanned": 6967,
+  "byCategory": {
+    "default": 562,
+    "tools": 586,
+    "coding": 248,
+    "longContext": 2013,
+    "thinking": 3534,
+    "webSearch": 24,
+    "vision": 0
+  },
+  "neverHit": [
+    "vision"
+  ],
+  "sampleByCategory": {
+    "thinking": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1762999988376_zyns5xw9n_provider-request.json",
+    "longContext": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763000100195_09q89vvi2_provider-request.json",
+    "tools": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002108961_i6ia6jndk_provider-request.json",
+    "webSearch": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002108961_k3ysf83dl_provider-request.json",
+    "coding": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002110308_iyj8j09zq_provider-request.json",
+    "default": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763014458732_3yfsckrin_provider-request.json"
+  },
+  "errors": []
+}

package/docs/reports/routing-classification-report.md

@@ -0,0 +1,18 @@
+# Routing Classification Report
+
+- Scanned: 6967
+- By Category: {"default":562,"tools":586,"coding":248,"longContext":2013,"thinking":3534,"webSearch":24,"vision":0}
+- Never Hit: vision
+
+## Samples
+
+- thinking: /Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1762999988376_zyns5xw9n_provider-request.json
+- longContext: /Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763000100195_09q89vvi2_provider-request.json
+- tools: /Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002108961_i6ia6jndk_provider-request.json
+- webSearch: /Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002108961_k3ysf83dl_provider-request.json
+- coding: /Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002110308_iyj8j09zq_provider-request.json
+- default: /Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763014458732_3yfsckrin_provider-request.json
+
+## Errors
+
+(none)

package/docs/reports/thinking-keywords-report.json

@@ -0,0 +1,19 @@
+{
+  "thinkingSamples": 3572,
+  "keywordHits": {
+    "analysis": 1234,
+    "思考": 1690,
+    "推理": 572,
+    "分析": 2348,
+    "reasoning": 1304,
+    "analyze": 12
+  },
+  "samplePerKeyword": {
+    "analysis": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1762999988376_zyns5xw9n_provider-request.json",
+    "思考": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002108523_9wlgh144y_provider-request.json",
+    "推理": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002108523_9wlgh144y_provider-request.json",
+    "分析": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002108523_9wlgh144y_provider-request.json",
+    "reasoning": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763002387567_v2m2i4vc2_provider-request.json",
+    "analyze": "/Users/fanzhang/.routecodex/codex-samples/openai-chat/req_1763085298297_n028lwxea_provider-request.json"
+  }
+}

package/docs/responses/README.md

@@ -0,0 +1,156 @@
+## OpenAI Responses 通信样本（FC upstream）
+
+本节记录当前已经验证 **可以和 `https://www.fakercode.top/v1/responses` 正常通信** 的典型请求形状，方便后续实现 Responses provider 和 llmswitch-core 路由时参考。
+
+> 最新直通黄金样本：  
+> - `~/.routecodex/codex-samples/openai-responses/req_req-v2-1763955655135-2z91vfddh_request_1_validation_pre.json`（llmswitch 输入）  
+> - `~/.routecodex/codex-samples/openai-responses/req_1763955655139_mhw2j6ao_http-request.json`（/v1/responses 入口）  
+> - `~/.routecodex/codex-samples/openai-responses/req_1763955655143_24f5h9qsj_provider-request.json`（Responses Provider 直通）  
+> 同一时间窗的前序样本（`req_1763955649860_832l5215_http-request.json`、`req_1763955649865_drd7xwttl_provider-request.json` 等）记录了相同请求在路由/Provider 侧的视角，可一起对照，`data` 或 `data.originalData` 即为发送给 FC 的最终载荷。
+
+### 1. 已验证成功的请求形状（摘要）
+
+核心字段结构如下（去掉了大段系统提示与对话文本，只保留结构）：
+
+```jsonc
+{
+  "model": "gpt-5.1",
+  "instructions": "（一段较长的系统说明，定义 Codex CLI 能力与工作模式……）",
+  "input": [
+    {
+      "type": "message",
+      "role": "user",
+      "content": [
+        { "type": "input_text", "text": "……用户提问 1……" }
+      ]
+    },
+    {
+      "type": "message",
+      "role": "user",
+      "content": [
+        { "type": "input_text", "text": "……用户提问 2……" }
+      ]
+    }
+    // 若干 user message，全部使用 type=message + content[].type=input_text
+  ],
+  "tools": [
+    {
+      "type": "function",
+      "name": "shell",
+      "description": "Runs a shell command and returns its output.",
+      "strict": false,
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "command": { "type": "array", "items": { "type": "string" } },
+          "justification": { "type": "string" },
+          "timeout_ms": { "type": "number" },
+          "with_escalated_permissions": { "type": "boolean" },
+          "workdir": { "type": "string" }
+        },
+        "required": ["command"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "type": "function",
+      "name": "list_mcp_resources",
+      "strict": false,
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "cursor": { "type": "string" },
+          "server": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "type": "function",
+      "name": "read_mcp_resource",
+      "strict": false,
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "server": { "type": "string" },
+          "uri": { "type": "string" }
+        },
+        "required": ["server", "uri"],
+        "additionalProperties": false
+      }
+    }
+    // 其余 MCP / update_plan / view_image / mcp__chrome-devtools__* 等函数工具……
+  ],
+  "metadata": {
+    "level": "normal",
+    "hookCount": 1,
+    "successCount": 1,
+    "errorCount": 0
+  },
+  "stream": true
+}
+```
+
+关键结论：
+
+- **模型**：当前推荐使用 `model: "gpt-5.1"`（历史快照中为 `gpt-5`，但通过 Responses SDK 直接回放同一 payload、仅替换模型为 `gpt-5.1`，FC 端同样可以正常工作）。  
+- **instructions 必须存在且较长**：包含系统级 persona 与行为约束；直接省略 instructions 的简化请求在 FC 侧返回 400。  
+- **input 必须是 Responses 规范的 `type: "message"` + `content[].type: "input_text"` 结构，而不是简化版 `messages[]`。  
+- **tools 可以是完整的 Codex 工具集合**（shell + MCP + view_image + chrome-devtools 等），FC 能接受并返回正常响应。  
+- **metadata 可以保留 RouteCodex 自己的统计字段**，对上游兼容无明显影响。  
+- **stream=true + SSE**：该请求在 FC 上下游是以 Responses SSE 事件流的形式返回（`response.created` / `response.output_text.delta` / `response.completed` 等事件）。
+- **工具结果配对只依赖 `call_id`**：OpenAI Responses 规范要求 `function_call` 与 `function_call_output` 仅通过同一 `call_id` 关联，并不会额外携带 `tool_call_id`。RouteCodex 在转换为 Chat 形状时会把 `call_id` 临时映射为 Chat 所需的 `tool_call_id`，但在发给上游或回传客户端前必须把结构还原为“只有 `call_id` 的官方形状”，否则像 c4m / Fai 这类严格实现会直接报 `Unknown parameter: input[].tool_call_id`。
+- **强制开启 streaming：在用户 Provider 配置（例如 `~/.routecodex/provider/fc/config.v1.json`）的 Responses 提供者下添加 `"responses": { "process": "passthrough", "streaming": "always" }`，这样 `ResponsesHttpProvider` 会通过 `responses.streaming` 判定为 `always`，即使入口是 Anthropic/Messages 也会对上游（如 Fai/c4m）以 SSE 模式发送请求。**
+
+### 2. 失败的简化请求形状（对比）
+
+在本仓库中使用 `scripts/fc-responses-tool-loop.mjs` 进行了多次实验：
+
+- 仅包含 `model + input[ { role, content[input_text] } ] + stream` 的最简 SSE 请求 → **400 `openai_error`**。  
+- 在最简请求中补充 `instructions` 与简单 `tools`（单个 echo 工具） → 仍然 **400 `openai_error`**。  
+
+结论：  
+目前 FC 的 `/v1/responses` 接口更接近“完整 Codex Responses 负载”的使用方式，对字段组合/shape 较敏感；**简单缩减字段容易 400**。因此：
+
+- 调试 / 文档中应优先使用已验证的完整样本形状；  
+- 如需精简，请务必通过快照 + 对比方式逐步删减字段，每删一类字段都重新验证 FC 是否仍返回 2xx。
+
+### 3. 通过 Responses SDK 回放快照（SSE 事件形状）
+
+使用 `scripts/fc-responses-from-snapshot.mjs` 可直接读取上述快照的 `originalData`，经 OpenAI Responses SDK 调用 FC `/v1/responses`：
+
+```bash
+FC_API_KEY=... FC_MODEL=gpt-5.1 \
+node scripts/fc-responses-from-snapshot.mjs \
+  ~/.routecodex/codex-samples/openai-responses/req_req-v2-1763955655135-2z91vfddh_request_1_validation_pre.json
+```
+
+在成功场景下，SDK 报告的事件分布如下（节选）：
+
+```jsonc
+{
+  "response.created": 1,
+  "response.in_progress": 1,
+  "response.output_item.added": 2,
+  "response.reasoning_summary_part.added": 3,
+  "response.reasoning_summary_text.delta": 329,
+  "response.reasoning_summary_text.done": 3,
+  "response.reasoning_summary_part.done": 3,
+  "response.output_item.done": 2,
+  "response.function_call_arguments.delta": 73,
+  "response.function_call_arguments.done": 1,
+  "response.completed": 1
+}
+```
+
+说明：
+
+- FC 在 Responses wire 上使用的是 **标准 `response.*` 事件族**，包含 reasoning 与 function_call_arguments 相关事件；  
+- monitor / provider 在做直通时，必须完整透传这些事件，而不能只假定存在 `response.output_text.delta`；  
+- 该事件分布可作为后续设计 `responses-standard` provider 与 llmswitch-core SSE 直通逻辑时的“金标准”参考。
+
+### 4. 与 RouteCodex / llmswitch-core 的关系
+
+- 通过 `routecodex monitor` + `monitor.json.transparent.wireApi = "responses"`，当前 monitor 路径会把 Codex 客户端产生的完整 Responses JSON **原样透传**到 FC `/v1/responses`，并在本地记录快照：  
+  - `http-request` / `http-request.parsed` / `monitor.upstream-request` / `monitor.upstream-response` / `monitor.http-response`。  
+- 这类样本为后续实现 **Responses provider + llmswitch-core responses 直通路由** 提供了可靠的“金标准负载”，后续设计将以此为基线，不再依赖简化/猜测字段。

package/docs/responses-generic-provider.md

@@ -0,0 +1,86 @@
+# OpenAI Responses 透传通路（generic-responses）设计说明
+
+目标
+- 在 `/v1/responses` 下提供一条“严格透传”的 Responses 流水线：请求/响应完全遵循 OpenAI Responses 规范，无跨协议转换、无兜底。
+- 在 `./sharedmodule` 的配置模块中新增 provider 家族 `generic_responses`，由配置引擎解析 `config.toml` 并产出 `virtualRouter`/`targetRuntime`（经 `bootstrapVirtualRouterConfig` 生成）；本仓仅消费该产物并完成模块接线。
+
+配置（config.toml 输入）
+- provider
+  - `[model_providers.generic_responses]`
+  - `name = "generic_responses"`
+  - `base_url = "https://api.example.com/v1"`
+  - `env_key = "GENERIC_RESPONSES_API_KEY"`
+  - `wire_api = "responses"`
+- 路由
+  - `[routes.responses]`
+  - `default = "generic_responses"`
+- 可选 key 映射
+  - `[keys.providers.generic_responses]`
+  - `key1 = "GENERIC_RESPONSES_API_KEY"`
+
+sharedmodule 改动（配置引擎与兼容映射）
+- config-engine（解析/校验）
+  - 新增 family: `generic_responses` 的 schema 与解析逻辑。
+  - 校验必填：`base_url`、`env_key`、`wire_api=responses`。
+  - 归一化输出 provider 记录：`type: "generic-responses"`，`config: { baseUrl, auth: { apiKey: "${GENERIC_RESPONSES_API_KEY}" } }`。
+  - 解析 `[routes.responses]`，校验 `default` 指向有效的 `generic_responses` provider。
+- config-compat（生成装配输入）
+  - pipelines += `openai.responses.generic`：
+    - `llmSwitch: { type: "llmswitch-responses-passthrough" }`
+    - `provider: { type: "generic-responses", config: { baseUrl, auth: { apiKey }, compatibilityProfile: "compat:passthrough" } }`
+  - routePools["/v1/responses"] = ["openai.responses.generic"].
+  - routeMeta["openai.responses.generic"] = `{ providerId: "generic_responses", modelId: "responses", keyId: "key1" }`。
+  - compatibilityProfile 由 provider 记录直接传给 Hub Pipeline（llmswitch-core 在 `compat:passthrough` 情况下等价于 no-op）。
+  - compatibilityConfig.keyMappings.providers.generic_responses.key1 = `${GENERIC_RESPONSES_API_KEY}`。
+  - 严格模式：未配置 `routes.responses` 时不生成上述管线/路由。
+- config-testkit（如有）
+  - 新增用例：最小配置、缺失 routes.responses、env_key 注入校验。
+
+virtualRouter 期望（关键片段）
+- `virtualRouter.routing["/v1/responses"]` 指向 `openai.responses.generic`。
+- `virtualRouter.pipelines` 包含：
+  - id: `openai.responses.generic`
+  - modules:
+    - `llmSwitch: { type: "llmswitch-responses-passthrough", config: {} }`
+    - `provider: { type: "generic-responses", config: { baseUrl, auth: { apiKey }, compatibilityProfile: "compat:passthrough" } }`
+- `targetRuntime["openai.responses.generic"]` = `{ providerId: "generic_responses", modelId: "responses", keyId: "key1", ... }`。
+- `keyMappings.providers.generic_responses.key1 = "${GENERIC_RESPONSES_API_KEY}"`。
+
+本仓接线与运行时模块
+- Provider：
+  - `src/providers/core/runtime/responses-provider.ts`：完整 Responses SSE 透传实现，负责 real-time `/responses` 请求、上游 SSE → Host JSON 的转换，以及快照写入。
+  - `src/providers/core/runtime/responses-http-provider.ts`：OpenAI Responses HTTP 直连 Provider（继承 `ChatHttpProvider`，统一通过 provider 层发送请求）。
+- LLMSwitch：`llmswitch-responses-passthrough`
+  - 逻辑位于 `sharedmodule/llmswitch-core`，Host 仅通过 `src/modules/llmswitch/bridge.ts` 间接调用，保持“llmswitch-core owns routing/tools”的约束。
+- 模块注册
+  - 由 llmswitch-core 的 pipeline registry 统一管理，Host 不再手动注册 Provider/LLMSwitch 组合，避免与 `bootstrapVirtualRouterConfig` 产物冲突。
+- 装配器消费
+  - 管线装配逻辑也在 llmswitch-core 内，Host 仅接收 virtualRouter + targetRuntime 并实例化 provider/runtime。
+- Handler 路由
+  - `src/server/handlers/responses-handler.ts` 按 virtualRouter pipelines 选择 `openai.responses.*` 管线处理 `/v1/responses`，禁用兜底。
+- Streaming
+  - Responses SSE 的透传/解析由 `src/providers/core/runtime/responses-provider.ts` 直接处理（Provider 层解析 SSE，再回写 JSON 响应）。
+
+校验与错误策略
+- 请求：缺失必填字段/类型不符 → 400（conversion_error），不 fallback 到 Chat。
+- 响应：原样返回；SSE 事件名/载荷/顺序不改动；解析失败 → 中断并映射 502。
+- 工具链：`required_action.submit_tool_outputs` 原样透传，不文本化。
+
+落盘与回放
+- 目录：`~/.routecodex/codex-samples/responses-replay`。
+- 文件：`raw-request_req_*.json`、`provider-out-generic_*.json`、`sse-events-<RID>.log`。
+- 脚本（新增）：
+  - `scripts/verify-responses-passthrough.mjs`：对比 raw-request 与 provider-out 正文字段一致（headers/trace 差异允许）。
+  - `scripts/replay-responses.mjs`：批量回放样本校验一致性。
+
+执行计划
+1) sharedmodule/config-engine：
+   - 新增 family `generic_responses` 的 schema 与解析；解析 `[routes.responses]`；输出规范 provider 与 routes。
+2) sharedmodule/config-compat：
+   - 生成 `openai.responses.generic` 管线与 routePools/routeMeta/keyMappings；严格模式无 fallback。
+3) 本仓接线：
+   - Provider `generic-responses`、LLMSwitch `llmswitch-responses-passthrough` 实现与注册；Assembler 放行类型；Responses Handler 固定直通；不再注入 host-side compatibility 模块。
+4) 校验工具：
+   - 新增 `scripts/verify-responses-passthrough.mjs`、`scripts/replay-responses.mjs`；准备 10 非流 + 10 流式样本自检。
+5) 文档与发布：
+   - 更新 README/变更日志；bump 版本，构建与全局安装（不自启动）。