wechat-decrypt

name	wechat-decrypt
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 必须执行）

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 三项）:

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/。