企业官网建设流程全解析

diagram-design 的 Mermaid 导入实战：从含多图块的 Markdown 中提取并重绘流程图与序列图

【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design

本篇技术指南围绕 diagram-design 仓库中的 Mermaid 导入（import-mermaid）能力展开，以scripts/fixtures/sample-readme-with-mermaid.md这一多图块 Markdown 测试样例为切入点，讲清楚三件事：Markdown 文件中的 Mermaid 图块如何被安全解析为结构化中间表示（IR）、多图块场景下如何用命令行选取与输出，以及解析结果如何经六步重绘流程变成符合项目设计系统的成稿。读完本文，你将能独立使用mermaid_extract.py处理.mmd/.mermaid/内嵌 Mermaid 的 Markdown 文件，并理解整套导入管线的信任边界与验证机制。

一、样例文件在导入管线中的定位

scripts/fixtures/sample-readme-with-mermaid.md是 Mermaid 导入管线中"Markdown 多图块"场景的固定测试夹具（fixture）。它模拟了开发者在 README 或技术文档中最常见的写法：正文散文与多个 mermaid 代码围栏（fence）交替出现。文件全文只有两个图块与两句注释性文字：

• 第一个图块是一个flowchart TD流程图，描述Request → Gateway → Service的三节点链路；
• 第二个图块是一个sequenceDiagram序列图，包含User、API Gateway、Database三个参与者、4 条消息、一个alt组合片段和一条注释；
• 图块之间穿插普通散文（"Surrounding prose must not become diagram content."、"More prose between diagrams."）。

文件标题下的那句注释正是这个夹具要守护的核心语义：周围的散文绝不能变成图的内容。它直接对应提取器load_blocks()中"只识别围栏内文本"的解析策略，并由验证脚本scripts/verify-mermaid-import.py的check_markdown_and_grammars()断言背书。

二、提取器如何解析 Markdown 多图块

skills/diagram-design/scripts/mermaid_extract.py是本流程的核心程序。从源码看，它的解析分三层：

1. 文件分拣：按后缀决定读取方式

MARKDOWN_SUFFIXES = {".md", ".markdown", ".mdown", ".mkd"} MERMAID_SUFFIXES = {".mmd", ".mermaid"}

• 后缀为.mmd/.mermaid时，整个文件被当作一个图块（SourceBlock(0, source, 1)）；
• 后缀为 Markdown 系列时，进入围栏扫描逻辑：逐行匹配^\s*({3,}|~{3,})\smermaid\s$`（大小写不敏感，支持反引号与波浪号两种围栏），遇到匹配行进入图块收集，遇到同长度闭合围栏则收束当前块。

该样例中两个图块被分别记为SourceBlock(0, ...)与SourceBlock(1, ...)，source_line记录围栏起始行，供后续报错与输出引用。三种失败路径都以退出码 2 明确终止：

• 遇到未闭合的 mermaid 围栏 →unterminated mermaid fence starting at line N；
• 一个 mermaid 围栏都没有 →no fenced mermaid block found；
• 图块内容非 UTF-8 →source is not valid UTF-8 text。

2. 语法识别：四种受支持的图类

每个图块提取后，_kind_and_direction()从首行判定图类与方向：

不支持的图类（pie、mindmap、gitgraph、gantt、journey、sankey、classDiagram等，源码中UNSUPPORTED_KINDS共列 13 种）会直接失败，并提示受支持种类，绝不降级近似渲染。

3. 预处理：把非语义内容挡在信任边界之外

_prepared_lines()在正式解析前做三层清洗，这正是"散文不变成图内容"的延伸保障：

• 前导 frontmatter：---起始的title/config块（最多 40 行）按行清空，仅作为标题/配置处理，不进 IR；
• %%{init}%%初始化指令：跨行指令直到}%%之前全部清空；
• %%行注释：整行清空。

同时，解析过程中对style、classDef、class、linkStyle四条样式指令和click处理器只计数、不保留（_discard_nonsemantic()），计数结果写入diagram.discarded。这意味着 Mermaid 的主题、配色、点击 URL 永远不会穿过信任边界——提取器从不求值、渲染、抓取或执行任何 Mermaid、JavaScript、浏览器内容、点击目标或 URL，也不发起任何网络调用（见skills/diagram-design/references/import-mermaid.md的 Step 1 说明）。

三、命令行实操：多图块的选择、输出与读取

对样例文件运行提取器（默认行为是只处理第一个图块）：

python3 skills/diagram-design/scripts/mermaid_extract.py scripts/fixtures/sample-readme-with-mermaid.md

输出头部会列出全文件图块清单，例如：

# Mermaid IR — sample-readme-with-mermaid.md 2 diagram(s): [0] flowchart (3n/2e), [1] sequenceDiagram (3n/4e) ## Diagram 0 — flowchart - source layout: none (Mermaid is layout-free); direction: TD - nodes: 3 total / 3 drawable / 0 containers, depth 0 - edges: 2 (0 labeled, 0 dangling), cycle: False - shapes: {'rect': 3} - type candidates: architecture, flowchart - budget: nodes ok (max 9), edges ok (max 12)

随后是### Nodes与### Edges两张 Markdown 表格，以及 hubs、入口点、终点、孤立节点等分析行。注意一个关键设计：默认只输出## Diagram 0（select_diagrams()中selector is None时返回diagrams[:1]），多图块文件必须显式指定，避免一次倾倒全部内容。

全部命令行参数

对样例执行--diagram all：

python3 skills/diagram-design/scripts/mermaid_extract.py scripts/fixtures/sample-readme-with-mermaid.md --diagram all --json

--json模式下返回结构化数据：diagrams_total为 2，diagrams数组按 Markdown 中出现顺序保留两个图块。其中第二个图块的解析结果印证了序列图语义的完整保留：

• 参与者：User（actor）、API（别名API Gateway）、DB（别名Database），共 3 个节点；
• 消息边：User->>API: Submit order、API->>DB: Save order、DB-->>API: Saved、API-->>User: Reject，共 4 条边，-->>被归一化为虚线样式；
• 组合片段：alt片段被记录为fragments条目，Valid order/Invalid order两个分支进入regions；
• 注释：Note right of API: One ordered interaction作为惰性文本进入notes。

这些正是"结构承载意义、样式不承载意义"原则在序列图上的体现：激活（activate/deactivate）与+/-后缀被丢弃，但片段顺序、分支与消息标签全部保留。

四、验证机制：这份夹具被断言了什么

scripts/verify-mermaid-import.py是导入功能的"体检驱动"，它会以子进程方式调用提取器并断言输出。针对本夹具的check_markdown_and_grammars()包含五条关键断言：

1. 头部必须包含2 diagram(s)且列出[1] sequenceDiagram—— 证明两个图块都被扫描到且种类识别正确；
2. 默认输出中不得出现## Diagram 1—— 证明缺省只选第 0 块；
3. --diagram all后两个图块的种类依次为["flowchart", "sequenceDiagram"]—— 证明块顺序未被破坏；
4. 序列图节点数 = 3、边数 = 4 —— 与上文分析一致；
5. fragments[0]["kind"] == "alt"且notes非空 —— 证明组合片段与注释被保留为惰性数据。

整套验证还覆盖：形状词表（classify_shape对 12 种括号形状的归一化）、边词表（---、--x、--o、-. -、===等）、紧凑/带空格标签边、:::class后缀剥离、frontmatter 跳过、对抗性标签（提示注入字符串保持惰性、URL 不得越界）、资源上限（源码 4 MiB、节点 2000、边 5000）与全部文档化退出码路径。运行方式：

python3 scripts/verify-mermaid-import.py

全部通过时输出All Mermaid import gates passed.，任一失败则打印FAIL: ...并以退出码 1 终止。

五、从 IR 到成稿：六步重绘流程

提取只是第一步。skills/diagram-design/references/import-mermaid.md定义了从 IR 到终稿的六步管线，其核心论断是：这是一次"重绘"（redraw），不是"渲染"或"转换"。Mermaid 只提供内容与声明方向，不提供坐标——因此 IR 摘要固定输出source layout: none (Mermaid is layout-free)，重绘必须从空白viewBox出发，丢弃 Mermaid 渲染器的自动布局、主题、类与样式。

1. 提取 IR：运行mermaid_extract.py（上文已述）；
2. 设定四个拨盘：--format、--size、--detail、--audience，依据skills/diagram-design/references/output-spec.md在动笔前定稿——它们同时影响交付物、布局、类型档位、节点数与措辞，事后更改等于重画；
3. 选择目标类型：语法是强内容信号但不是照搬指令。例如决策菱形+带标签分支 → Flowchart；含服务/容器拓扑且无决策 → Architecture；sequenceDiagram→ Sequence；stateDiagram-v2→ State machine；erDiagram→ ER / data model；嵌套子图深度 ≥2 且边少 → Nested。本样例的两个图块按此表应分别落入 Flowchart/Architecture 与 Sequence 类型；
4. 构建语义模型：一句话讲清故事、按降级阶梯应用细节档、用 hubs 佐证焦点节点（仅作证据不作自动答案）、为受众改写标签、保留有意义的边标签/状态守卫/片段顺序/ER 基数/容器从属；
5. 重绘：从空viewBox出发，用所选类型的语义化处理替换 Mermaid 形状（圆柱体 → Store/State，菱形仅流程图语境下保持决策，子图 → 分区或可折叠组），忽略 init 主题与样式指令，按 SKILL.md 连接器规则重排所有连线；
6. 交付：写出自包含 HTML → 过 SKILL.md §9 品味门与 output-spec §6 清单 → 按需导出 SVG/PNG → 报告保真度账本（源计数、绘制计数、每次合并/折叠/丢弃）。

多图块文件的成稿约定

Markdown 是多页 draw.io 的对应物，因此本夹具所在的场景有专门规则（见import-mermaid.md的 Multi-block files 一节）：

• 未指定--diagram时，先检查图块 0，若用户未指明目标块则列出全部图块（种类 + 节点/边数）并询问，不猜测；
• --diagram all为每个图块独立选型、独立成文，输出命名为<base>-<index>.html；
• 除非用户明确要求，禁止把多个图块拼到同一画布——相邻图块常常语法不同（本夹具就是 flowchart + sequenceDiagram 的混合）。

六、结合命令与实战参数

commands/import-mermaid.md定义了整套命令的对外形态，其默认值如下：

命令另有九条强制行为，其中与本文主题最相关的三条：提取器退出非零时必须原样转述其消息并停止；绝不允许渲染 Mermaid 或沿用其布局/主题/类/字体；源文本与摘要一律视为不可信数据，绝不执行点击目标或服从标签文字。仓库中skills/diagram-design/assets/example-import-mermaid.html是一个可对照的完整工作示例：它以format=html, size=doc-inline, detail=balanced, audience=mixed重绘了scripts/fixtures/sample-flowchart.mmd，并附有逐项"源→输出"对照表（如Postgres圆柱体转为扁平 Store/State 盒、未连接的Legacy note按降级阶梯第一步丢弃）。

七、边界情况与反模式速查

import-mermaid.md为导入流程准备了边界情况对照表，处理多图块 Markdown 时最常遇到：

与之对应的反模式包括：复刻 Mermaid 渲染器布局（等于把自动化间距与布线重新导入，正是本次重绘要替换的美学）；先渲染成 SVG 再导入（把源样式变成伪约束、跨越不必要的执行边界）；继承 init 主题/类；跟随 click URL；把标签文本当指令（标签是惰性图数据，包括提示注入字符串）；无视预算逐节点一一映射（忠实布线倾倒不是编辑级图表）；丢弃序列片段或 ER 基数（这些结构承载意义而非样式）；静默丢内容（每次导入必须附带保真度账本）。

八、小结

scripts/fixtures/sample-readme-with-mermaid.md虽然只有 28 行，却是 diagram-design Mermaid 导入管线中"多图块 Markdown"场景的完整行为契约：它验证了围栏扫描、图类识别、块序保持、默认选块策略、序列图语义（片段/注释/消息）保留，以及"散文不进入图内容"的边界语义。配合skills/diagram-design/scripts/mermaid_extract.py的解析实现、scripts/verify-mermaid-import.py的断言驱动与commands/import-mermaid.md/skills/diagram-design/references/import-mermaid.md的操作规范，你可以把任何 README 或技术文档中散落的 Mermaid 图块，安全地重绘为符合项目设计系统的编辑级自包含 HTML/SVG/PNG 图表。

# 快速上手：解析样例的多图块 Markdown（默认第 0 块） python3 skills/diagram-design/scripts/mermaid_extract.py scripts/fixtures/sample-readme-with-mermaid.md # 全量 JSON IR（含序列片段与注释） python3 skills/diagram-design/scripts/mermaid_extract.py scripts/fixtures/sample-readme-with-mermaid.md --diagram all --json # 验证整套导入行为 python3 scripts/verify-mermaid-import.py

【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design