lijianfei.com

在软件工程中，架构图（Architecture Diagram）是连接业务抽象与底层代码最核心的认知桥梁。然而在过去十几年里，开发者画架构图始终在两大地狱之间痛苦徘徊：一边是 Mermaid、PlantUML 等传统文本绘图工具生成的“上世纪工业风”静态死图，连线交错缠绕成麻花；另一边是 Figma、Excalidraw 等纯手工画布，随系统重构迅速沦为无人维护的“代码文物”。

当 Claude Code、Cursor、Codex、AGY 等 AI Coding Agent 开始全面接管日常代码编写时，这种断层被无限放大——AI 能在数秒内重构几千行代码，却没有任何一个现成工具能让它自动交付出一张既符合工程严密性、又具备顶级工业美学、还能全交互探索的动态系统地图。

近期在 GitHub 狂揽 4.8 万+ Stars 的开源项目 tt-a1i/archify，给出了教科书级的降维解决方案：它不把图当作文本画板，而是将系统图谱视为一套编译型领域模型（Typed JSON IR），通过物理避让引擎与确定性门禁校验，让 AI Agent 能够在两轮闭环内自愈并交付出像素级精致、单文件自包含、支持六维交互与 Git 源码溯源的次世代架构图。

一、 传统架构绘图的“三重困境”

在深入拆解 Archify 之前，我们需要客观审视：为什么现有的方案无法满足现代 AI 辅助工程研发？

flowchart TD
    subgraph Traditional["传统绘图工具的困局"]
        direction TB
        T1["Mermaid / PlantUML 等 DSL 方案<br/>• 自动布局僵化，多箭头中心扎堆重叠<br/>• 静态死图无法交互，与底层代码脱节<br/>• 报错晦涩无局部指引，LLM 难以闭环自愈"]
        T2["Excalidraw / Figma 等手绘方案<br/>• 无法嵌入 CI/CD 或 Agent 自动化流水线<br/>• 维护成本高昂，架构演进后迅速沦为文物"]
        T1 --- T2
    end

    Traditional ==>|范式升级与能力跃迁| ArchifyRevolution

    subgraph ArchifyRevolution["Archify 次世代系统地图引擎"]
        direction TB
        A1["Archify (Agent Skill 优先)<br/>• Typed JSON IR 领域模型，杜绝非结构化幻觉<br/>• 确定性几何碰撞检测与端口自动分散算法<br/>• 结构化修复回执 (Repair Receipt) 实现 1~2 轮自愈<br/>• 单文件自包含 HTML：六维全交互与 Git 源码溯源"]
    end

1. 自动布局的审美崩塌（Auto-layout Collapse）

无论是 Mermaid 还是 Graphviz，底层均重度依赖以 Dagre / Sugiyama 为代表的通用层次图算法。这类算法在节点数量超过 8 个、出现反向回环调用或跨层边界时，会瞬间失控：

• 节点被挤在画面角落，边缘空白巨大；
• 多条进出同一组件的箭头死板地汇聚在组件中点，重叠成一团漆黑的“线头”；
• 连线文字（Relationship Labels）经常直接横穿其他无关线条或节点矩形。

2. LLM“盲人摸象”式的自愈失败

当你让大模型生成一段包含十几步流程的复杂 Mermaid 代码时，只要出现一条语法错误或渲染异常，给 LLM 的报错通常是晦涩的 Parse error on line 42: ...。大语言模型根本无法在脑海中渲染出画布的真实几何布局，导致其每次“重试”都是对整张图进行推倒重写，不仅无法收敛，反而引入更多拓扑变形。

3. 静态交付与真实代码严重脱节

现存工具交付的产物无非是 PNG 图片或普通 SVG。在架构评审（Architecture Review）、Incident 复盘或技术答辩时，观众经常需要追溯：

• “这个服务挂了，到底会波及哪些下游链路？”
• “两个核心服务之间，最短的调用路径到底经过了哪几个中间件？”
• “图上画着 OrderService -> RiskEngine，这对应具体哪一个仓库的哪行实现？”

传统的静态图对此无能为力，图是图，代码是代码。

二、 Archify 核心架构与核心黑科技

Archify 的核心立意非常坚决：它不是通用的手绘白板，也不是又一个 Mermaid 主题，而是一个专为 Coding Agent 设计的“架构图编译器与运行时系统”。

整个系统采用清晰的管线流水线设计（Pipeline）：

sequenceDiagram
    autonumber
    actor Dev as 工程师 / Agent
    participant LLM as Coding Agent (Claude/Cursor)
    participant Core as Archify Compiler (Node.js)
    participant Val as 确定性校验门禁 (Layout & Rules)
    participant HTML as 自包含交互式 HTML 成品

    Dev->>LLM: 输入需求 / 扫描真实代码仓库
    LLM->>Core: 生成 Typed JSON IR (AST)
    loop 确定性校验与局部自愈 (最多 2 轮)
        Core->>Val: 执行 JSON Schema + 物理碰撞 + 避让检测
        alt 校验未通过
            Val-->>LLM: 返回机器可读修复回执 (Repair Receipt)
            Note over LLM: 仅局部修正 subject 节点/线路，绝不推倒重绘
            LLM->>Core: 重新提交微调后的 JSON
        else 校验全部通过
            Val-->>Core: 几何与拓扑准入放行
        end
    end
    Core->>HTML: 原子编译生成单个独立 HTML (内置矢量渲染与交互引擎)
    HTML-->>Dev: 交付完成 (支持全景交互 / 故事回放 / 源码跳转 / 导出)

下面我们深入剖析支撑 Archify 强大能力的四大工程基石。

黑科技一：Typed JSON IR 与五大领域图谱模型

Archify 彻底废弃了非结构化的自由文本 DSL，转而定义了一套严密的 Typed JSON IR（类型化中间表示）。所有 Schema 在最外层和属性层均开启了 additionalProperties: false，从协议层面遏制了 LLM 产生幻觉生成野字段的可能。

系统根据软件架构生命周期的不同场景，抽象出五大专用领域图谱：

以一个标准的 RAG（检索增强生成）流水线架构 为例，其 Typed JSON IR 结构极其干净直观：

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Production RAG Pipeline",
    "locale": "zh-CN",
    "animation": "trace",
    "visual_preset": "signal-flow",
    "views": [
      {
        "id": "query-path",
        "label": "用户提问主链路",
        "focus": ["user", "guardrail", "orchestrator", "retriever", "vectordb", "llm"],
        "note": "展示用户查询从安全拦截、混合检索到上下文生成的全链路"
      }
    ]
  },
  "components": [
    { "id": "user", "type": "external", "label": "终端用户", "sublabel": "Web / Mobile", "pos": [40, 200], "size": [110, 50] },
    { "id": "guardrail", "type": "security", "label": "安全护栏", "sublabel": "PII / 毒性拦截", "pos": [190, 200], "size": [120, 50] },
    { "id": "orchestrator", "type": "backend", "label": "Agent 编排器", "sublabel": "LangGraph Engine", "pos": [350, 200], "size": [130, 54] },
    { "id": "cache", "type": "database", "label": "语义缓存", "sublabel": "Redis Cluster", "pos": [350, 70], "size": [130, 50] },
    { "id": "vectordb", "type": "database", "label": "向量数据库", "sublabel": "Milvus HNSW", "pos": [530, 200], "size": [120, 54] },
    { "id": "llm", "type": "cloud", "label": "基础大模型", "sublabel": "Claude 3.7 Sonnet", "pos": [700, 200], "size": [130, 54] }
  ],
  "boundaries": [
    { "kind": "region", "label": "核心推理专有网络 (VPC-Internal)", "wraps": ["orchestrator", "cache", "vectordb"] }
  ],
  "connections": [
    { "id": "c1", "from": "user", "to": "guardrail", "label": "用户 Prompt", "variant": "emphasis" },
    { "id": "c2", "from": "guardrail", "to": "orchestrator", "label": "已校验查询", "variant": "security" },
    { "id": "c3", "from": "orchestrator", "to": "cache", "label": "语义未命中", "fromSide": "top", "toSide": "bottom" },
    { "id": "c4", "from": "orchestrator", "to": "vectordb", "label": "KNN 混合检索", "labelDy": -20 },
    { "id": "c5", "from": "vectordb", "to": "llm", "label": "注入 Top-K 上下文", "labelDy": -20 }
  ]
}

[!TIP]
设计小彩蛋：JSON 中的 components 支持直接声明知名品牌预设（如 "brand": "redis"、"brand": "aws"），Archify 内置了高质量矢量品牌 Logo 库，编译时会自动进行无损嵌入，省去了开发者到处找 SVG 图标的烦恼。

黑科技二：确定性几何校验与“修复回执（Repair Receipt）”机制

这是 Archify 最令工程师震撼的地方。

在以往使用 LLM 绘图时，哪怕是排版重叠，模型也毫无感知，只能任由读者忍受丑陋的连线。而 Archify 在编译层内置了数条物理几何准则：

1. 实体碰撞准则（No Overlap）：任何两个组件之间必须保持最小间隙（Clearance），禁止重叠；
2. 无关节点穿越封禁（No Crossing Opaque Nodes）：连接线绝对不允许穿透任何不相关的实体卡片；
3. 自动端口分散算法（Automatic Port Spread）：当有 3 条以上的连线进出同一个组件时，算法会自动计算端口间距，将箭头等距展开，彻底消灭传统工具多箭头扎在同一个点上的毛刺丑态；
4. 文字标签防遮挡（Label Clearance）：连线上的文字描述如果与其它管线产生交叉，校验器会直接驳回，并给出微调建议。

更为关键的是其报错交互哲学。当执行 node bin/archify.mjs validate architecture app.json --json 出现违规时，编译器不会抛出晦涩的异常堆栈，而是输出标准结构化的 Repair Receipt（修复回执）：

{
  "valid": false,
  "diagnostics": [
    {
      "code": "LABEL_INTERSECTS_ROUTE",
      "severity": "error",
      "subject": "c4",
      "measured": { "labelMask": [530, 195], "collidingRoute": "c3" },
      "supportedFixes": [
        "调整 c4 的 labelDy 偏移量 (-20 或 +20)",
        "通过 via: [[x, y]] 自定义中间折拐点",
        "调整 orchestrator 与 vectordb 的水平间距"
      ]
    }
  ]
}

当 Agent（如 Claude 或 Cursor）捕获到这个 JSON 后，它无需重新构思全图，只需精准对 c4 连接执行局部的 labelDy 参数调整，通常在第一轮或第二轮内就能 100% 自动收敛并通过门禁！

黑科技三：自包含单文件（Single HTML）与六维交互矩阵

传统工具导出的是“死图”，而 Archify 交付的产物是一个完全自包含的独立 HTML 文件（零外部 CDN 依赖、零运行时服务器）。

双击打开该 HTML，你得到的不仅是一张图，而是一个完整的交互式系统看板：

mindmap
  root("Archify 六维交互矩阵")
    ["全局模糊搜索 (快捷键 /)"]
      ["毫秒级定位目标节点"]
      ["高亮显示并平滑居中聚焦"]
    ["上下游可达性追溯 Reach"]
      ["聚焦某个微服务"]
      ["一键追踪所有上游依赖 Upstream"]
      ["一键点亮所有下游波及 Downstream"]
    ["拓扑路径探测 Path (快捷键 R)"]
      ["选择起点与终点组件"]
      ["实时计算最短有向传输路径"]
    ["语义角色对撞透视 Lens (快捷键 L)"]
      ["选择两个角色（如 Backend vs Database）"]
      ["全图仅保留两者交互流量"]
    ["故事分镜播放 Story (快捷键 P)"]
      ["预设业务讲解步骤"]
      ["像演讲 PPT 一样按章推进架构演进"]
    ["一键多模态导出 Export (快捷键 E)"]
      ["1200×630 社交与技术分享卡片 (Share Card)"]
      ["高清矢量 SVG"]
      ["动态 WebM 与透明背景 PNG"]

在日常架构答辩或团队 Code Review 中，Story 故事分镜功能（views）堪称杀手级特性：你可以把一张庞大的万级并发架构图切分成“正常请求链路”、“灰度放量链路”、“故障熔断降级”等 3~5 个命名章节。演示时只需敲击键盘快捷键 [ 和 ]，画面便会平滑切换聚焦，全场技术焦点的认知负担降低 80% 以上。

黑科技四：架构变更对比（Delta Review）与真实源码溯源（Source Evidence）

在企业级研发场景中，Archify 解决了两个最致命的痛点：

1. 架构级别的“代码审查”（Architecture Diff / Delta）

以前提交 PR，Reviewer 只能对着几十个文件、上千行代码变动猜测系统结构的变化。Archify 原生提供了架构 Diff 命令：

node archify/bin/archify.mjs compare architecture base.json head.json delta.html --json

它会在同一个视图中以高对比度颜色渲染出 Before / Delta / After：

• 绿色高亮标注新增的服务与调用；
• 红色删除线标注废弃的旧中间件；
• 橙色标识发生重构或重路由（Rerouted）的链路。

这使得架构演进在 PR 合并之前能够被团队所有人直观感知与严格审阅！

2. Git 源码真实性锚定（Source Evidence）

你是否见过那些“PPT 上画得天花乱坠，实际代码里根本找不到”的虚假架构？

Archify 在 architecture 规范中引入了 evidence 协议：

{
  "id": "router",
  "type": "backend",
  "label": "Command Router",
  "evidence": {
    "repo": "mco-org/mco",
    "commit": "9f1a1cf",
    "path": "crates/router/src/dispatch.rs",
    "lines": [42, 88]
  }
}

在渲染出的成品中，该组件会自动打上 SRC 1 的认证徽标。点击它，浏览器会立刻精准跳转到 GitHub 对应仓库固定 Commit 的真实代码行。这是业界首个真正打通“架构图”与“物理代码”的信任闭环。

三、 深度横评：Archify vs 常见绘图工具

为了更直观地展现 Archify 的定位优势，我们将其与主流技术绘图方案进行多维度对比：

四、 实战上手：5 分钟将 Archify 装入你的 Agent 工具箱

Archify 可以作为全局 Agent Skill 极其平滑地集成到各类主流工作流中。

1. 极速安装 Skill

在终端执行以下命令，全局安装 Archify Skill：

# 通用技能管理安装（支持 Cursor、Claude Code、Codex CLI 等）
npx skills add tt-a1i/archify -g

如果你使用的是 Cursor，也可以使用官方显式命令一键注册：

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

安装完成后，你可以随时在终端运行自检工具：

node $(npm root -g)/archify/bin/archify.mjs doctor

2. 在 Agent 对话中一键驱动

安装好 Skill 后，你无需学习复杂的 JSON IR 语法，直接在你的 Agent（Cursor、Claude Code 或 AGY）对话框中下达自然语言指令即可：

实战 Prompt 模板（场景一：从头描述系统）：
“请使用 archify 帮我绘制一张支付中台系统的运行时架构图。
包含：用户端、API 网关、支付路由服务、风控引擎、订单 DB、Redis 缓存以及外部微信/支付宝通道。
突出显示‘下单支付’的核心调用主路径，将内部微服务划分在核心支付域边界内，使用 signal-flow 预设，并生成 3 个主要交互 Views。”

实战 Prompt 模板（场景二：根据真实仓库逆向工程）：
“请深度分析当前代码仓库的工程结构，使用 archify 生成一份高层运行时架构图。
只保留 8~12 个最核心的业务模块与依赖组件，明确标出外部云服务与信任边界。
运行校验并修复所有连线遮挡，最终原子交付到 docs/architecture.html。”

Agent 会自动在后台：

1. 提取或构思系统拓扑；
2. 编写 architecture.json；
3. 运行 archify validate 获取校验反馈并局部微调；
4. 运行 archify deliver 原子生成可交付的 HTML，甚至直接为你一键导出高清分享卡片。

五、 总结与行业思考

从软件工程的发展历程来看：

• 第一阶段是 手工绘图（Diagram-as-Art）：人类在纸上、白板上和 Visio 里画图，充满艺术感但无法维护；
• 第二阶段是 文本即代码（Diagram-as-Code）：Mermaid 和 PlantUML 把图变成了纯文本，实现了 Git 版本控制，却受制于生硬的自动布局与静态死图的局限；
• 而以 Archify 为代表的第三阶段，正式开启了 智能体架构系统地图（Architecture-as-Agent-Memory） 的新时代。

它深刻洞察了 AI 时代的核心痛点：AI 编写代码的速度呈指数级增长，人类工程师对宏观架构的把控与审查能力必须同步升级。

Archify 通过类型化 IR、确定性编译器门禁、机器可读的修复闭环、以及六维可交互的单文件看板，不仅彻底终结了“丑陋 Mermaid”的时代，更为人机协同研发构建了一座看得清、摸得着、测得准的坚实信任桥梁。

如果你受够了箭头乱飞的陈旧流程图，或者正在搭建自己的 AI Coding Agent 自动化管线，Archify 绝对值得你今天就装进工具箱。

🔗 关联资源与开源地址

• 官方开源仓库：https://github.com/tt-a1i/archify
• 在线交互式作品集（Proof Lab）：https://tt-a1i.github.io/archify/gallery.html
• 场景选图指南：https://tt-a1i.github.io/archify/guide.html