web-search

网络搜索

概述

使用 DuckDuckGo 的 API 搜索网络，在网页、新闻文章、图片和视频中查找信息。以多种格式（文本、markdown、JSON）返回结果，并支持按时间范围、地区和安全搜索进行筛选。

何时使用此技能

用户提出以下请求时，可使用此技能：

• 搜索信息或资源
• 查找当前或近期的在线信息
• 查找特定主题的新闻文章
• 根据描述或主题搜索图片
• 查找特定主题的视频
• 需要当前网络数据的研究
• 使用网络来源进行事实核查或验证
• 收集某个主题的网址和资源

前提条件

安装所需的依赖项：

pip install duckduckgo-search

此库提供了一个简单的 Python 接口，用于调用 DuckDuckGo 的搜索 API，无需 API 密钥或身份验证。

核心功能

1. 基本网络搜索

搜索网页和信息：

python scripts/search.py "<query>"

示例：

python scripts/search.py "python asyncio tutorial"

以清晰的文本格式返回排名前 10 的网络搜索结果，包含标题、URL 和描述。

2. 限制结果数量

控制返回的结果数量：

python scripts/search.py "<query>" --max-results <N>

示例：

python scripts/search.py "machine learning frameworks" --max-results 20

适用于：

• 获取更全面的结果（增加数量上限）
• 快速查找少量结果（减少数量上限）
• 平衡详细程度与处理时间

3. 按时间范围筛选

按时效筛选结果：

python scripts/search.py "<query>" --time-range <d|w|m|y>

时间范围选项：

• d - 过去一天
• w - 过去一周
• m - 过去一个月
• y - 过去一年

示例：

python scripts/search.py "artificial intelligence news" --time-range w

适用于：

• 查找近期新闻或更新
• 筛除过时内容
• 跟踪近期进展

4. 新闻搜索

专门搜索新闻文章：

python scripts/search.py "<query>" --type news

示例：

python scripts/search.py "climate change" --type news --time-range w --max-results 15

新闻结果包括：

• 文章标题
• 来源媒体
• 发布日期
• URL
• 文章摘要/描述

5. 图片搜索

搜索图片：

python scripts/search.py "<query>" --type images

示例：

python scripts/search.py "sunset over mountains" --type images --max-results 20

图片筛选选项：

尺寸筛选：

python scripts/search.py "landscape photos" --type images --image-size Large

选项：Small、Medium、Large、Wallpaper

颜色筛选：

python scripts/search.py "abstract art" --type images --image-color Blue

选项：color、Monochrome、Red、Orange、Yellow、Green、Blue、Purple、Pink、Brown、Black、Gray、Teal、White

类型筛选：

python scripts/search.py "icons" --type images --image-type transparent

选项：photo、clipart、gif、transparent、line

布局筛选：

python scripts/search.py "wallpapers" --type images --image-layout Wide

选项：Square、Tall、Wide

图片结果包括：

• 图片标题
• 图片 URL（图片的直接链接）
• 缩略图 URL
• 来源网站
• 尺寸（宽 x 高）

6. 视频搜索

搜索视频：

python scripts/search.py "<query>" --type videos

示例：

python scripts/search.py "python tutorial" --type videos --max-results 15

视频筛选选项：

时长筛选：

python scripts/search.py "cooking recipes" --type videos --video-duration short

选项：short、medium、long

分辨率筛选：

python scripts/search.py "documentary" --type videos --video-resolution high

选项：high、standard

视频结果包括：

• 视频标题
• 发布者/频道
• 时长
• 发布日期
• 视频 URL
• 描述

7. 按地区搜索

搜索特定地区的结果：

python scripts/search.py "<query>" --region <region-code>

常见地区代码：

• us-en - 美国（英语）
• uk-en - 英国（英语）
• ca-en - 加拿大（英语）
• au-en - 澳大利亚（英语）
• de-de - 德国（德语）
• fr-fr - 法国（法语）
• wt-wt - 全球（默认）

示例：

python scripts/search.py "local news" --region us-en --type news

8. 安全搜索控制

控制安全搜索筛选：

python scripts/search.py "<query>" --safe-search <on|moderate|off>

选项：

• on - 严格筛选
• moderate - 平衡筛选（默认）
• off - 不筛选

示例：

python scripts/search.py "medical information" --safe-search on

9. 输出格式

选择结果的格式：

文本格式（默认）：

python scripts/search.py "quantum computing"

清晰易读的纯文本，结果带有编号。

Markdown 格式：

python scripts/search.py "quantum computing" --format markdown

格式化的 Markdown，包含标题、粗体文本和链接。

JSON 格式：

python scripts/search.py "quantum computing" --format json

便于程序处理的结构化 JSON 数据。

10. 将结果保存到文件

将搜索结果保存到文件：

python scripts/search.py "<query>" --output <file-path>

示例：

python scripts/search.py "artificial intelligence" --output ai_results.txt
python scripts/search.py "AI news" --type news --format markdown --output ai_news.md
python scripts/search.py "AI research" --format json --output ai_data.json

文件格式由 --format 标志决定，而不是由文件扩展名决定。

输出格式示例

文本格式

1. Page Title Here
   URL: https://example.com/page
   Brief description of the page content...

2. Another Result
   URL: https://example.com/another
   Another description...

Markdown 格式

## 1. Page Title Here

**URL:** https://example.com/page

Brief description of the page content...

## 2. Another Result

**URL:** https://example.com/another

Another description...

JSON 格式

[
  {
    "title": "Page Title Here",
    "href": "https://example.com/page",
    "body": "Brief description of the page content..."
  },
  {
    "title": "Another Result",
    "href": "https://example.com/another",
    "body": "Another description..."
  }
]

常见用法模式

主题研究

收集有关某个主题的全面信息：

# Get overview from web
python scripts/search.py "machine learning basics" --max-results 15 --output ml_web.txt

# Get recent news
python scripts/search.py "machine learning" --type news --time-range m --output ml_news.txt

# Find tutorial videos
python scripts/search.py "machine learning tutorial" --type videos --max-results 10 --output ml_videos.txt

追踪时事

跟踪特定主题的新闻：

python scripts/search.py "climate summit" --type news --time-range d --format markdown --output daily_climate_news.md

查找视觉资源

按特定条件搜索图片：

python scripts/search.py "data visualization examples" --type images --image-type photo --image-size Large --max-results 25 --output viz_images.txt

事实核查

使用最新来源核实信息：

python scripts/search.py "specific claim to verify" --time-range w --max-results 20

学术研究

查找学术主题相关资源：

python scripts/search.py "quantum entanglement research" --time-range y --max-results 30 --output quantum_research.txt

市场调研

收集有关产品或公司的信息：

python scripts/search.py "electric vehicle market 2025" --max-results 20 --format markdown --output ev_market.md
python scripts/search.py "EV news" --type news --time-range m --output ev_news.txt

实现方法

用户请求网页搜索时：

1. 确定搜索意图：

   • 需要哪种内容（网页、新闻、图片、视频）？
   • 结果需要有多新？
   • 需要多少条结果？
   • 有什么筛选要求？

2. 配置搜索参数：

   • 选择合适的搜索类型（--type）
   • 如果时效性很重要，则设置时间范围（--time-range）
   • 调整结果数量（--max-results）
   • 应用筛选条件（图片尺寸、视频时长等）

3. 选择输出格式：

   • 快速阅读时使用文本
   • 编写文档时使用 Markdown
   • 需要进一步处理时使用 JSON

4. 执行搜索：

   • 运行搜索命令
   • 如果需要保留结果，则保存到文件
   • 如果需要立即查看，则打印到标准输出

5. 处理结果：

   • 如有需要，读取已保存的文件
   • 提取 URL 或特定信息
   • 合并多次搜索的结果

快速参考

命令结构：

python scripts/search.py "<query>" [options]

基本选项：

• -t, --type - 搜索类型（web、news、images、videos）
• -n, --max-results - 最多返回的结果数（默认值：10）
• --time-range - 时间筛选（d、w、m、y）
• -r, --region - 区域代码（例如 us-en、uk-en）
• --safe-search - 安全搜索级别（on、moderate、off）
• -f, --format - 输出格式（text、markdown、json）
• -o, --output - 保存到文件

图片专用选项：

• --image-size - 尺寸筛选（Small、Medium、Large、Wallpaper）
• --image-color - 颜色筛选
• --image-type - 类型筛选（photo、clipart、gif、transparent、line）
• --image-layout - 布局筛选（Square、Tall、Wide）

视频专用选项：

• --video-duration - 时长筛选（short、medium、long）
• --video-resolution - 分辨率筛选（high、standard）

查看完整帮助：

python scripts/search.py --help

最佳实践

1. 明确具体 - 使用清晰、具体的搜索查询以获得更好的结果
2. 使用时间筛选 - 对于最新信息，应用 --time-range
3. 调整结果数量 - 从 10–20 条结果开始，需要时再增加
4. 保存重要搜索结果 - 使用 --output 保留结果
5. 选择合适的类型 - 时事使用新闻搜索，一般信息使用网页搜索
6. 自动化时使用 JSON - JSON 格式最便于通过程序解析
7. 合理使用 - 不要短时间内反复大量调用 API

故障排除

常见问题：

• “缺少必需的依赖项”：运行 pip install duckduckgo-search
• 未找到结果：尝试使用范围更广的搜索词，或移除时间筛选
• 超时错误：搜索服务可能暂时不可用；稍后重试
• 速率限制：发出大量请求时，请间隔一段时间再搜索
• 结果意外：DuckDuckGo 的结果可能与 Google 不同；尝试优化查询

局限性：

• 结果质量取决于 DuckDuckGo 的索引和算法
• 不支持高级搜索运算符（不像 Google 的 site:、filetype: 等）
• 图片和视频搜索的结果可能少于网页搜索
• 无法控制结果排名或相关性评分
• 使用专用搜索引擎进行某些专业搜索可能效果更好

高级用例

组合多种搜索

组合不同的搜索类型，收集全面信息：

# Web overview
python scripts/search.py "topic" --max-results 15 --output topic_web.txt

# Recent news
python scripts/search.py "topic" --type news --time-range w --output topic_news.txt

# Images
python scripts/search.py "topic" --type images --max-results 20 --output topic_images.txt

程序化处理

使用 JSON 输出进行自动化处理：

python scripts/search.py "research topic" --format json --output results.json
# Then process with another script
python analyze_results.py results.json

构建知识库

根据网页搜索结果创建可搜索的文档：

# Search multiple related topics
python scripts/search.py "topic1" --format markdown --output kb/topic1.md
python scripts/search.py "topic2" --format markdown --output kb/topic2.md
python scripts/search.py "topic3" --format markdown --output kb/topic3.md

资源

scripts/search.py

实现 DuckDuckGo 搜索功能的主要搜索工具。主要功能包括：

• 多种搜索类型 - 网页、新闻、图片和视频
• 灵活筛选 - 时间范围、地区、安全搜索和特定类型的筛选条件
• 多种输出格式 - 文本、Markdown 和 JSON
• 文件输出 - 保存结果以供后续处理
• 清晰的格式 - 提供包含所有关键信息、易于阅读的输出
• 错误处理 - 妥善处理网络错误和无结果的情况

该脚本可直接执行，并通过 --help 提供全面的命令行帮助。