stock-images

セキュリティルール

• 出力に API キーを絶対に表示しないでください
• API キーを含む完全な curl コマンドを絶対にそのまま出力しないでください
• Pixabay の制限：Pixabay では API キーを URL クエリパラメーターとして指定する必要があり、プロセス一覧（ps aux）に表示されます。この API 固有の制限に注意してください。完全な Pixabay curl コマンドを出力に絶対に表示しないでください。
• 許可されたドメインからのみダウンロードしてください：
  • images.pexels.com
  • images.unsplash.com、plus.unsplash.com
  • pixabay.com、cdn.pixabay.com
• すべての URL で HTTPS を使用してください
• ダウンロード後にファイルサイズを確認し、10MB を超える場合は警告してください
• Unsplash からダウンロードする場合は、Unsplash API の TOS に準拠するため、urls.raw ではなく links.download URL を使用してください（ダウンロード数が加算されます）

非アクティベーション

次の場合は、このスキルを有効にしないでください：

• 画像コンポーネント（<img>、next/image など）について話し合っている
• AI 画像生成がリクエストされている（これは別のスキルです）
• プロジェクト内にすでにある画像を参照している

セットアップの確認

検索する前に、API キーが設定されているか確認してください：

test -f ~/.config/stock-images/keys.json && stat -f "%Lp" ~/.config/stock-images/keys.json 2>/dev/null || stat -c "%a" ~/.config/stock-images/keys.json 2>/dev/null

• ファイルが存在しない場合：ユーザーを対話形式でセットアップに案内してください：
  1. 使用するプロバイダー（Pexels、Unsplash、Pixabay — すべて無料）を尋ねる
  2. 該当する登録リンクを提示する：
     • Pexels：https://www.pexels.com/api/
     • Unsplash：https://unsplash.com/developers
     • Pixabay：https://pixabay.com/api/docs/
  3. ユーザーからキーを受け取ったら、Bash 経由で chmod 600 を指定して設定ファイルを作成する
  4. 保存後、キーを絶対に再表示しない
• 権限が 600 でない場合：ユーザーに警告し、chmod 600 ~/.config/stock-images/keys.json で修正するか尋ねてください。
• ファイルが存在し、権限も正しい場合：キーを表示せずに使用してください。ファイルの内容、キー、キーの値を含むコマンドを表示しないでください。

秘密の値を表示せずに、設定済みのプロバイダーを特定します：

python3 - <<'PY'
import json
from pathlib import Path

config = Path.home() / ".config" / "stock-images" / "keys.json"
data = json.loads(config.read_text())
providers = [
    name for name in ("pexels", "unsplash", "pixabay")
    if data.get(name) and not str(data[name]).startswith("YOUR_")
]
print("\n".join(providers))
PY

JSON を解析して、設定済みのプロバイダー（空でなく、プレースホルダーでもない値が設定されているプロバイダー）を特定してください。少なくとも 1 つのプロバイダーが必要です。

検索の実行

ユーザーのリクエストから、次の情報を抽出します：

• query：検索対象（必須）
• count：画像の枚数（デフォルト：5、最大：20）
• orientation：landscape、portrait、または square — 文脈から判断します（例：「ヒーローバナー」→ landscape、「プロフィール写真」→ portrait）
• provider：特定のプロバイダー、または「all」（デフォルト：設定済みのすべて）

同じ会話内での追加リクエストに備え、解析した検索結果とメタデータを保持してください。後でユーザーが「画像 #3 をダウンロード」と言った場合、その番号を提示済みの検索結果に含まれる正確なプロバイダー、画像 URL、ダウンロード URL、作者、作者のプロフィール、帰属表示データに対応付けてください。

設定済みの各プロバイダーに対して curl コマンドを実行します。複数のプロバイダーが設定されている場合は、並行して実行してください（Bash ツールの呼び出しを分けます）。

Pexels

curl -sS -G --max-time 15 --fail "https://api.pexels.com/v1/search" \
  --data-urlencode "query=SEARCH_QUERY" \
  -d "per_page=COUNT" \
  -d "orientation=ORIENTATION" \
  -H "Authorization: PEXELS_KEY"

レスポンスフィールド：

• photos[].src.original — 元画像の URL
• photos[].src.medium — サムネイル
• photos[].photographer — 作者名
• photos[].photographer_url — 作者のプロフィール
• photos[].width、photos[].height — 寸法

Unsplash

curl -sS -G --max-time 15 --fail "https://api.unsplash.com/search/photos" \
  --data-urlencode "query=SEARCH_QUERY" \
  -d "per_page=COUNT" \
  -d "orientation=ORIENTATION" \
  -H "Authorization: Client-ID UNSPLASH_KEY"

レスポンスフィールド：

• results[].urls.raw — 元画像の URL
• results[].urls.small — サムネイル
• results[].user.name — 作者名
• results[].user.links.html — 作者のプロフィール
• results[].links.download — ダウンロード URL（ダウンロードには urls.raw ではなく、こちらを使用）
• results[].width、results[].height — 寸法

Pixabay

curl -sS -G --max-time 15 --fail "https://pixabay.com/api/" \
  -d "key=PIXABAY_KEY" \
  --data-urlencode "q=SEARCH_QUERY" \
  -d "per_page=COUNT" \
  -d "orientation=ORIENTATION" \
  -d "image_type=photo"

Pixabay 固有の設定：「landscape」→「horizontal」、「portrait」→「vertical」に変換します。per_page の最小値は 3 です。

レスポンスフィールド：

• hits[].largeImageURL — 元画像の URL
• hits[].previewURL — サムネイル
• hits[].user — 作者名
• hits[].user_id — プロフィール URL の作成に使用します：https://pixabay.com/users/USER-USER_ID/
• hits[].imageWidth、hits[].imageHeight — 寸法
• hits[].tags — 説明

エラー処理

• curl がゼロ以外の終了コードを返す／タイムアウトする場合：そのプロバイダーをスキップし、ほかのプロバイダーで処理を続け、ユーザーに知らせます
• HTTP 401：API キーが無効または失効しています。ユーザーに知らせ、セットアップを再実行するよう提案します
• HTTP 429：レート制限です。ユーザーに知らせ、待つか別のプロバイダーを試すよう提案します
• JSON が空／不正な場合：そのプロバイダーをスキップし、ほかのプロバイダーで処理を続けます
• keys.json が不正な場合：設定が破損していることをユーザーに知らせ、再作成するか確認します

結果の提示

ユーザーの言語で結果を提示します。形式：

## Results for "query" (N images)

### Provider Name
1. "Image Title/Description" — by [Author Name](author_profile_url)
   URL: https://...
   Resolution: WxH

提示後、ダウンロードしたい画像があるかユーザーに尋ねます。

ダウンロードの実装

ユーザーがダウンロードする画像を選択した場合：

1. URL を検証する：https:// で始まり、許可されたドメインと一致している必要があります
2. Unsplash の特別なケース：Unsplash API TOS に準拠するため、検索結果の urls.raw ではなく links.download URL を使用します（これにより Unsplash のダウンロードカウンターが作動します）
3. 保存先を決定する：現在のプロジェクトディレクトリ内の ./images/ をデフォルトとします。ディレクトリが存在しない場合は、作成前に確認を求めます
4. ファイル名を生成する：<query-slug>-<provider>.<ext>（例：mountain-landscape-pexels.jpg）。URL から明らかに判別できる場合（.png、.webp）を除き、拡張子はデフォルトで .jpg とします
5. ダウンロードする：

curl -sL --max-time 30 --fail -o "./images/FILENAME" "IMAGE_URL"

6. 検証する：ファイルサイズを確認し、ユーザーに知らせます

ls -lh "./images/FILENAME"

7. クレジット表記のリマインダー：ダウンロード後、ユーザーに次のようにリマインドします：

   クレジット表記が必要です：Photo by [Author](author_url) on [Provider]

ファイルサイズが 10MB を超える場合は警告します。ユーザーは、より小さい解像度を希望する可能性があります。

クレジット表記とライセンスの要件は、プロバイダーやプロジェクトでの用途によって異なります。ユーザーが該当するプロバイダーの規約を遵守できるよう、作者のクレジット情報を必ず保持して提示してください。

動作ガイドライン

• 文脈から向きを推測します：「hero」、「banner」、「header」→横向き、「avatar」、「profile」→縦向き、「thumbnail」、「icon」→正方形
• ユーザーが UI コンポーネントの作業中に画像が必要だと言及した場合は、ストック画像の検索を積極的に提案します
• 作者のクレジットは必ず提示します。Unsplash と Pixabay の TOS で必要です
• ユーザーの言語で応答します
• 結果が見つからない場合は、別の検索語を提案します
• 設定されているプロバイダーが 1 つだけの場合は、プロバイダーの選択を省略して直接使用します