Agent 实践

yichen-wechat-local-vault：把微信的 SQLCipher 数据库拆成你的本地 vault

5 分钟阅读AIAgent学习笔记Skill
文章目录
  1. 这是什么
  2. 为什么值得关注
  3. 它怎么转：四层逻辑
  4. 触发层
  5. 核心层（5 大模块）
  6. 输出层
  7. 卡点层
  8. 它能做什么：常用命令速查
  9. 怎么升级：分三档
  10. 入门（先核条件）
  11. 进阶（理解工作流）
  12. 高手（适配与审计）
  13. 场景迁移：两个直接可平移的方向
  14. 方向 1：本地资料查询

原研究日期：2026-09-10；2026-10-13 核对修订。项目：mcncarl/yichen-skills。

自有微信数据库转成锁在本机中的可查询资料库
图 1：把数据变成可查询的资产，也要守住明文资料库。

这是什么

一个 Mac 微信本地资料工具箱：按授权抓取/复用 key、生成明文 vault，再查询、统计、导出和准备摘要素材；另有实验性的 Windows 离线明文快照入口。

像给聊天记录配一个命令行档案柜，但不是微信官方备份功能的等价实现。日常查询不碰进程，首次抓钥路线却会运行 ad-hoc 重签名副本并 hook 本地进程，不能概括为“完全不动微信进程”。

与本站 id=29 是同一作者项目的前后版本笔记；当前支持范围以 README 和对应代码为准，不用父仓库 stars 推算子目录热度。

为什么值得关注

  1. 把已有本地资料变成可查询副本，不再只靠翻聊天；本地库并不保证包含所有历史消息或永久可恢复。
  2. 获取与查询分开，已有明文库的窄查询不必重新抓 key。
  3. 多数查询默认 JSON，便于 Agent 调用；status 默认 text，导出有自己的格式选项。
  4. Windows 快照有独立验证与路由，不会自动落回 Mac 抓钥流程。
  5. 保留子模块来源材料与合成测试，有助审计；文件数和测试行数不是安全或质量认证。

原稿“微信云端只存 14 天”没有对应官方依据，删除；也不再宣称工具可直接用于律师取证或记者调查。

它怎么转：四层逻辑

触发层

  • Mac 上处理自己有权访问的本地记录。
  • 用户明确提供已授权、静止、已解密的 Windows 快照。
  • 为明确会话和时间段准备摘要、复盘素材，不默认分析所有联系人。

核心层（5 大模块）

用户同意后运行临时重签名副本，经本机抓钥和解密生成明文副本供查询
图 2：用户同意与应用重签名是两件事；重签名不是官方认证。

1. 密钥获取。 extract_keys.py 优先复用已保存 key / 抓取日志；需要新捕获时，针对微信副本 hook CommonCrypto 的 CCKeyDerivationPBKDF。打开收藏和朋友圈是文档建议的触发手段，不是每个版本的必经或必成步骤。重签名不代表 Apple 或微信认证。

2. 解密。 decrypt_all_dbs.py 用已匹配 key 处理数据库，增量模式按变化跳过。源码固定了页大小与保留区等参数，不能许诺全面兼容 Mac 4.x；库数也随分片变化。抓钥等待时长 --duration 240 不是 PBKDF2 解密耗时参数。

3. 统一查询。 vault_cli.py 提供 status、sessions、unread、new-messages、contacts、members、history、search、stats、export、favorites、moments、digest-source，以及 snapshot 路由。不回写源聊天库不等于没有文件副作用：增量检查和导出会写状态或产物。

4. 摘要素材。 digest-source 生成 sources/*.json / *.md，并创建画像、图片说明目录。目录存在不等于 AI 已完成画像或看到了图片；没有图片说明时不能编造画面。摘要确认后再写历史锚点。

5. Windows 快照。

授权 Windows 明文快照经清单与路径验证后仅以只读模式查询
图 3：Windows 快照是独立的只读入口，不走 Mac 密钥提取流程。

snapshot --snapshot <dir> validate/chats/history/search/export 是独立后端，不抓钥、不解密、不增量刷新。输入要求 manifest、UUIDv4 快照标识、受支持 schema，且不存在相关 WAL/SHM/journal。SQLite 使用 mode=ro&immutable=1 并设置 query_only 等限制；validate 通过只表示程序接受该结构，不证明来源授权、完整 checkpoint 历史或全面版本兼容。详见 快照契约。

输出层

  • 私密 key、配置、明文库、manifest、增量状态。
  • 用户指定目录下的可读导出与群聊素材。
  • 快照 JSON 的 untrusted_snapshot_data 标记提示不可信输入，不代表正文已脱敏。

卡点层

  1. 抓钥路线受客户端版本、签名与进程保护影响；不能把失败一概归为 Gatekeeper。
  2. 解密状态与消息增量检查状态不是同一个文件；删后者不等于下次必然全量解密。
  3. 源库变化、分片、压缩和 schema 都要核对。
  4. 不为让快照通过校验而删除 WAL/SHM，应由提供方生成一致快照。
  5. Mac 与 Windows 参数不能混用；后者兼容性仍为实验性。
  6. 原始抓钥日志含敏感材料，终端脱敏不覆盖所有落盘文件。

它能做什么：常用命令速查

以下为核过官方文档/解析器的示例，在 Skill 根目录运行；本文没有执行这些命令。首次抓钥会操作客户端副本，需要单独授权。

# 先看已有条件，不启动微信
python3 scripts/extract_keys.py --list-dbs
python3 scripts/extract_keys.py --match-only --targets all --reuse-log

# 已取得密钥、明确要求生成或刷新明文库后
python3 scripts/decrypt_all_dbs.py --mode full
python3 scripts/decrypt_all_dbs.py --mode incremental

# 查询与窄导出，不把多个命令用斜线写成一条命令
python3 scripts/vault_cli.py status --format text
python3 scripts/vault_cli.py sessions --format text
python3 scripts/vault_cli.py history "群名" --start-time "2026-09-01"
python3 scripts/vault_cli.py search "关键词" --chat "群名" --type link
python3 scripts/vault_cli.py export "群名" --format markdown --output ./chat.md

# 明确设置私密素材目录，避免默认落在当前项目 wechat/ 下
python3 scripts/vault_cli.py digest-source "群名" --start "2026-09-01" --end "2026-09-10" --data-root ~/Documents/wechat-digests

# 用户提供的 Windows 已解密快照
python3 scripts/vault_cli.py snapshot --snapshot /path/to/authorized-snapshot validate
python3 scripts/vault_cli.py snapshot --snapshot /path/to/authorized-snapshot chats
python3 scripts/vault_cli.py snapshot --snapshot /path/to/authorized-snapshot history CHAT_ID

示例目录仍需确认不受 iCloud 等同步。Windows 导出到默认位置以外时，按该后端要求使用 --confirm-external-output；它不是 Mac 所有导出命令的通用参数。

怎么升级：分三档

入门（先核条件）

读许可、检查本机配置、复用已有 key、核对 manifest，再对一个授权会话抽样验收。不要承诺“10-30 分钟跑通”。

进阶（理解工作流）

日常按需增量 → 限定会话/日期生成素材 → 人工核对摘要 → 更新历史锚点。耗时取决于数据量和环境，不写“秒级保证”。Windows 从 validate 和精确 chat_id 开始，不猜同名会话。

高手（适配与审计）

用合成数据为 schema 变更补测试，保留 Windows 子模块的来源与许可。macOS 的调度或文件观察应选其支持的工具，原稿的 Linux inotifywait 不是 Mac 默认可用命令。客户运营、公司内部部署或公开打包前，先核对根许可的额外授权要求。

场景迁移：两个直接可平移的方向

方向 1：本地资料查询

底层逻辑是“有权处理的数据 → 独立副本 → 最小必要查询”，不是“App 在我电脑上 = 我有权解出一切”。其他应用的密钥、格式、合同与数据主体权益必须独立核查。

方向 2：Agent Skill 的隐私工程

同一抓钥事件分流到部分脱敏的终端输出和含密钥材料的原始日志
图 4：终端部分脱敏，不代表原始抓钥日志没有敏感材料。

这张图表达的是设计目标，不能当作所有实现已达到目标的证明：

  1. key、库、状态与导出分层存放。
  2. 终端隐藏部分标识，但 抓钥源码会把 PBKDF2 输入/输出写入原始日志，应按密钥材料管理。
  3. 回复少贴原文，文件中的原文照样敏感。
  4. 文档用占位符，实际路径也要检查日志和错误输出。
  5. 明确模式和范围，不能假定所有命令默认无副作用。

权限 600/700 不等于加密或抗同用户恶意进程。把本地素材交给云模型，又产生独立的数据发送与留存边界。

部署风险与收益

可编程检索和按需导出是实用收益；“永久资产”“合法逆向”“司法可采”“五重门保证隐私”都不是本文能给的承诺。账号风控概率、具体合同适用及真实 Windows 数据兼容性未验证。群友画像也不应推断健康、身份等敏感属性。

项目元数据

维度 核对结果
项目 mcncarl/yichen-skills 的 yichen-wechat-local-vault 子目录
许可 根 LICENSE 为个人学习与非商业使用自定义条款，并限制部分公开再分发
第三方材料 Windows 子模块保留来源、贡献授权与依赖许可，不能只看根许可
运行环境 README 列 macOS、Mac 微信 4.x、Python 3.9+；具体代码/依赖仍需匹配
兼容范围 Mac 主路径，Windows 静态明文快照实验性
热度/行数 删除无法复核的历史增长、子 Skill stars 与混杂测试行数

文件清单

核心文件为 SKILL.md、README.md，scripts 下的抓钥、解密、CLI、快照后端、导出和 schema 模块，以及 tests、references/windows-snapshot/。不再用某次行数充当稳定接口。

关键技术亮点

获取与查询解耦、快照路由隔离、字段别名处理、摘要锚点延后提交，以及来源记录，都值得借鉴。它们是可检查的工程安排，不自动等同于安全审计通过。

一句话总结

把本地聊天变成可查询资料，真正要学的是获取、明文、查询、导出四个边界怎么分开。

2026-10-13 资料核对说明： 实际读取官方 README、SKILL.md、extract_keys.py、decrypt_all_dbs.py、vault_cli.py、Windows 快照文档和根 LICENSE；未运行抓钥、解密、真实账号兼容测试或取证流程。原研究的行数/热度与“克隆并实测”措辞不作为本次证据。

记录到这里，判断留给实践。