让AI直接画界面:深入OneBox(万宝盒)A2UI动态生成Compose UI的协议实现

原创2026-10-24 12:00:432,238 阅读

让AI直接画界面:深入OneBox(万宝盒)A2UI动态生成Compose UI的协议实现

OneBox(万宝盒)是一款全量开源、免费使用的安卓 AI 智能体 & 工具箱,其中一项"黑魔法"是:AI 不只回复文字,还能用 A2UI 协议动态生成 Compose UI 界面——在聊天里直接画出可交互的表单、选择器和卡片,用户填完点提交,数据立刻以结构化文本回传给 AI 继续对话。

OneBox万宝盒卡片式工具箱首页,90+功能模块

本文将带你深入 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/):Column Row Card List Spacer,支持玻璃拟态样式
  • ⌨️ 输入(input/):Button TextField CheckBox Switch Slider Stepper ChoicePicker DateInput ColorPicker LocationPicker ImagePicker Rating 及各种 Selector,共 25 种
  • 👀 展示(display/):Text Image Icon Divider Tabs Badge AudioPlayer Video
  • 💬 反馈(feedback/):Progress Modal

想扩展新组件?实现一个 Renderer 并注册即可,协议层零改动。

3. 传输层:可插拔的消息通道

消息收发抽象在 A2uiTransport.kt,默认实现是 StubA2uiTransport.kt(进程内直通)。A2uiMessageHandler.kt 负责把消息路由到对应 Surface 状态,并对 callFunction 做了白名单校验——只有 getScreenResolution、getDeviceInfo 等安全函数可被 AI 调用,其余一律拒绝,这是"AI 驱动界面"场景下很重要的一道护栏。

四、双向交互:用户点"提交"后发生了什么

这是 A2UI 区别于"AI 生成静态图"的关键——界面是双向的:

  1. 用户点击 Button,其 action.event(结构见 A2uiAction.kt)携带事件名 submit 和 context.prompt 模板
  2. 事件经 A2uiActionBus.kt(基于 SharedFlow 的全局事件总线)发布
  3. A2uiDynamicContent.kt 订阅到事件后,把 dataModel 中各字段的值替换进 ${field} 占位符,例如模板 "姓名: ${name}" 变成 "姓名: 张三"
  4. 生成的 prompt 文本通过 onSubmit 回投给 AI 对话流,AI 基于结构化数据继续任务

如果没有模板,则自动把 dataModel 拼成 key: value 列表。也就是说,AI 自己设计表单 → 用户填写 → AI 拿到干净的结构化数据,全程不需要用户打字描述。

OneBox AI动手前弹授权框,工具分类、风险级别、原始参数全透明

五、OneBox AI 助手中的落地

在 feature/ai 模块中,A2UI 与聊天系统通过一层薄适配桥接:A2uiRendererImpl.kt 实现富文本组件的 A2uiRenderer 接口,内部委托给 A2uiDynamicContent。流式阶段,消息块以 a2ui 类型识别(见 BlockReuseCache.kt),只展示稳定骨架,避免半截 JSON 闪烁。

效果示例——AI 一边对话、一边把结果落成结构化卡片:

OneBox AI助手把一次对话拆成多条记录写入健康记录表单

想直接体验完整界面版本,可参考独立页面 A2uiScreen.kt。

六、动手上手:3 步让 AI 给你画界面

  1. 读协议:通读组件 Schema 文档 core/a2ui/a2ui.md,掌握"哪个场景必须用哪个组件"的选择表
  2. 写提示词:在 Agent 系统提示词中约束 AI 输出 createSurface JSON,并强调数据绑定必须用 {"path": "/x"} 格式
  3. 接回调:在 A2uiDynamicContent 的 onSubmit 中处理提交的 prompt 文本,继续对话或调用工具

完整源码目录速查:

七、小结

  • A2UI 把"AI 回复"从文本升级为可交互的原生界面,JSON 即协议,Compose 即画布
  • OneBox 的实现分层清晰:消息(A2uiMessage)→ 状态(SurfaceState)→ 组件树(ComponentTree + Registry)→ 事件(ActionBus),各层可独立替换扩展
  • 数据绑定 ${field} 模板 + path 双向绑定,是"表单提交回流 AI"闭环的精髓
  • 传输层白名单、组件注册表等设计,兼顾了灵活性与安全边界

如果你想让自己的 Android 应用也支持"AI 画界面",OneBox 的 core/a2ui 模块就是一份可以直接参考的开源实现。

登录后查看全文
OneBox