weichen
1c25d65ae9
Why: The U1 controlled trial finished; its fixtures, validator, runner, per-run results, report, and renderer spike must be reviewable from the task branch, and the task card needs the final PASS/FAIL record. Evidence: results/summary.json + report.md (SELF, MiniMax official channel, CNY 3 of 200 cap); make evidence receipts for precheck, task-sync, and make test follow in this branch. Impact: Task-scoped experiment artifacts only (.task/genui-u1/); no production code changes. Refs: Documents PR #62 (proposal r2); task card feature/generative-ui-u1
3.4 KiB
3.4 KiB
U1 附录：json-render / A2UI renderer 选型挑战（G2）
日期：2026-10-11。隔离环境：/tmp/genui-renderer-spike（不入仓）；React 19 + react-dom 19 + zod 4。
本节为原型 spike 记录，不是生产集成声明；未做视觉/可访问性验收，未接入 @ui 真实组件。
安装与体量
| 包 | 版本 | 许可 | peer | 体量（node_modules） |
|---|---|---|---|---|
| @json-render/core + /react | 0.21.0 | Apache-2.0 | react ^19.2.3、zod ^4 | ~1.8M（zod 另计 ~8.1M，dev 常见） |
| @a2ui/react | 0.13.0 | Apache-2.0 | react、react-dom、zod | ~20M（含 @a2ui/web_core、markdown-it） |
两者均可在 React 19 下干净安装，无版本冲突。
json-render：端到端跑通（含嵌套组合）
defineCatalog（zod props）+validateSpec+createRenderer+renderToString全链路可用； 用我们的 table/steps 形状定义目录，规格校验通过，嵌套组合（table 内挂 steps，经组件children）渲染正确。- 真实收益：schema 驱动的规格校验（可替代手写校验器，目录即文档即校验）；扁平 elements
- children 键的规格格式与流式 patch 设计成熟。
- 集成成本：
- 组件契约是
{element, slots, emit, on, bindings, loading, children}——16 个 @ui 组件各需 一层包装 + 测试，不是「换个 switch」。 - 规格为扁平格式，需与我们嵌套 UINode/Surface 信封之间加双向适配层（SurfaceVersion 联动）。
- 框架自带 state store、action binding、visibility、patch 流——与我们 SSE/store/cmdbus/审批 职责重叠（r1 风险表「引入第二套状态/runtime」）。仅用其 render+validate 可避开，但那样 增量价值缩小为主要买「校验器 + 目录格式」。
experimental_composeSpec（决策模型组合）依赖 Vercel AI Gateway 且标注 experimental，本期不用。
- 组件契约是
@a2ui/react：导入即要求 DOM，绑定模型与宿主解析相悖
- 包在导入时就引用
HTMLElement——裸 Node/SSR 环境直接抛错，需浏览器或 jsdom 垫片； 仅这一点就把它推向「前端专属重依赖」档（~20M）。 - 导出面为
A2uiSurface/createComponentImplementation/useSignalValue等：数据经 客户端 signal/binder 持续绑定。这与 r1 KTD4「数据绑定由宿主服务端解析、模型不能自报 数据值」的信任边界结构性冲突——采用它要么放弃宿主解析（否决），要么只用其组件壳不用其 绑定（价值进一步缩小）。 - 本轮未做完整渲染 spike（受 DOM 前置约束），标注为 部分完成；结论按结构冲突已足够定型。
结论（建议，随 r2 评审确认）
- 首期不引入外部 renderer：扩展现有 UIRenderer + 自研校验（本试验 G 臂即其原型）成本更低、 无第二运行时风险；json-render 的「目录即校验」思想值得在 U2 契约里借鉴（schema 驱动目录）。
- json-render 保留为 B 路线观察项：若后续 U5 交互闭环需要其 state/action/visibility 全家桶， 以「render+validate 子集」重评；A2UI 客户端绑定模型与宿主授权边界冲突，不推荐作为默认路线。
复核方式
/tmp/genui-renderer-spike/spike.mjs、spike2.mjs（含运行输出摘录见本目录 renderer-spike.log）；
版本锁定：@json-render/core@0.21.0、@json-render/react@0.21.0、@a2ui/react@0.13.0、react@19。