
WeChatDirect · 功能说明
长期合作对象的聊天可以持续更新,而不需要每次全量导出、复制旧媒体或把完整历史交给 AI。
当前情况:同一句“再保存一次”现在分成几种情况:没有变化就原地核对后只记一笔;有新内容走普通更新;要翻旧账时由我明确要求整段重新核对;只想补附件时单独补本机能打开的附件。本页未读档案正文,完整历史仍限本机实际可见范围。
具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库


WeChatDirect · 功能说明
长期合作对象的聊天可以持续更新,而不需要每次全量导出、复制旧媒体或把完整历史交给 AI。
当前情况:同一句“再保存一次”现在分成几种情况:没有变化就原地核对后只记一笔;有新内容走普通更新;要翻旧账时由我明确要求整段重新核对;只想补附件时单独补本机能打开的附件。本页未读档案正文,完整历史仍限本机实际可见范围。
具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库


用途与实际影响
只保存一次会漏掉后续内容;每次全量重做又慢、重复且容易在中断时留下半成品。真正可用的归档需要知道自己处理到哪里、来源是否变化、哪些是新增或更新,以及怎样验证提交完成。
我说“把这个供应商群持续保存下来”。第一次会保存当前设备能看到的完整本地历史;下周再说同一句,档案只补上次之后的新消息和最近这段时间里改过的内容,旧内容不会整包重抄。如果是很早的旧消息后来被改了,或者我后来才在微信里点开下载了一个旧附件,普通更新不保证碰得到:要我明确说“把这个群从头重新核对一遍”,或者“只补缺的附件”。
得到这个具名联系人或群在当前电脑能看到的消息、可读档案、附件与更新状态。写入中断时旧完整档案仍在。对方后来改了微信名、我换了称呼,还是同一份档案,不会多出一份;旧目录里已有同一个人的完整档案也接着用。缺的附件只有在我后来把它下载到这台电脑之后才能补;读不到就继续标为缺口,不保证追得回来。微信远端从未取得的内容不会因此出现。

用途与实际影响
只保存一次会漏掉后续内容;每次全量重做又慢、重复且容易在中断时留下半成品。真正可用的归档需要知道自己处理到哪里、来源是否变化、哪些是新增或更新,以及怎样验证提交完成。
我说“把这个供应商群持续保存下来”。第一次会保存当前设备能看到的完整本地历史;下周再说同一句,档案只补上次之后的新消息和最近这段时间里改过的内容,旧内容不会整包重抄。如果是很早的旧消息后来被改了,或者我后来才在微信里点开下载了一个旧附件,普通更新不保证碰得到:要我明确说“把这个群从头重新核对一遍”,或者“只补缺的附件”。
得到这个具名联系人或群在当前电脑能看到的消息、可读档案、附件与更新状态。写入中断时旧完整档案仍在。对方后来改了微信名、我换了称呼,还是同一份档案,不会多出一份;旧目录里已有同一个人的完整档案也接着用。缺的附件只有在我后来把它下载到这台电脑之后才能补;读不到就继续标为缺口,不保证追得回来。微信远端从未取得的内容不会因此出现。

有变化就合并新内容;没有变化也先核对旧档案、附件和清单仍是一套,确认后在原目录只更新运行记录,不重新复制整个档案。
旧消息后来修改、无时间记录或附件后来才下载到本机时,普通更新覆盖不到;需要对这个对象明确“整段重新核对”,或者单独“补本机附件”。
目录已有未知内容、账号不符、来源变化、旧档案自己核对不过,或档案文件正被别的程序占用时停下,不覆盖原档硬修;占用的情况关掉占用程序后原样重试即可。

有变化就合并新内容;没有变化也先核对旧档案、附件和清单仍是一套,确认后在原目录只更新运行记录,不重新复制整个档案。
旧消息后来修改、无时间记录或附件后来才下载到本机时,普通更新覆盖不到;需要对这个对象明确“整段重新核对”,或者单独“补本机附件”。
目录已有未知内容、账号不符、来源变化、旧档案自己核对不过,或档案文件正被别的程序占用时停下,不覆盖原档硬修;占用的情况关掉占用程序后原样重试即可。

明确要求长期保存一个具名联系人或群的微信历史。
- 明确账号和一个联系人或群
- 希望保存当前可见历史、更新既有归档、整段重新核对,还是只补附件


明确要求长期保存一个具名联系人或群的微信历史。
- 明确账号和一个联系人或群
- 希望保存当前可见历史、更新既有归档、整段重新核对,还是只补附件



- state.json 固定 wechat-direct-contact-sync.v1、账号身份承诺、联系人原生身份、游标、水位、来源指纹和消息数量。


- state.json 固定 wechat-direct-contact-sync.v1、账号身份承诺、联系人原生身份、游标、水位、来源指纹和消息数量。
数字截至 2026 年 11 月 6 日

- messages.jsonl 用 server id;没有 server id 时用本地 id、时间、sortSeq 与发送者计算稳定合并键。
- 默认 overlapSeconds=86400,允许 0 到 31 天;单分片且目录不变时使用 sortSeqReplayFloor。
- 旧说话人语义的完成态档案在下次对同一对象运行 sync-contact 时,先验原档,再以 sender_identity_reconcile 重核当前本机可见历史;其他聊天不扫描、不改写。源中已不存在的旧消息保留正文与原证据,显示身份未重核并计数。2026-10-11 16:32 清点时,5 份档案中 2 份已记录当前发送者解释版本,3 份没有;它们要等下次被点名同步时才会重核。
- 来源指纹未变时先再取一次指纹确认稳定,重验 manifest(清单) 自哈希及其与 state 的账号、身份承诺、联系人、来源指纹和数量绑定;messages.jsonl 核对 SHA-256 与记录数,context.md 和 ai-context.md 分别核对完整 SHA-256 与字节数。全部一致才在原目录返回 sourceMetadataFastPath/noChange 并只更新 last-run,不复制、不重新发布整包。
- sync-contact、sync-moments、repair-media 只在有变化时暂存并验证完整候选,通过同级.wechat-transaction记录准备、前像和替换状态;两次目录rename有独立中断状态。事务外层的并发变化检查用文件大小、修改时间和文件系统变更时间,不再为签名把整棵目录读两遍,这不替代内部的清单、全文、记录与媒体核对。复制、校验、改名或清理遇到文件被占用统一返回 archive_output_in_use。recover-export只读检查后按明确动作complete/rollback,已提交状态不能再回滚,身份或外来修改冲突保留。
- 正常写入由同级事务记录加操作系统租约阻止两个写者同时更新同一输出目录;旧版留下的 .sync.lock 仍按未知旧锁拦截,当前不会自动判断或清除。
- 快速返回已经包含导出全文与结构记录的完整哈希核对,不只是看文件存在或数量;独立 verify-export 另核整个导出的路径、媒体与派生关系,不应把两者的覆盖范围混为一谈。


- messages.jsonl 用 server id;没有 server id 时用本地 id、时间、sortSeq 与发送者计算稳定合并键。
- 默认 overlapSeconds=86400,允许 0 到 31 天;单分片且目录不变时使用 sortSeqReplayFloor。
- 旧说话人语义的完成态档案在下次对同一对象运行 sync-contact 时,先验原档,再以 sender_identity_reconcile 重核当前本机可见历史;其他聊天不扫描、不改写。源中已不存在的旧消息保留正文与原证据,显示身份未重核并计数。2026-10-11 16:32 清点时,5 份档案中 2 份已记录当前发送者解释版本,3 份没有;它们要等下次被点名同步时才会重核。
- 来源指纹未变时先再取一次指纹确认稳定,重验 manifest(清单) 自哈希及其与 state 的账号、身份承诺、联系人、来源指纹和数量绑定;messages.jsonl 核对 SHA-256 与记录数,context.md 和 ai-context.md 分别核对完整 SHA-256 与字节数。全部一致才在原目录返回 sourceMetadataFastPath/noChange 并只更新 last-run,不复制、不重新发布整包。
- sync-contact、sync-moments、repair-media 只在有变化时暂存并验证完整候选,通过同级.wechat-transaction记录准备、前像和替换状态;两次目录rename有独立中断状态。事务外层的并发变化检查用文件大小、修改时间和文件系统变更时间,不再为签名把整棵目录读两遍,这不替代内部的清单、全文、记录与媒体核对。复制、校验、改名或清理遇到文件被占用统一返回 archive_output_in_use。recover-export只读检查后按明确动作complete/rollback,已提交状态不能再回滚,身份或外来修改冲突保留。
- 正常写入由同级事务记录加操作系统租约阻止两个写者同时更新同一输出目录;旧版留下的 .sync.lock 仍按未知旧锁拦截,当前不会自动判断或清除。
- 快速返回已经包含导出全文与结构记录的完整哈希核对,不只是看文件存在或数量;独立 verify-export 另核整个导出的路径、媒体与派生关系,不应把两者的覆盖范围混为一谈。

数字截至 2026 年 11 月 6 日




| 名词 | 意思 |
|---|---|
| First full snapshot(首次完整快照) | 第一次保存该对象当前设备可见的全部本地历史;它仍不等于微信远端全历史。 |
| sortSeq cursor(排序游标) | 单一消息来源下按 WeChat 排序序号继续,能包含没有 createTime 的新增消息。 |
| Overlap window(重叠窗口) | 从上次最后时间向前回看一段,默认 1 天,用于吸收迟到或变化记录;更早的变化要靠显式重核。 |
| Source metadata fast path(来源元数据快速路径) | 相关源文件指纹重复核对未变时,不重新扫描源库消息;先重验本地导出全文、结构记录、清单与状态绑定,全部一致后在原目录确认无变化并只更新回执,不复制整包。 |

sync-contact 第一次保存该对象当前设备可见的完整本地历史;以后重复同一命令,没有变化就原地核对,有变化就按游标或重叠窗口合并增量。旧历史变化用 --full-reconcile 显式重核,只补现有归档的本机附件用 repair-media;两者都先核对旧档案。



sync-contact 第一次保存该对象当前设备可见的完整本地历史;以后重复同一命令,没有变化就原地核对,有变化就按游标或重叠窗口合并增量。旧历史变化用 --full-reconcile 显式重核,只补现有归档的本机附件用 repair-media;两者都先核对旧档案。

- 权限只覆盖用户点名的一个联系人或群,不扩到全账号。
- 首次本地完整不代表远端完整,也不补设备上已经不存在的历史。
- 普通增量不能保证抓到没有时间的旧记录、更早被修改的消息或后来才下载的历史附件;旧消息变化用 full reconcile,只补附件用 repair-media。
- 有具名媒体修复和导出事务恢复,但没有把档案导入回微信的restore/import,也不自动删除未知.sync.lock或接管无依据旧目录。
- 归档目录留在本机,不进入公开网站或 Git。
- 首次输出目录已有未知内容: 返回 sync_output_not_initialized,不覆盖用户文件。
- 账号、联系人或状态身份不一致: 返回 sync_identity_mismatch,保留原档案并要求使用原对象或新目录。
- 同一目录已有运行锁: 返回 sync_already_running_or_stale_lock;先确认旧进程与锁状态,不并发写。

- 权限只覆盖用户点名的一个联系人或群,不扩到全账号。
- 首次本地完整不代表远端完整,也不补设备上已经不存在的历史。
- 普通增量不能保证抓到没有时间的旧记录、更早被修改的消息或后来才下载的历史附件;旧消息变化用 full reconcile,只补附件用 repair-media。
- 有具名媒体修复和导出事务恢复,但没有把档案导入回微信的restore/import,也不自动删除未知.sync.lock或接管无依据旧目录。
- 归档目录留在本机,不进入公开网站或 Git。
- 首次输出目录已有未知内容: 返回 sync_output_not_initialized,不覆盖用户文件。
- 账号、联系人或状态身份不一致: 返回 sync_identity_mismatch,保留原档案并要求使用原对象或新目录。
- 同一目录已有运行锁: 返回 sync_already_running_or_stale_lock;先确认旧进程与锁状态,不并发写。

- 来源在读取期间发生变化: 返回 source_changed_during_sync_retry,不提交新 state;下次从旧完整状态重试。
- 来源没变,但本地导出文本、记录或清单绑定漂移: 按实际位置返回 sync_context_sha256_mismatch、sync_ai_context_sha256_mismatch、sync_records_sha256_mismatch 或 sync_manifest_state_mismatch 等精确错误;不返回 noChange,也不默默覆盖不同字节。旧档损坏时用一个新的空目录重新导出,不覆盖损坏的档案。
- 需要覆盖旧历史变化: 用户显式使用 --full-reconcile,先核对旧档,再重新核对该对象全部本地可见历史。
- 档案文件被其他程序占用: 复制、校验、改名或清理时统一返回 archive_output_in_use;关掉占用程序后对原输出重试。若新版本已发布、只是清理受阻,先运行 recover-export complete;保留前一版和事务记录,不掩盖更早的错误。
- 首次同步中断: 能找到同级事务记录的,先用 recover-export 检查后 complete 或 rollback;没有事务依据、只有半成品文件而没有 state 的旧目录仍返回 sync_output_not_initialized,需要人工核对或移走后重建,不自动接管。
- .sync.lock 来自已退出进程: 当前仍按锁冲突停止;不能无条件删除,也没有自动陈旧锁修复。

- 来源在读取期间发生变化: 返回 source_changed_during_sync_retry,不提交新 state;下次从旧完整状态重试。
- 来源没变,但本地导出文本、记录或清单绑定漂移: 按实际位置返回 sync_context_sha256_mismatch、sync_ai_context_sha256_mismatch、sync_records_sha256_mismatch 或 sync_manifest_state_mismatch 等精确错误;不返回 noChange,也不默默覆盖不同字节。旧档损坏时用一个新的空目录重新导出,不覆盖损坏的档案。
- 需要覆盖旧历史变化: 用户显式使用 --full-reconcile,先核对旧档,再重新核对该对象全部本地可见历史。
- 档案文件被其他程序占用: 复制、校验、改名或清理时统一返回 archive_output_in_use;关掉占用程序后对原输出重试。若新版本已发布、只是清理受阻,先运行 recover-export complete;保留前一版和事务记录,不掩盖更早的错误。
- 首次同步中断: 能找到同级事务记录的,先用 recover-export 检查后 complete 或 rollback;没有事务依据、只有半成品文件而没有 state 的旧目录仍返回 sync_output_not_initialized,需要人工核对或移走后重建,不自动接管。
- .sync.lock 来自已退出进程: 当前仍按锁冲突停止;不能无条件删除,也没有自动陈旧锁修复。

README.md · sync-contact首次全量、自动增量、AI 小上下文与 full reconcile 使用边界。
wechat_cli.py · command_sync_contact游标、重叠、合并、媒体、manifest(清单)/state 提交和回执实现。
wechat_source.py · contact_source_fingerprint与单对象相关的无正文来源变化指纹。
tests/首次、增量、游标、原子提交和来源变化回归。test_wechat_cli.py · contact sync
- test_contact_sync_is_full_then_bounded_incremental_ai_context 验证首次完整与 AI 小窗口。
- test_contact_sync_changed_source_replays_indexed_cursor_and_merges 验证来源变化后的游标合并。
- test_manifest_is_published_before_state_commit_marker 验证提交顺序。
- test_contact_sync_does_not_commit_when_source_changes_during_read 验证漂移失败关闭。

README.md · sync-contact首次全量、自动增量、AI 小上下文与 full reconcile 使用边界。
wechat_cli.py · command_sync_contact游标、重叠、合并、媒体、manifest(清单)/state 提交和回执实现。
wechat_source.py · contact_source_fingerprint与单对象相关的无正文来源变化指纹。
tests/首次、增量、游标、原子提交和来源变化回归。test_wechat_cli.py · contact sync
- test_contact_sync_is_full_then_bounded_incremental_ai_context 验证首次完整与 AI 小窗口。
- test_contact_sync_changed_source_replays_indexed_cursor_and_merges 验证来源变化后的游标合并。
- test_manifest_is_published_before_state_commit_marker 验证提交顺序。
- test_contact_sync_does_not_commit_when_source_changes_during_read 验证漂移失败关闭。

- test_contact_fast_path_rejects_hash_size_count_and_state_drift 覆盖无变化候选的清单自哈希、全文字节、记录数与状态绑定漂移;CLI(命令行工具) 回归另验证 context、ai-context 和 JSONL 内容变化不能返回 noChange。
- 当前 0.2.3 源码定义了目录替换中断、完成/回滚、文件占用、旧档损坏拒绝更新、媒体修复和冲突回归(tests/test_completion_reliability.py 等),11 月 4 日只清点了定义、没有运行;本网页未强杀真实归档、重读聊天或演练真实断电。
同一账号与对象贯穿上下文、归档与媒体;本模块拥有增量续作、显式重核、定向本地补媒体与已知事务恢复,原微信数据库始终只读。

- test_contact_fast_path_rejects_hash_size_count_and_state_drift 覆盖无变化候选的清单自哈希、全文字节、记录数与状态绑定漂移;CLI(命令行工具) 回归另验证 context、ai-context 和 JSONL 内容变化不能返回 noChange。
- 当前 0.2.3 源码定义了目录替换中断、完成/回滚、文件占用、旧档损坏拒绝更新、媒体修复和冲突回归(tests/test_completion_reliability.py 等),11 月 4 日只清点了定义、没有运行;本网页未强杀真实归档、重读聊天或演练真实断电。
同一账号与对象贯穿上下文、归档与媒体;本模块拥有增量续作、显式重核、定向本地补媒体与已知事务恢复,原微信数据库始终只读。
复制 AI 续作说明
项目:一个联系人或群的首次全量与自动增量归档;仓库:wlyaaaaa/WeChatDirect;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。








