# 请求路由 – 当前状态报告

## 概览

本报告梳理本项目中“请求从 HTTP 进入到外部服务”的实际执行路径，聚焦已有的服务器/路由/Provider 组件与 `src/modules/pipeline` 下的模块化流水线代码，指出当前生效路径、尚未接入的能力、存在的差距与风险，并给出可落地的改进建议与关键文件定位。

要点摘要：
- 目前生效的是“直通转发”路径：HTTP Server → OpenAI Router → Pass‑Through Provider → 外部 OpenAI API。
- 模块化流水线（LLM Switch、Compatibility、Provider、Pipeline Manager）代码已存在于 `src/modules/pipeline`，但尚未被 HTTP 服务实际调用。
- Anthropic 端点已挂载但返回 501（占位占位符）。
- Virtual Router 与配置驱动分类逻辑存在，但未接入到 HTTP 请求链路中。

---

## 实际运行路径

1) 启动与 HTTP Server 挂载
- 程序入口初始化并启动 HTTP Server：
  - `src/index.ts:69`, `src/index.ts:70`, `src/index.ts:76`
- 将 OpenAI 路由挂载到 `/v1/openai/*`：
  - `src/server/http-server.ts:518`

2) OpenAI Chat Completions（非流式）
- 路由注册：
  - `src/server/protocol-handler.ts:139`
- 处理函数直接调用“直通 Provider”（未经过 LLM Switch / Compatibility）：
  - `src/server/protocol-handler.ts:244`
- 将返回值直接写回客户端：
  - `src/server/protocol-handler.ts:269`

3) Pass‑Through Provider（直通转发）
- 目标地址为 `targetUrl + path`，默认 `targetUrl` 指向 OpenAI 官方 API（如未通过构造参数覆盖）：
  - 默认取值位置：`src/server/protocol-handler.ts:89`
- Chat 请求通过 Provider 层 `forwardRequest('/chat/completions', ...)` 直接转发：
  - `src/providers/core/runtime/chat-http-provider.ts:154`
- 实际发起 HTTP 请求与头处理：
  - `src/providers/core/runtime/chat-http-provider.ts:520`
- 如果原始请求头中带授权信息，会被透传。

4) 流式（SSE）
- 当前在 Router 内为“本地模拟流式”，并非真实上游 SSE 透传：
  - `src/server/protocol-handler.ts:812`

5) Anthropic 端点
- 已挂载 `/v1/anthropic/*`，但固定返回 501：
  - `src/server/http-server.ts:521`

---

## 模块化流水线能力 vs. 当前使用

目标链路（概念）：LLM Switch → Compatibility → Provider → 外部服务

- LLM Switch（分类/协议识别与转换）
  - 已有：OpenAI→OpenAI 规范化、Anthropic→OpenAI 映射。
    - `src/modules/pipeline/modules/llmswitch/openai-normalizer.ts`
    - `src/modules/pipeline/modules/llmswitch/anthropic-openai-converter.ts`
  - 现状：HTTP 服务未调用。

- Compatibility（格式转换）
  - 已有：LM Studio 等兼容模块与 JSON 规则驱动的变换引擎（现全部驻留在 llmswitch-core compat profiles 中）。
> ⚠️ 2025-12 更新：`src/providers/compat/*` 已下线；兼容行为现由 `sharedmodule/llmswitch-core/src/conversion/compat/` 提供，旧行号仅供历史排查参考。
  - 历史辅助引擎：`src/modules/pipeline/utils/transformation-engine.ts`
  - 现状：HTTP 服务未调用。

- Provider（标准 HTTP 通信、无格式转换）
  - 已有：统一的 Chat/Responses Provider 实现。
    - `src/providers/core/runtime/chat-http-provider.ts:15`
    - `src/providers/core/runtime/responses-http-provider.ts:15`
  - 现状：HTTP 路径应直接复用上述 Provider（由 Hub Pipeline 装配器管理），避免额外的直连/PassThrough 实现。

- 流水线编排
  - 已有：`BasePipeline` 将 LLM Switch → Workflow → Compatibility → Provider 串联，并在响应端做反向处理：
    - `src/modules/pipeline/core/base-pipeline.ts:119`
  - 管理/注册器存在，但未接入 HTTP Server：
    - `src/modules/pipeline/core/pipeline-manager.ts`
    - `src/modules/pipeline/core/pipeline-registry.ts`

---

## 配置情况

- 用户 `~/.rcc/config.json`（或 `ROUTECODEX_CONFIG_PATH` 指定的文件）由 `bootstrapVirtualRouterConfig` 直接解析，得到 `virtualRouter` + `targetRuntime`，HTTP 服务按该结果构造 Hub Pipeline 与 Provider。
- OpenAI Router 中的 `targetUrl` 由构造参数/默认值直接决定，并非来自 `modules.json`：
  - `src/server/protocol-handler.ts:89`

---

## Virtual Router 与分类（未接入 HTTP 路径）

- Virtual Router 模块提供：
  - 配置驱动的请求分类（default/longContext/thinking/coding/webSearch 等）。
  - 基于 provider.model 与 key 的负载均衡。
- 代表性位置：
  - 模块入口：`src/modules/virtual-router/virtual-router-module.ts:19`
  - 分类与路由选择：`src/modules/virtual-router/virtual-router-module.ts:288`
  - 分组/负载均衡：`src/modules/virtual-router/virtual-router-module.ts:646`

这些逻辑目前未与 `/v1/openai` 路径串联。

---

## 响应返回结构

- 直通路径下，Router 将 `PassThroughProvider.processChatCompletion` 的返回对象直接 `res.json` 给客户端。该对象是 Provider 自定义的 `ProviderResponse` 包装，含 `success/data/error/usage` 等字段，真实上游的 OpenAI JSON 在 `data` 字段内：
  - 写回位置举例：`src/server/protocol-handler.ts:269` 等

如需“完全 OpenAI 兼容”输出，应考虑在最终响应前去掉外层包装或改用严格对齐的响应结构。

---

## 差距与风险

- 模块化流水线未接入：请求未经过 LLM Switch / Compatibility 模块，Provider 也非模块化 Provider。
- Anthropic 端点仅为占位（501），多协议/多提供商能力未成闭环。
- 流式为本地模拟，缺少真实上游 SSE 透传。
- OpenAI `targetUrl` 未配置化读取 `modules.json`，多环境/多 Provider 的灵活性受限。
- Virtual Router 与分类未与 HTTP 链路整合，7 类路由能力无法在运行时发挥作用。

---

## 建议

1) 将 HTTP Server 接入流水线管理器
- 在请求进入时交给 `PipelineManager`，调用 `BasePipeline.processRequest`，串联 LLM Switch →（Workflow 可选）→ Compatibility → Provider。

2) 引入“智能选择”
- 使用 `HttpServer` 中的配置驱动 `RouteResolver`（`src/server/http-server.ts`），根据分类器与路由表选择合适的 LLM Switch（如 OpenAI→OpenAI 或 Anthropic→OpenAI）。

3) `targetUrl` 与 Provider 选择配置化
- 将 Provider 基础地址、鉴权、模型路由统一由 `config/modules.json`（合并配置）驱动，而非在 Router 中硬编码默认值。

4) 完成 Anthropic 端到端闭环
- 通过模块化链路完成 `anthropic →（LLM Switch）→ Compatibility → Provider` 的全链路调用，以验证多协议能力。

5) 升级流式为真实上游透传
- 在 Provider 层对接真实流式，并在 Router 层进行透传，输出严格兼容的 OpenAI SSE。

6) 激活 Virtual Router 智能路由
- 可选：在流水线选择前加入 Virtual Router 的分类逻辑，将请求映射到 7 类路由，并选择相应的流水线配置。

---

## 关键文件参考

- 服务器与路由
  - HTTP Server 挂载：`src/server/http-server.ts:518`
  - Anthropic 占位：`src/server/http-server.ts:521`
  - OpenAI Chat 路由：`src/server/protocol-handler.ts:139`
  - 直通调用位置：`src/server/protocol-handler.ts:244`
  - 响应写回：`src/server/protocol-handler.ts:269`

- 直通 Provider
  - 转发与 fetch：`src/providers/core/runtime/chat-http-provider.ts:520`

- 流水线（已实现但未接入 HTTP 路径）
  - BasePipeline 主链路：`src/modules/pipeline/core/base-pipeline.ts:119`
  - LLM Switch（OpenAI 直通）：`src/modules/pipeline/modules/llmswitch/openai-passthrough.ts:15`
- 历史兼容层（LM Studio）：`src/providers/compat/lmstudio-compatibility.ts:16`
  - Provider（Chat/Responses）：`src/providers/core/runtime/chat-http-provider.ts:15`
- 智能选择（格式识别/选择）：`src/server/http-server.ts` 提供的 `ConfigRequestClassifier` + RR 组合逻辑

- Virtual Router 与分类
  - 模块：`src/modules/virtual-router/virtual-router-module.ts:19`
  - 路由选择与转换：`src/modules/virtual-router/virtual-router-module.ts:288`
  - 负载均衡：`src/modules/virtual-router/virtual-router-module.ts:646`

- 配置
  - 模块配置：`config/modules.json`
  - 虚拟路由引导：`src/config/routecodex-config-loader.ts` + `llmswitch-core/v2/router/virtual-router/bootstrap.ts`

---

## 附录：端到端路径示意

- 当前生产路径（非流式）：
```
HTTP Server → OpenAI Router → Pass‑Through Provider → OpenAI API → OpenAI Router → Client
```

- 目标模块化路径（OpenAI 直通示例）：
```
HTTP → PipelineManager → BasePipeline
  → LLM Switch（openai‑passthrough）
  → Workflow（可选）
  → Compatibility（按 Provider 适配）
  → Provider（标准 HTTP）
  → 外部服务
  ← 反向转换 → Client
```

- 目标模块化路径（Anthropic → OpenAI 转换示例）：
```
HTTP → PipelineManager → BasePipeline
  → LLM Switch（anthropic‑openai‑converter）
  → Compatibility（工具/字段格式适配）
  → Provider（标准 HTTP）
  → 外部服务
  ← 反向转换 → Client
```

---

## 下一步（可选）
如需，我可以：
- 将 Router 的直通处理切换为经由 PipelineManager（同时保留“直通模式”作为可配置选项）。
- 引入 SmartPipelineFactory/Selector，按 URL/请求体自动选择 LLM Switch。
- 将 Provider 端点、鉴权、模型与路由统一改为配置驱动。
- 实现真实流式透传与 Anthropic 的完整模块化链路。