DOCX 创建、编辑与分析

解决什么问题

在构建自动化文档处理流水线时，你经常需要程序化地操作 Word 文档。无论是根据数据生成格式统一的报告，批量修改合同模板中的关键信息，还是提取合同中的特定内容，直接处理 .docx 文件都面临一个核心挑战：如何可靠地读写其复杂的内部结构。

技能如何工作

此技能提供了一套基于文件本质的工具集。其核心认知是：.docx 文件本质上是一个 ZIP 压缩包，内部包含多个 XML 文件。技能围绕这个结构展开两个主要方向：

1. 创建新文档
使用 docx JavaScript 库 (npm install -g docx) 来生成全新的文档。其关键步骤与规则包括：

• 页面设置：必须显式指定页面尺寸，使用 DXA 单位（1 英寸 = 1440 DXA）。对于美式文档，使用 US Letter (12240 x 15840) 而非默认的 A4。
• 结构元素：创建段落、列表、表格时，严格遵循最佳实践。例如，列表必须使用 LevelFormat.BULLET 配置，绝不能使用 unicode 符号。表格设置具有特殊要求：必须同时为整个表格设置 columnWidths 并为每个单元格设置 width，两者必须匹配，且始终使用 WidthType.DXA（百分比模式在 Google Docs 等平台会失效）。
• 样式覆盖：可以通过精确的内置样式 ID（如 "Heading1"）来覆盖默认标题样式，并包含 outlineLevel 以用于生成目录。
• 验证：创建后应立即进行验证，若失败则解包修复 XML。

2. 编辑现有文档
遵循严格的三步流程：

1. 解包：将 .docx 解压为格式化的 XML，并处理如智能引号转换（转换为 “ 等实体）和相邻 Run 合并等任务。
2. 编辑 XML：直接编辑 unpacked/word/ 目录下的文件。这是修改的核心。关键操作指南：

修改方法：使用 Edit 工具直接进行字符串替换，不要编写 Python 脚本，以降低复杂性并确保精确替换。
跟踪修改与批注：若添加跟踪修改或批注，新内容中若包含引号，必须使用 XML 实体（如 ’ 代表右单引号）来生成智能引号。添加批注时，需在多个 XML 文件中插入标记。
* 图片添加：需要将图片放入 word/media/，在关系文件 (document.xml.rels) 和内容类型文件 ([Content_Types].xml) 中添加相应条目，最后在文档 XML 中引用。

1. 打包：重新打包为 DOCX。工具会进行自动修复（如修复超限的 durableId、补全空格保留属性），但无法修复格式错误的 XML 或模式违规。

适用场景与重要限制

此技能集非常适合需要 批量处理、程序化生成或精细编辑 Word 文档的场景。它依赖 pandoc 进行文本提取，docx 库创建新文档，并通过解包-编辑-打包流程修改现有文档。处理遗留的 .doc 文件或进行 PDF 转换则依赖 LibreOffice（soffice.py 脚本已处理中文环境编码）。

必须注意的关键点：

• 编辑现有文档时，对文本内容的修改本质上是字符串替换，对于极其复杂的格式或宏，解包后的 XML 可能难以直观维护。
• 编辑工具（如 AI 助手）在跟踪修改中应默认以 “Claude” 作为作者名，除非用户明确指定其他名称。
• 自动修复功能是有限的，打包前的 XML 验证非常重要。
• 对于中文内容，尤其是 GBK 编码的老版 .doc 文件，需确保转换环境（LibreOffice）支持 zh_CN.UTF-8 区域设置。