Agent可视化生成方案：用IR中间表示替代AI硬写，降低幻觉与Token消耗

1. 为什么“让 AI 硬写”正在被淘汰

过去一年我接触了不少 Agent 项目，从最早的“给个大模型加个 while 循环”到后来各种框架满天飞，踩过的坑比写过的代码还多。最直观的感受是：让 AI 直接输出最终产物，在简单场景下能跑通，一旦进入真实业务就崩得稀里哗啦。比如让模型直接生成一段复杂的前端页面代码，它可能给你吐出一堆看似合理但根本跑不起来的 JSX；让它直接生成一份数据分析报告，数字和结论经常对不上。这不是模型不够强，而是缺少中间表示层——也就是 IR（Intermediate Representation）的思路。

所谓“Agent 可视化生成方案”，核心逻辑是：不让 AI 从零硬写最终产物，而是让 AI 生成一种结构化的中间描述，再由确定性的渲染引擎或代码生成器把中间描述转成最终结果。这个中间描述可以是 JSON Schema、DSL、节点图、甚至是一组带约束的指令序列。AI 只负责“决策”和“编排”，不负责“精确渲染”。这样做的好处非常明显：输出可控、可校验、可回滚、可局部修改，而且能大幅降低 token 消耗和幻觉概率。

这篇文章适合谁看？如果你正在做 Agent 开发、低代码平台、自动化报告生成、可视化搭建工具，或者单纯对“AI 怎么才能稳定干活”感兴趣，那接下来的内容应该能帮你省下不少试错时间。我会从架构设计、IR 设计、SDK 封装、实操步骤、常见坑几个角度，把“可视化生成”这条路讲透。全程不堆术语，尽量用我实际项目里的例子来说明。

2. 核心思路拆解：AI 只做它擅长的事

2.1 硬写模式为什么容易翻车

先说说“硬写”到底指什么。典型场景是：用户输入一句话需求，Agent 直接把这句话拼进 prompt，然后让大模型输出最终代码、最终文案、最终配置。这种模式在 demo 阶段很爽，因为链路短、开发快。但一旦上生产，问题就集中爆发：

• 输出不稳定：同一个需求跑两次，结果结构可能完全不同，前端没法做兜底渲染。
• 无法局部修改：用户说“把第三段改一下”，模型可能把整篇重写，改完还引入了新错误。
• 校验成本高：生成的是自然语言或大段代码，想校验正确性只能靠人眼或再跑一遍测试。
• token 浪费严重：每次修改都要重新生成全部内容，长文档场景下成本线性上涨。
• 幻觉不可控：模型会“编”出不存在的 API、不支持的属性、错误的数值。

我做过一个实验：让模型直接生成一份包含 20 个数据卡片的仪表盘 HTML。第一次生成了 1800 token，第二次生成了 2400 token，两次的 DOM 结构差异超过 40%。后来改成“先生成卡片配置 JSON，再渲染”，JSON 稳定在 400 token 左右，结构完全一致，只有数据值不同。这个对比非常说明问题。

2.2 可视化生成的核心分层

可视化生成方案的本质是把“生成”拆成两层：

1. 决策层：由 AI 完成。输入是用户意图、上下文、可用组件列表，输出是结构化的中间表示（IR）。这一层允许模糊、允许概率性，但输出格式必须严格约束。
2. 渲染层：由确定性代码完成。输入是 IR，输出是最终产物（HTML、PDF、图片、代码文件等）。这一层不允许有随机性，同样的 IR 必须得到同样的结果。

这两层之间通过Schema 契约连接。Schema 定义了“AI 能说什么”，渲染层只认 Schema 里的字段。AI 如果输出了 Schema 之外的字段，直接丢弃或报错，不会污染最终结果。

提示：Schema 的设计质量直接决定整个方案的稳定性。Schema 太松，AI 乱输出；Schema 太紧，AI 表达受限。建议从最小可用字段集开始，逐步扩展。

2.3 为什么 IR 比直接输出更省 token

很多人以为多一层转换会增加成本，实际恰恰相反。原因在于：

• AI 生成 IR 时，不需要考虑样式细节、不需要重复输出模板代码、不需要处理转义字符。
• IR 通常比最终产物短一个数量级。比如一个图表，最终 SVG 可能几千字符，IR 只需要{type: "bar", data: [...], x: "month", y: "sales"}。
• 修改时只改 IR 的局部字段，不需要重新生成整个产物。

我实测过一个报表场景：直接生成 HTML 平均 3200 token/次，生成 IR 平均 380 token/次，渲染层零 token。按每天 1000 次生成算，一个月能省下相当可观的调用成本。而且 IR 可以缓存、可以 diff、可以版本管理，工程上友好太多。

2.4 适用场景与边界

可视化生成不是万能药。它最适合的场景是：输出结构相对固定、组件可枚举、样式可模板化。比如：

• 数据仪表盘、报表、看板
• 表单、问卷、配置页面
• 流程图、思维导图、组织架构图
• 邮件模板、通知卡片、营销落地页
• 代码脚手架、配置文件、API 定义

不太适合的场景是：高度创意性、每次结构都不同、没有可复用组件的内容，比如写小说、写诗、生成完全自由的艺术图。这些场景 IR 反而会限制表达。所以选型时要先判断：你的业务输出能不能被“组件化描述”？能，就上可视化生成；不能，就老老实实让模型自由发挥，但要做好后处理。

3. IR 设计与 SDK 封装实操

3.1 IR 的三种常见形态

根据项目复杂度，IR 可以设计成不同形态。我按从简到繁列一下：

大多数业务场景用树形 JSON就够了。比如一个页面可以描述成：

{ "type": "page", "children": [ { "type": "header", "props": { "title": "销售月报", "level": 1 } }, { "type": "chart", "props": { "chartType": "bar", "data": [ { "month": "1月", "sales": 120 }, { "month": "2月", "sales": 180 } ], "xField": "month", "yField": "sales" } } ] }

这个 IR 里没有任何样式信息，样式由渲染层的组件默认值决定。AI 只需要关心“放什么组件、传什么数据”，不需要关心“颜色是 #1890ff 还是 #1677ff”。

3.2 Schema 约束怎么写才不坑

Schema 是 AI 和渲染层之间的合同。写 Schema 有几个实操要点：

• 用 JSON Schema 或 Zod 定义，不要用自然语言描述。自然语言描述 AI 会理解偏。
• 枚举字段必须给全。比如chartType只能是bar、line、pie，不要写“其他类型也可以”。
• 必填字段要明确。缺了必填字段，渲染层直接报错，不要给默认值兜底，否则 AI 会学会偷懒。
• 嵌套深度限制。建议不超过 5 层，太深了 AI 容易漏字段，渲染也容易出问题。
• 给每个字段写 description。这个 description 会进 prompt，帮 AI 理解字段含义。

我见过一个反例：Schema 里props是object类型，没有进一步约束。结果 AI 往里塞了各种奇怪字段，渲染层只能全部忽略，最后页面空白。后来改成props按组件类型分别定义，问题立刻消失。

3.3 SDK 封装：让渲染层可复用

渲染层建议封装成独立 SDK，和 Agent 逻辑解耦。SDK 的职责很纯粹：

1. 接收 IR
2. 校验 IR 是否符合 Schema
3. 按组件注册表查找对应渲染器
4. 递归渲染成最终产物
5. 返回产物和错误信息

SDK 的接口可以设计成：

import { Renderer } from 'visual-agent-sdk'; const renderer = new Renderer({ components: { page: PageComponent, header: HeaderComponent, chart: ChartComponent }, strict: true }); const result = renderer.render(ir); // result: { output: '<html>...</html>', errors: [] }

strict: true表示遇到未知组件直接报错，不静默跳过。这个开关在开发阶段非常有用，能快速发现 AI 输出了不存在的组件。

注意：SDK 不要依赖任何 AI 相关库。它应该是一个纯函数式的渲染器，输入 IR 输出产物。这样你可以单独测试它，也可以在不同 Agent 之间复用。

3.4 组件注册表的设计

组件注册表是 SDK 的核心数据结构。每个组件需要定义：

• type：唯一标识，和 IR 里的 type 对应
• schema：该组件的 props 校验规则
• render：渲染函数，接收 props 和 children，返回产物片段
• defaultProps：可选，默认属性

注册表可以用 Map 或普通对象实现。关键是要支持动态注册，这样业务方可以按需扩展组件，不用改 SDK 源码。

renderer.registerComponent({ type: 'chart', schema: z.object({ chartType: z.enum(['bar', 'line', 'pie']), data: z.array(z.record(z.any())), xField: z.string(), yField: z.string() }), render: (props, children) => { return `<div class="chart"># 渲染层 npm init -y npm install zod # Agent 层 pip install openai jsonschema

如果要做可视化预览，可以加一个简单的 HTTP 服务：

npm install express

实际项目中，渲染层可以跑在浏览器里，也可以跑在 Node 服务端。跑在服务端的好处是产物可以直接存文件或推送到下游系统。

4.2 定义 IR Schema

先写一个最小可用的 Schema。这里用 Zod 举例，因为它和 TypeScript 配合好，也能导出 JSON Schema 给 Agent 用。

import { z } from 'zod'; const BaseNode = z.object({ type: z.string(), props: z.record(z.any()).optional(), children: z.array(z.lazy(() => BaseNode)).optional() }); const PageSchema = BaseNode.extend({ type: z.literal('page'), children: z.array(BaseNode) });

实际项目中，每个组件的 props 要单独定义，不要用z.record(z.any())糊弄。上面只是为了演示递归结构。

4.3 Agent 侧 prompt 设计

Agent 的 prompt 要包含三部分：

1. 角色说明：你是一个页面结构生成器，只输出 JSON，不输出任何解释。
2. Schema 说明：把可用组件和字段列出来，最好附一个示例。
3. 用户需求：原始输入。

示例 prompt 片段：

你是一个可视化页面结构生成器。根据用户需求，输出一个 JSON 对象，表示页面结构。 可用组件： - page: 根节点，children 为子节点数组 - header: 标题，props: { title: string, level: 1|2|3 } - chart: 图表，props: { chartType: 'bar'|'line'|'pie', data: array, xField: string, yField: string } - table: 表格，props: { columns: array, rows: array } 输出格式：只输出 JSON，不要 markdown 代码块，不要解释。 用户需求：生成一个销售月报页面，包含标题、柱状图、数据表格。

关键点：明确说“只输出 JSON”，并且在代码里做 JSON 解析兜底。模型有时候还是会加 ```json 包裹，解析前先 strip 掉。

4.4 渲染层实现

渲染层核心是一个递归函数：

function renderNode(node, registry) { const component = registry.get(node.type); if (!component) { throw new Error(`Unknown component: ${node.type}`); } const parsed = component.schema.safeParse(node.props || {}); if (!parsed.success) { throw new Error(`Invalid props for ${node.type}: ${parsed.error.message}`); } const childrenOutput = (node.children || []) .map(child => renderNode(child, registry)) .join(''); return component.render(parsed.data, childrenOutput); }

这个函数是纯同步的，没有副作用，方便测试。如果组件渲染需要异步（比如请求远程数据），建议把数据获取提前到 IR 生成阶段，渲染层只做纯展示。

4.5 端到端跑通示例

假设用户输入：“生成一个包含标题和柱状图的页面，数据是 1 月 120、2 月 180、3 月 150。”

Agent 输出 IR：

{ "type": "page", "children": [ { "type": "header", "props": { "title": "月度销售", "level": 1 } }, { "type": "chart", "props": { "chartType": "bar", "data": [ { "month": "1月", "sales": 120 }, { "month": "2月", "sales": 180 }, { "month": "3月", "sales": 150 } ], "xField": "month", "yField": "sales" } } ] }

渲染层输出 HTML 片段，前端用 ECharts 或 Chart.js 初始化图表。整个过程 AI 只生成了不到 200 token 的 JSON，渲染完全确定。

4.6 局部修改怎么实现

可视化生成的一大优势是局部修改。用户说“把标题改成季度销售”，只需要：

1. 找到 IR 里 type 为 header 的节点
2. 修改 props.title
3. 重新渲染

不需要重新调用 AI。如果修改涉及结构变化，比如“再加一个饼图”，可以让 AI 只输出新增节点的 JSON，然后插入到 children 数组里。这样 token 消耗极低，而且不会影响已有内容。

实操心得：建议在 IR 里给每个节点加一个稳定 id，方便前端做 diff 和局部更新。id 可以由 AI 生成，也可以由渲染层在首次渲染时分配。

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

5.1 AI 输出不是合法 JSON 怎么办

这是最高频的问题。排查顺序：

1. 检查 prompt 是否明确要求“只输出 JSON”。如果写了“输出 JSON 格式”，模型可能还是会加解释。
2. 在代码里做预处理：去掉 markdown 代码块标记、去掉前后空白、找到第一个{和最后一个}再截取。
3. 如果还是失败，用 JSON 修复库（如jsonrepair）兜底。
4. 最后手段：把解析错误信息回传给模型，让它重新生成一次。但不要无限重试，最多 2 次。

我一般会在 prompt 里加一句：“如果无法生成合法 JSON，输出空对象 {}。”这样至少不会让整个流程挂掉。

5.2 组件类型对不上怎么办

AI 可能输出 Schema 里没有的组件类型。解决方案：

• 在 prompt 里把可用组件列表写全，并强调“只能使用以下组件”。
• 渲染层开启 strict 模式，遇到未知类型直接报错，并把错误信息记录到日志。
• 定期分析日志，看 AI 经常“发明”哪些组件，如果合理就加到注册表里，如果不合理就加强 prompt 约束。

我遇到过一个案例：AI 反复输出divider组件，但注册表里没有。后来发现用户需求里确实需要分割线，于是补上了这个组件，问题自然消失。所以有时候不是 AI 的错，是组件库不够全。

5.3 数据字段缺失或类型错误

比如 chart 组件需要data数组，AI 给了一个字符串。这种问题靠 Schema 校验能拦住大部分。但有些错误 Schema 拦不住，比如data是数组但里面对象缺少xField指定的字段。

解决方案：在渲染函数里做二次校验，缺字段时给一个明显的占位提示，而不是静默失败。这样用户能看到哪里出了问题，也方便反馈给 Agent 调整。

5.4 渲染结果和预期不一致

有时候 IR 完全合法，但渲染出来不是用户想要的。这通常是 prompt 理解偏差。排查方法：

• 把 IR 打印出来给用户看，确认结构是否符合预期。
• 如果 IR 对但渲染不对，检查组件默认样式和布局逻辑。
• 如果 IR 就不对，调整 prompt 里的示例，让示例更贴近目标场景。

避坑技巧：在开发阶段加一个“IR 预览”面板，把 AI 生成的 IR 以树形结构展示出来。这样调试时一眼就能看出是 AI 的问题还是渲染的问题。

5.5 性能与缓存策略

IR 生成是 IO 密集型（调模型），渲染是 CPU 密集型。优化点：

• 相同用户需求可以缓存 IR，加一个 hash 作为 key。
• 渲染层可以缓存组件实例，避免重复创建。
• 如果 IR 很大，考虑分片生成，先出骨架再填充细节。

我实测过一个 50 个节点的页面，IR 生成约 1.2 秒，渲染约 80 毫秒。瓶颈完全在模型调用，渲染层几乎不耗时。所以优化重点应该放在减少模型调用次数和 token 数上。

5.6 常见问题速查表

6. 多 Agent 协作下的可视化生成

6.1 什么时候需要多 Agent

单 Agent 能搞定大部分场景。但遇到复杂任务，比如“先生成页面结构，再填充数据，再校验合规性”，一个 Agent 容易顾此失彼。这时候可以拆成多个 Agent：

• 结构 Agent：只负责生成页面骨架 IR。
• 数据 Agent：负责根据骨架填充数据字段。
• 校验 Agent：负责检查 IR 是否符合业务规则。

每个 Agent 的输出都是 IR 的局部，最后由一个合并器拼成完整 IR。这样每个 Agent 的 prompt 更聚焦，输出更稳定。

6.2 协作协议怎么定

多 Agent 协作的关键是共享同一套 Schema。结构 Agent 输出的 IR 里，数据字段可以留空或给占位符。数据 Agent 读取这个 IR，只填充数据字段，不改结构。校验 Agent 读取完整 IR，输出校验报告。

合并器可以用简单的深度合并：

function mergeIR(base, patch) { // 按节点 id 合并 props // 结构以 base 为准，数据以 patch 为准 }

注意：多 Agent 会增加调用次数和延迟。如果单 Agent 能稳定输出，不要为了“架构好看”强行拆多 Agent。我见过一个项目拆了 5 个 Agent，结果延迟从 2 秒涨到 8 秒，稳定性反而下降。

6.3 可视化生成与 Agent 安全的结合

Agent 安全是最近的热词。可视化生成天然有安全优势：AI 不直接接触最终产物，只输出受限的 IR。这意味着：

• AI 无法注入任意代码，因为渲染层只认注册过的组件。
• AI 无法访问未授权的数据源，因为数据获取在渲染层之外。
• AI 的输出可以被完整审计，因为 IR 是结构化数据，容易做规则检查。

如果业务对安全要求高，可以在 IR 校验层加规则引擎，比如“禁止 chart 组件的数据超过 1000 条”“禁止 header 标题超过 50 字”。这些规则用代码实现，比在 prompt 里写“不要超过 1000 条”可靠得多。

7. 我踩过的坑和最后分享几个技巧

第一个坑是Schema 设计过度。一开始我想把所有组件的所有属性都定义清楚，结果 Schema 写了 800 行，AI 反而更容易出错，因为 prompt 太长，模型注意力被分散。后来精简到只定义核心字段，非核心字段用默认值，稳定性立刻提升。所以 Schema 不是越全越好，而是刚好够用最好。

第二个坑是忽略渲染层的错误处理。早期渲染层遇到非法 IR 直接抛异常，整个页面白屏。后来改成“局部降级”：某个节点渲染失败，就用一个错误占位符替代，其他节点正常渲染。这样用户至少能看到大部分内容，而不是一片空白。

第三个坑是没有做 IR 版本管理。组件库升级后，旧 IR 可能不兼容。后来在 IR 里加了version字段，渲染层根据版本走不同的渲染逻辑。这个改动不大，但省了很多兼容性麻烦。

最后分享一个小技巧：在 prompt 里给 AI 一个“思考步骤”。比如让它先输出{"plan": "...", "ir": {...}}，plan 字段写它的生成思路，ir 字段是实际结构。渲染层只读 ir，忽略 plan。这样 AI 的生成质量会明显提升，因为它在输出 IR 之前先“想了一遍”。实测下来，复杂页面的字段遗漏率能降低一半以上。

这个方案后续还可以扩展的方向：把 IR 存到数据库，做版本 diff 和回滚；把渲染层做成微服务，支持多语言产物（HTML、PDF、图片）；把组件注册表做成插件市场，业务方自助上传组件。这些都是工程上的自然延伸，核心思路不变——AI 做决策，代码做渲染，中间用 IR 连接。