google-image-search

用途

Google Image Search 技能用于通过 Google Custom Search API 搜索图片，并借助 LLM 进行智能评分与选择。它适合在以下场景使用：为技术文章或研究寻找配图、为演示文稿添加视觉素材、为 Obsidian 笔记补充相关图片、对多个主题进行批量图片搜索，以及从纯文本列表生成图片搜索配置。

主要能力

使用 Google Custom Search API 搜索图片。
基于关键词的评分系统，对候选图片进行排序。
使用 LLM 从高分候选中挑选最佳图片。
支持单次查询、批量处理、从术语列表生成 JSON 配置。
支持 Obsidian 笔记增强：自动检测 vault、提取视觉关键词、下载图片并插入嵌入。
支持仅返回 URL 而不下载、干运行预览等选项。

使用方式

环境要求

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+ 表示插件已注册其模型

运行模式

简单查询：

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

批量处理（从 JSON 配置）：

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

从术语生成配置：

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

增强 Obsidian 笔记：

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

该模式会：检测 Obsidian vault 和附件文件夹；使用 LLM 从笔记中提取值得配图的术语；为每个术语搜索图片；将最佳图片下载到附件文件夹；在相关标题下方插入图片嵌入；修改笔记前创建备份。

关键选项

--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 vault 中时：通过 .obsidian 文件夹自动检测 vault 根目录；使用配置的附件文件夹（默认：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：Vault 检测和增强
output.py：Markdown 输出生成

限制

需要 Google Custom Search API 密钥和 Search Engine ID，以及 OpenRouter API 密钥。LLM 选择依赖 llm CLI 和 llm-openrouter 插件的正确配置，否则会回退到关键词评分。其他限制暂未提供。