Markdown → Word（保留 Mermaid）普适笔记
面向：中文技术 Markdown（含 Mermaid、宽表、行内代码）要转成可评审的 Word，且只改版式、不改内容。
1. 适用 / 不适用
适用（必须同时满足多数）：
- 源是
.md，含#/##、列表、表格、`code` - 含一个或多个
```mermaid代码块，Word 里要看见图，不是代码 - 要求：内容零改动；美化与原文冲突时听原文
不适用（换别的流程）：
- 只要「能打开的 docx」、不在乎图与样式 → 可用更简单转换
- 必须离线、禁止访问公网渲染服务 → 本笔记主链路不成立（见备选）
- 需要完整 Markdown 扩展（脚注、复杂嵌套引用等）→ 先确认解析器能力，本流程未覆盖
2. 目标与非目标
| 类型 | 内容 |
|---|---|
| 必须 | 正文/表/列表语义不变；每个 Mermaid 块变成一张嵌入图；标题层级对应 |
| 建议 | 统一字体与页边距；代码等宽+浅底；表头区分；图下加图题 |
| 非目标 | 润色措辞、改流程图逻辑、补业务章节、当文档审稿 |
3. 推荐流水线（按决策顺序）
- 定约束：内容零改动；图必须保留；美化服从原文
- 探环境：Python /
python-docx/ 是否有 pandoc / 是否有 Word / 能否访问渲染 API - 抽 Mermaid：按围栏切出全部代码块，计数 N
- 渲图：本机验证过的渲染器 → 得到 N 张图；失败则停止，不占位糊弄
- 组 Word：按 md 结构写段落/标题/列表/表，在原图位置插入图片+图题
- 校验：文本对照 + 图数量 + 表列结构 + 翻页观感
- 交付：只交
.docx；说明「内容未改 / 图齐 / 表齐」
不要按聊天时间线复述；上面顺序可直接当作业清单。
4. 工具选型（本机验证过的路径）
主路径（本次已跑通）
.md
→ 解析（自写逻辑 / 简单状态机即可）
→ Mermaid 文本 URL-safe Base64
→ mermaid.ink 出图（可调 width 提高清晰度）
→ python-docx 写 .docx（插 PNG、设样式）
→ （可选）本机 Word COM 导出 PDF，再肉眼/截页看分页
| 环节 | 本机结论 |
|---|---|
python + python-docx | 可用，作为组稿主工具 |
mermaid.ink | 可用；width= 可提高分辨率 |
| 本机 Microsoft Word COM | 可用；仅作预览/导出校验，不是组稿工具 |
pandoc | 未安装 → 未采用；不要写成「已用 pandoc」 |
kroki.io | 请求曾 403 → 未采用 |
决策树
有 pandoc 且扩展能渲 Mermaid？
├─ 是 → 【备选·未在本机验证】可试 pandoc 一键转，仍须抽检图与中文
└─ 否 → 用「渲图 + python-docx」主路径
mermaid.ink 失败？
├─ 换其它本机已验证的渲染端
└─ 都失败 → 停止并报告（禁止灰框/纯文字冒充图）
备选（未在本机完整验证）
- pandoc：常见一键方案；本机当时命令不存在，未验证
- VS Code / Cursor「Markdown Preview Mermaid」：适合预览，不等于出 Word
- Typora / Obsidian 导出 Word/PDF：视版本而定，未在本流程验证
- 本地 mermaid-cli（mmdc）：适合强制离线；本次未装、未验证
5. Mermaid → 图片
必须：
- 用源文件里的围栏内容，不要改图内文字或节点
- 块数 N 与嵌入图数 N 一致
- 渲染失败 → 停止并报告
建议：
- 编码：UTF-8 → URL-safe Base64（去
=填充按服务要求） - 白底参数（如
bgColor=white），避免透明底在 Word 里发灰 - 复杂 mindmap / 高流程图：加大
width（例如 1800–3600），再按版心缩放 - Word 里图宽约占版心 85%–95%；图与图题
keep with next，避免图题落单页
可选：
- 图题：
图1 …/图2 …（算版式，不算改正文）
6. Word 版式约定清单
| 项 | 建议值（可微调，全文统一） |
|---|---|
| 纸张 | A4 |
| 页边距 | 上/下约 2.0–2.5 cm，左/右约 2.2–2.5 cm |
| 中文 | 微软雅黑（或全文统一的另一套） |
| 代码 | Consolas / Cascadia Mono；浅灰底 |
| 正文 | 11–12 pt；行距约 1.15–1.3 |
| 标题 | 深蓝灰；H1/H2 对应 # / ##；标题与下文「与下段同页」 |
| 表格 | 表头浅灰；长路径自动换行；行不可拆页（cantSplit） |
| 强调 | 仅保留源里已有的加粗（如结论数字）；不大面积涂色 |
| 页脚 | 居中页码 |
分页经验（必须当检查项）：
- 宽表一行被拆到两页 → 行禁止拆分，必要时略调列宽
- 「小节标题」单独落在页末、图在下一页 → 标题
keep with next - 段落后大片空白 → 略减段距；不要为了填满而改内容
- 末页只剩一两行：可接受；用「列表 keep-with-next 过强」时会制造空白页，宜克制
7. 质量校验清单
内容（必须）：
- 去掉 md 语法与 Mermaid 块后，关键句段在 docx 中均可检索到（零丢失）
- 表格列数/表头/单元格文字与源一致
- 行内代码、加粗范围与源一致（不丢、不强加）
图（必须）：
- Mermaid 块数 = 嵌入图数
- 图可读、未裁切关键文字
版式（建议）：
- 标题未与首段/首图分离
- 表行未跨页撕开
- 打印预览或 PDF 抽页扫一眼
交付话术（一句）：
「内容未改；N 张图已嵌入；表结构完整。」
8. 常见坑与对策
| 现象 | 对策 |
|---|---|
pandoc 不是内部或外部命令 | 记「未安装」；走 python-docx，勿假装用过 |
| Kroki 403 | 换已验证渲染端；或停 |
| mermaid.ink 默认图偏糊 | 加 width= 再嵌入 |
| 控制台打印中文乱码 | 校验改写文件 / 退出码，别只看终端字形 |
| 表路径把列撑爆 | 固定列宽 + 单元格换行 |
| 标题下只有图、标题落孤页 | 标题/图与图题 keep with next |
| 为「紧凑」合并段落或改字 | 禁止；美化服从原文 |
9. 可复制：转换提示词（短模板）
把给定 Markdown 转为 Word（.docx）。只做版式，不改实质内容。
硬约束：内容零改动；美化与原文冲突时听原文；全部 Mermaid 渲成图嵌入，失败则停；
表格结构与文字不变；行内代码用等宽区分；标题层级保留。
版式：A4；中文统一无字体；代码浅底；表头区分；图居中可加图题。
交付：docx + 一句话确认（内容/图/表）。
禁止：改结论与图逻辑；用文字或灰框冒充图；添加原文没有的章节。
需要更细的版式句，可从本笔记第 6 节按条粘贴。
10. 一页纸速查
- 先写死：不改内容、保留图、美化听原文
- 先探工具：没有 pandoc 就别依赖 pandoc
- 只写本机验证过的链路；别的标「备选·未验证」
- Mermaid：抽块 → 渲图 → 计数对齐；失败即停
- 组稿：
python-docx（或你已验证的等价物） - 代码等宽浅底；表头灰；图题可选
- 防拆页：表行 cantSplit；标题/图 keep with next
- 文本对照校验 + 图数校验
- 需要翻页观感再用 Word 导 PDF 扫一眼
- 交付只交 docx，附一句确认
下次开干前 5 问
- 这次是否允许访问公网渲 Mermaid？不行的话本地渲染装好了吗？
- 本机现在有什么：python-docx / pandoc / Word 哪个是真可用？
- Mermaid 有几块？失败时是「停」还是「允许纯文字」？（默认停）
- 有没有超宽三列表或超长路径？（提前定列宽与禁止拆行）
- 验收标准是否仍是：「内容零丢 + 图齐 + 表齐」，而不是「看起来更像重新写过」？
