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

Gemini OCR CLI

Wann verwenden

Verwenden Sie diesen Skill, wenn eine Aufgabe eine hochwertige Texterkennung (OCR) in einem lokalen Terminal-Workflow erfordert und die integrierte OCR des Hostmodells nicht zuverlässig genug ist.

Verwenden Sie ihn insbesondere, wenn ein Agent:

• Ein lokales Bild in originalgetreues Markdown umwandeln muss,
• Ein lokales PDF in originalgetreues Markdown umwandeln muss,
• Seitenstruktur, Tabellen und Beschriftungen so gut wie möglich erhalten muss,
• Über ein deterministisches CLI anstelle von Ad-hoc-Multimodal-Prompts arbeiten soll.

Voraussetzungen

• Stellen Sie sicher, dass das CLI global im PATH verfügbar ist:
  • bevorzugt: npm install -g @codecell-germany/gemini-ocr-agent-skill
  • überprüfen: gemini-ocr --help
• Installieren Sie ggf. das Skill-Paket:
  • gemini-ocr-skill install --force
• Erforderliche geheime Umgebungsvariable:
  • GEMINI_API_KEY=<api-key>
• Unterstützte Alias-geheime Umgebungsvariable:
  • GOOGLE_GENERATIVE_AI_API_KEY=<api-key>
• Unterstützte Fallback-geheime Umgebungsvariable:
  • GOOGLE_API_KEY=<api-key>
• Optionale Modell-Überschreibung:
  • GEMINI_OCR_MODEL=gemini-3-flash-preview

Kern-Workflow

1. Überprüfen Sie die öffentliche CLI-Oberfläche:
   • gemini-ocr --help
2. Validieren Sie die Umgebung:
   • gemini-ocr doctor --json
3. Falls die Umgebung unvollständig ist, drucken Sie die Setup-Anleitung:
   • gemini-ocr setup --language en
   • gemini-ocr setup --language de
4. Exportieren Sie eine der unterstützten API-Key-Umgebungsvariablen und führen Sie erneut aus:
   • gemini-ocr doctor --json
5. OCR eines Bildes:
   • gemini-ocr scan-image /absoluter/pfad/zu/bild.png
6. OCR eines PDFs:
   • gemini-ocr scan-pdf /absoluter/pfad/zu/dokument.pdf
7. Verwenden Sie die JSON-Ausgabe nur, wenn der aufrufende Workflow das strukturierte OCR-Objekt benötigt:
   • gemini-ocr scan-pdf /absoluter/pfad/zu/dokument.pdf --format json

Leitplanken

• Verwenden Sie die öffentlichen CLI-Namen gemini-ocr und gemini-ocr-skill.
• Umgehen Sie die Produktoberfläche nicht mit repo-lokalen Einstiegspunkten wie node dist/index.js.
• Rufen Sie keine versteckten installierten Laufzeitpfade wie ~/.codex/tools/gemini-ocr-cli/dist/index.js auf.
• Eingaben werden an Gemini zur Fernverarbeitung gesendet. Verwenden Sie das Tool nicht für Dokumente, die vollständig lokal bleiben müssen, es sei denn, diese Fernverarbeitungsrichtlinie ist akzeptabel.
• Die Standardausgabe ist Markdown auf stdout.
• Diagnosen und Warnungen gehören auf stderr.
• --format json ist der maschinenlesbare Ausweg.
• --pdf-mode auto kann eine fehlgeschlagene native PDF-Anfrage als Raster-OCR wiederholen, wenn pdftoppm verfügbar ist.
• --pdf-mode raster erfordert pdftoppm.
• API-Schlüssel verbleiben in der Shell-Umgebung. Fügen Sie sie nicht in Prompts, Tickets, Screenshots oder Chats ein.
• Bevorzugen Sie doctor vor dem ersten echten OCR-Durchlauf in einer neuen Shell oder Umgebung.

Referenzen

• Hauptübersicht: references/overview.md
• Agenten-Onboarding: references/agent-onboarding.md
• OCR-Erstdurchlauf: references/ocr-first-run.md
• Befehls-Spickzettel: references/command-cheatsheet.md
• Architektur: knowledge/ARCHITECTURE.md
• Release-Checkliste: knowledge/RELEASE_CHECKLIST.md