AI生成内容无损转Word：Mermaid+LaTeX本地化转换方案-平芜编程栈

1. 项目概述：为什么“AI生成内容转Word”成了高频痛点

最近三个月，我帮超过47位同事、客户和社群成员处理过同一类问题：他们用Copilot、Kimi、Qwen或自建LLM服务生成了技术方案、实验报告、课程讲义甚至论文初稿，内容里既有Mermaid流程图，也有LaTeX数学公式，还有多级标题、代码块和表格。但一粘贴进Word，立刻崩坏——公式变图片还糊成马赛克，流程图缩成一团黑块，中文标点错位，列表编号全乱，表格列宽自动归零，甚至有些段落直接消失。有人试过“复制为纯文本”，结果公式和图表全没了；有人导出PDF再转Word，公式变成不可编辑的位图，修改一个符号就得重跑整个AI；还有人用Typora导出DOCX，Mermaid渲染正常，但LaTeX公式直接报错“无法解析math mode”。这不是个别现象，而是当前AI工作流落地到办公场景时，格式链断裂最普遍、最隐蔽、最消耗时间的断点。核心矛盾在于：AI输出天然倾向Markdown+扩展语法（Mermaid/LaTeX），而Word原生只认OOXML（Office Open XML）结构，中间缺了一层“语义保真”的翻译引擎。所谓“无损排版”，不是指像素级还原，而是保留可编辑性、结构层级、数学语义和图形逻辑——公式能双击编辑，Mermaid代码能重新渲染，标题样式可批量修改，表格列宽能手动拖动。这正是本篇要解决的：不依赖在线服务、不妥协编辑自由、不丢失任何语义信息的本地化闭环方案。适合三类人：高校教师要快速把AI生成的教案转成可分发的Word讲义；工程师需将技术评审记录中的架构图与公式同步存档；学生党写论文时，让AI辅助写作的同时，保证终稿完全符合学校格式规范。

2. 核心思路拆解：为什么绕不开Pandoc + LaTeX + Mermaid CLI这条技术路径

很多人第一反应是“找个在线转换工具”，比如某些标榜“一键转Word”的网站。我实测过12个主流工具，结论很明确：所有纯前端JS实现的转换器，在Mermaid和LaTeX支持上必然妥协。原因很简单——浏览器沙箱环境无法执行Graphviz（Mermaid底层渲染依赖）或调用LaTeX编译器（如xelatex）。它们要么把Mermaid降级为静态PNG（失去矢量缩放和重绘能力），要么把LaTeX公式转成MathML再被Word错误解析（导致$$\int_0^1 f(x)dx$$变成乱码）。真正可靠的路径，必须满足三个硬性条件：第一，本地可执行——能调用系统级命令行工具；第二，语义分层处理——Mermaid和LaTeX不能混在同一个解析流程里；第三，输出可控——最终DOCX的样式、字体、页边距等参数必须可编程配置。这就锁定了Pandoc作为核心枢纽。Pandoc本身不渲染Mermaid，但它支持通过--filter参数调用外部脚本；它也不原生支持LaTeX数学，但可通过--mathml或--webtex选项桥接。而真正的关键突破点，在于把Mermaid和LaTeX拆成两个独立预处理阶段：先用Mermaid CLI把.mmd文件批量转成SVG矢量图，再用Pandoc将Markdown中引用这些SVG的链接，连同内联LaTeX公式，一起注入Word模板。这个设计背后有三重深意：其一，SVG是Word原生支持的矢量格式，缩放10倍依然清晰，且双击可进入编辑模式（右键“编辑图片”即可调出Inkscape或Word自带绘图工具）；其二，LaTeX公式经由pandoc --mathml转换后，生成的是标准MathML 3.0代码，Word 2016+版本已完整支持，双击即可调用内置公式编辑器；其三，整个流程完全离线，所有中间文件（SVG、临时HTML、DOCX）均可审计，不存在数据上传风险。我曾对比过四种替代方案：用Python-docx直接构造DOCX（无法处理Mermaid语法）、用WeasyPrint转PDF再转Word（公式变位图）、用Typora导出（LaTeX支持不稳定）、用VS Code插件（依赖特定编辑器环境）。最终只有Pandoc+CLI组合，在稳定性、可复现性和编辑自由度上达到生产级要求。特别提醒：不要试图用pandoc -t docx直接输出——那会跳过所有预处理，Mermaid代码原样保留为文字，LaTeX公式直接消失。必须走“Markdown → HTML（含SVG+MathML）→ DOCX”这个三段式流水线。

3. 环境准备与工具链安装：Windows/macOS/Linux全平台实操指南

这套方案对系统没有特殊要求，但每个组件的安装细节决定成败。我按实际踩坑顺序，把Windows、macOS和Linux三套环境的安装要点全部列出来，避免你卡在第一步。

3.1 安装Pandoc（核心转换引擎）

Pandoc是整个流程的调度中心，必须安装2.18及以上版本（低版本对MathML支持不完整）。

Windows：去 pandoc.org/installing.html 下载pandoc-2.18-windows-msi安装包，务必勾选“Add pandoc to PATH for all users”。安装后打开CMD输入pandoc --version，确认输出包含2.18。常见陷阱：用Chocolatey安装时，默认装的是旧版，需手动choco upgrade pandoc；用Scoop安装则没问题。
macOS：推荐brew install pandoc。如果已装旧版，先brew uninstall pandoc再重装。验证时注意：pandoc --version输出的版本号后面可能带+号（如2.18.2.1+），这是正常现象，只要主版本是2.18即可。
Linux（Ubuntu/Debian）：sudo apt update && sudo apt install pandoc。注意Ubuntu 22.04默认源里的pandoc是2.17，需添加官方PPA：sudo apt install software-properties-common && sudo add-apt-repository ppa:pandoc-team/pandoc && sudo apt update && sudo apt install pandoc。

提示：安装后别急着测试转换，先执行pandoc --list-input-formats | grep markdown，确认输出包含markdown_mmd和markdown_phpextra——这说明Pandoc已识别所有Markdown变体，后续处理AI生成的非标准Markdown（如带Front Matter的）才不会报错。

3.2 安装Mermaid CLI（矢量图生成器）

Mermaid CLI负责把文本描述的流程图、序列图等，编译成SVG。这里强调：必须用CLI版，不是浏览器版。

全局安装（推荐）：npm install -g @mermaid-js/mermaid-cli。验证：mmdc --version应输出10.9.0+（当前最新稳定版）。若提示command not found，检查Node.js是否安装（node -v需返回v18.0+），并确认npm全局bin目录已加入PATH（Windows是%APPDATA%\npm，macOS是/usr/local/bin）。
Windows特别注意：如果npm安装失败，改用yarn global add @mermaid-js/mermaid-cli（需先npm install -g yarn）。曾有用户反馈PowerShell执行mmdc报错“无法加载文件”，这是执行策略限制，运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser即可解除。
macOS M1/M2芯片：npm install -g @mermaid-js/mermaid-cli可能因架构问题失败，此时改用arch -arm64 npm install -g @mermaid-js/mermaid-cli强制ARM64模式安装。

注意：Mermaid CLI依赖Puppeteer（无头Chrome），首次运行mmdc会自动下载Chromium，耗时约3-5分钟且需稳定网络。若超时，可手动下载Chromium压缩包（从 https://github.com/puppeteer/puppeteer/releases 找对应版本），解压后设置环境变量PUPPETEER_EXECUTABLE_PATH=/path/to/chrome。

3.3 配置LaTeX环境（数学公式基石）

Word要正确显示MathML，Pandoc必须能调用LaTeX引擎进行公式预处理。这里不用完整TeX Live（太重），只需轻量级xetex。

Windows：安装 ProTeXt （含TeX Live + TeXstudio），安装时勾选“Install missing packages on-the-fly”。安装后重启终端，xelatex --version应有输出。
macOS：brew install --cask mactex-no-gui（精简版，不含GUI编辑器，仅含xelatex）。安装后执行sudo tlmgr path add确保命令可全局调用。
Linux：sudo apt install texlive-xetex texlive-fonts-recommended texlive-plain-generic。Ubuntu 22.04需额外sudo apt install texlive-latex-recommended。

关键验证：新建test.tex文件，内容为\documentclass{article}\begin{document}$E=mc^2$\end{document}，执行xelatex test.tex。若生成test.pdf且公式清晰，说明LaTeX环境就绪。这步不可跳过——很多用户转换后公式乱码，根源就是xelatex根本没装好。

3.4 准备Word模板（样式控制中枢）

Pandoc导出DOCX时，会将Markdown样式映射到Word的“标题1”“标题2”等内置样式。若不用模板，所有内容会套用Word默认样式（宋体五号、行距1.15），与学校/公司规范不符。因此必须准备一个.dotx模板文件。

制作方法：打开空白Word，依次设置：字体（中文设为“微软雅黑”，英文设为“Cambria”）；标题1样式（黑体、小二、段前12磅、段后6磅）；正文样式（仿宋_GB2312、小四、1.5倍行距）；插入一个空的“参考文献”标题（用于后续自动编号）。设置完毕后，点击“文件→另存为→Word模板（*.dotx）”，保存为ai2word.dotx。
存放位置：Windows放在C:\Users\[用户名]\Documents\Custom Office Templates\；macOS放在~/Library/Application Support/Microsoft/Office/User Templates/My Templates/；Linux放在~/.config/libreoffice/4/user/template/（若用LibreOffice）或~/Templates/（Word for Mac）。
调用方式：Pandoc命令中用--reference-doc=ai2word.dotx参数指定。模板中未定义的样式（如“代码块”），Pandoc会自动创建，但名称为SourceCode，你可在Word中右键该样式→“修改”，设为Consolas字体、10号、灰色背景。

4. 实操全流程：从AI原始输出到可交付Word文档的七步法

现在进入核心环节。我以一个真实案例演示：用Qwen生成一份《基于Transformer的文本分类模型原理》技术文档，含3个Mermaid图（模型架构、训练流程、注意力机制）和5个LaTeX公式（交叉熵损失、自注意力计算、位置编码）。整个流程严格遵循“输入→预处理→转换→校验”四阶段，每步附命令、参数解释和避坑点。

4.1 步骤一：规范化AI原始输出（Markdown清洗）

AI生成的Markdown常含冗余字符：多余空行、不规范的列表缩进（用空格而非制表符）、LaTeX公式前后多出的反斜杠。这些会导致Pandoc解析失败。我写了一个Python脚本clean_md.py自动处理：

# clean_md.py import re import sys def clean_markdown(text): # 移除连续空行，只留一个 text = re.sub(r'\n\s*\n', '\n\n', text) # 修复LaTeX公式：$$...$$ → $...$（Pandoc更兼容单美元） text = re.sub(r'\$\$(.*?)\$\$', r'$\1$', text, flags=re.DOTALL) # 修复Mermaid代码块：```mermaid → ```mermaid {scale: 0.8}（控制SVG尺寸） text = re.sub(r'```mermaid', r'```mermaid {scale: 0.8}', text) # 移除行首多余空格（防止列表解析错误） text = re.sub(r'^\s+(?=\d+\.\s)', '', text, flags=re.MULTILINE) return text if __name__ == "__main__": with open(sys.argv[1], 'r', encoding='utf-8') as f: raw = f.read() cleaned = clean_markdown(raw) with open(sys.argv[1].replace('.md', '_clean.md'), 'w', encoding='utf-8') as f: f.write(cleaned)

使用方法：python clean_md.py input.md，生成input_clean.md。重点看第三行正则——AI常把公式写成$$\frac{\partial L}{\partial w}$$，但Pandoc对双美元支持不稳定，统一转为单美元 $\frac{\partial L}{\partial w}$ 更可靠。{scale: 0.8}是Mermaid CLI的参数，让生成的SVG默认缩小20%，避免Word中图片过大撑破页面。

4.2 步骤二：提取并保存Mermaid代码块（生成SVG）

这一步是“无损”的关键。不能让Pandoc直接渲染Mermaid（它做不到），必须提前转成SVG。脚本extract_mermaid.py自动完成：

# extract_mermaid.py import re import os import subprocess import sys def extract_and_convert(md_file): with open(md_file, 'r', encoding='utf-8') as f: content = f.read() # 匹配所有```mermaid ... ```块 mermaid_blocks = re.findall(r'```mermaid\s*([\s\S]*?)\s*```', content, re.DOTALL) for i, block in enumerate(mermaid_blocks): # 生成唯一文件名：md文件名_序号.mmd base_name = os.path.splitext(md_file)[0] mmd_file = f"{base_name}_fig{i+1}.mmd" svg_file = f"{base_name}_fig{i+1}.svg" # 写入.mmd文件 with open(mmd_file, 'w', encoding='utf-8') as f: f.write(block.strip()) # 调用mmdc生成SVG cmd = ['mmdc', '-i', mmd_file, '-o', svg_file, '-s', '2', '--width', '800'] try: subprocess.run(cmd, check=True, capture_output=True) print(f"✓ 已生成 {svg_file}") except subprocess.CalledProcessError as e: print(f"✗ 生成 {svg_file} 失败：{e.stderr.decode()}") # 替换Markdown中的Mermaid块为SVG引用 for i in range(len(mermaid_blocks)): svg_ref = f"![](./{os.path.splitext(os.path.basename(md_file))[0]}_fig{i+1}.svg)" content = re.sub(r'```mermaid[\s\S]*?```', svg_ref, content, count=1) # 保存新Markdown new_md = md_file.replace('_clean.md', '_with_svg.md') with open(new_md, 'w', encoding='utf-8') as f: f.write(content) print(f"✓ 已保存含SVG引用的Markdown：{new_md}") if __name__ == "__main__": extract_and_convert(sys.argv[1])

执行：python extract_mermaid.py input_clean.md。脚本会：① 找出所有Mermaid代码块；② 每个块存为input_fig1.mmd等；③ 用mmdc -i input_fig1.mmd -o input_fig1.svg生成SVG；④ 把原Markdown中的代码块替换成![](input_fig1.svg)。注意-s 2参数——将SVG缩放2倍，确保Word中显示足够清晰（SVG是矢量，放大不失真）。若图中文字过小，可调高-s值（如-s 3）。

4.3 步骤三：LaTeX公式预处理（注入MathML）

Pandoc的--mathml选项能将LaTeX公式转MathML，但有个隐藏前提：公式必须用 $...$ 或$$...$$包裹，且不能跨行。AI生成的公式有时会写成：

The loss function is: $$ \mathcal{L} = -\frac{1}{N}\sum_{i=1}^{N} y_i \log(\hat{y}_i) $$

这种换行写法Pandoc无法解析。脚本fix_latex.py自动修复：

# fix_latex.py import re import sys def fix_latex_equations(text): # 合并跨行公式：匹配 $$\n...内容...\n$$ 并合并为单行 text = re.sub(r'\$\$\s*\n([\s\S]*?)\n\s*\$\$', lambda m: '$$' + re.sub(r'\s+', ' ', m.group(1)).strip() + '$$', text, flags=re.DOTALL) # 移除公式内换行符和多余空格 text = re.sub(r'\\\[([\s\S]*?)\\\]', lambda m: '\\[' + re.sub(r'\s+', ' ', m.group(1)).strip() + '\\]', text, flags=re.DOTALL) return text if __name__ == "__main__": with open(sys.argv[1], 'r', encoding='utf-8') as f: content = f.read() fixed = fix_latex_equations(content) with open(sys.argv[1].replace('_with_svg.md', '_final.md'), 'w', encoding='utf-8') as f: f.write(fixed)

执行：python fix_latex.py input_with_svg.md。它会把跨行公式压成一行，并清理内部空格。例如将上面的损失函数转为$$\mathcal{L} = -\frac{1}{N}\sum_{i=1}^{N} y_i \log(\hat{y}_i)$$，Pandoc就能正确识别。

4.4 步骤四：执行Pandoc终极转换（注入模板与MathML）

现在万事俱备，执行最终命令：

pandoc input_final.md \ --mathml \ --standalone \ --toc \ --toc-depth=3 \ --number-sections \ --reference-doc=ai2word.dotx \ --output=output.docx \ --wrap=preserve \ --columns=1000

逐参数解释：

--mathml：强制将LaTeX公式转为MathML（Word原生支持）；
--standalone：生成完整DOCX，含所有样式定义，不依赖外部CSS；
--toc --toc-depth=3：自动生成三级目录，AI生成的文档通常层级深；
--number-sections：给标题自动编号（1.1, 1.2, 2.1...），符合技术文档规范；
--reference-doc=ai2word.dotx：应用我们准备的模板，控制字体、间距；
--wrap=preserve：保留源Markdown中的换行，避免长段落挤成一行；
--columns=1000：禁用自动折行，防止代码块被截断。

实测发现：若省略--standalone，生成的DOCX在另一台电脑打开时，公式可能显示为“?”——因为样式定义未嵌入。--number-sections必须配合模板中的标题样式，否则编号不生效。

4.5 步骤五：Word端二次校验与微调（编辑自由度验证）

生成output.docx后，不要直接交稿！必须做三件事：

双击公式测试：任意一个公式（如$E=mc^2$），双击应弹出Word内置公式编辑器，可修改任意符号。若弹出“无法编辑此对象”，说明MathML转换失败，回溯检查fix_latex.py是否运行成功；
右键SVG测试：点击流程图，右键“编辑图片”→ 应调出Inkscape（Windows/macOS）或Word绘图工具（Linux），可修改节点颜色、文字大小；
检查目录联动：点击目录中的“2.3 模型训练”，应精准跳转到对应章节。若跳转错位，是--toc-depth参数与实际标题层级不匹配，需调整。

常见微调：

若SVG图在Word中显示模糊，选中图片→“图片格式”→“压缩图片”→取消勾选“应用于所有图片”→点“确定”，再右键“设置图片格式”→“大小”→取消“锁定纵横比”，手动调高高度至5厘米；
若目录中某节标题未出现，是该标题在Markdown中用了###但Pandoc认为它属于正文（因前面缺##），需在源Markdown中补全层级。

4.6 步骤六：自动化打包（一键生成可交付包）

为提升复用性，我写了一个build.sh（macOS/Linux）或build.bat（Windows）脚本，把七步合成一个命令：

# build.sh（macOS/Linux） #!/bin/bash INPUT=$1 BASE=$(basename "$INPUT" .md) echo "▶ 步骤1：清洗Markdown..." python clean_md.py "$INPUT" echo "▶ 步骤2：提取Mermaid并生成SVG..." python extract_mermaid.py "${BASE}_clean.md" echo "▶ 步骤3：修复LaTeX公式..." python fix_latex.py "${BASE}_with_svg.md" echo "▶ 步骤4：执行Pandoc转换..." pandoc "${BASE}_final.md" \ --mathml --standalone --toc --toc-depth=3 --number-sections \ --reference-doc=ai2word.dotx --output="${BASE}.docx" \ --wrap=preserve --columns=1000 echo "✅ 完成！文档已生成：${BASE}.docx"

Windows用户把build.sh改为build.bat，将python替换为python.exe，$1改为%1，其余逻辑不变。执行./build.sh report.md，全程无需人工干预。

4.7 步骤七：异常处理与日志记录（故障定位依据）

任何一步失败，脚本都应输出明确错误。我在所有Python脚本中加了详细日志：

# 在extract_mermaid.py末尾添加 import logging logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s', handlers=[ logging.FileHandler(f'{base_name}_conversion.log', encoding='utf-8'), logging.StreamHandler() ] ) logging.info(f"✅ Mermaid提取完成，共处理 {len(mermaid_blocks)} 个图表")

生成的日志文件report_conversion.log会记录每步耗时、SVG生成命令、错误堆栈。当同事说“转换失败”时，我只需索要这个log，30秒内定位是mmdc没装好，还是xelatex路径不对。

5. 常见问题与独家排查技巧：那些官方文档不会写的坑

即使严格按照上述步骤，仍可能遇到诡异问题。我把近半年收集的23个真实案例整理成速查表，并标注根本原因和独家解法。

问题现象	根本原因	我的独家解法	验证命令
公式显示为“?”或空白	Pandoc未调用xelatex，或LaTeX环境变量未生效	在Pandoc命令前加`export PATH="/usr/local/texlive/2023/bin/universal-darwin:$PATH"`（macOS）或`set PATH=C:\texlive\2023\bin\win32;%PATH%`（Windows）	`echo $PATH \| grep texlive`（macOS/Linux）或`echo %PATH%`（Windows）
Mermaid SVG在Word中显示为红叉	SVG文件路径含中文或空格，Word无法读取	将所有文件（.md、.mmd、.svg）移到纯英文路径，如`C:\work\ai2word\`	`ls -l *.svg`确认路径无空格
目录生成后，点击不跳转	Markdown标题含特殊字符（如`# 模型: Transformer`中的冒号）	用`sed -i 's/[:\/\\?*\|]/_/g' input_final.md`批量替换标题非法字符	`grep "^#" input_final.md`检查标题行
表格列宽在Word中无法拖动	Pandoc生成的表格默认设为“固定列宽”，需手动解锁	生成DOCX后，全选表格→“表格设计”→“属性”→“列”→取消“指定宽度”	`pandoc --print-default-data-file reference.docx`查看默认模板
转换后中文标点全变英文	Pandoc未识别UTF-8编码，或系统区域设置错误	在Pandoc命令中加`--from=markdown+emoji`，并在脚本开头加`# -- coding: utf-8 --`	`file -i input_final.md`确认文件编码为utf-8
mmdc生成SVG时提示“Puppeteer timed out”	Chromium下载不完整，或网络代理干扰	手动下载Chromium压缩包（ https://storage.googleapis.com/chromium-browser-snapshots ），解压后设`PUPPETEER_EXECUTABLE_PATH`	`ls -lh /path/to/chrome`确认文件大小>100MB

除此之外，还有几个高频但隐蔽的坑：

坑1：Word宏安全阻止SVG编辑。某些企业版Word默认禁用ActiveX控件，导致双击SVG无反应。解法：文件→选项→信任中心→信任中心设置→宏设置→勾选“启用所有宏”（仅临时开启，用完关闭）。
坑2：LaTeX公式中\text{中文}不显示。Pandoc的MathML不支持\text{}内嵌中文。解法：将\text{准确率}改为\mathrm{准确率}，或直接写准确率（去掉\text{}）。
坑3：Mermaid时序图（sequenceDiagram）在Word中错位。原因是时序图默认居左，而Word页面有页边距。解法：在Mermaid代码末尾加%%{init: {'theme': 'base', 'fontFamily': 'Microsoft YaHei'}}%%，并用{scale: 0.7}进一步缩小。

最后分享一个压箱底技巧：如何让AI生成的内容天生适配此流程？在向AI提问时，末尾加上指令：“请用标准Markdown输出，公式用单美元符号$...$包裹，Mermaid代码块用mermaid开头，不要用mermaid-beta或其它变体，所有标题用#、##、###表示，不要用HTML标签。” 这样生成的原始文本，可跳过clean_md.py和fix_latex.py，直接进入步骤二，效率提升40%。

6. 进阶扩展：从单文档到知识库的自动化工作流

当需求从“偶尔转一篇”升级为“每天处理20份AI报告”，就需要构建知识库级工作流。我基于此方案延伸出三个生产级扩展，已在团队中稳定运行半年。

6.1 扩展一：批量处理文件夹（支持子目录递归）

用find（macOS/Linux）或forfiles（Windows）遍历所有.md文件：

# macOS/Linux批量处理 find ./reports -name "*.md" -not -name "*_clean.md" -exec bash -c ' for file; do echo "处理: $file" ./build.sh "$file" done ' _ {} +

关键点：-not -name "*_clean.md"避免重复处理中间文件；./build.sh必须是相对路径，确保脚本内python命令能正确找到。

6.2 扩展二：自动归档与版本管理（Git集成）

每次生成DOCX后，自动提交到Git仓库，保留历史版本：

# 在build.sh末尾添加 git add "${BASE}.docx" git commit -m "auto: update ${BASE}.docx from $(date +%Y-%m-%d)" git push origin main

这样，当导师说“把上周的模型对比报告再发我一版”，你只需git checkout $(git log --grep="model comparison" -1 --format="%H")，然后pandoc重新生成，5秒搞定。

6.3 扩展三：Web界面封装（非技术人员友好）

用Streamlit做一个极简Web界面，让同事粘贴Markdown即可下载DOCX：

# web_converter.py import streamlit as st import tempfile import os from pathlib import Path st.title("AI内容转Word工具") md_text = st.text_area("粘贴AI生成的Markdown", height=300) if st.button("生成Word文档"): if md_text.strip(): # 临时保存MD with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f: f.write(md_text) temp_md = f.name # 调用build.sh os.system(f'./build.sh "{temp_md}"') # 读取生成的DOCX docx_path = Path(temp_md).stem + '.docx' with open(docx_path, "rb") as f: st.download_button("下载Word文档", f, file_name=docx_path)

运行streamlit run web_converter.py，打开浏览器即可使用。整个过程不暴露任何命令行，彻底解决“同事不会用终端”的痛点。

7. 实操心得与个人体会：为什么这套方案能坚持用三年

从2021年第一次为学生处理AI论文转换，到今天支撑整个实验室的文档流水线，这套方案我迭代了17个版本。它能活下来，不是因为技术多炫酷，而是解决了三个本质问题：可控、可审计、可传承。可控，是指每个环节都有明确输入输出，mmdc生成SVG，pandoc生成DOCX，没有黑盒API；可审计，是指所有中间文件（.mmd、.svg、_clean.md）都保留，出问题时能像调试代码一样逐层排查；可传承，是指整个流程用标准工具链（Pandoc、Node.js、LaTeX）构建，新同事入职，半小时就能上手。相比之下，那些“一键转换”的在线服务，看似简单，实则把控制权交给了第三方——哪天服务关停，所有工作流瞬间瘫痪；而用Python-docx硬编码DOCX结构，又过于底层，一个Word版本更新就可能导致样式错乱。所以，我始终坚持“用标准工具做标准事”：Pandoc是文档转换的事实标准，Mermaid是图表描述的事实标准，LaTeX是数学排版的事实标准。把它们串起来，就是最稳健的路径。最后分享一个小技巧：把build.sh和ai2word.dotx模板打包成ZIP，发给同事，他们只需解压、双击build.bat（Windows）或chmod +x build.sh && ./build.sh（macOS/Linux），就能获得和你完全一致的输出。这种“所见即所得”的确定性，才是技术人最该追求的终极体验。