serper

核心用法

serper 是一个基于 Serper API 的 Google 搜索技能，不仅能返回搜索结果，还会自动抓取并提取网页的完整正文内容（使用 trafilatura 库），而非仅提供摘要片段。

两种搜索模式

• default（默认模式）：全时段搜索，返回 5 条结果，适用于一般性问题、产品研究、技术文档、教程等非时效性内容
• current（新闻模式）：近一周搜索（3 条）+ Google 新闻（3 条），适用于新闻事件、最新动态、突发消息等时效性内容

本地化控制

• 英文查询无需额外参数，默认全球范围
• 非英文查询必须设置 --gl（国家代码）和 --hl（语言代码），如德语查询需加 --gl de --hl de

典型调用

python3 scripts/search.py -q "query" [--mode current] [--gl de --hl de]

显著优点

1. 全文本提取：自动抓取原网页并提取干净正文，省去二次调用网页抓取工具
2. 双模式设计：清晰区分时效性与非时效性需求，避免结果混杂
3. 多语言支持：完善的本地化参数控制，支持全球主要语言
4. 结构化输出：JSON 格式，包含标题、URL、来源类型、完整内容、日期等字段
5. 智能降级：页面提取失败时自动回退到搜索摘要

潜在缺点与局限性

1. 依赖外部 API：需 Serper API 密钥，存在服务可用性和速率限制风险
2. 内容提取限制：trafilatura 对某些网站（如重度 JavaScript 渲染页面）提取效果可能不佳
3. 结果数量固定：default 模式仅 5 条、current 模式仅 6 条，深度研究时可能不足
4. 无高级搜索语法：不支持 site:、filetype: 等 Google 高级搜索运算符
5. 成本因素：Serper API 为付费服务，高频使用产生费用

适合人群

• 需要实时信息的 AI 助手/Agent 开发者
• 进行新闻追踪、竞品调研、产品比价的研究人员
• 需要多语言搜索能力的国际化应用场景
• 构建RAG 系统需要高质量网页文本作为知识源的技术团队

常规风险

| 风险类型 | 说明 |

|---------|------|

| API 密钥泄露 | `.env` 文件需妥善保管，避免硬编码提交到版本控制 |

| 内容版权 | 提取的网页内容受原站版权保护，商用需注意合规 |

| 信息时效 | 即使 current 模式也存在数小时延迟，非实时数据 |

| 恶意网站 | 自动抓取可能访问到含恶意内容的页面，建议在隔离环境运行 |

| 速率限制 | 高频调用可能触发 Serper API 限制，需实现重试机制 |

核心用法

serper 是一款基于 Serper API 的 Google 搜索技能，核心亮点在于不仅返回搜索摘要，更通过 trafilatura 自动抓取并提取目标网页的完整正文内容。它提供两种精准匹配场景的模式：

• `default` 模式：通用搜索，返回 5 个结果，适合 evergreen 内容、技术文档、产品对比、教程指南等非时效性查询
• `current` 模式：时效搜索，返回过去一周的 3 个网页结果 + 3 个 Google News 结果，适合新闻、时事、最新动态等时间敏感型查询

本地化支持是另一关键特性：对于非英语查询或特定国家/地区需求，必须显式设置 --gl（国家代码）和 --hl（语言代码），如德语查询需 --gl de --hl de，确保结果精准。

---

显著优点

1. 深度内容获取：突破传统搜索仅返回摘要的限制，直接提取网页全文，大幅提升回答质量和信息完整性
2. 智能模式切换：内置清晰的查询信号识别表，自动或手动选择 default/current 模式，避免信息过时或冗余
3. 多语言原生支持：完善的本地化参数体系，非英语查询不再是二等公民
4. 输出结构化：纯 JSON 输出，包含标题、URL、来源类型、提取内容、日期（新闻）等完整元数据，便于下游处理
5. 安全合规基础：API 密钥通过 .env 管理，无硬编码敏感信息，符合 GDPR/CCPA 数据最小化原则

---

潜在缺点与局限性

| 维度 | 说明 |

|------|------|

| **来源可信度** | T3 级别（个人开发者/社区项目），无 GitHub 仓库公开关联，长期维护存在不确定性 |

| **网络依赖风险** | 核心功能依赖 Serper API 和任意第三方网站，存在服务中断、访问限制、目标网站反爬等风险 |

| **内容提取边界** | trafilatura 提取失败时仅回退到搜索摘要，动态渲染页面（SPA）可能提取不完整 |

| **依赖管理** | 运行时依赖 trafilatura 但未提供 requirements.txt，首次使用可能报错 |

| **URL 安全风险** | 抓取用户搜索返回的任意 URL，存在潜在 SSRF 风险（虽有 2 秒超时保护，但无域名白名单） |

| **速率与成本** | 高频使用可能触发 Serper API 配额限制，无内置缓存或速率限制机制 |

---

适合人群

• 知识工作者：研究人员、分析师、记者，需要快速获取某主题的全面资料
• 开发者与技术写作者：查找最新技术文档、API 参考、实现方案
• 市场与竞品分析人员：追踪产品动态、价格信息、用户评价
• 多语言用户：需要获取德语、法语等非英语本地化搜索结果
• AI 应用构建者：需要结构化、高质量网页内容作为 RAG 知识源

---

常规风险

1. 数据外泄：搜索关键词和 API 密钥传输至 Serper 第三方服务，敏感查询需谨慎
2. 恶意网站暴露：抓取搜索结果中的任意 URL 可能意外访问钓鱼或恶意站点
3. 供应链风险：trafilatura 运行时安装，若 PyPI 被投毒可能影响安全
4. 内容版权：提取的全文内容需遵守目标网站的版权和使用条款