Word 文档处理 Skill

使用 python-docx 库创建、编辑、格式化 Word 文档（.docx）。提供完整的文档操作能力：
从零创建文档、编辑已有文档、调整格式样式、高级排版、模板填充。

何时使用

• 用户要求创建 Word 文档（报告、方案、合同、信件、备忘录等）
• 用户要求编辑已有 .docx 文件（修改内容、查找替换、插入删除）
• 用户要求调整文档格式（字体、字号、颜色、对齐、行距、页边距等）
• 用户要求高级排版（页眉页脚、页码、目录、分节、多栏）
• 用户要求基于模板生成文档或批量填充数据

工作流程

1. 理解用户需求

从用户的自然语言描述中识别操作类型：
- 创建：用户描述了一个新文档的内容和结构
- 编辑：用户提到了已有文件需要修改
- 格式化：用户要求调整字体、样式、排版等
- 模板：用户提到模板或需要批量生成

2. 使用工具库

核心工具库在 scripts/docx_utils.py。在 Python 脚本中导入使用：

import sys
sys.path.insert(0, '<skill-path>/scripts')
from docx_utils import *

不要从头编写 python-docx 代码——优先使用工具库中已有的函数。工具库覆盖了
常见的文档操作场景，函数签名清晰、参数有默认值，能大幅减少出错概率。

如果工具库中的函数无法满足需求，可以参考 references/ 目录下的详细文档，
使用原始 python-docx API 实现自定义逻辑。

3. 执行操作

编写 Python 脚本调用工具库完成用户需求，保存 .docx 文件。

典型模式：

from docx_utils import create_document, add_heading, add_paragraph, add_table, save_document

doc = create_document()
add_heading(doc, "项目周报", level=0)
add_paragraph(doc, "本周工作进展顺利...")
add_table(doc, [["任务", "状态", "负责人"], ["需求分析", "已完成", "张三"]])
save_document(doc, "/path/to/output.docx")

4. 视觉验证（可选）

如果需要检查文档效果，使用渲染脚本将 .docx 转为 PNG 图片：

python3 <skill-path>/scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_preview

需要 LibreOffice 和 Poppler。如果未安装，跳过此步骤，用文本提取验证内容即可。

工具库 API 速览

完整 API 文档在 scripts/docx_utils.py 的函数文档字符串中。以下是快速参考：

文档创建

文档编辑

格式与样式

高级排版

模板功能

详细用法和参数说明请查看 scripts/docx_utils.py 中的函数文档字符串。
高级排版和格式化的更多细节请参考 references/formatting_guide.md 和 references/advanced_layout.md。

常见场景示例

场景 1：创建项目周报

from docx_utils import *

doc = create_document()
add_heading(doc, "项目周报", level=0)
add_heading(doc, "一、项目概述", level=1)
add_paragraph(doc, "本周项目进展顺利，完成了核心模块开发。")
add_heading(doc, "二、本周任务", level=1)
add_table(doc, [
    ["任务名称", "状态", "负责人", "完成日期"],
    ["需求分析", "已完成", "张三", "2025-01-10"],
    ["架构设计", "进行中", "李四", "—"],
])
add_heading(doc, "三、下周计划", level=1)
add_bullet_list(doc, ["完成架构设计文档", "启动前端开发", "组织代码评审"])
save_document(doc, "weekly_report.docx")

场景 2：编辑已有文档

from docx_utils import *

doc = open_document("report.docx")
find_and_replace(doc, "2024年", "2025年")
find_and_replace(doc, "旧项目名", "新项目名")

# 在特定段落后插入新内容
paras = find_paragraphs_by_text(doc, "结论")
if paras:
    insert_paragraph_after(paras[0], "新增的补充说明段落。")

save_document(doc, "report_updated.docx")

场景 3：格式调整

from docx_utils import *

doc = open_document("document.docx")
set_margins(doc, top=2.5, bottom=2.5, left=3.0, right=3.0)

# 修改标题样式
for p in doc.paragraphs:
    if p.style.name.startswith('Heading'):
        for run in p.runs:
            set_run_font(run, name='微软雅黑', size=18, bold=True, color='1F4E79')

# 修改正文样式
for p in doc.paragraphs:
    if p.style.name == 'Normal':
        for run in p.runs:
            set_run_font(run, name='宋体', size=12)
        set_paragraph_format(p, line_spacing=1.5, first_line_indent=0.74)

save_document(doc, "document_formatted.docx")

场景 4：模板填充

from docx_utils import *

# 单个文档填充
doc = load_template("contract_template.docx")
fill_placeholder(doc, "{{甲方}}", "ABC科技有限公司")
fill_placeholder(doc, "{{乙方}}", "XYZ咨询服务部")
fill_placeholder(doc, "{{金额}}", "人民币壹拾万元整")
fill_placeholder(doc, "{{日期}}", "2025年1月15日")
save_document(doc, "contract_abc.docx")

# 批量生成
contracts = [
    {"{{甲方}}": "ABC公司", "{{金额}}": "10万元"},
    {"{{甲方}}": "XYZ集团", "{{金额}}": "25万元"},
    {"{{甲方}}": "DEF科技", "{{金额}}": "50万元"},
]
for i, data in enumerate(contracts):
    fill_template("contract_template.docx", data, f"contract_{i+1}.docx")

注意事项

• 文件路径：始终使用绝对路径，避免相对路径导致的找不到文件问题
• 中文字体：设置中文字体时需同时设置 name（西文字体）和 east_asia（中文字体），工具库已处理此问题
• 颜色格式：颜色参数接受十六进制字符串（如 'FF0000'）或 RGB 元组（如 (255, 0, 0)）
• 单位：页边距和页面大小使用厘米（cm），字号使用磅（pt）
• 保存：修改后必须调用 save_document() 才会写入文件
• 编码：所有文本操作均使用 UTF-8 编码，中文无乱码问题