find-images：尋找、篩選、下載並標註圖片來源
腳本位於此技能目錄下的 scripts/imgs.py。在以下指令中，請將 <skill-dir> 替換為包含此 SKILL.md 的目錄完整路徑（例如 C:/Users/<name>/.claude/skills/find-images）。
金鑰來自環境變數或 ~/.config/image-search/keys.env（SERPER_API_KEY、PIXABAY_API_KEY、可選的 EXA_API_KEY）。腳本會自行讀取這些金鑰：切勿印出金鑰或到其他地方尋找。若缺少某個金鑰，腳本會跳過對應的來源並告知；請繼續使用其他來源，並按照此技能的 README.md 指示告訴使用者如何設定金鑰。
腳本訊息、連絡表標籤及 credits.md 會依系統語言（中文或英文）顯示；FIND_IMAGES_LANG=zh|en 可強制指定語言。
輸出檔案位於目前專案的 images/ 目錄下：_work/<tag>/ 存放候選圖與連絡表，assets/ 存放選定的圖片，manifest.json 記錄每張圖片的來源，credits.md 則是來源頁。
首先判斷該張投影片是否需要尋找圖片
| 內容類型 | 處理方式 |
|---|---|
| 數據、比較、趨勢 | 不要搜尋；直接使用原生 pptx 圖表或 matplotlib |
| 流程、結構、關係 | 不要搜尋；使用形狀或 SVG 繪製 |
| 概念、抽象插圖 | 先嘗試圖示（icons）；在 Codex 中也可使用 imagegen 生成 |
| 特定產品、地點、人物、活動、組織 | 使用此技能尋找真實照片 |
| 氛圍圖片、封面背景 | 使用此技能，指定 Pixabay 或 Commons 為來源 |
選擇來源
來源（src / mode） | 適用於 | 查詢語言 | 授權 |
|---|---|---|---|
web（Serper，即 Google 圖片） | 特定產品、新聞事件、人物、中文主題 | 任意語言。搜尋中文主題時，加入「官方圖」、「高清」或「新聞圖」有助於找到合適圖片 | 權利未知：僅限內部簡報與課程作業使用，且須標明來源 |
commons（Wikimedia Commons） | 地標、城市、建築、歷史、科學、公眾人物、組織標誌 | 僅限英文，2–4 個字（中文查詢幾乎無結果） | CC0 可自由使用；CC BY / BY-SA 需標註原作者 |
pixabay | 氛圍照及通用場景（辦公室、團隊合作、城市、自然、工業） | 中文或英文 | 可自由使用，可選擇是否標註作者；最大 1280px |
mode: site（官方頁面） | 來自產品或公司頁面的官方圖片 | 提供頁面 URL | 官方網站圖片；須標明來源 |
mode: icons（Iconify） | 來自開源圖示集（MIT、Apache 等）的圖示 | 僅限英文，1–2 個字（drone、battery）。若結果少於 6 個，腳本會自動分別搜尋每個單字 | 預設圖示集可自由使用，無需標註作者；color 對 SVG 與 PNG 皆有效 |
若需要特定主題的圖片，請使用 web 或 web,commons。當圖片必須可自由使用時，請使用 commons,pixabay 並排除 web。
工作流程
1. 撰寫圖片計畫（plan.json，UTF-8 編碼）
每張投影片一個項目；以投影片編號與用途命名每個 tag：
[
{"tag": "s01_cover", "q": "car carrier ship at port", "q_en": "car carrier ship",
"src": "commons,pixabay", "orient": "landscape", "min_side": 1600, "n": 12},
{"tag": "s04_product", "q": "比亞迪 海豹07 官方圖", "src": "web", "orient": "landscape", "min_side": 1200, "n": 9},
{"tag": "s05_official", "mode": "site", "url": "https://www.byd.com/cn/", "n": 9},
{"tag": "s07_icon", "mode": "icons", "q": "battery", "color": "#1F4E79", "n": 16}
]
q：主要查詢字串，供web與pixabay使用。可用中文查詢中文主題，如s04_product所示。q_en：供commons使用的英文查詢；預設與q相同。orient：landscape/portrait/square/any。min_side：圖片長邊的最小像素長度。全螢幕背景 1600，半張投影片 1000，小插圖 600。Pixabay 的免費 API 最多提供 1280px，因此腳本會將 Pixabay 的需求降低為 1280px。這對投影機或一般螢幕的全螢幕背景已足夠，在 4K 螢幕上會略顯模糊。若全螢幕圖片必須非常銳利，建議優先使用 Commons 的候選圖。n：連絡表上的候選圖數量，最多 16 個。
2. 搜尋並建立連絡表
python <skill-dir>/scripts/imgs.py search --plan plan.json --out images
也可單一項目搜尋：search --tag s04_product --q "..." --src web，或 site --tag .. --url ..、icons --tag .. --q ..。
若非 ASCII 引數在 Shell 中出現亂碼（例如在 Windows 的 Git Bash 中輸入中文），請改為寫在 plan.json 中。
每個項目會產生一張編號連絡表 images/_work/<tag>/sheet.jpg 以及一個文字清單，每行一個候選圖的資訊（尺寸、來源網域、授權）。
再次搜尋同一個 tag 會覆寫其候選圖與編號，所以在選圖前請先不要對同一個 tag 進行第二次搜尋。
3. 查看連絡表並選擇圖片
- 開啟連絡表圖片：在 Claude Code 中讀取，在 Codex 中使用 view_image。一張連絡表約耗費 1,600 tokens。不要逐一開啟候選圖。
- 確認主題是否正確（型號、地點）、構圖是否留有文字空間、沒有浮水印或大段文字、風格與簡報其他部分一致、解析度足夠。
- 若無合適圖片，則重新搜尋。第一次搜尋後，最多再重新搜尋兩次，每次應從不同角度切入（而非使用同義詞）：更特定或更廣泛的主題、其他來源、或另一種語言。若仍未找到，則改用圖示或純文字版面，或告知使用者。
- 當主題吻合與授權條件衝突時：若需求表示「偏好」可自由使用的圖片，請先搜尋
commons,pixabay；若重新搜尋後仍找不到相關主題的圖片，可使用web圖片並在報告中標示為「權利未知」。若需求表示圖片「必須」可自由使用或將公開發表，絕不要使用web，而應改用其他方案。 - 連絡表標籤顯示尺寸、授權（Commons 會顯示精確授權，如 CC BY-SA 4.0）及來源網域；文字清單則顯示相同資訊。
4. 下載選定的圖片
python <skill-dir>/scripts/imgs.py pick --tag s04_product --ids 6 --out images
腳本會下載原始圖片（Commons 透過其 1920px 標準縮圖；長邊超過 2560px 的圖片會縮小；webp/avif 轉為 jpg/png）並記錄在 manifest.json 中。
若 pick 報告下載品質降級（manifest 中的 "degraded": true，表示熱連結保護擋住了原始圖，僅取得縮圖），請選擇其他候選圖。
5. 插入圖片並建立來源頁
- 插入圖片時，請依據
manifest.json中的file、width與height，裁切成適合版面的大小，切勿拉伸。圖示會同時提供 PNG 與 SVG（svg欄位）。 - 執行
credits --out images以寫入credits.md，並將其來源章節放在最後一張投影片（來源頁）。若該頁有備註區，請將訊息傳遞給使用者。 - 完成整個簡報後，如常進行渲染與螢幕截圖檢查。這是主代理唯一需要查看圖片的時機。
節省上下文：將三張以上圖片交由子代理處理
主代理只需撰寫 plan.json 並讀取 manifest。查看連絡表、選擇與下載圖片的工作交由子代理執行，如此候選圖片便不會進入主代理的上下文。子代理的提示範本如下：
請閱讀 <skill-dir>/SKILL.md 並依照指示為 <project path> 中的簡報尋找圖片。
圖片計畫：<plan.json 路徑>（以下每個項目的標籤、用途與投影片背景）。
<每個項目：投影片內容、圖片位置、橫向或縱向、風格>
對於每個項目，查看連絡表一次並選擇 1 張圖片（至多 1 張備用）；挑選至 <project>/images。若無合適圖片，則以不同關鍵字重新搜尋，最多兩輪。
請回傳每個標籤：所選圖片的 id、檔案路徑、尺寸、授權類別與一句選擇理由；列出無合適圖片的標籤及其原因。請勿回傳圖片本身。
授權規則
- 可自由使用（CC0、Pixabay、開源圖示）：任何用途皆可。標註 CC0 與 Pixabay 圖片來源屬於禮貌性做法，非強制要求。
- 需標註作者（CC BY / BY-SA）：必須在來源頁標註作者與授權條款。經修改的 BY-SA 圖片必須以相同授權條款分享。
- 官方 / 權利未知（
site、web）：僅限內部簡報、課程作業及學術演講使用，並須標明來源。在公開發表或商業使用前，請告知使用者並替換為可自由使用的圖片。 - 人物照片：新聞背景下的公眾人物無妨；請勿將私人個人的照片用作裝飾。
配額與限制
- Serper：註冊後可免費查詢 2,500 次。當
n> 6 時，搜尋 20 筆結果耗費 2 次查詢，10 筆結果耗費 1 次。之後需加值，50,000 次查詢約 50 美元，加值後 6 個月內有效。餘額可在 serper.dev 儀表板查看。 - Pixabay：每分鐘 100 次請求；圖片不得熱連結（腳本會下載圖片）。
- Commons：只能取得標準縮圖寬度（960/1280/1920/3840）；請使用英文搜尋。
- Iconify：免費，無需金鑰。將 SVG 轉為 PNG 需要 Node.js 與 sharp。若缺少此工具，腳本會提示；請改用其他方式，或要求使用者執行
npm install -g sharp。 - Exa：僅在
site模式無法從頁面本身找到圖片時使用；會消耗 Exa 配額。