> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web 搜索与抓取

> 内置 web_search 与 web_fetch — 多引擎搜索、3 级抓取、进 Agent 上下文前过滤垃圾内容。

# Web 搜索与抓取

Myrm 内置 **web\_search** 与 **web\_fetch**，协同工作：搜索找来源，抓取读页面 — 均在进入 LLM **之前**过滤内容。

## 为何重要

多数 Agent 把原始搜索片段或整页 HTML 塞进模型，浪费 Token 且降低质量。Myrm 本地过滤流水线：

```
查询 → 多引擎搜索 → BM25/Reranker → 相关片段
URL  → 3 级抓取 → DOM 剪枝 →（可选）BM25+向量+Reranker → 干净文本
```

**结果：** Web 密集任务约少 40–50% Token，本地运行 **\$0/月**。

:::note 客观对比
Hermes、OpenClaw、OpenCode、Claude Code 都有基础 web 搜索/抓取。Myrm 优势是**完整本地过滤流水线** — 不仅是「有工具」，而是在进 LLM 前清洗内容。
:::

## Web 搜索

### 引擎

支持 **7 个提供商**（在 **设置 → 搜索** 配置）：

| 提供商          | 适合              |
| ------------ | --------------- |
| SearxNG（自托管） | 隐私，聚合 70+ 引擎含百度 |
| Tavily       | 通用研究            |
| Exa          | 语义/神经搜索         |
| Perplexity   | 问答风格            |
| Google PSE   | 站内搜索            |
| DataForSEO   | SEO/数据任务        |
| Firecrawl    | 搜索即服务回退         |

### X (Twitter) 实时搜索

Myrm 提供专属 **X/Twitter 实时搜索**，基于 xAI Responses API —— 检索帖子、话题和热门讨论，附带内联引用。

**两种认证方式：**

| 方式              | 设置                           | 适合                                 |
| --------------- | ---------------------------- | ---------------------------------- |
| API Key         | 在 设置 → 模型与提供商 粘贴 xAI API Key | 持有 xAI 付费 API 的开发者                 |
| SuperGrok OAuth | 在 设置 → 集成 一键设备码登录            | SuperGrok / X Premium+ 订阅用户（无额外费用） |

**能力：** 日期范围过滤、用户句柄包含/排除（最多 10 个）、匹配帖中图片/视频理解、内联引用含源 URL、降级结果检测（过滤无源数据时发出警告）。

OAuth token 以 AES-256-GCM 加密存储，过期前自动刷新，在 5 项 xAI 服务（X 搜索、图片生成、视频生成、TTS、STT）间复用 —— 一次登录解锁完整 xAI 多模态能力。

### 意图检测（零 LLM 成本）

自动识别 **7 种意图**并调整引擎参数：

* Code、News、Academic、Finance、Security、Social、General

说 *「最新 AI 安全 CVE」* — 无需选手动模式。

### 5 层智能路由

不同于竞品的单一检索路径，Myrm 采用 5 层路由智能 —— 全程无需额外 Planner LLM 调用：

| 层级 | 机制       | 收益                 |
| -- | -------- | ------------------ |
| 1  | LLM 自然选择 | Agent 每步自主决定调用哪些工具 |
| 2  | 工具描述引导   | 每个工具注明何时应被调用       |
| 3  | 意图优化器    | 零成本关键词路由至搜索引擎类别    |
| 4  | 能力发现     | 10+ 工具时语义搜索延迟加载工具  |
| 5  | RSG 后验评估 | 评估检索质量并指导补搜方向      |

### web\_fetch vs browser（智能分工）

同时开启 **web\_fetch** 与 **browser** 时，Myrm 通过工具层引导 Agent 选型，**不耦合 System Prompt**：

| 场景              | 优先工具            | 原因                            |
| --------------- | --------------- | ----------------------------- |
| 读文章/文档/博客（无需点击） | **web\_fetch**  | 更快更省；内部处理 JS 渲染               |
| 登录、表单、点击、无限滚动   | **browser**     | 完整交互 + Extension Bridge 复用登录态 |
| 先找 URL          | **web\_search** | 发现来源后再抓或浏览                    |

**机制**：工具描述 + Dynamic Hints（仅在配对工具可用时注入）+ Loop Guard 对称建议 + 浏览器池隔离（CRAWL vs AGENT）。Hermes 仅 browser→web\_extract 单向 hint；OpenClaw 无互引。

效果：零额外延迟、不破坏 prompt cache、比静态预规划更灵活。

### 检索模式

| 模式            | 何时   | 流水线                                       |
| ------------- | ---- | ----------------------------------------- |
| **Basic**（默认） | 多数查询 | BM25 + RRF 多查询融合 → 智能截断                   |
| **Precision** | 长文档  | 分块 → BM25 top-50 → Reranker top-20 → 合并相邻 |

Precision 用语义重排（阈值 **0.6**）— 低相关块丢弃。

### 同源衰减排序（Domain Diversity Sort）

多查询搜索结果自动按域名指数衰减重排序，防止单一网站刷屏。每个域名的后续结果按衰减因子（默认 **0.8**）递减：

* 第 1 条 `example.com` 结果 — 原始分数
* 第 2 条 `example.com` 结果 — 分数 × 0.8
* 第 3 条 `example.com` 结果 — 分数 × 0.64

确保 Agent 看到多样化的信息来源，而非同一网站的多个页面。无需配置，`combine_search_results_unified` 中默认启用。

### 视觉参考（无独立 image search 工具）

需要找参考图时，Agent 使用 **web\_search → web\_fetch / browser** 从页面获取图片 URL，再配合 **image\_tool** 生图。与 OpenClaw / Hermes 等通用助手一致，不维护单独的 DuckDuckGo 搜图依赖。

### 韧性

* **引擎回退** — 主引擎失败自动切换
* **15 分钟结果缓存** — 重复查询零成本
* **30s 健康探测** — 提前发现不可用引擎

## Web 抓取

### 3 级架构

| 级          | 速度      | 场景             |
| ---------- | ------- | -------------- |
| L1 HTTP    | \~100ms | 静态页、API        |
| L2 Browser | \~1–3s  | JS 渲染页         |
| L3 Stealth | \~3–5s  | Cloudflare、反爬站 |

**AdaptiveRouter** 学习每域成本并自动选最优级。

### 可选 L4 远程兜底（默认关闭）

L1–L3 全部失败后，可在 **设置 → 搜索 → 网页抓取远程兜底** 中**主动开启**：

| 提供商          | 作用                                                    |
| ------------ | ----------------------------------------------------- |
| Jina Reader  | 第一远程尝试（可选 Key；无 Key 时尝试免费档）                           |
| Firecrawl v2 | 第二尝试 — \*\*Keyless 免费层（1,000次/月）\*\*或输入 API Key 获更高配额 |

**Firecrawl v2 亮点：**

* **零配置即用** — 无需 API Key 即可使用 Firecrawl 免费层（1,000 次/月）
* **自定义 API Base** — 指向你自己的 Firecrawl 自托管实例，满足企业隐私或高吞吐需求
* **一键验证** — 设置界面可测试你配置的端点连通性（含自托管地址）

**与竞品差异（Hermes/OpenClaw 常直接走云 API 且必须 Key）：**

* **默认关闭** — 不影响 Turn1 工具装载与 Prompt 缓存
* **会话次数上限**（1–50）— 防止远程抓取失控计费
* **SSRF 防护** — 远程请求前强制校验
* **deep\_crawl 已移除** — 全站索引请用 search+fetch+browser，或接入 Firecrawl MCP
* **企业级 deny** — `MYRM_WEB_FETCH_ESCALATION=denied` 硬阻断

Myrm 坚持 **本地优先**，云端仅作显式、可封顶的最后手段。

### 隐私保护

**显式配置才启用：** 搜索仅在你手动配置并启用提供商后才会激活。与某些竞品在后台静默将用户查询发送到免费引擎（如 DuckDuckGo）不同，Myrm 在没有你的显式配置时绝不会发起任何网络请求。未配置 API key = 不搜索。

**透明回退通知：** 当主服务故障切换到你配置的备用服务时，你会在对话中收到实时通知，绝不会静默切换。

配置代理后，L2/L3 自动启用 **DNS over HTTPS (DoH)**——DNS 查询加密传输，ISP 和网络管理员无法得知你在访问哪些网站。零配置、零性能损耗。

### 广告/追踪器域名拦截

L2 和 L3 在网络层自动拦截 **3500+ 已知广告和追踪域名**（Peter Lowe 精选列表）。广告脚本根本不会加载——页面渲染更快、DOM 更干净、Token 消耗更低。零配置，standard 模式默认开启。

### fetch\_and\_extract（智能提取）

配置 Reranker + embedding 后，`web_fetch` 支持 **fetch\_and\_extract**：

1. 3 级爬取（HTTP → Browser → Stealth）
2. 页面分块
3. **BM25 + 向量混合检索**（Qdrant）
4. Reranker 重排 → 仅 top 相关段落

用**零 LLM 本地过滤**替代云端 LLM 摘要（如 Hermes `web_extract` + Gemini）。

### 内容清洗

文本进 Agent 上下文前：

1. **DOM 剪枝** — 去导航、广告、页脚、侧栏
2. **HTML → Markdown** — 结构化、LLM 友好
3. **智能截断** — `max_chars` + `was_truncated` 标志
4. **二进制路由** — PDF 单独解析（无乱码 HTML）
5. **YouTube 字幕快路径** — 自动识别 YouTube 链接，直接提取带时间戳的字幕；不可用时自动 fallback 到 HTML 抓取
6. **B站字幕快路径** — 自动识别 Bilibili 视频链接，通过公开 API（view + player）提取带时间戳的字幕；支持 SessionVault Cookie 获取 AI 生成字幕；不可用时 fallback 到浏览器抓取

### 缓存

* 请求合并（并发同 URL 只抓一次）
* Stale-While-Revalidate
* ETag / Last-Modified 条件请求
* 剥离 35+ 跟踪 URL 参数

## Deep Research：五阶段生命周期

Myrm 的 Deep Research 采用结构化的 **CLARIFY → PLAN → EXPLORE → RESEARCH → REPORT** 管线 — 不是简单的"搜一下再总结"：

| 阶段           | 做什么                                                          | 为什么重要                           |
| ------------ | ------------------------------------------------------------ | ------------------------------- |
| **CLARIFY**  | 结构化表单向用户确认意图                                                 | 100% 准确理解，不靠 AI 猜测              |
| **PLAN**     | 生成 ≤6 步研究计划，**暂停等用户审阅**（批准/编辑/跳过）                            | 系统覆盖，用户掌控方向，执行前不浪费 token        |
| **EXPLORE**  | 自动检索 Wiki 知识库（FTS5 全文搜索，零 LLM 成本）                            | 已有笔记的主题无需再搜索，子 Agent 只聚焦**新信息** |
| **RESEARCH** | 并行子 Agent 搜索 + `think` 工具自省；本地知识注入编排器提示词                     | 更快且每轮有质量检查，已知信息不重复搜索            |
| **REPORT**   | 多页结构化报告：内联引用【1】【2】+ 信息完整性规则 + Limitations/Gaps 声明，零额外 LLM 调用 | 可溯源验证，坦诚信息不足，不凭空杜撰              |

### Research Studio（三栏研究工作台）

`/research` 路由提供专为深度研究优化的三栏布局：

| 栏位         | 用途        | 核心功能                                          |
| ---------- | --------- | --------------------------------------------- |
| **左栏：资料池** | 组织输入材料    | Wiki 概念搜索、文件上传（含进度条）、checkbox 勾选              |
| **中栏：对话**  | 与 AI 协作研究 | 完整 ChatWindow，具备全部 Agent 能力                   |
| **右栏：产出**  | 预览研究成果    | ArtifactRenderer + PortalTabs + 下载 + 一键存 Wiki |

* **PC**：三栏并列，分割线可拖拽调整宽度（左栏 240–480px，右栏 280–600px）
* **移动端**：自动降级为 Tab 切换（768px 断点）
* **资料同步**：勾选资料池中的条目自动注入对话上下文（mentionReferences）；取消勾选自动移除，不影响用户手动 @ 的其他引用
* **产出操作**：下载工件或一键存入 Wiki（按当前 Agent 作用域）

### 研究中途控制

* **计划确认闸门** — 审阅、编辑或批准研究计划后才开始执行
* **HITL 回调** — 每轮结束可暂停调整方向
* **预算守卫** — `max_budget_usd` + 阈值告警
* **取消保留** — 随时停止，已完成结果保留
* **ReplanMiddleware** — 自动检测偏离并纠正

### vs MiroFlow（GAIA/BrowseComp 基准测试领先者）

|           |            Myrm           |               MiroFlow               |
| --------- | :-----------------------: | :----------------------------------: |
| 任务理解      |     ✅ 用户通过 CLARIFY 确认     |        ⚠️ AI 猜测"陷阱"（\$0.5–2/次）       |
| 研究规划      |          ✅ 结构化计划          |                  ❌ 无                 |
| 自我反思      |        ✅ `think` 工具       |                  ❌ 无                 |
| 中途控制      |      ✅ HITL + 取消 + 预算     |                  ❌ 无                 |
| 并行子 Agent |          ✅ 信号量控制          |                ❌ 单线串行                |
| 源去重       |      ✅ SourceTracker      |                  ❌ 无                 |
| 额外成本      |            \$0            |         \$0.5–2/次 o3 hint 调用         |
| 报告输出      | ✅ 多页结构化报告 + 内联引用 + 信息缺口声明 | ⚠️ `\boxed{42}` 短答案（仅 benchmark 评分用） |
| 报告可信度     |      ✅ 严格基于来源，未验证信息标注     |                  ❌ 无                 |

## 对比竞品

|        |                  Myrm                 |          Hermes         |         OpenClaw         |    OpenCode    |
| ------ | :-----------------------------------: | :---------------------: | :----------------------: | :------------: |
| 内置搜索   |                   ✅                   |            ✅            |             ✅            |        ✅       |
| 结果过滤   |            ✅ BM25/Reranker            |         ❌ API 直通        |          ❌ 原始片段          |    ❌ API 直通    |
| 内置抓取   |   ✅ 3 级本地 + L4 Firecrawl v2 Keyless   | ⚠️ Firecrawl+LLM（需 Key） | ⚠️ HTTP/Firecrawl（需 Key） |    ⚠️ 仅 HTTP   |
| 向量提取模式 |         ✅ fetch\_and\_extract         |        ❌（LLM 摘要）        |             ❌            |        ❌       |
| DOM 剪枝 |                   ✅                   |            ❌            |          ❌ 正则/文本         |  ❌ Turndown 整页 |
| 中文搜索   |              ✅ SearxNG+百度             |         ⚠️ 依赖后端         |          ❌ DDG 差         |    ⚠️ 云端 API   |
| 图片搜索   | ❌（web\_search + web\_fetch / browser） |            ❌            |             ❌            |        ❌       |
| 本地月成本  |         **\$0**（含 Keyless 免费层）        |       API 费（需 Key）      |   Firecrawl 回退费（需 Key）   | Exa/Parallel 费 |

### Hermes 差异（非更强）

* 插件后端（Exa/Tavily/Firecrawl）— 更多云厂商，均需 API Key
* `web_extract` 用 **LLM 摘要**跳过本地 embedding — 配置简单，**每页耗 Token**
* SSRF + URL 秘密阻断 — 成熟，与 Myrm 同级（非差异化）

### 自动去广告与冗余

| 清洗                 |         Myrm        | OpenClacky |    OpenCode   |   Hermes   |
| ------------------ | :-----------------: | :--------: | :-----------: | :--------: |
| 去 nav/侧栏/页脚        |      ✅ DOM 树剪枝      |   ❌ 全页正则   | ❌ Turndown 全页 | ⚠️ API/LLM |
| 去广告（link\_density） |          ✅          |      ❌     |       ❌       |      ❌     |
| 清洗搜索片段             |          ✅          |      ❌     |       ❌       |      ❌     |
| 多查询去重              |    ✅ URL+内容 hash    |      ❌     |       ❌       |      ❌     |
| 同源衰减排序             | ✅ decay\_factor=0.8 |      ❌     |       ❌       |      ❌     |
| 丢弃低相关段落            |    ✅ Reranker 0.6   |      ❌     |       ❌       |      ❌     |

**通俗说：** 我们不把整页丢给 AI — 提取正文、去广告导航、去重，只保留与问题相关的段落。

### 零配置对比

|                | Myrm                                              | Hermes                     |
| -------------- | ------------------------------------------------- | -------------------------- |
| 开箱 web\_fetch  | ✅ **本地 3 级 + L4 Firecrawl v2 Keyless**，无需 API Key | ❌ 需 Firecrawl/Exa Key      |
| 开箱 web\_search | ✅ GUI 一键 SearxNG/DuckDuckGo                       | ⚠️ `hermes tools` + 后端 Key |
| 长页智能提取         | ✅ fetch\_and\_extract                             | ⚠️ LLM 摘要（耗 Token）         |

**Myrm 在抓取上更零配置** — 本地清洗无需云 API。

## 检索充分性守卫 (RSG)

在 **deep search** 模式下，Myrm 会自动验证检索内容是否足够回答用户问题 — 在主 LLM 开始生成回答之前。

### 工作原理

每次 `web_search` 或 `web_fetch` 调用后（当 `search_depth == "deep"` 时）：

1. **轻量级 LLM**（你配置的 `lite_model`）评估检索结果与原始查询的匹配度
2. 返回结构化评估：充分/不充分 + 缺失信息 + 建议的后续查询
3. 检测 **负面约束违规**（如"排除 React"但结果包含 React 内容）
4. 结果附加到工具输出，供主 Agent 决策

### 核心设计

| 方面   | 决策                              | 原因                  |
| ---- | ------------------------------- | ------------------- |
| 激活条件 | 仅 `deep` 模式                     | 普通搜索保持快速；深度搜索获得质量保障 |
| 模型   | `lite_model_cfg` (Flash/Haiku)  | 成本 \< \$0.001/次评估   |
| 输出   | JSON Schema 强制                  | 本地模型也能可靠输出结构化结果     |
| 容错   | fail-open（`is_sufficient=True`） | 永不阻塞主流程             |
| 阈值   | `confidence >= 0.7` 通过          | 低于阈值视为不充分           |

### 负面约束检测（独有能力）

向量搜索和 BM25 无法处理"排除X"这类条件。RSG 显式提取这些约束并逐一校验：

```
查询："推荐后端框架，排除 Node.js"
检索结果：包含 Express.js（Node.js）的文章
RSG 评估：negative_constraint_violations = ["包含 Node.js/Express 内容"]
```

Agent 看到违规后会自动补搜以获取更精准结果。

### vs 竞品

没有竞品（Hermes、OpenClaw、Claude Code、Perplexity）有等价的后检索充分性校验。它们完全依赖主 LLM 判断信息是否充足 — 这是不可靠的，因为：

1. LLM 倾向于即使数据不足也自信作答（幻觉）
2. 没有专用评估器就无法做显式负面约束检测
3. 没有结构化指导告诉 Agent 接下来该搜什么

## PTC 集成

在 Programmatic Tool Calling 脚本中：

```python theme={null}
results = await tools.web_search("competitor pricing 2026", max_results=5)
page = await tools.web_fetch("https://example.com/pricing")
```

无额外 API 往返 — 搜索与抓取在沙箱内执行。

## 配置

1. **设置 → 搜索** — 选引擎、API Key、SearxNG URL
2. 检索设置启用 **Reranker** — 长文档 Precision 模式
3. **Web Fetch** 开箱可用（浏览器级用 Patchright 若已安装）

## 迁移提示

| 来自          | 操作                                               |
| ----------- | ------------------------------------------------ |
| Hermes      | 导入配置；停用仅 Firecrawl 的 web\_extract；用本地 web\_fetch |
| OpenClaw    | 导入配置；移除手工 Tavily/百度 Skill                        |
| Claude Code | 启用 SearxNG 自托管搜索；经 LiteLLM 配相同模型                 |

完整迁移收益见[竞品对比](/zh/getting-started/competitor-comparison#web-search--web-fetch--dual-engine-vs-hermes--openclaw--claude-code)。