开源项目第157期：archify — 用自然语言生成可主题切换、高分辨率导出的架构图

引言

"Generate beautiful architecture, technical workflow, sequence, data-flow, and lifecycle diagrams in chat."

这是「每日一个开源项目」系列的第 157 篇。今天的项目是 archify —— 一个让 AI agent 把自然语言描述转换成精美技术图表的 Skill 包，支持 Claude Code、Codex CLI 和 opencode。

「让 LLM 画架构图」这件事本身并不稀奇，但大多数实现到这一步就停了：让 LLM 直接写 SVG，结果是每次生成的质量都在赌运气。archify 的核心工程投入在于构建了一条完整的质量保障管道：自然语言 → JSON IR → Schema 校验 → 类型化渲染器 → 后渲染检查，最终输出一个可在浏览器里直接打开的自包含 HTML 文件。

3,464 颗 Star，创建于 2026 年 4 月，版本已迭代到 v2.10.0。

你会学到什么

• JSON IR 管道：为什么不让 LLM 直接写 SVG
• 5 种图表类型及其适用场景
• 4× 原生光栅化导出的技术实现
• 双主题自包含 SVG：一个文件跟随读者系统主题
• 语义技术标签：aws.lambda、postgres、kafka 如何映射到视觉分类

前提知识

• 使用过 Claude Code 或任意 AI coding agent
• 了解基本的系统架构概念

---

项目背景

概述

archify 是一个跨 agent 的 Skill 包。安装后，在 Claude Code 会话里输入 Use archify to draw...，agent 会执行一条质量管道，最终生成一个零依赖、单 HTML 文件的技术图表。

它由 Cocoon-AI/architecture-diagram-generator v1.0 fork 而来（原始版本只有深色主题和静态 HTML 输出），2.x 版本进行了大规模重写：CSS 变量主题系统、导出管道、类型化渲染器、Schema 校验、后渲染检查。

README 明确注明了 fork 来源和各版本新增内容 —— 这种透明度在开源工具里值得一提。

项目信息

• 作者: tt-a1i
• 主语言: JavaScript
• 许可证: MIT
• 版本: v2.10.0
• 项目主页: tt-a1i.github.io/archify

项目数据

• ⭐ GitHub Stars: 3,464+
• 🍴 Forks: 358+
• 📄 许可证: MIT
• 📅 创建时间: 2026-04-15

---

功能特性

安装

# 一条命令，全局安装，选择 agent 时按提示操作
npx skills add tt-a1i/archify -g

# 或者临时体验，不做永久安装
npx skills use tt-a1i/archify@archify --agent claude-code

安装后直接在 agent 里描述需求：

Use archify to map this repository's runtime architecture.

5 种图表类型

类型	适用场景	触发方式
Architecture	系统组件、云资源、数据库、边界、安全组	描述系统结构
Workflow	请求生命周期、审批流、工具调用、CI/CD、事件响应	描述参与者、步骤顺序、关键分支
Sequence	API 调用链、缓存穿透、认证检查、异步 trace	描述谁调用谁、顺序和返回值
Data Flow	数据管道、ETL/ELT、分析事件、PII 隔离、数仓同步	描述数据源、处理阶段、存储、消费者
Lifecycle	状态机、订单/任务/部署/agent run 生命周期	描述状态、转移事件、重试路径、终态

示例 Prompt

Web 应用架构：

Use archify to draw an architecture diagram:
React frontend calls a Node.js API backed by PostgreSQL and Redis,
deployed on AWS behind CloudFront.

CI/CD 工作流：

Use archify to draw a CI/CD workflow:
pull request -> tests -> approval gate -> build image ->
staging deploy -> smoke test -> production deploy, with rollback on failure.

数据流管道：

Use archify to draw a data flow:
Web and Mobile emit analytics events, Edge API collects them,
Consent Gate filters PII, Kafka carries accepted events,
Warehouse stores analytics tables, Feature Store derives daily features,
Dashboards and ML Model consume downstream data.

Agent run 生命周期：

Use archify to draw a lifecycle diagram:
Agent Run starts at Queued, moves through Planning, Executing, Reviewing.
Needs Approval and Blocked are wait states.
Failed can retry. Cancelled / Expired / Completed are terminal states.

主题与导出

生成的 HTML 文件右上角有两个按钮：

• 主题切换（Dark / Light）：一键切换，状态持久化到 localStorage。快捷键 T。
• 导出菜单：五个操作（复制 PNG + 下载 PNG/JPEG/WebP/SVG）。快捷键 E。

键盘导航：

• T — 切换主题
• E — 打开导出菜单
• ↑ ↓ — 菜单内导航
• Enter / Space — 执行
• Esc — 关闭菜单

URL 参数（适合自动化截图）：

• ?theme=light 或 ?theme=dark — 强制初始主题
• ?openExport=1 — 自动打开导出菜单

---

深度解析

JSON IR 管道：不让 LLM 直接写 SVG

这是 archify 最关键的架构决策。

用户描述（自然语言）
    ↓
Agent 生成 JSON IR（类型化的架构/工作流/...描述）
    ↓
Schema 校验（bundled standalone validators，无需安装依赖）
    ↓
类型化渲染器（生成 HTML/SVG 输出）
    ↓
后渲染检查（检测 SVG 错误坐标、意外对角线箭头、图例穿越路由等）
    ↓
交付自包含 HTML 文件

为什么不直接让 LLM 写 SVG？

LLM 直接生成 SVG 的问题是：每次结果都在赌运气。坐标计算错、元素重叠、箭头穿越不相关的节点……这些问题难以在 prompt 层面稳定解决。

JSON IR 把「描述内容」和「渲染布局」分开：LLM 只负责写清楚有哪些节点、连接关系和元数据，渲染器负责把这份结构化描述转换成 SVG。LLM 做自己擅长的（理解语义、组织结构），渲染器做规则明确的（坐标计算、箭头路由）。

后渲染检查具体做什么：

node scripts/check-render-output.mjs output.html
# 或通过 CLI
node bin/archify.mjs check output.html

检查项：

• SVG 坐标值是否有限（非 NaN/Infinity）
• 是否存在意外的两点对角线箭头
• 是否有箭头线段穿越图例区域
• 元素是否格式完整

如果检查失败，agent 针对 JSON IR 做修改，而非重新生成整个图表 —— 这使得迭代更精准，不会把正确的部分也改掉。

4× 原生光栅化导出

大多数「图表导出 PNG」实现都有一个隐藏缺陷：缩放是在 canvas 层做的。先生成 1× 分辨率的图，再放大到 4×，结果是模糊的。

archify 的实现方式：

1. 克隆 SVG 元素
2. 内联当前主题的 CSS 变量（解析 :root 中的 custom properties，写入克隆的 :root 规则）
3. 将克隆 SVG 的 width/height 设置为 "4 × viewBox 尺寸"
4. 浏览器以 4× 分辨率原生光栅化这个 SVG（矢量渲染，不是位图放大）
5. canvas 尺寸匹配，以自然尺寸绘制（无放大）
6. canvas.toBlob(mime) 生成文件

关键是第 3-4 步：给矢量 SVG 设置更大的 width/height，浏览器在更高分辨率下渲染它 —— 这是原生光栅化，不是位图放大，所以结果是真正锐利的。

当目标分辨率超过浏览器 canvas 限制时，自动降级到 3× 或 2×，确保导出不会失败。

双主题自包含 SVG

导出的 SVG 文件不是单主题的 —— 它同时包含深色和浅色的 CSS 变量集，加上 @media (prefers-color-scheme) 规则：

<style>
  :root {
    /* 深色变量 */
    --bg: #0f172a;
    --c-frontend: #06b6d4;
    ...
  }
  @media (prefers-color-scheme: light) {
    :root {
      /* 浅色变量 */
      --bg: #f8fafc;
      --c-frontend: #0891b2;
      ...
    }
  }
</style>

把这个 SVG 文件放进 GitHub README，它会自动跟随读者的系统主题 —— 不需要维护两张图片，不需要用 <picture> 标签做条件渲染，一个文件解决所有情况。

语义技术标签

在 prompt 或 JSON IR 里使用技术标签，archify 把它们映射到视觉分类：

标签示例	视觉分类	颜色
react, nextjs, ios, browser	Frontend	Cyan（青色）
node, go-service, python-worker, api-gateway	Backend	Emerald（翠绿）
postgres, mysql, redis, s3, bigquery	Database/Storage	Violet（紫色）
aws.lambda, aws.cloudfront, kubernetes	Cloud/Infrastructure	Amber（琥珀）
auth0, cognito, vault, security-group	Security	Rose（玫瑰红）
kafka, rabbitmq, sns, sqs	Message Bus	Orange（橙色）
stripe, github-actions, openai, anthropic	External	Slate（石板灰）

这套映射不需要图标库 —— 颜色语义已经足够传达「这个节点是什么类型」的信息，同时保持了生成文件的零依赖特性。

工作流图的结构增强（v2.7+）

Workflow 图不是通用流程图，它是技术沟通图：泳道、语义颜色、清晰的主路径，以及次要的异步/审批/trace 路径。

v2.7 引入的工程约束：

• Phase headers：工作流可以分阶段组织
• Groups：同一阶段内的节点分组
• Exception lanes：异常路径在独立泳道里，不与主路径混合
• Happy-path linting：检查是否有清晰的主路径
• 同泳道正交路由：泳道内的连接使用正交线条（水平/垂直），不允许穿越不相关节点的对角线

迭代式修改

生成图表后，可以继续对话修改：

add Redis between the API and PostgreSQL
move the auth service to the left
highlight the rollback path with a different color

因为修改是针对 JSON IR 的，而不是重新生成整个图表，所以「加一个节点」不会改变其他节点的布局。

CLI 工具

node bin/archify.mjs doctor        # 检查环境
node bin/archify.mjs demo /tmp/out # 生成示例图表
node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json output.html
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json
node bin/archify.mjs check output.html   # 后渲染检查
node bin/archify.mjs examples     # 列出内置示例
node bin/archify.mjs inspect output.html # 查看计算后的布局 JSON（v2.10 新增）

archify inspect 是 v2.10 新增的调试工具：输出渲染后的布局计算结果，方便理解节点为什么在特定位置。

---

参考资源

官方链接

• 🌟 GitHub: tt-a1i/archify
• 🌐 项目主页: tt-a1i.github.io/archify
• 📦 原始项目: Cocoon-AI/architecture-diagram-generator（archify 的 fork 来源）

---

总结

archify 在「LLM 生成图表」这个问题上做了一个明确的工程选择：不让 LLM 直接写最终的 SVG 坐标，而是让它写结构化的 JSON IR，然后由确定性的渲染器负责布局和渲染，最后由检查器验证输出质量。这条管道增加了复杂度，但换来的是可靠性 —— 生成的图表质量不再依赖 LLM 的当轮运气。

两个工程细节值得单独记住：

4× 原生光栅化：通过给矢量 SVG 设置 4× 的 width/height 让浏览器在更高分辨率下原生渲染，而不是生成 1× 图再放大。结果是在 Retina 屏幕、幻灯片、打印场景下，导出图片不会模糊。

双主题自包含 SVG：一个文件里同时嵌入深色和浅色 CSS 变量集，加 @media (prefers-color-scheme) 规则。放进 GitHub README 后自动跟随读者系统主题，不需要维护两张图。

如果你经常需要在文档、PR 描述或 Notion 里插入架构图，archify 的「描述 → 生成 → 导出」工作流值得试用 —— 一条 npx 命令安装，在 Claude Code 里 Use archify to draw... 触发。

---

探索 PrimeSkills —— 精选 AI agent 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

访问我的个人主页，获取更多见解和有趣的产品。