Google Search

核心功能与用法

google-search 是一款基于 Google 双引擎架构的搜索技能，整合了 Gemini 2.5 Flash 的 Search Grounding 能力与 Custom Search JSON API 作为降级方案。提供三种互斥的工作模式：

• search（默认推荐）：通过 Gemini 生成带编号的合成化答案，自动引用来源，适合问答、时事查询及需要直接结论的场景。支持 JSON 输出以获取置信度分数与结构化数据。
• raw：返回原始链接、标题与摘要，适用于研究、参考文献列表构建等需要精确 URL 的场景。
• image：调用图片搜索接口，返回图像 URL 与元数据。

配置通过环境变量管理，支持多语言（默认希伯来语 he）与区域定向（默认以色列 IL），命令行参数可覆盖全局设置。

显著优点

1. 双重引擎可靠性：主用 Gemini Grounding 提供语义理解，API 耗尽时自动降级至传统搜索，避免单点故障。
2. 希伯来语深度优化：默认语言设为希伯来语，文档与示例均体现对 RTL 语言的完整支持，填补多数搜索工具的多语言盲区。
3. 引用溯源机制：合成答案附带编号来源列表，降低幻觉风险，提升信息可信度。
4. 弹性配额管理：免费 tier generous，对轻中度使用友好；内置 429 自动重试与超时保护（30s）。

局限性与风险

• 配额天花板：Custom Search JSON API 免费版仅 100 次/日，高频场景需付费升级；Gemini API 虽免费 tier 宽松，但 RPM 限制（~15）仍可能制约并发。
• API 密钥依赖：需手动配置 GOOGLE_API_KEY 与可选的 GOOGLE_CSE_CX，首次部署门槛高于纯内置工具。
• 区域合规：默认定向以色列区域，跨国用户需显式覆盖 --country 参数，否则可能获取地理偏差结果。
• 降级透明度：Quota 耗尽时 fallback 至 Perplexity 内置搜索，但此行为文档未明确用户是否感知，可能导致结果质量波动。

适合人群

• 希伯来语用户或需处理 RTL 语言的研究者
• 需要带引用答案而非纯链接列表的知识工作者
• 对 Google 生态有既有 API 配额、希望整合 Gemini 智能总结能力的开发者

安全评估

技能执行外部 HTTP 请求至 Google API，存在常规的网络层风险。代码以 Python 脚本形式通过 exec 工具调用，需确保 skills/google-search/lib/google_search.py 文件完整性。未观察到本地文件系统越界访问或敏感数据持久化行为。建议生产环境监控 API 密钥的权限范围（限制至 Search/Generative Language API 最小权限）。

核心用法

本技能提供三种搜索模式，通过 Python 脚本 google_search.py 调用，需配置 GOOGLE_API_KEY 环境变量。

1. Search 模式（默认推荐）：调用 Gemini 2.5 Flash 进行 Grounding 搜索，返回带编号引用的合成答案，适合问答、时事查询、希伯来语内容等场景。输出包含整理后的答案文本及来源链接列表。

2. Raw 模式：使用 Custom Search JSON API 返回原始搜索结果（标题、链接、摘要），支持指定结果数量（-n），适合需要直接获取 URL 列表的研究场景。

3. Image 模式：通过 Custom Search API 进行图片搜索，返回图片 URL 及标题，适用于查找视觉素材。

通用配置支持多语言（--lang，默认希伯来语 he）和多国家（--country，默认以色列 IL），并提供 JSON 结构化输出选项（--json）便于程序化处理。

显著优点

• 双引擎可靠性：优先使用 Gemini Grounding 生成高质量答案，失败时自动降级至 Custom Search API，确保服务连续性
• 权威引用机制：合成答案附带编号引用，直接溯源至原始网页，提升信息可信度
• 原生希伯来语优化：默认语言设为希伯来语，对 RTL 语言支持良好，填补了多数搜索工具对非英语语言支持不足的空白
• 灵活输出格式：文本模式便于阅读，JSON 模式便于集成，满足人机两种使用场景
• 透明配额管理：清晰标注免费额度（Gemini API generous free tier，Custom Search 100 次/天）及付费上限，便于成本控制
• 健壮的错误处理：内置 429 限流自动重试、30 秒超时保护、清晰错误提示，提升用户体验

潜在缺点与局限性

• API 密钥依赖：必须拥有 Google Cloud 账号并启用相应 API，对普通用户存在配置门槛
• Custom Search 需额外配置：Raw 和 Image 模式需要 GOOGLE_CSE_CX（自定义搜索引擎 ID），设置流程较复杂
• 免费配额有限：Custom Search JSON API 仅 100 次/天免费额度，高频使用需付费
• 网络访问必需：完全依赖 Google 服务，网络不稳定或受限地区无法使用
• 语言默认偏向：默认希伯来语/以色列地区，其他语言用户需显式配置，存在使用摩擦
• 无本地缓存：每次搜索均实时请求 API，无法离线使用，重复查询消耗配额

适合的目标群体

• 研究人员与学者：需要带引用的权威信息，进行文献溯源和事实核查
• 希伯来语用户：母语为希伯来语的用户，可获得优于通用搜索工具的体验
• 内容创作者：需要快速获取时事资料、图片素材，并确保信息可引用
• 开发者与数据分析师：需要结构化搜索数据（JSON 输出）进行下游处理
• 新闻工作者：追踪实时事件，获取多源信息并进行交叉验证

使用风险

性能风险：依赖外部 API 响应速度，Gemini API 高峰期可能出现延迟；30 秒超时设置可能在弱网环境下导致请求失败。

配额与成本风险：超出免费额度后 Custom Search API 需按查询付费，高频自动化调用可能产生意外费用；建议监控用量并设置预算警报。

数据隐私风险：搜索查询、IP 地址、语言/地区偏好等数据将发送至 Google 服务器并受其隐私政策约束，敏感信息搜索存在数据泄露风险。

API 密钥安全风险：GOOGLE_API_KEY 需妥善保管，硬编码或日志泄露可能导致密钥被盗用；建议启用 Google Cloud 的密钥使用限制（IP 白名单）。

服务依赖风险：Google API 服务条款变更、服务下线或地区封锁可能导致技能失效；缺乏内置备用搜索引擎（除 Perplexity 回退外）。

合规风险：需确保遵守 Google API 使用条款，禁止自动化抓取、高频请求等滥用行为，否则可能导致 API 权限被撤销。