用途：在用户要求检查重复办公文档时，用 dupey 找出文档家族、解释分组原因，并准备安全的整理方案。它基于格式感知提取后的规范化文本做词法重叠检测，不使用语义嵌入，也不会删除文件。
安装与检查：先运行 dupey --version；若缺失则运行 cargo install dupey。
扫描与比较：用 dupey scan PATH --json 获取可决策的 JSON 结果；仅在调查特定文件对时用 dupey compare FILE_A FILE_B。除非用户明确要求更宽或更窄的搜索，否则保持默认阈值，并在最终报告中记录任何非默认阈值。
结果含义：exact 指提取出的规范文本 SHA-256 哈希相同；对无可比文本的文件（如纯图像 PDF），exact 要求原始字节完全相同。near 指通过精确词法重叠验证，默认要求 5-gram 集合的 jaccard >= 0.90，应视为高度重叠的版本而非可丢弃的证明。contains 是方向性证据，a 为容器、b 为被包含文档，默认要求 containment >= 0.96 且 jaccard >= 0.40。mixed 是家族级标签，家族是连通分量，可能具有传递性，不能假定家族内每对文件都直接匹配。
最新候选：pick.ranked[0] 只是候选而非权威结论；排序优先使用文档内部修改时间，否则用文件系统修改时间；文件名、修订号、包含方向和文档长度不影响评分。唯一最新时间戳得分为 1.0、置信度 0.9；时间戳并列或不可用时置信度为 0.5，此时排序不应视为最新版本的有效证据。
整理流程：扫描用户指定目录并报告所有提取错误（出错文件属于未分类而非唯一）；总结每个家族并引用支撑它的边；对 exact 文件结合用户偏好与非文本属性确定保留者；对 near 和 contains 在提议删除前检查或对比内容，若改动可能是有意为之则倾向都保留；给出具体计划（保留、重命名、移入复核/归档或删除）；删除、覆盖或移动前必须获得用户明确批准，仅要求“查找”或“分析”不构成删除授权；优先采用可逆整理；获批变更后再次扫描并报告剩余家族与错误。不得基于家族标签、高分、文件名或 pick.ranked[0] 自动删除。
报告应面向决策：扫描路径与阈值、提取错误、家族成员、直接边证据及其正确含义、最新候选置信度与时间戳来源、建议保留者及理由、建议的可逆操作、变更后扫描结果。