Community研究與資料分析github.com

tzwkb/wechat-decrypt

Agent 技能 — 微信 4.x 聊天記錄解密與查詢(macOS + Windows):MCP 讀取/搜尋、匯出、語音轉寫。

wechat-decrypt 是什麼?

此技能為 AI Agent(如 Claude Code)提供完整的微信 4.x 聊天記錄解密與查詢能力,支援 macOS 與 Windows 雙平台。核心功能包括:透過 MCP 工具讀取近期訊息、搜尋對話、列出會話、匯出聊天記錄(可選語音轉寫),並支援全自動語音轉寫(Whisper 模型)。 運作方式可分為三個階段:首先,Agent 執行自檢腳本確認依賴、金鑰與模型是否就緒;其次,進行跨平台的「金鑰提取」——macOS 透過 Frida hook CCKeyDerivationPBKDF 函數,Windows 則 hook SHA-512 入口攔截 HMAC ipad 明文金鑰,再使用 PBKDF2-HMAC-SHA512 推導出 SQLCipher 解密金鑰;最後,解密後的資料庫提供給 MCP 伺服器或命令列工具進行查詢與匯出。語音轉寫採用 SILK v3 解碼 → Whisper large-v3 模型,macOS 使用 mlx-whisper(Apple Silicon),Windows 使用 faster-whisper(CPU int8),全部離線完成,無需第三方音訊路由工具。 此技能特別強調安全與使用者體驗:金鑰提取為一次性操作,提取後建議重裝微信恢復簽名;Agent 在執行大模型下載(約 3GB)前必須主動徵求使用者同意;命令列支援 `--json` 輸出結構化結果,方便 Agent 解析。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add tzwkb/wechat-decrypt

Installed? Explore more 研究與資料分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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_MISSINGmacOS 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_chatcontact, limit(50), days(7)特定對話
wechat_search_messageskeyword, days(30), limit(50)全文搜尋
wechat_recent_messagesdays(3), limit(100)最近動態
wechat_chat_summarydays(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/。

相關技能