内容
# AgentCrawl
[](https://github.com/JorG18/agentcrawl/actions/workflows/ci.yml)
[](https://pypi.org/project/agentcrawl-ai/)
[](LICENSE)
🕷️ **一个用于 AI 代理的小型自托管爬虫。**
AgentCrawl 为代理提供了一种简单的方式来读取普通的网页，而无需将原始 HTML 粘贴到聊天中或将每个 URL 通过托管的爬虫路由。它将页面和本地文档转换为 Markdown、文本、链接、元数据、JSON-LD 和爬虫结果。它可以从 CLI、Python、Docker/API 或作为 MCP 服务器运行。
该项目仍处于早期阶段，但正在稳步开发：首先是可访问的页面，然后是干净的输出、本地状态和诚实的失败。
```bash
pip install agentcrawl-ai
agentcrawl scrape https://pypi.org/project/agentcrawl-ai/
```
### 边缘情况：`example.com` 返回 Cloudflare 客户端挑战
```bash
$ agentcrawl scrape https://example.com
# → ok=False, error_type=client_challenge
```
`example.com` 位于 Cloudflare 后面，并在大多数网络上返回客户端挑战。AgentCrawl **检测** 挑战页面并返回诚实的 `client_challenge` 错误，而不是将挑战 DOM 作为内容抓取。这是社区产品的边界，而不是错误。托管浏览器/代理/挑战处理属于增强/托管层，需要操作员或付费计划。
要验证社区产品在您的机器上是否有效，请将其指向任何可访问的文档页面：FastAPI、GitHub、维基百科、RFC 编辑器。
## 选择您的路径 🚀
### 代理：MCP 🤖
```bash
python -m pip install "agentcrawl-ai[browser]"
agentcrawl doctor
agentcrawl mcp
```
MCP 工具涵盖 `scrape_url`、`map_site`、`crawl_site`、作业状态、取消、事件历史、失败检查、选择性重试、用法和缓存控制。编码代理应遵循 [INSTALL_FOR_AGENTS.md](INSTALL_FOR_AGENTS.md)。
### 开发人员：Python + CLI 🧪
```bash
pip install agentcrawl-ai
agentcrawl scrape https://pypi.org/project/agentcrawl-ai/
```
```python
from agentcrawl import AgentCrawl
crawler = AgentCrawl({"fetcher": "http"})
document = crawler.scrape("https://pypi.org/project/agentcrawl-ai/")
print(document.markdown)
print(document.metadata)
```
### 服务器：Docker + API 🐳
```bash
docker run --rm -p 8000:8000 \
-e AGENTCRAWL_API_KEYS="replace-with-a-long-random-key" \
ghcr.io/jorg18/agentcrawl:latest
curl http://127.0.0.1:8000/health
# 只读本地仪表盘：
# open http://127.0.0.1:8000/dashboard
# curl http://127.0.0.1:8000/api/dashboard/summary
```
或使用 Compose：
```bash
cp .env.example .env
# 替换 .env 中的 AGENTCRAWL_API_KEYS 和 AGENTCRAWL_API_KEY
docker compose up -d
curl http://127.0.0.1:8000/health
```
## 为什么选择 AgentCrawl？ 🕸️
代理通常需要网页上下文，但原始 HTML 是一团糟。有用的页面可能混杂着导航、cookie 文本、相关链接、页脚链接、脚本和布局垃圾。
AgentCrawl 就是为此而设计的。它是一个小型本地层，为代理提供 URL，获取代理可以读取的内容，并将缓存、作业和失败保持在您的环境中。
当前功能：
- 🧹 已知 URL 输入，干净的 Markdown 输出：主内容提取、表格、代码块、链接、元数据和出处。
- ⚡ HTTP 优先：无需启动浏览器的快速默认提取。
- 🧱 持久爬虫：带有检查点、分页、取消、事件、重试和失败检查的 SQLite 作业。
- 📦 本地状态：缓存、用法、作业、事件、爬虫失败和提取的文档都保留在您这里。
- 📊 只读仪表盘：使用 `agentcrawl dashboard` 从 SQLite 生成静态 HTML，或在 API 服务器上打开 `/dashboard`。
- 🔒 更安全的 API 默认设置：承载者身份验证、`robots.txt` 支持、SSRF 保护、阻止不安全重定向和私有网络控制。
- 🤖 面向代理的接口：CLI、Python、HTTP API、Docker 和 MCP。
## 社区版包含哪些内容 🧰
AgentCrawl 社区版是自托管的信任层：
| 包含 | 说明 |
| --- | --- |
| CLI | 爬虫、爬行、检查作业、管理缓存、备份、恢复。 |
| Python 库 | 从脚本和代理运行时本地使用。 |
| HTTP API | 用于自托管部署的 FastAPI 服务器。 |
| MCP | 基于标准的 stdio MCP 服务器，用于代理客户端。 |
| Docker / GHCR | 由 GitHub Actions 构建和烟雾测试的公共镜像。 |
| 持久爬虫 | SQLite 作业、事件、检查点、重试和失败记录。 |
| 本地仪表盘 | 通过 `agentcrawl dashboard` 和 `/dashboard` 从 SQLite 读取静态 HTML。 |
| 质量提取 | Markdown、链接、元数据、JSON-LD/出处、表格、代码块。 |
| 基本浏览器备用 | 可选的本地浏览器/Camofox 路径，不适用于默认镜像。 |
| 轻量级文档 | 安装、示例、操作、发布、质量说明。 |
社区版是自托管的。它旨在用于可访问的网页内容、本地/私有工作流和诚实的失败报告，当页面受到反机器人或浏览器挑战的保护时。社区版可能会检测挑战页面并返回明确的 `client_challenge`/不支持失败；它不承诺绕过它们。可选的浏览器路径是本地自带渲染，而不是托管的浏览器池。托管浏览器、代理、计划、网络钩子、保留数据集、团队、计费和企业控件属于计划的增强/托管层，而不是社区运行时。
## 社区边界 🚧
社区版是开放的、自托管的信任层。它应该在优秀的可访问公共 HTML、本地文档、文档、API 参考、文章和参考页面方面保持优秀。它不应发展成为免费的托管爬虫平台。
社区版应对受保护的页面进行诚实报告，而不是将挑战文本作为内容返回。对于受保护的页面，使用本地浏览器备用方案，当足够时；如果目标需要托管浏览器/代理/挑战基础设施，请将其视为增强/托管用例。社区版不包括托管基础设施、托管浏览器池、代理网络、地理位置、隐身、计划、网络钩子、保留数据集、团队、计费或企业控件。
## 提取质量 🧹
社区引擎专注于稳定的、代理就绪的 Markdown，然后再进行基准测试声明：
- 从 `<main>`、`<article>`、文档/内容容器或富含文本的备用块中选择语义内容；
- 删除不安全和嘈杂的页面内容，如脚本、样式、隐藏内容、导航、页脚、cookie 横幅、侧边栏和相关帖子块；
- 保留带有标题和单元格值的 Markdown 表格；
- 保留带语言标签的围栏代码块，例如 `language-python` 和 `lang-javascript`；
- 附加提取出处，例如源/最终 URL、选定的内容提示、选择分数、候选人计数、内容哈希、提取策略、JSON-LD/模式字段、产品报价/评级字段和输出大小/结构元数据；
- 使用检查的固定装置对提取质量进行验证，并具有最低分数阈值和 Markdown 结构检查。
在本地运行报告：
```bash
python -m benchmarks.quality_report
```
## HTTP API 🌐
默认启用身份验证。在公开服务器之前，请配置至少一个 API 密钥：
```bash
export AGENTCRAWL_API_KEYS="replace-with-a-long-random-key"
python -m pip install "agentcrawl-ai[browser]"
agentcrawl serve --host 0.0.0.0 --port 8000
```
健康检查：
```bash
curl http://127.0.0.1:8000/health
```
爬取 URL：
```bash
curl http://127.0.0.1:8000/v1/scrape \
-H "authorization: Bearer replace-with-a-long-random-key" \
-H "content-type: application/json" \
-d '{"url":"https://example.com","formats":["markdown","links","metadata"]}'
```
主要端点：
```text
GET /health
GET /dashboard
GET /api/dashboard/summary
POST /v1/scrape
POST /v1/map
POST /v1/crawl
GET /v1/jobs/{job_id}
GET /v1/jobs/{job_id}/events
DELETE /v1/jobs/{job_id}
GET /v1/failures
GET /v1/jobs/{job_id}/failures
POST /v1/jobs/{job_id}/failures/retry
POST /v1/extract
GET /v1/usage
GET /v1/stats
DELETE /v1/cache
```
当服务器运行时，OpenAPI 文档可在 `/docs` 访问。
## 本地仪表盘 📊
从任何 AgentCrawl SQLite 数据库生成独立的静态 HTML 快照：
```bash
agentcrawl dashboard --db agentcrawl.db --output dashboard.html
```
当 API 服务器运行时，在 `/dashboard` 打开相同的只读视图，或在 `/api/dashboard/summary` 获取 JSON。仪表盘报告作业状态、爬虫队列、打开的失败、缓存域和用法单位，而不会将数据发送到任何托管服务。
## 爬虫作业 🧭
启动异步爬虫：
```bash
agentcrawl --remote crawl https://example.com --max-pages 25 --max-depth 2
```
HTTP 客户端可以附加幂等键，以便重试返回原始作业而不是启动重复作业：
```bash
curl http://127.0.0.1:8000/v1/crawl \
-H "authorization: Bearer replace-with-a-long-random-key" \
-H "content-type: application/json" \
-H "Idempotency-Key: docs-crawl-2026-06-06" \
-d '{"url":"https://example.com","max_pages":25,"max_depth":2}'
```
运行的作业检查队列、访问的 URL、重试尝试、进度和提取的文档在 SQLite 中。暂时的页面失败使用持续的指数退火重试，而不占用爬虫工作线程。它们在服务重启后被回收。
逐页读取已完成的文档：
```bash
agentcrawl --remote job JOB_ID --offset 0 --limit 100
```
在爬虫完成并带有终端失败时运行本地命令：
```bash
agentcrawl crawl https://example.com \
--alert-on-failure \
--cmd 'python notify.py'
```
命令通过 stdin 接收 JSON，包含 `source`、`failure_count` 和 `failures`。
检查或取消作业：
```bash
agentcrawl --remote job JOB_ID
agentcrawl --remote job-cancel JOB_ID
```
`/v1/stats` 报告队列准备情况、延迟重试、运行和取消作业、按状态划分的爬虫失败、开放的可重试失败和按错误类型划分的开放失败。
## 本地文档 📄
社区版支持本地文档摄入，无需将文件内容发送到托管解析器：
```bash
agentcrawl scrape ./notes.md
agentcrawl scrape ./data.json
agentcrawl scrape ./feed.xml
python -m pip install "agentcrawl-ai[browser]"
agentcrawl scrape ./report.pdf
```
当前文档支持：
| 输入 | 支持 |
| --- | --- |
| HTML | 主内容 Markdown 提取。 |
| Markdown | 作为 Markdown 直接传递。 |
| 文本 | 作为纯 Markdown 文本直接传递。 |
| JSON | 在围栏的 `json` 块内漂亮打印。 |
| XML/RSS/Atom | 在围栏的 `xml` 块内保留。 |
| PDF | 使用可选的 `docs` 额外功能逐页提取为 Markdown。强制执行大小/页面安全限制，并拒绝加密的 PDF。 |
## 浏览器渲染
默认包和默认 Docker 镜像使用 HTTP 提取。根据需要为需要 JavaScript 的站点添加浏览器渲染：
```bash
python -m pip install "agentcrawl-ai[browser]"
playwright install chromium
```
AgentCrawl 还支持可选的外部 Camofox REST 后端：
```bash
export AGENTCRAWL_BROWSER_BACKEND=camofox
export AGENTCRAWL_CAMOFOX_URL=http://127.0.0.1:9377
export AGENTCRAWL_CAMOFOX_ACCESS_KEY=replace-if-access-control-is-enabled
```
## 缓存 ⚡
禁用一次爬取的缓存或选择最多 30 天的 TTL：
```json
{"url":"https://example.com","cache":false}
```
```json
{"url":"https://example.com","cache_ttl_seconds":3600}
```
清除所有缓存条目或按域名或确切 URL 过滤：
```bash
agentcrawl --remote cache-clear
agentcrawl --remote cache-clear --domain example.com
agentcrawl --remote cache-clear --url https://example.com/page
```
## 备份 💾
在部署或迁移之前使用 SQLite 在线备份：
```bash
agentcrawl backup --db agentcrawl.db --output-dir ./backups
```
传递 `--env-file` 以复制受保护的环境文件到备份目录中，而不打印机密值。恢复拒绝覆盖现有数据库，除非提供 `--force` 并在复制前验证备份：
```bash
agentcrawl restore --backup-db ./backups/agentcrawl-YYYYMMDD-HHMMSS.db --db agentcrawl.db --force
```
## 安全默认值
HTTP 服务器拒绝本地文件路径、localhost、私有网络、非 HTTP 方案、嵌入式 URL 凭证和重定向到非全局地址。本地文件通过 Python 库保持可用。
请勿在没有身份验证、TLS、请求限制和网络控制的情况下公开 API。请参阅 [SECURITY.md](SECURITY.md) 和 [docs/OPERATIONS.md](docs/OPERATIONS.md)。
## 您会用到的文档 📚
- [代理安装](INSTALL_FOR_AGENTS.md)：编码代理的规范设置流程。
- [文档索引](docs/README.md)：公共文档集的映射。
- [示例](docs/EXAMPLES.md)：CLI、Python、HTTP、MCP、Docker 和代理的复制粘贴工作流。
- [质量基准](docs/QUALITY_BENCHMARKS.md)：提取质量的衡量和报告方式。
- [操作](docs/OPERATIONS.md)：部署、备份、恢复和生产检查。
- [发布清单](docs/RELEASE.md)：PyPI/GHCR 发布验证和烟雾测试。
- [比较](docs/COMPARISON.md)：在 AgentCrawl、Firecrawl、Crawl4AI、ScrapeGraphAI、Jina Reader、Crawlee 和 Stagehand 之间进行选择。
## 可选的 LLM 提取
AgentCrawl 社区版不需要 LLM 进行爬取、爬行、API、Docker 或 MCP 使用。遗留的提示驱动 `AgentCrawler.extract()` 路径是可选的：安装 `agentcrawl-ai[llm]` 并在使用的 `llm` 或 `llm_model` 配置之前进行配置。内置的网络搜索默认情况下被禁用；在您的代理/提供者层中保留搜索，除非您明确配置搜索后端。
## 开发
```bash
pip install -e ".[server,mcp,llm,dev]"
pytest -q
ruff check agentcrawl tests examples benchmarks
```
## 路线图
参见 [ROADMAP.md](ROADMAP.md)。
## 许可证
AgentCrawl 社区版在 Apache License 2.0 下获得许可。商业模块和托管服务是单独的产品，不包含在此存储库中。
