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 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/archify@archify --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，Archify 牺牲了高度自定义能力（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 原子验证）提出反驳，印证了这是其真实差异化点而非纯营销话术。

边界与被过度夸大的部分

几点需要诚实指出：

1. "Truthful interaction / 不会凭空发明拓扑"——这个承诺的边界是：Archify 确保已标记的节点和路由是 authored 的，但初始由 AI 从代码库推导出来的 JSON IR 本身仍然依赖 Agent 的理解质量，并非对代码做了静态分析级别的精确映射。

2. "Source evidence（源码证据）"功能只在 Evidence-backed Architecture 模式下启用，且需要 public commit，私有仓库场景受限明显。

3. 节点数量有上限：超过 50 个节点的复杂系统，布局会拥挤，Archify 官方推荐的解法是把细节放进 card，而不是无限扩展。

4. 没有实时协作：多人同时修改同一张图的需求无法满足。

5. 对提示词质量敏感：自然语言驱动的根本性局限，原 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 的替代品来评估，而要把它当成"架构文档的自动化生产流水线的一个节点"来评估。它的价值在于消除"代码写完但文档没更新"的老大难问题。

延伸思考

1. Typed JSON IR 的标准化可能性：Archify 自定义了一套 JSON IR，但如果这类 IR 格式能像 OpenAPI spec 一样走向行业标准化，各 AI 工具都能读写同一份 IR，那么"不同工具生成的架构图可以互相 diff"就不再依赖单一工具——Archify 现在的设计是否在无意中为这个方向奠基？

2. 架构图的"漂移"问题如何根本解决：Archify 能让图快速生成和更新，但它依赖开发者主动触发 Agent 来更新图，代码库与架构图之间的同步仍然不是自动的。真正的文档自治需要代码变更能自动触发图的增量更新——这一步何时、以何种机制实现，才是这条技术路线的真正终局？

3. 验证"可信度"的边界在哪里：Archify 强调"atomic validation"和"truthful interaction"，但这套验证只能保证 JSON IR 内部的结构一致性，不能验证 IR 本身与真实运行时系统的符合程度。当架构图被用于安全审计或合规场景时，这层"可信度"的真实边界该如何向读者披露？

📚 参考来源

1. GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence,>