# assistant-ui v0.14 迁移指南 > **摘要**：v0.14 移除了自 v0.11/v0.12 以来已废弃的 API，并将 Primitives 的 `components` prop 迁移为 children render function 模式。 --- ## 快速迁移如果你的应用已在 v0.13 且没有废弃警告，运行以下命令即可自动完成大部分迁移： ```bash npx assistant-ui@latest upgrade ``` 该 codemod 会自动处理 v0.12 的 hook 重命名（如 `useAssistantApi` → `useAui`）等操作。 --- ## 一、Hook 别名移除以下别名仅用于向前兼容，已在 v0.14 中移除，请直接使用新名称： | 已移除 | 替换为 | |--------|--------| | `useAssistantApi` | `useAui` | | `useAssistantState` | `useAuiState` | | `useAssistantEvent` | `useAuiEvent` | | `AssistantIf` | `AuiIf` | | `useLocalThreadRuntime` | `useLocalRuntime` | | `unstable_useRemoteThreadListRuntime` | `useRemoteThreadListRuntime` | | `unstable_useCloudThreadListAdapter` | `useCloudThreadListAdapter` | | `unstable_RemoteThreadListAdapter` | `RemoteThreadListAdapter` | | `unstable_InMemoryThreadListAdapter` | `InMemoryThreadListAdapter` | --- ## 二、Runtime API 清理 ### AssistantRuntime | 已移除 | 替换为 | |--------|--------| | `runtime.threadList` | `runtime.threads` | | `runtime.switchToNewThread()` | `runtime.threads.switchToNewThread()` | | `runtime.switchToThread(id)` | `runtime.threads.switchToThread(id)` | | `runtime.registerModelConfigProvider(p)` | `runtime.registerModelContextProvider(p)` | | `runtime.reset({ initialMessages })` | `runtime.thread.reset(initialMessages)` | ### ThreadRuntime | 已移除 | 替换为 | |--------|--------| | `thread.startRun(parentId)` | `thread.startRun({ parentId })` | | `thread.unstable_resumeRun(config)` | `thread.resumeRun(config)` | | `thread.unstable_loadExternalState(state)` | `thread.importExternalState(state)` | | `thread.getModelConfig()` | `thread.getModelContext()` | ### MessageState 重复的顶层 `submittedFeedback` 字段已移除，请使用： ```tsx // Before useAuiState((s) => s.message.submittedFeedback); // After useAuiState((s) => s.message.metadata.submittedFeedback); ``` ### ChatModelRunOptions 自定义 `ChatModelAdapter` 时，`options.config` 已移除，使用 `options.context`： ```tsx // Before const adapter: ChatModelAdapter = { async run({ messages, config }) { /* config.tools, config.config, ... */ }, }; // After const adapter: ChatModelAdapter = { async run({ messages, context }) { /* context.tools, context.config, ... */ }, }; ``` ### External Store Helpers `getExternalStoreMessage`（单数）已移除，使用 `getExternalStoreMessages`（复数）： ```tsx // Before const original = getExternalStoreMessage(threadMessage); // After const [original] = getExternalStoreMessages(threadMessage); ``` ### Assistant Transport Helpers `toAISDKTools` 和 `getEnabledTools` 已从 `@assistant-ui/react` 中移除，改用 `assistant-stream`： ```tsx // Before import { toAISDKTools } from "@assistant-ui/react"; const schemas = toAISDKTools(tools); // After import { toToolsJSONSchema } from "assistant-stream"; const schemas = toToolsJSONSchema(tools); ``` > **注意**：`toToolsJSONSchema` 默认会过滤掉 disabled 和 backend 工具。如需保留所有工具，传 `{ filter: () => true }`。 ### react-langgraph `useLangGraphRuntime` 的 `onSwitchToThread` 选项已移除，改用 `load`： ```tsx // Before useLangGraphRuntime({ stream, onSwitchToThread: async (threadId) => { return await fetchThread(threadId); }, }); // After useLangGraphRuntime({ stream, load: async (threadId, { signal } = {}) => { return await fetchThread(threadId, { signal }); }, }); ``` --- ## 三、核心变化：Primitives 的 Children API ⭐ 这是 v0.14 最重要的变化——将 `components` prop 替换为 children render function 模式，让你能完全控制渲染逻辑。 ### 1. ThreadPrimitive.Messages ```tsx // Before // After {({ message }) => { if (message.composer.isEditing) return ; if (message.role === "user") return ; return ; }} ``` ### 2. MessagePrimitive.Parts ```tsx // Before // After {({ part }) => { if (part.type === "text") return ; if (part.type === "reasoning") return ; if (part.type === "tool-call") return part.toolUI ?? ; return null; }} ``` ### 3. part.toolUI 和 part.dataRendererUI Tool-call 现在暴露 `toolUI` 属性，data 部分暴露 `dataRendererUI`： ```tsx // 如果有注册的 tool UI 则渲染，否则渲染 ToolFallback if (part.type === "tool-call") return part.toolUI ?? ; if (part.type === "data") return part.dataRendererUI ?? null; ``` > **注意**：返回 `null` 时，已注册的 tool UI 和 data renderer UI 仍会自动渲染。如需显式阻止渲染，返回 `<>`： ```tsx {({ part }) => { if (part.type === "text") return ; return null; // 注册的 tool/data UIs 仍然渲染 }} ``` ### 4. ThreadPrimitive.Suggestions ```tsx // Before // After {() => } ``` ### 5. ThreadListPrimitive.Items ```tsx // Before // After {() => } ``` ### 6. Attachments ```tsx // Before // After {() => } ``` --- ## 四、向后兼容 `components` prop 在所有 Primitives 上仍然受支持，但已被标记为 **deprecated**，将在未来版本中移除。 --- ## 五、仍处于 Deprecated 状态（尚未移除）以下 API 标记为 `@deprecated`，但保留了一到两个版本以便下游运行时间迁移： - `ThreadState.threadId` 和 `ThreadState.metadata` — 改用 `useThreadListItem()` - Legacy context hooks（`useThreadRuntime`、`useMessageRuntime` 等）— 已在 v0.12 被 `useAui()` / `useAuiState()` 替代 - Primitive If 组件（`ThreadIf`、`MessageIf`、`ComposerIf`、`ThreadEmpty`）— 已由 `AuiIf` 替代你会在这些地方继续看到 deprecated 警告，预计在未来的小版本中移除。 --- > **原文链接**：https://www.assistant-ui.com/docs/migrations/v0-14 > **获取帮助**：[GitHub Issues](https://github.com/assistant-ui/assistant-ui/issues)

assistant-ui v0.14 迁移指南：从 components prop 到 Children Render Function

assistant-ui v0.14 迁移指南：从 components prop 到 Children Render Function