1. 为什么“让 AI 硬写”正在成为过去式过去一年我接触了不少做 Agent 项目的团队从两三个人的小作坊到几十人的中台组都有一个特别普遍的现象是大家一开始都倾向于让大模型直接输出最终产物。你要一个网页它吐 HTML你要一段流程它吐一大段自然语言描述你要一个数据查询它直接拼字符串。刚开始 demo 跑得挺爽一旦进入真实业务问题就全冒出来了——格式飘、字段缺、逻辑断、改一处崩三处最后维护成本高到没人愿意碰。这就是标题里说的“别再让 AI 硬写”。Agent 可视化生成方案的核心思路是把大模型的角色从“直接产出成品的写手”降级为“生成中间结构的规划者”再由一套确定性的渲染或执行引擎把中间结构变成最终产物。这个中间结构就是热词里反复出现的IRIntermediate Representation中间表示。围绕 IR往上可以定义DSL领域特定语言来描述业务语义往下可以封装SDK让前端或后端直接消费。整条链路串起来就是当前 Agent 生成方案最主流、也最稳的演进方向。这篇文章适合谁看如果你正在做 Agent 相关的产品不管是画图、搭流程、生成页面、生成查询还是做自动化编排只要你被“模型输出不稳定”折磨过那这篇就是写给你的。我会把方案选型背后的取舍、IR 该怎么设计、DSL 和 SDK 各自承担什么职责、可视化层怎么落地以及我踩过的坑全部摊开讲。基础一般的读者也能看懂因为我会尽量用生活化的类比有经验的读者可以直接跳到 IR 设计和实操部分抄作业。先说结论性的判断Agent 生成能力的上限不取决于模型多强而取决于你给它设计的中间结构有多好。模型是概率机器你让它自由发挥它就在概率空间里乱走你给它一个受约束的结构它就在你划定的轨道里跑。可视化生成方案的本质就是给概率机器修轨道。2. 方案整体设计与思路拆解2.1 从“端到端硬写”到“三段式生成”的范式转变传统的做法我称之为“端到端硬写”用户输入需求模型直接输出最终产物。比如用户说“帮我做一个销售数据看板”模型直接吐出一整页 HTML 加 JS。这个模式在 demo 阶段很惊艳但工程上几乎不可维护。原因有三第一产物是黑盒你无法对中间过程做校验和干预第二任何微调都要重新生成整份产物token 消耗大且结果不可复现第三模型对结构化约束的遵守能力有限字段名、层级、类型经常对不上。可视化生成方案把它拆成三段意图理解 → 结构生成 → 确定性渲染。第一段由模型完成把自然语言需求翻译成 IR第二段还是模型但输出的是受 schema 约束的结构化数据第三段完全交给代码由渲染引擎或执行引擎把 IR 变成最终产物。模型只负责它擅长的“理解和规划”确定性的部分交给确定性的代码。这个分工是整套方案的地基。我常拿装修打比方。硬写模式相当于你告诉装修师傅“我想要个温馨的家”然后他凭感觉给你砌墙铺砖出来的东西可能温馨也可能灾难。三段式相当于先出一张施工图纸IR图纸有标准图例和尺寸标注DSL 和 schema然后施工队严格按图纸施工渲染引擎。图纸可以反复改改完再施工成本可控结果可预期。2.2 IR 为什么是整个方案的心脏IR 这个词来自编译器领域。编译器不会把高级语言直接翻译成机器码中间要经过若干层中间表示每一层都做特定的优化和校验。Agent 生成借鉴了这个思路IR 是模型输出和最终产物之间的契约。一个好的 IR 要满足几个条件。首先是可校验能用 JSON Schema 或类似机制约束字段类型、必填项、枚举值模型输出后立刻能验证合法性。其次是可组合IR 的节点能嵌套、能引用、能复用这样复杂产物可以由简单结构拼出来。第三是可渲染IR 到最终产物的映射是纯函数式的同样的 IR 永远渲染出同样的结果。第四是可版本化IR 结构本身能迭代老版本能平滑迁移。为什么 IR 这么关键因为它是唯一能同时被模型和代码理解的东西。模型擅长生成结构化文本代码擅长处理结构化数据IR 正好卡在中间。你把 IR 设计好了模型输出的稳定性会大幅提升因为它的自由度被约束在 schema 里渲染层的复杂度也会下降因为它只需要处理有限的结构组合而不是无穷无尽的自然语言。2.3 DSL、SDK、可视化层三者的职责边界热词里 DSL 和 SDK 出现频率很高很多人容易把它们和 IR 混为一谈。我用一句话区分IR 是数据DSL 是描述数据的语言SDK 是操作数据的工具可视化层是展示和编辑数据的界面。DSL 是面向人的。它可能是一种简化的配置语法也可能就是一套约定好的 JSON 结构。它的价值在于让业务人员或非算法工程师也能读懂和修改生成逻辑。比如你定义一套“看板 DSL”里面用chart、filter、datasource这些关键词描述一个看板业务方看一眼就懂。SDK 是面向开发者的。它把 IR 的构造、校验、渲染、序列化封装成函数前端调render(ir)就能出图后端调execute(ir)就能跑流程。SDK 屏蔽了底层细节让接入成本降到最低。可视化层是面向最终用户的。它把 IR 用图形界面呈现出来用户能拖拽、能连线、能实时预览。可视化层和 IR 是双向绑定的用户操作界面生成 IRIR 变化驱动界面更新。这一层做得好不好直接决定产品体验。三者的关系可以这样理解DSL 是语法IR 是句子SDK 是笔可视化层是纸和编辑器。缺了任何一个整套方案都不完整。3. 核心细节解析与实操要点3.1 IR 结构设计的五个关键决策设计 IR 是整个项目里最需要想清楚的事我把它拆成五个决策点每个都直接影响后续开发难度。第一个决策扁平还是嵌套。扁平结构用 ID 引用关联嵌套结构直接父子包含。扁平的好处是易于 diff 和局部更新嵌套的好处是渲染时不用做引用解析。我的经验是节点数量少、层级浅的场景用嵌套节点多、需要频繁局部修改的场景用扁平。大多数可视化场景我推荐扁平加引用因为用户拖拽一个节点时你只需要改一个对象不用递归遍历整棵树。第二个决策强类型还是弱类型。强类型给每个字段定死类型弱类型用any兜底。强类型校验严格但扩展性差弱类型灵活但容易埋雷。折中方案是核心字段强类型扩展字段用metadata对象承载。比如一个图表节点type、dataSource、encoding强类型其他样式配置放style里弱类型。第三个决策如何表达数据流。流程类 Agent 的 IR 必须能表达节点间的依赖关系。常见做法是用inputs和outputs声明每个节点的输入输出端口用edges描述连接。这里要注意环检测可视化编辑器里用户很容易连出环IR 层必须能识别并报错。第四个决策版本兼容策略。IR 一定会迭代老数据怎么办我的做法是在 IR 顶层放version字段渲染 SDK 里维护一个迁移函数表从任意老版本迁移到当前版本。迁移函数要幂等跑多次结果一致。第五个决策错误如何表达。模型生成的 IR 可能不合法渲染时可能失败。IR 里要不要预留错误字段我的建议是 IR 本身保持纯净错误信息放在校验结果对象里和 IR 分离。这样 IR 可以缓存、可以持久化错误信息是临时的。3.2 用 Schema 约束模型输出把幻觉关进笼子模型输出 IR 时最大的问题是幻觉编造不存在的字段、用错枚举值、漏掉必填项。解决办法是用 JSON Schema 做约束配合结构化输出能力。具体操作上我会先定义一份完整的 schema然后用它生成给模型的提示词。提示词里明确列出所有字段、类型、枚举值、必填项并给一两个示例。模型返回后用校验库比如 ajv验证不通过就带着错误信息重试。重试次数设上限比如三次三次还不行就降级到人工或默认模板。这里有个实操技巧把 schema 拆成小块喂给模型。一次性给几百个字段的 schema模型很容易漏。我会按节点类型拆分生成某个节点时只给它相关的子 schema。这样准确率能提升不少。另一个技巧是用枚举代替自由文本。凡是取值有限的字段一律用枚举。比如图表类型只允许line、bar、pie模型就不会编出curve这种不存在的值。枚举值要在提示词里列全并说明每个值的适用场景。3.3 渲染引擎的确定性保证渲染引擎是整套方案里唯一不允许有概率性的部分。同样的 IR 输入必须永远得到同样的输出。要做到这点有几个原则。原则一渲染函数无副作用。渲染过程中不读全局状态、不依赖时间、不依赖随机数。所有需要的上下文都通过参数传入。原则二渲染顺序确定。如果 IR 里有多个节点渲染顺序必须明确。要么按数组顺序要么按显式的order字段不能依赖对象键的遍历顺序。原则三失败要可定位。渲染失败时错误信息要精确到哪个节点、哪个字段、期望什么、实际什么。我见过太多渲染引擎报一句“渲染失败”就完事排查起来要命。原则四支持增量渲染。用户改一个节点不应该重渲染整棵树。IR 的扁平结构配合节点级 diff可以做到只重渲染变化的子树。这对大看板场景是刚需。3.4 可视化编辑器的双向绑定实现可视化编辑器是用户体验的核心难点在于界面和 IR 的双向同步。用户拖一个组件到画布IR 要新增节点用户改 IR比如通过代码编辑器画布要更新。实现上我推荐单一数据源模式IR 是唯一真相界面是 IR 的投影。用户操作界面时先算出新的 IR再让界面根据新 IR 重绘。不要反过来让界面状态和 IR 各存一份那样同步逻辑会变成噩梦。具体到技术选型前端可以用状态管理库如 Zustand、Pinia持有 IR界面组件订阅 IR 的切片。IR 更新走不可变数据模式每次生成新对象方便做 diff 和撤销重做。撤销重做栈里存的是 IR 快照不是界面状态这样跨会话也能恢复。4. 实操过程与核心环节实现4.1 从零定义一套看板 DSL 的完整过程我拿一个真实做过的看板生成项目举例把从 DSL 定义到渲染落地的全过程走一遍。第一步是梳理业务语义。看板的核心概念有哪些数据源、图表、筛选器、布局容器、联动规则。每个概念有哪些属性图表有类型、维度、度量、样式筛选器有字段、操作符、默认值。把这些列成清单就是 DSL 的词汇表。第二步是定义 IR 结构。我采用扁平加引用的方式顶层是nodes数组和edges数组。每个节点有id、type、props、position。props里放该类型特有的配置。边描述节点间的数据流或联动关系。{ version: 1.0, nodes: [ { id: n1, type: datasource, props: { table: sales, fields: [date, amount] } }, { id: n2, type: chart, props: { chartType: line, encoding: { x: date, y: amount } } } ], edges: [ { from: n1, to: n2, kind: data } ] }第三步是写 schema。用 JSON Schema 描述上面的结构枚举值列全必填项标清楚。这份 schema 既用于校验模型输出也用于编辑器里的表单生成。第四步是实现渲染 SDK。核心是一个render(ir, container)函数遍历节点按类型分发到对应的渲染器。每个渲染器负责把props变成实际的 DOM 或图表实例。边用于建立数据订阅源节点数据变化时通知目标节点。第五步是接入模型生成。把 schema 转成提示词让模型根据用户需求生成 IR。生成后校验通过则渲染不通过则带错误重试。4.2 模型生成 IR 的提示词工程细节提示词写得好不好直接决定 IR 生成的成功率。我的模板结构是这样的先给角色设定再给任务说明然后给 schema 摘要接着给示例最后给约束和输出格式要求。角色设定要具体“你是一个看板配置生成助手负责把用户的自然语言需求转换成符合 schema 的 JSON 配置。”任务说明要明确输入输出“用户会描述他们想要的看板你输出一个 JSON 对象不要输出任何解释文字。”schema 摘要不要贴完整 schema太长。我会提炼成人类可读的字段说明比如“chartType 字段可选值为 line、bar、pie分别代表折线图、柱状图、饼图”。示例给一到两个覆盖常见场景。约束里强调“只输出 JSON不要 markdown 代码块包裹不要注释”。实测下来这套模板在主流模型上的首次通过率能到七成左右重试一次能到九成。剩下的长尾靠人工兜底或默认模板。4.3 前端 SDK 的封装与接入SDK 的封装目标是让接入方三行代码跑起来。我设计的接口是这样的import { createRenderer } from dashboard-sdk; const renderer createRenderer({ container: #app }); renderer.render(ir); renderer.on(nodeClick, (nodeId) { /* ... */ });内部实现上createRenderer负责初始化容器、注册渲染器、建立事件总线。render接收 IR做校验、diff、增量更新。事件系统让接入方能监听节点交互。SDK 要处理几个边界情况容器不存在、IR 不合法、渲染器缺失。这些都要给出清晰的错误提示而不是静默失败。另外 SDK 要支持销毁renderer.destroy()清理事件监听和 DOM避免内存泄漏。4.4 后端执行引擎的对接如果 Agent 生成的不只是展示型看板还有可执行的流程那后端需要一个执行引擎。执行引擎接收 IR按拓扑排序依次执行节点把上游输出传给下游。执行引擎的关键是幂等和可重入。同一个 IR 执行多次结果一致中途失败能从断点恢复。实现上给每个节点执行结果加缓存key 是节点 ID 加输入哈希。输入没变就复用缓存输入变了才重跑。节点执行要设超时和重试。外部依赖数据库、API不稳定是常态超时设合理值重试带退避。失败节点的错误要记录到执行日志方便排查。5. 常见问题与排查技巧实录5.1 模型输出格式飘忽的排查思路这是最高频的问题。模型有时候输出纯 JSON有时候包在 markdown 代码块里有时候前面加一句“好的这是配置”。排查步骤先看提示词有没有明确禁止这些行为再看用的模型是否支持结构化输出模式。如果模型支持直接开启强制 JSON 模式能解决八成问题。如果不支持就在解析前做清洗用正则剥掉代码块标记和前后缀文字。还有个隐蔽的坑模型输出的 JSON 里有尾随逗号或单引号标准解析器会报错。我会在解析前用宽松解析库或者先做一次字符串替换。更稳的做法是让模型输出后用 schema 校验校验失败的信息回传给模型让它修正。5.2 IR 校验失败的典型场景与修复我整理了一张常见校验失败对照表基本覆盖了实际项目里九成的情况。失败类型典型表现根因修复方式字段缺失缺少必填的 type模型漏生成提示词强调必填项重试类型错误position 给了字符串模型理解偏差schema 里给类型示例枚举越界chartType 给了 curve枚举值没列全提示词列全枚举并解释引用悬空edge 指向不存在的 id模型编造 id校验后自动清理或重试循环依赖节点 A 依赖 BB 依赖 A模型逻辑错误拓扑排序检测报错重试修复策略上能自动修的就自动修比如悬空引用直接删掉不能自动修的带错误重试重试还不行就降级。5.3 渲染性能问题的定位与优化大看板场景下渲染卡顿很常见。定位方法先用性能面板看耗时分布是渲染函数慢还是 DOM 操作多。如果是渲染函数慢多半是每次全量重渲染改成增量渲染。如果是 DOM 操作多用虚拟化或 canvas 替代。我踩过的一个坑是IR 里节点顺序不稳定导致每次 diff 都认为全变了。后来在 IR 生成时对节点按 id 排序diff 就准了。还有个坑是事件监听没解绑节点删了监听还在内存一路涨。SDK 里要严格管理生命周期。5.4 可视化编辑器里用户误操作的防护用户在看板上乱拖乱连是常态。防护措施分几层拖拽时限制可放置区域连线时校验类型兼容删除节点时提示影响范围。IR 层要做环检测和悬空引用检测不合法就拒绝更新并提示。撤销重做是刚需。每次 IR 变更前存快照栈深度设上限比如五十步。快照存 IR 的深拷贝不要存引用。恢复时用快照替换当前 IR界面自动重绘。6. 我在这条路上踩过的几个真实坑第一个坑是过早优化 IR 结构。项目初期我想设计一套能覆盖所有场景的通用 IR结果结构复杂到模型根本生成不对。后来砍掉一半字段只保留核心概念生成成功率立刻上来了。IR 要跟着业务长不要一开始就追求大而全。第二个坑是忽视 schema 的可读性。schema 是给模型看的也是给开发者看的。字段名用缩写、嵌套层级过深都会让模型和人都懵。后来我强制字段名用完整单词嵌套不超过三层维护成本降了很多。第三个坑是渲染层和 IR 层耦合。早期渲染器直接读 IR 的原始字段IR 一改渲染器就崩。后来加了一层适配器渲染器只依赖适配后的视图模型IR 怎么变都不影响渲染逻辑。这层解耦看着多余实际省了大量重构时间。第四个坑是没有给模型留退路。模型生成失败时直接报错给用户体验很差。后来加了默认模板兜底生成失败就用一个通用看板模板用户至少能看到东西再手动调整。这个兜底策略把用户投诉降了一大截。这套方案我前后迭代了三个版本从最初的硬写到现在稳定的三段式最大的体会是Agent 生成的质量七分靠结构设计三分靠模型能力。你把 IR 和 schema 设计好了换个弱一点的模型也能跑结构设计烂再强的模型也救不回来。所以如果你正准备做 Agent 生成相关的项目先把 IR 想清楚再动手写代码这一步省不得。