用途:在需要创建、编辑、审阅或检查 .docx 文件时使用,提供可靠工作流,避免在库选择与格式细节上猜测。调用方式为在提示中写出准确技能名 $docx,例如“Use $docx to extract the text from this Word document.”“Use $docx to update this report and keep the headings and tables intact.”“Use $docx to create a new project brief from this outline.”“Use $docx to inspect the raw XML in this file because formatting keeps breaking.”
依赖工具与假设:python-docx 适合多数创建与编辑任务;pandoc 在可用时用于快速提取文本;zipfile、unzip 等归档工具用于直接检查原始 OOXML;docxtpl 在提供 .docx 模板时用于模板驱动生成。工具缺失时先安装,或回退到更简单流程。
推荐工作流:一、读取或提取内容,主要需要文本和标题时优先用 pandoc,需要注释、关系、编号、样式或嵌入资源时改用 ZIP 或 XML 检查,示例命令 pandoc input.docx -t markdown -o output.md。二、新建文档,信件、报告、会议记录和基础表格优先用 python-docx;用户提供带占位符的 Word 模板时优先用 docxtpl;先保持初版简单,再加高级样式或图片。三、编辑既有文档,python-docx 处理文本、标题、表格、列表与基础格式;对复杂版式改动保持保守;文档存在异常编号、分节符或域代码时,先检查 XML 再大范围修改。四、直接检查 OOXML:.docx 是 ZIP 归档,当样式损坏、编号意外重置、分节符消失、图片或关系缺失、需检查注释或元数据时,检查 word/document.xml、word/styles.xml、word/numbering.xml、word/comments.xml、word/_rels/document.xml.rels 等关键文件。
限制:标准 Python 库无法像 Microsoft Word 那样可靠生成原生修订(tracked changes);若用户明确需要真正的修订或评论线程,编辑前应说明。简单最终文本编辑通常 python-docx 足够;要保留审阅标记的保真度,可能仍需人工在 Word 中复核。
常见错误:把 .docx 当纯文本处理而丢失结构;未理解样式或编号模型就做全局 XML 编辑;假设修订会被自动保留;忘记底层段落插入可能需要 XML 样式 ID 而非可读样式名。若段落样式静默回退为 Normal,使用 $python-docx-style-id-mismatch。