引言“Generate beautiful architecture, technical workflow, sequence,>你会学到什么JSON IR 管道为什么不让 LLM 直接写 SVG5 种图表类型及其适用场景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 skillsaddtt-a1i/archify-g# 或者临时体验不做永久安装npx skills use tt-a1i/archifyarchify--agentclaude-code安装后直接在 agent 里描述需求Use archify to map this repositorys runtime architecture.5 种图表类型类型适用场景触发方式Architecture系统组件、云资源、数据库、边界、安全组描述系统结构Workflow请求生命周期、审批流、工具调用、CI/CD、事件响应描述参与者、步骤顺序、关键分支SequenceAPI 调用链、缓存穿透、认证检查、异步 trace描述谁调用谁、顺序和返回值Data Flow数据管道、ETL/ELT、分析事件、PII 隔离、数仓同步描述数据源、处理阶段、存储、消费者Lifecycle状态机、订单/任务/部署/agent run 生命周期描述状态、转移事件、重试路径、终态示例 PromptWeb 应用架构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 参数适合自动化截图?themelight或?themedark— 强制初始主题?openExport1— 自动打开导出菜单深度解析JSON IR 管道不让 LLM 直接写 SVG这是 archify 最关键的架构决策。用户描述自然语言 ↓ Agent 生成 JSON IR类型化的架构/工作流/...描述 ↓ Schema 校验bundled standalone validators无需安装依赖 ↓ 类型化渲染器生成 HTML/SVG 输出 ↓ 后渲染检查检测 SVG 错误坐标、意外对角线箭头、图例穿越路由等 ↓ 交付自包含 HTML 文件为什么不直接让 LLM 写 SVGLLM 直接生成 SVG 的问题是每次结果都在赌运气。坐标计算错、元素重叠、箭头穿越不相关的节点……这些问题难以在 prompt 层面稳定解决。JSON IR 把「描述内容」和「渲染布局」分开LLM 只负责写清楚有哪些节点、连接关系和元数据渲染器负责把这份结构化描述转换成 SVG。LLM 做自己擅长的理解语义、组织结构渲染器做规则明确的坐标计算、箭头路由。后渲染检查具体做什么nodescripts/check-render-output.mjs output.html# 或通过 CLInodebin/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,browserFrontendCyan青色node,go-service,python-worker,api-gatewayBackendEmerald翠绿postgres,mysql,redis,s3,bigqueryDatabase/StorageViolet紫色aws.lambda,aws.cloudfront,kubernetesCloud/InfrastructureAmber琥珀auth0,cognito,vault,security-groupSecurityRose玫瑰红kafka,rabbitmq,sns,sqsMessage BusOrange橙色stripe,github-actions,openai,anthropicExternalSlate石板灰这套映射不需要图标库 —— 颜色语义已经足够传达「这个节点是什么类型」的信息同时保持了生成文件的零依赖特性。工作流图的结构增强v2.7Workflow 图不是通用流程图它是技术沟通图泳道、语义颜色、清晰的主路径以及次要的异步/审批/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 工具nodebin/archify.mjs doctor# 检查环境nodebin/archify.mjs demo /tmp/out# 生成示例图表nodebin/archify.mjs render workflow examples/agent-tool-call.workflow.json output.htmlnodebin/archify.mjs validate workflow examples/agent-tool-call.workflow.json--jsonnodebin/archify.mjs check output.html# 后渲染检查nodebin/archify.mjs examples# 列出内置示例nodebin/archify.mjs inspect output.html# 查看计算后的布局 JSONv2.10 新增archify inspect是 v2.10 新增的调试工具输出渲染后的布局计算结果方便理解节点为什么在特定位置。参考资源官方链接GitHub: tt-a1i/archify项目主页: tt-a1i.github.io/archify原始项目: Cocoon-AI/architecture-diagram-generatorarchify 的 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 和技能工具每一个都经过真实工作流验证。没有炒作只有真正好用的工具。访问我的个人主页获取更多见解和有趣的产品。