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 图片时，请使用 links.download URL（而不是 urls.raw），以遵守 Unsplash API TOS（会触发下载计数）

不要激活

在以下情况下，不要激活此技能：

• 讨论图片组件（<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，确定配置了哪些提供商（值非空且非占位符）。至少需要一个提供商。

搜索实现

从用户请求中提取：

• query：搜索内容（必填）
• count：图片数量（默认值：5，最大值：20）
• orientation：横向、纵向或正方形——根据上下文判断（例如，“hero banner” → 横向，“profile photo” → 纵向）
• 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（下载时使用此 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 特殊情况：使用搜索结果中的 links.download URL，而不是 urls.raw，以遵守 Unsplash API TOS（这会触发其下载计数器）
3. 确定目标位置：默认为当前项目目录下的 ./images/。如果目录不存在，创建前先征求用户确认。
4. 生成文件名：<query-slug>-<provider>.<ext>（例如，mountain-landscape-pexels.jpg）。默认扩展名为 .jpg，除非 URL 明确表明应使用其他扩展名（.png、.webp）。
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 要求署名
• 使用用户的语言回复
• 如果没有找到结果，建议尝试其他搜索词
• 如果只配置了一个提供商，则跳过提供商选择，直接使用该提供商