A2UI:让 Agent 画界面,而不是写代码

01 · A2UI:让 Agent 画界面,而不是写代码

读完你会知道:

  1. A2UI 为什么出现,它和「让模型直接写 HTML」「用 JSON Schema 生成表单」的根本差别;
  2. A2UI 与 AG-UI、MCP、A2A 各自解决哪一类问题、边界在哪里;
  3. 五类协议消息、surface 生命周期,以及「结构 / 数据 / 界面状态」为什么必须三分;
  4. v1.0 收敛了哪四处(@path / @checks / 单消息实例化 / value=null 删键),以及为什么过渡期必须双读;
  5. 一次交互里,消息怎么从模型的 token 流变成屏幕上的 DOM,动作又该回到哪里;
  6. 一套最小可跑的实现需要哪几步,失败时先查什么。
    三句话版本
  • 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;

把「不执行代码」落到实现上,是五件具体的事:

  1. 组件名白名单:目录外一律跳过,但要留一条日志------静默跳过会让「界面少一块」无从排查。
  2. 属性类型收敛 :数字先 Number()、枚举先查表、长度先截断,再进 DOM。
  3. 文本走 textContent ,不拼 innerHTML;模型给的字符串不是可信 HTML。
  4. SVG / 属性禁止原样拼接 :size、href、src 这类能被事件或伪协议利用的字段尤其要小心。
  5. @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 上:先在左下角「⚙ 设置」里填自己的模型,再让它下一单试试------工具循环、步数预算、审批拦截都能在页面上看到。

相关推荐
阿里云云原生21 分钟前
阿里云 AgentLoop 通过中国信通院《企业级 FDE 交付能力要求》标准评估
agent
阿里云云原生2 小时前
2026 中国开源年会:Agent Builder Meetup×AAIF Meetup 分论坛精彩回顾 & PPT 下载
agent
花椒技术2 小时前
客户端团队用 AI 做直播间桌球,状态同步和渲染怎么落地
agent·ai编程·游戏开发
阿里云云原生2 小时前
我们用 AI 给 AgentLoop 手搓了一套海底世界探秘游戏,并开源了
云原生·agent
qinglongcn3 小时前
上下文压缩的六种武器——从工具结果去重到认知交班
agent·ai编程
Cosolar3 小时前
从 Model 到 System:AI Agent Infra 工程师的技术全景与学习路径
langchain·aigc·agent
武子康3 小时前
H3-World 动作控制怎么测:从左右对照到片内切换
人工智能·agent·claude
威哥爱编程5 小时前
模拟面试智能体开发实战 12:每篇都能跑不等于接起来能跑,端到端联调收官把十一块拼图合成一个能用的智能体
python·agent·harmonyos