AgentCrawl Skill 技能

技能简介

AgentCrawl 是一款面向 AI Agent 的自托管网页抓取与内容提取工具（PyPI 包名 agentcrawl-ai，Apache-2.0 开源）。它解决一个非常具体的痛点：Agent 需要读网页时，原始 HTML 混杂导航、Cookie 提示、页脚与脚本噪音，直接塞进上下文既浪费 token 又容易污染判断。AgentCrawl 在本地架起一层"读取层"——给它一个 URL，还给 Agent 一份干净、可引用的 Markdown，并把缓存、任务与失败记录全部留在你自己的环境里。它提供 CLI、Python 库、HTTP API、Docker 和 MCP 五种接入方式，既适合个人开发者本地使用，也适合团队私有化部署。

核心能力

• 干净的正文提取：主内容抽取，输出 Markdown，保留表格、代码块、链接、元数据、JSON-LD 与来源信息（provenance）。
• HTTP 优先的抓取引擎：默认纯 HTTP 快速提取，不启动浏览器；仅当页面依赖 JavaScript 渲染时才启用可选的 Playwright 浏览器通道（[browser] 扩展），并支持 Patchright 隐身重试与代理轮换。
• 持久化抓取任务：基于 SQLite 的作业系统，带检查点、分页、取消、事件、重试与失败归因，断点可续。
• MCP Server：标准 stdio MCP 服务，默认暴露 scrape_url、scrape_many、map_site、crawl_site、extract_structured 等核心工具，配置 full 档后追加作业历史、取消、失败检查、重试、用量、缓存与变更比对等运维工具。
• 变化追踪：每个页面记录 markdown_sha256、etag、last_modified，支持条件请求与 unified diff 输出，抓取时可标记"新增 / 变更 / 未变"。
• 结构化提取（零 LLM 成本）：CSS Schema 方式确定性抽取字段，一次生成、反复复用，不消耗 token。
• 安全默认值：Bearer 鉴权、遵守 robots.txt、SSRF 防护、危险重定向拦截、私网访问控制；MCP 默认只抓远程 URL，本地文件需显式开关。

安装配置

1. pip install agentcrawl-ai 即可获得 CLI 与 Python 库；需要 MCP 时安装 pip install "agentcrawl-ai[mcp]"，需要浏览器渲染再加 [browser] 扩展并执行 python -m playwright install chromium。
2. Docker 部署：运行 ghcr.io/jorg18/agentcrawl:latest 映射 8000 端口，通过 AGENTCRAWL_API_KEYS 配置密钥，/health 健康检查；也支持 Compose 一键启动。
3. MCP 客户端接入：先执行 agentcrawl doctor 自检浏览器可用性，再执行 agentcrawl mcp 启动服务；Agent 侧若需读取本地文档目录，须显式设置 AGENTCRAWL_ALLOW_LOCAL_FILES=true 并指定根目录。
4. 环境变量按需开启：AGENTCRAWL_SEARCH_ENGINE=duckduckgo（或 serper + API Key）启用联网搜索，AGENTCRAWL_LLM_MODEL 启用摘要生成。

使用步骤

1. 安装并自检：pip install agentcrawl-ai，执行 agentcrawl doctor 确认运行环境完整。
2. 命令行快速抓取：agentcrawl scrape https://docs.python.org/3/library/json.html，直接得到正文 Markdown。
3. Python 集成：from agentcrawl import AgentCrawl，实例化后调用 scrape(url)，读取 document.markdown 与 document.metadata。
4. 接入 Agent：在 MCP 客户端中配置 agentcrawl mcp 启动项，让 Agent 直接调用 scrape_url / map_site / crawl_site 等工具读取网页。
5. 深度抓取：用 crawl 配合 query 做自适应爬取（优先访问最相关链接，连续不相关即停止），或用 extract_structured 做字段级提取。
6. 私有化服务：Docker 启动 HTTP API 后，用 agentcrawl dashboard 或 /dashboard 查看只读运行面板。

适用场景

1. Agent 联网读文档：让编码 Agent 直接读官方文档、Stack Overflow、GitHub 页面，替代把原始 HTML 粘进对话。
2. 知识库灌库：批量抓取站点内容并输出带引用链接的可分块（chunks）文本，供 RAG 检索使用。
3. 竞品与舆情监控：持久化抓取任务 + 变化追踪，定期 diff 关键页面并通知变更。
4. 结构化数据采集：用 CSS Schema 确定性提取表格、列表字段，零 token 成本。
5. 框架集成：内置 LangChain AgentCrawlLoader 与 LlamaIndex AgentCrawlReader，并提供 Firecrawl 兼容的 /v2 API，可直接替换现有服务。

适用人群

AI 应用开发者、Agent 平台搭建者、RAG 知识库工程师、需要私有化数据抓取能力的数据团队，以及希望给编码 Agent 配一个"可控网页阅读器"的个人开发者。

工作原理

AgentCrawl 采用"HTTP 优先、浏览器兜底"的双通道抓取架构。请求进入后先走轻量 HTTP 通道完成下载与正文抽取；命中 JS 渲染页面时回退到本地 Playwright 浏览器，浏览器以真实 Chrome 身份出现，对自清除的验证（如 Cloudflare "Just a moment…"）按人的方式等待通过，遇到必须人工解的 CAPTCHA 则返回结构化的 client_challenge 错误与建议动作，绝不把拦截页伪装成内容。抓取结果统一转为 Markdown 并落库 SQLite（缓存、作业、事件、用量），上层通过 CLI / Python / API / MCP 四种接口暴露，所有状态默认留在本地，实现"自托管信任层"。

官方链接

• PyPI：https://pypi.org/project/agentcrawl-ai/
• GitHub：https://github.com/JorG18/agentcrawl