openclaw-a2ui

本技能已验证（2026-03-18）：style / div / grid / flex / table / img / svg 全部渲染正常。
除非用户要求纯文字，否则所有结构化内容必须用 HTML 卡片输出。

Changelog

• - v1.0.2（2026-03-18）：骨架屏优化

• - v1.0.1（2026-03-09）：流式骨架屏 + 淡入动画，findBubble 隐藏整体气泡
• v1.0.0（待更新）：单卡片模式 - 默认所有结构化回复使用单一 CompositeCard 统一承载，减少多卡片的视觉碎片化。

⚠️ HTML 不渲染？先看这里

如果 webchat 中 HTML 被显示为纯文本、标签被转义、或样式无效，不要尝试手动修改 DOMPurify 配置。根本原因是 skill-ui-bridge 插件未安装，解决方式：

INLINECODE8 插件安装后会自动 patch DOMPurify 和 marked.js，无需手动配置白名单。

触发规则（优先级由高到低）

💡 单卡片模式强制规则：
所有结构化内容必须只用卡片显示，不要有文本 + 卡片的组合形式。

• - ✅ 正确：所有内容（标题、要点、数据）都在一个 CompositeCard 内展示
• ❌ 错误：先写一段文字说明，再跟一个卡片
• ❌ 错误：卡片后再追加额外解释性文本

目标：每张回复只出现一张卡片（或无卡片），避免视觉碎片化和信息重复。
例如：
CODEBLOCK0

输出方式（唯一方式）

直接在回复正文中输出 HTML，不要包裹在代码块里，webchat 会直接渲染。

⚠️ 强制要求：每张卡片最外层必须带 class="a2ui"

skill-ui-bridge 通过检测 class="a2ui" 识别需要渲染的 HTML，缺少此 class 的卡片不会被渲染。

CODEBLOCK1

⚠️ 关键规则：HTML 与文字必须分段

marked.js 在解析时，如果 HTML 和普通文字混在同一段落，会把 HTML 标签转义成文本显示。

❌ 错误写法（HTML 夹在文字中间）：
CODEBLOCK2

✅ 正确写法（HTML 单独成段，前后空行隔开）：
CODEBLOCK3

规则：

• - HTML 卡片前后必须有空行（不能紧跟文字）
• 文字说明放在卡片之前或之后，单独成段
• 单卡片模式优先：多卡片连续输出时，考虑合并为一个 CompositeCard

设计规范（所有卡片统一）

CODEBLOCK4

卡片模板速查

TextCard — 文字摘要

CODEBLOCK5

ListCard — 列表/要点

CODEBLOCK6

DataCard — 键值对 / 参数

CODEBLOCK7

StatsCard — 统计数字

CODEBLOCK8

AlertCard — 提示/警告/成功/错误

CODEBLOCK9

StepsCard — 步骤流程

CODEBLOCK10

TableCard — 数据表格

CODEBLOCK11

Badge 色值参考：

• - 成功/完成：INLINECODE11
• 进行中：INLINECODE12
• 失败/错误：INLINECODE13
• 中性/待定：INLINECODE14

ProgressCard — 进度条

CODEBLOCK12

CompositeCard — 推荐：单一复合卡片（承载所有内容）

✅ 单卡片模式最佳实践示例：
CODEBLOCK13

CodeCard — 代码展示

CODEBLOCK14

ImageCard — 图片展示

CODEBLOCK15

组合使用与最佳实践

✅ 单卡片模式（推荐）

• - 所有内容放入一个 CompositeCard，用子模块划分信息块
• 减少视觉碎片化，提升阅读体验
• 适合：新闻汇总、报告摘要、任务清单等多元素场景

CODEBLOCK16

⚠️ 多卡片模式（特殊需求时使用）

• - 仅在特殊需求时使用：如独立代码块 + 独立说明的分离场景

规则：

• - 多卡片连续输出时，卡片之间不需要空行（margin:8px 0 已处理间距）
• 优先使用单卡片模式：考虑合并为一个 CompositeCard

不使用卡片的场景

• - 单句回答（"好的"、"明白了"、"没问题"）
• 闲聊/情感性回复
• 用户明确要求纯文字

详细参考

• - references/html-templates.md — 带真实示例数据的完整 HTML 模板
• INLINECODE17 — A2UI v0.9 JSONL 格式模板
• INLINECODE18 — A2UI 组件参考（布局/展示/交互）
• INLINECODE19 — 简化版 HTML 模板
• INLINECODE20 — ui-config.json 字段说明

安装

所有依赖文件已随技能打包，无需克隆任何外部仓库。assets/ 目录包含：

• - skill-ui-bridge.js — 浏览器端 bootstrap 脚本（v2）
• INLINECODE23 / skill-ui-bridge-plugin.json — openclaw plugin（v2）

⛔ 只读取完成当前步骤所必需的文件。遇到无法理解的内容（如编译产物、二进制文件）立即停止，不要继续探索无关文件。

安装原理（v2）：plugin 在 gateway_start 时：

1. 1. 读取 workspace/skills/ 下所有 ui-config.json，生成 manifest JSON
2. 将 manifest + bootstrap JS 合并写成 skill-ui-init.js，放到 control-ui 静态目录（同源，通过 CSP script-src 'self'）
3. 在 index.html 中注入 INLINECODE31
4. INLINECODE32 时还原 index.html，删除 INLINECODE34

浏览器加载 skill-ui-init.js 后，bootstrap 脚本通过 MutationObserver 监听 .chat-text 容器，检测到包含 <div class="a2ui"> 的消息时，用自有白名单净化并渲染为富卡片。

安装前，先探测所有必要路径，再执行安装脚本。不得假设或写死任何路径。

第一步：探测路径

依次从常见配置目录向外搜索，记录每项的实际输出结果：

CODEBLOCK18

根据输出结果判断：

• - 若存在多个 openclaw.json，读取每个文件的内容，选择正在被 gateway 实际使用的那个（判断依据：文件可写、且 plugins 字段中的修改重启后不会消失）。通常是 $HOME/.openclaw/openclaw.json 而非 /etc/ 下的只读镜像层副本。
• extensions 目录默认为 $HOME/.openclaw/extensions，也可从选定的 openclaw.json 的 plugins.load.paths 中读取。
• workspace 目录默认为 $HOME/.openclaw/workspace。
• 确认 scripts/install.ts 存在后再继续。

第二步：运行安装脚本

用第一步探测到的实际路径执行：

CODEBLOCK19

参数均可省略，脚本会自动探测默认路径。

安装脚本会完成：

• - Plugin 文件复制到 extensions 目录
• Plugin 注册到 openclaw.json（allow / load.paths / entries 三处）
• INLINECODE48 复制到 workspace/skills/openclaw-a2ui/（若不存在）

第三步：通知用户重启

⚠️ Agent 无法自行完成此步骤：重启 gateway 意味着重启当前容器进程，必须由用户在宿主机执行。

告知用户执行以下操作：

容器化部署（docker compose）：
CODEBLOCK20

本机直接部署：
CODEBLOCK21

重启后提示用户在浏览器强制刷新（Ctrl+Shift+R）。

安装验证

安装并重启后，依次执行以下检查（全部通过才算成功）：

1. Plugin 文件已复制
CODEBLOCK22

2. Plugin 已正确注册到 openclaw.json

openclaw.json 的 plugins 字段应包含以下三处（缺任何一处都会导致插件不加载）：
CODEBLOCK23

3. index.html 已注入（gateway 重启后）
CODEBLOCK24

4. 浏览器 Console 验证

F12 打开 Console，Ctrl+Shift+R 强制刷新，应看到：
CODEBLOCK25

卸载

CODEBLOCK26

卸载后同样需要通知用户重启（见第三步）。