Web Search

web-search — 统一搜索/抓取路由引擎

Phase 2 整合产物 — 合并 web-search-chain（抓取链路）、multi-engine-search（搜索策略）、web-research（深度调查）三份技能。

快速决策树

你要做什么？
  ├─ 搜搜索引擎找 URL          → web_search（web-ddgs）→ 见「搜索指南」
  │   └─ 引擎失败/中文专有词    → cn.bing.com / 编码回退
  ├─ 抓取已知 URL 的内容       → router.fetch(url)     → 见「抓取指南」
  ├─ 做深度调查               → GitHub Issue 深潜     → 见「深度调查」
  ├─ 理解官方文档              → F1/F2/F3 推导         → 见「文档分析」
  └─ 搜本地文件               → file-search skill

核心能力

自动路由引擎（SearchRouter）

~/.hermes/scripts/search_router.py — 自动选最优抓取/搜索路径，逐级降级。

from search_router import SearchRouter
router = SearchRouter()

# 自动抓取（从最轻量工具开始，失败后自动降级）
result = router.fetch("https://example.com")
# → {"success": True, "content": "...", "tool_used": "terminal-curl"}

# 指定优先使用浏览器（强反爬站点）
result = router.fetch("https://nowsecure.nl", prefer_browser=True)
# → {"success": True, "tool_used": "flaresolverr"}

# 查看各层工具健康状态
report = router.report()

降级路径：web-extract（builtin）→ terminal-curl（L1）→ cloudscraper（L13）→ FlareSolverr（L13）→ CloakBrowser（L1~5）

详见：SearchRouter 架构 | 工具能力声明

统一反爬适配器（AntiCrawlAdapter）

~/.hermes/scripts/anticrawl_adapter.py — 自动处理三大陷阱：

工具能力声明

8 个工具注册在 references/tool-capabilities/ 目录下，SearchRouter 自动加载：

搜索指南

搜索引擎选择

web_search 工具不等于 DuckDuckGo：它由 provider 插件（tavily / exa / … / ddgs）提供服务，谁是当前引擎由配置与探测决定 —— 见下节。

web_search / web_extract 的 provider 机制

随包注册 10 个 provider：tavily、firecrawl、exa、parallel、perplexity、keenable、brave-free、searxng、ddgs、xai（各自 plugins/web/*/plugin.yaml）。

选择优先级（agent/web_search_registry.py）：

1. web.search_backend / web.extract_backend / web.backend 显式配置 —— 命中即用；配置项失败不会静默换 provider，但会触发一次性 keyless 救捞（结果带 rescued_from / backend_error 标注，下次调用仍用配置项；web.keyless_rescue: false 关闭）
2. 唯一「已注册且可用」的 provider
3. 传统顺序：firecrawl → parallel → tavily → perplexity → exa → searxng → brave-free → ddgs
4. keyless 匿名免费档轮询：exa / parallel / firecrawl / keenable（关闭：web.keyless_fallback: false）

查证当前实际走谁（唯一可靠方法）：

# tools/web_tools.py 每次调用都会打 INFO 日志
grep 'Web search via' "$HERMES_HOME/logs/agent.log" | tail -5
grep 'Web extract via' "$HERMES_HOME/logs/agent.log" | tail -5

• 验证 pin 是否真生效（受控实验）：改 web.search_backend 后直接看 provider 自己打的 LOG —— Tavily search: … / web_search backend 'exa' failed (…)，能直接分辨路由到了谁（hermes config set 会重写 config.yaml 并丢掉文件尾部注释块，改后记得 diff 备份）
• plugins.enabled 里列了某插件 ≠ 它在生效；provider 的 is_available() 才是开关（如 ddgs 必须先能 import ddgs）
• 搜索与抓取可各钉一个 provider；换源后旧 provider 仍在注册表，可随时回退

中文搜索技巧

• 连字符处理：cn.bing.com 保留 scope-recall 为专有名词，www.bing.com 分词
• 编码回退：Bing 中文页可能返回 GBK → 用 decode_with_fallback()
• HTML 提取：Bing 用 b_algo 类名；Google 用 g 类
• 详见 multi-engine-search skill（旧版，已被替换）的参考文件

B站/内容平台搜索

策略：先 bili-cli（API 直连），失败后浏览器兜底。

• 参考：bili-cli 搜索指南 | 浏览器 B站搜索

GitHub 深度调查

6 步调查法：Issue body → 所有评论 → Timeline → 关联 Issue → 官方文档 → 代码搜索

# API 调用示例
curl -s "https://api.github.com/repos/owner/repo/issues/N"
curl -s "https://api.github.com/repos/owner/repo/issues/N/comments"
curl -s "https://api.github.com/repos/owner/repo/issues/N/timeline"
curl -s "https://api.github.com/search/issues?q=KEYWORD+repo:owner/repo"

注意事项：API 有 rate limit（未认证 60/h），timeline 包含 label/close/reopen 事件。

文档深度分析（F1/F2/F3 推导）

不逐行通读文档，而是：

1. DOM 精确提取 — browser_console JS 查询定位关键内容
2. 跨页交叉引用 — 架构 + 功能 + 参考 + 最佳实践 + 排障
3. F1/F2/F3 推导 — 从不可约减事实逐层推理

详见：文档深度分析

AI 市场研究

提取平台（build.nvidia.com / OpenRouter / HuggingFace）的定价 / 限流 / 试用信息。 详见：AI 市场研究

抓取指南

无反爬/API 站点 → terminal curl

curl -sL "URL" -H "User-Agent: Mozilla/5.0"

Cloudflare 站点 → cloudscraper（推荐）→ FlareSolverr（兜底）

import cloudscraper
scraper = cloudscraper.create_scraper(browser='chrome')
resp = scraper.get('https://target.com', timeout=15)
# 失败后自动 router.fetch() 会降级到 FlareSolverr

强反爬/行为检测 → CloakBrowser（需安装）

pip install cloakbrowser

详见：反爬五层对抗模型

本地文件搜索 → file-search skill

skill_view(name="file-search")

浏览器降级策略

当终端网络被阻断时（curl 超时 / CAPTCHA），使用 browser 工具：

browser_navigate(url="https://www.bing.com/search?q=TOPIC")
browser_snapshot(full=True)
browser_scroll(direction="down")
browser_click(ref="eXX")

触发条件：curl exit code 124/28（timeout），或返回 CAPTCHA 页面。

环境信息

代理配置

HTTP_PROXY=http://127.0.0.1:7890      # Clash Verge 注入
NO_PROXY=localhost,127.0.0.1,::1,...  # 已配置 ✅

• MSYS2 curl：受 NO_PROXY 保护，localhost 请求正常
• Python urllib：不读 shell NO_PROXY，需显式 ProxyHandler({})
• 统一处理：用 anticrawl_adapter.no_proxy_opener()

工具状态表

参考文件索引

迁移记录