Archify：让 AI Agent 直接在对话中生成可交互、可验证架构图的 Skill

Archify让 AI Agent 直接在对话中生成可交互、可验证架构图的 Skill核心观点Archify 的本质不是又一个画图工具而是把画架构图这件事变成 AI Agent 的原生能力。它以 agent skill 的形式安装到 Cursor、Claude Code、Codex CLI、OpenCode 等工具中让开发者在聊天窗口里一句话描述系统Agent 直接产出一个自包含的、可分享的 HTML 架构图——跳过了AI 生成代码 → 手动复制到 draw.io → 拖拽调整 → 导出这一套传统循环。这件事所处的阶段值得明确定位它不是范式级突破而是工具链整合的渐进优化但踩在了 AI 编程助手工作流标准化这条正在形成的范式切口上时机判断是准确的。关键机制Typed JSON IR 原子验证Archify 真正聪明的地方不在于AI 生成图而在于它引入了一个**中间表示层Typed JSON IR**并围绕它建立了端到端的确定性验证链自然语言描述 ↓ Agent 生成 Typed JSON IR结构化中间源 ↓ 原子验证schema / layout / HTML / SVG / 路由 / 标签间距 验证通过 → 渲染 HTML原子替换上一版本 验证失败 → 保留上一个最后已知好版本返回机器可读修复收据这是它区别于直接让 AI 输出 Mermaid 代码的核心机制。Mermaid 有个长期痛点AI 生成的 DSL 语法容错性差括号、关键字一旦出错就整张图渲染失败且错误信息对 AI 不友好。Archify 用 JSON IR 取代了 DSL每次变更都经过 schema 校验失败时返回稳定规则码 精确主体 可测量证据Agent 可以直接根据机器可读修复提示迭代而不是碰运气重试。这套最后已知好last-good机制在渐进迭代时特别有价值——你对一张有 20 个节点的图说把 Redis 挪到左侧其余结构保持稳定而不是整张图重绘。五种图类型与选型逻辑图类型最适合的场景Architecture组件/服务/存储/信任边界PR 前架构评审WorkflowCI/CD、审批流、工具调用、运维手册SequenceAPI 调用链、缓存 fallback、auth 流、异步追踪Data Flow数据管道、数据谱系、PII 边界Lifecycle状态机、重试、等待、终态另有Architecture Delta模式compare命令比较两个验证快照产出 Before/Delta/After 三视图精确标注新增、删除、变更、移动、重路由的节点和边适合架构变更的 PR review。node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json安装与最小可行用法# 全局安装通用 npx skills add tt-a1i/archify -g # Cursor 显式非交互安装 npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes # 不想永久安装试用一次 npx skills use tt-a1i/archifyarchify --agent codex安装后在 Agent 对话中分析这个仓库用 archify 创建一张高层运行时架构图。 展示 8–12 个核心组件一条主路径外部依赖以及信任边界。 支撑细节放进卡片而不是增加更多箭头。交互式迭代示例Use archify to draw this login flow: Browser - Web App - API - JWT validation - Redis session lookup - PostgreSQL fallback. Keep the cache-miss path secondary.与同类工具的历史脉络对比维度Mermaid / PlantUMLdraw.io / ExcalidrawArchify驱动方式代码 DSL鼠标拖拽 GUI自然语言 AgentAI 生成易错率中语法敏感❌ 不适配 AI低JSON IR 容错输出格式SVG/PNG私有格式/SVG自包含 HTML PNG/SVG/WebM迭代方式全量重写手工改精确补丁 最后已知好可交互性无有限节点搜索/路由追踪/故事播放信任边界无无有typed schema 强制校验相比 MermaidArchify 牺牲了高度自定义能力CSS/HTML 级别的随意控制和生态成熟度换来了对 AI 生成场景的专门优化。相比 draw.io它牺牲了精细手工控制换来了零工具切换成本。agentupdate.ai 的对比文章2026年6月研究了 oh-my-mermaid、architecture-diagram-generator、fireworks-tech-graph 三类工具归纳出一条关键判断优秀的技术项目必然走向文档完全自治——即 CI/CD 流程在代码变动时自动运行逆向分析并生成最新架构图无需手动维护。Archify 的设计方向与这条判断高度吻合。交叉验证信源一txtmix.com《Archify 拆解》2026年7月该文章对 Archify 的评价与原文官方说明基本吻合并补充了若干独立判断认同Archify 确实解决了AI 用 Mermaid 经常出错这一实际痛点输出质量达到可直接放入技术文档水准补充局限明确指出节点超过 50 个时图面会拥挤且不支持实时协作编辑对于客户演示级高保真场景Archify 的品牌精细控制能力不足独立判断定位 Archify 为时间效率 完美度场景的最优解而非全场景通用工具。这一判断是原 README 没有明说但隐含的边界txtmix 把它说清楚了。信源二agentupdate.ai《AI 时代开源架构作图工具对比》2026年6月该文章虽然对比的是另外三款工具OMM、ADG、FTG但提供了重要的横向框架参照认同明确区分了代码输入逆向分析配置输入DSL自然语言输入Agent三种路径Archify 属于第三类与文章归纳的趋势方向一致隐性补充该文指出自然语言驱动类工具的通病是依赖 AI 理解能力提示词质量影响输出——这一局限 Archify 同样存在但 README 刻意回避了这个话题。两个信源都没有对 Archify 的核心机制Typed JSON IR 原子验证提出反驳印证了这是其真实差异化点而非纯营销话术。边界与被过度夸大的部分几点需要诚实指出Truthful interaction / 不会凭空发明拓扑——这个承诺的边界是Archify 确保已标记的节点和路由是 authored 的但初始由 AI 从代码库推导出来的 JSON IR 本身仍然依赖 Agent 的理解质量并非对代码做了静态分析级别的精确映射。Source evidence源码证据功能只在 Evidence-backed Architecture 模式下启用且需要 public commit私有仓库场景受限明显。节点数量有上限超过 50 个节点的复杂系统布局会拥挤Archify 官方推荐的解法是把细节放进 card而不是无限扩展。没有实时协作多人同时修改同一张图的需求无法满足。对提示词质量敏感自然语言驱动的根本性局限原 README 的 prompt 模板限定 8–12 个节点、指定一条主路径本质是在约束 AI 的输出范围以规避这个问题并不能完全消除它。个人启发对独立开发者和技术写作者如果你需要给技术博客、内部文档、架构评审写架构图Archify 是目前集成 AI 编程流最顺畅的方案——不要用它替代 Figma 或 draw.io 的精细场景而要用它替代在 Mermaid 上反复调试语法的痛点场景。安装一次之后对 Agent 说话就能出图。对工程团队Architecture Delta 模式值得关注。在大型 PR 里架构变更往往口头说不清楚一张精确标注新增 A→B 边、删除 C 节点的对比图能大幅降低评审成本。把archify compare加进 CI/CD 流程让每次涉及架构改动的 PR 自动附带一份 Delta 图是一个具体可执行的方向。对工具决策者不要把 Archify 当成 draw.io 的替代品来评估而要把它当成架构文档的自动化生产流水线的一个节点来评估。它的价值在于消除代码写完但文档没更新的老大难问题。延伸思考Typed JSON IR 的标准化可能性Archify 自定义了一套 JSON IR但如果这类 IR 格式能像 OpenAPI spec 一样走向行业标准化各 AI 工具都能读写同一份 IR那么不同工具生成的架构图可以互相 diff就不再依赖单一工具——Archify 现在的设计是否在无意中为这个方向奠基架构图的漂移问题如何根本解决Archify 能让图快速生成和更新但它依赖开发者主动触发 Agent 来更新图代码库与架构图之间的同步仍然不是自动的。真正的文档自治需要代码变更能自动触发图的增量更新——这一步何时、以何种机制实现才是这条技术路线的真正终局验证可信度的边界在哪里Archify 强调atomic validation和truthful interaction但这套验证只能保证 JSON IR 内部的结构一致性不能验证 IR 本身与真实运行时系统的符合程度。当架构图被用于安全审计或合规场景时这层可信度的真实边界该如何向读者披露 参考来源GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence,>