Canvas 与 A2UI：Agent 可视化交互渲染

Canvas 与 A2UI：Agent 可视化交互渲染

概述

Canvas（画布）与 A2UI（Agent-to-User Interface）是一种从 Agent 的文本输出中提取交互式 UI 规范并渲染为可视化工作区的模式。Agent 不仅生成文本回复，还能生成可交互的 UI 组件，使用户能够在对话过程中直接操作和查看结果。

核心概念

A2UI 的核心思想是：Agent 的文本输出不仅是信息，还可以是 UI 的声明式描述。系统从文本中解析这些描述，并将其渲染为交互式组件。

两种提取方式

1. JSON 记录提取

从工具输出或 Agent 回复中解析 JSON 记录：

{
  "kind": "canvas",
  "presentation": {
    "target": "assistant_message",
    "title": "数据可视化",
    "preferred_height": 400
  },
  "view": {
    "url": "/path/to/canvas",
    "id": "doc-id"
  }
}

字段	说明
kind	固定为 "canvas"，标识这是一个 Canvas 记录
presentation.target	渲染目标表面，目前仅支持 "assistant_message"
presentation.title	Canvas 标题，显示在 UI 头部
presentation.preferred_height	首选高度（160-1200px）
view.url	Canvas 内容的 URL
view.id	文档标识符

2. 短代码（Shortcode）提取

从 Agent 的文本输出中解析 [embed] 短代码：

[embed ref="my-doc" title="我的画布" height=400 class="my-class" /]
[embed url="https://example.com/canvas" title="外部画布"][/embed]

短代码支持两种形式：

• 自闭合：[embed ref="..." ... /]
• 成对标签：[embed url="..."][/embed]

围栏感知解析

短代码解析器是围栏感知的：位于 Markdown 围栏代码块内的短代码会被忽略，不会被提取为 Canvas。这确保了代码示例中的短代码不会被误解析。

Canvas 渲染规范

属性	类型	说明	约束
kind	"canvas"	固定值	必须
surface	"assistant_message"	渲染表面	仅支持此值
render	"url"	渲染方式	通过 URL 加载
url	string	Canvas 内容 URL	可选
viewId	string	视图标识符	可选
title	string	标题	可选
preferredHeight	number	首选高度	160-1200px
className	string	CSS 类名	可选
style	string	内联样式	可选

URL 解析规则

当短代码使用 ref 而非完整 URL 时，系统自动解析为标准路径：

/__openclaw__/canvas/documents/<ref>/index.html

这使得 Agent 只需引用文档标识符，无需构建完整 URL。

设计考量

为什么选择声明式提取而非直接渲染？

方案	优点	缺点
声明式提取	安全（Agent 无法直接注入 HTML）、可控（尺寸约束）、可审计	灵活性受限、需要预定义格式
直接 HTML 渲染	完全灵活	XSS 风险、难以约束、安全风险高

围栏感知的重要性

围栏感知解析确保：

1. 代码示例中的短代码不会被误执行
2. Agent 可以安全地展示短代码语法作为教程
3. 解析器能够区分”使用”和”展示”短代码

尺寸约束的必要性

Canvas 高度限制在 160-1200px 之间：

• 最小值 160px：确保内容有足够空间展示
• 最大值 1200px：防止单个 Canvas 占据过多屏幕空间

与其他交互模式的对比

模式	描述	适用场景
纯文本	Agent 仅生成文本回复	简单问答、解释说明
工具调用	Agent 调用工具执行操作	文件操作、代码执行
Canvas/A2UI	Agent 生成可视化交互界面	数据可视化、编辑器、仪表板

参考来源

• A2UI 概念来源于 AI Agent 交互设计领域的通用模式
• 短代码语法受 WordPress shortcode 和 Astro component 语法启发