流程图、E-R图一键补齐：lunwen-skill的Mermaid/PlantUML图表渲染闭环教程

lunwen-skill 是一款面向本科计科学生的一键论文初稿 Skill，能把项目事实、样文规范与版式要求整合成可交付的.docx论文初稿。其中最实用的能力之一，就是流程图、E-R 图一键补齐：正文缺图时自动补上 Mermaid 图块与图题，再经渲染、嵌图、附件交付形成完整闭环。本文用 4 步带你跑通 lunwen-skill 的图表渲染全流程。

为什么论文需要“图表闭环”

本科计科论文评审时，图表往往是第一道关卡：

• 第 3 章设计部分至少要有 5 张设计图（架构图、功能模块图、权限流程图、业务流程图、E-R 图）
• 数据库设计部分缺少 E-R 图直接视为未完成
• 如果 Mermaid / PlantUML 图在 Word 里只是一段源码，等于"图没交"

lunwen-skill 的设计原则就是把"图表、截图、参考文献和 Word 交付都闭环"（见 SKILL.md）。也就是说：图要么渲染成真实图片插进.docx，要么退而求其次保留源码并交付附件，绝不留下"半张图"。

第一步：一键检测并补齐缺失的流程图、E-R 图

写作过程中，lunwen-skill 会持续检查正文图表是否齐全。对应工具是 tools/ensure_thesis_assets.py，它内置 6 类必备项模板：

只检查、不修改：

python tools/ensure_thesis_assets.py thesis.md --check-only

缺图时返回MISSING_COUNT和缺失项清单；加上--in-place参数后，脚本会在文末追加"图表与截图补全草稿"，图题编号自动接续正文已有的"图 x.x / 表 x.x"，不用手工数编号。

💡 E-R 图规则：如果数据库总表 E-R 图过大，lunwen-skill 会要求拆分为"总表设计图 + 核心表设计图"至少两张，业务复杂时还可按"用户域、预约域、设备域"等继续拆（规则见 prompts/chapter_writer.md）。

第二步：提取 Mermaid 图块，生成渲染清单

正文里的每个图都是"Mermaid 代码块 + 一行图题"的固定写法，例如：

![mermaid](https://web-api.gitcode.com/mermaid/svg/eNpLy8kvT85ILCpR8AniUgCC0OjnU1Y869geq6Cra6cQHv20s_f56vUQXnD0kx2znnYtfDanF0g-3dgEEXaJ1ng2dcOz3nVPd03WjAUAnHkljg) 图 3.1 系统总体架构图

tools/extract_mermaid_blocks.py 负责把正文里的图块"拆"出来：

python tools/extract_mermaid_blocks.py thesis.md tmp/mermaid --manifest tmp/mermaid/manifest.json

它会按图题命名生成01-系统总体架构图.mmd、02-数据库E-R图.mmd等.mmd源文件，并输出一份manifest.json清单，记录每张图的图题、源码路径和未来的图片输出路径（.png/.svg）。后续渲染和嵌图都靠这份清单对齐，图题、源码、成品图三者一一对应，不会张冠李戴。

第三步：把 Mermaid 源码渲染成真实图片

渲染入口是 tools/render_mermaid.py，它封装了npx @mermaid-js/mermaid-cli，一条命令完成单图渲染：

python tools/render_mermaid.py tmp/mermaid/01-系统总体架构图.mmd tmp/mermaid/01-系统总体架构图.png

使用前提：

• 环境已安装 Node.js（脚本会先检测npx，缺失时明确报Missing npx. Install Node.js first.）
• 按 INSTALL.md 建议，额外安装@mermaid-js/mermaid-cli；如需渲染 PlantUML，准备plantuml.jar或等效渲染方案

如果环境暂时没有 Mermaid 渲染能力，lunwen-skill 不会"装死"：流程图退回源码或占位，同时把图源码完整写进附件文档，保证材料不丢。

第四步：渲染图嵌入 .docx，完成成稿交付

图片渲染完成后，用 tools/build_image_map.py 建立"图题 → 图片文件"的映射（支持.png/.jpg/.jpeg，也支持手工映射文件覆盖默认匹配），然后交给 tools/generate_thesis_docx.py 生成主论文：

python tools/generate_thesis_docx.py thesis.md thesis.docx --image-map image-map.json

生成器读取正文时有一条关键逻辑：遇到mermaid代码块后标记"有图待发"，读到最后"图 x.x 图题"那一行时，按图题去 image map 里找对应图片——找到就插入真实图片，找不到就插入占位符，图题样式始终保留。这样即使某张图漏渲染，Word 里也能一眼看出哪里缺图，而不会默默跳过。

附件闭环：图源码单独交付一份 .docx

lunwen-skill 有一条硬约束：除了主论文，还必须额外交付一份"附件.docx"，收录正文中所有 Mermaid / PlantUML 图源码、E-R 图源码和关键流程图源码。生成脚本是 tools/generate_diagram_appendix_docx.py：

python tools/generate_diagram_appendix_docx.py "我的论文标题" thesis.md 我的论文标题-附件.docx

附件按图题逐条编号，注明图类型（mermaid/plantuml）并排版图源码，答辩老师要看"图怎么来的"时，直接翻附件即可。

交付前检查：图表是否真的闭环了？

最终检查清单见 prompts/final_checker.md，与图表相关的关键项：

• 图表编号是否连续、是否残留占位符
• 图表是否真实插入（而不是源码）
• 数据库部分是否包含 E-R 图、是否按需拆分为总表图和核心表图
• 第 3 章设计图是否达到 5 张及以上
• 存在 Mermaid / PlantUML 图时，附件.docx是否已生成

配合交付物命名规则（主论文、附件、image-map、文献核验清单均以论文标题命名），一套"流程图 + E-R 图 + 截图"的完整图表证据链就交付完毕了。

小结

用 lunwen-skill 补齐图表的完整链路可以概括为 4 步：

1. ensure_thesis_assets.py：检测缺失，一键补上流程图、E-R 图等图块骨架
2. extract_mermaid_blocks.py：提取图块，生成渲染清单
3. render_mermaid.py：把 Mermaid 源码渲染为 PNG
4. generate_thesis_docx.py + generate_diagram_appendix_docx.py：图片嵌入正文，源码收入附件

从"缺图焦虑"到"图表齐全、编号连续、源码可查"，这就是 lunwen-skill 的 Mermaid/PlantUML 图表渲染闭环。