[cunninghamcard-bit]

Summary

新增 rfc/0046-provider-protocol-abstraction.md，只有这一个文件，不改代码。

aimux-providers 里同一种协议有多份实现，厂商之间互相去对方的私有文件拿函数，形成 7 个环。本文做一次小重构并定下抽象：通用函数进 aimux-provider-utils，每种协议一份实现（模型 + XxxConfig），厂商只剩工厂、Config 取值和 Fetch 层鉴权；托管变体只换 Config，经对方的 internal 入口单向依赖，CI 禁止新的环。目录、文件名和测试位置随之整理。wire 行为不变；厂商模块根的导出和公开设置不变，但厂商目录里现在公开的 55 个子模块路径会变，provider-utils 删两个只有测试在用的公开函数（§4.5）。crate 怎么拆见 RFC-0044（#279），两份互不依赖。

实施进度（R1–R7 和各厂商搬移）在 #328 跟踪。

一、体系现状（概览，master 5743a40a）

协议实现和谁在用（48 个厂商实现）

协议	aimux 的实现	跑在上面的	上游
OpenAI Chat Completions	openai/、openai_compatible/	Azure；282 个 preset 和 Vertex 合作模型经兼容层；Groq、DeepSeek、Mistral、Cohere 各一份	@ai-sdk/openai、@ai-sdk/openai-compatible，Groq 等是独立包
OpenAI Responses	openai/responses/	Azure、Codex（直接用 OpenAI 私有模块）；open_responses.rs、xai/responses/、huggingface/responses.rs 各一份	上游这三家也各自一份
Anthropic Messages	anthropic/	Anthropic AWS、Vertex 上的 Claude；Bedrock 借它的工具准备	托管变体走 @ai-sdk/anthropic/internal
Google generateContent	google/	Vertex 上的 Gemini：流处理和结果解析整份复制	@ai-sdk/google-vertex 复用 @ai-sdk/google 的模型
Bedrock Converse	bedrock/	—	@ai-sdk/amazon-bedrock

基础厂商的一次调用（Mistral，右侧是去向）

aimux_providers::mistral::create_mistral           aimux-providers/src/mistral/mod.rs:161
 └ MistralProvider::language_model                 aimux-providers/src/mistral/mod.rs:270
   └ MistralModel::do_generate                     aimux-providers/src/mistral/model.rs:176
     └ build_request_body                          aimux-providers/src/mistral/convert.rs:225
       └ convert_prompt_to_mistral_messages        aimux-providers/src/mistral/convert.rs:105
         └ crate::openai::convert::tool_result_to_content
                                                    aimux-providers/src/mistral/convert.rs:167 → openai/convert.rs:512   ← 去 OpenAI 的私有文件拿
     └ aimux_provider_utils::post_json_to_api      aimux-providers/src/mistral/model.rs:180

上游 @ai-sdk/mistral 只依赖 @ai-sdk/provider 和 @ai-sdk/provider-utils，工具结果在 convert-to-mistral-chat-messages.ts:167 自己转换。

托管变体的一次调用（Vertex 上的 Claude）

Vertex provider 建 Claude 模型                      aimux-providers/src/vertex/anthropic_provider.rs:85
 └ vertex::anthropic_model::model                  aimux-providers/src/vertex/anthropic_model.rs:63
   └ AnthropicEndpoint::Vertex(resolver)           aimux-providers/src/vertex/anthropic_model.rs:86
     └ AnthropicModel::do_generate                 aimux-providers/src/anthropic/model.rs:152
       └ prepare → config.resolved()               aimux-providers/src/anthropic/model.rs:111 → :116
         └ AnthropicModelConfig::resolved          aimux-providers/src/anthropic/config.rs:156
           └ match AnthropicEndpoint::Vertex       aimux-providers/src/anthropic/config.rs:160
             └ crate::vertex::Publisher::Anthropic aimux-providers/src/anthropic/config.rs:162   ← Anthropic 反过来认识 Vertex（环）

上游托管变体走基础厂商的 /internal 入口，基础厂商不认识变体：amazon-bedrock/src/anthropic/amazon-bedrock-anthropic-provider.ts:17 从 @ai-sdk/anthropic/internal 取模型。

用户请求体回调：10 个公开设置有 transform_request_body: Option<TransformRequestBody>（兼容层照上游，另外 9 个是 aimux 扩展）。Anthropic 现在把内部改写和用户回调串在一起：

AnthropicModelConfig::transform_body               aimux-providers/src/anthropic/config.rs:285
 └ hooks.prepare_body（Vertex、Bedrock 的内部改写）  aimux-providers/src/anthropic/config.rs:286
 └ transform_request_body（用户回调，如 AWS、Vertex 设置传进来的）
                                                    aimux-providers/src/anthropic/config.rs:289

目录与测试：aimux-providers/src 三种目录形态混用，文件用通用名（model.rs、convert.rs），对不上上游文件；测试在 tests/ 下 126 个独立测试程序。

二、本 PR 改动（细节）

1. 三层

厂商（工厂、Config 取值、鉴权 Fetch）      vertex/、anthropic_aws/、azure/、codex/、preset 数据行 …
   │ 只经过 internal，单向
   ▼
协议实现（模型 + XxxConfig）               openai/（Chat、Responses）、openai_compatible/、anthropic/、google/、bedrock/
   │                                       独立上游包的厂商（Groq、Mistral、xAI …）各自是自己的协议实现，不合并
   ▼
通用函数（aimux-provider-utils）            parse_provider_options、流错误、响应元数据、工具结果转换、SigV4 …

2. 改完后的三条调用

Mistral：MistralModel::do_generate → convert_prompt_to_mistral_messages
 └ aimux_provider_utils::tool_result_to_content         ← 通用函数，不再进 openai/

Vertex 上的 Claude：vertex 工厂
 └ AnthropicModel + AnthropicConfig { endpoint, build_request_url: AnthropicRequestUrl::VertexRawPredict,
                                      body_rewrite: Some(AnthropicBodyRewrite::VertexRawPredict),
                                      transform_request_body: 用户在 VertexProviderSettings 传的回调, … }
   └ vertex 实现端点解析；Google 令牌在 Fetch 层          ← Anthropic 不再认识 vertex::Resolver、Publisher

Vertex 上的 Gemini：vertex 工厂
 └ Google 的模型 + GoogleConfig（端点、命名空间、字段剥离表、用户回调）
                                                        ← 删掉 vertex/model.rs 复制的流处理和结果解析（行为修正：ID 不再用计数器）

3. Config 钩子

厂商之间内部用的请求体改写、请求 URL 改成每种协议一个封闭枚举（AnthropicBodyRewrite、AnthropicRequestUrl、CompatibleBodyRewrite），放在单独的 body_rewrite、build_request_url 字段；枚举和改写函数都在协议目录（anthropic/request_rewrite.rs 等），托管变体只选变体，不形成反向边。10 个公开设置里的用户回调保留，进协议 Config 的 transform_request_body，先跑内部改写、再跑用户回调，和现在的顺序一样；公开别名 TransformRequestBody（shared/mod.rs:75）不改名。把用户回调也删掉是 §9 的备选。

4. SigV4

现在：anthropic_aws/model.rs:210-232 和 bedrock/mod.rs:364-395 都包同一个 SigV4Fetch，各自再写一遍外层（包名 UA、看哪个 header 决定签不签）
改成：provider-utils 里一个外层，包名和判断用的 header 是参数，两处都用它

5. 测试位置

厂商测试          src/<vendor>/tests/，mod.rs 末尾 #[cfg(test)] mod tests;
                 一个上游 foo.test.ts → tests/foo.rs（与被测源文件同名），直接调函数的和走 provider + mock fetch 的都在这里
                 fixtures/、snapshots/ 跟在 tests/ 下；被测私有函数改 pub(super)
共用 mock fetch   tests/common/ → src/test_support/mock_fetch.rs（cfg(any(test, feature = "test-support"))）
crate 的 tests/   126 个程序 → 只留跨厂商的（cassette 回放、conformance）；用 ReplaySession 的回放测试去 ops

搬移 PR 不改断言、不删测试，前后比较 cargo test -p aimux-providers -- --list 的数量；测试并进同一个程序后环境变量、全局计数器、临时路径变成共享，每个搬移 PR 的描述列出本家涉及哪些。

6. 公开路径

厂商目录里的 55 个 pub mod（openai 14、anthropic 11、google 9 …）按上游改名或收为私有，算破坏性变更，随下一个 minor 版本发布，每个搬移 PR 在 CHANGELOG 列出本家的旧路径和替代入口；留 #[deprecated] 过渡模块的做法是 §9 的待讨论项。例外两处：R1 删 provider-utils 的 with_user_agent_suffix_fn、without_trailing_slash_opt，同样登记为破坏性变更；replay 按 RFC-0044 C6 移到 ops，由那份 RFC 登记。

步骤

步骤	内容	前置
R1	provider-utils 补齐通用函数，删除死代码（两个公开函数，登记为破坏性变更）	无
R2	解开七个环（两个 Anthropic 的环靠只有 endpoint 的 AnthropicConfig），加 internal 模块和 CI 检查	R1
R3	AnthropicConfig 补齐其余字段，URL 和内部改写直接用枚举，用户回调单独一个字段；Anthropic AWS、Vertex Claude 改用它；两个 SigV4 外层合并	R2
R4	Vertex Gemini 改用 Google 模型 + GoogleConfig（行为修正）	R2
R5	兼容层：Vertex 合作模型的两种改写挪到 body_rewrite	R2
R6	模态与搜索厂商去重	R1
R7	目录、文件名、测试位置，layout.toml，按厂商家族分批，Mistral 先做样例	可与 R1–R6 交错

Type of change

• Docs / RFC

Checklist

• Updated relevant docs (rfc/)
• Commit messages follow Conventional Commits

纯文档，cargo 检查不受影响。

Notes for reviewers

• 文件从 0046-provider-layout-and-reuse.md 改名，标题改成“provider 协议的小重构与抽象设计”，目录和测试位置变成其中两节。
• 测试位置 10-20 改成每个厂商一个 tests/ 目录（§5），原来的 foo/tests.rs 加 tests/it/ 不再用。
• eric 10-20 的第一轮 review 已逐条处理（fe5f2f07）：公开路径（§4.5）、枚举改名、改写函数放协议目录、R2/R3 边界、回放测试去 ops、SigV4 的重复在哪、搬移不是“只搬不改”。
• 第二轮复审（5165bf28）：10 个公开回调的落点（§3.5 表），内部改写改成单独的 body_rewrite 字段；R3 直接用枚举，R5 只剩兼容层；V5 改正；provider-utils 两个公开函数和 replay 在 §4.5 登记；代码块闭合；55 个 pub mod 在基线上重数；全文行号在基线上重新核对。
• 待讨论三条在 §9：厂商目录名、旧子模块路径、Config 钩子的写法（含删除用户回调的备选）。
• 扫描中发现的行为偏差由单独的 PR 修，不放进搬移 PR。
• R7 的搬移已按厂商开出 Draft（Mistral refactor: move the Mistral files to the upstream layout #297、Cohere refactor: move the Cohere files to the upstream layout #298、DeepSeek refactor: move the DeepSeek files to the upstream layout #300、Groq refactor: move the Groq files to the upstream layout #302、Hugging Face refactor: move the Hugging Face files to the upstream layout #304、xAI refactor: move the xAI files to the upstream layout #313、Anthropic AWS refactor: move the Anthropic AWS files to the upstream layout #320、Azure refactor: move the Azure files to the upstream layout #326、Open Responses refactor: move the Open Responses files to the upstream layout #350、Google Vertex refactor: move the Google Vertex files to the upstream layout #353、OpenAI 兼容层 refactor: move the OpenAI-compatible files to the upstream layout #356、Amazon Bedrock refactor: move the Amazon Bedrock files to the upstream layout #359），各自叠在对应的测试 PR 上；进度见 包拆分与 provider 重构：RFC-0044、RFC-0046 实施进度 #328。
• 相关：RFC-0044（RFC-0044: crate 拆分与依赖反转 #279）、RFC-0045（RFC-0045: 上游测试迁移策略 #281，已合入，引用本文的 layout.toml 和测试位置）、RFC-0048（RFC-0048: 录制 schema 3 与传输回放 #325）、Provider 构造与配置：迁移后遗留缺口 #275、Core 运行时：与 AI SDK 的剩余差距（对齐文档 §9.1 已知差距） #276、测试：补迁上游 AI SDK 测试（按用例名约 18% 对上） #278。

🤖 Generated with Claude Code

https://claude.ai/code/session_0116HPMoqaLfFr1TyqDq1hrW

[cunninghamcard-bit]

贡献者意见（li），供维护者决定：

• 厂商目录名（§9 第 1 条）： 保留现有名字（bedrock/、vertex/ 等），不改成上游包名。目录名就是公开模块路径，改名是破坏性变更；对应哪个上游包写在 layout.toml 里就够了。
• Config 钩子（§9 第 2 条）： 不开放回调。兼容层用户设置里的 transform_request_body、metadata_extractor、supported_urls、convert_usage 也去掉，全部改成枚举；用户要改请求体或结果，用自定义 fetch 或模型 middleware。与上游 createOpenAICompatible 能传这四个函数的差异需要登记。（2026-10-20 更新：原先这一条写的是保留兼容层的用户回调。）

---

Generated by Claude Code

[eric8810]

Review

现状盘点（7 个环、126 个测试二进制、282 个 preset 等）基本准确，但方案有几处会阻碍实现：

• 阻塞 RFC 声称“不改变公开 API”，但 §4.2 把 openai::model、mistral::convert 等公开模块改名，下游路径会断；需要兼容 shim 或明确 major 版本。
• 阻塞 TransformRequestBody 枚举和现有公开 Arc<dyn Fn(Value) -> Value> 别名同名，兼容层用户回调无法放进这个枚举；建议换名并保留原 alias。
• 阻塞 枚举 dispatch 从 Anthropic 调 vertex::anthropic::...，又建回 Anthropic→Vertex 的反向边；应把变换放在协议/公共层，或存函数对象。
• 重要 R2 声称解开全部 7 个环，但 Anthropic↔Vertex/AWS 的 AnthropicConfig 在 R3 才引入；需要拆分 R2/R3 的边界。
• 重要 RFC-0048 计划把 provider replay 测试放在 aimux-providers/tests/common/replay.rs，但 ReplaySession 最终在 aimux-devtools，与 RFC-0044 分层冲突。
• 次要 两处 SigV4 实际都包同一个 SigV4Fetch，重复的是 UA/鉴权判断；搬移测试 PR 里有环境变量、计数器、临时路径的语义变化，不只是“只搬不改”。

[cunninghamcard-bit]

逐条处理如下，都在 fe5f2f0。左列是 @eric8810 的原话。

eric 的意见	核对	处理	位置
阻塞 RFC 声称“不改变公开 API”，但 §4.2 把 openai::model、mistral::convert 等公开模块改名，下游路径会断；需要兼容 shim 或明确 major 版本	属实。master@c0622ea4 厂商目录里有 55 个 pub mod（openai 14、anthropic 11、google 9、bedrock 5、xai 4、openai_compatible 3、cohere 3、voyage 2、mistral 2、vertex 1、huggingface 1）。已开的搬移 PR 里 #297（Mistral）、#298（Cohere）、#313（xAI）已经把 convert、embedding 等收为私有	Scope 改为：wire 行为、crate 根和厂商模块根的导出不变，子模块路径会变，是破坏性变更。新增 §4.5：默认不留 shim，随下一个 minor 版本发布，每个搬移 PR 在 CHANGELOG 列出本家的旧路径和替代入口；留 #[deprecated] 同名模块一个版本的做法列为 §9 待讨论。请定一种，定了之后已开的搬移 PR 照着补	Scope、§1 V8、§4.5、§9
阻塞 TransformRequestBody 枚举和现有公开 Arc<dyn Fn(Value) -> Value> 别名同名，兼容层用户回调无法放进这个枚举；建议换名并保留原 alias	属实，别名在 shared/mod.rs:75，7 个模块 re-export	枚举改名并按协议分开：AnthropicBodyRewrite、AnthropicRequestUrl、CompatibleBodyRewrite；TransformRequestBody 别名照旧给用户回调；兼容层字段是 CompatibleRequestBody { Callback(TransformRequestBody), Rewrite(CompatibleBodyRewrite) }。（li 在本 PR 的贡献者意见是兼容层的用户回调也去掉；若采纳，别名和 Callback 一起删）	§3.5
阻塞 枚举 dispatch 从 Anthropic 调 vertex::anthropic::...，又建回 Anthropic→Vertex 的反向边；应把变换放在协议/公共层，或存函数对象	属实	改写函数和枚举放在协议目录（anthropic/request_rewrite.rs、openai_compatible/request_rewrite.rs，记为 aimux 扩展），Vertex、Bedrock 只选变体，协议目录不 use 任何厂商。存函数对象的做法写进 §9 Config 钩子一条作为另一种选择	§3.5、§9
重要 R2 声称解开全部 7 个环，但 Anthropic↔Vertex/AWS 的 AnthropicConfig 在 R3 才引入；需要拆分 R2/R3 的边界	属实	R2 引入只有 endpoint: Arc<dyn ResolveEndpoint> 的 AnthropicConfig，删 AnthropicHeaders::Aws，两个 Anthropic 的环在 R2 解开；R3 补齐其余字段，把 URL、请求体改写、能力开关接上	§3.3 表、§6 R2/R3
重要 RFC-0048 计划把 provider replay 测试放在 aimux-providers/tests/common/replay.rs，但 ReplaySession 最终在 aimux-devtools，与 RFC-0044 分层冲突	属实。providers 不能依赖 devtools，devtools 也不依赖 providers（RFC-0044 §8 第 1 条）	这类测试放 ops 的集成测试（ops 两者都依赖）；tests/common/ 本来就按 §5 第 5 条移到 src/test_support/。#325 那边我会请负责的线程改	§5 第 9 条
次要 两处 SigV4 实际都包同一个 SigV4Fetch，重复的是 UA/鉴权判断	属实（anthropic_aws/model.rs:210-232、bedrock/mod.rs:364-395）	改成：重复的是外层，加各自包名的 UA、按 x-api-key 或 Authorization 决定签不签；合并后包名和判断用的 header 是两个参数	§2.4、§3.4
次要 搬移测试 PR 里有环境变量、计数器、临时路径的语义变化，不只是“只搬不改”	8 个搬移 PR 的 diff 里这些行逐字不变；变的是进程：原来每个文件单独一个进程，现在和别家共享 lib 的测试程序。涉及的有 Groq 1 个改 GROQ_API_KEY 的测试（带 #[serial]）、xAI 9 个 #[serial] 和 SOURCE_ID_COUNTER（只有 xAI 用）、AWS 36 个、Azure 1 个 #[serial]	§5 改成“不改断言、不删测试，但不是只搬不改”，每个搬移 PR 的描述列出本家共享了哪些环境变量、计数器、临时路径和处理方式；已开的 8 个 PR 描述我补上	§5

---

Generated by Claude Code

[eric8810]

复审（fe5f2f07）

之前 7 条里 6 条已实质解决：公开路径改为明确 breaking + §4.5、TransformRequestBody 枚举改名、Anthropic 改写移入协议目录、R2/R3 拆分、replay 测试移到 ops、SigV4/搬移措辞修正。

仍有以下阻塞/重要项：

• 阻塞 公开回调 API 没有落点：AnthropicAwsProviderSettings.transform_request_body、VertexProviderSettings.transform_request_body、Bedrock、Codex、ElevenLabs、HuggingFace、OpenResponses、Voyage、preset 等公开 settings 仍暴露 TransformRequestBody；RFC 只给 AnthropicConfig 一个 Option<AnthropicBodyRewrite>，这些用户回调没有迁移路径。需要在 Config 里保留 callback 变体，或在 §4.5 明确删除并登记 breaking。
• 重要 R3 与 R5 重复：R3 已说 AnthropicConfig 补齐 URL/请求体改写字段，R5 又说“Config 钩子改成枚举”。请明确 R3 只加字段、R5 再换枚举，或合并两步。
• 重要 V5 仍写“逻辑在厂商目录的普通函数里”，与 §3.5 的“协议目录、协议目录不 use 厂商”矛盾。
• 重要 §3.2 删除 with_user_agent_suffix_fn 和 without_trailing_slash_opt，两者都是 provider-utils 的公开 API；需要登记 breaking/deprecation。
• 次要 §4.5 说 crate root 导出不变，但 replay 按 C6 移出、provider-utils 公开函数删除；请把范围限定到 R7 或列出例外。
• 次要 §3.5 的 Rust 代码块结尾 ``` 和“端点解析…”写在同一行，CommonMark 不会正确闭合。
• 提示 基线写 5743a40a，但 55 个 pub mod 计数引用的是 c0622ea4。

[cunninghamcard-bit]

第二轮复审（review 5586872163）逐条处理，改动在 5165bf2。下表左列是 eric 的原话（摘要），每条都在 master@5743a40a 上对过代码。

eric 的意见	核对	处理
阻塞：公开回调 API 没有落点，AnthropicAwsProviderSettings、VertexProviderSettings、Bedrock、Codex、ElevenLabs、HuggingFace、OpenResponses、Voyage、preset 等公开 settings 仍暴露 TransformRequestBody，RFC 只给 AnthropicConfig 一个 Option<AnthropicBodyRewrite>	属实。原文“用户能填的只有兼容层”是错的：一共 10 个公开设置有 transform_request_body（另一个是 OpenAICompatibleProviderSettings）。现在 AnthropicConfig 只有一个字段，同时装 prepare_body 和用户回调（anthropic/config.rs:285-293），所以单个枚举字段放不下用户回调	§3.5 用一张表列出 10 个设置的字段位置和落点：兼容层和 preset 进兼容层 Config 的 transform_request_body；Anthropic AWS、Vertex 上的 Claude 进 AnthropicConfig.transform_request_body（R3）；Vertex Gemini 进 GoogleConfig.transform_request_body（R4）；Codex、Bedrock、ElevenLabs、HuggingFace、Open Responses、Voyage 用的是 OpenAI 配置或自己的模型，不变。内部改写改成单独的 body_rewrite 字段，先跑内部改写，再跑用户回调，和现在的顺序一样；原来的 CompatibleRequestBody { Callback, Rewrite } 去掉。公开设置不变，不算破坏性变更。把这些回调全部删掉作为第二种备选写进 §9（待讨论），如果选它，就按 §4.5 第 2 条登记为破坏性变更
重要：R3 与 R5 重复	属实	R3 补字段时直接用枚举（AnthropicRequestUrl、AnthropicBodyRewrite）和用户回调字段。R5 只剩兼容层：把 Vertex 合作模型的两种改写从公开回调字段挪到 body_rewrite（CompatibleBodyRewrite），前置改为 R2
重要：V5 仍写“逻辑在厂商目录的普通函数里”，与 §3.5 矛盾	属实	V5 改成“枚举和改写函数都在协议目录，协议目录不 use 厂商”，并写明 10 个公开回调保留
重要：§3.2 删除 with_user_agent_suffix_fn 和 without_trailing_slash_opt，两者都是 provider-utils 的公开 API	属实：headers 是 pub mod，without_trailing_slash_opt 在 lib.rs:68 re-export	§3.2 写明它们是公开 API，§4.5 第 3 条登记为破坏性变更。R1 的 PR 在 CHANGELOG 写替代写法：with_user_agent_suffix，以及 url.map(without_trailing_slash)
次要：§4.5 说 crate root 导出不变，但 replay 按 C6 移出、provider-utils 公开函数删除	属实（replay 在 aimux-providers/src/lib.rs:146-148）	§4.5 开头把范围限定为本文各步骤带来的变化，crate 根在 R7 之后不变。第 3 条列出两处例外：R1 删掉的两个函数；replay、rebuild_provider、rebuild_decision_provider 按 RFC-0044 C6 移到 ops，由那份 RFC 登记。Scope 一句同步改了
次要：§3.5 代码块结尾 ``` 和“端点解析…”写在同一行	属实	已修：``` 单独一行，后面另起一段
提示：基线写 5743a40a，55 个 pub mod 的计数引用 c0622ea4	在 5743a40a 上重数，各家数目一样（openai 14、anthropic 11 …，共 55）	§4.5 改成引用基线

顺带：全文的 file:line 在基线上又核对了一遍，§3.6 里 black_forest_labs.rs 和 stability.rs 的两对函数原来配错了行，已更正。

---

Generated by Claude Code

[eric8810]

复审通过。10 个公开 transform_request_body 的落点、R3/R5 边界、V5、provider-utils 公开 API 的破坏性登记、§4.5 范围、代码围栏和基线都已修正。Approve。