错误处理 — 参考并对齐 AI SDK 的错误体系(持续跟踪)

[cunninghamcard-bit]

目标

以 AI SDK 的错误处理为参照系,建立 aimux 完整的错误域。本 issue 是常设跟踪:相关 PR 全部关联到这里,具体设计与差距分析写在各 PR 里。

范围

• Provider 层错误分类:变体语义、结构化字段、HTTP/JSON/轮询失败的归类
• 编排层错误:工具调用错误细分、各模态生成失败、重试机制的错误表达
• 流式与取消:stream 内错误语义、abort/timeout 贯通
• 跨语言错误面:C ABI 与 native 绑定(Node/Python)的错误类层级与字段透出
• 配套:错误相关文档、CI 覆盖

原则

参考对齐而非照抄:与 AI SDK 架构不同处(C ABI、跨语言重试协议)以 aimux 自身契约优先。

进展

• P1 结构化错误业务语义:fix(error): structured ApiCall/NoSuchProvider fields, unified retry/2xx classification #94
• P2 跨语言错误模型与 C ABI 稳定契约:refactor(bindings,ffi)!: 稳定跨语言错误模型 #158

[cunninghamcard-bit]

#164(request pipeline 对齐 AI SDK)解决了 master 上本 issue 范围内的这些问题。主轴是两条:重试的分层与错误域本身,其余都是这两条带出来的。

• 重试放错了层,错误因此没有重试语义:master 的重试是 HTTP 模块内部逻辑,它自己的文档写着"provider 不感知重试发生"——一次逻辑调用和一次 HTTP 交换被糊在一起,错误既不保留 attempt 历史,也不区分"重试耗尽"与"本就不可重试",录制分不清第 N 次尝试和第 N 次交换。现在 Core 拥有操作级重试:RetryError { maxRetriesExceeded | errorNotRetryable } 完整保留各次尝试,错误消息与 AI SDK fixture 逐字一致;provider-utils 每次调用恰好一次交换——即 AI SDK 自己的分层。
• 错误域是有损的:5 个 provider(ElevenLabs / AssemblyAI / Deepgram / fal / Hume)套用 OpenAI 形状的 DEFAULT_ERROR_STRUCTURE(error.message / error.type),而这几家的真实错误格式(detail.*、裸 {error}、err_code/err_msg、FastAPI detail、顶层 message/code)解析出来是空消息;失败响应的 body 还被无上限全量读进内存。现在每个 mapper 按各家文档格式实现,错误体在 64 KiB 公开上限(lossy 解码后)+ 1 MiB 解析上限下 best-effort 读取,超大但合法的错误 JSON 仍能进 mapper。
• 坏帧即断流:master 里流中任何一个解析失败的帧都会终止整条流,且 core 消费端、两条 FFI pump、Node/Python driver 各自锁死。现在可恢复的帧错误按 AI SDK 契约作为数据继续传,只有传输/Core 错误才是终态。
• 流的终止依赖 provider 关闭连接:master 没有 Finish 保险丝,不配超时的情况下 provider 发完最后一个 chunk 但挂着连接,消费端永久阻塞。现在消费包装层是无条件的终止保险丝。
• 跨语言错误面收紧:C ABI 删除 aimux_error_request_id(breaking),115 个导出符号由 header/exports 一致性测试钉死;错误变体的 golden 契约测试用编译期穷举匹配,新增变体绕不开 wire-tag 检查。

设计上与 AI SDK 的全部差异记录在 docs/ai-sdk-request-pipeline.md §3 差异表。