web-search

网页搜索

跨一个或多个提供方运行搜索，获取可通过 rg、jq 或其他工具处理的 JSON 文件。只要答案依赖可能不在训练数据中的当前信息，就使用此工具，例如近期发布内容、今日新闻、某供应商本周的 API、某个库的实际使用示例、安全公告等。

决策：我该使用此技能吗？

问题特征	使用网页搜索？	原因
“当前的 X 是什么？” / “最新的 Y 是什么？”	是	有时效性
“查找人们使用库 Z 的示例”	是	真实代码语料
“供应商本月发布了关于 A 的什么消息？”	是	供应商近期公告
“查阅命令行标志 B 的文档”	是	权威参考资料
“X 的语法是什么？”（常见语言特性）	否	使用训练知识
“解释概念 C 和 D 的区别”	可能	先使用训练知识；如果用户需要引用来源，再搜索确认
“在此代码库中查找实现 X 的文件”	否	使用 grep / 浏览代码；无需网页搜索

如果决定搜索，请选择下方合适的调用方式。

如何调用

有三种方式，按复杂程度排序：

方式 1：单一提供方（最常见）

python3 scripts/web-search "<your query>"

使用已配置的默认提供方（如果没有设置 API 密钥，则使用 DuckDuckGo）。读取 stdout，其中包含便于人阅读的预览，以及标明结果文件的机器可读页脚：

=== duckduckgo (10 results, 393ms) ===
  [1] Python (programming language)
      https://en.wikipedia.org/wiki/Python_(programming_language)
      Python is a high-level, general-purpose programming language...
  [2] ...

--- WEBSEARCH ---
RESULT_FILE: /tmp/web-search/20260501T073731Z/combined.json
RUN_DIR:     /tmp/web-search/20260501T073731Z
PROVIDERS:   duckduckgo
TOTAL_RESULTS: 10

方式 2：指定提供方

python3 scripts/web-search --provider tavily "<query>"
python3 scripts/web-search --provider perplexity "<query>" --max-results 5
python3 scripts/web-search --provider anthropic "<query>"

需要特定功能时，使用指定提供方——例如，Perplexity 可按时间筛选查询，Tavily 可提供简洁的大模型摘要，Anthropic/OpenAI/xAI 可进行模型辅助综合。

方式 3：并行使用多个提供方

# Subset of providers in parallel:
python3 scripts/web-search --providers tavily,brave,perplexity "<query>"

# Every configured provider in parallel:
python3 scripts/web-search --all "<query>"

以下情况使用多提供方：

• 主题较新，需要通过不同索引交叉验证
• 单个提供方首次返回的结果较少或不相关
• 用户要求“深入研究”或“来自多个来源”

此技能会分别保存每个提供方的输出，因此即使部分请求失败，仍能获得有用数据。

方式 4：顺序备用链（由配置驱动）

在配置中添加 fallback 字段，技能便会按顺序运行各提供方，并在首个返回结果的提供方处停止：

{
  "default": "brave",
  "fallback": ["openai", "duckduckgo", "mwmbl"]
}

现在，python3 scripts/web-search "<query>"（不带 --provider 标志）会先尝试 brave；如果报错或返回 0 条结果，则继续尝试 openai；缺少凭据时会静默跳过该提供方，因此链条会继续到 duckduckgo 等。页脚会报告 MODE: fallback 和 FALLBACK_TRIED: <providers that failed>。

以下情况使用备用链：

• 需要避免付费提供方受到速率限制或发生服务中断的影响
• 希望在付费主提供方之外保留免费的安全网
• 希望面向未来做好准备——现在将 openai 列入链中，添加 apiKey 后即可启用

--provider、--providers 和 --all 都会覆盖备用链；如果某次调用需要特定行为，请使用这些选项。

阅读结果

每次运行都会将结果写入 <TMP_ROOT>/<run-id>/。路径会以 RESULT_FILE: 的形式出现在 stdout 中。默认的 <TMP_ROOT> 在 macOS/Linux 上是 /tmp/web-search，在 Windows 上是 <system-temp>/web-search。

以下三个标志对下游自动化很有用：

标志	作用
--print-path-only	仅打印 combined.json 的绝对路径。可在 $(...) 中使用。
--json	将完整的清单 JSON 打印到 stdout。可直接通过管道传给 jq。
--no-preview	跳过人类可读的预览，仅保留机器可读页脚。

管道（此技能的核心用途）

将 JSON 写入磁盘的核心目的，是让你无需重新运行搜索，就能筛选、转换和合并结果。示例：

# Get every URL across all providers:
RESULT=$(python3 scripts/web-search --all --print-path-only "...")
jq -r '.manifests[].results[].url' "$RESULT"

# Filter results to lines mentioning "release":
rg -i "release" "$RESULT"

# Stream straight from --json without disk:
python3 scripts/web-search --json "..." | jq '.manifests[].results[0]'

# Top result per provider:
jq -r '.manifests[] | "\(.provider): \(.results[0].title) - \(.results[0].url)"' "$RESULT"

# Dedupe across providers, sorted by score:
jq '[.manifests[].results[]] | unique_by(.url) | sort_by(-(.score // 0)) | .[:10]' "$RESULT"

更多示例见 references/pipelines.md。

当封装程序不可用时

如果主机有 curl，但没有 Python（某些 Windows 计算机、精简容器、受限 CI 环境），请直接调用各个提供方。每个提供方的准确请求格式都记录在 references/curl-recipes.md 中。输出架构与该技能内部生成的内容一致——字段和名称相同。

配置

该技能无需任何配置即可使用——DuckDuckGo 和 MWMBL 接受匿名调用。配置凭据可增加可用提供方。将配置文件放在以下任一位置：

OS	路径
macOS / Linux	~/.config/web-search/config.json
Windows	%APPDATA%\web-search\config.json
任意（项目本地）	./web-search.json
任意（环境变量）	$WEBSEARCH_CONFIG 指向一个文件

或者设置相应的环境变量（TAVILY_API_KEY、BRAVE_API_KEY 等），该技能会自动读取。各提供方获取密钥的步骤请参见 references/setup.md。

验证配置：

python3 scripts/web-search --check
python3 scripts/web-search --list-providers

baseUrl 覆盖（适用于所有提供方）

所有提供方都支持 baseUrl 字段，用于完全替换默认端点：

{
  "providers": {
    "tavily":    {"apiKey": "tvly-...", "baseUrl": "https://eu.api.tavily.com/search"},
    "anthropic": {"apiKey": "sk-ant-...", "baseUrl": "https://anthropic-gw.internal.example.com/v1/messages"},
    "openai":    {"apiKey": "sk-...", "baseUrl": "http://localhost:8787/openai/v1/responses"}
  }
}

可将其用于可自托管的代理、区域镜像、企业网关或本地模拟服务。此覆盖会完全替换默认端点——该技能不会将其与默认端点拼接。具体示例请参见 references/base-urls.md。

跨平台行为

相同的命令可在 macOS、Linux、WSL、Git Bash、Windows 原生环境和容器中运行。Python 脚本仅使用标准库和 pathlib.Path 处理路径——没有特定 shell 的语法，也不会遇到 / 与 \ 的问题。

Windows 注意事项：

# PowerShell:
$env:TAVILY_API_KEY = "tvly-..."
python scripts\web-search "your query"

# cmd.exe:
set TAVILY_API_KEY=tvly-...
python scripts\web-search "your query"

在 Windows 上会忽略 shebang #!/usr/bin/env python3——请显式调用 python（或 py）。完整指南请参见 references/platform-notes.md。

提供方选择指南

提供方	身份验证	最适用于
duckduckgo	无	快速查询事实；“X 是什么”
mwmbl	无	获取实际网页链接的免费备用选项
exa	必需	语义搜索；技术类查询
tavily	必需	适合大模型的简洁摘要
brave	必需	独立索引；注重隐私的场景
serper	必需	Google 自然搜索结果，价格低廉
google-cse	必需 + CSE id	使用自定义引擎的官方 Google 搜索
z-ai	必需	中文查询
perplexity	必需	按时效筛选；仅搜索或附带答案
xai	必需	Grok web_search + x_search（X/Twitter 帖子）
openai	必需	由 GPT 综合的网页搜索
anthropic	必需	由 Claude 综合的网页搜索

完整目录（含 API 格式、服务端上限和特殊说明）：references/providers/index.md。每个提供方都有专属页面（例如 providers/tavily.md、providers/anthropic.md）。

域名筛选

将结果限制为特定域名，或排除特定域名：

python3 scripts/web-search "..." --include docs.python.org,python.org
python3 scripts/web-search "..." --exclude reddit.com,medium.com

--include 和 --exclude 都接受逗号分隔的列表。某些提供方（z-ai、xAI）的限制更严格——请参见 references/providers/ 下对应的提供方页面。调用时，允许列表和屏蔽列表不能同时使用。

成本提示

级别	提供方
免费，无需密钥	duckduckgo、mwmbl
使用密钥免费（小额免费额度）	tavily、serper、google-cse、perplexity（小额）
按次付费	brave、z-ai、perplexity（按量）、xai、openai、anthropic

由模型处理的提供方（xai、openai、anthropic）会按调用次数和 Token 数量收费。在配置中设置 maxUses（Anthropic）或 max_tool_calls（OpenAI），以限制失控的 Agent 循环。进行大范围搜索时，优先使用成本较低的非模型提供方，并将大模型辅助搜索留作综合分析之用。

故障模式

症状	原因	解决方法
config error: No default provider configured	未设置密钥，且未设置默认提供方	运行 --check；至少配置一个提供方，或使用 --provider duckduckgo
[provider] HTTP 401	API 密钥无效或已过期	轮换密钥；使用 --check 验证
[provider] HTTP 429	达到速率限制	降低 --parallelism，在运行之间添加延迟，或切换提供方
Failed to parse response: ...	上游更改了架构，或 baseUrl 指向了错误路径	检查运行目录中的 <provider>-raw.json
预览为空，结果数为 0	查询范围过窄，或提供方没有相关索引	尝试使用 --all 或其他提供方

上游原始响应始终保存在 <run-dir>/<provider>-raw.json，因此无需重新查询即可检查故障。

参考索引

文件	内容
references/providers/index.md + 各提供方页面	12 个提供方各有一个独立页面，介绍端点、身份验证、请求/响应结构、设置、curl 示例、特性和 baseUrl 模式。索引包含比较表和选择指南。
references/setup.md	获取各提供方 API 密钥的分步说明
references/pipelines.md	用于筛选和合并结果的 rg / jq / awk 示例
references/curl-recipes.md	各提供方的直接 curl 调用——无需 Python 的备用方案
references/multi-provider.md	并行扇出策略、共识排名、故障隔离
references/result-schema.md	标准 JSON 输出架构；各提供方的字段映射
references/platform-notes.md	macOS / Linux / Windows / WSL / 容器注意事项
references/base-urls.md	用于代理、网关、模拟和镜像的 baseUrl 覆盖模式

快速参考

python3 scripts/web-search [OPTIONS] "<query>"

  --provider NAME         Single provider (overrides default)
  --providers a,b,c       Comma-separated subset, run in parallel
  --all                   Run every configured provider in parallel
  --max-results N         Cap per provider (default 10)
  --include DOMAIN[,...]  Allow-list domains
  --exclude DOMAIN[,...]  Block-list domains
  --config PATH           Override config file
  --tmp-dir PATH          Override output directory
  --json                  Print full manifest to stdout
  --print-path-only       Print only the result file path
  --raw                   Print raw upstream JSON
  --list-providers        Show configured providers and exit
  --check                 Validate config, exit 0 if any provider works

如有疑问：

python3 scripts/web-search --provider duckduckgo "<query>"   # always works, no key needed