AI SDK 升级后，哪些代理连接和请求行为需要重新验证

SDK 升级的回归范围，取决于这次实际换了哪一层。可能只是 SDK 版本变化，也可能连底层 HTTP 客户端和代理 agent 一起换了。代理 IP 的接入方式也可能被顺手改掉。先确认改动层级，再按固定清单逐项验证，避免只测一次“能请求成功”就算完成。测试使用测试账号和测试额度，具体行为以目标 SDK 的发布说明为准。

升级了运行时、SDK 还是 HTTP 客户端？

先看依赖变更清单，确认本次升级触及哪些层：

• 层级：SDK 自身 ｜ 典型变化：版本号、方法签名、默认参数 ｜ 影响：请求构造与重试策略
• 层级：HTTP 客户端 ｜ 典型变化：undici、axios、net/http 或底层库版本 ｜ 影响：连接复用、代理支持、超时语义
• 层级：代理 agent ｜ 典型变化：http-proxy-agent、HTTPS_PROXY 处理 ｜ 影响：代理参数是否被真正应用

只升了 SDK，但底层客户端被提升了大版本，回归范围应按底层算。锁文件里同时变化时，尤其要看清。

SDK 升级后，哪些代理行为需要重新测试？

用下表确定回归范围，后续各节按项目展开：

• 行为：认证头透传 ｜ 怎么观察：抓包看目标域，代理与上游是否各带各的头 ｜ 展开位置：认证透传与重定向
• 行为：跨域重定向 ｜ 怎么观察：重定向到其他域名后是否仍带认证头 ｜ 展开位置：认证透传与重定向
• 行为：连接复用 ｜ 怎么观察：连续请求是否复用同一连接 ｜ 展开位置：连接复用、TLS 与超时重试
• 行为：超时语义 ｜ 怎么观察：建连、首字节、整体三类超时是否各按预期触发 ｜ 展开位置：连接复用、TLS 与超时重试
• 行为：重试行为 ｜ 怎么观察：失败后实际发出的请求次数与退避间隔 ｜ 展开位置：连接复用、TLS 与超时重试
• 行为：流式响应 ｜ 怎么观察：是否逐块到达、代理是否缓冲 ｜ 展开位置：流式响应与 SSE
• 行为：代理参数优先级 ｜ 怎么观察：显式参数、环境变量、默认值谁生效 ｜ 展开位置：代理参数优先级与环境变量

清单固定的好处是：下次升级可以逐项打勾，不用重新想测什么。

升级后认证信息和重定向是否仍按预期工作？

代理认证（Proxy-Authorization）发给代理，上游认证（Authorization）发给授权 API；跨域重定向时应确认上游凭据没有带到新域名。

出现 401 时应核对上游鉴权，而不能因代理可达就排除密钥失效。检查请求目标、脱敏后认证头是否存在、密钥状态、scope/项目配置及服务方错误体。只记录头名称、发送目标域和“是否存在”的脱敏状态，不记录 Authorization 与 Proxy-Authorization 的取值。

怎么检查连接复用、TLS 和超时重试变化？

这三项决定“看起来成功、实际重复请求”的问题，也是升级后语义最容易变的三个地方。

• 连接复用：优先看客户端连接池的连接创建、复用与关闭事件，或服务端连接 ID 与受控代理日志；ss -tnp 里的 TIME_WAIT 数量只能作旁证，不能代表复用率；
• 超时：先按被测 SDK/HTTP 客户端列出实际支持的超时类型、默认值与范围；对可独立配置的阶段用受控延迟验证，整体 deadline 单独记录。客户端只有总超时不自动代表回归缺陷；比较升级前后相同的超时契约，并注明无法独立观测的阶段；
• 重试：为每次业务调用设置测试关联 ID，分别记录客户端发送尝试、重定向、服务端接收和业务处理事件，按关联 ID 对齐后识别重试与重放；请求计数差额只能当线索，并发、日志丢失、取消和代理重放都会让它失真。

若超时类型或默认值改变，整体等待时间可能随之变化；应按实际客户端支持项逐一核对。

TLS 行为也可能随底层库变化。下面命令检查直连时的协商结果：

```bash
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null | grep -E 'Protocol|Cipher|verify'
```

这条命令默认直连目标，只能观察直连路径上的 TLS。核对 CA 校验、TLS 版本和 SNI；若要观察代理隧道，可使用 OpenSSL 1.1.0 及以上版本的 -proxy host:port，或客户端自身的 TLS trace。直连结果不能代表代理路径。

怎么确认流式响应没有被缓冲或中断？

流式输出是 AI SDK 的核心能力，也是最容易在代理链路上退化的部分。

TCP/HTTP 读取块边界可能变化，应与应用层 SSE 事件区分。重点验证解析后的事件顺序、完整性和增量到达，以及连接中断能否被识别。TTFB 与总生成时长不能单独证明缓冲。记录首个应用事件及后续事件的单调时钟，与相同请求的升级前结果或受控上游基线比较；出现延迟时先标记为疑似，再定位客户端、代理和服务端。

显式配置和代理环境变量冲突时，哪个设置生效？

代理设置可能来自显式参数、环境变量或 SDK 默认值，实际优先级应按所用客户端和版本核对。可在隔离环境中将其中一项设为不可用代理，观察请求错误与实际出口；同时检查 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 的匹配结果。不要仅凭配置文本推断请求路径。

Android 网络栈与代理接入的排查思路可参考Android App 网络栈测试怎么做？接入代理后异常定位。Node.js 环境下的 Undici 配置请以Undici API 文档为准。

FAQ

Q：依赖升级没有改代理代码，也需要回归吗？

A：需要关注传递依赖和默认值变化，尤其是代理解析、重定向与重试行为。

Q：能用生产凭据跑回归测试吗？

A：优先使用受限测试凭据和非生产资源，避免重试或错误配置触发真实业务操作。

Q：不同 SDK 的测试结果可以直接横向比较吗？

A：只有请求、出口、超时和服务端条件一致时才有参考价值，并应注明版本差异。