git:20260610.5177d1c to git:20260901.823363c

- description: WeChat 4.x chat decrypt & query (macOS + Windows, both verified). Use when user asks about their WeChat messages, chats, contacts, or needs to re-extract the encryption key after WeChat update.

- allowed-tools: Bash

- # WeChat 4.x 聊天记录解密与查询（macOS + Windows）

-

- ## 首次加载自检（Agent 必须执行）

-

- ```bash

- python3 -c "import platform; print(platform.system())"

- claude mcp list 2>&1 | grep -q "wechat.*Connected" && echo "MCP_OK" || echo "MCP_MISSING"

- test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "KEY_OK" || echo "KEY_MISSING"

- ```

-

- | 状态 | 行动 |

- |------|------|

- | `MCP_MISSING` | macOS `bash setup.sh` / Windows `powershell -File setup.ps1`，告知「重启 Claude Code」 |

- | `KEY_MISSING` | 执行「密钥提取」对应平台流程（Windows 提 key 后还需 `python scripts\windows\decrypt_all.py` 解密全库到明文） |

- | 全部 OK | 直接使用 MCP 工具 |

-

- > **Windows 自检**（PowerShell，对齐上面 macOS 三项）:

- > ```powershell

- > python -c "import frida, Crypto; print('DEPS_OK')" # 缺 → pip install frida pycryptodome

- > Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\key_windows.txt" # 缺 → extract_raw_key.py 提 key

- > Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\decrypted" # 缺 → decrypt_all.py 解密全库

- > ```

- > 缺哪项跑对应步骤:deps→`setup.ps1`、key→`extract_raw_key.py`、明文库→`decrypt_all.py`。

- 不要跳过自检。

- ## Agent 触发规则

- | 用户意图 | 行动 |

- |----------|------|

- | "看我微信" "最近聊天" "谁找我" "有什么消息" | MCP: `wechat_recent_messages` / `wechat_chat_summary` |

- | "搜XX的聊天" "和XX提到" | MCP: `wechat_search_messages` |

- | "列出会话" "有哪些群" | MCP: `wechat_list_chats` |

- | "读和XX的聊天" | MCP: `wechat_read_chat` |

- | "导出和XX的聊天" "导出XX到桌面" | 先做①模型检查（见下），再 `python3 scripts/common/export_chat.py <contact> [--start/--end/--year] [-o path]`（不传日期=全部历史；模型在则默认转写，`--no-transcribe` 可关；语音转写结果持久缓存 voice_cache.json，二次导出秒回） |

- | "转写XX的语音" "语音转文字" "把语音导成文字" | `python3 scripts/common/export_chat.py <contact> --transcribe`，或单独 `python3 scripts/common/transcribe_db.py <contact> -o map.json` |

- | "微信更新了" "重新破解" "密钥失效" | 执行下方「密钥提取」对应平台流程 |

- ### ① 导出前置——语音转写模型检查（默认执行）

- 导出/转写任何可能含语音的对话前，先查模型是否就位：

- test -d ~/.cache/huggingface/hub/models--mlx-community--whisper-large-v3-mlx && echo MODEL_OK || echo MODEL_MISSING

- | 结果 | 行动 |

- |------|------|

- | `MODEL_OK` | 导出**默认开启语音转写**（脚本检测到模型即自动转，无需 `--transcribe`；用户明确不要才加 `--no-transcribe`） |

- | `MODEL_MISSING` | **先问用户是否安装**（whisper-large-v3 ~3GB，纯离线一次性）。装→加 `--transcribe`（首次自动下载并转写）；不装→普通导出，语音保留 `[Audio]` |

-

- 脚本侧已内置同逻辑（模型在→默认转，不在→留 `[Audio]` 并提示）。但 `MODEL_MISSING` 时 Agent 必须主动问，别擅自下 3GB。

-

- ## MCP 工具（注册名 `wechat`）

-

- | 工具 | 参数 | 用途 |

- |------|------|------|

- | `wechat_list_chats` | 无 | 所有会话（群名+备注已解析） |

- | `wechat_read_chat` | contact, limit(50), days(7) | 特定对话 |

- | `wechat_search_messages` | keyword, days(30), limit(50) | 全文搜索 |

- | `wechat_recent_messages` | days(3), limit(100) | 最近动态 |

- | `wechat_chat_summary` | days(3) | 结构化摘要 + 待办 |

-

- `[我]` = 用户发的，`[对方]` = 联系人发的。

- ## 语音转写（全自动）

- 语音消息（`local_type=34`）的音频以 SILK v3 存在 `media_0.db` 的 `VoiceInfo.voice_data`，按 `svr_id == server_id` 对齐。链路：VoiceInfo 直取 → `pilk` 解码 SILK→wav → whisper large-v3 转写 → 按 server_id 回填。全自动、批量、纯离线，无需 BlackHole/播放/重启。**默认行为：模型已缓存即自动转写；`--transcribe` 强制（含首次下载 ~3GB 模型，缓存 `~/.cache/huggingface/`）；`--no-transcribe` 关闭。** **后端按平台自动切**：macOS = `mlx-whisper`（Apple Silicon），Windows = `faster-whisper`（CPU int8，按需下载）；旧 BlackHole+Swift 方案在 langlobal 开发仓。

- ## 命令行 entry（逻辑核心；MCP 是可选薄门面）

- 逻辑核心在 `scripts/common/query.py`（命令行），`server.py` 的 MCP 工具只是转发到它。**agent 调用推荐加 `--json` 拿结构化输出**（解析可靠，不受文字排版影响）；人调试时不加、看文字。

- SKILL_DIR=~/.claude/skills/wechat-decrypt

- python3 "$SKILL_DIR/scripts/common/query.py" list

- python3 "$SKILL_DIR/scripts/common/query.py" recent -d 3 --json # agent 用 --json

- python3 "$SKILL_DIR/scripts/common/query.py" search 关键词 --json

- # 子命令: list / read <contact> / search <kw> / recent / summary / stats / media / openfile

- ## 密钥体系（两端通用）

-

- - **Raw Key**: 64 hex，**每设备独立**（微信 4.0：同账号 macOS 与 Windows 的 raw key 不同，不可互用）；微信不更新就持续有效

- - **派生公式**: `PBKDF2-HMAC-SHA512(raw_key, db_file_salt, 256000) → 32 bytes`

- - **SQLCipher 参数**: `PRAGMA key = "x'<derived>'"; PRAGMA kdf_iter = 1; PRAGMA cipher_compatibility = 4; PRAGMA cipher_page_size = 4096;`

-

- ## 数据库路径

-

- | 平台 | 路径 |

- |------|------|

- | macOS | `~/Library/Containers/com.tencent.xinWeChat/.../xwechat_files/{wxid}/db_storage/` |

- | Windows | `~/Documents/xwechat_files/{wxid}/db_storage/` |

-

- ---

-

- # 密钥提取

-

- ## macOS

-

- ### Agent 执行流程

-

- 1. 检查重签名：`codesign -dv /Applications/WeChat.app 2>&1 | grep -q "Signature=adhoc" || echo "NEED_RESIGN"`

- - `NEED_RESIGN` → 告知用户执行 `sudo codesign --force --deep --sign - /Applications/WeChat.app`

- 2. 运行 `bash ~/.claude/skills/wechat-decrypt/scripts/macos/extract_key.sh`

- 3. 脚本会 spawn 微信 → **告知用户扫码登录** → 登录后 key 自动写入 `key.txt`

- 4. 验证：`test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "OK"`

- 5. **提取后必须告知用户恢复签名**：adhoc 重签名是单向破坏性操作，会覆盖腾讯原始签名，导致微信截图/数据访问反复弹权限框。codesign 无法还原第三方签名，只能重装微信恢复。聊天记录在独立容器目录（`~/Library/Containers/com.tencent.xinWeChat/`），重装 `/Applications/WeChat.app` 不受影响。密钥提取后日常查消息只读 DB、不再需要重签名。

-

- ### 关键认知

-

- - 重签名只在「提取密钥」这一瞬间需要，提取完即应重装微信恢复签名。

- - 反复弹权限框 = 微信签名是 adhoc 状态的症状，不是 Claude Code/MCP 引起的。

- - 密钥每设备独立（同账号各端 key 不同，不可互用），微信不更新就一直有效，无需反复提取。

-

- ### 原理

-

- 微信 4.x macOS 版不调 `sqlite3_key`（苹果系统 SQLite 的该函数为空壳），而是通过 WCDB 统一加密层调用 `CCKeyDerivationPBKDF`（CommonCrypto）。Frida 使用 `Module.findGlobalExportByName`（Frida 17.x+ API）hook 该函数，在 `passwordLen=32, rounds>1000, dkLen=32` 时捕获密码参数（raw key）。

-

- ## Windows（已攻克：提 key→解密→读取，能力对标 macOS）

-

- **现状（2026-06-06 UTM 实测跑通）**：提 key→解密全库→MCP/导出/语音转写，与 macOS 同能力。message_0 解出 99 会话/1384 消息。全流程见 `docs/2026-06-06-windows-raw-key-journey.md`。

-

- ### Agent 执行流程

- 1. 登录微信

- 2. **提 key**：`python scripts\windows\extract_raw_key.py` → 按提示**桌面手动重启微信**（必须；schtasks/SSH 起的是空壳、不读 db）→ 脚本自动 race-attach + hook sha512 抓 raw key + 验证，写入 `key_windows.txt`

- 3. **解密全库**：`python scripts\windows\decrypt_all.py` → 用 raw key 把 db_storage 所有库解密到 `decrypted\{wxid}_<device>\db_storage\`（明文）

- 4. 重启 Claude Code → **MCP 工具、导出、语音转写与 macOS 完全一致**（server/export/transcribe 走 `DB_BACKEND="sqlite3"` 读明文库；语音用 faster-whisper）

-

- 单库验证/调试用 `scripts\windows\decrypt_read.py <raw_key>`（只解 message_0 验证）。

-

- ### 提 key 原理（sha512 入口 hook + HMAC ipad）

- **核心**：raw key/K1 在内存被三重保护（AES-NI 轮密钥/用后清除/secure mem，内存 brute 全失败），但 SQLCipher 派生 key 走 **PBKDF2-HMAC-SHA512**，HMAC 构造 ipad block 那一刻是 key 的**明文** `key XOR 0x36`（后 96 字节恒 0x36）——绕过所有保护直取。

- `extract_raw_key.py` 自包含：**自动定位** sha512 入口（搜 K 常量 `0x428a2f98d728ae22`→xref→反汇编，不硬编码地址，换微信版本也行）+ race-attach（赶在开 db 前）+ hook 入口（rdx=input block）+ 检测 ipad + 自动验证（`PBKDF2→AES page1` 出头=raw key 通用 / 直接 `AES` 出头=K1 单库）。启动 `PBKDF2(raw,salt)` 暴露 raw key；运行时 page-MAC 只暴露 mac_key（无用）→ 必须 race 赶**启动**。

- **frida 在 ARM 模拟（xtajit 翻译 x64）下能 hook 微信内部 x64 函数**（1127万次验证）；spawn 不兼容用 race-attach。

- - 数据路径：`C:\Users\<用户>\Documents\xwechat_files\{wxid}_<device>\db_storage\`。`wechat-dump-rs` 被 DMCA 封，本方法已替代。

- - 开发期全套攻关脚本（定位/brute/失败记录）在 langlobal 开发仓，运行只需 `extract_raw_key.py`+`decrypt_all.py`。

-

- ---

-

- ## 分发与安装

-

- 拷贝整个 skill 目录。接收方执行：

-

- **macOS:** `bash setup.sh`

- **Windows:** `powershell -File setup.ps1`

-

- `key.txt`、`contacts.json`、`all_keys.json`、`voice_cache.json` 是个人数据，分发前删除（已 `.gitignore`）。

-

- ## 文件清单

- ```

- ~/.claude/skills/wechat-decrypt/ # 运行单元；开发全套(tests/docs/攻关脚本/legacy)在 langlobal 开发仓

- ├── server.py config.py crypto.py db.py contacts.py message.py ← MCP 运行核心(6)，db.py 双后端

- ├── scripts/

- │ ├── common/ ← 跨平台：export_chat(导出+转写) transcribe_db voice_decode sqlcipher_decrypt read_doc export_media verify_key

- │ ├── macos/ ← extract_key.sh + hook_pbkdf.js (CCKeyDerivationPBKDF)

- │ └── windows/ ← extract_raw_key.py(自包含提key) decrypt_all.py(解密全库→明文) decrypt_read.py(单库验证)

- ├── setup.sh / setup.ps1 ← 平台安装

- ├── SKILL.md README.md LICENSE

- ├── key.txt key_windows.txt ← .gitignore

- └── contacts.json ← .gitignore

- ```

- 依赖：**macOS** 全局 python（mcp/frida/cryptography/pilk/mlx-whisper/zstd）；**Windows**（mcp/frida/pycryptodome/pilk/faster-whisper/zstandard）。语音模型缓存 `~/.cache/huggingface/`。