md-to-wordCAUTION

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

---
title: "我的第一份规范 Word 文档"
crossref:
tbl-prefix: "表"
---

# 引言

这是一份最小样例:一页纸、二十六行 Markdown。中文首行缩进两个字符、西文用
Times New Roman、行距 1.5 倍、各级标题黑体——这些都不用你在 Word 里点。

# 一个三线表

| 样例 | 篇幅 | 稳定耗时 | 主要演示的排版要素 |
|:------|:--|:---|:--------------|
| 最小样例(本文) | 1 页 | 0.95 s | 中西文字体、首行缩进、多级标题、三线表 |
| 技术白皮书样例 | 3 页 | 1.03 s | 全网格数据表、APA 引用、单线极简页眉 |
| 学位论文样例 | 8 页 | 1.15 s | 目录、分节页码、双线章名页眉、跨页表头 |

...(表格上方的表题包裹块、表注与正文段落见源文件)

纸张:A4
页边距:

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: md-to-word
description: "Exports Markdown documents, reports, and academic papers to standard, professional Word (.docx) files with modern Word 365 styles, custom typography, three-line tables, equation right-alignment, figure/table cross-referencing, and optional CSL bibliography formatting. Use when user asks to export Markdown to Word, generate docx, convert md/txt/text to docx, 导出Word, 文档转Word, 报告转Word, 论文转Word, 期刊排版, Word排版, 公文排版, or prepare submission docx."
license: MIT
compatibility: "Quarto >= 1.4;Python 3 需安装 python-docx、lxml、pyyaml。"
---

# Markdown → Word 现代文档与学术排版导出技能

把 Markdown 导出成符合规范的 Word (`.docx`)。两类稿子:**通用正式文档**(报告、技术方案、公文)与**学术论文**(期刊/学位论文,含摘要、公式编号右对齐、三线表、CSL 参考文献、动态目录)。

> **核心设计哲学**:内容与排版解耦(Markdown 为源,格式全交给本技能编译,于是文档能进 Git 做行级 diff);AI 全流程代办(用户提需求,Agent 包办格式提取、稿件改造、样式装配与质量闭环)。
>
> **统一入口**:`bash <本技能目录>/scripts/export.sh <稿件.md> [-r <格式要求.txt>] [-o <输出.docx>]`(若稿件同目录有唯一的 `.txt`,`-r` 可省略,模板每次导出实时生成)
> **核心引擎**:Quarto 现代渲染 + 纯净 Word 365 底模 (`resources/pure_modern_base.docx`) + 公式居中与编号靠右对齐引擎 + 自动质量门禁(导前预检 / 导后防丢数 / XML 样式对账)
>
> **首次使用前**:`pip install -r requirements.txt`,并确认本机有 Quarto(`quarto --version` 能查到即可,不卡版本号;没有则 `brew install quarto`)。缺任一个,导出第一步就会停下并提示。

**技能目录结构与文档路由**:

| 路径 | 用途与何时查阅 |
|:--|:--|
| `SKILL.md` | 技能主入口。理解 Agent 代办流程、模块化组装 `requirements.txt`、改造导出稿件并执行导出 |
| `references/reference.md` | 查 `requirements.txt` 完整合法词表(§1.5)、排版推导默认值(§1.6)、内置 CSL 清单(§3)时查阅 |
| `references/design.md` | **导出行为不符合预期**时(先看其 §2 故障排查找根因);或**需要修改 `scripts/` 下的脚本**时查阅 |
| `scripts/` | 导出与校验全链路脚本(主入口 `scripts/export.sh`) |
| `resources/` | 纯净 Word 365 底模 `pure_modern_base.docx` 与内置规范化引用样式库 `resources/csl/*.csl` |

---

## 〇、 Agent 核心代办工作流(面向任意输入与零基础用户)

用户的原始诉求通常是“把这份内容按某种格式要求导出为 Word”。**Agent 应全程代劳格式提取、标准 Markdown 转换与配置生成,遵循「先快速跑通导出让用户看到 `.docx`,再按反馈微调」的原则**:

### 1. 任意来源输入 → 标准化导出 `.md`
- 用户的源材料可能是**对话刚生成的文本、`.txt`、普通 `.md`、旧 `.docx` 或 `.pdf`**。
- Agent 先将其整理或提取为一份符合本技能排版契约(见 §一)的标准化 `.md` 文件(若用户原本就有 `.md`,则在同目录创建 `*_export.md` 副本进行改造,不破坏原稿)。

### 2. 识别格式需求 → 直接生成 `requirements.txt`(无需另建需求文档)
直接在稿件同目录编写 `<名称>_requirements.txt`(**整行** `#` 是注释,可记格式来源或分块;**行内 `#` 不是**——`正文:宋体 小四 #加粗` 里的 `#加粗` 会被当成没见过的词报错)。格式要求有三种获取路径:
- **路径 A:用户提供了参考 `.docx` 模板/样例文件(最准确)**
  直接跑本技能自带的读取脚本,把参考文件的格式读成一份 `requirements.txt` 草稿:

  ```bash
  python3 <本技能目录>/scripts/read_reference_docx.py 参考.docx -o <名称>_requirements.txt
  ```

  **读不出的项列在草稿末尾**,照着核一遍,别直接当成品。能读出哪些见 `reference.md §2`;
  ⚠ 别用 `python-docx` 的 API 自己读(中文字体、字符缩进、行距类型它都够不着,原因见 `design.md §2.21`)。

- **路径 B:用户提供了文字/PDF 格式说明或口头要求(最常见)**
  用户的要求通常很粗糙(例如只说“正文宋体小四、1.5倍行距”,没提段前段后、没提表内字号)。Agent **将用户明文指定的属性填入,未提及的同套必填字段按配对推导原则补齐**(例如不需额外段间距就显式写 `段前0磅 段后0磅`,不需缩进就写 `首行缩进0字符`,表内文字比正文小 1.5~2pt;推导规则见 `references/reference.md §1.6`)。
- **路径 C:用户未指定具体格式**
  Agent 直接采用 §2.3 的兜底基准(中文默认宋体/黑体小四,英文默认 Times New Roman 12pt),先快速导出一版标准 `.docx` 交付用户,再根据用户反馈调整。

### 3. 灵活处理参考文献(无文献 / 手写文献 / `.bib` 三种场景)
- **场景 1:普通文档 / 报告(无参考文献)**
  YAML 中**不写** `bibliography:` 和 `csl:`,文末不加任何文献标记,`requirements.txt` 中也不写参考文献样式,直接导出。
- **场景 2:无 `.bib` 文件,但文末已有手写的参考文献文本(如 `[1] 张三...`)**
  - **直接排版(推荐)**:YAML 不写 `bibliography:` / `csl:`,将文末标题用 `::: {custom-style="References Title"}` 包裹,将手写文献条目放进 `::: {custom-style="Bibliography"}` 包裹块中,即可直接套用 0.5 英寸悬挂缩进与文献专属字号;
  - **转换引用格式**:若用户要求统一转为 APA 或 GB/T 7714 等特定格式,由 Agent 根据手写文献在同目录生成 `references.bib`,并在正文填入引用键后按场景 3 导出。
- **场景 3:使用 `.bib` 文献库与 CSL 自动排版**
  - YAML 中配置 `bibliography: refs.bib` 和 `csl: <文件名.csl>`(**直接写本技能 `resources/csl/` 下的内置文件名即可**,如 `csl: apa.csl` 或 `csl: chinese-gb7714-2015-numeric.csl`,脚本会自动寻路挂载);
  - 正文引用**默认就是可点击的**(跳到文末对应条目),不用配什么;不要这个效果才在 YAML 里写 `link-citations: false`;
  - **正文引用写法(只有两种标准形式)**:
    - **括号引用 `[@key]`**(多篇用分号隔开:`[@zhang2024; @smith2023]`):在作者-年份制(APA)下渲染为 `(Zhang, 2024; Smith, 2023)`,在数字顺序编码制(GB/T 7714 / IEEE)下渲染为 `[1, 2]`;
    - **叙述引用 `@key`**(适合将作者作为句子主语):例如 `正如 @zhang2024 所指出`,在作者-年份制下渲染为 `正如 Zhang (2024) 所指出`,在数字制下渲染为 `正如 [1] 所指出`。

---

## 一、 导出稿 `.md` 排版契约

1. **标题与层级**:
   - 文档主标题写在 YAML `title: "主标题"` 里;正文从 `#` 起是各级章节标题,层级连续不跳级;标题自带阿拉伯数字编号时(`1.`、`2.1`、`2.1.1`),编号深度等于 `#` 的数量。
2. **自定义样式围栏(`:::`)与块间空行**:
   - 摘要、关键词、表题、表注、参考文献标题等用 `::: {custom-style="样式名"}` 包裹,**块内只放正文**,标题写在外面;
   - 所有块级元素(`$$` 公式、`:::` 围栏首行、表格首行、独立图片行、短代码)与相邻正文之间**必须隔开空行**。
3. **公式与图表**:
   - 带编号公式:`$$Y = \beta_0 + \beta_1 X + \epsilon$$ {#eq-model1}`,正文引用写 `@eq-model1`;**中文文档要在 YAML 里设交叉引用前缀**——`crossref: {eq-prefix: "式", fig-prefix: "图", tbl-prefix: "表"}`;**学位论文要按章编号**(`(2.1)` 而非 `(1)`)再加一行 `chapters: true`;无编号公式直接写 `$$...$$`;
   - 图片:用纯原生语法 `![图片题注文字](path/to/img.png){width=14cm}`,题注与内联格式直接写在括号内,**外层不要再套 `:::` 围栏**;
   - **图片不要加 `{#fig-xxx}` 标签**:会被套上三线表的框线、并失去居中。图号手写在题注文字里即可。(预检看不出这条,请照此写;机制见 `design.md §2.22`。)
   - 表格:表题用 `::: {custom-style="Table Caption"}` 包在上方,表注用 `::: {custom-style="Table Note"}` 包在下方。列宽**默认不动**(按内容排,长的撑满、短的窄着居中)。**要定列宽比例,就把分隔行的短横线写得长短不一**(`|:--|:--|:------|` → 约 2:2:6,按版心铺开)——**这靠本技能的后处理兑现,pandoc 本身不认**。写成一模一样 = 没指定;也因此**无法强制等宽**(三列等宽就写不出「长短不一」)。表要带首尾竖线(`| 甲 | 乙 |`),不带外框的写法认不出。
4. **标准短代码(仅限三种,独占一行且前后留空行)**:
   - 分页:`{{< pagebreak >}}`;
   - 目录:`{{< toc >}}`(默认收 1~3 级)或 `{{< toc 2 >}}`。**条目外观由 Word 决定**——`目录标题:` 生效,`目录一/二/三级` 会被 Word 更新域时重置,**别承诺能自定义条目字体/缩进**(原因见 `design.md §2.23`);
   - 分节:`{{< section 页码=罗马 起始=1 >}}`(**只在需要「前置罗马 + 正文阿拉伯」时用**;页码参数 `罗马`(`I, II`)/`小写罗马`(`i, ii`)/`阿拉伯` 等):
     - **它描述的是「它上面那一节」**(OOXML 里分节属性归前一节):标记写在目录后、第一章前,写的却是前置件的小写罗马——**正文节的页码由 `requirements.txt` 的 `页码:` 决定**;
     - **位置固定**:前置件(目录/摘要)最后、正文首个 `# 一级标题` 之前;
     - **后面不要再写 `{{< pagebreak >}}`**:分节符已自带「下一页」(导前预检会拦)。
5. **列表、引用块与字体扩展提示**:
   - **字体自由指定**:支持任意本机已安装字体(如公文常用的 `仿宋`/`仿宋_GB2312`/`方正小标宋简体`、商务报告常用的 `微软雅黑`/`等线`、引文常用的 `楷体`)。
   - **列表与条目**:Markdown 列表(`- ` / `1. `)映射为 **`紧凑` 样式**——**与表内文字同一个样式**,字体/字号/对齐都由 `紧凑:` 那行定(见 `reference.md §1.5`);要条目与正文完全同格式,就别用列表,正文里写行内序号(`(1)...`、`1 ...`)当普通段落。
   - **引用块**:若稿件使用了 `> ` 块引用,需在 `requirements.txt` 中声明 `引用块:` 样式行。
   - **代码块**:``` 围栏照常写,落 `SourceCode` 样式——底模已给等宽字体、清掉首行缩进、单倍行距,**不写 `代码:` 也正常**;要改字色字号才写 `代码:` 样式行。行内 `` `code` `` 走 `VerbatimChar`。
   - **脚注

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

not all pinned

Secrets in source

none-found

Findings (8)

hello.docx

thesis_sample.docx

report_sample.docx

pure_modern_base.docx

纸张:A4, 页边距:上2.54cm, 西文字体:Times, 校对语言:zh-CN, 文档标题:黑体/Times, 一级标题:黑体/Times, 正文:宋体/Times, 首段:宋体/Times

纸张:A4, 页边距:上2.54cm, 西文字体:Times, 校对语言:zh-CN, 装订线:1cm, 文档网格:每页22行, 文档标题:黑体/Times, 一级标题:黑体/Times

纸张:A4, 页边距:上2.54cm, 西文字体:Times, 校对语言:zh-CN, 文档标题:黑体/Times, 一级标题:黑体/Times, 二级标题:黑体/Times, 三级标题:黑体/Times

python-docx, lxml, PyYAML

Gates applied: no_behavioural_pass.