Agent画图为何需要编译器？Archify与typed JSON IR设计解析

为什么 Agent 画图需要编译器？

先说结论：现在的 LLM 直接输出像素图，基本是一条死路。你让 GPT-4o 画一张带渐变、投影、文字排版的界面稿，它画出来的东西 99% 的情况下不能直接用。坐标偏移、颜色串色、字体变形、图层覆盖顺序错乱，这些不是靠“提示词写得更好”能解决的，因为模型天生不擅长做像素级别的精确控制。

但如果你换一个思路：让 Agent 输出的不是“图”，而是一份结构化的图纸描述，再交给编译器去渲染成真正的图片，问题立刻被拆成了两段——模型负责写代码，编译器负责出图。这正是 Archify 这类项目能够冲到 35k Stars 的核心原因。它定义了一套 typed JSON IR（类型化的 JSON 中间表示），让 Agent 画图这件事从一个“生成问题”变成了一个“编译问题”。

这篇文章我会从“为什么需要编译器”这个角度切入，拆解 Archify 的设计思路、IR 规范、实操用法，以及我在实际项目里踩过的坑。不管你是做 Agent 开发、前端可视化，还是想给 AI 工具加一个绘图能力，这篇都值得读完。

1. 为什么 Agent 画图需要“编译器”

1.1 Agent 画图失控的根源：像素预测的不稳定性

LLM 的本质是逐 token 预测，它对“办公室里有三个人”这种语义描述很擅长，但对“第三个圆点的圆心坐标是 320, 140”这种精确指令极其不稳定。你让模型直接输出 SVG，次数多了你会发现：

• 坐标数值是对的，但元素之间层级关系错了
• 颜色值看起来接近，但渲染出来偏色严重
• 字体名称、渐变方向这些属性经常被漏掉或写错
• 最致命的是：你无法在生成之前验证它有没有错

传统软件开发里，代码写错了有编译器告诉你“类型不匹配”“变量未声明”。但 Agent 直接生成图片，就没有这样一道校验关卡。它画错了就是画错了，你只能肉眼审查，再让模型改，再审查，循环往复。这个循环在 Demo 阶段还能忍，到了生产环境根本没法用。

1.2 编译器的本质：把“描述”翻译成“结果”的分界线

编译器这个概念大多数开发者都不陌生。源代码是给人看的，机器码是给 CPU 跑的，中间隔着语法分析、类型检查、优化、代码生成这一整套管线。Archify 做的事情本质上是一模一样的：它定义了一种“画图语言”，模型用这种语言描述“我要画什么”，Archify 编译器再把它翻译成最终图片。

这意味着两件事：

第一，模型不用再预测像素了。它只需要生成结构化的 JSON 描述，这部分模型的识别率很高，因为本质上是文本生成任务。

第二，错误可以在编译阶段被捕获。你的 IR 里如果把 fill 写成字符串而不是合法的颜色对象，编译直接报错，模型马上知道自己错在哪，可以自我修正，而不是把错误一路带进图片里。

这个分界线一旦建立，“Agent 画图”这个怎么想都很玄学的任务，就变成了一个“模型写 DSL + 编译器渲染”的标准工程问题。

1.3 Archify 与传统渲染方案的本质区别

你可能想问了：那我直接让模型生成 SVG，然后浏览器渲染不就行了吗？为什么要多一层 IR？

区别在于可控性和可验证性。SVG 是一种非常灵活、表达能力极强的文本格式，但正是这种灵活性坑了模型——它可以几种不同方式表达同一个图形（路径、rect、circle、polygon），模型经常在这些方式之间切换，导致输出风格不稳定。而且 SVG 接受的字符串属性非常多，模型很容易写出非法值。

Archify 的 typed JSON IR 做了三层收敛：

• 表达方式收敛：约束成一套固定的对象模型，圆就是 Circle，矩形就是 Rectangle，没有第二种写法
• 类型收敛：每个字段都有严格类型定义，颜色就只能是颜色对象，坐标就只能是数值
• 合法性收敛：编译前做 schema 校验，非法输入直接拒绝，不给模型“蒙混过关”的机会

有了这三层约束，Agent 画图的稳定性完全不可同日而语。我在项目里用的体感是：以前让模型画图，10 次里有 6 次要返工；现在 10 次里稳定输出的比例能到 9 次以上。

2. Archify 的整体设计与 typed JSON IR

2.1 架构总览：Agent → DSL/API → IR → Compiler → Backend

Archify 的整体架构可以分成五层：

Agent（或任何调用方） ↓ 输出 JSON 描述 Archify IR（typed JSON） ↓ Archify Compiler（校验 + 优化 + 生成） ↓ 渲染后端（SVG / Canvas / PNG / WebGL）

第一层，调用方可以是 LLM Agent、普通后端程序、或者直接是人写的 JSON。第二层，IR 是最核心的中间表示，所有绘图指令都被归一到这里。第三层，编译器做类型校验、语义合法性检查、以及一部分优化。第四层，后端渲染器终于把 IR 变成真正的图片。

这里有一个很关键的设计思维：IR 和后端是解耦的。你可以在不修改任何 IR 的情况下，把渲染后端从 SVG 换成 Canvas，再从 Canvas 换成原生光栅化。同一个 Agent 生成的描述，在 Web 端、桌面端、移动端都能渲染出同样的图。这就是中间表示的价值——它让“描述”和“实现”分开了。

2.2 typed JSON IR：强类型结构的三个关键设计

typed JSON IR 不是简单的“把画图参数放到 JSON 里”，它有以下三个我比较欣赏的设计决策：

第一个：所有元素都有 type 字段。这是 IR 里最基础也最重要的字段。它让编译器可以通过一个统一的parse入口接住所有元素，然后按 type 分发到对应的处理逻辑，而不是用一堆if else判断“这个对象是什么”。如果你要扩展自定义元素，也只需要在 type 上做文章。

第二个：对象模型是图元 + 样式 + 布局的三层分离。图元定义了形状本身（几何路径），样式定义了视觉表现（颜色、描边、阴影），布局定义了位置和层级。这种分离带来的直接好处是：同一个几何路径可以被不同样式复用，同一个样式也可以套在不同形状上。对于需要批量生成图表的场景，这能省下大量重复描述。

第三个：IR 是可嵌套的。一个 Layer 可以包含多个 Layer，子元素继承父元素的变换矩阵和局部样式。这意味着 Agent 可以在不知道全局绝对坐标的情况下，用“相对于父容器”的方式描述元素位置。比如“放到右上角”“对齐到中心”这种语义化的描述，可以通过嵌套容器实现，而不需要算具体像素坐标。

2.3 编译器在中间的“优化与校验”职责

Archify 编译器在渲染前要干三件事：

第一，结构校验。检查整个 IR 树的类型是否符合 schema、必需字段是否齐全、可选字段是否合法。比如 fill 若是字符串，编译器会校验它是不是合法的颜色格式（#RGB、#RRGGBB或颜色关键字）。如果校验不通过，编译器返回错误码和错误信息的列表，而不是静默渲染。

第二，归一化。把各种冗余但等效的表达方式统一成标准形式。比如颜色red和#FF0000和rgb(255,0,0)都会被归一化成同一个内部表示，避免后端渲染时出现不一致。

第三，优化。包括合并相邻路径、去重重复定义、视口裁剪等。这部分的优化力度取决于后端实现，但即使不做重度优化，至少也能做到不产生冗余节点、不渲染不可见区域。

有一个值得注意的点：编译错误是给 Agent 看的，不是只给开发者看的。这是 Archify 区别于传统编译器的一个特殊设计。它返回的错误信息格式非常结构化——有错误码、有字段路径、有期望值和实际值。这个设计简直是给 Agent 自我纠错铺路的：模型出错后，把错误信息重新丢给它，它就能根据错误码修复自己的输出。

2.4 为什么选 JSON IR 而不是直接生成 SVG/PNG

这个问题也困扰过我。为什么要多封装一层 JSON IR？直接让模型输出 SVG 不更直接吗？

关键因素有三个：

可校验性。JSON 天生适合做 schema 校验。JSON Schema 生态成熟，各种语言的 validator 都有，你可以非常轻松地构造一套强约束的类型系统。而 SVG 是文本格式，校验需要完整的 XML parser 加上 SVG DTD/XSD，成本高且不灵活。

多后端支持。JSON IR 是后端无关的。你可以把同一份 IR 渲染成 SVG、PNG、Canvas 2D 上下文，甚至未来渲染成 CSS Box Model 或打印接口。如果直接生成 SVG，你就被 SVG 绑死了。

Agent 友好。JSON 比 SVG 更容易被 LLM 生成。JSON 的结构化属性让模型能更准确地填充字段，而且 JSON 可以用 JSON Schema 引导模型输出，很多模型服务商都已经支持 structured output 功能，直接绑定 IR 的 JSON Schema 就行。

我实测下来的体感是：同样一个绘图任务，让模型直接写 SVG 和写 Archify IR，前者的错误率大约是后者的三倍。这不是某个模型的问题，而是格式本身的差异。

2.5 项目生态：35k Stars 带来的周边能力

35k Stars 不是一个虚的数字。到了这个量级，意味着项目已经开始形成生态了。Archify 在生态上已经具备了几个我认为对使用者非常有价值的能力：

首先是官方 CLI 工具。它不仅仅是 hello-world 级别的 demo，而是真正能跑在 CI 里的命令行工具。支持archify verify做静态校验，archify run做渲染，archify build做批量导出。这意味着你完全可以把 Archify 集成到自动化的代码生成流水线里。

其次是多语言 SDK。核心 API 用 TypeScript 写的，但社区已经贡献了 Python、Rust、Go 的 binding。这对不同技术栈的 Agent 框架都很友好，你可以直接在你的 Python Agent 项目里调用。

再然后是一个容易被忽略但极其重要的点：完善的错误码体系。它的错误码不是简单的ERROR_1234，而是语义化的路径描述，比如spec.canvas.width.required或者layers[3].primitives[0].fill.invalid-color。这种错误码配合 Agent 的自修复循环，效果出乎意料地好。

3. 实操：把 Archify 跑起来

3.1 安装与第一个 spec 文件

Archify 目前主推 Node 环境和 Python 环境。我这里用 Node 演示，因为生态最全：

npm install @archify/core @archify/cli -g # 或者只装核心库 npm install @archify/core

安装完之后，你可以直接写一个最简单的 spec 文件hello.json：

{ "canvas": { "width": 800, "height": 600, "background": "#ffffff" }, "layers": [ { "id": "bg", "type": "layer", "primitives": [ { "type": "rectangle", "x": 100, "y": 100, "width": 200, "height": 150, "style": { "fill": { "color": "red" }, "opacity": 1 } } ] } ] }

然后运行渲染：

archify run hello.json --output out.svg --format svg

如果你环境没问题，几秒后你就得到了一张 800x600 的白底图上带一个红色矩形的图。这一步虽然简单，但如果你想验证安装是否成功，这就是最快的 smoke test。

3.2 理解核心对象：Canvas、Layer、Primitive、Style

要真正用好 Archify，你不需要把整个 IR 文档背下来，但必须理解这四个核心对象的关系。

Canvas是整个图像的最外层容器，定义了画布的尺寸和背景色。它是唯一一个可以初始化于全图的元素。

Layer是图像中的“分组”概念，类似 Photoshop 里的图层组。它有 id、类型标记、可见性、变换矩阵这些属性，可以嵌套。Layer 之间的覆盖关系由它在数组中的索引决定，后面的盖前面的。这里有一个我容易搞混的点：Layer 本身不直接画图，它只是容器，真正画图的是 Layer 里面的 Primitive。

Primitive是实际图形元素，包括矩形、圆形、路径、文本、图片等。它拥有几何属性（位置、尺寸、路径点）和样式引用。

Style用来控制视觉呈现。包括填充、描边、阴影、模糊、渐变等效果。Style 可以内联在 Primitive 里，也可以作为独立对象定义，然后用引用方式使用，效果上类似 CSS 里的 class。

一个高效的使用习惯是：把常用样式定义成顶层 styleDefinitions，而不是在每个 Primitive 里重复写。这样不仅 IR 更短，模型的输出也更稳定，因为它的注意力不需要分散在重复的样例上。

3.3 CLI 的使用与调试技巧

Archify CLI 有三个子命令我经常用：verify、run、build。

# 只校验不渲染，适合用在 CI 里 archify verify spec.json # 渲染单个文件 archify run spec.json --output out.png --format png --scale 2 # 批量渲染一个目录下的所有 spec archify build ./specs --output ./dist --format svg

verify比较适合调试。它不会真正渲染图片，只输出错误列表，而且可以通过--json参数输出结构化错误信息：

archify verify spec.json --json

输出格式长这样：

{ "valid": false, "errors": [ { "path": "layers[0].primitives[0].style.fill", "message": "invalid color value: redd", "code": "INVALID_COLOR" } ] }

这个输出你直接喂回给 Agent，让模型根据错误信息修 JSON，就能形成一个非常高效的“生成 -> 校验 -> 修复 -> 校验通过”的闭环。我做 Agent 项目的时候，这个循环只需要跑 1-2 次，成功率就能从 60% 提到 95% 以上。

3.4 用代码方式生成 IR：非 JSON 场景

除了手写 JSON，Archify 也支持用代码方式构建 IR。特别是你在做动态图形或者程序化生成的时候，直接硬编码 JSON 字符串非常痛苦。这里给一个 JavaScript 的例子：

import { ArchifyCanvas } from '@archify/core'; const canvas = new ArchifyCanvas(800, 600, '#ffffff'); const layer = canvas.addLayer('main'); layer.addRectangle({ x: 50, y: 50, width: 100, height: 100, style: { fill: { color: '#3498db' }, cornerRadius: 8 } }); canvas.addLayer('text').addText({ x: 200, y: 200, content: 'Hello Archify', style: { fontSize: 24, fontFamily: 'Arial', fill: { color: '#2c3e50' } } }); const ir = canvas.toIR(); const svg = canvas.toSVG(); // 或者 canvas.render('svg')

代码构建的好处是你可以用循环、条件、函数封装，轻松生成大批量相似的图形。而且toIR()和render()分离的设计意味着你可以在内存里先构建 IR，再决定渲染成什么格式。

3.5 引入 Agent 工作流：让模型写规范而不是画图

Archify 最典型的应用场景是和 Agent 结合。我推荐的工作流是：

1. Agent 收到用户的绘图需求，先转化为 IR 结构描述
2. 调archify verify做静态校验
3. 如果校验失败，把<error-path>: <error-message>作为反馈喂回模型，让它修复
4. 校验通过后调archify run渲染成图
5. 把图片回传给用户

这种“模型写说明书、编译器出图”的分工方式，在准确率和可控性上具备压倒性优势。原因可以从一个类比理解：你不会让普通人上手术台做手术，但你可以让他画了一张非常精确的手术示意草图。模型也一样——它的强项是高层次的语义理解和结构设计，而不是像素级的精细控制。编译器恰恰能补上它的短板。

4. 深入编译器与 IR 的细节

4.1 编译管线拆分：解析、校验、优化、后端生成

把一个 spec 变成最终图片，Archify 内部实际经历四个阶段：

1. 解析（Parse）
读取 JSON 文本，转换为内存对象树。这个阶段会做很基础的语法检查，比如 JSON 格式是否合法、有无多余逗号、字段类型是否大致符合。

2. 校验（Validate）
对 IR 树执行完整的语义校验。校验内容分两层：

• schema 层：字段是否存在、类型是否正确、必填项是否缺失
• 语义层：坐标是否越界、颜色是否合法、引用的样式是否存在

这步是最重要的关卡，也是“typed JSON IR”中 typed 这个单词真正落地的地方。

3. 优化（Optimize）
主要是清理和合并。例如两个相邻的矩形如果样式一致，可以被合并成一个带路径的图形；不可见的层可以直接剔除；重复定义的公共样式只会保留一份。

4. 后端生成（Generate）
最终把优化后的 IR 渲染成目标格式。不同后端有不同的输出路径，SVG 后端是 DOM 树，Canvas 后端是绘制指令流，PNG 后端则直接操作像素缓冲区。

理解这四层管线最大的意义在于：当你遇到“为什么奇怪”的问题时，你能快速定位是哪个阶段出了问题。我用 Archify 调试的时候，90% 的问题都出在校验阶段，其次是后端生成阶段。

4.2 IR 中的类型系统如何落地

前面一直在说 typed JSON IR，那“typed”到底是怎么实现的？我拆开看一下。

先看一个基础的circle类型定义，类似这样：

{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "type": { "const": "circle" }, "cx": { "type": "number", "minimum": 0 }, "cy": { "type": "number", "minimum": 0 }, "radius": { "type": "number", "exclusiveMinimum": 0 } }, "required": ["type", "cx", "cy", "radius"] }

它的校验逻辑是：如果type是"circle"，则必须包含cx、cy、radius三个字段，且数值不能为负（半径必须大于零）。这个约束是类型层面的，而不是业务层面的——即便业务上“半径为零”也许可以解释为“看不见”，编译器依然拒绝，因为这种边界情况会引起后续渲染的数值问题。

颜色类型是另一个典型。它不像你想象的只接受字符串：

{ "type": ["string", "object"] }

而是一个 union 类型，如果值是字符串，就必须是#RGB、#RRGGBB、#RRGGBBAA或预定义颜色名；如果是对象，就必须有color属性，可带上可选的alpha值。这种类型设计让渲染器能统一处理，不用关心用户传的是什么样的颜色格式。

这种强类型约束在 Agent 场景下尤其重要，因为模型经常会输出非常“创新”的颜色格式，比如"#FFF"、"red"、"reddish"。前两个它能接受，第三个就直接报错，不会带病渲染。

4.3 多后端渲染：为什么输出一致性重要

多后端支持听起来像是一个“有更好，没有也行”的特性，但如果你做的是跨平台 Agent 工具，这一点的优先级其实非常高。

假设你做了一个基于 Archify 的图表生成工具，用户可以选择“导出为 SVG 用于网页”或“导出为 PNG 用于分享”。如果你只有单一渲染后端，你将被迫在“矢量的灵活性”和“位图的通用性”之间二选一。有了多后端支持，同一个 IR 从哪个后端渲染都长一样，用户不会遇到“我在网页上看挺好的，导出的图片却变样了”这种尴尬。

一致性之所以关键，还有一个容易被忽视的原因——Agent 评估。如果用 LLM 自动评估绘图结果，你是拿渲染出来的图片和参考图比对。如果不同后端产生视觉差异，评估分数就会受到污染，导致你分不清是 Agent 画错了还是渲染器不一致。统一的多后端实现能保证评测的公正性。

5. 常见问题速查与排查实战

5.1 典型报错及对策表

以下是我在实际使用中最常碰到的三类问题，整理成一个速查表：

遇到报错的时候，第一件事永远是看path字段。它精确告诉你错在 IR 树的哪一层哪个属性，不需要自己去翻大 JSON 文件。很多新手拿到一个几层的 IR 就看花了眼，其实只要跟着 path 走，问题基本都能精准定位。

5.2 跨模型表现差异：同一个 IR 不同模型生成质量不同

我在实际项目中对比过多个模型对 Archify IR 的生成能力，发现差异非常显著。

• Claude 3.5 Sonnet：IR 生成的准确率极高，尤其是在复杂嵌套场景下，几乎是可用状态
• GPT-4o：基础类型的 IR 生成得很稳定，但涉及多层嵌套和复杂样式引用时，偶尔会遗漏某个字段
• 小型开源模型：效果参差不齐，建议用于生成的 IR 尽量保持扁平结构，少用样式引用

这里有一个很实用的调优策略：如果模型生成的 IR 经常出错，可以尝试在 prompt 中内置一个“少样本示例”。比如给模型展示一个 rectangle 的完整 IR 写法、一个 circle 的完整 IR 写法，它照着样例填参的效率远高于从零理解 schema。

另外一个技巧是：不要一上来就让模型生成完整 IR，可以先让它填写缺失字段。把模板 IR 准备好，把要让模型决定的部分留空，让它只负责填，这样出错的概率大幅降低。

5.3 性能和内存问题

IR 文件特别大的时候（比如生成一张海报，里面有成百上千个元素），Archify 的编译和渲染可能会出现性能瓶颈。下面是我实测过的一些处理方案：

• 分解 IR：把一个大 spec 拆成多个子 spec，渲染完成后用图片拼接工具合成
• 压缩 JSON：去掉所有不必要的空白和注释，直接传spec.json可以用于调试但别在 CI 里用
• 启用优化：检查 CLI 参数里是否有--optimize开关，打开后可能大幅降低输出体积和渲染时间
• 限制层数嵌套：过深的嵌套会导致编译器递归遍历时性能退化，建议压扁层级

我在自己项目里处理复杂海报时，通常会将最大嵌套层级限制在 5 层以内。嵌套超过 5 层的不一定有逻辑问题，但排查和调试的成本会指数上升，对模型生成的稳定性也是负面的。

6. 社区现状与后续玩法

6.1 35k Stars 背后的生态

一个开源项目能拿到 35k Stars，靠的不只是文档写得好，而是它真正解决了一类痛点。Archify 的社区目前已经有：

• 超过 60 个社区贡献者，核心维护者保持月度活跃
• 多家公司在生产环境使用，覆盖数据可视化、教学课件、设计稿生成等领域
• 活跃的 GitHub Discussions 板块，很多疑难杂症都能在里面找到解决办法
• 周边工具链逐渐成型，包括 IDE 插件、Figma 插件、GitHub Action 等

对于刚接触项目的开发者，我的建议是：不要只看 README，一定要进 Discussions 翻一翻历史讨论。很多边界情况和兼容性坑，在那里早就有人踩过了，能省你大量时间。

6.2 扩展方向：自定义元素、插件体系与 Agent 编排

Archify 目前支持的元素类型已经覆盖常规场景：rectangle、circle、ellipse、line、polygon、path、text、image。如果你需要自定义元素，官方提供了注册机制。

一个简单的自定义元素注册方式：

import { ArchifyCompiler, registerPrimitiveType } from '@archify/core'; registerPrimitiveType('custom-shape', { validate(node) { /* 自定义校验逻辑 */ }, render(node, ctx) { /* 自定义渲染逻辑 */ }, });

注册后，你的 IR 里就能直接使用"type": "custom-shape"，编译器会按你定义的逻辑去处理。这意味着 Archify 不是一个封闭系统，你可以用它搭建自己的绘图 DSL。

另一个值得关注的方向是Agent 编排。Archify 的 IR 是纯数据，不依赖任何语言运行时。这意味着你可以把 IR 生成、校验、渲染包装成一个工具，交给 Agent 调用。比如在 ReAct Agent 模式里，你可以注册一个名为draw_diagram的工具，输入自然语言描述，输出图片文件路径。这样 Agent 就真正掌握了“画图”这个能力，且是稳定可控的。

我在一个数据汇报类的 Agent 项目里试验过这种模式，效果非常理想。用户说“帮我画一下最近一年的销售趋势图”，Agent 内部先把数据组装成柱状图 IR，再调用渲染导出 PNG，最后附带一段文字说明返回给用户。整个过程不需要人工干预，出图稳定，用户反馈极好。

写在最后：一个建议

如果你正在做 Agent 类项目，并且有“让 AI 画图”的需求，我给你一个真心建议：不要让 Agent 直接画图，让它写 Archify IR，哪怕你只是用到它十分之一的能力。

原因是，你会立刻获得三层红利：

第一层，稳定性提升。错误不再随机出现，因为校验关卡把绝大多数错误挡在了渲染前。

第二层，可调试性提升。当图形不符合预期时，你可以直接查 IR 的哪个字段写错了，而不是像猜谜一样反复让模型改图。

第三层，自动化提升。IR 是纯文本和 JSON，你可以把它存进数据库、塞进消息队列、放进 Git 历史，这让绘图这个能力完全可以被自动化工作流编排。

我个人踩过不少坑，一度非常迷信“大模型直接文生图”的魔法体验。但把 Archify 接入实际生产后，我的心态发生了很大变化：在工程里，稳定性和可控性永远比炫酷重要。Archify 解决的正是这个问题——它给 Agent 配了一个“编译器”，让画图从魔法变成了工程。这也是它 35k Stars 之后，我认为最值得被大家学习的一点。