企业官网建设流程全解析

1. 为什么“让 AI 硬写”这条路越来越走不通

过去一年我接手过好几个 Agent 项目，从最早的“给个大模型加几个工具函数”到后来动辄几十个节点、上百条分支的复杂编排，踩的坑基本都指向同一个问题：让模型直接生成最终产物，短期看着惊艳，长期维护就是灾难。

所谓“硬写”，就是用户丢一句需求，模型从头到尾把代码、配置、流程一次性吐出来。Demo 阶段确实爽，但一旦进入真实业务，问题立刻暴露：同一个需求跑十次，十次结果都不一样；改一个字段，整段逻辑重写；想加个校验节点，发现模型把校验逻辑和业务逻辑揉在一起，拆都拆不开。更别提多人协作时，A 生成的流程 B 根本看不懂，交接成本比重新写还高。

这就是Agent 可视化生成方案要解决的核心矛盾。它的思路不是让模型“写得更准”，而是把模型的输出从“最终产物”降级为“中间表示”，再由确定性的引擎把中间表示渲染成可执行的东西。这个中间表示，就是热词里反复出现的IR（Intermediate Representation，中间表示），而描述这套中间表示的语言，就是DSL（Domain Specific Language，领域特定语言）。前端拿到 IR 之后负责画图、连线、预览，这套给前端用的工具包就是SDK。

一句话概括：Agent 可视化生成 = 模型产出 IR/DSL + 引擎确定性渲染 + SDK 负责交互与展示。模型只负责“理解意图并翻译成结构化描述”，剩下的布局、连线、校验、执行全部交给确定性代码。这样既保留了自然语言的灵活性，又把不确定性关进了笼子里。

这套方案适合谁？如果你正在做 Agent 编排平台、低代码流程工具、AI 工作流产品，或者你手上有大量“模型生成的东西没法维护”的存量项目，那这套思路基本是绕不开的。哪怕你只是想让 Agent 帮你画个流程图、生成个配置面板，理解 IR 和 DSL 的分层也能让你少走很多弯路。

下面我按实际落地顺序，把这套方案拆开讲透。

2. 整体架构设计：模型、IR、引擎、SDK 各管什么

2.1 四层职责划分，先把边界划清楚

很多团队做 Agent 可视化失败，根子在于职责没分清，模型既当翻译又当渲染还当执行，最后谁都不好改。我习惯把它拆成四层，每层只干一件事：

这张表是我踩了无数坑之后总结的。关键点在于：模型只碰意图层，绝不碰渲染层。模型输出的 IR 哪怕格式有点小瑕疵，也能通过校验层兜住；但如果让模型直接生成 SVG 坐标或者 React 组件，那基本没法维护。

2.2 为什么选 IR 而不是让模型直接出图

有人会问，现在多模态模型这么强，直接让它输出图片或者 HTML 不行吗？我实测过，短期可以，长期不行，原因有三个。

第一，不可编辑。模型生成的图片是像素，用户想改一个节点位置，只能重新生成，改完可能整个布局都变了。而 IR 是结构化的，改一个字段只影响那一个节点。

第二，不可校验。图片没有语义，你没法判断“这个流程有没有环”“这个节点的输入有没有连上”。IR 是带类型的树或图结构，校验规则可以写成代码，跑一遍就知道哪里有问题。

第三，不可版本化。IR 是文本，可以进 Git，可以 diff，可以回滚。图片和一次性生成的代码做不到这一点。热词里有个“dify 导入 dsl 文件提示版本不兼容”，这恰恰说明 DSL 作为文本格式是可以做版本管理的，虽然版本兼容是个麻烦事，但至少你有得管。

2.3 IR 和 DSL 的关系，别搞混了

这两个词经常被混用，我按自己的理解说清楚：DSL 是描述 IR 的语言，IR 是 DSL 解析后的内存对象。打个比方，DSL 是 JSON 文本，IR 是 JSON.parse 之后的对象。DSL 负责“可读可写可传输”，IR 负责“可操作可校验可渲染”。

实际项目里，DSL 通常设计成 JSON 或 YAML，因为这两种格式生态好、工具多、前端解析方便。也有用自定义语法的，比如类似 Mermaid 的文本描述，但自定义语法需要自己写 parser，维护成本高，除非你有特殊需求，否则不建议。

一个典型的 Agent 流程 DSL 大概长这样：

{ "version": "1.0", "nodes": [ { "id": "n1", "type": "llm", "params": { "model": "gpt-4", "prompt": "{{input}}" } }, { "id": "n2", "type": "tool", "params": { "name": "search", "query": "{{n1.output}}" } } ], "edges": [ { "from": "n1", "to": "n2" } ] }

这个结构简单到模型很容易生成，同时引擎解析起来毫无歧义。节点类型、参数、连线关系全部显式声明，模型不需要关心布局，引擎拿到之后自动算坐标、画连线。

2.4 SDK 在前端到底承担什么

热词里“前端 SDK”出现频率很高，这里说的 SDK 不是给后端调用的，而是给前端画布用的工具包。它至少要提供这几个能力：

• 解析与序列化：DSL 文本和 IR 对象互转，处理版本兼容。
• 布局计算：拿到节点和边，自动算出每个节点的坐标，支持分层、力导向等布局算法。
• 渲染与交互：把节点画成卡片，边画成连线，支持拖拽、缩放、选中、删除。
• 校验反馈：实时检查 IR 合法性，把错误标红显示在画布上。
• 回写：用户拖完节点，SDK 把新坐标写回 IR，保证 IR 始终是最新状态。

我见过有团队把布局算法写在后端，前端只负责画，结果每次拖拽都要请求后端，体验极差。正确做法是布局和交互全在前端 SDK 里，后端只负责存储和校验。

3. 核心细节解析：DSL 设计、IR 校验与模型约束

3.1 DSL 设计的三条铁律

设计 DSL 是整个方案里最考验功力的一步，我总结了三条铁律，违反任何一条后面都会痛苦。

第一条：节点类型要收敛，不要开放式。早期我图省事，让模型自由发挥节点类型，结果出现了几十种五花八门的类型，引擎根本没法统一渲染。后来改成枚举，只允许llm、tool、condition、loop、input、output这几种，模型只能在参数上发挥，类型必须从枚举里选。这一下就把不确定性砍掉了一大半。

第二条：参数用 schema 约束，不要自由文本。每个节点类型的参数结构提前定义好 JSON Schema，模型生成的时候按 schema 填。比如llm节点必须有model和prompt，tool节点必须有name和params。schema 之外的多余字段直接丢弃，缺失的必填字段报错。

第三条：连线只表达数据流，不表达控制流的复杂语义。早期我把条件分支、循环、异常处理全塞进边里，结果边变得极其复杂。后来改成：边只表示“A 的输出给 B 的输入”，条件分支用condition节点加多条出边表达，循环用loop节点包裹子图。这样边永远是简单的有向连接，渲染和校验都简单。

3.2 IR 校验层：把模型的错误挡在渲染之前

模型生成的东西一定会有错，这是概率模型的本质决定的，不要指望它百分百正确。所以校验层是必须的，而且要在渲染之前跑。

校验分三级：

• 语法级：DSL 是不是合法 JSON/YAML，字段类型对不对。这一级用 JSON Schema 就能搞定。
• 语义级：节点 ID 有没有重复，边的两端节点存不存在，有没有形成环（除非是 loop 节点允许的环），必填参数有没有缺。这一级要写代码遍历 IR 图。
• 业务级：比如某个 tool 节点引用的工具在系统里存不存在，某个 model 名称是不是支持的。这一级依赖具体业务，通常查数据库或配置。

校验失败怎么办？我的做法是不直接报错给用户，而是把错误信息回传给模型，让它自己修。这就是所谓的“自修复循环”：模型生成 IR → 校验 → 失败则把错误喂回模型 → 模型重新生成 → 再校验，最多循环三次。实测下来，第一次生成大概有六成能过，循环三次之后能到九成以上。剩下的一成确实修不好，就展示给用户手动改。

注意：自修复循环一定要设上限，否则模型可能陷入死循环，反复生成同样的错误。三次是我的经验值，再多收益递减。

3.3 怎么约束模型稳定输出 IR

光有校验还不够，得从源头让模型尽量少犯错。我用了这几个手段：

用 few-shot 示例。在 prompt 里塞三到五个高质量的 IR 示例，覆盖常见节点类型和连线模式。模型看到示例之后，输出格式的稳定性明显提升。示例要精选，不要塞太多，否则 prompt 太长反而稀释注意力。

用结构化输出。如果模型支持 JSON mode 或者 function calling，一定要开。这能从解码层面保证输出是合法 JSON，省掉语法级校验的一大半工作。

用固定模板。对于常见需求，比如“帮我做一个搜索加总结的流程”，可以预置模板，模型只需要填参数，不需要从零生成结构。模板覆盖率越高，稳定性越好。

用温度调低。生成 IR 这种结构化任务，温度调到 0 到 0.3 之间，不要用默认的 0.7。温度越低，输出越稳定，虽然创造性下降，但 IR 生成本来就不需要创造性。

3.4 版本兼容：DSL 演进绕不开的坎

热词里“dify 导入 dsl 文件提示版本不兼容”是个典型问题。DSL 一旦发布，就会有存量文件，你改格式就会破坏兼容。我的做法是：

• DSL 里必须带 version 字段，每次不兼容变更就升版本号。
• 写迁移函数，从旧版本升到新版本。比如migrate_v1_to_v2(ir)，把旧字段映射到新字段。
• 导入时先读 version，再决定要不要迁移。迁移完再校验，校验通过才渲染。

迁移函数要写单元测试，每个历史版本都要有对应的测试用例。这块工作很枯燥，但不做的话，用户存的老流程全打不开，口碑直接崩。

4. 实操过程：从零搭一个可视化生成的最小闭环

4.1 环境准备与技术选型

我按最小可用原则选型，不追求花哨：

• 前端画布：React + 一个图编辑库。图编辑库的选择很关键，要支持自定义节点、自定义边、布局算法、事件系统。我试过几个，最后选的是社区活跃、文档全的那个，具体名字不点了，你按“支持自定义节点 + 自动布局 + TypeScript”这三个条件去筛就行。
• 布局算法：分层布局（DAG 用）和力导向布局（通用）各备一个。分层布局适合有明确上下游的流程，力导向适合关系复杂的图。
• 后端：任意语言都行，我用的 Node.js，因为和前端共享 TypeScript 类型定义，IR 的类型两边复用，省很多事。
• 模型调用：走标准 API，开 JSON mode。

4.2 定义 IR 的 TypeScript 类型

先把类型定下来，这是整个项目的契约。前后端共享这份类型，任何改动都要同步。

type NodeType = 'input' | 'output' | 'llm' | 'tool' | 'condition' | 'loop'; interface IRNode { id: string; type: NodeType; params: Record<string, unknown>; position?: { x: number; y: number }; } interface IREdge { from: string; to: string; fromPort?: string; toPort?: string; } interface IR { version: string; nodes: IRNode[]; edges: IREdge[]; }

注意position是可选的。模型生成的时候不需要给坐标，坐标由前端布局算法算。用户拖拽之后，SDK 把坐标写回 IR，这时候position才有值。这样模型和布局解耦，模型不用操心坐标。

4.3 写校验函数

校验函数是纯函数，输入 IR，输出错误列表。我按三级校验写：

function validateIR(ir: IR): string[] { const errors: string[] = []; const ids = new Set<string>(); for (const node of ir.nodes) { if (ids.has(node.id)) { errors.push(`节点 ID 重复: ${node.id}`); } ids.add(node.id); if (!isValidNodeType(node.type)) { errors.push(`未知节点类型: ${node.type}`); } const schemaErrors = validateParams(node.type, node.params); errors.push(...schemaErrors); } for (const edge of ir.edges) { if (!ids.has(edge.from)) { errors.push(`边起点不存在: ${edge.from}`); } if (!ids.has(edge.to)) { errors.push(`边终点不存在: ${edge.to}`); } } if (hasCycle(ir) && !hasLoopNode(ir)) { errors.push('流程存在环，但没有 loop 节点'); } return errors; }

hasCycle用 DFS 实现，hasLoopNode检查有没有 loop 类型节点。这段代码不长，但能挡住绝大多数模型生成的错误。

4.4 自修复循环的实现

自修复循环是模型和校验之间的桥梁，逻辑如下：

async function generateIR(userInput: string): Promise<IR> { let prompt = buildPrompt(userInput); for (let i = 0; i < 3; i++) { const raw = await callModel(prompt); const ir = parseIR(raw); const errors = validateIR(ir); if (errors.length === 0) { return ir; } prompt = buildRepairPrompt(userInput, raw, errors); } throw new Error('三次修复后仍无法生成合法 IR'); }

buildRepairPrompt把原始输入、上次生成的 IR、错误列表一起塞给模型，让它针对性修复。实测这个循环能把成功率从六成提到九成以上。

4.5 前端渲染与交互

前端拿到合法 IR 之后，先跑布局算法算坐标，再渲染。布局算法我推荐分层布局，因为 Agent 流程大多是 DAG，分层布局出来的图最清晰。

渲染时每个节点类型对应一个自定义组件，llm节点显示模型名和 prompt 摘要，tool节点显示工具名，condition节点显示条件表达式。边用贝塞尔曲线，带箭头。

交互上至少支持：拖拽节点（拖完写回 position）、删除节点（同时删相关边）、新增边（拖拽端口连线）、缩放画布、框选。这些是基础，缺一个用户都会觉得难用。

4.6 回写与持久化

用户每次操作完，SDK 把最新 IR 序列化成 DSL 文本，存到后端。存的时候带上 version 和更新时间。下次打开时，先读 version，需要迁移就迁移，然后校验，校验通过再渲染。

这里有个细节：不要每次拖拽都存，太频繁。我的做法是防抖，用户停止操作 500ms 后再存。这样既保证不丢数据，又不会把后端打爆。

5. 常见问题与排查技巧实录

5.1 模型生成的 IR 总是缺字段怎么办

这是最常见的问题。我的排查顺序是：先看 prompt 里的 schema 描述够不够清楚，再看 few-shot 示例里有没有覆盖这个字段，最后看是不是模型能力不够。

如果 schema 描述清楚、示例也有，模型还是缺，那大概率是模型能力问题，换个更强的模型，或者把必填字段在 prompt 里用加粗强调。我试过在 prompt 里写“以下字段必须提供，缺失会导致校验失败：model, prompt”，效果比单纯列 schema 好。

5.2 布局出来的图重叠严重怎么调

分层布局重叠通常是层间距和节点间距设太小。调大这两个参数，一般能解决。如果还是重叠，检查是不是有节点没有正确分层，比如孤立节点被分到了同一层。

力导向布局重叠的话，调大斥力参数，或者增加迭代次数。力导向布局计算量大，节点多了会卡，超过 50 个节点建议换分层布局。

5.3 用户拖拽后 IR 和画布不同步

这是 SDK 状态管理的问题。常见原因是画布状态和 IR 状态各存一份，拖拽只更新了画布没更新 IR。正确做法是单一数据源：IR 是唯一真相，画布是 IR 的渲染结果。拖拽时先更新 IR，再触发重渲染。这样永远不会不同步。

5.4 版本迁移后老流程打不开

迁移函数写漏了字段，或者迁移顺序错了。排查方法是拿一个老版本的 DSL 文件，手动跑迁移函数，看输出对不对。每个历史版本都要有测试用例，CI 里跑一遍，防止改坏。

5.5 常见问题速查表

5.6 几个我踩过的坑

坑一：让模型生成坐标。早期我让模型直接给节点坐标，结果每次生成的布局都不一样，而且经常重叠。后来改成模型只给结构，坐标由前端算，问题消失。

坑二：DSL 用自定义语法。一开始觉得 JSON 太啰嗦，设计了一套类似 Mermaid 的简洁语法，结果 parser 写了一周，还各种边界情况。后来换回 JSON，半天搞定。除非有强需求，否则别造语法。

坑三：校验只做语法级。只校验 JSON 合法性，不校验语义，结果模型生成了引用不存在节点的边，渲染时直接崩。语义校验必须做。

坑四：自修复不设上限。有一次模型陷入死循环，反复生成同样的错误 IR，把 API 额度跑光了。后来加了三次上限，问题解决。

坑五：迁移函数没测试。改了一次 DSL 格式，迁移函数写漏了一个字段，导致所有老流程打不开。后来每个版本都加测试用例，再没出过问题。

6. 进阶方向：让可视化生成更稳更快

6.1 模板加模型混合生成

纯模型生成稳定性有上限，纯模板又不够灵活。我的做法是混合：常见需求走模板，模型只填参数；模板覆盖不到的需求才走全量生成。这样既保证常见场景的稳定性，又保留灵活性。模板库可以随着使用逐步积累，越用越稳。

6.2 IR 缓存与增量生成

同一个用户反复生成类似流程时，可以缓存 IR 片段。比如用户已经生成过一个搜索节点，下次生成时直接复用，只生成新增部分。这样既快又稳。缓存 key 可以用节点类型加参数摘要。

6.3 多模型投票

对稳定性要求极高的场景，可以同时调多个模型生成 IR，然后投票选最合法的那个。成本翻倍，但成功率能再提一截。适合关键流程，不适合高频调用。

6.4 把校验规则做成可配置

不同业务对 IR 的约束不一样，把校验规则做成配置，业务方自己加规则，不用改代码。比如某个业务要求所有 llm 节点必须指定 model，另一个业务不要求，配置一下就行。

6.5 可视化调试面板

给开发者一个调试面板，能看到模型原始输出、校验错误、修复过程、最终 IR。排查问题时非常有用，不用去翻日志。这个面板我强烈建议做，投入不大，收益很高。

7. 我在实际项目中的几点体会

这套方案我从第一个版本到现在迭代了大概七八次，最大的体会是：别指望模型一步到位，要把模型当成一个“会犯错但能改”的翻译官，而不是“一次成型”的生成器。IR 和校验层就是给模型兜底的安全网，网织得越密，模型能犯的错越少。

另一个体会是DSL 的设计要克制。我早期总想设计一个“什么都能表达”的 DSL，结果越设计越复杂，模型学不会，引擎也难解析。后来砍到只剩六种节点类型，反而好用了。DSL 的表达能力不是越强越好，够用就行，剩下的交给引擎和业务代码。

还有一点，前端 SDK 的体验决定用户留存。用户不关心你 IR 设计得多优雅，他们只关心拖拽顺不顺手、连线好不好连、预览快不快。SDK 的交互细节要反复打磨，这块投入再多都值得。

最后分享一个小技巧：如果你刚开始做，别一上来就追求全自动生成。先做“模型生成 + 用户手动调整”的半自动模式，让用户能改，你也能从用户的修改里学到模型哪里做得不好，反过来优化 prompt 和校验规则。等模型稳定了，再逐步减少手动环节。这个渐进路径比一步到位靠谱得多。