名称: documentation-scraper 描述: 在需要将文档网站爬取为markdown以供AI上下文使用时触发。在“scrape docs”、“download documentation”、“get docs for [library]”或创建在线文档的本地副本时触发。关键 - 始终在爬取前先分析站点地图。
文档爬虫与slurp-ai
概述
slurp-ai爬取文档网站并将其编译为单个markdown文件，优化用于AI代理上下文。它轻量、快速且确定性 - 不使用AI来爬取，而是供AI消费。
关键：在沙箱外运行
此技能中的所有命令必须在沙箱外运行。 对所有Bash命令使用 dangerouslyDisableSandbox: true，包括：
which slurp（安装检查）node analyze-sitemap.js（站点地图分析）slurp（爬取）- 文件检查命令（
wc、head、cat等）
沙箱会阻止网络访问和文件操作，这些是网络爬取所必需的。
预检：检查安装
爬取前，验证slurp-ai是否已安装：
which slurp || echo "未安装"
如果未安装，请用户运行：
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：解释输出
示例输出：
📊 站点地图中的总URL：247
📁 按顶级部分分组的URL：
/docs 182 页
/api 45 页
/blog 20 页
🎯 建议的 --base-path 选项：
https://docs.example.com/docs/guides/ (67 页)
https://docs.example.com/docs/reference/ (52 页)
https://docs.example.com/api/ (45 页)
💡 推荐的slurp命令：
# 仅 "/docs/guides" 部分 (67 页)
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命令
使用站点地图数据，您现在可以设置准确的参数：
# 从站点地图：/docs/api 有 45 页
slurp https://docs.example.com/docs/api/intro \
--base-path https://docs.example.com/docs/api/ \
--max 55
关键见解： 起始URL是爬虫开始的地方。基础路径过滤哪些链接被跟踪。它们可以不同（当基础路径本身返回404时有用）。
常见爬取模式
库文档（版本化）
# Express.js 4.x 文档
slurp https://expressjs.com/en/4x/api.html --base-path https://expressjs.com/en/4x/
# React 文档（最新）
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/ # 中间文件
└── page1.md
└── page2.md
slurp_compiled/ # 最终输出
└── compiled_docs.md # 编译结果
快速参考
# 1. 始终先分析站点地图
node analyze-sitemap.js https://docs.example.com
# 2. 使用基于站点地图分析的参数爬取
slurp https://docs.example.com/docs/ --base-path https://docs.example.com/docs/ --max 80
# 3. 跳过提示以自动化
slurp https://docs.example.com/ --yes
# 4. 检查输出
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上下文注入：
# 检查文件大小（上下文预算）
wc -c slurp_compiled/compiled_docs.md
# 预览结构
grep "^#" slurp_compiled/compiled_docs.md | head -30
# 与Claude Code一起使用 - 在提示中引用或通过@file
何时不使用
- OpenAPI/Swagger中的API规范：改用专用解析器
- GitHub READMEs：通过raw.githubusercontent.com直接获取
- npm包文档：通常更好地阅读源代码+README
- 频繁更新的文档：考虑缓存策略