---
name: "docx"
description: "Word 文档工程完整指南"
---

# Word 文档工程完整指南

## 适用场景
当需要基于 Markdown、数据报表或模板自动化生成专业排版、符合出版与企业级视觉标准的 Microsoft Word (`.docx`) 文档时，指导 AI 处理样式继承、标题层级、自动化表格、页眉页脚与 XML 底层修复。

## 功能说明
> 告别简陋的默认样式排版，将原始结构化数据和文本转换为符合企业 VI 标准、拥有清晰网格系统、专业配色、动态交叉引用和自动化目录的工程级 Word 文档。

## 这个案例能帮你做什么
- 将 Markdown 或纯文本一键转换为包含专业标题样式、段落缩进、首字下沉或引用块的高保真 Word 文档。
- 自动构建工业级表格：设置斑马纹、表头置顶重复（跨页表头）、列宽自动吸附与单元格对齐。
- 处理页眉页脚动态字段（页码、总页数、章节标题动态引用）与分节符（横纵页面混排）。
- 解决常见痛点：公式排版错乱、图片溢出边界、样式冲突以及底层 `word/document.xml` 损坏修复。

## 你需要的 Skills（按类型）

| 类型 | Skill / 工具 | 用途 | 来源 |
|---|---|---|---|
| 核心工具 | `python-docx` / `pandoc` | 文档 AST 解析与底层 OpenXML 构建 | Python Package / CLI |
| 内置 | `filesystem` | 读取源文本与生成目标 `.docx` | Built-in |
| 可选脚本 | `ooxml-patcher` | 修复损坏的 XML 命名空间与样式表 | Python Script |

## 快速体验版（先跑一轮）

```text
你是我的 Word 文档工程专家。
请将我提供的以下内容排版为一份标准商业研究报告（.docx）：
1. 建立清晰的 4 级标题系统（使用深蓝企业配色方案：主色 #1F4E79，辅色 #2E75B6）。
2. 正文采用宋体/Calibri（11pt，1.25倍行距，段后 4pt）。
3. 表格采用简洁商务风（浅灰边框 #D9D9D9，表头深蓝底白字，数据右对齐，文本左对齐）。
4. 第一页为独立封面（无页眉页脚），第二页起插入动态页码（第 X 页 共 Y 页）。
```

## 稳定自动版（可长期运行）

### 1) 自动化 Python 生成脚本 (`build_docx.py`)

```python
import docx
from docx.shared import Inches, Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.table import WD_TABLE_ALIGNMENT
from docx.oxml import OxmlElement, parse_xml
from docx.oxml.ns import nsdecls, qn

def create_styled_document(title, subtitle, sections, output_path):
    doc = docx.Document()
    
    # 页面基础设置 (A4，页边距 2.54cm)
    for section in doc.sections:
        section.top_margin = Inches(1.0)
        section.bottom_margin = Inches(1.0)
        section.left_margin = Inches(1.0)
        section.right_margin = Inches(1.0)
        section.different_first_page_header_footer = True
        
    # 配色常量
    COLOR_PRIMARY = RGBColor(0x1F, 0x4E, 0x79)    # 深海蓝
    COLOR_SECONDARY = RGBColor(0x2E, 0x75, 0xB6)  # 商务蓝
    COLOR_TEXT = RGBColor(0x26, 0x26, 0x26)       # 正文黑
    
    # 封面标题
    p_title = doc.add_paragraph()
    p_title.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run_title = p_title.add_run(title)
    run_title.font.size = Pt(28)
    run_title.font.bold = True
    run_title.font.color.rgb = COLOR_PRIMARY
    p_title.paragraph_format.space_before = Pt(120)
    p_title.paragraph_format.space_after = Pt(18)
    
    # 副标题
    p_sub = doc.add_paragraph()
    p_sub.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run_sub = p_sub.add_run(subtitle)
    run_sub.font.size = Pt(14)
    run_sub.font.color.rgb = COLOR_SECONDARY
    p_sub.paragraph_format.space_after = Pt(200)
    
    # 分页进入正文
    doc.add_page_break()
    
    # 写入正文各章节
    for heading, text, table_data in sections:
        h = doc.add_heading(heading, level=1)
        h.style.font.color.rgb = COLOR_PRIMARY
        h.paragraph_format.space_before = Pt(16)
        h.paragraph_format.space_after = Pt(6)
        
        p = doc.add_paragraph(text)
        p.paragraph_format.line_spacing = 1.25
        p.paragraph_format.space_after = Pt(8)
        
        if table_data:
            table = doc.add_table(rows=len(table_data), cols=len(table_data[0]))
            table.alignment = WD_TABLE_ALIGNMENT.CENTER
            for r_idx, row in enumerate(table_data):
                for c_idx, val in enumerate(row):
                    cell = table.cell(r_idx, c_idx)
                    cell.text = str(val)
                    if r_idx == 0:
                        shading = parse_xml(f'<w:shd {nsdecls("w")} w:fill="1F4E79"/>')
                        cell._tc.get_or_add_tcPr().append(shading)
                        for r in cell.paragraphs[0].runs:
                            r.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)
                            r.font.bold = True
    doc.save(output_path)

if __name__ == '__main__':
    demo_sections = [
        ("1. 项目背景与执行摘要", "本项目旨在通过体系化工作流加速多模型智能体协同研发。", None),
        ("2. 核心指标评估表", "以下为系统基准测试与吞吐量量化对比：", [
            ["模块", "吞吐量 (QPS)", "P99 延迟 (ms)", "可用性指标"],
            ["API 网关", "12,500", "42ms", "99.99%"],
            ["任务调度", "4,200", "88ms", "99.95%"],
            ["审计归档", "8,900", "35ms", "99.99%"]
        ])
    ]
    create_styled_document("企业级智能体系统设计方案", "系统架构、核心链路与性能基准评估", demo_sections, "output.docx")
```

### 2) Pandoc 企业级参考模板配置

使用自定义 `reference.docx` 固化团队样式规范：
```bash
# 提取默认模板样式库
pandoc --print-default-data-file reference.docx > custom_reference.docx

# 在 Word 中修改 custom_reference.docx 的样式库（Heading 1-4, Table, Block Quote）
# 之后利用其一键导出统一规格的 Word
pandoc input.md --reference-doc=custom_reference.docx -o formal_report.docx
```

## 风险与边界
- 避免直接拼接底层 XML 字符串，容易造成 Word 打开报错“发现无法读取的内容”。
- 超过 50 页的大型长文档，建议按章节拆分子文档编写，最后使用主控文档（Master Document）或统一脚本合并。
- 矢量图建议转换为 300+ DPI 高清 PNG 或保持 EMF/WMF 格式，防止 Word 压缩变模糊。

## 使用建议
- 建立固定的全局色卡（Primary, Secondary, Accent, Muted），全局正文字号与行间距不得在局部覆盖。
- 代码块推荐配置带圆角灰色底色 `#F5F5F5` 的单单元格无边框表格，避免换行撕裂。

## 成功标准
- 输出文档在 Microsoft Word、WPS 与 LibreOffice 中均无排版错乱。
- 目录与页码可一键（F9）无缝更新。
- 复杂跨页表格均带有重复表头行。

## 源文件
来源：awesome-openclaw-zh  
原始文件：docx.md