消息参考

当前 v0.9.1 生命周期

消息	方向	用途
`createSurface`	Agent → 渲染器	创建指定 Surface 并选择 Catalog。
`updateComponents`	Agent → 渲染器	添加或替换组件定义。
`updateDataModel`	Agent → 渲染器	应用带版本约束的数据模型变更。
`deleteSurface`	Agent → 渲染器	删除活跃 Surface 及其关联状态。

消息使用 application/a2ui+json 媒体类型。surfaceId 在活跃期间必须唯一，只能在删除后复用。所有消息应依据准确的官方 v0.9.1 Schema校验。

{"version":"v0.9.1","createSurface":{"surfaceId":"order","catalogId":"https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"}}
{"version":"v0.9.1","updateComponents":{"surfaceId":"order","components":[{"id":"root","component":"Column","children":["title"]},{"id":"title","component":"Text","text":"确认订单","variant":"h2"}]}}
{"version":"v0.9.1","updateDataModel":{"surfaceId":"order","path":"/","value":{"status":"draft"}}}

渲染器必须拒绝未支持的 Catalog、组件类型、路径、URL 与 Action。参见生产安全清单。

v0.8 旧版消息参考

以下内容只为仍要求 v0.8 的宿主产品保留。不得将这些消息名混入 v0.9.1 数据流。

消息类型

beginRendering

通知客户端开始渲染 Surface。

Schema:

{
  beginRendering: {
    surfaceId: string; // 必需：唯一 Surface 标识符
    root: string;      // 必需：要渲染的根组件 ID
    catalogId?: string; // 可选：组件目录 URL
    styles?: object;    // 可选：样式信息
  }
}

示例:

{ "beginRendering": { "surfaceId": "main", "root": "root-component" } }

surfaceUpdate

定义或更新 UI 组件。

Schema:

{
  surfaceUpdate: {
    surfaceId: string; // 必需：目标 Surface
    components: Array<{ // 必需：组件列表
      id: string; // 必需：组件 ID
      component: { // 必需：组件数据包装器
        [ComponentType]: { // 必需：确切的一个组件类型
          ...properties // 组件特定属性
        }
      }
    }>
  }
}

使用说明:

组件形成邻接表（扁平结构）。
发送具有现有 ID 的组件会更新该组件。
组件可以增量添加。

示例:

{
  "surfaceUpdate": {
    "surfaceId": "main",
    "components": [
      {
        "id": "greeting",
        "component": {
          "Text": {
            "text": {"literalString": "Hello, World!"},
            "usageHint": "h1"
          }
        }
      }
    ]
  }
}

dataModelUpdate

更新 Surface 的应用状态（数据模型）。

Schema:

{
  dataModelUpdate: {
    surfaceId: string; // 必需：目标 Surface
    path?: string;     // 可选：模型中的路径
    contents: Array<{  // 必需：数据条目
      key: string;
      valueString?: string;
      valueNumber?: number;
      valueBoolean?: boolean;
      valueMap?: Array<{...}>;
    }>
  }
}

使用说明:

contents 数组对 LLM 友好，避免了通用值类型推断问题。
支持通过 path 进行细粒度更新。

deleteSurface

移除 UI Surface 及其数据。

Schema:

{
  deleteSurface: {
    surfaceId: string; // 必需：要删除的 Surface
  }
}

示例:

{ "deleteSurface": { "surfaceId": "modal" } }

消息顺序

推荐顺序:

surfaceUpdate (定义组件)
dataModelUpdate (填充数据)
beginRendering (显示 UI)
后续的 surfaceUpdate / dataModelUpdate (交互式更新)
deleteSurface (清理)