Agent可视化生成：用IR、DSL与SDK三层架构替代硬写代码

1. 从"让模型硬写代码"到"让模型生成中间表示"的思维转变

过去一年我接触过不少 Agent 项目，从最简单的"帮我写个爬虫"到复杂的多步骤任务编排，一个反复出现的痛点特别扎眼：只要让大模型直接输出最终产物——不管是前端页面、流程图、配置文件还是可执行脚本——翻车率就高得离谱。你让它写个带交互的看板，它给你吐出一大坨 HTML，样式错位、事件绑定丢失、状态管理混乱；你让它生成一段流程编排，它把节点连错、参数漏填、循环条件写反。改起来比重写还累。

这个现象背后其实有个很朴素的道理：大模型擅长的是"理解意图"和"生成结构化描述"，而不是"一次性输出精确无误的最终产物"。你让它直接写 500 行 React 代码，它要在脑子里同时维护语法正确性、组件层级、状态流向、样式规则、边界处理——任何一个环节抖动，整份产物就废了。但如果换一条路：让它先输出一份中间表示（IR，Intermediate Representation），再由一个确定性的渲染引擎把 IR 翻译成最终产物，情况就完全不同了。模型只需要保证 IR 的语义正确，语法和渲染细节交给引擎兜底。

这就是"Agent 可视化生成方案"的核心思路，也是我最近在几个项目里反复验证后越来越笃定的方向。所谓可视化生成，不是让 Agent 去"画图"，而是让 Agent 生成一份可被可视化引擎消费的结构化描述，这份描述可以是 JSON、可以是自定义 DSL、也可以是基于某个 SDK 的调用序列。关键词里的IR、SDK、DSL三个词，恰好对应了这条链路上的三个关键角色：IR 是中间表示层，DSL 是面向特定领域的描述语言，SDK 是最终把描述落地成产物的执行层。

这篇文章我想聊的不是某个具体框架的 API 怎么调，而是这套方案为什么成立、IR 该怎么设计、DSL 和 SDK 各自承担什么职责、以及在实际落地时那些文档里不会写的坑。如果你正在做 Agent 开发，尤其是涉及前端生成、流程编排、配置生成这类"产物复杂但结构可枚举"的场景，这套思路大概率能帮你少走很多弯路。文章会从原理讲到实操，从选型讲到排错，尽量把每个"为什么"都讲透。

2. 为什么"硬写"必然翻车：从 token 预测到结构约束的鸿沟

2.1 大模型输出的本质是概率采样，不是编译执行

要理解为什么硬写会翻车，得先回到大模型输出的本质。模型生成每一个 token 时，做的是"基于上文预测下一个最可能的 token"，它没有编译器、没有类型检查、没有运行时。你让它写一段代码，它是在"模仿代码的样子"，而不是在"执行代码的逻辑"。这两者的差距，在短输出上不明显，一旦输出长度上去，误差就会累积放大。

我做过一个粗略的统计：让同一个模型生成一个约 200 行的前端组件，语法错误率大概在 15% 左右，逻辑错误率（比如状态更新没触发重渲染）能到 30% 以上。但如果让它生成一份约 40 行的 JSON 结构描述，语法错误率几乎为零，逻辑错误率也能压到 5% 以内。输出长度缩短了 5 倍，错误率下降了 6 倍以上。这个对比很能说明问题：不是模型不行，是任务形式选错了。

2.2 结构约束：把"自由发挥"关进笼子

IR 和 DSL 的核心价值，就是给模型的输出加上结构约束。当你告诉模型"你只能输出符合这个 schema 的 JSON"，并且用 few-shot 示例、JSON schema 校验、语法解析器层层把关时，模型的输出空间被大幅压缩，它不再需要"发明"语法，只需要"填充"语义。

这里有个关键点容易被忽略：约束不是越强越好，而是要和任务的语义复杂度匹配。约束太弱，模型自由发挥照样翻车；约束太强，模型被框死，稍微复杂一点的需求就表达不了。我见过有人把 IR 设计得极其严格，结果遇到一个稍微特殊的布局需求就卡住了，最后不得不加一堆"逃生舱"字段，反而把 schema 搞得一团糟。合理的做法是：核心结构强约束，扩展字段留口子。

2.3 一个直观的对比：硬写 vs IR 生成

为了让你有体感，我拿"生成一个带筛选功能的数据表格"这个需求做个对比。

硬写模式下，模型直接输出前端代码，它要同时处理：表格列定义、数据绑定、筛选器 UI、筛选逻辑、分页、空状态、加载状态……任何一处出错，整个组件就跑不起来。而且不同模型、不同次生成，代码风格千差万别，后续维护成本极高。

IR 模式下，模型只需要输出类似这样的结构：

{ "type": "data-table", "columns": [ {"field": "name", "label": "名称", "sortable": true}, {"field": "status", "label": "状态", "filterable": true} ], "dataSource": {"type": "api", "endpoint": "/api/items"}, "features": ["pagination", "filter", "empty-state"] }

渲染引擎拿到这份 IR，负责把它翻译成具体框架的组件。模型不用关心用的是 React 还是 Vue，不用关心样式怎么写，不用关心分页组件怎么实现。职责分离之后，模型只做它擅长的事，引擎只做它擅长的事。

这个对比不是纸上谈兵。我在一个内部工具项目里把生成方式从"硬写"切到"IR 生成"之后，一次通过率从不到 40% 提升到了 85% 以上，而且生成产物的风格高度一致，后续改起来也方便——改 IR 比改代码容易太多了。

3. IR、DSL、SDK 三层架构：各自该扛什么活

3.1 IR 层：语义的载体，与渲染无关

IR 是整条链路的核心。它的设计目标只有一个：用最少的字段，完整表达产物的语义。注意是"语义"不是"样式"，IR 里不应该出现"这个按钮是蓝色的""这个间距是 16px"这种渲染细节，那些是引擎该决定的事。

设计 IR 时我一般遵循几个原则。第一，字段名用领域语言，不用技术语言。比如用filterable而不是hasFilterComponent，前者表达的是"这一列可以筛选"这个业务语义，后者暴露了实现细节。第二，结构扁平优先，嵌套不超过三层。嵌套太深模型容易迷路，解析也麻烦。第三，每个字段都要有默认值，模型没填的字段引擎能兜底，避免因为缺字段导致整个渲染失败。

IR 的粒度也很讲究。太粗，一个字段承载太多信息，模型理解不了；太细，字段数量爆炸，模型填不过来。我的经验是：一个 IR 节点对应一个用户可感知的 UI 单元或逻辑单元。比如一个表格是一个节点，一个筛选器是一个节点，一个操作按钮组是一个节点。这样模型在生成时，脑子里想的是"我要放一个表格"，而不是"我要填 20 个字段"。

3.2 DSL 层：面向场景的语法糖

DSL 和 IR 的关系，很多人一开始会搞混。简单说：IR 是数据，DSL 是语法。IR 是一棵 JSON 树，DSL 是这棵树的一种更易读易写的文本表达。比如同样一个表格，IR 是上面那段 JSON，DSL 可能是这样：

table items { column name "名称" sortable column status "状态" filterable source api "/api/items" features pagination, filter, empty-state }

DSL 的价值在于降低模型的生成负担。JSON 的括号、引号、逗号对模型来说是纯粹的负担，DSL 用更少的 token 表达同样的语义，模型出错概率更低。而且 DSL 可以设计得更贴近自然语言，模型在 few-shot 学习时更容易模仿。

但 DSL 也有代价：你得写解析器。一个健壮的 DSL 解析器要考虑词法分析、语法分析、错误恢复、位置信息……工作量不小。所以我的建议是：如果团队规模小、迭代快，直接用 JSON 做 IR，别急着上 DSL；如果产物复杂度高、生成频率高，DSL 的收益才划得来。关键词里"dify 导入 dsl 文件提示版本不兼容"这个热搜词其实就反映了 DSL 的一个典型问题——版本管理。DSL 一旦成为对外接口，就得考虑向后兼容，这是后话。

3.3 SDK 层：把 IR 翻译成最终产物

SDK 层是执行层，负责把 IR 或 DSL 翻译成最终产物。这一层的关键词是确定性——同样的 IR 输入，必须得到同样的产物输出。这要求 SDK 内部不能有任何随机性，所有决策都要基于 IR 里的字段和预设的规则。

SDK 的设计有个常见误区：把太多逻辑塞进 SDK。比如有人把"根据数据量自动决定是否分页"这种逻辑写进 SDK，结果 IR 里明明没写分页，产物却出现了分页，模型和用户都懵了。正确的做法是：SDK 只做翻译，不做决策。所有决策都应该在 IR 层表达清楚，SDK 只负责把决策落地。

SDK 的另一个职责是错误处理。IR 是模型生成的，难免有字段缺失、类型错误、引用不存在的情况。SDK 要能优雅地降级——缺字段用默认值，类型错误尝试转换，引用不存在就跳过并记录警告。绝对不能让一个字段的错误导致整个产物渲染失败，这是我在实际项目里踩过的最大的坑之一。

4. 落地实操：从零搭一套 Agent 可视化生成链路

4.1 第一步：定义 IR Schema，别一上来就写代码

很多人一上来就开始写渲染引擎，结果 IR 改来改去，引擎跟着重写，浪费大量时间。我的建议是：先花足够时间把 IR Schema 定下来，用文档和示例把它描述清楚，再动手写引擎。

定义 Schema 时，我一般会做三件事。第一，列出所有需要支持的产物类型，比如表格、表单、图表、流程图、卡片列表等，每种类型对应一个 IR 节点类型。第二，为每种类型定义必填字段和可选字段，必填字段是模型必须生成的，可选字段是引擎有默认值的。第三，写至少 3 个完整的 IR 示例，覆盖简单、中等、复杂三种场景，这些示例后面会直接用作 few-shot 的素材。

Schema 定义好之后，用 JSON Schema 或者类似的工具做校验。模型生成完 IR 之后，先过一遍校验，不通过就让它重试或者走修复流程。这一步能拦掉大部分低级错误。

4.2 第二步：设计 Prompt，把 Schema 和示例喂给模型

Prompt 的设计直接决定生成质量。我的经验是：System Prompt 里放 Schema 说明和约束，User Prompt 里放具体需求和 few-shot 示例。Schema 说明要用人话写，别直接贴 JSON Schema，模型对那种格式的理解不如自然语言。

一个有效的 Prompt 结构大概是这样：

你是一个可视化配置生成器。根据用户需求，生成符合以下结构的 JSON 配置。 支持的节点类型： ->