google-image-search

Google 图片搜索 Skill

使用 Google Custom Search API 搜索图片，并通过智能评分和基于 LLM 的筛选选出最佳图片。

适用场景

• 查找图片，为技术文章或研究配图
• 为演示文稿添加视觉素材
• 为 Obsidian 笔记添加相关图片
• 批量搜索多个主题的图片
• 根据纯文本列表生成图片搜索配置

要求

• Google Custom Search API 密钥和 Search Engine ID
• OpenRouter API 密钥（用于 LLM 筛选）
• 已安装 llm CLI，路径为 /opt/homebrew/bin/llm

将凭据存储在 .env 中：

Google-Custom-Search-JSON-API-KEY=your_key
Google-Custom-Search-CX=your_cx
OPENROUTER-API-KEY=your_openrouter_key

（OPENROUTER_API_KEY=... 这种写法也可用——请参阅下方的插件说明。）

OpenRouter / llm-openrouter 注意事项

llm-openrouter 插件只有在能读取名为 OPENROUTER_KEY 的密钥时才会注册其模型（通过环境变量或 llm keys set openrouter 设置）。如果只设置了 OPENROUTER_API_KEY，llm models list 将显示 零个 OpenRouter 模型，所有 openrouter/... 名称都会报错 Unknown model——随后脚本会静默回退到 关键词评分。llm_select.py 会为子进程设置这两个名称，因此已处理此问题； 如果筛选功能再次异常，请先检查 OPENROUTER_KEY：

llm models list | grep -c openrouter   # 458+ means the plugin registered its models

运行模式

1. 简单查询

搜索单个词：

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --query "neural interface wearable device" \
  --output-dir ./images \
  --num-results 5

2. 批量处理

根据 JSON 配置处理多个查询：

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --config image_queries.json \
  --output-dir ./images \
  --llm-select

3. 根据词语生成配置

使用 LLM 根据词语列表创建 JSON 配置：

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --generate-config \
  --terms "AlterEgo wearable" "sEMG electrodes" "BCI headset" \
  --output my_queries.json

4. 丰富 Obsidian 笔记

从笔记中提取视觉主题词，查找图片并插入到相应标题下方：

python3 ~/.claude/skills/google-image-search/scripts/google_image_search.py \
  --enrich-note ~/Brains/brain/Research/neural-interfaces.md

此模式会：

1. 检测 Obsidian 知识库和附件文件夹
2. 使用 LLM 从笔记中提取适合配图的词语
3. 为每个词语搜索图片
4. 将最佳图片下载到附件文件夹
5. 在相关标题下方插入图片嵌入
6. 修改笔记前创建备份

主要选项

选项	说明
--query TEXT	简单的单个查询
--config FILE	批处理用的 JSON 配置
--generate-config	根据 --terms 生成配置
--enrich-note FILE	丰富 Obsidian 笔记
--output-dir DIR	图片保存位置
--urls-only	仅返回 URL，不下载
--llm-select	使用 LLM 选择最佳图片（默认：开启）
--no-llm-select	禁用 LLM 筛选
--num-results N	每个查询的结果数（默认：5）
--dry-run	显示将执行的操作

JSON 配置格式

每个条目支持：

{
  "id": "unique-id",
  "heading": "Display Heading",
  "description": "Context for what image to find",
  "query": "Google search query",
  "numResults": 5,
  "selectionCriteria": "What makes a good image",
  "requiredTerms": ["must", "have"],
  "optionalTerms": ["bonus", "terms"],
  "excludeTerms": ["stock", "clipart"],
  "preferredHosts": ["official-site.com"],
  "selectionCount": 2
}

完整文档请参阅 references/api_config_reference.md。

评分系统

图片根据以下因素评分：

• 必需词语：缺少时 -80，全部包含时 +30
• 可选词语：每匹配一个 +5
• 排除词语：每匹配一个 -50
• 首选主机：可信时 +25，未知时 -5
• MIME 类型：PNG/JPEG +5，GIF -10
• 分辨率：高分辨率 +10，低分辨率 -10
• 文件大小：非常小时 -5

LLM 筛选

评分后，LLM 会根据以下信息从候选图片中选出最佳图片：

• 标题和 URL 元数据
• 评分原因
• 筛选标准

LLM 会评估图片的真实性、清晰度，以及对技术受众的相关性。

Obsidian 集成

在 Obsidian 知识库中时：

• 通过 .obsidian 文件夹自动检测知识库根目录
• 使用配置的附件文件夹（默认：Attachments）
• 生成 Obsidian 风格的嵌入：![[image.png|alt text]]
• 修改笔记前创建备份

脚本文件

文件	用途
google_image_search.py	主入口
api.py	Google Custom Search API
config.py	凭据和配置处理
download.py	使用 magic bytes 下载图片
evaluate.py	基于关键词的评分
llm_select.py	LLM 筛选和词语提取
obsidian.py	知识库检测和内容丰富
output.py	Markdown 输出生成