DOCX Formatter

中文 DOCX 排版工具

本工具用于将文本或 Markdown 内容排版为专业的中文 Word (.docx) 文档。最常见的用法是把 AI 生成的 Markdown 正文（报告、说明、方案、论文、讲义等）按学术与工程规范排版为 .docx，同时借助库函数补充 Markdown 无法表达的构件：数学公式、表格框图、引用上标、封面与目录。核心功能：

1. Markdown 排版（把 Markdown 或纯文本正文按中文文档规范排版为 .docx）
2. 标准排版（黑体标题/宋体正文、标准页边距、行距）
3. OMML 数学公式（原生 Word 公式：行内公式和块级公式，直接生成 OMML XML，无中间库依赖）
4. 表格框图（使用 Word 表格 + Unicode 箭头绘制流程图，不使用 emoji 或图片）
5. 引用上标（正文中的 [1] 等引用标记自动渲染为上标）
6. 轻量验证（纯 stdlib 的 ZIP/XML 完整性检查，生成后默认执行）

本文档只收录编写调用脚本所必需的函数、规则与陷阱；排版数值、文件结构、各构件的完整示例与可选功能细节见仓库根目录 README.md 的「功能矩阵」「核心模块」「排版标准」「文件结构」「安装」「可选模块」各章。

如何开始

本工具为函数库，不含可执行入口：docx_layout_kit.py 无 main() 函数，直接运行不产生任何输出。Agent 生成文档的方式是编写调用脚本，导入库函数后按文档结构依次调用。

Agent 生成文档前，先阅读 scripts/_build_readme_docx.py。 该文件是本工具的标准骨架，从 setup_document() 到 doc.save() 的完整调用顺序（封面 → 目录 → 标题 → 正文 → 图表 → 参考文献 → 保存）均在其中示范；它同时用于生成项目根目录的 README.docx，因而始终与库保持同步。

参考文件：

标准流程：

1. 阅读 scripts/_build_readme_docx.py，理解 import 段与正文的调用顺序

2. 复制 scripts/docx_layout_kit.py 到工作目录；文档含公式时，再复制 scripts/omml_math_kit.py 与 scripts/formula_templates.py

   • 不要复制 scripts/optional/（可选功能专用）

3. 新建调用脚本，按范例顺序写入实际内容

4. 运行脚本生成文档，经 scripts/docx_validator.py 验证后交付

顺序规则（范例文件头有同样提示）：

1. set_preset() 须在 setup_document() 之前调用
2. add_cover_page() 须在所有其它内容之前调用
3. 分节决定页码起点：有目录时 add_toc() 已自动分节；有封面但无目录时须手动调用 start_body(doc)；两者皆无则无需处理

可选功能 — 默认跳过

以下功能默认不执行、不检查环境、不安装依赖。仅当用户明确要求时才启用，详见 README「可选模块」章节：

规则：默认工作流只有「生成 → 轻量验证 → 交付」。遇到可选功能请求时，先参考对应章节确认依赖（pywin32、LibreOffice、defusedxml、git 等均按需安装），再执行。

环境配置

核心排版功能仅需 Python 3.8+ 与 python-docx。数学公式由 omml_math_kit.py 直接生成 OMML XML，纯标准库实现，无需 Node.js、LaTeX 渲染器或 Pandoc。可选功能的依赖见「可选功能 — 默认跳过」一节，默认不安装、不检查。

核心函数（docx_layout_kit.py）

需复制到工作目录的脚本文件：

• scripts/docx_layout_kit.py — 包含所有排版辅助函数的构建库（无 main() 入口，由调用脚本 import 使用）

• scripts/omml_math_kit.py — OMML 数学构建器（仅文档含公式时需要）

• scripts/formula_templates.py — 公式定义示例（仅文档含公式时需要）

调用方式见 scripts/_build_readme_docx.py —— 那份范例展示了下面这些函数在真实文档中的完整串联顺序。不要直接运行 docx_layout_kit.py（它没有入口），也不要试图修改它来放入内容；内容应写在你自己的调用脚本里。

各构件（表格框图、流程图、横向箭头行、分层架构图、图表编号）的完整示例见 README「核心模块」章。

文档结构与函数映射

关键规则

1. （1）/（2）/（3）分点：label 部分加粗（含冒号），正文部分正常，使用 add_item_para，首行缩进2字符
2. a. / b. / c. 子步骤：同上格式，label 加粗（含冒号），使用 add_item_para
3. 步骤1：/ 步骤2：：作为二级标题处理，使用 add_h2，黑体小四加粗左对齐
4. （一）/（二）：作为二级标题处理，使用 add_h2
5. 3.1 / 3.2：作为二级标题处理，使用 add_h2
6. 正文中的 **bold**：add_body 自动解析加粗标记
7. 正文中的 [n] 引用：add_body 自动渲染为上标
8. Word 目录（TOC）支持：add_h1/add_h2/add_h3 使用 Word 内置 Heading 样式。使用 add_toc 按需插入目录域（TOC field），Word 打开文档时提示更新域，选择"是"即生成目录条目。add_title 不使用 Heading 样式，不进入目录
9. 标题字符格式写在样式上，不在 run 上：H1–H3 的字体、字号、加粗、黑色全部由 _setup_heading_styles()（setup_document() 内自动调用）写到 Word 内置 Heading 1/2/3 样式上，标题 run 不带任何直接字符格式。这样既覆盖了模板默认的蓝色标题（清除 color 的 themeColor 引用）与主题字体引用，又让 Word 更新目录域时无法把标题字体搬进条目，目录条目因此严格按 TOC 样式呈现。add_h1/add_h2/add_h3/add_bibliography 都遵循此约定，不要在调用脚本里给标题 run 直接设字体
10. 图表自动编号：add_fig_caption 和 add_table_caption 自动递增编号（图N / 表N），无需手动填写编号。传空字符串 "" 给 add_fig_caption 可生成纯间距段落（不编号）。图标题在图下方，表标题在表上方
11. 表下间距由构件自动处理：add_data_table 末尾自动追加一个间距段（默认 12pt，取预设 table.gap_after），无需手工补空行。原因是 Word 的间距只属于段落，表格自身没有段后属性——表名在表前、其段后 6pt 垫在表名与表之间，而表后若无段落则正文直接贴合表底。该行为恒定生效，后续无论是正文还是图标题都一样追加；若后续是图标题，其段前 6pt 与间距段取较大者，不会叠加
12. 页码从正文开始：封面与目录不显示页码，正文第一页为 1。含目录时由 add_toc() 自动分节；有封面但无目录时需手动调用 start_body(doc)；无封面无目录的单节文档无需任何处理
13. 封面独立成节：add_cover_page 必须以「下一页」分节符结束封面节，因此它必须在写任何其它内容之前调用，且用了它就不必再调 add_title。分节链上 add_toc() 与 start_body() 会自动识别并复用分节符留下的空节，不会产生空白页

排版预设（PRESETS / set_preset）

排版参数集中在 docx_layout_kit.py 顶部的 PRESETS 字典中（嵌套分组），不在各 add_* 函数内散落硬编码。

切换方式：set_preset('name') 整套切换，add_* 函数读取当前激活预设。默认激活 default，无需显式调用。须在 setup_document() 之前调用：页面边距与 Normal 默认字体在 setup_document() 时读取预设。

中西文分离：将预设 west.separate 设为 True 后，西文字符使用 west.body / west.head 指定的字体（如 Times New Roman），中文保持各元素字体不变。

不覆盖（按约定保持函数内硬编码，避免过度抽象）：代码块、数据表、框图、箭头、公式段。

新增预设：向 PRESETS 添加一份同键结构的嵌套字典即可，例如紧凑版或西文版。

排版数值、预设分组结构与页面设置见 README「排版标准」章与「排版预设」一节。

封面（add_cover_page）— 按需生成

封面默认不生成。仅在文档需要封面时调用 add_cover_page()。

版式

居中标题块，用顶部留白定位（不是垂直居中）：标题块距版心顶端一段按比例算出的距离，下方留白自然延伸。默认比例 0.264，A4 下留白 6.50cm，大标题段起点距页顶约 9.04cm（页面高度 30.4%）。

subtitle / org / date 均可省略，省略则该行不生成；title 必填。

用法

doc = setup_document()

add_cover_page(doc, "文档标题",
               subtitle="技术方案",
               org="某某科技有限公司",
               date="2026年9月")

add_toc(doc)                     # 目录；add_toc 末尾自动分节，页码从正文起算
add_h1(doc, "一、概述")

# 有封面但不生成目录：封面之后手动分节
add_cover_page(doc, "文档标题", subtitle="技术方案")
start_body(doc)
add_h1(doc, "一、概述")

注意事项

• 必须在写任何其它内容之前调用：它以「下一页」分节符结束封面节，之后的内容自然落到新的一页
• 用了封面就不必再调 add_title（add_title 用于不放封面时置于正文首行的文档主标题）
• 封面节不显示页码；其后的目录节同样不显示，正文从 1 起（见「页码」一节）
• 留白比例上限为 0.5：超过半个版心会把标题块挤到第二页
• 留白由空段落构成。Word 与 WPS 正常渲染；若交付链路中经过会剥离空段落的 docx→HTML 转换器，留白可能丢失

目录（TOC）— 按需生成

目录默认不生成。仅在文档需要目录时调用 add_toc()。

格式规范

缩进以「汉字符」为单位写入：w:ind 同时给出 w:leftChars（100 = 1 个汉字符）与 w:left（twips 兜底，1 个汉字符宽 = 字号 × 20，小四 12pt → 240 twips）。

用法

doc = setup_document()
add_title(doc, "文档标题")
add_toc(doc)                      # 默认收 1-3 级：Word 打开时提示更新域，选"是"生成条目
# add_toc(doc, levels='1-2')      # 只收 H1 + H2
# add_toc(doc, auto_update=False)  # 改为完全手动：仅右键"更新域"时生成条目
add_h1(doc, "一、概述")
add_body(doc, "正文内容...")

注意事项

• Word 打开文档时提示"是否更新此文档中的域"：选择"是"生成目录条目；选择"否"则保留占位文字，可随时在目录上右键 → "更新域"手动生成

• 更新前显示占位文字"（请在 Word 中右键此处选择"更新域"以生成目录）"

• 打开时更新由 auto_update 参数控制（默认开启），设为 False 后目录仅能手动更新

• add_title 不使用 Heading 样式，文档主标题不会出现在目录中

• 目录末尾是分节符（下一页），与正文分隔并触发正文页码重新起算；不要再另加分页符

• 条目字体由标题样式的写法决定：Word 更新目录域时，会把标题 run 上的字体（run 级直接格式）写进目录条目，其优先级高于 TOC 样式。本 skill 的标题一律不在 run 上设字体，H1–H3 的字体/字号/加粗/颜色全部写在 Heading 1/2/3 样式上（见 _setup_heading_styles()），标题 run 不带任何字符格式，因此 Word 无从覆盖，条目按 TOC 样式呈现：章标题行为黑体、一级/二级节标题行为宋体，无需在 Word 中手工调整

• 不要在调用脚本里给标题 run 设字体：若改用 set_run_font 等方式给标题文字直接设字体，Word 更新域时会把该字体搬进条目，覆盖 TOC 样式对宋体的声明——这正是本 skill 把标题字符格式放在样式层的原因

页码 — 从正文开始编号

封面页与目录页不显示页码，页码从正文第一页起算为 1。该行为由 start_body(doc) 实现，它把此前内容划为前置节、正文另起一节，并重置页码计数。

何时需要调用

封面由 add_cover_page() 生成，它自己就把封面结束成一个独立节；有目录时 add_toc() 接在封面之后，形成「封面节 → 目录节 → 正文节」三节结构（封面、目录两节均不显示页码）。

用法

# 场景一：封面 + 目录（add_cover_page 结束封面节，add_toc 末尾自动分节）
doc = setup_document()
add_cover_page(doc, "文档标题", subtitle="技术方案")
add_toc(doc)
add_h1(doc, "一、概述")          # 正文从这里开始，页码为 1

# 场景二：封面 + 正文，不生成目录（需手动分节）
doc = setup_document()
add_cover_page(doc, "文档标题", subtitle="技术方案")
start_body(doc)                  # 封面节到此结束，正文另起一页
add_h1(doc, "一、概述")          # 页码为 1

# 场景三：不放封面，用主标题开篇 + 目录
doc = setup_document()
add_title(doc, "文档标题")
add_toc(doc)
add_h1(doc, "一、概述")          # 页码为 1

引用上标

正文中的参考文献引用标记自动渲染为上标。适用于 add_body() 和 add_item_para() 函数。

支持的引用格式

参考文献表（add_bibliography）

生成 GB/T 7714-2015 顺序编码制参考文献表，格式对齐 NJUThesis LaTeX 模板。正文引用上标 [n] 与条目序号一一对应：add_body 中的 [1] 指向 entries[0]，以此类推。

排版：

用法：

add_bibliography(doc, [
    "张三, 李四. 示例期刊论文题名[J]. 示例期刊, 2020, 12(3): 45-56",
    "王五. 示例图书题名[M]. 示例市: 示例出版社, 2019",
    "赵六. 示例学位论文题名[D]. 示例市: 示例大学, 2021",
])

规则：

1. 条目序号自动生成，正文 [n] 引用与条目顺序必须一致
2. 多作者用逗号分隔，三位以上作者取前三名加 "等" 或 "et al"
3. 中英文作者混排时保持原语言，不强制转换
4. 标题默认为"参考文献"，可通过 title 参数自定义

OMML 数学公式指南

数学公式由 omml_math_kit.py 直接构建 OMML（Office Math Markup Language）XML，经 docx_layout_kit.py 的 add_eq_para() / add_body_with_math() 插入文档。生成的是 Word 原生可编辑公式，与手动插入的公式完全一致。

基本元素

from omml_math_kit import r, sub, sup, frac, sumOp, func, paren, bracket, math, inlineMath

# 纯数学文本
r("f(t)")

# 下标：a_k
sub("a", "k")

# 上标：x²
sup("x", "2")

# 分式：a/b
frac([r("a")], [r("b")])

# 求和：Σ_k（不要空上标！）
sumOp([r("k")], [sub("a", "k")])  # 返回列表，自动展平

# 函数：cos(kωt)
func("cos", [r("k"), r("ωt")])

# 圆括号：(a+b)
paren([r("a+b")])

# 方括号：[a+b]
bracket([r("a+b")])

# 块级公式（居中，独立行）— 传给 add_eq_para()
math([r("f(t) = "), sub("a", "0"), r(" + "), sumOp([r("k")], [sub("a", "k"), func("cos", [r("k"), r("ωt")])])])

# 行内公式（与文本混排）— 传给 add_body_with_math()
inlineMath([sub("a", "k")])

插入公式

块级公式（居中独立行）：

from docx_layout_kit import add_eq_para
from omml_math_kit import r, sub, frac, sumOp, func, math

eq = math([
    r("f(t) = "),
    frac([sub("a", "0")], [r("2")]),
    r(" + "),
    sumOp([r("k")], [sub("a", "k"), func("cos", [r("k"), r("ωt")])]),
])
add_eq_para(doc, eq)

行内公式（与正文混排）：

from docx_layout_kit import add_body_with_math
from omml_math_kit import sub, inlineMath

add_body_with_math(doc, [
    ("text", "其中，"),
    ("math", inlineMath([sub("a", "k")])),
    ("text", "为傅里叶系数，其数值由欧拉公式确定。"),
])

预定义公式（formula_templates.py）

formula_templates.py 提供 eq1~eq4 常用公式模板，可直接使用或作为新增公式的参考模式：

from formula_templates import eq1, eq2, eq3, eq4
add_eq_para(doc, eq2)

关键：求和符号

问题：n 元运算符（m:nary）使用空上标会在 Word 中渲染一个不可见的上标框，导致文件看起来损坏或显示异常。

解决方案：sumOp() 已用下标结构（m:sSub）配合 Unicode ∑（U+2211）实现，无空上标问题。始终使用 sumOp()，切勿手写 m:nary 加空上标。

关键：列表展平

sumOp() 返回列表 [sumSymbol, *body]。所有接收 children 的函数（math()、frac()、func()、paren()、bracket()、inlineMath()）内部已调用 _flat() 自动展平嵌套列表。

关键：XML 转义

r() 自动对文本进行 XML 转义（&、<、>），公式中可安全使用这些字符。

常见陷阱

1. 禁止使用 emoji — 文档中仅使用 Unicode 符号
2. 文件锁定：如果 Word 已打开文件，保存会静默失败 — 使用不同文件名
3. 禁止手写 m:nary 空上标：始终使用 omml_math_kit.py 中的 sumOp() — 它使用 m:sSub 配合 Unicode ∑，避免空上标渲染问题
4. 始终展平列表：所有数学辅助函数使用 _flat() — 新增函数时需对所有 children 参数应用 _flat()
5. 字体东亚设置：python-docx 中必须设置 rFonts.set(qn('w:eastAsia'), font_name) 才能正确渲染中文字体
6. 表格列宽：所有表格（框图 / 数据表 / 箭头行）一律经内部 _new_table() 建立——它把 w:tblW（dxa 总宽）、w:tblGrid/gridCol、每个 w:tcW 从同一份列宽一次写入并把布局锁为 fixed，宽度只有一个来源；默认总宽取常量 TABLE_WIDTH_CM（14cm）。不要绕开它用 doc.add_table() 自建表格，否则宽度会出现第二个口径，字多的那格被 Word autofit 撑宽，同一张图上下框体就会不等宽
7. 表格底纹：使用 WD_FILL_PATTERN.CLEAR 类型底纹而非其他填充模式，否则部分 Word 版本渲染异常
8. 列表符号：使用 Word 内置编号样式，切勿在文本中直接写 • 字符
9. 脚本级变量：_fig_counter / _tbl_counter 在 setup_document() 中自动重置。单进程多次生成文档时，只要重新调用 setup_document() 即可从 图1/表1 开始

文档验证（docx_validator.py）

docx_validator.py 是纯 Python 标准库实现的轻量验证脚本，无外部依赖。用于在生成 .docx 后快速检查文档结构完整性。

验证项

安全处理规范

处理来自不可信来源的 .docx 文件时，必须遵循以下安全规范：

from docx_layout_kit import safe_extract, rezip
import zipfile

# 安全解压现有 .docx
with zipfile.ZipFile("input.docx", "r") as zf:
    safe_extract(zf, "./unpacked")

# 编辑 XML 后重新打包
rezip("./unpacked", "output.docx")

编辑现有文档工作流

解压（safe_extract）→ 合并碎片 run（可选）→ 编辑 XML → 重新打包（rezip）→ 验证（docx_validator）

注意：编辑 XML 时保持原始格式，不要 pretty-print。xml.etree.ElementTree 的 tostring() 默认不保留原始缩进。

文件验证清单

交付 .docx 文件前：

• docx_validator.py 全部 5 项检查通过
• 文件大小 > 10KB（空文档约 3KB）
• 内容中无 emoji 字符
• 所有数学符号渲染为 OMML（非纯文本）
• 图表使用表格框模式（非图片）
• 表格有边框和标题底纹（D9D9D9，灰色）
• 所有公式使用 math() / inlineMath()，非原始文本加下标字符
• 标题颜色为黑色（非 Word 默认蓝色），且字符格式写在 Heading 样式中、标题 run 不带直接字符格式（否则更新目录域后条目字体会跟随标题）
• 图表编号从 图1/表1 开始（setup_document() 自动重置）
• 含封面时：封面节与目录节均不显示页码，正文首页为 1，且封面与目录之间无空白页