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 執行流程
- 檢查重新簽名:
codesign -dv /Applications/WeChat.app 2>&1 | grep -q "Signature=adhoc" || echo "NEED_RESIGN"NEED_RESIGN→ 告知用戶執行sudo codesign --force --deep --sign - /Applications/WeChat.app
- 運行
bash ~/.claude/skills/wechat-decrypt/scripts/macos/extract_key.sh - 腳本會 spawn 微信 → 告知用戶掃碼登入 → 登入後 key 自動寫入
key.txt - 驗證:
test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "OK" - 提取後必須告知用戶恢復簽名: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 執行流程
- 登入微信
- 提 key:
python scripts\windows\extract_raw_key.py→ 按提示桌面手動重啟微信(必須;schtasks/SSH 起的是空殼、不讀 db)→ 腳本自動 race-attach + hook sha512 抓 raw key + 驗證,寫入key_windows.txt - 解密全庫:
python scripts\windows\decrypt_all.py→ 用 raw key 把 db_storage 所有庫解密到decrypted\{wxid}_<device>\db_storage\(明文) - 重啟 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/。