docx

DOCX 创建、编辑和分析

概述

.docx 文件是包含 XML 文件的 ZIP 存档。

快速参考

任务	方法
读取／分析内容	使用 pandoc 或解压以查看原始 XML
创建新文档	使用 docx-js — 参见 references/docx-js.md
编辑现有文档	解压 → 编辑 XML → 重新打包
红线标注（修订）	使用 Document 库 — 参见 references/ooxml.md

将 .doc 转换为 .docx

必须先转换旧版 .doc 文件，然后才能编辑：

python scripts/soffice.py --headless --convert-to docx document.doc

读取内容

# Text extraction with tracked changes
pandoc --track-changes=all document.docx -o output.md

# Raw XML access
python scripts/unpack.py document.docx unpacked/

转换为图像

python scripts/soffice.py --headless --convert-to pdf document.docx
pdftoppm -jpeg -r 150 document.pdf page

接受修订

要生成已接受所有修订的干净文档（需要 LibreOffice）：

python scripts/accept_changes.py input.docx output.docx

---

创建新文档

使用 JavaScript 生成 .docx 文件。完整 API 参考请参见 references/docx-js.md。

工作流

1. 必须 — 阅读整个文件：继续操作前，请完整阅读 references/docx-js.md。
2. 使用 Document、Paragraph、TextRun 组件创建 JavaScript/TypeScript 文件。
3. 验证：python scripts/validate.py --original <any_existing.docx> unpacked/ 或在打包后验证。

---

编辑现有文档

按顺序完成全部 3 个步骤。

步骤 1：解压

python scripts/unpack.py document.docx unpacked/

此操作会提取 XML、进行美化打印、合并相邻的运行、简化修订，并将智能引号转换为 XML 实体（如 “），以确保编辑后仍能保留。使用 --merge-runs false 可跳过运行合并。

请记下解压脚本打印的建议 RSID — 将其用于修订。

步骤 2：编辑 XML

编辑 unpacked/word/ 中的文件。XML 模式和 Document Library API 请参见 references/ooxml.md。

两种方法：

1. 直接编辑 XML — 使用 Agent 的原生编辑工具进行字符串替换。最适合简单的修订和直接编辑。
2. Document Library（Python） — 适用于复杂的批量操作、以编程方式查找节点和红线标注工作流。请参见 references/ooxml.md 中的“Document Library”部分。

使用 Document Library

# Set PYTHONPATH to the skill root, then run your script
PYTHONPATH=/path/to/docx-skill uv run your_script.py

from scripts.document import Document, DocxXMLEditor

doc = Document("unpacked", author="Claude", initials="C")
node = doc["word/document.xml"].get_node(tag="w:r", contains="old text")
doc["word/document.xml"].replace_node(node, "<w:del>...<w:ins>...")
doc.save()

添加批注

使用 comment.py 处理多个 XML 文件中的样板内容：

python scripts/comment.py unpacked/ 0 "Comment text with & and ’"
python scripts/comment.py unpacked/ 1 "Reply text" --parent 0  # reply to comment 0

然后向 document.xml 添加标记（参见 references/ooxml.md 中的 Comments）。

步骤 3：打包

python scripts/pack.py unpacked/ output.docx --original document.docx

通过自动修复进行验证、压缩 XML 并创建 DOCX。使用 --validate false 可跳过验证。

自动修复会修复：

• durableId >= 0x7FFFFFFF（重新生成有效 ID）
• 带空白的 <w:t> 缺少 xml:space="preserve"

自动修复不会修复：

• 格式错误的 XML、无效的元素嵌套、缺失的关系、架构违规

---

文档审阅的红线标注工作流

此工作流用于对他人的文档进行全面修订。完整的 Document Library API 和 XML 模式请参见 references/ooxml.md。

批处理策略：将相关更改分成每批 3-10 项。这样既能保持效率，也便于调试。

原则：最小且精准的编辑 仅标记实际发生变化的文本。重复未更改的文本会让编辑内容更难审阅，也显得不专业。将替换拆分为：[未更改文本] + [删除] + [插入] + [未更改文本]。

修订跟踪工作流

1. 获取 Markdown 表示：pandoc --track-changes=all path-to-file.docx -o current.md
2. 识别并分组更改：按章节、类型或相近程度整理为逻辑批次
3. 阅读文档并解包：
   • 必须：完整阅读 references/ooxml.md
   • 解包：python scripts/unpack.py file.docx dir
   • 记下建议的 RSID
4. 分批实施更改：复杂操作使用 Document Library，简单操作可直接编辑 XML
5. 打包：python scripts/pack.py dir reviewed.docx --original file.docx
6. 最终验证：pandoc --track-changes=all reviewed.docx -o verification.md

---

依赖项

• pandoc：文本提取（apt-get install pandoc）
• docx：npm install -g docx（新建文档）
• LibreOffice：PDF 转换、接受修订（通过 scripts/soffice.py）
• Poppler：用于处理图像的 pdftoppm（apt-get install poppler-utils）
• defusedxml：安全的 XML 解析（pip install defusedxml）