开发者指南

开发者指南

本章节面向修改 ProxAI 内部实现的维护者，重点是源码边界、协议转换规则、流式行为和错误投影。

内部文档

这些页面描述实现边界。面向用户的行为应放在 使用 ProxAI、协议指南 和 参考。

核心边界

1. 1
   ingress

   模块

   src/ingress/src/protocol/

   职责

   检测入站协议、解析 payload，并规范化入站请求形状。

2. 2
   routing

   模块

   src/config.rspipeline routing

   职责

   通过协议感知 defaults 或显式模型 route 选择 provider。

3. 3
   translation

   模块

   src/translation/

   职责

   在纯协议边界上转换协议 payload 和 streams。

4. 4
   provider

   模块

   src/provider/*/requestsrc/provider/*/transport

   职责

   准备 provider request payload、改写模型、添加 provider auth、构造上游 URL 并发送。

5. 5
   response reconstruction

   模块

   src/http_supportsrc/error/

   职责

   把响应翻译回入站协议，并渲染紧凑的客户端错误。

源码目录地图

src/ingress/

入站 HTTP path/protocol 检测、请求解析，以及 routing 前的 normalization。

src/protocol/

OpenAI Responses、OpenAI Chat Completions、Anthropic Messages 和 SSE payload 的 wire data models。

src/translation/

显式 pair 之间的纯协议 payload 和 stream 转换。

src/provider/*/request

Provider request preparation、projection、provider model rewrite 和 outbound payload serialization。

src/provider/*/transport

上游 URL 构造、provider authentication headers 和 HTTP send 行为。

src/provider/*/response

Provider response summaries、streaming observers、协议状态机和 outcome diagnostics。

src/http_support/

response header/body reconstruction 和 byte streams 的 HTTP carrier helpers。

src/error/

内部 typed errors 和紧凑的客户端 HTTP/SSE error rendering。

src/observe/

结构化日志、request hints、duration coloring 和 capture-safe diagnostics。

页面

架构请求生命周期、模块边界、pipeline 阶段，以及协议转换如何接入代理链路。请求生命周期从入站请求、provider transport 到出站响应的源码级路径。协议转换面向协议 pair 的转换规则、wire model 对齐、SDK 比对和流式标识模型。流式内部实现carrier、BodyObserver、SSE scanner 与协议状态机。错误处理内部实现强类型错误、ErrorResponseSpec、fields、payload 与 HTTP/SSE 渲染。该改哪里面向 source owners、测试、验证和随实现移动的文档的任务地图。测试地图配置、路由、转换、流式、错误、capture 和文档变更的验证指南。贡献者检查清单运行时配置、转换 pair、流式、错误、测试和文档的操作清单。文档维护文档职责、双语页面、MDX 组件、验证和 source-of-truth 边界规则。

改动地图

新增运行时配置

更新 src/config.rs、config.example.toml、用户文档、reference 文档，以及 generated defaults 测试。

该改哪里

修改 routing、provider、translation、streaming、error、capture 或 docs internals 前，先看任务化源码地图。

测试地图

先选择最窄验证命令，再为用户可见 proxy 或 streaming 行为扩大验证。

新增转换 pair

补齐 request/response/streaming conversion、route 支持、行为测试和协议文档。

修改 streaming

检查 carrier 语义、SSE terminal events、tool-call stalls、Unicode chunk scanning 和 e2e 测试。

修改错误渲染

更新错误投影、保留 headers、SSE error 行为和行为契约。