stkoecn/im-mcp

Guia de Operação e Gerenciamento do Ciclo de Vida de Dados do Agente IM-MCP

Este guia instrui o agente a gerenciar o conjunto de ferramentas im-mcp (incluindo WeChat MCP e DingTalk MCP) nos ambientes Windows e macOS, abrangendo verificação prévia do ambiente, inicialização e descriptografia de banco de dados offline, pesquisa de dados de bate-papo e limpeza segura após a conclusão das tarefas.

---

1. Posicionamento Central e Estratégia de Execução

1.1 Princípio de Prioridade de Execução e Estratégia

Ao orientar ou auxiliar o usuário na implantação, o agente deve seguir as seguintes estratégias de execução:

1. Priorizar instalação persistente: Em ambientes como Claude Desktop, Cursor ou outros clientes desktop que suportam ferramentas persistentes, recomende usar uv tool install "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]";
2. Redução para ambiente restrito/sandbox: Se o ambiente atual do cliente de IA (por exemplo, ambiente sandbox Pi) bloquear a instalação global de ferramentas (exibindo Blocked ... use uvx), siga a política de segurança do ambiente e use uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" para executar comandos ad-hoc;
3. Alternativa de espelho para rede doméstica (fonte Gitee): Se o usuário estiver em um ambiente de rede doméstica ou tiver acesso limitado/lento ao GitHub, substitua o endereço Git acima pelo repositório espelho Gitee:
   • Persistente: uv tool install "git+https://gitee.com/ws4m/im-mcp.git" --with "im-mcp[all]"
   • Ad-hoc: uvx --from "git+https://gitee.com/ws4m/im-mcp.git[all]" <command>
4. Proibição de escrever código de teste de protocolo privado: Após a instalação e inicialização (wechat-init e dingtalk-init), é estritamente proibido escrever scripts ou códigos para simular testes de protocolo JSON-RPC/stdio subjacente. Deve-se entregar diretamente ao usuário e fornecer orientação de ativação do cliente;
5. Percepção do ambiente host e orientação de entrega: O agente deve, com base no ambiente do cliente atual (como Pi, Claude Code/Desktop, Cursor, Cline, etc.), determinar de forma autônoma e informar ao usuário as etapas específicas de habilitação do Skill e MCP (como informar para inserir /reload, reiniciar o cliente ou ativar a confiança na barra lateral) e fornecer diretamente 1 a 2 exemplos de uso para conversas diárias.

1.2 Matriz de Comandos e Visão Geral de Permissões

# Modo A: Instalação isolada persistente global da CLI (recomendado como primeira opção)
uv tool install "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"

Matriz de comandos:

Comando	Chamada após instalação global	Modo ad-hoc uvx em ambiente restrito/sandbox	Cenário de uso	Requisitos de permissão	Produto chave / Caminho
wechat-init	wechat-init	uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" wechat-init	Extrair chave DBKey do WeChat e descriptografar offline para banco SQLite	Windows: permissão de administrador (leitura de memória); macOS: suporta --passphrase ou configuração persistente	~/.wechat_mcp/decrypted/, ~/.wechat_mcp/app.db
dingtalk-init	dingtalk-init	uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" dingtalk-init	Extrair chave do DingTalk offline, descriptografar DB e mesclar transações WAL	Permissão de usuário comum	~/.dingtalk_mcp/decrypted/dingtalk.db
im-clean	im-clean	uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" im-clean	Limpeza segura com um clique de todos os dados descriptografados, chaves e cache	Permissão de usuário comum/administrador	Limpa as bibliotecas descriptografadas e diretórios de dados globais de ambos os itens acima
wechat-mcp	wechat-mcp	uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" wechat-mcp	Ponto de entrada padrão do servidor FastMCP do WeChat	Permissão de usuário comum	Interface stdio
dingtalk-mcp	dingtalk-mcp	uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" dingtalk-mcp	Ponto de entrada padrão do servidor FastMCP do DingTalk	Permissão de usuário comum	Interface stdio

---

2. Fluxo de Trabalho do Agente

2.1 Antes do Início da Tarefa: Inicialização Automática do Banco de Dados

Quando o usuário solicita "analisar comunicação recente do WeChat/DingTalk", "gerar relatório semanal", "procurar arquivo de grupo X" e o MCP reporta erro informando "banco de dados não encontrado" ou retorna resultados vazios, o agente deve executar a inicialização de forma autônoma:

Inicialização do Banco de Dados DingTalk

O DingTalk é descriptografado offline de forma puramente Python, quase 100% automatizado, sem necessidade de permissão de administrador:

# Agente executa a inicialização
dingtalk-init

• Saída esperada: Detecta UID ativo e exibe 🎉 Sincronização de inicialização de dados do DingTalk bem-sucedida!.
• Verificação prévia do ambiente (proibido escaneamento cego): Se for informado que o diretório de dados ou UID não foi encontrado, é proibido que o agente realize uma busca recursiva profunda e sem rumo por processos ou discos no sistema host. Pare imediatamente, explique a situação ao usuário e pergunte/lembre-o de confirmar se o cliente DingTalk está logado na máquina atual.

Inicialização do Banco de Dados WeChat

O WeChat requer chave e executa descriptografia e verificação do banco WCDB:

• Windows:

  # Windows: executar como administrador
  wechat-init
  

  O WeChat precisa extrair a chave da memória do processo do cliente em execução e executar a verificação. O cliente WeChat deve estar iniciado e logado. Se o WeChat não estiver iniciado, wechat-init reportará erro.
• macOS:

  # macOS: suporta passagem direta de passphrase de 64 bits
  wechat-init --passphrase <passphrase hexadecimal de 64 bits>
  

  A ferramenta localiza automaticamente o diretório de dados do WeChat no macOS (~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/*/db_storage), chama o CommonCrypto nativo do sistema (CCCrypt) para derivar a chave e concluir a descriptografia.
• Verificação prévia de execução do WeChat (proibido escaneamento cego):
  • Restrição importante: Se o processo do WeChat não for encontrado ou faltarem materiais de chave, o agente não deve tentar adivinhar ou escanear processos irrelevantes do sistema ou percorrer diretórios globais do sistema!
  • Ação correta: Explique claramente ao usuário o estado atual do ambiente e oriente-o a preparar o ambiente ou inserir a passphrase.
• Determinação de permissão: Se o Windows reportar Access Denied, explique o motivo e sugira executar como administrador.
• Indicador de sucesso: Geração do banco de dados descriptografado no diretório de usuário ~/.wechat_mcp/decrypted/ e conclusão da limpeza do índice FTS5 em ~/.wechat_mcp/app.db. Se apenas for necessário reexecutar a limpeza de dados e o índice, execute wechat-init --etl-only.

---

2.2 Durante a Execução da Tarefa: Especificações de Chamada de Ferramentas MCP

Após a inicialização bem-sucedida, o agente deve priorizar a pesquisa por meio de ferramentas MCP, evitando consultas SQL diretamente:

Ordem de chamada recomendada para WeChat:

1. list_wechat_sessions(limit=20): Listar as sessões/grupos ativos recentes para obter session_id chave (como xxx@chatroom ou ID do WeChat).
2. search_wechat_messages(query="palavra-chave", limit=50): Pesquisa de texto completo global no conteúdo do bate-papo (suporta paginação com offset).
3. get_session_history(session_id="...", limit=100): Obter o fluxo de mensagens de contexto da sessão alvo.
4. get_message_image(message_id=...): Descriptografia de imagem de bate-papo sob demanda. Quando a pesquisa ou o histórico de mensagens contiver [imagem], use o id da mensagem correspondente para chamar esta ferramenta.
   • Modo padrão: Retorna o caminho absoluto físico local da imagem descriptografada (armazenado em cache em ~/.wechat_mcp/images/), evitando que imagens grandes em Base64 sobrecarreguem diretamente o contexto do Agente;
   • Modo de visualização multimodal: Se o Agente atual precisar de análise visual de imagem, pode configurar include_base64=True para extrair a string Base64 para compreensão do modelo.
5. search_shared_files(keyword="...", limit=20): Localizar caminhos de arquivos transferidos em grupos ou conversas privadas.

O WeChat também oferece: get_messages_by_date / get_messages_by_range (coleta por data ou intervalo de tempo), search_contacts (consulta reversa de contatos), list_chatroom_members (lista de membros do grupo), search_media_files (caminhos de disco de imagens/vídeos), list_favorites (favoritos), list_emoticons (emoticons), get_chat_activity_stats (estatísticas de atividade), get_persona_style (destilação de estilo de comunicação), get_sync_status (atualização do índice). get_messages_by_date / get_messages_by_range e search_wechat_messages suportam paginação com offset.

Ordem de chamada recomendada para DingTalk:

1. list_dingtalk_conversations(limit=20): Obter lista de grupos e conversas privadas recentes (já mapeadas automaticamente para nomes reais e nomes de grupo atualizados).
2. search_dingtalk_messages(keyword="palavra-chave", limit=50): Pesquisa agregada de texto em 128 tabelas de partição.
3. get_dingtalk_messages(cid="...", limit=100): Visualizar detalhes da conversa em grupos ou conversas privadas específicas do DingTalk.
4. list_dingtalk_contacts(keyword="nome/pinyin"): Consulta reversa rápida de UID do contato e nome real.

---

2.3 Atualização de Versão e Manutenção

Quando o usuário solicitar "atualizar im-mcp", "atualizar WeChat/DingTalk MCP", "obter as últimas correções" ou descobrir novos recursos/correções de bugs, o agente deve executar uma atualização suave com base no método de instalação atual:

1. Atualização no modo de instalação persistente global (recomendado):

Se o usuário instalou anteriormente com uv tool install, use uv tool update ou reinstale especificando o repositório Git:

# Atualização global padrão com um comando
uv tool upgrade im-mcp

# Ou reinstalação forçada com a versão mais recente do repositório remoto (suporta o HEAD mais recente do Git)
uv tool install --force "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"

# Ambiente de rede doméstica (fonte Gitee)
uv tool install --force "git+https://gitee.com/ws4m/im-mcp.git" --with "im-mcp[all]"

2. Modo de execução ad-hoc (uvx):

Se executado em sandbox via uvx, o uvx pode armazenar em cache versões antigas do Wheel. Execute a atualização ou force a atualização do cache de versão:

# Limpar cache de ferramentas temporárias do uvx para garantir a obtenção do código Git mais recente
uv cache clean im-mcp

# Ou adicionar o parâmetro --refresh na próxima chamada ao uvx para forçar a obtenção da versão mais recente
uvx --refresh --from "git+https://github.com/stkoecn/im-mcp.git[all]" <command>

3. Recarregamento suave após atualização:

Após a conclusão da atualização, o agente deve lembrar ativamente o usuário de atualizar ou recarregar o cliente para carregar a versão mais recente da definição do serviço MCP e do conjunto de ferramentas:

• Pi / Pebrel: Solicitar a inserção de /reload;
• Claude Desktop / Cursor / WorkBuddy: Solicitar a reinicialização do cliente ou reconexão ao servidor MCP;
• Se a atualização envolver alterações na lógica de limpeza do banco de dados subjacente, execute wechat-init --etl-only para reconstruir o índice FTS mais recente em 2 segundos, sem necessidade de reextrair ou descriptografar.

---

2.4 Após a Conclusão da Tarefa: Limpeza de Privacidade e Armazenamento de Dados

Após a conclusão de relatórios semanais, resumos de horas trabalhadas ou quando o usuário solicitar explicitamente "limpar ambiente", "excluir histórico de bate-papo exportado", o agente deve chamar ativamente o im-clean:

Visualizar arquivos a serem limpos (verificação de segurança somente leitura):

im-clean --dry-run

Executar limpeza completa:

# Usar o parâmetro -y para limpeza silenciosa de todos os SQLite descriptografados, chaves e cache intermediário (suporta detecção automática e resolução de bloqueios de processos persistentes)
im-clean -y

# Se houver bloqueio de identificador residual, adicionar --force para forçar a interrupção do serviço MCP e concluir a exclusão completa
im-clean -y --force

Limpar dados de apenas uma plataforma específica:

# Limpar apenas dados do WeChat, manter DingTalk
im-clean --scope wechat -y

# Limpar apenas dados do DingTalk, manter WeChat
im-clean --scope dingtalk -y

2.5 Desinstalação Completa e Limpeza Coordenada do Cliente

Quando o usuário solicitar explicitamente "desinstalar completamente este MCP", "remover completamente a ferramenta de bate-papo e configuração", o agente deve ajudar o usuário a concluir a limpeza padrão nos níveis a seguir e informar ativamente ao usuário quais etapas ele precisa realizar manualmente na interface do cliente:

1. Sair do cliente ou parar o serviço: Lembrar o usuário de sair primeiro do cliente de IA atual, ou deixar que im-clean -y --force lide automaticamente com processos MCP residuais;
2. Limpeza automática de dados: O agente executa im-clean -y --force para limpar completamente ~/.wechat_mcp e ~/.dingtalk_mcp (garantir código de retorno 0; se não for 0, é estritamente proibido relatar sucesso);
3. Desinstalação automática de dependências: O agente executa uv tool uninstall im-mcp ou uv cache clean para limpar o ambiente e o cache;
4. Fornecer ativamente ao usuário lembretes de limpeza manual do cliente:
   • O agente deve, com base no cliente host atual, informar ao usuário sobre a limpeza manual dos arquivos de configuração (caminhos comuns para cada ambiente podem ser consultados no [Apêndice: Diretórios de referência do ambiente host do agente principal] no final deste guia).

---

3. Tratamento de Falhas Comuns e Regras de Comportamento do Agente

1. Regra fundamental: Pare imediatamente em caso de erro, é estritamente proibido analisar código ou tentativas cegas:

   • Se durante a instalação, inicialização ou chamada de teste ocorrer qualquer erro desconhecido, conflito de ambiente ou anomalia de execução:
   • Absolutamente proibido: O agente não pode, em hipótese alguma, vasculhar o código-fonte, escrever patches para corrigir o código, tentar repetidamente adivinhar ou escanear cegamente o ambiente do sistema;
   • Obrigatório: Pare imediatamente na etapa com erro, mostre o resumo do erro principal e pergunte claramente ao usuário:

     "Ocorreu um erro na etapa atual: [Breve descrição do erro]. Você gostaria que investigássemos para resolver o problema ou prefere parar a operação e não usar mais?"

   • Deixe o controle com o usuário; aja somente após o usuário confirmar se deseja continuar ou sair.

2. Após a instalação e inicialização, entregue imediatamente ao usuário, é estritamente proibido escrever código para simular protocolo e testar repetidamente:

   • Após a conclusão da instalação da ferramenta (como uv tool install), escrita dos arquivos de configuração e inicialização init, todo o processo de implantação está concluído.
   • Absolutamente proibido: O agente escrever scripts de teste Python/Node para simular handshake JSON-RPC 2.0, comunicação por pipe ou explorar detalhes internos do protocolo. Isso não apenas aumenta o consumo de tokens e o risco de erros inesperados incontroláveis, mas também tira a percepção e o controle do usuário em tempo real.
   • Obrigatório: Após a instalação e inicialização, entregue diretamente e forneça a orientação de uso mais simples e amigável:
     1. Instrua claramente o usuário a ativar/confiar no MCP no cliente atual (por exemplo, informar o usuário do Pi para executar /reload, usuário do Claude Desktop / Cursor para reiniciar o cliente);
     2. Forneça 1 a 2 exemplos simples e intuitivos de linguagem natural para orientar a experiência do usuário, por exemplo:

        "Instalação e inicialização concluídas! Confirme que confiou/ativou este MCP no seu cliente (por exemplo, executando /reload). Depois, é só me dizer algo como: 👉 'Me ajude a ver o que foi conversado no grupo do projeto recentemente' 👉 'Encontre os resultados de relatórios que Cheng Peng enviou no DingTalk' 👉 'Resuma as conversas da semana passada sobre o requisito X para fazer um relatório semanal'"

3. Autorização e confiança do cliente e aplicativo (identificação autônoma do ambiente host e orientação de ativação):

   • O agente deve identificar de forma autônoma o cliente host que o usuário está usando com base nas características da sessão atual;
   • É estritamente proibido dizer vagamente "ative no seu cliente", mas sim fornecer a maneira específica de ativação para o cliente host atual (por exemplo, informar o Pi para inserir /reload, ou informar aplicativos de desktop para reiniciar para que a alteração entre em vigor; consulte o apêndice no final para obter características específicas).

4. Regras de comportamento quando o processo do WeChat/DingTalk não é encontrado:

   • Proibido executar varreduras invasivas e demoradas em todo o disco ou adivinhar outros processos do sistema no host;
   • Obrigatório parar imediatamente e confirmar amigavelmente com o usuário o status de login do cliente.

5. Sincronização de mensagens incrementais do WeChat: Quando o cliente WeChat está online, novas mensagens são escritas no banco de criptografia original. Para obter mensagens recém-geradas, o agente pode informar o usuário a "reexecutar wechat-init" para atualizar a biblioteca descriptografada local.

6. Problema de bloqueio WAL do DingTalk: dingtalk-init já possui mecanismo de cópia automática embutido, portanto, mesmo que o DingTalk esteja em execução e em uma transação WAL, não ocorrerá conflito de bloqueio do SQLite.

7. Princípio de privacidade e segurança: O banco de dados SQLite descriptografado é privacidade local sensível. Em máquinas públicas ou ambientes multiusuário, após a conclusão do trabalho, é obrigatório orientar ou executar automaticamente im-clean -y.

8. Relatório de feedback de implantação e mecanismo automático de desenvolvimento da comunidade:

   • Quer a implantação e inicialização sejam bem-sucedidas ou enfrentem falhas, ao final do processo, o agente deve organizar e gerar para o usuário um resumo estruturado e conciso do Relatório de Feedback de Implantação e Operação, e informar que ele pode ser copiado com um clique e enviado como Issue no GitHub.
   • ⚠️ Princípio de destaque central (deve ser marcado com destaque, é estritamente proibido ser vago):
     • O título e a primeira linha de status do relatório devem usar identificadores visuais extremamente chamativos (como 【Status: 🟢 Implantação bem-sucedida / SUCCESS】 ou 【Status: 🔴 Implantação bloqueada / FAILED】);
     • É terminantemente proibido usar narrativas ambíguas ou neutras, para que o consulente e o agente de diagnóstico possam ver claramente se foi sucesso ou falha.
   • Compromisso de operação automatizada do agente: Informe ao usuário: "Este projeto está integrado a um pipeline de colaboração automatizada do GitHub Agent. O Issue que você enviar será automaticamente reproduzido, diagnosticado, corrigido e mesclado por um agente dedicado!"
   • Modelo padrão de geração de relatório:
     • Se bem-sucedido (SUCCESS):

       ### 📋 Relatório de Feedback de Implantação do im-mcp 【Status: 🟢 Implantação bem-sucedida / SUCCESS】
       > **Conclusão final**: ✅ Todas as dependências instaladas com sucesso, extração de dados e sincronização de índice concluídas, serviço pronto para uso imediato!
       
       - **Status principal**: 🟢 SUCCESS
       - **Informações do ambiente**: Versão do SO (ex: Win11 23H2), Cliente host (ex: WorkBuddy / Pi / Claude Desktop), Versão do Python e uv
       - **Modo de instalação**: `uv tool install` / `uvx` / Código-fonte local
       - **Métricas de inicialização**: Tempo gasto (ex: WeChat 12s / DingTalk 3s), Número de contatos/sessões/mensagens sincronizados
       - **Sugestões de uso**: Experiência de inicialização a frio, orientação de sincronização incremental ou expectativas de funcionalidades futuras
       - **Entrada de feedback**: Acesse [GitHub Issues](https://github.com/stkoecn/im-mcp/issues) para enviar sua experiência, o Agente da comunidade rastreará e otimizará automaticamente!
       

     • Se falhou ou encontrou obstáculo (FAILED):

       ### ⚠️ Relatório de Feedback de Implantação do im-mcp 【Status: 🔴 Implantação bloqueada / FAILED】
       > **Conclusão final**: ❌ O processo foi interrompido no meio do caminho. O serviço principal não pode ser iniciado normalmente. Consulte a localização da falha abaixo.
       
       - **Status principal**: 🔴 FAILED
       - **Etapa bloqueada**: Instalação de dependência / Extração de chave do WeChat / Descriptografia do DingTalk / Construção de índice do banco de dados / Montagem do cliente
       - **Características do ambiente**: Versão do SO, Cliente host, Versão do WeChat (ex: 4.x / 3.x), Versão do DingTalk (ex: 7.x V3)
       - **Resumo do erro principal**: Extrair o stack trace principal do erro ou aviso do sistema (ex: Access Denied / Processo não em execução / Bloqueio de arquivo negado)
       - **Medidas já tentadas**: Tentou elevação de privilégio? Tentou `--force` ou `--etl-only`?
       - **Sugestões de melhoria**: Aponte as etapas atuais que não são suaves ou que precisam de tolerância a falhas automatizada da ferramenta
       - **Feedback com um clique**: Copie este relatório e vá para [GitHub Issues](https://github.com/stkoecn/im-mcp/issues) para enviar. O agente dedicado do repositório analisará os logs e iniciará a correção automaticamente!
       

---

4. Apêndice: Diretórios de Referência do Ambiente Host do Agente Principal (Apenas para Referência)

💡 Declaração: Este diretório lista o comportamento padrão e as características de configuração dos principais ambientes de clientes/agentes de IA atuais, apenas para referência. As plataformas podem ter ajustes com atualizações de versão; consulte a documentação oficial mais recente da plataforma correspondente.

Ambiente do Cliente	Características Típicas de Identificação	Referência de Configuração/Ativação	Referência de Desinstalação/Limpeza
Pi / Pebrel	Presença de variáveis de ambiente PI_* ou diretório ~/.pi/	Editar ~/.pi/agent/mcp.json, inserir /reload na sessão para recarregar	Remover entrada de mcp.json, excluir ~/.agents/skills/im-mcp, inserir /reload
Claude Desktop	AppData local com configuração do Claude	Editar %APPDATA%\Claude\claude_desktop_config.json, reiniciar completamente o aplicativo cliente	Remover entrada de mcpServers no arquivo de configuração e reiniciar o software; limpar diretório do skill
Cursor	Derivado do VS Code, com configuração do Cursor	Adicionar em Settings ➔ Features ➔ MCP Servers, montagem instantânea na interface	Clicar em Delete / Remove na lista de servidores MCP
Cline / Roo Code	Painel de extensão do VS Code	Adicionar configuração na aba MCP da barra lateral de extensão, ativar e autorizar com "Enabled"	Desligar o interruptor ou clicar no ícone de lixeira na lista MCP da barra lateral
Cherry Studio	Ferramenta de gerenciamento de múltiplos modelos para desktop	Adicionar comando stdio em Configurações ➔ Servidor MCP, salvar para aplicar	Selecionar e clicar em "Excluir" na lista de servidores MCP, salvar configurações
WorkBuddy	Presença do diretório ~/.workbuddy/ ou configuração relacionada	Editar ~/.workbuddy/mcp.json, clicar manualmente em "Confiar/Ativar" na interface de gerenciamento de conectores	Remover bloco de configuração de mcp.json e remover conector na interface