用途
WebReaper 是一个 AI 原生网页抓取工具，主要将网页内容转换为适合大语言模型（LLM）使用的干净 Markdown 或结构化数据，并可作为 Firecrawl 的本地、MIT 许可替代方案。它以单一二进制文件分发，同时提供库和 MCP 服务器接口。
主要能力
- 输出 Markdown：每页输出包含 {title, markdown} 的结果，可直接送入后续 LLM 提示。
- 结构化字段提取：支持用 schema 提取字段，例如通过 new("字段名", "CSS选择器") 定义叶子节点，支持嵌套对象、数组（IsList = true）以及读取 HTML 属性（Attr = "href"）。
- 自动反爬升级：普通抓取或爬取会先走快速 HTTP 请求，仅在检测到封锁时自动升级到真实浏览器；首次确认封锁后，同一主机会记录“地板”层级，后续页面从可用层级开始，无需重复尝试。仍被封锁的页面会被丢弃，不会写入输出，且运行以非零状态退出。
- stealth 控制：--stealth 从 stealth 后端开始；--auto-stealth（或 WEBREAPER_AUTO_STEALTH=1）支持无人值守启用；--no-auto-stealth 将升级上限限制为普通浏览器。约 220 MB 的 stealth 后端仅在显式启用时下载。
- Claude Code 技能：webreaper init 会向 .claude/skills/webreaper/ 写入 SKILL.md，Claude Code 在下一会话加载后可将“给我 X 的 markdown”“Y 上有哪些博客文章”“抓取前 5 篇文章”等意图自动路由到 webreaper。
- MCP 服务器：提供两个 MCP 服务器，暴露 scrape、map、extract、extract_with_prompt、extract_inferred、crawl 等工具。WebReaper.Mcp 使用 stdio，适合 Cursor、Claude Desktop、Copilot Studio 等本地客户端；WebReaper.Mcp.AspNetCore 使用 Streamable HTTP，适合 n8n 等仅支持 URL 的客户端。
- AI 安全网：三种可组合模式，仅在确定性提取失败时调用 LLM；稳定页面零 LLM 调用，破损页面按（页面、字段）调用并缓存，schema 推断每个站点一次调用并缓存。WebReaper.AI 基于 Microsoft.Extensions.AI，可使用任意 IChatClient。
- 自主智能体：AgentEngine 以 decide → persist → execute 循环运行，基于封闭枚举 AgentDecision（Extract | Follow | Act | Stop）逐步决策，支持跨进程重启的持久化恢复。
- 语义页面动作：PageAction.SemanticAct(intent) 接受自然语言意图，通过注册的 IActionResolver（默认 LLM 支持）解析一次，并按意图字符串缓存；同一意图的后续页面直接派发缓存动作，无 LLM 调用。
- 浏览器与动态页面：对 JS 渲染页面可用 CrawlWithBrowser，并通过 WebReaper.Playwright 或 WebReaper.Cdp 注册浏览器传输。
- 持久化与恢复：支持文件后端（零依赖、核心内置）和 SQLite 后端（需 WebReaper.Sqlite）持久化进度，可跨重启恢复；支持 dataCleanupOnStart 在开始时清空存储。
- 分布式与无服务器：可将调度器、配置存储、链接追踪器切换为 Redis 或 Azure Service Bus，多个 worker 或 serverless 函数共享同一爬取任务。
- 自定义扩展：提供 fluently builder 和可替换 seam，支持自定义 sink，可接入 Redis、Cosmos DB 等。
使用方式
- 安装：macOS / Linux 可通过 Homebrew；任意 POSIX shell 可使用 install.sh；Windows 二进制位于 GitHub Releases 页面，winget 和 Scoop 在 v10.1 路线图中。更新方式：brew upgrade webreaper；重新运行 install.sh 并追加 --upgrade（ | sh -s -- --upgrade ）；或 dotnet add package WebReaper（库）。
- CLI 使用：基本抓取示例为 webreaper scrape <url>，支持 --stealth、--auto-stealth 等参数。结构化字段可用 Extract(schema) 替换 AsMarkdown()；JS 渲染页面用 CrawlWithBrowser 加传输 satellite。
- 在智能体 harness 中使用：单一二进制可在任何可启动 shell 的智能体中使用，如 LangChain ShellTool、OpenAI Assistants code-interpreter、GitHub Actions、内部脚本。
- 在自有应用中嵌入：dotnet add package WebReaper，通过公开注册 seam 接入自定义存储。
- MCP HTTP 服务：docker run -p 8080:8080 -e WEBREAPER_MCP_TOKEN=your-secret ghcr.io/alex-on-ai/webreaper-mcp-http:latest，然后将 n8n 的 MCP Client 节点指向该 URL 并带 bearer token。
- 日志提示：存在新版本时，scrape / crawl / map 会在 stderr 打印一行升级提示（仅交互式终端，管道或 CI 中不打印）；可用 WEBREAPER_NO_UPDATE_CHECK=1 禁用。
适用场景
- 为博客或文档站点构建 LLM 上下文：webreaper map 加 webreaper scrape 逐 URL 处理，输出到提示或向量数据库。
- 监控竞品定价或状态页面变化：用 cron 或 worker 定时运行 CLI，记录到 MongoDB 或 SQLite，结合 .WithChangeTracking() 仅在差异时触发 sink。
- 运行自主研究智能体：LlmAgent.RunAsync(url, goal, chatClient) 决定跟随哪些链接直到目标达成，支持跨重启恢复。
- 抓取 Cloudflare 保护的目录：普通抓取自动从 HTTP 升级到浏览器，加 --stealth 或 --auto-stealth 可升级到 stealth 后端。
- 从半结构化页面生成干净数据集：[ScrapeSchema] POCO 加源生成器，无反射，AOT 编译为原生二进制。
- 在自有应用中嵌入抓取能力。
限制
- Windows 的 winget 和 Scoop 支持仍在 v10.1 路线图中，暂未提供。
- 约 220 MB 的 stealth 后端仅在显式启用时下载。
- WebReaper.Cli 不是 NuGet 包，不能通过 dotnet tool install 安装，需通过 Homebrew、install.sh 或从源码构建。
- 需要登录的站点需自行调用 SetCookies 完成登录。
- 输出结果在某些场景下需要使用线程安全集合（如 ConcurrentBag）收集，因为 Crawl 驱动会并发向 sink 扇出。
许可
WebReaper 采用 MIT 许可。所有 NuGet 包及 WebReaper.Cli 二进制均按相同条款分发，可用于商业用途、嵌入专有软件、fork、修改和再分发，只需保留版权声明。在 10.0.0 之前为 GPL-3.0-or-later，重新许可后更宽松，现有用户不受影响。
