💡 完整可运行示例可在 GitHub 上获取：
document-version-metadata-diff-python

What You’ll Build

在本指南中，你将比较文档两个版本之间的每个元数据属性，并准确打印出哪些被添加、删除或更改。元数据版本差异是对同一文件两个修订的属性级比较，它能够捕捉文本比较永远看不到的信号：新的 Creator、递增的 RevisionNumber、审阅结束后记录的编辑会话。完成后，你将拥有一个可运行的解决方案，外加两个专注的检测器和两种导出格式，所有代码均来源于包含示例修订对的可运行仓库。

技能水平：中级 Python 开发者
所需条件：Python 3、pip，以及同一文档的两个修订版本

我第一次运行此脚本时，标记出了一个团队成员都不记得修改过的 Company 值变化；正是这行代码为整个设置买单。下面的所有内容均可直接复制粘贴，且总行数远不足百行。

整个流水线刻意保持乏味：打开两个文件、三个字典推导、一次打印循环。乏味正是目的。版本争议的决定依据是方法是否可解释且可复现，而如此小的脚本可以让任何质疑者完整阅读。

1. 安装

pip install groupdocs-metadata-net==26.5

配套仓库固定了此版本，并提供 document-v1.docx 与 document-v2.docx，因此下面的代码可直接运行。请锁定你审计时使用的版本；可复现性是证据的一部分。

2. 核心代码

读取两个属性树，然后使用集合逻辑对差异进行分类。这就是完整的 diff 实现：

# Flatten a file's complete property tree into a dict
def read_props(path):
    props = {}
    with Metadata(path) as metadata:
        for p in metadata.find_properties(lambda p: p.name is not None):
            props[p.name] = (str(p.interpreted_value) if p.interpreted_value is not None
                             else (str(p.value) if p.value is not None else ""))
    return props

v1 = read_props("resources/document-v1.docx")
v2 = read_props("resources/document-v2.docx")

# Classify every key; changed entries keep both values
added = {k: v for k, v in v2.items() if k not in v1}
removed = {k: v for k, v in v1.items() if k not in v2}
changed = {k: (v1[k], v2[k]) for k in v1 if k in v2 and v1[k] != v2[k]}

print(f"added={len(added)} removed={len(removed)} changed={len(changed)}")
for k, (old_v, new_v) in changed.items():
    print(f"  {k}: {old_v} -> {new_v}")

这就是你所需的最小实现。对真实的修订对计数通常很少；如果差异达到数十，通常意味着文件在途中经历了模板更改或存储迁移。接下来的章节会解释关键调用，并展示团队最先添加的自定义方式。

3. How It Works

  • Metadata：打开文件的上下文管理器，退出时自动释放；每个修订对应一个实例。
  • find_properties：一次遍历内置字段、自定义属性和 XMP，返回所有满足谓词的属性。
  • interpreted_value：属性的人类可读形式；优先使用它可以让日期和枚举以可打印的字符串比较。
  • 以合格名称作键：内置字段和自定义字段在字典中不会冲突，集合逻辑因此保持安全。

这里并未解析 DOCX 结构。产品文档列出了 170 多种格式共用同一调用，因此相同脚本同样适用于 PDF 或 XLSX 对。

设计的另一值得一提的特性是：API 边界止于两个 read_props 调用。其后的所有代码都是标准库 Python，所以单元测试、阈值判断和告警规则永远不触及文档层。将此包装成服务的团队通常会为每个修订缓存提取的字典，并让下游检查复用它们，从而无论有多少查询，只需每个版本打开一次文件。

4. 常见自定义

仅检测所有权变更

当问题是“谁触碰了这个文件”时，可在读取时使用标签谓词过滤，而不是在完整 diff 之后再过滤：

# Identity fields only, whatever the format calls them
def read_ownership(path):
    result = {}
    with Metadata(path) as metadata:
        props = metadata.find_properties(lambda p:
            Tags.person.creator in list(p.tags)
            or Tags.person.editor in list(p.tags)
            or Tags.person.manager in list(p.tags)
            or Tags.corporate.company in list(p.tags))
        for prop in props:
            result[prop.name] = (str(prop.interpreted_value)
                                 if prop.interpreted_value is not None
                                 else (str(prop.value) if prop.value is not None else ""))
    return result

对这两个字典运行相同的差异循环，使用 <missing> 作为默认值，这样即使字段消失也会被捕获。谓词不指向具体字段，这正是让单个检测器能够服务所有库读取格式的关键。

跟踪编辑时间线

将谓词换成 Tags.time 加上计数器名称规则，检测器即可报告 RevisionNumber、TotalEditingTime 与 LastPrinted 的变动：

props = metadata.find_properties(lambda p:
    Tags.time.modified in list(p.tags)
    or Tags.time.created in list(p.tags)
    or Tags.time.printed in list(p.tags)
    or (p.name is not None and ("Revision" in p.name
        or "EditTime" in p.name or "EditingTime" in p.name)))

导出审计报告

仅在控制台输出的发现会随之消失。下面的四列 CSV 能满足电子表格和 SIEM 案例的需求：

with open("output/diff.csv", "w", encoding="utf-8", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["change_type", "property", "old_value", "new_value"])
    for k, v in added.items():
        writer.writerow(["added", k, "", v])
    for k, v in removed.items():
        writer.writerow(["removed", k, v, ""])
    for k, (old_v, new_v) in changed.items():
        writer.writerow(["changed", k, old_v, new_v])

仓库还提供了一个 JSON 导出器，采用稳定的三映射结构，便于仪表盘和案件管理 API 使用。

实际运行场景

三种部署方式层出不穷。摄取流水线会将每个到达的文档与已有副本进行 diff，并对身份变更的配对进行隔离。合规作业按计划运行 diff，并为每对文档归档 CSV，构建无人需要事后重建的属性时间线。争议工具则按需运行两个检测器，因为当出现索赔时，首要问题始终是“谁触碰了文件以及何时”，而不是第四段的文字改动。

第四种模式是将文件与其最近一次已知良好快照进行 diff，代码复用相同，只是把一侧的字典换成已存储的快照。在所有场景中，导出文件才是交付物；控制台输出仅作进度噪声。脚本的退出码模式遵循仓库的 main.py，因此调度器和 CI 能把断言失败直接视为运行失败，无需额外包装。上述所有场景均未使用超出本页展示的代码。

什么算是值得标记的更改？

任何被 diff 分类出的项加上你自行添加的上下文都算。新增和删除的属性始终值得关注，因为它们意味着结构发生了变化，而不是单纯的值变动。对于已更改的条目，大多数团队首先对身份和修订组发出警报，其余则视为信息性。检测器的存在正是为了让首次检查只需一次函数调用。

5. 快速参考：关键调用

调用 功能说明
Metadata(path) 打开文件；上下文管理器负责释放
find_properties(predicate) 返回所有满足谓词的属性，跨越所有层级
p.interpreted_value 人类可读值；若无则回退到 p.value
Tags.person.* / Tags.corporate.company 身份分类，独立于格式
Tags.time.* 时间戳分类，用于修订检测器

请参阅完整 API 参考，了解全部搜索和标签功能。标签词汇远超此表；origin、content、legal 等标签组同样使用相同的成员测试方式。

6. 常见问题与解决方案

diff 结果庞大，像噪声
→ 两个路径可能并非同一文档的修订。解决办法：在 diff 前验证来源；不相关的文件会产生毫无意义的差异。

所有权检测器中从未出现的已知作者字段
→ 某些生产者将身份信息存放在未标记的自定义字段中。解决办法：先完整 diff 一次，找到真实字段名，然后在谓词中加入名称规则。

控制台显示评估模式警告
→ 未找到许可证文件。解决办法：在 main.py 中将 LICENSE_PATH 指向你的 .lic 文件，或在开发阶段保持评估模式；逻辑完全相同。

日期以原始序列号形式打印
→ 某处不小心使用了原始 p.value。解决办法：保持 read_props 中先使用 interpreted_value 的写法，这正是报告保持可读性的原因。

接下来做什么？

你已经拥有了可运行的元数据 diff。接下来可以这样继续：

  • 批量化：遍历文档对并为每对生成 CSV；每对的成本仅为两次文件打开，CSV 可直接拼接形成全库视图。
  • 调度执行：仓库的 main.py 对每一步进行断言并返回正确的退出码，能够直接接入 CI 或调度系统。
  • 学习教程版本：阅读用例指南，其中提供了三个分级教程，逐步构建相同流水线。
  • 查看完整项目：访问document-version-metadata-diff-python，其中包含示例修订对。

资源