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

Archify让 AI Agent 直接生成可校验架构图的 Agent Skill 深度解析核心观点Archify 的本质命题是把布局决策权还给 LLM让工具只做确定性校验和导出。这不是在做一个更好看的 Mermaid 主题而是对 AI 辅助画图工作流做了一次范式重构。当前大多数 AI 画图工具包括让 GPT/Claude 生成 Mermaid 代码的痛点在于自动布局引擎dagre、ELK把布局决策权拿走输出结果千篇一律——8 个组件和 40 个组件的图在视觉逻辑上毫无区别颜色语义在每次对话里都可能不一致。Archify 的核心设计哲学是布局本身就是信息让 Claude/Codex 等 Agent 直接决定坐标、颜色语义和边界工具层只负责五套类型化渲染器 JSON Schema 校验 渲染后检查器。关键机制拆解五段流水线阶段发生了什么关键设计GenerateAgent 根据描述或仓库生成 JSON IR中间格式选 JSON 而非 YAML因为 LLM 生成 YAML 看着对、解析错比例高Validate内置校验器检查 schema、布局、路由、标签失败时返回机器可读的 JSON repair receipt含 rule code 精确 subjectPreview (optional)桌面 loopback 监听单文件只加载通过校验的版本最后一张好图始终可见save 中断不会破坏预览状态Deliver同目录生成候选文件原子替换通过检查的产物失败不覆盖稳定性保证来自先检查再替换IterateAgent 只更新源不相关结构保持稳定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组件/服务/存储/信任边界用来画调用时序WorkflowCI/CD、审批、工具调用链用来替代时序图SequenceAPI 调用、缓存回源、异步 trace用来表达状态流转Data FlowETL/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/archifyarchify --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 编码 AgentArchify 价值一半在 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 diffArchify 的 Architecture Delta 是在图的层面引入类似机制。随着系统复杂度上升架构图版本控制会不会像代码版本控制一样成为标配而不是锦上添花 参考来源GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence,>