@civilization/deepseek-genui 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1577 @@
1
+ # Agent GenUI Runtime:系统设计文档
2
+
3
+ - **文档类型**:技术设计 / System Design
4
+ - **版本**:1.0
5
+ - **状态**:Draft for implementation
6
+ - **适用范围**:面向 Agent 对话产品的声明式、可交互 GenUI Runtime
7
+ - **核心原则**:模型提出 UI 结构与内容;Runtime
8
+ 验证协议、管理状态与权限;前端使用受信任的组件和渲染器完成展示。
9
+
10
+ ------------------------------------------------------------------------
11
+
12
+ ## 1. 摘要
13
+
14
+ 本文定义一个可扩展的 Agent GenUI(Generative
15
+ UI)运行时。系统允许模型根据用户任务生成结构化 UI
16
+ 描述,再由客户端将描述映射为经过注册、验证和授权的 UI
17
+ 组件。系统支持信息展示、数据可视化、用户输入、决策比较、Agent
18
+ 任务状态、导航探索、产物交付、多媒体和专业可视化等 UI 类型。
19
+
20
+ 推荐主链路:
21
+
22
+ ``` text
23
+ 用户请求 / Agent 输出
24
+ |
25
+ v
26
+ 生成 JSON UI DSL
27
+ |
28
+ v
29
+ 解析 -> 版本识别 -> 规范化
30
+ |
31
+ v
32
+ 多层验证
33
+ - 结构 Schema
34
+ - 组件属性契约
35
+ - 语义与数据引用
36
+ - 安全 / 权限策略
37
+ |
38
+ +---- 可确定性修复 ----> 再验证
39
+ |
40
+ +---- 可由模型修复 ----> 有界修复请求 ----> 再验证
41
+ |
42
+ +---- 不可修复 / 超限 ----> 安全降级
43
+ |
44
+ v
45
+ 规范化 UI AST / 组件计划
46
+ |
47
+ v
48
+ Renderer Registry 分发
49
+ |
50
+ v
51
+ React / DOM / SVG / Canvas / 专用引擎
52
+ |
53
+ v
54
+ 渲染错误边界 + 本地交互 + 事件回传
55
+ ```
56
+
57
+ 推荐采用 **JSON DSL + Schema + Renderer Registry**
58
+ 作为第一版架构。不要把模型生成的任意 React、HTML、CSS 或 JavaScript
59
+ 直接执行在宿主应用中。UI 协议是稳定的产品接口,不是临时的代码生成格式。
60
+
61
+ ## 2. 目标与非目标
62
+
63
+ ### 2.1 目标
64
+
65
+ 1. 让模型可以根据任务选择和组合 UI,而不必生成任意前端代码。
66
+ 2. 支持统一的协议、校验、渲染、交互、错误恢复和观测。
67
+ 3. 通过 Renderer Registry 解耦 DSL 与底层 UI 框架、组件库和图形引擎。
68
+ 4. 支持常见的声明式组件,以及图表、流程图、代码编辑器、地图等领域专用渲染器。
69
+ 5. 将本地交互与 Agent 推理/工具执行区分开,避免每次点击都调用模型。
70
+ 6. 对非法结构、未知组件、无效数据、运行时崩溃和权限违规进行分级处理。
71
+ 7. 支持渐进式扩展、协议版本管理、兼容性测试和灰度发布。
72
+ 8. 控制模型 Token 消耗、组件复杂度、渲染性能与安全风险。
73
+
74
+ ### 2.2 非目标
75
+
76
+ 第一版不尝试:
77
+
78
+ - 允许模型直接执行任意 JavaScript、动态导入或任意网络请求。
79
+ - 用一套自研 Canvas 引擎替代所有现有 UI 技术。
80
+ - 为所有领域实现完整的专业编辑器。
81
+ - 将 UI 渲染器作为权限系统的唯一安全边界。
82
+ - 让模型自由决定可执行操作、授权范围或任意组件属性。
83
+ - 将每次本地控件交互都发送回模型。
84
+ - 把复杂业务状态仅保存在模型生成的 DSL 中。
85
+
86
+ ## 3. 设计原则
87
+
88
+ ### 3.1 模型负责表达,Runtime 负责执行
89
+
90
+ 模型可以选择 UI 类型、填写数据、组织布局并声明有限的交互意图。Runtime
91
+ 负责验证类型、限制资源、解析事件、校验权限并调用已注册的操作。
92
+
93
+ ### 3.2 先使用确定性逻辑,再请求模型修复
94
+
95
+ 可安全、无歧义地修复的问题应在本地修复,例如填充可选默认值、移除未知的非关键装饰属性或将未知展示组件降级为文本。涉及业务语义、数据推断或权限的问题不能猜测。
96
+
97
+ ### 3.3 局部失败优于整页失败
98
+
99
+ 单个图表、卡片或图形渲染失败时,应尽量隔离错误节点,保留其余有效内容。根节点结构错误或安全策略违规则可以拒绝整份
100
+ UI。
101
+
102
+ ### 3.4 UI 协议与底层实现解耦
103
+
104
+ DSL 描述语义组件,例如
105
+ `chart`、`table`、`form`、`diagram`,而不是绑定到某个 React
106
+ 组件名。底层可以替换 ECharts、Recharts、React Flow
107
+ 或其他引擎,而无需让模型学习新协议。
108
+
109
+ ### 3.5 默认最小化
110
+
111
+ 不需要 UI 时返回普通文本;只有当 UI
112
+ 能提高信息可读性、比较效率或交互完成率时才生成。避免把简单回答包装成复杂仪表盘。
113
+
114
+ ### 3.6 渐进增强
115
+
116
+ 优先保证文本和基础 DOM
117
+ 的可用性。高级图形引擎加载失败时,应有轻量替代视图或明确的不可用状态。
118
+
119
+ ------------------------------------------------------------------------
120
+
121
+ ## 4. 系统架构
122
+
123
+ ### 4.1 逻辑组件
124
+
125
+ 1. **UI Planner**:决定是否需要 UI、选择模式、组件组合和信息密度。
126
+ 2. **DSL Generator**:按协议输出 JSON UI 描述。
127
+ 3. **Parser**:解析 JSON,拒绝非法或超限输入。
128
+ 4. **Normalizer**:填充默认值、规范化字段、处理兼容版本。
129
+ 5. **Schema Validator**:检查根结构、节点结构和字段类型。
130
+ 6. **Component Contract Validator**:验证具体组件的
131
+ props、数据形状和能力声明。
132
+ 7. **Semantic Validator**:检查数据引用、图表系列、节点
133
+ ID、交互目标和组件组合约束。
134
+ 8. **Policy
135
+ Validator**:检查允许的组件、动作、URL、资源大小、敏感操作和授权上下文。
136
+ 9. **Repair Coordinator**:决定自动修复、模型修复、局部降级或拒绝。
137
+ 10. **UI AST / Render Plan**:保存规范化且通过验证的组件树。若外部 DSL
138
+ 已与内部模型一致,可复用同一结构,不强制额外复制。
139
+ 11. **Renderer Registry**:按语义类型和能力选择渲染器。
140
+ 12. **Interaction Runtime**:维护本地状态、校验事件并路由到应用动作或
141
+ Agent。
142
+ 13. **Error Boundary**:隔离单个组件的渲染错误。
143
+ 14. **Telemetry**:记录生成、校验、修复、渲染、事件处理的耗时与错误类型。
144
+
145
+ ### 4.2 数据流
146
+
147
+ ``` mermaid
148
+ flowchart TD
149
+ A[Agent / Model Output] --> B[Parse JSON]
150
+ B --> C[Normalize and Migrate]
151
+ C --> D[Structural Schema Validation]
152
+ D --> E[Component Contract Validation]
153
+ E --> F[Semantic Validation]
154
+ F --> G[Security and Policy Validation]
155
+ G -->|Valid| H[Normalized UI AST]
156
+ D -->|Repairable| R[Repair Coordinator]
157
+ E -->|Repairable| R
158
+ F -->|Repairable| R
159
+ R -->|Deterministic Repair| C
160
+ R -->|Bounded Model Repair| M[Model Repair Request]
161
+ M --> B
162
+ R -->|Cannot Repair| X[Fallback / Text Mode]
163
+ G -->|Security Violation| Y[Reject Unsafe Action]
164
+ H --> I[Renderer Registry]
165
+ I --> J[Component Renderers]
166
+ J --> K[Error Boundary]
167
+ K --> L[Rendered UI]
168
+ L --> N[Local UI State]
169
+ L --> O[Interaction Event]
170
+ O --> P[Event Validator / Router]
171
+ P -->|Local State| N
172
+ P -->|Authorized App Action| Q[Application Service]
173
+ P -->|Needs Reasoning| A
174
+ ```
175
+
176
+ ### 4.3 推荐的进程边界
177
+
178
+ - DSL
179
+ 解析和校验可以在服务端、客户端或两端执行;客户端必须重新执行关键校验,不能盲信服务端输出。
180
+ - UI 组件运行在应用的受信任前端代码中。
181
+ - 专业引擎可按需懒加载,但必须有超时、加载失败和备用展示。
182
+ - 如果未来支持用户自定义代码预览或执行,应放入独立沙箱;不得复用普通
183
+ DSL Renderer 的权限。
184
+ - 业务动作必须由应用服务端再次鉴权,不能以"按钮已显示"作为授权凭证。
185
+
186
+ ------------------------------------------------------------------------
187
+
188
+ ## 5. 支持的 UI 类型与底层渲染技术
189
+
190
+ 本节是建议支持的产品能力目录。分类按任务目的组织,类别可以交叉;"支持"不意味着第一版全部实现。实施阶段见第
191
+ 15 节。
192
+
193
+ ### 5.1 信息展示型
194
+
195
+ -----------------------------------------------------------------------------------------
196
+ UI / Pattern 用途 推荐底层技术 关键能力
197
+ ----------------- ---------------------- ----------------- ------------------------------
198
+ Text / Paragraph 普通文本、说明 HTML / React 段落、换行、可读性
199
+
200
+ Markdown 技术回答、结构化说明 Markdown parser + 标题、列表、引用、代码
201
+ 安全 HTML
202
+ renderer
203
+
204
+ Heading / Divider 信息分层 DOM / CSS 层级与分隔
205
+
206
+ Info Card 对象摘要、插件介绍 React / Vue + DOM 标题、描述、元数据、操作入口
207
+
208
+ Metric Card 单个关键指标 DOM / SVG 数值、单位、变化、迷你趋势
209
+ sparkline
210
+
211
+ Badge / Status 状态和分类 DOM / CSS 状态色、标签、文本替代
212
+
213
+ Quote / Callout 引用、警告、提示 DOM / CSS 语义化强调
214
+
215
+ Accordion / 长内容折叠 原生 `details` 或 展开、折叠、键盘操作
216
+ Disclosure React 组件
217
+
218
+ Timeline 事件时间线 DOM / SVG 时间、状态、事件详情
219
+
220
+ Step List 有序步骤 DOM 编号、完成状态、说明
221
+
222
+ Tooltip / Popover 辅助信息 DOM + 浮层定位库 焦点管理、逃逸关闭
223
+ -----------------------------------------------------------------------------------------
224
+
225
+ ### 5.2 数据展示型
226
+
227
+ -----------------------------------------------------------------------------------------------------
228
+ UI / Pattern 推荐底层技术 适用场景 / 注意点
229
+ ----------------------- -------------------------------------- --------------------------------------
230
+ Basic Table HTML `<table>` 中小规模、强调语义和可访问性
231
+
232
+ Data Grid TanStack Table + 排序、筛选、分页、列配置、行展开
233
+ DOM;大数据量配虚拟列表
234
+
235
+ Bar / Line / Area Chart ECharts、Vega-Lite、Plotly、Recharts 类别比较、趋势、区间变化
236
+ 之一
237
+
238
+ Pie / Donut Chart 同一图表引擎 少量类别的构成;类别过多时改用条形图
239
+
240
+ Scatter / Bubble Chart ECharts、Vega-Lite、Plotly 分布、相关性、多维数据
241
+
242
+ Histogram / Box Plot ECharts、Vega-Lite、Plotly 统计分布;需验证输入数据
243
+
244
+ Heatmap ECharts、D3 或专用矩阵视图 密集二维数据
245
+
246
+ KPI Dashboard DOM 布局 + 指标卡 + 图表 页面级组合,不是基础组件
247
+
248
+ Log / Event Table Data Grid / 虚拟列表 大量日志、筛选、时间排序
249
+
250
+ Progress / Gauge DOM / SVG / 图表引擎 进度、占比、阈值;需避免误导性刻度
251
+ -----------------------------------------------------------------------------------------------------
252
+
253
+ **图表引擎选型建议:**
254
+
255
+ - 若优先需要完整交互和丰富图表,考虑 ECharts。
256
+ - 若优先需要声明式可视化语法和数据编码约束,考虑 Vega-Lite。
257
+ - 若需要科研绘图、复杂交互和较广图形能力,评估 Plotly。
258
+ - 若项目已采用 React 且偏好轻量组件式 API,可评估 Recharts。
259
+ - 第一版应尽量只选一个主图表引擎,避免同一图表类型出现多套重复实现。
260
+ - 无论使用哪种引擎,都要在 DSL
261
+ 与引擎配置之间设置白名单映射,不直接接受任意引擎配置对象。
262
+
263
+ ### 5.3 用户输入型
264
+
265
+ -----------------------------------------------------------------------------
266
+ UI / Pattern 推荐底层技术 关键要求
267
+ ----------------------- ------------------------ ----------------------------
268
+ Text Input HTML input / React 长度、类型、必填、错误提示
269
+
270
+ Textarea HTML textarea 字数限制、自动伸缩
271
+
272
+ Number Input / Stepper HTML input + 自定义控件 范围、精度、上下限
273
+
274
+ Search Input DOM + 防抖逻辑 搜索事件、清空、加载状态
275
+
276
+ Radio Group 原生控件或成熟组件库 单选语义、键盘操作
277
+
278
+ Checkbox / Multi-select 原生控件或组件库 多选、选择状态
279
+
280
+ Select / Combobox 原生 select 大选项集、搜索、键盘操作
281
+ 或可访问组件库
282
+
283
+ Segmented Control DOM + Button 互斥选项
284
+
285
+ Slider / Range Slider HTML range 或成熟组件库 最小值、最大值、步长
286
+
287
+ Date / Time Picker 原生控件或成熟日期库 时区、范围、格式校验
288
+
289
+ Dynamic Form React Hook Form 字段校验、默认值、提交状态
290
+ 等表单状态库 + Schema
291
+ validator
292
+
293
+ File Picker / Dropzone 浏览器 File API + MIME、大小、上传权限、扫描
294
+ 应用上传服务
295
+
296
+ JSON / Code Input Monaco / 只读/编辑模式、大小限制
297
+ CodeMirror(按需加载)
298
+ -----------------------------------------------------------------------------
299
+
300
+ 表单协议应把字段定义与布局分开,避免把业务数据和 UI
301
+ 配置混为一谈。敏感字段、文件内容和用户输入不应被自动发送给模型,必须由数据流策略明确决定。
302
+
303
+ ### 5.4 决策与比较型
304
+
305
+ --------------------------------------------------------------------------
306
+ UI / Pattern 推荐底层技术 关键能力
307
+ ----------------------- ----------------------- --------------------------
308
+ Comparison Table HTML Table / Data Grid 同一维度横向比较
309
+
310
+ Option Card Group DOM / React 选择方案、展示关键差异
311
+
312
+ Pros / Cons DOM / Markdown 分组说明、可读性
313
+
314
+ Scoring Matrix Table + 数值输入 / SVG 权重、评分依据、总分计算
315
+ 图表
316
+
317
+ Recommendation Panel DOM / Card 推荐理由、限制、备选方案
318
+
319
+ Decision Tree SVG / React Flow 分支、路径、节点说明
320
+
321
+ Budget Allocation 表单控件 + SVG / 调整预算、查看结果
322
+ 图表引擎
323
+
324
+ Trade-off Chart Scatter / Bar Chart 可解释的多维权衡
325
+ --------------------------------------------------------------------------
326
+
327
+ 推荐结果必须区分事实、用户提供的偏好、模型推断和主观评分。不能将模型估算的数字呈现为经验证的客观指标。
328
+
329
+ ### 5.5 流程与 Agent 任务型
330
+
331
+ --------------------------------------------------------------------------------
332
+ UI / Pattern 推荐底层技术 关键能力
333
+ ----------------------- ----------------------- --------------------------------
334
+ Task Checklist / Plan DOM / React 待执行、进行中、完成、失败
335
+
336
+ Progress Bar DOM / CSS 确定进度与不确定进度分开
337
+
338
+ Stepper / Wizard DOM / React 多阶段输入与状态恢复
339
+
340
+ Tool Call Timeline DOM / Virtual List 工具名称、状态、耗时、结果摘要
341
+
342
+ Execution Log 虚拟列表 + 可展开详情 大量输出按需查看
343
+
344
+ Approval Panel DOM + 服务端授权接口 动作、影响范围、批准/拒绝
345
+
346
+ Diff Viewer Monaco Diff / 专用 Diff 变更审查、接受/拒绝
347
+ renderer
348
+
349
+ Checkpoint / Undo Panel DOM + 后端任务状态 API 检查点、撤销、恢复
350
+
351
+ Retry / Recovery DOM / Button 重试、跳过、重新配置
352
+ Controls
353
+
354
+ Agent Handoff / DOM + 运行时状态机 暂停、人工接管、继续执行
355
+ Takeover
356
+
357
+ State Machine View SVG / React Flow 状态和转换关系
358
+ --------------------------------------------------------------------------------
359
+
360
+ 注意:计划、日志、审批和 Diff
361
+ 是不同语义。计划描述目标,日志记录已发生事实,审批负责授权,Diff
362
+ 负责展示变更,回滚依赖真实的恢复能力,不能只做成视觉按钮。
363
+
364
+ ### 5.6 导航与探索型
365
+
366
+ ----------------------------------------------------------------------------
367
+ UI / Pattern 推荐底层技术 关键能力
368
+ ----------------------- ----------------------- ----------------------------
369
+ Card Grid / Gallery DOM / CSS Grid 对象浏览
370
+
371
+ Carousel DOM + 滚动 / 有限数量内容浏览
372
+ 成熟轮播组件
373
+
374
+ Tabs DOM / Accessible tabs 同一内容区切换
375
+ component
376
+
377
+ Filters / Facets DOM / Form controls 过滤结果
378
+
379
+ Pagination DOM 大数据分页
380
+
381
+ Virtual List TanStack Virtual 等 大列表性能
382
+
383
+ Tree View DOM / Virtual Tree 层级展开与选择
384
+
385
+ Search Results DOM / Data Grid / Card 摘要、排序、筛选
386
+ List
387
+
388
+ Breadcrumbs DOM 层级导航
389
+
390
+ Command Palette DOM + 键盘事件 快速操作与搜索
391
+
392
+ Graph Explorer Cytoscape.js / D3 / 关系探索、节点聚焦
393
+ React Flow
394
+
395
+ Map / Route MapLibre GL JS 地理坐标、图层、路线、标记
396
+ 或合适的地图 SDK
397
+ ----------------------------------------------------------------------------
398
+
399
+ ### 5.7 产物与操作型
400
+
401
+ ---------------------------------------------------------------------------
402
+ UI / Pattern 推荐底层技术 关键能力
403
+ ----------------------- ----------------------- ---------------------------
404
+ Code Block 安全 Markdown renderer 复制、行号、语言标识
405
+ / Shiki 等高亮器
406
+
407
+ Code Viewer Monaco / CodeMirror 大文件、跳转、搜索
408
+ 或轻量高亮器
409
+
410
+ Code Editor Monaco / CodeMirror 编辑、校验、只读/可写权限
411
+
412
+ Diff View Monaco Diff / diff 行级差异
413
+ renderer
414
+
415
+ Document Preview Markdown / HTML / PDF 预览、目录、分页
416
+ viewer
417
+
418
+ Artifact Card DOM / React 文件名、类型、大小、状态
419
+
420
+ Download / Export 应用服务 API 访问控制、短期链接、审计
421
+ Action
422
+
423
+ Editable Artifact 受控编辑器 + 保存 API 草稿、版本、冲突处理
424
+
425
+ SQL / Query Result Code Editor + Data Grid 只读/执行权限、结果表
426
+
427
+ Generated Diagram Mermaid 或专用图形引擎 预览、错误定位、导出
428
+ ---------------------------------------------------------------------------
429
+
430
+ 文件卡片只展示资源信息,不应直接拼接不可信
431
+ URL。下载和打开必须经过应用路由及授权检查。
432
+
433
+ ### 5.8 多媒体与空间型
434
+
435
+ UI / Pattern 推荐底层技术 关键能力
436
+ ------------------ ------------------------------ ----------------------------------
437
+ Image HTML `<img>` 尺寸约束、替代文本、加载失败状态
438
+ Image Gallery DOM / CSS Grid / Carousel 缩略图、放大、切换
439
+ Image Annotation SVG overlay / Canvas 区域框选、标注、坐标映射
440
+ Audio Player HTML `<audio>` + 自定义控件 播放、暂停、时间轴
441
+ Video Player HTML `<video>` 或专用播放器 字幕、章节、播放状态
442
+ Transcript DOM / Virtual List 时间戳、片段跳转
443
+ Map / Route 地图引擎 标记、路线、图层
444
+ 2D Canvas Canvas / SVG 自由绘制或大量图元
445
+ 3D Scene Three.js / React Three Fiber 相机、材质、空间交互
446
+ Spatial Layout SVG / Canvas / WebGL 位置、连接、缩放与选择
447
+
448
+ ### 5.9 专业可视化型
449
+
450
+ ---------------------------------------------------------------------------
451
+ UI / Pattern 推荐底层技术 关键能力
452
+ ----------------------- -------------------------- ------------------------
453
+ Flowchart Mermaid(静态/声明式)或 节点、边、布局
454
+ React Flow(交互式)
455
+
456
+ Architecture Diagram SVG / React Flow / Mermaid 服务、依赖、数据流
457
+
458
+ Sequence Diagram Mermaid 或专用时序图引擎 参与者、消息、时序
459
+
460
+ ER Diagram SVG / React Flow / 专用 ER 表、字段、关系
461
+ renderer
462
+
463
+ Dependency Graph Cytoscape.js / D3 / React 关系、路径、局部展开
464
+ Flow
465
+
466
+ Knowledge Graph Cytoscape.js / D3 / WebGL 节点关系、筛选、聚焦
467
+ 方案
468
+
469
+ Math Formula KaTeX / MathJax 公式排版
470
+
471
+ Function Plot SVG / Canvas / Plotly 函数曲线、参数变化
472
+
473
+ Geometry Visualization SVG / Canvas / Three.js 点、线、面、交互
474
+
475
+ UML / State Diagram Mermaid / 专用图形引擎 类图、状态图、时序图
476
+
477
+ SQL Explain Plan Tree / Graph / Data Grid 计划节点、耗时、代价
478
+
479
+ Design Canvas SVG / Canvas / WebGL 拖动、缩放、选择、编辑
480
+ ---------------------------------------------------------------------------
481
+
482
+ ### 5.10 基础交互控件
483
+
484
+ 以下不是独立业务 UI 类别,但属于组件库的基础能力:
485
+
486
+ - Button、Icon Button、Link。
487
+ - Checkbox、Radio、Switch。
488
+ - Input、Textarea、Select、Combobox。
489
+ - Slider、Date Picker、Time Picker。
490
+ - Tabs、Accordion、Popover、Tooltip。
491
+ - Dialog、Drawer、Toast、Inline Alert。
492
+ - Loading Indicator、Skeleton、Empty State。
493
+ - Error State、Retry Control、Permission Denied State。
494
+ - Copy、Open、Download、Export 等受控动作。
495
+
496
+ ### 5.11 推荐的首发技术栈
497
+
498
+ 建议不要一次性引入所有表格、图表、图形和编辑器库。第一版可选:
499
+
500
+ - **宿主 UI**:React + TypeScript(若现有产品已使用 Vue,则不必为了
501
+ GenUI 迁移)。
502
+ - **协议与校验**:JSON Schema + Ajv 或同类验证器;TypeScript
503
+ 类型用于开发期,不代替运行时校验。
504
+ - **基础组件**:项目已有组件库或一套一致的 accessible primitives。
505
+ - **图表**:选择 ECharts 或 Vega-Lite 作为主引擎。
506
+ - **流程图**:Mermaid 用于简单声明式图;React Flow
507
+ 用于需要交互编辑的节点图。
508
+ - **代码**:轻量只读高亮器优先;确有编辑需求时再加载 Monaco /
509
+ CodeMirror。
510
+ - **Markdown**:使用安全解析器,禁用不需要的原始 HTML 和危险 URL。
511
+ - **虚拟列表**:只有数据规模需要时才引入。
512
+ - **地图 / 3D**:按产品需求懒加载,不进入基础 bundle。
513
+
514
+ ------------------------------------------------------------------------
515
+
516
+ ## 6. UI DSL 协议
517
+
518
+ ### 6.1 协议设计要求
519
+
520
+ DSL 应当:
521
+
522
+ 1. 是纯数据格式,不包含可执行代码。
523
+ 2. 有显式版本字段。
524
+ 3. 使用稳定的语义组件类型,而非框架组件名。
525
+ 4. 将组件属性、布局、数据、交互动作分离。
526
+ 5. 允许未知的非关键字段被安全忽略,但未知组件类型必须有明确策略。
527
+ 6. 限制深度、节点数量、字符串长度、数据集大小和资源引用。
528
+ 7. 支持向后兼容和迁移。
529
+ 8. 能够通过 Schema、语义校验和安全策略分别验证。
530
+
531
+ ### 6.2 顶层结构
532
+
533
+ 建议第一版使用如下结构:
534
+
535
+ ``` json
536
+ {
537
+ "protocol": "agent-genui",
538
+ "version": "1.0",
539
+ "id": "ui_01",
540
+ "title": "Kafka 请求统计",
541
+ "layout": {
542
+ "type": "stack",
543
+ "gap": "md"
544
+ },
545
+ "data": {
546
+ "requestStats": {
547
+ "columns": ["time", "requests"],
548
+ "rows": [
549
+ ["10:00", 120],
550
+ ["10:05", 156],
551
+ ["10:10", 143]
552
+ ]
553
+ }
554
+ },
555
+ "children": [
556
+ {
557
+ "id": "requests-chart",
558
+ "type": "chart",
559
+ "version": "1",
560
+ "props": {
561
+ "chartType": "line",
562
+ "title": "请求趋势",
563
+ "dataset": "requestStats",
564
+ "xField": "time",
565
+ "series": [
566
+ {
567
+ "field": "requests",
568
+ "label": "请求数"
569
+ }
570
+ ]
571
+ }
572
+ }
573
+ ]
574
+ }
575
+ ```
576
+
577
+ 说明:
578
+
579
+ - `protocol`:协议名称。
580
+ - `version`:DSL 主版本。
581
+ - `id`:一次 UI 实例的稳定标识。
582
+ - `layout`:根布局。
583
+ - `data`:受控数据集,或在后续版本中改用有权限的数据引用。
584
+ - `children`:语义组件树。
585
+ - `type`:组件语义类型。
586
+ - `version`:组件契约版本。
587
+ - `props`:经过该组件 Schema 验证的属性。
588
+
589
+ 示例中的 `data`
590
+ 只适用于小型数据集。大数据集、敏感数据和远程资源应使用服务端授权的数据引用,而不是把全部数据嵌入
591
+ DSL。
592
+
593
+ ### 6.3 布局协议
594
+
595
+ 初始布局类型建议保持有限:
596
+
597
+ - `stack`:纵向堆叠。
598
+ - `row`:横向排列。
599
+ - `grid`:网格布局。
600
+ - `split`:两区域分栏。
601
+ - `tabs`:标签页内容。
602
+ - `panel`:带标题的分区。
603
+
604
+ 不建议第一版让模型任意指定
605
+ CSS、绝对定位或任意嵌套布局。布局系统应根据容器宽度自动适配;不支持的布局应规范化或降级。
606
+
607
+ ### 6.4 组件示例
608
+
609
+ #### 信息卡
610
+
611
+ ``` json
612
+ {
613
+ "id": "plugin-card",
614
+ "type": "card",
615
+ "version": "1",
616
+ "props": {
617
+ "title": "日志分析",
618
+ "description": "按时间和级别检索日志",
619
+ "tone": "neutral"
620
+ }
621
+ }
622
+ ```
623
+
624
+ #### 表格
625
+
626
+ ``` json
627
+ {
628
+ "id": "error-table",
629
+ "type": "table",
630
+ "version": "1",
631
+ "props": {
632
+ "columns": [
633
+ {"key": "time", "label": "时间"},
634
+ {"key": "level", "label": "级别"},
635
+ {"key": "message", "label": "消息"}
636
+ ],
637
+ "rows": [
638
+ {"time": "10:01", "level": "ERROR", "message": "Connection timeout"}
639
+ ],
640
+ "pageSize": 20
641
+ }
642
+ }
643
+ ```
644
+
645
+ #### 表单
646
+
647
+ ``` json
648
+ {
649
+ "id": "search-form",
650
+ "type": "form",
651
+ "version": "1",
652
+ "props": {
653
+ "title": "查询日志",
654
+ "fields": [
655
+ {
656
+ "name": "keyword",
657
+ "type": "text",
658
+ "label": "关键词",
659
+ "required": true,
660
+ "maxLength": 100
661
+ },
662
+ {
663
+ "name": "level",
664
+ "type": "select",
665
+ "label": "级别",
666
+ "options": [
667
+ {"label": "错误", "value": "error"},
668
+ {"label": "警告", "value": "warn"}
669
+ ]
670
+ }
671
+ ],
672
+ "submitAction": "logs.search"
673
+ }
674
+ }
675
+ ```
676
+
677
+ `submitAction` 必须指向运行时注册的动作 ID,不能直接传函数或任意 URL。
678
+
679
+ #### 方案比较
680
+
681
+ ``` json
682
+ {
683
+ "id": "framework-comparison",
684
+ "type": "comparison",
685
+ "version": "1",
686
+ "props": {
687
+ "options": [
688
+ {"id": "a", "label": "方案 A"},
689
+ {"id": "b", "label": "方案 B"}
690
+ ],
691
+ "criteria": [
692
+ {
693
+ "key": "cost",
694
+ "label": "成本",
695
+ "values": {"a": "低", "b": "中"}
696
+ },
697
+ {
698
+ "key": "complexity",
699
+ "label": "复杂度",
700
+ "values": {"a": "中", "b": "低"}
701
+ }
702
+ ],
703
+ "recommendedOptionId": "a",
704
+ "recommendationReason": "适合当前的低维护成本要求"
705
+ }
706
+ }
707
+ ```
708
+
709
+ #### Agent 任务计划
710
+
711
+ ``` json
712
+ {
713
+ "id": "task-plan",
714
+ "type": "taskPlan",
715
+ "version": "1",
716
+ "props": {
717
+ "items": [
718
+ {"id": "inspect", "label": "检查配置", "status": "completed"},
719
+ {"id": "validate", "label": "验证参数", "status": "running"},
720
+ {"id": "execute", "label": "执行任务", "status": "pending"}
721
+ ]
722
+ }
723
+ }
724
+ ```
725
+
726
+ 执行状态应来自 Agent Runtime 的可信任务状态;模型生成的静态 UI
727
+ 不应伪造"已经完成"的系统操作。
728
+
729
+ #### 流程图
730
+
731
+ ``` json
732
+ {
733
+ "id": "pipeline",
734
+ "type": "diagram",
735
+ "version": "1",
736
+ "props": {
737
+ "diagramType": "flowchart",
738
+ "nodes": [
739
+ {"id": "input", "label": "输入"},
740
+ {"id": "validate", "label": "校验"},
741
+ {"id": "render", "label": "渲染"}
742
+ ],
743
+ "edges": [
744
+ {"source": "input", "target": "validate"},
745
+ {"source": "validate", "target": "render"}
746
+ ]
747
+ }
748
+ }
749
+ ```
750
+
751
+ 推荐由 Renderer
752
+ 将受控节点数据转换成图形引擎所需配置,而不是默认允许模型输出任意 Mermaid
753
+ 脚本或任意图形引擎配置。
754
+
755
+ ### 6.5 JSON Schema 示例
756
+
757
+ 下面是简化示例,用于说明协议边界。生产环境应为每个组件建立独立
758
+ Schema,并补充节点深度、总节点数和资源大小限制。
759
+
760
+ ``` json
761
+ {
762
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
763
+ "type": "object",
764
+ "required": ["protocol", "version", "id", "children"],
765
+ "properties": {
766
+ "protocol": {"const": "agent-genui"},
767
+ "version": {"type": "string", "const": "1.0"},
768
+ "id": {"type": "string", "minLength": 1, "maxLength": 128},
769
+ "title": {"type": "string", "maxLength": 200},
770
+ "layout": {
771
+ "type": "object",
772
+ "properties": {
773
+ "type": {
774
+ "enum": ["stack", "row", "grid", "split", "tabs", "panel"]
775
+ },
776
+ "gap": {"enum": ["none", "sm", "md", "lg"]}
777
+ },
778
+ "required": ["type"],
779
+ "additionalProperties": false
780
+ },
781
+ "children": {
782
+ "type": "array",
783
+ "maxItems": 50,
784
+ "items": {"$ref": "#/$defs/node"}
785
+ }
786
+ },
787
+ "additionalProperties": false,
788
+ "$defs": {
789
+ "node": {
790
+ "type": "object",
791
+ "required": ["id", "type", "version", "props"],
792
+ "properties": {
793
+ "id": {"type": "string", "minLength": 1, "maxLength": 128},
794
+ "type": {
795
+ "enum": [
796
+ "text", "card", "table", "chart", "form",
797
+ "comparison", "taskPlan", "diagram", "code", "image"
798
+ ]
799
+ },
800
+ "version": {"type": "string", "maxLength": 32},
801
+ "props": {"type": "object"}
802
+ },
803
+ "additionalProperties": false
804
+ }
805
+ }
806
+ }
807
+ ```
808
+
809
+ 注意:通用 Schema 只负责外层结构。`props` 必须按 `type + version`
810
+ 分发到对应的组件 Schema,不能因为它是对象就默认合法。
811
+
812
+ ### 6.6 数据引用设计
813
+
814
+ 数据规模较小时可以内嵌数据;复杂场景建议使用:
815
+
816
+ ``` json
817
+ {
818
+ "datasetRef": {
819
+ "id": "dataset_123",
820
+ "schemaVersion": "1",
821
+ "scope": "current-task"
822
+ }
823
+ }
824
+ ```
825
+
826
+ 规则:
827
+
828
+ - 引用由服务端或应用数据层签发。
829
+ - 引用必须绑定当前用户、会话或任务权限。
830
+ - 客户端不能通过修改 ID 访问未授权数据。
831
+ - 数据集大小、行数、列数、字符串长度和敏感字段需要限制。
832
+ - 数据源不存在时,显示可恢复的数据不可用状态,而不是崩溃。
833
+
834
+ ------------------------------------------------------------------------
835
+
836
+ ## 7. 解析、规范化与多层验证
837
+
838
+ ### 7.1 验证层次
839
+
840
+ **第 1 层:输入限制与 JSON 解析**
841
+
842
+ - 限制输入字节数。
843
+ - 拒绝无效 JSON、截断 JSON 和不支持的协议。
844
+ - 限制字符串长度、嵌套深度和数组大小。
845
+ - 防止超大输入导致 CPU 或内存耗尽。
846
+
847
+ **第 2 层:根结构 Schema**
848
+
849
+ - 必填字段。
850
+ - 字段类型。
851
+ - 协议版本。
852
+ - 允许的根布局。
853
+ - 节点数量上限。
854
+
855
+ **第 3 层:组件契约**
856
+
857
+ - 组件类型是否注册。
858
+ - 组件版本是否支持。
859
+ - `props` 是否符合组件专用 Schema。
860
+ - 枚举值、数值范围和默认值是否有效。
861
+
862
+ **第 4 层:语义验证**
863
+
864
+ - `datasetRef` 是否存在且授权。
865
+ - 图表字段是否存在且类型兼容。
866
+ - 图形节点 ID 是否唯一。
867
+ - 边是否引用存在的节点。
868
+ - 表单字段名称是否唯一。
869
+ - 提交动作是否注册。
870
+ - 组件组合是否满足布局约束。
871
+
872
+ **第 5 层:安全与权限策略**
873
+
874
+ - 禁止任意代码执行。
875
+ - 拒绝危险协议和不可信 URL。
876
+ - 限制资源加载来源。
877
+ - 对动作 ID 做 allowlist 校验。
878
+ - 验证动作参数和用户权限。
879
+ - 限制组件数量、计算量和媒体资源。
880
+ - 避免通过错误信息泄漏秘密或内部堆栈。
881
+
882
+ **第 6 层:运行时检查**
883
+
884
+ - 渲染器是否加载成功。
885
+ - 数据是否在渲染前后仍然有效。
886
+ - 交互事件是否符合组件契约。
887
+ - 异步加载是否超时。
888
+ - 组件是否出现异常或资源泄漏。
889
+
890
+ ### 7.2 规范化规则
891
+
892
+ 可以自动处理的规则:
893
+
894
+ - 补齐文档规定的可选默认值。
895
+ - 统一枚举大小写或旧版本别名(仅在协议明确允许时)。
896
+ - 将旧协议版本迁移到当前内部表示。
897
+ - 为缺失但可安全生成的稳定节点 ID 分配 ID。
898
+ - 删除明确标记为非关键的未知装饰字段。
899
+ - 对超出显示精度的数值按组件规范格式化。
900
+
901
+ 不能自动猜测的情况:
902
+
903
+ - 缺失的业务数据。
904
+ - 不明确的单位或时区。
905
+ - 未知的操作权限。
906
+ - 无法判断的图表字段映射。
907
+ - 可能改变业务语义的字段。
908
+ - 用户未授权的动作。
909
+
910
+ ### 7.3 组件注册契约
911
+
912
+ 建议为每个组件注册:
913
+
914
+ ``` ts
915
+ type ValidationIssue = {
916
+ path: string;
917
+ code: string;
918
+ message: string;
919
+ repairable: boolean;
920
+ };
921
+
922
+ type ValidationResult =
923
+ | { valid: true }
924
+ | { valid: false; issues: ValidationIssue[] };
925
+
926
+ type ComponentDefinition = {
927
+ type: string;
928
+ version: string;
929
+ schema: unknown;
930
+ validateSemantics?: (
931
+ props: unknown,
932
+ context: ValidationContext
933
+ ) => ValidationResult;
934
+ fallbackType?: string;
935
+ capabilities: string[];
936
+ maxPayloadBytes?: number;
937
+ };
938
+ ```
939
+
940
+ 示例仅表达接口意图,实际 TypeScript 类型应根据具体校验库、React
941
+ 版本和运行时上下文细化。
942
+
943
+ ------------------------------------------------------------------------
944
+
945
+ ## 8. 修复、重试与异常兜底
946
+
947
+ ### 8.1 错误分类
948
+
949
+ 错误 默认动作 是否调用模型
950
+ --------------------- ----------------------------------- ------------------
951
+ JSON 语法错误 发送有限修复请求;超限后降级 可以
952
+ Schema 不通过 返回精确路径和约束 可以
953
+ 未知组件类型 映射到通用文本/卡片或跳过可选节点 通常不需要
954
+ 可选属性缺失 填默认值 不需要
955
+ 属性语义不合法 确定性修复或模型修复 视情况
956
+ 数据引用不存在 重新绑定、请求数据或显示空状态 视情况
957
+ 图表数据类型不兼容 转换仅限无歧义场景,否则降级 视情况
958
+ Renderer 加载失败 备用 Renderer / 简化视图 不需要
959
+ 单个节点渲染异常 隔离节点,其他节点继续渲染 不需要
960
+ 根节点结构不可恢复 返回纯文本或通用错误视图 可选
961
+ 权限违规 拒绝操作并记录安全事件 不可通过重试绕过
962
+ 模型超时 / 输出截断 有界重试,最终返回文本 可以
963
+ 资源超限 截断、分页或拒绝超限内容 通常不需要
964
+
965
+ ### 8.2 推荐恢复顺序
966
+
967
+ ``` text
968
+ 1. 解析失败
969
+ -> 只允许有限的格式修复
970
+ -> 仍失败则安全降级
971
+
972
+ 2. Schema / 组件契约失败
973
+ -> 尝试确定性修复
974
+ -> 仍失败且可修复时请求模型修改失败片段
975
+ -> 再次验证
976
+
977
+ 3. 语义失败
978
+ -> 先检查数据引用、字段映射和动作注册
979
+ -> 无法无歧义修复时请求模型修改
980
+ -> 超限则降级相关节点
981
+
982
+ 4. 安全 / 权限失败
983
+ -> 拒绝危险节点或动作
984
+ -> 记录审计事件
985
+ -> 不允许模型重试绕过安全规则
986
+
987
+ 5. 渲染失败
988
+ -> Error Boundary 隔离节点
989
+ -> 使用 fallback renderer
990
+ -> 无 fallback 时显示简短错误状态
991
+ ```
992
+
993
+ ### 8.3 有界重试
994
+
995
+ 建议初始配置:
996
+
997
+ - 确定性修复:最多 2 次局部修复循环。
998
+ - 模型修复:最多 1 次,复杂场景最多 2 次。
999
+ - 整份 DSL
1000
+ 重新生成:默认不重试;只有根结构无法修复且任务价值较高时才考虑。
1001
+ - 总恢复时间:设置硬超时,不能无限等待。
1002
+ - 每次模型修复只发送失败节点、错误路径、允许修改的字段和必要上下文。
1003
+ - 修复后必须重新执行全部相关验证,不能直接信任修复输出。
1004
+
1005
+ 这些数值是初始建议,应通过实际模型质量、延迟和失败率指标调整。
1006
+
1007
+ ### 8.4 错误响应格式
1008
+
1009
+ ``` json
1010
+ {
1011
+ "code": "UI_SCHEMA_INVALID",
1012
+ "message": "组件属性不符合协议",
1013
+ "issues": [
1014
+ {
1015
+ "path": "children[0].props.series[0].field",
1016
+ "code": "UNKNOWN_DATA_FIELD",
1017
+ "message": "字段不存在于当前数据集中",
1018
+ "repairable": true
1019
+ }
1020
+ ],
1021
+ "recovery": {
1022
+ "strategy": "model_repair",
1023
+ "attempt": 1,
1024
+ "maxAttempts": 2
1025
+ }
1026
+ }
1027
+ ```
1028
+
1029
+ 错误消息应提供可定位信息,但不得包含密钥、敏感数据、内部系统提示词或完整服务端堆栈。
1030
+
1031
+ ### 8.5 兜底策略
1032
+
1033
+ 优先级:
1034
+
1035
+ 1. 保留有效节点,仅替换失败节点。
1036
+ 2. 使用同类别的轻量备用渲染器。
1037
+ 3. 将结构化数据转换为表格或列表。
1038
+ 4. 将无法渲染的内容转成安全的纯文本摘要。
1039
+ 5. 若整个输出不可信或违反安全策略,拒绝渲染并给出简洁原因。
1040
+
1041
+ 兜底本身也要经过安全处理。不能因为进入 fallback 就绕过
1042
+ URL、HTML、数据大小或权限检查。
1043
+
1044
+ ------------------------------------------------------------------------
1045
+
1046
+ ## 9. Renderer Registry 与渲染流程
1047
+
1048
+ ### 9.1 注册表职责
1049
+
1050
+ Renderer Registry 根据 `type + version` 找到组件定义和渲染器,负责:
1051
+
1052
+ - 查询组件是否支持。
1053
+ - 查询组件版本和能力。
1054
+ - 获取 Schema 与默认值。
1055
+ - 选择渲染器实现。
1056
+ - 选择 fallback 类型。
1057
+ - 提供懒加载策略。
1058
+ - 维护兼容性和弃用状态。
1059
+
1060
+ 示意接口:
1061
+
1062
+ ``` ts
1063
+ type RenderContext = {
1064
+ uiId: string;
1065
+ componentId: string;
1066
+ locale: string;
1067
+ theme: "light" | "dark" | "system";
1068
+ dataResolver: DataResolver;
1069
+ eventDispatcher: EventDispatcher;
1070
+ };
1071
+
1072
+ type Renderer<TProps = unknown> = {
1073
+ validateProps(props: unknown): ValidationResult;
1074
+ render(props: TProps, context: RenderContext): UIElement;
1075
+ };
1076
+
1077
+ interface RendererRegistry {
1078
+ get(type: string, version: string): Renderer | undefined;
1079
+ }
1080
+ ```
1081
+
1082
+ 这里的 `UIElement` 是概念占位符,不意味着 DSL 必须绑定
1083
+ React。具体实现可使用 React Element、Vue VNode 或内部渲染节点。
1084
+
1085
+ ### 9.2 渲染规则
1086
+
1087
+ - 每个组件都必须有稳定 ID,便于状态管理和局部更新。
1088
+ - 同一 UI 中 ID 不得重复。
1089
+ - Renderer 不得执行 DSL 中提供的任意代码。
1090
+ - Renderer 只能调用注册过的动作。
1091
+ - 组件不能直接越过 Event Dispatcher 修改 Agent 内部状态。
1092
+ - 大型图表、代码编辑器、地图和 3D 引擎按需加载。
1093
+ - 为每个复杂组件设置合理的资源上限。
1094
+ - 支持无障碍标签、键盘操作和明确的加载/错误状态。
1095
+ - 不允许通过任意 CSS 破坏宿主布局或覆盖安全界面。
1096
+
1097
+ ### 9.3 组件级错误边界
1098
+
1099
+ 每个复杂节点应能独立捕获运行时异常。推荐处理:
1100
+
1101
+ 1. 捕获渲染异常。
1102
+ 2. 记录组件类型、版本、错误代码和关联 ID。
1103
+ 3. 不记录不必要的完整敏感 props。
1104
+ 4. 尝试备用渲染器。
1105
+ 5. 备用渲染器失败时显示简化错误节点。
1106
+ 6. 不影响兄弟节点和对话其余内容。
1107
+
1108
+ React 的 Error Boundary
1109
+ 可以捕获其子树中的部分渲染错误,但不能替代异步操作、事件处理器、数据请求和安全校验的显式错误处理。
1110
+
1111
+ ------------------------------------------------------------------------
1112
+
1113
+ ## 10. 交互事件协议
1114
+
1115
+ ### 10.1 事件分类
1116
+
1117
+ **本地事件**:展开、折叠、Tab
1118
+ 切换、表格排序、分页、图例切换、输入框变化、局部筛选。默认在客户端处理,不调用模型。
1119
+
1120
+ **应用动作**:查询、保存、导出、提交表单、打开已授权资源。通过注册动作路由器调用应用服务,执行服务端授权和参数校验。
1121
+
1122
+ **Agent
1123
+ 事件**:需要模型理解或继续规划的用户行为,例如"按这些条件重新分析"。只发送必要的状态和用户意图,不把整个
1124
+ UI 树无条件重新注入上下文。
1125
+
1126
+ ### 10.2 事件信封
1127
+
1128
+ ``` json
1129
+ {
1130
+ "protocol": "agent-genui-event",
1131
+ "version": "1.0",
1132
+ "eventId": "evt_123",
1133
+ "uiId": "ui_01",
1134
+ "componentId": "search-form",
1135
+ "event": "submit",
1136
+ "payload": {
1137
+ "keyword": "timeout",
1138
+ "level": "error"
1139
+ },
1140
+ "source": "user"
1141
+ }
1142
+ ```
1143
+
1144
+ 服务端或 Runtime 需要验证:
1145
+
1146
+ - `uiId` 和 `componentId` 是否属于当前会话。
1147
+ - 事件名称是否由该组件声明。
1148
+ - Payload 是否符合事件 Schema。
1149
+ - 事件是否重复提交。
1150
+ - 当前用户是否有权执行目标动作。
1151
+ - 数据是否过期或任务是否已结束。
1152
+
1153
+ ### 10.3 动作注册
1154
+
1155
+ ``` ts
1156
+ type ActionDefinition = {
1157
+ id: string;
1158
+ inputSchema: unknown;
1159
+ authorization: "public" | "authenticated" | "privileged";
1160
+ execute: (
1161
+ input: unknown,
1162
+ context: ActionContext
1163
+ ) => Promise<ActionResult>;
1164
+ };
1165
+ ```
1166
+
1167
+ DSL 只能引用已注册的 `id`,不能提供 `execute`
1168
+ 函数。权限检查必须在真正执行动作时进行,而不是只在 UI 生成时做一次。
1169
+
1170
+ ### 10.4 避免无意义的模型调用
1171
+
1172
+ 以下事件通常不应触发 Agent:
1173
+
1174
+ - 展开一个折叠面板。
1175
+ - 在本地表格排序。
1176
+ - 切换图表图例。
1177
+ - 改变轮播页。
1178
+ - 在已经载入的选项中切换 Tab。
1179
+ - 调整仅影响本地预览的控件。
1180
+
1181
+ 以下事件可能触发 Agent:
1182
+
1183
+ - 用户要求对筛选结果进行解释。
1184
+ - 用户选择方案并要求继续执行。
1185
+ - 用户输入新的自然语言目标。
1186
+ - 用户请求对当前任务重新规划。
1187
+
1188
+ ------------------------------------------------------------------------
1189
+
1190
+ ## 11. 安全与信任边界
1191
+
1192
+ ### 11.1 禁止执行任意生成代码
1193
+
1194
+ 默认禁止:
1195
+
1196
+ - `eval`、`Function`、动态导入生成代码。
1197
+ - 模型提供的任意脚本、事件处理函数和回调。
1198
+ - 不受限的 HTML 注入。
1199
+ - 未验证的 `javascript:`、`data:` 等危险 URL。
1200
+ - 模型指定的任意网络请求或任意 API 地址。
1201
+ - 通过 DSL 直接访问浏览器 Cookie、Local Storage 或宿主内部对象。
1202
+
1203
+ 如果未来产品需要生成可运行代码,应建立独立沙箱,限制网络、文件、CPU、内存和执行时间,并通过单独的安全评审。
1204
+
1205
+ ### 11.2 XSS 与内容安全
1206
+
1207
+ - Markdown 渲染时禁用或严格净化原始 HTML。
1208
+ - 链接和图片 URL 使用协议白名单。
1209
+ - 外部图片、视频、地图资源遵守 CSP 和允许来源策略。
1210
+ - 用户内容与模型内容均按不可信输入处理。
1211
+ - 组件属性不能被直接拼接成 HTML。
1212
+ - 对下载文件和导出产物进行访问控制。
1213
+
1214
+ ### 11.3 权限
1215
+
1216
+ - UI 显示某个按钮不代表用户获得了权限。
1217
+ - 服务端必须再次鉴权。
1218
+ - 高风险动作必须显示影响范围并取得明确确认。
1219
+ - 事件 ID、动作 ID 和资源引用都要校验。
1220
+ - 需要审计的操作应记录操作者、时间、资源和结果。
1221
+ - 不允许通过模型修复流程绕过安全校验。
1222
+
1223
+ ### 11.4 资源与拒绝服务保护
1224
+
1225
+ 建议设置可配置限制:
1226
+
1227
+ - 最大 DSL 字节数。
1228
+ - 最大组件节点数。
1229
+ - 最大树深度。
1230
+ - 单组件最大属性体积。
1231
+ - 最大数据集行数、列数和单元格长度。
1232
+ - 最大图片/音视频资源大小。
1233
+ - 图表点数上限。
1234
+ - 图形节点和边数量上限。
1235
+ - 渲染器加载超时。
1236
+ - 单次模型修复总时限。
1237
+
1238
+ 具体阈值应通过实际负载测试确定,避免写死为所有业务共用的常数。
1239
+
1240
+ ------------------------------------------------------------------------
1241
+
1242
+ ## 12. 状态管理与上下文成本
1243
+
1244
+ ### 12.1 状态分类
1245
+
1246
+ 1. **展示状态**:展开、当前 Tab、排序、分页、缩放。
1247
+ 2. **表单状态**:输入值、校验错误、是否已提交。
1248
+ 3. **任务状态**:Agent 计划、工具调用、执行结果。
1249
+ 4. **数据状态**:数据集引用、版本、加载状态。
1250
+ 5. **权限状态**:可执行动作、审批状态、资源授权。
1251
+
1252
+ 展示状态通常保存在客户端;任务和权限状态由可信 Runtime
1253
+ 或服务端维护。不要把模型生成的 UI 文档当作任务状态的唯一事实来源。
1254
+
1255
+ ### 12.2 面向模型的上下文策略
1256
+
1257
+ - 不把每次本地交互的完整 UI 状态发回模型。
1258
+ - Agent 只接收对下一步推理有意义的事件。
1259
+ - 大表格、日志和图表数据通过数据引用或摘要传递。
1260
+ - 修复请求只携带失败节点和相关错误,不重复整个历史。
1261
+ - 为 UI DSL 设定生成 Token 预算。
1262
+ - 对重复、静态和低价值字段进行规范化压缩。
1263
+ - 保留必要的 UI ID、版本和状态关联,避免无条件重放完整 UI。
1264
+
1265
+ ### 12.3 流式生成
1266
+
1267
+ 第一版建议先支持完整 JSON
1268
+ 输出,确保解析和恢复路径稳定。后续如要流式渲染:
1269
+
1270
+ - 使用明确的增量协议或结构化输出机制。
1271
+ - 只渲染已完成且通过局部验证的节点。
1272
+ - 未闭合的 JSON 片段不能直接当作完整 UI。
1273
+ - 为增量节点建立临时状态和取消机制。
1274
+ - 最终完整文档仍需执行全量验证。
1275
+ - 发生修复时应避免闪烁和丢失用户输入。
1276
+
1277
+ ------------------------------------------------------------------------
1278
+
1279
+ ## 13. 版本、兼容性与扩展
1280
+
1281
+ ### 13.1 版本规则
1282
+
1283
+ - 协议版本和组件版本分开管理。
1284
+ - 非破坏性新增可选字段可以在兼容版本内发布。
1285
+ - 删除字段、改变语义或改变必填约束时,应升级主版本或提供迁移。
1286
+ - 对旧 DSL 建立迁移函数,先迁移再校验内部规范。
1287
+ - 未知主版本默认拒绝或降级,不应猜测解释。
1288
+
1289
+ ### 13.2 组件生命周期
1290
+
1291
+ 组件应有以下状态:
1292
+
1293
+ - `experimental`:实验性,可能变化。
1294
+ - `stable`:稳定支持。
1295
+ - `deprecated`:不建议新内容使用,但仍兼容旧内容。
1296
+ - `disabled`:安全或运行时原因暂时不可用。
1297
+
1298
+ ### 13.3 新增组件的标准流程
1299
+
1300
+ 1. 明确组件语义与适用任务。
1301
+ 2. 定义 DSL 属性和事件契约。
1302
+ 3. 编写 JSON Schema。
1303
+ 4. 编写语义验证规则。
1304
+ 5. 实现主 Renderer 和 fallback。
1305
+ 6. 增加安全、可访问性和性能测试。
1306
+ 7. 加入 Registry 并标注版本。
1307
+ 8. 增加模型选择规则和示例。
1308
+ 9. 通过灰度和指标验证后转为 stable。
1309
+
1310
+ ------------------------------------------------------------------------
1311
+
1312
+ ## 14. 可观测性与评估
1313
+
1314
+ ### 14.1 关键指标
1315
+
1316
+ 指标 含义
1317
+ ------------------------------- --------------------------------
1318
+ UI Generation Success Rate 生成结果通过验证的比例
1319
+ Schema Failure Rate 结构或组件契约失败比例
1320
+ Repair Success Rate 修复后通过验证的比例
1321
+ Fallback Rate 降级到通用 UI 或文本的比例
1322
+ Renderer Error Rate 渲染器异常比例
1323
+ First Render Latency 从收到输出到首个可用 UI 的耗时
1324
+ Full Render Latency 完整 UI 可交互的耗时
1325
+ Interaction Success Rate 事件验证并成功执行的比例
1326
+ Invalid Action Rejection Rate 非法动作被拒绝的比例
1327
+ DSL Token Cost 生成和修复消耗的 Token
1328
+ Bundle / Lazy-load Cost UI 引擎加载成本
1329
+ Accessibility Test Pass Rate 可访问性自动化测试通过率
1330
+
1331
+ ### 14.2 日志要求
1332
+
1333
+ 建议记录:
1334
+
1335
+ - trace ID、conversation/task ID、UI ID。
1336
+ - 协议版本和组件版本。
1337
+ - 生成耗时、解析耗时、验证耗时、渲染耗时。
1338
+ - 错误类别、错误路径、修复次数。
1339
+ - 选择的 Renderer 和 fallback。
1340
+ - 事件类型、授权结果和执行状态。
1341
+
1342
+ 默认不要记录完整用户数据、完整 DSL 或敏感
1343
+ props。若调试需要保留样本,应使用脱敏、访问控制、保留期限和用户数据策略。
1344
+
1345
+ ### 14.3 质量评估集
1346
+
1347
+ 建立固定测试集,覆盖:
1348
+
1349
+ - 简单解释不生成多余 UI。
1350
+ - 比较任务生成可读对比表。
1351
+ - 大数据任务采用表格、筛选或摘要。
1352
+ - 多参数任务生成可校验表单。
1353
+ - Agent 长任务显示可信任务状态。
1354
+ - 图表字段错误能够被发现并恢复。
1355
+ - 未知组件不会导致整页崩溃。
1356
+ - 恶意 HTML、危险 URL 和任意代码被拒绝。
1357
+ - 未授权动作无法执行。
1358
+ - 渲染器加载失败能进入 fallback。
1359
+ - 局部节点崩溃不会破坏兄弟节点。
1360
+ - 低屏幕宽度下布局仍然可用。
1361
+
1362
+ ------------------------------------------------------------------------
1363
+
1364
+ ## 15. 实施路线图
1365
+
1366
+ ### Phase 0:协议与运行时骨架
1367
+
1368
+ 交付:
1369
+
1370
+ - JSON DSL v1。
1371
+ - 根 Schema、节点 Schema、组件 Registry。
1372
+ - Parser、Normalizer、Validator。
1373
+ - 统一错误模型。
1374
+ - 文本 fallback。
1375
+ - 基础日志和测试框架。
1376
+
1377
+ 退出条件:非法 JSON、未知版本、超限节点和非法属性均可被确定性处理。
1378
+
1379
+ ### Phase 1:P0 通用组件
1380
+
1381
+ 首批支持:
1382
+
1383
+ - Text / Markdown。
1384
+ - Heading / Divider。
1385
+ - Card / Metric / Badge。
1386
+ - List / Accordion / Timeline。
1387
+ - Table。
1388
+ - Button / Link。
1389
+ - Input / Textarea / Select / Checkbox / Radio。
1390
+ - Form。
1391
+ - Code Block。
1392
+ - Image / Artifact Card。
1393
+ - Inline Error / Loading / Empty State。
1394
+
1395
+ 退出条件:常见回答、数据列表、表单收集和文件交付可用;关键交互均通过契约校验。
1396
+
1397
+ ### Phase 2:数据可视化与 Agent 状态
1398
+
1399
+ 增加:
1400
+
1401
+ - Line / Bar / Pie / Scatter Chart。
1402
+ - KPI Dashboard。
1403
+ - Task Plan / Progress。
1404
+ - Tool Timeline / Execution Log。
1405
+ - Approval Panel。
1406
+ - Diff View。
1407
+ - Retry / Recovery Controls。
1408
+
1409
+ 退出条件:图表数据校验、任务状态同步、审批授权和局部错误隔离通过测试。
1410
+
1411
+ ### Phase 3:导航和专业图形
1412
+
1413
+ 按真实需求引入:
1414
+
1415
+ - Tabs / Filters / Pagination / Virtual List。
1416
+ - Tree / Graph Explorer。
1417
+ - Mermaid Flowchart。
1418
+ - React Flow 交互图。
1419
+ - 数学公式与函数图。
1420
+ - Map / Route。
1421
+ - Monaco / CodeMirror。
1422
+ - 视频和图像标注。
1423
+
1424
+ 退出条件:专用引擎可懒加载,加载失败有 fallback,复杂图形性能符合目标。
1425
+
1426
+ ### Phase 4:优化与高级能力
1427
+
1428
+ - 流式增量 UI。
1429
+ - 组件级懒加载与 bundle 优化。
1430
+ - DSL 迁移工具。
1431
+ - 组件弃用与兼容策略。
1432
+ - 自动化视觉回归。
1433
+ - 生成策略评估与反馈闭环。
1434
+ - 受控的自定义扩展机制。
1435
+
1436
+ 退出条件:性能、兼容性、错误率和安全评估达到项目目标。
1437
+
1438
+ ------------------------------------------------------------------------
1439
+
1440
+ ## 16. 测试策略
1441
+
1442
+ ### 16.1 单元测试
1443
+
1444
+ - 每个组件 Schema 的有效与无效样例。
1445
+ - 默认值与规范化。
1446
+ - DSL 版本迁移。
1447
+ - 事件 payload 校验。
1448
+ - Action Registry 的权限规则。
1449
+ - 错误分类和恢复决策。
1450
+
1451
+ ### 16.2 集成测试
1452
+
1453
+ - JSON → Parser → Validator → Renderer。
1454
+ - 未知组件 → fallback。
1455
+ - 数据引用失效 → 空状态或重绑定。
1456
+ - Renderer 动态加载失败 → 备用渲染器。
1457
+ - 表单提交 → 事件路由 → 应用动作。
1458
+ - 高风险动作 → 授权检查 → 审计。
1459
+ - 局部组件崩溃 → 兄弟节点仍可用。
1460
+
1461
+ ### 16.3 安全测试
1462
+
1463
+ - XSS 字符串与恶意 Markdown。
1464
+ - 危险 URL 协议。
1465
+ - 超大嵌套对象和数组。
1466
+ - 重复组件 ID。
1467
+ - 未注册动作 ID。
1468
+ - 伪造或重放事件。
1469
+ - 未授权数据集引用。
1470
+ - 恶意属性和未知协议版本。
1471
+ - 模型试图输出脚本或动态导入。
1472
+
1473
+ ### 16.4 视觉与可访问性测试
1474
+
1475
+ - 桌面与窄屏布局。
1476
+ - 长文本、空数据、超长标签。
1477
+ - 深色和浅色主题。
1478
+ - 键盘导航、焦点可见性、ARIA 语义。
1479
+ - 加载、失败、禁用和空状态。
1480
+ - 图表替代说明和非颜色状态表达。
1481
+
1482
+ ------------------------------------------------------------------------
1483
+
1484
+ ## 17. 验收标准
1485
+
1486
+ 第一版发布前至少满足以下条件:
1487
+
1488
+ ### 协议与校验
1489
+
1490
+ - [ ] 所有 DSL 均带协议版本。
1491
+ - [ ] 未知协议版本不会被静默误解析。
1492
+ - [ ] 每个已支持组件都有 Schema 和版本。
1493
+ - [ ] 节点数量、深度、字符串和数据体积有限制。
1494
+ - [ ] 语义验证能够识别不存在的数据字段和图形节点。
1495
+ - [ ] 修复输出必须重新经过验证。
1496
+
1497
+ ### 渲染与恢复
1498
+
1499
+ - [ ] 未知组件可降级或明确报错,不导致整页崩溃。
1500
+ - [ ] 单个 Renderer 异常可以被隔离。
1501
+ - [ ] 复杂 Renderer 有加载失败状态和 fallback。
1502
+ - [ ] 模型重试有次数和总时间上限。
1503
+ - [ ] 安全错误不会进入可绕过权限的模型重试流程。
1504
+ - [ ] 空数据、超大数据和无效数据均有定义好的表现。
1505
+
1506
+ ### 交互与安全
1507
+
1508
+ - [ ] 本地 UI 交互默认不触发模型调用。
1509
+ - [ ] 所有应用动作都通过注册表和服务端鉴权。
1510
+ - [ ] 事件 payload 经过 Schema 校验。
1511
+ - [ ] 未注册动作、伪造事件和未授权数据引用被拒绝。
1512
+ - [ ] 不执行模型生成的任意 JavaScript。
1513
+ - [ ] Markdown、链接、图片和外部资源遵守安全策略。
1514
+
1515
+ ### 工程质量
1516
+
1517
+ - [ ] 关键链路有单元、集成和安全测试。
1518
+ - [ ] 有生成成功率、修复成功率、fallback 率和渲染错误率指标。
1519
+ - [ ] 支持稳定组件的版本兼容和弃用流程。
1520
+ - [ ] 基础 UI 不依赖所有专业引擎同时加载。
1521
+ - [ ] UI 在窄屏、键盘导航和错误状态下仍可使用。
1522
+
1523
+ ### 建议的初始 SLO
1524
+
1525
+ 以下是可讨论的起始目标,不是对所有项目都适用的硬性标准:
1526
+
1527
+ - 基础 DSL 解析与校验:P95 小于 50 ms(不含模型生成与外部数据请求)。
1528
+ - 基础 UI 首次可交互:P95 小于 1 s(不含模型生成与网络环境差异)。
1529
+ - 单个组件渲染异常导致整页不可用:目标为 0。
1530
+ - 未授权动作执行成功:目标为 0。
1531
+ - 所有已发布稳定组件:必须具备 Schema、基本交互测试和 fallback
1532
+ 行为定义。
1533
+
1534
+ ------------------------------------------------------------------------
1535
+
1536
+ ## 18. 关键设计决策总结
1537
+
1538
+ 1. **协议采用 JSON DSL**,不让模型直接生成并执行前端代码。
1539
+ 2. **组件按语义类型定义**,与 React、Vue 和具体组件库解耦。
1540
+ 3. **验证分层**:结构、组件契约、语义、安全、运行时。
1541
+ 4. **先确定性修复,再进行有界模型修复**;所有修复结果重新校验。
1542
+ 5. **异常按类别恢复**:局部降级、备用 Renderer、文本
1543
+ fallback、安全拒绝。
1544
+ 6. **通过 Renderer Registry 分发**,专用图形和编辑器按需加载。
1545
+ 7. **本地交互与 Agent 推理解耦**,只将有推理价值的事件回传模型。
1546
+ 8. **权限由应用服务端执行**,不以 UI 展示状态作为授权。
1547
+ 9. **先建设 P0 通用组件和运行时骨架**,再按实际需求扩展专业 UI。
1548
+ 10. **用评估集、指标和验收标准持续优化**,而不是单纯追求组件数量。
1549
+
1550
+ ## 19. 参考资料
1551
+
1552
+ 以下资料可用于实施时核对具体 API
1553
+ 和能力;选型时应以项目当前版本的官方文档为准。
1554
+
1555
+ - JSON Schema:<https://json-schema.org/>
1556
+ - Ajv JSON Schema Validator:<https://ajv.js.org/>
1557
+ - React:<https://react.dev/>
1558
+ - TanStack Table:<https://tanstack.com/table>
1559
+ - TanStack Virtual:<https://tanstack.com/virtual>
1560
+ - Apache ECharts:<https://echarts.apache.org/>
1561
+ - Vega-Lite:<https://vega.github.io/vega-lite/>
1562
+ - Plotly.js:<https://plotly.com/javascript/>
1563
+ - Recharts:<https://recharts.org/>
1564
+ - React Flow:<https://reactflow.dev/>
1565
+ - Mermaid:<https://mermaid.js.org/>
1566
+ - Monaco Editor:<https://microsoft.github.io/monaco-editor/>
1567
+ - CodeMirror:<https://codemirror.net/>
1568
+ - Cytoscape.js:<https://js.cytoscape.org/>
1569
+ - D3.js:<https://d3js.org/>
1570
+ - MapLibre GL JS:<https://maplibre.org/maplibre-gl-js/docs/>
1571
+ - Three.js:<https://threejs.org/docs/>
1572
+ - KaTeX:<https://katex.org/>
1573
+ - JSON Forms:<https://jsonforms.io/>
1574
+
1575
+ ------------------------------------------------------------------------
1576
+
1577
+ **文档结束。**