ariyaaditamaputra18/docx-format

Word 文档格式处理

使用 python-docx 库精确操作 Word 文档格式，适用于格式分析、格式规范化、批量修改。

核心规则

被调用时立即执行：

1. 确认文件路径：询问用户 Word 文档的完整路径
2. 明确需求：确认是分析格式还是修改格式，目标规范是什么
3. 选择模板：根据需求选择合适的代码模板或脚本
4. 生成脚本：创建独立的 Python 脚本文件
5. 执行验证：使用 uv run 执行并检查结果

强制性约束：

• ✓ 必须使用 uv run --with python-docx python3 script.py
• ✓ 必须处理 doc.paragraphs 和 doc.tables（文档正文常在表格内）
• ✓ 必须分设 中英文字体（使用 qn('w:eastAsia')）
• ✓ 必须询问 用户文件路径和输出路径
• ✗ 禁止使用 直接 python 命令（缺少依赖）
• ✗ 禁止遗漏 表格内容处理（常见错误）

何时使用

触发场景：

• 分析 Word 文档格式（字体/字号/缩进/行距）
• 批量修改文档格式
• 统一排版规范（学术论文、报告等）
• 处理中英文混排字体
• 修改交叉引用/参考文献样式

触发关键词：修改 Word 格式、统一字体、调整缩进、分析文档格式、参考文献格式

决策树

用户需求是什么？
├─ 不清楚当前格式 → 使用 scripts/analyze.py
├─ 应用公文标准 → 使用 scripts/format_official.py
├─ 应用学术标准 → 使用 scripts/format_academic.py
├─ 统一正文格式 → 使用【快速模板：批量格式化】
├─ 修改参考文献 → 使用【快速模板：参考文献处理】
└─ 自定义需求 → 基于【基础模板】组合

快速开始

基础模板

from docx import Document
from docx.shared import Pt
from docx.oxml.ns import qn

doc = Document('input.docx')

def set_font(run, cn='宋体', en='Times New Roman', size=10.5):
    """设置中英文字体"""
    run.font.name = en
    run._element.rPr.rFonts.set(qn('w:eastAsia'), cn)
    run.font.size = Pt(size)

def process_all_paragraphs(doc, process_func):
    """遍历所有段落（包括表格内）"""
    for para in doc.paragraphs:
        process_func(para)

    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for para in cell.paragraphs:
                    process_func(para)

# 使用示例
def format_para(para):
    para.paragraph_format.first_line_indent = Pt(21)
    for run in para.runs:
        set_font(run, cn='宋体', en='Times New Roman', size=10.5)

process_all_paragraphs(doc, format_para)
doc.save('output.docx')

快速模板：批量格式化

from docx import Document
from docx.shared import Pt
from docx.oxml.ns import qn

doc = Document('input.docx')

for para in doc.paragraphs:
    if len(para.text.strip()) > 30:
        para.paragraph_format.first_line_indent = Pt(21)
        para.paragraph_format.line_spacing = 1.5
        for run in para.runs:
            run.font.name = 'Times New Roman'
            run._element.rPr.rFonts.set(qn('w:eastAsia'), '宋体')
            run.font.size = Pt(10.5)

for table in doc.tables:
    for row in table.rows:
        for cell in row.cells:
            for para in cell.paragraphs:
                if len(para.text.strip()) > 30:
                    para.paragraph_format.first_line_indent = Pt(21)
                    for run in para.runs:
                        run.font.name = 'Times New Roman'
                        run._element.rPr.rFonts.set(qn('w:eastAsia'), '宋体')
                        run.font.size = Pt(10.5)

doc.save('output.docx')

快速模板：参考文献处理

from docx import Document
from docx.shared import Pt, RGBColor
import re

doc = Document('input.docx')
ref_pattern = re.compile(r'\[\d+\]')

for para in doc.paragraphs:
    if para.text.strip().startswith('[') and ']' in para.text[:5]:
        para.paragraph_format.first_line_indent = Pt(-21)
        para.paragraph_format.left_indent = Pt(21)

    for run in para.runs:
        if ref_pattern.search(run.text):
            run.font.color.rgb = RGBColor(0, 0, 255)

doc.save('output.docx')

执行检查清单

生成脚本前：

• [ ] 已确认用户提供的文件路径
• [ ] 已明确目标格式规范
• [ ] 已选择合适的模板或脚本

脚本中必须包含：

• [ ] 同时处理 doc.paragraphs 和 doc.tables
• [ ] 使用 qn('w:eastAsia') 设置中文字体
• [ ] 正确的输入/输出文件路径

执行前提醒用户：

• [ ] 备份原文件或使用不同的输出文件名
• [ ] 确认文件未被其他程序打开

执行命令：

uv run --with python-docx python3 script.py

常见错误

| 错误 | 原因 | 解决方案 | |------|------|----------| | 修改未生效 | 遗漏表格内容 | 检查是否处理了 doc.tables | | 中文字体不对 | 未用 qn('w:eastAsia') | 必须单独设置中文字体 | | 文件打开失败 | 路径错误或文件被占用 | 检查路径，关闭 Word | | 依赖缺失 | 未用 uv run | 使用完整命令 |

相关文档

• STANDARDS.md - 默认格式标准（公文/学术论文）和参数速查表
• EXAMPLES.md - 详细示例代码（多级标题、表格、图片、页眉页脚等）
• scripts/ - 预置工具脚本（分析、公文格式化、学术格式化）

Markdown 转 DOCX

直接读取 Markdown 文档并按格式要求写入 DOCX，无需 pandoc。

基础模板

from docx import Document
from docx.shared import Pt
from docx.oxml.ns import qn
from docx.enum.text import WD_ALIGN_PARAGRAPH
import re

doc = Document()

def add_heading(doc, text, level):
    """添加标题"""
    para = doc.add_paragraph(text)
    if level == 1:
        para.alignment = WD_ALIGN_PARAGRAPH.CENTER
        for run in para.runs:
            run.font.name = 'Arial'
            run._element.rPr.rFonts.set(qn('w:eastAsia'), '黑体')
            run.font.size = Pt(15)
            run.font.bold = True
    elif level == 2:
        para.alignment = WD_ALIGN_PARAGRAPH.LEFT
        for run in para.runs:
            run.font.name = 'Arial'
            run._element.rPr.rFonts.set(qn('w:eastAsia'), '黑体')
            run.font.size = Pt(14)
            run.font.bold = True
    elif level == 3:
        para.alignment = WD_ALIGN_PARAGRAPH.LEFT
        for run in para.runs:
            run.font.name = 'Arial'
            run._element.rPr.rFonts.set(qn('w:eastAsia'), '黑体')
            run.font.size = Pt(12)
            run.font.bold = True

def add_paragraph(doc, text):
    """添加正文段落"""
    para = doc.add_paragraph(text)
    para.alignment = WD_ALIGN_PARAGRAPH.JUSTIFY
    para.paragraph_format.first_line_indent = Pt(24)
    para.paragraph_format.line_spacing = 1.5
    for run in para.runs:
        run.font.name = 'Times New Roman'
        run._element.rPr.rFonts.set(qn('w:eastAsia'), '宋体')
        run.font.size = Pt(12)

# 读取 Markdown
with open('input.md', 'r', encoding='utf-8') as f:
    for line in f:
        line = line.rstrip()
        if not line:
            continue

        # 标题
        if line.startswith('# '):
            add_heading(doc, line[2:], 1)
        elif line.startswith('## '):
            add_heading(doc, line[3:], 2)
        elif line.startswith('### '):
            add_heading(doc, line[4:], 3)
        # 正文
        else:
            add_paragraph(doc, line)

doc.save('output.docx')

使用预置脚本：

uv run --with python-docx python3 .claude/skills/docx-format/scripts/md_to_docx.py input.md output.docx

注意事项

1. 只支持 .docx：不支持旧版 .doc
2. 表格内容：学术论文、报告等正文常在表格内，必须处理
3. 单位转换：font.size 返回 EMU，需转换（÷ 914400 × 72）
4. 备份原文件：修改前建议备份
5. Markdown 转换：使用 pandoc 转换后再格式化