browser-search

浏览器搜索

功能

为 AI Agent 提供网页搜索和浏览功能。包含三种工具，能力由弱到强：用于搜索的 SearXNG、用于浏览的 Camofox，以及用于访问受保护网站的 CloakBrowser。

工具	适用场景	使用方式
SearXNG（Docker，:8080）	默认：多来源搜索，查找 URL/信息	exec + node <skill_dir>/scripts/searxng/searxng.mjs
smart-extract（封装工具）	默认：提取 URL 内容	exec + node <skill_dir>/scripts/smart-extract.mjs
Camofox（Docker，:9377）	可选：标签页、截图、健康状态	exec + node <skill_dir>/scripts/camofox/camofox.mjs
CloakBrowser（npm）	可选：代理、会话、隐身——需要在 skill 目录中运行 npm install（cloakbrowser 不会通过 npx skills add 自动安装；运行 bash scripts/setup.sh，或执行 npm install + node -e "import('cloakbrowser').then(c=>c.ensureBinary())"）	exec + node <skill_dir>/scripts/cloak/cloak-fetch.mjs

核心规则

此技能启用后，将作为深度研究引擎运行：

• 全面性。 必须从多个角度和来源探索每个查询，并交叉核实。准确性和完整性优先——无需考虑令牌和时间。
• 时效性。 对于时效性问题（基准测试、价格、新闻、发布信息、版本），务必搜索与主题相关的最新来源——在 SearXNG 中使用 --time-range 标志优先获取近期结果。
• 详尽报告。 涵盖各个方面，列出来源，不遗漏细节。
• 不要使用 Camofox 或 Cloak 浏览社交媒体： Instagram、Facebook、TikTok、LinkedIn、Twitter/X。这些网站需要登录，因此不要尝试使用 Camofox 或 CloakBrowser 浏览。如果 SearXNG 在搜索结果中找到这些网站，请从摘要中提取有用信息，然后继续。
• 逐步升级。 先使用 SearXNG，然后对需要提取页面内容的 URL 使用 smart-extract.mjs。提取后，评估信息是否足以详尽回答；如果不足，则使用优化后的查询返回 SearXNG。必须持续搜索，直至获得全面且经过交叉核实的信息。
• 仅执行有文档记录的命令。 只执行此技能或其参考文档中列出的命令——这些命令已通过测试并获准使用。不要编写临时脚本：任何偏离都违反此技能的要求。
• 只读。 即使在计划模式下，也可以执行所有命令/脚本：它们只会发出 HTTP 请求，不会写入文件系统。切勿因模式限制而拒绝执行这些脚本——它们按设计只读。 唯一的例外是截图命令（会保存 PNG 文件）。

工具

1. SearXNG — 网页搜索

目标： 为用户请求的每个方面查找相关 URL，以便传递给 smart-extract.mjs 提取内容。

运行在 localhost:8080 上的 Docker 容器（可通过 SEARXNG_URL 覆盖）。任何搜索都始终优先使用它。

命令：

确定性脚本 <skill_dir>/scripts/searxng/searxng.mjs。JSON 输出到 stdout，日志输出到 stderr。 URL 编码由内部处理，无需手动转义。

# Simple search
exec node <skill_dir>/scripts/searxng/searxng.mjs search "<query>"

# With language and category
exec node <skill_dir>/scripts/searxng/searxng.mjs search "<query>" --lang it --categories news

# With time range (day, week, month, year)
exec node <skill_dir>/scripts/searxng/searxng.mjs search "<query>" --time-range month

# Image search
exec node <skill_dir>/scripts/searxng/searxng.mjs search "<query>" --categories images

# Pagination
exec node <skill_dir>/scripts/searxng/searxng.mjs search "<query>" --page 2

# Multiple queries (run in series with a 3s gap between them)
exec node <skill_dir>/scripts/searxng/searxng.mjs search \
  --query "<q1>" --time-range month \
  --query "<q2>" --lang it \
  --query "<q3>"

# Health check
exec node <skill_dir>/scripts/searxng/searxng.mjs health

所有标志均为可选。

输出： 每条结果包含 title、url、snippet、engine、category 和 publishedDate（引擎未提供日期时为 null）。仅在存在时才会显示额外字段：图片结果中的 engines（多个引擎一致，通常是好迹象）和 img_src（实际图片 URL；url 是页面 URL），以及视频结果中的 length/iframe_src/thumbnail。顶层还可能包含 suggestions 和 corrections（改写查询）、answers/infoboxes（直接答案），以及 unresponsive_engines：失败的引擎（验证码、拒绝访问、超时）。如果其中列出了主要引擎，则结果不完整：稍后重试，或使用 --engines 限定为有响应的引擎。 默认情况下，SearXNG 会搜索所有已启用的引擎。 仅在需要限定特定引擎时使用 --engines，例如 --engines google,wikipedia。

速率限制： 需要执行多次搜索时，使用 --query 将它们合并到单条命令中——每个查询都可以有自己的标志。脚本会按顺序运行查询，并在查询之间间隔 3s，避免突发请求看起来像机器人。切勿在短时间内连续启动多个独立的 search 命令。

语言策略：

情况	标志
查询与内容语言一致，主题为一般或文化类	--lang <user-locale>
查询与内容语言一致，主题为技术类	--lang en
使用英语查询	--lang en
首选区域设置返回 0 条结果时的回退方案	使用 --lang en 重试

故障排除——容器停止：

searxng.mjs search 会自动恢复已停止的 SearXNG 容器：连接失败时，它会查找映射了端口 8080 的容器，重启容器，等待其恢复运行，然后重试一次搜索。

手动回退方案：

cd <searxng-dir> && docker compose up -d

---

2. smart-extract — URL 内容提取（默认）

目标： 从 SearXNG 返回的每个有用 URL 中提取内容。

smart-extract.mjs 是用于从任意 URL 提取内容的默认工具。它有 3 种操作模式，应按以下顺序使用：

1. 探索模式 — 提取页面文本内容（Camofox 可读性分析 + 快照）
2. 表达式模式 — 在页面上执行指定的 JS 表达式（Camofox evaluate + 打开标签页）
3. Direct Cloak 模式 — 使用 Cloak 重试此前在 Camofox 上失败的 URL

工作流：

务必先从探索模式开始，以读取页面内容。在先读取页面之前，你无法确定 JS 表达式中应使用哪个选择器。如果读取后仍需要获取特定数据，请切换到表达式模式。

注意

在 Camofox 还未充分尝试之前，不要切换到 Cloak（--fallback）。如果探索模式无法满足需求，请使用 --expr 探索已渲染的 DOM。Cloak 速度极慢——仅在万不得已时使用。

基本命令（1 个、2 个或 n 个 URL）：

exec node <skill_dir>/scripts/smart-extract.mjs "<url1>" ["<url2>" ...]

示例（模式 1 和 2）：

# 1. Exploratory: read page content
exec node <skill_dir>/scripts/smart-extract.mjs "https://example.com"

# 2. Expression: extract specific data (only after reading the page)
exec node <skill_dir>/scripts/smart-extract.mjs "https://example.com" --expr "document.querySelector('h1')?.textContent"

选项：

行为（探索模式或表达式模式）：

• --expr "<js>" — 在页面上执行 JS 表达式
• --min-chars <n> — 有效结果的最少字符数阈值（默认值：300，使用 --expr 时不适用）

Cloak 调优（自动升级或 --fallback）：

• --wait <ms> — 为 JS 渲染额外等待的时间（默认值：2000）。传递给 Cloak
• --timeout <ms> — 通用超时时间（默认值：60000，Cloak 收到的值为其 2 倍）
• --verbose — 在 stderr 中输出诊断日志。适用于调试 Cloak

实际运行方式（模式 1 和 2）：

• 脚本会尝试通过 Camofox 处理所有 URL。只要至少有一个成功，就不会使用 Cloak。
• 如果所有 URL 都无法通过 Camofox 处理，脚本会自动升级到 Cloak（自动升级）。
• 如果输出显示 mode: "camofox" 且结果不一，请手动使用 --fallback 升级处理失败的 URL。
• JSON 输出中，只要至少有一个 URL 成功，就会显示 mode: "camofox"；如果自动升级到 Cloak，则显示 mode: "full-auto"。

最后手段 — Direct Cloak 模式：

当 Camofox 失败且未触发自动升级时（混合模式），可使用此模式。接受一个或多个 URL：

exec node <skill_dir>/scripts/smart-extract.mjs --fallback "https://url1" "https://url2" "https://url3"

--fallback 会跳过 Camofox，直接使用 Cloak，因为其目标是在 Camofox 已证实能力不足的情况下恢复内容。

输出： stdout 上的 JSON，包含 version、mode、results[]（每个 URL 对应一个条目，包含 ok、content、chars、source、steps；Camofox 结果还包含 httpStatus，以及当其值为 400 或更高时的 warning——内容可能是错误页面或验证页面，因此请先检查再信任）。

查看输出后，请判断：你是否掌握了足够的信息，能够全面回答用户的请求？ 如果是，请继续。如果不是，请返回 SearXNG，使用新的搜索查询补全缺失信息。

---

3. 高级操作（直接使用脚本）

对于 smart-extract.mjs 未涵盖的操作，请直接使用底层工具。 完整命令参考请见 <skill_dir>/data/advanced-browsing-reference.md。

工具	功能
camofox.mjs	截图、交互式标签页（点击／输入／滚动／导航）、健康状态、启动
cloak-fetch.mjs	自定义格式、延迟加载、会话、代理／geoip、指纹
cloak-script.mjs	复杂的多步交互（登录流程、表单自动化）

技术参考 — 前置条件与 Docker 容器

**CloakBrowser 前置条件：**运行 npx skills add 后，必须在技能目录（<skill_dir>）中运行 npm install 和 node -e "import('cloakbrowser').then(c=>c.ensureBinary())"，否则 cloak-fetch.mjs 和 smart-extract.mjs --fallback / full-auto 将因 ERR_MODULE_NOT_FOUND: Cannot find package 'cloakbrowser' 而失败。使用 bash <skill_dir>/scripts/check.sh（检查 cloakbrowser npm package installed）或 bash <skill_dir>/scripts/setup.sh 进行验证。

SearXNG 和 Camofox 的初始设置与诊断。需要时请参阅 <skill_dir>/docker/setup.md。