[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80919":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":38,"readmeContent":39,"aiSummary":40,"trendingCount":15,"starSnapshotCount":15,"syncStatus":41,"lastSyncTime":42,"discoverSource":43},80919,"docx-template-translator-skill","zouchenzhen\u002Fdocx-template-translator-skill","zouchenzhen","Codex \u002F Claude Skill for translating LaTeX, PDF, or Markdown into a specified Word template. 让 AI 将 LaTeX \u002F PDF \u002F Markdown 转写为指定 Word 模板格式。",null,"Python",41,4,33,1,0,5,8,3,2.1,"Apache License 2.0",false,"main",[24,25,26,27,28,29,30,31,32,33,34,35,36,37],"agent-skill","chinese","claude-skill","codex-skill","document-conversion","docx","latex","markdown","pandoc","pdf","python-docx","template-matching","thesis","word-template","2026-06-12 02:04:08","# DOCX Template Translator Skill\n\n一个用于将 **LaTeX、PDF、Markdown 或粗转 DOCX** 转译成指定 Word 模板格式的 Codex skill。\n\n它面向毕业论文、学位论文、单位报告、标准文档等场景，尤其适合那些 **pandoc 默认 DOCX 输出不够用**、必须严格套用学校或机构 Word 模板的任务。\n\nEnglish: [README.en.md](README.en.md)\n\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue.svg)\n![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)\n![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.10%2B-3776AB.svg)\n![Skill](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fskill-Codex-orange.svg)\n![Output](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Foutput-DOCX-2B579A.svg)\n\n---\n\n## 一分钟看效果\n\n仓库自带一个最小可跑示例 [`examples\u002Fminimal_markdown\u002F`](examples\u002Fminimal_markdown\u002F)，在仓库根目录跑：\n\n```bash\npython examples\u002Fminimal_markdown\u002Frun_example.py\n```\n\n脚本会现场生成一份 sample 模板，依次跑 inspect \u002F adaptive \u002F finalize，并在\nWindows + Word 环境下输出 PDF 预览图。下面两张图使用**同一份\n`sample.md` 和同一份真实郑州大学学位论文模板**生成，第一张走本项目的\nadaptive pipeline，第二张只直接运行 `pandoc --reference-doc`：\n\n**本项目输出：pandoc → adaptive pipeline → Word finalize**\n\n![本项目正文效果预览](examples\u002Fminimal_markdown\u002Fexpected\u002Fpreview.png)\n\n**直接 pandoc baseline：只使用 `pandoc --reference-doc`**\n\n![直接 pandoc baseline](examples\u002Fminimal_markdown\u002Fexpected\u002Fpandoc_baseline.png)\n\n> 两张图使用同一份输入和同一份模板，但**编号上下文不同**：本项目输出会保留\n> 真实模板里已有的前置内容和章节编号，所以示例小节会接在模板原有章节之后\n> （例如显示为 `4.7` \u002F `8.7` 这类编号，取决于模板当前内容）；直接 pandoc\n> baseline 是从 `sample.md` 新建文档，只复用 `--reference-doc` 的样式定义，\n> 因此从第 1 章开始编号（例如 `1.5`）。\n>\n> 对比可以看到：`pandoc --reference-doc` 能复用一部分样式，但它只知道样式定义，\n> 不理解学校模板里的正文语义和版式约束；图表\u002F公式\u002F表格更容易跨页、间距松散，\n> 表格也不是目标模板要求的三线表效果。本项目会先 inspect 模板，再用\n> adaptive pipeline 映射正文、图题、公式和表格，最后用 Word finalize 导出，\n> 所以更适合严格学校\u002F单位模板。\n>\n> 本项目输出图通过下面这条命令生成，然后从第 20 页裁剪出主体区域：\n>\n> ```bash\n> python examples\u002Fminimal_markdown\u002Frun_example.py \\\n>     --template \u003C你的本地模板.docx> \\\n>     --preview-pages \"20\"\n> ```\n>\n> 不传 `--template` 时 `run_example.py` 会用 `build_template.py` 现场生成的\n> 轻量 sample 模板，输出更简化但完全可重现；`--preview-pages` 默认 `\"1-4\"`，\n> 在 demo 模板上就够了。详见 [`examples\u002Fminimal_markdown\u002Fexpected\u002FREADME.md`](examples\u002Fminimal_markdown\u002Fexpected\u002FREADME.md)。\n\ninspect \u002F adaptive \u002F preview 三步在 macOS \u002F Linux \u002F Windows 都能跑；用 Word COM 更新字段并导出 PDF 的 finalize 步骤只在 Windows + Microsoft Word 下可用。\n\n## 为什么不是直接用 pandoc？\n\npandoc 很适合做第一轮转换，尤其适合 Markdown 和 LaTeX 类源文件。`--reference-doc`\n也能复用 Word 样式，但它只知道“样式定义”，不知道模板里的页面和段落语义。\n\n严格模板里经常会遇到这些问题：\n\n- 封面、英文封面、声明页没有正确填写；\n- 签名页、授权页、页眉页脚不符合模板；\n- 模板样式名具有迷惑性，例如 `Body Text` 实际用于英文封面；\n- 正文段落误套成封面样式；\n- 图表标题丢失编号；\n- 表格没有变成三线表；\n- 参考文献引用不是上标，也不能跳转；\n- 超链接以蓝色下划线显示，不适合打印版论文；\n- 目录、页码、交叉引用字段没有更新；\n- 没有自动导出 PDF 进行视觉检查。\n\n这个 skill 的定位不是替代 pandoc，而是把 pandoc、Word 和 Python 组合起来，让 AI\n根据用户上传的 Word 模板和源文件，自动写一版 **项目专用的后处理脚本**。\n\n## 现有项目调研\n\n- [pandoc](https:\u002F\u002Fpandoc.org\u002FMANUAL.html) 支持 `--reference-doc`，可以复用\n  DOCX 样式。官方文档说明：reference DOCX 的正文内容会被忽略，主要使用其中的样式和文档属性。\n- [Quarto DOCX](https:\u002F\u002Fquarto.org\u002Fdocs\u002Freference\u002Fformats\u002Fdocx.html) 也支持\n  `reference-doc`、目录、章节编号、引用和参考文献链接。\n- [pdf2docx](https:\u002F\u002Fgithub.com\u002FArtifexSoftware\u002Fpdf2docx) 可以把原生 PDF 转成\n  DOCX；项目文档说明其底层使用 PyMuPDF 解析 PDF、规则化分析版面，并用 `python-docx` 生成 Word。\n- [python-docx-template](https:\u002F\u002Fdocxtpl.readthedocs.io\u002F) 适合在预制 Word 模板里做 Jinja 风格变量替换。\n- [MDDoc](https:\u002F\u002Fwww.mddoc.app\u002F) 是商业化 Markdown 转 Word 工具，可以将 Markdown 元素映射到上传的 Word 模板。\n- [wmvanvliet\u002Fpandoc-tutorial](https:\u002F\u002Fgithub.com\u002Fwmvanvliet\u002Fpandoc-tutorial)\n  展示了复杂 LaTeX 转 DOCX 时的现实情况：pandoc 能完成大部分转换，但最后的模板适配通常需要自定义处理。\n- [openclaw\u002Fpdf-to-docx skill](https:\u002F\u002Fplaybooks.com\u002Fskills\u002Fopenclaw\u002Fskills\u002Fpdf-to-docx)\n  是一个基于 pdf2docx 的 PDF 转 DOCX skill。\n\n本项目的差异点是：它不是一个固定转换器，而是一个 **开放的 AI 模板重建工作流**。它让 AI 先检查用户上传的 Word 模板，再为该模板生成一版专用 Python 后处理脚本，从而适配学校、单位、期刊等强模板场景。\n\n## 核心思路\n\n1. 把 LaTeX\u002FPDF\u002FMarkdown 当作 **内容源**。\n2. 把 `.docx` 模板当作 **排版源**。\n3. 先用 pandoc、Word 导入或其他工具生成粗略 body DOCX。\n4. 检查模板样式、段落、编号、表格、超链接和 OOXML。\n5. 让 AI 基于模板检查结果编写或修改 Python 重建脚本。\n6. 用 `python-docx` 和底层 OOXML 操作生成最终 DOCX。\n7. 用 Word COM 更新目录、页码等字段，并导出 PDF。\n8. 把 PDF 渲染成预览拼图，快速检查封面、目录、图表、公式、参考文献。\n\n## 支持输入\n\n- LaTeX 项目：`main.tex`、章节、图片、BibTeX；\n- Markdown 文件；\n- 原生数字 PDF；\n- 已有粗转 Word 文件。\n\n如果有 LaTeX 或 Markdown 源文件，优先使用源文件。PDF 的语义信息较弱，不适合作为首选输入。\n\n## Skill 内容\n\nskill 位于：\n\n```text\nskills\u002Fdocx-template-translator\u002F\n```\n\n包含：\n\n- `SKILL.md`：AI 工作流程；\n- `scripts\u002Finspect_docx_template.py`：检查 Word 模板结构；\n- `scripts\u002Fadaptive_docx_pipeline.py`：可改造的 DOCX 重建脚本起点；\n- `scripts\u002Ffinalize_word_docx.py`：通过 Word 更新目录\u002F字段并导出 PDF；\n- `scripts\u002Fvalidate_docx_conversion.py`：结构层 QA（占位符 \u002F 顺序 \u002F 标题样式 \u002F 章节页眉 \u002F 受保护前置页格式漂移）；\n- `scripts\u002Fvalidate_docx_render.py`：渲染层 QA（TOC 字段是否存在 \u002F numId↔abstractNum 一致性 \u002F 多级标题格式串 \u002F 参考文献计数器独立性 \u002F 正文页眉静态文本残留 \u002F PDF 字段错误串）；\n- `scripts\u002Finject_toc_field.py`：在\"目录 \u002F Contents\"标题后幂等注入 `{ TOC \\o \"1-3\" \\h \\z \\u }` 字段，修复\"目录页只剩标题、TOC 字段缺失\"的常见 bug；\n- `scripts\u002Fset_styleref_header.py`：把指定 `headerN.xml` 的静态文本（如 `致谢`）改写为 `STYLEREF \u003CstyleId>` 字段，让正文页眉随章节动态更新；\n- `scripts\u002Frender_pdf_preview.py`：将 PDF 渲染为预览拼图；\n- `references\u002Fpandoc-limitations.md`：说明和 pandoc 默认功能的区别；\n- `references\u002Fzhengzhou-case-study.md`：郑州大学毕业论文模板转换案例。\n\n## 安装\n\n将 skill 复制到 Codex skills 目录。\n\nmacOS \u002F Linux：\n\n```bash\nmkdir -p ~\u002F.codex\u002Fskills\ncp -r skills\u002Fdocx-template-translator ~\u002F.codex\u002Fskills\u002F\n```\n\nWindows（PowerShell）：\n\n```powershell\nNew-Item -ItemType Directory -Force -Path \"$HOME\\.codex\\skills\" | Out-Null\nCopy-Item -Recurse -Force skills\\docx-template-translator \"$HOME\\.codex\\skills\\\"\n```\n\n然后可以这样调用：\n\n```text\nUse $docx-template-translator to convert my LaTeX thesis into Word using this .docx template.\n```\n\n如果需要在 Claude Code、Cursor 或其他 AI agent 里使用同一份 skill 文件夹，参考下文 [兼容性](#兼容性) 一节。\n\n## Python 依赖\n\n推荐安装：\n\n```bash\npip install python-docx pywin32 pymupdf pillow\n```\n\n可选：\n\n```bash\npip install pdf2docx\n```\n\nLaTeX 或 Markdown 转 DOCX 时建议另外安装 pandoc。\n\n最终更新目录和导出 PDF 时，推荐在 Windows 上使用本机 Microsoft Word，因为脚本通过\nWord COM 调用 Word 更新字段和导出 PDF。\n\n## 典型流程\n\n1. 用户提供源文件和 Word 模板。\n2. Codex 检查模板：\n\n```bash\npython scripts\u002Finspect_docx_template.py template.docx --out template_report.json\n```\n\n3. Codex 生成粗略 body DOCX：\n\n```bash\npandoc main.tex --citeproc --reference-doc template.docx -o body.docx\n```\n\n4. Codex 根据模板和 body 输出，改造 `scripts\u002Fadaptive_docx_pipeline.py`。\n   起步脚本支持 JSON 配置；如果是中文学位论文模板，可以直接复用内置 preset：\n\n```bash\npython skills\u002Fdocx-template-translator\u002Fscripts\u002Fadaptive_docx_pipeline.py \\\n    --template template.docx \\\n    --body-docx body.docx \\\n    --out final.docx \\\n    --config skills\u002Fdocx-template-translator\u002Fpresets\u002Fzhengzhou_thesis.json \\\n    --three-line-tables\n```\n\n非中文学位论文模板请去掉 `--three-line-tables`，并使用自己的 config（或保留默认行为，默认不会改写正文字体）。\n\n5. 最终处理：\n\n```bash\npython scripts\u002Ffinalize_word_docx.py final.docx --pdf\npython scripts\u002Frender_pdf_preview.py final.pdf --pages 1-8\n```\n\n## 和 pandoc 默认功能的本质区别\n\npandoc 是“格式转换器”，这个 skill 是“模板适配工作流”。\n\npandoc 默认能力通常止步于：把内容转换成 DOCX，并应用参考文档里的样式定义。\n\n这个 skill 的目标是进一步处理：\n\n- 根据模板语义重建封面和声明页；\n- 识别模板真正的正文、标题、目录、参考文献样式；\n- 自动补图表编号；\n- 改三线表；\n- 修引用上标和跳转；\n- 修超链接颜色；\n- 保留公式和图片；\n- 用 Word 更新目录和页码；\n- 自动导出 PDF 做视觉质检。\n\n## 项目状态\n\n这是一个工作流 skill，不是万能一键转换器。它的核心价值是：每个严格 Word 模板都有自己的局部规则，因此让 AI 先检查模板，再写一版专用 Python 脚本，往往比写一个“通用转换器”更可靠。\n\n## 已知限制\n\n- **finalize 阶段仅支持 Windows。** `finalize_word_docx.py` 通过 pywin32 调用 Microsoft Word COM 来更新字段\u002F目录并导出 PDF，因此只在装有真实 Word 的 Windows 机器上能跑完整流程。模板检查、adaptive pipeline 和 PDF 预览拼图在 macOS \u002F Linux 上不依赖 Word，可以直接运行。\n- **不支持扫描版 \u002F 纯图片 PDF。** PDF 输入需要原生数字文本层（pdf2docx \u002F Word 导入才能抽出结构），先 OCR 再转，或直接用 LaTeX \u002F Markdown 源文件。\n- **模板含宏：宏会被禁用。** finalize 阶段会先设置 `Word.AutomationSecurity = msoAutomationSecurityForceDisable`，再打开文档，因此模板里的 AutoMacros \u002F VBA 不会执行。详见 [SECURITY.md](SECURITY.md)。\n- **starter pipeline 默认行为是保守的。** 三线表、正文字体覆盖等中文学位论文专属处理改成了 opt-in，需要通过 config（参考 `presets\u002Fzhengzhou_thesis.json`）或 CLI flag 显式打开。默认行为不会偷偷改写你的正文字体。\n- **样式名识别覆盖英文和中文模板。** 其他本地化 Word 模板（日文 \u002F 韩文等）可能需要在 config 里补充 `unnumbered_heading_styles` 和 `body_candidate_styles`。\n\n## 安全说明\n\n- finalize 阶段会用本机 Microsoft Word 打开用户提供的 `.docx`。脚本默认禁用宏，请勿在不可信来源的输入上放宽该设置。\n- skill 工作流允许 AI agent 基于 `adaptive_docx_pipeline.py` 生成 \u002F 改写一份项目专用 Python 脚本。**运行 AI 改写后的脚本前请人工 review diff**。本项目自带的脚本不进行任何网络 I\u002FO，也只往用户显式指定的输出路径写文件。\n- 完整威胁模型详见 [SECURITY.md](SECURITY.md)。\n\n## 兼容性\n\nskill 元数据（带 `name` + `description` frontmatter 的 `SKILL.md`）虽然为 Codex 设计，但格式与 Anthropic Claude Skills 规范有重叠，因此同一份 skill 文件夹可以稍作包装后被其他 AI agent 复用。\n\n| Agent \u002F IDE     | 状态        | 说明 |\n| --------------- | ----------- | ---- |\n| **Codex**       | 原生支持     | 直接放到 `~\u002F.codex\u002Fskills\u002F`，用 `Use $docx-template-translator …` 触发。 |\n| **Claude Code** | 包装后可用   | `SKILL.md` 的 frontmatter 与 Claude Skills 规范一致，放到 Claude Skills 目录（例如 `~\u002F.claude\u002Fskills\u002F\u003Cname>\u002F`）或包装成 Claude Code plugin 即可。Python 脚本无需改动。 |\n| **Cursor**      | 手动 \u002F Rules | Cursor 没有原生 \"skill\" 概念，可以把 SKILL.md 内容粘到 `.cursor\u002Frules\u002F*.mdc` 里，让 agent 直接调用 `scripts\u002F*.py`。 |\n| **OpenClaw**    | 可适配       | 结构与 OpenClaw skill 约定接近，但仓库里没有 OpenClaw 专属 manifest，发布到该平台前请补元数据。 |\n\n脚本本身是纯 CPython，不依赖任何 agent runtime —— 任何能跑 shell 命令的 AI agent 都可以驱动这套工作流。\n\n## 许可证\n\n本项目采用 [Apache License 2.0](LICENSE) 开源许可。\n\nApache-2.0 允许使用、修改、分发、私有使用和商业使用，但需要遵守许可证条款。\n\n## 社区\n\n[LINUX DO — 中文开发者社区](https:\u002F\u002Flinux.do\u002F)\n\n本项目认可并感谢 LINUX DO 社区在中文开发者开源交流、项目分享和技术讨论中的价值。除非社区另有明确说明，此处仅为社区致谢和链接，不代表官方背书。\n","该项目旨在利用AI将LaTeX、PDF或Markdown文档转换为指定的Word模板格式。其核心功能包括对输入文档进行解析、自适应调整以及最终格式化输出，以确保生成的Word文档严格符合预设模板的要求。技术上，项目基于Python开发，结合了pandoc和Word处理库的优点，同时引入了AI辅助的自适应流程来优化文档结构与样式匹配度。适用于需要高度定制化Word输出的场景，如毕业论文、学位论文及各类正式报告的撰写过程中，当pandoc默认DOCX输出无法满足特定机构或学校要求时尤为有用。",2,"2026-06-11 04:02:50","CREATED_QUERY"]