用途与实际影响
这项功能怎样使用
为什么需要它
一份文件可能来自电脑，也可能是同一段画面和声音的另一种文件封装。全部当新作品会重复保留；还没核对就删除，又可能丢掉唯一的完整版本。
举个实际例子
我可以说：“这个本地 MP4 看起来只是现有视频的另一种封装，核对后再接入，别重复保存两份正式原件。”系统会比较实际视频内容；确认相同后只把变体留作恢复材料并记录关系，无法确认就不动来源文件。
最后我会得到什么
新的保留内容在媒体原件目录落位，并在 G 盘留下恢复副本，查找目录和后续手机、云端计划随之更新。确证重复的视频变体会保留恢复副本和与主版本的对应关系，再退出原暂存位置。失败时说明已保存了哪些文件、哪一步还没完成。
成功时
原文件仍是之前确认的那一份、目标也没有冲突；媒体原件与 G 盘副本检查一致，查找记录和后续恢复计划已更新，再说明原暂存文件的处理结果。
发现问题时
分类、时间、主版本或视频重复关系还不能确认时，先保留文件，指出需要补看的画面或信息，不猜一个归属后直接接入。
入口不可用时
暂存文件与媒体目录不在同一磁盘，或视频检查工具、原件目录、G 盘、目标位置及计划更新不可用时，停止对应步骤并报告已有副本。目前不会临时改成跨盘复制、手机批次处理或自动上传。
从哪里开始
点名一个已人工复核的本地照片、视频或录音，请 AI 接入媒体中心。
需要准备什么
- 明确源文件与预期内容
- 类别和说明
- 视频容器变体才需指明既有主版本
从开始到拿到结果
- 1
系统核对并处理
核对类型和字节；新原件写入正式目录与异卷恢复副本，容器变体先证明内容等价才记录关系。
- 2
交付与接续
交回目录、来源退休、手机与云候选的结果；哈希、卷或主版本不符时保留源文件。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
ingest-file强制--execute；普通输入在canonical根外，新增--register-existing可将媒体根内明确原件就地登记，不能同时退休等价变体。本轮只核对正式代码，未执行真实接入关键规则与设计选择
命令必须显式 --execute；没有只写计划后自动接入的后台路径。
整理顺序在新增、复查和续作中相同：无意义退出，精确/高度近重复择优，再按全库统一严格标准判断精选；不因一批新媒体要交付就凑精选。
裁剪、压缩、水印、边框和轻微界面变化不自动构成独立价值；不同凭据状态、重要文字或场景信息仍须保留。
普通输入须在E媒体中心之外并可与目标建hardlink（硬链接）；--register-existing仅对中心内已选择原件就地登记，不能退休等价变体。两者均不支持C/G异卷source直接接入。
新 keeper 需要 category；日期可明确选择，也可保留时间未知。普通新增默认不进入手机包，明确 --phone-recovery 与 --phone-recovery-reason 才赋予普通内容手机资格。
等价视频变体必须绑定现役 keeper SHA-256，并证明 demuxed video stream 完全相同。
ingest-file刷新本地目录、手机计划和云端期望候选；这一个命令不调用云提供者，后续cloud-sync负责实际上传。普通keeper不自动增加手机项，录音不进入手机包。
SQLite 与 E/G 文件动作不是一个跨文件系统原子事务；入口逐层 read-back（正式回读），但中断后仍要按现存副本和 receipt（执行回执） 恢复。
本模块用到的名词
- Independent local increment（独立本地增量）
- 不属于手机 capture、但已经明确选择的单个媒体文件。
- Demuxed video stream（解复用视频流）
- 从容器中抽出的实际视频流哈希；相同才支持‘只是容器不同’的等价判断。
- Content-equivalent variant（内容等价变体）
- 字节和容器不同，但已证明视频流与现役 keeper 相同；保留恢复副本和关系，不再作为第二个 keeper 浏览。
专业定义
手机不是唯一入口。一个已经人工看过的本地照片、视频或录音，可以单独接入；同一视频流的另一种容器也能保留恢复副本后退出浏览库。
解决什么
解决非手机本地新增、一次性脚本膨胀、同视频流容器重复、源文件退休无恢复副本和目录/恢复计划不同步。
当前怎样实现
- 解析source并核对E同卷；普通路线拒绝canonical根内文件，--register-existing则要求原件已在媒体根内且不与等价变体参数并用。计算size/SHA-256，expected_sha256存在时必须匹配；就地登记保留原件路径。
- ffprobe 判断 video/audio；新 keeper 用 category、secondary 和可选 formation-date 选择 canonical 目录。
- 新 keeper 用 os.link 在 E canonical 建 hardlink（硬链接），因此 source 必须与目标同卷；随后向 G 精确复制并回读，事务写入 media/meta 后退休 source。
- 等价变体先核对 keeper 当前存在、keeper E/G SHA-256 与两边 demuxed stream；再把变体精确复制到 G Variants、记录关系、退休 source 并更新 retired 状态。
- 两条路线都刷新 current（当前状态） seed 与 product candidates，写最小 ingest receipt（执行回执）；cloud_upload 固定为 0。
- update-entry按单一SHA-256与--execute定位已登记keeper，可更新具名相册、本人确认地点/日期和既有恢复资格。地点标记为user_confirmed，可靠日期校验时区与实际日期；更新SQLite、种子和候选后返回external_provider_calls=0。云端执行、手机文件写回及新增原件保全分别处理。
执行流程
- 1
选择一个已复核 source
- 2
绑定预期哈希和说明
- 3
探测媒体类型
- 4
选择新 keeper 或等价变体合同
- 5
E/G read-back（正式回读）
- 6
写目录与关系
- 7
退休 source
- 8
刷新 seed 和两套候选
- 9
写 receipt（执行回执）
边界
- 不批量扫描目录。
- 普通暂存接入不接受canonical根内文件；已在媒体中心的明确原件可以 --register-existing 就地登记，不移动原件。
- 新 keeper 不支持跨卷 source copy fallback（后备路线）。
- 不靠文件名宣布视频等价。
- 不把 --execute 扩张成云上传或手机删除授权。
- 不声称跨 E/G/SQLite 的绝对原子回滚。
失败与恢复
- 输入 SHA-256 与预期不同
- 在创建 canonical/G/目录状态前失败，要求重新确认当前字节。
- 新 keeper source 与 E canonical 不同卷
- os.link 失败并保留 source；当前先把已复核文件放到 E 卷明确暂存位置再重试，不能把异卷 copy 说成已支持。
- 新 keeper 没有 category 或目标已有不同字节
- 拒绝接入，不覆盖目标，也不退休 source。
- 等价 keeper 不存在、E/G read-back（正式回读） 失败或视频流不同
- 不建立等价关系，不复制/退休变体。
- 目录提交后 seed/候选刷新失败
- 保留已经读回的 canonical/G 字节和具名失败位置；按当前目录与 receipt（执行回执） 恢复，不把部分状态冒充完整收口。
真实入口
personal_media.pyingest-file、新 keeper、等价容器变体、seed 与候选刷新
test_personal_media.py隔离临时根中的新 keeper、E/G、catalog（目录）、来源退休、候选刷新与等价视频容器专项回归
README.md精确命令、输入、回读、半状态恢复与依赖说明
如何验证
- 源码和 README 均要求 --execute、一个 source、description 与可选 expected SHA-256。
- 专项回归证明新 keeper 的 E canonical、G 副本、catalog（目录）、source 退休、current（当前状态） seed、手机计划和 cloud plan 同次刷新。
- 专项回归证明等价视频的 E/G keeper、相同 demuxed stream、G 原始容器变体、关系写回和 source 退休。
- 2026-09-05 的 personal-media-current-acceptance.v1 运行 55 项测试、0 失败/错误，并闭合当时代承诺；不继承为后来 Git 元数据能力的完整回归。
与其他模块的关系
它是手机之外的单文件入口；完成后仍回到同一个当前目录、手机恢复候选和云端期望集合；实际云同步仍由同项目的cloud-sync完成，不建立第二套媒体库。