Archify：让 AI Agent 直接生成可校验架构图的 Agent Skill 深度解析

曦尧

173人浏览 · 2026-08-02 00:15:09

曦尧 · 2026-08-02 00:15:09 发布

Archify：让 AI Agent 直接生成可校验架构图的 Agent Skill 深度解析

核心观点

Archify 的本质命题是：把"布局决策权"还给 LLM，让工具只做确定性校验和导出。这不是在做一个"更好看的 Mermaid 主题"，而是对 AI 辅助画图工作流做了一次范式重构。

当前大多数 AI 画图工具（包括让 GPT/Claude 生成 Mermaid 代码）的痛点在于：自动布局引擎（dagre、ELK）把布局决策权拿走，输出结果千篇一律——8 个组件和 40 个组件的图在视觉逻辑上毫无区别，颜色语义在每次对话里都可能不一致。Archify 的核心设计哲学是"布局本身就是信息"，让 Claude/Codex 等 Agent 直接决定坐标、颜色语义和边界，工具层只负责五套类型化渲染器 + JSON Schema 校验 + 渲染后检查器。

关键机制拆解

五段流水线

阶段	发生了什么	关键设计
Generate	Agent 根据描述或仓库生成 JSON IR	中间格式选 JSON 而非 YAML，因为 LLM 生成 YAML "看着对、解析错"比例高
Validate	内置校验器检查 schema、布局、路由、标签	失败时返回机器可读的 JSON repair receipt，含 rule code + 精确 subject
Preview (optional)	桌面 loopback 监听单文件，只加载通过校验的版本	最后一张好图始终可见，save 中断不会破坏预览状态
Deliver	同目录生成候选文件，原子替换通过检查的产物	失败不覆盖，稳定性保证来自"先检查再替换"
Iterate	Agent 只更新源，不相关结构保持稳定	Typed JSON IR 使得局部修改不引发全图重排

四倍原生光栅化

传统做法是按 1× 画到 canvas 再拉伸，结果模糊。Archify 的做法是：克隆 SVG，内联主题 CSS 变量，把 width/height 设为 4 × viewBox，让浏览器按 4× 分辨率原生光栅化矢量。结果是真正高清的 PNG，不是放大后的位图糊。

Architecture Delta（变更对比）

这是区别于同类工具的独特功能：通过 archify.mjs compare 命令，对比 Before/After 两个 JSON 快照，产出精确的 Added/Removed/Changed/Moved/Rerouted 事实清单，并以 Before/Delta/After 三视图呈现。这对 PR 架构评审价值极高——相比XX（纯文字 diff 或人工对比图片），这个机制能准确捕捉"谁被移走了，谁的路由被改了"。

# 架构变更对比命令
node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

五种图类型与适用场景

类型	最适合	常见误用
Architecture	组件/服务/存储/信任边界	用来画调用时序
Workflow	CI/CD、审批、工具调用链	用来替代时序图
Sequence	API 调用、缓存回源、异步 trace	用来表达状态流转
Data Flow	ETL/PII 边界/下游消费	用来画系统组件图
Lifecycle	状态机、重试、终态	用来画调用顺序

选错图种比画得不好看更严重——这是 Archify 专门提供 CLI 引导选图的原因：

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

快速上手示例

# 全局安装
npx skills add tt-a1i/archify -g

# Cursor 显式安装
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

# 不安装直接试用（Codex）
npx skills use tt-a1i/archify@archify --agent codex

给 Agent 的典型提示：

Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

迭代时的精确指令：add Redis、move auth to the left、highlight the rollback path——Archify 保留 Typed JSON IR，局部修改不打乱整体结构。

交叉验证

信源一：jackssybin.cn《聊两句就画一张架构图：拆开 tt-a1i/archify 这个 agent skill》

这篇独立技术博客对 Archify 的机制做了完整的内部拆解，认同原文的核心设计判断，并补充了几个原 README 未明确说明的细节：

确认 JSON IR 选型的理由（LLM 生成 YAML 的解析失败率高于 JSON）；
补充指出 v2.7 才加入 check-render-output.mjs 这个最终渲染检查器（原文未提版本时间线）；
明确指出 Mermaid 在 Archify 里只是输入方言，不是渲染目标，这与原文"Archify 不是 Mermaid 主题"一致；
给出了"再等等的场景"：图是一次性的、需要精确坐标排版（用 Figma/Excalidraw），或团队根本不用 LLM 编码 Agent（Archify 价值一半在 skill，一半在产物）。

该文章补充了原文未说清的边界，是对原文结论的有效收敛。

信源二：infrasketch.net《Best Diagram-as-Code Tools 2026》

这篇比较全面的横向对比文章对 Archify 没有直接提及（其对标的 AI 生成工具是 InfraSketch），但其对各工具的核心结论与原文的竞品定位高度吻合：

Mermaid：布局控制最弱，复杂图无法精确排布——印证了原文"自动布局就是 Archify 要绕过的"；
D2：布局比 Mermaid 强，但最佳布局引擎 TALA 需付费，生态小——印证了 Archify 不走自动布局引擎路线的合理性；
Structurizr DSL：强制 C4 模型，学习曲线陡——适合重度架构团队，不是日常 LLM 迭代场景；
该文章的"实用建议"是"用 AI 快速探索，稳定后用代码化工具维护"——Archify 恰好是这两端的中间层：AI 主导生成 + 工具保证可校验导出。

两个独立信源均认同：自动布局是现有工具的共同短板，AI 辅助图表的价值在于快速迭代而不是精确像素控制。原文的核心判断经过了交叉验证。

边界局限：诚实地说

局限在于以下几个方面，不能无条件推荐：

强依赖 Agent 质量：Archify 把布局决策权还给 LLM，这意味着图的质量天花板就是当次对话里 Claude/Codex 的理解深度。如果 prompt 模糊，或者 Agent 对系统理解不到位，JSON IR 本身就是错的，再精密的校验器也救不了。
Schema 校验不等于语义正确：validate 只能保证结构合法，不能保证"这张图是否准确反映了真实架构"。原文强调的 "truthful interaction" 仅限于已经 authored 的节点和关系，无法替代人工架构 review。
并非适用于所有场景：需要甘特图、饼图、桑基图、ER 图等通用图表类型时，Mermaid/PlantUML 依然是更合适的选择。Archify 的五种图类型是深度而非广度。
4× 光栅化的浏览器稳定性：Chrome/Firefox/Safari 的 canvas 上限不同，超大图的降级阈值需要自验。原文未对"超大图"的边界做出明确说明。
团队前提：如果团队没有人把 LLM Coding Agent 装进日常工作流，Archify 的 skill 机制形同虚设，价值减半。

个人启发

这意味着 Archify 适合的是一类特定工作流，而不是所有画图需求。对开发者的具体行动建议：

立刻适用：你在用 Claude Code / Codex CLI / opencode 做技术方案、架构评审、PR review，且图需要反复迭代——现在就值得装，5 分钟装完能节省每张图半小时的手动排版；
谨慎适用：架构图是最终稳定版本，需要像素级排版控制，用 Figma 或 Excalidraw 手动精排仍然是更好的选择；
最大价值点：Architecture Delta 功能被严重低估——在 PR 阶段用机器可读的方式对比两个架构快照，是真正能改变架构评审流程的功能，而不只是"好看的图"；
对决策者：这不是"买一个画图 SaaS"的决策，而是"把架构文档纳入 Agent 工作流"的决策，两者的前提条件和价值量级完全不同。

接下来可以预见：随着 Claude Code、Codex CLI 等工具渗透率持续上升，Archify 这类"Agent Skill"的生态会快速扩展。目前 Archify 的护城河在 JSON IR + 五类型化渲染器 + 原子校验这套组合，而不是视觉美学本身（视觉跑不赢有足够资源的 Mermaid 社区）。这意味着接下来它的竞争优势会更集中在"可校验性"和"Delta 对比"这两个方向，而不是"更好看"。

延伸思考

"Agent Skill" 作为软件分发形式的未来：Archify 用 npx skills add 而不是传统 npm 包安装，这种以 Agent 为宿主的技能分发范式，与 VS Code 插件、浏览器扩展有何本质区别？它是否会成为下一个生态战场？
可校验性 vs 可解释性的张力：Archify 的 validate --json 能告诉你哪条规则失败了，但无法告诉你"这张图是否准确描述了真实系统"。在 AI 生成内容大量涌现的背景下，"结构合法"和"语义正确"之间的鸿沟如何被弥合？
架构图的版本控制是否会成为强需求：传统代码库有 git blame、git diff；Archify 的 Architecture Delta 是在图的层面引入类似机制。随着系统复杂度上升，架构图版本控制会不会像代码版本控制一样成为标配，而不是锦上添花？

📚 参考来源