/wechat-exporter

name: wechat-exporter
description: Use when the user says "wechat-exporter", "导出微信", "更新微信聊天记录", or wants to implement, decrypt, export, or refresh authorized local WeChat databases on macOS using the bundled implementation guide.

wechat-exporter

基于内置规范，为本人授权的 macOS 微信 4.x 本地 SQLCipher 数据库实现、测试和运行解密工具，输出经过验收的标准 SQLite 数据库。本仓库提供技能与规范，不附带现成扫描器、解密脚本或 MCP Server；不要声称安装技能后就已具备这些程序。

必读材料与优先级

开始实现或处理真实数据前，完整阅读本技能目录下的 [references/agent-decrypt-guide.md](references/agent-decrypt-guide.md)，包含附录。相对路径以本技能目录为基准，不是当前工作目录。

• 页面格式、密钥验证、快照、WAL 和验收以该指南为准，不用本文件的摘要代替完整规范。
• [references/database-schema.md](references/database-schema.md) 仅为解密后查询的历史结构参考，按需阅读并核验当前版本。
• 不再从旧版依赖仓库下载脚本，不假设 `find_all_keys_macos`、`decrypt_db.py`、`all_keys.json` 或 `server.py` 已存在或具有固定接口。
• 指南覆盖已取得密钥后的解密流程；密钥获取仅对分支 A 提供完整实现思路，分支 B 需版本相关分析。不得承诺所有微信 4.x 版本都可自动完成。

1. 明确范围与授权

确认目标账号、数据范围、工具工作目录、输出目录，以及用户要实现工具还是实际导出。发现多个账号时先列出候选并确认授权范围，不按“最近修改”自行选择账号，也不自动处理未授权账号。

仅处理本人设备、本人账号及本人授权的数据。不得覆盖原始库，不把密钥、数据库、消息正文或内存转储写入日志、版本控制或对外发送。工作目录放在源码仓库之外；目录权限收紧，确需持久化的密钥文件权限为 `600`，报告只含必要的非敏感状态。不要让用户粘贴密钥或完整扫描输出。

应用重签名、退出/重启客户端、改变系统保护状态等操作必须单独说明影响并取得明确授权。不要因版本变化自动重签名，不自动关闭 SIP。需要提权时说明具体命令和目的，由用户通过安全的本地方式完成，不收集密码。

2. 检查环境与已有实现

1. 发现客户端与 `db_storage` 路径，不硬编码应用名、账号目录或分片数量。 2. 检查现有编译器、`uv`、SQLCipher 等工具；缺少时再按用户环境安装。系统工具使用 Homebrew，Python 环境与依赖使用 `uv`，不使用系统 `pip`。 3. 若已有本地实现，先审查其接口与测试是否符合指南，再决定复用或补齐；不能凭目录存在就直接运行。 4. 若没有实现，按指南附录 B 拆分模块：发现、候选密钥、页面认证、逐页解密、一致快照、SQLCipher checkpoint、独立内容比对、逐库报告。

语言不限。可用 C/Mach API 实现扫描，用 Python 的 `hashlib` 与 AES 库实现页面处理；不强制复刻旧脚本接口。

3. 先实现并验证无真实数据的闭环

先完成指南第 6、7、9、10 节，不先操作微信进程：

• 用 SQLCipher 按目标参数生成已知内容的独立测试库，验证全页 HMAC、解密后文件尺寸、SQLite `integrity_check` 和逻辑内容。
• 覆盖第一页偏移、页码小端、认证密钥派生、80 字节保留区；错密钥、篡改页与截断输入必须失败，不能输出正式成功产物。
• 构造真正留在 WAL 中的已提交更新，尤其是只更新字段、不改变行数的用例；断言忽略 WAL 得旧值，正确 checkpoint 后得新值。
• 按指南第 10 节覆盖危险分支并写清预期行为。自制加密器与解密器往返只算单元测试，不能代替独立实现交叉验证。

测试未通过，不进入真实数据导出。没有运行过的测试必须标注未验证，不把文档内的实测记录当作本次实现的测试结果。

4. 取得并逐库验证密钥

客户端运行时，按指南第 3–5 节检查权限和密钥形态。版本号仅作诊断信息，不作为跳过验证的条件。

• 物理文件身份用账号加相对路径；候选按 salt 索引并保留多个候选；每个库独立校验，输出也按账号隔离。
• 分支 A 扫描标准 key/salt 字符串，处理分块重叠、去重与第一页 HMAC 验证。
• 无候选时先排查权限、进程、扫描覆盖和数据库是否已加载，不直接断定分支 B 或重签名。
• 分支 B 的 passphrase 获取不由指南完整覆盖。不能取得时停止对应库并报告不支持/缺密钥，不猜测或承诺可恢复。
• 密钥缓存存在也必须逐库重验。扫描完成、格式匹配、版本未变均不代表密钥有效。

5. 建立一致快照并处理 WAL

先取得密钥，再在整个复制期间确保停止写入，或采用能提供一致视图的快照方式。保留不参与改写的基准快照，记录采集时点及主库、WAL、SHM 文件清单。`-shm` 可缺失；不能漏掉存在的 WAL。

默认路线严格执行指南第 8.5 节：从基准快照建立可丢弃工作副本，让 SQLCipher checkpoint，再解密该工作副本。独立验证使用从同一基准快照另建的副本。

checkpoint 判定先检查 SQL 错误、不支持状态与 busy；`(0,-1,-1)` 单独解释；普通成功要求 busy 为 0、log 与 checkpointed 非负且相等。busy 为 0 本身不代表完成，TRUNCATE 的零计数也不能证明原先没有 WAL。

无法建立一致副本时，不能通过快照恢复验收。自写受限 WAL 恢复仅按第 8.4 节执行并标注限制，不宣称完整最新；遇到未经验证的页 1 帧，转 SQLCipher 或报告不支持。

指南中的 SQLCipher 命令是参数示意。工程实现不要把真实密钥拼进命令行参数、shell 历史或错误日志；通过受控进程输入或库接口提供，并对错误输出脱敏。

6. 解密与验收

按指南逐页先认证后解密，不去 PKCS#7 填充，不修改 SQLite 保留字节数，不静默补齐截断页。正式输出目录不得混入源密文 WAL/SHM。失败产物与通过验收的输出隔离并明确标记。

验收必须区分：

1. 主库解密通过：全页 HMAC、页面布局、输入输出尺寸、只读 SQLite 结构检查和同快照同视图的独立内容比对。 2. 快照恢复通过：输入一致、有效已提交 WAL 已正确处理，并注明快照时点。 3. 目标范围全部处理并报告：每个授权账号、每个目标库都有结论，不代表全部恢复成功。

全库内容一致必须比较对象定义及全部逻辑内容，保留类型、BLOB 字节和重复行，采用确定性顺序。表名可见、行数相同或 `integrity_check=ok` 都不能单独证明成功。

7. 交付报告与可选查询

报告列出：实现与测试状态、授权范围、快照时点、逐库状态、WAL 处理结果、认证与结构检查、内容比对范围、输出位置和未解决项。成功、缺密钥、失败、不支持、跳过、受限恢复分别统计；任何失败均须说明，不预设某一个库失败“正常”。

“最新”最多指采集一致快照中有效且已提交的状态，不代表客户端此刻状态。不在报告里输出聊天正文或密钥。

数据库结构确认后，可参考 `references/database-schema.md` 做只读查询。解密成功不代表正文解码、压缩处理或附件关联完成。

MCP 查询服务为独立可选工作：仅在用户需要时实现或适配，对已验收的明文库只读访问，限制数据范围与查询权限，另行测试并按所用客户端配置。未实际实现、注册与验证前，不宣称“MCP 已就绪”。