CommunityPesquisa e Análise de Dadosgithub.com

tzwkb/wechat-decrypt

Skill de agente — Decifração e consulta de bate-papos do WeChat 4.x (macOS + Windows): leitura/pesquisa via MCP, exportação, transcrição de voz.

O que é wechat-decrypt?

Este skill permite que um agente de IA (como o Claude Code) interprete e consulte o histórico de mensagens do WeChat 4.x em macOS e Windows, mesmo com criptografia SQLCipher. Ele fornece ferramentas MCP (listar conversas, ler mensagens, pesquisar, exportar) e suporta transcrição automática de áudios de voz (formato SILK) via modelos whisper offline (mlx-whisper no macOS e faster-whisper no Windows). A extração da chave de criptografia é feita por meio de hook com Frida (macOS: CCKeyDerivationPBKDF; Windows: HMAC-SHA512) sem intervenção manual complexa, e o banco de dados decifrado é lido diretamente. O agente deve executar verificações de pré-requisitos (dependências, chave, modelo de voz) antes de usar, e perguntar explicitamente ao usuário se deseja baixar o modelo de transcrição (~3GB) na primeira vez.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add tzwkb/wechat-decrypt

Installed? Explore more Pesquisa e Análise de Dados skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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"
StatusAção
MCP_MISSINGmacOS bash setup.sh / Windows powershell -File setup.ps1, informar "Reinicie o Claude Code"
KEY_MISSINGExecutar o fluxo de "extração de chave" da plataforma correspondente (no Windows, após extrair a chave, também executar python scripts\windows\decrypt_all.py para descriptografar todo o banco)
Tudo OKUsar diretamente as ferramentas MCP

Autoverificação no Windows (PowerShell, alinhado com os três itens do macOS acima):

python -c "import frida, Crypto; print('DEPS_OK')"   # Se falhar → pip install frida pycryptodome
Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\key_windows.txt"   # Se não existir → extrair chave com extract_raw_key.py
Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\decrypted"         # Se não existir → descriptografar todo o banco com decrypt_all.py

Se algum item estiver faltando, execute a etapa correspondente: deps→setup.ps1, chave→extract_raw_key.py, banco em texto claro→decrypt_all.py.

Não pule a autoverificação.

Regras de acionamento do agente

Intenção do usuárioAção
"Ver meu WeChat", "conversas recentes", "quem me procurou", "tem mensagens?"MCP: wechat_recent_messages / wechat_chat_summary
"Pesquisar conversa com XX", "mencionado por XX"MCP: wechat_search_messages
"Listar conversas", "quais grupos"MCP: wechat_list_chats
"Ler conversa com XX"MCP: wechat_read_chat
"Exportar conversa com XX", "exportar XX para a área de trabalho"Primeiro executar ① verificação de modelo (veja abaixo), depois python3 scripts/common/export_chat.py <contato> [--start/--end/--year] [-o caminho] (sem data = histórico completo; se o modelo estiver presente, a transcrição será feita por padrão, --no-transcribe para desligar; resultado da transcrição de voz é armazenado em cache persistente em voice_cache.json, segunda exportação instantânea)
"Transcrever áudio de XX", "áudio para texto", "converter áudio em texto"python3 scripts/common/export_chat.py <contato> --transcribe, ou separadamente python3 scripts/common/transcribe_db.py <contato> -o map.json
"WeChat atualizou", "re-crackear", "chave expirou"Executar o fluxo de "extração de chave" da plataforma correspondente abaixo

① Pré-requisito de exportação — Verificação do modelo de transcrição de voz (executado por padrão)

Antes de exportar/transcrever qualquer conversa que possa conter áudio, verifique se o modelo está presente:

test -d ~/.cache/huggingface/hub/models--mlx-community--whisper-large-v3-mlx && echo MODEL_OK || echo MODEL_MISSING
ResultadoAção
MODEL_OKA exportação ativa a transcrição de voz por padrão (o script detecta o modelo e transcreve automaticamente, sem precisar de --transcribe; só desligar se o usuário pedir explicitamente, com --no-transcribe)
MODEL_MISSINGPergunte primeiro ao usuário se deseja instalar (whisper-large-v3 ~3GB, offline único). Se sim → adicionar --transcribe (primeira vez baixa e transcreve automaticamente); se não → exportação normal, áudio mantido como [Audio]

O script já tem essa lógica embutida (modelo presente → transcrição padrão, ausente → mantém [Audio] e avisa). Mas quando MODEL_MISSING, o agente deve perguntar ativamente; não baixe 3GB por conta própria.

Ferramentas MCP (registradas como wechat)

FerramentaParâmetrosUso
wechat_list_chatsNenhumListar todas as conversas (nomes de grupos e apelidos já resolvidos)
wechat_read_chatcontact, limit(50), days(7)Ler uma conversa específica
wechat_search_messageskeyword, days(30), limit(50)Pesquisa em texto completo
wechat_recent_messagesdays(3), limit(100)Mensagens recentes
wechat_chat_summarydays(3)Resumo estruturado + tarefas pendentes

[Eu] = mensagens enviadas pelo usuário, [Outro] = mensagens enviadas pelo contato.

Transcrição de voz (totalmente automática)

Mensagens de voz (local_type=34) têm seu áudio armazenado como SILK v3 no banco media_0.db, campo VoiceInfo.voice_data, alinhado por svr_id == server_id. Fluxo: leitura direta de VoiceInfo → decodificação SILK→wav com pilk → transcrição com whisper large-v3 → realimentação por server_id. Totalmente automático, em lote, offline, sem necessidade de BlackHole/reprodução/reinicialização. Comportamento padrão: se o modelo estiver em cache, a transcrição é automática; --transcribe força (incluindo download inicial do modelo ~3GB, cache em ~/.cache/huggingface/); --no-transcribe desliga. O backend muda automaticamente conforme a plataforma: macOS = mlx-whisper (Apple Silicon), Windows = faster-whisper (CPU int8, download sob demanda); a abordagem antiga com BlackHole+Swift está no repositório de desenvolvimento langlobal.

Entry point de linha de comando (núcleo da lógica; MCP é uma fachada opcional)

O núcleo da lógica está em scripts/common/query.py (linha de comando); as ferramentas MCP em server.py são apenas encaminhamentos para ele. Para chamadas do agente, recomenda-se usar --json para saída estruturada (mais confiável para parsing, não afetada pela formatação do texto); para depuração humana, não usar --json, ver texto legível.

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      # agente usar --json
python3 "$SKILL_DIR/scripts/common/query.py" search 关键词 --json
# Subcomandos: list / read <contato> / search <palavra-chave> / recent / summary / stats / media / openfile

Sistema de chaves (comum a ambas as plataformas)

  • Chave bruta (Raw Key): 64 hex, independente por dispositivo (WeChat 4.0: mesma conta, chaves brutas do macOS e Windows são diferentes, não intercambiáveis); enquanto o WeChat não for atualizado, a chave permanece válida.
  • Fórmula de derivação: PBKDF2-HMAC-SHA512(chave_bruta, salt_do_arquivo_db, 256000) → 32 bytes
  • Parâmetros SQLCipher: PRAGMA key = "x'<derivada>'"; PRAGMA kdf_iter = 1; PRAGMA cipher_compatibility = 4; PRAGMA cipher_page_size = 4096;

Caminhos dos bancos de dados

PlataformaCaminho
macOS~/Library/Containers/com.tencent.xinWeChat/.../xwechat_files/{wxid}/db_storage/
Windows~/Documents/xwechat_files/{wxid}/db_storage/

Extração de chave

macOS

Fluxo de execução do agente

  1. Verificar re-assinatura: codesign -dv /Applications/WeChat.app 2>&1 | grep -q "Signature=adhoc" || echo "NEED_RESIGN"
    • NEED_RESIGN → Informar o usuário para executar sudo codesign --force --deep --sign - /Applications/WeChat.app
  2. Executar bash ~/.claude/skills/wechat-decrypt/scripts/macos/extract_key.sh
  3. O script iniciará o WeChat → Informar o usuário para escanear o QR code e fazer login → Após o login, a chave será gravada automaticamente em key.txt
  4. Verificar: test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "OK"
  5. Após a extração, o agente deve informar o usuário para restaurar a assinatura: a re-assinatura adhoc é uma operação destrutiva unidirecional; ela sobrescreve a assinatura original da Tencent, fazendo com que o WeChat exiba repetidamente caixas de diálogo de permissão para capturas de tela/acesso a dados. O codesign não pode restaurar assinaturas de terceiros; a única maneira é reinstalar o WeChat. O histórico de conversas está em um diretório de contêiner independente (~/Library/Containers/com.tencent.xinWeChat/); reinstalar /Applications/WeChat.app não o afeta. Após a extração da chave, a consulta diária de mensagens é somente leitura do banco de dados, não precisando mais de re-assinatura.

Pontos-chave

  • A re-assinatura é necessária apenas no momento da extração da chave; após a extração, reinstale o WeChat para restaurar a assinatura.
  • Caixas de diálogo de permissão repetidas = sintoma de que a assinatura do WeChat está em estado adhoc, não causado pelo Claude Code/MCP.
  • A chave é independente por dispositivo (cada conta em cada dispositivo tem chave diferente, não intercambiável); enquanto o WeChat não for atualizado, ela permanece válida, não sendo necessário extrair repetidamente.

Princípio

A versão macOS do WeChat 4.x não chama sqlite3_key (essa função do SQLite do sistema Apple é um shell vazio), mas sim usa a camada de criptografia unificada WCDB para chamar CCKeyDerivationPBKDF (CommonCrypto). O Frida usa Module.findGlobalExportByName (API Frida 17.x+) para fazer hook dessa função e capturar o parâmetro da senha quando passwordLen=32, rounds>1000, dkLen=32 (chave bruta).

Windows (já resolvido: extrair chave→descriptografar→ler, capacidade equivalente ao macOS)

Status atual (testado via UTM em 06/06/2026): extrair chave→descriptografar todo o banco→MCP/exportação/transcrição de voz, mesma capacidade do macOS. message_0 decifrado com 99 conversas/1384 mensagens. Fluxo completo em docs/2026-06-06-windows-raw-key-journey.md.

Fluxo de execução do agente

  1. Fazer login no WeChat
  2. Extrair chave: python scripts\windows\extract_raw_key.py → Seguir as instruções e reiniciar o WeChat manualmente na área de trabalho (obrigatório; iniciar via schtasks/SSH cria um processo vazio que não lê o banco) → O script faz race-attach automaticamente + hook sha512 para capturar a chave bruta + verificar, gravando em key_windows.txt
  3. Descriptografar todo o banco: python scripts\windows\decrypt_all.py → Usa a chave bruta para descriptografar todos os bancos em db_storage para o diretório decrypted\{wxid}_<device>\db_storage\ (texto claro)
  4. Reiniciar o Claude Code → Ferramentas MCP, exportação e transcrição de voz idênticas ao macOS (server/export/transcribe usam DB_BACKEND="sqlite3" para ler o banco em texto claro; voz usa faster-whisper)

Para verificar/ depurar um único banco, use scripts\windows\decrypt_read.py <chave_bruta> (apenas descriptografa message_0 para teste).

Princípio da extração de chave (hook da entrada sha512 + ipad HMAC)

Núcleo: A chave bruta/K1 na memória tem proteção tripla (chave de rodada AES-NI / limpeza pós-uso / memória segura, todas as tentativas de brute force na memória falham), mas a chave derivada do SQLCipher passa por PBKDF2-HMAC-SHA512. No momento da construção do bloco ipad do HMAC, a chave está em texto claro chave XOR 0x36 (os últimos 96 bytes são sempre 0x36) — contornando todas as proteções. extract_raw_key.py é autocontido: localiza automaticamente a entrada do sha512 (procura pela constante K 0x428a2f98d728ae22 → xref → desmontagem, sem endereços fixos, funciona mesmo se a versão do WeChat mudar) + race-attach (antes de abrir o banco) + hook na entrada (rdx = bloco de entrada) + detecção de ipad + verificação automática (PBKDF2→AES page1 resulta em chave bruta geral / AES direto resulta em K1 de banco único). Iniciar PBKDF2(raw,salt) expõe a chave bruta; em execução, page-MAC expõe apenas mac_key (inútil) → é obrigatório fazer race-attach na inicialização. O Frida sob emulação ARM (xtajit traduzindo x64) consegue fazer hook em funções x64 internas do WeChat (verificado 11,27 milhões de vezes); como spawn não é compatível, usa-se race-attach.

  • Caminho dos dados: C:\Users\<usuário>\Documents\xwechat_files\{wxid}_<device>\db_storage\. O wechat-dump-rs foi bloqueado por DMCA; este método o substitui.
  • O conjunto completo de scripts de desenvolvimento (localização/brute/registro de falhas) está no repositório de desenvolvimento langlobal; para executar, bastam extract_raw_key.py + decrypt_all.py.

Distribuição e instalação

Copie todo o diretório do skill. O destinatário executa:

macOS: bash setup.sh Windows: powershell -File setup.ps1

key.txt, contacts.json, all_keys.json, voice_cache.json são dados pessoais; remova-os antes de distribuir (já estão em .gitignore).

Lista de arquivos

~/.claude/skills/wechat-decrypt/          # Unidade de execução; desenvolvimento completo (testes/docs/scripts de pesquisa/legado) no repositório langlobal
├── server.py config.py crypto.py db.py contacts.py message.py   ← Núcleo MCP (6), db.py com backend duplo
├── scripts/
│   ├── common/    ← Multiplataforma: export_chat(exportação+transcrição) 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(autocontido para extrair chave) decrypt_all.py(descriptografa todo o banco→texto claro) decrypt_read.py(verificação de banco único)
├── setup.sh / setup.ps1   ← Instalação por plataforma
├── SKILL.md README.md LICENSE
├── key.txt key_windows.txt   ← .gitignore
└── contacts.json             ← .gitignore

Dependências: macOS Python global (mcp/frida/cryptography/pilk/mlx-whisper/zstd); Windows (mcp/frida/pycryptodome/pilk/faster-whisper/zstandard). Cache do modelo de voz em ~/.cache/huggingface/.

Habilidades Relacionadas