Communitygithub.com

tzwkb/wecom-agent

Skill para agente — Operações via API de aplicativo autoconstruído do WeCom (mensagens, contatos, calendário, documentos) e descriptografia de bate-papo no macOS.

O que é wecom-agent?

Este skill capacita agentes de IA (como Claude Code, Cursor, etc.) a interagir com o WeCom (WeChat Work) de forma abrangente: desde o envio de mensagens, gerenciamento de contatos, documentos e calendários via API oficial, até a descriptografia e análise local de conversas no macOS e Windows. Ele suporta três linhas de ação: (A) operações ativas via chamadas de API oficiais (mensagens, contatos, documentos, calendário, reuniões); (B) leitura local de histórico de bate-papo descriptografado (incluindo exportação estruturada com remetente, hora, conteúdo, e tipos como texto, imagem, áudio, documentos, cartões, etc.), permitindo consultas e análises totalmente offline (pesquisa, estatísticas, exportação de mídia); (C) recebimento em tempo real de mensagens do WeCom e processamento autônomo com resposta automática ou criação de documentos, usando um LLM configurável. O skill já foi verificado em macOS (com necessidade de re-assinatura ad-hoc do WeCom) e Windows (sem necessidade de re-assinatura), e oferece interface de linha de comando unificada (wecom_local.py/run.ps1) e uma camada MCP opcional para integração com ferramentas como Claude Code. Ele é ideal para desenvolvedores que precisam automatizar fluxos de trabalho do WeCom, como notificações, consultas de contatos, backup de conversas, ou criação de bots inteligentes que respondem a mensagens recebidas.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add tzwkb/wecom-agent

Perguntar na sua IA favorita

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

Documentação

wecom-agent — Agente completo do WeCom (Enterprise WeChat)

LinhaCapacidadeEntradaDependência
A Operações ativasEnviar mensagens/Contatos/Ler & escrever documentos/Agenda/Reuniõeswecom.pyCorpID+Secret+AgentId + IP confiável
B Leitura localDescriptografar e exportar histórico de bate-papo (sessão/remetente/hora/conteúdo)decrypt/WeCom logado + re-assinatura ad-hoc (remover hardened runtime)
C Recepção em tempo real + processamento autônomoReceber mensagens → analisar → responder automaticamente/criar documentosrecv_server.py+agent_worker.pyCredenciais da linha A + Token de recebimento/AESKey + URL pública

Consulte README.md e docs/Guia-de-Configuracao-de-Aplicativo-Autoconstruido.md. As credenciais ficam em config.json (já no gitignore).

A Operações ativas (API oficial)

python3 wecom.py <categoria> <método> '<parâmetros_json>'   # Saída JSON, errcode:0 sucesso
categoriamétodoparâmetrosFunção
contactdepartmentsnenhumLista de departamentos (nome+ID)
contactusers{"department_id":1}Membros do departamento (userid+nome)
contactget/search/list_id{"userid"/"keyword":..}Detalhes do membro/procurar por nome/Lista de IDs
messagetext/markdown/news{"touser":"x","content":".."}Enviar mensagem (touser padrão @all, vários usuários separados por |)
doccreate/get/edit/del/rename/sheet_get/sheet_editcorpo pass-throughLer & escrever/editar documentos e planilhas online (edit=batch_update)
schedule/meetingadd/create/list..corpo pass-throughAgenda/Reuniões
callEscotilha de emergência{"path":"/cgi-bin/..","body":{}}Qualquer interface oficial

Operações de escrita (enviar mensagem/excluir agenda/alterar documento) devem ser confirmadas com o usuário antes da execução.

B Leitura local do histórico de bate-papo

Dividido por sistema: macOS → decrypt/macos/, Windows → decrypt/windows/; o núcleo de descriptografia wxwork_crypto.py + análise export_wxwork.py em decrypt/ são compartilhados entre ambos os sistemas (mesmo AES wxSQLite3, já verificado em ambos).

macOS (verificado)

Pré-requisitos: WeCom em execução e logado + re-assinatura ad-hoc do WeCom (veja docs/Ideias-de-Descriptografia.md, [[wechat_codesign_pitfall]]).

python3 decrypt/macos/read_wecom.py        # ★Um comando: verifica se a chave é válida; se sim, pula → descriptografa → exporta
python3 decrypt/macos/find_key_fast.py     # Extrair chave separadamente (escaneia memória do processo ativo, só leitura, sem injeção); salva em wxwork_keys.json
python3 decrypt/macos/decrypt_wxwork.py    # Descriptografar todo o banco → decrypt/macos/decrypted/
python3 decrypt/macos/monitor.py --once    # Incremental (--poll N para monitoramento contínuo)

A análise já cobre: nome verdadeiro do remetente (Session.db USER), nome da conversa, tipo de mensagem — texto / imagem / [Áudio] / [Arquivo] nome / [Documento] título+link / [Cartão] título+link / sistema / reunião. Transcrição de áudio opcional: voice_transcribe.py (cache local SILK→whisper, requer pilk+mlx-whisper, cobre apenas áudios já reproduzidos). Após salvar a chave no disco, os passos (2), (3) e monitor não precisam escanear a memória novamente. Alternativa offline find_key_offline.py. Consulte docs/Ideias-de-Descriptografia.md. Os resultados são privados e estão no gitignore.

Consultas/análises de dados locais (após descriptografia, totalmente local sem rede): python3 decrypt/macos/wecom_local.py <subcomando>

SubcomandoFunção
contacts [palavra]Contatos: 138 pessoas (nome/departamento/cargo/telefone/email), pode filtrar por palavra
conversationsLista de conversas (nome/número de mensagens/último horário)
members <conversa>Membros do grupo (ordenados por número de mensagens)
search <palavra>Pesquisa de texto completo nas mensagens
statsEstatísticas (ranking de mensagens/ranking de conversas/tipo/por hora/por dia)
todo / calendarTarefas locais / Agenda
media [--out]Exportar cache de imagens e arquivos em texto claro (161 imagens + 119 arquivos)
openfile <nome/palavra>Encontrar documento na conversa → localizar arquivo original → para tipos textuais analisar conteúdo (txt/csv/md/xlsx/docx/PDF textual, requer openpyxl/pdfplumber/python-docx); imagens/PDFs escaneados retorna 🖼️VISUAL <caminho> → você usa Read multimodal para visualizar diretamente. Imagens inline (type29) não podem ser localizadas por mensagem; use media para exportar e depois navegar multimodal

Transcrição de áudio: python3 decrypt/macos/voice_transcribe.py (cache SILK→whisper large-v3, verificado em 6 mensagens).

MCP (camada fina opcional, alinhada com wechat)

O núcleo lógico é o comando wecom_local.py (--json para estruturação); as ferramentas MCP em server.py apenas encaminham chamadas para ele, sem lógica própria. Não precisa de MCP — basta executar wecom_local.py <subcomando>.

Registro: bash setup.sh (instala mcp + claude mcp add wecom) → reiniciar Claude Code. Ferramentas: wecom_contacts/conversations/members/search/stats/todo/calendar/media/openfile (parâmetros iguais aos subcomandos). Pré-requisito: primeiro executar read_wecom.py para descriptografar, e ter decrypt/macos/decrypted/ pronto.

Windows (verificado · UTM Win11 ARM · ponta a ponta 12/12)

Pré-requisitos: WXWork em execução e logado + Python instalado + pip install pycryptodome (backend de descriptografia; cryptography não tem wheel para win-arm64). Para análise de documentos com openfile, instale também pip install openpyxl xlrd pypdf python-docx. Não precisa de re-assinatura.

# ★Um comando: escanear chave → descriptografar → executar subcomando
powershell -ExecutionPolicy Bypass -File decrypt/windows/run.ps1 <subcomando>
#   Subcomandos (alinhados com macOS wecom_local):
#   read | contacts [palavra] | conversations | members <conversa> | search <palavra> | stats
#   todo | calendar | media [--out] | openfile <nome> | voice | monitor
powershell -ExecutionPolicy Bypass -File decrypt/windows/run_test.ps1   # Teste ponta a ponta de 12 itens → relatório
# Passo a passo:
powershell -ExecutionPolicy Bypass -File decrypt/windows/find_key.ps1   # PS+C# embutido escaneia memória do WXWork.exe (ReadProcessMemory)→ KEY=<hex>
python decrypt/windows/wecom_win.py <chave> <subcomando>                # Reutiliza wxwork_crypto/export_wxwork/read_doc da raiz

Resolução de nomes: user.db (uid→nome/telefone/email) + session.db (conversa→nome), 1:1 para obter o outro. Bancos em Documents\WXWork\<id>\Data\, cache de texto claro em …\Cache\{File,Image,Voice}. As tags content_type são mapeadas segundo os códigos do Windows (cobrindo a tabela de renderização do export_wxwork). Transcrição voice: no Windows x64 com faster-whisper+pilk funciona; na versão ARM, não há wheel win_arm64/ferramentas C++ → não disponível (localização/exportação ainda funcionam).

C Recepção em tempo real + processamento autônomo

# 1. Configure "Receber mensagens" (URL/Token/EncodingAESKey) conforme docs/Guia-de-Configuracao-de-Aplicativo-Autoconstruido.md
# 2. Exponha em rede pública: cloudflared tunnel --url http://localhost:8000
python3 recv_server.py               # Verificar assinatura+descriptografar AES+ACK rápido+enfileirar em jobs/inbox.jsonl
python3 agent_worker.py              # Ler fila→decidir→responder/criar documento via wecom.py

Em config.json, configure llm_base_url/llm_key/llm_model (compatível com OpenAI) → LLM decide autonomamente; "auto_reply":false apenas registra sem enviar (revisão manual).

Regras de ativação do agente

O usuário dizChamar
"Exportar/ler meu bate-papo do WeCom"Linha B em três passos
"Enviar WeCom para X" / "Notificar X"message text
"Consultar contatos" / "Encontrar pessoa chamada X"contact users/search
"Criar/ler documento do WeCom"doc create/get
"Agendar reunião" / "Criar evento"meeting create/schedule add
"Fazer o agente responder WeCom automaticamente"Linha C (recv_server + agent_worker)
Interface não encapsuladacall

Status

  • B Leitura local: ✅ Verificado com dados reais (5458 mensagens estruturadas).
  • A Operações ativas: Código pronto, endpoints corrigidos conforme documentação oficial; aguardando integração com credenciais reais (gettoken já testado com sucesso).
  • C Recepção em tempo real + processamento autônomo: Criptografia de retorno de chamada e ciclo de decisão testados com sucesso; aguardando integração com credenciais + URL pública.
  • Leitura de contatos está sujeita às restrições de privacidade do WeCom (requer escopo de visibilidade + permissões, caso contrário 60011/60020).

Habilidades Relacionadas