zouchenzhen/docx-template-translator-skill

Letzte erfasste Quellaktivität: 5. Juni 2026 um 15:56

SkillsMP-Katalog aktualisiert: 5. November 2026 um 19:57

gesammelte Skills: 1

GitHub-Stars: 79
GitHub-Forks: 6

Mit einem KI-Assistenten installieren

Diesen Prompt kopieren und in den verwendeten KI-Assistenten einfügen.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/zouchenzhen/docx-template-translator-skill.

README des Repositorys

README-Quelldatei: README.md

README-Quelldatei lesen

Vollständige README anzeigen

# DOCX Template Translator Skill 一个用于将 **LaTeX、PDF、Markdown 或粗转 DOCX** 转译成指定 Word 模板格式的 Codex skill。它面向毕业论文、学位论文、单位报告、标准文档等场景，尤其适合那些 **pandoc 默认 DOCX 输出不够用**、必须严格套用学校或机构 Word 模板的任务。 English: [README.en.md](README.en.md) ![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg) ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg) ![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg) ![Skill](https://img.shields.io/badge/skill-Codex-orange.svg) ![Output](https://img.shields.io/badge/output-DOCX-2B579A.svg) --- ## 一分钟看效果仓库自带一个最小可跑示例 [`examples/minimal_markdown/`](examples/minimal_markdown/)，在仓库根目录跑： ```bash 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** ![本项目正文效果预览](examples/minimal_markdown/expected/preview.png) **直接 pandoc baseline：只使用 `pandoc --reference-doc`** ![直接 pandoc baseline](examples/minimal_markdown/expected/pandoc_baseline.png) > 两张图使用同一份输入和同一份模板，但**编号上下文不同**：本项目输出会保留 > 真实模板里已有的前置内容和章节编号，所以示例小节会接在模板原有章节之后 > （例如显示为 `4.7` / `8.7` 这类编号，取决于模板当前内容）；直接 pandoc > baseline 是从 `sample.md` 新建文档，只复用 `--reference-doc` 的样式定义， > 因此从第 1 章开始编号（例如 `1.5`）。 > > 对比可以看到：`pandoc --reference-doc` 能复用一部分样式，但它只知道样式定义， > 不理解学校模板里的正文语义和版式约束；图表/公式/表格更容易跨页、间距松散， > 表格也不是目标模板要求的三线表效果。本项目会先 inspect 模板，再用 > adaptive pipeline 映射正文、图题、公式和表格，最后用 Word finalize 导出， > 所以更适合严格学校/单位模板。 > > 本项目输出图通过下面这条命令生成，然后从第 20 页裁剪出主体区域： > > ```bash > 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`](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](https://pandoc.org/MANUAL.html) 支持 `--reference-doc`，可以复用 DOCX 样式。官方文档说明：reference DOCX 的正文内容会被忽略，主要使用其中的样式和文档属性。 - [Quarto DOCX](https://quarto.org/docs/reference/formats/docx.html) 也支持 `reference-doc`、目录、章节编号、引用和参考文献链接。 - [pdf2docx](https://github.com/ArtifexSoftware/pdf2docx) 可以把原生 PDF 转成 DOCX；项目文档说明其底层使用 PyMuPDF 解析 PDF、规则化分析版面，并用 `python-docx` 生成 Word。 - [python-docx-template](https://docxtpl.readthedocs.io/) 适合在预制 Word 模板里做 Jinja 风格变量替换。 - [MDDoc](https://www.mddoc.app/) 是商业化 Markdown 转 Word 工具，可以将 Markdown 元素映射到上传的 Word 模板。 - [wmvanvliet/pandoc-tutorial](https://github.com/wmvanvliet/pandoc-tutorial) 展示了复杂 LaTeX 转 DOCX 时的现实情况：pandoc 能完成大部分转换，但最后的模板适配通常需要自定义处理。 - [openclaw/pdf-to-docx skill](https://playbooks.com/skills/openclaw/skills/pdf-to-docx) 是一个基于 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 的语义信息较弱，不适合作为首选输入。 ## Skill 内容 skill 位于： ```text skills/docx-template-translator/ ``` 包含： - `SKILL.md`：AI 工作流程； - `scripts/inspect_docx_template.py`：检查 Word 模板结构； - `scripts/adaptive_docx_pipeline.py`：可改造的 DOCX 重建脚本起点； - `scripts/finalize_word_docx.py`：通过 Word 更新目录/字段并导出 PDF； - `scripts/validate_docx_conversion.py`：结构层 QA（占位符 / 顺序 / 标题样式 / 章节页眉 / 受保护前置页格式漂移）； - `scripts/validate_docx_render.py`：渲染层 QA（TOC 字段是否存在 / numId↔abstractNum 一致性 / 多级标题格式串 / 参考文献计数器独立性 / 正文页眉静态文本残留 / PDF 字段错误串）； - `scripts/inject_toc_field.py`：在"目录 / Contents"标题后幂等注入 `{ TOC \o "1-3" \h \z \u }` 字段，修复"目录页只剩标题、TOC 字段缺失"的常见 bug； - `scripts/set_styleref_header.py`：把指定 `headerN.xml` 的静态文本（如 `致谢`）改写为 `STYLEREF <styleId>` 字段，让正文页眉随章节动态更新； - `scripts/render_pdf_preview.py`：将 PDF 渲染为预览拼图； - `references/pandoc-limitations.md`：说明和 pandoc 默认功能的区别； - `references/zhengzhou-case-study.md`：郑州大学毕业论文模板转换案例。 ## 安装将 skill 复制到 Codex skills 目录。 macOS / Linux： ```bash mkdir -p ~/.codex/skills cp -r skills/docx-template-translator ~/.codex/skills/ ``` Windows（PowerShell）： ```powershell New-Item -ItemType Directory -Force -Path "$HOME\.codex\skills" | Out-Null Copy-Item -Recurse -Force skills\docx-template-translator "$HOME\.codex\skills\" ``` 然后可以这样调用： ```text Use $docx-template-translator to convert my LaTeX thesis into Word using this .docx template. ``` 如果需要在 Claude Code、Cursor 或其他 AI agent 里使用同一份 skill 文件夹，参考下文 [兼容性](#兼容性) 一节。 ## Python 依赖推荐安装： ```bash pip install python-docx pywin32 pymupdf pillow ``` 可选： ```bash pip install pdf2docx ``` LaTeX 或 Markdown 转 DOCX 时建议另外安装 pandoc。最终更新目录和导出 PDF 时，推荐在 Windows 上使用本机 Microsoft Word，因为脚本通过 Word COM 调用 Word 更新字段和导出 PDF。 ## 典型流程 1. 用户提供源文件和 Word 模板。 2. Codex 检查模板： ```bash python scripts/inspect_docx_template.py template.docx --out template_report.json ``` 3. Codex 生成粗略 body DOCX： ```bash pandoc main.tex --citeproc --reference-doc template.docx -o body.docx ``` 4. Codex 根据模板和 body 输出，改造 `scripts/adaptive_docx_pipeline.py`。起步脚本支持 JSON 配置；如果是中文学位论文模板，可以直接复用内置 preset： ```bash python skills/docx-template-translator/scripts/adaptive_docx_pipeline.py \ --template template.docx \ --body-docx body.docx \ --out final.docx \ --config skills/docx-template-translator/presets/zhengzhou_thesis.json \ --three-line-tables ``` 非中文学位论文模板请去掉 `--three-line-tables`，并使用自己的 config（或保留默认行为，默认不会改写正文字体）。 5. 最终处理： ```bash python scripts/finalize_word_docx.py final.docx --pdf python scripts/render_pdf_preview.py final.pdf --pages 1-8 ``` ## 和 pandoc 默认功能的本质区别 pandoc 是“格式转换器”，这个 skill 是“模板适配工作流”。 pandoc 默认能力通常止步于：把内容转换成 DOCX，并应用参考文档里的样式定义。这个 skill 的目标是进一步处理： - 根据模板语义重建封面和声明页； - 识别模板真正的正文、标题、目录、参考文献样式； - 自动补图表编号； - 改三线表； - 修引用上标和跳转； - 修超链接颜色； - 保留公式和图片； - 用 Word 更新目录和页码； - 自动导出 PDF 做视觉质检。 ## 项目状态这是一个工作流 skill，不是万能一键转换器。它的核心价值是：每个严格 Word 模板都有自己的局部规则，因此让 AI 先检查模板，再写一版专用 Python 脚本，往往比写一个“通用转换器”更可靠。 ## 已知限制 - **finalize 阶段仅支持 Windows。** `finalize_word_docx.py` 通过 pywin32 调用 Microsoft Word COM 来更新字段/目录并导出 PDF，因此只在装有真实 Word 的 Windows 机器上能跑完整流程。模板检查、adaptive pipeline 和 PDF 预览拼图在 macOS / Linux 上不依赖 Word，可以直接运行。 - **不支持扫描版 / 纯图片 PDF。** PDF 输入需要原生数字文本层（pdf2docx / Word 导入才能抽出结构），先 OCR 再转，或直接用 LaTeX / Markdown 源文件。 - **模板含宏：宏会被禁用。** finalize 阶段会先设置 `Word.AutomationSecurity = msoAutomationSecurityForceDisable`，再打开文档，因此模板里的 AutoMacros / VBA 不会执行。详见 [SECURITY.md](SECURITY.md)。 - **starter pipeline 默认行为是保守的。** 三线表、正文字体覆盖等中文学位论文专属处理改成了 opt-in，需要通过 config（参考 `presets/zhengzhou_thesis.json`）或 CLI flag 显式打开。默认行为不会偷偷改写你的正文字体。 - **样式名识别覆盖英文和中文模板。** 其他本地化 Word 模板（日文 / 韩文等）可能需要在 config 里补充 `unnumbered_heading_styles` 和 `body_candidate_styles`。 ## 安全说明 - finalize 阶段会用本机 Microsoft Word 打开用户提供的 `.docx`。脚本默认禁用宏，请勿在不可信来源的输入上放宽该设置。 - skill 工作流允许 AI agent 基于 `adaptive_docx_pipeline.py` 生成 / 改写一份项目专用 Python 脚本。**运行 AI 改写后的脚本前请人工 review diff**。本项目自带的脚本不进行任何网络 I/O，也只往用户显式指定的输出路径写文件。 - 完整威胁模型详见 [SECURITY.md](SECURITY.md)。 ## 兼容性 skill 元数据（带 `name` + `description` frontmatter 的 `SKILL.md`）虽然为 Codex 设计，但格式与 Anthropic Claude Skills 规范有重叠，因此同一份 skill 文件夹可以稍作包装后被其他 AI agent 复用。 | Agent / IDE | 状态 | 说明 | | --------------- | ----------- | ---- | | **Codex** | 原生支持 | 直接放到 `~/.codex/skills/`，用 `Use $docx-template-translator …` 触发。 | | **Claude Code** | 包装后可用 | `SKILL.md` 的 frontmatter 与 Claude Skills 规范一致，放到 Claude Skills 目录（例如 `~/.claude/skills/<name>/`）或包装成 Claude Code plugin 即可。Python 脚本无需改动。 | | **Cursor** | 手动 / Rules | Cursor 没有原生 "skill" 概念，可以把 SKILL.md 内容粘到 `.cursor/rules/*.mdc` 里，让 agent 直接调用 `scripts/*.py`。 | | **OpenClaw** | 可适配 | 结构与 OpenClaw skill 约定接近，但仓库里没有 OpenClaw 专属 manifest，发布到该平台前请补元数据。 | 脚本本身是纯 CPython，不依赖任何 agent runtime —— 任何能跑 shell 命令的 AI agent 都可以驱动这套工作流。 ## 许可证本项目采用 [Apache License 2.0](LICENSE) 开源许可。 Apache-2.0 允许使用、修改、分发、私有使用和商业使用，但需要遵守许可证条款。 ## 社区 [LINUX DO — 中文开发者社区](https://linux.do/) 本项目认可并感谢 LINUX DO 社区在中文开发者开源交流、项目分享和技术讨论中的价值。除非社区另有明确说明，此处仅为社区致谢和链接，不代表官方背书。

README des Repositorys wird geladen…

Skills in diesem Repository

Textverarbeiter und Schreibkräfte

1 Berufskategorien · 100% klassifiziert

Skill

Beruf

Beschreibung

Aktualisiert

docx-template-translator

Textverarbeiter und Schreibkräfte

Adaptive conversion of LaTeX, PDF, or Markdown sources into a complete Word .docx that follows a user-supplied .docx template. Use when pandoc --reference-doc alone is not enough — for thesis, dissertation, report, or institutional Word formatting that needs…

Quellsprache: Englisch

2026-06-05

Es werden 1 von 1 gesammelten Skills angezeigt.