内容
# ai-crawler
[](https://github.com/cafitac/ai-crawler/actions/workflows/ci.yml)
由AI驱动的网络优先爬虫编译器，用于授权的工作流。
`ai-crawler` 将捕获的网络证据转化为可重复使用的爬虫配方。浏览器被用作短暂的探测器，用于API发现，而不是作为爬虫引擎。批量采集通过`curl-cffi`进行确定性的HTTP重放。
```text
浏览器不是爬虫，浏览器是探测器。
AI不是请求循环，AI是规划器/调试器/配方作者。
```
## 它是什么
`ai-crawler` 是一个早期的Python开源库和CLI，用于从网络证据中构建爬虫配方。
它专注于：
- 网络优先的API发现和重放
- 配方生成、测试、修复和确定性执行
- 简单的CLI默认值适用于人类和AI托管
- Python SDK facade用于应用程序集成
- stdio MCP服务器用于Hermes、Claude Code、Codex和其他代理
- 本地优先测试，带有假装运输和固定站点
- 安全边界：编辑、挑战检测和无CAPTCHA/MFA/机器人挑战绕过逻辑
## 安装用于本地开发
```bash
git clone https://github.com/cafitac/ai-crawler.git
cd ai-crawler
uv sync --extra dev --extra http --extra mcp
```
如果您已经在本地checkout中：
```bash
uv sync --extra dev --extra http --extra mcp
```
## npm 包装器
对于npm优先的入门，仓库还附带了一个薄的Node包装器，委托给Python核心：
```bash
npx @cafitac/ai-crawler --help
npx @cafitac/ai-crawler auto evidence.json --json
npx @cafitac/ai-crawler mcp
```
包装器行为：
- 在仓库checkout内：使用`uv run --project <repo> ai-crawler ...`运行本地Python核心
- 在仓库checkout之外：使用固定的git uvx规范运行发布的Python核心，当包装器包包含`gitHead`时，否则回退到`uvx --from "git+https://github.com/cafitac/ai-crawler.git[all]" ai-crawler ...`
- 使用`AI_CRAWLER_PYTHON_SPEC`覆盖发布的Python包规范
- 使用`AI_CRAWLER_UVX_PYTHON`覆盖uvx Python版本
## 快速开始
从URL到爬虫制品的一键路径是：
```bash
uv sync --extra browser --extra http
uv run --extra browser --extra http ai-crawler compile https://example.com/products --goal "collect products" --json
```
`compile` 简要打开页面，记录规范的网络响应事件到 `evidence.json`，生成配方，测试它，修复提取（如果可能），重新测试，并写入最终的 JSONL 输出。浏览器仅用于发现；生成的配方和最终爬取使用确定性的HTTP重放。默认情况下，探测证据保留适合重放的 `fetch`/`xhr` 2xx/3xx 响应，并丢弃静态资产、失败的响应和其他浏览器噪音。
如果您想在编译之前检查或编辑证据，请拆分流程：
```bash
uv run --extra browser ai-crawler probe https://example.com/products --goal "collect products"
uv run --extra browser ai-crawler probe https://example.com/products --goal "collect products" --wait-ms 2500 --max-events 50 --include-resource-type fetch,xhr,document
uv run --extra http ai-crawler auto evidence.json --json
```
如果您已经有一个证据文件，主要的AI托管命令是：
```bash
ai-crawler auto evidence.json --json
```
在本地checkout中：
```bash
uv run --extra http ai-crawler auto evidence.json --json
```
这会写入默认的制品：
```text
evidence.json # 浏览器探测证据，如果由探测生成
recipe.yaml # 初始生成的配方
repaired.recipe.yaml # 修复/最终配方
test.jsonl # 初始诊断爬取输出
crawl.jsonl # 最终爬取输出
auto.report.json # 稳定的机器可读报告
```
JSON报告包括：
- 最终成功/失败状态
- `command_type`（`compile` 或 `auto`）
- 用于快速分类的 `failure_phase`（`probe`、`generate`、`final_test` 或空表示成功）
- `probe -> generate -> initial_test -> repair -> final_test` 的有序 `phase_diagnostics`
- 配方/输出路径
- 初始和最终爬取结果
- 有界/编辑的诊断样本
- 失败分类，如 `success`、`extraction_failed`、`http_error`、`no_response`、`challenge_detected`、`probe_failed` 和 `no_endpoint_candidates`
在 `--json` 模式下，stdout 保留为一个机器可读的 JSON 对象。人类可读的失败消息写入 stderr。退出代码 `2` 仍然写入 `auto.report.json`，以便代理可以检查失败。
## 证据格式
使用短暂的浏览器探测创建证据：
```bash
uv run --extra browser ai-crawler probe https://example.com/products --goal "collect products" --output evidence.json
```
探测调优选项在 `probe` 和 `compile` 上均可用：
- `--wait-ms`：浏览器在网络空闲后的结算时间（默认值：`1000`）
- `--max-events`：过滤后保留的最大重放候选事件（默认值：`200`）
- `--include-resource-type`：以逗号分隔的 Playwright 资源类型以保留（默认值：`fetch,xhr`）
最小证据 JSON：
```json
{
"target_url": "https://example.com/products",
"goal": "collect products",
"events": [
{
"method": "GET",
"url": "https://example.com/api/products?page=1",
"status_code": 200,
"resource_type": "fetch"
}
]
}
```
手动生成和运行：
```bash
uv run --extra browser --extra http ai-crawler compile https://example.com/products --goal "collect products" --json
```
或自己运行每个制品步骤：
```bash
uv run --extra http ai-crawler generate-recipe evidence.json
uv run --extra http ai-crawler test-recipe recipe.yaml
uv run --extra http ai-crawler repair-recipe recipe.yaml
uv run --extra http ai-crawler test-recipe repaired.recipe.yaml --output crawl.jsonl
```
## MCP 用法
为本地 uv 项目用法生成客户端配置片段。有关 CLI/MCP/SDK 流的复制粘贴示例，请参阅 `docs/harness-examples.md`。
```bash
uv run ai-crawler mcp-config --client hermes --project /path/to/ai-crawler
uv run ai-crawler mcp-config --client claude-code --project /path/to/ai-crawler
uv run ai-crawler mcp-config --client codex --project /path/to/ai-crawler
```
为发布的包装器生成 npm-first 片段：
```bash
uv run ai-crawler mcp-config --client hermes --launcher npm
```
作为 stdio MCP 服务器运行：
```bash
uv run --extra mcp --extra http ai-crawler mcp
```
公开的工具：
- `compile_url`
- `auto_compile`
- `generate_recipe`
- `test_recipe`
- `repair_recipe`
如果您更喜欢使用 npm-first 安装进行代理工具，包装器也可以启动 MCP 服务器：
```bash
npx @cafitac/ai-crawler mcp
```
Hermes 开发片段形状：
```yaml
mcp_servers:
ai-crawler:
command: "uv"
args: ["run", "--project", "/path/to/ai-crawler", "--extra", "mcp", "--extra", "http", "ai-crawler", "mcp"]
timeout: 300
connect_timeout: 60
```
Hermes npm-first 片段形状：
```yaml
mcp_servers:
ai-crawler:
command: "npx"
args: ["-y", "@cafitac/ai-crawler", "mcp"]
timeout: 300
connect_timeout: 60
```
## Python SDK
Python SDK 仍然是稳定的嵌入式/编程接口。npm 包只是此 Python 核心周围的启动器包装器。有关复制粘贴的 SDK、MCP 和发布的包装器示例，请参阅 `docs/harness-examples.md`。
npm 发布会自动进行，使用 `.github/workflows/npm-publish.yml`。
- 推送一个与包版本匹配的标签，例如 `npm-v0.1.2`
- 或使用 `workflow_dispatch` 手动运行工作流
- 工作流在发布前验证 `package.json`、`pyproject.toml` 和 `src/ai_crawler/__init__.py` 是否同意发布版本
- 标签触发的发布还验证推送的标签是否与 `npm-v<package.json version>` 匹配
- 使用 `docs/release-runbook.md` 进行完整的版本提升、标记和发布后烟雾检查清单
示例标签流程：
```bash
git tag npm-v0.1.2
git push origin npm-v0.1.2
```
```python
from ai_crawler import AICrawler
crawler = AICrawler()
result = crawler.auto("evidence.json")
print(result.ok)
print(result.exit_code)
print(result.report)
compile_result = crawler.compile_url("https://example.com/products", goal="collect products")
print(compile_result.report["command_type"])
```
对于测试或嵌入式用法，注入假装获取器：
```python
crawler = AICrawler(fetcher=my_fake_fetcher)
```
## 验证
快速本地 lint/type 检查：
```bash
bash scripts/check-python.sh
```
完整的项目验证：
```bash
bash scripts/verify-ai-harness.sh
```
MCP `auto_compile` 固定烟雾测试：
```bash
uv run --extra http python scripts/smoke-mcp-auto-compile.py
```
这启动一个本地固定HTTP站点，并验证 `generate -> test -> repair -> retest` 无需外部互联网、真实浏览器或真实LLM。
## 安全性和合规边界
`ai-crawler` 用于授权的爬取、内部QA/测试、研究、拥有或允许的Web属性监控和数据可移植工作流。
它不实现：
- CAPTCHA 解决
- MFA 绕过
- Cloudflare/机器人挑战绕过
- 隐身指纹操纵
- 逃避代理轮换
类似挑战的响应被分类并作为需要人工/手动交接的适当要求。
诊断报告中的敏感值被编辑，包括常见的承载令牌、cookie、会话ID、API密钥和JSON嵌入令牌字段。
## 文档
开发文档位于 `.dev/` 下：
- `.dev/README.md`
- `.dev/03-ai/auto-harness-contract.md`
- `.dev/04-mcp/server.md`
- `.dev/08-operations/security-and-compliance.md`
- `.dev/08-operations/challenge-handling-policy.md`
## 状态
Alpha。确定性配方编译器、一键 `compile` 流、浏览器探测CLI、CLI、SDK facade、MCP服务器、编辑、失败分类和固定烟雾测试均已实现。实际的LLM提供者集成为可选/未来层，位于适配器边界后面。
## 许可证
MIT
