UI SDK 是给编程 Agent 用的「行为 / behaviors」库。据 官方仓库 README 和 文档,键盘导航、焦点、选择、关闭/驱散、弹层、拖拽,以及这些交互所需的 ARIA,都写在与框架无关的 TypeScript 核心包 @ui-sdk/core 里,再由 @ui-sdk/react、@ui-sdk/vue、@ui-sdk/svelte、@ui-sdk/solid、@ui-sdk/web 渲染到对应框架。它不是模型 API,也不替你决定外观:现成组件和自己用 definePrimitive 拼出来的部件都是无样式的,也没有 provider 或门户(portal)。
@vercel 在 2026 年 11 月 12 日 18:41 UTC(北京时间 11 月 13 日 02:41)发帖宣布「Introducing the UI SDK.」。同一时段 @shadcn 介绍了设计思路,@rauchg 把它比作「像给 Agent 用的 x86 指令集」。文档站是 ui-sdk.dev,源码在 vercel-labs/ui。npm 上的 @ui-sdk/core、@ui-sdk/react 以及其它框架包当前最新是 0.1.0-beta.1,许可证 Apache-2.0。
2026 年 11 月 13 日(北京时间,UTC+8),我们在一台 Debian 13 x86_64 机器上,用 Node.js v24.22.2、npm 11.19.1 和 React 19.3.1 做了实测:先 npm install @ui-sdk/react @ui-sdk/core,装上的就是 0.1.0-beta.1;再按官方 README 把 search-field 示例写进最小 Vite + React 项目,npm run build(tsc -b && vite build)通过;然后执行 npx skills add vercel-labs/ui --skill ui-sdk,并让 Claude Code 2.1.319 和 Codex CLI 0.167.0 经本站 API、按 skill 各生成一个五星评分组件。Cursor 的 Agent 任务这次没有实跑。下面的版本、命令、耗时和输出都来自这次实际运行。
先看结论
| 问题 | 答案 |
|---|---|
| UI SDK 是什么? | 给 Agent 用的行为库:交互和 ARIA 写在 @ui-sdk/core,再用各框架适配器渲染。 |
| 当前版本 | npm 0.1.0-beta.1(2026-11-12 发布,Apache-2.0)。需要 React 19+(React 适配器的 peer 依赖)。 |
| 怎么装? | React:npm install @ui-sdk/react @ui-sdk/core。其它框架把 @ui-sdk/react 换成对应包。 |
| 怎么让 Agent 用? | npx skills add vercel-labs/ui --skill ui-sdk,并按官方说明更新 AGENTS.md,指向随包文档,例如 node_modules/@ui-sdk/react/docs/llms.txt。 |
| 怎么自己写组件? | 用 definePrimitive 组合 behaviors,再用 createParts 在各框架里渲染。官方引导示例包括 search-field、mute button 和 reactions bar。 |
| 现成组件呢? | @ui-sdk/react 也提供 Select、Dialog、Tabs、Rating 等现成组件,无样式,也不需要 provider 或门户。 |
| 这次实测 | 安装约 0.8 秒;官方 search-field 构建约 0.9 秒通过。给 Agent 装 skill 约 6.7 秒。Claude Code 约 65 秒、Codex 约 71 秒各生成一个评分组件,构建都通过;Codex 的 2 个测试也通过。 |
| 需要注意 | 当前是 beta,受 Vercel public beta 条款约束。官方文档写明 API 仍可能变更。 |
UI SDK 是什么
据 官方文档 和 README,UI SDK 的核心不是又做一套带皮肤的组件库,而是把「界面怎么动」写成可组合的行为,再让人(或 Agent)用这些行为去拼组件。同一个 primitive 可以渲染到 React、Vue、Svelte、Solid 和 Web Components。
据 @shadcn:Agent 正在同时成为界面的构建者和使用者,所以抽象应该落在行为这一层。以 Select 为例,弹层、选择逻辑、键盘导航和焦点管理,在很多组件里都会用到;把这些部分拆开、测好、做成可复用的行为,行为本身不随框架或渲染器改变。他还写到,目标是让 Agent 能在需要时生成你要的界面,包括「我们还没想到的界面」。
据 @rauchg 的比喻,UI SDK「像给 Agent 用的 x86 指令集」,用来即时构建新的 UI 组件。
官方还提供两条并行的路径:
- 自己组合行为:用
definePrimitive定义部件、状态和动作,再用createParts渲染。官方仓库里的引导示例是 search-field;文档里还有 mute button,以及 Build a Component 里的 reactions bar。 - 直接用现成组件:
@ui-sdk/react按组件分子路径导出,例如@ui-sdk/react/button、@ui-sdk/react/dialog、@ui-sdk/react/tabs、@ui-sdk/react/rating。官方写明:没有从@ui-sdk/react根路径做统一导出;组件无样式、无依赖、无 provider、无门户,样式由你自己的 CSS 或 Tailwind 来写。
让 Agent 操作已经渲染出来的页面时,可以用 createAgent() 读取组件状态并调用 actions,文档在 Agents。官方 Agents 文档里有一组 project-settings 对照实验(各跑 3 次取中位数,都用 Sonnet,经 Claude Code,任务全部完成):走浏览器工具是 16 次工具调用、耗时 41 秒;走 ui-sdk 的 agent bridge 是 5 次工具调用、耗时 16 秒。这是官方给出的实验数字,不是我们复测的结果。
UI SDK 目前是 beta。文档站写着:「UI SDK is in beta, so some APIs may still change.」使用受 Vercel Public Beta Agreement 约束,正式 GA 之前,API、文档和行为都可能调整。
发布信息和讨论热度
官方发布时间以 @vercel 的宣布帖 为准:2026-11-12 18:41:04 UTC,对应北京时间 2026-11-13 02:41:04。npm 上 @ui-sdk/react@0.1.0-beta.1 的发布时间是 2026-11-12 17:09:05 UTC(北京时间 01:09),@ui-sdk/core@0.1.0-beta.1 是 17:12:06 UTC(北京时间 01:12)。
据 X 公开数据,截至北京时间 2026 年 11 月 13 日 04:23:
- @vercel 宣布帖:1420 次点赞、93978 次浏览、892 次收藏
- @shadcn 的说明帖:1519 次点赞、45079 次浏览、1064 次收藏
- @rauchg 的评论:221 次点赞、10762 次浏览
如果你已经在跟 Vercel 的其它 Agent 产品,也可以对照《Vercel agent-desktop 怎么用》和《Cursor Live Apps 怎么用》。
安装:先在 React 19 项目里装上 0.1.0-beta.1
官方 React 安装文档 要求项目使用 React 19 和 React DOM 19 或更新版本。我们用 create-vite@9.3.4 的 react-ts 模板建了一个最小项目,模板带上的是 react@19.3.1 / react-dom@19.3.1,以及 @types/react@19.3.0(官方还要求 TypeScript 用户使用 @types/react 19.2.10 或更新)。
npm install @ui-sdk/react @ui-sdk/core
我们这条命令在 2026-11-13 04:20(北京时间)执行,npm 输出是 added 2 packages, and audited 31 packages in 797ms,墙钟约 0.86 秒,退出码 0。npm ls 看到的精确版本是:
@ui-sdk/core@0.1.0-beta.1
@ui-sdk/react@0.1.0-beta.1
react@19.3.1
react-dom@19.3.1
两个 SDK 包的许可证都是 Apache-2.0。@ui-sdk/react 的 peer 依赖写的是 react / react-dom >=19,以及 @ui-sdk/core ^0.1.0-beta.1。其它框架按官方 README 把 @ui-sdk/react 换成 @ui-sdk/vue、@ui-sdk/svelte、@ui-sdk/solid 或 @ui-sdk/web 即可,同样需要同时安装 @ui-sdk/core。
按官方示例写出 search-field,并确认能构建
官方 README 的引导示例是一个带清除按钮的 search-field:输入框有内容时才显示 Clear,按下后清空并把焦点送回输入框。我们按原文把 primitive 和 React 渲染写进 src/lib/search-field.ts 和 src/components/Search.tsx,并在 App.tsx 里同时渲染官方 First Component 文档里的 Toggle。
import { createFocusRecovery, definePrimitive } from "@ui-sdk/core"
const searchField = definePrimitive({
name: "search-field",
state: () => ({ value: "" }),
api: (context) => ({
set: (value: string) => context.store.set({ value }),
recovery: createFocusRecovery({ fallback: () => context.element("input") }),
}),
slots: (slot) => ({
input: slot({
attrs: (state) => ({ value: state.value }),
on: {
input: (event, { api }) =>
api.set((event.target as HTMLInputElement).value),
},
}),
clear: slot({
present: (state) => state.value !== "",
attrs: () => ({ type: "button" }),
press: ({ api }) => api.set(""),
bind: (el, part) => part.api.recovery.bind(el, part),
}),
}),
})
export { searchField }
import { createParts } from "@ui-sdk/react/primitive"
import { searchField } from "../lib/search-field"
const parts = createParts(searchField, { input: "input", clear: "button" })
const SearchField = parts.Root
const SearchFieldInput = parts.Input
const SearchFieldClear = parts.Clear
function Search() {
return (
<SearchField>
<SearchFieldInput placeholder="Search" />
<SearchFieldClear>Clear</SearchFieldClear>
</SearchField>
)
}
export { Search }
随后在项目里执行 npm run build(脚本是 tsc -b && vite build)。本次构建在 2026-11-13 04:20(北京时间)完成,Vite 8.3.8 输出 189 modules transformed,built in 175ms,整条命令墙钟约 0.88 秒,退出码 0。我们没有再打开浏览器手动点选这个搜索框,构建通过就是这一步的结果。
给 Claude Code / Codex / Cursor 装上 UI SDK skill
要让 Agent 按官方工作流选行为、定义 primitive、渲染并测试,官方文档给的安装命令是:
npx skills add vercel-labs/ui --skill ui-sdk
我们在刚才那个 React 项目根目录执行这条命令,墙钟约 6.71 秒,退出码 0。安装器检测到当前环境后,把 skill 拷到了项目里的 ./.agents/skills/ui-sdk。输出写明它面向 Cursor、Codex 以及其它一批 Agent。官方还说明:同一份 skill 也随 @ui-sdk/core 发布,路径是 node_modules/@ui-sdk/core/skills/ui-sdk/SKILL.md,始终和你安装的包版本一致;如果你的 Agent 不支持 skills,可以把 Agent 指到这个文件。
官方 React 快速开始 还要求在 AGENTS.md 里补一段说明(没有就新建)。我们按文档写了如下内容,指向随包文档:
Before using ui-sdk, follow the ui-sdk skill if it is installed, and read
node_modules/@ui-sdk/react/docs/llms.txt. To build a new component, also search
node_modules/@ui-sdk/react/docs/core.md by heading, and read rendering.md next
to it.
其它框架把路径里的 @ui-sdk/react 换成对应包名。关于 Skill 在不同客户端里的安装目录和触发方式,可以继续看《Agent Skills 怎么用》和《tstack 怎么装、怎么用》。如果还要在工具调用前后加钩子,见《Claude Code / Codex / Cursor Agent Hooks 怎么配》。
官方给 Agent 的示例提示是这样的(框架和交互可以按你的需求改):
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.
实测:让 Claude Code 和 Codex 按 skill 生成五星评分
我们把已经装好 SDK、写好 AGENTS.md、并装好 ui-sdk skill 的项目,分别交给 Claude Code 和 Codex,提示词就是上面这条官方示例,并要求保留已有的 search-field、把评分组件接到 App.tsx,最后跑 npm run build。两次运行都走本站 API(配置见下一节),用的是隔离的 HOME,跑完即删除含 Key 的配置。Claude Code 这次还把 skill 拷到了项目内的 .claude/skills/ui-sdk,因为它默认会读这个目录。
Claude Code 2.1.319,模型 claude-opus-5-5,2026-11-13 04:22:01 开始,04:23:06 结束(北京时间),墙钟 65.02 秒,JSON 结果里 duration_ms 为 64442,num_turns 为 20,subtype 为 success。它没有调用现成的 Rating 组件,而是用 @ui-sdk/core 的 definePrimitive、createChange 和 createRovingFocus 写了 src/lib/rating.ts,再用 createParts 写成 src/components/Rating.tsx,五个星星是 role="radio" 的按钮,方向键移动焦点并改值。它自己跑的 npm run build 退出码 0,约 0.9 秒,191 个模块。我们随后在同一目录再构建一次,退出码 0,约 0.79 秒。
Codex CLI 0.167.0,模型 gpt-6.1-sol,同一时间开始,04:23:12 结束,墙钟 70.92 秒。它走的是另一条官方路径:直接使用现成组件 @ui-sdk/react/rating 里的 Rating 和 RatingItem,写成 src/components/Rating.tsx,并用 createAgent() 写了测试。它报告测试 2 passed、退出码 0,构建退出码 0、耗时 0.68 秒(196 个模块,Vite 显示 built in 147ms)。我们随后重新执行 npx vitest run --environment jsdom(Vitest 5.1.0),结果是 Test Files 1 passed、Tests 2 passed,耗时 802ms;再跑一次构建,退出码 0,built in 157ms。两个测试分别覆盖:方向键选择星星且只保留一个 tab stop,以及 agent 通过 snapshot / act({ action: "setValue", args: [4] }) 把评分改成 4。Codex 写明没有做浏览器里的视觉检查。
Cursor 可以安装同一个 skill(这次安装器已经把它列为目标之一),但我们没有在 Cursor 里再跑一遍生成任务,能不能在你的 Cursor 版本里顺利触发,要以你本机为准。
让 Agent 读取并操作系统里的组件
组件渲染到页面之后,Agent 还可以通过官方的 agent bridge 读状态、调 actions。React 的写法据 Agents 文档:
import { createAgent } from "@ui-sdk/react/agent"
const agent = createAgent()
agent.snapshot() 会列出页面上的 ui-sdk 组件、它们的状态和可用 actions。例如一个带无障碍名称的输入框,可以返回 setValue、clear 这类动作。再调用:
await agent.act({
steps: [{ ref: "Project name", action: "setValue", args: ["Atlas"] }],
})
其它框架从 @ui-sdk/vue/agent、@ui-sdk/svelte/agent、@ui-sdk/solid/agent 或 @ui-sdk/web/agent 导入。上面 Codex 的第二条测试就是在用这条 API:它在评分组件上执行了 setValue(4),并且测试通过。你也可以给 createAgent 传入 allow 回调,决定哪些动作可以被执行。
在 Claude Code / Codex / Cursor 里接本站 API Key
UI SDK 本身不是模型 API,不需要单独给它配模型价格。但如果你希望 Claude Code、Codex 或 Cursor 用本站的模型来按 skill 写组件,只需要把客户端指到本站,并填入本站 API Key。三个客户端并列,选你平时用的即可。
Claude Code 写 ~/.claude/settings.json:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
"ANTHROPIC_AUTH_TOKEN": "你的 AICodeWith API Key"
}
}
Codex 写 ~/.codex/config.toml。base_url 必须是 https://api.aicodewith.ai/chatgpt/v1,不要写成 /v1。用全局的 experimental_bearer_token,name 写成 "aicodewith":
model_provider = "aicodewith"
model = "gpt-6.1-sol"
[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "你的 AICodeWith API Key"
Cursor 可以在模型设置里填自定义 API 和模型名。这条路径我们没有实跑,配置是否能连上要以你本机的 Cursor 版本为准。
想先拿一个本站 Key 来跑类似这次的生成任务,可以在下面创建。
常见报错与解法
| 报错 / 现象 | 原因 | 解法 |
|---|---|---|
| 安装或类型检查提示 React peer 不满足 | @ui-sdk/react 要求 React 19+ | 把 react 和 react-dom 升到 19 或更新;TypeScript 用户把 @types/react 升到 19.2.10 或更新 |
| 只装了 @ui-sdk/react,运行或解析失败 | @ui-sdk/core 是 peer 依赖,官方要求两个包一起装,保证只用一份 core | 补装 npm install @ui-sdk/core |
| Cannot find module '@ui-sdk/react' 或没有你要的组件名 | 官方写明没有根路径统一导出,组件从各自的子路径导入 | 改成 import { Dialog, DialogTrigger } from "@ui-sdk/react/dialog" 这种写法 |
| Agent 不按 ui-sdk skill 走,或找不到文档 | skill 没装到该客户端会读的目录,或 AGENTS.md 没有指向随包 llms.txt | 重新执行 npx skills add vercel-labs/ui --skill ui-sdk;按官方说明更新 AGENTS.md;也可以直接让 Agent 读 node_modules/@ui-sdk/core/skills/ui-sdk/SKILL.md |
| Codex 提示模型不存在,但你写的是已上架模型 | base_url 写成了 https://api.aicodewith.ai/v1 | 改成 https://api.aicodewith.ai/chatgpt/v1 |
| 构建通过,但 Clear 按钮不出现,或焦点没有回到输入框 | 没按官方示例接 present / createFocusRecovery,或 Clear 没有包在同一个 primitive 的 Root 里 | 对照官方 search-field 示例检查 present、press 和 bind |
| 升级小版本后 API 对不上文档 | 当前是 beta,官方写明 API 仍可能变更 | 以你安装版本里 node_modules/@ui-sdk/*/docs/ 的随包文档为准,不要只看网站上可能已更新的页面 |
FAQ
UI SDK 和普通组件库有什么不同?
据官方文档,行为集中在 @ui-sdk/core,和框架无关;适配器只负责渲染。现成的 Select、Dialog、Tabs、Rating 也建立在同一套行为上,而且无样式、不需要 provider 或门户。你也可以完全不用现成组件,只用 definePrimitive 拼自己的界面。
必须用 React 吗?
不是。官方同时提供 Vue、Svelte、Solid 和 Web Components 适配器。我们这次实测走的是 React 19.3.1 这条路径,其它框架按官方文档换成对应包即可。本次没有在那些框架里再跑一遍构建。
给 Agent 用,一定要装 skill 吗?
不是必须。官方说:如果你的 Agent 支持 skills,就用 npx skills add vercel-labs/ui --skill ui-sdk;不支持的话,把 Agent 指到 node_modules/@ui-sdk/core/skills/ui-sdk/SKILL.md 或随包的 llms.txt 也可以。我们两种路径都核到了文件确实存在。
beta 阶段能用在生产里吗?
官方文档写明它处于 beta,API 仍可能变更,并指向 Vercel Public Beta Agreement。是否用于生产,要按这份条款和你自己的风险判断来决定。本文只记录安装、构建和 Agent 生成组件的实测结果。
这次 Cursor 为什么没有一起跑?
安装器已经把 Cursor 列为 skill 的目标之一,但我们没有在 Cursor 里发起一次生成任务。正文里的 Cursor 配置是按本站常见写法整理的,没有在这次运行中核对。
需要用本站模型来跑 Claude Code 或 Codex 时,可以先创建一个 API Key。



