公共 API 请求和传输架构

fn from(v: VerbosityConfig) -> Self

作用：把项目内部配置里的“回答详细程度”转换成 OpenAI 请求里使用的详细程度值。有人要把配置写进 API 请求时会用到它。

数据流：进去的是一个 VerbosityConfig，也就是内部配置里的低、中、高。函数逐项对应：低变成 Low，中变成 Medium，高变成 High。出来的是 OpenAiVerbosity，之后可以被序列化成请求里的 JSON 字段。

调用关系：它是一个类型转换入口。create_text_param_for_request 在组装 text 参数时，会通过通用转换机制用到它，把用户或配置里的详细程度放进真正要发给服务器的请求里。

fn from(request: &ResponsesApiRequest) -> Self

作用：把普通 Responses API 请求复制并改造成 WebSocket 版本的 response.create 请求内容。这样同一份请求信息不用手工重新拼一遍。

数据流：进去的是一个 ResponsesApiRequest 的引用，里面有模型、指令、输入、工具、是否流式、推理参数、文本控制等字段。函数把这些字段克隆到新的 ResponseCreateWsRequest 里，并把 WebSocket 专用或可选字段设置好，比如 previous_response_id 和 generate 先留空。出来的是可发送到 WebSocket 的请求结构。

调用关系：它会在 stream_responses_websocket 准备通过 WebSocket 发起响应创建时被调用。它不负责真正联网，只负责把“普通请求单”改写成“WebSocket 请求单”，之后交给发送 WebSocket 消息的流程。

调用图：被 1 处调用（stream_responses_websocket）。

fn response_create_client_metadata(
    client_metadata: Option<HashMap<String, String>>,
    trace: Option<&W3cTraceContext>,
) -> Option<HashMap<String, String>>

作用：把已有的客户端元数据和链路追踪信息合并起来，生成要随请求发送的 metadata。这样后台排查问题时，能把客户端这次请求和服务端日志串起来。

数据流：进去的是可选的 HashMap 元数据，以及可选的 W3cTraceContext。W3cTraceContext 可以理解成网页和服务之间通用的“包裹追踪号”。函数先拿已有元数据，没有就建一个空表；如果 traceparent 或 tracestate 存在，就用固定 key 写进去。最后如果表还是空，就返回 None；如果有内容，就返回这个表。

调用关系：它属于请求组装前的小助手。调用方在创建 response.create 请求时可以先用它补齐追踪字段，再把结果放进 ResponsesApiRequest 或 ResponseCreateWsRequest 的 client_metadata。

fn create_text_param_for_request(
    verbosity: Option<VerbosityConfig>,
    output_schema: &Option<Value>,
    output_schema_strict: bool,
) -> Option<TextControls>

作用：按需要创建请求里的 text 控制参数，用来告诉服务器回答要多详细，以及是否必须按指定 JSON 结构输出。

数据流：进去的是可选的详细程度、可选的输出 JSON Schema，以及 strict 开关。JSON Schema 可以理解成“规定 JSON 长相的模板”；strict 表示是否严格按模板检查。函数如果发现两者都没有，就直接返回 None，避免请求里多放空字段；否则生成 TextControls，里面可能包含 verbosity，也可能包含格式要求。出来的是可选的 TextControls。

调用关系：它通常在构造 API 请求时被调用。它会借助 OpenAiVerbosity::from 完成详细程度转换，然后把结果交给请求结构的 text 字段，让后续 HTTP 或 WebSocket 发送流程使用。

fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>

作用：让 ResponseStream 像标准异步流一样吐出下一条服务器事件。外部代码不用关心里面其实是一个消息通道。

数据流：进去的是流本身和异步运行时给的唤醒上下文。函数去内部的 rx_event 接收通道里尝试拿下一条消息：可能拿到一个 ResponseEvent，也可能拿到 ApiError，也可能暂时没准备好或已经结束。出来的是 Poll 包装的下一项结果。

调用关系：它是 ResponseStream 接入 Rust 异步 Stream 机制的关键点。外部消费流时会间接调用它；它把具体工作交给底层接收器的 poll_recv，用通道里已有的事件驱动上层的流式响应处理。

调用图：外部调用 1 个（poll_recv）。

fn from(err: RateLimitError) -> Self

作用：这个函数把 RateLimitError 转成 ApiError，让“限流错误”可以自然地进入统一的 API 错误体系。有人在调用 API 时遇到限流，就不用单独处理另一套错误类型。

数据流：进去的是一个 RateLimitError，也就是表示请求太频繁的错误。函数把这个错误转成文字说明，再包进 ApiError::RateLimit 这个统一错误种类里。出来的是一个 ApiError，同时原始错误不会再以原类型继续向外传，而是变成 API 层统一认识的错误。

调用关系：它通常在其他代码用问号运算符或自动错误转换时被触发，相当于错误传递路上的一个“翻译员”。它会读取 RateLimitError 的内容，并调用 to_string 把它变成可展示的文字，然后交给 ApiError::RateLimit，方便上层按统一方式处理。

调用图：外部调用 2 个（RateLimit, to_string）。

fn parse_realtime_event(
    payload: &str,
    event_parser: RealtimeEventParser,
) -> Option<RealtimeEvent>

作用：这个函数把 WebSocket 收到的一段原始文字消息，转换成程序能理解的实时事件。它的价值在于屏蔽协议版本差异：调用者不用自己判断该走 v1 还是 v2 的解析规则。

数据流：进去的是一段消息文本 payload，以及一个表示解析版本的 event_parser。函数查看 event_parser：如果是 V1，就把文本交给 parse_realtime_event_v1；如果是 RealtimeV2，就交给 parse_realtime_event_v2。出来的是一个可选的 RealtimeEvent：能认出来就返回具体事件，认不出来或格式不对就返回空值，不会硬造一个错误事件。

调用关系：它被 next_event 调用，通常发生在 WebSocket 连接等待下一条消息时。它自己不真正拆 JSON 细节，而是把活儿转交给 parse_realtime_event_v1 或 parse_realtime_event_v2；这样读取消息的流程保持简单，具体协议变化则集中在各版本解析器里。

调用图：调用 2 个内部函数（parse_realtime_event_v1, parse_realtime_event_v2）；被 1 处调用（next_event）。