Vercel UI SDK 怎么装：50 个交互行为与 Agent Bridge 实测

一句话结论：Vercel Labs 在 11 月 12 日开源的 UI SDK 把前端交互拆成 50 多个可复用的行为模块，本地实测装上 @ui-sdk/core 与 @ui-sdk/react 只要两条 npm 命令，React、Vue、Svelte、Solid 和 Web Components 五套适配器共用同一份交互内核，官方跑分显示接入 Agent Bridge 后工具调用次数最多降到原来的四成、成本降到五成左右。

让编码智能体写前端，卡在哪儿通常不是写按钮。按钮谁都会写，难的是弹层关掉之后焦点回哪儿、方向键在网格里怎么走、Escape 触发后屏幕阅读器播报什么。Vercel 把这层脏活从组件里剥出来，做成独立的行为库，让智能体去拼行为而不是去抄组件源码。

UI SDK 是什么：50 个行为而不是 50 个组件

UI SDK 的核心包 @ui-sdk/core 里没有一个完整的 Select。官方给的说法是，如果直接把 Select 组件交给智能体，它只能拼出 Select；如果交给组成 Select 的零件，它能拼出自动补全框、命令面板，甚至没人设计过的新控件。

这批零件就是行为（behavior）。本地安装 @ui-sdk/core@beta 后用 Node 直接枚举导出，一共拿到 117 个导出符号，其中以 create 或 define 开头的行为工厂有 37 个，涵盖焦点、选择、弹层、拖拽排序、虚拟滚动、撤销栈这些交互内核。

行为之上是 primitive。用 definePrimitive 把状态、动作和插槽写在一起，同一份 primitive 可以渲染到五个框架里，部件名保持一致，迁移框架时不用重写交互逻辑。仓库里 React 适配器的 dist 目录实测有 170 个产物文件，core 侧内置 51 个无样式组件模块，从 accordion 到 waterfall 都在。

怎么装：两条 npm 命令加一份技能

官方 README 给的安装路径很短。React 项目装 core 加 react 两个包，其余框架把 @ui-sdk/react 换成 @ui-sdk/vue、@ui-sdk/svelte、@ui-sdk/solid 或 @ui-sdk/web 即可。

npm install @ui-sdk/react @ui-sdk/core
npx skills add vercel-labs/ui --skill ui-sdk

本机实测这条安装命令一次装入 5 个包，@ui-sdk/core 落盘约 7.5 MB，@ui-sdk/react 约 3.6 MB。整个 @ui-sdk/core 没有任何运行时依赖，React 适配器对宿主要求 React 19 及以上，类型包要求 @types/react 不低于 19.2.10。

版本节奏很密。npm 上 @ui-sdk/core 从 11 月 12 日的 0.1.0-beta.1 一天涨到 0.1.0-beta.2，11 月 15 日一天内连发 beta.3、beta.4、beta.5 三个版本，到 11 月 16 日 latest 标签仍停在 beta.3，beta 标签指向 beta.5。装的时候要清楚自己在用哪个通道，两条通道的文档内容可能不同。

另一个容易忽略的细节是文档也随包发布。每个包目录下都有 docs/llms.txt 作为索引，core 的 docs/core.md 超过 300 KB，包内还自带 skills/ui-sdk/SKILL.md 与 7 份参考文档。给智能体装 skill 的意义在于，它先读包内那份与当前版本一致的文档，而不是去读线上可能已经更新的版本。

给智能体的三条路径

包内 SKILL.md 把工作流分成三条路径，读法比官方 README 清晰。

第一条路径是用现成组件拼界面，比如做一个设置页或命令面板，只需要读组件文档。第二条路径是库里没有的组件就自己用行为拼，比如 stepper、splitter、transfer list、emoji picker。第三条路径是给已有界面补测试，检查键盘行为、焦点、ARIA 和服务端渲染。文档明确要求智能体不要去读 dist 里的编译产物，文档和 .d.ts 才是 API。

组件本身不带样式，视觉层交给使用者。@ui-sdk/core/web.css 提供一套可选的默认外观，没有构建步骤的页面可以直接用两个标签引入 ui-sdk.dev/web.js 和 web.css。

Agent Bridge：让智能体直接操作界面

这是 UI SDK 与普通无样式组件库拉开差距的部分。普通做法是让智能体截图，再在图片里找像素坐标；另一种是把整棵 DOM 树和可访问性树塞进上下文硬读。UI SDK 提供了第三种路径，在页面渲染前建一个 bridge。

import { createAgent } from "@ui-sdk/react/agent"
const agent = createAgent()

页面渲染完成后调用 agent.snapshot()，它返回的是一份结构化清单，包含组件编号、类型、标签、当前值和可调用动作。例如项目名输入框会返回组件编号 c1、类型 input、标签 Project name、当前值 Apollo、可用动作 setValue 与 clear。智能体要改名，调用 agent.act 指定引用与动作即可，不需要算坐标。

本地实测 @ui-sdk/react/agent 这个入口导出三个符号：createAgent、registerTools 和 agentTools。前面两个分别用于建桥和把工具注册给浏览器，第三个用于把桥暴露给外部智能体。文档还提到 agent.query 可以在指定区域内按文本查找选项，几百个选项的下拉框不必先展开再滚动去找。

权限控制走 allow 回调。开发者可以只允许智能体改某个表单，或者在它点关键按钮前弹确认框。组件自身的变更回调能拿到 source === "agent" 标记，可以识别并拦截来自智能体的改动，并配合历史记录与撤销。registerTools(agent) 则把 snapshot、act、query 三个工具注册给浏览器的 WebMCP 协议，浏览器自带的智能体就能读懂并操作这些控件。

官方跑分：工具调用与成本差多少

官方在 benchmarks/agent 目录放了一套可复现的对比测试。任务是同一个项目设置页，重命名项目、改可见性、更新两名成员和通知设置，然后保存。两种实现都用 Claude Code 里的 Sonnet 模型、相同提示词，各跑三次取中位数。

换算成官方给出的相对变化，React 那一行工具调用少 59%、Tokens 少 76%、耗时少 41%、成本少 68%；Vue 是 44%、60%、39%、55%；Svelte 是 53%、64%、45%、54%。三个框架的结论一致，成本差距都在一半以上。

这组数据有两个限制要留意。官方自己说明对照组里的 ui-sdk 页面也用浏览器工具跑过，耗时与其他库接近，说明差异来自工具而不是页面本身。另外这套测试只有一个任务场景，没有公开标准基准，第三方独立复现还没出现。仓库里带着完整测试脚本，想自己验一遍的话克隆仓库后 pnpm install，装上 Playwright 的 Chromium，再跑 pnpm --filter agent-benchmark bench，加 --framework vue 或 --framework svelte 换框架，加 --runs 3 取中位数。

UI SDK 与 Vercel AI SDK 有什么区别

两个名字相近但解决的是不同问题。AI SDK 是调用大模型和做流式输出的 TypeScript 工具包，属于数据层；UI SDK 是构建界面交互的行为库，属于视图层。它们可以同时装在一个应用里，各自承担自己的职责，不存在二选一。

如果你的项目已经在用 AI SDK，接 UI SDK 的成本主要是引入 React 19 这一项约束，以及把现有组件层的交互逻辑改写成 primitive 定义。存量项目想直接吃到 Agent Bridge 的红利，前提是界面本身由 UI SDK 搭出来，老组件拿不到结构化接口。

常见问题

UI SDK 现在能用于生产环境吗

官方定位是公开测试版，仓库 README 里明确写了框架、API、文档和行为在正式发布前都可能变化。npm 上的版本号也一直停在 0.1.0-beta 通道，11 月 15 日一天内连发三个 beta 就是明证。稳妥做法是先在内部工具或新页面里试，不要直接替换已经跑在生产上的组件库。

它和 shadcn/ui 是什么关系

shadcn/ui 的思路是把组件源码复制进项目自己维护，UI SDK 的思路是把交互行为做成可复用内核再配无样式组件。两者可以共存，用 shadcn/ui 做视觉层、用 UI SDK 补齐智能体需要的可操作接口是常见组合。仓库里也还没有 shadcn 端口，社区已经在提需求。

不接智能体，用它写普通界面值不值

值不值取决于你的组件需求是否落在官方那 51 个模块里，以及团队是否愿意维护 primitive 这一层抽象。普通界面开发直接用现成组件库成本更低。UI SDK 的价值在智能体要生成界面、要操作界面这两个场景才明显，单纯写给人用的表单并不划算。

小结

UI SDK 提供的是一条此前不常见的路线，把交互内核做成框架无关的行为库，让智能体在行为层拼装界面，再用 Agent Bridge 把这些界面反过来交给智能体操作。官方跑分显示接入 bridge 后工具调用和 token 成本能砍掉一半以上，但数据只覆盖单一任务场景，需要自己复现验证。

落地顺序建议是：先装包读 llms.txt，让智能体用现成组件搭一个真实页面，验证键盘和焦点行为符合预期，再决定要不要把 bridge 接进你的智能体链路。相关的智能体工程实践，可以参考本站关于 [LobeHub Agent 自改 harness 的成本拆解](https://fluxbbs.com/lobehub-agent-harness-frontier-70-percent-cost-2026/)、[腾讯 Agent 四层栈的数据断点](https://fluxbbs.com/tencent-agent-four-layer-stack-data-gaps-20261109/) 与 [AGENTS.md 投毒自查清单](https://fluxbbs.com/agents-md-poisoning-codex-claude-code-self-check-2026/) 的拆解。

相关阅读

• 谷歌 A2UI 1.0：4 类消息与 6 大渲染器怎么接
• LobeHub Agent 自改 harness：70% 通过率与 1.68 美元成本拆解
• Grok Build 泄露 94.7%：3.7 万应用默认公开与自查清单
• AGENTS.md 投毒怎么查：Codex 中招率超 90% 自查清单