Mermaid on 潘达窝

mmdx：给 AI agent 用的 Mermaid 渲染器怎么设计

Sun, 06 Sep 2026 20:07:23 +0800

mmdx：给 AI agent 用的 Mermaid 渲染器怎么设计

上一篇《Mermaid 主题定制暗坑大全》把 mermaid 主题系统里的坑挨个盘了一遍，这篇讲我把那些教训固化成的东西：mmdx，一个给 AI agent 用的 Mermaid → SVG/PNG 导出 CLI。重点写它的主题系统组织和全覆盖颜色检测——后者是我认为这个项目里最值钱的设计。

痛点：agent 写得动 mermaid，交不出图

LLM 写 mermaid 语法的准确率已经很高了，但"写得出"和"交得出图"之间隔着一条鸿沟。我在 agent 工作流里要一张架构图时，实际发生的事情是：

agent 产出的 ```mermaid 块只能靠渲染器活着——聊天窗口里凑合看，发博客、贴 issue、放幻灯片就露馅
现有工具要么是 VSCode 插件手动导出（默认紫黄 #ECECFF 主题，上一篇吐槽过的那套），要么是 MCP 渲染服务——每个都重造一遍管线基础
agent 在别人的机器上跑，没有 Node、没有字体、主题不可控，渲染结果不可复现

所以 mmdx 的定位很明确：agent 拿着一段 markdown 就能出一个带主题的 SVG/PNG，不装 Node、不下 Chromium（复用系统 Edge/Chrome）、中文字体内置。package.json 里的一句话定位：

1
2
3
4


{
 "name": "mmdx",
 "description": "Mermaid → SVG/PNG exporter with tech-doc themes, bundled CJK font and ELK layout, built for AI agents"
}

“built for AI agents” 不是营销词，它决定了后面一堆设计取舍：CLI 契约要机器可读、输出要确定性、失败要响亮不能挂住。

主链路：五个模块，一条管线

整个 src/ 目录不到 2000 行，模块划分：

1
2
3
4
5


cli.ts 入口：参数解析、围栏块提取、主题叠加、输出契约（462 行）
render.ts 渲染核：单 Chromium + 页面池 + 截图裁切（520 行）
themes.ts 七套主题预设 + deepMerge（667 行）
blocks.ts table/list/card 扩展块转 HTML（193 行）
embed.ts 内嵌资产：mermaid UMD、ELK、字体、svgo（编译期生成）

主链路一句话：提取围栏块 → 主题配置合成 → 页面池渲染 → SVG/PNG 落盘。

flowchart LR
A[md/mmd/stdin] --> B[extractBlocks]
B --> C[主题合成
preset + theme-js + config + css]
C --> D[Renderer 页面池
mermaid.render]
D --> E[SVG 重算 viewBox]
D --> F[PNG 墨迹二次裁切]
E --> G[svgo 压缩]
G --> H[落盘 + --json]
F --> H

块提取是纯正则，FENCE_RE 扫所有围栏语言，认识的才收（src/cli.ts:161）：

1
2
3
4
5
6
7
8


// any fenced block with a recognized language (mermaid / table / list)
const FENCE_RE = /^[ \t]*```([A-Za-z0-9_-]+)[^\n]*\n([\s\S]*?)^[ \t]*```\s*$/gm;

function extractBlocks(input: string, raw: string): Block[] {
 // ... kind = fenceKind(m[1]); kind === 'unknown' 就跳过
 // 记录 line（块在原文的行号，报错时 agent 能定位回源文件）
 blocks.push({ input, base, index: blocks.length + 1, line, code, kind });
}

渲染核 Renderer 是一个类，单浏览器实例 + 页面池。每个页面初始化一次就反复渲染很多图（src/render.ts:145 的 initPage）：注入 mermaid UMD、把 ELK 的 7MB bundle 以 base64 塞进 window.__elkB64 但不解析、注入 Noto Sans SC 子集字体并强制 document.fonts.load：

1
2
3
4
5
6
7
8
9


// src/render.ts:154 — ELK 懒加载的关键
if (this.opts.layout === 'elk' && this.assets.elkJs) {
 // stash the payload; ELK is parsed lazily on the first flowchart render
 // (its 7MB bundle costs ~0.8s of parse per page and only flowchart/
 // graph diagrams ever use it)
 await page.evaluate((b) => {
 (window as any).__elkB64 = b;
 }, b64);
}

真正渲染发生在页面里（src/render.ts:260 的 page.evaluate），几个值得说的点：

1
2
3
4
5
6


mermaid.initialize({
 ...config,
 layoutAlgorithm: wantElk ? 'elk' : 'dagre',
 startOnLoad: false,
 suppressErrorRendering: true, // ← 语法错误必须 throw，不能返回"错误炸弹"SVG
});

suppressErrorRendering: true 是给 agent 的：mermaid 默认把语法错误渲染成一张带错误文字的 SVG 图，agent 拿到文件看不出问题。这里强制它 throw，错误进 --json 的 errors 数组。

SVG 拿到手后 mermaid 给的 viewBox 不能信（上一篇写过：under-measures wrapped CJK labels），所以整棵树重新量一遍。量法有个坐标系陷阱——每个叶子的 getBBox() 在自己的局部坐标系，必须经过 getCTM() 矩阵换算到根 svg 的 user space 再 union（src/render.ts:326 的 toRootRect）：

1
2
3
4


// getCTM maps into VIEWPORT space, which includes the (stale)
// root viewBox scale; divide it out so all leaves land in the
// root's own user space, the space the viewBox is written in.
const m = root.inverse().multiply(mRaw);

PNG 则走两遍截图：第一遍按几何 bounds 截，然后 inkBBox（src/render.ts:72）逐像素找墨迹包围盒，第二遍按墨迹裁——因为几何 bounds 会漏掉箭头 marker 和字形 overshoot。四边留白对称是这么构造出来的，不是靠猜：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// geometric bounds miss marker arrowheads and glyph overshoot; a
// second capture clipped to the actual ink gives pixel-exact,
// symmetric file margins
const ink = inkBBox(first);
if (!ink) return first;
const mx = Math.max(1, padX * sc - 2);
const clip = {
 x: Math.max(0, (ink.x0 - mx) / sc),
 // ... y / width / height 同理
};
return (await page.screenshot({ clip, omitBackground: transparent })) as Buffer;

这个二次截图是我最满意的实现细节之一：留白对称性从"调参调出来的"变成"构造保证的"，测试里断言 L/R 边距差就够了，不用碰玄学。

主题系统：themeVariables 集中 + themeCSS 补刀

七套预设：tech（默认）、openai / openai-dark、minimal、latte / mocha、sketch。每个预设是一个 ThemePreset（src/themes.ts:6）：

1
2
3
4
5
6


export interface ThemePreset {
 config: Record<string, unknown>; // 直接喂 mermaid.initialize
 background: string; // 页面背景，也是 edgeLabelBackground
 dark?: boolean; // 预设是否深色页
 remap?: Record<string, string>; // 渲染后 hex→hex 重着色（mermaid 写死的色）
}

组织原则一：颜色尽量收敛进 themeVariables，走官方派生链。tech 主题的 themeVariables 有 100 多个键，按图型分组注释，核心派生键放最前面（src/themes.ts:167）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


themeVariables: {
 // ---- core derivation chain: every diagram inherits from these.
 // primaryColor in particular must be set — its default (#fff4dd cream)
 // is the "native mermaid" look leaking through every unset corner.
 primaryColor: '#E8F3FF',
 primaryTextColor: '#1D2129',
 primaryBorderColor: '#4098FC',
 // ...
 // ---- pie: AntV G2 default categorical palette
 pie1: '#5B8FF9', pie2: '#5AD8A6', /* ... pie12 */
 // ---- xyChart: plotColorPalette (defaults start with mermaid purple #ECECFF)
 xyChart: { plotColorPalette: '#5B8FF9,#F6BD16,#5AD8A6,...', /* ... */ },
},

组织原则二：themeVariables 覆盖不到的用 themeCSS 补。最典型的是 flowchart 形状分色——mermaid 只给一个 primaryColor，想要"矩形=流程、菱形=判定、圆=状态、圆柱=存储"四色语义，只能 CSS 按形状选择器上色（src/themes.ts:82）：

1
2
3
4
5
6
7


/* shape-coding: mermaid variables only offer a single primaryColor for node
 shapes, so the rect=process / diamond=decision / circle=state / store=purple
 colour roles are painted here */
.node rect { fill: #E8F3FF; stroke: #4098FC; }
.node polygon { fill: #FFF7E6; stroke: #FF9A2E; }
.node circle, .node ellipse { fill: #E8FFEA; stroke: #23C343; }
.node path { fill: #F5E8FF; stroke: #722ED1; }

组织原则三：mermaid 写死在渲染产物的颜色，用渲染后 remap 兜底。sankey 的 tableau10 色板和 journey 的表情底色没有 themeVariables 通道，tech 预设带一张 remap 表，在 SVG 字符串进 DOM 之前做 hex 替换（src/themes.ts:359、src/render.ts:296）：

1
2
3
4


remap: {
 // sankey nodes/links default to the tableau10 set (no theme variables)
 '#4e79a7': '#6E94BB', '#f28e2c': '#D2A36C', /* ... */
},

1

在 render() 里：svg 字符串 → remap 逐条 replace → 才 innerHTML 进 DOM

这样 SVG 和 PNG 拿到的是同一份颜色，不会出现"PNG 对了 SVG 错了"的精神分裂。

三层的覆盖关系在 cli.ts:298 串起来，顺序是固定的：

1
2
3
4


let config = JSON.parse(JSON.stringify(preset.config)); // 1. 预设
if (o.themeJs) config = applyThemeJs(..., config, ...); // 2. --theme-js 整体改写
if (o.config) config = deepMerge(config, JSON.parse(...)); // 3. --config 深合并
if (o.css) config.themeCSS += '\n' + css; // 4. --css 追加

上一篇写过的"assignWithDepth 对数组是追加不是替换"的坑，在这里的对策就是 remap + CSS 钉死（journey actor 圆点的注释直接写在 TECH_CSS 里：config.journey.actorColours is useless — mermaid's assignWithDepth APPENDS arrays）。把踩坑结论固化成代码注释和默认行为，比写博客本身更重要——博客是给人看的，注释是给三个月后的自己看的。

全覆盖检测：像素级颜色普查

主题系统最大的风险不是"某个变量设错了值"，而是"某个角落根本没被任何变量覆盖"。20 种图型 × 100 多个主题变量，人眼看不过来——改一个变量得把 20 张图全渲染一遍肉眼扫，而且人眼对"这个蓝和那个蓝差了 5%“毫无办法。

所以检测必须系统化，分两步。

第一步：全图型渲染筛查（tests/run.ts）。tests/diagrams/ 下每图型一个 fixture——block、c4、class、er、flowchart、gantt、gitgraph、journey、kanban、mindmap、pie、quadrant、radar、requirement、sankey、sequence、state、timeline、treemap、xychart，正好 20 个。全部渲染成 PNG 后做像素分析：

1
2
3
4
5
6


// tests/run.ts:95 — 库级筛查的三个断言
const lr = Math.abs(a.margins.l - a.margins.r); // 左右边距差
const tb = Math.abs(a.margins.t - a.margins.b); // 上下边距差
if (lr > 16) problems.push(`L/R margins ${a.margins.l}/${a.margins.r}`);
if (a.ink < 0.005) problems.push('near-blank'); // 白图检测
if (a.ink > 0.85 && name !== 'treemap') problems.push('overfull');

这一层只筛"结构性坏了”（边距不对称、空白、糊满），颜色对不对它管不了。

第二步：颜色普查（scripts/theme-census.ts），这才是全覆盖的核心。思路：渲染出的 PNG 里每个像素都应该能溯源到主题调色板——溯源不了的就是漏网之鱼。

坏值清单必须有定义来源。检测的"合法色集合"不是手工罗列的，而是从 themes.ts 源码里正则抽出来的全部 hex 字面量（theme-census.ts:16）：

1
2
3
4


// 1. allowed palette = every hex literal in themes.ts + black/white
const themeSrc = fs.readFileSync(path.join(ROOT, 'src', 'themes.ts'), 'utf8');
const allowed = new Set<string>(['#000000', '#FFFFFF']);
for (const m of themeSrc.matchAll(/#([0-9a-fA-F]{6})\b/g)) allowed.add('#' + m[1].toUpperCase());

这一步是整个设计的命门。如果合法集合只写"已知踩过的坑"（比如 #ECECFF），那换个没踩过的默认色漏出来就漏报了。从主题源码抽取，等于声明：凡是主题作者没写进源码的颜色，都是非法的——新增图型用了新默认色、主题改版引入漂移，都会被同一张网捞住。

然后逐像素统计，跳过半透明抗锯齿边缘（theme-census.ts:38）：

1
2
3
4
5
6


for (let i = 0; i < data.length; i += 4) {
 if (data[i + 3] < 250) continue; // AA fringe
 const key = '#' + [data[i], data[i+1], data[i+2]]
 .map((v) => v.toString(16).padStart(2, '0').toUpperCase()).join('');
 counts.set(key, (counts.get(key) ?? 0) + 1);
}

问题来了：抗锯齿和半透明填充会产生调色板色的合成产物——比如 35% 透明度的雷达曲线叠在白底上，逐像素值不在调色板里，但它是合法的。硬把抗锯齿当坏值，工具会误报到没法用。所以有个合成容差判定 isDerived：某颜色 c 合法，当且仅当存在调色板色 P 和 alpha a，使 P*a + 255*(1-a) 在每通道 ±3 内还原出 c（theme-census.ts:48）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


const isDerived = (hex: string): boolean => {
 const c = [r, g, b];
 for (const p of pal) {
 // 反解三个通道各自的 alpha，要求自洽（差 < 0.06）且在合理范围
 const alphas = [0, 1, 2].map((i) => (255 - c[i]) / (255 - p[i] || 1));
 const a = alphas[0];
 if (a < 0.08 || a > 1) continue;
 if (alphas.every((x) => Math.abs(x - a) < 0.06) &&
 [0,1,2].every((i) => Math.abs(Math.round(p[i]*a + 255*(1-a)) - c[i]) <= 3)) return true;
 }
 return false;
};

这个反解 alpha 的写法有点取巧：假设合成发生在白底上（255*(1-a)）。页面背景不是白色时（比如 mocha 的 #1E1E2E）它会误判——目前的普查脚本只跑默认 tech 主题所以没事，这是个已知的边界，见文末。

最后一层是刺眼默认色黑名单：有些 mermaid 默认色面积很小（journey 的 actor 圆点、单条错误的连线），按面积阈值会漏掉，但它们恰恰是最扎眼的。黑名单里的颜色任何覆盖率都报（theme-census.ts:61）：

1
2
3
4
5
6
7


// known garish mermaid defaults — flag at ANY coverage (tiny elements
// like journey actor dots fall below the area threshold)
const loud = ['#7CFC00', '#00FFFF', '#8FBC8F', '#ECECFF', '#9370DB',
 '#191970', '#8B008B', '#FF0000', '#00BFFF', '#FF8888'];
const off = [...counts.entries()].filter(([c, n]) =>
 !allowed.has(c) && !isDerived(c) &&
 (n / total > 0.0015 || (loud.includes(c) && n > total * 0.0001)));

注意黑名单的角色和 allowed 集合不同：allowed 是定义合法性（源头是 themes.ts），loud 是提高灵敏度（源头是已知刺眼色的经验清单）。前者漏报新形态，后者只是让小面积的已知坏值更早暴露——两层缺一不可，但只有第一层是完备的。

这套检测的真实战绩：xyChart 的 plotColorPalette 默认以 mermaid 紫 #ECECFF 打头、radar 曲线的 cScale 粉彩在网格线上几乎隐形、treemap 各分区色几乎不可区分——全是普查跑出来的，不是肉眼。另外一个隐蔽案例印证了上一篇"配置嵌套层级"的教训：批量补丁曾把 todayLineColor、quadrant*Fill 等键错误地插进 themeVariables.xyChart 内部，键还在、值也对，就是层级错了导致静默失效——这类错误肉眼 review 配置文件根本看不出来，但普查会直接报"pie 图出现了 off-palette 默认色"，因为变量没生效、默认色就漏出来了。

变量"不生效"的头号症状就是嵌套位置错，而像素普查是唯一能兜住这种静默失效的网——它不检查你写了什么配置，它检查渲染结果长什么样。配置对不对是手段，像素对不对才是目的。

agent 友好性：CLI 契约的取舍

给 agent 用的 CLI 和给人用的差别很大，几个明确的取舍：

1. stdout 只有一份 JSON，进度全走 stderr。 --json 打开时人类可读的进度行全部静默，stdout 是单个 JSON（cli.ts:432）：

1
2
3
4
5
6
7


console.log(JSON.stringify({
 theme: o.theme, layout: o.layout, format: o.format, background,
 blocks: blocks.length, rendered: results.length - failed.length,
 failed: failed.length, files: written,
 errors: failed.map((f) => ({ input: f.input, index: f.index, error: f.error })),
 ...(o.profile ? { profile: profileSummary() } : {}),
}, null, 2));

agent 解析 files 数组核对产物、解析 errors[].input/index/error 定位坏块，不用猜输出格式。

2. 失败隔离 + 确定性退出码。 一个块渲染失败不拖垮整批，--json 里如实记录；退出码三档：0 全成、1 有渲染失败（其余照常出图）、2 用法错误。agent 看到 1 就读 errors 数组，看到 2 就改命令行。

3. 挂死必须响亮。 每次渲染包一层 Promise.race，60 秒必报错（render.ts:505）：

1
2
3
4
5
6
7


// a wedged renderer (bad diagram, crashed tab) must fail loud, never hang
return await Promise.race([
 fn(page),
 new Promise<never>((_, rej) => {
 timer = setTimeout(() => rej(new Error('render timed out after 60s')), 60_000);
 }),
]);

并发下浏览器的瞬时抽风（截图超时之类）则由外层自动重试一次（cli.ts:400）——agent 不该为这类抖动买单，但真正的语法错误重试也没用，两次都失败才进 errors。

4. 确定性输出命名。 同一输入永远产出同名文件：README-m1.svg、README-m2.svg……--index 2 筛选后仍保留 -m2 后缀（cli.ts:292 的注释：keep the -m<n> suffix ... so blocks don't masquerade as the whole file's diagram），agent 引用文件名不会漂移。

5. 观测性。 --profile 输出各阶段耗时（browser-launch / page-init / mermaid-render / screenshot / svgo），典型单图 95ms 渲染 + 90ms 截图。agent 调优 --jobs 或怀疑卡顿时有数据可依。

6. 不下载任何东西。 浏览器按 Edge → Chrome 常见路径探测（render.ts:36 的 detectBrowser），找不到快速报错并列出搜索路径——绝不拉 Chromium。icon 包从 unpkg 拉一次就缓存到临时目录。agent 在别人机器上跑，网络行为必须可预期。

这几条里最费心思的是"响亮失败"和"重试"的边界：重试 absorb 的只该是瞬时故障，语法错误重试是浪费。现在的实现是简单粗暴的无差别重试一次——够用但不精致，理想情况应该按错误类型分流，比如超时重试、语法错误不重试。

结语

回头看，这个项目一半的代码在渲染，另一半在"证明渲染是对的"。主题系统的三层结构（themeVariables 派生链 / themeCSS 形状语义 / remap 兜底）本质上是在跟 mermaid 的历史包袱做分层妥协；而像素普查则是把"主题改完了没漏"从人眼工程变成可回归的断言。

还有几块明显欠账：普查脚本只覆盖默认 tech 主题、没有接进 CI 自动跑、合成容差假设白底、–theme-js 用 new Function 执行用户代码没做任何沙箱。这些都不影响它作为一个 agent 工具完成本职，但离"可以放心让别人依赖的渲染服务"还有距离。

我现在的判断是：给 agent 造工具，最难的不是功能，是让失败的路径和成功的路径一样被设计过——JSON 契约、退出码、超时、坏块隔离这些东西写起来毫无乐趣，但 agent 每天 80% 的时间活在这些路径上。接下来值得想的问题是：像素普查这套思路能不能反哺给 agent 本身——agent 自己产图、自己跑一遍普查、自己修，直到 ALL CLEAN？那才是"built for AI agents"的完全体。

Mermaid 主题定制暗坑大全

Sun, 06 Sep 2026 20:06:28 +0800

Mermaid 主题定制暗坑大全

我给 mmdx（自己的 Mermaid 导出器）做了一套完整主题预设，过程中在 mermaid 的主题机制上反复撞墙：变量改了不生效、CSS 写了被盖、颜色改了换了个地方又冒出来。这篇把踩过的坑整理成 checklist，每条都是"现象 → 为什么 → 怎么绕"，代码全部来自真实仓库。

先立结论：themeVariables 根上的键永远生效

这是整个主题定制的第一原则，反过来用就是最重要的排错手段。

mermaid 的主题计算（Theme.calculate）流程是三步：用户覆盖 → 推导派生色 → 再覆盖。也就是说 themeVariables 根上的键永远赢——不管后面的推导链怎么算，你写在根上的值是最后生效的。所以：

变量"不生效"，九成不是机制问题，而是嵌套位置错——键被插到了某个图型的子配置里，而不是 themeVariables 根上。
例外只有一种：渲染器根本不读这个变量（走了硬编码），那是另一类坑，后面单说。

我真实踩过的版本：用 python 脚本给主题补丁批量插入 pie1~pie12、quadrant1Fill、todayLineColor 十几个键，锚点缩进算错一层，整批键被插进了 themeVariables.xyChart 对象内部：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


themeVariables: {
 primaryColor: '#E8F3FF',
 // ...几十个根级键...
 xyChart: {
 plotColorPalette: '#5B8FF9,#F6BD16,...',
 pie1: '#5B8FF9', // ← 全在这里，静默失效
 pie2: '#5AD8A6', // pie 图根本不读 xyChart 命名空间
 todayLineColor: '#FF9A2E',
 },
},

配置是合法 JSON，渲染不报错，颜色就是不变。排错半天以为是变量名写错或 mermaid 版本问题，最后把配置 dump 出来做括号深度计数才发现层级错了。

“变量不生效 = 先查嵌套位置”，这条现在是我排 mermaid 主题问题的第一反应。批量改配置结构后，写个脚本断言每个键的括号深度，或者干脆整段重写而不是锚点替换——锚点替换省的那几分钟会在排错时十倍还回来。

assignWithDepth：数组是追加不是替换

第二个大坑在 mermaid 合并用户配置的入口函数 assignWithDepth 里。看 mermaid 源码（src/assignWithDepth.ts，dist 产物 chunk-DU6HZSFF.mjs 原样保留）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


var assignWithDepth = (dst, src, { depth = 2 } = {}) => {
 if (Array.isArray(src) && !Array.isArray(dst)) {
 src.forEach((s) => assignWithDepth(dst, s, config2));
 return dst;
 } else if (Array.isArray(src) && Array.isArray(dst)) {
 src.forEach((s) => {
 if (!dst.includes(s)) { // ← 追加，不是替换
 dst.push(s);
 }
 });
 return dst;
 }
 // 对象走递归合并，标量直接覆盖 —— 这部分行为正常

对象合并符合直觉，标量覆盖也正常，唯独数组是 push。dst 里已经有默认值时，你配置的数组元素会追加在默认值后面。

具体受害场景是 journey 图的 actor 圆点。journey 配置里有 actorColours 数组，我配置成：

1
2
3


journey: {
 actorColours: ['#6E94BB', '#7FB08A', '#63A8A4', '#D2A36C', '#8B99A8', '#C48BA6'],
},

结果圆点颜色纹丝不动。原因是 mermaid 默认的 6 个 actor 颜色已经占了 0-5 槽位，我的 6 个颜色被 append 到第 7-12 位——而 journey 只有 6 个 actor，永远读不到追加的段。同理 journey.actorColours 在 themeVariables.cScaleInv 那条路上也有类似问题。

怎么绕？journey 圆点的 fill 是 SVG presentation attribute（fill="cornsilk" 这类），而 presentation attribute 的优先级低于任何 CSS 规则。所以用 themeCSS 直接压：

1
2
3
4
5
6


/* src/themes.ts — journey actor dots: config.journey.actorColours is useless —
 mermaid's assignWithDepth APPENDS arrays, so the hardcoded defaults keep
 slots 0-5. Presentation-attribute fills lose to plain CSS, so pin the dots here. */
.actor-0 { fill: #6E94BB; stroke: #FFFFFF; }
.actor-1 { fill: #7FB08A; stroke: #FFFFFF; }
/* ... .actor-2 到 .actor-5 同理 */

“presentation attribute 输给任何 CSS"是 SVG 规范行为，不是 mermaid 的锅，但它决定了绕法的方向：凡是 fill 写死在元素属性上的地方，别试图找主题变量了，直接 CSS 压，稳赢。

themeCSS 的 #svgId 前缀：svg 根类匹配不到

第三个坑在 themeCSS 本身。mermaid 拿到 themeCSS 后不是原样注入 <style>，而是给每条规则加一个 #svgId 前缀（svg 元素的 id 选择器），把作用域限定在当前图里。

这意味着你的选择器实际生效形式是：

1
2
3
4
5


/* 你写的 */
.erDiagram .entityBox { fill: #E8F3FF; }

/* 实际注入的 */
#svgId .erDiagram .entityBox { fill: #E8F3FF; }

问题来了：.erDiagram 这个类挂在 svg 根元素上，而 #svgId 就是这个根元素。CSS 里"X 的后代 Y"要求 X 是 Y 的祖先——svg 根不可能是自己的后代，所以 #svgId .erDiagram ... 永远匹配不到任何元素。凡是想以 svg 根类做后代选择器中间环节的写法，全部静默失效。

绕法：跳过根类，直接锚定根类内部的结构类：

1
2
3
4
5
6


/* src/themes.ts — ER 实体外壳是 .node path，属性行走 themeVariables */
.node .outer-path path { fill: #E8F3FF; stroke: #4098FC; }
.node .row-rect-odd path { fill: #FFFFFF; stroke: #4098FC; }
.node .row-rect-even path { fill: #F7F8FA; stroke: #4098FC; }
/* class 图的分隔线也会撞上 .node path 规则，单独钉住 */
.divider path { stroke: #4098FC; }

注意上面还有个连锁坑：ER 实体外壳和 class 图的分隔线都是 .node path，会被 flowchart 的通用 .node path 填色规则误伤（我把通用 path 涂成紫色代表"存储”，结果 ER 实体全紫了）。主题 CSS 里每加一条宽泛规则，都要想一遍哪些图型的哪些元素也满足这个选择器。

官方文档完全没提 #svgId 前缀这回事，themeCSS 的行为只能靠 dump 生成的 SVG <style> 反推。我怀疑没几个人成功用过 .erDiagram 开头的 themeCSS 选择器。

内联 style !important：CSS 的尽头是改数据

第四个坑是优先级天花板。C4 图的元素标签文字是硬编码白色内联样式——渲染器里直接 color: fontColor ?? '#FFFFFF' 且带 !important 写进元素的 style 属性。内联样式加 !important，是 CSS 层叠里赢不了的东西：任何外部样式表规则，不管特异性多高，都输给它。

所以我给 C4 换浅色主题的第一次尝试：themeCSS 里写 text { fill: #1D2129 !important } 之类，全部无效。

绕法只有一条：改数据源头。不动文字颜色，把 C4 的填充色调到足够深，让白字可读。官方通道是 config.c4 段（这也是 C4 填充色的正确出处，不在 themeVariables 里）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// src/themes.ts — C4 element palette: official channel is the c4 config section
// NOTE: c4 label text is hardcoded white inline (c4ShapeAdapter: color:
// fontColor ?? '#FFFFFF', applied with !important) — no theme variable
// can change it, so fills must stay dark enough for white text
c4: {
 person_bg_color: '#4A6F94', person_border_color: '#3A5A78',
 external_person_bg_color: '#76828F', external_person_border_color: '#6A7581',
 container_bg_color: '#4A6F94', container_border_color: '#3A5A78',
 // ...
},

这条给了我一个方法论上的提醒：遇到"怎么写 CSS 都不生效"时，先确认目标元素上有没有内联 !important（dump SVG 看 style 属性）。有，就别在 CSS 层纠缠了，往上找数据源——改不了数据源（比如白字是 mermaid 写死的），就把自己的设计往数据源头让步，而不是继续堆选择器。

直接命中 beats 继承：压到实际文字元素上

第五个坑是层叠里最不起眼的一类。我想统一图内文字颜色，在容器层设置：

1

.mindmap-node .label { color: #1D2129 !important; }

.label 是 foreignObject 里的 div，直觉上 color 会继承到内部所有文字。但 mindmap 某些节点的文字元素（span、.text-inner-tspan）上挂着直接命中的规则（比如 root 节点的 tspan 通过 section-root 规则拿到 gitBranchLabel0 的白色），直接命中永远赢过继承——父元素的 color 设得再对，子元素自己有规则就轮不到继承。

绕法：选择器覆盖到实际渲染文字的元素，一层都别省：

1
2
3
4
5
6
7
8


/* src/themes.ts — mindmap 标签是 HTML（foreignObject）——
 颜色必须钉到 span/p/tspan 级别，root 的 text-inner-tspan 否则会
 经 section-root 规则拿到 gitBranchLabel0（白色） */
.mindmap-node .label,
.mindmap-node .label div,
.mindmap-node .label span,
.mindmap-node .label p,
.mindmap-node .text-inner-tspan { color: #1D2129 !important; fill: #1D2129 !important; }

这里 fill 也要一起设——SVG 文字的着色走 fill 而不是 color，混排（HTML 标签 + SVG tspan）的图两种都要覆盖。

层叠顺序"直接命中 beats 继承"是 CSS 基本功，但在 mermaid 里特别容易栽：图型渲染器往内部元素上撒直接规则的习惯比一般网页重得多。div 上设 color “看起来生效了一部分”（普通节点对了，root 节点没对）比全不生效更迷惑人。

同特异性看插入顺序：neo 主题的渐变遮蔽

前面几条都是"我的规则被别人盖"，这一条反过来：mermaid 自己生成的规则会盖掉 themeVariables。

开 look: 'neo' 后（切换到 theme-neo 那套渲染），mermaid 会为 mindmap 每个分区生成带渐变填充的规则，并追加在 themeCSS 之后注入。同特异性时后者赢，结果就是我在 themeVariables.cScale0-5 里精心配的分区色全部被 mainBkg + gradient stroke 的统一渐变盖掉，mindmap 各分支变成同一种颜色。

绕法是在 themeCSS 里显式恢复，并用 !important 对抗插入顺序（规则来源无法控制顺序时，特异性又相同，只能加权重）：

1
2
3
4
5
6
7


/* src/themes.ts — under look:'neo' the generated gradient rule (appended
 later, same specificity) paints EVERY section box mainBkg + gradient
 stroke, masking the cScale section colours; restore per-branch pastels */
.mindmap-node.section--1 rect,
.mindmap-node.section--1 path,
.mindmap-node.section--1 circle { fill: #E8F3FF !important; stroke: #4098FC !important; stroke-width: 2.5px !important; }
.mindmap-node.section-0 rect, /* ...0-5 各分区同理... */

注意根节点是 section--1（双横线），分区是 section-0 到 section-N——这个命名也是 dump SVG 才能确认的。

mermaid 的规则注入顺序是"基础 themeCSS → 图型生成规则 → neo 渐变"，我方永远在下游被动挨打。能用 themeVariables 根键解决的绝不用 CSS，因为 CSS 要跟生成规则抢位置；根键走的是 Theme.calculate 的覆盖链，不受注入顺序影响。

验证方法论：dump + 反查，不靠记忆猜

以上每个坑的定位过程都指向同一套验证手段，值得单独总结。主题排错不要对着记忆猜优先级，两步拿到事实：

dump SVG 的 <style> 全部规则：把渲染产物 SVG 存下来，看 <style> 里到底注入了什么、顺序如何、有没有 #svgId 前缀、目标元素上挂着哪些规则。内联样式直接看元素的 style 属性。
getComputedStyle 反查：在浏览器 console 里对目标元素跑 getComputedStyle(el)，看 fill/color 的最终值，再沿匹配规则定位来源。

在 mmdx 里我把这个思路固化成了全覆盖检测脚本（scripts/theme-census.ts）：渲染全部图型，像素级统计颜色，凡是落在主题调色板和合成容差之外的都报警，外加一张"mermaid 原生刺眼默认色"黑名单按任意覆盖率标记（小元素如 journey 圆点面积太小，覆盖率阈值会漏报，只能靠黑名单兜）：

1
2
3


// scripts/theme-census.ts — allowed palette = themes.ts 里每个 hex 字面量 + 黑白
for (const m of themeSrc.matchAll(/#([0-9a-fA-F]{6})\b/g)) allowed.add('#' + m[1].toUpperCase());
// ...渲染后逐像素计数，接受"调色板色以某 alpha 合成到白底"的结果（抗锯齿/半透明填充）

关键设计：黑名单必须有定义来源（主题调色板全集），只列已知坏值（比如 #ECECFF 这个 mermaid 紫）会漏掉"自家主题色被误用"这类新形态——这也是我从教训里烧出来的：第一版检测脚本只黑名单了 #ECECFF，结果自己的 Arco 色被另一条规则覆盖了照样漏。

手工排错靠 dump + 反查，批量验收靠像素普查。两者缺一不可：前者定位单点，后者保证"改 A 没顺手弄坏 B"——主题这种全联动的东西，没有全覆盖检测就是在打地鼠。

颜色散落地图

最后一个 checklist 是"哪里能改哪个颜色"。mermaid 的颜色配置入口散落在至少四个地方，找对入口能省掉前五节大半的斗争：

图型/元素	颜色入口	备注
全局派生链	`themeVariables` 根（primaryColor 等）	根键永远生效，配这里优先
C4 元素填充	`config.c4.*`	不在 themeVariables；白字硬编码，填充必须够深
journey 分段	`themeVariables.fillType0-7`	圆点例外，见 assignWithDepth 一节
xyChart 调色板	`themeVariables.xyChart.plotColorPalette`	逗号分隔字符串，不是数组；默认头一个就是 `#ECECFF` 紫
radar 曲线	`themeVariables.cScale` + `config.radar`	cScale 粉彩在刻度网上不可读，我用 CSS 覆盖成 AntV 色
mindmap 根节点	`themeVariables.git0` / `gitBranchLabel0`	是的，mindmap 借用 gitgraph 的变量名
treemap	`cScale`（类目）+ `cScalePeer`	相邻分区色差太小，CSS 单独配
sankey	无主题变量	走 tableau10 硬编码，mmdx 里用渲染后 hex→hex remap 补救
neo look 渐变	`themeVariables.gradientStart/Stop`	注意 genGradient 遮蔽 mindmap 分区色

look: 'neo' 这个开关单独提醒：它不只是加圆角，是整套渲染走 theme-neo 的新代码路径，渐变生成、阴影、mindmap 分区行为都变了。我最后是 neo + 显式 CSS 恢复分区色的组合。

sankey 那行值得多说一句：连主题变量都没有的图型，唯一出路是渲染后处理。mmdx 的 ThemePreset.remap 就是为此存在的——PNG 出来前对 SVG 里的硬编码 hex 做一次映射表替换。丑，但比魔改 mermaid 源码可持续。

最后是工程坑：批量补丁怎么不翻车

上面的坑里有两类（补 themeVariables 大批键、补 themeCSS 大段规则）都涉及"往配置文件里批量插入大块内容"，这里踩的坑不在 mermaid 而在工具链：

坑一：超长 heredoc 截断。 用 bash heredoc 往文件里写整段 CSS/配置模板，内容一长（几百行）会被静默截断，文件尾部缺失。绕法：大块内容用 Write 工具（或编辑器）写成独立文件，再用小脚本拼接进去，heredoc 只留给几行的东西。

坑二：python 补丁必须带断言和回滚。 批量插入用锚点替换时，锚点选错（缩进差一层）就是我第一节那个 pie1-12 插错层的事故。防线两条：

1
2
3
4


# 每个 replace 前断言锚点恰好出现一次
assert src.count(anchor) == 1, f"anchor not unique: {anchor[:40]}"
src = src.replace(anchor, patched)
# 任何一步失败，整体回滚，不许半成品落盘

插入后立刻做层级断言：括号深度计数，断言新键在预期嵌套层级上。锚点替换赌的是"锚点文本唯一且位置如我所想"，断言是把这个赌注变成显式检查。

这两条是纯工程纪律，但和 mermaid 的坑叠加起来杀伤力最大：插错层是静默失效，heredoc 截断也是静默截断——两个静默叠在一起，你还以为自己的主题配置"试过了没用"。所有静默失败的工具链环节，都值得配一道显式断言。

总结成一句话：mermaid 主题定制的所有坑，本质是"三层优先级体系 + 散落的配置入口"——themeVariables 根键 > CSS（受 #svgId 前缀、注入顺序、内联 !important 制约）> presentation attribute，而 C4 白字、sankey 配色这类硬编码点只能改数据或后处理。排错永远从 dump SVG 开始，不要猜。下一篇写 mmdx 本身的设计，以及那套全覆盖像素检测是怎么建的。