setup

assistant-ui 配置

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

assistant-ui CLI 可搭建项目、添加组件并保持安装内容更新。本技能涵盖 CLI 的完整用法，以及接下来应接入哪种运行时适配器；安装带样式的 UI 本身请参阅 elements。

参考资料

• ./references/ai-sdk.md -- @assistant-ui/ai-sdk（v7）：传输、前端工具、多步骤、审批、引用上下文、令牌用量、历史记录、useAISDKRuntime
• ./references/ai-sdk-legacy.md -- 固定版本的 @assistant-ui/react-ai-sdk（v6、v5）和 @assistant-ui/react-data-stream（v4）配置
• ./references/langgraph.md -- @assistant-ui/react-langgraph：流式传输、中断、消息编辑、会话线程、Agent 状态
• ./references/langchain.md -- 基于 useStream 的 LangGraph 适配器，以及它与 react-langgraph 的对比
• ./references/google-adk.md -- @assistant-ui/react-google-adk：流式传输、工具确认、身份验证流程、输入请求、制品
• ./references/a2a.md -- @assistant-ui/react-a2a：A2AClient、任务状态、制品、多租户
• ./references/ag-ui.md -- @assistant-ui/react-ag-ui：Agent 状态、中断、子 Agent 嵌套、自定义事件
• ./references/eve.md -- @assistant-ui/eve：会话、连接器授权、withEve + withAui
• ./references/opencode.md -- @assistant-ui/react-opencode：权限、问题、子 Agent 任务、会话扩展项
• ./references/claude-managed-agents.md -- 通过 useExternalStoreRuntime 接入 Anthropic Managed Agents 会话
• ./references/custom-backend.md -- 为没有专用适配器的后端使用 useLocalRuntime 和 useExternalStoreRuntime
• ./references/tanstack.md -- Vite + TanStack Router/Start 配置
• ./references/mastra.md -- 基于 AI SDK 运行时的 Mastra 全栈和独立服务端模式
• ./references/cloudflare-agents.md -- 通过 @cloudflare/ai-chat 和 useAISDKRuntime 使用 Durable Object Agent
• ./references/providers.md -- 大模型网关、本地开发的 ChatGPT/Codex 订阅，以及 Electron
• ./references/devtools.md -- @assistant-ui/react-devtools、DevToolsModal、自定义插件

CLI 决策流程

• 新建应用 / 空目录：npx assistant-ui@latest create <name>
• 已有包含 package.json 的项目：npx assistant-ui@latest init
• 为已有运行时的项目添加一个或多个带样式的组件：npx assistant-ui@latest add <items...>（参阅 elements）
• 升级 @assistant-ui/* 版本：npx assistant-ui@latest update
• 跨越一个存在破坏性变更的版本进行迁移：npx assistant-ui@latest upgrade（完整迁移指南请参阅 update）
• 将编辑器连接到文档：npx assistant-ui@latest mcp
• 收集环境信息以提交错误报告：npx assistant-ui@latest info
• 诊断版本偏差或损坏的安装：npx assistant-ui@latest doctor
• 打开已预加载这些技能的 Claude Code：npx assistant-ui@latest agent "add a chat sidebar"

create

npx assistant-ui@latest create my-app
npx assistant-ui@latest create my-app -t cloud-clerk
npx assistant-ui@latest create my-app -e with-langgraph
npx assistant-ui@latest create my-app --native   # Expo, equivalent to -e with-expo
npx assistant-ui@latest create my-app --ink      # React Ink, equivalent to -e with-react-ink

模板（-t, --template）：

模板	内容
default	Vercel AI SDK、useChatRuntime
minimal	采用本地组件的精简起步模板
cloud	由 AssistantCloud 提供支持的持久化
cloud-clerk	使用 Clerk 身份验证的 AssistantCloud 持久化
langchain	基于 @assistant-ui/react-langchain 适配器的 LangGraph 起步模板
mcp	MCP 工具及 MCP Apps 渲染器
eve	基于 eve/next 的 Eve Agent

没有 langgraph 模板；基于 LangGraph 的起步模板是 langchain（react-langchain），而 -e with-langgraph 会搭建原始的 @assistant-ui/react-langgraph 适配器。

示例（-e, --example），每个都是完整的功能演示：

示例	展示内容
with-ai-sdk-v7	Vercel AI SDK v7
with-eve	Eve Agent 集成
with-artifacts	带实时预览的 HTML 制品渲染
with-langgraph	使用自定义工具的 LangGraph Agent
with-google-adk	Google ADK Agent
with-ag-ui	AG-UI 协议
with-cloud	AssistantCloud 持久化
with-assistant-transport	通过 Assistant Transport 使用自定义后端
with-resumable-stream	可恢复流，在响应过程中重新加载后仍可继续
with-chain-of-thought	推理、工具调用、来源引用
with-external-store	外部消息存储
with-interactables	由 AI 驱动的交互式 UI 组件
with-openui	OpenUI 生成式 UI
with-custom-thread-list	自定义线程列表 UI
with-react-hook-form	React Hook Form 集成
with-ffmpeg	FFmpeg 视频处理工具
with-elevenlabs-conversational	实时语音、ElevenLabs
with-livekit	实时语音、LiveKit
with-elevenlabs-scribe	语音转录、ElevenLabs
with-expo	Expo / React Native（也可使用 --native）
with-react-ink	终端 UI 聊天（也可使用 --ink）
with-react-router	React Router v7
with-tanstack	TanStack Start

其他标志：-p, --preset <name-or-url> 会在搭建完成后通过 shadcn add 应用 playground 预设（例如 chatgpt），可与 --template 组合使用，但不能与 --example、--native 或 --ink 组合；--use-npm / --use-pnpm / --use-yarn / --use-bun 用于指定包管理器；--skip-install 跳过安装依赖包；--skills / --no-skills 用于添加或跳过本仓库的 Agent 技能（在 TTY 中省略时会提示选择）。在非交互式 Shell 中，如果省略 -t/-e，默认使用 default 模板；如果省略项目目录，默认使用 my-aui-app。

init

npx assistant-ui@latest init

对于带有 package.json 的现有项目：检测项目，运行 shadcn add 添加快速入门组件，添加默认组件，并配置 TypeScript 路径。标志：-y, --yes 跳过确认提示（在 CI 或 Agent Shell 中使用），-o, --overwrite 替换现有文件，-c, --cwd <dir> 指定项目，--use-npm / --use-pnpm / --use-yarn / --use-bun 用于指定包管理器，--skip-install 跳过安装依赖包。如果在没有 package.json 的目录中运行，则会转而执行 create。

add

npx assistant-ui@latest add thread thread-list

接入运行时后，add 会从 assistant-ui 注册表（r.assistant-ui.com）获取样式组件，安装其 npm 依赖和 TypeScript 类型，并解析注册表依赖（thread 还会拉取 markdown-text、tool-fallback、reasoning 等）。-y, --yes 跳过确认提示（默认为 true），-o, --overwrite 替换现有文件，-p, --path 重新指定安装目录。完整目录、运行时连接（.aui）与独立组件的区别，以及支持 Radix/Base UI 样式感知的注册表 URL，请参阅 elements。

保持安装版本为最新

命令	用途
assistant-ui update [--dry]	将所有已安装的 @assistant-ui/* 软件包升级到最新版本；--dry 会打印命令而不执行
assistant-ui upgrade [-d] [-p] [--verbose]	按顺序运行当前主版本附带的所有 codemod；-d 执行试运行，-p 打印转换后的文件
assistant-ui codemod <name> <source> [-d] [-p]	运行一个指定名称的 codemod，而不是完整的升级序列
assistant-ui mcp [--cursor|--windsurf|--vscode|--zed|--claude-code|--claude-desktop]	为指定的 IDE 注册托管 MCP 文档端点（https://www.assistant-ui.com/mcp），或为 Zed 和 Claude Desktop 注册本地 @assistant-ui/mcp-docs-server stdio 服务；这两个 IDE 只能启动本地服务
assistant-ui info	打印 CLI、操作系统、软件包管理器、框架、已安装的 @assistant-ui/*/生态系统版本信息，生成可直接粘贴到错误报告中的内容块
assistant-ui doctor [--no-network]	诊断现有安装（@assistant-ui/* 软件包版本不一致、配置错误）；--no-network 会跳过 npm 注册表中最新版本的检查
assistant-ui agent "<prompt>" [--dry]	启动预载了 assistant-ui 技能的 Claude Code，并附上给定提示词；--dry 会打印命令而不执行

切勿对当前（0.15.x）安装运行 codemod v0-8/ui-package-split；其 @assistant-ui/react-ui 目标早于当前运行时，而且 upgrade 已将其排除。完整的版本表、迁移顺序以及 0.15.x 后续迁移事项（注册表路径、AuiConfig、threads.selectionChanged），请参阅 更新。

选择运行时

按框架选择（已有适用框架时）：

后端	Hook	Package	参考
Vercel AI SDK v7	useChatRuntime	@assistant-ui/ai-sdk	ai-sdk.md
LangGraph Cloud（原始 SDK）	useLangGraphRuntime	@assistant-ui/react-langgraph	langgraph.md
LangGraph Cloud（useStream）	useStreamRuntime	@assistant-ui/react-langchain	langchain.md
Google ADK（JS 或 Python）	useAdkRuntime	@assistant-ui/react-google-adk	google-adk.md
A2A v1.0 Agent 服务	useA2ARuntime	@assistant-ui/react-a2a	a2a.md
AG-UI Agent 服务	useAgUiRuntime	@assistant-ui/react-ag-ui	ag-ui.md
Eve（eve/next）	useEveAgentRuntime	@assistant-ui/eve	eve.md
OpenCode 服务（实验性）	useOpenCodeRuntime	@assistant-ui/react-opencode	opencode.md
Claude Managed Agents 会话	useExternalStoreRuntime + useRemoteThreadListRuntime	@assistant-ui/react（无专用适配器）	claude-managed-agents.md

按需求选择（完整决策树见 custom-backend.md），当没有适用的框架适配器时：

你的需求	Hook	参考
向你的 API 发起 fetch 调用；运行时负责管理状态	useLocalRuntime	custom-backend.md
消息已存储在 redux、zustand、tanstack-query 中	useExternalStoreRuntime	custom-backend.md
后端已输出数据流协议	useDataStreamRuntime	../streaming/SKILL.md
后端流式传输完整的 Agent 状态快照，或需要双向命令	useAssistantTransportRuntime	../streaming/SKILL.md

框架和提供商接入指南均基于上述 AI SDK 运行时，而非专用适配器：mastra.md（全栈或独立服务）、cloudflare-agents.md（Durable Object Agent）和 providers.md（用于路由和 BYOK 的大模型网关、无需 API 密钥即可在本地开发时使用的 ChatGPT/Codex 订阅，以及 Electron 的托管后端与本地主进程拆分方案）。

平台目标

目标	Package	脚手架	技能
Web（React）	@assistant-ui/react	create	此技能、elements
Expo / React Native	@assistant-ui/react-native + @assistant-ui/metro	create <name> --native（或 -e with-expo）	react-native
终端	@assistant-ui/react-ink + @assistant-ui/react-ink-markdown	create <name> --ink（或 -e with-react-ink）	ink

基于 Vite 的 Web 应用（TanStack Start、纯 Vite、Nuxt）不是 create 模板；手动设置方法以及来自 @assistant-ui/vite 的 aui() 编译器插件，请参阅 tanstack.md。

常见问题

npx assistant-ui create 会直接选择默认模板，不会提示

• 标准输入不是 TTY（CI、Agent Shell）。请显式传入 -t/-e，不要依赖交互式选择器。

“只能指定一个脚手架选择器”

• --template、--example、--native 和 --ink 互斥。--preset 可以与 --template 配合使用，但不能与其他三个选项配合使用。

init 在 CI 或 Agent Shell 中卡住

• 传入 -y, --yes 跳过确认提示；如果需要替换上次运行留下的文件，请添加 -o, --overwrite。

依赖 @assistant-ui/styles 或 @assistant-ui/react-ui 无法解析或安装

• 这两个软件包已停用（@assistant-ui/styles 在 npm 上标记为已弃用）。现在，样式来自 CLI 复制到项目中的元素；请移除该依赖并运行 npx assistant-ui@latest add thread。

Cannot find module '@/components/assistant-ui/thread'

• 组件已移至 elements/ 下，运行时连接的文件带有 .aui 后缀：@/components/assistant-ui/elements/thread.aui。请参阅 elements。

add 重新安装了已自定义的组件

• 请有意传入 -o, --overwrite，或先将修改移到其他位置；普通的 add 会跳过已存在的文件。

注册表安装在 create 过程中途失败

• create 仍会完成项目创建；注册表或网络问题解决后，请在项目目录中重新运行打印出的重试命令。

相关技能

• elements -- 通过 add 安装并自定义带样式的 Thread、ThreadList 和 120+ 个目录组件
• primitives -- 使用 elements 之外的组件自行组合 UI 时所需的无样式构建模块
• runtime -- 深入了解所选运行时的钩子、适配器、事件和功能
• update -- upgrade 背后的版本检测、完整迁移映射和 codemod 列表
• react-native -- 使用 --native 创建脚手架后所需的 Expo / React Native 相关说明
• ink -- 使用 --ink 创建脚手架后所需的 React Ink 终端相关说明
• cloud -- cloud 和 cloud-clerk 模板背后的 AssistantCloud 持久化功能
• tools -- 配置好运行时后定义工具