Image Describer

GEMINI_API_KEY=your_api_key node .agents/skills/image-describer/scripts/describe.js "data:image/png;base64,iVBOR..."

Dry Run

設定 IMAGE_DESCRIBER_DRY_RUN=1 可在不呼叫 Gemini API 的情況下，預覽解析後的輸入 metadata：

IMAGE_DESCRIBER_DRY_RUN=1 node .agents/skills/image-describer/scripts/describe.js "https://example.com/photo.jpg"

輸出格式

輸出為繁體中文 Markdown，包含以下區段：

• 圖片描述 — 整體場景與內容描述
• 文字辨識（OCR） — 圖片中可辨識的文字
• 關鍵物件 — 畫面中的關鍵物件列表

Instructions for the Agent

⚠️ skill 腳本位於 repo 根目錄。若 cwd 不在 repo root，先獨立執行 git rev-parse --show-toplevel 取得路徑，再 cd 到該路徑後執行。禁止使用 $(...) 語法。

1. 向使用者取得圖片 URL 或本地檔案路徑（若尚未提供）。
2. 確認環境中已設定 GEMINI_API_KEY。
3. 執行描述腳本：

   node .agents/skills/image-describer/scripts/describe.js "<image-path-or-url>"
   

4. 若輸入為本地檔案路徑或 file:// URL，腳本會自動轉換為 Base64 data URI。
5. 將產生的描述結果呈現給使用者。
6. 若腳本以非零代碼結束，回報錯誤訊息給使用者。

限制

• 支援的圖片格式：JPEG、PNG、GIF、WebP、BMP、SVG
• 本地大型圖片檔案會轉為 Base64，可能消耗較多記憶體
• 遠端 URL 必須可被 Gemini API 直接存取
• OCR 準確度取決於圖片品質與文字清晰度

錯誤處理

• 若 GEMINI_API_KEY 未設定，腳本會以代碼 1 結束並印出錯誤訊息。
• 若圖片輸入缺失或無效，腳本會以代碼 1 結束並印出用法說明。
• 若本地檔案無法讀取，腳本會以代碼 1 結束並回報路徑相關錯誤。
• API 錯誤會輸出到 stderr，程序以代碼 1 結束。

實作備註

• scripts/describe.js 是預建置的零依賴 bundle（由 Bun 從 src/describe.js 建置）。
• 模型：gemini-3-flash-preview（快速、平衡，適合圖片理解）。
• 遠端 URL 直接作為 image part 的 uri 傳入。
• 本地檔案轉換為 Base64 data:<mime>;base64,... URI 後傳送。
• 設定 IMAGE_DESCRIBER_DRY_RUN=1 可預覽解析後的輸入 metadata，不呼叫 Gemini API。
• 輸出以串流方式寫入 stdout，即時顯示。
• 需要 Node.js >= 20.0.0。

從原始碼重新建置

若需修改腳本，編輯 src/describe.js 後重新建置：

cd .agents/skills/image-describer
bun install
bun build src/describe.js --outfile scripts/describe.js --target node --minify