用途与实际影响
这项功能怎样使用
为什么需要它
本地候选不是账号侧备份，上传了字节也不等于已经进入正确相册。网络中断后若把未知对象当作没上传，或在旧相册消失时直接重建，容易产生重复和错误外部状态。
举个实际例子
我说“先看看这批整理后的照片和录音上云还差什么”。系统预览Photos与Drive各自工作，不调用上传；进入获准云阶段后再按选定范围执行，遇到已建相册消失就明确暂停相关部分，不擅自重建补传。
最后我会得到什么
得到本地期望集合、云对象、相册关系与实际执行结果的分层说明。旧候选清单仍可只读查看；云端全量、真删除/重传和手机回写是否完成分别以对应实测为准。
成功时
预览返回选定范围与待办而不调用提供者；获准执行时分别记录对象和相册关系结果，已上传对象先补关系，再处理新字节。
发现问题时
部分成功、配额暂停、对象身份未知或已建相册异常消失时保存精确缺口，不把整批当成功，也不盲目重传。
入口不可用时
本地期望不完整、来源不可读或现有PCConfig提供者不可用时，只停止受影响步骤；不猜账号、不另建云入口，不让云故障改动本机原件。
从哪里开始
说明要预览或同步哪类媒体到既有 Google Photos 或 Drive。
需要准备什么
- 要同步到 Photos、Drive 或两者的选择
- 需要的相册关系和超出现有授权的范围（如有）
从开始到拿到结果
- 1
系统核对并处理
先形成本地期望；预览只计算差异，独立执行入口才逐项处理云对象、相册关系和退出。
- 2
交付与接续
按真实远端回读说明对象、关系和播放状态；本地 synced 只代表本地记录，失败先核对已有对象再续作。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
当前4358项云端映射来自本地已提交状态；本轮未重做远端回读、播放或手机验收关键规则与设计选择
9月13日首轮4230项云上传分类有完整回读，随后新增照片和具名相册已有本地映射及来源记录。本网页不重新上传或删除；当前播放和手机回写依各自真实回执，不用本地synced升级证据。
后续已获准范围内的正常云增量不逐批重复索要批准；扩大来源、账号或公开面仍按真实授权处理。
照片/视频走Photos恢复集与其他归档，PSD排除且不另投Drive或自动转码；两类色情保留内容全部归云端恢复集的同名相册，不按季度拆。录音走Drive音乐/录音，音乐和铃声走已有音乐根；音频不进手机包或Photos，文档不在本次媒体上云范围。旧Photos清除不顺带删除Drive音频。
本地保留、手机资格与云端资格分别判断，不能用一个keeper标记自动填满所有集合。
可信原件删除仍由现有本地维护收敛候选；云端真实删除不是本地索引删除的同义词。
旧upload=0字段只说明对应本地候选观察，不证明后续账号侧从未发生上传。
本模块用到的名词
- Cloud candidate（云端候选）
- 本地计划，不等于目标账号已有字节。
- Desired state（期望状态）
- 本次范围内应存在的内容对象及集合关系，先在本地表达。
- Membership（集合关系）
- 已上传对象与相册的关联，和对象字节分别维护。
- External read-back（外部回读）
- 从现有目标提供者核对真实对象与相册身份；本地清单和命令成功不能代替。
专业定义
照片视频到Photos、录音到Drive；先预览选定工作，再按当前授权阶段执行，部分成功和未知远端身份各自保留。
解决什么
解决候选冒充备份、对象与相册混为一谈、部分上传中断后重复传输、旧相册身份丢失以及云故障拖住本地整理。
当前怎样实现
- cloud-candidates.ndjson继续保存本地逐项候选与相册计划，candidate-refresh记录本地刷新；cloud-status只读，不启动同步。
- cloud-reconcile根据当前目录和选定范围建立本地期望对象与关系；--execute也只写本地SQLite，不调用提供者。
- cloud-sync默认返回DRY_RUN_PROVIDER_NOT_CALLED；显式--execute才经现有PCConfig提供者工作，并先拒绝缺失或不完整的本地期望状态。
- 同一SQLite内的cloud_object与cloud_membership分别保存内容对象和集合关系，不新建第二媒体库。已有上传身份不因相册消失而清零。
- Photos先核对远端对象与已存相册ID，先补已上传对象的相册关系，再按相册分组处理小文件，批次大小1至50；保留每项部分结果，配额限制暂停受影响工作。
- 已建相册ID不存在或歧义时记unknown（未验证）并阻塞该集合，不自行重建补传；上传身份不明时保留不确定性，先回读而非猜未上传。
- 未知上传先按保留的内容身份与远端ID查询，Drive可用ResumeOnly接续；不清零状态后整批重传。cloud-delete-plan只读生成已确认退出对象的精确Photos链接，正规网页真删后cloud-settle-retired定向结算；移出相册不等于删除媒体。
- metadata（元数据）/current.zip加入cloud-state.json，保存内容身份、远端ID、集合关系及退出状态。catalog-build只保留目标数据库已经存在的云状态，空目录重建不会导入该JSON；独立云映射导入及零起点恢复链尚未完成。保留现行库与映射，不能丢映射后重新全量上传。
- 云操作使用可复用的提供者会话并在结束关闭；cloud-reconcile、候选更新、上传字节、相册归属和真实删除各有不同效果。
- 具名照片相册参与期望集合和membership，不改变原件分类。重复增量沿已有内容哈希与远端ID处理，更新本地相册名不等于外部相册已更新；来源映射不足或矛盾时保留Unknown（未验证），不丢映射后重新全量上传。
执行流程
- 1
完成本地分类与去重
- 2
按真实范围预览期望集合
- 3
当前阶段允许时写本地期望
- 4
预览云工作且不调用提供者
- 5
进入获准云阶段后回读远端身份
- 6
先补已有对象的集合关系，再有界处理新字节
- 7
分别报告完成、部分、暂停与未知
边界
- 预览不上传。
- 本次网页核对不连接账号或执行云动作。
- 不把旧零上传记录写成永久产品限制。
- 不让云故障改变本机原件。
- 不在网页复制候选原始清单。
- 云端全量以Owner真实结果证明；手机恢复和从零恢复仍需各自验收。
失败与恢复
- 本地期望缺失或不完整
- cloud-sync执行前拒绝，先通过现有cloud-reconcile核对该范围。
- 已建相册ID消失或存在多个身份
- 保留unknown（未验证）与现有上传身份，暂停相关集合，不盲目重建或补传。
- 配额、网络或部分对象失败
- 保留逐项结果和暂停原因；已上传对象先核对关系，不把整个批次重传或报告全部完成。
- 候选与原件漂移
- 本地维护先收敛清单；真实云删除/重传按独立阶段与实际能力处理。
真实入口
AGENTS.md / USER_REQUIREMENTS.md当前用户阶段、集合用途与实际授权边界
personal_media.py候选、cloud-reconcile、cloud-sync与同库状态
cloud-candidates.ndjson本地外部计划，非账号侧回读
CLOUD_UPLOAD_RESULT.md当前云对象、分类、重入零写、播放缺口与备份Owner结果
如何验证
- 来源fb75ce0的CLOUD_UPLOAD_RESULT.md记录4230项/96,179,188,822字节；Photos全部3473个ID可读、9相册关系一致，Drive完整分页757个ID/SHA-256/大小/父目录一致；最后全量COMPLETE且两端零远端写，失败/未知/待退出0。
- 102项本地测试通过与独立只读审查为来源Owner记录，网页未重跑；115视频READY/1PROCESSING，未做手机或Takeout从零恢复。
- 旧候选header的upload=0只约束本地生成命令；不会覆盖当前cloud_object/cloud_membership的真实云端状态。
与其他模块的关系
它消费媒体整理后的集合，与本地原件和手机恢复分开；本地目录、云上传与分类已形成独立结果，Google播放处理和手机回写继续按真实来源验收。