Markdown Mermaid Illustrator

markdown-mermaid-illustrator

概述

分析 Markdown 技术文档，生成高质量的 Mermaid 图表，用户确认后替换。混合模板匹配与 LLM 理解两条路径。

解决的核心痛点：

适用场景

• 为技术文档新建 Mermaid 图表（架构图、流程图、时序图、概念图、决策树）
• 重构现有图表修复 Dark 模式兼容问题
• 将 ASCII 图表升级为 Mermaid 格式

运行环境

跨平台：纯文本处理，适配 GitHub、GitLab、Obsidian、MkDocs、Docusaurus 等所有支持 Mermaid 的环境。

图表类型路由指南

第零步：不确定时主动询问用户

当以下任意情况出现时，必须先询问用户再动手，不要自行猜测：

• 同一内容可以用 2 种以上截然不同的图表类型表达（如"关系"可以是流程图、思维导图或 ER 图）
• 用户描述含有模糊词（"画个图看看""展示一下关系""做个分析"）
• 内容涉及数据可视化，不确定是否有具体数据

询问格式（输出给用户）：

我理解你想表达「[内容摘要]」，有以下几种图表方式，你倾向于哪种？

1. [图表类型 A]——[一句话说明适合原因]
2. [图表类型 B]——[一句话说明适合原因]
3. [图表类型 C]——[一句话说明适合原因]（如有第三选项）

或者告诉我你的偏好，我来设计。

图表类型速查表

✅ Mermaid 原生支持（直接生成）

⚠️ Mermaid 近似支持（有局限，先告知用户）

❌ 超出 Mermaid 能力范围（告知用户并推荐替代工具）

当内容落入"超出范围"时，不要强行用 Mermaid 近似，应告知用户局限并推荐替代工具，再询问是否仍想要 Mermaid 的近似版本。

核心设计规范

规范 1：Frontmatter 配置

每个图表头部必须包含：

---
config:
  theme: neutral
  look: neo
---

• theme: neutral：中性主题，文字颜色由渲染引擎自动计算。
• look: neo：圆角现代风格。

GitHub 特例：GitHub 会根据用户 appearance 设置自动切换 Mermaid 主题，但前提是图表无任何 config / %%{init}%% 指令。若目标平台只有 GitHub，可省略 Frontmatter 完全依赖自动切换；其他平台保留。

规范 2：节点配色——中饱和度色板

为什么不用浅色系（如 #e3f2fd）？ Mermaid classDef 的 fill 是固定 hex，不随 dark/light 模式变化。浅色系在暗色背景下产生刺眼"亮泡"效果。中饱和度填充色（L ≈ 40-60%）在两种背景下都有足够视觉重量，且渲染引擎能从中正确推断文字颜色。

禁止写法：

%% 禁止 1：硬编码文字颜色
style NodeA fill:#4A90D9,stroke:#333,color:#fff

%% 禁止 2：浅色系 fill（dark 模式下亮泡）
classDef core fill:#e3f2fd,stroke:#1976d2,stroke-width:2px

正确写法：

%% classDef 不指定 color，引擎自动适配
classDef core fill:#3D7DC8,stroke:#1A4E8A,stroke-width:2px
NodeA:::core

推荐节点色板（Light / Dark 双模式兼容）：

规范 3：subgraph 背景色

问题：rgba() 不被 Mermaid 解析器支持；8位 hex（#RRGGBBAA）同样不支持。 解法：用中色调实色（L ≈ 70-80%），通过底部 style SubgraphID 指令单独设置，每个 subgraph 可独立配色。

flowchart LR
    subgraph Local["🖥️ 本地环境"]
        A:::core --> B:::data
    end
    subgraph Cloud["☁️ Cloud 服务端"]
        C:::ext
    end

    style Local fill:#C4D3E8,stroke:#5599CC,stroke-width:2px
    style Cloud fill:#E8D5B8,stroke:#CC8833,stroke-width:2px

推荐 subgraph 背景色板：

subgraph 背景色应比对应节点色更浅（L 高 20-30%），形成明确的层次感。虚线外框（stroke-dasharray:5 5）区分外部/第三方区域。

规范 4：布局方向

默认 LR（从左到右），仅在以下情况用 TD：

• 明确表达"层级从上到下"语义（如决策树）
• 节点数 ≤ 5 且无分支

多层级叠加：外层 flowchart LR，subgraph 内部 direction TB：

flowchart LR
    subgraph L1["第一层"]
        direction TB
        A --> B
    end
    subgraph L2["第二层"]
        direction TB
        C --> D
    end
    L1 --> L2

文本换行：超过 6 个字用 <br/>：

A(["执行核心<br/>业务逻辑"])   %% 正确
A(["执行核心业务逻辑并返回处理结果"])  %% 错误

规范 5：形状语义化

规范 6：图标增强

每个节点文本前置一个 Emoji。以下为参考，不限于此——根据节点具体语义自主推断最贴切图标，同一图表内不同语义节点使用不同图标，所有 subgraph 标题也带图标：

• 用户/入口：👤 🧑‍💻
• 启动/发布：🚀
• 数据/存储：💾 🗄️ 📦
• 认证/安全：🔐 🔑 🛡️
• 执行/处理：⚡ ⚙️ 🔧
• 观察/检查：👁️ 🔍 📊
• 完成：✅ 🎯    失败：❌ ⚠️
• AI 推理：🧠 💭    循环：🔄
• 网络/云：☁️ 🌐 📡
• 文件：📄 📁 📝    消息：📨 🔔
• 时间：⏱️    配置：🎛️

规范 7：线条语义化

A ==> B      %% 主链路（同步调用）粗实线
A --> B       %% 普通流程细实线
A -.-> B      %% 异步/事件/缓存虚线
A -->|"说明"| B   %% 带标签（用双引号）
A & B --> C   %% 并列汇聚
A ~~~ B       %% 不可见连接（仅对齐布局用）

规范 8：对称性设计

在不牺牲语义的前提下主动追求布局对称：

subgraph 节点均衡：并列 subgraph 内节点数尽量相等。节点少的一侧可拆分信息或补充关联节点，或用 ~~~ 添加对齐占位。

同层节点对齐：用 ~~~ 声明同层关系：

R1 ~~~ R2 ~~~ R3   %% 强制 R1 R2 R3 视觉等高

节点宽度一致：同类节点文本长度应相近，用 <br/> 调整换行点使节点宽度趋于统一。

规范 9：语法自检清单

输出前逐项确认：

• Frontmatter 包含 theme: neutral + look: neo
• 节点 ID 纯英文字母/数字，无中文、空格、特殊符号
• 含括号/引号/斜杠的显示文本用双引号包裹：A["User (Client)"]
• 无 color:#fff / color:#000 硬编码文字颜色
• classDef 定义在图表顶部（紧跟类型声明）
• subgraph 标题用双引号：subgraph ID["标题"]
• classDef fill 使用中饱和度色（非浅色系）
• subgraph 背景通过 style ID fill:...,stroke:... 设置（文件底部）
• 超过 6 字的节点文本使用 <br/> 换行
• 各 subgraph 节点数大致均衡，同层节点已 ~~~ 对齐
• 未使用实验性语法（block-beta、architecture 等）

标准模板库

模板 A：分层架构图

---
config:
  theme: neutral
  look: neo
---
flowchart LR
    classDef core fill:#3D7DC8,stroke:#1A4E8A,stroke-width:2px
    classDef data fill:#48A880,stroke:#256B4E,stroke-width:2px
    classDef ext  fill:#D4822A,stroke:#8B5000,stroke-width:2px

    subgraph Client["👤 客户端层"]
        direction TB
        Web(["🌐 Web App"]):::core
        App(["📱 Mobile App"]):::core
    end

    subgraph Services["⚙️ 核心服务层"]
        direction TB
        Auth(["🔐 Auth"]):::core
        Biz(["⚡ Business"]):::core
    end

    subgraph Storage["💾 数据层"]
        direction TB
        DB[("🗄️ PostgreSQL")]:::data
        Cache[("⚡ Redis")]:::data
    end

    Client --> Services
    Services ==> DB
    Services -.-> Cache

    style Client   fill:#C4D3E8,stroke:#5599CC,stroke-width:2px
    style Services fill:#D0C8E8,stroke:#9977DD,stroke-width:2px
    style Storage  fill:#C4D8CC,stroke:#55AA88,stroke-width:2px

模板 B：流程图（带判断分支）

---
config:
  theme: neutral
  look: neo
---
flowchart LR
    classDef core    fill:#3D7DC8,stroke:#1A4E8A,stroke-width:2px
    classDef warning fill:#D97F2A,stroke:#8B4500,stroke-width:2px
    classDef danger  fill:#C94444,stroke:#8B1A1A,stroke-width:2px

    Start(["🚀 开始"]) --> Check{"🔐 校验<br/>权限"}:::warning
    Check -- "通过" --> Process(["⚡ 执行<br/>核心逻辑"]):::core
    Check -- "拒绝" --> Reject(["❌ 返回<br/>403 错误"]):::danger
    Process --> DB[("💾 保存数据")]
    DB --> End(["✅ 结束"])
    Reject --> End

模板 C：Agent 循环（Think-Act-Observe）

---
config:
  theme: neutral
  look: neo
---
flowchart LR
    classDef brain   fill:#7055BB,stroke:#412A88,stroke-width:2px
    classDef action  fill:#3D7DC8,stroke:#1A4E8A,stroke-width:2px
    classDef observe fill:#48A880,stroke:#256B4E,stroke-width:2px
    classDef io      fill:#D97F2A,stroke:#8B4500,stroke-width:2px

    User(["👤 用户输入"]) --> Think

    subgraph Loop["🔄 Agent 循环"]
        direction LR
        Think(["🧠 思考<br/>规划意图"]):::brain
        Act(["⚡ 执行<br/>调用工具"]):::action
        Observe(["👁️ 观察<br/>读取结果"]):::observe
        Think --> Act --> Observe --> Think
    end

    Observe --> Done{"✅ 完成？"}
    Done -- "否" --> Think
    Done -- "是" --> Output(["📤 输出结果"]):::io

    style Loop fill:#D0C8E8,stroke:#9977DD,stroke-width:2px

模板 D：时序图

---
config:
  theme: neutral
  look: neo
---
sequenceDiagram
    autonumber
    participant U as 👤 用户
    participant G as ⚙️ Gateway
    participant A as 🔐 Auth
    participant S as 🚀 Service
    participant D as 💾 DB

    U->>G: POST /api/data
    G->>A: 验证 Token
    A-->>G: ✅ 通过
    G->>S: 转发请求
    S->>D: 查询数据
    D-->>S: 返回结果
    S-->>G: 200 + payload
    G-->>U: 响应数据

模板 E：决策树

---
config:
  theme: neutral
  look: neo
---
flowchart TD
    classDef decision fill:#D97F2A,stroke:#8B4500,stroke-width:2px
    classDef result   fill:#48A880,stroke:#256B4E,stroke-width:2px
    classDef hot      fill:#C94444,stroke:#8B1A1A,stroke-width:2px

    Q1{"🤔 最在意<br/>什么？"}:::decision
    Q1 -- "性能优先" --> R1(["🚀 方案 A"]):::hot
    Q1 -- "成本优先" --> Q2{"🌍 国内还是<br/>海外？"}:::decision
    Q1 -- "开源可控" --> R3(["🔓 方案 C"]):::result
    Q2 -- "国内"     --> R2A(["🏠 方案 B1"]):::result
    Q2 -- "海外"     --> R2B(["✈️ 方案 B2"]):::result

    R1 ~~~ Q2 ~~~ R3

流程步骤

1. 分析文档 — 识别所有插图位置（已有 Mermaid 块、ASCII 图、应配图章节），产出插图清单。

2. 选模板 — 匹配 templates/ YAML 的关键词，选最近似模板；无匹配时 LLM 自主设计。

3. 设计图表 — 默认 flowchart LR；按规范 2-8 分配形状、色板、图标、subgraph 背景、对称布局。

4. 自检 — 按规范 9 清单逐项核对。

5. 展示确认 — 输出完整可渲染代码，用户选择：满意 / 重新生成 / 修改建议。

6. 应用 — 替换原文档对应区域。

7. 模板沉淀（可选） — 被采纳的 LLM 方案可保存为新 YAML 模板。

注意事项

• 每次输出的 Mermaid 代码必须完整可渲染，不输出片段或省略号。
• 时序图（sequenceDiagram）本身纵向，不适用"默认 LR"规则；参与者数量控制在 ≤ 7 个。
• Mermaid 不支持 rgba() 或 8位 hex alpha（#RRGGBBAA）——务必使用标准 6位 hex。
• 图表文本与文档语言保持一致。

Token 约束

• Mermaid 代码生成后不重复粘贴，只确认已写入文件。
• 文档内容只读取必要部分，不全文复制。