01 · A2UI:让 Agent 画界面,而不是写代码
读完你会知道:
- A2UI 为什么出现,它和「让模型直接写 HTML」「用 JSON Schema 生成表单」的根本差别;
- A2UI 与 AG-UI、MCP、A2A 各自解决哪一类问题、边界在哪里;
- 五类协议消息、surface 生命周期,以及「结构 / 数据 / 界面状态」为什么必须三分;
- v1.0 收敛了哪四处(
@path/@checks/ 单消息实例化 /value=null删键),以及为什么过渡期必须双读;- 一次交互里,消息怎么从模型的 token 流变成屏幕上的 DOM,动作又该回到哪里;
- 一套最小可跑的实现需要哪几步,失败时先查什么。
三句话版本
- A2UI 是声明式 UI 载荷:只说「用哪些组件、绑哪些数据」,不执行代码,也不规定传输。
- AG-UI 是管道,A2UI 是货物;换成 SSE、WebSocket 或一次 HTTP 响应,货物照样能运。
- v1.0 的四处变化都在「让模型少写错」:
@path、@checks、单消息实例化、value: null删键;读的时候双读,写的时候规范。
适用版本与读者路径本文对应 A2UI v1.0(2026-11),兼容 v0.9 的裸
path读法。文中 JSON 示例按本项目渲染器的约定做了简化,字段名以官方规范和实际渲染器为准;凡是写「本项目」的地方都是工程取舍,不是协议规定。
官方规范在 GitHub 的
a2ui-project/a2ui仓库(Apache 2.0),另有 AG-UI、MCP、A2A 各自的规范;本文不复制规范原文,需要逐字段核对时以仓库里的 schema 为准。
架构 / 产品:1 → 2.5 → 五 → 七;前端实现:2.2 → 2.3 → 2.6 → 三 → 四;
只想跑通本项目:4.3 → 4.5,再按需查第六节(那节是代码索引,可以跳过)。
官方定义(意译) :A2UI 是 Google 提出的声明式 UI 载荷协议 (Apache 2.0)。它不规定传输方式,只规定「Agent 用什么 JSON 描述一块界面」;渲染由客户端用自己信任的原生组件完成。
与之相邻的 AG-UI 由 CopilotKit 主导,是事件式的 Agent ↔ 前端通信协议,规定「怎么把事件推给前端」。
一、为什么会有它
1.1 起因:模型刚学会「调函数」,就有人让它「画界面」
2022 年 10 月,普林斯顿的 Shunyu Yao 等人把「想一步、做一步、看一眼结果」写成了论文 ReAct,
模型第一次有了 thought → action → observation 的循环。约八个月后的 2023 年 6 月 13 日,OpenAI 把这套循环做成了 API:
function calling 让模型直接吐出符合 JSON Schema 的调用参数,靠正则解析字符串的时代结束了。
能力一到手,产品经理的胃口立刻变大。既然模型能稳定输出结构化 JSON,为什么不让它输出界面 ?
2023 年下半年起,一批「一句话生成页面」的产品出现:模型写 HTML、写 React、写 Tailwind 类名,前端拿到就渲染。
演示视频都很好看------好看的原因是演示者只输入了它擅长的那几句话。
1.2 撞墙:三条路,最后都撞在同一堵墙上
行业试过三种做法,每一种都在同一个地方停下:
| 做法 | 当时看起来的优势 | 生产环境撞在哪 |
|---|---|---|
| 前端写死所有界面,模型只挑一个 | 绝对安全、绝对一致 | 界面组合是开放集合,穷举不完;新需求仍要发版 |
| 模型直接生成 HTML / JS | 想画什么画什么 | 模型输出是不可信输入,一段 <script> 就是任意代码执行;HTML 是闭合树,半个标签没法渲染;一份 HTML 绑死一个端 |
| 生成的代码塞进 iframe 沙箱 | 把注入面关进笼子 | 安全了,但样式、无障碍、原生交互全丢;仍然只在 Web 上成立 |
三条路的失败点看着不同,根因是同一个:模型在生成「可执行的东西」 。
只要生成物能被浏览器执行,安全、流式、跨端就永远只能打补丁。
还有一条常被忽略的岔路:用 JSON Schema / OpenAPI 生成表单 。它确实安全,也确实能跨端,
但 Schema 描述的是「数据长什么样」,不是「界面长什么样」:字段顺序、分组、只读态、按钮位置、
「什么时候该禁用」都不在 Schema 里。最后仍然要在前端写一套「Schema → 组件」的映射,
模型能控制的只剩字段名------这又退回了「界面写死」的老问题。
1.3 转折:不写代码,只报菜名
2025 年 12 月 15 日,Google 公开了 A2UI(Apache 2.0,CopilotKit 与社区共同参与)。
它的判断只有一句:把「生成代码」换成「声明组件」。
协议定义一份组件菜单------Card、Button、TextField、Chart------模型只声明「这里要一个标题、一个输入框、一个按钮」,
客户端拿自己实现的 组件去画。模型碰不到可执行代码,代码执行类 注入面从结构上消失;
但要留意「消失」的边界------属性值、文本、URL、SVG 参数仍可能在渲染端被拼成危险内容,
这部分要靠在渲染器里收敛(第五节有实例)。组件也是客户端自己的,样式与无障碍可以跟着宿主走,
不过那只是「能做对」的基础,aria、焦点、键盘仍要渲染器自己处理。
这份规范不是一次设计出来的,而是被模型的真实行为推着改了四版:
flowchart LR V8"v0.8\
结构化输出优先\
surface / 组件 / 数据绑定" --> V9"v0.9\
转向 Prompt-First\
createSurface / 客户端函数 / 自定义 catalog" V9 --> V91"v0.9.1\
稳定版\
统一 application/a2ui+json" V91 --> V10"v1.0(2026-11)\
@path 绑定 / @checks 校验\
单消息实例化 / 删键语义"
第一版假设模型会「一次性吐一份完整 JSON」,实际它做不到,于是 v0.9 转向增量与提示词优先;
跑起来又发现「用户点了按钮,回执没地方放」,才补上 action 回执与 action id。
协议的形状,是模型的短处刻出来的。
v1.0 于 2026 年 11 月发布,改的不是消息种类(仍是那五类),而是模型最容易写错的四处:
| 变化 | v0.9 的写法 | v1.0 | 为什么改 |
|---|---|---|---|
| 绑定键加前缀 | {"path":"/form/name"} |
{"@path":"/form/name"} |
path 是个太普通的词,绑定的 {"path":...} 和数据本身叫 path 的字段分不开;加 @ 一眼看出「这是指针」 |
| 校验进协议 | 规则散在渲染器与宿主代码里,模型看不见 | 组件带 @checks |
「必填 / 格式」本来是界面的事,却只能散落在渲染器和提示词里 |
| 单消息实例化 | 先 createSurface,再 updateComponents,再 updateDataModel |
createSurface 里直接内嵌 components 与 dataModel |
模型经常漏发第一步,前端就得靠兜底猜「这轮是不是要开新画布」 |
| 删键有语义 | 删一个键只能整块重写 | updateDataModel 的 value: null 表示删掉该键 |
表单里「清空某个字段」以前要重发整棵数据 |
注意 @ 只加在绑定 上。updateDataModel.path 是消息自己的参数,指名「往哪里写」,
它不是绑定,仍然写 "path";表格列定义里的 path 是字段名,也不是绑定。这三处混起来,
模型会稳定地在某些位置漏掉或加上 @------所以本项目的护栏是双读,而不是硬性要求一种写法(见 2.6)。
1.4 三代方案放在一起看
上面四处都是协议内部的事,回答不了「为什么该选它」。把它放回更大的坐标里,和另外两条路比一比:
| 写死界面 | 生成代码(HTML/JS) | 声明式组件(A2UI) | |
|---|---|---|---|
| 界面自由度 | 低(预先枚举) | 无限 | 高(受组件目录约束) |
| 安全边界 | 只需防传统 Web 风险(XSS 等),不涉及模型注入 | 靠沙箱,仍有逃逸面 | 代码执行面消失;属性、文本仍要渲染端收敛 |
| 流式渲染 | 不适用 | 半截标签无法渲染 | 天然增量:一条组件一条消息 |
| 跨端 | 每端各写一遍 | 绑死 Web | 一份载荷,各端各自渲染 |
| 新增一个组件 | 改前端 + 发版 | 无需改,但样式不可控 | 加渲染 + 加目录条目 |
| 模型可控范围 | 只能选 | 任意代码 | 组件、属性、数据、事件 |
这张表对应 1.2 的三条撞墙记录:A2UI 不是把三条都优化了,而是把「生成物」从代码换成了数据,三条同时消失。
1.5 它在协议栈里的位置
「Agent 协议」经常被混为一谈。更准确的说法是:它们是 Agent 伸向四个方向 的四条边界,各自解决一件事,
彼此不构成依赖链。
flowchart LR AG(("Agent")) AG -->|"要工具 / 数据"| MCP"MCP\
Agent ↔ 工具" AG -->|"要另一个 Agent 干活"| A2A"A2A\
Agent ↔ Agent" AG -->|"把过程与界面推给前端"| AGUI"AG-UI\
Agent ↔ 前端事件管道" AGUI -->|"CUSTOM 帧里的载荷"| A2UI"A2UI\
声明式界面" AG -.->|"直接 SSE / WebSocket / HTTP"| A2UI
这张图想说:MCP、A2A、AG-UI 是三根不同的出线,A2UI 是其中一件「货」------最常装在 AG-UI 这条管道里,
但也有一条自己的直连路线。把 AG-UI 换成 SSE 直推,A2UI 照样能用,它不依赖管道 。
本项目走的就是虚线这条:没有引入 AG-UI,只用 SSE 的 a2ui 帧。
项目内另有一张可交互版(
blog/diagrams/protocol-boundaries.html,可缩放、右侧带补充卡片)。不在本仓库里读这篇的读者跳过即可,不影响正文。
- MCP(Model Context Protocol):把工具与数据接给模型,官方定位是「标准化应用如何向 LLM 提供上下文」。
- A2A(Agent2Agent):让 Agent 之间互相发现与派活。
- AG-UI:把 Agent 的运行事件(文本增量、工具调用、状态)推给前端。
- A2UI:规定这些事件里「界面部分」长什么样。
一句话区分:AG-UI 是管道,A2UI 是货物。所以 A2UI 可以跑在 SSE 上、WebSocket 上,甚至一次 HTTP 响应里------传输方式不改变协议本身。
sequenceDiagram autonumber participant A as Agent 运行时 participant G as AG-UI 事件层 participant F as 前端 A->>G: RUN_STARTED A->>G: TEXT_MESSAGE_CONTENT(正文增量) A->>G: CUSTOM(a2ui):updateComponents / updateDataModel A->>G: RUN_FINISHED G->>F: SSE / WebSocket 帧 F->>F: 文本走 markdown,a2ui 走渲染器
这条时序解释了一个常见误解:用了 AG-UI 不等于有了界面协议 。AG-UI 只保证「事件能到前端」,
事件里的 CUSTOM 载荷长什么样、前端怎么渲染,仍然要 A2UI 这样的约定了算。
二、它是什么
2.1 三个核心对象
| 对象 | 含义 | 归属 | 生命周期 |
|---|---|---|---|
| Surface | 一块画布,有 id,独立于页面 | 渲染器 | 一次任务 |
| Component | 画布上的节点,扁平列表 + children 引用组成树 |
渲染器 | 随 surface |
| DataModel | 键值数据,组件通过 {"@path": "/x/y"} 绑定 |
渲染器 | 随 surface |
组件树是扁平数组 而不是嵌套 JSON:每个组件带 id,父子关系靠 children: ["a","b"] 表达。
这个设计不是审美选择,而是流式的必要条件------模型可以先发骨架,再逐条追加子组件,不必等整棵树闭合。
三个词后面会反复出现,先对齐:组件目录(catalog) 是渲染器认识的那份组件清单,目录外的一律不画;
绑定(binding) 是 {"@path":"/x/y"} 这种「值不在这里,去数据模型取」的写法;
动作(action) 是 {"event":{"name":...,"context":...}},只描述「发生了什么」,不含「发给谁」。
2.2 扁平数组如何变成一棵树
渲染器不按数组顺序画,而是先建 id → component 的索引,再从 root 递归:
js
// 渲染器的核心循环(简化)
handleMessage(msg) {
for (const c of msg.updateComponents.components) this.components.set(c.id, c);
this.requestRender();
}
render() {
const root = this.components.get('root');
this.container.appendChild(this.renderComponent(root.id)); // 递归 children
}
扁平结构带来三个工程性质:
- 同 id 覆盖是幂等的 :模型重发一次
updateComponents,只会替换定义,不会多出一个节点; - 可以只发一半 :先发
root + Column,下一帧再发子组件,前端不会因为「引用暂时不存在」崩掉,只会先空着; - 可以局部删除 :
deleteComponents只移除指定 id,不必整面重画。
代价是引用完整性要靠约定 :children 指向不存在的 id 时,渲染器只能跳过。
所以提示词里必须要求「先骨架、后子件,且只追加不重复」,否则会出现「界面看起来少了一块」。
2.3 五类消息
| 消息 | 作用 | 幂等性 | 常见误用 |
|---|---|---|---|
createSurface |
开一块画布 | 重复创建等于重置 | 每条消息都带一次,导致界面被清空 |
updateComponents |
声明组件、追加或更新组件定义 | 同 id 覆盖 | 重复发已存在的 id,把用户输入冲掉 |
updateDataModel |
往数据模型写值(按 path 合并) | 同 path 覆盖 | 用数组下标拼 path,后端一改结构就错位 |
deleteComponents |
删除指定组件(局部收敛,不必整面重画) | 删除不存在的 id 无副作用 | 拿它当「清空界面」,结果 dataModel 还在 |
deleteSurface |
关掉画布 | 重复调用无副作用 | 以为它会清历史 DOM(它只清渲染器状态) |
字段速查(真想写渲染器时,先看这张):
| 消息 | 必填 | 可选 / 形态说明 |
|---|---|---|
createSurface |
surfaceId |
title;components[](v1.0 可内嵌);dataModel(v1.0 可内嵌) |
updateComponents |
surfaceId、components[] |
每个组件必须带 id,父子靠 children 引用 |
updateDataModel |
surfaceId、path、value |
value: null 表示删键(v1.0);path 是消息参数,不带 @ |
deleteComponents |
surfaceId、componentIds[] |
本项目渲染器 componentIds 与 ids 都读,取值顺序是前者优先;写法以你的渲染器为准 |
deleteSurface |
surfaceId |
无 |
createSurface 是这五条里唯一会「丢掉用户输入」的。 v1.0 允许它内嵌 components 与 dataModel 之后,
风险更大:重复发一次,不只清组件,连 dataModel 里用户已经填好的值一起重置。
两条纪律:一轮只在开头发一次;内嵌的 dataModel 只放初始值,不要放「当前值」。
value: null 在协议里是删键 ,不是「存一个 null」。业务上确实要表达空值时,
用空字符串、省略该键,或自己约定一个空值标记------别指望 null 能落库成「空」。
deleteComponents 常被忽略,但它决定了「界面能否优雅收敛」:提交成功后撤掉表单、只留结果,靠它;
没有它就只能整块重画或另开 surface。
deleteSurface 有一个容易误解的边界:它清的是渲染器内部状态 (components / dataModel / surfaceId),
不会删除页面上已经生成的 DOM。历史气泡仍然看得见、甚至还能点------这就是为什么本项目还要额外做
「历史 surface 冻结」(a2-surface-history),不能指望 deleteSurface 收尾。
surface 的生命周期和「一次任务」对齐,2.3 那五类消息沿一条主路径排开:
flowchart LR C"createSurface\
开画布" --> U"updateComponents\
组件增改" U --> D"updateDataModel\
数据写入" D --> U D --> X"deleteComponents\
局部收敛" X --> S"deleteSurface\
关画布" U -.->|"也可以直接关"| S S -.->|"只清渲染器状态"| H"页面上的历史气泡仍在"
这张图想说:画布可以反复增改、也可以局部收敛;deleteSurface 是终点,但它清的是渲染器内部,
页面上的旧 DOM 不会跟着消失------所以「关掉画布」和「用户看不见了」是两件事。
deleteSurface 不要求 先走 deleteComponents:用户切任务、关面板、直接换一轮对话,都会整块丢弃,
这时渲染器把 components / dataModel / surfaceId 一起清掉,本来就没什么可「局部收敛」的。
deleteComponents 只在「同一块画布要保留、只撤掉其中一块」时才有意义。
项目内另有一张可交互版(
blog/diagrams/surface-lifecycle.html,含「终点 ≠ 消失」「唯一会丢输入的动作」两张警示卡),本仓库外读者可跳过。
v1.0 之后 createSurface 多了一种形态:components 与 dataModel 直接内嵌在它里面,
一条消息完成「开画布 + 铺内容」。老的三条写法仍然有效,渲染器两种都认------
规范演进时只加形态、不删旧形态,是这类协议的通用做法,否则存量消息全得重写。
2.4 关键设计:结构 ≠ 数据 ≠ 界面状态
这是理解 A2UI 的钥匙。同一张饼图由两条消息组成:
json
// ① 结构:只有数据指针,没有数值
{"updateComponents":{"surfaceId":"main","components":[
{"id":"catChart","component":"Chart","chartType":"pie","label":"投诉类型分布",
"data":{"@path":"/analytics/categoryDistribution"}}
]}}
// ② 数据:真值在这里(path 是消息参数,不是绑定,所以不带 @;surfaceId 必填,不能省)
{"updateDataModel":{"surfaceId":"main","path":"/analytics","value":{
"categoryDistribution":[{"name":"商品质量","value":3},{"name":"物流配送","value":2}]
}}}
flowchart LR C"updateComponents\
组件树 + {@path}" --> R"渲染器" D"updateDataModel\
/analytics 真实数值" --> R R -->|"按 path 取值"| OUT"Chart / Table / Text"
三个直接收益:
- 结构可复用:同一套组件声明可以喂不同数据,不必每次重写树;
- 一份数据多处绑定:饼图、表格、文本可以指向同一个 path;
- 可增量:数据后到就先画骨架,到一条刷一条------这正是流式界面的基础。
但「三分」比「两分」更准确。除了结构与数据,还有第三类东西:界面状态 。
页签下标、哪个分组被折叠、哪些组件被本地按钮隐藏------它们只影响渲染,不是业务数据。
本项目的做法是把它们放进独立的 uiState:
js
this.uiState = { tabs: {}, collapsed: {}, hidden: new Set() };
如果把它们混进 DataModel,会立刻出现两个问题:提交表单时被当成业务字段发给后端;
服务端 schema 校验把它判成「未定义字段」而拒绝。界面状态一旦进入数据模型,就不再是界面状态了。
2.5 它能做什么,不能做什么
| 能做 | 不能做 |
|---|---|
| 用统一 JSON 描述表单、卡片、表格、图表等结构化界面 | 描述任意像素级布局、动画、自定义样式 |
| 跨端渲染(组件实现由各端提供) | 保证各端视觉完全一致(取决于实现) |
| 流式增量渲染、局部更新 | 替代前端框架的状态管理 |
| 把用户动作以「事件名 + 上下文」回传 | 规定动作必须发给谁(由宿主决定) |
| 约束模型只能组合已登记的组件 | 阻止模型把错误值写进合法字段(要靠服务端护栏) |
最后一行很重要:A2UI 解决「不执行代码」,不解决「事实正确」。
模型仍然可以在合法的 Text 组件里写一个错误的金额------这属于业务护栏,见后文。
2.6 v1.0 的两个新东西:@checks 与「双读」
@checks 把「界面该提示什么」从代码搬进了消息。 以前「必填」是渲染器里的一个 if,
「邮箱格式」是宿主页面里的正则,模型既看不见也改不了;现在它跟着组件一起下发:
json
{"id":"email","component":"TextField","label":"邮箱",
"value":{"@path":"/form/email"},
"@checks":[{"expression":{"@call":{"name":"email"}}}]}
校验规则是一个表达式,取三种形态之一:
| 形态 | expression 的写法 |
语义 |
|---|---|---|
| 基础函数 | {"@call":{"name":"regex","args":{"pattern":"^1\\d{10}$","message":"手机号格式不对"}}} |
内置 required / regex / length / numeric / email 五个 |
| 数据绑定 | {"@path":"/form/agree"} |
取数据模型里的值,作为布尔条件求值------用于「勾了才允许提交」这类跨字段规则 |
| 字面量 | true / {"equals":1} |
常量规则,少见 |
文案的优先级要小心,它跟形态有关:函数形态 的文案在 args.message 里,不写就用函数自带的
(required → 「此项为必填」、email → 「邮箱格式不正确」);绑定表达式 没有函数可返回文案,
才用规则上的 message 兜底。规则上的 message 对函数形态是无效的------这个细节写错了不会报错,
只会显示一句你不认识的内置文案,排查时容易以为「提示没生效」。
求值结果统一成 ValidationResult(valid + message)。这一层抽象很值钱:
函数可以返回结构化结果,绑定表达式只能给出一个可判真假的布尔,渲染器却只需要处理一种返回类型。
一个真实输入下,校验是本地同步 完成的:输入框失焦 → 取 @checks → 求值 → 有错就标红并在字段下写 message,
全程零请求。所以它属于「体验」,不属于「边界」------用户改个 DOM 就绕过了,服务端仍旧要按字段定义再判一遍(11 篇的三层校验)。
「双读」是过渡期的成本。 v1.0 把绑定键改成 @path,但线上还有旧消息、模型也会混写。
本项目的渲染器与后端护栏都按 @path 优先、裸 path 兜底来读:
js
function bindingPathOf(binding) {
if (!binding || typeof binding !== 'object') return '';
const p = binding['@path'] ?? binding.path; // v1.0 优先,v0.9 兼容
return typeof p === 'string' ? p : '';
}
这不是「和稀泥」。模型对键名的漂移是稳定发生 的:同一轮里它可能给输入框写 @path、给图表写 path。
如果渲染器只认一种,症状是「界面出来了但输入框是死的」------比报错更难查。
兼容读的代价只有一行代码,覆盖的是「漏 @」与「旧版裸 path」这两类;它兜不住 @ 放错位置({"path":"@/form/x"}),
也兜不住字段名漂移------那两样要靠规范化与测试(4.5 有一条真实失败样例)。
三、运行机制
一条消息从模型到屏幕,要经过「切分 → 传输 → 渲染」三段:
sequenceDiagram autonumber participant M as 模型(流式) participant P as 流式解析器 participant E as 后端端点 participant F as 前端宿主 participant R as 渲染器 M->>P: 正文与 JSON 混在同一条流 Note over P: 文本模式:探测协议键名<br/>JSON 模式:按花括号配平切消息 P->>E: 文本增量 / 完整消息 / 全文替换 E->>F: SSE:status · textdelta/text · a2ui · approval · done F->>R: updateComponents / updateDataModel R->>R: 建树、按 path 取值、render() R-->>F: DOM / SVG
3.1 模式判定:为什么不能只看第一个字符
流式解析器一上来就要回答一个问题:这轮输出是「正文」还是「A2UI JSON」?
最直觉的做法是看第一个非空白字符:{ 或 [ 就是 JSON,否则是正文。这个做法在真实模型上会出错------
模型经常先寒暄一句「好的,我来帮你建一个表单」,再输出 JSON。首字是「好」,于是被永久锁进文本模式,
后面的 JSON 全被当正文发给用户。
本项目的处理(A2uiStreamParser)是两段式:
- 首字不是
{/[/ 代码围栏 → 先按文本模式走,但保留 64 字符的探测窗口; - 窗口里持续扫描「
{+ 可选空白 +"+ 协议键名」,命中才切 JSON 模式; - 切换时把已经当正文发出去的那段 JSON 撤回。
「撤回」这个动作穿过了三层,名字和载体都不一样,读代码时最容易在这里绕晕:
| 层 | 名字 | 形态 |
|---|---|---|
| 解析器内部 | ReplaceText |
ParseStep 的构造参数,标记「这一步要撤回已发文本」 |
| 解析器对外 | ReplacesText |
只读属性,=> ReplaceText,给上层判断 |
| SSE 传输 | 无对应字段 | 后端改发一条 type:"text" 的全量文本帧,前端整段覆盖 |
也就是说前端收到的帧里不会 出现 replacesText;它能看到的只有「来了一条 text 全量帧」。
textdelta 是追加,text 是覆盖------两者的差别就是撤回本身(3.4 的帧表按这个写)。
少了这一步,用户会先看到半截 {"updateComponents"... 再突然消失。
3.2 切分:字符串里的括号不算括号
JSON 模式下,解析器按花括号配平切消息。必须跳过字符串与转义,否则一条消息会被切成两半:
csharp
if (inString) {
if (escaped) { escaped = false; continue; }
if (ch == '\\') { escaped = true; continue; }
if (ch == '"') inString = false;
continue;
}
真实模型还会输出代码围栏、行尾逗号、两条消息之间的说明文字。解析器的策略是「能丢就丢,不能卡死」:
围栏整行丢弃,非 JSON 噪音按行丢弃,半截 JSON 解析失败就丢掉这一条------流式下宁可少一条,也不要整条流断掉。
3.3 渲染:全量重建 + 局部恢复
渲染器收到一条消息就 requestRender()。在流式场景里,autoRender 会被临时关掉,
由宿主用 requestAnimationFrame 合并成一次重绘:
js
renderer.autoRender = false;
for (const m of batch) renderer.handleMessage(m);
renderer.autoRender = true;
renderer.render();
render() 是全量重建 :清空容器,从 root 重新递归。这听起来很贵,但换来三个确定的好处:
同 id 覆盖天然幂等、组件删除不会留孤儿 DOM、错误态与显隐可以统一重算。
全量重建的代价是焦点丢失 。本项目在重建前 captureFocus() 记住当前输入框的 data-path 与光标位置,
重建后 restoreFocus() 还原;否则用户每打一个字,光标就跳走一次。
它还有规模上限:界面在几十个组件时,一次全量重建是毫秒级,完全够用;到几百个组件、或流式追加频率很高时,
拐点就来了------那时该按 surface 分区渲染,或做局部 diff。协议不限制组件数量,但**「全量重建」是策略,不是协议**。
3.4 一条真实的消息序列
text
data: {"type":"status","data":{"text":"智能体正在思考..."}}
data: {"type":"textdelta","data":{"text":"好的"}}
data: {"type":"text","data":{"text":"好的,我来帮你查订单。"}} ← 撤回 JSON 前缀后的全量文本
data: {"type":"a2ui","data":{"createSurface":{"surfaceId":"main"}}}
data: {"type":"a2ui","data":{"updateComponents":{...}}}
data: {"type":"a2ui","data":{"updateDataModel":{...}}}
data: {"type":"done","data":{"kind":"a2ui","count":3}}
帧类型一共六种,type 决定谁消费、怎么消费:
type |
内容 | 谁消费 | 误用后果 |
|---|---|---|---|
status |
过程提示:「智能体正在思考...」「正在调用 查订单...」 | 状态条 / loading | 当正文渲染,聊天里会出现「智能体正在思考...」 |
textdelta |
正文增量 | 流式气泡 | 当最终结果,丢最后一段 |
text |
正文全量;收到它就意味着覆盖,帧里不带任何标记字段 | markdown 渲染(整段替换) | 当增量追加,文字重复 |
a2ui |
一条 A2UI 消息 | 界面渲染器 | 没收到,只有文字没有界面 |
approval |
待审批的工具调用 | 审批卡片 | 忽略,流程卡在「等你确认」 |
done |
收尾:kind(text / a2ui / approval),a2ui 轮还带 count |
结束态、计数 | 不处理,一直转圈 |
status 与 approval 是最容易漏的两类:前者不是内容,只说明「正在干什么」;后者只在有高风险工具时出现,
走的是另一条回传路径(14 篇讲 HITL)。上面那段是「纯界面」一轮,所以只看到 status / textdelta / text / a2ui + done。
approval 与 done.kind=approval 是配套的,别只处理一个:这一轮以「等你确认」结束时,
done 之前必然 已经发过一帧 approval(先发卡片、再发收尾),顺序固定;
纯文本轮、纯界面轮的 done 前面则永远不会有 approval。
把 a2ui 当文本渲染、或把 textdelta 当最终结果,症状分别是「界面变成一串 JSON」和「最后一段文字丢了」。
上面是 v0.9 的节奏。v1.0 里第一条 a2ui 帧往往直接带上 components 与 dataModel,帧数少一条;
但 SSE 的 type 一个都没变------协议升级不必动传输层,这正是把 A2UI 与 AG-UI 分开的收益。
四、最小实践
4.1 场景
给「查询订单」做一个最小界面:一个标题、一个订单号输入框、一个查询按钮。
要求:输入绑定到表单、按钮回传意图、不依赖任何前端框架。
4.2 一条消息就够(v1.0)
json
{"createSurface":{"surfaceId":"main","title":"查询订单",
"dataModel":{"form":{"orderId":""}},
"components":[
{"id":"root","component":"Column","children":["t","f","b"]},
{"id":"t","component":"Text","text":"请提供订单号","variant":"h2"},
{"id":"f","component":"TextField","label":"订单号","value":{"@path":"/form/orderId"},
"@checks":[{"expression":{"@call":{"name":"required","args":{"message":"订单号不能为空"}}}},
{"expression":{"@call":{"name":"regex","args":{"pattern":"^[A-Z]{2}\\d{6}$",
"message":"格式应为两位字母 + 六位数字"}}}}]},
{"id":"b","component":"Button","child":"bt","action":{"event":{"name":"agentIntent",
"context":{"intent":"queryOrder","label":"查询订单"}}}},
{"id":"bt","component":"Text","text":"查询订单"}
]}}
v0.9 要三条消息(createSurface → updateComponents → updateDataModel),v1.0 允许一条发完。
这不破坏流式:单条只是「首帧更完整」,后续仍可以继续 updateComponents 追加,或 updateDataModel 填值。
真正常见的是反过来 ------模型忘了发 createSurface 就直接发组件,v1.0 之前前端只能自己兜底建画布。
三点必须遵守:root 是根组件;输入值绑到 /form/xxx(随表单一起提交);按钮的 action 只是「事件名 + 上下文」。
注意 context.label 和按钮上那行字是两样东西 :按钮显示什么由 child 指向的 Text(这里是 bt)决定,
context.label 是给 Agent 看的意图描述。这个例子里两者都写「查询订单」只是为了直观;
真实项目里常写成按钮显示「查」、context 写「queryOrder」,甚至 context 比按钮文字信息更多(带上前一屏的 id、用户已选的项)。
别把展示文案当成意图传递的唯一通道 ------模型看不到你屏幕上的字。
@checks 里的 pattern 是字符串 ,反斜杠要按 JSON 转义写两次------这也是为什么「正则别让模型自由发挥」,
11 篇会讲正则超时与放行。
字段名先对齐(这段按本项目渲染器的约定写,不是规范逐字;换实现要先核对):
| 字段 | 含义 |
|---|---|
child / children |
单子节点 / 多子节点。按钮文字用 child 指向一个 Text |
action.event |
动作名 + context,这是「事件」,不是「接口调用」 |
value |
输入类组件的绑定({"@path":...}) |
data |
图表、表格的数据绑定(同样 {"@path":...}) |
label |
显示名,同时应作为无障碍名称------渲染器要负责把它落到 aria-label |
点下按钮之后发生什么。 action.event 只是起跑线,闭环要宿主接:
sequenceDiagram autonumber participant U as 用户 participant R as 渲染器 participant H as 宿主 participant A as Agent U->>R: 点击「查询订单」 R->>R: 读 Button.action.event R->>H: agentIntent + context{intent, label} H->>A: POST /api/chat(把 intent/context 拼进这一轮) A-->>H: SSE:textdelta / text / a2ui / done H->>R: 新的 a2ui 消息
这张图想说:协议只规定「发什么事件」,不规定「发给谁」。渲染器把事件抛给宿主,
宿主可以把它拼成下一轮对话(本项目的做法),也可以直接调一个固定接口------两条路都合法。
项目内另有一张可交互版(
blog/diagrams/action-roundtrip.html,带「按钮点不动先查历史冻结」的排错卡),本仓库外读者可跳过。
4.3 跑起来
以下命令是 Unix shell(macOS / Linux / Git Bash);PowerShell 里 T=$(...) 不成立,python 也可能叫 python3。
bash
# 1) 拿一个匿名票据(浏览器由 HttpOnly Cookie 自动携带,CLI 需要显式拿)
T=$(curl -s --noproxy '*' -X POST http://localhost:5210/api/identity/anonymous \
| python3 -c "import sys,json;print(json.load(sys.stdin)['ticket'])")
# 2) 发一句话,观察 SSE 帧
curl -s --noproxy '*' -N -X POST http://localhost:5210/api/chat \
-H 'Content-Type: application/json' \
-d "{\"message\":\"帮我做一个查询订单的界面\",\"sessionId\":\"$T\"}" \
--max-time 120 | head -40
预期能看到四组帧:status、textdelta / text、a2ui、done(3.4 那张表列了六种,另外两种这轮不会出现:
approval 只在有高风险工具要人工确认时才发,纯界面轮没有)。
done 的 kind 是 a2ui(并带 count)就说明这轮出界面了。
若只有 textdelta、没有 a2ui,先查模型这一轮有没有真的输出协议键名,而不是先怀疑渲染器。
两个容易卡住的点:一是 head -40 按行截断,界面复杂时 done 可能被截掉,看起来像「流没结束」------
去掉 head,或改用 `grep -E '"(status |
textdelta | text | a2ui | done)"'` 只留帧头; |
二是 /api/chat 的 sessionId 里放的应该是匿名票据,把登录 token 塞进去会被当成匿名身份静默降级。 |
4.4 前端最小接入
html
<div id="host"></div>
<script src="/assets/a2ui-core.js"></script>
<script>
const renderer = new A2uiRenderer();
renderer.container = document.getElementById('host');
// 收到 SSE 的 a2ui 帧就喂进来
function onA2ui(message) { renderer.handleMessage(message); }
</script>
不需要 React/Vue。渲染器只做三件事:维护 components 与 dataModel、按 path 取值、把组件画成 DOM/SVG。
调试时直接读实例上的 renderer.dataModel,或者 handleMessage 之后打一行
console.log(JSON.stringify(renderer.dataModel))------「输入到底有没有写进数据模型」,
盯着 DOM 是看不出来的:输入框里明明有字,绑定没生效也照样有字。
4.5 验收与失败样例
| 检查点 | 通过标准 | 失败时先查 |
|---|---|---|
| 组件渲染 | 标题、输入框、按钮都出现 | root 是否存在;children 引用的 id 是否都发过 |
| 输入真的绑上了 | 打字后 renderer.dataModel.form.orderId 有值(用 console 看,不看输入框) |
value 是否 {"@path":"/form/orderId"}(v1.0 带 @,v0.9 不带);updateDataModel 的 path 是否写全了层级 |
| 本地校验 | 留空失焦即标红,不发请求 | 函数形态的文案是否写在 args.message 里(写到规则上会被内置文案盖掉) |
| 动作回传 | 点按钮产生 agentIntent |
action.event.name 是否拼写正确;按钮是否在历史 surface 里 |
| 流式 | 界面逐条出现,不是最后一次性出现 | 解析器是否误判成文本模式 |
这一行把「绑定声明对不对」和「值有没有真的落进去」合成了一个检查点:声明对但值没进,和值进了但路径错,
症状完全一样------界面上看着正常,提交时值不对。所以不分开列,统一以 dataModel 里的实际值为准。
三个真实失败长这样:
- 组件名不在目录 :模型输出
{"component":"Select"},渲染器静默跳过,界面少一块。查Skills/a2ui-basic/SKILL.md与a2ui-core.js的case列表是否同步。 - 绑定键写错位置 :
{"@path":"/form/orderId"}写成{"path":"@/form/orderId"},渲染器读不到路径,输入框是空的但能编辑;提交时才暴露。双读只能兜住「漏 @」,兜不住「@ 放错地方」。 - JSON 半截 :解析器丢掉半条消息,界面停在骨架。看后端 trace 的
a2ui条数与模型原文是否一致。
五、边界与取舍
| 取舍 | 说明 |
|---|---|
| 协议只到消息级 | 后端通常只按消息 key 白名单过滤,不校验组件类型名;组件合法性由前端渲染器决定 |
| 组件目录有两处真相 | 「渲染器支持什么」+「提示词里告诉模型能生成什么」,必须同时维护,否则模型会生成渲染不出来的组件 |
| 不做布局引擎 | A2UI 描述的是组件与数据,不是 CSS;精细排版仍由客户端组件实现负责 |
| 安全性来自「不执行代码」 | 组件名、属性值仍要在渲染端做白名单校验,否则会退化成「用 JSON 表达的 XSS」 |
@checks 不是安全边界 |
它跑在用户浏览器里,改 DOM、直接打接口都能绕过。它买的是「即时提示」与「规则跟着消息走」,裁决仍在服务端 |
| 不保证事实正确 | 模型仍可在合法组件里写错金额/状态;要靠服务端事实与一致性护栏(见 02、12 篇) |
「不执行代码」不等于「绝对安全」,本项目就踩过一次:Icon 的 size 属性被原样拼进 SVG 字符串,
模型输出 size: '20" onload="..."' 就能闭合属性注入事件处理器。修复方式不是加提示词,
而是在渲染器里把它收敛成数字:
js
const n = Number(size);
const px = Number.isFinite(n) && n > 0 ? Math.round(n) : 20;
把「不执行代码」落到实现上,是五件具体的事:
- 组件名白名单:目录外一律跳过,但要留一条日志------静默跳过会让「界面少一块」无从排查。
- 属性类型收敛 :数字先
Number()、枚举先查表、长度先截断,再进 DOM。 - 文本走
textContent,不拼innerHTML;模型给的字符串不是可信 HTML。 - SVG / 属性禁止原样拼接 :
size、href、src这类能被事件或伪协议利用的字段尤其要小心。 @checks只做体验,服务端仍按字段定义校验------它是给人看的提示,不是准入。
还有两件常被漏掉的事:本项目 渲染器里 @checks 的内置文案是写死的中文(「此项为必填」「邮箱格式不正确」),
这是实现选择,不是协议规定------换一个实现,语言策略可能完全不同。要支持多语言,文案就得跟着字段定义走
(在 args.message 里显式给),不能指望协议内置函数;label 要落到 aria-label、错误提示要能被打字机读到
(aria-describedby),重建后焦点要回原位(见 3.3 的 captureFocus / restoreFocus)。
无障碍不是组件自带的美德,是渲染器要写的代码。
同理,当模型频繁把 SegmentedControl 的绑定写成 value 而不是 selections 时,
只在提示词里强调是不够的:渲染器要兼容两种写法,服务端 Normalize 还要把 value:{"@path":...} 补成 selections。
模型字段名漂移是常态,兜底要放在代码里 ------这条在 v1.0 之后多了一个实例:绑定键的 @ 前缀,
模型会稳定地在某些位置漏写、在另一些位置多写,所以读的时候只能双读,写的时候才要求规范。
什么样的情况不该用 A2UI:
- 需要像素级设计器、自由拖拽布局------A2UI 的组件目录会限制你;
- 需要任意脚本交互(画布、复杂动画)------它本来就不执行代码;
- 界面完全固定、只有一两个字段------直接写前端比引入协议更便宜。
六、小结
- A2UI 解决的是「界面无法预定义」与「模型输出不可信」的矛盾:只描述结构,不执行代码。
- 它的三个核心设计是扁平组件树 (可流式、可局部更新)、结构与数据分离 (可复用、可增量)、
界面状态独立(不污染提交数据)。 - v1.0 没有推翻这套骨架,只是把模型最容易写错的四处显式化:绑定键
@path、校验@checks、
createSurface单消息内嵌组件与数据、value=null删键。协议越往后走,改的越是「模型的行为」,不是「界面的能力」。 - 它不管传输,也不管动作发给谁;这两件事分别由 AG-UI / SSE 和宿主决定。
- 安全上它只消掉「代码执行」这一类风险;属性收敛、文本转义、无障碍,仍然是渲染器的活。
- 它也不保证事实正确:金额、状态、权限仍需服务端确定性护栏------这是下一篇 Harness 要接住的事。
在线体验:http://117.72.72.215:5210
这套东西跑在一个真实部署的 Demo 上:先在左下角「⚙ 设置」里填自己的模型,再让它下一单试试------工具循环、步数预算、审批拦截都能在页面上看到。