document-docx

DOCX 文档技能——快速参考

此技能涵盖专业 .docx 工作流程：docxtpl 模板流水线、python-docx 结构编辑与内容提取、LLM/RAG 数据摄取，以及无障碍/EAA 合规。

**适用范围：**如果官方 Anthropic docx 技能可用，纯粹的创建/编辑（docx-js）、通过 <w:ins>/<w:del> 和 validate.py 编写修订（红线），以及编写批注时，优先使用该技能。如果用户只要求“创建一份文档”而未指定格式，且有文档连接器或制品类型可用，优先使用它，而不是生成 .docx。

核心决策规则

• 非开发人员在 Word 中负责版式，代码提供数据：使用 docxtpl。由代码决定结构：使用 python-docx（Python）或 docx（Node）。
• 模板渲染应在失败时终止。docxtpl 默认会将缺失变量渲染为空白，并且不会转义 &/<，因此文件可以正常打开，也能通过标签扫描。使用 scripts/docx_render_template.py（StrictUndefined + autoescape）；参见 references/template-workflows.md。
• 修订：切勿承诺高级库支持，也不要用颜色或删除线伪造修订。将编写工作交由官方 docx 技能的 OOXML 工作流处理。参见 references/tracked-changes.md。
• 从可信文件生成语义 HTML：使用 mammoth，然后进行清理（它不会执行清理）。用于 RAG 的 Markdown/JSON：使用 Markdown 转换器或 scripts/docx_extract.py；参见 references/llm-extraction-workflows.md。
• 将 DOCX 输入知识库或索引：内容控件内的表格不会显示在 Document.tables 中，粘贴为图像的表格没有文本，修订需要明确的接受/原文策略，文件名也可能有误。在索引任何文件前，运行 references/docx-extraction-failure-modes.md 中的表格计数检测检查（DOCX 作为摄取输入时，务必加载此文件）。
• PDF 输出：为获得最高保真度，使用 Word 自动化；CI 和批处理使用 LibreOffice 无头模式。
• .doc：先转换为 .docx。.docm/.dotm：将宏视为不可信内容，绝不执行。
• .docx 是可编辑源文件；PDF 是发布制品。

快速参考

任务	工具	适用场景
填充模板、邮件合并	docxtpl + scripts/docx_render_template.py	由 Word 编写的模板、批量文档
使用 Python 进行结构编辑	python-docx（references/docx-patterns.md）	样式、表格、分节、字段、超链接
批注	python-docx add_comment（受版本限制）或官方 docx 技能	添加审阅备注，不涉及修订
DOCX 转 HTML	通过 scripts/docx_to_html.mjs 使用 mammoth	可信文档、语义 HTML
DOCX 转 JSON/Markdown	scripts/docx_extract.py、Markdown 转换器	自动化、RAG 数据摄取
检查修订/批注	scripts/docx_inspect_ooxml.py	编辑任何已审阅文档前
发布门禁	scripts/docx_quality_gate.py	每个生成或编辑的文件
DOCX 转 PDF	Word 自动化 / LibreOffice 无头模式	发布制品、CI 冒烟测试

格式与安全注意事项

• python-docx 批注：仅限正文，不支持在页眉或页脚中添加锚点，不支持串联回复或已解决状态，且锚点必须是完整运行。
• python-docx 不支持编写修订、设置替代文本属性、字段 API 或公开的超链接编写 API。参考资料中的变通方法使用了私有属性；升级后请重新验证。
• 在 Word 中更新或通过 LibreOffice 渲染之前，目录和其他 Word 字段会保持为空或过时。
• 新建的 python-docx 文档可能会继承默认模板中的作者、日期和批注。分发前请检查核心属性。

承诺功能前先检查版本

不要假定环境中安装的是最新库：

• Document.add_comment() 是 python-docx 最近新增的方法，在较旧的固定版本中会引发 AttributeError。承诺支持批注前，请检查 hasattr(docx.document.Document, "add_comment")。
• 如果用户要求的功能在此处标记为不支持（在 python-docx 中创建修订、线程式回复、已解决的批注），请明确说明，并引导其使用官方 docx 技能。不要用格式设置来模拟这些功能。

默认工作流

1. 确认文件类型和信任级别：.docx/.dotx、.docm/.dotm 或旧版 .doc。
2. 如果文档可能包含审阅元数据，请先运行 scripts/docx_inspect_ooxml.py --json。
3. 生成或修改文档：通过 docx_render_template.py 使用 docxtpl，或通过 python-docx/docx 处理结构。
4. 对于新生成的输出文件，将 doc.core_properties 设置为预期作者，清除模板批注，并将 created/modified 设置为 datetime.now(timezone.utc).replace(tzinfo=None)（python-docx 要求使用无时区的 UTC 时间）。对于现有文件的修改，除非用户要求重置元数据，否则应保留其来源信息。
5. 运行 scripts/docx_quality_gate.py。出现任何问题时，该脚本都会以状态码 2 退出，包括无法运行用户要求的 --check-libreoffice 检查。
6. 将文件渲染为图像，并在交付前查看每一页：运行 soffice --headless --convert-to pdf out.docx && pdftoppm -png -r 80 out.pdf page，然后打开 page-*.png 文件。对外分发时，还应在 Word 中检查，并应用无障碍检查清单。

python3 scripts/docx_render_template.py template.docx context.json out.docx   # exit 2 on missing vars
python3 scripts/docx_quality_gate.py out.docx --json                          # exit 2 on any issue
python3 scripts/docx_extract.py in.docx --include headers footers comments --out extracted.json
node scripts/docx_to_html.mjs in.docx out.html --style-map map.txt --extract-images-dir assets/

往返验证

• 在最终保存前，记录分节、表格、图像、超链接、批注和修订的预期数量。
• 重新打开保存后的 DOCX，并比较数量。
• 渲染副本，检查分页、编号、表格溢出、缺失字体和未解析标签。

OOXML 解析或文本提取成功，并不能证明版式保真。PDF 视觉效果正确，也不能证明批注、超链接、域或无障碍元数据在可编辑 DOCX 中得以保留。记录主要审阅使用的查看器，以及已检查的辅助查看器。

导航

资源

• references/docx-patterns.md - python-docx 的注意事项：样式、表格、分节、字段、超链接、损坏风险
• references/template-workflows.md - docxtpl 标签放置、失败即关闭式渲染、批处理规则
• references/review-comments-workflows.md - 批注、审阅备注、程序化修订路由、批注限制
• references/tracked-changes.md - 修订跟踪的可行与不可行之处
• references/llm-extraction-workflows.md - Mammoth、MarkItDown、Docling、HTML/Markdown/JSON 提取；包括按任务列出的 Extraction Stack 工具候选项（原生解析、结构化转换器、OCR）
• references/docx-extraction-failure-modes.md - 知识库/RAG 导入时的静默丢失模式（内容控件表格、图片表格、修订、误导性文件名）及表格计数检测检查
• references/accessibility-compliance.md - Word 无障碍访问、EN 301 549 背景、手动检查
• references/cross-platform-compatibility.md - Word、Google Docs、LibreOffice、PDF 转换
• references/document-automation-pipelines.md - CI/CD、批量生成、质量门禁
• data/sources.json - 外部文档链接

脚本

• scripts/docx_inspect_ooxml.py - 无需依赖项的 OOXML 检查，用于查看修订和批注
• scripts/docx_extract.py - 将文本、表格、元数据以及可选的页眉/页脚/超链接/批注/图片提取为 JSON
• scripts/docx_render_template.py - 使用 JSON 渲染 docxtpl 模板，缺少变量时失败（草稿可使用 --allow-missing）
• scripts/docx_to_html.mjs - 使用样式映射将可信的 .docx 转换为 HTML，并可选择提取图片
• scripts/docx_quality_gate.py - 验证可解析性、未解析的模板标签、修订/批注信号，以及可选的 LibreOffice 转换；存在任何问题时以状态码 2 退出

模板

• assets/docx-template-authoring-checklist.md - 模板编写与交接检查清单

相关技能

• ../document-pdf/SKILL.md - PDF 生成与发布工作流
• ../document-xlsx/SKILL.md - 电子表格生成与导出
• ../document-pptx/SKILL.md - 演示文稿生成
• ../docs-codebase/SKILL.md - 技术写作模式

经验循环

当先前的决策或陷阱与当前任务相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要了解历史或它是可用的备用文件时，才使用 learnings.md。否则跳过这两个文件。

应用相关经验后，如果遇到了值得记住的模式、值得预防的错误或令人意外的领域知识，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目符号。不要修改 SKILL.md 本身。