DOCX Template Translator Skill

一个用于将 LaTeX、PDF、Markdown 或粗转 DOCX 转译成指定 Word 模板格式的 Codex skill。

它面向毕业论文、学位论文、单位报告、标准文档等场景，尤其适合那些 pandoc 默认 DOCX 输出不够用、必须严格套用学校或机构 Word 模板的任务。

English: README.en.md

---

一分钟看效果

仓库自带一个最小可跑示例 examples/minimal_markdown/，在仓库根目录跑：

python examples/minimal_markdown/run_example.py

脚本会现场生成一份 sample 模板，依次跑 inspect / adaptive / finalize，并在 Windows + Word 环境下输出 PDF 预览图。下面两张图使用同一份 sample.md 和同一份真实郑州大学学位论文模板生成，第一张走本项目的 adaptive pipeline，第二张只直接运行 pandoc --reference-doc：

本项目输出：pandoc → adaptive pipeline → Word finalize

直接 pandoc baseline：只使用 pandoc --reference-doc

两张图使用同一份输入和同一份模板，但编号上下文不同：本项目输出会保留 真实模板里已有的前置内容和章节编号，所以示例小节会接在模板原有章节之后 （例如显示为 4.7 / 8.7 这类编号，取决于模板当前内容）；直接 pandoc baseline 是从 sample.md 新建文档，只复用 --reference-doc 的样式定义， 因此从第 1 章开始编号（例如 1.5）。

对比可以看到：pandoc --reference-doc 能复用一部分样式，但它只知道样式定义， 不理解学校模板里的正文语义和版式约束；图表/公式/表格更容易跨页、间距松散， 表格也不是目标模板要求的三线表效果。本项目会先 inspect 模板，再用 adaptive pipeline 映射正文、图题、公式和表格，最后用 Word finalize 导出， 所以更适合严格学校/单位模板。

本项目输出图通过下面这条命令生成，然后从第 20 页裁剪出主体区域：

python examples/minimal_markdown/run_example.py \
    --template <你的本地模板.docx> \
    --preview-pages "20"

不传 --template 时 run_example.py 会用 build_template.py 现场生成的 轻量 sample 模板，输出更简化但完全可重现；--preview-pages 默认 "1-4"， 在 demo 模板上就够了。详见 examples/minimal_markdown/expected/README.md。

inspect / adaptive / preview 三步在 macOS / Linux / Windows 都能跑；用 Word COM 更新字段并导出 PDF 的 finalize 步骤只在 Windows + Microsoft Word 下可用。

为什么不是直接用 pandoc？

pandoc 很适合做第一轮转换，尤其适合 Markdown 和 LaTeX 类源文件。--reference-doc 也能复用 Word 样式，但它只知道“样式定义”，不知道模板里的页面和段落语义。

严格模板里经常会遇到这些问题：

• 封面、英文封面、声明页没有正确填写；
• 签名页、授权页、页眉页脚不符合模板；
• 模板样式名具有迷惑性，例如 Body Text 实际用于英文封面；
• 正文段落误套成封面样式；
• 图表标题丢失编号；
• 表格没有变成三线表；
• 参考文献引用不是上标，也不能跳转；
• 超链接以蓝色下划线显示，不适合打印版论文；
• 目录、页码、交叉引用字段没有更新；
• 没有自动导出 PDF 进行视觉检查。

这个 skill 的定位不是替代 pandoc，而是把 pandoc、Word 和 Python 组合起来，让 AI 根据用户上传的 Word 模板和源文件，自动写一版 项目专用的后处理脚本。

现有项目调研

• pandoc 支持 --reference-doc，可以复用 DOCX 样式。官方文档说明：reference DOCX 的正文内容会被忽略，主要使用其中的样式和文档属性。
• Quarto DOCX 也支持 reference-doc、目录、章节编号、引用和参考文献链接。
• pdf2docx 可以把原生 PDF 转成 DOCX；项目文档说明其底层使用 PyMuPDF 解析 PDF、规则化分析版面，并用 python-docx 生成 Word。
• python-docx-template 适合在预制 Word 模板里做 Jinja 风格变量替换。
• MDDoc 是商业化 Markdown 转 Word 工具，可以将 Markdown 元素映射到上传的 Word 模板。
• wmvanvliet/pandoc-tutorial 展示了复杂 LaTeX 转 DOCX 时的现实情况：pandoc 能完成大部分转换，但最后的模板适配通常需要自定义处理。
• openclaw/pdf-to-docx skill 是一个基于 pdf2docx 的 PDF 转 DOCX skill。

本项目的差异点是：它不是一个固定转换器，而是一个 开放的 AI 模板重建工作流。它让 AI 先检查用户上传的 Word 模板，再为该模板生成一版专用 Python 后处理脚本，从而适配学校、单位、期刊等强模板场景。

核心思路

1. 把 LaTeX/PDF/Markdown 当作 内容源。
2. 把 .docx 模板当作 排版源。
3. 先用 pandoc、Word 导入或其他工具生成粗略 body DOCX。
4. 检查模板样式、段落、编号、表格、超链接和 OOXML。
5. 让 AI 基于模板检查结果编写或修改 Python 重建脚本。
6. 用 python-docx 和底层 OOXML 操作生成最终 DOCX。
7. 用 Word COM 更新目录、页码等字段，并导出 PDF。
8. 把 PDF 渲染成预览拼图，快速检查封面、目录、图表、公式、参考文献。

支持输入

• LaTeX 项目：main.tex、章节、图片、BibTeX；
• Markdown 文件；
• 原生数字 PDF；
• 已有粗转 Word 文件。

如果有 LaTeX 或 Markdown 源文件，优先使用源文件。PDF 的语义信息较弱，不适合作为首选输入。