Compare Files Viewer 是一个原生 Mac 结果查看器，用来展示快捷指令或其他工具生成的文件比较报告。
目录里同时出现“最终版”“最终版 2”“修改后最终版”时，真正想知道的往往是：它们是什么关系，应该先打开哪一份？如果报告还能展示路径、时间、哈希或文字差异，判断就会更有依据。
Compare Files Viewer 负责把这些结果放进原生窗口。它本身不执行文件比较，需要上游工具先分析，再传入结构化报告。
从源码构建查看器
项目要求 macOS 14 或更新版本，以及 Xcode Command Line Tools，目前没有 GitHub Release 安装包。
下载源码，在项目根目录执行：
|
|
生成的可执行文件位于 .build/release/。可以先打开仓库提供的示例：
|
|
示例中的路径不一定存在于自己的 Mac，它只是展示报告格式，不会比较你的实际文档。
第一次打开示例时，可以先看“建议主版本”和文件顺序，再展开详情找支持这个判断的证据。这样能先熟悉窗口，再决定是否值得把自己的比较流程接进来；运行示例不会读取你文件夹里那些叫“最终版”的文档。
一份报告可以展示什么
输入包含 files、analysis 和可选的 local_evidence。根据上游提供的数据，界面可以显示：
- 整体关系、置信度与建议的主版本。
- 版本顺序，以及每份文件的路径、大小和修改时间。
- Finder 图标、在 Finder 中显示等操作。
- 本地 SHA-256 元数据、文字差异或图像比较依据。
应用支持中英文，也提供详情页帮助检查结论。但这些字段是否可靠，取决于上游比较过程。没有哈希不代表内容不同，AI 分组也不能直接当作字节完全相同的证明。
例如两份报告可能只差一个数字。修改时间较晚的那份可以先打开，但真正决定保留哪份的是具体差异和文件来源；如果上游只给出日期，没有提供文字差异或哈希，查看器也无法凭空补出证据。
接入自己的比较工作流
应用支持 --file 读取 JSON 文件、--json 接收文本，以及从标准输入读取结果。编写快捷指令或脚本时，可以用 ExamplePayload.json 对照字段。
仓库提供查看器源码和 ExamplePayload.json，但没有可直接导入的 Compare Files.shortcut 文件。想比较自己的文件，需要先准备能生成这种 JSON 报告的快捷指令或脚本；只打开查看器不会开始比较。
如果已经有一套文件比较流程，只是想把长文本报告换成更清楚的原生窗口，这个项目会更合适。
按一个具体例子读懂报告
仓库示例把 report.pdf、report-v2.pdf 和 report-final.pdf 放在同一组。它列出了建议主版本和先后顺序，还给出“增加章节”“页数变化”这样的说明。读的时候先看三份文件是否真的属于同一个主题，再看后两份与前一份具体差在哪里；不要从名字里有 final 就直接跳到保留决定。
接着展开详情，对照文件路径、大小和修改时间。下载目录里的一份“最终版”，可能只是别人重新发送的旧稿；云盘中的另一份文件，也可能包含尚未并入主稿的批注。路径能告诉你材料从哪里来，差异才能告诉你内容是否值得保留。这两类线索放在一起，才有助于处理实际工作里的版本混乱。
示例中的哈希值带有省略号，路径也使用演示账户，因此它适合熟悉界面，不能拿来证明本机文件的关系。如果想看自己的结果，需要让上游工具读取自己的文件并输出完整数据。更改示例里的文件名，只会改变报告内容，不会触发重新分析。
哈希、文字差异和建议分别说明什么
完整的文件哈希适合判断两个文件的字节内容是否一致。文字哈希针对提取后的文字；两份 PDF 的文字相同，页面布局、批注或内嵌图片仍可能不同。因此，看到“文字相同”时，应先确认自己关心的是正文，还是整个文件的全部内容。
文字差异也可能只是节选。示例里有新增行数、删除行数和部分样本，并标记样本被截断。遇到这样的报告，可以先用节选定位变动区域，再打开原文件确认上下文。比如只看到新增了一个数字，不知道对应的是金额、日期还是页码，就还不能据此选择版本。
建议主版本属于汇总判断，适合帮助决定阅读顺序。对带批注的合同、带修订记录的文稿，或者不同格式的导出件，最好保留原有分工：一个用于继续编辑，一个用于最终发送。文件有不同用途时，不必强行选出唯一版本。
自己接入时，从 JSON 文件开始
第一次接入，优先让脚本先把结果保存成一个 JSON 文件，再用 --file 打开。这样报告不对时，可以回头查看输入，而不必同时调试文件分析和窗口显示。等文件方式稳定后，再考虑用标准输入串成一步操作。
以仓库的 ExamplePayload.json 为结构参考：files 放文件清单，analysis 放关系与建议，local_evidence 放实际取得的比较依据。缺少的证据就明确缺少，不要用看似合理的文字填充。文件路径也应对应真实文件，才能让“在 Finder 中显示”有用。
如果启动后出现读取或解析错误，先核对命令指向的文件是否存在、内容是不是有效 JSON，再检查字段结构。特别要区分 JSON 文件路径和报告内原始文件路径：前者负责打开报告，后者负责定位被比较的材料。两层路径都正确，界面才能帮你回到真正需要检查的文件。
建议主版本，不等于可以直接删其他文件
修改时间不一定代表内容新旧。复制、导出都会影响日期，两份文件之间也可能只有很小、却关键的差异。
可以把建议版本当作阅读起点：先打开，再核实重要差异，确认关系以前保留原文件。查看器不合并文档，也不应该成为自动删除其他版本的依据。
应用本身不发送网络请求或上传文件；如果上游使用 AI，隐私与内容处理方式由上游决定。
陌生格式先看 What File Is This，确定保留版本后再考虑 Auto Filename Helper 的命名流程。接入入口见 README 与示例 JSON。