Implantação e integração do GenericAgent: robôs em toda a plataforma WeChat/QQ/Feishu

Visão geral do projeto

GenericAgent é uma estrutura de agente autônomo extremamente minimalista, com capacidade de se autogeralizar (autoevoluir). Seu núcleo tem apenas ~3K linhas de código e, com 9 ferramentas atômicas + um Agent Loop de ~100 linhas, ele concede a qualquer LLM controle em nível de sistema sobre o computador local.

A filosofia de design é bem interessante: não pressupõe habilidades; obtém capacidades pela evolução. A cada nova tarefa resolvida, o GenericAgent fixa automaticamente o caminho de execução como uma Skill. Quanto mais tempo você usa, mais skills ficam sedimentadas, formando uma árvore de habilidades totalmente sua — crescendo a partir de um código-fonte-semente de 3K linhas.

Em comparação com o OpenClaw (~530K linhas de código), o GenericAgent segue uma rota minimalista: implantação simples (pip install + API Key), sem necessidade de orquestrar múltiplos serviços, mas ainda preserva capacidades centrais como controle completo do navegador, operações de teclado e mouse e controle de dispositivos móveis via ADB.

---

Dificuldade/Duração/Benefícios

• Dificuldade: nível iniciante, sem necessidade de experiência aprofundada em programação
• Duração: cerca de 30 minutos
• Benefícios: dominar a configuração e a implantação do GenericAgent + integrar com as três plataformas de IM (WeChat/QQ/Feishu), para controlar a IA do computador com o celular a qualquer hora e em qualquer lugar

---

Perfil de público-alvo

• Desenvolvedores backend ou full-stack com 1 a 5 anos de experiência
• Pessoas que querem montar um assistente de IA pessoal e fluxos de trabalho automatizados
• Quem tem interesse em tecnologia de agentes e quer experimentar rapidamente "fazer com que a IA realmente trabalhe por você"
• Necessidade de integração de IM em múltiplas plataformas (por exemplo, controlar remotamente o computador via WeChat/QQ)

---

Dependências principais e ambiente

---

Estrutura completa do projeto

GenericAgent/
├── agentmain.py              # Ponto de entrada principal, com suporte ao modo de linha de comando
├── launch.pyw                # Script de inicialização da GUI desktop
├── agent_loop.py             # Agent Loop principal (cerca de 100 linhas)
├── llmcore.py                # Gerenciamento de sessão do LLM
├── ga.py                     # GenericAgentHandler, gerenciamento de memória e despacho de ferramentas
├── frontends/                # Adaptadores para plataformas de IM
│   ├── wechatapp.py         # Bot do WeChat
│   ├── qqapp.py             # Bot do QQ
│   ├── fsapp.py             # Bot do Feishu
│   ├── tgapp.py             # Bot do Telegram
│   ├── wecomapp.py          # Bot do WeCom (WeChat corporativo)
│   ├── dingtalkapp.py       # Bot do DingTalk
│   ├── tuiapp.py            # UI do terminal
│   └── ...
├── assets/
│   ├── mykey_template.py    # Modelo de configuração de API Key
│   ├── tools_schema.json    # Definições de 9 ferramentas atômicas
│   ├── sys_prompt*.txt      # Prompts do sistema
│   └── tmwd_cdp_bridge/    # Plugin de injeção no navegador
├── memory/                   # Diretório de armazenamento de memória
└── temp/                     # Arquivos temporários e logs

---

Passo a passo

Step 1: Instalar o projeto e as dependências

Primeiro, clone o repositório e instale as dependências básicas:

# Clonar repositório
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# Instalar dependências básicas
pip install requests

# Instalar dependências da GUI (modo desktop)
pip install streamlit pywebview

# Ou instalar dependências da UI de terminal
pip install requests textual

Step 2: Configurar a API Key

Copie o modelo de configuração:

cp assets/mykey_template.py mykey.py

Edite mykey.py e preencha sua configuração de LLM. A seguir está um exemplo usando Defapi (como exemplo, Claude):

# Usar Claude via Defapi (meio preço oficial)
native_claude_config = {
    'name': 'claude-defapi',                    # Nome exibido
    'apikey': 'sk-ant-your-defapi-key',         # Key fornecida pela Defapi
    'apibase': 'https://api.defapi.org',        # Endpoint da Defapi
    'model': 'claude-sonnet-4-6',               # ou claude-opus-4-7
    'fake_cc_system_prompt': True,              # O serviço proxy precisa disso
    'thinking_type': 'adaptive',
    'max_tokens': 16384,
}

O GenericAgent identifica automaticamente o formato do protocolo com base no nome das variáveis:

• Contém native + claude → NativeClaudeSession (campo de ferramentas do tool nativo)
• Contém native + oai → NativeOAISession (campo de ferramentas do tool nativo do OpenAI)
• Contém claude (sem native) → ClaudeSession (ferramentas em protocolo textual)

Step 3: Iniciar o GenericAgent

Primeiro, teste se o modo de linha de comando funciona corretamente:

python agentmain.py

Você deve ver o prompt de interação >, e então inserir uma frase para testar:

> Crie um hello.txt na área de trabalho com o conteúdo Hello World

Se tudo estiver correto, o Agent executará a tarefa e retornará o resultado.

Mude para o modo GUI desktop:

python launch.pyw

---

Step 4: Integrar o Bot do WeChat

O Bot do WeChat suporta login por leitura de QR code do WeChat pessoal, sendo a integração mais simples.

Instalar dependências adicionais:

pip install pycryptodome qrcode requests

Configuração (opcional; dá para usar mesmo sem configurar, mas recomenda-se definir uma lista de permissões):

No mykey.py, adicione:

# Lista branca do WeChat; preencha o ID do WeChat. Se não preencher, permite todos os usuários
wechat_allowed_users = []

Iniciar o Bot do WeChat:

python frontends/wechatapp.py

Na primeira inicialização, será aberta uma janela de QR code; confirme com o WeChat escaneando. Após o login bem-sucedido, seu WeChat se transforma na interface para conversar com o GenericAgent.

Step 5: Integrar o Bot do QQ

O Bot do QQ usa a API oficial de robôs do QQ, não precisa de webhook público, e recebe mensagens via uma conexão longa WebSocket.

Instalar dependências:

pip install qq-botpy

Configuração:

1. Acesse QQ Open Platform e crie um robô, obtendo AppID e AppSecret
2. No mykey.py, adicione:

qq_app_id = "SEU_APP_ID"
qq_app_secret = "SEU_APP_SECRET"
qq_allowed_users = ["openid_do_usuario"]  # ou ['*'] para permitir todos

Iniciar o Bot do QQ:

python frontends/qqapp.py

Depois de enviar uma mensagem ao robô pela primeira vez, o openid do usuário será registrado em temp/qqapp.log.

Step 6: Integrar o Bot do Feishu

O Bot do Feishu suporta vários formatos de mensagens, como texto, rich text, imagens, arquivos, áudio e cards de interação.

Instalar dependências:

pip install lark-oapi

Configuração:

1. No Feishu Open Platform, crie um aplicativo corporativo interno e obtenha AppID e AppSecret
2. No mykey.py, adicione:

fs_app_id = "cli_xxxxxxxxxxxxxxxx"
fs_app_secret = "xxxxxxxxxxxxxxxx"
fs_allowed_users = ["ou_xxxxxxxxxxxxxxxx"]  # ou ['*'] para permitir todos

Iniciar o Bot do Feishu:

python frontends/fsapp.py

Step 7: Validar e ajustar

Todos os Bots suportam estes comandos genéricos:

• /new - inicia um novo diálogo, limpando o contexto atual
• /continue - lista snapshots de sessões que podem ser restauradas
• /continue N - restaura a N-ésima sessão histórica

Validar integração simultânea em múltiplas plataformas:

Se você quiser rodar vários Bots ao mesmo tempo, basta abrir vários terminais:

# Terminal 1: WeChat
python frontends/wechatapp.py

# Terminal 2: QQ
python frontends/qqapp.py

# Terminal 3: Feishu
python frontends/fsapp.py

---

Solução de problemas frequentes

1. Após configurar a API Key, aparece erro de autenticação

Causa: nome da variável digitado errado ou configuração incorreta de fake_cc_system_prompt

Solução:

• Confirme que o nome da variável contém as palavras-chave corretas (como native_claude, oai_config etc.)
• Para serviços de proxy, é obrigatório fake_cc_system_prompt: True
• Verifique se apibase está correto (por exemplo, Defapi usa https://api.defapi.org)

2. Após escanear no WeChat, aparece falha no login

Causa: restrições de risco/controle do WeChat para login de novos dispositivos

Solução:

• Tente confirmar o login no celular (às vezes é necessária verificação adicional no celular)
• Garanta que a conta do WeChat não tenha comportamento anormal
• Reduza a frequência de uso do Bot para evitar ativar controles de segurança

3. O Bot do QQ não recebe mensagens

Causa: o robô não foi ativado ou houve erro na configuração de permissões

Solução:

• Confirme na QQ Open Platform que o robô está habilitado
• Verifique se você adicionou corretamente a assinatura/assinatura de eventos (é necessário subscrever o evento de mensagens de conversa privada)
• Verifique temp/qqapp.log para confirmar se o openid do usuário está sendo registrado corretamente

4. O Bot do Feishu responde com alto atraso

Causa: a inferência do LLM em si é lenta, ou há atraso de rede

Solução:

• Use um modelo mais rápido (como GPT-4o-mini, MiniMax-M2)
• Verifique a latência da rede até a API do LLM
• Ajuste de forma apropriada max_tokens para acelerar a resposta do primeiro token

5. O Bot não consegue lembrar o contexto da conversa

Causa: você executou o comando /new ou a sessão expirou

Solução:

• Use o comando /continue para restaurar sessões históricas
• Confirme que o diretório memory/ tem permissão de escrita
• Verifique se há registros de sessão no diretório temp/model_responses/

6. Em tempo de execução, aparece ModuleNotFoundError

Causa: falta um pacote de dependências

Solução:

# Faça com que o Agent instale
> Por favor, ajude-me a instalar todas as dependências Python necessárias

# Ou instale manualmente dependências comuns
pip install requests pycryptodome qrcode streamlit pywebview

---

Leitura adicional / Direções avançadas

Capacidade de automação do navegador

Após desbloquear as ferramentas Web, o GenericAgent pode operar em um navegador real com sua sessão de login preservada:

> Executar web setup sop, desbloquear web tools

Depois, você pode usar assim:

> Abrir Taobao, pesquisar iPhone 16 e ordenar por preço
> Ir para a Bilibili e ver os vídeos do meu histórico de visualização recente

O plugin do navegador fica em assets/tmwd_cdp_bridge/ e suporta navegadores populares como Chrome/Edge.

Explicação detalhada do mecanismo de autoevolução

A diferença central do GenericAgent está em que a cada tarefa concluída, o caminho de execução é automaticamente consolidado como uma Skill. Na próxima vez que você encontrar uma tarefa semelhante, ela será chamada diretamente, sem necessidade de redescobrir tudo.

Isso significa que:

• Quanto mais você usa, mais o Agent entende seu fluxo de trabalho
• A árvore de skills é totalmente sua, sem se parecer com "skills pré-definidas" de outras pessoas
• Um código-semente de 3K linhas pode crescer para possibilidades infinitas

Ecossistema de Skill Library

A comunidade já acumulou skills em nível de milhão ( artigo na conta oficial ), e você pode:

• Pedir para o Agent buscar: Me encontre uma skill para fazer XXX
• Importar diretamente: Acesse XXX e faça seguindo esta skill

Modo avançado

Todas as funcionalidades avançadas do GenericAgent são autodocumentadas — basta perguntar ao Agent:

Habilidades de programação e comparação com Claude Code

Muitos desenvolvedores se perguntam: o GenericAgent consegue substituir o Claude Code ou o Codex?

Resposta: ele consegue programar, mas não substitui completamente.

Capacidade de programação do GenericAgent

O GenericAgent executa código arbitrário por meio da ferramenta code_run, combinada com operações de arquivo como file_read/file_write/file_patch. Ou seja, a capacidade de programação é completa. Desde que você configure um modelo bom em programação (como Claude, GPT-4o), ele consegue:

• Ler e escrever arquivos
• Executar comandos de linha de comando
• Depurar código
• Explicar a lógica do código

# Configurar Claude como backend
native_claude_config = {
    'apikey': 'your-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,
}

Então você pode programar diretamente em linguagem natural:

> Crie uma função de quicksort rápida e depois execute os testes
> Implemente um servidor HTTP usando Python
> Explique como este componente React funciona

Diferença em relação a Claude Code / Codex

A diferença-chave é: Claude Code trabalha por meio do seu próprio protocolo e toolchain (semelhante ao MCP), então o GenericAgent não consegue chamá-los diretamente. Mas há maneiras indiretas:

Método 1: Uso paralelo com Codeg

Codeg pode iniciar o GenericAgent + Claude Code + Codex simultaneamente; eles colaboram dentro da mesma interface:

# Colocar GenericAgent e Codeg no mesmo nível
/workspace/
  ├── GenericAgent/
  └── codeg/

# O Codeg detecta automaticamente o GenericAgent e usa em paralelo

Método 2: Via proxy por API

O NativeClaudeSession do GenericAgent utiliza um protocolo compatível com Claude Code. Se o seu serviço de proxy (como Defapi) suportar passagem (transparência) do Claude, você consegue usar as capacidades de programação do Claude via GenericAgent:

# GenericAgent programando com as capacidades do Claude
native_claude_config = {
    'name': 'claude-defapi',
    'apikey': 'your-defapi-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,  # Passagem do protocolo do Claude Code
}

Conclusão

---

Referência

• GitHub: lsdefine/GenericAgent
• Relatório técnico: arXiv:2604.17091
• Tutorial de início: Datawhale Hello GenericAgent
• Guia de configuração do Feishu: assets/SETUP_FEISHU.md