ai-sdk/svelte 演进全解AI SDK 中 Svelte 5 UI 层的版本脉络、破坏性变更与结构化对象能力【免费下载链接】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/svelte/CHANGELOG.md 为骨架梳理ai-sdk/svelte从 4.x 到 5.0.97 的完整演进脉络并结合 packages/svelte/src 源码与测试解读Chat、Completion、StructuredObject三大核心 API 的实现原理与配置细节。读完你将掌握Svelte 5 运行时的状态管理方式、v5 大版本的 ESM-only 与 Node 22 底线、StructuredObject从 experimental 到 stable 的迁移路径以及 typed custom bodies、fallback 错误处理等能力更新的底层机制。一、包定位AI SDK 的 Svelte UI 层ai-sdk/svelte是 AI SDK 官方提供的 Svelte UI 组件库当前版本 5.0.97见 package.json与ai7.0.97、ai-sdk/provider-utils5.0.39同步发布。它围绕三类核心场景提供响应式 APIChat多轮对话与 Agent 交互Completion单轮文本补全StructuredObject按 Schema 流式生成结构化 JSON 对象。包入口 index.ts 统一导出上述三个类与createAIContext()。值得注意的设计是Experimental_StructuredObject与Experimental_StructuredObjectOptions作为带deprecated标注的别名导出与 CHANGELOG 5.0.18 中PromoteStructuredObjectto stable exports, with deprecated experimental aliases for backwards compatibility的变更一一对应。从 package.json 的依赖与工程配置可见其约束peerDependenciessvelte^5.31.0即只面向 Svelte 5enginesnode 22与 CHANGELOG 中Raise minimum supported Node.js version to 22一致exports仅暴露svelte条件导出./dist/index.js且type: module标记为 ESM-only测试栈vitest testing-library/svelte jsdom通过 vitest.config.ts 与 vitest-setup-client.ts 驱动。二、v5.0.0 大版本ESM-only 与 Node 22 是硬门槛CHANGELOG 的5.0.0一节集中记录了 v7 预发布期的三项重大变更它们是升级到 5.x 时必须先评估的破坏性因素移除 CommonJS 导出ef992f8所有包改为 ESM-onlytype: module。使用require()的消费方必须切换到 ESMimport语法若项目仍依赖 CJS 互操作需先改造构建链。启动 v7 预发布83596125.0.0 之后是一长串5.0.0-beta.x与5.0.0-canary.x版本最终收敛为稳定的 5.0.x 系列。Node 版本底线提升7fc6bd6最低 Node.js 版本提高到 22受支持版本为 22、24、26。低于 22 的运行环境将无法使用本包。其余围绕 5.0.0 的 Patch 大多为发布基建类9f0e36cprovenance 配置后的全量触发、0c4c275canary 触发、b8396f0beta 触发以及258c093的导入一致性整理避免重复导入与循环依赖。从版本号演进看5.0.97 这一代还持续跟随上游几乎所有 Patch 都只更新ai与ai-sdk/provider-utils依赖说明 UI 层刻意保持薄封装——把流式协议、消息解析、Schema 校验等重逻辑下沉到核心包Svelte 包只负责 Svelte 5 的响应式适配。三、Svelte 5 响应式核心$state / $derived 与共享 Store要理解本包为何是 Svelte 专属实现需要看它的状态层。Chat在 chat.svelte.ts 中通过SvelteChatState实现ChatState接口class SvelteChatStateUI_MESSAGE extends UIMessage implements ChatStateUI_MESSAGE { messages: UI_MESSAGE[]; status $stateChatStatus(ready); error $stateError | undefined(undefined); constructor(messages: UI_MESSAGE[] []) { this.messages $state(messages); } setMessages (messages: UI_MESSAGE[]) { this.messages messages; }; pushMessage (message: UI_MESSAGE) { this.messages.push(message); }; popMessage () { this.messages.pop(); }; replaceMessage (index: number, message: UI_MESSAGE) { this.messages[index] message; }; snapshot T(thing: T): T $state.snapshot(thing) as T; }关键点状态字段全部用 Svelte 5 的$state声明messages的变更push/pop/按索引替换都会触发依赖它的组件重新渲染snapshot()借助$state.snapshot取出深层不可变快照用于向核心AbstractChat传递序列化数据Chat继承自核心包ai的AbstractChatUI_MESSAGE仅注入 Svelte 状态实现业务逻辑发送、流式接收、tool call完全复用核心层。StructuredObject与Completion则使用基于KeyedStore的共享 Store 模式见 structured-object-context.svelte.ts 与 completion-context.svelte.tsStructuredObjectStore持有object、loading、error三个$state字段KeyedStructuredObjectStore按id索引多个实例的状态。createAIContext()见 context-provider.ts在组件树顶层创建并注入这两个 Store使不同组件中相同id的Completion/StructuredObject共享同一份响应式状态——这正是 CHANGELOG 5.0.92 中d1904d3empty HTTP response bodies 的 fallback 错误等 UI 层修复能跨组件生效的前提。四、StructuredObject从 experimental 到 stable 的完整能力清单CHANGELOG 中与结构化对象直接相关的两个关键条目5.0.180363440useObjectReact、Vue与StructuredObjectSvelte晋升为 stable 导出同时保留 deprecated 的实验别名以保证向后兼容。对 Svelte 用户而言直接使用StructuredObject即可旧代码中的Experimental_StructuredObject会触发deprecated提示。5.0.62e0bcf52为 Completion API 增加 typed custom bodies——CompletionOptionsBODY现在是泛型body 类型由调用方显式约束。StructuredObject的完整选项定义在 structured-object.svelte.ts选项类型说明apistring以分块文本流式返回 JSON 的 API 端点schemaFlexibleSchema定义完整对象形状的 Schema用于流式校验idstring唯一标识缺省时随机生成跨组件共享状态需显式指定initialValueDeepPartialRESULT初始对象值fetchFetchFunction自定义 fetch可拦截请求或用于测试onFinish(event) void流结束回调object在 Schema 校验失败时为undefinederror携带校验错误onError(error) void出错回调headersRecordstring, string \| Headers附加请求头credentialsRequestCredentialsomit \| same-origin \| include默认same-origin实例方法包括submit(input)以 JSON body 发起 POST 请求、stop()立即中止请求但保留已生成的 partial object、clear()中止并清空状态。其submit实现值得留意内部用parsePartialJson对累积文本做增量解析再以isDeepEqualData去重避免重复赋值触发多余渲染流结束时用safeValidateTypesasSchema做最终 Schema 校验结果决定onFinish中object与error的取值。这一增量解析 去重 终值校验链路正是 CHANGELOG 中各类ai-sdk/provider-utils升级要保障的稳定性核心。五、Completiontyped custom bodies 与双流协议Completion在 5.0.62 之后支持CompletionOptionsBODY extends object泛型complete(prompt, options?)的第二参数可携带headers与body与构造选项中的对应字段合并后交给核心层callCompletionApi见 completion.svelte.ts。该类的默认值与行为默认 API 端点/api/completion默认id由generateId()生成streamProtocol默认data可切换为textinput是$state可写字段可直接与表单输入双向绑定handleSubmit会在有输入时自动调用completecompletion、error、loading均为响应式 getter绑定到模板即可自动更新。测试 completion.svelte.test.ts 验证了两条关键行为streamProtocol: text下接收纯文本 chunkHello, ,, world, .能正确拼接为Hello, world.data协议下消费text-start/text-delta/text-end消息块onFinish(prompt, completion)恰好触发一次。这套测试与ai-sdk/test-server的createTestServer结合说明了 UI 层不依赖真实网络即可验证流协议解析。六、围绕 v4 的历史演进Svelte 5 支持与消息模型重构回看 4.x 时代的变更能更完整地理解当前 API 形态的来源这些条目同样记录在 CHANGELOG 中Svelte 5 适配4.x 中期feat (ui/svelte): Modern Svelte 59e2cb6f是 4.x 系列的 breaking change随后feat (provider/svelte): support Svelte 530e6ebd与feat (ui/svelte): support Svelte 5 peer dependencyd92fd9f逐步放开了 peer 依赖fix: Remove hard-cast causing Readable to be treated as Writable57cf070修掉了 Svelte 4Readable/Writable语义残留。消息模型重构feat (ui): introduce message parts for useChatbcc61d4引入了消息分区模型feat (ui): introduce ChatStore and ChatTransport40acf9b把传输层独立出来chore (ui): remove managed chat inputs98f25e5随之删除托管输入chore (ui): inline/remove ChatRequest type496bbc1进一步简化了请求类型。这些重构奠定了当前Chat继承AbstractChat、注入 Svelte 状态的架构。状态与错误处理feat (ui): add useChat statusc43df41引入status字段fix (ui): set status to ready after stream was aborted60c3220修复中止后的状态残留chore (ui): set default value of useChat keepLastMessageOnError to truefe4f109将错误保留消息设为默认。结构化对象增强feat: add credentials support to experimental useObject and StructuredObjectd92fa29为StructuredObject增加credentials选项Add clear object function to StructuredObjectac34802引入clear()。工具与附加能力feat (ai/ui): add setData helper to useChatcaedcda、experimental attachment support5d7a3b6、feat (ui): expose useChat id and send it to the server37f4510、typed tool parts in ui messages0a710d8等都是当前版本能力的历史地基。Zod 生态feature: using Zod 4 for internal stuffd1a034f与fix: improve Zod compatibility205077b说明 Schema 层对 Zod 4 的兼容是持续投入的方向。另外两条工程类变更值得注意fix: moved dependency ai-sdk/test-server to devDependencies10c1322保证运行时依赖干净chore: excluded tests from src folder in npm package4de5a1d使发布产物不再携带测试文件当前 package.json 的files字段通过!src/**/*.test.*等规则落实了这一点。七、升级与迁移速查综合 CHANGELOG 中的破坏性条目给出升级检查清单Node 版本必须 ≥ 22推荐 22 / 24 / 26见 package.json 的engines。模块系统5.x 为 ESM-onlyrequire(ai-sdk/svelte)不再可用全部改为import。Svelte 版本peer 依赖要求svelte^5.31.0Svelte 4 项目需先完成框架升级。结构化对象 API若仍在使用Experimental_StructuredObject迁移到StructuredObject仅换名行为不变废弃别名仍保留。Completion body 类型升级到 5.0.62 后可利用CompletionOptionsBODY泛型获得请求体类型提示注意complete()的 options 会与构造选项中的headers/body做浅合并。依赖关系上本包与ai、ai-sdk/provider-utils保持严格同步发布workspace 依赖任何 UI 层的流式协议、错误处理、Schema 校验修复都跟随核心包版本落地——这也是为什么 CHANGELOG 中绝大多数条目是Updated dependencies。需要深入验证某一行为时可直接阅读 packages/svelte/src 下的源码与*.test.ts测试它们与 CHANGELOG 共同构成了本包最完整的行为文档。【免费下载链接】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），仅供参考 @ai-sdk/svelte 演进全解：AI SDK 中 Svelte 5 UI 层的版本脉络、破坏性变更与结构化对象能力
ai-sdk/svelte 演进全解AI SDK 中 Svelte 5 UI 层的版本脉络、破坏性变更与结构化对象能力【免费下载链接】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/svelte/CHANGELOG.md 为骨架梳理ai-sdk/svelte从 4.x 到 5.0.97 的完整演进脉络并结合 packages/svelte/src 源码与测试解读Chat、Completion、StructuredObject三大核心 API 的实现原理与配置细节。读完你将掌握Svelte 5 运行时的状态管理方式、v5 大版本的 ESM-only 与 Node 22 底线、StructuredObject从 experimental 到 stable 的迁移路径以及 typed custom bodies、fallback 错误处理等能力更新的底层机制。一、包定位AI SDK 的 Svelte UI 层ai-sdk/svelte是 AI SDK 官方提供的 Svelte UI 组件库当前版本 5.0.97见 package.json与ai7.0.97、ai-sdk/provider-utils5.0.39同步发布。它围绕三类核心场景提供响应式 APIChat多轮对话与 Agent 交互Completion单轮文本补全StructuredObject按 Schema 流式生成结构化 JSON 对象。包入口 index.ts 统一导出上述三个类与createAIContext()。值得注意的设计是Experimental_StructuredObject与Experimental_StructuredObjectOptions作为带deprecated标注的别名导出与 CHANGELOG 5.0.18 中PromoteStructuredObjectto stable exports, with deprecated experimental aliases for backwards compatibility的变更一一对应。从 package.json 的依赖与工程配置可见其约束peerDependenciessvelte^5.31.0即只面向 Svelte 5enginesnode 22与 CHANGELOG 中Raise minimum supported Node.js version to 22一致exports仅暴露svelte条件导出./dist/index.js且type: module标记为 ESM-only测试栈vitest testing-library/svelte jsdom通过 vitest.config.ts 与 vitest-setup-client.ts 驱动。二、v5.0.0 大版本ESM-only 与 Node 22 是硬门槛CHANGELOG 的5.0.0一节集中记录了 v7 预发布期的三项重大变更它们是升级到 5.x 时必须先评估的破坏性因素移除 CommonJS 导出ef992f8所有包改为 ESM-onlytype: module。使用require()的消费方必须切换到 ESMimport语法若项目仍依赖 CJS 互操作需先改造构建链。启动 v7 预发布83596125.0.0 之后是一长串5.0.0-beta.x与5.0.0-canary.x版本最终收敛为稳定的 5.0.x 系列。Node 版本底线提升7fc6bd6最低 Node.js 版本提高到 22受支持版本为 22、24、26。低于 22 的运行环境将无法使用本包。其余围绕 5.0.0 的 Patch 大多为发布基建类9f0e36cprovenance 配置后的全量触发、0c4c275canary 触发、b8396f0beta 触发以及258c093的导入一致性整理避免重复导入与循环依赖。从版本号演进看5.0.97 这一代还持续跟随上游几乎所有 Patch 都只更新ai与ai-sdk/provider-utils依赖说明 UI 层刻意保持薄封装——把流式协议、消息解析、Schema 校验等重逻辑下沉到核心包Svelte 包只负责 Svelte 5 的响应式适配。三、Svelte 5 响应式核心$state / $derived 与共享 Store要理解本包为何是 Svelte 专属实现需要看它的状态层。Chat在 chat.svelte.ts 中通过SvelteChatState实现ChatState接口class SvelteChatStateUI_MESSAGE extends UIMessage implements ChatStateUI_MESSAGE { messages: UI_MESSAGE[]; status $stateChatStatus(ready); error $stateError | undefined(undefined); constructor(messages: UI_MESSAGE[] []) { this.messages $state(messages); } setMessages (messages: UI_MESSAGE[]) { this.messages messages; }; pushMessage (message: UI_MESSAGE) { this.messages.push(message); }; popMessage () { this.messages.pop(); }; replaceMessage (index: number, message: UI_MESSAGE) { this.messages[index] message; }; snapshot T(thing: T): T $state.snapshot(thing) as T; }关键点状态字段全部用 Svelte 5 的$state声明messages的变更push/pop/按索引替换都会触发依赖它的组件重新渲染snapshot()借助$state.snapshot取出深层不可变快照用于向核心AbstractChat传递序列化数据Chat继承自核心包ai的AbstractChatUI_MESSAGE仅注入 Svelte 状态实现业务逻辑发送、流式接收、tool call完全复用核心层。StructuredObject与Completion则使用基于KeyedStore的共享 Store 模式见 structured-object-context.svelte.ts 与 completion-context.svelte.tsStructuredObjectStore持有object、loading、error三个$state字段KeyedStructuredObjectStore按id索引多个实例的状态。createAIContext()见 context-provider.ts在组件树顶层创建并注入这两个 Store使不同组件中相同id的Completion/StructuredObject共享同一份响应式状态——这正是 CHANGELOG 5.0.92 中d1904d3empty HTTP response bodies 的 fallback 错误等 UI 层修复能跨组件生效的前提。四、StructuredObject从 experimental 到 stable 的完整能力清单CHANGELOG 中与结构化对象直接相关的两个关键条目5.0.180363440useObjectReact、Vue与StructuredObjectSvelte晋升为 stable 导出同时保留 deprecated 的实验别名以保证向后兼容。对 Svelte 用户而言直接使用StructuredObject即可旧代码中的Experimental_StructuredObject会触发deprecated提示。5.0.62e0bcf52为 Completion API 增加 typed custom bodies——CompletionOptionsBODY现在是泛型body 类型由调用方显式约束。StructuredObject的完整选项定义在 structured-object.svelte.ts选项类型说明apistring以分块文本流式返回 JSON 的 API 端点schemaFlexibleSchema定义完整对象形状的 Schema用于流式校验idstring唯一标识缺省时随机生成跨组件共享状态需显式指定initialValueDeepPartialRESULT初始对象值fetchFetchFunction自定义 fetch可拦截请求或用于测试onFinish(event) void流结束回调object在 Schema 校验失败时为undefinederror携带校验错误onError(error) void出错回调headersRecordstring, string \| Headers附加请求头credentialsRequestCredentialsomit \| same-origin \| include默认same-origin实例方法包括submit(input)以 JSON body 发起 POST 请求、stop()立即中止请求但保留已生成的 partial object、clear()中止并清空状态。其submit实现值得留意内部用parsePartialJson对累积文本做增量解析再以isDeepEqualData去重避免重复赋值触发多余渲染流结束时用safeValidateTypesasSchema做最终 Schema 校验结果决定onFinish中object与error的取值。这一增量解析 去重 终值校验链路正是 CHANGELOG 中各类ai-sdk/provider-utils升级要保障的稳定性核心。五、Completiontyped custom bodies 与双流协议Completion在 5.0.62 之后支持CompletionOptionsBODY extends object泛型complete(prompt, options?)的第二参数可携带headers与body与构造选项中的对应字段合并后交给核心层callCompletionApi见 completion.svelte.ts。该类的默认值与行为默认 API 端点/api/completion默认id由generateId()生成streamProtocol默认data可切换为textinput是$state可写字段可直接与表单输入双向绑定handleSubmit会在有输入时自动调用completecompletion、error、loading均为响应式 getter绑定到模板即可自动更新。测试 completion.svelte.test.ts 验证了两条关键行为streamProtocol: text下接收纯文本 chunkHello, ,, world, .能正确拼接为Hello, world.data协议下消费text-start/text-delta/text-end消息块onFinish(prompt, completion)恰好触发一次。这套测试与ai-sdk/test-server的createTestServer结合说明了 UI 层不依赖真实网络即可验证流协议解析。六、围绕 v4 的历史演进Svelte 5 支持与消息模型重构回看 4.x 时代的变更能更完整地理解当前 API 形态的来源这些条目同样记录在 CHANGELOG 中Svelte 5 适配4.x 中期feat (ui/svelte): Modern Svelte 59e2cb6f是 4.x 系列的 breaking change随后feat (provider/svelte): support Svelte 530e6ebd与feat (ui/svelte): support Svelte 5 peer dependencyd92fd9f逐步放开了 peer 依赖fix: Remove hard-cast causing Readable to be treated as Writable57cf070修掉了 Svelte 4Readable/Writable语义残留。消息模型重构feat (ui): introduce message parts for useChatbcc61d4引入了消息分区模型feat (ui): introduce ChatStore and ChatTransport40acf9b把传输层独立出来chore (ui): remove managed chat inputs98f25e5随之删除托管输入chore (ui): inline/remove ChatRequest type496bbc1进一步简化了请求类型。这些重构奠定了当前Chat继承AbstractChat、注入 Svelte 状态的架构。状态与错误处理feat (ui): add useChat statusc43df41引入status字段fix (ui): set status to ready after stream was aborted60c3220修复中止后的状态残留chore (ui): set default value of useChat keepLastMessageOnError to truefe4f109将错误保留消息设为默认。结构化对象增强feat: add credentials support to experimental useObject and StructuredObjectd92fa29为StructuredObject增加credentials选项Add clear object function to StructuredObjectac34802引入clear()。工具与附加能力feat (ai/ui): add setData helper to useChatcaedcda、experimental attachment support5d7a3b6、feat (ui): expose useChat id and send it to the server37f4510、typed tool parts in ui messages0a710d8等都是当前版本能力的历史地基。Zod 生态feature: using Zod 4 for internal stuffd1a034f与fix: improve Zod compatibility205077b说明 Schema 层对 Zod 4 的兼容是持续投入的方向。另外两条工程类变更值得注意fix: moved dependency ai-sdk/test-server to devDependencies10c1322保证运行时依赖干净chore: excluded tests from src folder in npm package4de5a1d使发布产物不再携带测试文件当前 package.json 的files字段通过!src/**/*.test.*等规则落实了这一点。七、升级与迁移速查综合 CHANGELOG 中的破坏性条目给出升级检查清单Node 版本必须 ≥ 22推荐 22 / 24 / 26见 package.json 的engines。模块系统5.x 为 ESM-onlyrequire(ai-sdk/svelte)不再可用全部改为import。Svelte 版本peer 依赖要求svelte^5.31.0Svelte 4 项目需先完成框架升级。结构化对象 API若仍在使用Experimental_StructuredObject迁移到StructuredObject仅换名行为不变废弃别名仍保留。Completion body 类型升级到 5.0.62 后可利用CompletionOptionsBODY泛型获得请求体类型提示注意complete()的 options 会与构造选项中的headers/body做浅合并。依赖关系上本包与ai、ai-sdk/provider-utils保持严格同步发布workspace 依赖任何 UI 层的流式协议、错误处理、Schema 校验修复都跟随核心包版本落地——这也是为什么 CHANGELOG 中绝大多数条目是Updated dependencies。需要深入验证某一行为时可直接阅读 packages/svelte/src 下的源码与*.test.ts测试它们与 CHANGELOG 共同构成了本包最完整的行为文档。【免费下载链接】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），仅供参考