[特殊字符] ZorvAI 动态 UI 组件：让 AI 的回答「看得见、用得上」

🌟 项目简介

ZorvAI 动态 UI（quro-ui） 是一套基于 Jetpack Compose 原生构建的可交互界面渲染框架。它让 AI 不再局限于「文字 + 代码块」的输出形态，而是能够主动地生成卡片、表单、列表、播放器、浏览器、富媒体等完整的交互式界面——就像一位熟练的前端工程师，根据用户意图即时绘制出最合适的 UI。

🔗 开源地址：https://github.com/Quor-a/ZorvAI

✨ 核心理念

🏛 架构总览

┌────────────────────────────────────────────────────────────────────────┐
│ QuroAssistant 主对话流水线 │
├────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌────────────┐ ┌─────────┐ ┌─────────────────┐ │
│ │ 用户提问 │ → │ System │ → │ LLM │ → │ 文本/quro-ui │ │
│ │ + 上下文 │ │ Prompt │ │ 决策 │ │ JSON 混合输出 │ │
│ └─────────┘ │ 「动态 UI │ │ 工具调用│ └─────────────────┘ │
│ │ 必备输出」 │ └─────────┘ │ │
│ └────────────┘ ▼ │
│ ┌─────────────────┐ │
│ │ A2uiEnvelope │ │
│ │ (a2ui 协议信封) │ │
│ └─────────────────┘ │
│ │ │
│ ┌───────────────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ QuroUiDslParser│ → │ QuroUiCatalog│ → │ QuroUiNode │ │
│ │ 净化/解析/纠错 │ │ 调色板与图标 │ │ AST │ │
│ │ │ │ 字面量校验 │ │ │ │
│ └────────────────┘ └──────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ SurfaceHost │ │
│ │ 挂载 Compose 容器 │ │
│ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ QuroUiRenderer │ │
│ │ 17+ 原生组件渲染 │ │
│ └──────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘

📦 模块拆解 · 10 个文件各司其职

core/ui/dynamicui/
├── QuroUiNode.kt # AST 节点类型定义
├── QuroUiDslParser.kt # quro-ui 字符串净化 + JSON 解析
├── QuroUiCatalog.kt # 调色板 / 图标库 / 校验器
├── QuroUiColor.kt # 16 阶灰度 + 语义色映射
├── QuroUiIcons.kt # Lucide 图标库（camelCase → snake_case）
├── QuroUiPointer.kt # 路径解析 + 数据更新指针（[a-z0-9_./-]+）
├── QuroUiRenderer.kt # ⭐ 核心：JSON AST → Compose 组件
├── SurfaceHost.kt # 无限尺寸 / maxWidth 崩溃修复 + 渲染挂载
├── A2uiEnvelope.kt # a2ui 信封协议（deepMerge / updateDataModel）
├── A2uiInterpreter.kt # 信封嗅探（lowercase 开头自动识别）
└── QuroDynamicUiTool.kt # ⭐ ui_dsl_spec / ui_validate 工具

🔧 各文件职责一览

🧬 DSL 解析管线

quro-ui 的输入是模型输出在 fenced code block 里的 JSON。我们永远不假设模型一定写出干净 JSON，所以解析管线有四层防护：

🛡 1️⃣ sanitizeJson(raw: String)

目标：抹平「误置闭合符」（最常见的 AI 病）。

fun sanitizeJson(raw: String): String {
// 1) 找到第一个 '[' 或 '{' 作为起点
// 2) 跟踪 (字符串内/外) + (反斜杠转义) 状态机
// 3) 在字符串外允许的成对字符 [ ] { } ：
// – 若遇到孤立的 ']' 或 '}'，先看上层栈；不平衡则补一个同向（保守）补齐
// 4) 丢弃顶层其余杂质（多余反引号、注释尾巴）
}

🔧 典型拯救：

// 模型输出：
[
{ "type": "text", "text": "你好" }
{ "type": "button", "label": "确定" } // ← 漏了 ,
]

// sanitizeJson 后：
[
{ "type": "text", "text": "你好" },
{ "type": "button", "label": "确定" }
]

🛡 2️⃣ fixOutsideStrings(s: String)

目标：修字符串外的脏括号（{ type: "foo} — 引号未关）。

fun fixOutsideStrings(s: String): String {
val out = StringBuilder()
var inSgl = false; var inDbl = false
for (c in s) {
when {
c == '\\\\' && (inSgl || inDbl) -> { out.append(c); /* 跳过下个 */ }
c == '"' && !inSgl -> inDbl = !inDbl
c == '\\'' && !inDbl -> inSgl = !inSgl
...
}
out.append(c)
}
}

🛡 3️⃣ normalizeQuotes(s: String)

目标：统一单/双引号 → JSON 标准双引号。在字符串外为 inSgl = false 时安全替换。

🛡 4️⃣ QuroUiCatalog + QuroUiColor.parse() 校验

目标：颜色字面量必须是已知 token，否则归一为 gray.7（中灰）；图标名必须存在于白名单。

🎨 渲染管线

JSON AST (QuroUiNode)
│
▼
┌─────────────────────────────┐
│ QuroUiRenderer.render(root) │
└─────────────────────────────┘
│
├─ 容器节点 → RenderColumn/RenderRow/RenderBox/RenderCard
│ │
│ └─ forEach child → 递归调用 renderChild()
│
└─ 叶子节点 → RenderText/RenderImage/RenderButton/RenderHtml/…
│
└─ stableId(prefix, json) → 用于 Compose Key

📐 密度自适应（360 dp 设计宽度）

@Composable
fun rememberDensityScale(): Float {
val config = LocalConfiguration.current
val designWidthDp = 360f
val actualWidthDp = config.screenWidthDp.toFloat()
return (actualWidthDp / designWidthDp).coerceIn(0.85f, 2.0f)
}

文本、间距、内边距、圆角、卡片宽度都按 densityScale 缩放；图标按矢量自

🛠 实战：构建一个待办清单

理论讲完，来点能直接跑的东西。下面用 quro-ui 构建一个完整的「待办清单」：顶部一个输入框，中间是 list 渲染的待办项（每项带 checkbox 勾选），底部一个「清空已完成」按钮。

下面是你的待办清单，试试勾选或新增：

```quro-ui
{
"type": "column",
"gap": 12,
"padding": 14,
"children": [
{
"type": "text",
"text": "📝 今日待办",
"weight": "bold",
"size": 18
},
{
"type": "row",
"gap": 8,
"children": [
{
"type": "text_input",
"placeholder": "输入新任务，回车添加",
"value": "{{input}}",
"onSubmit": {
"type": "callback",
"name": "todo_add",
"payload": { "text": "{{input}}" }
}
},
{
"type": "button",
"label": "添加",
"variant": "primary",
"action": {
"type": "callback",
"name": "todo_add",
"payload": { "text": "{{input}}" }
}
}
]
},
{
"type": "list",
"gap": 8,
"data": [
{ "id": "t1", "title": "写周报", "done": false },
{ "id": "t2", "title": "回复邮件", "done": true },
{ "id": "t3", "title": "预约会议室", "done": false }
],
"template": {
"type": "row",
"gap": 10,
"align": "spaceBetween",
"children": [
{
"type": "checkbox",
"label": "{{item.title}}",
"checked": "{{item.done}}",
"onChange": {
"type": "toggle",
"stateKey": "todo.{{item.id}}.done"
}
},
{
"type": "button",
"label": "删除",
"variant": "secondary",
"action": {
"type": "callback",
"name": "todo_remove",
"payload": { "id": "{{item.id}}" }
}
}
]
}
},
{
"type": "button",
"label": "🗑 清空已完成",
"variant": "danger",
"action": {
"type": "callback",
"name": "todo_clear_done",
"payload": {}
}
}
]
}
```

🧩 节点渲染效果拆解

⚡ 交互动作如何绑定

• callback（新增 / 删除 / 清空）：按钮或输入框的 action / onSubmit 里声明 { "type": "callback", "name": "todo_add", "payload": {…} }。点击后前端把 name + payload 回传给宿主，由业务层更新数据模型并重渲染。
• toggle（勾选完成）：checkbox 的 onChange 用 { "type": "toggle", "stateKey": "todo.{{item.id}}.done" }。它不经过业务回调，直接翻转 stateKey 指向的布尔状态，实现「本地即时勾选」——配合 {{item.done}} 回显，勾选后整行状态立刻同步。
• 占位符联动：{{item.id}} / {{item.title}} / {{item.done}} 在 list 内逐行求值，让每个 checkbox 和删除按钮都拿到自己那一行的数据，互不串扰。

💡 要点：callback 适合「需要宿主处理」的动作（增删、持久化），toggle 适合「纯本地状态翻转」（勾选、开关）。两者组合，就能在纯 JSON 里搭出可交互的完整界面。

适应不缩放。

🧩 节点类型完整清单 · 17+ 组件

📝 实战示例：AI 输出

下面是配置服务器的一键操作清单：

```quro-ui
{
"type": "list",
"padding": 12,
"gap": 8,
"data": [
{ "emoji": "🛠", "title": "安装 Nginx", "desc": "通过 apt/yum 安装最新稳定版" },
{ "emoji": "🔒", "title": "配置 HTTPS", "desc": "使用 Let's Encrypt 自动签发" },
{ "emoji": "📦", "title": "部署静态站点", "desc": "/var/www/html 权限设置" }
],
"template": {
"type": "row",
"gap": 12,
"children": [
{ "type": "text", "text": "{{item.emoji}}", "size": 20 },
{
"type": "column",
"children": [
{ "type": "text", "text": "{{item.title}}", "weight": "bold" },
{ "type": "text", "text": "{{item.desc}}", "size": 12, "color": "gray.10" }
]
}
]
}
}
```

渲染效果：每行 = 表情 + 加粗标题 + 灰色描述，自适应宽度。

⚡ 动作类型 · 8+ 种交互

🔁 占位符与数据流

🔧 工具支持 · 模型自检

🧰 ui_dsl_spec

// 模型调用：
{ "tool": "ui_dsl_spec", "args": { "section": "all" } }

// 返回：quro-ui 节点清单 + 示例 JSON + 注意事项

🧰 ui_validate

// 模型自检：把刚才输出的 quro-ui JSON 喂回工具，立即返回可解析性评分
{ "tool": "ui_validate", "args": { "dsl": "<JSON>" } }

// 返回： { "ok": true, "warnings": […], "fix_suggestions": […] }

✅ 典型用法：模型自检一轮后再发出，比直接发送错误 JSON 被前端报错更稳健。

🎨 主题与样式

🌑 调色板（QuroUiColor）

✏️ 图标（QuroUiIcons）

• 内置 Lucide 图标集（约 1000 个常用图标）
• camelCase → snake_case → 小写归一
• 未知图标回退 circle_help，绝不渲染空白方块

🧠 v1.0.82 必备输出设计 · 系统提示词

这一节是让「动态 UI」真正成为默认行为的关键。

### 动态 UI（quro-ui 原生组件 · 必备输出）

**何时用：** 始终默认使用。任何需要呈现「操作清单 / 选项 / 表单 /
播放器 / 浏览器 / 富媒体」的回答，都优先用 quro-ui 渲染，而不是
纯文本。即使只生成一张卡片也要用它。

**输出规范：**
1. 单条 quro-ui JSON 必须被 ```quro-ui … ```围栏包裹；
2. 复杂的可拆为多条 ```quro-ui 块；
3. 关键结论、解释、对话照常用正文；UI 只是更强的呈现通道。

**自检：** 发送前调用 ui_validate 工具。

🧭 在工具分类中的位置

🧠 ToolCapabilityDirectory.DYNAMIC_UI
├─ IntentMatcher: "原生交互界面 / 动态UI"
│ └─ 命中工具: [ui_dsl_spec, ui_validate]
├─ IntentMatcher: "卡片 / 列表 / 表单 / 播放器 / 浏览器界面"
│ └─ 命中工具: [ui_dsl_spec]
└─ 优先级: 5（高于普通 text/image）

QuroToolRouter.categorize() 已加入 DYNAMIC_UI 映射，早于 ui_* 规则，避免被通用 UI 工具误判。

🐞 8 轮 Bug 修复亮点

🎯 设计哲学

❓ 为什么选 Compose 原生而不是 WebView？

➡ 结论：可枚举的非媒体场景一律 Compose 原生；只有真正需要浏览器内核的（如打开任意 URL）才走 WebView 容器节点 browser。

❓ 为什么 JSON DSL 而不是 JSON Schema 或 Protobuf？

• JSON Schema 太啰嗦，模型不爱输出；结构校验可以靠 catalog 完成
• Protobuf / TypeScript 模型往往拼错大小写或忘了枚举值；JSON 字面量最稳
• YAML 缩进依赖坑惨过模型
• JSON 是当下 LLM 输出文本的最稳定格式（token 训练量最大）

🚀 未来扩展方向

• 🧩 可视化处理（render_vispro）：流程图、时序图、思维导图渲染器
• 🎞 Timeline / Carousel 节点：横向滑动 + 自动播放
• 🪟 visual_ask 增强：多选、可填空、附件上传
• 🧠 state.io 持久化：节点状态写入数据模型，跨消息保持
• 🌐 a2ui envelope 互通：与外部 a2ui 协议完全双向兼容
• 📱 桌面 / 折叠屏断点：除 360 dp 外，新增 ≥ 600 dp / ≥ 840 dp 的多断点布局

📚 参考示例 · 完整卡片输出

下面为你列出 3 款适合远程开发的笔记本，按性价比排序：

```quro-ui
{
"type": "card",
"padding": 14,
"gap": 10,
"background": "surface",
"radius": 14,
"children": [
{
"type": "row",
"align": "spaceBetween",
"children": [
{ "type": "text", "text": "🏆 性价比首选", "weight": "bold", "size": 16 },
{ "type": "badge", "text": "TOP1", "variant": "success" }
]
},
{
"type": "text",
"text": "MacBook Air M2 · 16 GB / 512 GB",
"size": 14
},
{
"type": "row",
"gap": 8,
"children": [
{
"type": "button",
"label": "查看配置",
"variant": "primary",
"action": { "type": "open_url", "url": "https://example.com/mac-air" }
},
{
"type": "button",
"label": "加入对比",
"variant": "secondary",
"action": { "type": "tool_call", "name": "add_to_compare", "args": { "id": "mac-air-m2" } }
}
]
}
]
}
```

如果你需要开发 Android 原生，建议再考虑内存升级到 24 GB 的型号。

🌟 动态 UI，让 AI 的回答「看得见、用得上」🌟

ZorvAI · v1.0.82 · 2026-09-05

如嵌套 `tabs`/`card`，子节点也能