json-render：用 JSON 约束 AI 生成界面的框架，靠谱吗？

它解决的痛点：AI 生成界面，但别让它乱来

直接用大模型生成界面，最常见的问题是输出不可控。模型可能返回一段 JSX，也可能是一堆 Markdown，甚至混入不存在的组件。json-render 的解法是把输出格式硬性规定为 JSON，并且这个 JSON 只能引用你预先定义的组件。你写一个 catalog，里面列出允许使用的组件、它们的 props 类型和描述，AI 就在这个框子里生成。这样你得到的是结构化的、可预测的界面描述，而不是一段随时可能编译失败的代码。它面向的是那些想把 AI 接入产品、但又不想牺牲稳定性的团队，尤其是已经有现成组件库、只缺一个安全桥接层的开发者。

核心机制：catalog、registry 与 spec 三层结构

json-render 的工作流程可以拆成三层。第一层是 catalog，用 defineCatalog 定义，里面用 zod schema 描述每个组件的 props，比如 Card 需要 title 字符串，Metric 需要 label、value 和可选的 format 枚举。这个 catalog 同时会生成给 AI 用的提示词，告诉模型有哪些组件可用、每个组件接受什么参数。第二层是 registry，用 defineRegistry 把 catalog 里的组件名映射到实际的渲染函数，比如 Card 对应一个 React 组件，Button 对应一个带 emit 事件的 button。第三层是 spec，就是 AI 生成的那个 JSON 对象，它有一个 root 键指向根元素，一个 elements 映射表存储所有节点，每个节点包含 type、props 和 children。Renderer 组件接收 spec 和 registry，遍历 elements 树，把每个节点交给对应的组件渲染。这个设计把 AI 输出和实际渲染完全隔离，AI 只负责生成符合 schema 的 JSON，不接触任何代码。

上手：三行代码定义一个组件，但真正的成本在后面

快速开始很简洁。先定义 catalog，用 defineCatalog 传入 schema 和组件定义，每个组件就是 zod 对象加一段 description。然后定义 registry，用 defineRegistry 把 catalog 和实际组件绑定，组件函数接收 props 和 children，Button 还能通过 emit 触发事件。最后把 AI 生成的 spec 丢给 Renderer。README 里的例子看起来就这么简单，但注意，这只是单个组件的定义。你的 catalog 里如果有几十个组件，每个都要写 zod schema、写描述、写渲染函数，这个工作量是线性的。而且 schema 变了，AI 的提示词也得重新生成，模型输出可能随之变化。所以上手容易，维护 catalog 才是长期成本。

跨平台是卖点，但每个平台都要单独适配

json-render 的包列表很长：React、Vue、Svelte、Solid、React Native、Remotion、React PDF、React Email、Ink 终端、甚至 React Three Fiber。听起来一个 catalog 到处用，实际上每个平台都要有自己的 renderer 和 schema 适配。比如 @json-render/react 和 @json-render/vue 各自导出 defineRegistry 和 Renderer，API 相似但不完全一致。Svelte 5 用 runes 实现响应式，Solid 用细粒度更新，这些底层差异意味着你为 React 写的组件函数不能直接搬到 Vue。README 里没有说明跨平台复用的具体程度，但根据包结构，共享的应该只是 catalog 定义和 spec 格式，渲染层还是要为每个目标平台分别实现。如果你的项目只在一个框架内，这个跨平台优势就只是纸面上的。

流式渲染与指令系统：两个值得注意的设计

README 提到一个关键特性：流式渲染。AI 模型是逐步输出 token 的，json-render 有 SpecStream 工具，可以把不完整的 JSON 流解析成部分 spec，然后渐进渲染。这意味着用户不用等整个 JSON 生成完，界面会一块一块地出现。另一个亮点是 directives 包，内置了 $format、$math、$concat、$pluralize、$t 这类指令。这些不是组件，而是数据转换函数，可以在 spec 里对 props 做后处理，比如格式化货币、拼接字符串或做国际化。这个设计把逻辑从组件里抽出来，让 AI 生成的 JSON 可以直接表达数据处理意图。但注意，这些指令是预定义的，如果你需要自定义转换，就得自己扩展，README 没提扩展机制，可能需要翻源码。

真实局限：schema 是双刃剑，模型输出仍然可能不合规

json-render 声称 JSON 输出每次都能匹配 schema，但这个保证取决于模型是否严格遵守提示词。README 没有说明如果模型返回了非法 JSON，或者引用了不存在的组件，框架会怎么处理。是抛错、降级还是重试？这是生产环境必须回答的问题。另一个局限是组件目录的粒度。你的 catalog 定义了组件，但组件内部的布局逻辑是死的，比如 Card 只能接受 title，不能接受副标题或图片。AI 无法在目录之外表达更丰富的界面，所以生成的 UI 会很受限于你预先定义的组件集。如果你需要高度定制化的界面，要么把组件拆得很细，要么接受模板化的输出。此外，shadcn 的 36 个预置组件只覆盖常见场景，遇到特殊需求还是要自己写，这又回到了维护成本的问题。

替代方案：对比直接生成代码和纯 JSON Schema

一个直接的替代方案是让 AI 生成 JSX 或 TSX 代码，然后用沙箱执行。这个思路的差异在于，代码生成没有组件目录限制，AI 可以自由组合 HTML 和样式，灵活性高得多，但安全性和可预测性差。你需要处理代码注入、运行时错误、样式隔离等问题。另一个替代是只用 JSON Schema 定义输出格式，不限定组件。比如让模型返回一个通用的 UI 树，节点类型是开放的，然后你在渲染层自己映射。这种做法比 json-render 更轻，但少了 catalog 提供的提示词生成和类型安全。json-render 的独特之处在于把组件目录、schema 校验和渲染器绑定在一起，形成一套完整的约束链。如果你已经有自己的 schema 校验和渲染逻辑，json-render 可能反而多余。

维护与升级成本：版本节奏快，包数量多

从 release 记录看，json-render 从 v0.18.0 到 v0.20.0 只用了四个月，版本号还是 0.x，意味着 API 可能随时变。README 里列了 20 多个包，每个包都可能独立发版，跟进升级需要盯着多个仓库。许可证是 Apache-2.0，商用友好，没有 copyleft 风险，但前提是你不修改源码。如果你要自定义 renderer 或 directives，改动可能涉及核心包，那就要注意 Apache-2.0 的条款，虽然宽松，但专利授权和免责声明还是要看。另外，shadcn 组件本身依赖 Radix UI 和 Tailwind CSS，这意味着你的项目也要引入这些依赖，哪怕你只是想用几个组件。整体来看，json-render 适合愿意承受一定版本波动、并且有资源维护多包依赖的团队。

编辑结论

json-render 适合那些已经确定组件库、且愿意为 AI 输出建立严格边界的团队，尤其是需要在 React、Vue、Svelte 等多端复用同一套组件逻辑的项目。它不适合追求完全自由生成、或者希望 AI 动态发明新组件的场景，也不适合组件目录尚未稳定、需要频繁改 schema 的早期原型。在采用前，先验证三件事：你的模型能否稳定输出符合目录的 JSON，流式渲染在你的网络环境下是否顺畅，以及 shadcn 组件之外的定制成本你是否接受。如果这些都能过关，json-render 提供了一条比自由生成更可控的路径；如果过不了，它可能只是给 AI 套了一层更复杂的壳。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes