word-review：文档审核与原生批注
核心理念
脚本只管“准”：解析 docx、把审核意见精确锚定到原文、写回原生 Word 批注、读回校验。
你只管“懂”：读什么、审几遍、用什么标准、如何取舍、是否分片或并行，完全由你判断。
不要被工具限制审核方式：先想清楚用户要什么，再决定用哪些命令。
环境准备
脚本位于本技能目录 scripts/review.py，依赖 python-docx>=1.2.0 与 rapidfuzz。首次使用先检测：
python3 -c "import docx, rapidfuzz" 2>/dev/null && echo OK
缺依赖时用 uv（推荐，无需安装，不加 --python 参数）：
uv run --with "python-docx>=1.2.0" --with rapidfuzz python3 <技能目录>/scripts/review.py <子命令> ...
或安装到当前 Python：
python3 -m pip install --user "python-docx>=1.2.0" rapidfuzz
下文命令均以 python3 review.py 示意；缺依赖时把前缀换成 uv run --with "python-docx>=1.2.0" --with rapidfuzz python3；Windows 环境下把 python3 换成 python。
自检（可选，验证环境与功能，约 10 秒，无需网络）：
python3 <技能目录>/tests/selftest.py
工具契约
| 命令 | 用途 | 关键输出 |
|---|---|---|
extract |
解析 docx，建立可锚定的文本块视图 | blocks.json + blocks.md（含稳定 block_id、原文、位置标签、文档大纲） |
scan |
词表命中 + 确定性检查（括号/引号配对、重复标点、中文后半角标点） | 候选 issues JSON |
apply |
定位 quote → 写回原生 Word 批注 → 导出 | 批注版 docx；--dry-run 只预检；--report 输出定位明细 |
report |
合并 issues 生成统计报告 | Markdown 或 HTML（分类/等级统计 + 明细表） |
verify |
读回输出文档中的批注 | 批注数量、作者、锚定原文 |
工作目录与命名
extract默认在文档同目录创建<文件名>_review/，内含blocks.json、blocks.md；apply默认输出<文件名>_审核结果.docx；report默认输出 issues 同目录审核报告.md；scan默认输出<文件名>_review/scan_issues.json。所有默认值都可用参数覆盖。
issues 最小契约
[{"block_id": "paragraph_12", "quote": "原文连续片段", "comment": "批注意见"}]
可选字段：replacement（有则批注自动附“建议改为：X”）、category、severity（严重/一般/建议）、confidence、context（quote 在块内多次出现时用于消歧）、note（仅报告可见）。详见 references/issues-schema.md。
scan 词表格式
每行一条：词、词=>替换、词 @类别、词=>替换 @类别；# 开头为注释。
推荐工作流（按需裁剪）
- 明确审核目标：用户给了审核要求、规则文件或词表就以用户为准；没有则做默认文字校审（错别字、语法、标点、表述、内容风险），场景清单可参考
references/review-playbook.md。 - extract：拿到
blocks.md（人读）与blocks.json（结构化）。文档大纲部分可帮助快速定位重点章节。 - 审核：通读原文产出 issues。
- 文档不大：直接读blocks.md，可多遍审核（先文字、后逻辑与合规）；
- 文档很大：按标题或块区间分片，可用子代理并行，各自输出issues_partN.json（apply/report 支持多文件自动去重）；
- 发挥全局视野：术语/数字/编号一致性、前后矛盾、标题层级、跨表格数据核对，这些是逐段校对做不到的；
- 需要确定性兜底时运行scan（词表、括号引号、标点），与模型结果合并。 - apply --dry-run 预检定位：失败项会给出原因（quote 不在块内 / 多处歧义 / 评分过低），据此修正 quote、补 block_id 或 context 后重试；确实无法锚定的条目留在报告中说明。
- 预览确认：用
report生成统计与明细给用户确认；用户可按类别/严重度筛选、删改条目（直接编辑 issues 文件）后再 apply。 - apply 正式写回，verify 抽查批注数量与锚定文本，向用户汇报输出路径与统计。
硬约束
quote必须是原文连续片段，不得改写、拼接、跨块；写回只加批注，不改动正文。- 可锚定范围：正文段落、表格单元格、超链接、修订插入内容（w:ins）、内容控件（w:sdt）；修订删除内容（w:del）不参与审核；页眉页脚无法写批注（可写进报告）；嵌套表格内层文字暂不解析。
- 需要
python-docx>=1.2.0（低版本没有批注 API）。 - 不臆造原文：拿不准的问题降低
confidence，或只写进报告不写回。
常见问题
- quote 定位失败：看 dry-run 的
failures原因。归一化匹配已容忍空格、全半角、弯直引号差异；多处歧义时补block_id/context；仍失败说明 quote 与原文出入较大，回原文核对。 - 批注重叠被跳过：同一位置只保留一条（按 confidence、跨度排序），dry-run 的
conflicts与 apply 的skipped会列出被跳过的条目。 - 表格合并单元格：extract 已按单元格去重，合并单元格只产生一个块。
- 超链接/修订/内容控件：其中的文字正常参与审核与批注；批注范围以整个超链接或修订块为界。
- 中文乱码：脚本按 UTF-8 读写；终端异常时把输出重定向到文件再读。
