md-to-word：专为 AI Agent 与 Markdown 打造的规范 Word 排版技能

English | 简体中文

用纯文本与 Git 挥洒思想，让 AI 全自动交付规范的 Word（.docx）文档。
一键直出符合中国高校硕博学位论文、中文核心学术期刊、企业级技术白皮书与规范公文排版标准的 Word 文件。

💡 为什么坚持 Markdown + md-to-word？

在长篇学术论文、专业技术报告与商业白皮书的撰写中，许多团队都经历过 Word 带来的协作阵痛：

• Word（.docx）是封闭的二进制黑盒：Git 无法对其进行行级差异对比（diff），改动全凭肉眼；多人协作时分支合并（merge）极易损坏文件，团队只能依靠“论文_终稿_v2_定稿_真的不改了.docx”痛苦传递。
• 排版耗费大量非生产性时间：在 Word 中反复刷样式、手动断开分节符、调整三线表边框、狂按空格硬凑公式对齐；一旦源文字稍作修改，排版往往前功尽弃。

md-to-word 提供的现代化工作流：

1. 内容与排版彻底解耦：作者在纯文本 Markdown 中专注逻辑与思考，享受 Git 版本分支、代码审查（PR）与持续集成的全部工程红利；
2. AI Agent 原生友好：大语言模型天然精通 Markdown，配合本技能可直接全流程闭环完成规范排版；
3. 确定性交付：通过纯净 Word 365 底模与中文声明式规则，全自动输出符合严格审查标准的规范 Word。

⚡ 30 秒看懂：你写的 vs 你得到的

排版规则写在 requirements.txt 里——一行一条，进 Git 能 diff，不用在 Word 里点。

你写的（demo/00_quickstart/hello.md，节选）：

---
title: "我的第一份规范 Word 文档"
---

# 引言

这是正文。

| 指标 | 方案 A | 方案 B |
|:---|---:|---:|
| 首次排版耗时（秒） | 1.10 | 1.04 |

…（此处省略三线表题注、表注与交叉引用前缀，全文见源文件）

你跑的：

bash scripts/export.sh hello.md -r requirements.txt -o hello.docx

你得到的（约 1 秒）：

中文首行缩进两个字符、西文 Times New Roman、三线表带表题表注——没有一步是在 Word 里点的。

📄 手上有现成的模板？（学校 / 期刊 / 单位发的 .docx）

不用对着模板一条条抄格式要求。把模板交给助手，让它跑这个脚本反推出一份 requirements.txt 草稿：

python3 scripts/read_reference_docx.py 学校模板.docx -o 论文_requirements.txt

读出来的是：页面尺寸、页边距、页眉页脚距边界、页码格式与起始、各样式的中西文字体与字号、加粗倾斜、对齐、行距（分得清倍数 / 固定值 / 最小值）、段前段后、缩进（字符单位也读得到）、段落下边框、表格边框与表头行、页眉页脚内容与域。读不出来的项会列成待确认清单，不会假装读到了。

🚀 装上它：三步，全交给你的 AI 助手

本项目是面向 AI 智能体调优的技能——你不用在终端敲任何命令，把源码交给助手，剩下的它代办。

1. 让助手自己装：把下面这句话原样发给它。各家助手的技能目录位置不同、系统之间也不同，交给它自己判断，你不用操心：

   帮我安装这个技能：https://github.com/ls18166407597-design/md-to-word
   克隆到你的技能目录，装好后读一遍 SKILL.md，告诉我它能做什么、怎么触发。

2. 验证装好了：让助手跑一遍仓库里最小的一份样例，看到 ✅ Word 文档导出成功 就算装成了：

   cd demo/00_quickstart
   bash ../../scripts/export.sh hello.md -r requirements.txt -o hello.docx
   

3. 开始用它：把你的 Markdown 发给助手，说清要什么格式：

   帮我把这份《智能系统设计.md》按某某大学研究生学位论文的格式要求导出为 Word。

   接下来它全包：识别版面与字体要求 → 生成合规底模 → 编译并净化 OOXML → 跑三道质量门禁 → 把 .docx 交给你。

💡 命令行 / CI 也可直接用：
bash scripts/export.sh 你的文档.md [-r 格式要求.txt] -o 输出文档.docx

加 --pdf 还能顺带用本机 Word 渲染一份 PDF——这是唯一能把目录页码、页眉章名这些「域」真正展开的方式，用它核对成品最直接。

📸 排版效果实测展示（本技能体系自举样例）

除上面那份最小样例外，仓库还内置两套完整样例，均基于 md-to-word 本身的设计原理与工程实践撰写，真正实现“以身说法”：

样例一：中文硕博学位论文 / 核心期刊（全要素学术排版）

前置独立小写罗马页码（i, ii）、Word 原生动态目录（收到二级）、双线动态章名页眉、三线表跨页时自动重现表头、公式按章编号（(2.1)）且绝对居中靠右、GB/T 7714-2015 顺序编码文献。

📁 源码、格式规则与一键复现命令 → demo/01_chinese_thesis

论文开篇与摘要（居中大标题/无页眉）	Word 动态目录（点线制表位/小写罗马页码）	动态章名页眉与架构流程图

公式按章编号与质量门禁流程	表跨页后自动重现表头与国标参考文献

样例二：现代企业级技术白皮书 / 商业研究报告

扁平单节结构、开门见山执行摘要、单线现代极简页眉、全网格线数据表、APA 7th 作者-年份制引用。

📁 源码、格式规则与一键复现命令 → demo/02_modern_report

执行摘要与正文第一章	效能推导公式与耗时实测图	全网格线数据表与 APA 参考文献

🔍 横向对比：同一个效果，各方要做什么

判定口径：各工具均取默认导出（不装模板、不写 filter）。⚠️ = 能做，但要手工改底模、逐段逐表设置或自己写 XML；✅ = 默认就有；❌ = 默认路径下没有。最后一列是本技能的实际写法。

这张表里 Pandoc 与 Quarto 的 ✅ 是如实标注的——比如跨页重复表头和 citeproc 参考文献，它们默认就有。本技能的价值不在「别人做不到」，而在同一份 requirements.txt 把所有项一次性说清：不用改底模、不用写 XML、不用逐段逐表点鼠标。

📚 常见疑问：什么是参考文献（.bib）？如何获取？

很多初次接触学术排版的用户不清楚 .bib 文件是什么：

• 什么是 .bib？
  .bib（BibTeX）是全球学术界通用的纯文本结构化参考文献数据库。每一条文献包含条目类别、作者、篇名、期刊、出版年份等字段。
• 如何获取？完全不需要手动敲代码，两大傻瓜获取方式：
  1. 各大检索网站一键导出（知网 / 百度学术 / 谷歌学术）：
     在知网（CNKI）、百度学术或 Google Scholar 搜索到目标论文后，点击文献下方的“引用”按钮 → 选择“导出 BibTeX”，将弹出的文本复制保存为 references.bib 即可。
  2. 文献管理软件批量导出（Zotero / EndNote / Mendeley）：
     在 Zotero 或 EndNote 中选中所需文献，右键选择“导出文献库”，导出格式选择 BibTeX。
• 如何在正文中使用？
  在 Markdown 中只需写 [@文献key]（例如 [@vaswani2017]），导出时系统将根据指定的 CSL 样式表（如国标 chinese-gb7714-2015-numeric.csl 或 apa.csl）在文末自动生成严整规范的参考文献列表。

🛠️ 环境依赖

运行本技能仅需两项基础环境：

1. Python 依赖（Python 3.9+）：

   pip install -r requirements.txt
   

2. 渲染引擎 Quarto（Quarto ≥ 1.4，内嵌 Pandoc）：

   # macOS
   brew install quarto
   
   # Linux / Windows：请访问 https://quarto.org/docs/get-started/ 下载官方安装包
   

📖 技能路由与文档速查

📄 开源协议

本项目基于 MIT License 开源，欢迎自由使用、集成与改进。