开发者指南

开发者指南

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

内部文档

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

核心边界

1. 1
   core pipeline

   模块

   crates/proxai-core/src/pipeline/src/pipeline/

   职责

   Core 组合结构化 ingress、routing、translation 与 provider adaptation，应用层负责 HTTP carrier 和 transport。

2. 2
   ingress

   模块

   src/pipeline/inbound.rscrates/proxai-core/src/ingress/

   职责

   应用 adapter 检测入站协议并解析 HTTP bytes，core 再对结构化 payload 做归一化和校验。

3. 3
   routing

   模块

   src/config.rscrates/proxai-core/src/pipeline/

   职责

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

4. 4
   translation

   模块

   crates/proxai-core/src/translation/

   职责

   在不引入 HTTP carrier 的边界内转换协议 payload 和 stream；合法适配发出类型化 observation。

5. 5
   provider

   模块

   crates/proxai-core/src/provider/src/provider/*/requestsrc/provider/*/transport

   职责

   在 core 中准备结构化 provider value，再由应用层完成 projection、序列化、认证和发送。

6. 6
   response reconstruction

   模块

   src/http_supportsrc/error/

   职责

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

源码目录地图

src/pipeline/inbound.rs

入站 HTTP path/protocol 检测、JSON bytes 解析和应用错误映射。

crates/proxai-core/src/pipeline/

Carrier-independent request/response composition façade 和 request-scoped core observer 绑定。

crates/proxai-core/src/ingress/

与 carrier 无关的请求归一化、协议校验、模型提取和类型化 ingress observations。

crates/proxai-core/src/observe.rs

共享 `Observer` contract、封闭的 `Observation` variants 和 no-op 默认实现。

crates/proxai-core/src/protocol/

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

crates/proxai-core/src/translation/

显式 pair 之间与 carrier 无关的协议 payload 和 stream 转换，并发出类型化 adaptation observation。

crates/proxai-core/src/provider/

与 carrier 无关的 provider request value preparation、结构化响应/错误 normalization 和类型化 adaptation observations。

src/provider/*/request

Provider 日志 projection/summary 提取、outbound payload 序列化和 request carrier 组装。

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 行为和行为契约。