a2ui-v0-8

name	a2ui-v0-8
description	使用 A2UI v0.8（以 renderers/lit/src/0.8 与 specification/0.8 为准）生成服务端 JSONL UI 消息，并实现客户端事件与 A2A 扩展回传。适用于把用户需求转成 A2UI 组件树+数据模型+渲染序列，以及处理 action/userAction 与后端接口调用的场景。

A2UI v0.8 统一技能

概览

提供 A2UI v0.8 的端到端规范与实操流程：UI 生成（surfaceUpdate/dataModelUpdate/beginRendering/deleteSurface）与客户端事件回传（action → userAction → A2A）。

工作流（必须遵循）

1. 确认 Catalog 与 surfaceId：默认标准 Catalog，所有组件 id 唯一。
2. 设计组件图：扁平组件列表 + children/child 组装树。
3. 写入数据模型：dataModelUpdate 填充 ValueMap，并用 path 绑定。
4. 触发渲染：发送 beginRendering 指定 root。
5. 交互回传：组件 action.context 绑定数据，客户端解析为 userAction。
6. 增量更新：结构变更 surfaceUpdate，数据变更 dataModelUpdate。

生成侧规则

• 每条消息只能有一个顶级键：beginRendering / surfaceUpdate / dataModelUpdate / deleteSurface。
• surfaceUpdate.components 中 component 只能有一个组件类型键。
• children 使用 explicitList 或 template（template 必须含 componentId 与 dataBinding）。
• dataModelUpdate.contents 只使用 ValueMap（valueString/valueNumber/valueBoolean/valueMap）。
• BoundValue 的 literal* 与 path 二选一；相对 path 以 dataContextPath 解析。

客户端事件规则

• userAction 必填：name、surfaceId、sourceComponentId、timestamp。
• action.context 必须解析成最终值（不可保留 path）。
• 发送 DataPart 时 mimeType 必须与服务端一致，规范为 application/json+a2ui。
• 每次 A2A 消息都携带 a2uiClientCapabilities（supportedCatalogIds）。

兼容性提示

• TextField 字段命名在 schema 与 renderer 存在差异：schema 常用 textFieldType，Lit v0.8 类型用 type。接入时必须做字段对齐或映射。
• Modal 的 entryPointChild 会被渲染器赋 slot="entry"，不要复用 slot 名称。

参考资料（按需加载）

• 协议与数据模型：references/protocol-v0-8.md
• 标准组件清单：references/standard-catalog-v0-8.md
• Schema 定位：references/schemas-v0-8.md
• JSONL 模板示例：references/examples-jsonl-v0-8.md
• 片段库：references/snippets-v0-8.md
• 客户端事件解析：references/client-events-v0-8.md
• A2A 扩展与能力协商：references/a2a-extension-v0-8.md
• 端到端流程：references/sample-client-flow.md
• 端到端请求模板：usage.md