[cunninghamcard-bit]

Summary

按 RFC-0045（#281）把 @ai-sdk/huggingface@2.0.62 的上游测试迁完，按厂商分批的第五个（Mistral #295、Cohere #296、DeepSeek #299、Groq #301）。

上游 2 个测试文件共 38 个用例：

• 34 个有对应测试并通过：原有 12 个补上出处标记，新增 22 个。
• 1 个记为 registered：首个 SSE 事件就是错误时，aimux 在 do_stream 里直接返回 Err（已登记的「SSE 预读」）。
• 3 个记为 sub-feature（Core 运行时：与 AI SDK 的剩余差距（对齐文档 §9.1 已知差距） #276）：错误提示文字来自 aimux-core 的错误类型，NoSuchModel 和 UnsupportedFunctionality 的消息格式和上游不同，[15/15] feat!: generate binding DTOs from the Rust types #268 合并后仍是这样。

迁移中发现三处行为差异，各自单独一个 fix PR，本 PR 叠在最后一个上：

• fix: Hugging Face MCP calls are not dynamic #305：MCP 工具调用（mcp_call、mcp_list_tools）多带了 dynamic: true。
• fix: Hugging Face output items yield a tool-result #306：非流式的 function_call 带 output 时没有输出 tool-result；mcp_call 的 output 为空字符串时却输出了。
• fix: Hugging Face stream errors end with an error finish #307：流里的错误事件只认顶层 error 字段，response.failed 和消息写在事件本身的 error 事件都漏掉；出错后结束原因停在 other，上游是 error。

这几处修复最早在本分支上提交过，拆出去之后用一个合并提交把 #307 合进来。#307 已合入 master，所以相对 master 的 diff 只有测试和 layout.toml。

原有测试里 18 个只覆盖了上游用例的一部分（或换了输入），完整用例在新文件里重新迁了一遍，原测试留着但不计数，注释指向完整的那个。

位置按新定的布局：一个厂商的测试全放 src/huggingface/tests/，一个上游测试文件对应一个 Rust 文件。原有的 tests/huggingface_responses_test.rs 留在原地，由包拆分线程的搬移 PR 合进来。

一、体系概览：Hugging Face 的测试现在怎么跑（master 5743a40a）

cargo test -p aimux-providers
  ├─ unittests src/lib.rs                                   Hugging Face 一个都没有
  └─ tests/*.rs
       └─ huggingface_responses_test.rs     32 个，出处写成 /// TS: "…"，不带 describe 链
            create_huggingface(HuggingFaceProviderSettings { .. })        huggingface.rs:106
            ├ Provider::embedding_model / image_model                    huggingface.rs:203 / :207   → NoSuchModel，没有上游的提示文字
            └ HuggingFaceProvider::responses                              huggingface.rs:177
              └ HuggingFaceResponsesModel::do_generate / do_stream        huggingface/responses.rs:163 / :216
                ├ build_request_body_with_warnings                        responses.rs:580
                │ ├ convert_to_huggingface_responses_messages             responses.rs:726
                │ └ prepare_responses_tools                               responses.rs:880
                ├ do_generate → build_generate_content                    responses.rs:933
                │   ├ "function_call"                                     :995    ← 有 output 也不出 tool-result（#306 修）
                │   └ "mcp_call" / "mcp_list_tools"                       :1013   ← dynamic: Some(true)（#305 修）
                └ do_stream → 预读首个事件                                responses.rs:232   首事件是错误就返回 Err（SSE 预读）
                    └ HuggingFaceResponsesStream::transform_event         responses.rs:306
                        ├ huggingface_stream_error(event)                 responses.rs:94    ← 只看顶层 error 字段（#307 修）
                        └ Err(解析失败)                                   :536               ← finish_reason 不变（#307 修）

上游 packages/huggingface/src/ 对应：

huggingface-provider.test.ts                               6   createHuggingFace → provider.responses / embeddingModel / imageModel
responses/huggingface-responses-language-model.test.ts    32   createTestServer → provider.responses(...).doGenerate / doStream

改动前 32 个测试和上游用例对不上号：出处只写了 it 文本，没有 describe 链，18 个只比了部分字段或换了输入。

二、本 PR 的改动（细节）

1. 原有 32 个测试补标记（tests/huggingface_responses_test.rs）

mod hugging_face_responses_language_model › mod do_stream / mod message_conversion / mod structured_output
                                           › mod provider_options / mod tool_preparation / mod top_level_only_media_type_resolution
  /// upstream: @ai-sdk/huggingface src/responses/huggingface-responses-language-model.test.ts › HuggingFaceResponsesLanguageModel › message conversion › should handle assistant messages

12 个和上游用例一一对应，加标记、按 describe 包 mod；18 个只比了部分字段或换了输入，注释写明缺什么、完整用例在哪；2 个是 aimux 自己的测试（坏帧之后流继续、supported_urls）；三个 fix PR 另加的 3 个 aimux 测试也在这个文件末尾。函数体不变（逐行比对过）。

2. 剩下的上游用例（新目录，huggingface.rs 末尾 #[cfg(test)] mod tests;）

cargo test -p aimux-providers --lib huggingface::                    22 个
  src/huggingface/tests/mod.rs                 mod provider; mod responses;
  src/huggingface/tests/provider.rs            4 个   默认 / 自定义配置、responses 和 language_model 方法
  src/huggingface/tests/responses/responses_language_model.rs
    mod do_generate / do_stream / message_conversion / tool_calls / structured_output / reasoning   18 个
      /// upstream: … › doGenerate › basic text response › should handle MCP tools with annotations
      MockFetch::json(..) → provider.responses(MODEL).do_generate → 与上游 toMatchInlineSnapshot 的 JSON 比
  src/test_support/mod.rs                      #[path = "../../tests/common/mock_fetch.rs"] mod mock_fetch;   lib.rs 末尾 #[cfg(test)] mod test_support;
scripts/check_provider_boundaries.sh           规则 7c、8b 的 find 跳过 */tests/*（同 #[cfg(test)] 块）

3. aimux-providers/layout.toml（只有 [huggingface]）

12 个上游源文件：10 个 mapped（rust 是现在的源文件名）
  huggingface-provider.ts                       sub-feature 2 条，issue = 276：NoSuchModelError 的提示文字
  huggingface-responses-language-model.ts       registered 1 条，ref = "SSE 预读"：首事件错误
                                                sub-feature 1 条，issue = 276：UnsupportedFunctionalityError 的提示文字
responses/huggingface-responses-settings.ts、version.ts    not-applicable

harness 上的差别（期望值都没改）：createTestServer 换成 MockFetch，server.calls[0] 换成它记下的请求体；快照里值为 undefined 的键在 JSON 里省略；typeof provider === 'function' 换成调用 HuggingFaceProvider::call。

Type of change

• Bug fix (non-breaking)
• New feature (non-breaking)
• Breaking change
• New provider
• New / updated binding
• Docs / RFC
• Tests（上游测试迁移）

Checklist

• cargo +1.99 fmt -p aimux-providers -- --check passes
• cargo +1.99 clippy -p aimux-providers --lib --tests -- -D warnings passes
• cargo +1.99 test -p aimux-providers：lib 157（其中 huggingface 22）、huggingface_responses 35，以及用到 Hugging Face 的 cassette_full、conformance、package_user_agent、thin_wrapper_config，全过
• scripts/check_provider_boundaries.sh passes
• Commit messages follow Conventional Commits

Notes for reviewers

• 和 test: port the upstream Mistral tests #295、test: port the upstream Cohere tests #296、test: port the upstream DeepSeek tests #299、test: port the upstream Groq tests #301 一样新建了 src/test_support/mod.rs、aimux-providers/layout.toml，并改了边界脚本的同两行；这几处在各 PR 里内容相同，后合入的只需合并 layout.toml 的厂商表。
• 38 个上游用例和标记逐条对过：34 个各有一个标记，剩下 4 个在 layout.toml 的手写排除里。
• 基线是 master（fix: Hugging Face stream errors end with an error finish #307 已合入）。
• 跟踪 测试：补迁上游 AI SDK 测试（按用例名约 18% 对上） #278；错误提示文字的缺口挂在 Core 运行时：与 AI SDK 的剩余差距（对齐文档 §9.1 已知差距） #276。

https://claude.ai/code/session_01RoxcKU4zBD64Lri3e4Lrq5

---

Generated by Claude Code

[eric8810]

Hugging Face test port：34 个 marker + 4 个 layout exclusion 覆盖 38 个上游 case，fixtures 一致，无生产行为变化。Approve。

[eric8810]

Rebase is content-preserving: only master/parent merges and CHANGELOG/layout conflict resolution; tests and CI unchanged. Re-approving current head.

[eric8810]

Rebase verified content-preserving: only master/parent merges and CHANGELOG/layout conflict resolution; CI 16/16. Re-approving current head.

[eric8810]

Rebase verified content-preserving: only master/parent merges and conflict resolution; CI 16/16. Re-approving current head.

[eric8810]

Rebase verified content-preserving: only master/parent merges and conflict resolution; CI 16/16. Re-approving current head.

[eric8810]

Rebase verified content-preserving: only master merges and conflict resolution; CI 16/16. Re-approving current head.