💡 完整可运行示例已在 GitHub 上提供：
document-version-metadata-diff-python

What You’ll Build

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

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

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

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

1. Install

pip install groupdocs-metadata-net==26.5

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

2. The Core Code

读取两个属性树后，使用集合逻辑对差异进行分类。这就是完整的 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. Common Customizations

仅检测所有权变更

当问题是“谁触碰了此文件”时，可在读取阶段使用标签谓词过滤，而不是在完整 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 使用。

Where This Runs in Practice

目前常见的三种部署方式：

  1. 入口流水线：对每个新到达的文档与已有副本进行 diff，若出现身份变更则将该对隔离。
  2. 合规作业：按计划运行 diff，并为每对文档归档 CSV，构建无人需要后期重建的属性时间线。
  3. 争议工具：按需运行两个检测器，因为当争议出现时，首要问题总是“谁何时触碰了文件”，而不是段落四的具体改动。

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

What counts as a change worth flagging?

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

5. Quick Reference: Key Calls

Call What It Does
Metadata(path) Opens the file; context manager handles release
find_properties(predicate) Returns every property the predicate accepts, across all layers
p.interpreted_value Human-readable value; falls back to p.value
Tags.person.* / Tags.corporate.company Identity classification, format-independent
Tags.time.* Timestamp classification for the revision detector

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

6. Common Issues & Fixes

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

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

控制台出现 evaluation-mode 警告
→ 未找到许可证文件。解决办法：在 main.py 中将 LICENSE_PATH 指向你的 .lic 文件，或在开发阶段保持评估模式；逻辑保持不变。

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

What’s Next?

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

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

Resources