web-fetch

网页抓取

通过 Chrome DevTools Protocol (CDP) 控制无头 Chrome 实例，抓取网页并完整渲染 JavaScript。支持处理 JS 重定向、SPA 和动态内容，并从任意 URL 提取干净的文本。

前提条件

• Google Chrome 或 Chromium：系统上必须已安装。
  • macOS：brew install --cask google-chrome
  • Ubuntu/Debian：sudo apt install google-chrome-stable
  • Windows：winget install Google.Chrome
• Python 3：仅使用标准库，不依赖 pip。可选安装 trafilatura 以改进内容提取效果。
• 无需 API 密钥或令牌。

用法

单个 URL

python <skill-path>/scripts/web_fetch.py --url "https://example.com/article"

多个 URL（单个 Chrome 会话，更高效）

python <skill-path>/scripts/web_fetch.py --url "https://example.com/a" --url "https://example.com/b"

管道输入（每行一个 URL）

echo "https://example.com/article" | python <skill-path>/scripts/web_fetch.py

将 JSON 输出到文件（建议用于多个 URL）

# Cross-platform temp dir
TMPDIR=$(python -c "import tempfile; print(tempfile.gettempdir())")
python <skill-path>/scripts/web_fetch.py --url "https://example.com" --format json -o "$TMPDIR/results.json"

选项

标志	默认值	描述
--url	—	要抓取的 URL（可重复指定）
--format	text	输出格式：text 或 json
-o, --output	stdout	输出到文件而非标准输出（大型结果建议使用此选项）
--wait-ms	1500	JS 渲染等待时间，单位为毫秒
--timeout	15	每个 URL 的超时时间，单位为秒
--max-chars	15000	每个页面的最大字符数
--batch-size	3	每批 URL 数量（为提高稳定性，批次之间会重启 Chrome）
--port	auto	CDP 调试端口（默认：自动检测可用端口）

输出

文本模式（默认）

每个 URL 的纯文本内容，以 --- 分隔。

JSON 模式

[
  {
    "url": "https://news.google.com/rss/articles/...",
    "final_url": "https://www.theguardian.com/actual-article",
    "success": true,
    "content": "Article text content..."
  }
]

失败时：

[
  {
    "url": "https://example.com/broken",
    "success": false,
    "error": "Page load timeout"
  }
]

工作原理

1. 查找 Chrome — 检查平台专属路径，然后搜索 PATH
2. 启动隔离的 Chrome — --headless=new --remote-debugging-port=PORT --user-data-dir=TMPDIR（不会与正在运行的 Chrome 冲突）
3. 通过 CDP 控制 — 使用纯 Python CDP 客户端通过 WebSocket 连接（无依赖）
4. 导航并等待 — 使用 Page.navigate，监听 loadEventFired，然后等待 JS 渲染
5. 捕获内容 — 通过 Runtime.evaluate 获取最终 URL，通过 DOM.getOuterHTML 提取 DOM
6. 提取文本 — 使用 trafilatura（如果已安装），否则回退到剥离 HTML 标签
7. 清理 — 终止 Chrome 并移除临时配置文件

主要优势

• 无配置文件冲突 — 使用隔离的 --user-data-dir，可与正在运行的 Chrome 并行使用
• 支持 JS 重定向 — Google News、URL 缩短服务和 SPA 路由均可正常处理
• 零依赖 — 纯 Python 3 标准库（包含 WebSocket 客户端）
• 单个 Chrome 会话 — 多个 URL 复用同一个实例（速度快）
• 跨平台 — Mac、Windows、Linux

跨平台支持

平台	检查的 Chrome 路径
macOS	/Applications/Google Chrome.app/...、Chromium.app
Linux	/usr/bin/google-chrome、chromium、snap chromium
Windows	%ProgramFiles%\Google\Chrome\...、%LocalAppData%\...

在所有平台上，如果未找到，还会搜索 PATH。

说明

• 无需配置 — 只需安装 Chrome。无需启用“远程调试”或更改任何 Chrome 设置，脚本会自动处理所有操作。
• macOS 首次运行 — 系统可能会弹出提示：“是否允许应用程序 Google Chrome 接受传入的网络连接？”点击 允许。这是因为 CDP 使用本地端口（127.0.0.1），不会产生外部网络流量。