让AI直接画界面:深入OneBox(万宝盒)A2UI动态生成Compose UI的协议实现
让AI直接画界面:深入OneBox(万宝盒)A2UI动态生成Compose UI的协议实现
OneBox(万宝盒)是一款全量开源、免费使用的安卓 AI 智能体 & 工具箱,其中一项"黑魔法"是:AI 不只回复文字,还能用 A2UI 协议动态生成 Compose UI 界面——在聊天里直接画出可交互的表单、选择器和卡片,用户填完点提交,数据立刻以结构化文本回传给 AI 继续对话。
本文将带你深入 OneBox 的 core/a2ui 模块,拆解这套"AI 画界面"的协议实现:消息结构、组件模型、数据绑定、渲染管线,以及表单如何提交回 AI。无需精通 Kotlin,看懂 JSON 就能理解 90% 的设计。
一、A2UI 是什么:AI 动态生成界面的开放协议
A2UI(Agent-to-User Interface) 是 Google 发起的开放协议,核心思路很直白:
不让 AI 输出 Markdown 或 HTML,而是让 AI 输出一段描述"界面结构"的 JSON,客户端把它渲染成原生 Compose 组件。
这样做的好处:
- 🎨 原生体验:按钮、输入框都是系统级 Compose 控件,跟随主题与深色模式
- 📡 流式友好:JSON 边生成边解析,界面可以"长"出来
- 🔒 安全可控:AI 只能描述"要什么组件",无法执行任意代码
OneBox 在 core/a2ui/a2ui.md 中维护了完整的组件 Schema 参考文档,这也是写自定义 Agent 提示词时的"字典"。
二、一条消息如何变成一张界面
1. 最小消息:createSurface
AI 回复中的 JSON 本质是一封"信封包裹的指令"。OneBox 的解析器 A2uiContentParser.kt 会依次尝试从 createSurface、body 或根对象中提取界面描述:
{
"createSurface": {
"surfaceId": "ai_dynamic",
"catalogId": "basic",
"components": [
{
"id": "root",
"component": "Column",
"padding": 16,
"spacing": 12,
"children": ["title", "name", "submit"]
},
{
"id": "title",
"component": "Text",
"text": "帮我预约一次服务",
"style": "titleMedium"
},
{
"id": "name",
"component": "TextField",
"label": "您的姓名",
"value": { "path": "/name" }
},
{
"id": "submit",
"component": "Button",
"label": "提交",
"action": {
"event": {
"name": "submit",
"context": { "prompt": "姓名: ${name}" }
}
}
}
],
"dataModel": { "name": "" }
}
}
界面加载后,AI 还可以继续"局部改画"。OneBox 支持的全部消息类型定义在 A2uiMessage.kt 中:
| 消息 | 方向 | 作用 |
|---|---|---|
createSurface |
AI → 端 | 创建一块界面(Surface),携带初始组件与数据 |
updateComponents |
AI → 端 | 增量更新/替换组件 |
updateDataModel |
AI → 端 | 按 JSON Pointer 路径更新表单数据 |
deleteSurface |
AI → 端 | 销毁界面 |
callFunction |
AI → 端 | 调用端侧能力(如 getDeviceInfo) |
actionResponse |
端 → AI | 动作执行结果 |
error |
双向 | 错误通知 |
2. 组件模型:五个保留字段撑起一切
每个组件就是一个 JSON 对象,模型类 A2uiComponent.kt 只保留 5 个字段,其余属性一律归入 properties:
| 字段 | 含义 |
|---|---|
id |
组件唯一标识,children 通过 id 组树 |
component |
组件类型名(如 TextField) |
properties |
除保留字段外的所有属性(自动收纳) |
children |
子组件 id 数组 |
action |
点击等交互动作(事件或函数调用) |
这种"开放属性 + 封闭骨架"的设计,让 LLM 生成 JSON 时出错率极低:属性写多了不会被拒绝,只有 id 和 component 缺失才会报错。
3. 数据绑定:DynamicValue 的三种取值
表单界面的灵魂是数据与视图分离。DynamicValue.kt 定义了属性值的三种形态:
| 形态 | JSON 写法 | 用途 |
|---|---|---|
字面量 Literal |
"padding": 16 |
固定值 |
路径绑定 Pointer |
{ "path": "/name" } |
双向绑定 dataModel 中的字段 |
函数 Function |
{ "call": "xxx", "args": [] } |
计算型取值 |
一个约定特别重要:数据绑定必须写成 {"path": "/x"} 对象格式。这是写 Agent 提示词时最容易踩的坑,a2ui.md 文档里也专门用 ⚠️ 标注了。
用户输入时,控件的值沿 path 写回 A2uiSurfaceState.kt 中的 dataModel——它同时保存组件表和表单数据,是整个界面的"内存"。
三、渲染管线:JSON 树递归长出 Compose 组件
1. 状态层:快照驱动的响应式界面
A2uiSurfaceState 使用 Compose 的 SnapshotStateMap 存放组件,任何一条 updateComponents 消息落地,对应组件自动失效重绘,无需手动刷新。多块界面并存时,由 A2uiSurfaceHolder.kt 按 surfaceId 管理生命周期。
2. 注册表 + 递归组件树
渲染入口 A2uiSurfaceView.kt 找到 id = "root" 的组件后,交给 A2uiComponentTree.kt 按 id 递归展开;每种组件类型对应一个 Renderer,统一由 A2uiComponentRegistry.kt 注册分发。
OneBox 内置的渲染器按四类组织,位于 catalog/builtin:
- 📐 布局(layout/):
ColumnRowCardListSpacer,支持玻璃拟态样式 - ⌨️ 输入(input/):
ButtonTextFieldCheckBoxSwitchSliderStepperChoicePickerDateInputColorPickerLocationPickerImagePickerRating及各种Selector,共 25 种 - 👀 展示(display/):
TextImageIconDividerTabsBadgeAudioPlayerVideo - 💬 反馈(feedback/):
ProgressModal
想扩展新组件?实现一个 Renderer 并注册即可,协议层零改动。
3. 传输层:可插拔的消息通道
消息收发抽象在 A2uiTransport.kt,默认实现是 StubA2uiTransport.kt(进程内直通)。A2uiMessageHandler.kt 负责把消息路由到对应 Surface 状态,并对 callFunction 做了白名单校验——只有 getScreenResolution、getDeviceInfo 等安全函数可被 AI 调用,其余一律拒绝,这是"AI 驱动界面"场景下很重要的一道护栏。
四、双向交互:用户点"提交"后发生了什么
这是 A2UI 区别于"AI 生成静态图"的关键——界面是双向的:
- 用户点击
Button,其action.event(结构见 A2uiAction.kt)携带事件名submit和context.prompt模板 - 事件经 A2uiActionBus.kt(基于
SharedFlow的全局事件总线)发布 - A2uiDynamicContent.kt 订阅到事件后,把
dataModel中各字段的值替换进${field}占位符,例如模板"姓名: ${name}"变成"姓名: 张三" - 生成的 prompt 文本通过
onSubmit回投给 AI 对话流,AI 基于结构化数据继续任务
如果没有模板,则自动把 dataModel 拼成 key: value 列表。也就是说,AI 自己设计表单 → 用户填写 → AI 拿到干净的结构化数据,全程不需要用户打字描述。
五、OneBox AI 助手中的落地
在 feature/ai 模块中,A2UI 与聊天系统通过一层薄适配桥接:A2uiRendererImpl.kt 实现富文本组件的 A2uiRenderer 接口,内部委托给 A2uiDynamicContent。流式阶段,消息块以 a2ui 类型识别(见 BlockReuseCache.kt),只展示稳定骨架,避免半截 JSON 闪烁。
效果示例——AI 一边对话、一边把结果落成结构化卡片:
想直接体验完整界面版本,可参考独立页面 A2uiScreen.kt。
六、动手上手:3 步让 AI 给你画界面
- 读协议:通读组件 Schema 文档 core/a2ui/a2ui.md,掌握"哪个场景必须用哪个组件"的选择表
- 写提示词:在 Agent 系统提示词中约束 AI 输出
createSurfaceJSON,并强调数据绑定必须用{"path": "/x"}格式 - 接回调:在
A2uiDynamicContent的onSubmit中处理提交的 prompt 文本,继续对话或调用工具
完整源码目录速查:
- 协议模型:domain/model/
- 渲染注册表:catalog/
- 状态与事件:state/
- 界面入口:ui/
七、小结
- A2UI 把"AI 回复"从文本升级为可交互的原生界面,JSON 即协议,Compose 即画布
- OneBox 的实现分层清晰:消息(A2uiMessage)→ 状态(SurfaceState)→ 组件树(ComponentTree + Registry)→ 事件(ActionBus),各层可独立替换扩展
- 数据绑定
${field}模板 +path双向绑定,是"表单提交回流 AI"闭环的精髓 - 传输层白名单、组件注册表等设计,兼顾了灵活性与安全边界
如果你想让自己的 Android 应用也支持"AI 画界面",OneBox 的 core/a2ui 模块就是一份可以直接参考的开源实现。


