企业官网建设流程全解析

AI SDK React 包（@ai-sdk/react）版本演进全解析：从 useChat 到 Realtime 与 MCP Apps

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai

本篇指南以仓库内 packages/react/CHANGELOG.md（覆盖 0.0.1 → 4.0.100 共 6438 行变更记录）为主体，系统梳理 AI SDK 官方 React 集成层的核心 API（useChat、useCompletion、useObject、useRealtime）、重大破坏性变更（ESM-only、Node 22+）、Realtime 语音对话支持与 MCP Apps 安全模型，并结合 packages/react/src 源码给出可验证的实现依据。读完你将能理解 @ai-sdk/react 各版本之间的能力边界、关键选项（throttle、resume、ChatStore/ChatTransport、UI_MESSAGE泛型）的由来与正确用法，以及如何为 React 应用接入 AI 流式对话、结构化对象生成和实时语音交互。

一、版本体系速览：从 0.0.1 到 4.0.100 的三次大版本跃迁

从 CHANGELOG 可以还原出 @ai-sdk/react 的完整演进脉络：

• 0.0.1（初始版本）：chore: extracted ui library support into separate modules，从ai主包中拆出独立的 UI 支持模块，并依赖@ai-sdk/ui-utils@0.0.1。此后experimental_useObject（0.0.4）、experimental_throttle（0.0.70）、附件管理（0.0.22）、keepLastMessageOnError（0.0.21）等能力陆续以实验性形态加入。
• 1.0.0（AI SDK 4.0 发布）：一次大规模"清理式"发版，移除useChat的 roundtrip 选项、streamMode、experimental_useAssistant导出、experimental_addToolResult、useObject的setInputhelper 与 legacy function/tool calling，并将useChat的keepLastMessageOnError默认值改为true（见 CHANGELOG 1.0.0 条目）。
• 2.0.0（AI SDK 5）：引入ChatStore+ChatTransport架构、消息的 typed tool parts、UI_MESSAGE泛型，移除useAssistanthook（破坏性变更），支持resume恢复进行中的流。
• 3.0.0（AI SDK 6）：chat.addToolResult()更名为chat.addToolOutput()、新增 tool execution approval、onFinish回调携带finishReason、内部改用 Zod v4，并因 CVE-2025-55182 收紧 React 版本要求。
• 4.0.0（AI SDK 7）：全部包转为 ESM-only、最低 Node.js 版本提升到 22，新增 Realtime 语音对话与 MCP Apps 支持，MCP App 工具调用默认拒绝（deny-by-default）。

当前仓库中 packages/react/package.json 的版本号为4.0.100，"type": "module"，engines.node >= 22，peerDependencies要求react ^18 || ~19.0.1 || ~19.1.2 || ^19.2.1，与 CHANGELOG 顶部记录完全一致，可作为当前稳定分支的对照基准。

二、4.0.0 里程碑：ESM-only 与 Node 22+ 带来的迁移要求

4.0.0 是@ai-sdk/react最重要的一次 Major 发布，其变更集中在两个提交（commitef992f8与7fc6bd6）：

• 移除 CommonJS 导出，全面 ESM-only：所有包"type": "module"，使用require()的消费者必须切换到 ESMimport语法。对应源码，packages/react/package.json 的exports字段仅提供import与default两种条件导出，没有require分支。
• Node.js 最低版本提升至 22：支持版本为 22、24、26。这会影响所有在服务端使用该包的场景（例如 Next.js Route Handlers 中的流式接口）。

此外 4.0.0 还包含一次"全量发布"（trigger release for all packages after provenance setup）与publishConfig.provenance: true的供应链接入（见 package.json 的publishConfig字段）。

迁移清单（从 CHANGELOG 可直接推导）：

1. 将构建产物目标切换为 ESM，移除require('@ai-sdk/react')用法；
2. 将开发/部署环境的 Node.js 升级到 22 及以上；
3. 若项目中使用experimental_useObject、experimental_throttle等旧名称，替换为稳定导出（见下节）；
4. 若在 React 中使用useAssistant，需要迁移到基于ChatStore的新 API（该 hook 在 2.0.0 已被移除）。

三、useChat 的架构演进：ChatStore、ChatTransport 与 UI_MESSAGE 泛型

useChat是@ai-sdk/react的核心 hook（packages/react/src/use-chat.ts），其 2.0.0 版本引入的ChatStore+ChatTransport是理解后续所有行为的钥匙：

• ChatTransport：抽象"如何把消息发送给服务端、如何接收流"的传输层。CHANGELOG 4.0.12 的fix(react): use the latest transport in useChat instead of a stale one说明传输层实例会被持久引用，必须保证组件重渲染后仍指向最新配置——这正是useChat中defaultTransport ??= new DefaultChatTransport<UI_MESSAGE>()（use-chat.ts 第 103–106 行）这段"惰性单例"代码存在的意义。
• UI_MESSAGE泛型：useChat以UI_MESSAGE为泛型参数，配合 2.0.0 的 typed tool parts，让消息中的 tool 部分（输入、输出、状态）在类型层面可见，替代了旧的ChatRequest类型（chore (ui): inline/remove ChatRequest type）。
• Chat.clearError()：2.0.0 新增的显式清错 API（f2c7f19），在 packages/react/src/chat.react.ts 的Chat类中实现。

两个值得深入的关键选项（源码见 use-chat.ts 第 49–62 行）：

实现上，throttleWaitMs = throttle ?? experimental_throttle（use-chat.ts 第 71 行），节流逻辑封装在 packages/react/src/throttle.ts；resume为true时会在 effect 中调用chatRef.current.resumeStream()（use-chat.ts 第 234–237 行），并把resumeStream暴露到返回的 helpers 中（第 248 行）。

CHANGELOG 中反复出现的三类 useChat 修复，能帮你避免常见的坑：

1. stale closures（闭包过期）：3.0.24 通过"中间代理回调转发到 ref"的方式，保证onToolCall等回调始终使用最新版本，而不是在每次属性变化时重建 chat 实例，并附带回归测试。4.0.8 的fix: Treat nullish useChat IDs the same as omitted IDs也属于同类问题——id为null/undefined时应视为"未传"，避免每次渲染都重建实例。
2. 节流节奏：4.0.59 修复了"无关的 React 渲染不得在节流节奏之前提前发布消息快照"的问题，确保throttle真正按配置的节奏发布快照。
3. 性能：4.0.67 避免在流式聊天过程中反复 deep-clone 累积的消息负载。

四、useCompletion 与 useObject：稳定化之路

useCompletion

useCompletion（packages/react/src/use-completion.ts）用于非多轮对话的补全场景，其关键变更：

• 4.0.64：提交 prompt 后重置输入框内容；
• 4.0.65：为 Completion API 增加类型化自定义 body（feat(ui): add typed custom bodies to Completion APIs）；
• 4.0.18：throttle选项同样在此 hook 上转正。

useObject

useObject（packages/react/src/use-object.ts）用于从模型流式生成结构化对象，其演进最能体现"实验性 → 稳定"的 SDK 节奏：

• 0.0.4：以experimental_useObject加入；
• 0.0.42：支持非 Zod schema（FlexibleSchema）；
• 0.0.60 / 3.0.28：支持headers选项，且 3.0.28 进一步支持async/function headers——可动态生成请求头（如异步获取 auth token），且不会触发 hook 重新渲染，与useChat对齐，解决基于 state 的 headers 配合useEffect造成的死循环问题；
• 1.2.2：增加credentials支持；
• 0.0.34 / 0.0.35：onFinish回调、加载新结果时清空旧对象；
• 4.0.69：当 API URL 变化时保留已生成的useObject值；
• 4.0.19：useObject转正为稳定导出，experimental_useObject保留为 deprecated 别名（见 packages/react/src/index.ts 第 22 行），类型别名Experimental_UseObjectOptions/Experimental_UseObjectHelpers同样保留。

五、Realtime 语音对话：experimental_useRealtime

4.0.0 引入了一等公民的 realtime（语音对语音）API 支持（commitce769dd），这是 CHANGELOG 中篇幅最长的功能条目：

• @ai-sdk/provider中定义了Experimental_RealtimeModelV4规范，统一事件类型与工厂函数；
• OpenAI、Google、xAI 三个提供商提供 realtime 实现：openai.experimental_realtime()/google.experimental_realtime()/xai.experimental_realtime()，服务端与浏览器均可使用；
• 每个 provider 提供静态.getToken()方法，用于服务端创建一次性 ephemeral token；
• experimental_getRealtimeToolDefinitions辅助函数生成 provider 会话工具定义；
• experimental_useRealtimehook（在@ai-sdk/react中）返回UIMessage[]，与useChat的消息模型对齐，支持onToolCall与addToolOutput驱动客户端执行工具；
• inputAudioTranscription会话配置可在 provider 支持时展示转写后的用户音频消息。

源码佐证：packages/react/src/use-realtime.ts 中get messages(): UIMessage[]（第 66 行）、useRealtime主函数（第 151 行），以及末尾的export const experimental_useRealtime = useRealtime（第 246 行）——与experimental_useObject相同的"先实验后稳定"命名策略。同目录 use-realtime.test.tsx 提供了该 hook 的测试覆盖。

配套能力：4.0.15增加实验性流式转录（transcription）支持，覆盖 OpenAIgpt-realtime-whisper与 xAI WebSocket STT，为语音对话补上"听"的能力。

六、MCP Apps：集成外部应用的安全边界

CHANGELOG 在 4.0.x 阶段密集出现 MCP Apps 相关条目，对应的实现集中在 packages/react/src/mcp-apps 目录（含bridge.ts、app-renderer.tsx、sandbox.ts、app-frame.tsx、utils.ts、types.ts及其测试文件）。核心是把不可信的 MCP App 内容加载进 iframe，并通过 bridge 与宿主通信，因此安全加固是绝对主线：

1. 工具调用默认拒绝（deny-by-default，4.0.0 / commit555c5de）：experimental_MCPAppRenderer的 bridge 原本只在allowedTools非空时检查白名单，省略allowedTools会跳过检查，导致 MCP App iframe 发出的每个tools/call都被转发给宿主的callTool——恶意或被攻破的 MCP 服务器可能调用宿主接入的任何工具。修复后：未显式提供allowedTools时，所有tools/call一律拒绝；要暴露工具，必须在handlers.allowedTools中显式列出。
2. CSP 消毒（4.0.29 / commit519c72b）：getMCPAppCSP对服务端下发的 CSP 域名进行消毒，防止值注入额外的指令、source 或策略。
3. 资源元数据与桥接加固（4.0.31 / commit48e7e78）：
   • 运行时校验_meta.ui，丢弃畸形或非字符串字段；
   • 通过新的sandbox.allowedPermissions白名单对 iframe 权限做默认拒绝的闸门控制；
   • 推导具体的postMessage目标 origin，并校验入站消息的 origin；
   • 校验入站 bridge 参数：resources/read仅限ui://资源，ui/open-link仅允许https/http/mailto；
   • 新增fingerprintMCPAppResource/detectMCPAppResourceDrift，用于固定（pinning）并对比 App 资源，检测资源漂移。

从源码结构看，sandbox.ts对应 iframe 权限模型，bridge.ts对应宿主与 iframe 的 postMessage 桥接，app-renderer.tsx是experimental_MCPAppRenderer的渲染入口，app-frame.tsx封装受限 iframe；三者配合utils.ts/types.ts构成完整的"加载—校验—桥接"链路。集成 MCP Apps 时，请始终显式配置allowedTools与sandbox.allowedPermissions，不要依赖默认行为。

七、从 CHANGELOG 提炼的实战注意事项

1. 版本升级时的破坏性变更速查

• 2.0.0：useAssistant移除；ChatRequest类型内联移除；managed chat inputs 移除。
• 3.0.0：chat.addToolResult()→chat.addToolOutput()；useChat的onFinish回调新增finishReason参数；React 19-rc 支持被移除（针对 CVE-2025-55182 收紧 RSC 最低版本，3.0.0 条目中的af65ab6）。
• 4.0.0：ESM-only；Node ≥ 22；MCP App 工具调用默认拒绝。

2. 依赖拓扑与打包细节

CHANGELOG 的依赖更新条目（Patch Changes 中的Updated dependencies）揭示了包的依赖面：package.json 声明@ai-sdk/mcp、@ai-sdk/provider、@ai-sdk/provider-utils、ai（均 workspace 内联）、swr与throttleit为运行时依赖，@ai-sdk/test-server仅为 devDependency（3.0.0 中10c1322将其移出运行时依赖）。此外 3.0.50 的excluded tests from src folder in npm package与 3.0.48 的add src folders to package bundle说明 npm 包内的src目录会被完整发布（测试文件除外），便于调试。

3. 测试与验证路径

仓库为这些行为提供了完整测试，可作为行为契约参考：

• packages/react/src/use-chat.ui.test.tsx ——useChat的 UI 行为测试；
• packages/react/src/use-object.ui.test.tsx ——useObject的 UI 行为测试；
• packages/react/src/use-completion.ui.test.tsx ——useCompletion测试；
• packages/react/src/use-realtime.test.tsx —— Realtime hook 测试；
• packages/react/src/mcp-apps 下的bridge.test.ts、sandbox.test.ts、app-frame.test.tsx、utils.test.ts—— MCP Apps 安全链路测试。

运行方式：在packages/react目录执行pnpm test（对应 package.json 中"test": "vitest --config vitest.config.js --run"），或pnpm test:watch进入监听模式；pnpm type-check可校验类型。

4. 查看文档与示例

• 包的官方说明见 packages/react/README.md，其中列出了useChat、useCompletion、useObject三个核心 hook；
• 仓库的 React 实战示例位于 examples/next（Next.js 集成）与 examples/ai-e2e-next（端到端 Agent 应用），其中大量使用useChat与工具调用；Realtime 相关的 provider 实现可参考 packages/openai、packages/google 与 packages/xai 中的experimental_realtime()入口。

八、结语：CHANGELOG 即能力地图

packages/react/CHANGELOG.md不只是发布流水账，它完整记录了@ai-sdk/react从 UI 辅助模块到"对话 + 补全 + 结构化对象 + 实时语音 + MCP Apps"全栈 React AI 基础设施的能力地图。理解这张地图，你就能在升级时精准预判破坏性变更（ESM-only、addToolOutput改名、MCP 默认拒绝），在排查问题时快速定位对应修复（stale closure、节流、transport 引用），并在新项目里正确使用throttle、resume、typed tool parts 与UI_MESSAGE泛型这些经过多版本打磨的稳定 API。

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai