browser-search — Agent 的自托管联网技能

项目	内容
仓库	Johell1NS/browser-search
许可证	MIT
技术栈	Node.js ≥ 20 · Docker · SearXNG · Camofox · CloakBrowser
我的角色	贡献者（健康检查与依赖修复已合入）
文档	English · 简体中文

---

这是什么

browser-search 是给 AI Agent 用的 Skill：让代理能搜索网页、打开页面、在被反爬拦下时自动升级工具——全部自托管，不买搜索 / 抓取 API。

它刻意把「模型说自然语言」和「真正执行」拆开：

• Skill（SKILL.md）用自然语言告诉模型何时用哪把工具
• 实际动作只允许跑仓库里写死的确定性脚本

这样最便宜的模型也不容易编命令、编结果——抗幻觉是结构保证，不是 prompt 口号。

典型搭载环境：OpenCode、Claude Code、Cursor、OpenClaw 等；逻辑通用，换宿主主要是 Skill 安装方式不同。

---

为什么需要三级，而不是一个 Playwright

多数 Agent 联网工具停在墙前：Cloudflare / Akamai 一出挑战就返回 blocked，任务结束。browser-search 的设计是层层升级：

层级	工具	角色	大致成本
1	SearXNG（Docker :8080）	多源元搜索，拿 URL / 摘要	毫秒级
2	Camofox（Docker :9377）	Firefox + REST：点击、JS、Readability 抽正文	冷启 1–3s，之后近即时
3	CloakBrowser（npm）	隐身 Chromium：反指纹、过挑战、代理 / GeoIP	按需启动，更重

流程：

用户问题
   → SearXNG 多角度搜 URL
   → smart-extract / Camofox 抽正文
   → 若被挑战拦截 → CloakBrowser
   → 交叉验证后再回答（Deep Research）

Camofox 覆盖大部分「普通站」；CloakBrowser 留给那一小撮硬骨头。速度与隐身做成显式权衡，而不是一个万能浏览器硬扛所有流量。

---

抗幻觉：Deep Research 规则在管什么

Skill 激活后，核心约束包括：

1. 先搜后答 — 事实主张必须对着线上来源核
2. 多角度交叉 — 同一问题换查询、换来源，不单点定论
3. 时效敏感题用时间窗 — SearXNG --time-range（day / week / month / year）
4. 只跑文档里的命令 — 禁止临场拼 ad-hoc 脚本
5. 默认只读 — 脚本只发 HTTP；截图写 PNG 是少数例外
6. 社交登录墙不硬闯 — Instagram / Facebook / TikTok / LinkedIn / X 等，摘要够用就跳过

「模型可以描述工具，但不能自由发明执行路径」——这是这个项目最值得抄的一点。

---

常用命令（摘录）

完整参数以仓库 SKILL.md 为准。Skill 目录记为 <skill_dir>。

搜索

node <skill_dir>/scripts/searxng/searxng.mjs search "your query"
node <skill_dir>/scripts/searxng/searxng.mjs search "your query" --lang zh --time-range month
node <skill_dir>/scripts/searxng/searxng.mjs search --query "q1" --query "q2"   # 串行，间隔约 3s
node <skill_dir>/scripts/searxng/searxng.mjs health

需要限制引擎时再用 --engines，例如 --engines google,wikipedia（默认搜全部已启用引擎）。相关讨论：Issue #6。

抽正文 / 浏览

node <skill_dir>/scripts/smart-extract.mjs "https://example.com"
node <skill_dir>/scripts/camofox/camofox.mjs readability "https://example.com"
node <skill_dir>/scripts/camofox/camofox.mjs evaluate "https://example.com" "document.title"

过硬防护

node <skill_dir>/scripts/cloak/cloak-fetch.mjs "https://protected-site.com"
node <skill_dir>/scripts/cloak/cloak-fetch.mjs "https://example.com" --format markdown

CloakBrowser 依赖需在 skill 目录执行 npm install / bash scripts/setup.sh，不要假设 npx skills add 会装好二进制。

---

部署要点（踩坑向）

1. SearXNG / Camofox 先用 Docker 拉起来，再跑 Agent；否则健康检查会红一片。
2. 本机绑定：文档推荐 SEARXNG_HOST=127.0.0.1，避免搜索引擎误暴露到局域网。
3. Camofox 镜像用官方 ghcr.io/jo-inc/camofox-browser，别抄过期示例。
4. 健康检查要测 HTTP API，不能只看容器名是否存在——容器在但端口挂了，旧检查会假绿。
5. CloakBrowser 二进制路径因版本而异（如 ~/.cloakbrowser）；检查脚本要用 ESM import，不要假设 CommonJS require 一定可用。

官方 FAQ / Docker 说明见仓库 FAQ.md 与 docker/setup.md。

---

我贡献了什么

#4 fix: health check false negatives and update CloakBrowser

合入时间：2026-07-07。主要改动：

改动	原因
check.sh 优先用 HTTP API 探测 SearXNG / Camofox	避免「容器在、服务挂」仍判健康
修正 ~/.cloakbrowser 下 Chromium 二进制探测	新版本布局导致假阴性
CloakBrowser 包检测改为 ESM import	与包导出方式一致
文档改用官方 Camofox 镜像，并写明 SEARXNG_HOST=127.0.0.1	安装路径可复现、默认更安全
cloak-fetch 默认 format 与真实输出对齐	减少「脚本说 markdown、实际是 text」的错位
CloakBrowser 0.3.31 → 0.4.8	跟上上游能力与修复

另有使用反馈与文档建议：

• Issue #5 — 架构讨论与上手体验
• Issue #6 — SearXNG 示例里 engines= 的推荐写法

---

适合什么场景

• 要给 Agent 稳定、可复现的联网研究能力，又不想绑商业 Search API
• 需要在 自建机器 / 树莓派级硬件上跑 24×7 的轻量栈
• 研究流程要求 可审计：搜了什么、打开了什么、何时升级到隐身浏览器

不适合：需要登录态的社交平台深扒、或把「绕过站点防护」用在未授权目标上——技术栈能做到，不等于可以乱用。

---

相关链接

• GitHub
• Releases
• Discussions
• PR #4
• 同栏目：Adnify