metona-ai-desktop/docs/Agent网络工具通用设计-v2.md

Agent 网络工具通用设计（增强版）

本文档描述 Agent 网络工具链的整体设计与优化方案，涵盖 SearXNG 元搜索配置、web_search 搜索、web_fetch 抓取、browser 浏览器控制四个核心模块。文档聚焦架构、配置与接口，不绑定具体编程语言与框架实现，并给出各环节可引入的成熟第三方库建议。

目录

1. SearXNG 配置设计
2. web_search 搜索设计
3. web_fetch 抓取设计
4. browser 浏览器设计
5. 第三方库选型指南
6. 优化增强路线图

---

1. SearXNG 配置设计

1.1 架构概览

SearXNG 是开源元搜索引擎，支持 70+ 搜索引擎聚合，不追踪用户、不记录隐私。本设计将 SearXNG 作为可选替代方案：启用后通过 SearXNG 的 JSON 或 HTML API 进行搜索；关闭时回退到内置四引擎 HTML 解析方案（Bing + 百度 + 搜狗 + 360 搜索）。

整体分为三层。UI 层负责配置模态框的交互与表单同步；数据层负责通过本地数据库读写配置项，键值对形式持久化；执行层位于主进程，在搜索请求到来时读取配置，决定走 SearXNG 通道还是内置引擎通道，并完成参数拼装、认证注入、请求发送与结果解析。

┌─────────────────────────────────────────────────────┐
│                    UI 层（Renderer）                   │
│  配置模态框 / 表单控件 / 状态指示                      │
├─────────────────────────────────────────────────────┤
│              数据层（SQLite / LocalStorage）           │
│  键值对持久化 / 运行时缓存 / 配置校验                  │
├─────────────────────────────────────────────────────┤
│              执行层（Main Process）                    │
│  参数拼装 → 认证注入 → API 调用 → 结果解析             │
│  双模式切换：SearXNG / 内置四引擎                     │
└─────────────────────────────────────────────────────┘

1.2 配置项定义

SearXNG 相关配置共 12 项，各配置项的默认值与含义如下：

配置项	类型	默认值	说明
enabled	boolean	false	是否启用 SearXNG
url	string	''	SearXNG 实例根地址（不含 /search 路径）
engines	string	''	引擎列表，逗号分隔，留空则使用实例默认引擎
language	string	'zh-CN'	搜索语言
safesearch	number	1	安全搜索级别（0=关闭，1=中等，2=严格）
time_range	string	''	时间范围过滤（day/week/month/year）
max_results	number	0	单次最大结果数，0 表示使用默认
auth_key	string	''	认证密钥，内容随认证类型不同而不同
auth_type	string	'bearer'	认证类型（bearer 或 basic）
format	string	'json'	返回格式（json 或 html）
fetch_count	number	0	自动抓取条数，0 表示由 AI 决定
fetch_mode	string	'sequential'	抓取类型（sequential 顺序或 random 随机）

1.3 持久化存储

配置通过本地数据库以键值对形式持久化。写入时逐项调用 saveSetting(key, value)，读取时通过 getSetting(key, default) 回填到运行时缓存。对应的存储键名汇总如下：

存储键名	对应配置项	默认值
searxng_enabled	enabled	false
searxng_url	url	''
searxng_engines	engines	''
searxng_language	language	'zh-CN'
searxng_safesearch	safesearch	1
searxng_time_range	time_range	''
searxng_max_results	max_results	0
searxng_auth_key	auth_key	''
searxng_auth_type	auth_type	'bearer'
searxng_format	format	'json'
fetch_count	fetch_count	0
fetch_mode	fetch_mode	'sequential'

1.4 UI 模态框

配置界面以模态框形式呈现，包含以下交互控件。启用开关为实时保存，切换即写入数据库；其余字段在点击保存按钮时统一校验并落库。URL 字段需通过非空校验与 http/https 格式校验。

• 启用开关：实时切换 SearXNG 启用状态，立即持久化
• API 地址：实例根地址，必填，需为 http/https 格式
• 搜索引擎：逗号分隔的引擎名称，留空使用实例默认
• 语言选择：下拉项含 zh-CN / zh-TW / en / ja / ko / 自动检测
• 安全搜索：下拉项含 0 关闭 / 1 中等 / 2 严格
• 时间范围：下拉项含 不限 / 一天 / 一周 / 一月 / 一年
• 结果数量：数字输入，0 表示使用默认
• 返回格式：下拉项含 JSON 结构化解析 / HTML 原始网页
• 自动抓取条数：数字输入，范围 1–8
• 抓取类型：下拉项含 顺序抓取 / 随机抓取
• 认证设置：认证类型（bearer / basic）+ 认证密钥（密码型输入框）
• 保存按钮：校验后批量持久化全部字段
• 连接测试按钮（增强）：一键验证 URL 可达性与认证有效性

工具栏入口按钮上设状态指示圆点：启用时为绿色，未启用时为灰色；模态框内同时显示文字状态徽章（已启用 / 未启用）。

1.5 SearXNG 认证方式详解

SearXNG 实例可配置鉴权，本设计支持两种认证类型，由 auth_type 配置项决定，认证密钥统一存放在 auth_key 中。两种方式的核心区别在于请求头的构造方式与密钥的填写格式。

Bearer Token 认证（auth_type = 'bearer'，默认值）

当认证类型为 bearer 时，系统在 HTTP 请求头中添加：

Authorization: Bearer <auth_key>

密钥原样放入 token 位置，不做任何编码转换。auth_key 应直接填写 SearXNG 实例签发的访问令牌本身。

适用场景：

• SearXNG 实例通过反向代理（如 Nginx/Caddy）签发的固定令牌鉴权
• JWT（JSON Web Token）格式的令牌
• OAuth2 Bearer Token
• 任何基于 Token 的简单鉴权方案

安全要求：建议配合 HTTPS 使用，防止令牌在网络传输中被截获。

Basic 认证（auth_type = 'basic'）

当认证类型为 basic 时，系统将 auth_key 整体进行 Base64 编码，再在请求头中添加：

Authorization: Basic <Base64(auth_key)>

auth_key 应填写 用户名:密码 格式的明文字符串，由系统负责编码。

适用场景：

• SearXNG 实例配置了 HTTP Basic Auth 的场景
• Nginx/Caddy 反向代理的 auth_basic 指令保护
• 任何标准用户名密码鉴权网关

安全要求：必须配合 HTTPS 使用。Basic Auth 以 Base64 编码传输凭据（非加密），明文网络可还原。

两种方式对比

维度	Bearer	Basic
请求头格式	Authorization: Bearer <token>	Authorization: Basic <Base64>
密钥填写内容	令牌原值	用户名:密码 明文串
是否编码	否，原样透传	是，整体 Base64 编码
适用场景	令牌/JWT/OAuth2 鉴权	用户名密码鉴权
安全要求	建议 HTTPS	必须 HTTPS
凭据可复用性	高（无状态令牌）	低（每次携带凭据）
撤销方式	令牌失效/黑名单	修改密码

无论哪种方式，仅当 auth_key 非空时才会注入 Authorization 头；auth_key 为空则视为匿名访问，不附加任何认证信息。认证逻辑对 JSON 与 HTML 两种返回格式均生效。

1.6 主进程搜索调用流程

搜索请求到达主进程后，执行层按以下步骤处理：

1. 读取配置：从数据库加载全部 SearXNG 相关配置项
2. 构建参数：
   • 查询词、引擎列表、语言、安全搜索级别拼入查询串
   • 时间范围优先使用调用方传入值，缺省时回退到配置项默认值
   • 最大结果数取配置项与入参的较大有效值
3. 认证注入：根据 auth_type 构造对应的 Authorization 请求头
4. 发送请求：向 <url>/search?<参数> 发起 HTTP GET 请求
5. 解析结果：
   • JSON 模式：结构化解析每条结果的标题、URL、摘要、来源引擎
   • HTML 模式：转为纯文本交由 AI 自行分析
6. 统计引擎状态：记录各引擎命中条数与异常原因

1.7 双模式切换逻辑

在统一的搜索入口处，通过读取 searxng_enabled 判断走哪条通道：

• SearXNG 启用时：
  • 自动抓取条数从面板配置读取，取配置项与默认下限的较大值，限制在最大抓取上限内
  • 抓取类型为顺序或随机
  • 日志标记来源为 [SearXNG]
• 未启用时：
  • 走内置四引擎并行搜索通道
  • 日志标记来源为 [内置]

---

2. web_search 搜索设计

2.1 架构概览

web_search 是搜索工具的总入口，内部根据 SearXNG 开关分流到两条通道。SearXNG 通道走元搜索 API；内置通道则并行调度四个搜索引擎，经合并去重、可达性预检、智能排序、摘要增强与缓存后输出结果。无论哪条通道，最终都会进入自动抓取阶段，对前 N 条结果抓取完整内容。

web_search 入口
    ├── searxng_enabled?
    │   ├── 是 → SearXNG API 搜索
    │   └── 否 → 内置四引擎并行搜索
    │              ├── Bing (权重90)
    │              ├── 百度 (权重80)
    │              ├── 搜狗 (权重75)
    │              └── 360搜索 (权重75)
    │         → Promise.allSettled 并行容错
    │         → 合并去重（URL 标准化）
    │         → 可达性预检（并发5）
    │         → 智能排序（可达性+权重+摘要质量）
    │         → 摘要自动增强（web_fetch top3）
    │         → LRU 缓存（5分钟TTL）
    └── 自动抓取前N条完整内容
        → 相关性过滤 → 逐条抓取 → 失败随机补充

2.2 函数参数

web_search 接受以下参数：

参数	类型	默认值	说明
query	string	必填	搜索关键词
max_results	number	30	最大结果数，上限 30
time_range	string	—	时间过滤（day/week/month/year 等，支持中英文别名）
enhance_snippets	boolean	true	是否自动增强过短摘要
fetch_top	number	5	自动抓取前 N 条完整内容，范围 3–8

2.3 内置四引擎并行搜索

内置通道调度四个搜索引擎，每个引擎带有权重，用于后续排序。四个引擎并行执行，采用容错并发模型，任一引擎失败不影响其余引擎。

引擎	权重	请求地址	特殊处理
Bing	90	bing.com/search	支持 freshness 参数映射时间范围
百度	80	baidu.com/s	从 data-url 属性提取真实 URL
搜狗	75	sogou.com/web	过滤 sogou.com 自身链接
360 搜索	75	so.com/s	过滤 so.com 自身链接

时间范围参数映射规则：

用户输入	Bing 参数	说明
day / 1d / 一天	Day	最近一天
week / 1w / 一周	Week	最近一周
month / 1m / 一月	Month	最近一月

2.4 搜索引擎 HTML 解析

每个引擎返回的是 HTML 页面，需要专门的解析器从中提取标题、URL、摘要三要素。四个解析器的提取策略各有差异，但整体思路一致：先以块级结构切分结果条目，再从条目内提取标题链接与摘要文本，最后过滤掉引擎自身的导航类链接。

• Bing 解析：按 <li class="b_algo"> 块切分，从锚点提取标题与 URL，从 <p> 或 .b_caption 提取描述
• 百度解析：按 <div class="result"> 块切分，标题取自 <h3 class="t"> 锚点，真实 URL 取自 data-url 属性，摘要取自 .c-abstract 或 .content-right_*
• 搜狗解析：按 .vrwrap 或 .rb 块切分，摘要取自多个候选区域（.star-wiki / .space-txt / .str_info），过滤 sogou.com 自身链接
• 360 搜索解析：按 .res-list 或 .result 块切分，摘要取自 .res-desc / .res-rich / .res-summary / <dd>，过滤 so.com 自身链接

[增强建议] 各引擎解析器可迁移至基于 CSS 选择器的 DOM 解析方案（如 Cheerio），替代当前的正则匹配，提升鲁棒性与维护性。详见第 5 章「第三方库选型指南」。

2.5 智能排序算法

合并去重后，对结果计算综合评分并排序。评分由三部分加权构成：

\text{score} = \underbrace{\frac{\text{weight}}{100} \times 50}_{\text{引擎权重 50\%}} + \underbrace{\text{可达性加分}}_{\text{可达 +30 / 不可达 -20}} + \underbrace{\frac{\min(\text{snippetLen}, 100)}{100} \times 20}_{\text{摘要质量 20%（上限100字符）}}

最终按评分降序排列。

2.6 URL 可达性预检

为剔除死链，排序前对候选结果做可达性预检。采用并发批次控制策略：

• 并发数：每批 5 个 URL
• 超时：每个请求 3 秒
• 判断标准：仅判断响应是否成功（HTTP 2xx），不读取正文
• 结果回填：写入结果的 reachable 字段（true / false）

2.7 摘要自动增强

当 enhance_snippets 开启时，对排序前列中摘要过短（< 30 字符）且可达的结果，调用 web_fetch 补充抓取其正文，取前 200 字符替换原摘要。该增强最多对前 3 条执行，避免过度请求。增强后的结果打上 _enhanced: true 标记。

2.8 自动抓取完整内容

搜索完成后，对前 N 条结果自动抓取完整正文，供 AI 综合分析。完整流程：

1. 相关性过滤：从查询词中提取中文双字/三字片段与英文单词，在标题与摘要中匹配计分，得分上限 100，得分为 0 的结果直接过滤
2. 构建抓取列表：
   • sequential 模式：按相关性降序取前 N 条
   • random 模式：Fisher-Yates 洗牌后取 N 条
3. 逐条抓取：调用 web_fetch，失败时从剩余未抓取结果中随机选 1 条补充重试
4. 结果存入：_fetched 数组 + _fetched_count 计数

2.9 LRU 搜索缓存

为降低重复查询的开销，搜索结果带 LRU 缓存。

参数	值
最大容量	200 条
过期时间	5 分钟（300,000ms）
缓存键	查询词（归一化后）
淘汰策略	最早写入淘汰
命中时行为	校验时效，过期删除并返回未命中

[增强建议] 可替换为成熟的 lru-cache 库，支持 TTL、大小限制、统计指标等开箱能力。详见第 5 章。

2.10 响应格式

web_search 返回结构化结果，主要字段如下：

{
  "success": true,
  "query": "搜索关键词",
  "results": [
    {
      "title": "标题",
      "url": "https://...",
      "snippet": "摘要文本",
      "engine": "bing",
      "weight": 90,
      "reachable": true,
      "_score": 68.5,
      "_enhanced": false
    }
  ],
  "total": 15,
  "formatted": "人类可读文本汇总",
  "structured": [...],
  "from_cache": false,
  "engine_stats": { "bing": "8 条", "百度": "5 条" },
  "_mode": "builtin | searxng",
  "_fetched": [{ "url", "title", "content" }],
  "_fetched_count": 5
}

---

3. web_fetch 抓取设计

3.1 架构概览

web_fetch 采用三阶段回退策略，确保最大概率获取网页内容：

Phase 1: HTTP 抓取
├── UA 轮换池（5种）+ Accept-Language 轮换池（3种）
├── 指数退避重试（2s→4s→6s + jitter ±60%）
├── 反爬请求头（Sec-Fetch-* / DNT / Referer 等）
├── 流式读取（10MB 上限）
└── 拦截检测（10 种特征模式）
    ↓ 失败/被拦截/内容过短
Phase 2: SPA 自动升级
└── HTML 内容 < 200 字符 → 升级浏览器渲染
    ↓ 失败
Phase 3: 浏览器回退
├── 打开隐藏窗口 → 等待 2.5s JS 渲染
├── 提取页面正文 → 关闭窗口
└── LRU 缓存（100 条, 10 分钟 TTL）

3.2 函数参数

web_fetch 接受以下参数：

参数	类型	默认值	说明
url	string	必填	目标 URL，仅支持 http/https
max_chars	number	—	最大字符数，0 表示不截断
extract_mode	string	—	提取模式
mobile_ua	boolean	—	是否使用移动端 UA
retry	boolean	true	是否启用重试

3.3 反爬请求头

为规避基础反爬，HTTP 抓取阶段采用请求头轮换策略。

UA 轮换池（5 种）：覆盖桌面 Chrome、Edge、Safari、Firefox 与移动端 Chrome，模拟主流浏览器指纹。

Accept-Language 轮换池（3 种）：中英混合、中文优先、英文优先三种语言偏好。

每次重试按尝试序号取模轮换 UA 与语言，同时附带完整的反爬请求头集合：

请求头	值	用途
User-Agent	轮换池取模	浏览器指纹伪装
Accept	text/html,application/xhtml+xml,...	声明接受内容类型
Accept-Language	轮换池取模	语言偏好伪装
Accept-Encoding	gzip, deflate, br	声明压缩格式
Cache-Control	no-cache	禁止缓存
DNT	1	Do Not Track
Referer	目标站点根地址	来源页伪装
Sec-Fetch-Dest	document	导航目标声明
Sec-Fetch-Mode	navigate	请求模式声明
Sec-Fetch-Site	none	来源站点声明
Sec-Fetch-User	?1	用户触发声明
Pragma	no-cache	HTTP/1.0 兼容

[增强建议] 可引入 got-scraping 库，其内置了更完善的浏览器指纹模拟、Cookie Jar 管理、HTTP/2 支持与代理集成能力，详见第 5 章。

3.4 重试配置

参数	值
最大重试次数	3 次（Phase 1 内部）
基础退避间隔	2s → 4s → 6s
Jitter 范围	基础延迟 × [0%, +60%] 随机
直接跳过重试的状态码	403 / 503 / 429 / 502
可重试状态码	5xx（除上述外）

3.5 HTML 转文本引擎

抓取到的 HTML 需转为纯文本。处理流水线：

1. 移除噪声标签及内容：script、style、noscript、nav、header、footer、aside、iframe、svg
2. 移除 HTML 注释
3. 块级标签转行：p、div、h1-h6、li、tr、blockquote、section、article、pre、br、hr → \n
4. 表格单元制表符：td、th → \t
5. 移除剩余标签
6. 解码 HTML 实体：30+ 命名实体（ 、<、&、…、— 等）+ 全部数字实体（{、）
7. 清理空白：合并连续空白、清理首尾空行

[增强建议] 可引入 @mozilla/readability 作为前置步骤，先提取文章主体内容再做文本转换，大幅减少导航/广告/侧边栏等噪声；或使用 turndown 将 HTML 转 Markdown 保留结构。详见第 5 章。

3.6 拦截页面检测

维护一组拦截特征模式，命中任一特征即判定为拦截页，触发浏览器回退：

特征模式	对应防护
Just a moment... / Cloudflare 标题	Cloudflare JS Challenge
Attention Required!	Cloudflare 托管挑战
challenge-platform	Cloudflare 平台标识
.cf-challenge- 类名	Cloudflare Challenge 页面
Access Denied 标题	WAF 拒绝
403 Forbidden 标题	HTTP 403 拦截
请启用 JavaScript	JS 强制检测
Please enable JavaScript	JS 强制检测（英文）
Checking your browser	浏览器环境检测
DDoS protection	DDoS 防护页
正文长度 < 80 字符	空白/空壳页面

3.7 内容过短自动升级

对于成功返回但正文过短（< 200 字符）的页面——通常是 SPA 单页应用或空壳页面，其有效内容依赖 JS 渲染——自动升级到浏览器渲染通道。若渲染成功则用渲染结果替换，方法标记为 browser。

3.8 浏览器回退实现

浏览器回退通道的完整流程：

1. 查缓存：LRU 缓存（100 条，10 分钟 TTL），命中则截断返回
2. 打开窗口：隐藏 BrowserWindow 加载目标 URL
3. 等待渲染：2.5秒让 SPA/动态内容完成 JS 渲染
4. 提取正文：移除非内容标签后取 innerText
5. 关闭窗口：确保资源释放
6. 写缓存：正文 ≥ 100 字符时写入缓存

异常保障：任何步骤出错均确保调用关闭函数，避免窗口泄漏。

3.9 触发浏览器回退的条件

条件	说明	Phase 1 → Phase 3
HTTP 403/503/429/502	反爬/限流/拦截信号	✅ 直接跳转
拦截特征匹配	Cloudflare/验证码/JS 要求等	✅ 直接跳转
内容 < 200 字符	SPA 或空壳页面	✅ 经 Phase 2 升级
请求超时	超过 HTTP 超时阈值	✅ 直接跳转
所有重试均失败	网络不可达等	✅ 直接跳转

3.10 流式读取与大文件保护

参数	值
硬上限	10 MB
无 Content-Length 时	流式读取，累计字节数
超限处理	中止下载，返回错误
有 Content-Length 时	预判是否超限

3.11 超时封装

HTTP 抓取通过带超时的封装发起请求：创建 AbortController，设定超时定时器，超时即中止请求。该封装同时被搜索阶段的可达性预检复用。

---

4. browser 浏览器设计

4.1 架构概览

browser 模块基于隐藏浏览器窗口实现，提供完整的网页加载、截图、JS 执行、内容提取与交互操作能力。整个模块封装为单例窗口，包含 9 个核心函数。

函数	职责	关键参数
browserOpen	打开 URL	url, waitSelector
browserScreenshot	截图	fullPage, selector（视口/元素/全页三模式）
browserEvaluate	执行 JS	js（任意代码）
browserExtract	提取内容	selector, maxChars
browserClick	点击元素	selector, wait
browserType	输入文本	selector, text, clear, submit
browserScroll	滚动页面	direction, selector
browserWait	等待条件	selector, timeMs
browserClose	关闭窗口	—

窗口默认参数：1280×800、不可见（show:false）、上下文隔离、沙箱模式、页面加载超时 30s。

4.2 核心状态管理

维度	设计决策
实例模式	单例懒加载，首次调用时创建
销毁方式	browserClose() 显式销毁
应用退出	统一调用 browserClose() 清理
就绪检查	操作前校验窗口存在且已加载页面
安全配置	禁用 Node.js 集成、上下文隔离、沙箱、允许跨域（截图需要）

4.3 打开 URL

• 若已有窗口加载了不同 URL → 先关闭重建，避免历史状态干扰
• 加载目标 URL，30 秒超时
• 可选等待指定 CSS 选择器出现（轮询 300ms，最长 10s）
• 返回页面标题与实际 URL

4.4 截图

三种模式：

模式	触发条件	输出
元素截图	指定 selector	该元素矩形区域 PNG（Base64）
全页截图	fullPage=true	完整滚动尺寸 PNG（Base64）
视口截图	默认	当前可见区域 PNG（Base64）

4.5 执行 JavaScript

接收任意 JS 在页面上下文中执行。字符串原样返回，其余类型序列化为格式化 JSON。独立超时控制。

4.6 提取页面内容

• 克隆目标根节点，移除 script/style/iframe/svg 后取 innerText
• 支持 CSS 选择器限定提取区域
• 默认上限 15000 字符
• 同时提取最多 50 个有效链接（http 开头 + 有可见文本）

4.7 点击元素

可选等待元素出现 → 滚动到视口中央 → 触发点击 → 等待 500ms。元素不存在则报错。

4.8 输入文本

聚焦 → clear 决定清空/追加 → 赋值 → 触发 input + change 事件（兼容 React/Vue）→ submit 决定是否提交（form.submit 或 Enter 键）。输入后等 300ms（提交等 1000ms）。

4.9 滚动页面

• 指定 selector → scrollIntoView 到中央
• 方向滚动：down(+500px) / up(-500px) / top(回顶) / bottom(到底)

4.10 等待条件

• 选择器等待：轮询 300ms，默认 10s（可由 timeMs 覆盖）
• 定时等待：按 timeMs 固定延迟，默认 1s

4.11 关闭浏览器

销毁单例窗口并置空引用。幂等操作——窗口已销毁时为空操作。

4.12 工具调度映射

所有 browser 函数通过统一工具执行通道调度：

调用名	映射函数	入参
browser_open	browserOpen	url, wait_selector
browser_screenshot	browserScreenshot	full_page, selector
browser_evaluate	browserEvaluate	js
browser_extract	browserExtract	selector, max_chars
browser_click	browserClick	selector, wait
browser_type	browserType	selector, text, clear, submit
browser_scroll	browserScroll	direction, selector
browser_wait	browserWait	selector, time_ms
browser_close	browserClose	—

4.13 浏览器与 web_fetch 的协作关系

web_fetch 三阶段回退:
  Phase 1 (HTTP) 失败
    ├─ 403/503/429/502? → browserFallback(url)
    ├─ Cloudflare 拦截?   → browserFallback(url)
    ├─ 内容 < 200 字符?   → browserFallback(url) [经 Phase 2]
    ├─ 超时?              → browserFallback(url)
    └─ 所有重试失败?       → browserFallback(url)

browserFallback:
  browserOpen(url) → 等待 2.5s → browserExtract() → browserClose()
  结果进入 LRU 缓存 (100条, 10分钟TTL)

4.14 超时配置汇总

工具	默认超时	最大超时	说明
web_search	3,000ms/引擎	300,000ms	每引擎独立超时
web_fetch	20,000ms	600,000ms	HTTP 抓取超时
browser_extract	10,000ms	300,000ms	页面提取超时
browser_evaluate	8,000ms	—	JS 执行超时
browser_screenshot	—	60,000ms	截图超时
browser_open	30,000ms	—	页面加载超时

---

5. 第三方库选型指南

本章针对工具链各环节，给出经过筛选的成熟第三方库推荐，涵盖 HTTP 客户端、HTML 解析、文章提取、浏览器反检测、缓存、URL 处理等领域。所有推荐库均为 npm 生态中活跃维护、广泛使用的项目。

5.1 HTTP 客户端层

当前实现使用原生 fetch + 手动请求头构造。以下库可在对应层面提供增强：

got-scraping（⭐ 重点推荐）

维度	详情
包名	got-scraping
定位	专为网页抓取设计的 HTTP 客户端，基于 got 封装
核心优势	内置浏览器指纹轮换、Cookie Jar 自动管理、HTTP/2 支持、代理集成、流式处理
指纹模拟	自动轮换 Header Order、TLS 指纹、HTTP/2 SETTINGS 帧，比手动构造请求头更难被识别
代理支持	原生支持 HTTP/SOCKS5 代理，可配置代理轮换
Cookie 管理	自动 Cookie Jar，跨请求保持会话状态
重试机制	内置指数退避重试，可自定义重试条件
适用环节	替代 web_fetch Phase 1 的原生 fetch，显著降低被反爬识别的概率
替代方案	axios（通用 HTTP 客户端）、undici（Node.js 原生 HTTP/1.1 客户端）

为什么选 got-scraping 而非 axios/got：

axios 是通用 HTTP 客户端，不具备抓取专用能力；got 是底层 HTTP 库，功能强大但需自行组装抓取特性；got-scraping 在 got 之上专门为抓取场景做了封装，开箱即用的指纹模拟、Cookie 管理与代理支持正好覆盖 web_fetch Phase 1 的全部需求。

axios（备选）

维度	详情
包名	axios
定位	最流行的 Node.js/Browser 通用 HTTP 客户端
核心优势	拦截器机制、请求/响应转换、取消令牌、CSRF 保护、JSON 自动处理
周边生态	axios-retry（自动重试）、cache-interceptor（缓存拦截器）
适用环节	如不需要抓取专用特性而偏向通用性，可作为基础 HTTP 层
注意事项	不自带指纹模拟，需手动构造请求头；2025 年曾发生供应链攻击事件，锁定版本

5.2 HTML 解析层

当前实现使用正则表达式解析搜索引擎 HTML 结果。以下库可提供更健壮的 DOM 级解析能力：

cheerio（⭐ 重点推荐）

维度	详情
包名	cheerio
定位	服务端 jQuery 核心子集实现，轻量快速 DOM 解析
核心优势	jQuery 风格 API（$('.b_algo')）、极快速度（约比 jsdom 快 8 倍）、零依赖、API 熟悉度高
适用环节	替代四引擎解析器中的正则匹配，改用 CSS 选择器精确提取标题/URL/摘要
示例场景	$('li.b_algo').each((i, el) => { const $el = $(el); ... })
版本注意	Cheerio v1（最新版）API 有变化，需参考新版文档

jsdom（特定场景备选）

维度	详情
包名	jsdom
定位	纯 JavaScript 实现的完整 DOM 环境
核心优势	完整 DOM API（querySelector/getComputedStyle 等）、脚本执行、兼容依赖 DOM 的库
适用环节	需要 DOM 兼容性的复杂解析场景（如运行依赖 DOM 的第三方提取脚本）
权衡	比 cheerio 慢且重量大，一般场景 cheerio 已足够

parse5（底层备选）

维度	详情
包名	parse5
定位	WHATWG HTML Living Standard 合规的 HTML 解析/序列化工具集
核心优势	严格符合 HTML5 规范、可处理畸形 HTML、提供 serialize 功能
适用环节	需要规范合规 HTML 解析的底层场景；或作为 cheerio/jsdom 的底层解析引擎

5.3 文章内容提取层

当前 htmlToText 函数做简单的标签移除与文本提取。以下库可大幅提升文章类页面的提取质量：

@mozilla/readability（⭐ 重点推荐）

维度	详情
包名	@mozilla/readability
定位	Mozilla Firefox Reader View 的算法移植，自动提取文章主体内容
核心优势	基于 Mozilla 成熟算法，自动识别文章正文区、剥离导航/广告/评论/侧边栏噪声
输入要求	需配合 jsdom 提供 DOM 环境
输出	{ title, content, textContent, length }
适用环节	web_fetch 抓取后作为 htmlToText 的前置步骤：先 readability 提取主体，再转文本
效果预期	对新闻/博客/百科/论坛帖子类页面效果极佳，可直接替代手动噪声标签列表
依赖	需搭配 jsdom 使用
同类项目	node-readability（封装了 request + @mozilla/readability 的老项目，已不太活跃）
注意事项	对非文章类页面（如搜索结果页、列表页、数据仪表盘）可能误提取或返回空

turndown（HTML → Markdown）

维度	详情
包名	turndown
定位	HTML 到 Markdown 的转换器
核心优势	保留文档结构（标题层级、表格、列表、代码块、链接），输出格式友好
适用环节	当需要保留 HTML 结构而非纯文本时，作为 htmlToText 的替代或补充
使用方式	TurndownService().turndown(htmlString) → Markdown 文本

5.4 浏览器反检测层

当前 browser 模块使用 Electron 原生 BrowserWindow，无额外反检测措施。以下插件可显著降低被网站识别为自动化脚本的概率：

puppeteer-extra-plugin-stealth（⭐ 重点推荐）

维度	详情
包名	puppeteer-extra-plugin-stealth
定位	Puppeteer 反检测插件，隐藏无头浏览器自动化痕迹
核心优势	18 种独立的反检测技术模块，系统性覆盖所有主要检测维度
检测维度覆盖	见下方详细列表
架构设计	微内核 + 插件化，每种技术封装为独立模块，可单独启停
依赖关系	需配合 puppeteer-extra 使用
适用环节	browser 模块的 BrowserWindow 创建时注入 stealth 脚本，或在 browser 回退通道中使用 puppeteer-extra 替代原生 BrowserWindow

18 种反检测技术模块清单：

#	模块名	解决的检测点
1	navigator.webdriver	移除 webdriver=true 标志
2	chrome.runtime	模拟 chrome.runtime 对象
3	chrome.loadTimes	模拟已废弃但仍被检测的 API
4	chrome.csi	模拟 Chrome CSI 对象
5	iframe.contentWindow	修复 iframe contentWindow 检测
6	media.codecs	补全媒体编解码器支持列表
7	navigator.plugins	模拟浏览器插件信息
8	navigator.languages	修正语言设置
9	navigator.platform	修正平台标识
10	navigator.hardwareConcurrency	模拟真实的 CPU 核心数
11	webgl.vendor	伪装 WebGL 渲染厂商/型号
12	window.outerdimensions	修正窗口尺寸关系
13	sourceurl	移除源码 URL 泄露
14	user-agent-override	同步 navigator.userAgent 与请求头
15	permissions	修正 Permissions API 行为
16	runtime.enable	修复 chrome.runtime.enable
17	eof	修复 EOF 检测
18	preload	修复脚本 preload 检测

集成建议：由于本项目基于 Electron（非独立 Puppeteer），有两种集成路径：(A) 将 stealth 插件的各模块 JS 脚本提取出来，通过 webContents.executeJavaScript 在 BrowserWindow 加载时注入；(B) 在 browser 回退通道中使用 puppeteer-extra + stealth 替代原生 BrowserWindow。路径 A 更轻量，路径 B 更彻底。

5.5 缓存层

当前使用手写 Map 实现 LRU 缓存。以下库提供更完善的能力：

lru-cache（⭐ 推荐）

维度	详情
包名	lru-cache
定位	高性能 LRU 缓存实现，支持 TTL、大小限制、统计
核心优势	TTL 自动过期、 maxSize 按 count 或 byte 限制、hit/miss/stale 统计、异步 dispose 回调
适用环节	替代搜索缓存（200 条/5min）和浏览器回退缓存（100 条/10min）的手写实现
API 示例	new LRUMax({ max: 200, ttl: 300_000 })

cacheable（备选）

维度	详情
包名	cacheable
定位	支持多后端（内存/Redis/文件）的统一缓存抽象
核心优势	可无缝切换存储后端，适合未来分布式部署需求
适用环节	如果未来需要跨进程共享缓存（如主进程 + 多个渲染进程）

5.6 URL 处理层

当前 URL 去重依赖简单标准化。以下库可提供更强的 URL 归一化能力：

normalize-url（推荐）

维度	详情
包名	normalize-url
定位	URL 归一化工具
核心优势	自动去除追踪参数（utm_*）、统一协议/路径/查询串/片段格式、强制小写、去除默认端口
适用环节	搜索结果合并去重阶段的 URL 标准化，减少因 URL 变体导致的重复结果

5.7 SearXNG 客户端层

当前 SearXNG 调用通过手动拼接 URL 参数 + fetch 发送。以下方案可考虑：

手动封装（当前方案，合理）

SearXNG API 本身非常简单（GET /search?q=...&format=json），手动拼接完全够用。不建议引入额外的客户端库增加复杂度。如未来需要更多功能（如实例健康检查、引擎状态查询），可考虑封装一个轻量内部模块即可。

5.8 库选型总览

环节	当前方案	⭐ 推荐替代	核心收益	引入成本
HTTP 抓取	原生 fetch + 手动请求头	got-scraping	指纹模拟、Cookie管理、HTTP/2、代理	中（替换 fetch 调用）
HTML 解析（搜索引擎）	正则匹配	cheerio	CSS选择器、DOM遍历、鲁棒性	中（重写4个解析器）
文章内容提取	标签移除 + 纯文本	@mozilla/readability	自动识别正文、剥离噪声	中（需jsdom依赖）
HTML → 结构化文本	自定义 htmlToText	turndown（可选）	保留Markdown结构	低（新增转换通道）
浏览器反检测	无	puppeteer-extra-plugin-stealth	18种反检测、绕过Cloudflare	高（需适配Electron）
缓存	手写 Map LRU	lru-cache	TTL、统计、dispose回调	低（替换数据结构）
URL 归一化	简单标准化	normalize-url	去追踪参数、统一格式	低（替换标准化函数）

---

6. 优化增强路线图

本章按优先级排列可执行的优化项，每项标注预期收益、复杂度与依赖关系。

6.1 P0 — 高优先级（立即可做）

6.1.1 引入 lru-cache 替换手写缓存

• 改动范围：搜索缓存 + 浏览器回退缓存
• 工作量：小（约 2-3 小时）
• 收益：消除手写 LRU 的边界 bug 风险，获得 TTL 精确过期与统计指标
• 依赖：安装 lru-cache 包

6.1.2 引入 cheerio 重写四引擎解析器

• 改动范围：Bing/百度/搜狗/360 四个 HTML 解析函数
• 工作量：中（约 1-2 天）
• 收益：正则 → CSS 选择器，解析鲁棒性大幅提升，应对搜索引擎 HTML 变更的成本降低
• 依赖：安装 cheerio 包

6.1.3 引入 normalize-url 强化去重

• 改动范围：搜索结果合并去重的 URL 标准化步骤
• 工作量：小（约 1-2 小时）
• 收益：减少因 utm_* 参数、尾部斜杠、协议差异导致的重复结果
• 依赖：安装 normalize-url 包

6.2 P1 — 中优先级（短期规划）

6.2.1 引入 got-scraping 替换 web_fetch Phase 1

• 改动范围：web_fetch 的 HTTP 抓取阶段
• 工作量：中（约 2-3 天）
• 收益：内置指纹轮换、Cookie Jar、HTTP/2、代理支持，被反爬识别概率显著降低
• 风险：got-scraping 基于 got，需确认与 Electron 进程的兼容性；必要时可用 got 核心自行封装
• 依赖：安装 got-scraping 包

6.2.2 引入 @mozilla/readability 提升文章提取质量

• 改动范围：web_fetch 的 HTML 转文本流程，新增 readability 前置步骤
• 工作量：中（约 1-2 天）
• 收益：新闻/博客/百科类页面的提取质量质的飞跃，噪声自动剥离
• 注意事项：需处理非文章页面的 fallback（readability 返回空时回退到原有 htmlToText）
• 依赖：安装 @mozilla/readability + jsdom

6.2.3 UI 增加「连接测试」按钮

• 改动范围：SearXNG 配置模态框
• 工作量：小（约 半天）
• 收益：用户保存配置前可一键验证 URL 可达性与认证有效性，降低配置错误率
• 实现要点：向 ${url}/search?q=test&format=json 发送带认证头的测试请求，展示响应状态与耗时

6.3 P2 — 中低优先级（中期规划）

6.3.1 集成 stealth 反检测

• 改动范围：browser 模块的 BrowserWindow 创建 / browser 回退通道
• 工作量：大（约 3-5 天）
• 收益：绕过 Cloudflare 等反爬检测的概率大幅提升，减少浏览器回退触发频率
• 推荐路径：提取 stealth 插件的 JS 脚本，通过 webContents.executeJavaScript 注入 BrowserWindow
• 依赖：分析 puppeteer-extra-plugin-stealth 源码，提取各 evasions 模块

6.3.2 引入 turndown 新增 Markdown 输出模式

• 改动范围：web_fetch / browserExtract 的内容输出
• 工作量：小（约 1 天）
• 收益：AI 收到的网页内容保留结构（标题层级、表格、列表、代码块），提升理解质量
• 实现要点：新增 format: 'markdown' 参数选项，默认保持现有纯文本行为不变

6.3.3 代理支持

• 改动范围：web_fetch HTTP 抓取阶段 + SearXNG 调用
• 工作量：中（约 2-3 天）
• 收益：企业网络环境下可通过代理访问外网；高频抓取时可轮换 IP 降低封禁风险
• 实现要点：配置项新增 proxy_url / proxy_list，got-scraping 原生支持代理

6.4 P3 — 低优先级（长期规划）

6.4.1 分布式缓存后端

• 前提：P0 缓存改造完成
• 方向：使用 cacheable 或类似方案，支持 Redis / SQLite / 文件后端
• 收益：多实例部署时缓存共享，避免重复抓取

6.4.2 搜索引擎解析器热更新

• 方向：将四引擎解析规则外部化为配置文件或脚本，支持不重启生效
• 收益：搜索引擎 HTML 结构变更时无需发版，运维可快速响应

6.4.3 抓取速率自适应限速

• 方向：根据目标站点的响应时间与错误率动态调整请求间隔
• 收益：尊重目标站点，减少被封禁概率，体现负责任的抓取行为

---

附录 A：工具联动模式

四种模块在实际任务中的典型协作流程：

标准搜索流程：

web_search(query) → 分析结果 → web_fetch(topN URLs) → 综合回答

浏览器交互流程：

browser_open(url) → browser_wait(selector) → browser_extract()
→ browser_screenshot() → browser_click() / browser_type() → browser_close()

自动降级流程：

web_fetch(url) → [HTTP失败] → browser_open(url) → browser_extract() → browser_close()

SearXNG + 自动抓取流程：

web_search(query) → [SearXNG模式] → JSON结果 → 相关性过滤
→ applyAutoFetch(topN) → 逐条web_fetch() → 带全文的回答

附录 B：关键文件索引（原始实现参考）

文件	说明
electron/harness/tools/built-in/browser.ts	浏览器控制核心（9 个 action 路由）
electron/harness/tools/built-in/browser-window-manager.ts	浏览器窗口状态管理 + 页面操作（单例 + 隔离会话）
electron/harness/tools/built-in/web-search.ts	web_search 工具（SearXNG / 内置四引擎双模式）
electron/harness/tools/built-in/web-fetch.ts	web_fetch 工具（三阶段回退抓取）
electron/harness/tools/built-in/network-utils.ts	网络工具函数（LRU 缓存、UA 轮换、反爬请求头、拦截检测、HTML 转文本、SearXNG 认证）
electron/harness/tools/built-in/http-request.ts	HTTP/REST API 请求工具
electron/harness/tools/built-in/file-guard.ts	文件保护（工作空间边界 + MEMORY.md 保护）
electron/harness/tools/registry.ts	工具注册表 + PolicyEngine 策略引擎 + truncateResult
electron/harness/sandbox/permissions.ts	PolicyEngine（三级权限 + 频率限制 + 通配符策略）
electron/harness/agent-loop/engine.ts	Agent Loop 引擎（ReAct 状态机 + 工具超时配置）
electron/ipc/handlers.ts	IPC 通道处理（50+ 通道，含 searxng:testConnection）
electron/main.ts	应用生命周期（启动流程 + browserClose on quit）
src/components/settings/SettingsModal.tsx	设置面板（含 SearXNG 配置 Tab）
src/stores/agent-store.ts	Agent 状态管理（Zustand）
src/hooks/useAgentStream.ts	流式事件监听 Hook

附录 C：第三方库速查表

库名	版本建议	npm 周下载量级	许可证	引入优先级
got-scraping	最新稳定版	~500K+/周	MIT	P1
cheerio	v1.x	~10M+/周	MIT	P0
@mozilla/readability	最新版	~2M+/周	Apache-2.0	P1
jsdom	最新版	~5M+/周	MIT	P1（readability 依赖）
turndown	v7.x	~2M+/周	MIT	P2
puppeteer-extra-plugin-stealth	最新版	~500K+/周	MIT	P2
puppeteer-extra	最新版	~1M+/周	MIT	P2（stealth 依赖）
lru-cache	v10.x	~20M+/周	ISC	P0
normalize-url	最新版	~5M+/周	MIT	P0
axios	^1.7.x（锁定安全版本）	~30M+/周	MIT	备选