web-search

网页搜索与抓取

你有三个用于访问网页的工具。根据任务需求组合使用。

工具组合

SearXNG — 搜索引擎

本地元搜索引擎，聚合了 25 个以上的搜索引擎（Google、Bing、DuckDuckGo、Brave 等）。不跟踪用户，无速率限制，提供 JSON API。

# Basic search
curl -s "http://localhost:8888/search?q=QUERY&format=json" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for r in data.get('results', [])[:10]:
    print(r.get('title', ''))
    print(r.get('url', ''))
    print(r.get('content', '')[:200])
    print()
"

按类别搜索 — 添加 &categories=，可选类别：general、news、images、files、science、it、music、videos

# News search
curl -s "http://localhost:8888/search?q=QUERY&format=json&categories=news"

# Multiple categories
curl -s "http://localhost:8888/search?q=QUERY&format=json&categories=science,it"

翻页 — 添加 &pageno=2（或 3、4 等）获取更多结果。

Lightpanda — 快速无头抓取

使用 Zig 构建。速度比 Chrome 快 10 倍，占用内存极少。抓取网页内容时默认使用此工具。

# Fetch as markdown (best for reading/summarizing)
lightpanda fetch --dump markdown https://example.com

# Fetch as HTML (when you need structure)
lightpanda fetch --dump html https://example.com

# Semantic tree (useful for understanding page layout)
lightpanda fetch --dump semantic_tree https://example.com

# Strip unnecessary elements
lightpanda fetch --dump markdown --strip_mode js,css https://example.com

# Include iframe content
lightpanda fetch --dump markdown --with_frames https://example.com

Agent-Browser — 完整的浏览器自动化

基于 Playwright。遇到 Lightpanda 无法处理的页面时使用（JavaScript 密集型 SPA、需要登录的页面、动态内容、表单交互）。

# Open and snapshot
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot -i

# Get text content
agent-browser get text body

# Interact with elements
agent-browser fill @e1 "search query"
agent-browser click @e2

# Screenshot for visual inspection
agent-browser screenshot --annotate

# Always close when done
agent-browser close

选择指南

需要查找内容？ → 首选 SearXNG。始终如此。

需要网页内容？ → 使用 Lightpanda。它速度快，返回简洁的 Markdown，并能处理 90% 的网页。

Lightpanda 返回的内容杂乱或为空？ → 页面可能需要 JavaScript 才能呈现。改用 Agent-Browser。

需要登录、填写表单或完成一系列点击操作？ → 使用 Agent-Browser。保存身份验证状态以便重复使用：

agent-browser state save auth.json
# Later:
agent-browser state load auth.json

web-search CLI

此外，还有一个整合后的 CLI，位于 ~/.agents/tools/web-search（也可通过 PATH 使用 web-search），可串联使用这些工具：

# Search only
web-search "hospice compliance CMS 2026"

# Search + scrape top results
web-search "hospice compliance CMS 2026" --scrape -n 3

# Fetch a single URL
web-search --fetch https://example.com

# Use Agent-Browser for JS-heavy pages
web-search --fetch https://spa-app.com --browser

# News search + scrape
web-search "CMS hospice updates" --categories news --scrape

常见模式

研究某个主题

# 1. Search
curl -s "http://localhost:8888/search?q=topic+here&format=json" > /tmp/results.json

# 2. Review results, pick the best URLs

# 3. Fetch the good ones
lightpanda fetch --dump markdown https://good-result.com

获取最新或突发信息

# News category + recent results
curl -s "http://localhost:8888/search?q=topic&format=json&categories=news"

深度抓取多个页面

# Search, extract URLs, fetch each
curl -s "http://localhost:8888/search?q=topic&format=json" | \
  python3 -c "import json,sys; [print(r['url']) for r in json.load(sys.stdin)['results'][:5]]" | \
  while read url; do
    echo "=== $url ==="
    lightpanda fetch --dump markdown "$url" 2>/dev/null
  done

处理难以抓取的 JavaScript 密集型页面

# Lightpanda returned nothing useful? Switch to agent-browser
agent-browser open https://stubborn-spa.com
agent-browser wait --load networkidle
agent-browser get text body > /tmp/page-content.txt
agent-browser close

重要说明

• SearXNG 运行于 http://localhost:8888。如果服务未运行，请检查：docker ps | grep searxng，并使用 docker start searxng 重启
• Lightpanda 位于 /opt/homebrew/bin/lightpanda
• Agent-Browser 位于 /opt/homebrew/bin/agent-browser（v0.21.1）
• web-search CLI 位于 ~/.agents/tools/web-search，并链接到 /opt/homebrew/bin/web-search
• SearXNG 返回结果时，content 字段包含摘要 — 通常无需抓取完整页面，就足以回答简单的事实性问题
• 如需在 curl 中对 URL 进行编码，请使用 python：python3 -c "import urllib.parse; print(urllib.parse.quote('my query'))"

附带资源

此技能包含重建或排查工具组合所需的一切：

• scripts/web-search — 整合后的 CLI 脚本（也安装在 ~/.agents/tools/web-search）
• references/infrastructure.md — 完整的基础设施文档：二进制文件位置、SearXNG API 参考、容器管理、OrbStack 设置和故障排除指南。如果出现问题或需要重新配置，请阅读此文档。
• references/searxng-settings.yml — SearXNG 配置（引擎、格式、API 设置）。编辑后复制到 ~/.agents/searxng/config/settings.yml，然后运行 docker restart searxng 以应用更改。

相关技能

• [[agent-browser]] — 用于 JavaScript 密集型页面和表单交互的完整浏览器自动化
• [[human-browser]] — 使用住宅代理隐匿浏览，访问受机器人防护的网站
• [[seo]] — 与网络研究相辅相成的 SEO 审核与优化