用途与实际影响
这项功能怎样使用
为什么需要它
朋友圈不是普通聊天目录：账号自己的身份可能不在会话列表，当前缓存里的发布者也可能没有聊天会话。若只查 session 或默认 auto，容易漏人、串号并把缓存未命中误写成没有内容。
举个实际例子
我说“看看副号里小王最近发的朋友圈”。工具只看副号在这台电脑上已经缓存的内容；能找到人但没有正文时，它会提示我回到副号手动打开小王主页后再试，不把“本机没缓存”说成“他什么都没发”。
最后我会得到什么
得到这个明确账号在当前电脑已缓存的朋友圈内容、实际可见时间和缺口。没有本机缓存时会提示在同一账号手动打开目标后再试，不说对方没有发布。
可直接使用
账号和发布者能唯一对应、电脑里确实有相关缓存时，交回实际可见部分。
需要确认
发布者重名、媒体未缓存或本机缓存变化时保留候选和缺口。
当前不可用
本机尚无这名发布者的缓存时说明如何手动取得，不自动打开主页或联网补历史。
从哪里开始
明确账号和联系人，请查看电脑当前已经缓存的朋友圈。
需要准备什么
- primary 或 secondary 账号
- 联系人和所需范围
从开始到拿到结果
- 1
系统核对并处理
只读本机当前缓存并说明覆盖；没缓存时可在同一账号手动打开目标后再试。
- 2
交付与接续
交回实际可见内容与缺口；不称远端全部历史已取得，也不混主副号。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
显式账号、自身身份、缓存发布者、未命中下一步和快照替换均有合成回归；未读取真实朋友圈正文关键规则与设计选择
朋友圈始终显式指定 primary 或 secondary；自然请求没给账号时分别读取并标注两份结果。
self 使用来源账号作者身份承诺，不从昵称或头像推断。
发布者目录组合联系人、未登记联系人和当前缓存，不建立持久人物索引。
sync-moments 保存当前缓存快照，缓存已淘汰条目会从新快照移除。
target_not_in_current_local_cache 只触发一次同账号手动打开后重试。
本模块用到的名词
- Explicit account（显式账号）
- 朋友圈不接受 auto；每份结果必须明确属于主号或副号。
- targetCacheStatus
- 目标已缓存、目标不在当前缓存，或正在读取账号整体缓存。
- Current cache replacement（当前缓存替换）
- 刷新后档案准确代表当前可见集合；被缓存淘汰的旧条目不继续冒充可见。
- Source-proven self
- 从配置绑定的账号原生身份推导本人朋友圈作者，不从显示名称猜。
专业定义
moments 与 sync-moments 只读取明确账号当前设备可见的 sns 缓存；缓存未命中不是空主页，刷新也不保留已淘汰条目。
解决什么
解决朋友圈作者目录不完整、主副号串用、缓存未命中冒充空内容和旧缓存条目长期残留。
当前怎样实现
- _resolve_moments_subject 强制显式账号，并组合 source-proven self、完整联系人目录和当前缓存发布者。
- list_moments 对指定人会扫描完整当前缓存后再应用 limit，避免目标在后部时被错误截断。
- moments 返回 target_cached / target_not_in_current_local_cache / account_cache_read。
- sync-moments 用当前集合与旧 JSONL 比较 new / updated / removed，输出完整替换快照。
- 来源指纹只覆盖 sns.db 与 contact.db 元数据；无变化时走快速路径。
执行流程
- 1
要求明确账号和 self / contact 选择。
- 2
从账号身份、联系人目录和当前缓存解析唯一发布者。
- 3
在请求窗口内扫描本机 sns 缓存。
- 4
投影发布者标签、文字、媒体和 gaps。
- 5
一次读取返回有界 JSON；同步则与旧快照比较变化。
- 6
写出 current_local_cache_only 状态、清单和最近回执。
边界
- 只读取当前设备缓存，不访问远端朋友圈主页或补历史。
- 不自动切号、点击、点赞、评论或输入。
- 联系人/群会话不是完整朋友圈作者目录。
- 真实朋友圈正文、发布者和媒体不进入网站。
失败与恢复
- 没有明确账号
- 命令返回 moments_explicit_account_required；自然语言入口分别对主副号执行。
- 同名发布者
- 返回 contact_ambiguous 候选，不按第一项选择。
- 目标不在当前缓存
- 提示在同一账号手动打开该目标朋友圈后重试，不宣称为空。
- 刷新期间缓存变化
- 返回 source_changed_during_sync_retry，不提交新的 state。
真实入口
README.md · moments / sync-moments当前缓存、显式账号与手动补缓存边界。
wechat_cli.py · _resolve_moments_subjectself、联系人和缓存发布者的唯一解析。
wechat_cli.py · command_sync_moments当前集合替换、增删改和导出清单。
tests/test_wechat_cli.py · moments身份、缓存未命中、跨账号和淘汰回归。
如何验证
- test_moments_self_uses_source_account_identity 验证本人身份来自来源账号。
- test_moments_self_cache_miss_requests_same_account_profile_open 验证缓存未命中下一步。
- test_moments_rejects_implicit_cross_account_selection 验证不跨账号猜。
- test_moments_sync_replaces_items_evicted_from_current_cache 验证快照替换。
与其他模块的关系
朋友圈与聊天共享账号身份和媒体读取，但拥有独立的缓存范围、对象解析与同步状态，不能用聊天档案替代。