如何让 AI 对 Word 文档进行批注

Python Word docx 批注 AI
发布日期:   2026-06-08

如何让 AI 对 Word 文档进行批注

一、原理概述

.docx 文件本质上是一个 ZIP 压缩包，内部包含多个 XML 文件。Word 批注（Comment）就存储在其中的 XML 文件里。因此，实现批注的完整流程是：

解压 .docx → 编辑 XML → 重新打包 → 得到带批注的 .docx

二、涉及的文件结构

解压后，和批注相关的核心文件如下：

文件路径 作用
word/document.xml 正文内容，批注标记插入此处
word/comments.xml 批注内容（作者、时间、文字）存储在此
word/_rels/document.xml.rels 关联关系文件，需包含 comments 关系
[Content_Types].xml 内容类型注册

三、依赖工具

3.1 Python 环境

推荐使用 Python 3.10+，需要以下模块：

pip install defusedxml lxml
  • defusedxml：安全解析 XML（防止 XXE 攻击）
  • lxml：XML 验证与处理

3.2 WorkBuddy docx 技能脚本

WorkBuddy 内置的 docx 技能提供了三个关键脚本（路径示例）：

~/.workbuddy/plugins/marketplaces/codebuddy-plugins-official/plugins/docx/scripts/
├── office/
│   ├── unpack.py     # 解压 docx → 格式化 XML
│   ├── pack.py       # 重新打包 → 生成 docx
│   └── validate.py   # 验证 XML 合规性
└── comment.py        # 生成批注 XML 模板（核心工具）

四、完整操作步骤

Step 1：解压 .docx 文件

python scripts/office/unpack.py 原文件.docx unpacked/

执行后，unpacked/ 目录内容如下：

unpacked/
├── word/
│   ├── document.xml        ← 正文（重点编辑对象）
│   ├── comments.xml        ← 批注内容（自动生成或手动创建）
│   ├── _rels/
│   │   └── document.xml.rels
│   └── ...
├── [Content_Types].xml
└── ...

unpack.py 会自动美化 XML 格式（pretty-print）并合并相邻的文字 run，方便手动编辑。

Step 2：生成批注内容（comment.py）

使用 comment.py 在 comments.xml 中写入批注内容：

python scripts/comment.py unpacked/ <批注ID> "批注正文内容" --author "作者名"

参数说明：

参数 说明
unpacked/ 解压目录路径
<批注ID> 整数，从 0 开始，每条批注唯一
"批注正文内容" 批注显示的文字
--author 批注作者名（显示在 Word 侧边栏），默认为 Claude
--parent 若为回复批注，指定父批注 ID

示例：

# 添加一条主批注（ID=0）
python scripts/comment.py unpacked/ 0 "这是重点" --author "审核"

# 添加对批注0的回复（ID=1）
python scripts/comment.py unpacked/ 1 "已确认，请注意" --author "审核" --parent 0

执行后，脚本会输出需要插入 document.xml 的标记代码，例如：

Added comment 0 (para_id=72AA8855)

Add to document.xml (markers must be direct children of w:p, never inside w:r):
  <w:commentRangeStart w:id="0"/>
  <w:r>...</w:r>
  <w:commentRangeEnd w:id="0"/>
  <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>

Step 3：在 document.xml 中插入批注标记

打开 unpacked/word/document.xml，找到需要批注的文字所在的 <w:p> 段落。

关键规则：

<w:commentRangeStart> 和 <w:commentRangeEnd> 必须是 <w:p> 的直接子元素，绝对不能放在 <w:r> 内部。

原始 XML（修改前）：

<w:p>
  <w:pPr>...</w:pPr>
  <w:r>
    <w:rPr>
      <w:color w:val="000000"/>
      <w:sz w:val="24"/>
    </w:rPr>
    <w:t>160天。</w:t>
  </w:r>
</w:p>

插入批注标记后（修改后）：

<w:p>
  <w:pPr>...</w:pPr>

  <!-- 批注范围开始 -->
  <w:commentRangeStart w:id="0"/>

  <w:r>
    <w:rPr>
      <w:color w:val="000000"/>
      <w:sz w:val="24"/>
    </w:rPr>
    <w:t>160天。</w:t>
  </w:r>

  <!-- 批注范围结束 -->
  <w:commentRangeEnd w:id="0"/>

  <!-- 批注引用锚点（必须有，否则批注不显示） -->
  <w:r>
    <w:rPr><w:rStyle w:val="CommentReference"/></w:rPr>
    <w:commentReference w:id="0"/>
  </w:r>

</w:p>

多条批注嵌套（批注+回复）示例：

<w:p>
  <w:commentRangeStart w:id="0"/>
    <w:commentRangeStart w:id="1"/>
    <w:r><w:t>被批注的文字</w:t></w:r>
    <w:commentRangeEnd w:id="1"/>
  <w:commentRangeEnd w:id="0"/>
  <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
  <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="1"/></w:r>
</w:p>

Step 4：重新打包生成 .docx

python scripts/office/pack.py unpacked/ 输出文件.docx --original 原文件.docx

参数说明：

参数 说明
unpacked/ 解压后的目录
输出文件.docx 生成的新文件路径
--original 原文件.docx 原始文件（用于补全二进制资源，如图片、字体等）
--validate false 跳过 XML 验证（遇到 GBK 编码等误报时使用）

注意： 若文档原始编码为 GBK（老版 Word 生成），validate.py 可能误报编码错误，此时加 --validate false 跳过即可，不影响文件实际内容。

五、comments.xml 的结构说明

comment.py 会自动生成 comments.xml，其结构如下：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:comments xmlns:wpc="..." xmlns:w="...">

  <!-- 一条批注 -->
  <w:comment w:id="0" w:author="审核" w:date="2026-06-08T00:00:00Z" w:initials="审">
    <w:p>
      <w:pPr>
        <w:pStyle w:val="CommentText"/>
      </w:pPr>
      <w:r>
        <w:rPr><w:rStyle w:val="CommentReference"/></w:rPr>
        <w:annotationRef/>
      </w:r>
      <w:r>
        <w:t>这是重点</w:t>
      </w:r>
    </w:p>
  </w:comment>

</w:comments>

六、完整实战示例

场景：对 合同.docx 中"工期160天"添加批注"这是重点"。

# 1. 解压
python scripts/office/unpack.py 合同.docx unpacked/

# 2. 生成批注（ID=0，作者=审核）
python scripts/comment.py unpacked/ 0 "这是重点" --author "审核"
# 脚本会输出需要插入 document.xml 的 XML 标记，按提示操作

# 3. 编辑 unpacked/word/document.xml
#    找到含"160天"的 <w:r>，在其外层 <w:p> 中插入批注标记
#    （见上方 Step 3 的 XML 示例）

# 4. 重新打包
python scripts/office/pack.py unpacked/ 合同_批注版.docx --original 合同.docx

# 5. 清理临时目录（可选）
rm -rf unpacked/

七、常见问题

Q1：批注不显示怎么办？

检查以下几点：

  • <w:commentRangeStart> 和 <w:commentRangeEnd> 是否是 <w:p> 直接子元素（不能在 <w:r> 里面）
  • <w:commentReference w:id="0"/> 是否已添加（锚点必须有）
  • comments.xml 中的 w:id 是否与 document.xml 中一致

Q2：pack.py 报 GBK 编码错误？

# 加上 --validate false 跳过验证
python scripts/office/pack.py unpacked/ output.docx --original input.docx --validate false

这是验证脚本的编码误报，不影响文件内容。

Q3：如何批量批注多处？

每条批注分配唯一 ID（0, 1, 2...），分别运行 comment.py 生成内容，再逐一在 document.xml 中插入对应标记。

Q4：如何添加回复批注？

# 主批注 ID=0
python scripts/comment.py unpacked/ 0 "这里有问题" --author "审核"

# 回复批注 ID=1，回复 ID=0
python scripts/comment.py unpacked/ 1 "已修改完成" --author "作者" --parent 0

八、核心要点速记

要点 说明
批注标记位置 <w:commentRangeStart/End> 必须是 <w:p> 的直接子节点
锚点必须添加 <w:commentReference> 缺失则批注不可见
ID 唯一性 每条批注 w:id 全文档唯一，从 0 开始递增
编码问题 GBK 文档 validate 可能误报，加 --validate false
作者名 通过 --author 参数指定，影响 Word 侧边栏显示
时间格式 w:date 必须是 ISO 8601 格式：2026-06-08T00:00:00Z
文章作者: 摸鱼
文章链接: https://gtjs-9gjbu0mx.maozi.io/2026/06/07/guan-yu-ji-neng/23-ru-he-rang-ai-dui-word-wen-dang-jin-xing-pi-zhu/
版权声明: 本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 摸鱼 !
Python Word docx 批注 AI
赏
  目录