Archify：面向 AI Agent 的可验证架构图生成技能

在 AI Agent 深度介入代码审查与架构讨论的今天如何将一段技术方案快速转化为清晰、可交互、可验证的可视化图表成为团队沟通效率的关键瓶颈。Archify 给出了一个独特答案它不是通用绘图编辑器也不是 Mermaid 主题的变体而是一个专为 AI Agent 设计的、以类型化 JSON IR 驱动架构图表生成与验证的技能工具。本文将带你全面了解 Archify 的定位、能力边界、核心机制与安装方式帮助你在实际工程中判断它是否适合你的工作流。一、核心定位Agent 驱动的图表渲染与验证系统Archify 的运行架构建立在两个角色分离的基础上AI Agent如 Cursor、Claude Code、Codex CLI、OpenCode 等负责生成结构化的类型化 JSON IRIntermediate Representation而 Archify 本身则是一个 Node.js 渲染与验证系统负责将这份 IR 确定性编译为 HTML/SVG 输出。这意味着 Archify 不负责「画图」而是负责「把意图翻译成可沟通的制品」。Agent 生成的 IR 必须通过 Archify 内置的校验链才能进入渲染环节这从根本上保证了输出图表与输入描述之间的一致性——不会出现 Agent 描述的组件在图中凭空出现或消失的情况。原文描述指出Agents produce typed JSON IR; Archify deterministically compiles it into HTML/SVG。 这里的关键词是「typed」和「deterministically」前者意味着 IR 有严格的类型约束后者意味着相同输入必然产生相同输出这对于工程审校场景至关重要。二、五类图表与风格预设Archify 目前支持五种图表类型每种类型对应一种常见的系统沟通场景-Architecture架构图展示组件及其边界关系适合表达系统分层与依赖。-Workflow工作流图表达 CI/CD 流水线或审批流程节点间存在顺序与分支逻辑。-Sequence时序图描述 API 调用链或缓存回退等交互序列。-Data Flow数据流图刻画数据管线或血缘关系强调数据的流向与转换。-Lifecycle生命周期图描绘状态机含重试、终止等状态转换路径。风格层面提供 dark/light 主题切换、品牌徽标嵌入和有限动画支持。所谓「有限动画」是指仅在关键交互如节点高亮、路由追踪时触发而非自由式动效这是为了保持图表的「可审校性」不被装饰性元素干扰。三、原子级验证与可修复诊断这是 Archify 与 Mermaid、Draw.io 等工具最本质的区别之一。Archify 要求所有检查在交付前通过且每个检查项都有明确的机器可读诊断。当校验失败时Archify 不会返回人类难以解析的堆栈或模糊的重试提示而是返回包含以下字段的「修复收据」repair receipt-rule codes规则编码标识具体哪条校验规则未通过。-subject出问题的具体元素如某个节点 ID 或连接线。-measured evidence测量的证据说明为什么这条规则不满足。-supportedFixes支持的修复动作列表供 Agent 选择执行。原文提到Failures come with a repair receipt — validate --json and deliver --json return stable rule codes, the exact subject, measured evidence, and only supported repair controls. 这使得整个验证过程从「人工排查」变为「Agent 可自动执行的修复闭环」。四、真实交互拒绝虚构拓扑Archify 强调所有交互行为必须基于已认证源数据不能发明拓扑也不能声称具有运行时影响。支持的操作包括-搜索节点按名称或类型过滤图中元素。-溯源上下游追踪某个节点的上游生产者和下游消费者。-探针路由沿某条连接线查看其携带的数据或控制流语义。-角色对比并列查看同一组件在不同视图中的表现。-引导故事沿着预设路径逐步讲解系统架构。原文强调Review architecture changes before merge — compare two validated snapshots as Before / Delta / After. 这意味着你完全可以在 PR 合入前将新旧两个版本的已验证快照导入 Archify系统会自动呈现增删改移和重路由的事实而不是让审阅者肉眼比对两张静态图片。五、单文件交付与多格式导出Archify 的输出始终是自包含的 HTML 文件内部嵌入完整的 SVG 图表和交互逻辑无需外部依赖即可在任何现代浏览器中打开。同时支持导出为 PNG、SVG、WebM 以及 1200×630 的社交分享卡片尺寸且所有导出均保留完整图表上下文不含临时查看器状态。原文指出One file, ready to trust and share — self-contained HTML plus PNG, SVG, WebM, and 1200×630 share cards. 这一设计特别适合需要将架构图嵌入文档、邮件、PR 描述或内部 Wiki 的场景。六、Before/Delta/After 变更对比Archify 的 delta 模式是面向工程治理的设计。你可以传入两个已验证的快照系统会生成一份精确的变更报告展示哪些节点被添加、删除或修改哪些连接关系发生了重路由。对于生产部署审查场景Archify 还支持启用deployment-ownership工程配置。当关键元信息如负责人、变更范围、风险等级缺失时系统会采取 fail-closed 策略——即拒绝生成图表而非含糊通过以此强制推动团队补全必要信息。七、安装方式Archify 提供三种安装途径1.npx 全局安装npx skills add tt-a1i/archify -g2.手动 ZIP 安装将压缩包放入 Raven~/.raven/workspace/skills目录3.DeepSeek Harness 社区插件dsh plugin --profile web add这种多途径覆盖确保了不同 Agent 生态的用户都能便捷接入。八、设计哲学明确边界Archify 在文档中明确声明了自己的边界- 不是通用绘图编辑器——不支持自由拖拽、像素级对齐或手绘式编辑。- 不是 Mermaid 主题——不兼容 Mermaid 语法也不走 Mermaid 的渲染管线。- 不支持托管分享服务——图表是本地或自托管的 HTML 文件。- 不支持 WYSIWYG 编辑——所有修改必须通过重新生成 IR 并重走验证流程完成。原文总结Archify 明确声明不是通用绘图编辑器或 Mermaid 主题其目标是把技术意图转化为可沟通的制品。 这种克制正是它的优势所在它把精力集中在「确定性」和「可验证性」上而非功能广度。九、相比 Mermaid / Draw.io 的实际优势从工程实践角度Archify 的核心差异化价值体现在两点确定性布局Mermaid 和 Draw.io 的布局算法往往带有随机性或启发式特征同一份定义在不同环境或版本下可能产出不同的布局。Archify 采用确定性编译相同 IR 必然产生相同渲染结果这对版本控制下的架构图审计意义重大。验证内嵌Draw.io 本质上是一个编辑器它的「校验」依赖人工Mermaid 几乎没有结构校验语法错误往往只在渲染时暴漏。Archify 的校验是设计时的第一公民IR 不通过校验就永远无法进入渲染环节这大幅降低了「图与实现不一致」的隐形风险。十、待深挖问题根据现有素材以下问题原文未提供可直接引用的答案建议在实际使用中查阅 Archify 的官方文档或源码- 类型化 JSON IR 的完整字段定义及五类图的结构差异约束。-deployment-ownership配置的具体校验规则与适用生产场景清单。- Proof Lab 中 11 个已检查场景的验证收据validation receipts格式规范。- Archify 在大型代码库百级节点以上中的性能表现与布局策略。小结Archify 的核心价值不在于「画出好看的图」而在于「让图可验证、可追溯、可对比」。对于重度依赖 AI Agent 进行架构讨论和变更审查的团队来说它填补了 Mermaid语法驱动但缺乏校验和 Draw.io自由编辑但缺乏确定性之间的空白地带。如果你正在构建一个需要频繁比对架构变更、且希望图表本身能被自动校验的工程流程Archify 值得纳入你的工具链评估范围。