连接 A2UI 渲染器

宿主渲染器负责校验消息、维护 Surface 状态、把 Catalog 映射到本地组件，并返回用户 Action；传输层是独立职责。

1. 选择官方维护渲染器

安装官方渲染器目录列出的版本，并固定对应协议 Schema。公开 API 可能随协议分支变化，初始化代码应来自已安装包文档，而不是未标版本的文章。

2. 注册 Catalog

把每个允许的 Catalog 条目映射到宿主自有组件。Catalog 应保持小型、版本化和显式。能够导航、嵌入远程内容、读取文件、使用剪贴板、认证或提交交易的组件必须单独审核策略。

// 1. 创建注册表 (防火墙)
const catalog = createCatalog({ Text, Button, Form });

// 2. 渲染输出
const renderer = createRenderer({ catalog, protocolVersion: "0.9.1" });

上述标识符用于说明职责；实际代码应使用固定渲染器版本导出的准确 API。

3. 连接有边界的数据流

A2UI 与传输无关，但消息分帧不可省略。必须保留完整消息边界，限制大小和速率，认证对端，处理取消，并拒绝不支持的媒体类型。

const response = await fetch("/api/agent", {
  headers: { Accept: "application/a2ui+json" },
});

// 将数据块喂给 A2UI 解析器
for await (const message of decodeA2UI(response.body)) {
  renderer.receive(validateA2UI(message));
}

4. 通过服务端处理 Action

renderer.onAction(async (action) => {
  // Action = { name: "submit", data: { ... } }
  await sendAuthorizedAction(action);
});

可见或禁用组件都不是授权边界。服务端必须重新检查身份、权限、资源状态和幂等性。发布前测试非法消息、不支持组件、半包、重连、过期 Action、键盘操作与文本降级。

参见消息参考、渲染器矩阵和生产安全清单。