UI SDK 是什么:让 Agent 写组件,也让它直接操作页面

Vercel Labs 11 月 12 日发布了 UI SDK(vercel-labs/ui,Apache-2.0)。它是一套 TypeScript 写的界面行为库,官方说它是给 Agent 用的,分两种用法:Agent 用它的行为块拼出你要的组件,另一个 Agent 再通过 createAgent 直接读写这些组件的状态,用不着截图、也用不着模拟鼠标去点。前端开发者、在做 AI 助手面板的团队可以看看。
它是什么
组件库一般直接给你成品按钮和下拉框。UI SDK 往下拆了一层,只提供「行为」:createRovingFocus 管方向键移动焦点,createTypeahead 管打字跳到选项,createPopup 管弹层贴着按钮打开、按 Esc 或点外面关闭、焦点回到原处。组件本身不带样式,@ui-sdk/core/web.css 是可选的默认外观。
| 仓库 | github.com/vercel-labs/ui |
|---|---|
| 作者 | Vercel Labs |
| 许可证 | Apache-2.0 |
| 热度 | GitHub 4,054 星(GitHub API,2026-11-14 16:04 北京时间);npm @ui-sdk/core 上周下载 3,176 次(11-06 至 11-12) |
| 版本 | Beta,各框架包最新为 0.1.0-beta.2(2026-11-13 21:02 北京时间) |
| 框架 | React、Vue、Svelte、Solid、Web Components;没有构建步骤的页面可直接引 web.js + web.css |
让 Agent 造组件:装 Skill,再说清交互
安装分两步,先装包,再给编程 Agent 装 Skill:
npm install @ui-sdk/react @ui-sdk/core
npx skills add vercel-labs/ui --skill ui-sdk
换框架就把 @ui-sdk/react 换成 @ui-sdk/vue、@ui-sdk/svelte、@ui-sdk/solid 或 @ui-sdk/web。npx skills 这个命令行工具本身怎么用,站内有一篇 npx skills 拆解。Agent 不支持 Skill 的话,同一份 SKILL.md 也随包装在 node_modules/@ui-sdk/core/skills/ui-sdk/ 下,版本和你装的一致,让它直接读那份就行。
每个框架包里还带着对应版本的 Markdown 文档。官方建议的开场提示词是:
This project uses React and ui-sdk. Read
node_modules/@ui-sdk/react/docs/llms.txt to see what's available.
For a custom component, read the relevant sections of docs/core.md
and docs/rendering.md in the same package.
Skill 里有两条值得记住的规矩:docs/core.md 超过 300 KB,只按标题搜,不整篇读;也别去翻 dist/*.js,以文档和 .d.ts 类型为准。造组件时把交互写具体,比如官方的评分组件例子:
Use ui-sdk to build a five-star rating in React.
Arrow keys should move between stars and choose a rating.
Use our existing styles and test the keyboard behavior.
文档还建议先要一个最小可用版本,比如固定几个表情、一个示例页,看过再提「搜不到时显示 No emoji found、焦点留在输入框」这类具体修改,最后让 Agent 跑类型检查和测试,并报告哪些没能检查。
让 Agent 用组件:snapshot、query、act
在页面渲染前创建一个桥:
import { createAgent } from "@ui-sdk/react/agent"
const agent = createAgent()
Object.assign(window, { agent })
export { agent }
之后浏览器控制台里就能做三件事。window.agent.snapshot() 返回组件列表,每项带 ref、组件类型、标签、当前值和能调用的动作;await window.agent.query({ within: "Region" }) 列出下拉框的全部选项;改值用:
await window.agent.act({
steps: [{ ref: "Region", action: "setValue", args: ["north-america"] }],
})
ref 可以写标签名,按整词匹配,不分大小写和重音;标签有歧义时返回错误并列出候选。多个 step 按顺序执行,某一步失败时 ok 为 false,前面已执行的步骤不回滚。所以每个控件都要有名字,SelectLabel、FieldLabel 或 aria-label 都行,读屏软件和 Agent 都靠它找控件。
想让浏览器里自带的 Agent 也能用,再加一行 registerTools(agent, { allow }),它会通过 document.modelContext 把 snapshot、query、act 注册成 WebMCP 工具。官方指南用的是 ChatGPT 桌面版内置浏览器的「Site tools」。浏览器没有 document.modelContext.registerTool 时这个调用什么也不做,控制台那套照常能用。
官方给了一组对比:同一个项目设置页面(改项目名、成员、通知设置再保存),一边用浏览器工具操作另一个组件库做的页面,一边用 UI SDK 的桥,都是 Claude Code 里的 Sonnet,同样的任务和系统提示词,各跑 3 次取中位数,全部完成任务:
| 指标 | 浏览器工具 | UI SDK + agent 桥 | 变化 |
|---|---|---|---|
| 工具调用 | 16 次 | 5 次 | −69% |
| 读入文本 | 39.8k 字符 | 6.8k 字符 | −83% |
| 耗时 | 41 秒 | 16 秒 | −61% |
| 花费 | $0.073 | $0.032 | −56% |
这是厂商自己的基准,样本只有一个页面。结论方向和站内那篇 Agent 浏览器工具成本对比 一致:Agent 读结构化状态,比读整页无障碍树或截图省得多。
权限:哪些动作要人点头
不写 allow 时,桥接受所有支持的动作。上线前至少收窄一下:
const agent = createAgent({
allow: ({ component, label, action }) =>
component === "select" && label === "Region" && action === "setValue",
})
allow 可以返回 Promise<boolean>,接你自己的确认弹窗,5 分钟没人回答这一步就失败。另外三个 HTML 标记:
data-agent-confirm="Charges $20 to your card for 1,000 credits":不管allow怎么写,这个控件都等人确认;没配allow时直接报「Needs a person」。data-agent-hidden:里面的组件不进 snapshot 和 query,Agent 看不到。data-agent-secret:组件可见、能输入,值显示成[redacted]。
Agent 改值走的是组件自己的 API,你写在键盘和鼠标事件里的校验拦不住它。
校验要放进 onValueChange 这类变更回调,回调里 details.source === "agent" 能区分来源,details.cancel() 能拒绝。被回调取消的那一步,act 仍可能返回 ok: true,要看每步的 changes 和返回的 values 才知道到底改没改。第二个坑:allow 只管动作,不管可见性,组件和动作照样出现在 snapshot 里,不想给看的区域要另加 data-agent-hidden。第三个:WebMCP 工具结果里有页面文字,三个工具都标了 untrustedContentHint,和 agent-browser 的处理一样,页面内容只能当数据看。
适合谁,不适合谁
适合:正在自建设计系统、想让 Agent 稳定产出可访问组件的团队;产品里要嵌 AI 助手、希望它直接改表单和设置的应用。不适合:要稳定 API 的生产项目,它还在 0.1 beta;已经深度用 Radix、shadcn/ui 且没有 Agent 操作需求的项目,迁移收益不大。官方致谢里列了 Radix、Base UI、React Aria、shadcn/ui 等项目。
最后
照官方 Guide 用 Vite 起一个只有 Region 下拉框的页面,在控制台跑一遍 snapshot、query、act,再给它加上 allow 和一个带 data-agent-confirm 的按钮,看拒绝时返回什么。