项目2026-11-14 · 智涌AI

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

UI SDK 头图:右侧对比官方项目设置基准,浏览器工具与 UI SDK agent 桥的工具调用 16 次对 5 次、读入文本 39.8k 对 6.8k、耗时 41 秒对 16 秒、花费 0.073 美元对 0.032 美元;左下标注 4,054 GitHub 星和 50 多个界面行为

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 标记:

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 的按钮,看拒绝时返回什么。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。