anyui-template-authoring

AnyUI 模板与卡片设计专家规范

AnyUI 用于在 MioChat 聊天流中输出高保真、响应式且可直接交互的 HTML 卡片。前端通过 Shadow DOM 同文档渲染（样式完全隔离于主页面）。

---

一、核心设计哲学：前后端解耦与模板原生视觉掌控

1. 零轮次开销内置异步生图（无需调用单独的 draw 工具）

AnyUI 原生打通了后端生图服务。在调用 send_ui 时：

• 文生图模式：直接传入 prompt 或 imagePrompt，后端只负责创建任务并传递 taskId。初始状态下 imageUrl 保持为空，由 HTML 模板通过原生 CSS/DOM 呈现精美的骨架屏与极光流体动效；图片绘制完成后前端通过 WebSocket 直接将真实 URL 回填至 img.src 并平滑淡入！无需调用 draw 工具，前后端完全解耦。
• 静态图片模式：传入已有图片链接 imageUrl 或 imgurl，直接即时渲染。
• 图生图模式：同时传入 imageUrl（参考图）+ prompt（重绘提示词），自动进行图生图并在完成后替换。

2. 全局通用模板库（Global Templates）

系统内置全局共享模板目录 templates/global/，所有用户与智能体可直接免定义调用：

• gal_dialogue_card：Galgame / 视觉小说通用卡片（桌面端 480px 宽度约束，原生流体极光骨架屏，自适应 object-fit: contain 比例留白，支持章节标题、三行滚动对白、剧情分支选项、全屏画廊预览与异步生图）。

---

二、可用工具与模板语法

1. 三大工具

• send_ui(template?, html?, variables?, prompt?, imageUrl?)：
  • 优先使用：指定全局或已有模板 template: "gal_dialogue_card" + variables: JSON.stringify({...}) + 可选 prompt；
  • 也可传 html 直接发送自定义内联 HTML。
• define_ui_template(name, html, description?, schema?)：保存新模板到模板库；schema 接收标准 JSON Schema（如 {"type":"object","properties":{...},"required":[...]}），用于为每个字段定义类型、说明和必填约束，保存后 manage_ui_templates 的 list/get 均可查看标准 Schema 与字段规范。
• manage_ui_templates(action: 'list' | 'get' | 'delete', name?)：管理与查询可用模板列表；list 返回每个模板的名称、描述与标准 JSON Schema，get 返回完整正文与 Schema 详情。

2. 模板语法规范（支持 JSX 组件与经典 HTML 双模）

• JSX / JS 组件模式（推荐）：使用 export default function Card(props, html) 或 (props, html) => html\...`` 编写。
  • 支持完整的 JavaScript 动态逻辑（条件渲染 ${hasImage && html\...`}、动态数组循环 ${items.map(it => html`...`)}`、默认值兜底等）；
  • 内部通过 html 模板标签构建安全、自动转义的 HTML 结构。
• 经典 HTML 模式（向后兼容）：{{var}} 变量替换与 {{#each items}}...{{/each}} 循环。

---

三、Shadow DOM 交互 API（window.__mio）

API	参数	行为与使用场景
window.__mio.sendText(text)	string	填入输入框并在约 30ms 后自动提交（用于按钮/选项点击触发继续推进剧情）
window.__mio.setInput(text)	string	仅填入输入框并自动聚焦，等待用户继续编辑
window.__mio.previewImage(url)	string	全屏画廊遮罩预览图片（Teleport 到 body，脱离 Shadow DOM 局限）