用途与实际影响
这项功能怎样使用
为什么需要它
文件名、目录和拍摄时间不足以判断裁切版、连拍、截图、模糊图和更好版本的关系；纯哈希也只能发现字节完全相同。
举个实际例子
我可以问：“这批截图哪些值得留，哪些只是缓存、重复图或已经有更完整版本？”系统会先整理重复关系，再把少量候选放在一张联系表里一起判断，交回保留或退出的理由。
最后我会得到什么
每张图片或每段视频都有明确的保留或移出决定、分类、时间、说明和重复依据。照片精选没有数量配额，普通视频不另设精选目录。整理后核对原件位置、查找目录和后续恢复计划是否一致；实际备份、写回手机和上传云端各自另报结果。
成功时
本批每份不同内容都已看过并作出完整决定；保存分类后，留下的原件能找到，目录与手机、云端的后续计划也对应正确。计划准备好不等于已经传到手机或云端。
发现问题时
画面看不清、近重复关系不确定、唯一性或恢复责任未证明时保留原件/候选并只打开少量原图复核。
入口不可用时
打不开文件、缺少看图依据或本批没有审完时，不应用整理决定。分类还没保存就失败时，撤回本批未完成的记录和新建链接；分类已保存、但后续清单更新失败时，保留原件和已保存分类，说明哪些清单还要补齐，不能说整批已经全部撤回或全部完成。
从哪里开始
把一小批已取得的照片或截图交给 AI，问哪些要留、分类或待复核。
需要准备什么
- 本批可打开原件
- 本人已有的保留或精选选择（如有）
从开始到拿到结果
- 1
系统核对并处理
排开缓存和完全重复，再比较画面意义、质量与更完整版本；逐件给出保留、退出或待复核理由。
- 2
交付与接续
完整决定应用后更新目录与本地计划；跨批近重复和看不清的对象保留，备份、手机及云各自验收。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
当前3,601项照片/视频，照片六入口含910项精选；普通视频平铺视频根，特殊视频独立一层；实体归位已由来源Owner确认关键规则与设计选择
照片采用精选、生活与回忆、收藏与作品、资料原图、证件、色情图片六入口；现已完成六入口归位，新增证件独立入口；资料原图不是无意义截图兜底库。
保留的色情图片全部进入本地手机包，色情视频不进，普通视频按需选择；这三种规则不混成统一keeper资格。
精确重复退出仍要核对唯一性、引用和恢复责任。
高度近重复是视觉判断，不由相似分数自动删除。
照片精选不设上下限；好看、独特回忆或不可替代价值须有实际依据。本人手筛的图片及全部视频留下者保留，不用精选门槛二次淘汰。
照片精选只移动原件、不复制；普通视频归视频根，不再设精选视频入口。本人手筛留下者优先保留；目录归位已由本地Owner确认，改名和移动不计瘦身。
phone-apply 的 near_duplicate_of 只允许本批 group，并要求指向本批 keeper；不能直接把新文件关联到既有 catalog（目录） keeper。
跨批近重复需要另行人工核对并通过现有精确入口处理，当前没有同等自动关系命令。
默认小批量快速路径只适用于不超过 100 个可打开对象；每张联系表最多 25 个，只重验本批变化。超过 100 时重新按真实规模规划，不能沿用 4 分钟目标。
分类完成前不把移动到根目录称为完成。
“色情图片”“色情视频”两个分类身份公开保留，具体个人载荷与当前数量逐值处理。
本模块用到的名词
- Occurrence（出现位置）
- 同一内容在来源或暂存中的一个路径；多个 occurrence 不等于多个不同原件。
- Primary / secondary（主类 / 次级主题）
- 主类决定主要浏览入口；截图等对象还可保留一个真实次级主题。
- Native visual review（原生视觉复核）
- 直接根据联系表和必要原图判断画面，不从文件名或元数据猜内容。
专业定义
分类不是把文件移动到一个目录；它必须说明画面是什么、是否值得留、哪个版本更好，以及退出后还能从哪里恢复。
解决什么
解决精确重复、裁切/连拍近重复、缓存、模糊失误、类别混乱和只移动不理解内容。
当前怎样实现
- 机械预检按 SHA-256 合并 occurrence 并检查可打开性与技术缓存。
- contact sheet（页面总览图） 每张最多 25 个对象，避免逐文件重复工具调用。
- review.json 要求 PASS_NATIVE_VISUAL_REVIEW 并精确覆盖本批唯一哈希。
- phone-apply 在 SQLite commit 前异常时 rollback 并清理本批新 E/G hardlink（硬链接）；commit 后再原子刷新 current（当前状态） seed、phone plan、cloud plan 与 receipt（执行回执），这些文件之间不构成单一事务。
- 只对联系表看不清的个别原图单开。必要文字承接复用所属领域与理解/表达库的既有入口，不复制中央库；正式原件退出、手机包派生退出、旧ZIP/硬链接路径清理与物理空间释放分别记录。本次本地整理与最终媒体状态G/H已由Owner收口；后续退出仍按当批实际字节与引用单独验收，不从旧成功回执推定新批次完成。
- named_album支持本人选择的照片相册，名称1–120字符且拒绝路径分隔、控制字符与无效文件名字符；只用于image，不改变现有category。命名关系进入同一目录、手机恢复Images布局和云相册期望，不创建第二数据库或媒体副本。
执行流程
- 1
机械预检
- 2
合并 occurrence
- 3
隔离技术缓存
- 4
生成联系表
- 5
一次视觉决定
- 6
补看少量原图
- 7
事务应用
- 8
增量验证目录与计划
边界
- 不从路径或文件名猜人物与画面。
- 不把相似度分数当删除授权。
- near_duplicate_of 只编码本批内关系；跨批近重复仍是独立缺口。
- ≤100 个可打开对象才进入默认小批量快速路径；超过后不冒充 19 图/4 分钟验收。
- 不重复审计未变化的完整媒体库。
- 不为一批媒体增加模块、schema（数据结构） 或长期服务。
失败与恢复
- 对象不可打开
- 标记缺口并保留来源，不自动当成无意义内容退出。
- review 漏掉唯一哈希
- phone-apply 在写入前整体拒绝，不留下分类。
- catalog（目录） 已提交但 seed/phone/cloud refresh 中断
- 保留已验 canonical/G keeper 与 catalog（目录）；用 current（当前状态） seed/candidate receipt（执行回执）/plan-status 识别哪一面陈旧，重跑 refresh 与 acceptance，不回删已提交原件。
- 近重复没有明确更好版本
- 两者都保留或进入待复核，不以容量为由强删。
- 新对象疑似与既有 catalog（目录） keeper 跨批近重复
- phone-apply 不直接写该关系；保留新对象与证据，另行打开既有 keeper 做人工比较，再选择精确接入/退出路线。
- 小批量超过速度目标
- 停止扩写工程，报告真实外部/工具 blocker；不再加回执或全库扫描。
真实入口
personal_media.pyphone-prepare、phone-apply、分类与事务
AGENTS.md小批量快速路径与反膨胀边界
test_personal_media.py查询、plan_status、ingest-file 与 recovery-sync 回归；当前仍没有直接 phone_apply fault-injection 用例
如何验证
- 审查时既有测试没有直接调用 phone_apply；review 全覆盖、pre-commit rollback 与 post-commit refresh 目前按源码和历史批次证据说明，专项 fault-injection 回归仍是缺口。
- 历史2026-08-25增量把 118 个 occurrence 收敛为 63 个唯一哈希并完成视觉治理。
- 19 张普通截图从双盘保全到可检索的产品目标低于 4 分钟。
与其他模块的关系
它决定什么进入当前目录；查找消费 keeper，手机与恢复模块分别提供来源和后续恢复责任。