用途:把已有的 assistant-ui 应用升级到当前 AI SDK v7 与 assistant-ui 0.15.x,并应用所需迁移。官方提示始终查阅 assistant-ui.com/llms.txt 获取最新 API。
主要能力:分两阶段升级。先让 AI SDK 及其 assistant-ui 适配器兼容,再更新 assistant-ui 并应用 API 迁移。资料提供三份参考:ai-sdk.md(AI SDK v4/v5 到 v6、v6 到 v7 及适配器版本钉选)、assistant-ui.md(0.8 到 0.15、toolkits、LangGraph、弃用策略)、breaking-changes.md(版本与症状速查)。
使用方式:在应用根目录用 npm ls 和 npm view 检测已安装与最新版本,再按 @assistant-ui/react 安装版本对照阈值表,按升序应用每项适用指南。迁移顺序为:先迁移 AI SDK(目标 ai@^7、@ai-sdk/react@^4 搭配 @assistant-ui/ai-sdk),再更新 assistant-ui,最后验证。CLI 命令保持原样:
npx assistant-ui@latest update npx assistant-ui@latest update --dry npx assistant-ui@latest upgrade -d -p npx assistant-ui@latest codemod v0-11/content-part-to-message-part ./src npx assistant-ui@latest doctor npx assistant-ui@latest info
内置 upgrade 按固定顺序运行 codemod:v0-9/edge-package-split、v0-11/content-part-to-message-part、v0-12/assistant-api-to-aui、v0-12/event-names-to-camelcase、v0-12/primitive-if-to-aui-if、v0-15/aui-accessor-calls-to-properties。建议先用 -d 和 -p 预览,确认 diff 后再正式运行;不要在当前升级中加入历史 v0-8/ui-package-split。
0.15.x 后续事项:AI SDK 导入从 @assistant-ui/react-ai-sdk 改为 @assistant-ui/ai-sdk;useAui 不再接收配置,改用 AuiConfig 并传给 provider,嵌套 AuiProvider 需声明 extends={aui} 或 extends={null};运行时边界用 config 替换 aui;复制来的 registry 组件移至 components/assistant-ui/elements/ 下,区分 .aui.tsx 与 .tsx;线程选择事件合并为 threads.selectionChanged;旧交互与工具注册迁移到 unstable_useInteractable、unstable_Interactables()、unstable_interactableTool,工具改用 defineToolkit 并注册到 AuiConfig。
验证:运行 npx tsc --noEmit、npm run build、npm test,并实际打开聊天路由验证普通消息、工具调用、审批门、线程切换与持久化历史;依赖或环境不匹配时运行 doctor 与 info。
限制:包更新只覆盖 @assistant-ui 包,ai 与 @ai-sdk/react 需单独更新;@assistant-ui/react-ai-sdk 是旧安装别名;aui.thread 恒为真,需检查 aui.thread.source != null;作用域访问器为属性,应调用作用域方法。关联技能包括 setup、runtime、tools、elements。