update

assistant-ui 更新

请始终查阅 assistant-ui.com/llms.txt 以获取最新 API。

分两步升级。首先确保 AI SDK 及其 assistant-ui 适配器兼容，然后更新 assistant-ui 并应用其 API 迁移。编辑前请阅读相关参考资料，因为直接跳转可能会跨越多个弃用窗口。

参考资料

• ./references/ai-sdk.md -- AI SDK v4 和 v5 到 v6 的迁移、v6 到 v7 的变更，以及适配器版本锁定
• ./references/assistant-ui.md -- assistant-ui 0.8 到 0.15、工具包、LangGraph 和弃用政策
• ./references/breaking-changes.md -- 按版本和症状快速查找

检测已安装的版本系列

在应用根目录运行这些命令。npm ls 会报告已安装的依赖关系图，npm view 会报告已发布的最新版本。

npm ls @assistant-ui/react @assistant-ui/ai-sdk @assistant-ui/react-ai-sdk @assistant-ui/core @assistant-ui/store assistant-stream ai @ai-sdk/react

npm view @assistant-ui/react version
npm view @assistant-ui/ai-sdk version
npm view @assistant-ui/react-ai-sdk version
npm view @assistant-ui/core version
npm view @assistant-ui/store version
npm view assistant-stream version
npm view ai version
npm view @ai-sdk/react version

截至 2026 年 9 月当前已发布的版本系列：

包	当前版本系列
assistant-ui	0.0.x
@assistant-ui/react	0.15.x
@assistant-ui/ai-sdk	0.0.x
@assistant-ui/react-ai-sdk	1.4.x
@assistant-ui/core	0.3.x
@assistant-ui/store	0.3.x
assistant-stream	0.3.x
assistant-cloud	0.1.x
ai	7.x

@assistant-ui/react-ai-sdk 会为较早版本的安装重新导出相同的 API。新代码应从 @assistant-ui/ai-sdk 导入。

选择迁移集

将已安装的 @assistant-ui/react 版本与以下每个阈值进行比较。按版本升序应用所有适用的指南。

之前安装的版本	检查内容
0.8.x	历史 UI 包拆分。当前升级包有意不包含 v0-8/ui-package-split，因为其目标版本与当前运行时不兼容。请手动迁移到 Elements 注册表。
0.9.x	v0-9/edge-package-split codemod。
0.10.x	打包的迁移没有专用的 0.10 codemod。运行后续 codemod，并根据项目当前的工具链解决剩余的包或构建错误。
0.11.x	ContentPart 名称和 MessagePrimitive.Content 将变为 MessagePart 和 MessagePrimitive.Parts。
0.12.x	统一状态 API、hook 别名和 camelCase 事件名称。
0.13.x	继续之前请查看 0.14 指南，因为它会移除 v0.11 和 v0.12 中弃用的内容。
0.14.x	已移除的别名和运行时 API，以及 primitive 子元素渲染函数。
0.15.x	作用域属性、已移除的旧版 hooks、toolUIs、standalone-tool-call、AuiConfig 和 threads.selectionChanged。

迁移顺序

1. 首先迁移 AI SDK。如果项目使用 v4、v5 或 v6，请阅读 ai-sdk.md。目标版本为 ai@^7 和 @ai-sdk/react@^4，并使用 @assistant-ui/ai-sdk。
2. 接下来更新 assistant-ui。使用阈值表和 assistant-ui.md，从最早的适用版本开始。
3. 只有在包和源代码迁移都完成后才进行验证。运行类型检查和构建，并测试应用使用的聊天、工具、审批和线程选择流程。

运行 CLI

# Update every installed @assistant-ui/* package.
npx assistant-ui@latest update

# Preview package changes without installing them.
npx assistant-ui@latest update --dry

# Preview the complete bundled migration and print each transformed file.
npx assistant-ui@latest upgrade -d -p

# Apply one codemod to a source directory.
npx assistant-ui@latest codemod v0-11/content-part-to-message-part ./src

# Report environment and dependency details.
npx assistant-ui@latest doctor
npx assistant-ui@latest info

打包的升级命令会严格按以下顺序运行这些 codemod：

1. v0-9/edge-package-split
2. v0-11/content-part-to-message-part
3. v0-12/assistant-api-to-aui
4. v0-12/event-names-to-camelcase
5. v0-12/primitive-if-to-aui-if
6. v0-15/aui-accessor-calls-to-properties

请先使用 dry 和 print 形式。检查差异后，再运行不带 -d 和 -p 的 upgrade。不要将历史版 v0-8/ui-package-split codemod 添加到当前升级中。

0.15.x 后续变更

这些变更在 0.15.0 发布后推出，且没有伴随新的主版本。即使项目已经声明使用 0.15.x，也请检查并处理这些变更。

更改 AI SDK 导入

// Before
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

// After
import { useChatRuntime } from "@assistant-ui/ai-sdk";

将客户端构建改为配置

useAui 不接受配置。使用 AuiConfig 构建配置，并将其传递给 provider。嵌套的 AuiProvider 必须声明是扩展父客户端还是与其隔离。

// Before
const aui = useAui({ tools: Tools({ toolkit }) });
return <AuiProvider value={aui}>{children}</AuiProvider>;

// After
const aui = useAui();
const config = AuiConfig({ tools: Tools({ toolkit }) });
return <AuiProvider extends={aui} config={config}>{children}</AuiProvider>;

在运行时边界处，将 AssistantRuntimeProvider aui 替换为 config。对于隔离的根，使用 AuiProvider extends={null} config={config}。

// Before
return <AssistantRuntimeProvider runtime={runtime} aui={aui}>{children}</AssistantRuntimeProvider>;

// After
const config = AuiConfig({ tools: Tools({ toolkit }) });
return <AssistantRuntimeProvider runtime={runtime} config={config}>{children}</AssistantRuntimeProvider>;

移动复制的注册表组件

连接运行时的注册表组件位于 components/assistant-ui/elements/.aui.tsx，并通过 @/components/assistant-ui/elements/.aui 导入。渲染器和独立 Elements 使用 components/assistant-ui/elements/.tsx，导入时省略 .aui。在同一轮修改中替换已弃用的 @/components/assistant-ui/ 导入。

整合线程选择事件

// Before
useAuiEvent("threadListItem.switchedTo", ({ threadId }) => select(threadId));
useAuiEvent("threadListItem.switchedAway", ({ threadId }) => clear(threadId));

// After
useAuiEvent("threads.selectionChanged", ({ threadId, previousThreadId }) => {
  select(threadId);
  if (previousThreadId) clear(previousThreadId);
});

新事件由 threads 作用域共享。之前位于线程列表项中的监听器可以根据该项的 id 进行筛选。

替换旧版交互组件和工具注册

useAssistantInteractable、Interactables() 和 useInteractableState 自 2026-06-14 起已弃用，并计划于 2026-09-14 或之后移除。迁移到 unstable_useInteractable、unstable_Interactables() 和 unstable_interactableTool。

makeAssistantTool、useAssistantTool、makeAssistantToolUI 和 useAssistantToolUI 已弃用。将模型契约、执行器和渲染器放入 defineToolkit 条目中，并使用 AuiConfig({ tools: Tools({ toolkit }) }) 注册。转换有状态工具或仅用于 UI 的工具之前，请阅读 assistant-ui.md 中的 toolkits 章节。

验证

npx tsc --noEmit
npm run build
npm test

还要打开一个真实的聊天路由，验证普通消息、工具调用、审批关卡（如果存在）、线程切换，以及项目的持久化历史记录路径。如果仍存在依赖或环境不匹配，请运行 npx assistant-ui@latest doctor 和 npx assistant-ui@latest info。

常见问题

升级命令更改了导入，但应用仍在使用旧适配器

• 软件包更新只涵盖 @assistant-ui 软件包。请单独更新 ai 和 @ai-sdk/react，然后参照 AI SDK 参考文档。
• @assistant-ui/react-ai-sdk 是旧版安装的别名。当前源码从 @assistant-ui/ai-sdk 导入。

AuiProvider 或 AssistantRuntimeProvider 不再接受旧属性

• useAui() 仅用于访问上下文。请构建 AuiConfig({...}) 并将其作为 config 传入。
• 嵌套的 AuiProvider 需要 extends={aui}；独立的则需要 extends={null}。

作用域查找不再像空值检查那样工作

• aui.thread 始终为真值。访问可选作用域前，请检查 aui.thread.source != null。
• 作用域访问器是属性。请调用作用域方法，而不是调用作用域本身。

类型检查仍发现已移除的钩子或工具映射

• 应用 assistant-ui.md 中完整的已移除钩子映射。
• 将 s.tools.tools 替换为 s.tools.toolUIs，并将 mcp-app 分组键替换为 standalone-tool-call。

相关技能

• setup -- 将 assistant-ui 安装到此前未使用过它的项目中
• runtime -- 迁移后构建或自定义活动运行时
• tools -- 编写工具包、前端工具、审批流程和工具 UI
• elements -- 安装和自定义复制的 Elements 注册表组件