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 集成层的核心 APIuseChat、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-utils0.0.1。此后experimental_useObject0.0.4、experimental_throttle0.0.70、附件管理0.0.22、keepLastMessageOnError0.0.21等能力陆续以实验性形态加入。1.0.0AI 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.0AI SDK 5引入ChatStoreChatTransport架构、消息的 typed tool parts、UI_MESSAGE泛型移除useAssistanthook破坏性变更支持resume恢复进行中的流。3.0.0AI SDK 6chat.addToolResult()更名为chat.addToolOutput()、新增 tool execution approval、onFinish回调携带finishReason、内部改用 Zod v4并因 CVE-2025-55182 收紧 React 版本要求。4.0.0AI SDK 7全部包转为 ESM-only、最低 Node.js 版本提升到 22新增 Realtime 语音对话与 MCP Apps 支持MCP App 工具调用默认拒绝deny-by-default。当前仓库中 packages/react/package.json 的版本号为4.0.100type: moduleengines.node 22peerDependencies要求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 可直接推导将构建产物目标切换为 ESM移除require(ai-sdk/react)用法将开发/部署环境的 Node.js 升级到 22 及以上若项目中使用experimental_useObject、experimental_throttle等旧名称替换为稳定导出见下节若在 React 中使用useAssistant需要迁移到基于ChatStore的新 API该 hook 在 2.0.0 已被移除。三、useChat 的架构演进ChatStore、ChatTransport 与 UI_MESSAGE 泛型useChat是ai-sdk/react的核心 hookpackages/react/src/use-chat.ts其 2.0.0 版本引入的ChatStoreChatTransport是理解后续所有行为的钥匙ChatTransport抽象如何把消息发送给服务端、如何接收流的传输层。CHANGELOG 4.0.12 的fix(react): use the latest transport in useChat instead of a stale one说明传输层实例会被持久引用必须保证组件重渲染后仍指向最新配置——这正是useChat中defaultTransport ?? new DefaultChatTransportUI_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 新增的显式清错 APIf2c7f19在 packages/react/src/chat.react.ts 的Chat类中实现。两个值得深入的关键选项源码见 use-chat.ts 第 49–62 行选项说明演进过程throttle消息与 data 更新的节流等待毫秒数控制 UI 渲染频率0.0.70 以experimental_throttle引入4.0.18 转正并保留 deprecated 别名resume是否恢复一条仍在进行中的生成流2.0.0canary 阶段c34ccd7引入resumeStream实现上throttleWaitMs throttle ?? experimental_throttleuse-chat.ts 第 71 行节流逻辑封装在 packages/react/src/throttle.tsresume为true时会在 effect 中调用chatRef.current.resumeStream()use-chat.ts 第 234–237 行并把resumeStream暴露到返回的 helpers 中第 248 行。CHANGELOG 中反复出现的三类 useChat 修复能帮你避免常见的坑stale closures闭包过期3.0.24 通过中间代理回调转发到 ref的方式保证onToolCall等回调始终使用最新版本而不是在每次属性变化时重建 chat 实例并附带回归测试。4.0.8 的fix: Treat nullish useChat IDs the same as omitted IDs也属于同类问题——id为null/undefined时应视为未传避免每次渲染都重建实例。节流节奏4.0.59 修复了无关的 React 渲染不得在节流节奏之前提前发布消息快照的问题确保throttle真正按配置的节奏发布快照。性能4.0.67 避免在流式聊天过程中反复 deep-clone 累积的消息负载。四、useCompletion 与 useObject稳定化之路useCompletionuseCompletionpackages/react/src/use-completion.ts用于非多轮对话的补全场景其关键变更4.0.64提交 prompt 后重置输入框内容4.0.65为 Completion API 增加类型化自定义 bodyfeat(ui): add typed custom bodies to Completion APIs4.0.18throttle选项同样在此 hook 上转正。useObjectuseObjectpackages/react/src/use-object.ts用于从模型流式生成结构化对象其演进最能体现实验性 → 稳定的 SDK 节奏0.0.4以experimental_useObject加入0.0.42支持非 Zod schemaFlexibleSchema0.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.35onFinish回调、加载新结果时清空旧对象4.0.69当 API URL 变化时保留已生成的useObject值4.0.19useObject转正为稳定导出experimental_useObject保留为 deprecated 别名见 packages/react/src/index.ts 第 22 行类型别名Experimental_UseObjectOptions/Experimental_UseObjectHelpers同样保留。五、Realtime 语音对话experimental_useRealtime4.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 tokenexperimental_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 与宿主通信因此安全加固是绝对主线工具调用默认拒绝deny-by-default4.0.0 / commit555c5deexperimental_MCPAppRenderer的 bridge 原本只在allowedTools非空时检查白名单省略allowedTools会跳过检查导致 MCP App iframe 发出的每个tools/call都被转发给宿主的callTool——恶意或被攻破的 MCP 服务器可能调用宿主接入的任何工具。修复后未显式提供allowedTools时所有tools/call一律拒绝要暴露工具必须在handlers.allowedTools中显式列出。CSP 消毒4.0.29 / commit519c72bgetMCPAppCSP对服务端下发的 CSP 域名进行消毒防止值注入额外的指令、source 或策略。资源元数据与桥接加固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.0useAssistant移除ChatRequest类型内联移除managed chat inputs 移除。3.0.0chat.addToolResult()→chat.addToolOutput()useChat的onFinish回调新增finishReason参数React 19-rc 支持被移除针对 CVE-2025-55182 收紧 RSC 最低版本3.0.0 条目中的af65ab6。4.0.0ESM-onlyNode ≥ 22MCP 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仅为 devDependency3.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/nextNext.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考