office-review-pass

/office-review-pass — 审阅并修订 Word 交付文件，同时保持其完好

只做一件事：让 .docx 完成一轮审阅，并在整个过程中保持 Ane 的格式不变，同时确保文件中每一项更改都可核验。

所有 Office 文档操作都在 ane_package.officeops 中进行。此技能负责判断，而非处理底层操作。如果某种模式需要 officeops 尚不具备的功能，请在 officeops 中添加并在那里测试——这样才能让此技能保持精简，也正因如此，我们才先抽取了该模块。确切的调用签名见 references/officeops-api.md；编写任何代码前，请先阅读。

模式选择

• read — 文档带有批注，或需要专家审阅。只读。
• annotate — 审阅意见应直接写入文档，作为由 Ane 添加的页边批注。写入她的工作副本，并保留备份。
• track — 必须让其他人能够看到并撤销编辑。写入带修订标记的副本。
• revise — Ane 已同意修复内容，并希望就地应用。编辑她的文件。
• annex — 文档需要附加术语表和来源附录。

模式可串联使用：read 生成审阅意见，annotate 将意见写入页边，track 或 revise 则将意见应用为编辑。如果模式不明确，请先用一句话询问。track 与 revise 的区别在于由谁决定：如果对方必须能够拒绝某项编辑，就用 track；如果 Ane 已经做出决定，就用 revise。annotate 与 track 的区别在于评论还是更改：批注说明哪里有问题，修订标记则说明应改成什么。

所有模式通用规则

• 以 Ane 的文件为基准。 如果目标文件已存在，请遵循 mel_wiki/wiki/concepts/edit-preservation-protocol.md。读取磁盘上的内容，只修改指定部分，其他内容保持逐字节不变。绝不要重新生成文档，也不要根据聊天中声称的内容重建文档——聊天展示的是系统生成的内容，磁盘展示的是 Ane 后来对其所做的修改。
• 核验已写入的文件，绝不能只看调用是否返回。 重新打开已保存的 .docx，并使用 officeops.verify 断言。save() 返回并不能证明任何事：有 6 个 ToR 版本发布时只有配色板，没有 logo，而且这些运行都正常退出了。
• 绝不捏造事实。 姓名、日期、数字、条款编号、URL、MA 名称。如果信息不在文档或已加载的上下文中，就先询问。这一点在 annex 模式中尤为重要，因为一个看似合理的 URL，在有人点击之前与真实 URL 无从区分。
• 按 EDIT-PRESERVATION DELIVERY 格式报告：说明更改了什么、哪些内容保持原样，以及列出但未处理的范围外观察项。

阅读模式

目的不是总结文档，而是针对 Ane 已经注意到的内容，给她一份真正深入审阅后的第二意见。

1. 呈现文档，并保留其中的评论。 python scripts/review_pass.py read <path> --out review.md 此命令封装了 officeops.comments.render_review，该函数按文档顺序遍历正文，并在每条评论范围的起始位置打印评论，同时显示其覆盖的锚定文字、作者、解决状态，以及缩进显示的所有回复。请阅读该文件，而不是原始的 .docx。
2. 先通读整份文档，再看评论。 先形成自己的判断，再了解她的看法，交叉审阅才有价值。模型如果先读她的评论，往往会对她的所有意见都表示赞同。
3. 交叉审阅每条评论，并将其归入以下三类之一，明确说明类别：
   • 认同 — 并补充她未提及的内容：其后果、修正方法，或与之冲突的条款。
   • 反驳 — 说明理由。她的评论是需要认真回应的同行评审意见，不是要照办的指令。若对所有意见都表示赞同，就没有提供任何她尚未知道的信息；而这正是此模式要避免的问题。
   • 重新界定 — 她指出了真实问题，但对问题的诊断浅了一层或深了一层。
4. 补充她遗漏的发现，并标注渲染结果中的区块编号，方便她直接定位。
5. 先给出 BLUF：用一句话给出对文档的判断，然后说明关键依据，再逐条交叉审阅评论，最后列出你自己的发现。采用一级工作简报的风格，除非文档面向的受众另有要求。
6. 提出是否需要转发邮件给文档所有者；不要主动代写。Ane 需要时，邮件应简短，点明两三项关键事项，并附上文档，而不是逐项复述。

修订痕迹也属于审阅内容：render_review 会将插入内容显示为已接受、删除内容显示为已删除，并在对应区块标注 +ins / -del。如果需要单独讨论某项更改，officeops.tracked.read_revisions(path) 会逐项提供修订内容、作者和日期。

关于语气。 正在审阅的文档通常有一位并非 Ane 的作者。发现应针对文本，而非针对个人，并保持协作语气——例如“未说明验收标准”，而不是“作者未能说明验收标准”。

批注模式

这是阅读模式发现的写入路径：每项发现都会成为 Ane 工作副本中的一条边栏评论——这种常见做法是，她的反馈副本（fbANE 文件）会附上她的评论，返还给文档所有者。此模式概括自一轮评估审阅；当时 Ane 是手动插入每条评论的。

1. 确认发现事项清单和作者署名。 默认作者为“Ane Gasser”，不添加其他标注——这是她在上一轮审阅中的明确要求，因为在发给交易对手的文档中，带有 AI 标签的评论看起来像机器生成的内容。署名由她决定：写入前先确认，并根据下方的范围边界，将离开 IPPF 的文档视为 AI 辅助出版物。
2. 每个锚点必须包含五个或更多连续词语，且恰好匹配一个段落。 将评论写入 JSON 文件，然后运行 python scripts/review_pass.py annotate <path> --comments comments.json --author "Ane Gasser" 文件格式为 [{"match": "...", "text": "..."}] 或 {"anchor words": "comment text"}；每项中的 author 和 initials 会覆盖默认值。写入前会预先检查正文和表格段落中的锚点；匹配结果为零个或多个时，整个操作都会失败，并列出所有有问题的锚点；驱动程序会直接拒绝少于五个词的锚点。重新选择失败的锚点；绝不能放宽要求。
3. 只有在带评论的副本通过验证后，才会替换原文件。 officeops.add_comments_in_place 会在原文件旁写入副本并对其进行断言检查——每条新评论都存在、每条现有评论都按其各自的 ID 保留、正文词数不变——然后在源文件旁写入带时间戳的 _BACKUP_ 文件，再进行替换。操作失败时，工作副本会保持字节级不变；不会出现她的文件受损的情况。
4. 报告已写入文件中的计数，而不是请求列表中的计数：评论总数、保留的现有评论数、新增评论数、正文词数是否不变、备份文件名。驱动程序会准确输出这些内容；在交付报告中重复这些内容。
5. 后续审阅中遇到的陷阱。 (a) 将 Windows 路径（C:/Users/...）传给驱动程序；Git Bash 路径（/c/Users/...）会在 zipfile 中触发 FileNotFoundError。(b) read_comments 会在拼接评论段落时不加分隔符，因此，用 写入的评论读回来会连成一串；比较时应忽略空白，否则即使写入正确也会被报告为不匹配。(c) 驱动程序只能添加评论。目前尚不支持就地改写 Ane 的现有评论文本（待办事项：ENHANCE office-review-pass）。在支持之前，保留每条评论最后一个 w:p，因为 commentsExtended.xml 和 commentsIds.xml 以该段落的 w14:paraId 为键，并围绕它重建文本。修改 comments.xml 和 people.xml 中的 w:author，在临时副本上验证 ID、作者、日期、锚点和正文词数，然后再备份并替换。参考脚本：工作文件夹中的 agent-improvements/handoffs/hera-hub-round2-scripts/hera_apply_aar.py。(d) 2026-09-25 新增（Member Association 案例研究）： 锚点必须逐字符匹配，而 Word 文本通常使用弯引号和弯撇号（’、“）。在匹配字符串中输入直撇号 ' 会导致无法匹配。请选择不含撇号或引号的五词片段，或者从提取的文本中复制片段，而不要重新输入。驱动程序的预检查会指出失败的锚点，但提前选择干净的片段可以避免重新运行。(d) 修改措辞时，应在现有的 w:t 运行内编辑，而不是重建段落：找到恰好包含一次旧字符串的那个 w:t，在该处替换；匹配结果为零个或多个时，直接停止。这样段落数量、paraId 和运行格式都保持不变，并且可以断言所有未修改的评论在 comments.xml 中字节级不变。参考：hera-hub-round2-scripts/hera_apply_align.py（2026-09-24，运行两次）。(e) Word 重新保存可能会将一条评论的文本拆分到多个运行中，但字符本身并未改变：Ane 重新保存审阅后的报告后，有一个句子在 Table| 4) 处分成两段，单运行匹配因此失败。遇到这种情况应停止操作并输出运行结构，然后将编辑目标改为包含该文本的运行；绝不能放宽匹配条件或合并运行。(f) 2026-10-14 新增（RBM ES 审阅，评论格式处理）： 不要想当然地认为陷阱 (c) 中的限制适用，先检查部件列表。 由本地化评论驱动程序写入评论的包不含 commentsExtended.xml、commentsIds.xml 或 people.xml，因此没有任何内容以 w14:paraId 为键，现有评论文本可以自由重建——重写 w:comment 子项，保留 ID、作者和日期，只替换对应的一个部件，并断言所有其他部件都字节级不变。只有经过 Word 重新保存的包才需要保留最后一个 w:p 并进行相应处理。另外，主文档部件由 _rels/.rels 指向，不一定总是 word/document.xml——某个 Storyline/供应商导出包使用了 word/document2.xml，硬编码文件名会触发看似数据损坏的 KeyError。参考脚本（按幻灯片映射重建评论、失败即停止、字节级不变地替换包）：1. Ane's PROJECTS/RBM II/RBM - transaltions SP/review-working/transform_comments_v2_20261014.py。 评论文字应遵循阅读模式的原则：针对文本，而非针对个人；每条评论都应说明后果或给出修正方案，而不只是提出异议——只写一句“表述不清”的边注会让作者不得不猜。

修订模式

适用于承包商提案、合作伙伴文档和翻译审校：对方在 Word 中打开文件时，能看到每处更改的归属，并逐一接受或拒绝。

1. 确认编辑清单，以及更改中应显示的作者姓名。归属是关键——未标注作者的修订看起来就像系统生成的内容。
2. 将编辑写入 JSON 文件，然后运行 python scripts/review_pass.py track <path> --edits edits.json --author "Ane Gasser" --out marked-up.docx 如果编辑需要逻辑处理，也可以直接调用 officeops.tracked.TrackedEditor。无论采用哪种方式，都会写入副本；源文件保持不变。
3. 检查每项编辑返回的计数。 .replace() 会返回替换次数。0 表示搜索字符串有误，而不是文档已经正确——成功消息中这两种情况看起来一模一样，但只有一种是真的。
4. 使用 read_revisions 验证写入后的文件，切勿使用 paragraph.text。 python-docx 不会读取 w:ins 中的文本，因此跟踪插入后，段落看起来就像缺少新增文字。根据 paragraph.text 断言会让你误以为编辑失败，尽管实际上已经成功。python scripts/review_pass.py revisions marked-up.docx 会打印实际写入的内容。
5. 报告每项编辑及其计数，并提供修订后文件的路径，以及一行说明收件人会看到什么。

评论和修订可以很好地配合使用：officeops.comments.add_comments 会将边注添加到副本中，因此修订后的文档可以同时包含更改及其原因。匹配字符串必须包含连续五个或更多单词，并且只匹配一个段落——匹配到零个或多个段落时会抛出异常，而不是自行猜测，因为评论落在错误段落上，读起来像审校失误，而不是工具错误。捕获异常后重新选择匹配字符串；不要放宽匹配条件。

修订模式

Ane 已手动编辑了文档。格式是她设置的，而 python-docx 对运行片段的编辑会破坏格式——一个分成三个运行片段的短语会变成一个运行片段，并沿用第一个运行片段的格式，而且不会有任何提示。

1. 确认范围。 只处理约定的列表，不多不少。发现的其他问题写进报告，不要应用修改。
2. 必须先在 Word 中关闭文件。 COM 会操作正在运行的 Word 实例；文件仍处于打开状态会导致 PackageNotFoundError，看起来像文件损坏，实际并非如此。
3. 运行 python scripts/review_pass.py revise <path> --edits edits.json，并封装 officeops.wordcom.find_replace。首次编辑前会自动写入带时间戳的备份，因为 COM 会原地编辑，且没有撤销操作。
4. 读取返回的计数并报告。 函数会从 Word 中读取计数，而不是自行假定。任何一对计数返回 0，都说明搜索字符串有误，必须向 Ane 确认，不能悄悄删掉。若文本也出现在页眉或页脚中，请传入 --headers；联系信息块和文档标题常出现在这些位置。如果你知道某个字符串出现了两次，但计数为 1，这是真正的遗漏，不是四舍五入造成的。 有一轮审阅中，两个表格里重复出现的页眉只改了第一个；重新渲染文件后发现第二个未变，再运行一次才捕捉到。请重新渲染，并与编辑前的渲染结果进行差异比较；绝不能只相信计数。如果同一单元格文本重复出现，且需按行进行不同修改（Yes → Yes (Table 1, EQ3)），查找替换无法按位置定位：请改用 python-docx 按表格、行和列编辑单元格，并查看下一段关于如何保存的说明。
5. 验证写入的文件：python scripts/review_pass.py verify <path> 会运行品牌标识、页眉/页脚、悬空超链接和字数断言。悬空超链接是文本替换造成的特定损坏——文字被删掉了，关系却保留了，最终文档中会有一个指向空处的链接。

将 python-docx 的编辑保存到 Ane 的文件中。 Document.save() 会重新序列化每个部分：页眉、页脚、样式、设置、core.xml。即使你只编辑了正文，与原文件进行字节检查时，这些部分也都会不匹配。请先保存到临时文件，只取其中的 word/document.xml，再将其写入原始软件包的副本中，并确保其他每个部分的字节都与原件完全一致。然后断言只有 word/document.xml 发生变化，备份并替换。参考：hera-hub-round2-scripts/hera_annex_final_ir.py。

PDF。 officeops.wordcom.export_pdf 默认拒绝导出，这是正确的。对 Wine & Slate 套件中的文档调用 ExportAsFixedFormat 会无限期挂起：页数会返回，但导出不会完成，Word 进程仍在运行并占用文件。因此，此模式不会生成 PDF。最后用一句话告诉 Ane，让她在 Word 中手动导出：文件、另存为、PDF。只有在她确认这份特定文档不受影响时，才传入 allow_known_hang=True；是否这样做由她决定，而不是你决定。用更长的超时时间掩盖挂起只会浪费几分钟，仍然失败。

annex 模式

附加两个部分，让起草团队以外的读者无需询问他人也能读懂文档。

1. 术语表 —— 列出文档中使用的所有缩写和技术术语，并写出全称；如果仅给出全称还不够清楚，再用大约六个英文单词作通俗解释。请通读文档来编制术语表；不要套用标准清单，因为标准清单会包含本文档未使用的术语，也会漏掉本文档自创的术语。
2. 来源附录 —— 列出所有引用的文档、法律、标准和框架，并附上可点击的超链接。
   • 本次会话中的 WebSearch 或 WebFetch 才算验证。 凭训练数据回忆起的 URL 只是披着链接外衣的猜测，这是此模式可能交付的最严重问题。
   • 优先采用权威发布方的链接，其次是该域名上的直接 PDF，再其次是机构知识库或 DOI。仅在同时提供权威链接时才使用聚合网站。
   • 无法验证的内容须标记为 ⚠️ URL unverified — confirm before publication，且不添加链接。切勿猜测看似合理的 URL。
3. 沿用文档现有的标题样式，不要另行引入新样式，并保持 IPPF Visual Identity 2025 模板完整。
4. 验证：verify.hyperlink_targets 确认每个链接都指向预期地址，verify.stranded_hyperlinks 确认没有孤立的超链接。报告术语数量、来源数量，并明确列出每个未验证项。

验证计划

每种模式都要在开始处理前说明检查内容，并在完成后重新打开写入的文件：

模式	检查内容
read	只读——不写入任何内容。报告渲染结果中的区块数和批注数。
annotate	对写入后的文件运行 read_comments：报告原有与新增批注的数量、确认原有 ID 得以保留、字数不变，以及源文件旁存在备份。
track	对写入副本运行 read_revisions：每次替换各有一处插入和一处删除，并已设置作者和日期。
revise	从 Word 读回替换数量，然后运行 verify——检查品牌标识、页眉／页脚、是否存在孤立的超链接，以及字数。
annex	运行 hyperlink_targets 和 stranded_hyperlinks，并统计验证失败的来源数量。

python scripts/test_review_pass.py 用于检查驱动程序本身——确认两种编辑文件格式都能加载、带标记的副本不会覆盖源文件，以及找不到匹配项的搜索字符串会以非零状态退出。最后一项正是创建该驱动程序的原因：若审阅轮次没有应用任何编辑，生成的文件看起来会与已应用全部编辑的文件完全相同。Office 行为本身由工作目录中的 tests/test_officeops.py 覆盖。

范围边界

• 仅润色英文行文、不改动文件的工作属于 ane-voice。对完成的简报给出只读 QA 结论属于 check-deliverable。目标语言工作属于 localise。使用生成器编写 ToR 属于 tor-procurement。从带批注的文档中提取决策并整理成会议记录，属于 meeting-notes 的边注模式——该模式会读取批注，但不会写入批注；写入批注则属于此技能的 annotate 模式。
• 修复 Excel 和将过时的生成器规范化属于 office-repair（Wave 3），不属于此技能。
• COM 模式需要 Windows、Word，且文件必须处于关闭状态。在 Web 容器中，read 和 track 路径仍可运行——它们只使用纯 Python python-docx 和 lxml——但 revise 无法运行。
• 经 AI 辅助处理后离开 IPPF 的文档属于 AI 辅助出版物：请依据 mel_wiki/wiki/concepts/ai-use-in-publications.md 提供版权页说明。仅涉及常规语法的编辑不在此列。