L1ngg's Home

需求原点：解耦请求审计与响应诊断#

在 Forge 框架中，为了实现请求全生命周期的追踪与调试，我们需要暴露两类低层级钩子：

• onPayload：用于在请求发送前观察或修改 Provider 编码后的实际 Payload（例如检查模型参数、安全脱敏或补充元数据）。
• onResponse：用于获取模型供应商返回的原始 HTTP 响应状态（status）与响应头（headers）。

边界厘清

onResponse 解决的是传输层网络与协议诊断问题（例如捕获 429 限流响应头中的 retry-after、追踪网关注入的 x-request-id、记录 HTTP 500 状态），它不是业务层的模型流式文本输出回调，也不是 Token 结算的 usage 回调。

Forge 内部已能通过自定义 streamFn 来包装并组合这些回调，从而覆盖完整的任务运行与会话摘要链路。但对于宿主应用来说，更理想的做法是能够直接通过框架配置传入诊断回调，同时无缝复用 Forge 内置的网络传输和凭据认证逻辑。

然而在接入底层适配层时，我们发现“将回调传入 Provider 配置”与“每次收到 HTTP 响应都能收到通知”之间存在巨大落差。

实现割裂：pi-ai@0.85.1 的三类执行分支#

Forge 的模型适配层依赖了 @earendil-works/pi-ai@0.85.1。对外，该库暴露了统一的 Provider 回调配置参数；但通过对其内部各 Provider 适配实现的源码走读，我们发现其运行时行为严重分化为三类完全不同的执行路径：

对比各适配路径的具体表现：

这证明了在多模型抽象层中，仅凭统一的 TypeScript 类型定义并不代表底层有统一的生命周期保证。

层级错位：为什么 HTTP 429/500 会被静默绕过？#

为什么在 OpenAI 与 Anthropic 路径上，非 2xx 的响应无法触发回调？这并非 HTTP 协议本身的限制。无论是 429 Too Many Requests 还是 500 Internal Server Error，远端服务器都返回了合法的 HTTP 状态行与响应头。

问题根源在于回调注册所在的抽象层级：

1
真实 HTTP 响应流转：
2
[HTTP 响应到达]
3
   │
4
   ├── 传输层 (Transport Layer)
5
   │     └── 可优先记录 status / headers，无论状态如何
6
   │
7
   └── 供应商官方 SDK 封装层
8
         ├── 遇到非 2xx：直接包装为 APIError 抛出异常 ──┐ (中断正常控制流)
9
         │                                            │
10
         └── 仅当 2xx 成功：继续执行业务回调 ◄─────────┴─ onResponse 被跳过

当适配层直接基于官方 SDK 的高阶封装方法编写逻辑时，一旦网络响应处于非 2xx 状态，官方 SDK 在解析响应头阶段就会直接抛出错误。位于下游成功流处理中的 onResponse 因此根本没有执行机会。

对比业界成熟方案的实现位置：

• Vercel AI SDK：允许向 Provider 注入 custom fetch，在网络传输层最外层拦截所有的 Response 对象，无论后续如何解析，均可无条件审计状态码与 Headers。
• Anthropic 官方 SDK：上游提供了按每次 HTTP 尝试（HTTP attempt）执行的 Client Middleware，重试前后的每一次 HTTP 响应都能完整被观察。

统一观察在技术上完全可行，但其钩子必须注入在传输层，而非供应商 SDK 的成功结果处理层。

排除版本假象：从 npm 0.86.1 到 upstream main 实测#

面对上述行为缺失，第一反应往往是怀疑“当前依赖版本较旧，上游可能已经修复”。为了验证这一假设，我们对三个层次进行了代码对齐：

1. 项目当前安装版本：pi-ai@0.85.1。
2. npm 当时最新发布版本：pi-ai@0.86.1。下载实际 tarball 并解压其发布构建产物（.js 与 .d.ts）进行比对。
3. 上游代码仓库 HEAD：Git Commit 3390bd93630965a12a0a1a5c36ce890ec22f7e1d 快照。

核对结果如下：

排查同时确认，历史版本 0.84.3 确实合并过一次响应头处理相关的提交，但该提交仅修复了 Bedrock 路径下响应头格式解析不全的局部问题，与此处的通用生命周期缺陷无关。

实证表明：单纯升级 Pi 的版本无法解决当前问题，必须定位上游的既有讨论或提交修复。

根因穿透：Pi #5623 与 Google #1869 的深层束缚#

顺着调用路径向上游溯源时，我们在社区仓库中找到了对应的 Issue，并发现了更深层次的技术约束。两条链路需分开审视：

1
// Google GenAI SDK 的类型声明中看似拥有完整 HTTP 响应：
2
interface GenerateContentResponse {
3
  sdkHttpResponse?: {
4
    status: number;
5
    headers: Record<string, string>;
6
  };
7
  // ...
8
}
9

10
// 实际运行时流式返回对象：
11
// 实际流式结果仅返回了包含 { headers } 的部分数据，
12
// sdkHttpResponse 实例未被正确挂载，status 字段彻底丢失！

解法与启示：在 SDK 上层观测失效时，如何正确捕获大模型流量#

通过这次穿透式排查，我们得出以下架构设计与工程落地维度的结论：

1
// 传输层拦截示例：保证所有状态码无遗漏捕获
2
const customFetch: typeof fetch = async (url, init) => {
3
  const response = await fetch(url, init);
4

5
  // 无论 response.status 是否为 200，此处必定能获取完整 HTTP 状态与标头
6
  diagnostics.recordResponse({
7
    url: url.toString(),
8
    status: response.status,
9
    headers: Object.fromEntries(response.headers.entries()),
10
  });
11

12
  return response;
13
};