documentation-scraper

使用 slurp-ai 抓取文档

概览

slurp-ai 会抓取文档网站，并将其编译为一个针对 AI Agent 上下文优化的 Markdown 文件。它轻量、快速且结果确定——它不会使用 AI 进行抓取，而是供 AI 使用。

重要：在沙盒外运行

本技能中的所有命令都必须在沙盒外运行。 所有 Bash 命令均需使用 dangerouslyDisableSandbox: true，包括：

• which slurp（安装检查）
• node analyze-sitemap.js（站点地图分析）
• slurp（抓取）
• 文件检查命令（wc、head、cat 等）

沙盒会阻止网页抓取所需的网络访问和文件操作。

准备工作：检查安装情况

抓取前，请确认已安装 slurp-ai：

which slurp || echo "NOT INSTALLED"

如果尚未安装，请让用户运行：

npm install -g slurp-ai

要求： Node.js v20+

确认已安装 slurp-ai 之前，请勿继续抓取。

命令

命令	用途
slurp <url>	一步完成抓取和编译
slurp fetch <url> [version]	仅将文档下载到分片文件
slurp compile	将分片文件编译为单个文件
slurp read <package> [version]	读取本地文档

输出： 根据 slurp_partials/ 中的分片文件创建 slurp_compiled/compiled_docs.md。

重要：先分析站点地图

运行 slurp 之前，务必先分析站点地图。 这会显示完整的网站结构，帮助你确定 --base-path 和 --max 的设置。

步骤 1：运行站点地图分析

使用随附的 analyze-sitemap.js 脚本：

node analyze-sitemap.js https://docs.example.com

输出内容包括：

• 页面总数（用于确定 --max）
• 按章节分组的 URL（用于确定 --base-path）
• 带有适当标志的建议 slurp 命令
• 用于了解命名模式的示例 URL

步骤 2：解读输出

输出示例：

📊 Total URLs in sitemap: 247

📁 URLs by top-level section:
   /docs                          182 pages
   /api                            45 pages
   /blog                           20 pages

🎯 Suggested --base-path options:
   https://docs.example.com/docs/guides/     (67 pages)
   https://docs.example.com/docs/reference/  (52 pages)
   https://docs.example.com/api/             (45 pages)

💡 Recommended slurp commands:

   # Just "/docs/guides" section (67 pages)
   slurp https://docs.example.com/docs/guides/ --base-path https://docs.example.com/docs/guides/ --max 80

步骤 3：根据分析结果选择范围

站点地图显示	操作
总页数 < 50	抓取整个网站：slurp <url> --max 60
50-200 页	使用 --base-path 将范围限定到相关章节
200 页以上	必须缩小范围——选择特定子章节
未找到站点地图	从 --max 30 开始，检查分片文件并调整

步骤 4：构建 Slurp 命令

有了站点地图数据后，就可以设置准确的参数：

# From sitemap: /docs/api has 45 pages
slurp https://docs.example.com/docs/api/intro \
  --base-path https://docs.example.com/docs/api/ \
  --max 55

关键要点： 起始 URL 是开始爬取的位置。基础路径用于筛选要继续访问的链接。二者可以不同（当基础路径本身返回 404 时很有用）。

常见抓取模式

库文档（有版本）

# Express.js 4.x docs
slurp https://expressjs.com/en/4x/api.html --base-path https://expressjs.com/en/4x/

# React docs (latest)
slurp https://react.dev/learn --base-path https://react.dev/learn

仅 API 参考

slurp https://docs.example.com/api/introduction --base-path https://docs.example.com/api/

完整文档网站

slurp https://docs.example.com/

CLI 选项

标志	默认值	用途
--max <n>	20	抓取的最大页面数
--concurrency <n>	5	并行页面请求数
--headless <bool>	true	使用无头浏览器
--base-path <url>	起始 URL	将链接筛选为此前缀下的链接
--output <dir>	./slurp_partials	分片文件的输出目录
--retry-count <n>	3	请求失败时的重试次数
--retry-delay <ms>	1000	重试间隔
--yes	-	跳过确认提示

编译选项

标志	默认值	用途
--input <dir>	./slurp_partials	输入目录
--output <file>	./slurp_compiled/compiled_docs.md	输出文件
--preserve-metadata	true	保留元数据块
--remove-navigation	true	移除导航元素
--remove-duplicates	true	删除重复内容
--exclude <json>	-	要排除的正则表达式模式的 JSON 数组

何时禁用无头模式

以下情况使用 --headless false：

• 静态 HTML 文档网站
• 无需 JS 渲染时，可加快抓取速度

默认启用无头模式（true）——适用于大多数现代文档网站，包括 SPA。

输出结构

slurp_partials/              # Intermediate files
  └── page1.md
  └── page2.md
slurp_compiled/              # Final output
  └── compiled_docs.md       # Compiled result

快速参考

# 1. ALWAYS analyze sitemap first
node analyze-sitemap.js https://docs.example.com

# 2. Scrape with informed parameters (from sitemap analysis)
slurp https://docs.example.com/docs/ --base-path https://docs.example.com/docs/ --max 80

# 3. Skip prompts for automation
slurp https://docs.example.com/ --yes

# 4. Check output
cat slurp_compiled/compiled_docs.md | head -100

常见问题

问题	原因	解决方案
--max 值错误	猜测页面数量	先运行 analyze-sitemap.js
抓取的页面太少	--max 限制（默认值为 20）	根据站点地图分析设置 --max
内容缺失	JS 未渲染	确保设置 --headless true（默认值）
爬取卡住或速度慢	速率限制	降低 --concurrency 3
章节重复	内容相似	使用 --remove-duplicates（默认值）
包含了错误的页面	基础路径范围太宽	使用站点地图查找正确的 --base-path
提示阻止自动化	交互模式	添加 --yes 标志

抓取后的用法

输出的 Markdown 专为注入 AI 上下文而设计：

# Check file size (context budget)
wc -c slurp_compiled/compiled_docs.md

# Preview structure
grep "^#" slurp_compiled/compiled_docs.md | head -30

# Use with Claude Code - reference in prompt or via @file

不适用的场景

• OpenAPI/Swagger API 规范：改用专用解析器
• GitHub README：直接通过 raw.githubusercontent.com 获取
• npm 包文档：通常更适合阅读源码和 README
• 频繁更新的文档：考虑缓存策略