架构概览
GodeX 是一个网关，将 OpenAI Responses API 请求转换为 Chat Completions API 调用，支持任何已配置的上游 Provider。它采用分层架构，关注点清晰分离：协议处理在边界层，桥接逻辑在中间层，提供商特定代码封装在 spec 和 hooks 中。
本页包含两个互补的视图：请求生命周期（单个请求如何在系统中流转）和 组件模型（构建块是什么、它们如何相互依赖）。理解两者对于调试兼容性问题、添加新 Provider 或扩展桥接层都至关重要。
概览
| 层级 | 组件 | 职责 |
|---|---|---|
| CLI | serve | 引导配置、注册器、ApplicationContext 和 Bun 服务器 |
| 应用 | ApplicationContext | 持有配置、解析器、注册器、会话存储、追踪记录器 |
| 应用 | ApplicationServices | 工厂，连接 logger、ModelResolver、Registrar、ResponsesBridgeRuntime |
| 服务器 | createBuiltinRoutes | 将 /health、/v1/models、/v1/responses 映射到处理函数 |
| 路由 | handleResponses | 解析请求，创建 ResponsesContext，分发 |
| 上下文 | ResponsesContext | 每请求状态：已解析的模型、Provider、会话、诊断信息 |
| 桥接 | ProviderExchange | 构建 Chat Completion 请求，调用上游，记录追踪 |
| 桥接 | ResponsesBridgeRuntime | 选择同步或流式管道 |
| Provider | Registrar | 管理 ProviderEdge 工厂和已解析的实例 |
| 解析器 | ModelResolver | 将模型选择器映射为 (provider, model) 对 |
请求生命周期
核心类型
启动序列
请求处理序列
桥接管道详解
ProviderExchange 内部的桥接管道遵循固定的序列。每一步产生的决策和数据供下游步骤消费：
| 步骤 | 函数 | 输出 |
|---|---|---|
| 1 | planBridgeCompatibility | 兼容性计划，包含参数决策 |
| 2 | planTools | 工具声明、tool_choice、工具决策 |
| 3 | planOutputContract | 响应格式计划（原生、降级或合成） |
| 4 | normalizeCurrentInput + normalizeResponseItems | 标准化的 ChatCompletionMessageParam[] |
| 5 | buildChatMessages | 合并后的助手消息（含工具调用） |
| 6 | applyTools | request.tools 和 request.tool_choice |
| 7 | applyRequestOptions | stream、temperature、top_p、max_tokens、reasoning |
系统组件
完整的请求路径连接了每一层 —— 从 Bun 服务器路由，经过桥接请求构建器、Provider 边界，直到重建层：
核心领域类型及其关系：
层级职责
| 层级 | 模块 | 职责 |
|---|---|---|
| Server | src/server/ | HTTP 路由、请求解析、SSE 编码、错误处理 |
| Context | src/context/ | ApplicationContext（应用级服务）和 ResponsesContext（请求级状态） |
| Bridge | src/bridge/ | 与提供商无关的 Responses-to-Chat 规划与重建 |
| Responses | src/responses/ | 同步和流式编排管道 |
| Provider | src/providers/ | 提供商 spec、hooks、客户端和注册表 |
| Session | src/session/ | 历史持久化和 previous_response_id 链式解析 |
| Resolver | src/resolver/ | 模型别名和 provider/model 选择器解析 |
| Config | src/config/ | YAML 模式、环境变量插值、默认值 |
| Error | src/error/ | 结构化错误层次与域代码 |
依赖流
交叉引用
- 兼容性：桥接如何在构建请求前规划功能兼容性
- 请求构建：从 Responses API 到 Chat Completions API 的逐步转换
- 响应重建：上游响应如何映射回 Responses API 格式
参考
- src/cli/serve.ts:12-62 -- CLI 入口点、服务器引导和关闭处理
- src/context/application-context.ts:10-40 --
ApplicationContext类，持有所有共享服务 - src/context/application-services.ts:1-48 -- 工厂，连接 logger、解析器、注册器、桥接运行时
- src/server/server.ts:21-51 -- 路由映射创建和 Bun 服务器启动
- src/server/routes/responses/handler.ts:1-33 -- Responses 路由处理函数，包含解析、上下文创建和分发
- src/responses/runtime.ts:19-41 --
ResponsesBridgeRuntime委派同步和流式管道 - src/responses/provider-exchange.ts:1-166 --
ProviderExchange编排请求构建和上游调用 - src/providers/registrar.ts:1-95 -- Provider 工厂注册和解析
- src/resolver/model-resolver.ts:1-37 -- 模型选择器解析和别名解析