名称: 文档抓取器 描述: 当需要将文档网站抓取为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
- 频繁更新的文档：考虑缓存策略