codecell-germany/gemini-pdf-img-ocr-agent-skill

gemini-ocr-cli

Quando usar

Use esta skill quando uma tarefa precisar de OCR de alta qualidade em um fluxo de trabalho terminal local e o próprio OCR do modelo hospedeiro não for suficientemente confiável.

Use-a especialmente quando um agente precisar:

• Converter uma imagem local em Markdown fiel,
• Converter um PDF local em Markdown fiel,
• Preservar a estrutura de página, tabelas e rótulos da melhor forma possível,
• Trabalhar por meio de uma CLI determinística em vez de prompts multimodais ad-hoc.

Pré-condições

• Garanta que a CLI esteja globalmente disponível no PATH:
  • preferido: npm install -g @codecell-germany/gemini-ocr-agent-skill
  • verifique: gemini-ocr --help
• Instale o pacote da skill se necessário:
  • gemini-ocr-skill install --force
• Variável de ambiente secreta necessária:
  • GEMINI_API_KEY=<api-key>
• Variável de ambiente secreta com alias suportada:
  • GOOGLE_GENERATIVE_AI_API_KEY=<api-key>
• Variável de ambiente secreta de fallback suportada:
  • GOOGLE_API_KEY=<api-key>
• Sobrescrita opcional de modelo:
  • GEMINI_OCR_MODEL=gemini-3-flash-preview

Fluxo de trabalho principal

1. Verifique a superfície pública da CLI:

• gemini-ocr --help

2. Valide o ambiente:

• gemini-ocr doctor --json

3. Se o ambiente estiver incompleto, exiba o guia de configuração:

• gemini-ocr setup --language en
• gemini-ocr setup --language de

4. Exporte uma das variáveis de ambiente de chave de API suportadas e execute novamente:

• gemini-ocr doctor --json

5. Converta uma imagem via OCR:

• gemini-ocr scan-image /caminho/absoluto/para/imagem.png

6. Converta um PDF via OCR:

• gemini-ocr scan-pdf /caminho/absoluto/para/documento.pdf

7. Use saída JSON apenas quando o fluxo de trabalho chamador precisar do objeto OCR estruturado:

• gemini-ocr scan-pdf /caminho/absoluto/para/documento.pdf --format json

Diretrizes

• Use os nomes públicos da CLI gemini-ocr e gemini-ocr-skill.
• Não ignore a superfície do produto usando pontos de entrada locais do repositório, como node dist/index.js.
• Não chame caminhos de runtime instalados ocultos como ~/.codex/tools/gemini-ocr-cli/dist/index.js.
• As entradas são enviadas para o Gemini para processamento remoto. Não use a ferramenta em documentos que precisem permanecer totalmente locais, a menos que essa política de processamento remoto seja aceitável.
• A saída padrão é Markdown no stdout.
• Diagnósticos e avisos pertencem ao stderr.
• --format json é a saída legível por máquina.
• --pdf-mode auto pode tentar novamente uma solicitação de PDF nativa falha como OCR rasterizado quando pdftoppm estiver disponível.
• --pdf-mode raster requer pdftoppm.
• As chaves de API permanecem no ambiente do shell. Não as cole em prompts, tickets, capturas de tela ou chats.
• Prefira doctor antes da primeira execução real de OCR em um novo shell ou ambiente.

Referências

• Visão geral principal: references/overview.md
• Integração do agente: references/agent-onboarding.md
• Primeira execução do OCR: references/ocr-first-run.md
• Folha de dicas de comandos: references/command-cheatsheet.md
• Arquitetura: knowledge/ARCHITECTURE.md
• Lista de verificação de lançamento: knowledge/RELEASE_CHECKLIST.md