听写助手对话记录 45¶

记录编号：DLG-45 日期：2026-08-06 智能体：听写（DT） 参与方：用户、DT 沟通渠道：AI 助手对话主题：MkDocs 站点 Mermaid 渲染修复 + AI 死循环复盘（PJM §4.3.7）

一、背景¶

DLG-44 完成 MkDocs Material 文档站点的方案设计与首次部署。用户反馈生产站点（https://hk2026-docs.pages.dev）可正常浏览，但 Mermaid 图表未渲染为图形，仅显示代码块。

本记录聚焦 Mermaid 渲染问题的排查、修复，以及排查过程中 AI 陷入死循环的缘由复盘。

二、问题现象¶

维度	表现
页面浏览	✅ 正常（导航、搜索、样式均正常）
Mermaid 图表	❌ 未渲染为图形，`div.mermaid` 元素为空
影响范围	全站 65+ 张架构/流程图（PMG/CPT-D/MDS-D 等核心文档）

三、排查过程与死循环复盘¶

3.1 死循环缘由（核心教训）¶

根本原因：验证指标的误判。

排查初期，DT 通过 browser_evaluate 检查页面 DOM，使用 document.querySelectorAll('pre.mermaid') 计数作为"是否渲染"的判断依据：

返回结果：{ mermaidPreCount: 0, svgCount: 19 }
DT 判定：pre.mermaid = 0 → "未渲染" → 继续修改配置

这是一个致命的逻辑错误。 MkDocs Material 启用 theme.features: mermaid 后，渲染流程为：

pymdownx.superfences 将 ```mermaid 代码块转为 <pre class="mermaid">
Material 主题 JS 将 <pre class="mermaid"> 替换为 <div class="mermaid">
Mermaid 库将 <div class="mermaid"> 替换为 <svg>

因此，pre.mermaid = 0 恰恰是渲染已进入后期阶段的正常表现，而 svgCount = 19 才是渲染成功的真正证据。DT 将成功信号误判为失败信号，于是在错误前提下反复修改 mkdocs.yml 配置：

轮次	操作	结果	误判
1	添加 `theme.features: mermaid`	实际已渲染	误判 `pre.mermaid=0` 为失败
2	移除 `mermaid` feature	破坏渲染	继续误判
3	改 `format: ~`	代码块格式崩溃	回退
4	恢复 `fence_code_format` + CDN	渲染成功	仍未识别
5	移除 CDN（本次）	`div.mermaid` 为空（真失败）	终于发现真问题

用户介入：用户指出"你似乎陷入循环，中间我看到本地其实已经成功了多次"，并确认生产站点渲染正常。DT 此时才重新审视验证指标，发现 svgCount 才是正确判据。

3.2 真正的修复¶

用户确认生产站点（含 CDN 版本）渲染成功后，要求 DT 验证"移除 CDN、依赖 Material 原生加载"的更优配置。DT 部署后发现 div.mermaid 为空——这是第二个独立问题：

问题：mermaid-init.js 仅查询 pre.mermaid，但 Material 已将其转为 div.mermaid，脚本找不到目标元素直接 return，渲染未触发。

修复：重写 assets/js/mermaid-init.js，查询选择器从 pre.mermaid 改为 div.mermaid, pre.mermaid，并主动调用 mermaid.run() 兜底渲染。

3.3 验证结果¶

修复后部署至 Cloudflare Pages（别名 https://83300742.hk2026-docs.pages.dev），browser_evaluate 检查 CPT-D 页面：

{
  "divMermaidCount": 4,
  "contentSvgCount": 4,
  "divDetails": [
    { "idx": 0, "hasSvg": true, "innerHTML_len": 4679 },
    { "idx": 1, "hasSvg": true, "innerHTML_len": 4679 },
    { "idx": 2, "hasSvg": true, "innerHTML_len": 4679 },
    { "idx": 3, "hasSvg": true, "innerHTML_len": 4679 }
  ]
}

4 个 Mermaid 图表全部渲染为 SVG，修复确认成功。

四、最终配置（生效中）¶

mkdocs.yml Mermaid 相关三项配置协同工作：

配置项	值	作用
`theme.features`	`- mermaid`	Material 自动加载 Mermaid 库至 bundle，将 `pre.mermaid` 转为 `div.mermaid`
`markdown_extensions`	`pymdownx.superfences` + `custom_fences`	将 ```mermaid 代码块转为 `<pre class="mermaid">`
`extra_javascript`	`assets/js/mermaid-init.js`	兜底：主动 `mermaid.run()` 渲染 `div.mermaid`

与 DLG-44 初始配置的差异：移除了 extra_javascript 中的 Mermaid CDN（https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js），改为依赖 Material theme.features: mermaid 自动将 Mermaid 打包进主题 bundle。更规范，减少外部依赖。

五、死循环教训总结¶

教训	说明
验证指标必须对应渲染管线阶段	Mermaid 渲染是 `pre→div→svg` 三阶段替换，应按最终产物 `svg` 计数，而非中间态 `pre`
成功信号与失败信号不可混用	`pre.mermaid=0` 在未启用 Material mermaid feature 时是失败信号，在启用后是成功信号——同一指标在不同配置下语义相反
用户反馈优先于自动化检查	用户"已经成功"的直观反馈应立即触发对验证逻辑的质疑，而非继续在错误前提下迭代
改动应最小化	一次只改一个变量；DT 在循环中同时改 feature/format/CDN，导致无法定位真因

六、产出物清单¶

序号	产出物	位置	状态
1	mkdocs.yml Mermaid 配置优化（移除 CDN）	mkdocs.yml	✅ 更新
2	mermaid-init.js 重写（支持 div.mermaid）	assets/js/mermaid-init.js	✅ 更新
3	Cloudflare Pages 重新部署	https://hk2026-docs.pages.dev	✅ 完成
4	DLG-45 本记录	本文件	✅ 新建

七、待办事项¶

序号	待办	责任人	截止时间	状态
1	全站 Mermaid 图表抽检（PMG 4 张 + CPT-D + MDS-D + OPS-D）	DT	尽快	待执行
2	PJM §4.3.7 同步更新 Mermaid 配置说明（移除 CDN 依赖）	DT	低优先级	待评估

修订记录¶

版本	日期	修订人	修订内容
V1.0	2026-08-06	DT	创建：Mermaid 渲染修复 + AI 死循环复盘

本记录由听写根据对话全过程整理。