WJZ-P/gemini-skill

Gemini Skill

⚠️ Prioridade de Operação (obrigatório)

Toda interação com o Gemini deve seguir esta ordem de precedência:

1. 🥇 Primeira opção: chamar ferramenta MCP — Use diretamente as ferramentas MCP expostas por este Skill. Cobre a grande maioria dos cenários.
2. 🥈 Segunda opção: executar script do Skill — Quando a ferramenta MCP não for suficiente, execute os scripts fornecidos neste projeto.
3. 🥉 Última opção: conectar ao navegador gerenciado pelo Skill — Somente quando as duas formas anteriores falharem, obtenha as informações de conexão CDP via gemini_browser_info e conecte-se ao navegador gerenciado por este Skill. Esta forma requer consentimento explícito do usuário.

Proibido absolutamente: iniciar uma nova instância de navegador para acessar a página do Gemini (por exemplo, usando OpenClaw, Puppeteer, etc.). Isso causaria conflitos de sessão.

O Daemon do navegador é iniciado automaticamente pela ferramenta MCP quando não estiver rodando. Nenhuma ação manual é necessária.

📡 Regras de Sincronização de Progresso e Ferramentas de Longa Duração

As chamadas de ferramentas MCP (especialmente geração de imagens, espera por respostas) podem levar de 60 a 180 segundos. Regras obrigatórias:

• Todas as ferramentas MCP deste Skill são chamadas síncronas bloqueantes — elas retornam apenas com o resultado final. Não há "estado intermediário" que exija polling.
• Ao chamar ferramentas de longa duração, timeoutMs deve ser ≥ 180000 (3 minutos) para evitar que o timeout da camada de transporte interrompa a chamada prematuramente.
• Não encerre a conversa ou informe ao usuário "ainda executando"/"ferramenta excedeu tempo" antes de receber o retorno final da ferramenta.
• Envie uma mensagem de progresso ao usuário a cada 15-30 segundos (ex.: "Aguardando o Gemini gerar a imagem... já se passaram 30 segundos...") para manter o feedback.
• Assim que o resultado final chegar, retorne imediatamente o artefato (caminho do arquivo) ou reporte o erro. Não omita.
• Se o modo fullSize falhar, é possível fazer um fallback tentando novamente com fullSize=false (modo preview é mais estável).

Palavras-chave de Gatilho

• Tarefas de geração de imagem: gerar imagem, desenhar, ilustrar, pôster, nano banana, nanobanana, image generation, 生成图片
• Se a solicitação for ambígua, primeiro confirme se o usuário precisa de geração de imagem.

Modo de Uso

Este Skill expõe ferramentas através de um Servidor MCP, que a IA pode chamar diretamente.

Inicialização do navegador, gerenciamento de sessão, extração de imagens, salvamento de arquivos e outros processos já estão encapsulados dentro das ferramentas.

⚠️ Regra Obrigatória

A IA deve sempre realizar todas as operações através das ferramentas MCP.

É proibido contornar o MCP escrevendo scripts temporários (como node -e "..." ou criando arquivos .js temporários) para import/require funções exportadas por este projeto (como createGeminiSession, createOps, etc.).

Se a ferramenta MCP realmente não atender à necessidade atual, a IA deve primeiro explicar o motivo ao usuário e obter consentimento explícito antes de escrever um script temporário para chamar a API subjacente. Sem o consentimento do usuário, é proibido.

Ferramentas Disponíveis

Geração de Imagem Principal (fluxo completo encapsulado):

Nome da Ferramenta	Descrição	Parâmetros
gemini_generate_image	Fluxo completo de geração de imagem: nova sessão → enviar prompt → aguardar → extrair imagem → salvar localmente (leva cerca de 60–120 segundos)	prompt, newSession (padrão false), referenceImages (array de caminhos de imagens de referência), fullSize (padrão true, imagem original em alta resolução; false gera preview), timeout (padrão 120000ms)

Gerenciamento de Sessão:

Nome da Ferramenta	Descrição	Parâmetros
gemini_new_chat	Iniciar uma nova conversa em branco	Nenhum
gemini_temp_chat	Entrar no modo de conversa temporária (não mantém histórico)	Nenhum

Troca de Modelo:

Nome da Ferramenta	Descrição	Parâmetros
gemini_switch_model	Trocar o modelo Gemini	model (pro / quick / think)

Conversa de Texto:

Nome da Ferramenta	Descrição	Parâmetros
gemini_send_message	Enviar uma mensagem de texto e aguardar a resposta completa, retornando diretamente o texto da resposta do Gemini	message, timeout (padrão 120000ms)

Operações com Imagens:

Nome da Ferramenta	Descrição	Parâmetros
gemini_upload_images	Enviar imagens para a caixa de entrada (apenas envia, não envia a mensagem; pode ser combinado com send_message)	images (array de caminhos)
gemini_get_images	Obter metadados de todas as imagens carregadas na sessão	Nenhum
gemini_extract_image	Extrair o base64 de uma imagem específica e salvá-la localmente	imageUrl (obtido de get_images)
gemini_download_full_size_image	Baixar a imagem de alta resolução em tamanho completo; por padrão a mais recente, pode especificar um índice	index (opcional, começa em 0, do mais antigo para o mais novo)
gemini_share_latest_image	Criar um link de compartilhamento público para a imagem e retorná-lo diretamente; por padrão a mais recente	index (opcional), timeout, copyToClipboard, closeDialog

Extração de Respostas de Texto:

Nome da Ferramenta	Descrição	Parâmetros
gemini_get_all_text_responses	Obter todas as respostas de texto da sessão (apenas texto, sem imagens)	Nenhum
gemini_get_latest_text_response	Obter a resposta de texto mais recente	Nenhum

Status de Login:

Nome da Ferramenta	Descrição	Parâmetros
gemini_check_login	Verificar se está logado em uma conta Google	Nenhum

Navegação de Páginas:

Nome da Ferramenta	Descrição	Parâmetros
gemini_navigate_to	Abrir uma URL específica da página Gemini (ex.: link de conversa histórica). Apenas domínios gemini.google.com são permitidos	url (URL alvo), timeout (padrão 30000ms)

Diagnóstico e Recuperação:

Nome da Ferramenta	Descrição	Parâmetros
gemini_probe	Verificar o estado de vários elementos da página (caixa de entrada, botões, modelo, etc.)	Nenhum
gemini_reload_page	Recarregar a página (use quando estiver travada ou com comportamento anormal)	timeout (padrão 30000ms)
gemini_browser_info	Obter informações de conexão do navegador (porta CDP, wsEndpoint, etc.)	Nenhum

Uso Típico

Geração rápida de imagem (tudo em um passo):

1. Chame gemini_generate_image com o prompt → retorna o caminho local da imagem

Gerar imagem e obter link de compartilhamento:

1. Chame gemini_generate_image para gerar a imagem
2. Chame gemini_share_latest_image para retornar o link público

Combinação flexível (controle fino):

1. gemini_new_chat — Iniciar nova sessão
2. gemini_switch_model → pro — Trocar para modelo de alta qualidade
3. gemini_upload_images — Enviar imagens de referência
4. gemini_send_message — Enviar descrição
5. gemini_get_images → gemini_extract_image — Obter e salvar imagem

Solução de problemas:

1. gemini_probe — Verificar se os elementos da página estão no lugar
2. gemini_reload_page — Se a página travar, recarregar
3. gemini_browser_info — Obter informações CDP para conectar e depurar manualmente

Configuração do Cliente MCP

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["<caminho absoluto do projeto>/src/mcp-server.js"]
    }
  }
}

Também pode ser iniciado manualmente com npm run mcp.

Tratamento de Falhas

As ferramentas já incluem lógica de repetição interna. Se ainda assim falharem, o valor de retorno conterá isError: true e a mensagem de erro indicará a causa:

• Tempo de geração excedido — Sugira ao usuário simplificar a descrição e tentar novamente
• Daemon não iniciado — A ferramenta tentará iniciá-lo automaticamente; se ainda falhar, execute npm run daemon manualmente
• Página anormal — Chame gemini_browser_info para verificar o estado do navegador e depurar

Referência

• Execução detalhada e fallbacks: references/gemini-flow.md
• Palavras-chave e roteamento de intenção: references/intent-routing.md