lijianfei.com

在日常深度使用 Claude Code、Cursor 与 Codex 等各类 AI 编码助手的过程中，我时常感叹大模型在代码重构、测试编写与跨框架迁移上的惊人执行力。然而，每当我尝试让 Agent “画一张系统整体架构图”或“梳理一下核心业务时序”时，生成的视觉成果往往瞬间将我拉回现实——满屏千篇一律、色彩突兀的浅蓝与浅绿圆角矩形，毫无章法的连线穿越，以及毫无层级可言的文字排版，也就是海外开发者圈子戏称的“Mermaid 视觉灾难”（Mermaid Slop）。

为了摆脱这种要么对着粗糙的默认图表皱眉、要么被迫切入 Figma 或 Excalidraw 手工折腾半小时的尴尬割裂，设计师兼创业者 Cathryn Lavery 开源了近期在 GitHub 上狂揽超过 6.3 万 Star 的标杆级 Agent 技能库——Diagram Design。它没有选择构建庞大臃肿的前端渲染器，而是将顶尖出版物的设计法则提炼为一套高确定性的 Agent 视觉约束，驱动模型直接生成无须任何第三方运行时、完全自包含的单文件 HTML 与内联 SVG。我通读了该项目的全套规范体系、语义解析脚本与对比度自检管线，对这套把“杂志级审美”系统性注入 AI Agent 的前沿工程实践进行了全链路拆解。

一、 审美危机：为什么传统 AI 架构制图总像“半成品”？

在技术写作与工程文档沉淀中，图表从来不只是纯粹的信息载体，更是技术架构审美与系统思考深度的第一张门面。然而在主流 AI 助手的生成链路中，架构图长期陷于两大极端的拉扯之中：

flowchart LR
    subgraph TraditionalPain ["传统 AI 制图的两极困境"]
        direction TB
        P1["文本 DSL 渲染派<br/>(Mermaid / PlantUML)"] --- R1["优势：Git 友好、文本可 Diff<br/>痛点：默认排版粗糙、连线碰撞严重、缺乏品牌与出版级层级"]
        P2["手动拖拽画板派<br/>(Figma / draw.io / Excalidraw)"] --- R2["优势：视觉表现上限高、自由度大<br/>痛点：打断 Agent 自动化心流、修改耗时漫长、无法闭环交付"]
    end

    subgraph Solution ["Diagram Design 的解题破局"]
        D1["Agent 级出版约束引擎<br/>45 种预置范式 + 语义优先 + 4px 网格 + 零运行时自包含 HTML/SVG"]
    end

    TraditionalPain ==> Solution

1. 结构与表现的割裂

Mermaid 作为基于文本的图表 DSL，核心设计目标是“轻量化与 Git 版本控制”，它将布局与渲染完全交由底层的 Dagre / D3 算法自动计算。但算法缺乏人类设计师的“视觉权重感知”：

• 节点之间等宽等距机械排列，无法凸显核心网关与边缘从属服务的优先级；
• 标签过长时文字溢出或生硬折行；
• 默认配色饱和度过高或灰暗混杂，直接截取放入技术白皮书、融资路演 PPT 或官方技术博客时，显得极度业余。

2. 人类“Taste”与机器执行的脱节

很多工程师在 Prompt 中向大模型强调“请设计得好看一点”、“符合现代简约风”，但模型依然只能吐出带着浅灰阴影和渐变色块的平庸设计。正如 Cathryn Lavery 在项目设计动机中所言：

“大模型本身完全理解系统的内容与拓扑关系，它唯一缺失的是真正的设计品味（Taste）。因此，我必须将这些品味用不可逾越的代码与文字规则一条条焊死。”

针对这些长期痛点，Diagram Design 确立了一套反直觉却极其严苛的设计哲学：

二、 45 种出版范式：从“视觉挑图”转向“语义行为路由”

Diagram Design 最具震撼力的一点，是它一次性梳理并内置了 45 种专业级的视觉图表范式。但它绝非简单的“模板大杂烩”，在其核心规范体系 SKILL.md 与 references/semantic-patterns.md 中，它强制推行了一套 “语义行为模式优先（Semantic Pattern First）” 的路由算法。

1. 语义行为优先的路由逻辑

许多开发者或普通模型在画图时的第一反应是“我想画一个流程图”或“我想画几个方框”。Diagram Design 彻底颠覆了这种流于表面的思考，强制 Agent 首先识别系统在行为、风险、控制或生命周期层面的本质特征：

flowchart TD
    Start["开发者自然语言需求<br/>(例如：展示鉴权网关的限流与降级过程)"] --> PatternMatch{"第一步：匹配底层语义行为模式<br/>(Semantic Pattern)"}

    PatternMatch -->|"多生产者竞争有限服务容量"| P1["扇入排队 / 瓶颈模式<br/>(Fan-in queue / bottleneck)"]
    PatternMatch -->|"跨阶段重复问询、治理与产出插槽"| P2["阶段插槽框架模式<br/>(Stage framework)"]
    PatternMatch -->|"松散对话或请求收敛为结构化记录"| P3["非结构化输入 → 结构化资产模式<br/>(Unstructured → Structured)"]
    PatternMatch -->|"规则逐项比对并寻找首个分歧点"| P4["配对策略评估路径模式<br/>(Paired policy-evaluation)"]
    PatternMatch -->|"受信边界穿透与阻断路径"| P5["安全铺装道路模式<br/>(Secure paved road)"]
    PatternMatch -->|"补偿式纵深防御与残余风险转移"| P6["补偿性安全层模式<br/>(Compensating security)"]

    P1 --> V1["映射布局：Data Flow (数据流图)"]
    P2 --> V2["映射布局：Process (阶段工序图)"]
    P3 --> V3["映射布局：Data Flow (流转图)"]
    P4 --> V4["映射布局：Flowchart (分支决策图)"]
    P5 --> V5["映射布局：Architecture (架构拓扑图)"]
    P6 --> V6["映射布局：Layer Stack (层级堆叠图)"]

    V1 & V2 & V3 & V4 & V5 & V6 --> GridEngine["第二步：注入 4px 网格与自适应品牌色板"]
    GridEngine --> Output["第三步：输出出版级自包含 HTML 文件"]

2. 代表性出版级拓扑形态

在 45 种范式中，除了常规的架构拓扑、时序图与状态机之外，Diagram Design 引入了大量传统图表库极其罕见、却在高端工业报告与系统白皮书中不可或缺的硬核范式：

1. 架构变更对比矩阵（Architecture Delta）：
   专为系统重构设计。左侧展示重构前拓扑（Before），右侧同步对齐展示重构后拓扑（After），底部附带结构化的“变更账本”（Changes Ledger），用统一的视觉标尺直接对比节点消除、链路缩短与协议升级；
2. 爆炸轴测分解图（Exploded Axonometric）：
   借鉴工业设计制图语言，将一整套复杂的软硬件系统或平台分层，沿着斜向轴线进行立体等距拉伸“炸开”，以极富透视感的三维视觉展现内核层、驱动层、服务层与应用层的物理/逻辑堆叠次序；
3. 轴测平面规划图（Axonometric Plan）：
   从斜俯视角度精准展现物理机房、数据中心机柜集群或多园区组网规划；
4. 湖仓架构（Medallion Architecture）：
   原生针对现代数据平台的铜（Bronze Raw）、银（Silver Cleaned）、金（Gold Aggregated）三层数据流转、清洗过滤与权限策略进行标准化建模；
5. 双向策略评估分歧图（Paired Policy-Evaluation Traces）：
   同时跟踪两条极为相似的请求链路，在逐条规则匹配（PASS、FAIL、SKIPPED、NOT REACHED）中，精确用显式标签标定二者产生行为偏离的“第一分歧点”（First Divergence）。

三、 零运行时黑魔法：纯粹的自包含 HTML + 内联 SVG 引擎

绝大多数现代图表工具为了追求交互效果，往往需要引入庞大的 JavaScript 打包体积、WebAssembly 核心甚至是无头浏览器（Puppeteer）进行服务端位图截图。而 Diagram Design 的技术选型极其纯粹与克制：只交付单文件 HTML 与纯原生内联 SVG。

classDiagram
    class StandaloneHTML {
        +DOCTYPE html
        +Semantic Head
        +Inline CSS Variables
        +Font Stack (Web / System)
        +Frame Container (max-width: 1200px)
        +SVG Root (Responsive ViewBox)
    }

    class InlineSVG {
        +viewBox: 0 0 960 600
        +role: "img"
        +aria-labelledby: "title-id desc-id"
        +defs (Markers, Filters, Patterns)
        +Background Rect (#f5f5f5 / #2d3142)
        +Hairline Rules (1px)
        +Topological Nodes
        +Connectors & Flow Lines
    }

    class StyleEngine {
        +Paper Token
        +Ink Token
        +Muted Token
        +Accent Token (Burnt-Tangerine)
        +Rule Token (Hairline rgba)
    }

    StandaloneHTML *-- InlineSVG
    StandaloneHTML *-- StyleEngine

这种架构带来了四个极其霸道的工程优势：

1. 绝对的便携性与零依赖

生成的 .html 文件体积通常只有几十 KB，没有任何打包构建步骤，不需要起本地开发服务器。无论双击直接通过浏览器查看，还是发送给协作方、嵌入企业 Wiki 内部，都不会遭遇诸如“版本不兼容”、“CDN 资源加载失败”或“跨域脚本拦截”的问题。

2. 印刷与暗色原生三态

每个图表模版都天然衍生并校验了三种渲染变体：

• 简约亮色（Minimal Light）：白烟底色（#f5f5f5）搭配深碳墨色（#2d3142），专为日间高亮阅读与 Paper 论文印刷优化；
• 极简暗色（Minimal Dark）：暗灰底色（#2d3142）搭配乳白文字（#f5f5f5），强调色微调增亮（#f08a59），完美契合现代 IDE 与夜间技术文档；
• 全量出版（Full-Editorial）：带有杂志级眉标、副标题、图解脚注与精致背景微网格（Dotted Paper）。

3. 严苛的字阶系统（Typography Ramp）

Diagram Design 拒绝随意的字体大小设置，全站制定了不可违背的字体规范：

┌────────────────────────────────────────────────────────┐
│ Title: Instrument Serif (1.75rem, 400 权重, 优雅衬线) │
├────────────────────────────────────────────────────────┤
│ Node Name: Geist (12px, 600 权重, 现代无衬线高清晰度)  │
├────────────────────────────────────────────────────────┤
│ Sublabel: Geist Mono (9px, 400 权重, 端口/协议/类型)  │
├────────────────────────────────────────────────────────┤
│ Eyebrow: Geist Mono (7~8px, 500, tracked 0.18em, 全大写)│
└────────────────────────────────────────────────────────┘

当需要离线环境或禁止加载 Google Fonts 时，只需传入 --system-fonts 参数，全套样式立即平滑降级至系统的无衬线与等宽字体堆栈，并自动保留 8px 的内边距缓冲区，防止字体度量差异造成容器挤压。

4. 深度无障碍契约（Accessibility Contract）

每个内联 SVG 均原生挂载 role="img" 与明确解析的 aria-labelledby，首层子节点严格包含 <title> 与 <desc>。所有节点 ID 均按图表 Slug 隔离前缀，即使在一张长页面中同时内联十几个 SVG，也绝不会发生 DOM ID 碰撞。

四、 品牌一键克隆（Onboarding Engine）：自动采色与 WCAG 验真

过去在团队中推行统一制图规范，最困难的就是“品牌资产适配”。每个团队都有自己的主色调、背景基色与字体要求，往往需要设计师专门输出一套规范手册，开发者在实际调用时依然错漏百出。

Diagram Design 独创了 Onboarding 自动化提取引擎。在与 Agent 对话时，只需一句指令：

onboard diagram-design to https://example.com

1. 自动化色彩与字体解析流水线

sequenceDiagram
    autonumber
    actor Dev as 开发者 / 架构师
    participant Agent as AI Coding Agent
    participant Browser as Headless 渲染浏览器
    participant StyleGuide as 样式规范核心 (style-guide.md)
    participant CI as 对比度校验器 (verify-contrast.py)

    Dev->>Agent: onboard diagram-design to https://mysite.com
    Agent->>Dev: 确认外部 URL 访问信任授权
    Dev-->>Agent: 授权确认
    Agent->>Browser: 抓取首页与博客页渲染 DOM 及截图
    Browser-->>Agent: 返回计算样式 (getComputedStyle) 与直方图
    Agent->>Agent: 语义角色映射 (body bg -> paper, CTA -> accent...)
    Agent->>CI: 发起 WCAG AA 对比度契约校验
    alt 对比度不达标 (如亮色文字 < 4.5:1)
        CI-->>Agent: 警告：当前强调色在白底对比度仅 2.8:1
        Agent->>Agent: 自动色相微调加深直至达标 (>= 4.5:1)
    end
    Agent->>Dev: 展示 Token 差异并请求确认
    Dev-->>Agent: 确认应用
    Agent->>StyleGuide: 写入专属语义 Token 并生成 Profile

2. 严苛的 WCAG 2.x 对比度数学契约

Diagram Design 的核心仓库内嵌了独立的自动化校验脚本 verify-contrast.py。它拒绝“靠眼睛主观感觉好看”，而是将色彩搭配转化为严格的数学不等式：

1. 常规文字与语义标签：无论在亮色背景还是暗色背景上，文字对比度必须绝对高于 4.5:1；
2. 关键非文字图形元素：箭头、连线、边框轮廓、数据节点必须绝对高于 3:1；
3. 半透明色块动态合成：所有 rgba() 填充必须先在底层 paper 颜色上进行真实 Alpha 混合后，再计算实际感官对比度，杜绝因半透明叠加引发的失焦。

五、 逆向重绘流水线：把现存的“丑图”优雅洗白

很多老项目已经在 Markdown 中沉淀了大量的 Mermaid 流程图或 .drawio、.excalidraw 文件。Diagram Design 并不仅仅是一个“新图生成器”，它内置了强大的 逆向重绘（Redraw）流水线。

在项目源码的 skills/diagram-design/scripts/ 目录下，附带了完全不依赖第三方重量级库的解析引擎：

• mermaid_extract.py：Mermaid 语法 AST 提取器；
• drawio_extract.py：draw.io 压缩 XML 结构解析器；
• excalidraw_extract.py：Excalidraw JSON 元素萃取器。

flowchart LR
    subgraph InputSources ["输入源 (Untrusted Data)"]
        M1["Mermaid (.mmd / Markdown)"]
        M2["draw.io (.drawio XML)"]
        M3["Excalidraw (.excalidraw JSON)"]
    end

    subgraph IR_Stage ["中间表示层 (IR Extraction)"]
        Extract["提取拓扑关系与层级结构<br/>(剔除原始 classDef、内联颜色与生硬坐标)"]
    end

    subgraph Degrade_Ladder ["语义降噪梯子 (Degrade Ladder)"]
        D1["删除无连接的废弃节点"] --> D2["折叠层级过深的从属容器"]
        D2 --> D3["基于拓扑度数识别 1~2 个 Hub 节点"]
    end

    subgraph Output_Stage ["出版级重绘输出"]
        Redraw["重新投射到 4px 网格<br/>应用品牌样式与 1px 发丝线"]
    end

    InputSources --> Extract --> Degrade_Ladder --> Redraw

为什么它叫“重绘”而非“转换”？

很多自动化工具在做图表格式转换时，仅仅是把 Mermaid 渲染出的坐标直接复制过去，这导致原图的拥挤、混乱完全被继承了下来。

Diagram Design 的重绘哲学截然相反：

1. 彻底丢弃原图坐标与主题：原图中的字体、配色、圆角与折线路径全部视为垃圾数据被直接抛弃，仅提取节点身份、父子容器关系与拓扑流向；
2. 应用语义降噪梯子（Degrade Ladder）：若原图过于臃肿，自动识别并合并次要边缘节点，丢弃孤立无连线的无效注释；
3. 重新确立单焦点：基于节点的度数中心性（Degree Centrality），精准识别系统运转的核心枢纽，为其赋予唯一的 accent 珊瑚橙高亮，其余节点自动降级为标准墨水色；
4. 重新排布于 4px 网格：从零构建纯净的 SVG viewBox，以完美的网格呼吸感呈现出重获新生的架构全景。

六、 实战踩坑与架构设计启示

在我将 Diagram Design 接入自身日常的 Agent 工作流与系统架构评审的过程中，我体会到了这套工具带来的技术震撼，同时也总结出了一些极高价值的实操认知与边界把握：

1. 什么时候该用它？什么时候老老实实用回 Mermaid？

• 必须使用 Diagram Design 的场景：对外公开发布的技术博客、给客户或投资人演示的技术白皮书、系统主架构图、以及长周期固化的核心协议拓扑。此时视觉体验与可读性是第一优先级，出版级图表能建立极强的专业信任感；
• 依然推荐 Mermaid 的场景：在 GitHub Pull Request 中临时展示某个微小函数的判断分支、每日高频变更的内部原型设计。因为 Mermaid 的文本本质在 Git 差异比对中具有不可替代的轻量优势，而 SVG 一旦变动往往会导致数十行坐标的 Diff 扰动。

2. 对 AI Agent 工具体系的深层启示

Diagram Design 的爆火，标志着 AI 工具链正在从“功能可用”迈向“审美工业化”的关键分水岭：

[!NOTE] 核心架构启示
在 LLM 时代，不要指望用空泛的修饰词教大模型学会“审美”。真正的品味落地，必须依赖系统级的确定性约束：通过 4px 空间网格物理量化留白，通过 1~2 个单焦点限制视觉贪婪，通过数学级的对比度契约守住可读性底线，再通过零运行时单文件架构守住工程交付的确定性。

Cathryn Lavery 为整个 AI 社区树立了一个教科书般的标杆：将人类专业领域几十年的顶级设计经验，转化为机器能够毫厘不差严格执行的 Agent 规范。让工程师即使不打开复杂的矢量设计软件，也能在 AI 的加持下，随手交付出宛如刊登在《连线》或《经济学人》上的艺术级架构蓝图。

原文链接与参考资料

• Diagram Design 官方开源仓库：GitHub - cathrynlavery/diagram-design
• Diagram Design 官方交互式画廊：Diagram Design Live Gallery
• Diagram Design 官方网站：diagramdesign.dev
• Cross-Agent Skills 跨平台技能分发中心：skills.sh - cathrynlavery/diagram-design
• 作者个人博客与设计手记：LittleMight - Cathryn Lavery