1. 需求拆解批注合并和对比究竟在解决什么问题文档审阅批注的合并和对比说白了就是两件事一堆人各自在自己那份稿子上留了话怎么收拢到一处以及同一份稿子的两个轮次之间批注变了哪些、没变哪些怎么一眼看出来。做过投标文件、合同评审、技术方案会签的人应该都有体会——五个人回五份带批注的 Word你坐在那儿开着四个窗口来回切换复制粘贴到半夜第二天还有人问我那条关于付款节点的意见怎么没了。这不是能力问题是方法问题。这篇内容适合三类人看一是经常要汇总多方评审意见的项目协调岗、法务、质量岗二是想用脚本把这活儿自动化的技术同学三是需要给团队搭一套审阅意见管理系统的工具开发者。我不打算只讲某个软件的按钮在哪而是从 docx 文件内部结构讲起把批注到底是什么为什么合并会出错对比该怎么比这三件事串起来。看完之后手动场景你能少踩八成坑脚本场景你能直接抄走可运行的代码。先说清楚一个前提批注comment和修订tracked change是两个东西。批注是挂在某段文字旁边的意见盒子修订是直接改在正文里的红字。这两者的合并逻辑完全不同。批注合并本质是把多个 XML 部件里的 comment 节点拼到一起并修正锚点 id修订合并本质是把多个版本的正文差异统一表达成一套修订标记。前者相对可控后者基本只能靠 Word 原生的比较引擎或者自己写 diff。很多人把这两件事混为一谈结果方案设计阶段就跑偏了。2. 底层结构解析一份带批注的 docx 里到底存了什么2.1 把 docx 当压缩包拆开看docx 不是二进制黑盒它就是一个 ZIP。你把合同评审.docx改名成合同评审.zip再解压会看到这么一棵树word/ document.xml # 正文 comments.xml # 批注正文 commentsExtended.xml# 批注的已解决状态、回复关系 commentsIds.xml # 批注的持久化 ID people.xml # 批注人多人协作时才有 styles.xml settings.xml docProps/ core.xml app.xml [Content_Types].xml _rels/.rels关键点在于批注的文字不在 document.xml 里。document.xml 里只有三个路标节点真正的批注内容住在 comments.xml。这个设计决定了合并的核心动作——你要同时改两个文件且 id 必须对得上。2.2 comments.xml 的最小结构一条最简单的批注长这样w:comment w:id3 w:author张工 w:date2024-05-11T09:12:00Z w:initialsZG w:p w14:paraId5A3C1B77 w14:textId77777777 w:rw:t付款节点建议改成验收后 15 个工作日。/w:t/w:r /w:p /w:commentw:id是这条批注在当前文档内的编号w:author和w:date是展示用的。注意w14:paraId这个属性它是 Word 2010 之后给每个段落分配的一个 8 位十六进制随机值后面讲已解决状态时会用到也是合并时最容易出冲突的地方。2.3 锚点三件套RangeStart、RangeEnd、Referencedocument.xml 里被批注覆盖的那段文字会被三个节点包起来w:commentRangeStart w:id3/ w:rw:t乙方应在项目验收合格后支付尾款。/w:t/w:r w:commentRangeEnd w:id3/ w:r w:rPrw:rStyle w:valCommentReference//w:rPr w:commentReference w:id3/ /w:r这三处的w:id必须完全一致只要有一处对不上Word 打开时轻则批注跑到别的地方去重则直接报文档内容有问题。我见过最离谱的一次合并脚本只改了commentRangeStart忘了改commentReference结果 30 条批注全部堆在文档末尾同事看完以为我把他的意见全删了。2.4 commentsExtended.xml现代批注的灵魂Word 2013 之后引入的回复和已解决状态存在commentsExtended.xml里w15:commentsEx w15:commentEx w15:paraId5A3C1B77 w15:done1/ w15:commentEx w15:paraId7B2D4C11 w15:paraIdParent5A3C1B77/ /w15:commentsExw15:paraId对应的是这条批注最后一个段落的 paraIdw15:paraIdParent指向被回复的那条批注w15:done1表示已解决。这里有个巨坑paraId在整份文档里理论上应该唯一但跨文档合并时几乎必然撞车——8 位十六进制看起来多实际 Word 生成算法有规律同一台机器上连续生成的文档撞车概率不低。合并时必须重新生成 paraId 并同步更新引用这一点绝大多数网上流传的合并脚本都没做。2.5 还有两个容易被忽略的部件commentsIds.xml里存的是w16cid:durableId一个 32 位整数作用是在文档保存、重编号之后仍然能稳定标识一条批注。如果你要做两轮批注对比用w:id做键是不行的因为它每次保存都可能变必须用 durableId 或者自己造指纹。people.xml则是给谁在线这种协作提示用的合并时把几个文档的 people 列表去重合并即可不影响批注本身。注意.doc老格式根本没有comments.xml这套结构。做批量处理前先用脚本或者 Word 把所有.doc另存为.docx否则你的解析器会在第一步就抛异常。3. 工具选型从手动点按钮到写脚本的四条路线3.1 四条路线的横向对比路线适用规模上手成本可控性主要限制Word 原生比较/合并3 人以内、临时救急极低低要求同一基准稿正文改动会产生大量假修订Word COM 自动化10 份以内、Windows 环境中中依赖本机 Office不能跑在 Linux 服务器直接读写 OOXML任意规模、要嵌入系统高最高需要理解 XML 结构边界情况要自己兜商业库Aspose.Words 等企业级、预算充足低高授权费且批注扩展部件的支持深度要实测3.2 Word 原生功能的真实能力边界审阅选项卡里的比较和合并是两个不同的东西很多人用混了。比较选两份文档Word 生成第三份带修订标记的文档把差异全部标出来。这是做版本对比最省事的办法。合并用于多人并行评审。基准稿发给五个人收回来五份用合并依次把每份的修订和批注吸入同一份文档。它要求所有副本都源自同一个基准版本且正文改动不要太离谱。实测下来合并在处理纯批注时表现还行一旦有两个人改了同一个段落的同一句话就会出现嵌套修订展示成红字套红字可读性极差。而且合并结果里批注的已解决状态经常会丢。3.3 python-docx 读不到批注这是个硬伤python-docx是我最常用的库但它对批注的支持长期停留在能读不能写的状态comments.xml甚至不在它的解析范围内。所以只要你涉及批注的增删改就得绕开它用zipfilelxml直接操作 XML。这不是什么高深技术本质就是解压、改文本、重新打包难的是改对地方。3.4 我的实际选择小批量、一次性的活儿我直接用 Word 的比较功能五分钟搞定。批量、反复、要进系统的活儿我用 Python 直接改 XML。原因是可复现——脚本跑一遍和跑一百遍结果一样出了错能定位到具体是哪条批注第几个节点。COM 自动化我基本不用因为一旦要部署到服务器上就抓瞎。4. 合并实操把三个人的批注揉进一份文档4.1 合并前必须做的三件标准化在写代码之前有三件事不做后面全是坑。第一统一作者名。让每个人在自己的 Word 里把用户名设成姓名-部门比如张工-法务。不然合并完你看到五个Administrator发的批注根本分不清谁是谁。这个在 Word 选项里改改完对所有新文档生效。第二约定批注格式。我们团队的规矩是批注必须以[等级]开头比如[必改]、[建议]、[疑问]。这样导出来之后可以直接按等级排序评审会上先过必改项。第三确认所有副本源自同一基准稿。这个可以通过对比docProps/app.xml里的TotalTime或者直接比正文哈希来验证。如果发现有人拿的是上一版直接退回不要硬合。4.2 解包与读取先把批注抽成结构化数据import zipfile from lxml import etree W http://schemas.openxmlformats.org/wordprocessingml/2006/main W14 http://schemas.microsoft.com/office/word/2010/wordml W15 http://schemas.microsoft.com/office/word/2012/wordml NS {w: W, w14: W14, w15: W15} W_ID f{{{W}}}id W_PARAID f{{{W14}}}paraId def load_part(docx_path, part): with zipfile.ZipFile(docx_path) as z: try: return etree.fromstring(z.read(part)) except KeyError: return None def dump_comments(docx_path): root load_part(docx_path, word/comments.xml) if root is None: return [] result [] for c in root.findall(w:comment, NS): paras c.findall(w:p, NS) result.append({ id: c.get(W_ID), author: c.get(f{{{W}}}author), date: c.get(f{{{W}}}date), text: .join(c.itertext()).strip(), last_para_id: paras[-1].get(W_PARAID) if paras else None, }) return result跑一遍三份文档的批注就变成了三个 Python 列表。这一步的价值在于你能先做一次预检——统计每人提了多少条、有没有重复、有没有空批注。空批注只有批注框没内容在合并后会让 Word 显示异常最好提前清掉。4.3 id 重编号与锚点同步这是合并的核心动作。假设主文档最大批注 id 是 7那么从文档的所有 id 从 8 开始顺延。def renumber_comments(src_comments_root, start_id): 把一份 comments.xml 里的 id 重编号返回 旧id - 新id 的映射 mapping {} nxt start_id for c in src_comments_root.findall(w:comment, NS): old c.get(W_ID) new str(nxt) mapping[old] new c.set(W_ID, new) nxt 1 return mapping def apply_mapping_to_doc(doc_root, mapping): 同步 document.xml 中的三个锚点节点 for local in (commentRangeStart, commentRangeEnd, commentReference): for el in doc_root.iter(f{{{W}}}{local}): old el.get(W_ID) if old in mapping: el.set(W_ID, mapping[old])调用顺序不能反。必须先重编号 comments.xml 拿到映射表再拿着映射表去改 document.xml。如果先改正文再改批注中途一旦出错两边 id 就对不上了。4.4 paraId 冲突处理前面说过合并时两个文档的 paraId 撞车是大概率事件。处理方式是收集主文档所有已用 paraId然后给从文档的批注段落重新分配。import random def collect_para_ids(*roots): used set() for root in roots: if root is None: continue for el in root.iter(): pid el.get(W_PARAID) if pid: used.add(pid) return used def new_para_id(used): while True: pid f{random.getrandbits(32):08X} if pid not in used: used.add(pid) return pid重点在于改了批注段落的 paraId就必须同步改 commentsExtended.xml 里的w15:paraId和所有指向它的w15:paraIdParent。这一步漏了回复关系会断已解决状态会飘到别的批注上去。我建议的做法是给每条批注维护一个旧paraId - 新paraId的字典然后拿这个字典去遍历 commentsExtended 里所有属性一次性替换。4.5 重新打包与自检改完之后把内存里的 XML 序列化回去覆盖原 ZIP 中的对应条目def repack(src_path, dst_path, replacements: dict): with zipfile.ZipFile(src_path) as zin, \ zipfile.ZipFile(dst_path, w, zipfile.ZIP_DEFLATED) as zout: for item in zin.infolist(): data replacements.get(item.filename) if data is None: data zin.read(item.filename) else: data etree.tostring(data, xml_declarationTrue, encodingUTF-8, standaloneTrue) zout.writestr(item, data)打包之后一定要做一道自检我固定查这几项检查项判断方式不通过的后果批注总数合并后条数 各文档条数之和少了几条说明 append 漏了id 唯一性所有w:id去重后数量不变Word 报文档损坏锚点完整性三件套 id 集合完全一致批注跑到文档末尾paraId 唯一性全局去重后数量不变回复关系错乱正文哈希与主文档原文一致说明误改了正文实操心得自检脚本要用 Python 的assert写死不要只打印警告。合并这事儿一旦看起来没问题你就不太可能再打开逐条核对而问题往往在别人打开文档时才暴露。5. 对比实操两版批注清单怎么比对差异5.1 先抽清单再谈对比做批注对比的第一步不是写 diff 算法而是把两轮批注都导成结构化表格。列大概是轮次 / 编号 / 作者 / 时间 / 锚点段落 / 批注正文 / 状态。导出成 CSV 或者 Excel先让人肉看一眼。很多差异其实一眼就能解释第二轮多了三条是复审新提的少了两条是因为被标记为已解决。已解决不等于删除如果对比时把已解决项过滤掉了你会发现差异列表长得吓人实际上啥事没有。5.2 匹配策略别指望单一键能搞定两轮之间的批注w:id大概率变了paraId也可能变。我一般用三级匹配第一级durableId 精确匹配。如果两份文档都是 Word 2013 保存的commentsIds.xml里的w16cid:durableId是跨保存稳定的。这一级能捞回大部分原封不动的批注。第二级作者加文本指纹。用作者 规范化后的批注文本算哈希。规范化就是把空白、全角半角、尾部标点统一处理掉。import hashlib, re def normalize(text): text re.sub(r\s, , text) text text.replace(, ,).replace(。, .).replace(, :) return text.strip(.,;:) def fingerprint(author, text): key f{author or }|{normalize(text)} return hashlib.sha1(key.encode(utf-8)).hexdigest()[:16]第三级模糊匹配兜底。批注文字被人改过一两个字的情况很常见这时候用相似度from difflib import SequenceMatcher def best_match(target, candidates, threshold0.82): best, score None, 0.0 for c in candidates: s SequenceMatcher(None, normalize(target), normalize(c[text])).ratio() if s score: best, score c, s return (best, score) if score threshold else (None, score)阈值定在 0.82 是我调了若干次的经验值。调太低会把建议延长质保期和建议缩短质保期这种语义相反的批注配成一对——那比配不上还危险。调太高又漏得多。5.3 差异分类与报告产出匹配完之后差异归成四类这个分类直接决定了后续动作类型含义后续动作新增新版有、旧版无评审会上确认是否采纳消失旧版有、新版无确认是被删除还是被合并进别的批注修改两级匹配命中但文本有差异展示前后对照人工确认状态变更文本没变但 done 从 0 变 1一般无需处理只在报告里标注报告我习惯输出成 Excel一列是上一轮批注一列是本轮对应批注中间一列标注差异类型再加一列留白给评审会现场写结论。用openpyxl写顺手加点底色法务和业务方看着舒服。from openpyxl import Workbook from openpyxl.styles import PatternFill COLORS {新增: FFC7CE, 消失: FFEB9C, 修改: DDEBF7, 状态变更: E2EFDA} wb Workbook() ws wb.active ws.title 批注差异 ws.append([类型, 上一轮批注, 本轮批注, 相似度, 评审结论]) for row in diff_rows: ws.append(row) fill PatternFill(solid, fgColorCOLORS.get(row[0], FFFFFF)) for cell in ws[ws.max_row]: cell.fill fill wb.save(批注差异报告.xlsx)5.4 正文也变了怎么办——批注漂移检测如果两轮之间正文被改过会出现批注还是那条批注但挂的位置变了。这种情况光比批注文本是发现不了的。我的做法是在导出阶段顺便记下每条批注锚定段落的前后各 20 个字形成一个上下文指纹。对比时如果批注文本匹配上了但上下文指纹对不上就在报告里标一个锚点疑似漂移的警告提示人工复核。这个检查加进去之后我们内部评审的返工率大概降了一半——以前总有人的意见被挂到隔壁段落去评审会上才发现。def context_snippet(doc_root, comment_id, radius20): 取批注锚点前后文用于漂移检测 nodes list(doc_root.iter()) start_idx None for i, el in enumerate(nodes): if (etree.QName(el).localname commentRangeStart and el.get(W_ID) comment_id): start_idx i break if start_idx is None: return full .join(nodes[start_idx:start_idx 40]) return full[:radius * 2]6. 常见问题与排查实录6.1 打开提示文档内容有问题这是合并脚本最常见的报错九成出在 XML 层面。按这个顺序排查第一检查 XML 声明。lxml序列化时如果没加xml_declarationTrue和正确的 encodingWord 会直接拒绝。第二检查命名空间前缀有没有丢w14和w15是 Word 特有前缀某些解析器会重命名。第三检查[Content_Types].xml里有没有commentsExtended的 Override 条目——如果你给一份原本没有扩展部件的文档加了commentsExtended.xml忘了补这个声明Word 照样报错。6.2 批注在但点不动、点不到现象是批注框正常显示但点击之后光标不跳到正文对应位置。这几乎可以肯定是commentReference缺失或者 id 对不上。还有一个隐蔽情况commentRangeStart被放在了段落的w:pPr里面。锚点节点必须是段落的直接子节点位置放错了 Word 能渲染但不认交互。6.3 同事用 WPS部件结构和 Word 不一样WPS 保存的 docx 大体兼容 OOXML但有几个差异要注意commentsExtended.xml有可能缺失也就是说已解决状态可能直接丢了commentsIds.xml里的durableId生成规则和 Word 不同部分版本会把w:initials用得很随意。处理办法是不要依赖 durableId 做跨工具匹配老老实实用作者加文本指纹。另外收到 WPS 的文档后第一件事是用 Word 打开另存一次让它把扩展部件补齐。6.4 批注的已解决状态在合并后丢了原因通常是两条一是合并没有处理commentsExtended.xml只合并了comments.xml二是 paraId 被重新分配了但commentsExtended里的引用没跟着更新。第二种更隐蔽因为文档能正常打开只是所有已解决的批注全部变回未解决。这也是我坚持要先建旧paraId - 新paraId字典再统一替换的原因。6.5 问题速查表现象最可能的原因处理方式打开报文档损坏XML 声明错误 / Content_Types 缺条目用 Office Open XML SDK 校验器过一遍批注全部堆在文末commentReference 缺失或 id 不匹配校验三件套 id 集合是否一致批注数量莫名变少直接覆盖了 comments.xml 而非 append检查合并逻辑是 append 还是 replace回复关系错乱paraId 撞车后未同步更新引用重建 paraId 映射表已解决状态全丢未合并 commentsExtended.xml补齐该部件并更新 Content_Types作者名显示为乱码XML 编码不是 UTF-8序列化时强制指定 encoding点击批注无跳转锚点节点放在 pPr 内移到段落直接子节点层级一个独家避坑技巧合并前先把所有输入文档用 Word 打开、另存为新 docx再做处理。这一步能把大量格式不规范的历史文档洗成统一结构后面的脚本会稳得多。听起来很土但省下来的调试时间远超这几分钟。7. 我在实际项目里摸索出的流程建议做了几年文档评审的自动化我现在的标准流程是这样的评审开始前把基准稿的批注全部清空、作者名统一格式、等级标签规则写在封面页上评审过程中所有人只在自己那份上加批注禁止直接改正文需要改的话走修订收回来之后先跑一遍预检脚本统计条数、查空批注、验正文哈希然后合并、自检、输出带等级排序的批注清单评审会上按清单过一遍结论直接写在批注回复里最后用对比脚本生成两轮差异报告作为过程留痕归档。这套流程里最值钱的其实不是脚本而是禁止直接改正文这条规矩。一旦有人既改正文又加批注合并的复杂度会指数级上升因为你要先解决正文合并才能解决批注合并。把这两件事物理隔离开整个链条就简单了。还有一个小技巧分享一下批注等级标签如果写成[必改]、[建议]、[疑问]这种方括号前缀导出到 Excel 之后用个正则就能拆成独立列排序、筛选、统计一次到位。比事后人工分类靠谱得多也不增加评审人的负担——多打四个字符而已。
