Material Collector

素材收集官 (material-collector)

這個 skill 在做什麼

把設計師的創作意圖(「我要 50 張橫幅的極簡北歐室內參考」)翻譯成 gallery-dl 的具體指令,並把抓下來的圖按主題自動歸檔成可用的素材庫或情緒板。

gallery-dl 的真正價值不在「下載」,而在三件事 —— 這個 skill 的核心就是幫使用者把意圖對應到這三組設定:

| 意圖層 | gallery-dl 機制 | 參考檔 | |---|---|---| | 「我要什麼樣的圖」 | --filter Python 表達式(解析度/方向/格式/日期/讚數) | references/filtering.md | | 「圖要怎麼擺」 | -D / --filename / --directory 模板 | references/templates.md | | 「抓完怎麼整理」 | 下載封存去重、classify 分類、情緒板、編目 | references/postprocess.md |

前置檢查(每次任務開始前先做)

1. 確認 gallery-dl 可用(免 Python 的 standalone 執行檔):

本 skill 不使用 pip。改用官方 nightly 打包好的獨立執行檔(gdl-org/builds),它已內含 Python runtime,Windows / Mac 都免裝 Python、不汙染環境。

先檢查是否已可用(使用者可能已自行裝過、在 PATH 上): `` gallery-dl --version `` 若找不到,再檢查本 skill 預設的 standalone 路徑是否存在:

• Windows:F:/materials/bin/gallery-dl.exe
• macOS:~/materials/bin/gallery-dl

若都沒有,直接下載 nightly 執行檔(這是單一自包含檔案、非 pip 套件,Claude 可直接代為下載):

Windows(PowerShell): ``powershell New-Item -ItemType Directory -Force F:/materials/bin | Out-Null curl.exe -L -o F:/materials/bin/gallery-dl.exe https://github.com/gdl-org/builds/releases/latest/download/gallery-dl_windows.exe F:/materials/bin/gallery-dl.exe --version ``

macOS(bash/zsh): ``bash mkdir -p ~/materials/bin curl -L -o ~/materials/bin/gallery-dl https://github.com/gdl-org/builds/releases/latest/download/gallery-dl_macos chmod +x ~/materials/bin/gallery-dl ~/materials/bin/gallery-dl --version ``

• /releases/latest/download/... 是 GitHub 永久連結,永遠指向最新 nightly,不需手動填版號。
• 其他平台資產:32 位元 Windows 用 gallery-dl_windows_x86.exe、Linux 用 gallery-dl_linux。
• macOS 首次執行若被 Gatekeeper 攔(未簽章),請使用者執行 xattr -d com.apple.quarantine ~/materials/bin/gallery-dl 解除隔離。

> 後續所有 gallery-dl ... 指令:若它不在 PATH 上,一律改用上面下載的完整路徑(例 Windows:F:/materials/bin/gallery-dl.exe ...;macOS:~/materials/bin/gallery-dl ...)。或把 bin 目錄加入 PATH 以便直接打 gallery-dl。

有需要轉檔(如 ugoira→gif)時另需 ffmpeg(本機已安裝)。

1. 確認素材根目錄:預設建議 F:/materials/,可向使用者確認。

核心工作流程(SOP)

收到「收集素材」類請求時,依序釐清並組裝指令,不要急著下載:

步驟 1 — 釐清意圖(問清楚再動手)

• 主題是什麼?(例:極簡室內、賽博龐克街景、手沖咖啡情境)→ 決定歸檔資料夾名
• 條件?解析度下限、橫/直幅、格式、數量上限、時間範圍
• 數量?(用 --range 或 -A 控制,避免一次抓爆)

步驟 1.5 — 選對來源(關鍵:能下載 ≠ 找得對)

這步決定成敗。 同一句關鍵字在不同站會得到完全不同性質的內容,選錯來源就算抓到一堆圖也全是雜訊。依用途對應已實測的來源(完整對照與實測品質見 references/sites.md):

| 用途 | 首選 | 補充 | 別用 | |---|---|---|---| | 室內/建築/空間風格 | Pinterest | ArtStation(CG) | Wallhaven、Flickr | | CG/概念/遊戲場景 | ArtStation | Pinterest | Flickr | | 真實攝影主題(自然/街拍/實物) | Flickr | 500px | Pinterest | | 構圖/配色/UI 靈感 | Pinterest | Behance、Dribbble | — |

• 已驗證免登入可抓:Pinterest、Flickr、ArtStation、Wallhaven(僅限 SFW)。
• 被反爬牆擋:Unsplash(Anubis)、Pexels(Cloudflare)→ 改走官方 API,別用 gallery-dl 硬撞。
• 內容安全:Wallhaven 一律加 &purity=100;設計/室內查詢直接避開 Wallhaven。

步驟 2 — 先模擬,不要直接下載

務必先用 --simulate 或 -g 確認抓到的東西對不對、量有多大:

gallery-dl --simulate --range "1-5" ""

若不確定可篩哪些欄位,先用 -K 列出該來源的 metadata 欄位:

gallery-dl -K ""

(-K 是設計過濾條件的關鍵 —— 不同平台欄位不同,先看再篩。見 references/filtering.md)

步驟 3 — 組裝正式指令(按主題歸檔的標準型)

本 skill 預設「按主題/標籤歸檔」,跨平台同主題壓進同一資料夾,標準指令型:

gallery-dl ^
  -D "F:/materials/" ^
  --filename "{category}_{id}.{extension}" ^
  --download-archive "F:/materials//.archive.sqlite3" ^
  --filter "width>=1920 and width>height" ^
  --range "1-60" ^
  --sleep-request 1.5 ^
  ""

• -D 把所有圖平鋪進主題資料夾(不分平台子目錄)→ 適合做情緒板
• --filename "{category}_..." 保留來源平台前綴,仍可追溯出處
• --download-archive 同主題共用封存檔 → 重跑不會重抓
• --sleep-request 禮貌限速,避免被站台封鎖(見 references/etiquette.md)

> 若使用者改要「按平台/搜尋詞」分層歸檔,改用 -d + --directory 模板,見 references/templates.md。

步驟 4 — 品質把關(交付前必做)

抓完先抽看再交付,不要把整包未檢查的圖丟給使用者:

• 用縮圖牆目視檢查:python assets/scripts/make_contactsheet.py "F:/materials/"
• 確認與主題相符、無不當/低品質內容(Pinterest 的文字拼圖、Wallhaven 的 NSFW、Flickr 的偏題雜訊都在此剔除)。
• 偏題率高就回步驟 1.5 換來源,別硬抓。

步驟 5 —(備選)交付情緒板 moodboard

搜尋只是過程,設計師要的是成果。除了素材資料夾,可主動多給一張情緒板:

• 情緒板/縮圖牆:python assets/scripts/make_contactsheet.py "F:/materials/" --cols 4 --thumb 360 --output "_moodboard.png"
• 可瀏覽索引:python assets/scripts/build_catalog.py "F:/materials/" → 產出 catalog.html
• 情緒板用品質把關後的精選圖最好看;需要時把選中的圖另存一個 _curated/ 子夾再拼。
• 需 Pillow(make_contactsheet.py);去重已由 --download-archive 處理,進階分類見 references/postprocess.md。

參考檔索引(progressive disclosure)

按需讀取,不要一次全載:

• references/sites.md — (必讀) 用途→來源對照、各站實測品質、反爬牆狀態、內容安全
• references/filtering.md — --filter 表達式庫、用 -K 探索可篩欄位、常見條件對照表
• references/templates.md — 目錄/檔名模板、四種歸檔方案(主題/平台/專案/用途)
• references/config.md — config.json 設定檔說明,搭配 assets/config.template.json
• references/postprocess.md — 封存去重、classify、metadata sidecar、情緒板、編目
• references/auth.md — Pinterest / Tumblr / Flickr 等需登入站台的 cookies / API 設定
• references/etiquette.md — 限速、重試、避免封鎖與基本禮貌

重要原則

• 先模擬再下載:任何正式抓取前一定先 --simulate 看量。
• 數量要設上限:用 --range / -A,別讓搜尋頁無限翻頁。
• 禮貌限速:加 --sleep-request,尊重來源站台。
• 選對來源勝過抓得多:能下載 ≠ 找得對。依用途選已實測的來源(步驟 1.5 / sites.md),偏題就換站。
• 交付前先把關:抓完用情緒板目視抽查,剔除文字拼圖、NSFW、偏題雜訊,確認與主題相符再交付。
• 內容安全:Wallhaven 強制 &purity=100;設計類查詢避開 Wallhaven。
• gallery-dl 用 standalone 執行檔,不用 pip:從 gdl-org/builds 下載 nightly 自包含執行檔(免 Python),Claude 可直接代為下載(見前置檢查)。
• 不替使用者裝 pip 套件:後處理腳本若需 Pillow,仍由使用者自行 python -m pip install --user Pillow,Claude 不直接裝。
• 產生 .bat 時全英文:若做批次啟動檔,內容務必全英文(CP950 編碼問題)。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dseditor
• Source: dseditor/material-collector
• License: MIT

Install and usage instructions live in the source repository linked above.