read-docx-review

read-docx-review — docx 批注与修订对账

一条命令把审阅过的 docx 读成对账表：谁批的、批在哪段、批了什么、处理状态，外加修订模式的 逐段删改。产出表格自带空白「处置」列——它的用途就是拿去逐条裁决。

引擎提炼自作者一个真实图书出版项目的审阅工具链（2026-02 起生产验证：单文件 96 条编辑批注、 整书修订处理、输入含 WPS 云文档导出件），此处为通用化版本。书稿级的深度编辑工作流（版本链、 批注 resolve 状态机、审阅看板）留在原项目（私有），不在本 skill 范围。

快速开始

本文全部命令都假设工作目录是本 skill 根目录（scripts/ 是相对路径）——先 cd 过来， 或把 scripts/… 换成绝对路径；docx 参数无所谓相对绝对。

uv run python scripts/extract_review.py <审阅稿.docx>

预期输出（有批注时）：

# 审阅对账 · 某某协议-审阅版.docx

批注 12 条（未处理 10 / 已处理 2，其中回复 1 条）；修订段落 3 个（删除元素 2、插入元素 4）。

## 批注

| # | 批注人 | 时间 | 锚定段落 | 批注内容 | 状态 | 处置 |
|---|---|---|---|---|---|---|
| 0 | 张三 | 2026-02-14 16:02 | 乙方应于收到通知后 15 个工作日内… | 15 天太短，建议 30 天 | 未处理 |  |
| ↳1 | 李四 | 2026-02-14 18:11 | （回复 #0） | 同意，30 天合理 | 未处理 |  |

## 修订（track changes）

| 段落 | 删除 | 插入 | 处置 |
|---|---|---|---|
| 47 | 百分之十五 | 百分之十 |  |

无批注无修订时输出一段明确提示（「这份 docx 没有携带任何审阅痕迹」＋两个常见原因）， 不会静默输出空表——拿到丢了批注的副本还以为对方没意见，比读错内容更危险。

变体：

# 机器可读全量（锚定段落不截断、含全部字段）
uv run python scripts/extract_review.py <docx> --json

# 对账表包含已处理（resolved）的批注（默认只列未处理）
uv run python scripts/extract_review.py <docx> --include-resolved

要看某条批注前后更多上下文段落（对账表锚定列截断到 60 字，--json 里是全文）：

uv run python -c "
import sys; sys.path.insert(0, 'scripts')   # 同样假设 cwd = skill 根目录
from bridge_lib.docx_bridge_client import extract_views
for v in extract_views('<docx>', paragraph_range=(40, 55)):  # 批注锚定段落 ±N
    print(v['index'], v['display'][:100])"

为什么必须走这套引擎（不要退回 python-docx 裸读）

python-docx 的 paragraph.text 走 paragraph.runs，runs 只取直接子 <w:r>、不递归 <w:ins> 包装——对方用修订模式插入的所有内容都会被漏读；裸 lxml 的 .//w:t 能读到 ins，但认不出「段落标记被 <w:del> 包装的整段」（接受修订后会整段消失的内容仍有 <w:t>）。 两个方向的漏读都在真实出版审阅稿上踩过。本 skill 的 csx 引擎基于 Word 工程团队 官方维护的 OpenXML SDK，ins/del/move 是一等公民。机制细节、段落索引语义（body 直接子段， 与 python-docx 对齐、不递归表格内段）与三个 csx 的出参规格见 references/csharp-tasks-spec.md。

scripts/bridge_lib/docx_bridge_client.py 是 Python 入口层：list_comments() / list_revisions() / extract_views() / paragraph_text()，全部无状态直读 docx，按 (路径+mtime) 做内存缓存。写自定义分析时 import 它，别绕过它手解 XML。