DOCX：Word 文档创建与编辑

▐▎ 双栏模式

快速概览 结构拆解 脚本解读 最佳实践

一句话总结

docx 是 Word 文档处理的完整解决方案——通过 docx-js 创建新文档，通过”拆包-编辑XML-打包”流水线修改现有文档，完整支持修订追踪、评论和格式化。

核心能力

• 📝 使用 docx-js（JavaScript）创建新文档，支持完整格式化
• 🔧 使用”拆包-编辑XML-验证-打包”流水线编辑现有文档
• ✍️ 完整的修订追踪支持（插入/删除/嵌套操作）
• 💬 评论系统（含回复链）
• 📊 表格、图像、页眉页脚、目录、脚注、多栏布局
• ✅ XML Schema 验证与自动修复

触发场景

用户提及 Word 文档、.docx 文件、需要创建报告/备忘录/信件、需要编辑或修改现有 Word 文档、需要处理修订和评论。

文件清单

One-Line Summary

docx is a complete Word document processing solution — creating documents via docx-js, editing existing documents through the “unpack-edit XML-pack” pipeline, with full support for tracked changes, comments, and formatting.

Core Capabilities

• 📝 Create new documents with docx-js (JavaScript) with full formatting support
• 🔧 Edit existing documents via “unpack-edit XML-validate-pack” pipeline
• ✍️ Complete tracked changes support (insertions/deletions/nested operations)
• 💬 Comment system (with reply chains)
• 📊 Tables, images, headers/footers, table of contents, footnotes, multi-column layouts
• ✅ XML Schema validation with auto-repair

Trigger Scenarios

User mentions Word documents, .docx files, needs to create reports/memos/letters, edit existing documents, or work with tracked changes and comments.

File Inventory

• docx
  • SKILL.md 主入口 · ~590 行 DOCX 处理指南
  • LICENSE.txt 许可证
  • scripts
    • comment.py 评论添加脚本
    • accept_changes.py 接受修订
    • __init__.py 包初始化
    • office 共享 Office 核心包
      • pack.py XML → DOCX 打包
      • unpack.py DOCX → XML 拆包
      • validate.py 验证入口
      • soffice.py LibreOffice 封装
      • validators 模式验证器
        • __init__.py
        • base.py 基础验证器
        • docx.py DOCX 验证器
        • pptx.py PPTX 验证器
        • redlining.py 修订验证器
      • helpers
        • __init__.py
        • merge_runs.py 合并相邻 runs
        • simplify_redlines.py 简化修订标记
      • schemas XSD Schema 文件
        • microsoft/
        • mce/
    • templates XML 模板
      • comments.xml
      • commentsExtensible.xml
      • commentsExtended.xml
      • commentsIds.xml
      • people.xml

目录结构分析

docx 的结构属于**“拆包-编辑-验证-打包”流水线型**——围绕一个共享的 scripts/office/ Python 包构建，该包被 docx、pptx、xlsx 三个 skill 共享。

SKILL.md 结构解析

约 590 行的 SKILL.md，是文档类 skill 中最详尽的。核心结构包含：

1. Quick Reference：三种任务的三条路径——读取用 pandoc，新建用 docx-js，编辑用 XML 流水线
2. Creating New Documents：docx-js 的完整参考——页面尺寸、样式、列表、表格、图像、页眉页脚、目录、脚注、制表位、多栏布局。每个主题都包含 Critical Rules
3. Editing Existing Documents：严格三步流程——拆包 → 编辑 XML → 打包，附带 XML 参考
4. XML Reference：Schema 合规要求、修订追踪 XML 模式、评论 XML 结构、图像添加步骤
5. Dependencies：pandoc、docx、LibreOffice、Poppler

YAML Frontmatter 分析

TRIGGER 条件非常广泛——“用户想对 Word 文档做任何操作”，同时包含明确的 SKIP 条件：“不为 PDF、电子表格、Google Docs 或与文档生成无关的通用编码任务触发”。触发示例包括”report”、“memo”、“letter”、“template”等关键词。

模块关系

docx 的脚本分为三个层次：

• 用户面向脚本：comment.py（添加评论）、accept_changes.py（接受修订）
• Office 核心：office/unpack.py、office/pack.py、office/validate.py、office/soffice.py
• 支持模块：office/validators/（5 个验证器）、office/helpers/（XML 工具）、templates/（XML 模板）

设计模式分类

docx 是典型的**“流水线”（Pipeline）** 型 Skill：

共享 office/ 包架构

scripts/office/ 是一个被 docx、pptx、xlsx 三个 skill 共享的 Python 包：

这种共享架构是文档类 skill 的核心设计模式——它避免了代码重复，确保了三个 Office 格式的处理一致性。

Directory Structure Analysis

The docx skill follows an “Unpack-Edit-Validate-Pack” pipeline pattern — built around a shared scripts/office/ Python package that is reused by docx, pptx, and xlsx skills.

SKILL.md Structure Analysis

An ~590-line SKILL.md, the most detailed among document skills. Core sections include:

1. Quick Reference: Three paths for three tasks — read with pandoc, create with docx-js, edit with XML pipeline
2. Creating New Documents: Complete docx-js reference — page size, styles, lists, tables, images, headers/footers, TOC, footnotes, tab stops, multi-column layouts. Each topic includes Critical Rules
3. Editing Existing Documents: Strict three-step process — unpack → edit XML → pack, with XML reference
4. XML Reference: Schema compliance requirements, tracked changes XML patterns, comment XML structure, image add steps
5. Dependencies: pandoc, docx, LibreOffice, Poppler

YAML Frontmatter Analysis

TRIGGER conditions are very broad — “user wants to do anything with Word documents”, with clear SKIP conditions: “Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation”. Examples include “report”, “memo”, “letter”, “template” keywords.

Module Relationships

docx scripts are organized in three layers:

• User-facing scripts: comment.py (add comments), accept_changes.py (accept revisions)
• Office core: office/unpack.py, office/pack.py, office/validate.py, office/soffice.py
• Support modules: office/validators/ (5 validators), office/helpers/ (XML utilities), templates/ (XML templates)

Design Pattern Classification

docx is a typical “Pipeline” Skill:

Shared office/ Package Architecture

scripts/office/ is a Python package shared by docx, pptx, and xlsx:

This shared architecture is the core design pattern of document skills — it avoids code duplication and ensures consistency across all three Office formats.

特征	说明
模式	拆包 → 编辑 XML → 验证 → 打包
共享包	office/ 被 docx/pptx/xlsx 共享
双路径	docx-js（创建）+ XML（编辑）
脚本数	15 个 Python 文件（含 office 包 + 模板）

Feature	Description
Pattern	Unpack → Edit XML → Validate → Pack
Shared Package	office/ shared by docx/pptx/xlsx
Dual Path	docx-js (creation) + XML (editing)
Script Count	15 Python files (including office package + templates)

模块	功能	被哪些 skill 使用
unpack.py	ZIP 提取 + XML 格式化	docx, pptx, xlsx
pack.py	XML → ZIP 打包	docx, pptx, xlsx
validate.py	验证入口	docx, pptx, xlsx
soffice.py	LibreOffice 封装	docx, pptx, xlsx
validators/	7 个 Schema 验证器	docx, pptx, xlsx
helpers/	XML 操作工具	docx, pptx, xlsx

Module	Function	Used by
unpack.py	ZIP extraction + XML formatting	docx, pptx, xlsx
pack.py	XML → ZIP packaging	docx, pptx, xlsx
validate.py	Validation entry point	docx, pptx, xlsx
soffice.py	LibreOffice wrapper	docx, pptx, xlsx
validators/	7 Schema validators	docx, pptx, xlsx
helpers/	XML manipulation utilities	docx, pptx, xlsx

脚本清单

docx 的脚本按层次分组：

用户面向脚本

Office 核心（共享包）

验证器

详细分析

office/unpack.py

这是整个 Office 处理流水线的起点，同时支持 DOCX、PPTX、XLSX 三种格式。

核心处理流程：

1. ZIP 提取：使用 zipfile.ZipFile 提取所有文件
2. XML 格式化：遍历所有 XML 和 .rels 文件，使用 defusedxml.minidom.toprettyxml() 美化成可读格式
3. DOCX 特有处理：
   • simplify_redlines：合并相邻的、来自同一作者的修订标记
   • merge_runs：合并格式相同的相邻 <w:r> 元素
4. 智能引号转义：将 Unicode 智能引号转为 XML 实体（“ 等），避免 XML 编辑时丢失

该脚本的关键设计在于它是可逆的——它的输出应能通过 pack.py 精确重建原始文件。

Script Inventory

docx scripts are grouped by layer:

User-Facing Scripts

Office Core (Shared Package)

Validators

Detailed Analysis

office/unpack.py

This is the entry point of the entire Office processing pipeline, supporting DOCX, PPTX, and XLSX formats simultaneously.

Core processing flow:

1. ZIP extraction: Uses zipfile.ZipFile to extract all files
2. XML formatting: Pretty-prints all XML and .rels files using defusedxml.minidom.toprettyxml()
3. DOCX-specific processing:
   • simplify_redlines: Merges adjacent tracked changes from the same author
   • merge_runs: Merges adjacent <w:r> elements with identical formatting
4. Smart quote escaping: Converts Unicode smart quotes to XML entities (“ etc.) to prevent loss during XML editing

The key design aspect is that this script is reversible — its output should be able to precisely reconstruct the original file via pack.py.

脚本	功能	依赖
comment.py	添加评论/回复（自动处理 XML 模板）	defusedxml
accept_changes.py	接受所有修订生成干净文档	LibreOffice

Script	Function	Dependency
comment.py	Add comments/replies (auto-handles XML templates)	defusedxml
accept_changes.py	Accept all tracked changes, produce clean document	LibreOffice

脚本	功能	依赖
office/unpack.py	ZIP 提取 + XML 格式化	defusedxml
office/pack.py	XML → ZIP 打包 + 验证	defusedxml, lxml
office/validate.py	验证入口	defusedxml, lxml
office/soffice.py	LibreOffice 封装（沙箱兼容）	subprocess

Script	Function	Dependency
office/unpack.py	ZIP extraction + XML formatting	defusedxml
office/pack.py	XML → ZIP packaging + validation	defusedxml, lxml
office/validate.py	Validation entry point	defusedxml, lxml
office/soffice.py	LibreOffice wrapper (sandbox compatible)	subprocess

脚本	功能
validators/base.py	基础验证器（XML、命名空间、关系 ID）
validators/docx.py	DOCX 特定验证（ID 约束、空白保留、评论标记）
validators/pptx.py	PPTX 验证
validators/redlining.py	修订标记验证

Script	Function
validators/base.py	Base validator (XML, namespaces, relationship IDs)
validators/docx.py	DOCX-specific validation (ID constraints, whitespace preservation, comment markers)
validators/pptx.py	PPTX validation
validators/redlining.py	Redline markup validation

office/unpack.py — 核心拆包逻辑 ↗ 源文件

1 def unpack(input_file, output_directory, merge_runs=True, simplify_redlines=True): 2 input_path = Path(input_file) 3 output_path = Path(output_directory) 4 suffix = input_path.suffix.lower() 5 6 if suffix not in {".docx", ".pptx", ".xlsx"}: 7 return None, f"Error: {input_file} must be .docx, .pptx, or .xlsx" 8 9 output_path.mkdir(parents=True, exist_ok=True) 10 11 with zipfile.ZipFile(input_path, "r") as zf: 12 zf.extractall(output_path) 13 14 xml_files = list(output_path.rglob("*.xml")) + list(output_path.rglob("*.rels")) 15 for xml_file in xml_files: 16 _pretty_print_xml(xml_file) 17 18 if suffix == ".docx": 19 if simplify_redlines: 20 do_simplify_redlines(str(output_path)) 21 if merge_runs: 22 do_merge_runs(str(output_path)) 23 24 for xml_file in xml_files: 25 _escape_smart_quotes(xml_file) 26 27 return None, f"Unpacked {input_file} ({len(xml_files)} XML files)"

代码解读

L1 函数入口：接受 4 个参数——输入文件、输出目录、是否合并 runs、是否简化修订。merge_runs 和 simplify_redlines 默认开启，仅对 DOCX 生效。 L4 格式验证：只接受 .docx/.pptx/.xlsx 三种 Office Open XML 格式——这也是 office/ 包被三个 skill 共享的基础。 L8 ZIP 提取：Office 文件本质上是 ZIP 压缩包，直接用 zipfile 提取所有 XML、图像、关系文件。 L13 XML 美化：对所有 XML 文件进行格式化缩进，使其可读、可编辑——这是"可编辑性"设计的核心。 L18 DOCX 后处理：仅对 DOCX 执行 run 合并和修订简化。这些操作减少了 XML 的噪声，让 Claude 更容易理解文档结构。 L23 智能引号转义：将 Unicode 智能引号转换为 XML 实体，避免在编辑过程中丢失。引号是最容易被意外修改的字符之一。

office/pack.py

打包脚本是拆包的逆操作，将编辑后的 XML 目录重新打包为有效的 Office 文件。

核心流程：

1. 验证：使用 validators/ 中的 Schema 验证器检查 XML 的正确性
2. 自动修复：修复常见问题（如过大的 durableId、缺失的 xml:space="preserve"）
3. XML 压缩：将美化后的 XML 压缩为单行格式
4. ZIP 打包：使用 zipfile.ZipFile 创建有效的 Office 文件

关键设计是验证-修复循环——验证失败时自动尝试修复，降低编辑 XML 时的出错概率。

comment.py 简要分析

评论脚本处理了 DOCX 评论系统最复杂的部分——跨多个 XML 文件的一致性维护。它自动：

• 在 comments.xml 中创建 <w:comment> 元素
• 在 commentsExtensible.xml 中创建扩展属性
• 在 commentsExtended.xml 中创建扩展数据
• 在 commentsIds.xml 中创建 ID 映射
• 在 people.xml 中注册作者

支持回复链（--parent 参数可指定父评论 ID）。

accept_changes.py 简要分析

调用 LibreOffice 宏接受所有修订，是”一键清理”工具。比在 XML 中手动删除 <w:ins> 和 <w:del> 元素更可靠。

validators/docx.py 简要分析

DOCX 的 XML Schema 验证器，检查内容包括：

• XML 格式正确性：标签闭合、属性格式
• 命名空间一致性：确保使用了正确的命名空间
• ID 唯一性：paraId 和 durableId 不重复
• 空白保留：含首尾空格的 <w:t> 必须有 xml:space="preserve"
• 修订标记正确性：<w:del> 内不能有 <w:t>，<w:ins> 内不能有 <w:delText>
• 评论标记配对：commentRangeStart 和 commentRangeEnd 必须成对出现

共享 office/ 包的设计价值

docx/pptx/xlsx 三个 skill 共享 scripts/office/ 包，这是文档类 skill 最核心的架构决策：

1. 代码复用：unpack/pack/validate/soffice 四个核心脚本无需重写
2. 一致性：三个格式的处理流程完全一致——拆包 → 编辑 → 验证 → 打包
3. 验证器增长：每个 skill 只需添加自己的 Schema 验证器（docx.py/pptx.py），共享 base.py 和 redlining.py
4. 维护简化：修复一个 bug 即可惠及所有三个格式

office/pack.py

The packaging script is the inverse of unpacking, repacking the edited XML directory into a valid Office file.

Core flow:

1. Validation: Uses Schema validators from validators/ to check XML correctness
2. Auto-repair: Fixes common issues (oversized durableId, missing xml:space="preserve")
3. XML condensing: Compresses pretty-printed XML into single-line format
4. ZIP packaging: Creates a valid Office file using zipfile.ZipFile

The key design is the validation-repair loop — when validation fails, it automatically attempts repair, reducing error probability when editing XML.

comment.py Brief Analysis

The comment script handles the most complex part of DOCX’s comment system — maintaining consistency across multiple XML files. It automatically:

• Creates <w:comment> elements in comments.xml
• Creates extension properties in commentsExtensible.xml
• Creates extension data in commentsExtended.xml
• Creates ID mappings in commentsIds.xml
• Registers authors in people.xml

Supports reply chains (via --parent parameter specifying parent comment ID).

accept_changes.py Brief Analysis

Calls LibreOffice macros to accept all tracked changes — a “one-click cleanup” tool. More reliable than manually removing <w:ins> and <w:del> elements in XML.

validators/docx.py Brief Analysis

DOCX XML Schema validator checking:

• XML well-formedness: Tag closure, attribute formatting
• Namespace consistency: Correct namespace usage
• ID uniqueness: Non-duplicate paraId and durableId
• Whitespace preservation: <w:t> with leading/trailing spaces must have xml:space="preserve"
• Redline correctness: No <w:t> inside <w:del>, no <w:delText> inside <w:ins>
• Comment marker pairing: commentRangeStart and commentRangeEnd must appear in pairs

Shared office/ Package Design Value

The docx/pptx/xlsx skills sharing the scripts/office/ package is the most important architectural decision for document skills:

1. Code reuse: unpack/pack/validate/soffice core scripts don’t need rewriting
2. Consistency: Processing flow is identical for all three formats — unpack → edit → validate → pack
3. Validator growth: Each skill only needs to add its own Schema validator (docx.py/pptx.py), sharing base.py and redlining.py
4. Simplified maintenance: One bug fix benefits all three formats

设计亮点

1. “拆包-编辑-验证-打包”流水线：将复杂格式的编辑问题转化为简单的 XML 文本编辑问题，使 Claude 的 Strengths（文本编辑、正则替换）能直接发挥
2. 共享 office/ 包：docx/pptx/xlsx 三个 skill 共享核心代码，避免了 60% 以上的代码重复
3. 双重创建策略：新建文档用 docx-js（高效、类型安全），编辑文档用 XML（灵活、精确控制）
4. XML 模板模式：templates/ 目录中的预构建 XML 片段（评论、作者、扩展），避免从零生成
5. 验证-修复循环：pack.py 先验证再打包，发现可修复问题自动修复，降低用户出错成本

可复用模式

移植思路

“如果你想为另一个 Office 格式（或任何基于 ZIP 的格式）创建类似的处理 Skill…”

1. 复用office/包：unpack.py、pack.py、soffice.py 可以直接复用——它们设计为格式无关
2. 创建格式专用验证器：继承 validators/base.py 中的 BaseSchemaValidator，添加格式特有的验证规则
3. 选择创建工具：根据格式选择最佳的高层创建库（如 docx-js for Word、PptxGenJS for PowerPoint）
4. 编写 XML 参考：在 SKILL.md 中添加格式的 XML 参考，包括常见编辑模式和 Critical Rules
5. 编写用户面向脚本：为最常见的操作（添加评论、接受修订）编写便捷脚本

常见坑

⚠️ 引号编码问题： XML 编辑中最常见的错误——Unicode 智能引号（“ 等）在 XML 工具中可能会被错误处理，必须使用 XML 实体

⚠️ 修订标记嵌套： <w:ins> 和 <w:del> 必须正确嵌套——删除其他作者的插入时，必须在 <w:ins> 内部使用 <w:del>

⚠️ <w:t> 内的空白： <w:t> 元素默认不保留首尾空白，必须显式添加 xml:space="preserve" 属性——这是 DOCX XML 编辑中最大的陷阱

⚠️ docx-js 版本锁定： docx-js 的 API 变化频繁，新版本可能改变默认行为（如页面尺寸从 A4 改为 Letter），需要在 SKILL.md 中锁定关键行为

⚠️ 打包时原始文件参考： pack.py 的 --original 参数非常关键——验证器需要比较原始文件和新文件的段落数等指标。缺少原始文件时，部分验证会跳过

Design Highlights

1. “Unpack-Edit-Validate-Pack” Pipeline: Transforming complex format editing into simple XML text editing, leveraging Claude’s strengths (text editing, regex replacement) directly
2. Shared office/ Package: docx/pptx/xlsx share core code, eliminating 60%+ code duplication
3. Dual Creation Strategy: New documents with docx-js (efficient, type-safe), editing with XML (flexible, precise control)
4. XML Template Pattern: Pre-built XML fragments in templates/ directory (comments, authors, extensions)
5. Validation-Repair Loop: pack.py validates before packaging, auto-repairs fixable issues

Reusable Patterns

Porting Guide

“If you want to create a similar processing Skill for another Office format (or any ZIP-based format)…”

1. Reuse the office/ package: unpack.py, pack.py, soffice.py are format-agnostic and directly reusable
2. Create format-specific validator: Extend BaseSchemaValidator from validators/base.py
3. Choose a creation tool: Select the best high-level creation library for the format (docx-js for Word, PptxGenJS for PowerPoint)
4. Write XML reference: Add format-specific XML reference to SKILL.md
5. Write user-facing scripts: Create convenience scripts for common operations

Common Pitfalls

⚠️ Quote encoding: The most common XML editing error — Unicode smart quotes (“ etc.) may be mishandled by XML tools; must use XML entities

⚠️ Redline nesting: <w:ins> and <w:del> must be properly nested — when deleting another author’s insertion, use <w:del> inside <w:ins>

⚠️ Whitespace in <w:t>: <w:t> elements don’t preserve leading/trailing whitespace by default — must explicitly add xml:space="preserve" attribute — the biggest trap in DOCX XML editing

⚠️ docx-js version locking: docx-js API changes frequently — new versions may change default behavior (page size from A4 to Letter), must lock critical behaviors in SKILL.md

⚠️ Original file reference during packaging: pack.py’s --original parameter is critical — validators compare paragraph counts between original and new files. Without the original, some validations are skipped

模式	说明	适用于...
Unpack-Edit-Pack 流水线	解包 → 编辑 → 验证 → 打包	任何基于 ZIP 的复杂格式（Office、EPUB、JAR）
共享核心包	多个 skill 共享同一套基础代码	处理同系列格式的 skill 组
XML 模板	预构建的 XML 结构片段	需要频繁插入标准 XML 结构的场景
双重创建策略	高层 API 建新 + 底层格式编辑	同时需要"从零创建"和"修改现有"的场景
验证-修复循环	先验证，修复可修复问题，报告不可修复问题	编辑有严格 Schema 约束的格式

Pattern	Description	Applies to...
Unpack-Edit-Pack Pipeline	Unpack → Edit → Validate → Pack	Any ZIP-based complex format (Office, EPUB, JAR)
Shared Core Package	Multiple skills sharing base code	Skill groups processing related formats
XML Templates	Pre-built XML structure fragments	Scenarios needing frequent standard XML insertion
Dual Creation Strategy	High-level API for new + low-level format editing	Scenarios needing both "from scratch" and "edit existing"
Validation-Repair Loop	Validate first, repair fixable issues, report unfixable ones	Formats with strict Schema constraints

↗ 新窗口 ×

加载中...