For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/genui/a2ui/protocol-1.0-audit.md.
这是开发预览网站。请访问正式文档 lynx-stack.dev
  • 简体中文

      • A2UI 1.0 迁移复核

      English | 简体中文

      本次复核覆盖从 c118dd9fd 到 9f8404e0a 的六个迁移提交，包括测试、生成的 Catalog、提示词、示例、传输适配和文档。对照官方提交 24d1bf9c830071f74c9c908433e73cc6cbe0aa33。 官方 版本清单 已将 1.0 标为当前版本；分支之前固定到 1c45c809b655878d06e3afc6dda22100afecc0a4。

      与分支原有契约的差异

      范围分支原有行为当前标准与实现
      消息版本"v1.0"双向消息、元数据、示例和提示词统一为 "1.0"；拒绝旧版本及缺少版本的消息。
      动态值path、call改为 @path、@call；普通键作为字面数据；@@ 只去掉一个前缀；未知指令报错。
      组件字段catalogId、metadata、accessibility、checks改为 @catalogId、@metadata、@accessibility、@checks。Surface/函数的 catalogId、ChildList.path、updateDataModel.path 不加前缀。
      Renderer RPC没有数据模型作用域surfaceId 可选；省略时使用隔离的空模型；无效作用域或权限错误通过关联的 rendererFunctionResponse 返回。
      函数执行权限和参数检查不完整检查 allowedCallers、requiresUserActivation、解析后的参数和默认值；无本地实现的 schema 声明可路由给 Agent；action 等待嵌套异步结果，每次发起新调用。
      失败处理部分错误被吞成 undefined 或等到超时动态绑定失败为 null；远程错误关联 functionCallId，本地错误关联 surfaceId；传输拒绝及时结束 RPC。
      校验Boolean 和 ValidationResult 行为混杂使用明确的 DynamicBoolean 转换；保留可选 CheckRule.message，以及结果消息优先级、code、severity。
      插值与正则依赖旧 Web 函数包使用本地实现；插值继承外层函数 Catalog，支持 @index；正则执行可移植方言、安全静态分析、Unicode 码点和严格结束锚点。
      Catalog较早的函数和组件结构当前判别字段、相对 common type 引用；保留用户手势声明，禁止声明保留的 Surface 组件，执行组合约束。
      快照输出内部模板实例上下文保留协议模板和元数据，不把内部克隆 ID、dataContextPath 当作组件属性输出。
      Playground只转发点击转发协议消息和数据模型元数据；全部 Local/Gallery 示例对照固定的官方 schema 和生成的 Lynx Catalog 校验。

      按代码区域复核

      • src/store：生命周期、JSON 子树更新、Catalog 查找、表达式、模板展开、RPC 关联、 异步值和组合约束。内部资源仍有 beginRendering/surfaceUpdate 名称，它们不是可接收的 wire 操作，也不是 0.9 兼容分支。
      • src/react、src/catalog：action、校验、组件 Catalog 选择、无障碍属性和序列化。 action/checks 保留到执行边界才求值；删除旧 Modal 字段别名和嵌套 template 回退。
      • src/functions：14 个官方 basic 函数和 11 个明确声明的 Lynx 工具函数；后者属于自定义 Catalog，不代表支持旧协议。删除 0.9 Web SDK 依赖；函数 schema 和正则分析与协议夹具 固定到同一个上游提交。
      • src/snapshot：保留 JSON 类型、删除语义、可达组件定义、集合模板和 Surface 扩展元数据。
      • a2ui-catalog-extractor：组件/函数判别字段、引用类型、Catalog 联合定义、测试夹具和文档。
      • server/agent/a2ui：当前提示词、消息、Catalog、公共类型、来源检查、流式校验和组合约束； 严格信封解析拒绝 theme 等已移除字段。
      • server/app/a2ui：将 renderer 消息与 HTTP 选项分开校验，保留 JSON/SSE RPC 和 action 元数据；无 Surface 的 renderer 反馈由无状态服务确认接收，不虚构 Surface。
      • playground、CLI 模板、示例：当前字段、Catalog ID、合法组件 ID、可见错误和 RPC 转发； 媒体示例使用已实现的链接动作，不再宣称存在 AudioPlayer/Video renderer。
      • Bench adapter/runner：版本、消息提取、来源检查和回放夹具使用相同契约，评估行为保持一致。

      实现范围与宿主职责

      发布的是 Lynx Catalog，不表示官方 basic catalog 的每个组件都有原生实现。GenUI 服务未安装 Agent 端 Catalog 函数，因此对这类请求返回 UNKNOWN_FUNCTION；宿主可以注册 可信实现。客户端表达式求值不会拉取远程代码或 Catalog 引用。

      无障碍 label/description、hidden 映射到 Lynx 属性，Web 属性还携带 live-region 意图。 读屏实际行为取决于宿主平台。openUrl 需要浏览器或宿主提供的原生实现。原生字节码构建 检查不替代真机读屏测试。

      回归测试使用固定的官方 schema、本地 mock 和生成的 Catalog，不依赖模型现场输出， 也不宣称通过外部认证项目。

      验证结果

      • 全仓构建：75 个任务通过，包含原生字节码和 Web。
      • 相关回归：114 个文件、1,028 个用例通过，包括 8 个 Local Examples 和 35 个 Gallery 示例的官方 schema 校验。
      • client、server、extractor 类型检查通过；API Extractor 的 26 个任务通过。
      • 修改文件的 ESLint、Biome、dprint 和 git diff --check 通过；changeset 检查包含预期的 GenUI minor 发布，并明确标注破坏性变化。
      • 不限定范围的全仓 Biome 会扫描 examples/react-debug-metadata/dist-consumer 下被 Git 忽略的构建产物，报告生成代码错误。本次源码范围检查通过，没有提交这些构建产物。
      • Playground 独立 tsc --noEmit 被现有项目引用配置阻止（TS6310）；Web 和原生生产构建通过。

      与 main 的集成

      协议审计后合入 main 的 3ff5a0282，保留其拆分后的 Playground 渲染入口和按批次处理 的流式占位逻辑。在 playground/src/render/a2ui.ts 转发 RPC 和元数据；将 Jev 生成、 内联快照恢复和独立预览页迁移至当前协议。Jev action 响应更新已有 Surface，不再重复 发送 createSurface。

      合并后全仓 80 个构建任务、170 个文件中的 1,948 个测试、26 个 API Extractor 任务通过。 Client、server、extractor 类型检查和修改范围的 ESLint、Biome、dprint 检查通过。 Server Catalog 已与当前提取器输出同步，并补齐新文档站要求的 API 中文翻译。