A2UI 渲染器生产就绪指南
渲染器会把 Agent 生成的数据变成交互控件，因此它本身就是安全边界。即使 Agent 可以回答问题，其载荷仍可能包含错误类型、不受支持的组件、不安全 URL，或用户没有授权的操作。生产就绪不只是“演示能显示”，还要求宿主在输入残缺、延迟、重复、恶意或协议版本不一致时保持控制。
本指南面向准备上线 Web 渲染器或宿主集成的团队。官方仓库目前将 v0.9.1 作为生产版本线，v1.0 仍是候选规范。Agent、传输层、Schema 校验器、Catalog 与渲染器必须固定到同一个版本，不得在同一消息流混用不同版本的消息名或组件结构。
1. 明确信任边界
记录每个值由谁生成、谁有权执行。以下输入在宿主校验前都应视为不可信：
- Agent 或模型发送的全部消息；
- Catalog 标识和组件名称；
- 文本、URL、媒体地址、样式与数据绑定；
- Action 名称、参数与目标标识；
- 指向已有 Surface 的增量更新。
渲染器只能实例化宿主注册目录中的组件。载荷不得选择任意模块、执行内嵌代码、注入原始 HTML，或把普通字符串直接解释为高权限命令。Catalog 是白名单和兼容契约，不是远程代码发现机制。
2. 改变状态前完成校验
每条消息进入渲染状态前，都要按固定协议版本的 Schema 校验。拒绝未知顶层消息、Schema 不允许的属性、非法标识、不支持的 Catalog、错误值类型以及超限载荷。
还需要语义校验：确认 surfaceId 已存在、组件 ID 满足唯一性、绑定只指向允许的数据路径、组件关系不会形成非法或过深的树。必须使用真正的 JSON 解析器；不要静默“修复”模型生成的错误 JSON，因为修复可能改变操作含义。
向 Agent 或传输层返回结构化且不泄露敏感信息的错误。用户界面应保留最后一个有效 Surface 或显示稳定降级状态，不能直接白屏。
3. 强制执行生命周期
v0.9 使用 createSurface、updateComponents、updateDataModel 和 deleteSurface。为每个 Surface 单独维护状态，并明确拒绝非法转换。未知 Surface 的更新不能隐式创建 Surface；重复创建不能覆盖活跃 Surface；删除后要清理组件状态、数据绑定、待执行回调和订阅。
流式传输还会产生顺序问题。在上层协议支持时携带序列信息，按确定顺序处理消息，并规定重连时如何处理重复数据。至少测试：创建前收到更新、更新中删除、消息重复、数据流截断，以及部分渲染后重连。
4. 缩小 Catalog 范围
从满足产品需求的最小组件目录开始。每个组件适配器都要定义允许的属性、默认值、大小限制、子组件关系和无障碍行为。即使其他渲染器支持某组件，本宿主目录未登记时也要拒绝。
URL 需要独立策略：只允许必要协议，禁止脚本 URL，并按业务需要限制图片或跳转来源。不得把 Agent 提供的请求头、凭据或令牌转发到远程地址。支持富文本时应由宿主使用可靠规则净化；没有经过评审的明确需求时，不开放原始 HTML。
5. 由宿主授权 Action
A2UI Action 只是请求，不代表权限。宿主必须通过自己的注册表解析 Action 名称并校验全部参数。应区分无害的本地交互，与读取私有数据、修改服务端状态、付款、发消息、上传文件或离站跳转等操作。
敏感操作应提供明确确认，准确说明将发生什么。服务端必须再次鉴权；隐藏按钮不等于访问控制。可能重复提交的操作要具备幂等保护，并向用户展示取消、失败和重试状态。
不得让模型通过 Action 载荷提供可执行 JavaScript、SQL、Shell 命令、任意 API 路径或授权范围。正确做法是把少量声明式 Action 名称映射到经过审查的应用代码。
6. 限制资源消耗
为消息字节数、组件数量、嵌套深度、文本长度、数据模型大小、更新频率、媒体尺寸和活跃 Surface 数量设置上限。远程媒体和 Action 调用要有超时；大型列表应虚拟化，而不是一次渲染全部项目。
触发限制时要可预测：记录带关联标识的原因，显示简洁降级界面，并允许对话继续。限制必须通过测试验证，只有文档说明而没有运行时执行并不能保护浏览器。
7. 保持无障碍能力
生成界面应达到与手写页面相同的无障碍标准：语义化控件、可见标签、合理标题层级、键盘操作、清晰焦点、足够对比度和可感知的校验错误。流式更新不能抢走焦点；重要状态可通过合适的实时区域播报，但不应逐字朗读每个 Token。
组件适配器应内置这些保证，避免让 Agent 自行发明 ARIA 属性。至少测试纯键盘、页面缩放、减少动态效果、高对比度和一种屏幕阅读器。降级界面也必须可访问。
8. 设计稳定失败状态
为加载、空数据、不支持组件、消息无效、传输离线、Action 失败和权限拒绝分别设计状态。可恢复更新期间保留用户已经输入的数据。不要向用户展示原始 Schema 错误、堆栈、提示词或可能暴露内部数据的模型输出。
单个组件失败时，优先隔离该组件，而不是销毁整个界面。尤其涉及高影响操作时，只要正确性不确定就停止，并请求新的有效响应，不能猜测执行。
9. 可观测但不过度收集
监测校验失败、不支持组件请求、渲染耗时、Action 成功率、重试次数、Surface 生命周期和降级频率。可以把版本、Catalog、组件和错误码作为维度，但不要记录完整提示词、私有数据模型值、认证材料或完整 Action 载荷。
为 Surface 和 Action 分配可安全记录的关联标识，在入口处脱敏，并规定保留期限和高频事件采样。可观测数据应足以解释故障，但不能重建用户的私密会话。
10. 执行上线测试矩阵
上线前既要测试符合固定 Schema 的正常样例，也要主动测试错误样例。覆盖慢速流、消息乱序、重复、断线、不支持的 Catalog、恶意 URL、超大载荷、深层组件图、Action 重放、授权过期、键盘操作、窄屏、国际化和渲染器升级。
Agent 与渲染器之间使用契约测试；组件适配器和 Action 映射使用单元测试；生命周期使用集成测试；无障碍和恢复能力使用浏览器测试。将代表性载荷保存为 Fixture，使协议升级产生可审查的差异。
上线门槛
只有以下条件全部满足，渲染器才可视为生产就绪：
- 端到端固定同一个协议版本；
- 每条入站消息都经过 Schema 与策略校验；
- 只接受宿主批准的 Catalog、组件、URL 和 Action；
- 高影响操作经过服务端授权并在必要时二次确认；
- 生命周期、流式处理、重连和清理行为确定；
- 资源限制和安全降级已经测试；
- 生成控件支持键盘和屏幕阅读器；
- 日志可诊断问题，但不保存秘密或不必要的个人数据；
- 回滚和兼容流程已经演练。
请以官方渲染器开发指南、消息参考和A2UI 分版本规范为准。本站用于解释实现决策，不能替代实际发布版本的 Schema。