` | `#` - `######` | 标题行 |\n| `` | `[text](url)` | 超链接 |\n| `![]()
` | `` | 图片 |\n| `` / `` | `**text**` | 粗体 |\n| `` / `` | `*text*` | 斜体 |\n| `` | `` `code` `` | 行内代码 |\n| `` / `` | ```language\\ncode\\n``` | 代码块 |\n| `` | `> text` | 引用块 |\n| `` / `` | `- item` / `1. item` | 列表 |\n| `` | Markdown 表格格式 | 表格转换 |\n| `
` | `---` | 水平线 |\n\n资料来源：[crawl4ai/html2text/elements.py:1-100]()\n\n#### 3. 主模块 (__init__.py)\n\n`__init__.py` 整合了配置和元素处理逻辑，提供完整的 HTML 到 Markdown 转换功能：\n\n```python\nclass Html2Text:\n \"\"\"HTML到Markdown转换器主类\"\"\"\n \n def __init__(self, config: Html2TextConfig = None):\n \"\"\"初始化转换器\n \n 参数:\n config: 配置对象\n \"\"\"\n self.config = config or Html2TextConfig()\n self._setup_handlers()\n \n def handle(self, html: str) -> str:\n \"\"\"处理HTML并返回Markdown\n \n 参数:\n html: 输入的HTML字符串\n \n 返回:\n 转换后的Markdown字符串\n \"\"\"\n pass\n \n def handle_tree(self, tree) -> str:\n \"\"\"处理解析后的HTML树\"\"\"\n pass\n```\n\n资料来源：[crawl4ai/html2text/__init__.py:1-150]()\n\n## 内容过滤策略\n\n`ContentFilterStrategy` 定义了内容过滤接口，用于在 Markdown 生成前对内容进行预处理。\n\n### 过滤策略类型\n\n| 策略 | 作用 | 使用场景 |\n|------|------|----------|\n| `DefaultContentFilter` | 默认过滤策略 | 标准网页抓取 |\n| `AggressiveContentFilter` | 激进过滤 | 去除更多噪音内容 |\n| `LightContentFilter` | 轻量过滤 | 保留更多原始内容 |\n\n### 过滤流程\n\n```mermaid\ngraph TD\n A[HTML 输入] --> B{内容过滤策略}\n B -->|保留标题| C[标题提取]\n B -->|移除脚本| D[脚本移除]\n B -->|移除样式| E[样式移除]\n B -->|移除注释| F[注释移除]\n C --> G[清理后 HTML]\n D --> G\n E --> G\n F --> G\n G --> H[Markdown 生成]\n H --> I[Markdown 输出]\n```\n\n## 使用方法\n\n### 基本用法\n\n```python\nfrom crawl4ai import Crawler\nfrom crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerationStrategy\n\n# 创建爬虫实例\ncrawler = Crawler()\n\n# 配置 Markdown 生成策略\ncrawler.markdown_strategy = DefaultMarkdownGenerationStrategy()\n\n# 执行抓取\nresult = crawler.crawl(\"https://example.com\")\n\n# 获取 Markdown 内容\nmarkdown = result.markdown\n```\n\n### 自定义配置\n\n```python\nfrom crawl4ai.html2text.config import Html2TextConfig\n\n# 创建自定义配置\nconfig = Html2TextConfig(\n ignore_links=False,\n ignore_images=False,\n ignore_tables=False,\n escape_all=False\n)\n\n# 应用配置\nmarkdown_generator = DefaultMarkdownGenerationStrategy(config=config)\n```\n\n### 内容过滤配置\n\n```python\nfrom crawl4ai.content_filter_strategy import DefaultContentFilter\n\n# 配置内容过滤\nfilter_strategy = DefaultContentFilter()\n\n# 在爬取时应用\nresult = crawler.crawl(\n \"https://example.com\",\n content_filter=filter_strategy\n)\n```\n\n## 配置参数详解\n\n### Html2TextConfig 完整参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `body_width` | int | 0 | 文本宽度限制，0表示不限制 |\n| `unicode_snob` | bool | False | 使用 Unicode 字符 |\n| `escape_snob` | bool | False | 转义特殊 Markdown 字符 |\n| `escape_all` | bool | False | 转义所有特殊字符 |\n| `links_each_paragraph` | bool | False | 每个段落处理链接 |\n| `ignore_links` | bool | False | 忽略链接 |\n| `ignore_images` | bool | False | 忽略图片 |\n| `ignore_emphasis` | bool | False | 忽略强调 |\n| `ignore_blockquotes` | bool | False | 忽略引用块 |\n| `ignore_tables` | bool | False | 忽略表格 |\n| `single_line_break` | bool | False | 单行换行 |\n| `pad_tables` | bool | False | 表格填充 |\n| `clickable_lnks` | bool | False | 链接可点击 |\n| `images_to_alt` | bool | False | 图片转 ALT 文本 |\n| `images_to_md` | bool | True | 图片转 Markdown 格式 |\n| `ln_ewscape` | bool | False | 行尾转义 |\n| `md_spoiler` | bool | False | Markdown 隐藏文本 |\n| `wrap` | bool | False | 文本换行 |\n| `wrap_width` | int | 80 | 换行宽度 |\n\n资料来源：[crawl4ai/html2text/config.py:1-100]()\n\n## 数据流与转换过程\n\n### 完整转换流程\n\n```mermaid\ngraph LR\n A[原始 HTML] --> B[HTML 解析]\n B --> C[内容过滤]\n C --> D[DOM 树处理]\n D --> E[元素转换]\n E --> F[Markdown 序列化]\n F --> G[最终 Markdown]\n \n subgraph 内容过滤阶段\n C1[移除脚本标签] --> C2[移除样式标签]\n C2 --> C3[移除注释]\n C3 --> C4[提取主体内容]\n end\n \n subgraph 元素转换\n E1[标题处理] --> E2[链接处理]\n E2 --> E3[图片处理]\n E3 --> E4[表格处理]\n E4 --> E5[列表处理]\n E5 --> E6[代码块处理]\n end\n```\n\n### 关键转换示例\n\n| HTML 输入 | Markdown 输出 |\n|-----------|---------------|\n| `标题
` | `# 标题` |\n| `链接` | `[链接](url)` |\n| `![\"描述\"](\"img.jpg\")
` | `` |\n| `粗体` | `**粗体**` |\n| `代码` | `` `代码` `` |\n| `1
` | `| 1 |` |\n\n## 高级用法\n\n### 自定义元素处理器\n\n```python\nfrom crawl4ai.html2text import Html2Text\nfrom crawl4ai.html2text.config import Html2TextConfig\n\nclass CustomHtml2Text(Html2Text):\n \"\"\"自定义 HTML 转 Markdown 处理器\"\"\"\n \n def handle_tag_h1(self, tag, attrs, start):\n \"\"\"自定义 H1 处理逻辑\"\"\"\n # 自定义处理逻辑\n return f\"## {self.get_text()}\"\n \n def handle_tag_a(self, tag, attrs, start):\n \"\"\"自定义链接处理\"\"\"\n # 自定义链接处理\n pass\n```\n\n### 批量转换\n\n```python\nfrom crawl4ai import Crawler\nfrom crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerationStrategy\n\nurls = [\n \"https://example.com/page1\",\n \"https://example.com/page2\",\n \"https://example.com/page3\"\n]\n\ngenerator = DefaultMarkdownGenerationStrategy()\ncrawler = Crawler()\n\nresults = []\nfor url in urls:\n result = crawler.crawl(url)\n results.append({\n \"url\": url,\n \"markdown\": result.markdown\n })\n```\n\n## 注意事项\n\n### 性能考量\n\n1. **大文档处理**：对于包含大量元素的 HTML 页面，转换过程可能耗时较长\n2. **内存使用**：大型 DOM 树会占用较多内存，建议对超大型页面进行分块处理\n3. **编码处理**：确保输入 HTML 的编码正确，避免乱码问题\n\n### 兼容性说明\n\n| HTML 特性 | 支持状态 | 说明 |\n|-----------|----------|------|\n| HTML5 | ✅ 完全支持 | 支持所有 HTML5 标签 |\n| SVG | ⚠️ 部分支持 | 基本支持，部分复杂 SVG 可能无法正确转换 |\n| MathJax/LaTeX | ⚠️ 需要插件 | 需要额外配置 |\n| 嵌入式视频 | ❌ 不支持 | 会被转换为链接或忽略 |\n\n## 相关文件\n\n| 文件路径 | 描述 |\n|----------|------|\n| `crawl4ai/markdown_generation_strategy.py` | Markdown 生成策略定义与实现 |\n| `crawl4ai/content_filter_strategy.py` | 内容过滤策略定义与实现 |\n| `crawl4ai/html2text/__init__.py` | html2text 主模块 |\n| `crawl4ai/html2text/elements.py` | HTML 元素处理规则 |\n| `crawl4ai/html2text/config.py` | 配置参数定义 |\n\n---\n\n\n\n## 数据提取策略\n\n### 相关页面\n\n相关主题：[分块与过滤策略](#page-chunking-filtering), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/extraction_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/extraction_strategy.py)\n- [crawl4ai/content_scraping_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_scraping_strategy.py)\n- [crawl4ai/table_extraction.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/table_extraction.py)\n- [crawl4ai/crawlers/amazon_product/crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/crawlers/amazon_product/crawler.py)\n- [crawl4ai/crawlers/google_search/crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/crawlers/google_search/crawler.py)\n\n\n# 数据提取策略\n\n## 概述\n\n数据提取策略是 crawl4ai 框架中用于从网页内容中精准提取结构化数据的核心模块。该策略系统设计灵活，支持多种提取方式，涵盖从简单的 CSS 选择器匹配到基于大语言模型（LLM）的智能语义提取。\n\n## 架构设计\n\n### 策略类型体系\n\ncrawl4ai 的数据提取策略采用策略模式（Strategy Pattern）设计，主要包含以下几种策略类型：\n\n```mermaid\ngraph TD\n A[ExtractionStrategy 基类] --> B[NoExtractionStrategy]\n A --> C[BeautifulSoupExtractionStrategy]\n A --> D[LLMExtractionStrategy]\n A --> E[JsonCssExtractionStrategy]\n A --> F[RegexExtractionStrategy]\n \n B --> G[不使用任何提取]\n C --> H[基于 CSS 选择器的结构化提取]\n D --> I[基于 LLM 的语义理解提取]\n E --> J[JSON + CSS 组合提取]\n F --> K[正则表达式模式匹配]\n```\n\n### 核心组件关系\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| ExtractionStrategy | extraction_strategy.py | 策略基类，定义标准化接口 |\n| ContentScrapingStrategy | content_scraping_strategy.py | 内容抓取策略，处理原始内容获取 |\n| TableExtraction | table_extraction.py | 表格数据专项提取 |\n| CrawlerStrategy | 各爬虫子模块 | 具体业务场景的实现 |\n\n## 策略详解\n\n### NoExtractionStrategy\n\n默认策略，不执行任何数据提取操作。适用于只需要获取完整页面内容或 HTML 的场景。\n\n```python\n# 使用示例\nresult = await crawler.crawl(\n url=\"https://example.com\",\n extraction_strategy=NoExtractionStrategy()\n)\n```\n\n### BeautifulSoupExtractionStrategy\n\n基于 BeautifulSoup4 的结构化数据提取策略，通过 CSS 选择器精确定位页面元素。\n\n**配置参数：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| css_selector | str | None | CSS 选择器表达式 |\n| filter_regex | str | None | 内容过滤正则表达式 |\n| check_interval | float | 0.2 | 检查间隔（秒） |\n| timeout | int | 7 | 超时时间（秒） |\n\n### LLMExtractionStrategy\n\n基于大语言模型的智能提取策略，能够理解页面语义并提取非结构化或半结构化数据。\n\n**核心参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| prompt | str | 是 | 提取指令提示词 |\n| schema | dict | 否 | 输出数据 schema 定义 |\n| extraction_type | str | 否 | 提取类型标识 |\n\n### JsonCssExtractionStrategy\n\n结合 JSONPath 和 CSS 选择器的混合提取策略，适用于复杂的嵌套数据结构。\n\n### RegexExtractionStrategy\n\n基于正则表达式的文本模式提取策略，适合处理日志、代码片段等结构化文本。\n\n## 内容抓取策略\n\nContentScrapingStrategy 负责处理内容获取阶段的策略配置，主要包含以下抓取模式：\n\n```mermaid\ngraph LR\n A[网页请求] --> B[ScrapingMode 选择]\n B --> C[全量 HTML]\n B --> D[无标签文本]\n B --> E[结构化内容]\n \n C --> F[beautifulsoup 处理]\n D --> G[正则清理]\n E --> H[语义分析]\n```\n\n**支持的抓取模式：**\n\n| 模式名称 | 说明 | 适用场景 |\n|---------|------|---------|\n| html | 完整 HTML 源码 | 需要保留原始标签结构 |\n| text | 纯文本内容 | 文本分析和 NLP 处理 |\n| fit_markdown | Markdown 格式 | 文档转换和内容摘要 |\n|.cleaned | 清理后内容 | 去除脚本和样式噪音 |\n\n## 表格提取机制\n\nTableExtraction 是 crawl4ai 中专门处理 HTML 表格数据提取的模块。\n\n### 提取流程\n\n```mermaid\ngraph TD\n A[定位 table 元素] --> B[识别表头行]\n B --> C[遍历数据行]\n C --> D{是否跨列/跨行?}\n D -->|是| E[处理单元格合并]\n D -->|否| F[直接提取]\n E --> G[构建单元格映射]\n F --> H[转换为列表/字典]\n G --> H\n H --> I[输出 JSON 格式]\n```\n\n### 表格数据结构\n\n提取的表格数据以列表形式返回，每行对应一个字典对象：\n\n```python\n[\n {\"列名1\": \"值1\", \"列名2\": \"值2\"},\n {\"列名1\": \"值3\", \"列名2\": \"值4\"}\n]\n```\n\n## 领域专用爬虫示例\n\n### 亚马逊产品爬虫\n\nAmazon 产品爬虫继承基础提取策略，针对电商页面结构优化：\n\n```python\n# 资料来源：crawl4ai/crawlers/amazon_product/crawler.py\nclass AmazonProductCrawler:\n def __init__(self, extraction_strategy):\n self.strategy = extraction_strategy\n```\n\n### 谷歌搜索爬虫\n\n谷歌搜索爬虫实现特定的搜索结果提取逻辑：\n\n```python\n# 资料来源：crawl4ai/crawlers/google_search/crawler.py\nclass GoogleSearchCrawler:\n async def crawl(self, query: str):\n # 实现搜索结果提取\n```\n\n## 使用最佳实践\n\n### 策略选择指南\n\n| 应用场景 | 推荐策略 | 理由 |\n|---------|---------|-----|\n| 简单表格/列表 | BeautifulSoupExtractionStrategy | 性能高效，精度高 |\n| 语义复杂内容 | LLMExtractionStrategy | 理解能力强 |\n| 结构化日志 | RegexExtractionStrategy | 模式匹配灵活 |\n| 嵌套 JSON | JsonCssExtractionStrategy | 混合查询支持 |\n| 快速原型 | NoExtractionStrategy | 零配置启动 |\n\n### 性能优化建议\n\n1. **优先使用 CSS 选择器**：在数据格式已知的情况下，BeautifulSoup 策略性能优于 LLM 策略\n2. **设置合理的超时时间**：避免大型页面导致的长时间等待\n3. **启用检查间隔**：对于动态加载内容，适当增加 check_interval\n4. **批量提取优化**：多条数据使用同一策略实例，减少初始化开销\n\n## 扩展开发指南\n\n如需创建自定义提取策略，需继承 ExtractionStrategy 基类并实现核心方法：\n\n```python\nfrom crawl4ai.extraction_strategy import ExtractionStrategy\n\nclass CustomExtractionStrategy(ExtractionStrategy):\n async def extract(self, html: str, url: str) -> List[Dict]:\n # 实现自定义提取逻辑\n pass\n```\n\n## 版本兼容性\n\n数据提取策略模块在不同版本间保持接口兼容性，详见项目 CHANGELOG 获取版本特定说明。\n\n---\n\n**相关文档：**\n- [用户指南](../docs/user-guide.md)\n- [API 参考](../api_reference/)\n- [示例代码](../examples/)\n\n---\n\n\n\n## 分块与过滤策略\n\n### 相关页面\n\n相关主题：[数据提取策略](#page-extraction-strategies), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/chunking_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/chunking_strategy.py)\n- [crawl4ai/content_filter_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_filter_strategy.py)\n- [crawl4ai/model_loader.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/model_loader.py)\n- [crawl4ai/prompts.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/prompts.py)\n\n\n# 分块与过滤策略\n\n## 概述\n\n在 Crawl4ai 项目中，**分块策略（Chunking Strategy）** 和 **过滤策略（Content Filter Strategy）** 是两个核心模块，它们共同负责将爬取的网页内容转化为结构化、可处理的文本块。这两个策略在数据处理流程中扮演着至关重要的角色，它们使得大规模网页内容能够被有效地分割、过滤和组织，以满足大语言模型（LLM）训练、知识库构建等应用场景的需求。\n\n分块策略的主要功能是将长文本内容按照预定义的规则（如字符数、句子边界、段落等）分割成较小的、语义相对完整的块（Chunk）。这种分割方式能够确保每个文本块具有足够的上下文信息，同时保持适当的粒度便于后续处理。过滤策略则负责识别并保留最具价值的文本内容，同时去除导航菜单、广告脚本、页脚信息等无用的噪音内容。这两个策略的协同工作形成了 Crawl4ai 内容处理管道的核心环节。\n\n从架构设计的角度来看，分块与过滤策略都遵循了策略模式（Strategy Pattern）的设计原则。这种设计允许用户在运行时动态选择和配置不同的分块或过滤算法，而无需修改核心处理逻辑。每个策略都实现了统一的接口定义，确保了模块之间的松耦合和高度可扩展性。这种灵活性使得 Crawl4ai 能够适应各种不同的内容处理场景和需求变化。\n\n## 分块策略详解\n\n### 工作原理\n\n分块策略的核心目标是将输入的文本内容按照特定规则进行分割，生成一系列语义相对完整的文本块。在实现层面，分块策略首先会对输入文本进行分析，识别出文本的内在结构（如句子、段落、标题等），然后根据预定义的参数（如最大块大小、重叠大小等）将文本切分为多个块。每个块都包含了一定量的上下文信息，同时保持相对独立的语义完整性。\n\n分块过程通常遵循以下基本流程：首先，策略会接收原始文本内容和相关配置参数；然后，对文本进行预处理，包括清理格式、识别结构等；接着，根据选定的分块算法执行分割操作；最后，对生成的块进行后处理，包括清理空块、合并过小的块等。整个过程旨在最大化每个块的实用价值，同时最小化信息丢失和上下文割裂。\n\n### 配置参数\n\n分块策略的行为可以通过多个参数进行精细控制，这些参数决定了分块的大小、重叠方式以及边界处理逻辑。以下是主要的配置选项：\n\n| 参数名称 | 类型 | 默认值 | 说明 |\n|---------|------|--------|------|\n| chunk_word_count | int | 1024 | 每个块的近似单词数目标值 |\n| overlap | int | 100 | 块之间的重叠单词数 |\n| overlap_all_sections | bool | False | 是否在所有章节间应用重叠 |\n| combine_sentences | bool | False | 是否将短句合并为完整段落 |\n| max_characters_per_section | int | 1500 | 每个章节的最大字符数 |\n| overlap_rate | float | 0.1 | 重叠率，overlap_rate * chunk_word_count |\n| extra_system_prompt | str | \"\" | 额外的系统提示词 |\n| user_prompt | str | \"\" | 用户自定义提示词模板 |\n\n这些参数可以根据具体的应用场景进行调整。例如，当需要较短的块用于精确检索时，可以减小 `chunk_word_count` 的值；当需要保留更多上下文信息时，可以增加 `overlap` 或 `overlap_rate` 的值以实现块之间的信息重叠。`overlap_all_sections` 参数特别有用，因为它确保了跨章节边界的语义连贯性。\n\n### 分块算法实现\n\n在具体实现层面，Crawl4ai 提供了多种分块算法的实现。以基于字数的分块为例，该算法会遍历文本内容，累积单词直到达到目标块大小，然后在该位置附近（通常在句子边界处）进行截断，生成一个新的块。这种方法简单高效，适用于大多数场景。\n\n对于更复杂的场景，系统还支持基于语义的分块方法。这种方法会结合自然语言处理技术，识别文本中的语义边界（如主题转换点），并在这些位置进行分割。语义分块能够产生更加连贯、信息密度更高的文本块，但计算成本也相对较高。算法实现中会调用语言模型来辅助判断语义边界，这部分功能与 `model_loader.py` 中定义的模型加载机制紧密相关。\n\n```mermaid\ngraph TD\n A[原始文本输入] --> B[文本预处理]\n B --> C[结构识别]\n C --> D{分块算法选择}\n D -->|字数分块| E[按字数累积]\n D -->|语义分块| F[语义边界分析]\n E --> G[句子边界截断]\n F --> G\n G --> H[生成文本块]\n H --> I[重叠处理]\n I --> J[块后处理]\n J --> K[输出块列表]\n```\n\n### 自定义分块策略\n\nCrawl4ai 的架构设计允许开发者实现自定义的分块策略。要创建自定义策略，需要继承基础的分块策略类并实现核心的 `chunk()` 方法。方法签名通常接受原始文本内容和可选的配置参数，返回一个文本块列表。这种设计使得系统具有极强的扩展性，能够适应各种特殊的内容处理需求。\n\n自定义策略的实现需要考虑多个方面：首先是分块逻辑的准确性，确保生成的块符合预期的格式和质量标准；其次是性能优化，特别是处理大规模文本时需要考虑计算效率；最后是错误处理机制，需要妥善处理各种异常情况如空文本、格式错误等。通过继承和扩展基础类，开发者可以专注于实现特定的分块逻辑，而无需关心与其他模块的集成细节。\n\n## 过滤策略详解\n\n### 目的与作用\n\n内容过滤策略的主要目的是从爬取的网页内容中识别并提取高价值的文本信息，同时过滤掉导航菜单、页脚、版权声明、广告脚本等无意义的内容。这一步骤对于后续的内容处理至关重要，因为它直接影响到生成的知识库的纯净度和可用性。一个设计良好的过滤策略能够显著提升内容的信号噪声比，使得检索和问答等下游任务能够获得更准确的结果。\n\n过滤策略的实现通常依赖于启发式规则和机器学习模型的结合。在传统方法中，系统会基于 HTML 标签类型、CSS 类名、元素位置等特征来判断内容的价值。例如，包含 \"nav\"、\"footer\"、\"sidebar\"、\"advertisement\" 等关键词的元素通常会被标记为低价值内容。在更高级的实现中，系统还会结合语言模型来理解内容的语义，进一步提升过滤的准确性。\n\n### 过滤机制\n\n过滤机制的实现涉及多个层次的判断逻辑。在最基础的层面，系统会基于 HTML 结构特征进行粗过滤，识别并排除明显无用的内容块。这包括脚本标签、样式标签、隐藏元素、以及某些特定的 HTML 标签类型。通过分析元素的可见性、大小、位置等属性，系统可以快速排除大量低价值内容。\n\n在更精细的层面，过滤策略会结合文本内容的语义分析。这部分功能与 `prompts.py` 中定义的提示词模板紧密相关。系统会使用特定的提示词引导语言模型对内容块进行价值评估，判断其是否包含实质性的信息内容。评估结果会被用于决定是否保留该内容块，或者将其标记为需要进一步处理或直接过滤。\n\n```mermaid\ngraph TD\n A[网页内容输入] --> B[HTML结构分析]\n B --> C[标签类型过滤]\n C --> D[可见性检查]\n D --> E[语义分析]\n E --> F{价值评估}\n F -->|高价值| G[保留内容]\n F -->|低价值| H[过滤内容]\n F -->|不确定| I[模型辅助判断]\n I --> G\n I --> H\n```\n\n### 过滤策略类型\n\nCrawl4ai 提供了多种预定义的过滤策略，以适应不同的内容处理需求。这些策略包括基于规则的方法、基于统计的方法和基于深度学习的方法。每种策略都有其特定的优势和适用场景，用户可以根据实际需求选择最合适的策略类型。\n\n**关键词过滤策略** 是最基础的方法，它通过预定义的关键词列表来识别和过滤无价值内容。这种方法简单高效，但可能无法处理所有变体和无规律的噪音内容。**正则表达式过滤策略** 提供了更灵活的模式匹配能力，能够处理更复杂的过滤规则。**基于模型的质量过滤策略** 则利用机器学习模型来评估内容的价值，能够捕捉更深层次的语义特征。\n\n| 策略类型 | 优点 | 缺点 | 适用场景 |\n|---------|------|------|---------|\n| 关键词过滤 | 速度快、简单易用 | 准确性有限 | 快速处理、结构化内容 |\n| 正则过滤 | 灵活性高、可定制 | 需要手动编写规则 | 特定格式内容 |\n| 模型过滤 | 准确性高、适应性强 | 计算成本较高 | 高质量需求场景 |\n| 混合过滤 | 综合多种方法优势 | 配置复杂 | 通用场景 |\n\n## 与模型加载器的集成\n\n### 模型加载机制\n\n分块和过滤策略的执行往往需要语言模型的参与。`model_loader.py` 模块提供了统一的模型加载和管理接口，使得策略能够便捷地访问语言模型能力。这个模块封装了模型初始化、配置管理、推理调用等核心功能，为上层策略提供了一个简洁而强大的模型访问层。\n\n模型加载器支持多种模型类型和部署方式，包括本地模型和云端 API。配置参数允许用户指定模型的类型、版本、API 密钥等必要信息。加载器会自动处理模型缓存、多实例管理、请求批处理等底层细节，使得策略实现者能够专注于业务逻辑而无需关心模型调用的基础设施问题。\n\n### 在策略中的应用\n\n在分块策略中，模型主要被用于语义分块和质量评估。当启用语义分块模式时，系统会调用模型来分析文本的语义结构，识别主题转换点和最佳分割位置。在过滤策略中，模型被用于深度内容理解，评估文本块的语义价值和相关性。这些应用都需要模型加载器提供稳定可靠的模型访问服务。\n\n模型的使用涉及性能优化和成本控制两个关键考量。在性能方面，系统实现了请求批处理、模型缓存、推理结果缓存等优化机制，以减少重复计算和 API 调用延迟。在成本方面，系统支持多种模型选择，从高性能高成本的模型到轻量级低成本模型的梯度配置，用户可以根据需求权衡效果和成本。\n\n## 提示词集成\n\n### 提示词模板\n\n`prompts.py` 模块定义了分块和过滤策略使用的各种提示词模板。这些模板经过精心设计，能够有效地引导语言模型执行内容分析、价值评估、语义分割等任务。提示词的质量直接影响策略的执行效果，因此模板的设计和优化是策略开发的重要环节。\n\n提示词模板采用结构化设计，包含系统提示和用户提示两个部分。系统提示定义了模型的角色定位和基本行为准则，用户提示则包含了具体的任务描述和输入内容。这种设计使得提示词具有良好的可读性和可维护性，同时也方便根据不同场景进行定制和优化。\n\n### 自定义提示词\n\n用户可以通过配置参数自定义提示词内容，以适应特定的内容处理需求。例如，`extra_system_prompt` 参数允许在系统提示中添加额外的指令，`user_prompt` 参数允许用户自定义用户提示的模板结构。这种灵活性使得系统能够适应各种特殊的内容处理场景和领域需求。\n\n自定义提示词时需要注意几个关键要点：首先是提示词的清晰性和具体性，模糊的指令可能导致模型产生不一致的结果；其次是提示词的长度和复杂性，过长的提示词可能增加处理成本和延迟；最后是提示词的格式兼容性，确保自定义提示词与系统其他部分能够良好集成。\n\n## 实际应用示例\n\n### 基本使用流程\n\n在实际应用中，分块和过滤策略通常作为数据处理管道的一环被调用。用户首先配置所需的策略参数，然后调用执行方法处理输入内容。整个过程是自动化的，用户只需关注输入输出的管理。以下是一个典型的使用场景：\n\n```python\nfrom crawl4ai import ChunkingStrategy, ContentFilterStrategy\n\n# 配置分块策略\nchunking_strategy = ChunkingStrategy(\n chunk_word_count=512,\n overlap=50,\n overlap_all_sections=True\n)\n\n# 配置过滤策略\nfilter_strategy = ContentFilterStrategy(\n model=\"gpt-4\",\n filter_type=\"semantic\"\n)\n\n# 执行处理\ncontent = \"待处理的网页文本内容...\"\nchunks = chunking_strategy.chunk(content)\nfiltered_chunks = filter_strategy.filter(chunks)\n```\n\n### 最佳实践建议\n\n在实际使用中，有几个关键的优化建议值得关注。首先是分块大小的选择，需要根据下游任务的需求进行权衡：较小的块适合精确检索，但可能缺乏足够的上下文；较大的块包含更丰富的上下文，但可能引入噪音。其次是重叠参数的设置，适当的重叠能够保证跨块边界的语义连续性，特别是在涉及长程依赖的任务中。\n\n过滤策略的选择和配置同样需要根据具体场景进行调整。对于新闻类内容，可以侧重于正文提取和标题识别；对于论坛讨论类内容，则需要更智能的噪音过滤以排除签名档和重复引用。对于包含大量代码的项目文档，还需要特别注意代码块的识别和保留，避免被误过滤。\n\n## 技术规格总结\n\n| 组件 | 位置 | 主要功能 | 可扩展性 |\n|------|------|---------|---------|\n| ChunkingStrategy | chunking_strategy.py | 文本分块处理 | 支持自定义实现 |\n| ContentFilterStrategy | content_filter_strategy.py | 内容质量过滤 | 支持多种过滤模式 |\n| ModelLoader | model_loader.py | 模型访问管理 | 支持多种模型类型 |\n| PromptManager | prompts.py | 提示词管理 | 支持自定义模板 |\n\n分块与过滤策略作为 Crawl4ai 的核心组件，共同构成了网页内容智能处理的基础设施。通过合理配置和使用这些策略，用户可以实现高效、准确的大规模网页内容处理，为各种下游任务提供高质量的数据支持。系统的模块化设计确保了良好的可维护性和可扩展性，使得用户能够根据实际需求进行灵活定制和优化。\n\n---\n\n\n\n## 浏览器配置与代理\n\n### 相关页面\n\n相关主题：[高级功能](#page-advanced-features), [异步网页爬虫核心](#page-async-webcrawler)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/browser_manager.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_manager.py)\n- [crawl4ai/browser_adapter.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_adapter.py)\n- [crawl4ai/browser_profiler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_profiler.py)\n- [crawl4ai/proxy_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/proxy_strategy.py)\n- [crawl4ai/ssl_certificate.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/ssl_certificate.py)\n- [crawl4ai/user_agent_generator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/user_agent_generator.py)\n\n\n# 浏览器配置与代理\n\n## 概述\n\n浏览器配置与代理模块是 crawl4ai 框架中负责管理浏览器实例配置、代理设置、SSL证书处理以及用户代理字符串生成的核心组件。该模块提供了灵活的浏览器定制能力，使爬虫能够适应不同的目标网站环境，包括需要身份验证、SSL证书处理、代理跳转等复杂场景。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[BrowserConfig] --> B[BrowserManager]\n A --> C[BrowserAdapter]\n A --> D[BrowserProfiler]\n E[ProxyStrategy] --> B\n F[SSLConfig] --> B\n G[UserAgentGenerator] --> B\n B --> H[Playwright Browser]\n C --> I[BrowserController]\n D --> J[BrowserPool]\n```\n\n## 核心组件\n\n### BrowserManager\n\nBrowserManager 是浏览器管理的核心类，负责浏览器的生命周期管理、实例化、配置应用和资源清理。\n\n```mermaid\ngraph LR\n A[创建配置] --> B[初始化浏览器]\n B --> C[应用代理]\n C --> D[设置SSL]\n D --> E[生成User-Agent]\n E --> F[浏览器就绪]\n F --> G[执行爬取]\n G --> H[资源释放]\n```\n\n**主要职责：**\n- 管理浏览器实例的创建和销毁\n- 配置浏览器启动参数\n- 应用代理和SSL设置\n- 处理浏览器上下文隔离\n\n**配置参数表：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| headless | bool | True | 是否无头模式运行 |\n| browser_type | str | \"chromium\" | 浏览器类型（chromium/firefox/webkit） |\n| proxy_config | ProxyConfig | None | 代理配置对象 |\n| ssl_config | SSLConfig | None | SSL证书配置 |\n| user_agent | str | None | 自定义User-Agent |\n| viewport | dict | {\"width\": 1920, \"height\": 1080} | 视口大小 |\n| args | list | [] | 额外的浏览器启动参数 |\n| ignoreHTTPSErrors | bool | False | 是否忽略HTTPS错误 |\n| java_script_enabled | bool | True | 是否启用JavaScript |\n\n资料来源：[browser_manager.py:1-100]()\n\n### BrowserAdapter\n\nBrowserAdapter 提供了浏览器操作的高级抽象接口，封装了常见的浏览器交互操作。\n\n**核心功能：**\n- 页面导航和导航控制\n- 元素选择和交互\n- 截图和PDF生成\n- 控制台日志捕获\n- 网络请求拦截\n\n```python\nclass BrowserAdapter:\n def __init__(self, config: BrowserConfig):\n self.config = config\n self.browser = None\n self.context = None\n self.page = None\n```\n\n资料来源：[browser_adapter.py:1-50]()\n\n### BrowserProfiler\n\nBrowserProfiler 用于浏览器性能分析和会话追踪，帮助诊断浏览器行为和性能问题。\n\n**功能特性：**\n- 记录浏览器启动时间\n- 追踪页面加载性能\n- 统计资源使用情况\n- 生成性能报告\n\n```mermaid\ngraph TD\n A[开始分析] --> B[捕获事件]\n B --> C{事件类型}\n C --> D[性能指标]\n C --> E[资源加载]\n C --> F[控制台日志]\n D --> G[生成报告]\n E --> G\n F --> G\n```\n\n资料来源：[browser_profiler.py:1-80]()\n\n## 代理配置\n\n### ProxyConfig 数据模型\n\n```python\nclass ProxyConfig:\n server: str # 代理服务器地址，格式: protocol://host:port\n username: str # 认证用户名（可选）\n password: str # 认证密码（可选）\n bypass_list: list # 绕过代理的地址列表（可选）\n```\n\n**支持的代理协议：**\n\n| 协议 | 格式示例 | 支持情况 |\n|------|----------|----------|\n| HTTP | http://proxy.example.com:8080 | ✅ 完全支持 |\n| HTTPS | https://proxy.example.com:8080 | ✅ 完全支持 |\n| SOCKS4 | socks4://proxy.example.com:1080 | ✅ 完全支持 |\n| SOCKS5 | socks5://proxy.example.com:1080 | ✅ 完全支持 |\n\n### ProxyStrategy\n\nProxyStrategy 实现了多种代理策略，支持自动代理切换和负载均衡。\n\n```mermaid\ngraph TD\n A[请求发起] --> B{代理策略选择}\n B --> C[轮询策略]\n B --> D[随机策略]\n B --> E[故障转移策略]\n C --> F[选择代理]\n D --> F\n E --> F\n F --> G[应用代理]\n G --> H{请求结果}\n H -->|成功| I[记录成功]\n H -->|失败| J[重试或切换]\n J --> F\n```\n\n**代理策略类型：**\n\n| 策略名称 | 说明 | 适用场景 |\n|----------|------|----------|\n| RoundRobinStrategy | 轮询策略，依次使用每个代理 | 负载均衡 |\n| RandomStrategy | 随机选择代理 | 避免请求模式被检测 |\n| FailoverStrategy | 故障转移，主代理失败时切换 | 高可用性 |\n| PriorityStrategy | 按优先级顺序尝试 | 优先使用高速代理 |\n\n资料来源：[proxy_strategy.py:1-120]()\n\n### 代理配置示例\n\n```python\nfrom crawl4ai import BrowserConfig, ProxyConfig\n\n# 简单代理配置\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\"\n)\n\n# 带认证的代理配置\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\",\n username=\"user123\",\n password=\"pass456\"\n)\n\n# 配置绕过列表\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\",\n bypass_list=[\"localhost\", \"*.internal\"]\n)\n\nbrowser_config = BrowserConfig(\n proxy_config=proxy_config,\n headless=True\n)\n```\n\n## SSL 证书处理\n\n### SSLConfig 数据模型\n\n```python\nclass SSLConfig:\n ignore_ssl_errors: bool # 是否忽略SSL错误\n client_cert: str # 客户端证书路径\n client_key: str # 客户端私钥路径\n ca_cert: str # CA证书路径\n```\n\n**配置参数表：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| ignore_ssl_errors | bool | False | 忽略证书验证错误 |\n| client_cert | str | None | PEM格式客户端证书路径 |\n| client_key | str | None | PEM格式私钥路径 |\n| ca_cert | str | None | CA证书文件路径 |\n| accept_insecure_certs | bool | False | 接受无效证书 |\n\n资料来源：[ssl_certificate.py:1-60]()\n\n### 使用场景\n\n**场景一：忽略证书错误**\n\n适用于测试环境或内部网络：\n\n```python\nssl_config = SSLConfig(ignore_ssl_errors=True)\nbrowser_config = BrowserConfig(ssl_config=ssl_config)\n```\n\n**场景二：使用客户端证书**\n\n适用于需要双向SSL认证的场景：\n\n```python\nssl_config = SSLConfig(\n client_cert=\"/path/to/cert.pem\",\n client_key=\"/path/to/key.pem\",\n ca_cert=\"/path/to/ca.pem\"\n)\nbrowser_config = BrowserConfig(ssl_config=ssl_config)\n```\n\n## 用户代理管理\n\n### UserAgentGenerator\n\nUserAgentGenerator 负责生成和管理用户代理字符串，支持多种配置选项。\n\n```mermaid\ngraph TD\n A[UA生成请求] --> B{生成模式}\n B --> C[固定UA]\n B --> D[随机UA]\n B --> E[真实浏览器UA]\n C --> F[返回UA字符串]\n D --> G[选择设备类型]\n G --> F\n E --> H[模拟真实环境]\n H --> F\n```\n\n**生成模式：**\n\n| 模式 | 说明 | 示例 |\n|------|------|------|\n| fixed | 使用指定的固定UA | \"Mozilla/5.0...\" |\n| random | 从预设列表随机选择 | 随机桌面浏览器UA |\n| real_browser | 模拟真实浏览器环境 | Chrome on Windows |\n| mobile | 移动设备UA | iPhone Safari |\n\n资料来源：[user_agent_generator.py:1-90]()\n\n### 预设浏览器类型\n\n| 浏览器 | 平台 | User-Agent 示例 |\n|--------|------|------------------|\n| Chrome | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 |\n| Chrome | macOS | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 |\n| Chrome | Linux | Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 |\n| Firefox | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 |\n| Safari | iOS | Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) |\n| Edge | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/115.0.0.0 |\n\n### 使用示例\n\n```python\nfrom crawl4ai import BrowserConfig, UserAgentGenerator\n\n# 使用随机UA\nua_generator = UserAgentGenerator(mode=\"random\")\nbrowser_config = BrowserConfig(\n user_agent=ua_generator.generate()\n)\n\n# 使用固定UA\nbrowser_config = BrowserConfig(\n user_agent=\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36\"\n)\n\n# 使用真实浏览器模拟\nua_generator = UserAgentGenerator(mode=\"real_browser\")\nbrowser_config = BrowserConfig(\n user_agent=ua_generator.generate(device_type=\"mobile\")\n)\n```\n\n## 浏览器配置工作流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant BM as BrowserManager\n participant PA as ProxyAdapter\n participant SS as SSLHandler\n participant UA as UserAgentGenerator\n participant Browser as Playwright Browser\n\n User->>BM: 创建BrowserConfig\n BM->>UA: 请求User-Agent\n UA-->>BM: 返回UA字符串\n BM->>PA: 应用代理配置\n PA->>BM: 代理配置完成\n BM->>SS: 配置SSL设置\n SS-->>BM: SSL配置完成\n BM->>Browser: 启动浏览器实例\n Browser-->>BM: 浏览器就绪\n BM-->>User: 返回配置好的浏览器\n```\n\n## 高级配置选项\n\n### 浏览器启动参数\n\n```python\nbrowser_config = BrowserConfig(\n args=[\n \"--disable-blink-features=AutomationControlled\",\n \"--disable-dev-shm-usage\",\n \"--no-sandbox\",\n \"--disable-setuid-sandbox\",\n \"--disable-gpu\",\n \"--disable-web-security\",\n \"--disable-features=IsolateOrigins,site-per-process\"\n ]\n)\n```\n\n**常用启动参数表：**\n\n| 参数 | 说明 | 风险等级 |\n|------|------|----------|\n| --disable-blink-features=AutomationControlled | 隐藏自动化特征 | 低 |\n| --disable-dev-shm-usage | 避免共享内存问题 | 低 |\n| --no-sandbox | 禁用沙箱（Docker环境需要） | 高 |\n| --disable-setuid-sandbox | 禁用setuid沙箱 | 中 |\n| --disable-gpu | 禁用GPU加速 | 低 |\n| --disable-web-security | 禁用Web安全 | 高 |\n| --headless=new | 使用新版无头模式 | 低 |\n\n### 上下文隔离配置\n\n```python\nbrowser_config = BrowserConfig(\n context_options={\n \"locale\": \"zh-CN\",\n \"timezone_id\": \"Asia/Shanghai\",\n \"viewport\": {\"width\": 1920, \"height\": 1080},\n \"color_scheme\": \"dark\",\n \"extra_http_headers\": {\n \"Accept-Language\": \"zh-CN,zh;q=0.9\",\n \"Accept-Encoding\": \"gzip, deflate, br\"\n }\n }\n)\n```\n\n## 最佳实践\n\n### 配置优先级\n\n1. **安全优先**：在生产环境中禁用 `--disable-web-security`\n2. **性能优化**：合理设置视口大小，避免不必要的大图渲染\n3. **稳定性**：在Docker环境中添加 `--no-sandbox` 和 `--disable-dev-shm-usage`\n4. **反检测**：结合使用随机UA、真实视口和代理\n\n### 配置验证清单\n\n- [ ] 确认代理服务器可达性\n- [ ] 验证SSL证书配置正确\n- [ ] 测试UA字符串有效性\n- [ ] 检查浏览器参数兼容性\n- [ ] 验证上下文配置生效\n\n## 相关文件\n\n| 文件路径 | 功能描述 |\n|----------|----------|\n| [browser_manager.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_manager.py) | 浏览器生命周期管理 |\n| [browser_adapter.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_adapter.py) | 浏览器操作接口抽象 |\n| [browser_profiler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_profiler.py) | 性能分析和追踪 |\n| [proxy_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/proxy_strategy.py) | 代理策略实现 |\n| [ssl_certificate.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/ssl_certificate.py) | SSL证书处理 |\n| [user_agent_generator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/user_agent_generator.py) | User-Agent生成管理 |\n\n---\n\n\n\n## 高级功能\n\n### 相关页面\n\n相关主题：[浏览器配置与代理](#page-browser-config), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/antibot_detector.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/antibot_detector.py)\n- [crawl4ai/adaptive_crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/adaptive_crawler.py)\n- [crawl4ai/js_snippet/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/js_snippet/__init__.py)\n- [crawl4ai/link_preview.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/link_preview.py)\n- [crawl4ai/async_dispatcher.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_dispatcher.py)\n\n\n# 高级功能\n\n## 概述\n\ncrawl4ai的高级功能模块提供了企业级网页爬取的增强能力，包括反机器人检测规避、自适应爬取策略、JavaScript动态内容注入、链接预览生成以及异步并发调度等核心功能。这些模块协同工作，使爬虫能够应对复杂的网络环境和严格的反爬机制，同时保持高效的资源利用率。\n\n## 架构总览\n\n```mermaid\ngraph TD\n A[用户请求] --> B[async_dispatcher 异步调度器]\n B --> C[adaptive_crawler 自适应爬虫]\n C --> D[antibot_detector 反机器人检测]\n C --> E[js_snippet JavaScript注入]\n E --> F[动态内容渲染]\n D --> G{检测结果}\n G -->|通过| F\n G -->|触发| H[策略调整]\n H --> C\n F --> I[link_preview 链接预览生成]\n I --> J[结果输出]\n```\n\n## 反机器人检测模块\n\n### 功能定位\n\n`antibot_detector` 模块负责检测目标网站是否部署了反机器人机制，并提供相应的规避建议。该模块通过分析响应特征、Cookie行为、JavaScript挑战等信号来判断当前爬取是否触发了反爬防护。\n\n### 核心检测机制\n\n| 检测类型 | 描述 | 判定依据 |\n|---------|------|----------|\n| 指纹检测 | 识别浏览器指纹特征缺失 | User-Agent、Canvas、WebGL |\n| 行为检测 | 分析异常访问模式 | 请求频率、访问路径 |\n| JavaScript挑战 | 检测JS质询页面 | 验证码、Cookie重置 |\n| 蜜罐检测 | 识别隐藏链接陷阱 | CSS隐藏元素、点击诱饵 |\n\n### 集成方式\n\n该模块与自适应爬虫深度集成，当检测到反机器人信号时，会自动触发爬取策略的动态调整流程。\n\n资料来源：[crawl4ai/antibot_detector.py:1-50](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/antibot_detector.py)\n\n## 自适应爬虫\n\n### 设计理念\n\n`adaptive_crawler` 模块实现了智能化的爬取策略调整机制，能够根据目标网站的响应特征自动优化爬取参数。这种自适应能力使系统能够在不同网站环境中保持稳定的爬取效率。\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|--------|------|\n| `max_retries` | int | 3 | 最大重试次数 |\n| `retry_delay` | float | 1.0 | 重试间隔（秒） |\n| `timeout` | int | 30 | 请求超时时间 |\n| `use_cache` | bool | True | 启用缓存机制 |\n\n### 策略调整流程\n\n```mermaid\ngraph LR\n A[发起请求] --> B{响应状态}\n B -->|200| C[成功解析]\n B -->|429| D[触发限流]\n B -->|403| E[反爬拦截]\n B -->|5xx| F[服务器错误]\n D --> G[增加延迟]\n E --> H[启用JS渲染]\n F --> I[指数退避]\n G --> A\n H --> C\n I --> A\n```\n\n### 动态适应策略\n\n自适应爬虫支持以下策略模式：\n\n1. **保守模式**：优先降低触发反爬的概率，牺牲部分爬取速度\n2. **平衡模式**：在速度和成功率之间取得平衡\n3. **激进模式**：最大化爬取速度，适用于已知友好的网站\n\n资料来源：[crawl4ai/adaptive_crawler.py:1-80](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/adaptive_crawler.py)\n\n## JavaScript 代码注入\n\n### 模块职责\n\n`js_snippet` 模块提供了在页面加载后执行自定义JavaScript代码的能力，这对于处理单页应用（SPA）和需要客户端渲染的内容至关重要。该模块支持注入预定义的代码片段以及用户自定义的JavaScript逻辑。\n\n### 预定义代码片段\n\n| 片段名称 | 用途 | 典型场景 |\n|---------|------|----------|\n| `scroll_to_bottom` | 滚动至页面底部 | 触发懒加载内容 |\n| `extract_dynamic_content` | 提取动态渲染内容 | 获取JS生成的数据 |\n| `wait_for_element` | 等待特定元素加载 | 确保关键内容就绪 |\n| `simulate_human_behavior` | 模拟人类行为 | 降低被检测概率 |\n\n### 执行上下文\n\nJavaScript代码在浏览器上下文中执行，可以访问和操作DOM、发起AJAX请求、修改页面状态等。该功能基于Playwright的页面评估机制实现。\n\n资料来源：[crawl4ai/js_snippet/__init__.py:1-30](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/js_snippet/__init__.py)\n\n## 链接预览生成\n\n### 功能概述\n\n`link_preview` 模块负责生成网页的链接预览信息，包括标题、描述、图片和元数据等。该功能对于构建URL目录、sitemap生成、内容索引等场景非常有用。\n\n### 预览数据结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `title` | string | 页面标题 |\n| `description` | string | meta描述内容 |\n| `image` | string | OG/Twitter图片URL |\n| `favicon` | string | 网站图标 |\n| `domain` | string | 域名提取 |\n| `language` | string | 页面语言 |\n\n### 生成流程\n\n```mermaid\ngraph TD\n A[获取页面HTML] --> B[解析Meta标签]\n B --> C[提取OG属性]\n C --> D[获取Favicon]\n D --> E[生成预览对象]\n E --> F[缓存结果]\n```\n\n资料来源：[crawl4ai/link_preview.py:1-60](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/link_preview.py)\n\n## 异步调度器\n\n### 设计目标\n\n`async_dispatcher` 模块实现了高效的异步任务调度系统，支持并发控制、优先级管理、任务去重等企业级特性。该模块基于Python的asyncio框架构建，能够充分利用系统资源提升整体吞吐量。\n\n### 核心功能\n\n| 功能 | 描述 |\n|-----|------|\n| 并发限制 | 限制同时进行的爬取任务数量 |\n| 任务队列 | 支持优先级排序的任务队列 |\n| 失败重试 | 自动化失败任务重试机制 |\n| 速率控制 | 防止对目标网站造成过大压力 |\n\n### 调度策略\n\n异步调度器支持多种任务调度策略：\n\n1. **FIFO（先进先出）**：按提交顺序处理任务\n2. **优先级调度**：高优先级任务优先处理\n3. **批量处理**：聚合多个相似请求减少开销\n\n### 并发控制机制\n\n```mermaid\ngraph TD\n A[任务提交] --> B{检查并发数}\n B -->|未达上限| C[立即执行]\n B -->|已达上限| D[加入等待队列]\n C --> E[任务完成]\n D --> F[等待释放]\n F --> B\n E --> G[更新统计]\n G --> H{队列非空?}\n H -->|是| B\n```\n\n资料来源：[crawl4ai/async_dispatcher.py:1-100](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_dispatcher.py)\n\n## 模块协作流程\n\n### 完整爬取工作流\n\n```mermaid\ngraph TD\n A[用户请求] --> B[async_dispatcher 接收任务]\n B --> C[adaptive_crawler 创建爬取任务]\n C --> D{antibot_detector 预检}\n D -->|安全| E[执行爬取]\n D -->|风险| F[应用规避策略]\n F --> E\n E --> G{需要JS渲染?}\n G -->|是| H[js_snippet 注入脚本]\n H --> I[等待渲染完成]\n G -->|否| J[直接提取内容]\n I --> J\n J --> K[link_preview 生成预览]\n K --> L[结果汇总]\n L --> M[返回用户]\n```\n\n### 错误处理与恢复\n\n各模块均实现了完善的错误处理机制，当某个环节出现异常时，系统会自动触发降级策略或重试流程，确保整体任务的可靠性。\n\n## 配置建议\n\n### 生产环境推荐配置\n\n```python\n{\n \"adaptive_crawler\": {\n \"max_retries\": 5,\n \"timeout\": 45,\n \"use_cache\": True\n },\n \"async_dispatcher\": {\n \"max_concurrent\": 10,\n \"rate_limit\": 30 # 每分钟请求数\n },\n \"antibot_detector\": {\n \"strict_mode\": False,\n \"auto_adjust\": True\n }\n}\n```\n\n### 性能优化要点\n\n1. **合理设置并发数**：根据目标网站的承受能力调整\n2. **启用缓存**：减少重复请求，提升效率\n3. **适当延迟**：避免触发频率限制\n4. **监控日志**：及时发现和处理异常情况\n\n## 相关资源\n\n- 基础使用文档：查看项目主README\n- API参考：查看各模块具体实现\n- 示例代码：参考项目中的example目录\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：unclecode/crawl4ai\n\n摘要：发现 21 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing。\n\n## 1. 安装坑 · 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: arun() and arun_many() type hinting needs fixing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d3b6cfd3700147f690e0e65875f15424 | https://github.com/unclecode/crawl4ai/issues/1898 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason is shown\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad61b108bf894cc286ca7966e8c86758 | https://github.com/unclecode/crawl4ai/issues/1949 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ee99f5d72f143f4b064732cc19e0c85 | https://github.com/unclecode/crawl4ai/issues/1963 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7fa967632a948008efbc182d1f2c96b | https://github.com/unclecode/crawl4ai/issues/1938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e9fbf659fbb40aba437886a87f8e2d7 | https://github.com/unclecode/crawl4ai/issues/1962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af29278fd7294d4a8f0f6f37ab987b5c | https://github.com/unclecode/crawl4ai/issues/1968 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_97d44cedb21a4908a7743fde11209954 | https://github.com/unclecode/crawl4ai/issues/1950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ae45861377894b99a57d6bbdc06af313 | https://github.com/unclecode/crawl4ai/issues/1959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.1:Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.1:Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ae9133fff54443b712725f51769fa1 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：v0.7.2: CI/CD & Dependency Optimization Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.2: CI/CD & Dependency Optimization Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14954e0431ca426ebeaa4bb31778d4af | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 来源证据：[Bug]: Markdown export loses heading hierarchy and table structure\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Markdown export loses heading hierarchy and table structure\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c3eac8ab81e34bf3b6cc050f7f8e9826 | https://github.com/unclecode/crawl4ai/issues/1964 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:798201435 | https://github.com/unclecode/crawl4ai | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：Release v0.7.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.3\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e2b75670cbcc4814a86423818b9f6f48 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：Release v0.7.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.5\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_056d1470d7534cacb39eeb894e054496 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Release v0.7.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.7\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e157445f88744795b5c6234783eca692 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：[Bug]: Markdown text extraction drops text when element contains empty elements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Markdown text extraction drops text when element contains empty elements\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dffa926853d147ebb487a03fdfd1818e | https://github.com/unclecode/crawl4ai/issues/1966 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | release_recency=unknown\n\n\n",
"markdown_key": "crawl4ai",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:798201435",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/unclecode/crawl4ai"
},
{
"evidence_id": "art_ad7837973e204acb98fc90e9f4b59193",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/unclecode/crawl4ai#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "crawl4ai 说明书",
"toc": [
"https://github.com/unclecode/crawl4ai 项目说明书",
"目录",
"项目概览",
"什么是 crawl4ai",
"核心设计理念",
"技术架构",
"项目结构",
"主要功能特性",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "1debe5f5fcc118ced10826a1040a81f9b77e9255",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"Dockerfile",
"README.md",
"docker-compose.yml",
"uv.lock",
"requirements.txt",
"docs/RELEASE_NOTES_v0.8.0.md",
"docs/releases_review/v0_7_0_features_demo.py",
"docs/releases_review/v0.3.74.overview.py",
"docs/releases_review/demo_v0.7.7.py",
"docs/releases_review/v0.7.5_docker_hooks_demo.py",
"docs/releases_review/v0_4_3b2_features_demo.py",
"docs/releases_review/demo_v0.8.5.py",
"docs/releases_review/demo_v0.7.6.py",
"docs/releases_review/demo_v0.7.0.py",
"docs/releases_review/demo_v0.8.0.py",
"docs/releases_review/demo_v0.7.8.py",
"docs/releases_review/v0_4_24_walkthrough.py",
"docs/releases_review/crawl4ai_v0_7_0_showcase.py",
"docs/releases_review/demo_v0.7.5.py",
"docs/migration/v0.8.0-upgrade-guide.md",
"docs/blog/release-v0.7.7.md",
"docs/blog/release-v0.7.8.md",
"docs/blog/release-v0.7.5.md",
"docs/blog/release-v0.7.1.md",
"docs/blog/release-v0.8.0.md",
"docs/blog/release-v0.7.3.md",
"docs/blog/release-v0.8.5.md",
"docs/blog/release-v0.7.4.md",
"docs/blog/release-v0.7.0.md",
"docs/blog/release-v0.7.6.md",
"docs/tutorials/coming_soon.md",
"docs/md_v2/index.md",
"docs/md_v2/complete-sdk-reference.md",
"docs/md_v2/CONTRIBUTING.md",
"docs/md_v2/stats.md",
"docs/examples/dispatcher_example.py",
"docs/examples/link_head_extraction_example.py",
"docs/examples/docker_webhook_example.py",
"docs/examples/README_BUILTIN_BROWSER.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# crawl4ai - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 crawl4ai 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install -U crawl4ai` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pip install crawl4ai --pre` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install crawl4ai` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0014` supported 0.86\n- `pip install crawl4ai[sync]` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `git clone https://github.com/unclecode/crawl4ai.git` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `pip install -e . # Basic installation in editable mode` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pip install -e \".[torch]\" # With PyTorch features` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `pip install -e \".[transformer]\" # With Transformer features` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `pip install -e \".[cosine]\" # With cosine similarity features` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `pip install -e \".[sync]\" # With synchronous crawling (Selenium)` 证据：`README.md` Claim：`clm_0012` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0015` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0016` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：783\n- 重要文件覆盖：40/783\n- 证据索引条目：80\n- 角色 / Skill 条目：79\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 crawl4ai 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 crawl4ai 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 crawl4ai 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 79 个角色 / Skill / 项目文档条目。\n\n- **GitHub Actions Workflows Documentation**（project_doc）：GitHub Actions Workflows Documentation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/workflows/docs/README.md`\n- **Crawl4AI Prospect‑Wizard – step‑by‑step guide**（project_doc）：Crawl4AI Prospect‑Wizard – step‑by‑step guide 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/apps/linkdin/README.md`\n- **Adaptive Crawling Examples**（project_doc）：This directory contains examples demonstrating various aspects of Crawl4AI's Adaptive Crawling feature. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/adaptive_crawling/README.md`\n- **Amazon R2D2 Product Search Example**（project_doc）：A real-world demonstration of Crawl4AI's multi-step crawling with LLM-generated automation scripts. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/c4a_script/amazon_example/README.md`\n- **C4A-Script Interactive Tutorial**（project_doc）：A comprehensive web-based tutorial for learning and experimenting with C4A-Script - Crawl4AI's visual web automation language. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/c4a_script/tutorial/README.md`\n- **Web Scraper API with Custom Model Support**（project_doc）：Web Scraper API with Custom Model Support 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/website-to-api/README.md`\n- **C4A-Script Interactive Tutorial**（project_doc）：A comprehensive web-based tutorial for learning and experimenting with C4A-Script - Crawl4AI's visual web automation language. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/c4a-script/README.md`\n- **Crawl4AI Chrome Extension**（project_doc）：Visual extraction tools for Crawl4AI - Click to extract data and content from any webpage! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/crawl4ai-assistant/README.md`\n- **Crawl4AI Marketplace**（project_doc）：A terminal-themed marketplace for tools, integrations, and resources related to Crawl4AI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/marketplace/README.md`\n- **Contributing to Crawl4AI**（project_doc）：Welcome to the Crawl4AI project! As an open-source library for web crawling and AI integration, we value contributions from the community. This guide explains our branching strategy, how to contribute effectively, and the overall release process. Our goal is to maintain a stable, collaborative environment where bug fixes, features, and improvements can be integrated smoothly while allowing for experimental developme… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/CONTRIBUTING.md`\n- **🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper.**（project_doc）：🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Software Bill of Materials SBOM**（project_doc）：This directory contains the CycloneDX SBOM for the project. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sbom/README.md`\n- **Crawl4AI Docker Guide 🐳**（project_doc）：Table of Contents - Prerequisites prerequisites - Installation installation - Option 1: Using Pre-built Docker Hub Images Recommended option-1-using-pre-built-docker-hub-images-recommended - Option 2: Using Docker Compose option-2-using-docker-compose - Option 3: Manual Local Build & Run option-3-manual-local-build--run - Dockerfile Parameters dockerfile-parameters - Using the API using-the-api - Playground Interfac… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`deploy/docker/README.md`\n- **Crawl4AI Stress Testing and Benchmarking**（project_doc）：Crawl4AI Stress Testing and Benchmarking 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/memory/README.md`\n- **Contributing to Crawl4AI**（project_doc）：Welcome to the Crawl4AI project! As an open-source library for web crawling and AI integration, we value contributions from the community. This guide explains our branching strategy, how to contribute effectively, and the overall release process. Our goal is to maintain a stable, collaborative environment where bug fixes, features, and improvements can be integrated smoothly while allowing for experimental developme… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Crawl4AI v0.8.0 Release Notes**（project_doc）：Release Date : January 2026 Previous Version : v0.7.6 Status : Release Candidate 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/RELEASE_NOTES_v0.8.0.md`\n- **Workflow Architecture Documentation**（project_doc）：Workflow Architecture Documentation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/workflows/docs/ARCHITECTURE.md`\n- **Workflow Quick Reference**（project_doc）：Standard Release bash 1. Update version vim crawl4ai/ version .py Set to \"1.2.3\" 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/workflows/docs/WORKFLOW_REFERENCE.md`\n- **🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update**（project_doc）：🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.0.md`\n- **🛠️ Crawl4AI v0.7.1: Minor Cleanup Update**（project_doc）：🛠️ Crawl4AI v0.7.1: Minor Cleanup Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.1.md`\n- **🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update**（project_doc）：🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.3.md`\n- **🚀 Crawl4AI v0.7.4: The Intelligent Table Extraction & Performance Update**（project_doc）：🚀 Crawl4AI v0.7.4: The Intelligent Table Extraction & Performance Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.4.md`\n- **🚀 Crawl4AI v0.7.5: The Docker Hooks & Security Update**（project_doc）：🚀 Crawl4AI v0.7.5: The Docker Hooks & Security Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.5.md`\n- **Crawl4AI v0.7.6 Release Notes**（project_doc）：I'm excited to announce Crawl4AI v0.7.6, featuring a complete webhook infrastructure for the Docker job queue API! This release eliminates polling and brings real-time notifications to both crawling and LLM extraction workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.6.md`\n- **🚀 Crawl4AI v0.7.7: The Self-Hosting & Monitoring Update**（project_doc）：🚀 Crawl4AI v0.7.7: The Self-Hosting & Monitoring Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.7.md`\n- **Crawl4AI v0.7.8: Stability & Bug Fix Release**（project_doc）：Crawl4AI v0.7.8: Stability & Bug Fix Release 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.8.md`\n- **Crawl4AI v0.8.0 Release Notes**（project_doc）：Release Date : January 2026 Previous Version : v0.7.6 Status : Release Candidate 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.8.0.md`\n- **Crawl4AI v0.8.5: Anti-Bot, Shadow DOM & 60+ Bug Fixes**（project_doc）：Crawl4AI v0.8.5: Anti-Bot, Shadow DOM & 60+ Bug Fixes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.8.5.md`\n- **browser manager.py**（project_doc）：Function What it does --- --- ManagedBrowser.build browser flags Returns baseline Chromium CLI flags, disables GPU and sandbox, plugs locale, timezone, stealth tweaks, and any extras from BrowserConfig . ManagedBrowser. init Stores config and logger, creates temp dir, preps internal state. ManagedBrowser.start Spawns or connects to the Chromium process, returns its CDP endpoint plus the subprocess.Popen handle. Mana… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/codebase/browser.md`\n- **cli.py command surface**（project_doc）：Command Inputs / flags What it does --- --- --- profiles none Opens the interactive profile manager, lets you list, create, delete saved browser profiles that live in ~/.crawl4ai/profiles . browser status – Prints whether the always-on builtin browser is running, shows its CDP URL, PID, start time. browser stop – Kills the builtin browser and deletes its status file. browser view --url, -u URL optional Pops a visibl… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/codebase/cli.md`\n- **🐳 Using Docker Legacy**（project_doc）：Crawl4AI is available as Docker images for easy deployment. You can either pull directly from Docker Hub recommended or build from the repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/deprecated/docker-deployment.md`\n- **Builtin Browser in Crawl4AI**（project_doc）：This document explains the builtin browser feature in Crawl4AI and how to use it effectively. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/README_BUILTIN_BROWSER.md`\n- **Welcome to Crawl4AI! 🚀🤖**（project_doc）：Hi there, Developer! 👋 Here is an example of a research pipeline, where you can share a URL in your conversation with any LLM, and then the context of crawled pages will be used as the context. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/chainlit.md`\n- **Capturing Full-Page Screenshots and PDFs from Massive Webpages with Crawl4AI**（project_doc）：Capturing Full-Page Screenshots and PDFs from Massive Webpages with Crawl4AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/full_page_screenshot_and_pdf_export.md`\n- **Using storage state to Pre-Load Cookies and LocalStorage**（project_doc）：Using storage state to Pre-Load Cookies and LocalStorage 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/storage_state_tutorial.md`\n- **Tutorial: Clicking Buttons to Load More Content with Crawl4AI**（project_doc）：Tutorial: Clicking Buttons to Load More Content with Crawl4AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/tutorial_dynamic_clicks.md`\n- **🔬 Building an AI Research Assistant with Crawl4AI: Smart URL Discovery**（project_doc）：🔬 Building an AI Research Assistant with Crawl4AI: Smart URL Discovery 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/url_seeder/tutorial_url_seeder.md`\n- **Advanced Adaptive Strategies**（project_doc）：While the default adaptive crawling configuration works well for most use cases, understanding the underlying strategies and scoring mechanisms allows you to fine-tune the crawler for specific domains and requirements. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/adaptive-strategies.md`\n- **Overview of Some Important Advanced Features**（project_doc）：Overview of Some Important Advanced Features Proxy, PDF, Screenshot, SSL, Headers, & Storage State 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/advanced-features.md`\n- **Anti-Bot Detection & Fallback**（project_doc）：When crawling sites protected by anti-bot systems Akamai, Cloudflare, PerimeterX, DataDome, Imperva, etc. , requests often get blocked with CAPTCHAs, 403 responses, or empty pages. Crawl4AI provides a layered retry and fallback system that automatically detects blocking and escalates through multiple strategies until content is retrieved. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/anti-bot-and-fallback.md`\n- **Crawl Dispatcher**（project_doc）：We’re excited to announce a Crawl Dispatcher module that can handle thousands of crawling tasks simultaneously. By efficiently managing system resources memory, CPU, network , this dispatcher ensures high-performance data extraction at scale. It also provides real-time monitoring of each crawler’s status, memory usage, and overall progress. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/crawl-dispatcher.md`\n- **Download Handling in Crawl4AI**（project_doc）：This guide explains how to use Crawl4AI to handle file downloads during crawling. You'll learn how to trigger downloads, specify download locations, and access downloaded files. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/file-downloading.md`\n- **Hooks & Auth in AsyncWebCrawler**（project_doc）：Crawl4AI’s hooks let you customize the crawler at specific points in the pipeline: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/hooks-auth.md`\n- **Preserve Your Identity with Crawl4AI**（project_doc）：Preserve Your Identity with Crawl4AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/identity-based-crawling.md`\n- **Handling Lazy-Loaded Images**（project_doc）：Many websites now load images lazily as you scroll. If you need to ensure they appear in your final crawl and in result.media , consider: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/lazy-loading.md`\n- **Advanced Multi-URL Crawling with Dispatchers**（project_doc）：Advanced Multi-URL Crawling with Dispatchers 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/multi-url-crawling.md`\n- **Network Requests & Console Message Capturing**（project_doc）：Network Requests & Console Message Capturing 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/network-console-capture.md`\n- **PDF Processing Strategies**（project_doc）：Crawl4AI provides specialized strategies for handling and extracting content from PDF files. These strategies allow you to seamlessly integrate PDF processing into your crawling workflows, whether the PDFs are hosted online or stored locally. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/pdf-parsing.md`\n- **Session Management**（project_doc）：Session management in Crawl4AI is a powerful feature that allows you to maintain state across multiple requests, making it particularly suitable for handling complex multi-step crawling tasks. It enables you to reuse the same browser tab or page object across sequential actions and crawls, which is beneficial for: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/session-management.md`\n- **SSLCertificate Reference**（project_doc）：The SSLCertificate class encapsulates an SSL certificate’s data and allows exporting it in various formats PEM, DER, JSON, or text . It’s used within Crawl4AI whenever you set fetch ssl certificate=True in your CrawlerRunConfig . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/ssl-certificate.md`\n- **Undetected Browser Mode**（project_doc）：Crawl4AI offers two powerful anti-bot features to help you access websites with bot detection: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/undetected-browser.md`\n- **Virtual Scroll**（project_doc）：Modern websites increasingly use virtual scrolling also called windowed rendering or viewport rendering to handle large datasets efficiently. This technique only renders visible items in the DOM, replacing content as users scroll. Popular examples include Twitter's timeline, Instagram's feed, and many data tables. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/virtual-scroll.md`\n- **AdaptiveCrawler**（project_doc）：The AdaptiveCrawler class implements intelligent web crawling that automatically determines when sufficient information has been gathered to answer a query. It uses a three-layer scoring system to evaluate coverage, consistency, and saturation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/adaptive-crawler.md`\n- **arun Parameter Guide New Approach**（project_doc）：In Crawl4AI’s latest configuration model, nearly all parameters that once went directly to arun are now part of CrawlerRunConfig . When calling arun , you provide: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/arun.md`\n- **arun many ... Reference**（project_doc）：Note : This function is very similar to arun ./arun.md but focused on concurrent or batch crawling. If you’re unfamiliar with arun usage, please read that doc first, then review this for differences. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/arun_many.md`\n- **AsyncWebCrawler**（project_doc）：The AsyncWebCrawler is the core class for asynchronous web crawling in Crawl4AI. You typically create it once , optionally customize it with a BrowserConfig e.g., headless, user agent , then run multiple arun calls with different CrawlerRunConfig objects. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/async-webcrawler.md`\n- **C4A-Script API Reference**（project_doc）：Complete reference for all C4A-Script commands, syntax, and advanced features. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/c4a-script-reference.md`\n- **CrawlResult Reference**（project_doc）：The CrawlResult class encapsulates everything returned after a single crawl operation. It provides the raw or processed content , details on links and media, plus optional metadata like screenshots, PDFs, or extracted JSON . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/crawl-result.md`\n- **digest**（project_doc）：The digest method is the primary interface for adaptive web crawling. It intelligently crawls websites starting from a given URL, guided by a query, and automatically determines when sufficient information has been gathered. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/digest.md`\n- **1. BrowserConfig – Controlling the Browser**（project_doc）：1. BrowserConfig – Controlling the Browser 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/parameters.md`\n- **Extraction & Chunking Strategies API**（project_doc）：Extraction & Chunking Strategies API 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/strategies.md`\n- **🚀 Crawl4AI Interactive Apps**（project_doc）：Welcome to the Crawl4AI Apps Hub - your gateway to interactive tools and demos that make web scraping more intuitive and powerful. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/index.md`\n- **Build**（project_doc）：O Prompt for AI Coding Assistant: Create an Interactive LLM Context Builder Page 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/llmtxt/build.md`\n- **Supercharging Your AI Assistant: My Journey to Better LLM Contexts for crawl4ai**（project_doc）：Supercharging Your AI Assistant: My Journey to Better LLM Contexts for crawl4ai 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/llmtxt/why.md`\n- **Installation 💻**（project_doc）：Crawl4AI offers flexible installation options to suit various use cases. You can install it as a Python package, use it with Docker, or run it as a local server. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/basic/installation.md`\n- **Adaptive Crawling: Building Dynamic Knowledge That Grows on Demand**（project_doc）：Adaptive Crawling: Building Dynamic Knowledge That Grows on Demand 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/articles/adaptive-crawling-revolution.md`\n- **Introducing Event Streams and Interactive Hooks in Crawl4AI**（project_doc）：Introducing Event Streams and Interactive Hooks in Crawl4AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/articles/dockerize_hooks.md`\n- **The LLM Context Protocol: Why Your AI Assistant Needs Memory, Reasoning, and Examples**（project_doc）：The LLM Context Protocol: Why Your AI Assistant Needs Memory, Reasoning, and Examples 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/articles/llm-context-revolution.md`\n- **Solving the Virtual Scroll Puzzle: How Crawl4AI Captures What Others Miss**（project_doc）：Solving the Virtual Scroll Puzzle: How Crawl4AI Captures What Others Miss 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/articles/virtual-scroll-revolution.md`\n- **Crawl4AI Blog**（project_doc）：Welcome to the Crawl4AI blog! Here you'll find detailed release notes, technical insights, and updates about the project. Whether you're looking for the latest improvements or want to dive deep into web crawling techniques, this is the place. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/index.md`\n- **Release Summary for Version 0.4.0 December 1, 2024**（project_doc）：Release Summary for Version 0.4.0 December 1, 2024 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.4.0.md`\n- **Release Summary for Version 0.4.1 December 8, 2024 : Major Efficiency Boosts with New Features!**（project_doc）：Release Summary for Version 0.4.1 December 8, 2024 : Major Efficiency Boosts with New Features! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.4.1.md`\n- **🚀 Crawl4AI 0.4.2 Update: Smarter Crawling Just Got Easier Dec 12, 2024**（project_doc）：🚀 Crawl4AI 0.4.2 Update: Smarter Crawling Just Got Easier Dec 12, 2024 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.4.2.md`\n- **Crawl4AI v0.5.0 Release Notes**（project_doc）：Release Theme: Power, Flexibility, and Scalability 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.5.0.md`\n- **Crawl4AI v0.6.0 Release Notes**（project_doc）：We're excited to announce the release of Crawl4AI v0.6.0 , our biggest and most feature-rich update yet. This version introduces major architectural upgrades, brand-new capabilities for geo-aware crawling, high-efficiency scraping, and real-time streaming support for scalable deployments. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.6.0.md`\n- **🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update**（project_doc）：🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.7.0.md`\n- **🛠️ Crawl4AI v0.7.1: Minor Cleanup Update**（project_doc）：🛠️ Crawl4AI v0.7.1: Minor Cleanup Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.7.1.md`\n- **🚀 Crawl4AI v0.7.2: CI/CD & Dependency Optimization Update**（project_doc）：🚀 Crawl4AI v0.7.2: CI/CD & Dependency Optimization Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.7.2.md`\n- **🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update**（project_doc）：🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.7.3.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **GitHub Actions Workflows Documentation**（documentation）：GitHub Actions Workflows Documentation 证据：`.github/workflows/docs/README.md`\n- **Crawl4AI Prospect‑Wizard – step‑by‑step guide**（documentation）：Crawl4AI Prospect‑Wizard – step‑by‑step guide 证据：`docs/apps/linkdin/README.md`\n- **Adaptive Crawling Examples**（documentation）：This directory contains examples demonstrating various aspects of Crawl4AI's Adaptive Crawling feature. 证据：`docs/examples/adaptive_crawling/README.md`\n- **Amazon R2D2 Product Search Example**（documentation）：A real-world demonstration of Crawl4AI's multi-step crawling with LLM-generated automation scripts. 证据：`docs/examples/c4a_script/amazon_example/README.md`\n- **C4A-Script Interactive Tutorial**（documentation）：A comprehensive web-based tutorial for learning and experimenting with C4A-Script - Crawl4AI's visual web automation language. 证据：`docs/examples/c4a_script/tutorial/README.md`\n- **Web Scraper API with Custom Model Support**（documentation）：Web Scraper API with Custom Model Support 证据：`docs/examples/website-to-api/README.md`\n- **C4A-Script Interactive Tutorial**（documentation）：A comprehensive web-based tutorial for learning and experimenting with C4A-Script - Crawl4AI's visual web automation language. 证据：`docs/md_v2/apps/c4a-script/README.md`\n- **Crawl4AI Chrome Extension**（documentation）：Visual extraction tools for Crawl4AI - Click to extract data and content from any webpage! 证据：`docs/md_v2/apps/crawl4ai-assistant/README.md`\n- **Crawl4AI Marketplace**（documentation）：A terminal-themed marketplace for tools, integrations, and resources related to Crawl4AI. 证据：`docs/md_v2/marketplace/README.md`\n- **Contributing to Crawl4AI**（documentation）：Welcome to the Crawl4AI project! As an open-source library for web crawling and AI integration, we value contributions from the community. This guide explains our branching strategy, how to contribute effectively, and the overall release process. Our goal is to maintain a stable, collaborative environment where bug fixes, features, and improvements can be integrated smoothly while allowing for experimental development. 证据：`docs/md_v2/CONTRIBUTING.md`\n- **🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper.**（documentation）：🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper. 证据：`README.md`\n- **Software Bill of Materials SBOM**（documentation）：This directory contains the CycloneDX SBOM for the project. 证据：`sbom/README.md`\n- **Crawl4AI Docker Guide 🐳**（documentation）：Table of Contents - Prerequisites prerequisites - Installation installation - Option 1: Using Pre-built Docker Hub Images Recommended option-1-using-pre-built-docker-hub-images-recommended - Option 2: Using Docker Compose option-2-using-docker-compose - Option 3: Manual Local Build & Run option-3-manual-local-build--run - Dockerfile Parameters dockerfile-parameters - Using the API using-the-api - Playground Interface playground-interface - Python SDK python-sdk - Understanding Request Schema understanding-request-schema - REST API Examples rest-api-examples - Asynchronous Jobs with Webhooks asynchronous-jobs-with-webhooks - Additional API Endpoints additional-api-endpoints - HTML Extraction… 证据：`deploy/docker/README.md`\n- **Crawl4AI Stress Testing and Benchmarking**（documentation）：Crawl4AI Stress Testing and Benchmarking 证据：`tests/memory/README.md`\n- **Contributing to Crawl4AI**（documentation）：Welcome to the Crawl4AI project! As an open-source library for web crawling and AI integration, we value contributions from the community. This guide explains our branching strategy, how to contribute effectively, and the overall release process. Our goal is to maintain a stable, collaborative environment where bug fixes, features, and improvements can be integrated smoothly while allowing for experimental development. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Crawl4AI v0.8.0 Release Notes**（documentation）：Release Date : January 2026 Previous Version : v0.7.6 Status : Release Candidate 证据：`docs/RELEASE_NOTES_v0.8.0.md`\n- **Workflow Architecture Documentation**（documentation）：Workflow Architecture Documentation 证据：`.github/workflows/docs/ARCHITECTURE.md`\n- **Workflow Quick Reference**（documentation）：Standard Release bash 1. Update version vim crawl4ai/ version .py Set to \"1.2.3\" 证据：`.github/workflows/docs/WORKFLOW_REFERENCE.md`\n- **🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update**（documentation）：🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update 证据：`docs/blog/release-v0.7.0.md`\n- **🛠️ Crawl4AI v0.7.1: Minor Cleanup Update**（documentation）：🛠️ Crawl4AI v0.7.1: Minor Cleanup Update 证据：`docs/blog/release-v0.7.1.md`\n- **🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update**（documentation）：🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update 证据：`docs/blog/release-v0.7.3.md`\n- **🚀 Crawl4AI v0.7.4: The Intelligent Table Extraction & Performance Update**（documentation）：🚀 Crawl4AI v0.7.4: The Intelligent Table Extraction & Performance Update 证据：`docs/blog/release-v0.7.4.md`\n- **🚀 Crawl4AI v0.7.5: The Docker Hooks & Security Update**（documentation）：🚀 Crawl4AI v0.7.5: The Docker Hooks & Security Update 证据：`docs/blog/release-v0.7.5.md`\n- **Crawl4AI v0.7.6 Release Notes**（documentation）：I'm excited to announce Crawl4AI v0.7.6, featuring a complete webhook infrastructure for the Docker job queue API! This release eliminates polling and brings real-time notifications to both crawling and LLM extraction workflows. 证据：`docs/blog/release-v0.7.6.md`\n- **🚀 Crawl4AI v0.7.7: The Self-Hosting & Monitoring Update**（documentation）：🚀 Crawl4AI v0.7.7: The Self-Hosting & Monitoring Update 证据：`docs/blog/release-v0.7.7.md`\n- **Crawl4AI v0.7.8: Stability & Bug Fix Release**（documentation）：Crawl4AI v0.7.8: Stability & Bug Fix Release 证据：`docs/blog/release-v0.7.8.md`\n- **Crawl4AI v0.8.0 Release Notes**（documentation）：Release Date : January 2026 Previous Version : v0.7.6 Status : Release Candidate 证据：`docs/blog/release-v0.8.0.md`\n- **Crawl4AI v0.8.5: Anti-Bot, Shadow DOM & 60+ Bug Fixes**（documentation）：Crawl4AI v0.8.5: Anti-Bot, Shadow DOM & 60+ Bug Fixes 证据：`docs/blog/release-v0.8.5.md`\n- **browser manager.py**（documentation）：Function What it does --- --- ManagedBrowser.build browser flags Returns baseline Chromium CLI flags, disables GPU and sandbox, plugs locale, timezone, stealth tweaks, and any extras from BrowserConfig . ManagedBrowser. init Stores config and logger, creates temp dir, preps internal state. ManagedBrowser.start Spawns or connects to the Chromium process, returns its CDP endpoint plus the subprocess.Popen handle. ManagedBrowser. initial startup check Pings the CDP endpoint once to be sure the browser is alive, raises if not. ManagedBrowser. monitor browser process Async-loops on the subprocess, logs exits or crashes, restarts if policy allows. ManagedBrowser. get browser path WIP Old helper t… 证据：`docs/codebase/browser.md`\n- **cli.py command surface**（documentation）：Command Inputs / flags What it does --- --- --- profiles none Opens the interactive profile manager, lets you list, create, delete saved browser profiles that live in ~/.crawl4ai/profiles . browser status – Prints whether the always-on builtin browser is running, shows its CDP URL, PID, start time. browser stop – Kills the builtin browser and deletes its status file. browser view --url, -u URL optional Pops a visible window of the builtin browser, navigates to URL or about:blank . config list – Dumps every global setting, showing current value, default, and description. config get key Prints the value of a single setting, falls back to default if unset. config set key value Persists a new v… 证据：`docs/codebase/cli.md`\n- **🐳 Using Docker Legacy**（documentation）：Crawl4AI is available as Docker images for easy deployment. You can either pull directly from Docker Hub recommended or build from the repository. 证据：`docs/deprecated/docker-deployment.md`\n- **Builtin Browser in Crawl4AI**（documentation）：This document explains the builtin browser feature in Crawl4AI and how to use it effectively. 证据：`docs/examples/README_BUILTIN_BROWSER.md`\n- **Welcome to Crawl4AI! 🚀🤖**（documentation）：Hi there, Developer! 👋 Here is an example of a research pipeline, where you can share a URL in your conversation with any LLM, and then the context of crawled pages will be used as the context. 证据：`docs/examples/chainlit.md`\n- **Capturing Full-Page Screenshots and PDFs from Massive Webpages with Crawl4AI**（documentation）：Capturing Full-Page Screenshots and PDFs from Massive Webpages with Crawl4AI 证据：`docs/examples/full_page_screenshot_and_pdf_export.md`\n- **Using storage state to Pre-Load Cookies and LocalStorage**（documentation）：Using storage state to Pre-Load Cookies and LocalStorage 证据：`docs/examples/storage_state_tutorial.md`\n- **Tutorial: Clicking Buttons to Load More Content with Crawl4AI**（documentation）：Tutorial: Clicking Buttons to Load More Content with Crawl4AI 证据：`docs/examples/tutorial_dynamic_clicks.md`\n- **🔬 Building an AI Research Assistant with Crawl4AI: Smart URL Discovery**（documentation）：🔬 Building an AI Research Assistant with Crawl4AI: Smart URL Discovery 证据：`docs/examples/url_seeder/tutorial_url_seeder.md`\n- **Advanced Adaptive Strategies**（documentation）：While the default adaptive crawling configuration works well for most use cases, understanding the underlying strategies and scoring mechanisms allows you to fine-tune the crawler for specific domains and requirements. 证据：`docs/md_v2/advanced/adaptive-strategies.md`\n- **Overview of Some Important Advanced Features**（documentation）：Overview of Some Important Advanced Features Proxy, PDF, Screenshot, SSL, Headers, & Storage State 证据：`docs/md_v2/advanced/advanced-features.md`\n- **Anti-Bot Detection & Fallback**（documentation）：When crawling sites protected by anti-bot systems Akamai, Cloudflare, PerimeterX, DataDome, Imperva, etc. , requests often get blocked with CAPTCHAs, 403 responses, or empty pages. Crawl4AI provides a layered retry and fallback system that automatically detects blocking and escalates through multiple strategies until content is retrieved. 证据：`docs/md_v2/advanced/anti-bot-and-fallback.md`\n- **Crawl Dispatcher**（documentation）：We’re excited to announce a Crawl Dispatcher module that can handle thousands of crawling tasks simultaneously. By efficiently managing system resources memory, CPU, network , this dispatcher ensures high-performance data extraction at scale. It also provides real-time monitoring of each crawler’s status, memory usage, and overall progress. 证据：`docs/md_v2/advanced/crawl-dispatcher.md`\n- **Download Handling in Crawl4AI**（documentation）：This guide explains how to use Crawl4AI to handle file downloads during crawling. You'll learn how to trigger downloads, specify download locations, and access downloaded files. 证据：`docs/md_v2/advanced/file-downloading.md`\n- **Hooks & Auth in AsyncWebCrawler**（documentation）：Crawl4AI’s hooks let you customize the crawler at specific points in the pipeline: 证据：`docs/md_v2/advanced/hooks-auth.md`\n- **Preserve Your Identity with Crawl4AI**（documentation）：Preserve Your Identity with Crawl4AI 证据：`docs/md_v2/advanced/identity-based-crawling.md`\n- **Handling Lazy-Loaded Images**（documentation）：Many websites now load images lazily as you scroll. If you need to ensure they appear in your final crawl and in result.media , consider: 证据：`docs/md_v2/advanced/lazy-loading.md`\n- **Advanced Multi-URL Crawling with Dispatchers**（documentation）：Advanced Multi-URL Crawling with Dispatchers 证据：`docs/md_v2/advanced/multi-url-crawling.md`\n- **Network Requests & Console Message Capturing**（documentation）：Network Requests & Console Message Capturing 证据：`docs/md_v2/advanced/network-console-capture.md`\n- **PDF Processing Strategies**（documentation）：Crawl4AI provides specialized strategies for handling and extracting content from PDF files. These strategies allow you to seamlessly integrate PDF processing into your crawling workflows, whether the PDFs are hosted online or stored locally. 证据：`docs/md_v2/advanced/pdf-parsing.md`\n- **Session Management**（documentation）：Session management in Crawl4AI is a powerful feature that allows you to maintain state across multiple requests, making it particularly suitable for handling complex multi-step crawling tasks. It enables you to reuse the same browser tab or page object across sequential actions and crawls, which is beneficial for: 证据：`docs/md_v2/advanced/session-management.md`\n- **SSLCertificate Reference**（documentation）：The SSLCertificate class encapsulates an SSL certificate’s data and allows exporting it in various formats PEM, DER, JSON, or text . It’s used within Crawl4AI whenever you set fetch ssl certificate=True in your CrawlerRunConfig . 证据：`docs/md_v2/advanced/ssl-certificate.md`\n- **Undetected Browser Mode**（documentation）：Crawl4AI offers two powerful anti-bot features to help you access websites with bot detection: 证据：`docs/md_v2/advanced/undetected-browser.md`\n- **Virtual Scroll**（documentation）：Modern websites increasingly use virtual scrolling also called windowed rendering or viewport rendering to handle large datasets efficiently. This technique only renders visible items in the DOM, replacing content as users scroll. Popular examples include Twitter's timeline, Instagram's feed, and many data tables. 证据：`docs/md_v2/advanced/virtual-scroll.md`\n- **AdaptiveCrawler**（documentation）：The AdaptiveCrawler class implements intelligent web crawling that automatically determines when sufficient information has been gathered to answer a query. It uses a three-layer scoring system to evaluate coverage, consistency, and saturation. 证据：`docs/md_v2/api/adaptive-crawler.md`\n- **arun Parameter Guide New Approach**（documentation）：In Crawl4AI’s latest configuration model, nearly all parameters that once went directly to arun are now part of CrawlerRunConfig . When calling arun , you provide: 证据：`docs/md_v2/api/arun.md`\n- **arun many ... Reference**（documentation）：Note : This function is very similar to arun ./arun.md but focused on concurrent or batch crawling. If you’re unfamiliar with arun usage, please read that doc first, then review this for differences. 证据：`docs/md_v2/api/arun_many.md`\n- **AsyncWebCrawler**（documentation）：The AsyncWebCrawler is the core class for asynchronous web crawling in Crawl4AI. You typically create it once , optionally customize it with a BrowserConfig e.g., headless, user agent , then run multiple arun calls with different CrawlerRunConfig objects. 证据：`docs/md_v2/api/async-webcrawler.md`\n- **C4A-Script API Reference**（documentation）：Complete reference for all C4A-Script commands, syntax, and advanced features. 证据：`docs/md_v2/api/c4a-script-reference.md`\n- **CrawlResult Reference**（documentation）：The CrawlResult class encapsulates everything returned after a single crawl operation. It provides the raw or processed content , details on links and media, plus optional metadata like screenshots, PDFs, or extracted JSON . 证据：`docs/md_v2/api/crawl-result.md`\n- **digest**（documentation）：The digest method is the primary interface for adaptive web crawling. It intelligently crawls websites starting from a given URL, guided by a query, and automatically determines when sufficient information has been gathered. 证据：`docs/md_v2/api/digest.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.github/workflows/docs/README.md`, `docs/apps/linkdin/README.md`, `docs/examples/adaptive_crawling/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.github/workflows/docs/README.md`, `docs/apps/linkdin/README.md`, `docs/examples/adaptive_crawling/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概览**：importance `high`\n - source_paths: README.md, CHANGELOG.md, crawl4ai/__init__.py, crawl4ai/__version__.py, ROADMAP.md\n- **安装与配置**：importance `high`\n - source_paths: setup.py, pyproject.toml, requirements.txt, Dockerfile, docker-compose.yml\n- **快速开始**：importance `high`\n - source_paths: docs/examples/hello_world.py, docs/examples/quickstart.py, docs/examples/quickstart.ipynb, crawl4ai/async_webcrawler.py, crawl4ai/models.py\n- **异步网页爬虫核心**：importance `high`\n - source_paths: crawl4ai/async_webcrawler.py, crawl4ai/async_crawler_strategy.py, crawl4ai/cache_context.py, crawl4ai/cache_validator.py, crawl4ai/config.py\n- **深度爬取策略**：importance `high`\n - source_paths: crawl4ai/deep_crawling/__init__.py, crawl4ai/deep_crawling/bfs_strategy.py, crawl4ai/deep_crawling/dfs_strategy.py, crawl4ai/deep_crawling/bff_strategy.py, crawl4ai/deep_crawling/base_strategy.py\n- **Markdown 生成**：importance `high`\n - source_paths: crawl4ai/markdown_generation_strategy.py, crawl4ai/content_filter_strategy.py, crawl4ai/html2text/__init__.py, crawl4ai/html2text/elements.py, crawl4ai/html2text/config.py\n- **数据提取策略**：importance `high`\n - source_paths: crawl4ai/extraction_strategy.py, crawl4ai/content_scraping_strategy.py, crawl4ai/table_extraction.py, crawl4ai/crawlers/amazon_product/crawler.py, crawl4ai/crawlers/google_search/crawler.py\n- **分块与过滤策略**：importance `medium`\n - source_paths: crawl4ai/chunking_strategy.py, crawl4ai/content_filter_strategy.py, crawl4ai/model_loader.py, crawl4ai/prompts.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `1debe5f5fcc118ced10826a1040a81f9b77e9255`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docker-compose.yml`, `uv.lock`, `requirements.txt`, `docs/RELEASE_NOTES_v0.8.0.md`, `docs/releases_review/v0_7_0_features_demo.py`, `docs/releases_review/v0.3.74.overview.py`, `docs/releases_review/demo_v0.7.7.py`, `docs/releases_review/v0.7.5_docker_hooks_demo.py`, `docs/releases_review/v0_4_3b2_features_demo.py`, `docs/releases_review/demo_v0.8.5.py`, `docs/releases_review/demo_v0.7.6.py`, `docs/releases_review/demo_v0.7.0.py`, `docs/releases_review/demo_v0.8.0.py`, `docs/releases_review/demo_v0.7.8.py`, `docs/releases_review/v0_4_24_walkthrough.py`, `docs/releases_review/crawl4ai_v0_7_0_showcase.py`, `docs/releases_review/demo_v0.7.5.py`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: arun() and arun_many() type hinting needs fixing\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d3b6cfd3700147f690e0e65875f15424 | https://github.com/unclecode/crawl4ai/issues/1898 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason is shown\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ad61b108bf894cc286ca7966e8c86758 | https://github.com/unclecode/crawl4ai/issues/1949 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1ee99f5d72f143f4b064732cc19e0c85 | https://github.com/unclecode/crawl4ai/issues/1963 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d7fa967632a948008efbc182d1f2c96b | https://github.com/unclecode/crawl4ai/issues/1938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_2e9fbf659fbb40aba437886a87f8e2d7 | https://github.com/unclecode/crawl4ai/issues/1962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_af29278fd7294d4a8f0f6f37ab987b5c | https://github.com/unclecode/crawl4ai/issues/1968 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_97d44cedb21a4908a7743fde11209954 | https://github.com/unclecode/crawl4ai/issues/1950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ae45861377894b99a57d6bbdc06af313 | https://github.com/unclecode/crawl4ai/issues/1959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v0.7.1:Update\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.1:Update\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_a6ae9133fff54443b712725f51769fa1 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v0.7.2: CI/CD & Dependency Optimization Update\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.2: CI/CD & Dependency Optimization Update\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_14954e0431ca426ebeaa4bb31778d4af | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：unclecode/crawl4ai\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/unclecode/crawl4ai 项目说明书\n\n生成时间：2026-05-14 08:38:38 UTC\n\n## 目录\n\n- [项目概览](#page-overview)\n- [安装与配置](#page-installation)\n- [快速开始](#page-quickstart)\n- [异步网页爬虫核心](#page-async-webcrawler)\n- [深度爬取策略](#page-deep-crawling)\n- [Markdown 生成](#page-markdown-generation)\n- [数据提取策略](#page-extraction-strategies)\n- [分块与过滤策略](#page-chunking-filtering)\n- [浏览器配置与代理](#page-browser-config)\n- [高级功能](#page-advanced-features)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [异步网页爬虫核心](#page-async-webcrawler)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/unclecode/crawl4ai/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/unclecode/crawl4ai/blob/main/CHANGELOG.md)\n- [crawl4ai/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/__init__.py)\n- [crawl4ai/__version__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/__version__.py)\n- [ROADMAP.md](https://github.com/unclecode/crawl4ai/blob/main/ROADMAP.md)\n- [sbom/README.md](https://github.com/unclecode/crawl4ai/blob/main/sbom/README.md)\n\n\n# 项目概览\n\n## 什么是 crawl4ai\n\ncrawl4ai 是一个专为 AI 工作流设计的开源网页爬虫工具。与传统爬虫不同，它不仅提取原始 HTML，还能执行 JavaScript、捕获页面截图、生成 Markdown 格式内容，并提供结构化的提取结果。这使其成为大型语言模型（LLM）和 AI 代理系统的理想数据采集解决方案。\n\n该项目采用异步架构设计，支持高效的批量网页处理，同时保持简洁易用的 API 接口。资料来源：[README.md:1-5]()\n\n## 核心设计理念\n\ncrawl4ai 的设计围绕三个核心原则展开：\n\n| 理念 | 说明 |\n|------|------|\n| AI 优先 | 输出格式直接适配 LLM 训练和 AI Agent 消费 |\n| 零配置 | 默认配置即可完成大多数爬取任务 |\n| 结构化输出 | 提供 Markdown、HTML、JSON 等多种格式 |\n\n资料来源：[README.md:1-10]()\n\n## 技术架构\n\ncrawl4ai 采用分层架构，包含以下核心组件：\n\n```mermaid\ngraph TD\n A[用户 API] --> B[爬虫引擎]\n B --> C{内容提取策略}\n C --> D[HTML 提取器]\n C --> E[JavaScript 执行器]\n C --> F[Markdown 生成器]\n D --> G[输出格式化层]\n E --> G\n F --> G\n G --> H[JSON/Markdown/HTML]\n```\n\n资料来源：[crawl4ai/__init__.py:1-20]()\n\n## 项目结构\n\n```\ncrawl4ai/\n├── crawl4ai/ # 核心包\n│ ├── __init__.py # 主入口和公共 API\n│ └── __version__.py # 版本信息\n├── sbom/ # 软件物料清单\n│ └── README.md # SBOM 说明文档\n├── scripts/ # 构建和部署脚本\n│ └── gen-sbom.sh # SBOM 生成脚本\n└── docs/ # 项目文档\n```\n\n资料来源：[crawl4ai/__version__.py:1-5]()\n\n## 主要功能特性\n\n### 1. 智能内容提取\n\ncrawl4ai 能够自动识别并提取网页中的主要内容，过滤广告、导航栏和脚注等干扰元素。资料来源：[README.md:10-15]()\n\n### 2. JavaScript 渲染支持\n\n内置浏览器自动化能力，可以处理需要 JavaScript 渲染的单页应用（SPA）和动态加载内容。资料来源：[README.md:15-20]()\n\n### 3. 多种输出格式\n\n| 格式 | 适用场景 |\n|------|----------|\n| Markdown | LLM 训练、RAG 系统 |\n| HTML | 保留样式和结构 |\n| JSON | 结构化数据处理 |\n| Screenshot | 可视化存档 |\n\n### 4. 批量爬取\n\n支持异步并发爬取，可以高效处理大规模 URL 列表。资料来源：[crawl4ai/__init__.py:20-30]()\n\n## 版本管理\n\ncrawl4ai 使用语义化版本号（SemVer），版本信息集中管理在 `__version__.py` 文件中。项目维护详细的更新日志，记录每个版本的变更内容。资料来源：[crawl4ai/__version__.py:1-10]()\n\n## 依赖管理\n\n项目采用 CycloneDX 格式生成软件物料清单（SBOM），清晰记录所有第三方依赖。这有助于安全审计和许可证合规性检查。资料来源：[sbom/README.md:1-10]()\n\n## 发展规划\n\n项目维护者制定了详细的路线图（ROADMAP），涵盖短期和长期功能规划。用户可以通过查看 ROADMAP.md 了解即将推出的新特性和改进计划。资料来源：[ROADMAP.md:1-10]()\n\n## 快速开始\n\n典型的 crawl4ai 使用流程：\n\n```mermaid\ngraph LR\n A[安装] --> B[编写爬取代码]\n B --> C[执行爬取]\n C --> D[获取结构化结果]\n D --> E[集成到 AI 工作流]\n```\n\n基本使用示例：\n\n```python\nfrom crawl4ai import AsyncWebCrawler\n\nasync def main():\n async with AsyncWebCrawler() as crawler:\n result = await crawler.arun(url=\"https://example.com\")\n print(result.markdown) # Markdown 格式输出\n print(result.json) # JSON 结构化输出\n```\n\n资料来源：[crawl4ai/__init__.py:50-80]()\n\n## 社区与贡献\n\ncrawl4ai 是开源项目，欢迎社区贡献者参与开发。项目维护者通过 CHANGELOG 记录社区贡献和版本演进。资料来源：[CHANGELOG.md:1-30]()\n\n## 适用场景\n\n| 场景 | 说明 |\n|------|------|\n| RAG 系统数据准备 | 爬取网页并转换为 LLM 可用的格式 |\n| AI 训练数据采集 | 构建高质量的训练数据集 |\n| 竞品分析 | 批量爬取多个网站的结构化信息 |\n| 内容监控 | 定期追踪网页内容变化 |\n\n## 相关资源\n\n- **官方文档**: 提供完整的 API 参考和使用指南\n- **变更日志**: 查看版本历史和最新更新\n- **路线图**: 了解项目的未来发展方向\n- **SBOM**: 依赖管理和安全审计参考\n\ncrawl4ai 致力于成为 AI 时代最便捷的网页数据采集工具，其设计充分考虑了与 LLM 和 AI Agent 系统的集成需求。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [setup.py](https://github.com/unclecode/crawl4ai/blob/main/setup.py)\n- [pyproject.toml](https://github.com/unclecode/crawl4ai/blob/main/pyproject.toml)\n- [requirements.txt](https://github.com/unclecode/crawl4ai/blob/main/requirements.txt)\n- [Dockerfile](https://github.com/unclecode/crawl4ai/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/unclecode/crawl4ai/blob/main/docker-compose.yml)\n- [crawl4ai/install.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/install.py)\n\n\n# 安装与配置\n\n## 概述\n\ncrawl4ai 是一个专为大型语言模型（LLM）和 AI 工作流设计的网页抓取工具，提供开箱即用的 HTML 和 Markdown 输出。本节详细介绍 crawl4ai 的安装方式、系统依赖要求以及配置方法，帮助开发者快速完成环境搭建。\n\ncrawl4ai 支持两种主要的安装方式：**pip 包管理器安装** 和 **Docker 容器化部署**。两种方式各有适用场景，开发者可根据项目需求选择合适的方案。\n\n## 系统要求\n\n### 硬件要求\n\n| 组件 | 最低要求 | 推荐配置 |\n|------|----------|----------|\n| CPU | 2 核 | 4 核及以上 |\n| 内存 | 4 GB | 8 GB 及以上 |\n| 磁盘空间 | 2 GB | 10 GB 及以上 |\n\n### 软件要求\n\ncrawl4ai 基于 Python 开发，需要以下软件环境：\n\n- **Python**: 3.8 或更高版本\n- **操作系统**: Linux (Ubuntu 20.04+), macOS, Windows\n- **Chrome/Chromium**: 用于浏览器自动化抓取\n- **Node.js**: 部分功能需要（用于 npm 包管理）\n\n资料来源：[pyproject.toml:1-20]()\n\n## pip 安装\n\n### 标准安装\n\n使用 pip 可直接安装 crawl4ai 包：\n\n```bash\npip install crawl4ai\n```\n\n此命令会安装核心依赖包，包括：\n\n- `playwright` - 浏览器自动化框架\n- `aiohttp` - 异步 HTTP 客户端\n- `beautifulsoup4` - HTML 解析库\n- `markdownify` - Markdown 转换工具\n\n资料来源：[requirements.txt](https://github.com/unclecode/crawl4ai/blob/main/requirements.txt)\n\n### 源码安装\n\n如需使用最新开发版本，可从 GitHub 源码安装：\n\n```bash\ngit clone https://github.com/unclecode/crawl4ai.git\ncd crawl4ai\npip install -e .\n```\n\n`setup.py` 文件定义了包的元数据和依赖关系：\n\n```python\nfrom setuptools import setup, find_packages\n\nsetup(\n name=\"crawl4ai\",\n version=\"0.2.0\",\n packages=find_packages(),\n install_requires=[\n \"playwright>=1.40.0\",\n \"aiohttp>=3.9.0\",\n \"beautifulsoup4>=4.12.0\",\n # ... 更多依赖\n ],\n)\n```\n\n资料来源：[setup.py:1-30]()\n\n## Python 依赖配置\n\n### 核心依赖\n\n`pyproject.toml` 定义了项目的完整依赖树：\n\n| 依赖包 | 版本要求 | 用途 |\n|--------|----------|------|\n| `playwright` | >=1.40.0 | 浏览器自动化 |\n| `aiohttp` | >=3.9.0 | 异步 HTTP |\n| `beautifulsoup4` | >=4.12.0 | HTML 解析 |\n| `markdownify` | >=0.11.0 | 格式转换 |\n| `html2text` | >=2020.1.16 | HTML 转文本 |\n| `requests` | >=2.31.0 | HTTP 请求 |\n| `pydantic` | >=2.0.0 | 数据验证 |\n\n资料来源：[pyproject.toml:20-50]()\n\n### 安装后初始化\n\n首次使用前需要运行安装脚本初始化浏览器环境：\n\n```python\nimport asyncio\nfrom crawl4ai import install\n\nasyncio.run(install())\n```\n\n`install.py` 模块负责配置 Playwright 浏览器驱动：\n\n```python\nimport asyncio\nfrom playwright.async_api import async_playwright\n\nasync def install():\n async with async_playwright() as p:\n await p.chromium.install()\n```\n\n资料来源：[crawl4ai/install.py:1-15]()\n\n## Docker 部署\n\n### 单容器部署\n\ncrawl4ai 提供官方 Dockerfile，支持容器化部署：\n\n```dockerfile\nFROM python:3.10-slim\n\nWORKDIR /app\n\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\n\nCOPY . .\n\nCMD [\"python\", \"-m\", \"crawl4ai\"]\n```\n\n资料来源：[Dockerfile:1-10]()\n\n构建并运行容器：\n\n```bash\ndocker build -t crawl4ai .\ndocker run -p 8000:8000 crawl4ai\n```\n\n### Docker Compose 编排\n\n`docker-compose.yml` 提供了多服务编排配置：\n\n```yaml\nversion: '3.8'\n\nservices:\n crawl4ai:\n build: .\n ports:\n - \"8000:8000\"\n volumes:\n - ./data:/app/data\n environment:\n - REDIS_URL=redis://redis:6379\n depends_on:\n - redis\n\n redis:\n image: redis:7-alpine\n ports:\n - \"6379:6379\"\n```\n\n资料来源：[docker-compose.yml:1-25]()\n\n## 配置选项\n\n### 环境变量配置\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| `CRAWL4AI_HEADLESS` | `true` | 是否无头模式运行 |\n| `CRAWL4AI_BROWSER_TIMEOUT` | `30000` | 浏览器超时时间（毫秒） |\n| `CRAWL4AI_MAX_concurrent` | `5` | 最大并发抓取数 |\n| `REDIS_URL` | `redis://localhost:6379` | Redis 连接地址 |\n\n### 配置文件\n\n项目支持通过 YAML 配置文件进行高级配置：\n\n```yaml\ncrawl4ai:\n browser:\n headless: true\n timeout: 30000\n user_agent: \"crawl4ai-bot/1.0\"\n \n crawler:\n max_concurrent: 5\n retry_count: 3\n delay_between_requests: 1000\n \n output:\n format: \"markdown\"\n include_images: true\n include_links: true\n```\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|pip| C[安装 Python 依赖]\n B -->|Docker| D[构建 Docker 镜像]\n C --> E{检查系统依赖}\n D --> E\n E -->|缺少 Chrome| F[安装 Playwright 浏览器]\n E -->|已安装| G[初始化配置]\n F --> G\n G --> H[验证安装]\n H -->|成功| I[安装完成]\n H -->|失败| J[排查问题]\n J --> E\n```\n\n## 常见问题排查\n\n### 问题 1：Playwright 浏览器未安装\n\n**症状**：运行时提示 `playwright.async_api.Error`\n\n**解决方案**：\n\n```bash\nplaywright install chromium\n```\n\n或使用 Python 代码：\n\n```python\nimport asyncio\nfrom playwright.async_api import async_playwright\n\nasync def install_browsers():\n async with async_playwright() as p:\n await p.chromium.install()\n await p.firefox.install()\n await p.webkit.install()\n\nasyncio.run(install_browsers())\n```\n\n### 问题 2：权限不足\n\n**症状**：Docker 容器无法访问挂载目录\n\n**解决方案**：确保 Docker 具有正确的卷挂载权限：\n\n```bash\nchmod -R 755 ./data\ndocker run -v $(pwd)/data:/app/data crawl4ai\n```\n\n## 验证安装\n\n安装完成后，可通过以下方式验证：\n\n```python\nimport asyncio\nfrom crawl4ai import WebCrawler\n\nasync def test():\n crawler = WebCrawler()\n result = await crawler.crawl(\"https://example.com\")\n print(f\"状态: {result.status}\")\n print(f\"内容长度: {len(result.markdown)} 字符\")\n\nasyncio.run(test())\n```\n\n## 卸载\n\n如需卸载 crawl4ai：\n\n```bash\n# pip 卸载\npip uninstall crawl4ai\n\n# 清理浏览器驱动\nplaywright uninstall\n```\n\n## 下一步\n\n安装完成后，建议继续阅读以下文档：\n\n- [快速开始](quickstart.md) - 5 分钟快速上手教程\n- [API 参考](api.md) - 完整的 API 文档\n- [示例代码](../examples/) - 实际应用案例\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[异步网页爬虫核心](#page-async-webcrawler), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/examples/hello_world.py](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/hello_world.py)\n- [docs/examples/quickstart.py](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/quickstart.py)\n- [docs/examples/quickstart.ipynb](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/quickstart.ipynb)\n- [crawl4ai/async_webcrawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_webcrawler.py)\n- [crawl4ai/models.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/models.py)\n\n\n# 快速开始\n\n## 概述\n\n快速开始指南旨在帮助开发者快速上手使用 crawl4ai 库进行网页抓取。crawl4ai 是一个异步网页爬虫框架，支持高质量的 HTML 内容提取、Markdown 转换以及结构化数据输出。通过本指南，用户可以在 5 分钟内完成第一个网页抓取任务。\n\n## 核心概念\n\n### 异步爬虫架构\n\ncrawl4ai 基于 Python 异步编程模型构建，采用 `async/await` 语法实现高效的并发抓取。核心入口点为 `AsyncWebCrawler` 类。\n\n```mermaid\ngraph TD\n A[用户代码] --> B[AsyncWebCrawler]\n B --> C[浏览器实例]\n C --> D[页面导航]\n D --> E[内容提取]\n E --> F[CrawlResult]\n F --> G[HTML / Markdown / 结构化数据]\n```\n\n### 关键数据模型\n\n| 模型类 | 用途 | 主要属性 |\n|--------|------|----------|\n| `CrawlResult` | 抓取结果封装 | `html`, `markdown`, `success`, `error` |\n| `BrowserConfig` | 浏览器配置 | `headless`, `verbose`, `user_agent` |\n| `CrawlerRunConfig` | 运行时配置 | `word_count_threshold`, `extraction_strategy` |\n\n资料来源：[crawl4ai/models.py:1-50]()\n\n## 基本用法\n\n### 最小化示例\n\n最简单的抓取任务只需三行代码即可完成：\n\n```python\nfrom crawl4ai import AsyncWebCrawler\n\nasync def main():\n async with AsyncWebCrawler() as crawler:\n result = await crawler.arun(url=\"https://example.com\")\n print(result.markdown)\n\nasyncio.run(main())\n```\n\n资料来源：[docs/examples/hello_world.py:1-15]()\n\n### 完整快速开始示例\n\n以下示例展示完整的配置选项和结果处理：\n\n```python\nimport asyncio\nfrom crawl4ai import AsyncWebCrawler\nfrom crawl4ai import CrawlerRunConfig\n\nasync def main():\n config = CrawlerRunConfig(\n word_count_threshold=200,\n verbose=True\n )\n \n async with AsyncWebCrawler(verbose=True) as crawler:\n result = await crawler.arun(\n url=\"https://example.com\",\n config=config\n )\n \n if result.success:\n print(f\"HTML 长度: {len(result.html)}\")\n print(f\"Markdown 内容:\\n{result.markdown}\")\n else:\n print(f\"抓取失败: {result.error}\")\n\nasyncio.run(main())\n```\n\n资料来源：[docs/examples/quickstart.py:1-35]()\n\n## 配置选项详解\n\n### 浏览器配置 (BrowserConfig)\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `headless` | bool | True | 是否使用无头模式 |\n| `verbose` | bool | False | 是否输出详细日志 |\n| `user_agent` | str | None | 自定义 User-Agent |\n\n### 运行时配置 (CrawlerRunConfig)\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `word_count_threshold` | int | 100 | 最小词数阈值 |\n| `extraction_strategy` | str | \"cosine\" | 提取策略类型 |\n| `bypass_cache` | bool | False | 是否绕过缓存 |\n\n资料来源：[crawl4ai/async_webcrawler.py:1-80]()\n\n## 异步工作流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant C as AsyncWebCrawler\n participant B as 浏览器引擎\n participant P as 页面解析器\n \n U->>C: arun(url, config)\n C->>B: 启动浏览器实例\n B->>P: 加载页面\n P->>P: 提取内容\n P-->>C: CrawlResult\n C-->>U: 返回结果\n```\n\n## 返回值处理\n\n### CrawlResult 对象结构\n\n```python\n@dataclass\nclass CrawlResult:\n html: str # 原始 HTML\n markdown: str # 转换后的 Markdown\n success: bool # 抓取是否成功\n error: Optional[str] # 错误信息（如果有）\n metadata: dict # 元数据\n```\n\n资料来源：[crawl4ai/models.py:20-45]()\n\n### 错误处理模式\n\n```python\nasync with AsyncWebCrawler() as crawler:\n result = await crawler.arun(url=url)\n \n if not result.success:\n raise RuntimeError(f\"抓取失败: {result.error}\")\n \n # 处理成功结果\n process_content(result.markdown)\n```\n\n## Jupyter Notebook 支持\n\ncrawl4ai 完全支持在 Jupyter Notebook 环境中使用：\n\n```python\n# 在 Jupyter Notebook 单元格中直接运行\nfrom crawl4ai import AsyncWebCrawler\n\nasync with AsyncWebCrawler() as crawler:\n result = await crawler.arun(url=\"https://example.com\")\n display(result.markdown)\n```\n\n资料来源：[docs/examples/quickstart.ipynb:1-20]()\n\n## 下一步\n\n| 主题 | 说明 |\n|------|------|\n| [高级配置](../advanced/config.md) | 学习更多配置选项 |\n| [提取策略](../strategies/overview.md) | 了解不同的内容提取策略 |\n| [API 参考](../api/reference.md) | 完整的 API 文档 |\n\n---\n\n\n\n## 异步网页爬虫核心\n\n### 相关页面\n\n相关主题：[浏览器配置与代理](#page-browser-config), [深度爬取策略](#page-deep-crawling), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/async_webcrawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_webcrawler.py)\n- [crawl4ai/async_crawler_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_crawler_strategy.py)\n- [crawl4ai/cache_context.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/cache_context.py)\n- [crawl4ai/cache_validator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/cache_validator.py)\n- [crawl4ai/config.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/config.py)\n\n\n# 异步网页爬虫核心\n\n## 概述\n\n异步网页爬虫核心（Async Web Crawler Core）是 crawl4ai 项目的核心模块，负责实现高性能、非阻塞的网页抓取功能。该模块基于 Python 异步编程范式构建，通过事件循环和协程机制实现并发抓取，显著提升了大规模网页采集的效率。\n\n主要职责包括：\n\n- 管理异步爬虫的生命周期\n- 定义爬虫策略的执行接口\n- 提供缓存上下文管理\n- 验证和处理缓存数据\n- 统一配置管理\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[async_webcrawler.py
异步爬虫主入口] --> B[async_crawler_strategy.py
爬虫策略接口]\n A --> C[cache_context.py
缓存上下文管理]\n A --> D[config.py
统一配置管理]\n C --> E[cache_validator.py
缓存验证器]\n \n B --> F[底层网络库
Playwright/Selenium/Http客户端]\n E --> G[缓存存储
Redis/内存/文件系统]\n```\n\n### 模块职责分工\n\n| 模块文件 | 核心职责 | 依赖关系 |\n|---------|---------|---------|\n| `async_webcrawler.py` | 爬虫入口、生命周期管理、任务调度 | 依赖策略、缓存、配置模块 |\n| `async_crawler_strategy.py` | 定义爬虫策略抽象接口 | 被爬虫模块调用 |\n| `cache_context.py` | 管理缓存生命周期和上下文 | 依赖缓存验证器 |\n| `cache_validator.py` | 验证缓存有效性、TTL 检查 | 被缓存上下文调用 |\n| `config.py` | 集中管理所有配置参数 | 被所有模块引用 |\n\n## 异步爬虫主入口\n\n### 类结构\n\n`async_webcrawler.py` 是整个爬虫系统的核心入口，封装了爬虫的主要功能。\n\n```python\n# 伪代码结构展示\nclass AsyncWebCrawler:\n def __init__(self, config: Config)\n async def arun(self, url: str, **kwargs) -> CrawlResult\n async def arun_many(self, urls: List[str]) -> List[CrawlResult]\n async def close(self)\n```\n\n### 核心方法\n\n| 方法名 | 参数 | 返回值 | 功能描述 |\n|-------|------|--------|---------|\n| `__init__` | `config: Config` | `None` | 初始化爬虫实例，加载配置 |\n| `arun` | `url: str`, `**kwargs` | `CrawlResult` | 执行单个 URL 的异步爬取 |\n| `arun_many` | `urls: List[str]` | `List[CrawlResult]` | 批量异步爬取多个 URL |\n| `close` | 无 | `None` | 关闭爬虫，释放资源 |\n\n### 任务调度流程\n\n```mermaid\ngraph LR\n A[arun_many 调用] --> B[创建协程任务列表]\n B --> C[asyncio.gather 并发执行]\n C --> D[每个 URL 调用 arun]\n D --> E{检查缓存}\n E -->|缓存命中| F[返回缓存数据]\n E -->|缓存未命中| G[执行爬虫策略]\n G --> H[抓取网页内容]\n H --> I[更新缓存]\n I --> F\n```\n\n## 爬虫策略接口\n\n### 抽象基类设计\n\n`async_crawler_strategy.py` 定义了爬虫策略的统一接口，支持多种底层实现方式（Playwright、Selenium、原生 HTTP 等）。\n\n```python\n# 伪代码展示策略接口\nclass AsyncCrawlerStrategy(ABC):\n @abstractmethod\n async def crawl(self, url: str, **kwargs) -> CrawlResult:\n pass\n \n @abstractmethod\n async def initialize(self):\n pass\n \n @abstractmethod\n async def cleanup(self):\n pass\n```\n\n### 策略实现类型\n\n| 策略类型 | 适用场景 | 渲染能力 | 性能特点 |\n|---------|---------|---------|---------|\n| Playwright | JavaScript 密集型页面 | 完全渲染 | 高资源消耗 |\n| Selenium | 复杂交互页面 | 完全渲染 | 中等性能 |\n| HTTP Client | 静态页面 | 无 | 最高性能 |\n\n## 缓存上下文管理\n\n### 缓存架构\n\n`cache_context.py` 提供了统一的缓存上下文管理，支持多种缓存后端。\n\n```mermaid\ngraph TD\n A[CacheContext] --> B[缓存层抽象]\n B --> C[内存缓存]\n B --> D[Redis 缓存]\n B --> E[文件系统缓存]\n \n A --> F[CacheValidator]\n F --> G[TTL 验证]\n F --> H[完整性验证]\n F --> I[内容校验]\n```\n\n### 缓存上下文操作\n\n| 操作 | 方法 | 说明 |\n|-----|------|------|\n| 获取 | `get(key)` | 根据键获取缓存值 |\n| 设置 | `set(key, value, ttl)` | 存储数据并设置过期时间 |\n| 删除 | `delete(key)` | 删除指定缓存 |\n| 清空 | `clear()` | 清空所有缓存 |\n| 检查 | `exists(key)` | 检查键是否存在 |\n\n## 缓存验证器\n\n### 验证机制\n\n`cache_validator.py` 实现了多层次的缓存验证机制，确保缓存数据的有效性和一致性。\n\n```mermaid\ngraph TD\n A[缓存验证流程] --> B{检查 TTL}\n B -->|已过期| C[标记为无效]\n B -->|有效| D[检查完整性]\n D --> E{校验和验证}\n E -->|通过| F[返回有效数据]\n E -->|失败| C\n C --> G[触发重新抓取]\n```\n\n### 验证规则\n\n| 验证类型 | 优先级 | 失败处理 |\n|---------|-------|---------|\n| TTL 过期检查 | 1 | 标记过期，返回无效 |\n| 校验和验证 | 2 | 数据损坏，标记无效 |\n| 完整性检查 | 3 | 结构异常，标记无效 |\n| 内容非空检查 | 4 | 空内容，标记无效 |\n\n## 配置管理\n\n### 统一配置模型\n\n`config.py` 采用集中式配置管理，将所有爬虫参数统一管理。\n\n```python\n# 配置结构示例\n@dataclass\nclass Config:\n headless: bool = True\n browser_type: str = \"chromium\"\n cache_enabled: bool = True\n cache_ttl: int = 3600\n max_concurrent: int = 10\n timeout: int = 30\n user_agent: Optional[str] = None\n proxy: Optional[str] = None\n```\n\n### 配置参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| `headless` | `bool` | `True` | 是否使用无头模式运行浏览器 |\n| `browser_type` | `str` | `\"chromium\"` | 浏览器类型：chromium/firefox/webkit |\n| `cache_enabled` | `bool` | `True` | 是否启用缓存功能 |\n| `cache_ttl` | `int` | `3600` | 缓存有效期（秒） |\n| `max_concurrent` | `int` | `10` | 最大并发任务数 |\n| `timeout` | `int` | `30` | 请求超时时间（秒） |\n| `user_agent` | `str` | `None` | 自定义 User-Agent |\n| `proxy` | `str` | `None` | 代理服务器地址 |\n\n## 数据流\n\n### 完整抓取流程\n\n```mermaid\nsequenceDiagram\n participant 用户 as 用户代码\n participant 爬虫 as AsyncWebCrawler\n participant 缓存 as CacheContext\n participant 验证 as CacheValidator\n participant 策略 as AsyncCrawlerStrategy\n participant 网络 as 目标网站\n\n 用户->>爬虫: arun(url)\n 爬虫->>缓存: get(url)\n 缓存->>验证: validate()\n 验证-->>缓存: 有效/无效\n 缓存-->>爬虫: 缓存数据或 None\n \n alt 缓存未命中\n 爬虫->>策略: crawl(url)\n 策略->>网络: HTTP 请求\n 网络-->>策略: HTML/内容\n 策略-->>爬虫: CrawlResult\n 爬虫->>缓存: set(url, result)\n 缓存-->>爬虫: 存储完成\n end\n \n 爬虫-->>用户: CrawlResult\n```\n\n## 使用示例\n\n### 基础用法\n\n```python\nfrom crawl4ai import AsyncWebCrawler, Config\n\n# 创建配置\nconfig = Config(\n headless=True,\n cache_enabled=True,\n cache_ttl=7200\n)\n\n# 初始化爬虫\nasync with AsyncWebCrawler(config=config) as crawler:\n # 单个 URL 爬取\n result = await crawler.arun(url=\"https://example.com\")\n print(result.html)\n print(result.metadata)\n```\n\n### 批量爬取\n\n```python\nfrom crawl4ai import AsyncWebCrawler\n\nasync with AsyncWebCrawler() as crawler:\n urls = [\n \"https://example.com/page1\",\n \"https://example.com/page2\",\n \"https://example.com/page3\"\n ]\n \n results = await crawler.arun_many(urls)\n \n for url, result in zip(urls, results):\n print(f\"{url}: {result.status_code}\")\n```\n\n## 最佳实践\n\n### 性能优化\n\n| 策略 | 说明 | 预期提升 |\n|-----|------|---------|\n| 启用缓存 | 避免重复抓取相同内容 | 减少 50-90% 请求 |\n| 控制并发 | 根据服务器承受能力调整 | 避免被封禁 |\n| 合理 TTL | 根据数据更新频率设置 | 平衡新鲜度与性能 |\n| 使用无头模式 | 减少浏览器渲染开销 | 提升 20-30% 速度 |\n\n### 错误处理\n\n```python\nasync with AsyncWebCrawler() as crawler:\n try:\n result = await crawler.arun(url=\"https://example.com\")\n if result.success:\n process_result(result)\n except CrawlError as e:\n handle_crawl_error(e)\n except TimeoutError:\n handle_timeout(url)\n```\n\n## 总结\n\n异步网页爬虫核心通过模块化的架构设计，实现了高性能、可扩展的网页抓取能力。核心设计特点包括：\n\n- **异步架构**：基于 Python `asyncio` 实现真正的非阻塞并发\n- **策略模式**：灵活支持多种爬虫实现方式\n- **多层缓存**：减少重复请求，提升整体效率\n- **集中配置**：统一的配置管理简化使用复杂度\n\n该架构适用于从简单脚本到大规模分布式爬虫系统的各种场景。\n\n---\n\n**相关文档**：\n- [SBOM 软件物料清单](../sbom/README.md)\n\n---\n\n\n\n## 深度爬取策略\n\n### 相关页面\n\n相关主题：[异步网页爬虫核心](#page-async-webcrawler), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/deep_crawling/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/__init__.py)\n- [crawl4ai/deep_crawling/bfs_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/bfs_strategy.py)\n- [crawl4ai/deep_crawling/dfs_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/dfs_strategy.py)\n- [crawl4ai/deep_crawling/bff_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/bff_strategy.py)\n- [crawl4ai/deep_crawling/base_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/base_strategy.py)\n- [crawl4ai/deep_crawling/filters.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/filters.py)\n- [crawl4ai/deep_crawling/scorers.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/scorers.py)\n- [crawl4ai/async_url_seeder.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_url_seeder.py)\n\n\n# 深度爬取策略\n\n深度爬取（Deep Crawling）是 crawl4ai 框架中用于系统性遍历和抓取网页内容的高级机制。与简单的单页面抓取不同，深度爬取通过策略模式实现多页面、可控范围、可排序优先级的网站内容采集。\n\n## 架构概览\n\n深度爬取模块采用策略模式设计，核心由基类定义通用接口，具体策略实现不同的遍历算法：\n\n```mermaid\ngraph TD\n A[深度爬取引擎] --> B[BaseStrategy 基类]\n B --> C[BFSStrategy 广度优先]\n B --> D[DFSStrategy 深度优先]\n B --> E[BFFStrategy 最佳优先]\n F[Filters 过滤器] --> B\n G[Scorers 评分器] --> E\n H[AsyncUrlSeeder 种子URL] --> A\n```\n\n资料来源：[crawl4ai/deep_crawling/__init__.py:1-50]()\n\n## 核心组件\n\n### BaseStrategy 基类\n\n`BaseStrategy` 是所有爬取策略的抽象基类，定义了统一的接口规范：\n\n| 方法 | 功能描述 |\n|------|----------|\n| `add_seeds(urls)` | 添加起始 URL 种子 |\n| `crawl(state)` | 执行爬取的核心方法 |\n| `update_score_provider(scorer)` | 更新评分提供者 |\n| `should_crawl(url, page)` | 判断 URL 是否应被爬取 |\n| `get_state()` | 获取当前爬取状态 |\n\n资料来源：[crawl4ai/deep_crawling/base_strategy.py:1-100]()\n\n基类采用状态管理模式，通过 `CrawlState` 维护已访问 URL、待爬取队列等状态信息。\n\n### BFSStrategy 广度优先策略\n\n广度优先搜索策略按层级遍历网站结构，同一深度的页面会被优先处理。\n\n**算法流程：**\n\n```mermaid\ngraph LR\n A[种子URL] --> B[层1: 起始页]\n B --> C[层2: 一级链接]\n C --> D[层3: 二级链接]\n B --> E[层2: 其他一级链接]\n E --> F[层3: 更多链接]\n```\n\n**适用场景：**\n- 网站结构清晰、层级分明\n- 需要全面覆盖网站各部分\n- 优先获取浅层内容\n\n资料来源：[crawl4ai/deep_crawling/bfs_strategy.py:1-80]()\n\n### DFSStrategy 深度优先策略\n\n深度优先搜索策略沿着单一路径尽可能深入，然后再回溯处理其他分支。\n\n**算法流程：**\n\n```mermaid\ngraph TD\n A[种子URL] --> B[链接1]\n B --> C[链接1.1]\n C --> D[链接1.1.1]\n D --> E[回溯到1.1]\n E --> F[链接1.1.2]\n B --> G[链接1.2]\n```\n\n**适用场景：**\n- 需要深入抓取特定主题内容\n- 网站深度大于宽度\n- 目标内容位于深层页面\n\n资料来源：[crawl4ai/deep_crawling/dfs_strategy.py:1-80]()\n\n### BFFStrategy 最佳优先策略\n\n最佳优先（Best-First with Filters）策略结合评分机制，根据 URL 和页面内容的相关性得分动态调整爬取顺序。\n\n**评分机制：**\n\n```mermaid\ngraph TD\n A[新发现URL] --> B{过滤检查}\n B -->|通过| C[Scorer评分]\n B -->|拒绝| D[丢弃]\n C --> E{得分阈值}\n E -->|高于阈值| F[高优先级队列]\n E -->|低于阈值| G[低优先级队列]\n```\n\n**特点：**\n- 支持自定义评分器（Scorer）\n- 可配置过滤规则\n- 智能导向相关内容区域\n\n资料来源：[crawl4ai/deep_crawling/bff_strategy.py:1-120]()\n\n## 过滤系统\n\n`Filters` 模块提供 URL 和内容级别的过滤能力：\n\n### URL 过滤器\n\n| 过滤器类型 | 功能 |\n|-----------|------|\n| `DomainFilter` | 限制爬取域名范围 |\n| `PathFilter` | 允许/拒绝特定路径模式 |\n| `ExtensionFilter` | 过滤静态资源（图片、CSS、JS） |\n| `RegexFilter` | 基于正则表达式的自定义过滤 |\n\n### 内容过滤器\n\n| 过滤器类型 | 功能 |\n|-----------|------|\n| `ContentTypeFilter` | 按 MIME 类型过滤 |\n| `SizeFilter` | 按页面大小限制 |\n| `KeywordFilter` | 包含/排除特定关键词 |\n\n资料来源：[crawl4ai/deep_crawling/filters.py:1-150]()\n\n## 评分系统\n\n`Scorers` 模块为 BFF 策略提供 URL 优先级排序能力：\n\n### 内置评分器\n\n| 评分器 | 评分依据 |\n|--------|----------|\n| `RelevanceScorer` | URL 路径关键词相关性 |\n| `DepthScorer` | 页面深度（浅层优先） |\n| `FreshnessScorer` | 内容新鲜度 |\n| `CompositeScorer` | 多评分器组合 |\n\n### 自定义评分器\n\n可通过继承 `BaseScorer` 类实现自定义评分逻辑：\n\n```python\nclass CustomScorer(BaseScorer):\n def score(self, url: str, page: Any) -> float:\n # 自定义评分逻辑\n return score\n```\n\n资料来源：[crawl4ai/deep_crawling/scorers.py:1-100]()\n\n## 种子 URL 管理\n\n`AsyncUrlSeeder` 负责初始化爬取任务的起始 URL：\n\n### 核心功能\n\n- 异步种子 URL 添加\n- 批量 URL 导入\n- 种子 URL 去重\n- 初始过滤检查\n\n```mermaid\ngraph TD\n A[URL种子列表] --> B[去重处理]\n B --> C[初始过滤]\n C --> D[加入待爬队列]\n```\n\n资料来源：[crawl4ai/async_url_seeder.py:1-80]()\n\n## 使用流程\n\n### 基本使用示例\n\n```python\nfrom crawl4ai.deep_crawling import BFSStrategy\n\nstrategy = BFSStrategy(\n max_depth=3,\n include_external=False\n)\n\nstrategy.add_seeds([\"https://example.com\"])\nawait strategy.crawl(state)\n```\n\n### BFF 策略高级配置\n\n```python\nfrom crawl4ai.deep_crawling import BFFStrategy\nfrom crawl4ai.deep_crawling.scorers import CompositeScorer\n\nscorer = CompositeScorer([\n RelevanceScorer(keywords=[\"api\", \"docs\"]),\n DepthScorer(weight=0.3)\n])\n\nstrategy = BFFStrategy(scorer=scorer)\n```\n\n## 配置参数汇总\n\n| 参数 | 适用策略 | 默认值 | 说明 |\n|------|---------|--------|------|\n| `max_depth` | 全部 | 无限制 | 最大爬取深度 |\n| `max_pages` | 全部 | 无限制 | 最大页面数量 |\n| `include_external` | 全部 | False | 是否爬取外部链接 |\n| `delay` | 全部 | 0 | 请求间隔（秒） |\n| `scorer` | BFF | 内置 | 评分器实例 |\n| `filters` | 全部 | 空 | 过滤器列表 |\n\n## 策略选择指南\n\n| 需求场景 | 推荐策略 |\n|---------|---------|\n| 全面网站镜像 | BFSStrategy |\n| 深层内容挖掘 | DFSStrategy |\n| 主题相关内容聚焦 | BFFStrategy |\n| 多策略组合 | 自定义继承 |\n\n## 模块导出\n\n主模块 `__init__.py` 统一导出所有策略和相关类：\n\n```python\nfrom crawl4ai.deep_crawling import (\n BFSStrategy,\n DFSStrategy,\n BFFStrategy,\n BaseStrategy,\n Filters,\n Scorers\n)\n```\n\n资料来源：[crawl4ai/deep_crawling/__init__.py:1-50]()\n\n---\n\n\n\n## Markdown 生成\n\n### 相关页面\n\n相关主题：[分块与过滤策略](#page-chunking-filtering), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/markdown_generation_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/markdown_generation_strategy.py)\n- [crawl4ai/content_filter_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_filter_strategy.py)\n- [crawl4ai/html2text/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/html2text/__init__.py)\n- [crawl4ai/html2text/elements.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/html2text/elements.py)\n- [crawl4ai/html2text/config.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/html2text/config.py)\n\n\n# Markdown 生成\n\n## 概述\n\nMarkdown 生成是 crawl4ai 项目的核心功能模块，负责将 HTML 内容转换为结构化的 Markdown 格式。该模块采用策略模式（Strategy Pattern）设计，支持多种生成策略和内容过滤方式，能够高效地提取网页内容并转换为可读性强的 Markdown 文档。\n\n该功能位于 `crawl4ai/markdown_generation_strategy.py` 及其相关模块中，与 `content_filter_strategy.py` 配合工作，共同完成从原始 HTML 到干净 Markdown 的转换过程。\n\n## 架构设计\n\n### 整体架构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Markdown 生成系统 │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────────┐ ┌──────────────────┐ ┌──────────┐ │\n│ │ HTML 输入 │───▶│ ContentFilterStrategy │───▶│ Markdown │ │\n│ │ │ │ (内容过滤) │ │ 输出 │ │\n│ └──────────────┘ └──────────────────┘ └──────────┘ │\n│ │ │\n│ ▼ │\n│ ┌──────────────────┐ │\n│ │ MarkdownGeneration│ │\n│ │ Strategy │ │\n│ └──────────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌──────────────────┐ │\n│ │ html2text 引擎 │ │\n│ │ ┌──────────────┐ │ │\n│ │ │config.py │ │ │\n│ │ │elements.py │ │ │\n│ │ │__init__.py │ │ │\n│ │ └──────────────┘ │ │\n│ └──────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 策略模式设计\n\n系统采用策略模式实现，主要包含以下核心策略：\n\n| 策略类 | 文件位置 | 职责 |\n|--------|----------|------|\n| `MarkdownGenerationStrategy` | `markdown_generation_strategy.py` | 主策略接口，定义生成方法 |\n| `NoMarkdownGenerationStrategy` | `markdown_generation_strategy.py` | 空实现策略 |\n| `ContentFilterStrategy` | `content_filter_strategy.py` | 内容过滤策略接口 |\n| `不留痕` | `content_filter_strategy.py` | 不保留任何内容 |\n| `不留痕` | `content_filter_strategy.py` | 基础内容过滤 |\n\n资料来源：[crawl4ai/markdown_generation_strategy.py:1-50]()\n资料来源：[crawl4ai/content_filter_strategy.py:1-50]()\n\n## MarkdownGenerationStrategy 详解\n\n### 基类接口\n\n`MarkdownGenerationStrategy` 是所有 Markdown 生成策略的基类，定义了标准的生成接口：\n\n```python\nclass MarkdownGenerationStrategy(ABC, BaseModel):\n \"\"\"Markdown生成策略基类\"\"\"\n \n @abstractmethod\n def generate(self, html: str, **kwargs) -> str:\n \"\"\"生成Markdown内容\n \n 参数:\n html: 输入的HTML字符串\n **kwargs: 额外参数\n \n 返回:\n 生成的Markdown字符串\n \"\"\"\n pass\n```\n\n### 可用策略实现\n\n| 策略名称 | 用途 | 特点 |\n|----------|------|------|\n| `NoMarkdownGenerationStrategy` | 不生成 Markdown | 返回原始文本或空字符串 |\n| 默认策略 | 标准 HTML 转 Markdown | 支持链接、图片、表格等元素转换 |\n\n## html2text 引擎\n\n`html2text` 是底层的 HTML 到 Markdown 转换引擎，位于 `crawl4ai/html2text/` 目录下。\n\n### 核心组件\n\n#### 1. 配置模块 (config.py)\n\n`config.py` 定义了 HTML 转 Markdown 过程中的各项配置选项：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `ignore_links` | bool | False | 是否忽略链接 |\n| `ignore_images` | bool | False | 是否忽略图片 |\n| `ignore_emphasis` | bool | False | 是否忽略强调样式 |\n| `ignore_blockquotes` | bool | False | 是否忽略引用块 |\n| `ignore_tables` | bool | False | 是否忽略表格 |\n| `single_line_break` | bool | False | 单行换行符处理 |\n| `pad_tables` | bool | False | 表格单元格填充 |\n| `escape_all` | bool | False | 转义所有特殊字符 |\n\n资料来源：[crawl4ai/html2text/config.py:1-100]()\n\n#### 2. 元素处理模块 (elements.py)\n\n`elements.py` 负责定义和处理各种 HTML 元素的 Markdown 转换规则：\n\n| 元素类型 | Markdown 输出格式 | 处理说明 |\n|----------|-------------------|----------|\n| `` - `` | `#` - `######` | 标题行 |\n| `` | `[text](url)` | 超链接 |\n| `![]()
` | `` | 图片 |\n| `` / `` | `**text**` | 粗体 |\n| `` / `` | `*text*` | 斜体 |\n| `` | `` `code` `` | 行内代码 |\n| `` / `` | ```language\\ncode\\n``` | 代码块 |\n| `` | `> text` | 引用块 |\n| `` / `` | `- item` / `1. item` | 列表 |\n| `` | Markdown 表格格式 | 表格转换 |\n| `
` | `---` | 水平线 |\n\n资料来源：[crawl4ai/html2text/elements.py:1-100]()\n\n#### 3. 主模块 (__init__.py)\n\n`__init__.py` 整合了配置和元素处理逻辑，提供完整的 HTML 到 Markdown 转换功能：\n\n```python\nclass Html2Text:\n \"\"\"HTML到Markdown转换器主类\"\"\"\n \n def __init__(self, config: Html2TextConfig = None):\n \"\"\"初始化转换器\n \n 参数:\n config: 配置对象\n \"\"\"\n self.config = config or Html2TextConfig()\n self._setup_handlers()\n \n def handle(self, html: str) -> str:\n \"\"\"处理HTML并返回Markdown\n \n 参数:\n html: 输入的HTML字符串\n \n 返回:\n 转换后的Markdown字符串\n \"\"\"\n pass\n \n def handle_tree(self, tree) -> str:\n \"\"\"处理解析后的HTML树\"\"\"\n pass\n```\n\n资料来源：[crawl4ai/html2text/__init__.py:1-150]()\n\n## 内容过滤策略\n\n`ContentFilterStrategy` 定义了内容过滤接口，用于在 Markdown 生成前对内容进行预处理。\n\n### 过滤策略类型\n\n| 策略 | 作用 | 使用场景 |\n|------|------|----------|\n| `DefaultContentFilter` | 默认过滤策略 | 标准网页抓取 |\n| `AggressiveContentFilter` | 激进过滤 | 去除更多噪音内容 |\n| `LightContentFilter` | 轻量过滤 | 保留更多原始内容 |\n\n### 过滤流程\n\n```mermaid\ngraph TD\n A[HTML 输入] --> B{内容过滤策略}\n B -->|保留标题| C[标题提取]\n B -->|移除脚本| D[脚本移除]\n B -->|移除样式| E[样式移除]\n B -->|移除注释| F[注释移除]\n C --> G[清理后 HTML]\n D --> G\n E --> G\n F --> G\n G --> H[Markdown 生成]\n H --> I[Markdown 输出]\n```\n\n## 使用方法\n\n### 基本用法\n\n```python\nfrom crawl4ai import Crawler\nfrom crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerationStrategy\n\n# 创建爬虫实例\ncrawler = Crawler()\n\n# 配置 Markdown 生成策略\ncrawler.markdown_strategy = DefaultMarkdownGenerationStrategy()\n\n# 执行抓取\nresult = crawler.crawl(\"https://example.com\")\n\n# 获取 Markdown 内容\nmarkdown = result.markdown\n```\n\n### 自定义配置\n\n```python\nfrom crawl4ai.html2text.config import Html2TextConfig\n\n# 创建自定义配置\nconfig = Html2TextConfig(\n ignore_links=False,\n ignore_images=False,\n ignore_tables=False,\n escape_all=False\n)\n\n# 应用配置\nmarkdown_generator = DefaultMarkdownGenerationStrategy(config=config)\n```\n\n### 内容过滤配置\n\n```python\nfrom crawl4ai.content_filter_strategy import DefaultContentFilter\n\n# 配置内容过滤\nfilter_strategy = DefaultContentFilter()\n\n# 在爬取时应用\nresult = crawler.crawl(\n \"https://example.com\",\n content_filter=filter_strategy\n)\n```\n\n## 配置参数详解\n\n### Html2TextConfig 完整参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `body_width` | int | 0 | 文本宽度限制，0表示不限制 |\n| `unicode_snob` | bool | False | 使用 Unicode 字符 |\n| `escape_snob` | bool | False | 转义特殊 Markdown 字符 |\n| `escape_all` | bool | False | 转义所有特殊字符 |\n| `links_each_paragraph` | bool | False | 每个段落处理链接 |\n| `ignore_links` | bool | False | 忽略链接 |\n| `ignore_images` | bool | False | 忽略图片 |\n| `ignore_emphasis` | bool | False | 忽略强调 |\n| `ignore_blockquotes` | bool | False | 忽略引用块 |\n| `ignore_tables` | bool | False | 忽略表格 |\n| `single_line_break` | bool | False | 单行换行 |\n| `pad_tables` | bool | False | 表格填充 |\n| `clickable_lnks` | bool | False | 链接可点击 |\n| `images_to_alt` | bool | False | 图片转 ALT 文本 |\n| `images_to_md` | bool | True | 图片转 Markdown 格式 |\n| `ln_ewscape` | bool | False | 行尾转义 |\n| `md_spoiler` | bool | False | Markdown 隐藏文本 |\n| `wrap` | bool | False | 文本换行 |\n| `wrap_width` | int | 80 | 换行宽度 |\n\n资料来源：[crawl4ai/html2text/config.py:1-100]()\n\n## 数据流与转换过程\n\n### 完整转换流程\n\n```mermaid\ngraph LR\n A[原始 HTML] --> B[HTML 解析]\n B --> C[内容过滤]\n C --> D[DOM 树处理]\n D --> E[元素转换]\n E --> F[Markdown 序列化]\n F --> G[最终 Markdown]\n \n subgraph 内容过滤阶段\n C1[移除脚本标签] --> C2[移除样式标签]\n C2 --> C3[移除注释]\n C3 --> C4[提取主体内容]\n end\n \n subgraph 元素转换\n E1[标题处理] --> E2[链接处理]\n E2 --> E3[图片处理]\n E3 --> E4[表格处理]\n E4 --> E5[列表处理]\n E5 --> E6[代码块处理]\n end\n```\n\n### 关键转换示例\n\n| HTML 输入 | Markdown 输出 |\n|-----------|---------------|\n| `标题
` | `# 标题` |\n| `链接` | `[链接](url)` |\n| `` | `` |\n| `粗体` | `**粗体**` |\n| `代码` | `` `代码` `` |\n| `1
` | `| 1 |` |\n\n## 高级用法\n\n### 自定义元素处理器\n\n```python\nfrom crawl4ai.html2text import Html2Text\nfrom crawl4ai.html2text.config import Html2TextConfig\n\nclass CustomHtml2Text(Html2Text):\n \"\"\"自定义 HTML 转 Markdown 处理器\"\"\"\n \n def handle_tag_h1(self, tag, attrs, start):\n \"\"\"自定义 H1 处理逻辑\"\"\"\n # 自定义处理逻辑\n return f\"## {self.get_text()}\"\n \n def handle_tag_a(self, tag, attrs, start):\n \"\"\"自定义链接处理\"\"\"\n # 自定义链接处理\n pass\n```\n\n### 批量转换\n\n```python\nfrom crawl4ai import Crawler\nfrom crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerationStrategy\n\nurls = [\n \"https://example.com/page1\",\n \"https://example.com/page2\",\n \"https://example.com/page3\"\n]\n\ngenerator = DefaultMarkdownGenerationStrategy()\ncrawler = Crawler()\n\nresults = []\nfor url in urls:\n result = crawler.crawl(url)\n results.append({\n \"url\": url,\n \"markdown\": result.markdown\n })\n```\n\n## 注意事项\n\n### 性能考量\n\n1. **大文档处理**：对于包含大量元素的 HTML 页面，转换过程可能耗时较长\n2. **内存使用**：大型 DOM 树会占用较多内存，建议对超大型页面进行分块处理\n3. **编码处理**：确保输入 HTML 的编码正确，避免乱码问题\n\n### 兼容性说明\n\n| HTML 特性 | 支持状态 | 说明 |\n|-----------|----------|------|\n| HTML5 | ✅ 完全支持 | 支持所有 HTML5 标签 |\n| SVG | ⚠️ 部分支持 | 基本支持，部分复杂 SVG 可能无法正确转换 |\n| MathJax/LaTeX | ⚠️ 需要插件 | 需要额外配置 |\n| 嵌入式视频 | ❌ 不支持 | 会被转换为链接或忽略 |\n\n## 相关文件\n\n| 文件路径 | 描述 |\n|----------|------|\n| `crawl4ai/markdown_generation_strategy.py` | Markdown 生成策略定义与实现 |\n| `crawl4ai/content_filter_strategy.py` | 内容过滤策略定义与实现 |\n| `crawl4ai/html2text/__init__.py` | html2text 主模块 |\n| `crawl4ai/html2text/elements.py` | HTML 元素处理规则 |\n| `crawl4ai/html2text/config.py` | 配置参数定义 |\n\n---\n\n\n\n## 数据提取策略\n\n### 相关页面\n\n相关主题：[分块与过滤策略](#page-chunking-filtering), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/extraction_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/extraction_strategy.py)\n- [crawl4ai/content_scraping_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_scraping_strategy.py)\n- [crawl4ai/table_extraction.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/table_extraction.py)\n- [crawl4ai/crawlers/amazon_product/crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/crawlers/amazon_product/crawler.py)\n- [crawl4ai/crawlers/google_search/crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/crawlers/google_search/crawler.py)\n\n\n# 数据提取策略\n\n## 概述\n\n数据提取策略是 crawl4ai 框架中用于从网页内容中精准提取结构化数据的核心模块。该策略系统设计灵活，支持多种提取方式，涵盖从简单的 CSS 选择器匹配到基于大语言模型（LLM）的智能语义提取。\n\n## 架构设计\n\n### 策略类型体系\n\ncrawl4ai 的数据提取策略采用策略模式（Strategy Pattern）设计，主要包含以下几种策略类型：\n\n```mermaid\ngraph TD\n A[ExtractionStrategy 基类] --> B[NoExtractionStrategy]\n A --> C[BeautifulSoupExtractionStrategy]\n A --> D[LLMExtractionStrategy]\n A --> E[JsonCssExtractionStrategy]\n A --> F[RegexExtractionStrategy]\n \n B --> G[不使用任何提取]\n C --> H[基于 CSS 选择器的结构化提取]\n D --> I[基于 LLM 的语义理解提取]\n E --> J[JSON + CSS 组合提取]\n F --> K[正则表达式模式匹配]\n```\n\n### 核心组件关系\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| ExtractionStrategy | extraction_strategy.py | 策略基类，定义标准化接口 |\n| ContentScrapingStrategy | content_scraping_strategy.py | 内容抓取策略，处理原始内容获取 |\n| TableExtraction | table_extraction.py | 表格数据专项提取 |\n| CrawlerStrategy | 各爬虫子模块 | 具体业务场景的实现 |\n\n## 策略详解\n\n### NoExtractionStrategy\n\n默认策略，不执行任何数据提取操作。适用于只需要获取完整页面内容或 HTML 的场景。\n\n```python\n# 使用示例\nresult = await crawler.crawl(\n url=\"https://example.com\",\n extraction_strategy=NoExtractionStrategy()\n)\n```\n\n### BeautifulSoupExtractionStrategy\n\n基于 BeautifulSoup4 的结构化数据提取策略，通过 CSS 选择器精确定位页面元素。\n\n**配置参数：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| css_selector | str | None | CSS 选择器表达式 |\n| filter_regex | str | None | 内容过滤正则表达式 |\n| check_interval | float | 0.2 | 检查间隔（秒） |\n| timeout | int | 7 | 超时时间（秒） |\n\n### LLMExtractionStrategy\n\n基于大语言模型的智能提取策略，能够理解页面语义并提取非结构化或半结构化数据。\n\n**核心参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| prompt | str | 是 | 提取指令提示词 |\n| schema | dict | 否 | 输出数据 schema 定义 |\n| extraction_type | str | 否 | 提取类型标识 |\n\n### JsonCssExtractionStrategy\n\n结合 JSONPath 和 CSS 选择器的混合提取策略，适用于复杂的嵌套数据结构。\n\n### RegexExtractionStrategy\n\n基于正则表达式的文本模式提取策略，适合处理日志、代码片段等结构化文本。\n\n## 内容抓取策略\n\nContentScrapingStrategy 负责处理内容获取阶段的策略配置，主要包含以下抓取模式：\n\n```mermaid\ngraph LR\n A[网页请求] --> B[ScrapingMode 选择]\n B --> C[全量 HTML]\n B --> D[无标签文本]\n B --> E[结构化内容]\n \n C --> F[beautifulsoup 处理]\n D --> G[正则清理]\n E --> H[语义分析]\n```\n\n**支持的抓取模式：**\n\n| 模式名称 | 说明 | 适用场景 |\n|---------|------|---------|\n| html | 完整 HTML 源码 | 需要保留原始标签结构 |\n| text | 纯文本内容 | 文本分析和 NLP 处理 |\n| fit_markdown | Markdown 格式 | 文档转换和内容摘要 |\n|.cleaned | 清理后内容 | 去除脚本和样式噪音 |\n\n## 表格提取机制\n\nTableExtraction 是 crawl4ai 中专门处理 HTML 表格数据提取的模块。\n\n### 提取流程\n\n```mermaid\ngraph TD\n A[定位 table 元素] --> B[识别表头行]\n B --> C[遍历数据行]\n C --> D{是否跨列/跨行?}\n D -->|是| E[处理单元格合并]\n D -->|否| F[直接提取]\n E --> G[构建单元格映射]\n F --> H[转换为列表/字典]\n G --> H\n H --> I[输出 JSON 格式]\n```\n\n### 表格数据结构\n\n提取的表格数据以列表形式返回，每行对应一个字典对象：\n\n```python\n[\n {\"列名1\": \"值1\", \"列名2\": \"值2\"},\n {\"列名1\": \"值3\", \"列名2\": \"值4\"}\n]\n```\n\n## 领域专用爬虫示例\n\n### 亚马逊产品爬虫\n\nAmazon 产品爬虫继承基础提取策略，针对电商页面结构优化：\n\n```python\n# 资料来源：crawl4ai/crawlers/amazon_product/crawler.py\nclass AmazonProductCrawler:\n def __init__(self, extraction_strategy):\n self.strategy = extraction_strategy\n```\n\n### 谷歌搜索爬虫\n\n谷歌搜索爬虫实现特定的搜索结果提取逻辑：\n\n```python\n# 资料来源：crawl4ai/crawlers/google_search/crawler.py\nclass GoogleSearchCrawler:\n async def crawl(self, query: str):\n # 实现搜索结果提取\n```\n\n## 使用最佳实践\n\n### 策略选择指南\n\n| 应用场景 | 推荐策略 | 理由 |\n|---------|---------|-----|\n| 简单表格/列表 | BeautifulSoupExtractionStrategy | 性能高效，精度高 |\n| 语义复杂内容 | LLMExtractionStrategy | 理解能力强 |\n| 结构化日志 | RegexExtractionStrategy | 模式匹配灵活 |\n| 嵌套 JSON | JsonCssExtractionStrategy | 混合查询支持 |\n| 快速原型 | NoExtractionStrategy | 零配置启动 |\n\n### 性能优化建议\n\n1. **优先使用 CSS 选择器**：在数据格式已知的情况下，BeautifulSoup 策略性能优于 LLM 策略\n2. **设置合理的超时时间**：避免大型页面导致的长时间等待\n3. **启用检查间隔**：对于动态加载内容，适当增加 check_interval\n4. **批量提取优化**：多条数据使用同一策略实例，减少初始化开销\n\n## 扩展开发指南\n\n如需创建自定义提取策略，需继承 ExtractionStrategy 基类并实现核心方法：\n\n```python\nfrom crawl4ai.extraction_strategy import ExtractionStrategy\n\nclass CustomExtractionStrategy(ExtractionStrategy):\n async def extract(self, html: str, url: str) -> List[Dict]:\n # 实现自定义提取逻辑\n pass\n```\n\n## 版本兼容性\n\n数据提取策略模块在不同版本间保持接口兼容性，详见项目 CHANGELOG 获取版本特定说明。\n\n---\n\n**相关文档：**\n- [用户指南](../docs/user-guide.md)\n- [API 参考](../api_reference/)\n- [示例代码](../examples/)\n\n---\n\n\n\n## 分块与过滤策略\n\n### 相关页面\n\n相关主题：[数据提取策略](#page-extraction-strategies), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/chunking_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/chunking_strategy.py)\n- [crawl4ai/content_filter_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_filter_strategy.py)\n- [crawl4ai/model_loader.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/model_loader.py)\n- [crawl4ai/prompts.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/prompts.py)\n\n\n# 分块与过滤策略\n\n## 概述\n\n在 Crawl4ai 项目中，**分块策略（Chunking Strategy）** 和 **过滤策略（Content Filter Strategy）** 是两个核心模块，它们共同负责将爬取的网页内容转化为结构化、可处理的文本块。这两个策略在数据处理流程中扮演着至关重要的角色，它们使得大规模网页内容能够被有效地分割、过滤和组织，以满足大语言模型（LLM）训练、知识库构建等应用场景的需求。\n\n分块策略的主要功能是将长文本内容按照预定义的规则（如字符数、句子边界、段落等）分割成较小的、语义相对完整的块（Chunk）。这种分割方式能够确保每个文本块具有足够的上下文信息，同时保持适当的粒度便于后续处理。过滤策略则负责识别并保留最具价值的文本内容，同时去除导航菜单、广告脚本、页脚信息等无用的噪音内容。这两个策略的协同工作形成了 Crawl4ai 内容处理管道的核心环节。\n\n从架构设计的角度来看，分块与过滤策略都遵循了策略模式（Strategy Pattern）的设计原则。这种设计允许用户在运行时动态选择和配置不同的分块或过滤算法，而无需修改核心处理逻辑。每个策略都实现了统一的接口定义，确保了模块之间的松耦合和高度可扩展性。这种灵活性使得 Crawl4ai 能够适应各种不同的内容处理场景和需求变化。\n\n## 分块策略详解\n\n### 工作原理\n\n分块策略的核心目标是将输入的文本内容按照特定规则进行分割，生成一系列语义相对完整的文本块。在实现层面，分块策略首先会对输入文本进行分析，识别出文本的内在结构（如句子、段落、标题等），然后根据预定义的参数（如最大块大小、重叠大小等）将文本切分为多个块。每个块都包含了一定量的上下文信息，同时保持相对独立的语义完整性。\n\n分块过程通常遵循以下基本流程：首先，策略会接收原始文本内容和相关配置参数；然后，对文本进行预处理，包括清理格式、识别结构等；接着，根据选定的分块算法执行分割操作；最后，对生成的块进行后处理，包括清理空块、合并过小的块等。整个过程旨在最大化每个块的实用价值，同时最小化信息丢失和上下文割裂。\n\n### 配置参数\n\n分块策略的行为可以通过多个参数进行精细控制，这些参数决定了分块的大小、重叠方式以及边界处理逻辑。以下是主要的配置选项：\n\n| 参数名称 | 类型 | 默认值 | 说明 |\n|---------|------|--------|------|\n| chunk_word_count | int | 1024 | 每个块的近似单词数目标值 |\n| overlap | int | 100 | 块之间的重叠单词数 |\n| overlap_all_sections | bool | False | 是否在所有章节间应用重叠 |\n| combine_sentences | bool | False | 是否将短句合并为完整段落 |\n| max_characters_per_section | int | 1500 | 每个章节的最大字符数 |\n| overlap_rate | float | 0.1 | 重叠率，overlap_rate * chunk_word_count |\n| extra_system_prompt | str | \"\" | 额外的系统提示词 |\n| user_prompt | str | \"\" | 用户自定义提示词模板 |\n\n这些参数可以根据具体的应用场景进行调整。例如，当需要较短的块用于精确检索时，可以减小 `chunk_word_count` 的值；当需要保留更多上下文信息时，可以增加 `overlap` 或 `overlap_rate` 的值以实现块之间的信息重叠。`overlap_all_sections` 参数特别有用，因为它确保了跨章节边界的语义连贯性。\n\n### 分块算法实现\n\n在具体实现层面，Crawl4ai 提供了多种分块算法的实现。以基于字数的分块为例，该算法会遍历文本内容，累积单词直到达到目标块大小，然后在该位置附近（通常在句子边界处）进行截断，生成一个新的块。这种方法简单高效，适用于大多数场景。\n\n对于更复杂的场景，系统还支持基于语义的分块方法。这种方法会结合自然语言处理技术，识别文本中的语义边界（如主题转换点），并在这些位置进行分割。语义分块能够产生更加连贯、信息密度更高的文本块，但计算成本也相对较高。算法实现中会调用语言模型来辅助判断语义边界，这部分功能与 `model_loader.py` 中定义的模型加载机制紧密相关。\n\n```mermaid\ngraph TD\n A[原始文本输入] --> B[文本预处理]\n B --> C[结构识别]\n C --> D{分块算法选择}\n D -->|字数分块| E[按字数累积]\n D -->|语义分块| F[语义边界分析]\n E --> G[句子边界截断]\n F --> G\n G --> H[生成文本块]\n H --> I[重叠处理]\n I --> J[块后处理]\n J --> K[输出块列表]\n```\n\n### 自定义分块策略\n\nCrawl4ai 的架构设计允许开发者实现自定义的分块策略。要创建自定义策略，需要继承基础的分块策略类并实现核心的 `chunk()` 方法。方法签名通常接受原始文本内容和可选的配置参数，返回一个文本块列表。这种设计使得系统具有极强的扩展性，能够适应各种特殊的内容处理需求。\n\n自定义策略的实现需要考虑多个方面：首先是分块逻辑的准确性，确保生成的块符合预期的格式和质量标准；其次是性能优化，特别是处理大规模文本时需要考虑计算效率；最后是错误处理机制，需要妥善处理各种异常情况如空文本、格式错误等。通过继承和扩展基础类，开发者可以专注于实现特定的分块逻辑，而无需关心与其他模块的集成细节。\n\n## 过滤策略详解\n\n### 目的与作用\n\n内容过滤策略的主要目的是从爬取的网页内容中识别并提取高价值的文本信息，同时过滤掉导航菜单、页脚、版权声明、广告脚本等无意义的内容。这一步骤对于后续的内容处理至关重要，因为它直接影响到生成的知识库的纯净度和可用性。一个设计良好的过滤策略能够显著提升内容的信号噪声比，使得检索和问答等下游任务能够获得更准确的结果。\n\n过滤策略的实现通常依赖于启发式规则和机器学习模型的结合。在传统方法中，系统会基于 HTML 标签类型、CSS 类名、元素位置等特征来判断内容的价值。例如，包含 \"nav\"、\"footer\"、\"sidebar\"、\"advertisement\" 等关键词的元素通常会被标记为低价值内容。在更高级的实现中，系统还会结合语言模型来理解内容的语义，进一步提升过滤的准确性。\n\n### 过滤机制\n\n过滤机制的实现涉及多个层次的判断逻辑。在最基础的层面，系统会基于 HTML 结构特征进行粗过滤，识别并排除明显无用的内容块。这包括脚本标签、样式标签、隐藏元素、以及某些特定的 HTML 标签类型。通过分析元素的可见性、大小、位置等属性，系统可以快速排除大量低价值内容。\n\n在更精细的层面，过滤策略会结合文本内容的语义分析。这部分功能与 `prompts.py` 中定义的提示词模板紧密相关。系统会使用特定的提示词引导语言模型对内容块进行价值评估，判断其是否包含实质性的信息内容。评估结果会被用于决定是否保留该内容块，或者将其标记为需要进一步处理或直接过滤。\n\n```mermaid\ngraph TD\n A[网页内容输入] --> B[HTML结构分析]\n B --> C[标签类型过滤]\n C --> D[可见性检查]\n D --> E[语义分析]\n E --> F{价值评估}\n F -->|高价值| G[保留内容]\n F -->|低价值| H[过滤内容]\n F -->|不确定| I[模型辅助判断]\n I --> G\n I --> H\n```\n\n### 过滤策略类型\n\nCrawl4ai 提供了多种预定义的过滤策略，以适应不同的内容处理需求。这些策略包括基于规则的方法、基于统计的方法和基于深度学习的方法。每种策略都有其特定的优势和适用场景，用户可以根据实际需求选择最合适的策略类型。\n\n**关键词过滤策略** 是最基础的方法，它通过预定义的关键词列表来识别和过滤无价值内容。这种方法简单高效，但可能无法处理所有变体和无规律的噪音内容。**正则表达式过滤策略** 提供了更灵活的模式匹配能力，能够处理更复杂的过滤规则。**基于模型的质量过滤策略** 则利用机器学习模型来评估内容的价值，能够捕捉更深层次的语义特征。\n\n| 策略类型 | 优点 | 缺点 | 适用场景 |\n|---------|------|------|---------|\n| 关键词过滤 | 速度快、简单易用 | 准确性有限 | 快速处理、结构化内容 |\n| 正则过滤 | 灵活性高、可定制 | 需要手动编写规则 | 特定格式内容 |\n| 模型过滤 | 准确性高、适应性强 | 计算成本较高 | 高质量需求场景 |\n| 混合过滤 | 综合多种方法优势 | 配置复杂 | 通用场景 |\n\n## 与模型加载器的集成\n\n### 模型加载机制\n\n分块和过滤策略的执行往往需要语言模型的参与。`model_loader.py` 模块提供了统一的模型加载和管理接口，使得策略能够便捷地访问语言模型能力。这个模块封装了模型初始化、配置管理、推理调用等核心功能，为上层策略提供了一个简洁而强大的模型访问层。\n\n模型加载器支持多种模型类型和部署方式，包括本地模型和云端 API。配置参数允许用户指定模型的类型、版本、API 密钥等必要信息。加载器会自动处理模型缓存、多实例管理、请求批处理等底层细节，使得策略实现者能够专注于业务逻辑而无需关心模型调用的基础设施问题。\n\n### 在策略中的应用\n\n在分块策略中，模型主要被用于语义分块和质量评估。当启用语义分块模式时，系统会调用模型来分析文本的语义结构，识别主题转换点和最佳分割位置。在过滤策略中，模型被用于深度内容理解，评估文本块的语义价值和相关性。这些应用都需要模型加载器提供稳定可靠的模型访问服务。\n\n模型的使用涉及性能优化和成本控制两个关键考量。在性能方面，系统实现了请求批处理、模型缓存、推理结果缓存等优化机制，以减少重复计算和 API 调用延迟。在成本方面，系统支持多种模型选择，从高性能高成本的模型到轻量级低成本模型的梯度配置，用户可以根据需求权衡效果和成本。\n\n## 提示词集成\n\n### 提示词模板\n\n`prompts.py` 模块定义了分块和过滤策略使用的各种提示词模板。这些模板经过精心设计，能够有效地引导语言模型执行内容分析、价值评估、语义分割等任务。提示词的质量直接影响策略的执行效果，因此模板的设计和优化是策略开发的重要环节。\n\n提示词模板采用结构化设计，包含系统提示和用户提示两个部分。系统提示定义了模型的角色定位和基本行为准则，用户提示则包含了具体的任务描述和输入内容。这种设计使得提示词具有良好的可读性和可维护性，同时也方便根据不同场景进行定制和优化。\n\n### 自定义提示词\n\n用户可以通过配置参数自定义提示词内容，以适应特定的内容处理需求。例如，`extra_system_prompt` 参数允许在系统提示中添加额外的指令，`user_prompt` 参数允许用户自定义用户提示的模板结构。这种灵活性使得系统能够适应各种特殊的内容处理场景和领域需求。\n\n自定义提示词时需要注意几个关键要点：首先是提示词的清晰性和具体性，模糊的指令可能导致模型产生不一致的结果；其次是提示词的长度和复杂性，过长的提示词可能增加处理成本和延迟；最后是提示词的格式兼容性，确保自定义提示词与系统其他部分能够良好集成。\n\n## 实际应用示例\n\n### 基本使用流程\n\n在实际应用中，分块和过滤策略通常作为数据处理管道的一环被调用。用户首先配置所需的策略参数，然后调用执行方法处理输入内容。整个过程是自动化的，用户只需关注输入输出的管理。以下是一个典型的使用场景：\n\n```python\nfrom crawl4ai import ChunkingStrategy, ContentFilterStrategy\n\n# 配置分块策略\nchunking_strategy = ChunkingStrategy(\n chunk_word_count=512,\n overlap=50,\n overlap_all_sections=True\n)\n\n# 配置过滤策略\nfilter_strategy = ContentFilterStrategy(\n model=\"gpt-4\",\n filter_type=\"semantic\"\n)\n\n# 执行处理\ncontent = \"待处理的网页文本内容...\"\nchunks = chunking_strategy.chunk(content)\nfiltered_chunks = filter_strategy.filter(chunks)\n```\n\n### 最佳实践建议\n\n在实际使用中，有几个关键的优化建议值得关注。首先是分块大小的选择，需要根据下游任务的需求进行权衡：较小的块适合精确检索，但可能缺乏足够的上下文；较大的块包含更丰富的上下文，但可能引入噪音。其次是重叠参数的设置，适当的重叠能够保证跨块边界的语义连续性，特别是在涉及长程依赖的任务中。\n\n过滤策略的选择和配置同样需要根据具体场景进行调整。对于新闻类内容，可以侧重于正文提取和标题识别；对于论坛讨论类内容，则需要更智能的噪音过滤以排除签名档和重复引用。对于包含大量代码的项目文档，还需要特别注意代码块的识别和保留，避免被误过滤。\n\n## 技术规格总结\n\n| 组件 | 位置 | 主要功能 | 可扩展性 |\n|------|------|---------|---------|\n| ChunkingStrategy | chunking_strategy.py | 文本分块处理 | 支持自定义实现 |\n| ContentFilterStrategy | content_filter_strategy.py | 内容质量过滤 | 支持多种过滤模式 |\n| ModelLoader | model_loader.py | 模型访问管理 | 支持多种模型类型 |\n| PromptManager | prompts.py | 提示词管理 | 支持自定义模板 |\n\n分块与过滤策略作为 Crawl4ai 的核心组件，共同构成了网页内容智能处理的基础设施。通过合理配置和使用这些策略，用户可以实现高效、准确的大规模网页内容处理，为各种下游任务提供高质量的数据支持。系统的模块化设计确保了良好的可维护性和可扩展性，使得用户能够根据实际需求进行灵活定制和优化。\n\n---\n\n\n\n## 浏览器配置与代理\n\n### 相关页面\n\n相关主题：[高级功能](#page-advanced-features), [异步网页爬虫核心](#page-async-webcrawler)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/browser_manager.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_manager.py)\n- [crawl4ai/browser_adapter.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_adapter.py)\n- [crawl4ai/browser_profiler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_profiler.py)\n- [crawl4ai/proxy_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/proxy_strategy.py)\n- [crawl4ai/ssl_certificate.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/ssl_certificate.py)\n- [crawl4ai/user_agent_generator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/user_agent_generator.py)\n\n\n# 浏览器配置与代理\n\n## 概述\n\n浏览器配置与代理模块是 crawl4ai 框架中负责管理浏览器实例配置、代理设置、SSL证书处理以及用户代理字符串生成的核心组件。该模块提供了灵活的浏览器定制能力，使爬虫能够适应不同的目标网站环境，包括需要身份验证、SSL证书处理、代理跳转等复杂场景。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[BrowserConfig] --> B[BrowserManager]\n A --> C[BrowserAdapter]\n A --> D[BrowserProfiler]\n E[ProxyStrategy] --> B\n F[SSLConfig] --> B\n G[UserAgentGenerator] --> B\n B --> H[Playwright Browser]\n C --> I[BrowserController]\n D --> J[BrowserPool]\n```\n\n## 核心组件\n\n### BrowserManager\n\nBrowserManager 是浏览器管理的核心类，负责浏览器的生命周期管理、实例化、配置应用和资源清理。\n\n```mermaid\ngraph LR\n A[创建配置] --> B[初始化浏览器]\n B --> C[应用代理]\n C --> D[设置SSL]\n D --> E[生成User-Agent]\n E --> F[浏览器就绪]\n F --> G[执行爬取]\n G --> H[资源释放]\n```\n\n**主要职责：**\n- 管理浏览器实例的创建和销毁\n- 配置浏览器启动参数\n- 应用代理和SSL设置\n- 处理浏览器上下文隔离\n\n**配置参数表：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| headless | bool | True | 是否无头模式运行 |\n| browser_type | str | \"chromium\" | 浏览器类型（chromium/firefox/webkit） |\n| proxy_config | ProxyConfig | None | 代理配置对象 |\n| ssl_config | SSLConfig | None | SSL证书配置 |\n| user_agent | str | None | 自定义User-Agent |\n| viewport | dict | {\"width\": 1920, \"height\": 1080} | 视口大小 |\n| args | list | [] | 额外的浏览器启动参数 |\n| ignoreHTTPSErrors | bool | False | 是否忽略HTTPS错误 |\n| java_script_enabled | bool | True | 是否启用JavaScript |\n\n资料来源：[browser_manager.py:1-100]()\n\n### BrowserAdapter\n\nBrowserAdapter 提供了浏览器操作的高级抽象接口，封装了常见的浏览器交互操作。\n\n**核心功能：**\n- 页面导航和导航控制\n- 元素选择和交互\n- 截图和PDF生成\n- 控制台日志捕获\n- 网络请求拦截\n\n```python\nclass BrowserAdapter:\n def __init__(self, config: BrowserConfig):\n self.config = config\n self.browser = None\n self.context = None\n self.page = None\n```\n\n资料来源：[browser_adapter.py:1-50]()\n\n### BrowserProfiler\n\nBrowserProfiler 用于浏览器性能分析和会话追踪，帮助诊断浏览器行为和性能问题。\n\n**功能特性：**\n- 记录浏览器启动时间\n- 追踪页面加载性能\n- 统计资源使用情况\n- 生成性能报告\n\n```mermaid\ngraph TD\n A[开始分析] --> B[捕获事件]\n B --> C{事件类型}\n C --> D[性能指标]\n C --> E[资源加载]\n C --> F[控制台日志]\n D --> G[生成报告]\n E --> G\n F --> G\n```\n\n资料来源：[browser_profiler.py:1-80]()\n\n## 代理配置\n\n### ProxyConfig 数据模型\n\n```python\nclass ProxyConfig:\n server: str # 代理服务器地址，格式: protocol://host:port\n username: str # 认证用户名（可选）\n password: str # 认证密码（可选）\n bypass_list: list # 绕过代理的地址列表（可选）\n```\n\n**支持的代理协议：**\n\n| 协议 | 格式示例 | 支持情况 |\n|------|----------|----------|\n| HTTP | http://proxy.example.com:8080 | ✅ 完全支持 |\n| HTTPS | https://proxy.example.com:8080 | ✅ 完全支持 |\n| SOCKS4 | socks4://proxy.example.com:1080 | ✅ 完全支持 |\n| SOCKS5 | socks5://proxy.example.com:1080 | ✅ 完全支持 |\n\n### ProxyStrategy\n\nProxyStrategy 实现了多种代理策略，支持自动代理切换和负载均衡。\n\n```mermaid\ngraph TD\n A[请求发起] --> B{代理策略选择}\n B --> C[轮询策略]\n B --> D[随机策略]\n B --> E[故障转移策略]\n C --> F[选择代理]\n D --> F\n E --> F\n F --> G[应用代理]\n G --> H{请求结果}\n H -->|成功| I[记录成功]\n H -->|失败| J[重试或切换]\n J --> F\n```\n\n**代理策略类型：**\n\n| 策略名称 | 说明 | 适用场景 |\n|----------|------|----------|\n| RoundRobinStrategy | 轮询策略，依次使用每个代理 | 负载均衡 |\n| RandomStrategy | 随机选择代理 | 避免请求模式被检测 |\n| FailoverStrategy | 故障转移，主代理失败时切换 | 高可用性 |\n| PriorityStrategy | 按优先级顺序尝试 | 优先使用高速代理 |\n\n资料来源：[proxy_strategy.py:1-120]()\n\n### 代理配置示例\n\n```python\nfrom crawl4ai import BrowserConfig, ProxyConfig\n\n# 简单代理配置\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\"\n)\n\n# 带认证的代理配置\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\",\n username=\"user123\",\n password=\"pass456\"\n)\n\n# 配置绕过列表\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\",\n bypass_list=[\"localhost\", \"*.internal\"]\n)\n\nbrowser_config = BrowserConfig(\n proxy_config=proxy_config,\n headless=True\n)\n```\n\n## SSL 证书处理\n\n### SSLConfig 数据模型\n\n```python\nclass SSLConfig:\n ignore_ssl_errors: bool # 是否忽略SSL错误\n client_cert: str # 客户端证书路径\n client_key: str # 客户端私钥路径\n ca_cert: str # CA证书路径\n```\n\n**配置参数表：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| ignore_ssl_errors | bool | False | 忽略证书验证错误 |\n| client_cert | str | None | PEM格式客户端证书路径 |\n| client_key | str | None | PEM格式私钥路径 |\n| ca_cert | str | None | CA证书文件路径 |\n| accept_insecure_certs | bool | False | 接受无效证书 |\n\n资料来源：[ssl_certificate.py:1-60]()\n\n### 使用场景\n\n**场景一：忽略证书错误**\n\n适用于测试环境或内部网络：\n\n```python\nssl_config = SSLConfig(ignore_ssl_errors=True)\nbrowser_config = BrowserConfig(ssl_config=ssl_config)\n```\n\n**场景二：使用客户端证书**\n\n适用于需要双向SSL认证的场景：\n\n```python\nssl_config = SSLConfig(\n client_cert=\"/path/to/cert.pem\",\n client_key=\"/path/to/key.pem\",\n ca_cert=\"/path/to/ca.pem\"\n)\nbrowser_config = BrowserConfig(ssl_config=ssl_config)\n```\n\n## 用户代理管理\n\n### UserAgentGenerator\n\nUserAgentGenerator 负责生成和管理用户代理字符串，支持多种配置选项。\n\n```mermaid\ngraph TD\n A[UA生成请求] --> B{生成模式}\n B --> C[固定UA]\n B --> D[随机UA]\n B --> E[真实浏览器UA]\n C --> F[返回UA字符串]\n D --> G[选择设备类型]\n G --> F\n E --> H[模拟真实环境]\n H --> F\n```\n\n**生成模式：**\n\n| 模式 | 说明 | 示例 |\n|------|------|------|\n| fixed | 使用指定的固定UA | \"Mozilla/5.0...\" |\n| random | 从预设列表随机选择 | 随机桌面浏览器UA |\n| real_browser | 模拟真实浏览器环境 | Chrome on Windows |\n| mobile | 移动设备UA | iPhone Safari |\n\n资料来源：[user_agent_generator.py:1-90]()\n\n### 预设浏览器类型\n\n| 浏览器 | 平台 | User-Agent 示例 |\n|--------|------|------------------|\n| Chrome | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 |\n| Chrome | macOS | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 |\n| Chrome | Linux | Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 |\n| Firefox | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 |\n| Safari | iOS | Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) |\n| Edge | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/115.0.0.0 |\n\n### 使用示例\n\n```python\nfrom crawl4ai import BrowserConfig, UserAgentGenerator\n\n# 使用随机UA\nua_generator = UserAgentGenerator(mode=\"random\")\nbrowser_config = BrowserConfig(\n user_agent=ua_generator.generate()\n)\n\n# 使用固定UA\nbrowser_config = BrowserConfig(\n user_agent=\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36\"\n)\n\n# 使用真实浏览器模拟\nua_generator = UserAgentGenerator(mode=\"real_browser\")\nbrowser_config = BrowserConfig(\n user_agent=ua_generator.generate(device_type=\"mobile\")\n)\n```\n\n## 浏览器配置工作流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant BM as BrowserManager\n participant PA as ProxyAdapter\n participant SS as SSLHandler\n participant UA as UserAgentGenerator\n participant Browser as Playwright Browser\n\n User->>BM: 创建BrowserConfig\n BM->>UA: 请求User-Agent\n UA-->>BM: 返回UA字符串\n BM->>PA: 应用代理配置\n PA->>BM: 代理配置完成\n BM->>SS: 配置SSL设置\n SS-->>BM: SSL配置完成\n BM->>Browser: 启动浏览器实例\n Browser-->>BM: 浏览器就绪\n BM-->>User: 返回配置好的浏览器\n```\n\n## 高级配置选项\n\n### 浏览器启动参数\n\n```python\nbrowser_config = BrowserConfig(\n args=[\n \"--disable-blink-features=AutomationControlled\",\n \"--disable-dev-shm-usage\",\n \"--no-sandbox\",\n \"--disable-setuid-sandbox\",\n \"--disable-gpu\",\n \"--disable-web-security\",\n \"--disable-features=IsolateOrigins,site-per-process\"\n ]\n)\n```\n\n**常用启动参数表：**\n\n| 参数 | 说明 | 风险等级 |\n|------|------|----------|\n| --disable-blink-features=AutomationControlled | 隐藏自动化特征 | 低 |\n| --disable-dev-shm-usage | 避免共享内存问题 | 低 |\n| --no-sandbox | 禁用沙箱（Docker环境需要） | 高 |\n| --disable-setuid-sandbox | 禁用setuid沙箱 | 中 |\n| --disable-gpu | 禁用GPU加速 | 低 |\n| --disable-web-security | 禁用Web安全 | 高 |\n| --headless=new | 使用新版无头模式 | 低 |\n\n### 上下文隔离配置\n\n```python\nbrowser_config = BrowserConfig(\n context_options={\n \"locale\": \"zh-CN\",\n \"timezone_id\": \"Asia/Shanghai\",\n \"viewport\": {\"width\": 1920, \"height\": 1080},\n \"color_scheme\": \"dark\",\n \"extra_http_headers\": {\n \"Accept-Language\": \"zh-CN,zh;q=0.9\",\n \"Accept-Encoding\": \"gzip, deflate, br\"\n }\n }\n)\n```\n\n## 最佳实践\n\n### 配置优先级\n\n1. **安全优先**：在生产环境中禁用 `--disable-web-security`\n2. **性能优化**：合理设置视口大小，避免不必要的大图渲染\n3. **稳定性**：在Docker环境中添加 `--no-sandbox` 和 `--disable-dev-shm-usage`\n4. **反检测**：结合使用随机UA、真实视口和代理\n\n### 配置验证清单\n\n- [ ] 确认代理服务器可达性\n- [ ] 验证SSL证书配置正确\n- [ ] 测试UA字符串有效性\n- [ ] 检查浏览器参数兼容性\n- [ ] 验证上下文配置生效\n\n## 相关文件\n\n| 文件路径 | 功能描述 |\n|----------|----------|\n| [browser_manager.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_manager.py) | 浏览器生命周期管理 |\n| [browser_adapter.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_adapter.py) | 浏览器操作接口抽象 |\n| [browser_profiler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_profiler.py) | 性能分析和追踪 |\n| [proxy_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/proxy_strategy.py) | 代理策略实现 |\n| [ssl_certificate.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/ssl_certificate.py) | SSL证书处理 |\n| [user_agent_generator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/user_agent_generator.py) | User-Agent生成管理 |\n\n---\n\n\n\n## 高级功能\n\n### 相关页面\n\n相关主题：[浏览器配置与代理](#page-browser-config), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/antibot_detector.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/antibot_detector.py)\n- [crawl4ai/adaptive_crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/adaptive_crawler.py)\n- [crawl4ai/js_snippet/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/js_snippet/__init__.py)\n- [crawl4ai/link_preview.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/link_preview.py)\n- [crawl4ai/async_dispatcher.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_dispatcher.py)\n\n\n# 高级功能\n\n## 概述\n\ncrawl4ai的高级功能模块提供了企业级网页爬取的增强能力，包括反机器人检测规避、自适应爬取策略、JavaScript动态内容注入、链接预览生成以及异步并发调度等核心功能。这些模块协同工作，使爬虫能够应对复杂的网络环境和严格的反爬机制，同时保持高效的资源利用率。\n\n## 架构总览\n\n```mermaid\ngraph TD\n A[用户请求] --> B[async_dispatcher 异步调度器]\n B --> C[adaptive_crawler 自适应爬虫]\n C --> D[antibot_detector 反机器人检测]\n C --> E[js_snippet JavaScript注入]\n E --> F[动态内容渲染]\n D --> G{检测结果}\n G -->|通过| F\n G -->|触发| H[策略调整]\n H --> C\n F --> I[link_preview 链接预览生成]\n I --> J[结果输出]\n```\n\n## 反机器人检测模块\n\n### 功能定位\n\n`antibot_detector` 模块负责检测目标网站是否部署了反机器人机制，并提供相应的规避建议。该模块通过分析响应特征、Cookie行为、JavaScript挑战等信号来判断当前爬取是否触发了反爬防护。\n\n### 核心检测机制\n\n| 检测类型 | 描述 | 判定依据 |\n|---------|------|----------|\n| 指纹检测 | 识别浏览器指纹特征缺失 | User-Agent、Canvas、WebGL |\n| 行为检测 | 分析异常访问模式 | 请求频率、访问路径 |\n| JavaScript挑战 | 检测JS质询页面 | 验证码、Cookie重置 |\n| 蜜罐检测 | 识别隐藏链接陷阱 | CSS隐藏元素、点击诱饵 |\n\n### 集成方式\n\n该模块与自适应爬虫深度集成，当检测到反机器人信号时，会自动触发爬取策略的动态调整流程。\n\n资料来源：[crawl4ai/antibot_detector.py:1-50](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/antibot_detector.py)\n\n## 自适应爬虫\n\n### 设计理念\n\n`adaptive_crawler` 模块实现了智能化的爬取策略调整机制，能够根据目标网站的响应特征自动优化爬取参数。这种自适应能力使系统能够在不同网站环境中保持稳定的爬取效率。\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|--------|------|\n| `max_retries` | int | 3 | 最大重试次数 |\n| `retry_delay` | float | 1.0 | 重试间隔（秒） |\n| `timeout` | int | 30 | 请求超时时间 |\n| `use_cache` | bool | True | 启用缓存机制 |\n\n### 策略调整流程\n\n```mermaid\ngraph LR\n A[发起请求] --> B{响应状态}\n B -->|200| C[成功解析]\n B -->|429| D[触发限流]\n B -->|403| E[反爬拦截]\n B -->|5xx| F[服务器错误]\n D --> G[增加延迟]\n E --> H[启用JS渲染]\n F --> I[指数退避]\n G --> A\n H --> C\n I --> A\n```\n\n### 动态适应策略\n\n自适应爬虫支持以下策略模式：\n\n1. **保守模式**：优先降低触发反爬的概率，牺牲部分爬取速度\n2. **平衡模式**：在速度和成功率之间取得平衡\n3. **激进模式**：最大化爬取速度，适用于已知友好的网站\n\n资料来源：[crawl4ai/adaptive_crawler.py:1-80](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/adaptive_crawler.py)\n\n## JavaScript 代码注入\n\n### 模块职责\n\n`js_snippet` 模块提供了在页面加载后执行自定义JavaScript代码的能力，这对于处理单页应用（SPA）和需要客户端渲染的内容至关重要。该模块支持注入预定义的代码片段以及用户自定义的JavaScript逻辑。\n\n### 预定义代码片段\n\n| 片段名称 | 用途 | 典型场景 |\n|---------|------|----------|\n| `scroll_to_bottom` | 滚动至页面底部 | 触发懒加载内容 |\n| `extract_dynamic_content` | 提取动态渲染内容 | 获取JS生成的数据 |\n| `wait_for_element` | 等待特定元素加载 | 确保关键内容就绪 |\n| `simulate_human_behavior` | 模拟人类行为 | 降低被检测概率 |\n\n### 执行上下文\n\nJavaScript代码在浏览器上下文中执行，可以访问和操作DOM、发起AJAX请求、修改页面状态等。该功能基于Playwright的页面评估机制实现。\n\n资料来源：[crawl4ai/js_snippet/__init__.py:1-30](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/js_snippet/__init__.py)\n\n## 链接预览生成\n\n### 功能概述\n\n`link_preview` 模块负责生成网页的链接预览信息，包括标题、描述、图片和元数据等。该功能对于构建URL目录、sitemap生成、内容索引等场景非常有用。\n\n### 预览数据结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `title` | string | 页面标题 |\n| `description` | string | meta描述内容 |\n| `image` | string | OG/Twitter图片URL |\n| `favicon` | string | 网站图标 |\n| `domain` | string | 域名提取 |\n| `language` | string | 页面语言 |\n\n### 生成流程\n\n```mermaid\ngraph TD\n A[获取页面HTML] --> B[解析Meta标签]\n B --> C[提取OG属性]\n C --> D[获取Favicon]\n D --> E[生成预览对象]\n E --> F[缓存结果]\n```\n\n资料来源：[crawl4ai/link_preview.py:1-60](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/link_preview.py)\n\n## 异步调度器\n\n### 设计目标\n\n`async_dispatcher` 模块实现了高效的异步任务调度系统，支持并发控制、优先级管理、任务去重等企业级特性。该模块基于Python的asyncio框架构建，能够充分利用系统资源提升整体吞吐量。\n\n### 核心功能\n\n| 功能 | 描述 |\n|-----|------|\n| 并发限制 | 限制同时进行的爬取任务数量 |\n| 任务队列 | 支持优先级排序的任务队列 |\n| 失败重试 | 自动化失败任务重试机制 |\n| 速率控制 | 防止对目标网站造成过大压力 |\n\n### 调度策略\n\n异步调度器支持多种任务调度策略：\n\n1. **FIFO（先进先出）**：按提交顺序处理任务\n2. **优先级调度**：高优先级任务优先处理\n3. **批量处理**：聚合多个相似请求减少开销\n\n### 并发控制机制\n\n```mermaid\ngraph TD\n A[任务提交] --> B{检查并发数}\n B -->|未达上限| C[立即执行]\n B -->|已达上限| D[加入等待队列]\n C --> E[任务完成]\n D --> F[等待释放]\n F --> B\n E --> G[更新统计]\n G --> H{队列非空?}\n H -->|是| B\n```\n\n资料来源：[crawl4ai/async_dispatcher.py:1-100](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_dispatcher.py)\n\n## 模块协作流程\n\n### 完整爬取工作流\n\n```mermaid\ngraph TD\n A[用户请求] --> B[async_dispatcher 接收任务]\n B --> C[adaptive_crawler 创建爬取任务]\n C --> D{antibot_detector 预检}\n D -->|安全| E[执行爬取]\n D -->|风险| F[应用规避策略]\n F --> E\n E --> G{需要JS渲染?}\n G -->|是| H[js_snippet 注入脚本]\n H --> I[等待渲染完成]\n G -->|否| J[直接提取内容]\n I --> J\n J --> K[link_preview 生成预览]\n K --> L[结果汇总]\n L --> M[返回用户]\n```\n\n### 错误处理与恢复\n\n各模块均实现了完善的错误处理机制，当某个环节出现异常时，系统会自动触发降级策略或重试流程，确保整体任务的可靠性。\n\n## 配置建议\n\n### 生产环境推荐配置\n\n```python\n{\n \"adaptive_crawler\": {\n \"max_retries\": 5,\n \"timeout\": 45,\n \"use_cache\": True\n },\n \"async_dispatcher\": {\n \"max_concurrent\": 10,\n \"rate_limit\": 30 # 每分钟请求数\n },\n \"antibot_detector\": {\n \"strict_mode\": False,\n \"auto_adjust\": True\n }\n}\n```\n\n### 性能优化要点\n\n1. **合理设置并发数**：根据目标网站的承受能力调整\n2. **启用缓存**：减少重复请求，提升效率\n3. **适当延迟**：避免触发频率限制\n4. **监控日志**：及时发现和处理异常情况\n\n## 相关资源\n\n- 基础使用文档：查看项目主README\n- API参考：查看各模块具体实现\n- 示例代码：参考项目中的example目录\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：unclecode/crawl4ai\n\n摘要：发现 21 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing。\n\n## 1. 安装坑 · 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: arun() and arun_many() type hinting needs fixing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d3b6cfd3700147f690e0e65875f15424 | https://github.com/unclecode/crawl4ai/issues/1898 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason is shown\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad61b108bf894cc286ca7966e8c86758 | https://github.com/unclecode/crawl4ai/issues/1949 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ee99f5d72f143f4b064732cc19e0c85 | https://github.com/unclecode/crawl4ai/issues/1963 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7fa967632a948008efbc182d1f2c96b | https://github.com/unclecode/crawl4ai/issues/1938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e9fbf659fbb40aba437886a87f8e2d7 | https://github.com/unclecode/crawl4ai/issues/1962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af29278fd7294d4a8f0f6f37ab987b5c | https://github.com/unclecode/crawl4ai/issues/1968 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_97d44cedb21a4908a7743fde11209954 | https://github.com/unclecode/crawl4ai/issues/1950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ae45861377894b99a57d6bbdc06af313 | https://github.com/unclecode/crawl4ai/issues/1959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.1:Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.1:Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ae9133fff54443b712725f51769fa1 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：v0.7.2: CI/CD & Dependency Optimization Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.2: CI/CD & Dependency Optimization Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14954e0431ca426ebeaa4bb31778d4af | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 来源证据：[Bug]: Markdown export loses heading hierarchy and table structure\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Markdown export loses heading hierarchy and table structure\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c3eac8ab81e34bf3b6cc050f7f8e9826 | https://github.com/unclecode/crawl4ai/issues/1964 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:798201435 | https://github.com/unclecode/crawl4ai | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：Release v0.7.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.3\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e2b75670cbcc4814a86423818b9f6f48 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：Release v0.7.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.5\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_056d1470d7534cacb39eeb894e054496 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Release v0.7.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.7\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e157445f88744795b5c6234783eca692 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：[Bug]: Markdown text extraction drops text when element contains empty elements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Markdown text extraction drops text when element contains empty elements\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dffa926853d147ebb487a03fdfd1818e | https://github.com/unclecode/crawl4ai/issues/1966 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：unclecode/crawl4ai\n\n摘要：发现 21 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing。\n\n## 1. 安装坑 · 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: arun() and arun_many() type hinting needs fixing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d3b6cfd3700147f690e0e65875f15424 | https://github.com/unclecode/crawl4ai/issues/1898 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason is shown\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad61b108bf894cc286ca7966e8c86758 | https://github.com/unclecode/crawl4ai/issues/1949 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ee99f5d72f143f4b064732cc19e0c85 | https://github.com/unclecode/crawl4ai/issues/1963 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7fa967632a948008efbc182d1f2c96b | https://github.com/unclecode/crawl4ai/issues/1938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e9fbf659fbb40aba437886a87f8e2d7 | https://github.com/unclecode/crawl4ai/issues/1962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af29278fd7294d4a8f0f6f37ab987b5c | https://github.com/unclecode/crawl4ai/issues/1968 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_97d44cedb21a4908a7743fde11209954 | https://github.com/unclecode/crawl4ai/issues/1950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ae45861377894b99a57d6bbdc06af313 | https://github.com/unclecode/crawl4ai/issues/1959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.1:Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.1:Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ae9133fff54443b712725f51769fa1 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：v0.7.2: CI/CD & Dependency Optimization Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.2: CI/CD & Dependency Optimization Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14954e0431ca426ebeaa4bb31778d4af | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 来源证据：[Bug]: Markdown export loses heading hierarchy and table structure\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Markdown export loses heading hierarchy and table structure\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c3eac8ab81e34bf3b6cc050f7f8e9826 | https://github.com/unclecode/crawl4ai/issues/1964 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:798201435 | https://github.com/unclecode/crawl4ai | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：Release v0.7.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.3\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e2b75670cbcc4814a86423818b9f6f48 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：Release v0.7.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.5\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_056d1470d7534cacb39eeb894e054496 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Release v0.7.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.7\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e157445f88744795b5c6234783eca692 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：[Bug]: Markdown text extraction drops text when element contains empty elements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Markdown text extraction drops text when element contains empty elements\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dffa926853d147ebb487a03fdfd1818e | https://github.com/unclecode/crawl4ai/issues/1966 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# crawl4ai - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 crawl4ai 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的流程自动化任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: 🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-async-webcrawler：异步网页爬虫核心。围绕“异步网页爬虫核心”模拟一次用户任务，不展示安装或运行结果。\n5. page-deep-crawling：深度爬取策略。围绕“深度爬取策略”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-async-webcrawler\n输入：用户提供的“异步网页爬虫核心”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-deep-crawling\n输入：用户提供的“深度爬取策略”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-async-webcrawler：Step 4 必须围绕“异步网页爬虫核心”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-deep-crawling：Step 5 必须围绕“深度爬取策略”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/unclecode/crawl4ai\n- https://github.com/unclecode/crawl4ai#readme\n- README.md\n- CHANGELOG.md\n- crawl4ai/__init__.py\n- crawl4ai/__version__.py\n- ROADMAP.md\n- setup.py\n- pyproject.toml\n- requirements.txt\n- Dockerfile\n- docker-compose.yml\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 crawl4ai 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：unclecode/crawl4ai\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install -U crawl4ai\n```\n\n来源：https://github.com/unclecode/crawl4ai#readme\n\n## 来源\n\n- repo: https://github.com/unclecode/crawl4ai\n- docs: https://github.com/unclecode/crawl4ai#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_854bda8c953f459280cd4085d3ec4f00"
}
` / `` | ```language\\ncode\\n``` | 代码块 |\n| `` | `> text` | 引用块 |\n| `` / `` | `- item` / `1. item` | 列表 |\n| `` | Markdown 表格格式 | 表格转换 |\n| `
` | `---` | 水平线 |\n\n资料来源：[crawl4ai/html2text/elements.py:1-100]()\n\n#### 3. 主模块 (__init__.py)\n\n`__init__.py` 整合了配置和元素处理逻辑，提供完整的 HTML 到 Markdown 转换功能：\n\n```python\nclass Html2Text:\n \"\"\"HTML到Markdown转换器主类\"\"\"\n \n def __init__(self, config: Html2TextConfig = None):\n \"\"\"初始化转换器\n \n 参数:\n config: 配置对象\n \"\"\"\n self.config = config or Html2TextConfig()\n self._setup_handlers()\n \n def handle(self, html: str) -> str:\n \"\"\"处理HTML并返回Markdown\n \n 参数:\n html: 输入的HTML字符串\n \n 返回:\n 转换后的Markdown字符串\n \"\"\"\n pass\n \n def handle_tree(self, tree) -> str:\n \"\"\"处理解析后的HTML树\"\"\"\n pass\n```\n\n资料来源：[crawl4ai/html2text/__init__.py:1-150]()\n\n## 内容过滤策略\n\n`ContentFilterStrategy` 定义了内容过滤接口，用于在 Markdown 生成前对内容进行预处理。\n\n### 过滤策略类型\n\n| 策略 | 作用 | 使用场景 |\n|------|------|----------|\n| `DefaultContentFilter` | 默认过滤策略 | 标准网页抓取 |\n| `AggressiveContentFilter` | 激进过滤 | 去除更多噪音内容 |\n| `LightContentFilter` | 轻量过滤 | 保留更多原始内容 |\n\n### 过滤流程\n\n```mermaid\ngraph TD\n A[HTML 输入] --> B{内容过滤策略}\n B -->|保留标题| C[标题提取]\n B -->|移除脚本| D[脚本移除]\n B -->|移除样式| E[样式移除]\n B -->|移除注释| F[注释移除]\n C --> G[清理后 HTML]\n D --> G\n E --> G\n F --> G\n G --> H[Markdown 生成]\n H --> I[Markdown 输出]\n```\n\n## 使用方法\n\n### 基本用法\n\n```python\nfrom crawl4ai import Crawler\nfrom crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerationStrategy\n\n# 创建爬虫实例\ncrawler = Crawler()\n\n# 配置 Markdown 生成策略\ncrawler.markdown_strategy = DefaultMarkdownGenerationStrategy()\n\n# 执行抓取\nresult = crawler.crawl(\"https://example.com\")\n\n# 获取 Markdown 内容\nmarkdown = result.markdown\n```\n\n### 自定义配置\n\n```python\nfrom crawl4ai.html2text.config import Html2TextConfig\n\n# 创建自定义配置\nconfig = Html2TextConfig(\n ignore_links=False,\n ignore_images=False,\n ignore_tables=False,\n escape_all=False\n)\n\n# 应用配置\nmarkdown_generator = DefaultMarkdownGenerationStrategy(config=config)\n```\n\n### 内容过滤配置\n\n```python\nfrom crawl4ai.content_filter_strategy import DefaultContentFilter\n\n# 配置内容过滤\nfilter_strategy = DefaultContentFilter()\n\n# 在爬取时应用\nresult = crawler.crawl(\n \"https://example.com\",\n content_filter=filter_strategy\n)\n```\n\n## 配置参数详解\n\n### Html2TextConfig 完整参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `body_width` | int | 0 | 文本宽度限制，0表示不限制 |\n| `unicode_snob` | bool | False | 使用 Unicode 字符 |\n| `escape_snob` | bool | False | 转义特殊 Markdown 字符 |\n| `escape_all` | bool | False | 转义所有特殊字符 |\n| `links_each_paragraph` | bool | False | 每个段落处理链接 |\n| `ignore_links` | bool | False | 忽略链接 |\n| `ignore_images` | bool | False | 忽略图片 |\n| `ignore_emphasis` | bool | False | 忽略强调 |\n| `ignore_blockquotes` | bool | False | 忽略引用块 |\n| `ignore_tables` | bool | False | 忽略表格 |\n| `single_line_break` | bool | False | 单行换行 |\n| `pad_tables` | bool | False | 表格填充 |\n| `clickable_lnks` | bool | False | 链接可点击 |\n| `images_to_alt` | bool | False | 图片转 ALT 文本 |\n| `images_to_md` | bool | True | 图片转 Markdown 格式 |\n| `ln_ewscape` | bool | False | 行尾转义 |\n| `md_spoiler` | bool | False | Markdown 隐藏文本 |\n| `wrap` | bool | False | 文本换行 |\n| `wrap_width` | int | 80 | 换行宽度 |\n\n资料来源：[crawl4ai/html2text/config.py:1-100]()\n\n## 数据流与转换过程\n\n### 完整转换流程\n\n```mermaid\ngraph LR\n A[原始 HTML] --> B[HTML 解析]\n B --> C[内容过滤]\n C --> D[DOM 树处理]\n D --> E[元素转换]\n E --> F[Markdown 序列化]\n F --> G[最终 Markdown]\n \n subgraph 内容过滤阶段\n C1[移除脚本标签] --> C2[移除样式标签]\n C2 --> C3[移除注释]\n C3 --> C4[提取主体内容]\n end\n \n subgraph 元素转换\n E1[标题处理] --> E2[链接处理]\n E2 --> E3[图片处理]\n E3 --> E4[表格处理]\n E4 --> E5[列表处理]\n E5 --> E6[代码块处理]\n end\n```\n\n### 关键转换示例\n\n| HTML 输入 | Markdown 输出 |\n|-----------|---------------|\n| `标题
` | `# 标题` |\n| `链接` | `[链接](url)` |\n| `` | `` |\n| `粗体` | `**粗体**` |\n| `代码` | `` `代码` `` |\n| `1
` | `| 1 |` |\n\n## 高级用法\n\n### 自定义元素处理器\n\n```python\nfrom crawl4ai.html2text import Html2Text\nfrom crawl4ai.html2text.config import Html2TextConfig\n\nclass CustomHtml2Text(Html2Text):\n \"\"\"自定义 HTML 转 Markdown 处理器\"\"\"\n \n def handle_tag_h1(self, tag, attrs, start):\n \"\"\"自定义 H1 处理逻辑\"\"\"\n # 自定义处理逻辑\n return f\"## {self.get_text()}\"\n \n def handle_tag_a(self, tag, attrs, start):\n \"\"\"自定义链接处理\"\"\"\n # 自定义链接处理\n pass\n```\n\n### 批量转换\n\n```python\nfrom crawl4ai import Crawler\nfrom crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerationStrategy\n\nurls = [\n \"https://example.com/page1\",\n \"https://example.com/page2\",\n \"https://example.com/page3\"\n]\n\ngenerator = DefaultMarkdownGenerationStrategy()\ncrawler = Crawler()\n\nresults = []\nfor url in urls:\n result = crawler.crawl(url)\n results.append({\n \"url\": url,\n \"markdown\": result.markdown\n })\n```\n\n## 注意事项\n\n### 性能考量\n\n1. **大文档处理**：对于包含大量元素的 HTML 页面，转换过程可能耗时较长\n2. **内存使用**：大型 DOM 树会占用较多内存，建议对超大型页面进行分块处理\n3. **编码处理**：确保输入 HTML 的编码正确，避免乱码问题\n\n### 兼容性说明\n\n| HTML 特性 | 支持状态 | 说明 |\n|-----------|----------|------|\n| HTML5 | ✅ 完全支持 | 支持所有 HTML5 标签 |\n| SVG | ⚠️ 部分支持 | 基本支持，部分复杂 SVG 可能无法正确转换 |\n| MathJax/LaTeX | ⚠️ 需要插件 | 需要额外配置 |\n| 嵌入式视频 | ❌ 不支持 | 会被转换为链接或忽略 |\n\n## 相关文件\n\n| 文件路径 | 描述 |\n|----------|------|\n| `crawl4ai/markdown_generation_strategy.py` | Markdown 生成策略定义与实现 |\n| `crawl4ai/content_filter_strategy.py` | 内容过滤策略定义与实现 |\n| `crawl4ai/html2text/__init__.py` | html2text 主模块 |\n| `crawl4ai/html2text/elements.py` | HTML 元素处理规则 |\n| `crawl4ai/html2text/config.py` | 配置参数定义 |\n\n---\n\n\n\n## 数据提取策略\n\n### 相关页面\n\n相关主题：[分块与过滤策略](#page-chunking-filtering), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/extraction_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/extraction_strategy.py)\n- [crawl4ai/content_scraping_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_scraping_strategy.py)\n- [crawl4ai/table_extraction.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/table_extraction.py)\n- [crawl4ai/crawlers/amazon_product/crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/crawlers/amazon_product/crawler.py)\n- [crawl4ai/crawlers/google_search/crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/crawlers/google_search/crawler.py)\n\n\n# 数据提取策略\n\n## 概述\n\n数据提取策略是 crawl4ai 框架中用于从网页内容中精准提取结构化数据的核心模块。该策略系统设计灵活，支持多种提取方式，涵盖从简单的 CSS 选择器匹配到基于大语言模型（LLM）的智能语义提取。\n\n## 架构设计\n\n### 策略类型体系\n\ncrawl4ai 的数据提取策略采用策略模式（Strategy Pattern）设计，主要包含以下几种策略类型：\n\n```mermaid\ngraph TD\n A[ExtractionStrategy 基类] --> B[NoExtractionStrategy]\n A --> C[BeautifulSoupExtractionStrategy]\n A --> D[LLMExtractionStrategy]\n A --> E[JsonCssExtractionStrategy]\n A --> F[RegexExtractionStrategy]\n \n B --> G[不使用任何提取]\n C --> H[基于 CSS 选择器的结构化提取]\n D --> I[基于 LLM 的语义理解提取]\n E --> J[JSON + CSS 组合提取]\n F --> K[正则表达式模式匹配]\n```\n\n### 核心组件关系\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| ExtractionStrategy | extraction_strategy.py | 策略基类，定义标准化接口 |\n| ContentScrapingStrategy | content_scraping_strategy.py | 内容抓取策略，处理原始内容获取 |\n| TableExtraction | table_extraction.py | 表格数据专项提取 |\n| CrawlerStrategy | 各爬虫子模块 | 具体业务场景的实现 |\n\n## 策略详解\n\n### NoExtractionStrategy\n\n默认策略，不执行任何数据提取操作。适用于只需要获取完整页面内容或 HTML 的场景。\n\n```python\n# 使用示例\nresult = await crawler.crawl(\n url=\"https://example.com\",\n extraction_strategy=NoExtractionStrategy()\n)\n```\n\n### BeautifulSoupExtractionStrategy\n\n基于 BeautifulSoup4 的结构化数据提取策略，通过 CSS 选择器精确定位页面元素。\n\n**配置参数：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| css_selector | str | None | CSS 选择器表达式 |\n| filter_regex | str | None | 内容过滤正则表达式 |\n| check_interval | float | 0.2 | 检查间隔（秒） |\n| timeout | int | 7 | 超时时间（秒） |\n\n### LLMExtractionStrategy\n\n基于大语言模型的智能提取策略，能够理解页面语义并提取非结构化或半结构化数据。\n\n**核心参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| prompt | str | 是 | 提取指令提示词 |\n| schema | dict | 否 | 输出数据 schema 定义 |\n| extraction_type | str | 否 | 提取类型标识 |\n\n### JsonCssExtractionStrategy\n\n结合 JSONPath 和 CSS 选择器的混合提取策略，适用于复杂的嵌套数据结构。\n\n### RegexExtractionStrategy\n\n基于正则表达式的文本模式提取策略，适合处理日志、代码片段等结构化文本。\n\n## 内容抓取策略\n\nContentScrapingStrategy 负责处理内容获取阶段的策略配置，主要包含以下抓取模式：\n\n```mermaid\ngraph LR\n A[网页请求] --> B[ScrapingMode 选择]\n B --> C[全量 HTML]\n B --> D[无标签文本]\n B --> E[结构化内容]\n \n C --> F[beautifulsoup 处理]\n D --> G[正则清理]\n E --> H[语义分析]\n```\n\n**支持的抓取模式：**\n\n| 模式名称 | 说明 | 适用场景 |\n|---------|------|---------|\n| html | 完整 HTML 源码 | 需要保留原始标签结构 |\n| text | 纯文本内容 | 文本分析和 NLP 处理 |\n| fit_markdown | Markdown 格式 | 文档转换和内容摘要 |\n|.cleaned | 清理后内容 | 去除脚本和样式噪音 |\n\n## 表格提取机制\n\nTableExtraction 是 crawl4ai 中专门处理 HTML 表格数据提取的模块。\n\n### 提取流程\n\n```mermaid\ngraph TD\n A[定位 table 元素] --> B[识别表头行]\n B --> C[遍历数据行]\n C --> D{是否跨列/跨行?}\n D -->|是| E[处理单元格合并]\n D -->|否| F[直接提取]\n E --> G[构建单元格映射]\n F --> H[转换为列表/字典]\n G --> H\n H --> I[输出 JSON 格式]\n```\n\n### 表格数据结构\n\n提取的表格数据以列表形式返回，每行对应一个字典对象：\n\n```python\n[\n {\"列名1\": \"值1\", \"列名2\": \"值2\"},\n {\"列名1\": \"值3\", \"列名2\": \"值4\"}\n]\n```\n\n## 领域专用爬虫示例\n\n### 亚马逊产品爬虫\n\nAmazon 产品爬虫继承基础提取策略，针对电商页面结构优化：\n\n```python\n# 资料来源：crawl4ai/crawlers/amazon_product/crawler.py\nclass AmazonProductCrawler:\n def __init__(self, extraction_strategy):\n self.strategy = extraction_strategy\n```\n\n### 谷歌搜索爬虫\n\n谷歌搜索爬虫实现特定的搜索结果提取逻辑：\n\n```python\n# 资料来源：crawl4ai/crawlers/google_search/crawler.py\nclass GoogleSearchCrawler:\n async def crawl(self, query: str):\n # 实现搜索结果提取\n```\n\n## 使用最佳实践\n\n### 策略选择指南\n\n| 应用场景 | 推荐策略 | 理由 |\n|---------|---------|-----|\n| 简单表格/列表 | BeautifulSoupExtractionStrategy | 性能高效，精度高 |\n| 语义复杂内容 | LLMExtractionStrategy | 理解能力强 |\n| 结构化日志 | RegexExtractionStrategy | 模式匹配灵活 |\n| 嵌套 JSON | JsonCssExtractionStrategy | 混合查询支持 |\n| 快速原型 | NoExtractionStrategy | 零配置启动 |\n\n### 性能优化建议\n\n1. **优先使用 CSS 选择器**：在数据格式已知的情况下，BeautifulSoup 策略性能优于 LLM 策略\n2. **设置合理的超时时间**：避免大型页面导致的长时间等待\n3. **启用检查间隔**：对于动态加载内容，适当增加 check_interval\n4. **批量提取优化**：多条数据使用同一策略实例，减少初始化开销\n\n## 扩展开发指南\n\n如需创建自定义提取策略，需继承 ExtractionStrategy 基类并实现核心方法：\n\n```python\nfrom crawl4ai.extraction_strategy import ExtractionStrategy\n\nclass CustomExtractionStrategy(ExtractionStrategy):\n async def extract(self, html: str, url: str) -> List[Dict]:\n # 实现自定义提取逻辑\n pass\n```\n\n## 版本兼容性\n\n数据提取策略模块在不同版本间保持接口兼容性，详见项目 CHANGELOG 获取版本特定说明。\n\n---\n\n**相关文档：**\n- [用户指南](../docs/user-guide.md)\n- [API 参考](../api_reference/)\n- [示例代码](../examples/)\n\n---\n\n\n\n## 分块与过滤策略\n\n### 相关页面\n\n相关主题：[数据提取策略](#page-extraction-strategies), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/chunking_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/chunking_strategy.py)\n- [crawl4ai/content_filter_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_filter_strategy.py)\n- [crawl4ai/model_loader.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/model_loader.py)\n- [crawl4ai/prompts.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/prompts.py)\n\n\n# 分块与过滤策略\n\n## 概述\n\n在 Crawl4ai 项目中，**分块策略（Chunking Strategy）** 和 **过滤策略（Content Filter Strategy）** 是两个核心模块，它们共同负责将爬取的网页内容转化为结构化、可处理的文本块。这两个策略在数据处理流程中扮演着至关重要的角色，它们使得大规模网页内容能够被有效地分割、过滤和组织，以满足大语言模型（LLM）训练、知识库构建等应用场景的需求。\n\n分块策略的主要功能是将长文本内容按照预定义的规则（如字符数、句子边界、段落等）分割成较小的、语义相对完整的块（Chunk）。这种分割方式能够确保每个文本块具有足够的上下文信息，同时保持适当的粒度便于后续处理。过滤策略则负责识别并保留最具价值的文本内容，同时去除导航菜单、广告脚本、页脚信息等无用的噪音内容。这两个策略的协同工作形成了 Crawl4ai 内容处理管道的核心环节。\n\n从架构设计的角度来看，分块与过滤策略都遵循了策略模式（Strategy Pattern）的设计原则。这种设计允许用户在运行时动态选择和配置不同的分块或过滤算法，而无需修改核心处理逻辑。每个策略都实现了统一的接口定义，确保了模块之间的松耦合和高度可扩展性。这种灵活性使得 Crawl4ai 能够适应各种不同的内容处理场景和需求变化。\n\n## 分块策略详解\n\n### 工作原理\n\n分块策略的核心目标是将输入的文本内容按照特定规则进行分割，生成一系列语义相对完整的文本块。在实现层面，分块策略首先会对输入文本进行分析，识别出文本的内在结构（如句子、段落、标题等），然后根据预定义的参数（如最大块大小、重叠大小等）将文本切分为多个块。每个块都包含了一定量的上下文信息，同时保持相对独立的语义完整性。\n\n分块过程通常遵循以下基本流程：首先，策略会接收原始文本内容和相关配置参数；然后，对文本进行预处理，包括清理格式、识别结构等；接着，根据选定的分块算法执行分割操作；最后，对生成的块进行后处理，包括清理空块、合并过小的块等。整个过程旨在最大化每个块的实用价值，同时最小化信息丢失和上下文割裂。\n\n### 配置参数\n\n分块策略的行为可以通过多个参数进行精细控制，这些参数决定了分块的大小、重叠方式以及边界处理逻辑。以下是主要的配置选项：\n\n| 参数名称 | 类型 | 默认值 | 说明 |\n|---------|------|--------|------|\n| chunk_word_count | int | 1024 | 每个块的近似单词数目标值 |\n| overlap | int | 100 | 块之间的重叠单词数 |\n| overlap_all_sections | bool | False | 是否在所有章节间应用重叠 |\n| combine_sentences | bool | False | 是否将短句合并为完整段落 |\n| max_characters_per_section | int | 1500 | 每个章节的最大字符数 |\n| overlap_rate | float | 0.1 | 重叠率，overlap_rate * chunk_word_count |\n| extra_system_prompt | str | \"\" | 额外的系统提示词 |\n| user_prompt | str | \"\" | 用户自定义提示词模板 |\n\n这些参数可以根据具体的应用场景进行调整。例如，当需要较短的块用于精确检索时，可以减小 `chunk_word_count` 的值；当需要保留更多上下文信息时，可以增加 `overlap` 或 `overlap_rate` 的值以实现块之间的信息重叠。`overlap_all_sections` 参数特别有用，因为它确保了跨章节边界的语义连贯性。\n\n### 分块算法实现\n\n在具体实现层面，Crawl4ai 提供了多种分块算法的实现。以基于字数的分块为例，该算法会遍历文本内容，累积单词直到达到目标块大小，然后在该位置附近（通常在句子边界处）进行截断，生成一个新的块。这种方法简单高效，适用于大多数场景。\n\n对于更复杂的场景，系统还支持基于语义的分块方法。这种方法会结合自然语言处理技术，识别文本中的语义边界（如主题转换点），并在这些位置进行分割。语义分块能够产生更加连贯、信息密度更高的文本块，但计算成本也相对较高。算法实现中会调用语言模型来辅助判断语义边界，这部分功能与 `model_loader.py` 中定义的模型加载机制紧密相关。\n\n```mermaid\ngraph TD\n A[原始文本输入] --> B[文本预处理]\n B --> C[结构识别]\n C --> D{分块算法选择}\n D -->|字数分块| E[按字数累积]\n D -->|语义分块| F[语义边界分析]\n E --> G[句子边界截断]\n F --> G\n G --> H[生成文本块]\n H --> I[重叠处理]\n I --> J[块后处理]\n J --> K[输出块列表]\n```\n\n### 自定义分块策略\n\nCrawl4ai 的架构设计允许开发者实现自定义的分块策略。要创建自定义策略，需要继承基础的分块策略类并实现核心的 `chunk()` 方法。方法签名通常接受原始文本内容和可选的配置参数，返回一个文本块列表。这种设计使得系统具有极强的扩展性，能够适应各种特殊的内容处理需求。\n\n自定义策略的实现需要考虑多个方面：首先是分块逻辑的准确性，确保生成的块符合预期的格式和质量标准；其次是性能优化，特别是处理大规模文本时需要考虑计算效率；最后是错误处理机制，需要妥善处理各种异常情况如空文本、格式错误等。通过继承和扩展基础类，开发者可以专注于实现特定的分块逻辑，而无需关心与其他模块的集成细节。\n\n## 过滤策略详解\n\n### 目的与作用\n\n内容过滤策略的主要目的是从爬取的网页内容中识别并提取高价值的文本信息，同时过滤掉导航菜单、页脚、版权声明、广告脚本等无意义的内容。这一步骤对于后续的内容处理至关重要，因为它直接影响到生成的知识库的纯净度和可用性。一个设计良好的过滤策略能够显著提升内容的信号噪声比，使得检索和问答等下游任务能够获得更准确的结果。\n\n过滤策略的实现通常依赖于启发式规则和机器学习模型的结合。在传统方法中，系统会基于 HTML 标签类型、CSS 类名、元素位置等特征来判断内容的价值。例如，包含 \"nav\"、\"footer\"、\"sidebar\"、\"advertisement\" 等关键词的元素通常会被标记为低价值内容。在更高级的实现中，系统还会结合语言模型来理解内容的语义，进一步提升过滤的准确性。\n\n### 过滤机制\n\n过滤机制的实现涉及多个层次的判断逻辑。在最基础的层面，系统会基于 HTML 结构特征进行粗过滤，识别并排除明显无用的内容块。这包括脚本标签、样式标签、隐藏元素、以及某些特定的 HTML 标签类型。通过分析元素的可见性、大小、位置等属性，系统可以快速排除大量低价值内容。\n\n在更精细的层面，过滤策略会结合文本内容的语义分析。这部分功能与 `prompts.py` 中定义的提示词模板紧密相关。系统会使用特定的提示词引导语言模型对内容块进行价值评估，判断其是否包含实质性的信息内容。评估结果会被用于决定是否保留该内容块，或者将其标记为需要进一步处理或直接过滤。\n\n```mermaid\ngraph TD\n A[网页内容输入] --> B[HTML结构分析]\n B --> C[标签类型过滤]\n C --> D[可见性检查]\n D --> E[语义分析]\n E --> F{价值评估}\n F -->|高价值| G[保留内容]\n F -->|低价值| H[过滤内容]\n F -->|不确定| I[模型辅助判断]\n I --> G\n I --> H\n```\n\n### 过滤策略类型\n\nCrawl4ai 提供了多种预定义的过滤策略，以适应不同的内容处理需求。这些策略包括基于规则的方法、基于统计的方法和基于深度学习的方法。每种策略都有其特定的优势和适用场景，用户可以根据实际需求选择最合适的策略类型。\n\n**关键词过滤策略** 是最基础的方法，它通过预定义的关键词列表来识别和过滤无价值内容。这种方法简单高效，但可能无法处理所有变体和无规律的噪音内容。**正则表达式过滤策略** 提供了更灵活的模式匹配能力，能够处理更复杂的过滤规则。**基于模型的质量过滤策略** 则利用机器学习模型来评估内容的价值，能够捕捉更深层次的语义特征。\n\n| 策略类型 | 优点 | 缺点 | 适用场景 |\n|---------|------|------|---------|\n| 关键词过滤 | 速度快、简单易用 | 准确性有限 | 快速处理、结构化内容 |\n| 正则过滤 | 灵活性高、可定制 | 需要手动编写规则 | 特定格式内容 |\n| 模型过滤 | 准确性高、适应性强 | 计算成本较高 | 高质量需求场景 |\n| 混合过滤 | 综合多种方法优势 | 配置复杂 | 通用场景 |\n\n## 与模型加载器的集成\n\n### 模型加载机制\n\n分块和过滤策略的执行往往需要语言模型的参与。`model_loader.py` 模块提供了统一的模型加载和管理接口，使得策略能够便捷地访问语言模型能力。这个模块封装了模型初始化、配置管理、推理调用等核心功能，为上层策略提供了一个简洁而强大的模型访问层。\n\n模型加载器支持多种模型类型和部署方式，包括本地模型和云端 API。配置参数允许用户指定模型的类型、版本、API 密钥等必要信息。加载器会自动处理模型缓存、多实例管理、请求批处理等底层细节，使得策略实现者能够专注于业务逻辑而无需关心模型调用的基础设施问题。\n\n### 在策略中的应用\n\n在分块策略中，模型主要被用于语义分块和质量评估。当启用语义分块模式时，系统会调用模型来分析文本的语义结构，识别主题转换点和最佳分割位置。在过滤策略中，模型被用于深度内容理解，评估文本块的语义价值和相关性。这些应用都需要模型加载器提供稳定可靠的模型访问服务。\n\n模型的使用涉及性能优化和成本控制两个关键考量。在性能方面，系统实现了请求批处理、模型缓存、推理结果缓存等优化机制，以减少重复计算和 API 调用延迟。在成本方面，系统支持多种模型选择，从高性能高成本的模型到轻量级低成本模型的梯度配置，用户可以根据需求权衡效果和成本。\n\n## 提示词集成\n\n### 提示词模板\n\n`prompts.py` 模块定义了分块和过滤策略使用的各种提示词模板。这些模板经过精心设计，能够有效地引导语言模型执行内容分析、价值评估、语义分割等任务。提示词的质量直接影响策略的执行效果，因此模板的设计和优化是策略开发的重要环节。\n\n提示词模板采用结构化设计，包含系统提示和用户提示两个部分。系统提示定义了模型的角色定位和基本行为准则，用户提示则包含了具体的任务描述和输入内容。这种设计使得提示词具有良好的可读性和可维护性，同时也方便根据不同场景进行定制和优化。\n\n### 自定义提示词\n\n用户可以通过配置参数自定义提示词内容，以适应特定的内容处理需求。例如，`extra_system_prompt` 参数允许在系统提示中添加额外的指令，`user_prompt` 参数允许用户自定义用户提示的模板结构。这种灵活性使得系统能够适应各种特殊的内容处理场景和领域需求。\n\n自定义提示词时需要注意几个关键要点：首先是提示词的清晰性和具体性，模糊的指令可能导致模型产生不一致的结果；其次是提示词的长度和复杂性，过长的提示词可能增加处理成本和延迟；最后是提示词的格式兼容性，确保自定义提示词与系统其他部分能够良好集成。\n\n## 实际应用示例\n\n### 基本使用流程\n\n在实际应用中，分块和过滤策略通常作为数据处理管道的一环被调用。用户首先配置所需的策略参数，然后调用执行方法处理输入内容。整个过程是自动化的，用户只需关注输入输出的管理。以下是一个典型的使用场景：\n\n```python\nfrom crawl4ai import ChunkingStrategy, ContentFilterStrategy\n\n# 配置分块策略\nchunking_strategy = ChunkingStrategy(\n chunk_word_count=512,\n overlap=50,\n overlap_all_sections=True\n)\n\n# 配置过滤策略\nfilter_strategy = ContentFilterStrategy(\n model=\"gpt-4\",\n filter_type=\"semantic\"\n)\n\n# 执行处理\ncontent = \"待处理的网页文本内容...\"\nchunks = chunking_strategy.chunk(content)\nfiltered_chunks = filter_strategy.filter(chunks)\n```\n\n### 最佳实践建议\n\n在实际使用中，有几个关键的优化建议值得关注。首先是分块大小的选择，需要根据下游任务的需求进行权衡：较小的块适合精确检索，但可能缺乏足够的上下文；较大的块包含更丰富的上下文，但可能引入噪音。其次是重叠参数的设置，适当的重叠能够保证跨块边界的语义连续性，特别是在涉及长程依赖的任务中。\n\n过滤策略的选择和配置同样需要根据具体场景进行调整。对于新闻类内容，可以侧重于正文提取和标题识别；对于论坛讨论类内容，则需要更智能的噪音过滤以排除签名档和重复引用。对于包含大量代码的项目文档，还需要特别注意代码块的识别和保留，避免被误过滤。\n\n## 技术规格总结\n\n| 组件 | 位置 | 主要功能 | 可扩展性 |\n|------|------|---------|---------|\n| ChunkingStrategy | chunking_strategy.py | 文本分块处理 | 支持自定义实现 |\n| ContentFilterStrategy | content_filter_strategy.py | 内容质量过滤 | 支持多种过滤模式 |\n| ModelLoader | model_loader.py | 模型访问管理 | 支持多种模型类型 |\n| PromptManager | prompts.py | 提示词管理 | 支持自定义模板 |\n\n分块与过滤策略作为 Crawl4ai 的核心组件，共同构成了网页内容智能处理的基础设施。通过合理配置和使用这些策略，用户可以实现高效、准确的大规模网页内容处理，为各种下游任务提供高质量的数据支持。系统的模块化设计确保了良好的可维护性和可扩展性，使得用户能够根据实际需求进行灵活定制和优化。\n\n---\n\n\n\n## 浏览器配置与代理\n\n### 相关页面\n\n相关主题：[高级功能](#page-advanced-features), [异步网页爬虫核心](#page-async-webcrawler)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/browser_manager.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_manager.py)\n- [crawl4ai/browser_adapter.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_adapter.py)\n- [crawl4ai/browser_profiler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_profiler.py)\n- [crawl4ai/proxy_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/proxy_strategy.py)\n- [crawl4ai/ssl_certificate.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/ssl_certificate.py)\n- [crawl4ai/user_agent_generator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/user_agent_generator.py)\n\n\n# 浏览器配置与代理\n\n## 概述\n\n浏览器配置与代理模块是 crawl4ai 框架中负责管理浏览器实例配置、代理设置、SSL证书处理以及用户代理字符串生成的核心组件。该模块提供了灵活的浏览器定制能力，使爬虫能够适应不同的目标网站环境，包括需要身份验证、SSL证书处理、代理跳转等复杂场景。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[BrowserConfig] --> B[BrowserManager]\n A --> C[BrowserAdapter]\n A --> D[BrowserProfiler]\n E[ProxyStrategy] --> B\n F[SSLConfig] --> B\n G[UserAgentGenerator] --> B\n B --> H[Playwright Browser]\n C --> I[BrowserController]\n D --> J[BrowserPool]\n```\n\n## 核心组件\n\n### BrowserManager\n\nBrowserManager 是浏览器管理的核心类，负责浏览器的生命周期管理、实例化、配置应用和资源清理。\n\n```mermaid\ngraph LR\n A[创建配置] --> B[初始化浏览器]\n B --> C[应用代理]\n C --> D[设置SSL]\n D --> E[生成User-Agent]\n E --> F[浏览器就绪]\n F --> G[执行爬取]\n G --> H[资源释放]\n```\n\n**主要职责：**\n- 管理浏览器实例的创建和销毁\n- 配置浏览器启动参数\n- 应用代理和SSL设置\n- 处理浏览器上下文隔离\n\n**配置参数表：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| headless | bool | True | 是否无头模式运行 |\n| browser_type | str | \"chromium\" | 浏览器类型（chromium/firefox/webkit） |\n| proxy_config | ProxyConfig | None | 代理配置对象 |\n| ssl_config | SSLConfig | None | SSL证书配置 |\n| user_agent | str | None | 自定义User-Agent |\n| viewport | dict | {\"width\": 1920, \"height\": 1080} | 视口大小 |\n| args | list | [] | 额外的浏览器启动参数 |\n| ignoreHTTPSErrors | bool | False | 是否忽略HTTPS错误 |\n| java_script_enabled | bool | True | 是否启用JavaScript |\n\n资料来源：[browser_manager.py:1-100]()\n\n### BrowserAdapter\n\nBrowserAdapter 提供了浏览器操作的高级抽象接口，封装了常见的浏览器交互操作。\n\n**核心功能：**\n- 页面导航和导航控制\n- 元素选择和交互\n- 截图和PDF生成\n- 控制台日志捕获\n- 网络请求拦截\n\n```python\nclass BrowserAdapter:\n def __init__(self, config: BrowserConfig):\n self.config = config\n self.browser = None\n self.context = None\n self.page = None\n```\n\n资料来源：[browser_adapter.py:1-50]()\n\n### BrowserProfiler\n\nBrowserProfiler 用于浏览器性能分析和会话追踪，帮助诊断浏览器行为和性能问题。\n\n**功能特性：**\n- 记录浏览器启动时间\n- 追踪页面加载性能\n- 统计资源使用情况\n- 生成性能报告\n\n```mermaid\ngraph TD\n A[开始分析] --> B[捕获事件]\n B --> C{事件类型}\n C --> D[性能指标]\n C --> E[资源加载]\n C --> F[控制台日志]\n D --> G[生成报告]\n E --> G\n F --> G\n```\n\n资料来源：[browser_profiler.py:1-80]()\n\n## 代理配置\n\n### ProxyConfig 数据模型\n\n```python\nclass ProxyConfig:\n server: str # 代理服务器地址，格式: protocol://host:port\n username: str # 认证用户名（可选）\n password: str # 认证密码（可选）\n bypass_list: list # 绕过代理的地址列表（可选）\n```\n\n**支持的代理协议：**\n\n| 协议 | 格式示例 | 支持情况 |\n|------|----------|----------|\n| HTTP | http://proxy.example.com:8080 | ✅ 完全支持 |\n| HTTPS | https://proxy.example.com:8080 | ✅ 完全支持 |\n| SOCKS4 | socks4://proxy.example.com:1080 | ✅ 完全支持 |\n| SOCKS5 | socks5://proxy.example.com:1080 | ✅ 完全支持 |\n\n### ProxyStrategy\n\nProxyStrategy 实现了多种代理策略，支持自动代理切换和负载均衡。\n\n```mermaid\ngraph TD\n A[请求发起] --> B{代理策略选择}\n B --> C[轮询策略]\n B --> D[随机策略]\n B --> E[故障转移策略]\n C --> F[选择代理]\n D --> F\n E --> F\n F --> G[应用代理]\n G --> H{请求结果}\n H -->|成功| I[记录成功]\n H -->|失败| J[重试或切换]\n J --> F\n```\n\n**代理策略类型：**\n\n| 策略名称 | 说明 | 适用场景 |\n|----------|------|----------|\n| RoundRobinStrategy | 轮询策略，依次使用每个代理 | 负载均衡 |\n| RandomStrategy | 随机选择代理 | 避免请求模式被检测 |\n| FailoverStrategy | 故障转移，主代理失败时切换 | 高可用性 |\n| PriorityStrategy | 按优先级顺序尝试 | 优先使用高速代理 |\n\n资料来源：[proxy_strategy.py:1-120]()\n\n### 代理配置示例\n\n```python\nfrom crawl4ai import BrowserConfig, ProxyConfig\n\n# 简单代理配置\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\"\n)\n\n# 带认证的代理配置\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\",\n username=\"user123\",\n password=\"pass456\"\n)\n\n# 配置绕过列表\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\",\n bypass_list=[\"localhost\", \"*.internal\"]\n)\n\nbrowser_config = BrowserConfig(\n proxy_config=proxy_config,\n headless=True\n)\n```\n\n## SSL 证书处理\n\n### SSLConfig 数据模型\n\n```python\nclass SSLConfig:\n ignore_ssl_errors: bool # 是否忽略SSL错误\n client_cert: str # 客户端证书路径\n client_key: str # 客户端私钥路径\n ca_cert: str # CA证书路径\n```\n\n**配置参数表：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| ignore_ssl_errors | bool | False | 忽略证书验证错误 |\n| client_cert | str | None | PEM格式客户端证书路径 |\n| client_key | str | None | PEM格式私钥路径 |\n| ca_cert | str | None | CA证书文件路径 |\n| accept_insecure_certs | bool | False | 接受无效证书 |\n\n资料来源：[ssl_certificate.py:1-60]()\n\n### 使用场景\n\n**场景一：忽略证书错误**\n\n适用于测试环境或内部网络：\n\n```python\nssl_config = SSLConfig(ignore_ssl_errors=True)\nbrowser_config = BrowserConfig(ssl_config=ssl_config)\n```\n\n**场景二：使用客户端证书**\n\n适用于需要双向SSL认证的场景：\n\n```python\nssl_config = SSLConfig(\n client_cert=\"/path/to/cert.pem\",\n client_key=\"/path/to/key.pem\",\n ca_cert=\"/path/to/ca.pem\"\n)\nbrowser_config = BrowserConfig(ssl_config=ssl_config)\n```\n\n## 用户代理管理\n\n### UserAgentGenerator\n\nUserAgentGenerator 负责生成和管理用户代理字符串，支持多种配置选项。\n\n```mermaid\ngraph TD\n A[UA生成请求] --> B{生成模式}\n B --> C[固定UA]\n B --> D[随机UA]\n B --> E[真实浏览器UA]\n C --> F[返回UA字符串]\n D --> G[选择设备类型]\n G --> F\n E --> H[模拟真实环境]\n H --> F\n```\n\n**生成模式：**\n\n| 模式 | 说明 | 示例 |\n|------|------|------|\n| fixed | 使用指定的固定UA | \"Mozilla/5.0...\" |\n| random | 从预设列表随机选择 | 随机桌面浏览器UA |\n| real_browser | 模拟真实浏览器环境 | Chrome on Windows |\n| mobile | 移动设备UA | iPhone Safari |\n\n资料来源：[user_agent_generator.py:1-90]()\n\n### 预设浏览器类型\n\n| 浏览器 | 平台 | User-Agent 示例 |\n|--------|------|------------------|\n| Chrome | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 |\n| Chrome | macOS | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 |\n| Chrome | Linux | Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 |\n| Firefox | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 |\n| Safari | iOS | Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) |\n| Edge | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/115.0.0.0 |\n\n### 使用示例\n\n```python\nfrom crawl4ai import BrowserConfig, UserAgentGenerator\n\n# 使用随机UA\nua_generator = UserAgentGenerator(mode=\"random\")\nbrowser_config = BrowserConfig(\n user_agent=ua_generator.generate()\n)\n\n# 使用固定UA\nbrowser_config = BrowserConfig(\n user_agent=\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36\"\n)\n\n# 使用真实浏览器模拟\nua_generator = UserAgentGenerator(mode=\"real_browser\")\nbrowser_config = BrowserConfig(\n user_agent=ua_generator.generate(device_type=\"mobile\")\n)\n```\n\n## 浏览器配置工作流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant BM as BrowserManager\n participant PA as ProxyAdapter\n participant SS as SSLHandler\n participant UA as UserAgentGenerator\n participant Browser as Playwright Browser\n\n User->>BM: 创建BrowserConfig\n BM->>UA: 请求User-Agent\n UA-->>BM: 返回UA字符串\n BM->>PA: 应用代理配置\n PA->>BM: 代理配置完成\n BM->>SS: 配置SSL设置\n SS-->>BM: SSL配置完成\n BM->>Browser: 启动浏览器实例\n Browser-->>BM: 浏览器就绪\n BM-->>User: 返回配置好的浏览器\n```\n\n## 高级配置选项\n\n### 浏览器启动参数\n\n```python\nbrowser_config = BrowserConfig(\n args=[\n \"--disable-blink-features=AutomationControlled\",\n \"--disable-dev-shm-usage\",\n \"--no-sandbox\",\n \"--disable-setuid-sandbox\",\n \"--disable-gpu\",\n \"--disable-web-security\",\n \"--disable-features=IsolateOrigins,site-per-process\"\n ]\n)\n```\n\n**常用启动参数表：**\n\n| 参数 | 说明 | 风险等级 |\n|------|------|----------|\n| --disable-blink-features=AutomationControlled | 隐藏自动化特征 | 低 |\n| --disable-dev-shm-usage | 避免共享内存问题 | 低 |\n| --no-sandbox | 禁用沙箱（Docker环境需要） | 高 |\n| --disable-setuid-sandbox | 禁用setuid沙箱 | 中 |\n| --disable-gpu | 禁用GPU加速 | 低 |\n| --disable-web-security | 禁用Web安全 | 高 |\n| --headless=new | 使用新版无头模式 | 低 |\n\n### 上下文隔离配置\n\n```python\nbrowser_config = BrowserConfig(\n context_options={\n \"locale\": \"zh-CN\",\n \"timezone_id\": \"Asia/Shanghai\",\n \"viewport\": {\"width\": 1920, \"height\": 1080},\n \"color_scheme\": \"dark\",\n \"extra_http_headers\": {\n \"Accept-Language\": \"zh-CN,zh;q=0.9\",\n \"Accept-Encoding\": \"gzip, deflate, br\"\n }\n }\n)\n```\n\n## 最佳实践\n\n### 配置优先级\n\n1. **安全优先**：在生产环境中禁用 `--disable-web-security`\n2. **性能优化**：合理设置视口大小，避免不必要的大图渲染\n3. **稳定性**：在Docker环境中添加 `--no-sandbox` 和 `--disable-dev-shm-usage`\n4. **反检测**：结合使用随机UA、真实视口和代理\n\n### 配置验证清单\n\n- [ ] 确认代理服务器可达性\n- [ ] 验证SSL证书配置正确\n- [ ] 测试UA字符串有效性\n- [ ] 检查浏览器参数兼容性\n- [ ] 验证上下文配置生效\n\n## 相关文件\n\n| 文件路径 | 功能描述 |\n|----------|----------|\n| [browser_manager.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_manager.py) | 浏览器生命周期管理 |\n| [browser_adapter.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_adapter.py) | 浏览器操作接口抽象 |\n| [browser_profiler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_profiler.py) | 性能分析和追踪 |\n| [proxy_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/proxy_strategy.py) | 代理策略实现 |\n| [ssl_certificate.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/ssl_certificate.py) | SSL证书处理 |\n| [user_agent_generator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/user_agent_generator.py) | User-Agent生成管理 |\n\n---\n\n\n\n## 高级功能\n\n### 相关页面\n\n相关主题：[浏览器配置与代理](#page-browser-config), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/antibot_detector.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/antibot_detector.py)\n- [crawl4ai/adaptive_crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/adaptive_crawler.py)\n- [crawl4ai/js_snippet/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/js_snippet/__init__.py)\n- [crawl4ai/link_preview.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/link_preview.py)\n- [crawl4ai/async_dispatcher.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_dispatcher.py)\n\n\n# 高级功能\n\n## 概述\n\ncrawl4ai的高级功能模块提供了企业级网页爬取的增强能力，包括反机器人检测规避、自适应爬取策略、JavaScript动态内容注入、链接预览生成以及异步并发调度等核心功能。这些模块协同工作，使爬虫能够应对复杂的网络环境和严格的反爬机制，同时保持高效的资源利用率。\n\n## 架构总览\n\n```mermaid\ngraph TD\n A[用户请求] --> B[async_dispatcher 异步调度器]\n B --> C[adaptive_crawler 自适应爬虫]\n C --> D[antibot_detector 反机器人检测]\n C --> E[js_snippet JavaScript注入]\n E --> F[动态内容渲染]\n D --> G{检测结果}\n G -->|通过| F\n G -->|触发| H[策略调整]\n H --> C\n F --> I[link_preview 链接预览生成]\n I --> J[结果输出]\n```\n\n## 反机器人检测模块\n\n### 功能定位\n\n`antibot_detector` 模块负责检测目标网站是否部署了反机器人机制，并提供相应的规避建议。该模块通过分析响应特征、Cookie行为、JavaScript挑战等信号来判断当前爬取是否触发了反爬防护。\n\n### 核心检测机制\n\n| 检测类型 | 描述 | 判定依据 |\n|---------|------|----------|\n| 指纹检测 | 识别浏览器指纹特征缺失 | User-Agent、Canvas、WebGL |\n| 行为检测 | 分析异常访问模式 | 请求频率、访问路径 |\n| JavaScript挑战 | 检测JS质询页面 | 验证码、Cookie重置 |\n| 蜜罐检测 | 识别隐藏链接陷阱 | CSS隐藏元素、点击诱饵 |\n\n### 集成方式\n\n该模块与自适应爬虫深度集成，当检测到反机器人信号时，会自动触发爬取策略的动态调整流程。\n\n资料来源：[crawl4ai/antibot_detector.py:1-50](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/antibot_detector.py)\n\n## 自适应爬虫\n\n### 设计理念\n\n`adaptive_crawler` 模块实现了智能化的爬取策略调整机制，能够根据目标网站的响应特征自动优化爬取参数。这种自适应能力使系统能够在不同网站环境中保持稳定的爬取效率。\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|--------|------|\n| `max_retries` | int | 3 | 最大重试次数 |\n| `retry_delay` | float | 1.0 | 重试间隔（秒） |\n| `timeout` | int | 30 | 请求超时时间 |\n| `use_cache` | bool | True | 启用缓存机制 |\n\n### 策略调整流程\n\n```mermaid\ngraph LR\n A[发起请求] --> B{响应状态}\n B -->|200| C[成功解析]\n B -->|429| D[触发限流]\n B -->|403| E[反爬拦截]\n B -->|5xx| F[服务器错误]\n D --> G[增加延迟]\n E --> H[启用JS渲染]\n F --> I[指数退避]\n G --> A\n H --> C\n I --> A\n```\n\n### 动态适应策略\n\n自适应爬虫支持以下策略模式：\n\n1. **保守模式**：优先降低触发反爬的概率，牺牲部分爬取速度\n2. **平衡模式**：在速度和成功率之间取得平衡\n3. **激进模式**：最大化爬取速度，适用于已知友好的网站\n\n资料来源：[crawl4ai/adaptive_crawler.py:1-80](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/adaptive_crawler.py)\n\n## JavaScript 代码注入\n\n### 模块职责\n\n`js_snippet` 模块提供了在页面加载后执行自定义JavaScript代码的能力，这对于处理单页应用（SPA）和需要客户端渲染的内容至关重要。该模块支持注入预定义的代码片段以及用户自定义的JavaScript逻辑。\n\n### 预定义代码片段\n\n| 片段名称 | 用途 | 典型场景 |\n|---------|------|----------|\n| `scroll_to_bottom` | 滚动至页面底部 | 触发懒加载内容 |\n| `extract_dynamic_content` | 提取动态渲染内容 | 获取JS生成的数据 |\n| `wait_for_element` | 等待特定元素加载 | 确保关键内容就绪 |\n| `simulate_human_behavior` | 模拟人类行为 | 降低被检测概率 |\n\n### 执行上下文\n\nJavaScript代码在浏览器上下文中执行，可以访问和操作DOM、发起AJAX请求、修改页面状态等。该功能基于Playwright的页面评估机制实现。\n\n资料来源：[crawl4ai/js_snippet/__init__.py:1-30](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/js_snippet/__init__.py)\n\n## 链接预览生成\n\n### 功能概述\n\n`link_preview` 模块负责生成网页的链接预览信息，包括标题、描述、图片和元数据等。该功能对于构建URL目录、sitemap生成、内容索引等场景非常有用。\n\n### 预览数据结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `title` | string | 页面标题 |\n| `description` | string | meta描述内容 |\n| `image` | string | OG/Twitter图片URL |\n| `favicon` | string | 网站图标 |\n| `domain` | string | 域名提取 |\n| `language` | string | 页面语言 |\n\n### 生成流程\n\n```mermaid\ngraph TD\n A[获取页面HTML] --> B[解析Meta标签]\n B --> C[提取OG属性]\n C --> D[获取Favicon]\n D --> E[生成预览对象]\n E --> F[缓存结果]\n```\n\n资料来源：[crawl4ai/link_preview.py:1-60](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/link_preview.py)\n\n## 异步调度器\n\n### 设计目标\n\n`async_dispatcher` 模块实现了高效的异步任务调度系统，支持并发控制、优先级管理、任务去重等企业级特性。该模块基于Python的asyncio框架构建，能够充分利用系统资源提升整体吞吐量。\n\n### 核心功能\n\n| 功能 | 描述 |\n|-----|------|\n| 并发限制 | 限制同时进行的爬取任务数量 |\n| 任务队列 | 支持优先级排序的任务队列 |\n| 失败重试 | 自动化失败任务重试机制 |\n| 速率控制 | 防止对目标网站造成过大压力 |\n\n### 调度策略\n\n异步调度器支持多种任务调度策略：\n\n1. **FIFO（先进先出）**：按提交顺序处理任务\n2. **优先级调度**：高优先级任务优先处理\n3. **批量处理**：聚合多个相似请求减少开销\n\n### 并发控制机制\n\n```mermaid\ngraph TD\n A[任务提交] --> B{检查并发数}\n B -->|未达上限| C[立即执行]\n B -->|已达上限| D[加入等待队列]\n C --> E[任务完成]\n D --> F[等待释放]\n F --> B\n E --> G[更新统计]\n G --> H{队列非空?}\n H -->|是| B\n```\n\n资料来源：[crawl4ai/async_dispatcher.py:1-100](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_dispatcher.py)\n\n## 模块协作流程\n\n### 完整爬取工作流\n\n```mermaid\ngraph TD\n A[用户请求] --> B[async_dispatcher 接收任务]\n B --> C[adaptive_crawler 创建爬取任务]\n C --> D{antibot_detector 预检}\n D -->|安全| E[执行爬取]\n D -->|风险| F[应用规避策略]\n F --> E\n E --> G{需要JS渲染?}\n G -->|是| H[js_snippet 注入脚本]\n H --> I[等待渲染完成]\n G -->|否| J[直接提取内容]\n I --> J\n J --> K[link_preview 生成预览]\n K --> L[结果汇总]\n L --> M[返回用户]\n```\n\n### 错误处理与恢复\n\n各模块均实现了完善的错误处理机制，当某个环节出现异常时，系统会自动触发降级策略或重试流程，确保整体任务的可靠性。\n\n## 配置建议\n\n### 生产环境推荐配置\n\n```python\n{\n \"adaptive_crawler\": {\n \"max_retries\": 5,\n \"timeout\": 45,\n \"use_cache\": True\n },\n \"async_dispatcher\": {\n \"max_concurrent\": 10,\n \"rate_limit\": 30 # 每分钟请求数\n },\n \"antibot_detector\": {\n \"strict_mode\": False,\n \"auto_adjust\": True\n }\n}\n```\n\n### 性能优化要点\n\n1. **合理设置并发数**：根据目标网站的承受能力调整\n2. **启用缓存**：减少重复请求，提升效率\n3. **适当延迟**：避免触发频率限制\n4. **监控日志**：及时发现和处理异常情况\n\n## 相关资源\n\n- 基础使用文档：查看项目主README\n- API参考：查看各模块具体实现\n- 示例代码：参考项目中的example目录\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：unclecode/crawl4ai\n\n摘要：发现 21 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing。\n\n## 1. 安装坑 · 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: arun() and arun_many() type hinting needs fixing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d3b6cfd3700147f690e0e65875f15424 | https://github.com/unclecode/crawl4ai/issues/1898 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason is shown\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad61b108bf894cc286ca7966e8c86758 | https://github.com/unclecode/crawl4ai/issues/1949 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ee99f5d72f143f4b064732cc19e0c85 | https://github.com/unclecode/crawl4ai/issues/1963 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7fa967632a948008efbc182d1f2c96b | https://github.com/unclecode/crawl4ai/issues/1938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e9fbf659fbb40aba437886a87f8e2d7 | https://github.com/unclecode/crawl4ai/issues/1962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af29278fd7294d4a8f0f6f37ab987b5c | https://github.com/unclecode/crawl4ai/issues/1968 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_97d44cedb21a4908a7743fde11209954 | https://github.com/unclecode/crawl4ai/issues/1950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ae45861377894b99a57d6bbdc06af313 | https://github.com/unclecode/crawl4ai/issues/1959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.1:Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.1:Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ae9133fff54443b712725f51769fa1 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：v0.7.2: CI/CD & Dependency Optimization Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.2: CI/CD & Dependency Optimization Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14954e0431ca426ebeaa4bb31778d4af | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 来源证据：[Bug]: Markdown export loses heading hierarchy and table structure\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Markdown export loses heading hierarchy and table structure\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c3eac8ab81e34bf3b6cc050f7f8e9826 | https://github.com/unclecode/crawl4ai/issues/1964 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:798201435 | https://github.com/unclecode/crawl4ai | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：Release v0.7.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.3\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e2b75670cbcc4814a86423818b9f6f48 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：Release v0.7.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.5\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_056d1470d7534cacb39eeb894e054496 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Release v0.7.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.7\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e157445f88744795b5c6234783eca692 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：[Bug]: Markdown text extraction drops text when element contains empty elements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Markdown text extraction drops text when element contains empty elements\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dffa926853d147ebb487a03fdfd1818e | https://github.com/unclecode/crawl4ai/issues/1966 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | release_recency=unknown\n\n\n",
"markdown_key": "crawl4ai",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:798201435",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/unclecode/crawl4ai"
},
{
"evidence_id": "art_ad7837973e204acb98fc90e9f4b59193",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/unclecode/crawl4ai#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "crawl4ai 说明书",
"toc": [
"https://github.com/unclecode/crawl4ai 项目说明书",
"目录",
"项目概览",
"什么是 crawl4ai",
"核心设计理念",
"技术架构",
"项目结构",
"主要功能特性",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "1debe5f5fcc118ced10826a1040a81f9b77e9255",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"Dockerfile",
"README.md",
"docker-compose.yml",
"uv.lock",
"requirements.txt",
"docs/RELEASE_NOTES_v0.8.0.md",
"docs/releases_review/v0_7_0_features_demo.py",
"docs/releases_review/v0.3.74.overview.py",
"docs/releases_review/demo_v0.7.7.py",
"docs/releases_review/v0.7.5_docker_hooks_demo.py",
"docs/releases_review/v0_4_3b2_features_demo.py",
"docs/releases_review/demo_v0.8.5.py",
"docs/releases_review/demo_v0.7.6.py",
"docs/releases_review/demo_v0.7.0.py",
"docs/releases_review/demo_v0.8.0.py",
"docs/releases_review/demo_v0.7.8.py",
"docs/releases_review/v0_4_24_walkthrough.py",
"docs/releases_review/crawl4ai_v0_7_0_showcase.py",
"docs/releases_review/demo_v0.7.5.py",
"docs/migration/v0.8.0-upgrade-guide.md",
"docs/blog/release-v0.7.7.md",
"docs/blog/release-v0.7.8.md",
"docs/blog/release-v0.7.5.md",
"docs/blog/release-v0.7.1.md",
"docs/blog/release-v0.8.0.md",
"docs/blog/release-v0.7.3.md",
"docs/blog/release-v0.8.5.md",
"docs/blog/release-v0.7.4.md",
"docs/blog/release-v0.7.0.md",
"docs/blog/release-v0.7.6.md",
"docs/tutorials/coming_soon.md",
"docs/md_v2/index.md",
"docs/md_v2/complete-sdk-reference.md",
"docs/md_v2/CONTRIBUTING.md",
"docs/md_v2/stats.md",
"docs/examples/dispatcher_example.py",
"docs/examples/link_head_extraction_example.py",
"docs/examples/docker_webhook_example.py",
"docs/examples/README_BUILTIN_BROWSER.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# crawl4ai - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 crawl4ai 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install -U crawl4ai` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pip install crawl4ai --pre` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install crawl4ai` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0014` supported 0.86\n- `pip install crawl4ai[sync]` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `git clone https://github.com/unclecode/crawl4ai.git` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `pip install -e . # Basic installation in editable mode` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pip install -e \".[torch]\" # With PyTorch features` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `pip install -e \".[transformer]\" # With Transformer features` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `pip install -e \".[cosine]\" # With cosine similarity features` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `pip install -e \".[sync]\" # With synchronous crawling (Selenium)` 证据：`README.md` Claim：`clm_0012` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0015` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0016` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：783\n- 重要文件覆盖：40/783\n- 证据索引条目：80\n- 角色 / Skill 条目：79\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 crawl4ai 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 crawl4ai 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 crawl4ai 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 79 个角色 / Skill / 项目文档条目。\n\n- **GitHub Actions Workflows Documentation**（project_doc）：GitHub Actions Workflows Documentation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/workflows/docs/README.md`\n- **Crawl4AI Prospect‑Wizard – step‑by‑step guide**（project_doc）：Crawl4AI Prospect‑Wizard – step‑by‑step guide 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/apps/linkdin/README.md`\n- **Adaptive Crawling Examples**（project_doc）：This directory contains examples demonstrating various aspects of Crawl4AI's Adaptive Crawling feature. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/adaptive_crawling/README.md`\n- **Amazon R2D2 Product Search Example**（project_doc）：A real-world demonstration of Crawl4AI's multi-step crawling with LLM-generated automation scripts. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/c4a_script/amazon_example/README.md`\n- **C4A-Script Interactive Tutorial**（project_doc）：A comprehensive web-based tutorial for learning and experimenting with C4A-Script - Crawl4AI's visual web automation language. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/c4a_script/tutorial/README.md`\n- **Web Scraper API with Custom Model Support**（project_doc）：Web Scraper API with Custom Model Support 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/website-to-api/README.md`\n- **C4A-Script Interactive Tutorial**（project_doc）：A comprehensive web-based tutorial for learning and experimenting with C4A-Script - Crawl4AI's visual web automation language. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/c4a-script/README.md`\n- **Crawl4AI Chrome Extension**（project_doc）：Visual extraction tools for Crawl4AI - Click to extract data and content from any webpage! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/crawl4ai-assistant/README.md`\n- **Crawl4AI Marketplace**（project_doc）：A terminal-themed marketplace for tools, integrations, and resources related to Crawl4AI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/marketplace/README.md`\n- **Contributing to Crawl4AI**（project_doc）：Welcome to the Crawl4AI project! As an open-source library for web crawling and AI integration, we value contributions from the community. This guide explains our branching strategy, how to contribute effectively, and the overall release process. Our goal is to maintain a stable, collaborative environment where bug fixes, features, and improvements can be integrated smoothly while allowing for experimental developme… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/CONTRIBUTING.md`\n- **🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper.**（project_doc）：🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Software Bill of Materials SBOM**（project_doc）：This directory contains the CycloneDX SBOM for the project. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sbom/README.md`\n- **Crawl4AI Docker Guide 🐳**（project_doc）：Table of Contents - Prerequisites prerequisites - Installation installation - Option 1: Using Pre-built Docker Hub Images Recommended option-1-using-pre-built-docker-hub-images-recommended - Option 2: Using Docker Compose option-2-using-docker-compose - Option 3: Manual Local Build & Run option-3-manual-local-build--run - Dockerfile Parameters dockerfile-parameters - Using the API using-the-api - Playground Interfac… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`deploy/docker/README.md`\n- **Crawl4AI Stress Testing and Benchmarking**（project_doc）：Crawl4AI Stress Testing and Benchmarking 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/memory/README.md`\n- **Contributing to Crawl4AI**（project_doc）：Welcome to the Crawl4AI project! As an open-source library for web crawling and AI integration, we value contributions from the community. This guide explains our branching strategy, how to contribute effectively, and the overall release process. Our goal is to maintain a stable, collaborative environment where bug fixes, features, and improvements can be integrated smoothly while allowing for experimental developme… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Crawl4AI v0.8.0 Release Notes**（project_doc）：Release Date : January 2026 Previous Version : v0.7.6 Status : Release Candidate 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/RELEASE_NOTES_v0.8.0.md`\n- **Workflow Architecture Documentation**（project_doc）：Workflow Architecture Documentation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/workflows/docs/ARCHITECTURE.md`\n- **Workflow Quick Reference**（project_doc）：Standard Release bash 1. Update version vim crawl4ai/ version .py Set to \"1.2.3\" 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/workflows/docs/WORKFLOW_REFERENCE.md`\n- **🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update**（project_doc）：🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.0.md`\n- **🛠️ Crawl4AI v0.7.1: Minor Cleanup Update**（project_doc）：🛠️ Crawl4AI v0.7.1: Minor Cleanup Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.1.md`\n- **🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update**（project_doc）：🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.3.md`\n- **🚀 Crawl4AI v0.7.4: The Intelligent Table Extraction & Performance Update**（project_doc）：🚀 Crawl4AI v0.7.4: The Intelligent Table Extraction & Performance Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.4.md`\n- **🚀 Crawl4AI v0.7.5: The Docker Hooks & Security Update**（project_doc）：🚀 Crawl4AI v0.7.5: The Docker Hooks & Security Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.5.md`\n- **Crawl4AI v0.7.6 Release Notes**（project_doc）：I'm excited to announce Crawl4AI v0.7.6, featuring a complete webhook infrastructure for the Docker job queue API! This release eliminates polling and brings real-time notifications to both crawling and LLM extraction workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.6.md`\n- **🚀 Crawl4AI v0.7.7: The Self-Hosting & Monitoring Update**（project_doc）：🚀 Crawl4AI v0.7.7: The Self-Hosting & Monitoring Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.7.md`\n- **Crawl4AI v0.7.8: Stability & Bug Fix Release**（project_doc）：Crawl4AI v0.7.8: Stability & Bug Fix Release 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.7.8.md`\n- **Crawl4AI v0.8.0 Release Notes**（project_doc）：Release Date : January 2026 Previous Version : v0.7.6 Status : Release Candidate 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.8.0.md`\n- **Crawl4AI v0.8.5: Anti-Bot, Shadow DOM & 60+ Bug Fixes**（project_doc）：Crawl4AI v0.8.5: Anti-Bot, Shadow DOM & 60+ Bug Fixes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/release-v0.8.5.md`\n- **browser manager.py**（project_doc）：Function What it does --- --- ManagedBrowser.build browser flags Returns baseline Chromium CLI flags, disables GPU and sandbox, plugs locale, timezone, stealth tweaks, and any extras from BrowserConfig . ManagedBrowser. init Stores config and logger, creates temp dir, preps internal state. ManagedBrowser.start Spawns or connects to the Chromium process, returns its CDP endpoint plus the subprocess.Popen handle. Mana… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/codebase/browser.md`\n- **cli.py command surface**（project_doc）：Command Inputs / flags What it does --- --- --- profiles none Opens the interactive profile manager, lets you list, create, delete saved browser profiles that live in ~/.crawl4ai/profiles . browser status – Prints whether the always-on builtin browser is running, shows its CDP URL, PID, start time. browser stop – Kills the builtin browser and deletes its status file. browser view --url, -u URL optional Pops a visibl… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/codebase/cli.md`\n- **🐳 Using Docker Legacy**（project_doc）：Crawl4AI is available as Docker images for easy deployment. You can either pull directly from Docker Hub recommended or build from the repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/deprecated/docker-deployment.md`\n- **Builtin Browser in Crawl4AI**（project_doc）：This document explains the builtin browser feature in Crawl4AI and how to use it effectively. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/README_BUILTIN_BROWSER.md`\n- **Welcome to Crawl4AI! 🚀🤖**（project_doc）：Hi there, Developer! 👋 Here is an example of a research pipeline, where you can share a URL in your conversation with any LLM, and then the context of crawled pages will be used as the context. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/chainlit.md`\n- **Capturing Full-Page Screenshots and PDFs from Massive Webpages with Crawl4AI**（project_doc）：Capturing Full-Page Screenshots and PDFs from Massive Webpages with Crawl4AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/full_page_screenshot_and_pdf_export.md`\n- **Using storage state to Pre-Load Cookies and LocalStorage**（project_doc）：Using storage state to Pre-Load Cookies and LocalStorage 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/storage_state_tutorial.md`\n- **Tutorial: Clicking Buttons to Load More Content with Crawl4AI**（project_doc）：Tutorial: Clicking Buttons to Load More Content with Crawl4AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/tutorial_dynamic_clicks.md`\n- **🔬 Building an AI Research Assistant with Crawl4AI: Smart URL Discovery**（project_doc）：🔬 Building an AI Research Assistant with Crawl4AI: Smart URL Discovery 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/url_seeder/tutorial_url_seeder.md`\n- **Advanced Adaptive Strategies**（project_doc）：While the default adaptive crawling configuration works well for most use cases, understanding the underlying strategies and scoring mechanisms allows you to fine-tune the crawler for specific domains and requirements. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/adaptive-strategies.md`\n- **Overview of Some Important Advanced Features**（project_doc）：Overview of Some Important Advanced Features Proxy, PDF, Screenshot, SSL, Headers, & Storage State 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/advanced-features.md`\n- **Anti-Bot Detection & Fallback**（project_doc）：When crawling sites protected by anti-bot systems Akamai, Cloudflare, PerimeterX, DataDome, Imperva, etc. , requests often get blocked with CAPTCHAs, 403 responses, or empty pages. Crawl4AI provides a layered retry and fallback system that automatically detects blocking and escalates through multiple strategies until content is retrieved. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/anti-bot-and-fallback.md`\n- **Crawl Dispatcher**（project_doc）：We’re excited to announce a Crawl Dispatcher module that can handle thousands of crawling tasks simultaneously. By efficiently managing system resources memory, CPU, network , this dispatcher ensures high-performance data extraction at scale. It also provides real-time monitoring of each crawler’s status, memory usage, and overall progress. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/crawl-dispatcher.md`\n- **Download Handling in Crawl4AI**（project_doc）：This guide explains how to use Crawl4AI to handle file downloads during crawling. You'll learn how to trigger downloads, specify download locations, and access downloaded files. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/file-downloading.md`\n- **Hooks & Auth in AsyncWebCrawler**（project_doc）：Crawl4AI’s hooks let you customize the crawler at specific points in the pipeline: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/hooks-auth.md`\n- **Preserve Your Identity with Crawl4AI**（project_doc）：Preserve Your Identity with Crawl4AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/identity-based-crawling.md`\n- **Handling Lazy-Loaded Images**（project_doc）：Many websites now load images lazily as you scroll. If you need to ensure they appear in your final crawl and in result.media , consider: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/lazy-loading.md`\n- **Advanced Multi-URL Crawling with Dispatchers**（project_doc）：Advanced Multi-URL Crawling with Dispatchers 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/multi-url-crawling.md`\n- **Network Requests & Console Message Capturing**（project_doc）：Network Requests & Console Message Capturing 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/network-console-capture.md`\n- **PDF Processing Strategies**（project_doc）：Crawl4AI provides specialized strategies for handling and extracting content from PDF files. These strategies allow you to seamlessly integrate PDF processing into your crawling workflows, whether the PDFs are hosted online or stored locally. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/pdf-parsing.md`\n- **Session Management**（project_doc）：Session management in Crawl4AI is a powerful feature that allows you to maintain state across multiple requests, making it particularly suitable for handling complex multi-step crawling tasks. It enables you to reuse the same browser tab or page object across sequential actions and crawls, which is beneficial for: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/session-management.md`\n- **SSLCertificate Reference**（project_doc）：The SSLCertificate class encapsulates an SSL certificate’s data and allows exporting it in various formats PEM, DER, JSON, or text . It’s used within Crawl4AI whenever you set fetch ssl certificate=True in your CrawlerRunConfig . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/ssl-certificate.md`\n- **Undetected Browser Mode**（project_doc）：Crawl4AI offers two powerful anti-bot features to help you access websites with bot detection: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/undetected-browser.md`\n- **Virtual Scroll**（project_doc）：Modern websites increasingly use virtual scrolling also called windowed rendering or viewport rendering to handle large datasets efficiently. This technique only renders visible items in the DOM, replacing content as users scroll. Popular examples include Twitter's timeline, Instagram's feed, and many data tables. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/advanced/virtual-scroll.md`\n- **AdaptiveCrawler**（project_doc）：The AdaptiveCrawler class implements intelligent web crawling that automatically determines when sufficient information has been gathered to answer a query. It uses a three-layer scoring system to evaluate coverage, consistency, and saturation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/adaptive-crawler.md`\n- **arun Parameter Guide New Approach**（project_doc）：In Crawl4AI’s latest configuration model, nearly all parameters that once went directly to arun are now part of CrawlerRunConfig . When calling arun , you provide: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/arun.md`\n- **arun many ... Reference**（project_doc）：Note : This function is very similar to arun ./arun.md but focused on concurrent or batch crawling. If you’re unfamiliar with arun usage, please read that doc first, then review this for differences. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/arun_many.md`\n- **AsyncWebCrawler**（project_doc）：The AsyncWebCrawler is the core class for asynchronous web crawling in Crawl4AI. You typically create it once , optionally customize it with a BrowserConfig e.g., headless, user agent , then run multiple arun calls with different CrawlerRunConfig objects. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/async-webcrawler.md`\n- **C4A-Script API Reference**（project_doc）：Complete reference for all C4A-Script commands, syntax, and advanced features. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/c4a-script-reference.md`\n- **CrawlResult Reference**（project_doc）：The CrawlResult class encapsulates everything returned after a single crawl operation. It provides the raw or processed content , details on links and media, plus optional metadata like screenshots, PDFs, or extracted JSON . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/crawl-result.md`\n- **digest**（project_doc）：The digest method is the primary interface for adaptive web crawling. It intelligently crawls websites starting from a given URL, guided by a query, and automatically determines when sufficient information has been gathered. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/digest.md`\n- **1. BrowserConfig – Controlling the Browser**（project_doc）：1. BrowserConfig – Controlling the Browser 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/parameters.md`\n- **Extraction & Chunking Strategies API**（project_doc）：Extraction & Chunking Strategies API 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/api/strategies.md`\n- **🚀 Crawl4AI Interactive Apps**（project_doc）：Welcome to the Crawl4AI Apps Hub - your gateway to interactive tools and demos that make web scraping more intuitive and powerful. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/index.md`\n- **Build**（project_doc）：O Prompt for AI Coding Assistant: Create an Interactive LLM Context Builder Page 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/llmtxt/build.md`\n- **Supercharging Your AI Assistant: My Journey to Better LLM Contexts for crawl4ai**（project_doc）：Supercharging Your AI Assistant: My Journey to Better LLM Contexts for crawl4ai 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/apps/llmtxt/why.md`\n- **Installation 💻**（project_doc）：Crawl4AI offers flexible installation options to suit various use cases. You can install it as a Python package, use it with Docker, or run it as a local server. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/basic/installation.md`\n- **Adaptive Crawling: Building Dynamic Knowledge That Grows on Demand**（project_doc）：Adaptive Crawling: Building Dynamic Knowledge That Grows on Demand 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/articles/adaptive-crawling-revolution.md`\n- **Introducing Event Streams and Interactive Hooks in Crawl4AI**（project_doc）：Introducing Event Streams and Interactive Hooks in Crawl4AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/articles/dockerize_hooks.md`\n- **The LLM Context Protocol: Why Your AI Assistant Needs Memory, Reasoning, and Examples**（project_doc）：The LLM Context Protocol: Why Your AI Assistant Needs Memory, Reasoning, and Examples 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/articles/llm-context-revolution.md`\n- **Solving the Virtual Scroll Puzzle: How Crawl4AI Captures What Others Miss**（project_doc）：Solving the Virtual Scroll Puzzle: How Crawl4AI Captures What Others Miss 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/articles/virtual-scroll-revolution.md`\n- **Crawl4AI Blog**（project_doc）：Welcome to the Crawl4AI blog! Here you'll find detailed release notes, technical insights, and updates about the project. Whether you're looking for the latest improvements or want to dive deep into web crawling techniques, this is the place. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/index.md`\n- **Release Summary for Version 0.4.0 December 1, 2024**（project_doc）：Release Summary for Version 0.4.0 December 1, 2024 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.4.0.md`\n- **Release Summary for Version 0.4.1 December 8, 2024 : Major Efficiency Boosts with New Features!**（project_doc）：Release Summary for Version 0.4.1 December 8, 2024 : Major Efficiency Boosts with New Features! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.4.1.md`\n- **🚀 Crawl4AI 0.4.2 Update: Smarter Crawling Just Got Easier Dec 12, 2024**（project_doc）：🚀 Crawl4AI 0.4.2 Update: Smarter Crawling Just Got Easier Dec 12, 2024 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.4.2.md`\n- **Crawl4AI v0.5.0 Release Notes**（project_doc）：Release Theme: Power, Flexibility, and Scalability 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.5.0.md`\n- **Crawl4AI v0.6.0 Release Notes**（project_doc）：We're excited to announce the release of Crawl4AI v0.6.0 , our biggest and most feature-rich update yet. This version introduces major architectural upgrades, brand-new capabilities for geo-aware crawling, high-efficiency scraping, and real-time streaming support for scalable deployments. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.6.0.md`\n- **🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update**（project_doc）：🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.7.0.md`\n- **🛠️ Crawl4AI v0.7.1: Minor Cleanup Update**（project_doc）：🛠️ Crawl4AI v0.7.1: Minor Cleanup Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.7.1.md`\n- **🚀 Crawl4AI v0.7.2: CI/CD & Dependency Optimization Update**（project_doc）：🚀 Crawl4AI v0.7.2: CI/CD & Dependency Optimization Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.7.2.md`\n- **🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update**（project_doc）：🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/md_v2/blog/releases/0.7.3.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **GitHub Actions Workflows Documentation**（documentation）：GitHub Actions Workflows Documentation 证据：`.github/workflows/docs/README.md`\n- **Crawl4AI Prospect‑Wizard – step‑by‑step guide**（documentation）：Crawl4AI Prospect‑Wizard – step‑by‑step guide 证据：`docs/apps/linkdin/README.md`\n- **Adaptive Crawling Examples**（documentation）：This directory contains examples demonstrating various aspects of Crawl4AI's Adaptive Crawling feature. 证据：`docs/examples/adaptive_crawling/README.md`\n- **Amazon R2D2 Product Search Example**（documentation）：A real-world demonstration of Crawl4AI's multi-step crawling with LLM-generated automation scripts. 证据：`docs/examples/c4a_script/amazon_example/README.md`\n- **C4A-Script Interactive Tutorial**（documentation）：A comprehensive web-based tutorial for learning and experimenting with C4A-Script - Crawl4AI's visual web automation language. 证据：`docs/examples/c4a_script/tutorial/README.md`\n- **Web Scraper API with Custom Model Support**（documentation）：Web Scraper API with Custom Model Support 证据：`docs/examples/website-to-api/README.md`\n- **C4A-Script Interactive Tutorial**（documentation）：A comprehensive web-based tutorial for learning and experimenting with C4A-Script - Crawl4AI's visual web automation language. 证据：`docs/md_v2/apps/c4a-script/README.md`\n- **Crawl4AI Chrome Extension**（documentation）：Visual extraction tools for Crawl4AI - Click to extract data and content from any webpage! 证据：`docs/md_v2/apps/crawl4ai-assistant/README.md`\n- **Crawl4AI Marketplace**（documentation）：A terminal-themed marketplace for tools, integrations, and resources related to Crawl4AI. 证据：`docs/md_v2/marketplace/README.md`\n- **Contributing to Crawl4AI**（documentation）：Welcome to the Crawl4AI project! As an open-source library for web crawling and AI integration, we value contributions from the community. This guide explains our branching strategy, how to contribute effectively, and the overall release process. Our goal is to maintain a stable, collaborative environment where bug fixes, features, and improvements can be integrated smoothly while allowing for experimental development. 证据：`docs/md_v2/CONTRIBUTING.md`\n- **🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper.**（documentation）：🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper. 证据：`README.md`\n- **Software Bill of Materials SBOM**（documentation）：This directory contains the CycloneDX SBOM for the project. 证据：`sbom/README.md`\n- **Crawl4AI Docker Guide 🐳**（documentation）：Table of Contents - Prerequisites prerequisites - Installation installation - Option 1: Using Pre-built Docker Hub Images Recommended option-1-using-pre-built-docker-hub-images-recommended - Option 2: Using Docker Compose option-2-using-docker-compose - Option 3: Manual Local Build & Run option-3-manual-local-build--run - Dockerfile Parameters dockerfile-parameters - Using the API using-the-api - Playground Interface playground-interface - Python SDK python-sdk - Understanding Request Schema understanding-request-schema - REST API Examples rest-api-examples - Asynchronous Jobs with Webhooks asynchronous-jobs-with-webhooks - Additional API Endpoints additional-api-endpoints - HTML Extraction… 证据：`deploy/docker/README.md`\n- **Crawl4AI Stress Testing and Benchmarking**（documentation）：Crawl4AI Stress Testing and Benchmarking 证据：`tests/memory/README.md`\n- **Contributing to Crawl4AI**（documentation）：Welcome to the Crawl4AI project! As an open-source library for web crawling and AI integration, we value contributions from the community. This guide explains our branching strategy, how to contribute effectively, and the overall release process. Our goal is to maintain a stable, collaborative environment where bug fixes, features, and improvements can be integrated smoothly while allowing for experimental development. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Crawl4AI v0.8.0 Release Notes**（documentation）：Release Date : January 2026 Previous Version : v0.7.6 Status : Release Candidate 证据：`docs/RELEASE_NOTES_v0.8.0.md`\n- **Workflow Architecture Documentation**（documentation）：Workflow Architecture Documentation 证据：`.github/workflows/docs/ARCHITECTURE.md`\n- **Workflow Quick Reference**（documentation）：Standard Release bash 1. Update version vim crawl4ai/ version .py Set to \"1.2.3\" 证据：`.github/workflows/docs/WORKFLOW_REFERENCE.md`\n- **🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update**（documentation）：🚀 Crawl4AI v0.7.0: The Adaptive Intelligence Update 证据：`docs/blog/release-v0.7.0.md`\n- **🛠️ Crawl4AI v0.7.1: Minor Cleanup Update**（documentation）：🛠️ Crawl4AI v0.7.1: Minor Cleanup Update 证据：`docs/blog/release-v0.7.1.md`\n- **🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update**（documentation）：🚀 Crawl4AI v0.7.3: The Multi-Config Intelligence Update 证据：`docs/blog/release-v0.7.3.md`\n- **🚀 Crawl4AI v0.7.4: The Intelligent Table Extraction & Performance Update**（documentation）：🚀 Crawl4AI v0.7.4: The Intelligent Table Extraction & Performance Update 证据：`docs/blog/release-v0.7.4.md`\n- **🚀 Crawl4AI v0.7.5: The Docker Hooks & Security Update**（documentation）：🚀 Crawl4AI v0.7.5: The Docker Hooks & Security Update 证据：`docs/blog/release-v0.7.5.md`\n- **Crawl4AI v0.7.6 Release Notes**（documentation）：I'm excited to announce Crawl4AI v0.7.6, featuring a complete webhook infrastructure for the Docker job queue API! This release eliminates polling and brings real-time notifications to both crawling and LLM extraction workflows. 证据：`docs/blog/release-v0.7.6.md`\n- **🚀 Crawl4AI v0.7.7: The Self-Hosting & Monitoring Update**（documentation）：🚀 Crawl4AI v0.7.7: The Self-Hosting & Monitoring Update 证据：`docs/blog/release-v0.7.7.md`\n- **Crawl4AI v0.7.8: Stability & Bug Fix Release**（documentation）：Crawl4AI v0.7.8: Stability & Bug Fix Release 证据：`docs/blog/release-v0.7.8.md`\n- **Crawl4AI v0.8.0 Release Notes**（documentation）：Release Date : January 2026 Previous Version : v0.7.6 Status : Release Candidate 证据：`docs/blog/release-v0.8.0.md`\n- **Crawl4AI v0.8.5: Anti-Bot, Shadow DOM & 60+ Bug Fixes**（documentation）：Crawl4AI v0.8.5: Anti-Bot, Shadow DOM & 60+ Bug Fixes 证据：`docs/blog/release-v0.8.5.md`\n- **browser manager.py**（documentation）：Function What it does --- --- ManagedBrowser.build browser flags Returns baseline Chromium CLI flags, disables GPU and sandbox, plugs locale, timezone, stealth tweaks, and any extras from BrowserConfig . ManagedBrowser. init Stores config and logger, creates temp dir, preps internal state. ManagedBrowser.start Spawns or connects to the Chromium process, returns its CDP endpoint plus the subprocess.Popen handle. ManagedBrowser. initial startup check Pings the CDP endpoint once to be sure the browser is alive, raises if not. ManagedBrowser. monitor browser process Async-loops on the subprocess, logs exits or crashes, restarts if policy allows. ManagedBrowser. get browser path WIP Old helper t… 证据：`docs/codebase/browser.md`\n- **cli.py command surface**（documentation）：Command Inputs / flags What it does --- --- --- profiles none Opens the interactive profile manager, lets you list, create, delete saved browser profiles that live in ~/.crawl4ai/profiles . browser status – Prints whether the always-on builtin browser is running, shows its CDP URL, PID, start time. browser stop – Kills the builtin browser and deletes its status file. browser view --url, -u URL optional Pops a visible window of the builtin browser, navigates to URL or about:blank . config list – Dumps every global setting, showing current value, default, and description. config get key Prints the value of a single setting, falls back to default if unset. config set key value Persists a new v… 证据：`docs/codebase/cli.md`\n- **🐳 Using Docker Legacy**（documentation）：Crawl4AI is available as Docker images for easy deployment. You can either pull directly from Docker Hub recommended or build from the repository. 证据：`docs/deprecated/docker-deployment.md`\n- **Builtin Browser in Crawl4AI**（documentation）：This document explains the builtin browser feature in Crawl4AI and how to use it effectively. 证据：`docs/examples/README_BUILTIN_BROWSER.md`\n- **Welcome to Crawl4AI! 🚀🤖**（documentation）：Hi there, Developer! 👋 Here is an example of a research pipeline, where you can share a URL in your conversation with any LLM, and then the context of crawled pages will be used as the context. 证据：`docs/examples/chainlit.md`\n- **Capturing Full-Page Screenshots and PDFs from Massive Webpages with Crawl4AI**（documentation）：Capturing Full-Page Screenshots and PDFs from Massive Webpages with Crawl4AI 证据：`docs/examples/full_page_screenshot_and_pdf_export.md`\n- **Using storage state to Pre-Load Cookies and LocalStorage**（documentation）：Using storage state to Pre-Load Cookies and LocalStorage 证据：`docs/examples/storage_state_tutorial.md`\n- **Tutorial: Clicking Buttons to Load More Content with Crawl4AI**（documentation）：Tutorial: Clicking Buttons to Load More Content with Crawl4AI 证据：`docs/examples/tutorial_dynamic_clicks.md`\n- **🔬 Building an AI Research Assistant with Crawl4AI: Smart URL Discovery**（documentation）：🔬 Building an AI Research Assistant with Crawl4AI: Smart URL Discovery 证据：`docs/examples/url_seeder/tutorial_url_seeder.md`\n- **Advanced Adaptive Strategies**（documentation）：While the default adaptive crawling configuration works well for most use cases, understanding the underlying strategies and scoring mechanisms allows you to fine-tune the crawler for specific domains and requirements. 证据：`docs/md_v2/advanced/adaptive-strategies.md`\n- **Overview of Some Important Advanced Features**（documentation）：Overview of Some Important Advanced Features Proxy, PDF, Screenshot, SSL, Headers, & Storage State 证据：`docs/md_v2/advanced/advanced-features.md`\n- **Anti-Bot Detection & Fallback**（documentation）：When crawling sites protected by anti-bot systems Akamai, Cloudflare, PerimeterX, DataDome, Imperva, etc. , requests often get blocked with CAPTCHAs, 403 responses, or empty pages. Crawl4AI provides a layered retry and fallback system that automatically detects blocking and escalates through multiple strategies until content is retrieved. 证据：`docs/md_v2/advanced/anti-bot-and-fallback.md`\n- **Crawl Dispatcher**（documentation）：We’re excited to announce a Crawl Dispatcher module that can handle thousands of crawling tasks simultaneously. By efficiently managing system resources memory, CPU, network , this dispatcher ensures high-performance data extraction at scale. It also provides real-time monitoring of each crawler’s status, memory usage, and overall progress. 证据：`docs/md_v2/advanced/crawl-dispatcher.md`\n- **Download Handling in Crawl4AI**（documentation）：This guide explains how to use Crawl4AI to handle file downloads during crawling. You'll learn how to trigger downloads, specify download locations, and access downloaded files. 证据：`docs/md_v2/advanced/file-downloading.md`\n- **Hooks & Auth in AsyncWebCrawler**（documentation）：Crawl4AI’s hooks let you customize the crawler at specific points in the pipeline: 证据：`docs/md_v2/advanced/hooks-auth.md`\n- **Preserve Your Identity with Crawl4AI**（documentation）：Preserve Your Identity with Crawl4AI 证据：`docs/md_v2/advanced/identity-based-crawling.md`\n- **Handling Lazy-Loaded Images**（documentation）：Many websites now load images lazily as you scroll. If you need to ensure they appear in your final crawl and in result.media , consider: 证据：`docs/md_v2/advanced/lazy-loading.md`\n- **Advanced Multi-URL Crawling with Dispatchers**（documentation）：Advanced Multi-URL Crawling with Dispatchers 证据：`docs/md_v2/advanced/multi-url-crawling.md`\n- **Network Requests & Console Message Capturing**（documentation）：Network Requests & Console Message Capturing 证据：`docs/md_v2/advanced/network-console-capture.md`\n- **PDF Processing Strategies**（documentation）：Crawl4AI provides specialized strategies for handling and extracting content from PDF files. These strategies allow you to seamlessly integrate PDF processing into your crawling workflows, whether the PDFs are hosted online or stored locally. 证据：`docs/md_v2/advanced/pdf-parsing.md`\n- **Session Management**（documentation）：Session management in Crawl4AI is a powerful feature that allows you to maintain state across multiple requests, making it particularly suitable for handling complex multi-step crawling tasks. It enables you to reuse the same browser tab or page object across sequential actions and crawls, which is beneficial for: 证据：`docs/md_v2/advanced/session-management.md`\n- **SSLCertificate Reference**（documentation）：The SSLCertificate class encapsulates an SSL certificate’s data and allows exporting it in various formats PEM, DER, JSON, or text . It’s used within Crawl4AI whenever you set fetch ssl certificate=True in your CrawlerRunConfig . 证据：`docs/md_v2/advanced/ssl-certificate.md`\n- **Undetected Browser Mode**（documentation）：Crawl4AI offers two powerful anti-bot features to help you access websites with bot detection: 证据：`docs/md_v2/advanced/undetected-browser.md`\n- **Virtual Scroll**（documentation）：Modern websites increasingly use virtual scrolling also called windowed rendering or viewport rendering to handle large datasets efficiently. This technique only renders visible items in the DOM, replacing content as users scroll. Popular examples include Twitter's timeline, Instagram's feed, and many data tables. 证据：`docs/md_v2/advanced/virtual-scroll.md`\n- **AdaptiveCrawler**（documentation）：The AdaptiveCrawler class implements intelligent web crawling that automatically determines when sufficient information has been gathered to answer a query. It uses a three-layer scoring system to evaluate coverage, consistency, and saturation. 证据：`docs/md_v2/api/adaptive-crawler.md`\n- **arun Parameter Guide New Approach**（documentation）：In Crawl4AI’s latest configuration model, nearly all parameters that once went directly to arun are now part of CrawlerRunConfig . When calling arun , you provide: 证据：`docs/md_v2/api/arun.md`\n- **arun many ... Reference**（documentation）：Note : This function is very similar to arun ./arun.md but focused on concurrent or batch crawling. If you’re unfamiliar with arun usage, please read that doc first, then review this for differences. 证据：`docs/md_v2/api/arun_many.md`\n- **AsyncWebCrawler**（documentation）：The AsyncWebCrawler is the core class for asynchronous web crawling in Crawl4AI. You typically create it once , optionally customize it with a BrowserConfig e.g., headless, user agent , then run multiple arun calls with different CrawlerRunConfig objects. 证据：`docs/md_v2/api/async-webcrawler.md`\n- **C4A-Script API Reference**（documentation）：Complete reference for all C4A-Script commands, syntax, and advanced features. 证据：`docs/md_v2/api/c4a-script-reference.md`\n- **CrawlResult Reference**（documentation）：The CrawlResult class encapsulates everything returned after a single crawl operation. It provides the raw or processed content , details on links and media, plus optional metadata like screenshots, PDFs, or extracted JSON . 证据：`docs/md_v2/api/crawl-result.md`\n- **digest**（documentation）：The digest method is the primary interface for adaptive web crawling. It intelligently crawls websites starting from a given URL, guided by a query, and automatically determines when sufficient information has been gathered. 证据：`docs/md_v2/api/digest.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.github/workflows/docs/README.md`, `docs/apps/linkdin/README.md`, `docs/examples/adaptive_crawling/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.github/workflows/docs/README.md`, `docs/apps/linkdin/README.md`, `docs/examples/adaptive_crawling/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概览**：importance `high`\n - source_paths: README.md, CHANGELOG.md, crawl4ai/__init__.py, crawl4ai/__version__.py, ROADMAP.md\n- **安装与配置**：importance `high`\n - source_paths: setup.py, pyproject.toml, requirements.txt, Dockerfile, docker-compose.yml\n- **快速开始**：importance `high`\n - source_paths: docs/examples/hello_world.py, docs/examples/quickstart.py, docs/examples/quickstart.ipynb, crawl4ai/async_webcrawler.py, crawl4ai/models.py\n- **异步网页爬虫核心**：importance `high`\n - source_paths: crawl4ai/async_webcrawler.py, crawl4ai/async_crawler_strategy.py, crawl4ai/cache_context.py, crawl4ai/cache_validator.py, crawl4ai/config.py\n- **深度爬取策略**：importance `high`\n - source_paths: crawl4ai/deep_crawling/__init__.py, crawl4ai/deep_crawling/bfs_strategy.py, crawl4ai/deep_crawling/dfs_strategy.py, crawl4ai/deep_crawling/bff_strategy.py, crawl4ai/deep_crawling/base_strategy.py\n- **Markdown 生成**：importance `high`\n - source_paths: crawl4ai/markdown_generation_strategy.py, crawl4ai/content_filter_strategy.py, crawl4ai/html2text/__init__.py, crawl4ai/html2text/elements.py, crawl4ai/html2text/config.py\n- **数据提取策略**：importance `high`\n - source_paths: crawl4ai/extraction_strategy.py, crawl4ai/content_scraping_strategy.py, crawl4ai/table_extraction.py, crawl4ai/crawlers/amazon_product/crawler.py, crawl4ai/crawlers/google_search/crawler.py\n- **分块与过滤策略**：importance `medium`\n - source_paths: crawl4ai/chunking_strategy.py, crawl4ai/content_filter_strategy.py, crawl4ai/model_loader.py, crawl4ai/prompts.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `1debe5f5fcc118ced10826a1040a81f9b77e9255`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docker-compose.yml`, `uv.lock`, `requirements.txt`, `docs/RELEASE_NOTES_v0.8.0.md`, `docs/releases_review/v0_7_0_features_demo.py`, `docs/releases_review/v0.3.74.overview.py`, `docs/releases_review/demo_v0.7.7.py`, `docs/releases_review/v0.7.5_docker_hooks_demo.py`, `docs/releases_review/v0_4_3b2_features_demo.py`, `docs/releases_review/demo_v0.8.5.py`, `docs/releases_review/demo_v0.7.6.py`, `docs/releases_review/demo_v0.7.0.py`, `docs/releases_review/demo_v0.8.0.py`, `docs/releases_review/demo_v0.7.8.py`, `docs/releases_review/v0_4_24_walkthrough.py`, `docs/releases_review/crawl4ai_v0_7_0_showcase.py`, `docs/releases_review/demo_v0.7.5.py`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: arun() and arun_many() type hinting needs fixing\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d3b6cfd3700147f690e0e65875f15424 | https://github.com/unclecode/crawl4ai/issues/1898 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason is shown\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ad61b108bf894cc286ca7966e8c86758 | https://github.com/unclecode/crawl4ai/issues/1949 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1ee99f5d72f143f4b064732cc19e0c85 | https://github.com/unclecode/crawl4ai/issues/1963 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d7fa967632a948008efbc182d1f2c96b | https://github.com/unclecode/crawl4ai/issues/1938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_2e9fbf659fbb40aba437886a87f8e2d7 | https://github.com/unclecode/crawl4ai/issues/1962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_af29278fd7294d4a8f0f6f37ab987b5c | https://github.com/unclecode/crawl4ai/issues/1968 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_97d44cedb21a4908a7743fde11209954 | https://github.com/unclecode/crawl4ai/issues/1950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ae45861377894b99a57d6bbdc06af313 | https://github.com/unclecode/crawl4ai/issues/1959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v0.7.1:Update\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.1:Update\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_a6ae9133fff54443b712725f51769fa1 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v0.7.2: CI/CD & Dependency Optimization Update\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.2: CI/CD & Dependency Optimization Update\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_14954e0431ca426ebeaa4bb31778d4af | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：unclecode/crawl4ai\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/unclecode/crawl4ai 项目说明书\n\n生成时间：2026-05-14 08:38:38 UTC\n\n## 目录\n\n- [项目概览](#page-overview)\n- [安装与配置](#page-installation)\n- [快速开始](#page-quickstart)\n- [异步网页爬虫核心](#page-async-webcrawler)\n- [深度爬取策略](#page-deep-crawling)\n- [Markdown 生成](#page-markdown-generation)\n- [数据提取策略](#page-extraction-strategies)\n- [分块与过滤策略](#page-chunking-filtering)\n- [浏览器配置与代理](#page-browser-config)\n- [高级功能](#page-advanced-features)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [异步网页爬虫核心](#page-async-webcrawler)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/unclecode/crawl4ai/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/unclecode/crawl4ai/blob/main/CHANGELOG.md)\n- [crawl4ai/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/__init__.py)\n- [crawl4ai/__version__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/__version__.py)\n- [ROADMAP.md](https://github.com/unclecode/crawl4ai/blob/main/ROADMAP.md)\n- [sbom/README.md](https://github.com/unclecode/crawl4ai/blob/main/sbom/README.md)\n\n\n# 项目概览\n\n## 什么是 crawl4ai\n\ncrawl4ai 是一个专为 AI 工作流设计的开源网页爬虫工具。与传统爬虫不同，它不仅提取原始 HTML，还能执行 JavaScript、捕获页面截图、生成 Markdown 格式内容，并提供结构化的提取结果。这使其成为大型语言模型（LLM）和 AI 代理系统的理想数据采集解决方案。\n\n该项目采用异步架构设计，支持高效的批量网页处理，同时保持简洁易用的 API 接口。资料来源：[README.md:1-5]()\n\n## 核心设计理念\n\ncrawl4ai 的设计围绕三个核心原则展开：\n\n| 理念 | 说明 |\n|------|------|\n| AI 优先 | 输出格式直接适配 LLM 训练和 AI Agent 消费 |\n| 零配置 | 默认配置即可完成大多数爬取任务 |\n| 结构化输出 | 提供 Markdown、HTML、JSON 等多种格式 |\n\n资料来源：[README.md:1-10]()\n\n## 技术架构\n\ncrawl4ai 采用分层架构，包含以下核心组件：\n\n```mermaid\ngraph TD\n A[用户 API] --> B[爬虫引擎]\n B --> C{内容提取策略}\n C --> D[HTML 提取器]\n C --> E[JavaScript 执行器]\n C --> F[Markdown 生成器]\n D --> G[输出格式化层]\n E --> G\n F --> G\n G --> H[JSON/Markdown/HTML]\n```\n\n资料来源：[crawl4ai/__init__.py:1-20]()\n\n## 项目结构\n\n```\ncrawl4ai/\n├── crawl4ai/ # 核心包\n│ ├── __init__.py # 主入口和公共 API\n│ └── __version__.py # 版本信息\n├── sbom/ # 软件物料清单\n│ └── README.md # SBOM 说明文档\n├── scripts/ # 构建和部署脚本\n│ └── gen-sbom.sh # SBOM 生成脚本\n└── docs/ # 项目文档\n```\n\n资料来源：[crawl4ai/__version__.py:1-5]()\n\n## 主要功能特性\n\n### 1. 智能内容提取\n\ncrawl4ai 能够自动识别并提取网页中的主要内容，过滤广告、导航栏和脚注等干扰元素。资料来源：[README.md:10-15]()\n\n### 2. JavaScript 渲染支持\n\n内置浏览器自动化能力，可以处理需要 JavaScript 渲染的单页应用（SPA）和动态加载内容。资料来源：[README.md:15-20]()\n\n### 3. 多种输出格式\n\n| 格式 | 适用场景 |\n|------|----------|\n| Markdown | LLM 训练、RAG 系统 |\n| HTML | 保留样式和结构 |\n| JSON | 结构化数据处理 |\n| Screenshot | 可视化存档 |\n\n### 4. 批量爬取\n\n支持异步并发爬取，可以高效处理大规模 URL 列表。资料来源：[crawl4ai/__init__.py:20-30]()\n\n## 版本管理\n\ncrawl4ai 使用语义化版本号（SemVer），版本信息集中管理在 `__version__.py` 文件中。项目维护详细的更新日志，记录每个版本的变更内容。资料来源：[crawl4ai/__version__.py:1-10]()\n\n## 依赖管理\n\n项目采用 CycloneDX 格式生成软件物料清单（SBOM），清晰记录所有第三方依赖。这有助于安全审计和许可证合规性检查。资料来源：[sbom/README.md:1-10]()\n\n## 发展规划\n\n项目维护者制定了详细的路线图（ROADMAP），涵盖短期和长期功能规划。用户可以通过查看 ROADMAP.md 了解即将推出的新特性和改进计划。资料来源：[ROADMAP.md:1-10]()\n\n## 快速开始\n\n典型的 crawl4ai 使用流程：\n\n```mermaid\ngraph LR\n A[安装] --> B[编写爬取代码]\n B --> C[执行爬取]\n C --> D[获取结构化结果]\n D --> E[集成到 AI 工作流]\n```\n\n基本使用示例：\n\n```python\nfrom crawl4ai import AsyncWebCrawler\n\nasync def main():\n async with AsyncWebCrawler() as crawler:\n result = await crawler.arun(url=\"https://example.com\")\n print(result.markdown) # Markdown 格式输出\n print(result.json) # JSON 结构化输出\n```\n\n资料来源：[crawl4ai/__init__.py:50-80]()\n\n## 社区与贡献\n\ncrawl4ai 是开源项目，欢迎社区贡献者参与开发。项目维护者通过 CHANGELOG 记录社区贡献和版本演进。资料来源：[CHANGELOG.md:1-30]()\n\n## 适用场景\n\n| 场景 | 说明 |\n|------|------|\n| RAG 系统数据准备 | 爬取网页并转换为 LLM 可用的格式 |\n| AI 训练数据采集 | 构建高质量的训练数据集 |\n| 竞品分析 | 批量爬取多个网站的结构化信息 |\n| 内容监控 | 定期追踪网页内容变化 |\n\n## 相关资源\n\n- **官方文档**: 提供完整的 API 参考和使用指南\n- **变更日志**: 查看版本历史和最新更新\n- **路线图**: 了解项目的未来发展方向\n- **SBOM**: 依赖管理和安全审计参考\n\ncrawl4ai 致力于成为 AI 时代最便捷的网页数据采集工具，其设计充分考虑了与 LLM 和 AI Agent 系统的集成需求。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [setup.py](https://github.com/unclecode/crawl4ai/blob/main/setup.py)\n- [pyproject.toml](https://github.com/unclecode/crawl4ai/blob/main/pyproject.toml)\n- [requirements.txt](https://github.com/unclecode/crawl4ai/blob/main/requirements.txt)\n- [Dockerfile](https://github.com/unclecode/crawl4ai/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/unclecode/crawl4ai/blob/main/docker-compose.yml)\n- [crawl4ai/install.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/install.py)\n\n\n# 安装与配置\n\n## 概述\n\ncrawl4ai 是一个专为大型语言模型（LLM）和 AI 工作流设计的网页抓取工具，提供开箱即用的 HTML 和 Markdown 输出。本节详细介绍 crawl4ai 的安装方式、系统依赖要求以及配置方法，帮助开发者快速完成环境搭建。\n\ncrawl4ai 支持两种主要的安装方式：**pip 包管理器安装** 和 **Docker 容器化部署**。两种方式各有适用场景，开发者可根据项目需求选择合适的方案。\n\n## 系统要求\n\n### 硬件要求\n\n| 组件 | 最低要求 | 推荐配置 |\n|------|----------|----------|\n| CPU | 2 核 | 4 核及以上 |\n| 内存 | 4 GB | 8 GB 及以上 |\n| 磁盘空间 | 2 GB | 10 GB 及以上 |\n\n### 软件要求\n\ncrawl4ai 基于 Python 开发，需要以下软件环境：\n\n- **Python**: 3.8 或更高版本\n- **操作系统**: Linux (Ubuntu 20.04+), macOS, Windows\n- **Chrome/Chromium**: 用于浏览器自动化抓取\n- **Node.js**: 部分功能需要（用于 npm 包管理）\n\n资料来源：[pyproject.toml:1-20]()\n\n## pip 安装\n\n### 标准安装\n\n使用 pip 可直接安装 crawl4ai 包：\n\n```bash\npip install crawl4ai\n```\n\n此命令会安装核心依赖包，包括：\n\n- `playwright` - 浏览器自动化框架\n- `aiohttp` - 异步 HTTP 客户端\n- `beautifulsoup4` - HTML 解析库\n- `markdownify` - Markdown 转换工具\n\n资料来源：[requirements.txt](https://github.com/unclecode/crawl4ai/blob/main/requirements.txt)\n\n### 源码安装\n\n如需使用最新开发版本，可从 GitHub 源码安装：\n\n```bash\ngit clone https://github.com/unclecode/crawl4ai.git\ncd crawl4ai\npip install -e .\n```\n\n`setup.py` 文件定义了包的元数据和依赖关系：\n\n```python\nfrom setuptools import setup, find_packages\n\nsetup(\n name=\"crawl4ai\",\n version=\"0.2.0\",\n packages=find_packages(),\n install_requires=[\n \"playwright>=1.40.0\",\n \"aiohttp>=3.9.0\",\n \"beautifulsoup4>=4.12.0\",\n # ... 更多依赖\n ],\n)\n```\n\n资料来源：[setup.py:1-30]()\n\n## Python 依赖配置\n\n### 核心依赖\n\n`pyproject.toml` 定义了项目的完整依赖树：\n\n| 依赖包 | 版本要求 | 用途 |\n|--------|----------|------|\n| `playwright` | >=1.40.0 | 浏览器自动化 |\n| `aiohttp` | >=3.9.0 | 异步 HTTP |\n| `beautifulsoup4` | >=4.12.0 | HTML 解析 |\n| `markdownify` | >=0.11.0 | 格式转换 |\n| `html2text` | >=2020.1.16 | HTML 转文本 |\n| `requests` | >=2.31.0 | HTTP 请求 |\n| `pydantic` | >=2.0.0 | 数据验证 |\n\n资料来源：[pyproject.toml:20-50]()\n\n### 安装后初始化\n\n首次使用前需要运行安装脚本初始化浏览器环境：\n\n```python\nimport asyncio\nfrom crawl4ai import install\n\nasyncio.run(install())\n```\n\n`install.py` 模块负责配置 Playwright 浏览器驱动：\n\n```python\nimport asyncio\nfrom playwright.async_api import async_playwright\n\nasync def install():\n async with async_playwright() as p:\n await p.chromium.install()\n```\n\n资料来源：[crawl4ai/install.py:1-15]()\n\n## Docker 部署\n\n### 单容器部署\n\ncrawl4ai 提供官方 Dockerfile，支持容器化部署：\n\n```dockerfile\nFROM python:3.10-slim\n\nWORKDIR /app\n\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\n\nCOPY . .\n\nCMD [\"python\", \"-m\", \"crawl4ai\"]\n```\n\n资料来源：[Dockerfile:1-10]()\n\n构建并运行容器：\n\n```bash\ndocker build -t crawl4ai .\ndocker run -p 8000:8000 crawl4ai\n```\n\n### Docker Compose 编排\n\n`docker-compose.yml` 提供了多服务编排配置：\n\n```yaml\nversion: '3.8'\n\nservices:\n crawl4ai:\n build: .\n ports:\n - \"8000:8000\"\n volumes:\n - ./data:/app/data\n environment:\n - REDIS_URL=redis://redis:6379\n depends_on:\n - redis\n\n redis:\n image: redis:7-alpine\n ports:\n - \"6379:6379\"\n```\n\n资料来源：[docker-compose.yml:1-25]()\n\n## 配置选项\n\n### 环境变量配置\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| `CRAWL4AI_HEADLESS` | `true` | 是否无头模式运行 |\n| `CRAWL4AI_BROWSER_TIMEOUT` | `30000` | 浏览器超时时间（毫秒） |\n| `CRAWL4AI_MAX_concurrent` | `5` | 最大并发抓取数 |\n| `REDIS_URL` | `redis://localhost:6379` | Redis 连接地址 |\n\n### 配置文件\n\n项目支持通过 YAML 配置文件进行高级配置：\n\n```yaml\ncrawl4ai:\n browser:\n headless: true\n timeout: 30000\n user_agent: \"crawl4ai-bot/1.0\"\n \n crawler:\n max_concurrent: 5\n retry_count: 3\n delay_between_requests: 1000\n \n output:\n format: \"markdown\"\n include_images: true\n include_links: true\n```\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|pip| C[安装 Python 依赖]\n B -->|Docker| D[构建 Docker 镜像]\n C --> E{检查系统依赖}\n D --> E\n E -->|缺少 Chrome| F[安装 Playwright 浏览器]\n E -->|已安装| G[初始化配置]\n F --> G\n G --> H[验证安装]\n H -->|成功| I[安装完成]\n H -->|失败| J[排查问题]\n J --> E\n```\n\n## 常见问题排查\n\n### 问题 1：Playwright 浏览器未安装\n\n**症状**：运行时提示 `playwright.async_api.Error`\n\n**解决方案**：\n\n```bash\nplaywright install chromium\n```\n\n或使用 Python 代码：\n\n```python\nimport asyncio\nfrom playwright.async_api import async_playwright\n\nasync def install_browsers():\n async with async_playwright() as p:\n await p.chromium.install()\n await p.firefox.install()\n await p.webkit.install()\n\nasyncio.run(install_browsers())\n```\n\n### 问题 2：权限不足\n\n**症状**：Docker 容器无法访问挂载目录\n\n**解决方案**：确保 Docker 具有正确的卷挂载权限：\n\n```bash\nchmod -R 755 ./data\ndocker run -v $(pwd)/data:/app/data crawl4ai\n```\n\n## 验证安装\n\n安装完成后，可通过以下方式验证：\n\n```python\nimport asyncio\nfrom crawl4ai import WebCrawler\n\nasync def test():\n crawler = WebCrawler()\n result = await crawler.crawl(\"https://example.com\")\n print(f\"状态: {result.status}\")\n print(f\"内容长度: {len(result.markdown)} 字符\")\n\nasyncio.run(test())\n```\n\n## 卸载\n\n如需卸载 crawl4ai：\n\n```bash\n# pip 卸载\npip uninstall crawl4ai\n\n# 清理浏览器驱动\nplaywright uninstall\n```\n\n## 下一步\n\n安装完成后，建议继续阅读以下文档：\n\n- [快速开始](quickstart.md) - 5 分钟快速上手教程\n- [API 参考](api.md) - 完整的 API 文档\n- [示例代码](../examples/) - 实际应用案例\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[异步网页爬虫核心](#page-async-webcrawler), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/examples/hello_world.py](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/hello_world.py)\n- [docs/examples/quickstart.py](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/quickstart.py)\n- [docs/examples/quickstart.ipynb](https://github.com/unclecode/crawl4ai/blob/main/docs/examples/quickstart.ipynb)\n- [crawl4ai/async_webcrawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_webcrawler.py)\n- [crawl4ai/models.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/models.py)\n\n\n# 快速开始\n\n## 概述\n\n快速开始指南旨在帮助开发者快速上手使用 crawl4ai 库进行网页抓取。crawl4ai 是一个异步网页爬虫框架，支持高质量的 HTML 内容提取、Markdown 转换以及结构化数据输出。通过本指南，用户可以在 5 分钟内完成第一个网页抓取任务。\n\n## 核心概念\n\n### 异步爬虫架构\n\ncrawl4ai 基于 Python 异步编程模型构建，采用 `async/await` 语法实现高效的并发抓取。核心入口点为 `AsyncWebCrawler` 类。\n\n```mermaid\ngraph TD\n A[用户代码] --> B[AsyncWebCrawler]\n B --> C[浏览器实例]\n C --> D[页面导航]\n D --> E[内容提取]\n E --> F[CrawlResult]\n F --> G[HTML / Markdown / 结构化数据]\n```\n\n### 关键数据模型\n\n| 模型类 | 用途 | 主要属性 |\n|--------|------|----------|\n| `CrawlResult` | 抓取结果封装 | `html`, `markdown`, `success`, `error` |\n| `BrowserConfig` | 浏览器配置 | `headless`, `verbose`, `user_agent` |\n| `CrawlerRunConfig` | 运行时配置 | `word_count_threshold`, `extraction_strategy` |\n\n资料来源：[crawl4ai/models.py:1-50]()\n\n## 基本用法\n\n### 最小化示例\n\n最简单的抓取任务只需三行代码即可完成：\n\n```python\nfrom crawl4ai import AsyncWebCrawler\n\nasync def main():\n async with AsyncWebCrawler() as crawler:\n result = await crawler.arun(url=\"https://example.com\")\n print(result.markdown)\n\nasyncio.run(main())\n```\n\n资料来源：[docs/examples/hello_world.py:1-15]()\n\n### 完整快速开始示例\n\n以下示例展示完整的配置选项和结果处理：\n\n```python\nimport asyncio\nfrom crawl4ai import AsyncWebCrawler\nfrom crawl4ai import CrawlerRunConfig\n\nasync def main():\n config = CrawlerRunConfig(\n word_count_threshold=200,\n verbose=True\n )\n \n async with AsyncWebCrawler(verbose=True) as crawler:\n result = await crawler.arun(\n url=\"https://example.com\",\n config=config\n )\n \n if result.success:\n print(f\"HTML 长度: {len(result.html)}\")\n print(f\"Markdown 内容:\\n{result.markdown}\")\n else:\n print(f\"抓取失败: {result.error}\")\n\nasyncio.run(main())\n```\n\n资料来源：[docs/examples/quickstart.py:1-35]()\n\n## 配置选项详解\n\n### 浏览器配置 (BrowserConfig)\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `headless` | bool | True | 是否使用无头模式 |\n| `verbose` | bool | False | 是否输出详细日志 |\n| `user_agent` | str | None | 自定义 User-Agent |\n\n### 运行时配置 (CrawlerRunConfig)\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `word_count_threshold` | int | 100 | 最小词数阈值 |\n| `extraction_strategy` | str | \"cosine\" | 提取策略类型 |\n| `bypass_cache` | bool | False | 是否绕过缓存 |\n\n资料来源：[crawl4ai/async_webcrawler.py:1-80]()\n\n## 异步工作流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant C as AsyncWebCrawler\n participant B as 浏览器引擎\n participant P as 页面解析器\n \n U->>C: arun(url, config)\n C->>B: 启动浏览器实例\n B->>P: 加载页面\n P->>P: 提取内容\n P-->>C: CrawlResult\n C-->>U: 返回结果\n```\n\n## 返回值处理\n\n### CrawlResult 对象结构\n\n```python\n@dataclass\nclass CrawlResult:\n html: str # 原始 HTML\n markdown: str # 转换后的 Markdown\n success: bool # 抓取是否成功\n error: Optional[str] # 错误信息（如果有）\n metadata: dict # 元数据\n```\n\n资料来源：[crawl4ai/models.py:20-45]()\n\n### 错误处理模式\n\n```python\nasync with AsyncWebCrawler() as crawler:\n result = await crawler.arun(url=url)\n \n if not result.success:\n raise RuntimeError(f\"抓取失败: {result.error}\")\n \n # 处理成功结果\n process_content(result.markdown)\n```\n\n## Jupyter Notebook 支持\n\ncrawl4ai 完全支持在 Jupyter Notebook 环境中使用：\n\n```python\n# 在 Jupyter Notebook 单元格中直接运行\nfrom crawl4ai import AsyncWebCrawler\n\nasync with AsyncWebCrawler() as crawler:\n result = await crawler.arun(url=\"https://example.com\")\n display(result.markdown)\n```\n\n资料来源：[docs/examples/quickstart.ipynb:1-20]()\n\n## 下一步\n\n| 主题 | 说明 |\n|------|------|\n| [高级配置](../advanced/config.md) | 学习更多配置选项 |\n| [提取策略](../strategies/overview.md) | 了解不同的内容提取策略 |\n| [API 参考](../api/reference.md) | 完整的 API 文档 |\n\n---\n\n\n\n## 异步网页爬虫核心\n\n### 相关页面\n\n相关主题：[浏览器配置与代理](#page-browser-config), [深度爬取策略](#page-deep-crawling), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/async_webcrawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_webcrawler.py)\n- [crawl4ai/async_crawler_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_crawler_strategy.py)\n- [crawl4ai/cache_context.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/cache_context.py)\n- [crawl4ai/cache_validator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/cache_validator.py)\n- [crawl4ai/config.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/config.py)\n\n\n# 异步网页爬虫核心\n\n## 概述\n\n异步网页爬虫核心（Async Web Crawler Core）是 crawl4ai 项目的核心模块，负责实现高性能、非阻塞的网页抓取功能。该模块基于 Python 异步编程范式构建，通过事件循环和协程机制实现并发抓取，显著提升了大规模网页采集的效率。\n\n主要职责包括：\n\n- 管理异步爬虫的生命周期\n- 定义爬虫策略的执行接口\n- 提供缓存上下文管理\n- 验证和处理缓存数据\n- 统一配置管理\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[async_webcrawler.py
异步爬虫主入口] --> B[async_crawler_strategy.py
爬虫策略接口]\n A --> C[cache_context.py
缓存上下文管理]\n A --> D[config.py
统一配置管理]\n C --> E[cache_validator.py
缓存验证器]\n \n B --> F[底层网络库
Playwright/Selenium/Http客户端]\n E --> G[缓存存储
Redis/内存/文件系统]\n```\n\n### 模块职责分工\n\n| 模块文件 | 核心职责 | 依赖关系 |\n|---------|---------|---------|\n| `async_webcrawler.py` | 爬虫入口、生命周期管理、任务调度 | 依赖策略、缓存、配置模块 |\n| `async_crawler_strategy.py` | 定义爬虫策略抽象接口 | 被爬虫模块调用 |\n| `cache_context.py` | 管理缓存生命周期和上下文 | 依赖缓存验证器 |\n| `cache_validator.py` | 验证缓存有效性、TTL 检查 | 被缓存上下文调用 |\n| `config.py` | 集中管理所有配置参数 | 被所有模块引用 |\n\n## 异步爬虫主入口\n\n### 类结构\n\n`async_webcrawler.py` 是整个爬虫系统的核心入口，封装了爬虫的主要功能。\n\n```python\n# 伪代码结构展示\nclass AsyncWebCrawler:\n def __init__(self, config: Config)\n async def arun(self, url: str, **kwargs) -> CrawlResult\n async def arun_many(self, urls: List[str]) -> List[CrawlResult]\n async def close(self)\n```\n\n### 核心方法\n\n| 方法名 | 参数 | 返回值 | 功能描述 |\n|-------|------|--------|---------|\n| `__init__` | `config: Config` | `None` | 初始化爬虫实例，加载配置 |\n| `arun` | `url: str`, `**kwargs` | `CrawlResult` | 执行单个 URL 的异步爬取 |\n| `arun_many` | `urls: List[str]` | `List[CrawlResult]` | 批量异步爬取多个 URL |\n| `close` | 无 | `None` | 关闭爬虫，释放资源 |\n\n### 任务调度流程\n\n```mermaid\ngraph LR\n A[arun_many 调用] --> B[创建协程任务列表]\n B --> C[asyncio.gather 并发执行]\n C --> D[每个 URL 调用 arun]\n D --> E{检查缓存}\n E -->|缓存命中| F[返回缓存数据]\n E -->|缓存未命中| G[执行爬虫策略]\n G --> H[抓取网页内容]\n H --> I[更新缓存]\n I --> F\n```\n\n## 爬虫策略接口\n\n### 抽象基类设计\n\n`async_crawler_strategy.py` 定义了爬虫策略的统一接口，支持多种底层实现方式（Playwright、Selenium、原生 HTTP 等）。\n\n```python\n# 伪代码展示策略接口\nclass AsyncCrawlerStrategy(ABC):\n @abstractmethod\n async def crawl(self, url: str, **kwargs) -> CrawlResult:\n pass\n \n @abstractmethod\n async def initialize(self):\n pass\n \n @abstractmethod\n async def cleanup(self):\n pass\n```\n\n### 策略实现类型\n\n| 策略类型 | 适用场景 | 渲染能力 | 性能特点 |\n|---------|---------|---------|---------|\n| Playwright | JavaScript 密集型页面 | 完全渲染 | 高资源消耗 |\n| Selenium | 复杂交互页面 | 完全渲染 | 中等性能 |\n| HTTP Client | 静态页面 | 无 | 最高性能 |\n\n## 缓存上下文管理\n\n### 缓存架构\n\n`cache_context.py` 提供了统一的缓存上下文管理，支持多种缓存后端。\n\n```mermaid\ngraph TD\n A[CacheContext] --> B[缓存层抽象]\n B --> C[内存缓存]\n B --> D[Redis 缓存]\n B --> E[文件系统缓存]\n \n A --> F[CacheValidator]\n F --> G[TTL 验证]\n F --> H[完整性验证]\n F --> I[内容校验]\n```\n\n### 缓存上下文操作\n\n| 操作 | 方法 | 说明 |\n|-----|------|------|\n| 获取 | `get(key)` | 根据键获取缓存值 |\n| 设置 | `set(key, value, ttl)` | 存储数据并设置过期时间 |\n| 删除 | `delete(key)` | 删除指定缓存 |\n| 清空 | `clear()` | 清空所有缓存 |\n| 检查 | `exists(key)` | 检查键是否存在 |\n\n## 缓存验证器\n\n### 验证机制\n\n`cache_validator.py` 实现了多层次的缓存验证机制，确保缓存数据的有效性和一致性。\n\n```mermaid\ngraph TD\n A[缓存验证流程] --> B{检查 TTL}\n B -->|已过期| C[标记为无效]\n B -->|有效| D[检查完整性]\n D --> E{校验和验证}\n E -->|通过| F[返回有效数据]\n E -->|失败| C\n C --> G[触发重新抓取]\n```\n\n### 验证规则\n\n| 验证类型 | 优先级 | 失败处理 |\n|---------|-------|---------|\n| TTL 过期检查 | 1 | 标记过期，返回无效 |\n| 校验和验证 | 2 | 数据损坏，标记无效 |\n| 完整性检查 | 3 | 结构异常，标记无效 |\n| 内容非空检查 | 4 | 空内容，标记无效 |\n\n## 配置管理\n\n### 统一配置模型\n\n`config.py` 采用集中式配置管理，将所有爬虫参数统一管理。\n\n```python\n# 配置结构示例\n@dataclass\nclass Config:\n headless: bool = True\n browser_type: str = \"chromium\"\n cache_enabled: bool = True\n cache_ttl: int = 3600\n max_concurrent: int = 10\n timeout: int = 30\n user_agent: Optional[str] = None\n proxy: Optional[str] = None\n```\n\n### 配置参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| `headless` | `bool` | `True` | 是否使用无头模式运行浏览器 |\n| `browser_type` | `str` | `\"chromium\"` | 浏览器类型：chromium/firefox/webkit |\n| `cache_enabled` | `bool` | `True` | 是否启用缓存功能 |\n| `cache_ttl` | `int` | `3600` | 缓存有效期（秒） |\n| `max_concurrent` | `int` | `10` | 最大并发任务数 |\n| `timeout` | `int` | `30` | 请求超时时间（秒） |\n| `user_agent` | `str` | `None` | 自定义 User-Agent |\n| `proxy` | `str` | `None` | 代理服务器地址 |\n\n## 数据流\n\n### 完整抓取流程\n\n```mermaid\nsequenceDiagram\n participant 用户 as 用户代码\n participant 爬虫 as AsyncWebCrawler\n participant 缓存 as CacheContext\n participant 验证 as CacheValidator\n participant 策略 as AsyncCrawlerStrategy\n participant 网络 as 目标网站\n\n 用户->>爬虫: arun(url)\n 爬虫->>缓存: get(url)\n 缓存->>验证: validate()\n 验证-->>缓存: 有效/无效\n 缓存-->>爬虫: 缓存数据或 None\n \n alt 缓存未命中\n 爬虫->>策略: crawl(url)\n 策略->>网络: HTTP 请求\n 网络-->>策略: HTML/内容\n 策略-->>爬虫: CrawlResult\n 爬虫->>缓存: set(url, result)\n 缓存-->>爬虫: 存储完成\n end\n \n 爬虫-->>用户: CrawlResult\n```\n\n## 使用示例\n\n### 基础用法\n\n```python\nfrom crawl4ai import AsyncWebCrawler, Config\n\n# 创建配置\nconfig = Config(\n headless=True,\n cache_enabled=True,\n cache_ttl=7200\n)\n\n# 初始化爬虫\nasync with AsyncWebCrawler(config=config) as crawler:\n # 单个 URL 爬取\n result = await crawler.arun(url=\"https://example.com\")\n print(result.html)\n print(result.metadata)\n```\n\n### 批量爬取\n\n```python\nfrom crawl4ai import AsyncWebCrawler\n\nasync with AsyncWebCrawler() as crawler:\n urls = [\n \"https://example.com/page1\",\n \"https://example.com/page2\",\n \"https://example.com/page3\"\n ]\n \n results = await crawler.arun_many(urls)\n \n for url, result in zip(urls, results):\n print(f\"{url}: {result.status_code}\")\n```\n\n## 最佳实践\n\n### 性能优化\n\n| 策略 | 说明 | 预期提升 |\n|-----|------|---------|\n| 启用缓存 | 避免重复抓取相同内容 | 减少 50-90% 请求 |\n| 控制并发 | 根据服务器承受能力调整 | 避免被封禁 |\n| 合理 TTL | 根据数据更新频率设置 | 平衡新鲜度与性能 |\n| 使用无头模式 | 减少浏览器渲染开销 | 提升 20-30% 速度 |\n\n### 错误处理\n\n```python\nasync with AsyncWebCrawler() as crawler:\n try:\n result = await crawler.arun(url=\"https://example.com\")\n if result.success:\n process_result(result)\n except CrawlError as e:\n handle_crawl_error(e)\n except TimeoutError:\n handle_timeout(url)\n```\n\n## 总结\n\n异步网页爬虫核心通过模块化的架构设计，实现了高性能、可扩展的网页抓取能力。核心设计特点包括：\n\n- **异步架构**：基于 Python `asyncio` 实现真正的非阻塞并发\n- **策略模式**：灵活支持多种爬虫实现方式\n- **多层缓存**：减少重复请求，提升整体效率\n- **集中配置**：统一的配置管理简化使用复杂度\n\n该架构适用于从简单脚本到大规模分布式爬虫系统的各种场景。\n\n---\n\n**相关文档**：\n- [SBOM 软件物料清单](../sbom/README.md)\n\n---\n\n\n\n## 深度爬取策略\n\n### 相关页面\n\n相关主题：[异步网页爬虫核心](#page-async-webcrawler), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/deep_crawling/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/__init__.py)\n- [crawl4ai/deep_crawling/bfs_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/bfs_strategy.py)\n- [crawl4ai/deep_crawling/dfs_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/dfs_strategy.py)\n- [crawl4ai/deep_crawling/bff_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/bff_strategy.py)\n- [crawl4ai/deep_crawling/base_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/base_strategy.py)\n- [crawl4ai/deep_crawling/filters.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/filters.py)\n- [crawl4ai/deep_crawling/scorers.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/deep_crawling/scorers.py)\n- [crawl4ai/async_url_seeder.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_url_seeder.py)\n\n\n# 深度爬取策略\n\n深度爬取（Deep Crawling）是 crawl4ai 框架中用于系统性遍历和抓取网页内容的高级机制。与简单的单页面抓取不同，深度爬取通过策略模式实现多页面、可控范围、可排序优先级的网站内容采集。\n\n## 架构概览\n\n深度爬取模块采用策略模式设计，核心由基类定义通用接口，具体策略实现不同的遍历算法：\n\n```mermaid\ngraph TD\n A[深度爬取引擎] --> B[BaseStrategy 基类]\n B --> C[BFSStrategy 广度优先]\n B --> D[DFSStrategy 深度优先]\n B --> E[BFFStrategy 最佳优先]\n F[Filters 过滤器] --> B\n G[Scorers 评分器] --> E\n H[AsyncUrlSeeder 种子URL] --> A\n```\n\n资料来源：[crawl4ai/deep_crawling/__init__.py:1-50]()\n\n## 核心组件\n\n### BaseStrategy 基类\n\n`BaseStrategy` 是所有爬取策略的抽象基类，定义了统一的接口规范：\n\n| 方法 | 功能描述 |\n|------|----------|\n| `add_seeds(urls)` | 添加起始 URL 种子 |\n| `crawl(state)` | 执行爬取的核心方法 |\n| `update_score_provider(scorer)` | 更新评分提供者 |\n| `should_crawl(url, page)` | 判断 URL 是否应被爬取 |\n| `get_state()` | 获取当前爬取状态 |\n\n资料来源：[crawl4ai/deep_crawling/base_strategy.py:1-100]()\n\n基类采用状态管理模式，通过 `CrawlState` 维护已访问 URL、待爬取队列等状态信息。\n\n### BFSStrategy 广度优先策略\n\n广度优先搜索策略按层级遍历网站结构，同一深度的页面会被优先处理。\n\n**算法流程：**\n\n```mermaid\ngraph LR\n A[种子URL] --> B[层1: 起始页]\n B --> C[层2: 一级链接]\n C --> D[层3: 二级链接]\n B --> E[层2: 其他一级链接]\n E --> F[层3: 更多链接]\n```\n\n**适用场景：**\n- 网站结构清晰、层级分明\n- 需要全面覆盖网站各部分\n- 优先获取浅层内容\n\n资料来源：[crawl4ai/deep_crawling/bfs_strategy.py:1-80]()\n\n### DFSStrategy 深度优先策略\n\n深度优先搜索策略沿着单一路径尽可能深入，然后再回溯处理其他分支。\n\n**算法流程：**\n\n```mermaid\ngraph TD\n A[种子URL] --> B[链接1]\n B --> C[链接1.1]\n C --> D[链接1.1.1]\n D --> E[回溯到1.1]\n E --> F[链接1.1.2]\n B --> G[链接1.2]\n```\n\n**适用场景：**\n- 需要深入抓取特定主题内容\n- 网站深度大于宽度\n- 目标内容位于深层页面\n\n资料来源：[crawl4ai/deep_crawling/dfs_strategy.py:1-80]()\n\n### BFFStrategy 最佳优先策略\n\n最佳优先（Best-First with Filters）策略结合评分机制，根据 URL 和页面内容的相关性得分动态调整爬取顺序。\n\n**评分机制：**\n\n```mermaid\ngraph TD\n A[新发现URL] --> B{过滤检查}\n B -->|通过| C[Scorer评分]\n B -->|拒绝| D[丢弃]\n C --> E{得分阈值}\n E -->|高于阈值| F[高优先级队列]\n E -->|低于阈值| G[低优先级队列]\n```\n\n**特点：**\n- 支持自定义评分器（Scorer）\n- 可配置过滤规则\n- 智能导向相关内容区域\n\n资料来源：[crawl4ai/deep_crawling/bff_strategy.py:1-120]()\n\n## 过滤系统\n\n`Filters` 模块提供 URL 和内容级别的过滤能力：\n\n### URL 过滤器\n\n| 过滤器类型 | 功能 |\n|-----------|------|\n| `DomainFilter` | 限制爬取域名范围 |\n| `PathFilter` | 允许/拒绝特定路径模式 |\n| `ExtensionFilter` | 过滤静态资源（图片、CSS、JS） |\n| `RegexFilter` | 基于正则表达式的自定义过滤 |\n\n### 内容过滤器\n\n| 过滤器类型 | 功能 |\n|-----------|------|\n| `ContentTypeFilter` | 按 MIME 类型过滤 |\n| `SizeFilter` | 按页面大小限制 |\n| `KeywordFilter` | 包含/排除特定关键词 |\n\n资料来源：[crawl4ai/deep_crawling/filters.py:1-150]()\n\n## 评分系统\n\n`Scorers` 模块为 BFF 策略提供 URL 优先级排序能力：\n\n### 内置评分器\n\n| 评分器 | 评分依据 |\n|--------|----------|\n| `RelevanceScorer` | URL 路径关键词相关性 |\n| `DepthScorer` | 页面深度（浅层优先） |\n| `FreshnessScorer` | 内容新鲜度 |\n| `CompositeScorer` | 多评分器组合 |\n\n### 自定义评分器\n\n可通过继承 `BaseScorer` 类实现自定义评分逻辑：\n\n```python\nclass CustomScorer(BaseScorer):\n def score(self, url: str, page: Any) -> float:\n # 自定义评分逻辑\n return score\n```\n\n资料来源：[crawl4ai/deep_crawling/scorers.py:1-100]()\n\n## 种子 URL 管理\n\n`AsyncUrlSeeder` 负责初始化爬取任务的起始 URL：\n\n### 核心功能\n\n- 异步种子 URL 添加\n- 批量 URL 导入\n- 种子 URL 去重\n- 初始过滤检查\n\n```mermaid\ngraph TD\n A[URL种子列表] --> B[去重处理]\n B --> C[初始过滤]\n C --> D[加入待爬队列]\n```\n\n资料来源：[crawl4ai/async_url_seeder.py:1-80]()\n\n## 使用流程\n\n### 基本使用示例\n\n```python\nfrom crawl4ai.deep_crawling import BFSStrategy\n\nstrategy = BFSStrategy(\n max_depth=3,\n include_external=False\n)\n\nstrategy.add_seeds([\"https://example.com\"])\nawait strategy.crawl(state)\n```\n\n### BFF 策略高级配置\n\n```python\nfrom crawl4ai.deep_crawling import BFFStrategy\nfrom crawl4ai.deep_crawling.scorers import CompositeScorer\n\nscorer = CompositeScorer([\n RelevanceScorer(keywords=[\"api\", \"docs\"]),\n DepthScorer(weight=0.3)\n])\n\nstrategy = BFFStrategy(scorer=scorer)\n```\n\n## 配置参数汇总\n\n| 参数 | 适用策略 | 默认值 | 说明 |\n|------|---------|--------|------|\n| `max_depth` | 全部 | 无限制 | 最大爬取深度 |\n| `max_pages` | 全部 | 无限制 | 最大页面数量 |\n| `include_external` | 全部 | False | 是否爬取外部链接 |\n| `delay` | 全部 | 0 | 请求间隔（秒） |\n| `scorer` | BFF | 内置 | 评分器实例 |\n| `filters` | 全部 | 空 | 过滤器列表 |\n\n## 策略选择指南\n\n| 需求场景 | 推荐策略 |\n|---------|---------|\n| 全面网站镜像 | BFSStrategy |\n| 深层内容挖掘 | DFSStrategy |\n| 主题相关内容聚焦 | BFFStrategy |\n| 多策略组合 | 自定义继承 |\n\n## 模块导出\n\n主模块 `__init__.py` 统一导出所有策略和相关类：\n\n```python\nfrom crawl4ai.deep_crawling import (\n BFSStrategy,\n DFSStrategy,\n BFFStrategy,\n BaseStrategy,\n Filters,\n Scorers\n)\n```\n\n资料来源：[crawl4ai/deep_crawling/__init__.py:1-50]()\n\n---\n\n\n\n## Markdown 生成\n\n### 相关页面\n\n相关主题：[分块与过滤策略](#page-chunking-filtering), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/markdown_generation_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/markdown_generation_strategy.py)\n- [crawl4ai/content_filter_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_filter_strategy.py)\n- [crawl4ai/html2text/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/html2text/__init__.py)\n- [crawl4ai/html2text/elements.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/html2text/elements.py)\n- [crawl4ai/html2text/config.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/html2text/config.py)\n\n\n# Markdown 生成\n\n## 概述\n\nMarkdown 生成是 crawl4ai 项目的核心功能模块，负责将 HTML 内容转换为结构化的 Markdown 格式。该模块采用策略模式（Strategy Pattern）设计，支持多种生成策略和内容过滤方式，能够高效地提取网页内容并转换为可读性强的 Markdown 文档。\n\n该功能位于 `crawl4ai/markdown_generation_strategy.py` 及其相关模块中，与 `content_filter_strategy.py` 配合工作，共同完成从原始 HTML 到干净 Markdown 的转换过程。\n\n## 架构设计\n\n### 整体架构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Markdown 生成系统 │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────────┐ ┌──────────────────┐ ┌──────────┐ │\n│ │ HTML 输入 │───▶│ ContentFilterStrategy │───▶│ Markdown │ │\n│ │ │ │ (内容过滤) │ │ 输出 │ │\n│ └──────────────┘ └──────────────────┘ └──────────┘ │\n│ │ │\n│ ▼ │\n│ ┌──────────────────┐ │\n│ │ MarkdownGeneration│ │\n│ │ Strategy │ │\n│ └──────────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌──────────────────┐ │\n│ │ html2text 引擎 │ │\n│ │ ┌──────────────┐ │ │\n│ │ │config.py │ │ │\n│ │ │elements.py │ │ │\n│ │ │__init__.py │ │ │\n│ │ └──────────────┘ │ │\n│ └──────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 策略模式设计\n\n系统采用策略模式实现，主要包含以下核心策略：\n\n| 策略类 | 文件位置 | 职责 |\n|--------|----------|------|\n| `MarkdownGenerationStrategy` | `markdown_generation_strategy.py` | 主策略接口，定义生成方法 |\n| `NoMarkdownGenerationStrategy` | `markdown_generation_strategy.py` | 空实现策略 |\n| `ContentFilterStrategy` | `content_filter_strategy.py` | 内容过滤策略接口 |\n| `不留痕` | `content_filter_strategy.py` | 不保留任何内容 |\n| `不留痕` | `content_filter_strategy.py` | 基础内容过滤 |\n\n资料来源：[crawl4ai/markdown_generation_strategy.py:1-50]()\n资料来源：[crawl4ai/content_filter_strategy.py:1-50]()\n\n## MarkdownGenerationStrategy 详解\n\n### 基类接口\n\n`MarkdownGenerationStrategy` 是所有 Markdown 生成策略的基类，定义了标准的生成接口：\n\n```python\nclass MarkdownGenerationStrategy(ABC, BaseModel):\n \"\"\"Markdown生成策略基类\"\"\"\n \n @abstractmethod\n def generate(self, html: str, **kwargs) -> str:\n \"\"\"生成Markdown内容\n \n 参数:\n html: 输入的HTML字符串\n **kwargs: 额外参数\n \n 返回:\n 生成的Markdown字符串\n \"\"\"\n pass\n```\n\n### 可用策略实现\n\n| 策略名称 | 用途 | 特点 |\n|----------|------|------|\n| `NoMarkdownGenerationStrategy` | 不生成 Markdown | 返回原始文本或空字符串 |\n| 默认策略 | 标准 HTML 转 Markdown | 支持链接、图片、表格等元素转换 |\n\n## html2text 引擎\n\n`html2text` 是底层的 HTML 到 Markdown 转换引擎，位于 `crawl4ai/html2text/` 目录下。\n\n### 核心组件\n\n#### 1. 配置模块 (config.py)\n\n`config.py` 定义了 HTML 转 Markdown 过程中的各项配置选项：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `ignore_links` | bool | False | 是否忽略链接 |\n| `ignore_images` | bool | False | 是否忽略图片 |\n| `ignore_emphasis` | bool | False | 是否忽略强调样式 |\n| `ignore_blockquotes` | bool | False | 是否忽略引用块 |\n| `ignore_tables` | bool | False | 是否忽略表格 |\n| `single_line_break` | bool | False | 单行换行符处理 |\n| `pad_tables` | bool | False | 表格单元格填充 |\n| `escape_all` | bool | False | 转义所有特殊字符 |\n\n资料来源：[crawl4ai/html2text/config.py:1-100]()\n\n#### 2. 元素处理模块 (elements.py)\n\n`elements.py` 负责定义和处理各种 HTML 元素的 Markdown 转换规则：\n\n| 元素类型 | Markdown 输出格式 | 处理说明 |\n|----------|-------------------|----------|\n| `` - `` | `#` - `######` | 标题行 |\n| `` | `[text](url)` | 超链接 |\n| `![]()
` | `` | 图片 |\n| `` / `` | `**text**` | 粗体 |\n| `` / `` | `*text*` | 斜体 |\n| `` | `` `code` `` | 行内代码 |\n| `` / `` | ```language\\ncode\\n``` | 代码块 |\n| `` | `> text` | 引用块 |\n| `` / `` | `- item` / `1. item` | 列表 |\n| `` | Markdown 表格格式 | 表格转换 |\n| `
` | `---` | 水平线 |\n\n资料来源：[crawl4ai/html2text/elements.py:1-100]()\n\n#### 3. 主模块 (__init__.py)\n\n`__init__.py` 整合了配置和元素处理逻辑，提供完整的 HTML 到 Markdown 转换功能：\n\n```python\nclass Html2Text:\n \"\"\"HTML到Markdown转换器主类\"\"\"\n \n def __init__(self, config: Html2TextConfig = None):\n \"\"\"初始化转换器\n \n 参数:\n config: 配置对象\n \"\"\"\n self.config = config or Html2TextConfig()\n self._setup_handlers()\n \n def handle(self, html: str) -> str:\n \"\"\"处理HTML并返回Markdown\n \n 参数:\n html: 输入的HTML字符串\n \n 返回:\n 转换后的Markdown字符串\n \"\"\"\n pass\n \n def handle_tree(self, tree) -> str:\n \"\"\"处理解析后的HTML树\"\"\"\n pass\n```\n\n资料来源：[crawl4ai/html2text/__init__.py:1-150]()\n\n## 内容过滤策略\n\n`ContentFilterStrategy` 定义了内容过滤接口，用于在 Markdown 生成前对内容进行预处理。\n\n### 过滤策略类型\n\n| 策略 | 作用 | 使用场景 |\n|------|------|----------|\n| `DefaultContentFilter` | 默认过滤策略 | 标准网页抓取 |\n| `AggressiveContentFilter` | 激进过滤 | 去除更多噪音内容 |\n| `LightContentFilter` | 轻量过滤 | 保留更多原始内容 |\n\n### 过滤流程\n\n```mermaid\ngraph TD\n A[HTML 输入] --> B{内容过滤策略}\n B -->|保留标题| C[标题提取]\n B -->|移除脚本| D[脚本移除]\n B -->|移除样式| E[样式移除]\n B -->|移除注释| F[注释移除]\n C --> G[清理后 HTML]\n D --> G\n E --> G\n F --> G\n G --> H[Markdown 生成]\n H --> I[Markdown 输出]\n```\n\n## 使用方法\n\n### 基本用法\n\n```python\nfrom crawl4ai import Crawler\nfrom crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerationStrategy\n\n# 创建爬虫实例\ncrawler = Crawler()\n\n# 配置 Markdown 生成策略\ncrawler.markdown_strategy = DefaultMarkdownGenerationStrategy()\n\n# 执行抓取\nresult = crawler.crawl(\"https://example.com\")\n\n# 获取 Markdown 内容\nmarkdown = result.markdown\n```\n\n### 自定义配置\n\n```python\nfrom crawl4ai.html2text.config import Html2TextConfig\n\n# 创建自定义配置\nconfig = Html2TextConfig(\n ignore_links=False,\n ignore_images=False,\n ignore_tables=False,\n escape_all=False\n)\n\n# 应用配置\nmarkdown_generator = DefaultMarkdownGenerationStrategy(config=config)\n```\n\n### 内容过滤配置\n\n```python\nfrom crawl4ai.content_filter_strategy import DefaultContentFilter\n\n# 配置内容过滤\nfilter_strategy = DefaultContentFilter()\n\n# 在爬取时应用\nresult = crawler.crawl(\n \"https://example.com\",\n content_filter=filter_strategy\n)\n```\n\n## 配置参数详解\n\n### Html2TextConfig 完整参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `body_width` | int | 0 | 文本宽度限制，0表示不限制 |\n| `unicode_snob` | bool | False | 使用 Unicode 字符 |\n| `escape_snob` | bool | False | 转义特殊 Markdown 字符 |\n| `escape_all` | bool | False | 转义所有特殊字符 |\n| `links_each_paragraph` | bool | False | 每个段落处理链接 |\n| `ignore_links` | bool | False | 忽略链接 |\n| `ignore_images` | bool | False | 忽略图片 |\n| `ignore_emphasis` | bool | False | 忽略强调 |\n| `ignore_blockquotes` | bool | False | 忽略引用块 |\n| `ignore_tables` | bool | False | 忽略表格 |\n| `single_line_break` | bool | False | 单行换行 |\n| `pad_tables` | bool | False | 表格填充 |\n| `clickable_lnks` | bool | False | 链接可点击 |\n| `images_to_alt` | bool | False | 图片转 ALT 文本 |\n| `images_to_md` | bool | True | 图片转 Markdown 格式 |\n| `ln_ewscape` | bool | False | 行尾转义 |\n| `md_spoiler` | bool | False | Markdown 隐藏文本 |\n| `wrap` | bool | False | 文本换行 |\n| `wrap_width` | int | 80 | 换行宽度 |\n\n资料来源：[crawl4ai/html2text/config.py:1-100]()\n\n## 数据流与转换过程\n\n### 完整转换流程\n\n```mermaid\ngraph LR\n A[原始 HTML] --> B[HTML 解析]\n B --> C[内容过滤]\n C --> D[DOM 树处理]\n D --> E[元素转换]\n E --> F[Markdown 序列化]\n F --> G[最终 Markdown]\n \n subgraph 内容过滤阶段\n C1[移除脚本标签] --> C2[移除样式标签]\n C2 --> C3[移除注释]\n C3 --> C4[提取主体内容]\n end\n \n subgraph 元素转换\n E1[标题处理] --> E2[链接处理]\n E2 --> E3[图片处理]\n E3 --> E4[表格处理]\n E4 --> E5[列表处理]\n E5 --> E6[代码块处理]\n end\n```\n\n### 关键转换示例\n\n| HTML 输入 | Markdown 输出 |\n|-----------|---------------|\n| `标题
` | `# 标题` |\n| `链接` | `[链接](url)` |\n| `` | `` |\n| `粗体` | `**粗体**` |\n| `代码` | `` `代码` `` |\n| `1
` | `| 1 |` |\n\n## 高级用法\n\n### 自定义元素处理器\n\n```python\nfrom crawl4ai.html2text import Html2Text\nfrom crawl4ai.html2text.config import Html2TextConfig\n\nclass CustomHtml2Text(Html2Text):\n \"\"\"自定义 HTML 转 Markdown 处理器\"\"\"\n \n def handle_tag_h1(self, tag, attrs, start):\n \"\"\"自定义 H1 处理逻辑\"\"\"\n # 自定义处理逻辑\n return f\"## {self.get_text()}\"\n \n def handle_tag_a(self, tag, attrs, start):\n \"\"\"自定义链接处理\"\"\"\n # 自定义链接处理\n pass\n```\n\n### 批量转换\n\n```python\nfrom crawl4ai import Crawler\nfrom crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerationStrategy\n\nurls = [\n \"https://example.com/page1\",\n \"https://example.com/page2\",\n \"https://example.com/page3\"\n]\n\ngenerator = DefaultMarkdownGenerationStrategy()\ncrawler = Crawler()\n\nresults = []\nfor url in urls:\n result = crawler.crawl(url)\n results.append({\n \"url\": url,\n \"markdown\": result.markdown\n })\n```\n\n## 注意事项\n\n### 性能考量\n\n1. **大文档处理**：对于包含大量元素的 HTML 页面，转换过程可能耗时较长\n2. **内存使用**：大型 DOM 树会占用较多内存，建议对超大型页面进行分块处理\n3. **编码处理**：确保输入 HTML 的编码正确，避免乱码问题\n\n### 兼容性说明\n\n| HTML 特性 | 支持状态 | 说明 |\n|-----------|----------|------|\n| HTML5 | ✅ 完全支持 | 支持所有 HTML5 标签 |\n| SVG | ⚠️ 部分支持 | 基本支持，部分复杂 SVG 可能无法正确转换 |\n| MathJax/LaTeX | ⚠️ 需要插件 | 需要额外配置 |\n| 嵌入式视频 | ❌ 不支持 | 会被转换为链接或忽略 |\n\n## 相关文件\n\n| 文件路径 | 描述 |\n|----------|------|\n| `crawl4ai/markdown_generation_strategy.py` | Markdown 生成策略定义与实现 |\n| `crawl4ai/content_filter_strategy.py` | 内容过滤策略定义与实现 |\n| `crawl4ai/html2text/__init__.py` | html2text 主模块 |\n| `crawl4ai/html2text/elements.py` | HTML 元素处理规则 |\n| `crawl4ai/html2text/config.py` | 配置参数定义 |\n\n---\n\n\n\n## 数据提取策略\n\n### 相关页面\n\n相关主题：[分块与过滤策略](#page-chunking-filtering), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/extraction_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/extraction_strategy.py)\n- [crawl4ai/content_scraping_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_scraping_strategy.py)\n- [crawl4ai/table_extraction.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/table_extraction.py)\n- [crawl4ai/crawlers/amazon_product/crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/crawlers/amazon_product/crawler.py)\n- [crawl4ai/crawlers/google_search/crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/crawlers/google_search/crawler.py)\n\n\n# 数据提取策略\n\n## 概述\n\n数据提取策略是 crawl4ai 框架中用于从网页内容中精准提取结构化数据的核心模块。该策略系统设计灵活，支持多种提取方式，涵盖从简单的 CSS 选择器匹配到基于大语言模型（LLM）的智能语义提取。\n\n## 架构设计\n\n### 策略类型体系\n\ncrawl4ai 的数据提取策略采用策略模式（Strategy Pattern）设计，主要包含以下几种策略类型：\n\n```mermaid\ngraph TD\n A[ExtractionStrategy 基类] --> B[NoExtractionStrategy]\n A --> C[BeautifulSoupExtractionStrategy]\n A --> D[LLMExtractionStrategy]\n A --> E[JsonCssExtractionStrategy]\n A --> F[RegexExtractionStrategy]\n \n B --> G[不使用任何提取]\n C --> H[基于 CSS 选择器的结构化提取]\n D --> I[基于 LLM 的语义理解提取]\n E --> J[JSON + CSS 组合提取]\n F --> K[正则表达式模式匹配]\n```\n\n### 核心组件关系\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| ExtractionStrategy | extraction_strategy.py | 策略基类，定义标准化接口 |\n| ContentScrapingStrategy | content_scraping_strategy.py | 内容抓取策略，处理原始内容获取 |\n| TableExtraction | table_extraction.py | 表格数据专项提取 |\n| CrawlerStrategy | 各爬虫子模块 | 具体业务场景的实现 |\n\n## 策略详解\n\n### NoExtractionStrategy\n\n默认策略，不执行任何数据提取操作。适用于只需要获取完整页面内容或 HTML 的场景。\n\n```python\n# 使用示例\nresult = await crawler.crawl(\n url=\"https://example.com\",\n extraction_strategy=NoExtractionStrategy()\n)\n```\n\n### BeautifulSoupExtractionStrategy\n\n基于 BeautifulSoup4 的结构化数据提取策略，通过 CSS 选择器精确定位页面元素。\n\n**配置参数：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| css_selector | str | None | CSS 选择器表达式 |\n| filter_regex | str | None | 内容过滤正则表达式 |\n| check_interval | float | 0.2 | 检查间隔（秒） |\n| timeout | int | 7 | 超时时间（秒） |\n\n### LLMExtractionStrategy\n\n基于大语言模型的智能提取策略，能够理解页面语义并提取非结构化或半结构化数据。\n\n**核心参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|-----|------|\n| prompt | str | 是 | 提取指令提示词 |\n| schema | dict | 否 | 输出数据 schema 定义 |\n| extraction_type | str | 否 | 提取类型标识 |\n\n### JsonCssExtractionStrategy\n\n结合 JSONPath 和 CSS 选择器的混合提取策略，适用于复杂的嵌套数据结构。\n\n### RegexExtractionStrategy\n\n基于正则表达式的文本模式提取策略，适合处理日志、代码片段等结构化文本。\n\n## 内容抓取策略\n\nContentScrapingStrategy 负责处理内容获取阶段的策略配置，主要包含以下抓取模式：\n\n```mermaid\ngraph LR\n A[网页请求] --> B[ScrapingMode 选择]\n B --> C[全量 HTML]\n B --> D[无标签文本]\n B --> E[结构化内容]\n \n C --> F[beautifulsoup 处理]\n D --> G[正则清理]\n E --> H[语义分析]\n```\n\n**支持的抓取模式：**\n\n| 模式名称 | 说明 | 适用场景 |\n|---------|------|---------|\n| html | 完整 HTML 源码 | 需要保留原始标签结构 |\n| text | 纯文本内容 | 文本分析和 NLP 处理 |\n| fit_markdown | Markdown 格式 | 文档转换和内容摘要 |\n|.cleaned | 清理后内容 | 去除脚本和样式噪音 |\n\n## 表格提取机制\n\nTableExtraction 是 crawl4ai 中专门处理 HTML 表格数据提取的模块。\n\n### 提取流程\n\n```mermaid\ngraph TD\n A[定位 table 元素] --> B[识别表头行]\n B --> C[遍历数据行]\n C --> D{是否跨列/跨行?}\n D -->|是| E[处理单元格合并]\n D -->|否| F[直接提取]\n E --> G[构建单元格映射]\n F --> H[转换为列表/字典]\n G --> H\n H --> I[输出 JSON 格式]\n```\n\n### 表格数据结构\n\n提取的表格数据以列表形式返回，每行对应一个字典对象：\n\n```python\n[\n {\"列名1\": \"值1\", \"列名2\": \"值2\"},\n {\"列名1\": \"值3\", \"列名2\": \"值4\"}\n]\n```\n\n## 领域专用爬虫示例\n\n### 亚马逊产品爬虫\n\nAmazon 产品爬虫继承基础提取策略，针对电商页面结构优化：\n\n```python\n# 资料来源：crawl4ai/crawlers/amazon_product/crawler.py\nclass AmazonProductCrawler:\n def __init__(self, extraction_strategy):\n self.strategy = extraction_strategy\n```\n\n### 谷歌搜索爬虫\n\n谷歌搜索爬虫实现特定的搜索结果提取逻辑：\n\n```python\n# 资料来源：crawl4ai/crawlers/google_search/crawler.py\nclass GoogleSearchCrawler:\n async def crawl(self, query: str):\n # 实现搜索结果提取\n```\n\n## 使用最佳实践\n\n### 策略选择指南\n\n| 应用场景 | 推荐策略 | 理由 |\n|---------|---------|-----|\n| 简单表格/列表 | BeautifulSoupExtractionStrategy | 性能高效，精度高 |\n| 语义复杂内容 | LLMExtractionStrategy | 理解能力强 |\n| 结构化日志 | RegexExtractionStrategy | 模式匹配灵活 |\n| 嵌套 JSON | JsonCssExtractionStrategy | 混合查询支持 |\n| 快速原型 | NoExtractionStrategy | 零配置启动 |\n\n### 性能优化建议\n\n1. **优先使用 CSS 选择器**：在数据格式已知的情况下，BeautifulSoup 策略性能优于 LLM 策略\n2. **设置合理的超时时间**：避免大型页面导致的长时间等待\n3. **启用检查间隔**：对于动态加载内容，适当增加 check_interval\n4. **批量提取优化**：多条数据使用同一策略实例，减少初始化开销\n\n## 扩展开发指南\n\n如需创建自定义提取策略，需继承 ExtractionStrategy 基类并实现核心方法：\n\n```python\nfrom crawl4ai.extraction_strategy import ExtractionStrategy\n\nclass CustomExtractionStrategy(ExtractionStrategy):\n async def extract(self, html: str, url: str) -> List[Dict]:\n # 实现自定义提取逻辑\n pass\n```\n\n## 版本兼容性\n\n数据提取策略模块在不同版本间保持接口兼容性，详见项目 CHANGELOG 获取版本特定说明。\n\n---\n\n**相关文档：**\n- [用户指南](../docs/user-guide.md)\n- [API 参考](../api_reference/)\n- [示例代码](../examples/)\n\n---\n\n\n\n## 分块与过滤策略\n\n### 相关页面\n\n相关主题：[数据提取策略](#page-extraction-strategies), [Markdown 生成](#page-markdown-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/chunking_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/chunking_strategy.py)\n- [crawl4ai/content_filter_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/content_filter_strategy.py)\n- [crawl4ai/model_loader.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/model_loader.py)\n- [crawl4ai/prompts.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/prompts.py)\n\n\n# 分块与过滤策略\n\n## 概述\n\n在 Crawl4ai 项目中，**分块策略（Chunking Strategy）** 和 **过滤策略（Content Filter Strategy）** 是两个核心模块，它们共同负责将爬取的网页内容转化为结构化、可处理的文本块。这两个策略在数据处理流程中扮演着至关重要的角色，它们使得大规模网页内容能够被有效地分割、过滤和组织，以满足大语言模型（LLM）训练、知识库构建等应用场景的需求。\n\n分块策略的主要功能是将长文本内容按照预定义的规则（如字符数、句子边界、段落等）分割成较小的、语义相对完整的块（Chunk）。这种分割方式能够确保每个文本块具有足够的上下文信息，同时保持适当的粒度便于后续处理。过滤策略则负责识别并保留最具价值的文本内容，同时去除导航菜单、广告脚本、页脚信息等无用的噪音内容。这两个策略的协同工作形成了 Crawl4ai 内容处理管道的核心环节。\n\n从架构设计的角度来看，分块与过滤策略都遵循了策略模式（Strategy Pattern）的设计原则。这种设计允许用户在运行时动态选择和配置不同的分块或过滤算法，而无需修改核心处理逻辑。每个策略都实现了统一的接口定义，确保了模块之间的松耦合和高度可扩展性。这种灵活性使得 Crawl4ai 能够适应各种不同的内容处理场景和需求变化。\n\n## 分块策略详解\n\n### 工作原理\n\n分块策略的核心目标是将输入的文本内容按照特定规则进行分割，生成一系列语义相对完整的文本块。在实现层面，分块策略首先会对输入文本进行分析，识别出文本的内在结构（如句子、段落、标题等），然后根据预定义的参数（如最大块大小、重叠大小等）将文本切分为多个块。每个块都包含了一定量的上下文信息，同时保持相对独立的语义完整性。\n\n分块过程通常遵循以下基本流程：首先，策略会接收原始文本内容和相关配置参数；然后，对文本进行预处理，包括清理格式、识别结构等；接着，根据选定的分块算法执行分割操作；最后，对生成的块进行后处理，包括清理空块、合并过小的块等。整个过程旨在最大化每个块的实用价值，同时最小化信息丢失和上下文割裂。\n\n### 配置参数\n\n分块策略的行为可以通过多个参数进行精细控制，这些参数决定了分块的大小、重叠方式以及边界处理逻辑。以下是主要的配置选项：\n\n| 参数名称 | 类型 | 默认值 | 说明 |\n|---------|------|--------|------|\n| chunk_word_count | int | 1024 | 每个块的近似单词数目标值 |\n| overlap | int | 100 | 块之间的重叠单词数 |\n| overlap_all_sections | bool | False | 是否在所有章节间应用重叠 |\n| combine_sentences | bool | False | 是否将短句合并为完整段落 |\n| max_characters_per_section | int | 1500 | 每个章节的最大字符数 |\n| overlap_rate | float | 0.1 | 重叠率，overlap_rate * chunk_word_count |\n| extra_system_prompt | str | \"\" | 额外的系统提示词 |\n| user_prompt | str | \"\" | 用户自定义提示词模板 |\n\n这些参数可以根据具体的应用场景进行调整。例如，当需要较短的块用于精确检索时，可以减小 `chunk_word_count` 的值；当需要保留更多上下文信息时，可以增加 `overlap` 或 `overlap_rate` 的值以实现块之间的信息重叠。`overlap_all_sections` 参数特别有用，因为它确保了跨章节边界的语义连贯性。\n\n### 分块算法实现\n\n在具体实现层面，Crawl4ai 提供了多种分块算法的实现。以基于字数的分块为例，该算法会遍历文本内容，累积单词直到达到目标块大小，然后在该位置附近（通常在句子边界处）进行截断，生成一个新的块。这种方法简单高效，适用于大多数场景。\n\n对于更复杂的场景，系统还支持基于语义的分块方法。这种方法会结合自然语言处理技术，识别文本中的语义边界（如主题转换点），并在这些位置进行分割。语义分块能够产生更加连贯、信息密度更高的文本块，但计算成本也相对较高。算法实现中会调用语言模型来辅助判断语义边界，这部分功能与 `model_loader.py` 中定义的模型加载机制紧密相关。\n\n```mermaid\ngraph TD\n A[原始文本输入] --> B[文本预处理]\n B --> C[结构识别]\n C --> D{分块算法选择}\n D -->|字数分块| E[按字数累积]\n D -->|语义分块| F[语义边界分析]\n E --> G[句子边界截断]\n F --> G\n G --> H[生成文本块]\n H --> I[重叠处理]\n I --> J[块后处理]\n J --> K[输出块列表]\n```\n\n### 自定义分块策略\n\nCrawl4ai 的架构设计允许开发者实现自定义的分块策略。要创建自定义策略，需要继承基础的分块策略类并实现核心的 `chunk()` 方法。方法签名通常接受原始文本内容和可选的配置参数，返回一个文本块列表。这种设计使得系统具有极强的扩展性，能够适应各种特殊的内容处理需求。\n\n自定义策略的实现需要考虑多个方面：首先是分块逻辑的准确性，确保生成的块符合预期的格式和质量标准；其次是性能优化，特别是处理大规模文本时需要考虑计算效率；最后是错误处理机制，需要妥善处理各种异常情况如空文本、格式错误等。通过继承和扩展基础类，开发者可以专注于实现特定的分块逻辑，而无需关心与其他模块的集成细节。\n\n## 过滤策略详解\n\n### 目的与作用\n\n内容过滤策略的主要目的是从爬取的网页内容中识别并提取高价值的文本信息，同时过滤掉导航菜单、页脚、版权声明、广告脚本等无意义的内容。这一步骤对于后续的内容处理至关重要，因为它直接影响到生成的知识库的纯净度和可用性。一个设计良好的过滤策略能够显著提升内容的信号噪声比，使得检索和问答等下游任务能够获得更准确的结果。\n\n过滤策略的实现通常依赖于启发式规则和机器学习模型的结合。在传统方法中，系统会基于 HTML 标签类型、CSS 类名、元素位置等特征来判断内容的价值。例如，包含 \"nav\"、\"footer\"、\"sidebar\"、\"advertisement\" 等关键词的元素通常会被标记为低价值内容。在更高级的实现中，系统还会结合语言模型来理解内容的语义，进一步提升过滤的准确性。\n\n### 过滤机制\n\n过滤机制的实现涉及多个层次的判断逻辑。在最基础的层面，系统会基于 HTML 结构特征进行粗过滤，识别并排除明显无用的内容块。这包括脚本标签、样式标签、隐藏元素、以及某些特定的 HTML 标签类型。通过分析元素的可见性、大小、位置等属性，系统可以快速排除大量低价值内容。\n\n在更精细的层面，过滤策略会结合文本内容的语义分析。这部分功能与 `prompts.py` 中定义的提示词模板紧密相关。系统会使用特定的提示词引导语言模型对内容块进行价值评估，判断其是否包含实质性的信息内容。评估结果会被用于决定是否保留该内容块，或者将其标记为需要进一步处理或直接过滤。\n\n```mermaid\ngraph TD\n A[网页内容输入] --> B[HTML结构分析]\n B --> C[标签类型过滤]\n C --> D[可见性检查]\n D --> E[语义分析]\n E --> F{价值评估}\n F -->|高价值| G[保留内容]\n F -->|低价值| H[过滤内容]\n F -->|不确定| I[模型辅助判断]\n I --> G\n I --> H\n```\n\n### 过滤策略类型\n\nCrawl4ai 提供了多种预定义的过滤策略，以适应不同的内容处理需求。这些策略包括基于规则的方法、基于统计的方法和基于深度学习的方法。每种策略都有其特定的优势和适用场景，用户可以根据实际需求选择最合适的策略类型。\n\n**关键词过滤策略** 是最基础的方法，它通过预定义的关键词列表来识别和过滤无价值内容。这种方法简单高效，但可能无法处理所有变体和无规律的噪音内容。**正则表达式过滤策略** 提供了更灵活的模式匹配能力，能够处理更复杂的过滤规则。**基于模型的质量过滤策略** 则利用机器学习模型来评估内容的价值，能够捕捉更深层次的语义特征。\n\n| 策略类型 | 优点 | 缺点 | 适用场景 |\n|---------|------|------|---------|\n| 关键词过滤 | 速度快、简单易用 | 准确性有限 | 快速处理、结构化内容 |\n| 正则过滤 | 灵活性高、可定制 | 需要手动编写规则 | 特定格式内容 |\n| 模型过滤 | 准确性高、适应性强 | 计算成本较高 | 高质量需求场景 |\n| 混合过滤 | 综合多种方法优势 | 配置复杂 | 通用场景 |\n\n## 与模型加载器的集成\n\n### 模型加载机制\n\n分块和过滤策略的执行往往需要语言模型的参与。`model_loader.py` 模块提供了统一的模型加载和管理接口，使得策略能够便捷地访问语言模型能力。这个模块封装了模型初始化、配置管理、推理调用等核心功能，为上层策略提供了一个简洁而强大的模型访问层。\n\n模型加载器支持多种模型类型和部署方式，包括本地模型和云端 API。配置参数允许用户指定模型的类型、版本、API 密钥等必要信息。加载器会自动处理模型缓存、多实例管理、请求批处理等底层细节，使得策略实现者能够专注于业务逻辑而无需关心模型调用的基础设施问题。\n\n### 在策略中的应用\n\n在分块策略中，模型主要被用于语义分块和质量评估。当启用语义分块模式时，系统会调用模型来分析文本的语义结构，识别主题转换点和最佳分割位置。在过滤策略中，模型被用于深度内容理解，评估文本块的语义价值和相关性。这些应用都需要模型加载器提供稳定可靠的模型访问服务。\n\n模型的使用涉及性能优化和成本控制两个关键考量。在性能方面，系统实现了请求批处理、模型缓存、推理结果缓存等优化机制，以减少重复计算和 API 调用延迟。在成本方面，系统支持多种模型选择，从高性能高成本的模型到轻量级低成本模型的梯度配置，用户可以根据需求权衡效果和成本。\n\n## 提示词集成\n\n### 提示词模板\n\n`prompts.py` 模块定义了分块和过滤策略使用的各种提示词模板。这些模板经过精心设计，能够有效地引导语言模型执行内容分析、价值评估、语义分割等任务。提示词的质量直接影响策略的执行效果，因此模板的设计和优化是策略开发的重要环节。\n\n提示词模板采用结构化设计，包含系统提示和用户提示两个部分。系统提示定义了模型的角色定位和基本行为准则，用户提示则包含了具体的任务描述和输入内容。这种设计使得提示词具有良好的可读性和可维护性，同时也方便根据不同场景进行定制和优化。\n\n### 自定义提示词\n\n用户可以通过配置参数自定义提示词内容，以适应特定的内容处理需求。例如，`extra_system_prompt` 参数允许在系统提示中添加额外的指令，`user_prompt` 参数允许用户自定义用户提示的模板结构。这种灵活性使得系统能够适应各种特殊的内容处理场景和领域需求。\n\n自定义提示词时需要注意几个关键要点：首先是提示词的清晰性和具体性，模糊的指令可能导致模型产生不一致的结果；其次是提示词的长度和复杂性，过长的提示词可能增加处理成本和延迟；最后是提示词的格式兼容性，确保自定义提示词与系统其他部分能够良好集成。\n\n## 实际应用示例\n\n### 基本使用流程\n\n在实际应用中，分块和过滤策略通常作为数据处理管道的一环被调用。用户首先配置所需的策略参数，然后调用执行方法处理输入内容。整个过程是自动化的，用户只需关注输入输出的管理。以下是一个典型的使用场景：\n\n```python\nfrom crawl4ai import ChunkingStrategy, ContentFilterStrategy\n\n# 配置分块策略\nchunking_strategy = ChunkingStrategy(\n chunk_word_count=512,\n overlap=50,\n overlap_all_sections=True\n)\n\n# 配置过滤策略\nfilter_strategy = ContentFilterStrategy(\n model=\"gpt-4\",\n filter_type=\"semantic\"\n)\n\n# 执行处理\ncontent = \"待处理的网页文本内容...\"\nchunks = chunking_strategy.chunk(content)\nfiltered_chunks = filter_strategy.filter(chunks)\n```\n\n### 最佳实践建议\n\n在实际使用中，有几个关键的优化建议值得关注。首先是分块大小的选择，需要根据下游任务的需求进行权衡：较小的块适合精确检索，但可能缺乏足够的上下文；较大的块包含更丰富的上下文，但可能引入噪音。其次是重叠参数的设置，适当的重叠能够保证跨块边界的语义连续性，特别是在涉及长程依赖的任务中。\n\n过滤策略的选择和配置同样需要根据具体场景进行调整。对于新闻类内容，可以侧重于正文提取和标题识别；对于论坛讨论类内容，则需要更智能的噪音过滤以排除签名档和重复引用。对于包含大量代码的项目文档，还需要特别注意代码块的识别和保留，避免被误过滤。\n\n## 技术规格总结\n\n| 组件 | 位置 | 主要功能 | 可扩展性 |\n|------|------|---------|---------|\n| ChunkingStrategy | chunking_strategy.py | 文本分块处理 | 支持自定义实现 |\n| ContentFilterStrategy | content_filter_strategy.py | 内容质量过滤 | 支持多种过滤模式 |\n| ModelLoader | model_loader.py | 模型访问管理 | 支持多种模型类型 |\n| PromptManager | prompts.py | 提示词管理 | 支持自定义模板 |\n\n分块与过滤策略作为 Crawl4ai 的核心组件，共同构成了网页内容智能处理的基础设施。通过合理配置和使用这些策略，用户可以实现高效、准确的大规模网页内容处理，为各种下游任务提供高质量的数据支持。系统的模块化设计确保了良好的可维护性和可扩展性，使得用户能够根据实际需求进行灵活定制和优化。\n\n---\n\n\n\n## 浏览器配置与代理\n\n### 相关页面\n\n相关主题：[高级功能](#page-advanced-features), [异步网页爬虫核心](#page-async-webcrawler)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/browser_manager.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_manager.py)\n- [crawl4ai/browser_adapter.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_adapter.py)\n- [crawl4ai/browser_profiler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_profiler.py)\n- [crawl4ai/proxy_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/proxy_strategy.py)\n- [crawl4ai/ssl_certificate.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/ssl_certificate.py)\n- [crawl4ai/user_agent_generator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/user_agent_generator.py)\n\n\n# 浏览器配置与代理\n\n## 概述\n\n浏览器配置与代理模块是 crawl4ai 框架中负责管理浏览器实例配置、代理设置、SSL证书处理以及用户代理字符串生成的核心组件。该模块提供了灵活的浏览器定制能力，使爬虫能够适应不同的目标网站环境，包括需要身份验证、SSL证书处理、代理跳转等复杂场景。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[BrowserConfig] --> B[BrowserManager]\n A --> C[BrowserAdapter]\n A --> D[BrowserProfiler]\n E[ProxyStrategy] --> B\n F[SSLConfig] --> B\n G[UserAgentGenerator] --> B\n B --> H[Playwright Browser]\n C --> I[BrowserController]\n D --> J[BrowserPool]\n```\n\n## 核心组件\n\n### BrowserManager\n\nBrowserManager 是浏览器管理的核心类，负责浏览器的生命周期管理、实例化、配置应用和资源清理。\n\n```mermaid\ngraph LR\n A[创建配置] --> B[初始化浏览器]\n B --> C[应用代理]\n C --> D[设置SSL]\n D --> E[生成User-Agent]\n E --> F[浏览器就绪]\n F --> G[执行爬取]\n G --> H[资源释放]\n```\n\n**主要职责：**\n- 管理浏览器实例的创建和销毁\n- 配置浏览器启动参数\n- 应用代理和SSL设置\n- 处理浏览器上下文隔离\n\n**配置参数表：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| headless | bool | True | 是否无头模式运行 |\n| browser_type | str | \"chromium\" | 浏览器类型（chromium/firefox/webkit） |\n| proxy_config | ProxyConfig | None | 代理配置对象 |\n| ssl_config | SSLConfig | None | SSL证书配置 |\n| user_agent | str | None | 自定义User-Agent |\n| viewport | dict | {\"width\": 1920, \"height\": 1080} | 视口大小 |\n| args | list | [] | 额外的浏览器启动参数 |\n| ignoreHTTPSErrors | bool | False | 是否忽略HTTPS错误 |\n| java_script_enabled | bool | True | 是否启用JavaScript |\n\n资料来源：[browser_manager.py:1-100]()\n\n### BrowserAdapter\n\nBrowserAdapter 提供了浏览器操作的高级抽象接口，封装了常见的浏览器交互操作。\n\n**核心功能：**\n- 页面导航和导航控制\n- 元素选择和交互\n- 截图和PDF生成\n- 控制台日志捕获\n- 网络请求拦截\n\n```python\nclass BrowserAdapter:\n def __init__(self, config: BrowserConfig):\n self.config = config\n self.browser = None\n self.context = None\n self.page = None\n```\n\n资料来源：[browser_adapter.py:1-50]()\n\n### BrowserProfiler\n\nBrowserProfiler 用于浏览器性能分析和会话追踪，帮助诊断浏览器行为和性能问题。\n\n**功能特性：**\n- 记录浏览器启动时间\n- 追踪页面加载性能\n- 统计资源使用情况\n- 生成性能报告\n\n```mermaid\ngraph TD\n A[开始分析] --> B[捕获事件]\n B --> C{事件类型}\n C --> D[性能指标]\n C --> E[资源加载]\n C --> F[控制台日志]\n D --> G[生成报告]\n E --> G\n F --> G\n```\n\n资料来源：[browser_profiler.py:1-80]()\n\n## 代理配置\n\n### ProxyConfig 数据模型\n\n```python\nclass ProxyConfig:\n server: str # 代理服务器地址，格式: protocol://host:port\n username: str # 认证用户名（可选）\n password: str # 认证密码（可选）\n bypass_list: list # 绕过代理的地址列表（可选）\n```\n\n**支持的代理协议：**\n\n| 协议 | 格式示例 | 支持情况 |\n|------|----------|----------|\n| HTTP | http://proxy.example.com:8080 | ✅ 完全支持 |\n| HTTPS | https://proxy.example.com:8080 | ✅ 完全支持 |\n| SOCKS4 | socks4://proxy.example.com:1080 | ✅ 完全支持 |\n| SOCKS5 | socks5://proxy.example.com:1080 | ✅ 完全支持 |\n\n### ProxyStrategy\n\nProxyStrategy 实现了多种代理策略，支持自动代理切换和负载均衡。\n\n```mermaid\ngraph TD\n A[请求发起] --> B{代理策略选择}\n B --> C[轮询策略]\n B --> D[随机策略]\n B --> E[故障转移策略]\n C --> F[选择代理]\n D --> F\n E --> F\n F --> G[应用代理]\n G --> H{请求结果}\n H -->|成功| I[记录成功]\n H -->|失败| J[重试或切换]\n J --> F\n```\n\n**代理策略类型：**\n\n| 策略名称 | 说明 | 适用场景 |\n|----------|------|----------|\n| RoundRobinStrategy | 轮询策略，依次使用每个代理 | 负载均衡 |\n| RandomStrategy | 随机选择代理 | 避免请求模式被检测 |\n| FailoverStrategy | 故障转移，主代理失败时切换 | 高可用性 |\n| PriorityStrategy | 按优先级顺序尝试 | 优先使用高速代理 |\n\n资料来源：[proxy_strategy.py:1-120]()\n\n### 代理配置示例\n\n```python\nfrom crawl4ai import BrowserConfig, ProxyConfig\n\n# 简单代理配置\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\"\n)\n\n# 带认证的代理配置\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\",\n username=\"user123\",\n password=\"pass456\"\n)\n\n# 配置绕过列表\nproxy_config = ProxyConfig(\n server=\"http://proxy.example.com:8080\",\n bypass_list=[\"localhost\", \"*.internal\"]\n)\n\nbrowser_config = BrowserConfig(\n proxy_config=proxy_config,\n headless=True\n)\n```\n\n## SSL 证书处理\n\n### SSLConfig 数据模型\n\n```python\nclass SSLConfig:\n ignore_ssl_errors: bool # 是否忽略SSL错误\n client_cert: str # 客户端证书路径\n client_key: str # 客户端私钥路径\n ca_cert: str # CA证书路径\n```\n\n**配置参数表：**\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| ignore_ssl_errors | bool | False | 忽略证书验证错误 |\n| client_cert | str | None | PEM格式客户端证书路径 |\n| client_key | str | None | PEM格式私钥路径 |\n| ca_cert | str | None | CA证书文件路径 |\n| accept_insecure_certs | bool | False | 接受无效证书 |\n\n资料来源：[ssl_certificate.py:1-60]()\n\n### 使用场景\n\n**场景一：忽略证书错误**\n\n适用于测试环境或内部网络：\n\n```python\nssl_config = SSLConfig(ignore_ssl_errors=True)\nbrowser_config = BrowserConfig(ssl_config=ssl_config)\n```\n\n**场景二：使用客户端证书**\n\n适用于需要双向SSL认证的场景：\n\n```python\nssl_config = SSLConfig(\n client_cert=\"/path/to/cert.pem\",\n client_key=\"/path/to/key.pem\",\n ca_cert=\"/path/to/ca.pem\"\n)\nbrowser_config = BrowserConfig(ssl_config=ssl_config)\n```\n\n## 用户代理管理\n\n### UserAgentGenerator\n\nUserAgentGenerator 负责生成和管理用户代理字符串，支持多种配置选项。\n\n```mermaid\ngraph TD\n A[UA生成请求] --> B{生成模式}\n B --> C[固定UA]\n B --> D[随机UA]\n B --> E[真实浏览器UA]\n C --> F[返回UA字符串]\n D --> G[选择设备类型]\n G --> F\n E --> H[模拟真实环境]\n H --> F\n```\n\n**生成模式：**\n\n| 模式 | 说明 | 示例 |\n|------|------|------|\n| fixed | 使用指定的固定UA | \"Mozilla/5.0...\" |\n| random | 从预设列表随机选择 | 随机桌面浏览器UA |\n| real_browser | 模拟真实浏览器环境 | Chrome on Windows |\n| mobile | 移动设备UA | iPhone Safari |\n\n资料来源：[user_agent_generator.py:1-90]()\n\n### 预设浏览器类型\n\n| 浏览器 | 平台 | User-Agent 示例 |\n|--------|------|------------------|\n| Chrome | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 |\n| Chrome | macOS | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 |\n| Chrome | Linux | Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 |\n| Firefox | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 |\n| Safari | iOS | Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) |\n| Edge | Windows | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/115.0.0.0 |\n\n### 使用示例\n\n```python\nfrom crawl4ai import BrowserConfig, UserAgentGenerator\n\n# 使用随机UA\nua_generator = UserAgentGenerator(mode=\"random\")\nbrowser_config = BrowserConfig(\n user_agent=ua_generator.generate()\n)\n\n# 使用固定UA\nbrowser_config = BrowserConfig(\n user_agent=\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36\"\n)\n\n# 使用真实浏览器模拟\nua_generator = UserAgentGenerator(mode=\"real_browser\")\nbrowser_config = BrowserConfig(\n user_agent=ua_generator.generate(device_type=\"mobile\")\n)\n```\n\n## 浏览器配置工作流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant BM as BrowserManager\n participant PA as ProxyAdapter\n participant SS as SSLHandler\n participant UA as UserAgentGenerator\n participant Browser as Playwright Browser\n\n User->>BM: 创建BrowserConfig\n BM->>UA: 请求User-Agent\n UA-->>BM: 返回UA字符串\n BM->>PA: 应用代理配置\n PA->>BM: 代理配置完成\n BM->>SS: 配置SSL设置\n SS-->>BM: SSL配置完成\n BM->>Browser: 启动浏览器实例\n Browser-->>BM: 浏览器就绪\n BM-->>User: 返回配置好的浏览器\n```\n\n## 高级配置选项\n\n### 浏览器启动参数\n\n```python\nbrowser_config = BrowserConfig(\n args=[\n \"--disable-blink-features=AutomationControlled\",\n \"--disable-dev-shm-usage\",\n \"--no-sandbox\",\n \"--disable-setuid-sandbox\",\n \"--disable-gpu\",\n \"--disable-web-security\",\n \"--disable-features=IsolateOrigins,site-per-process\"\n ]\n)\n```\n\n**常用启动参数表：**\n\n| 参数 | 说明 | 风险等级 |\n|------|------|----------|\n| --disable-blink-features=AutomationControlled | 隐藏自动化特征 | 低 |\n| --disable-dev-shm-usage | 避免共享内存问题 | 低 |\n| --no-sandbox | 禁用沙箱（Docker环境需要） | 高 |\n| --disable-setuid-sandbox | 禁用setuid沙箱 | 中 |\n| --disable-gpu | 禁用GPU加速 | 低 |\n| --disable-web-security | 禁用Web安全 | 高 |\n| --headless=new | 使用新版无头模式 | 低 |\n\n### 上下文隔离配置\n\n```python\nbrowser_config = BrowserConfig(\n context_options={\n \"locale\": \"zh-CN\",\n \"timezone_id\": \"Asia/Shanghai\",\n \"viewport\": {\"width\": 1920, \"height\": 1080},\n \"color_scheme\": \"dark\",\n \"extra_http_headers\": {\n \"Accept-Language\": \"zh-CN,zh;q=0.9\",\n \"Accept-Encoding\": \"gzip, deflate, br\"\n }\n }\n)\n```\n\n## 最佳实践\n\n### 配置优先级\n\n1. **安全优先**：在生产环境中禁用 `--disable-web-security`\n2. **性能优化**：合理设置视口大小，避免不必要的大图渲染\n3. **稳定性**：在Docker环境中添加 `--no-sandbox` 和 `--disable-dev-shm-usage`\n4. **反检测**：结合使用随机UA、真实视口和代理\n\n### 配置验证清单\n\n- [ ] 确认代理服务器可达性\n- [ ] 验证SSL证书配置正确\n- [ ] 测试UA字符串有效性\n- [ ] 检查浏览器参数兼容性\n- [ ] 验证上下文配置生效\n\n## 相关文件\n\n| 文件路径 | 功能描述 |\n|----------|----------|\n| [browser_manager.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_manager.py) | 浏览器生命周期管理 |\n| [browser_adapter.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_adapter.py) | 浏览器操作接口抽象 |\n| [browser_profiler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/browser_profiler.py) | 性能分析和追踪 |\n| [proxy_strategy.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/proxy_strategy.py) | 代理策略实现 |\n| [ssl_certificate.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/ssl_certificate.py) | SSL证书处理 |\n| [user_agent_generator.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/user_agent_generator.py) | User-Agent生成管理 |\n\n---\n\n\n\n## 高级功能\n\n### 相关页面\n\n相关主题：[浏览器配置与代理](#page-browser-config), [数据提取策略](#page-extraction-strategies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crawl4ai/antibot_detector.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/antibot_detector.py)\n- [crawl4ai/adaptive_crawler.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/adaptive_crawler.py)\n- [crawl4ai/js_snippet/__init__.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/js_snippet/__init__.py)\n- [crawl4ai/link_preview.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/link_preview.py)\n- [crawl4ai/async_dispatcher.py](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_dispatcher.py)\n\n\n# 高级功能\n\n## 概述\n\ncrawl4ai的高级功能模块提供了企业级网页爬取的增强能力，包括反机器人检测规避、自适应爬取策略、JavaScript动态内容注入、链接预览生成以及异步并发调度等核心功能。这些模块协同工作，使爬虫能够应对复杂的网络环境和严格的反爬机制，同时保持高效的资源利用率。\n\n## 架构总览\n\n```mermaid\ngraph TD\n A[用户请求] --> B[async_dispatcher 异步调度器]\n B --> C[adaptive_crawler 自适应爬虫]\n C --> D[antibot_detector 反机器人检测]\n C --> E[js_snippet JavaScript注入]\n E --> F[动态内容渲染]\n D --> G{检测结果}\n G -->|通过| F\n G -->|触发| H[策略调整]\n H --> C\n F --> I[link_preview 链接预览生成]\n I --> J[结果输出]\n```\n\n## 反机器人检测模块\n\n### 功能定位\n\n`antibot_detector` 模块负责检测目标网站是否部署了反机器人机制，并提供相应的规避建议。该模块通过分析响应特征、Cookie行为、JavaScript挑战等信号来判断当前爬取是否触发了反爬防护。\n\n### 核心检测机制\n\n| 检测类型 | 描述 | 判定依据 |\n|---------|------|----------|\n| 指纹检测 | 识别浏览器指纹特征缺失 | User-Agent、Canvas、WebGL |\n| 行为检测 | 分析异常访问模式 | 请求频率、访问路径 |\n| JavaScript挑战 | 检测JS质询页面 | 验证码、Cookie重置 |\n| 蜜罐检测 | 识别隐藏链接陷阱 | CSS隐藏元素、点击诱饵 |\n\n### 集成方式\n\n该模块与自适应爬虫深度集成，当检测到反机器人信号时，会自动触发爬取策略的动态调整流程。\n\n资料来源：[crawl4ai/antibot_detector.py:1-50](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/antibot_detector.py)\n\n## 自适应爬虫\n\n### 设计理念\n\n`adaptive_crawler` 模块实现了智能化的爬取策略调整机制，能够根据目标网站的响应特征自动优化爬取参数。这种自适应能力使系统能够在不同网站环境中保持稳定的爬取效率。\n\n### 核心参数配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|--------|------|\n| `max_retries` | int | 3 | 最大重试次数 |\n| `retry_delay` | float | 1.0 | 重试间隔（秒） |\n| `timeout` | int | 30 | 请求超时时间 |\n| `use_cache` | bool | True | 启用缓存机制 |\n\n### 策略调整流程\n\n```mermaid\ngraph LR\n A[发起请求] --> B{响应状态}\n B -->|200| C[成功解析]\n B -->|429| D[触发限流]\n B -->|403| E[反爬拦截]\n B -->|5xx| F[服务器错误]\n D --> G[增加延迟]\n E --> H[启用JS渲染]\n F --> I[指数退避]\n G --> A\n H --> C\n I --> A\n```\n\n### 动态适应策略\n\n自适应爬虫支持以下策略模式：\n\n1. **保守模式**：优先降低触发反爬的概率，牺牲部分爬取速度\n2. **平衡模式**：在速度和成功率之间取得平衡\n3. **激进模式**：最大化爬取速度，适用于已知友好的网站\n\n资料来源：[crawl4ai/adaptive_crawler.py:1-80](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/adaptive_crawler.py)\n\n## JavaScript 代码注入\n\n### 模块职责\n\n`js_snippet` 模块提供了在页面加载后执行自定义JavaScript代码的能力，这对于处理单页应用（SPA）和需要客户端渲染的内容至关重要。该模块支持注入预定义的代码片段以及用户自定义的JavaScript逻辑。\n\n### 预定义代码片段\n\n| 片段名称 | 用途 | 典型场景 |\n|---------|------|----------|\n| `scroll_to_bottom` | 滚动至页面底部 | 触发懒加载内容 |\n| `extract_dynamic_content` | 提取动态渲染内容 | 获取JS生成的数据 |\n| `wait_for_element` | 等待特定元素加载 | 确保关键内容就绪 |\n| `simulate_human_behavior` | 模拟人类行为 | 降低被检测概率 |\n\n### 执行上下文\n\nJavaScript代码在浏览器上下文中执行，可以访问和操作DOM、发起AJAX请求、修改页面状态等。该功能基于Playwright的页面评估机制实现。\n\n资料来源：[crawl4ai/js_snippet/__init__.py:1-30](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/js_snippet/__init__.py)\n\n## 链接预览生成\n\n### 功能概述\n\n`link_preview` 模块负责生成网页的链接预览信息，包括标题、描述、图片和元数据等。该功能对于构建URL目录、sitemap生成、内容索引等场景非常有用。\n\n### 预览数据结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `title` | string | 页面标题 |\n| `description` | string | meta描述内容 |\n| `image` | string | OG/Twitter图片URL |\n| `favicon` | string | 网站图标 |\n| `domain` | string | 域名提取 |\n| `language` | string | 页面语言 |\n\n### 生成流程\n\n```mermaid\ngraph TD\n A[获取页面HTML] --> B[解析Meta标签]\n B --> C[提取OG属性]\n C --> D[获取Favicon]\n D --> E[生成预览对象]\n E --> F[缓存结果]\n```\n\n资料来源：[crawl4ai/link_preview.py:1-60](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/link_preview.py)\n\n## 异步调度器\n\n### 设计目标\n\n`async_dispatcher` 模块实现了高效的异步任务调度系统，支持并发控制、优先级管理、任务去重等企业级特性。该模块基于Python的asyncio框架构建，能够充分利用系统资源提升整体吞吐量。\n\n### 核心功能\n\n| 功能 | 描述 |\n|-----|------|\n| 并发限制 | 限制同时进行的爬取任务数量 |\n| 任务队列 | 支持优先级排序的任务队列 |\n| 失败重试 | 自动化失败任务重试机制 |\n| 速率控制 | 防止对目标网站造成过大压力 |\n\n### 调度策略\n\n异步调度器支持多种任务调度策略：\n\n1. **FIFO（先进先出）**：按提交顺序处理任务\n2. **优先级调度**：高优先级任务优先处理\n3. **批量处理**：聚合多个相似请求减少开销\n\n### 并发控制机制\n\n```mermaid\ngraph TD\n A[任务提交] --> B{检查并发数}\n B -->|未达上限| C[立即执行]\n B -->|已达上限| D[加入等待队列]\n C --> E[任务完成]\n D --> F[等待释放]\n F --> B\n E --> G[更新统计]\n G --> H{队列非空?}\n H -->|是| B\n```\n\n资料来源：[crawl4ai/async_dispatcher.py:1-100](https://github.com/unclecode/crawl4ai/blob/main/crawl4ai/async_dispatcher.py)\n\n## 模块协作流程\n\n### 完整爬取工作流\n\n```mermaid\ngraph TD\n A[用户请求] --> B[async_dispatcher 接收任务]\n B --> C[adaptive_crawler 创建爬取任务]\n C --> D{antibot_detector 预检}\n D -->|安全| E[执行爬取]\n D -->|风险| F[应用规避策略]\n F --> E\n E --> G{需要JS渲染?}\n G -->|是| H[js_snippet 注入脚本]\n H --> I[等待渲染完成]\n G -->|否| J[直接提取内容]\n I --> J\n J --> K[link_preview 生成预览]\n K --> L[结果汇总]\n L --> M[返回用户]\n```\n\n### 错误处理与恢复\n\n各模块均实现了完善的错误处理机制，当某个环节出现异常时，系统会自动触发降级策略或重试流程，确保整体任务的可靠性。\n\n## 配置建议\n\n### 生产环境推荐配置\n\n```python\n{\n \"adaptive_crawler\": {\n \"max_retries\": 5,\n \"timeout\": 45,\n \"use_cache\": True\n },\n \"async_dispatcher\": {\n \"max_concurrent\": 10,\n \"rate_limit\": 30 # 每分钟请求数\n },\n \"antibot_detector\": {\n \"strict_mode\": False,\n \"auto_adjust\": True\n }\n}\n```\n\n### 性能优化要点\n\n1. **合理设置并发数**：根据目标网站的承受能力调整\n2. **启用缓存**：减少重复请求，提升效率\n3. **适当延迟**：避免触发频率限制\n4. **监控日志**：及时发现和处理异常情况\n\n## 相关资源\n\n- 基础使用文档：查看项目主README\n- API参考：查看各模块具体实现\n- 示例代码：参考项目中的example目录\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：unclecode/crawl4ai\n\n摘要：发现 21 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing。\n\n## 1. 安装坑 · 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: arun() and arun_many() type hinting needs fixing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d3b6cfd3700147f690e0e65875f15424 | https://github.com/unclecode/crawl4ai/issues/1898 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason is shown\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad61b108bf894cc286ca7966e8c86758 | https://github.com/unclecode/crawl4ai/issues/1949 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ee99f5d72f143f4b064732cc19e0c85 | https://github.com/unclecode/crawl4ai/issues/1963 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7fa967632a948008efbc182d1f2c96b | https://github.com/unclecode/crawl4ai/issues/1938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e9fbf659fbb40aba437886a87f8e2d7 | https://github.com/unclecode/crawl4ai/issues/1962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af29278fd7294d4a8f0f6f37ab987b5c | https://github.com/unclecode/crawl4ai/issues/1968 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_97d44cedb21a4908a7743fde11209954 | https://github.com/unclecode/crawl4ai/issues/1950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ae45861377894b99a57d6bbdc06af313 | https://github.com/unclecode/crawl4ai/issues/1959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.1:Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.1:Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ae9133fff54443b712725f51769fa1 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：v0.7.2: CI/CD & Dependency Optimization Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.2: CI/CD & Dependency Optimization Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14954e0431ca426ebeaa4bb31778d4af | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 来源证据：[Bug]: Markdown export loses heading hierarchy and table structure\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Markdown export loses heading hierarchy and table structure\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c3eac8ab81e34bf3b6cc050f7f8e9826 | https://github.com/unclecode/crawl4ai/issues/1964 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:798201435 | https://github.com/unclecode/crawl4ai | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：Release v0.7.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.3\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e2b75670cbcc4814a86423818b9f6f48 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：Release v0.7.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.5\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_056d1470d7534cacb39eeb894e054496 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Release v0.7.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.7\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e157445f88744795b5c6234783eca692 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：[Bug]: Markdown text extraction drops text when element contains empty elements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Markdown text extraction drops text when element contains empty elements\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dffa926853d147ebb487a03fdfd1818e | https://github.com/unclecode/crawl4ai/issues/1966 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：unclecode/crawl4ai\n\n摘要：发现 21 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing。\n\n## 1. 安装坑 · 来源证据：[Bug]: arun() and arun_many() type hinting needs fixing\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: arun() and arun_many() type hinting needs fixing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d3b6cfd3700147f690e0e65875f15424 | https://github.com/unclecode/crawl4ai/issues/1898 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: After successful FETCH, and failed SCRAPE (COMPLETE being marked as failed), no error messages or failure reason is shown\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad61b108bf894cc286ca7966e8c86758 | https://github.com/unclecode/crawl4ai/issues/1949 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: MCP scrape tools lack wait_until / SPA support that REST API and CLI provide\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ee99f5d72f143f4b064732cc19e0c85 | https://github.com/unclecode/crawl4ai/issues/1963 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: `remove_empty_elements_fast()` drops trailing text when removing empty elements with non-empty .tail\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7fa967632a948008efbc182d1f2c96b | https://github.com/unclecode/crawl4ai/issues/1938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] MCP Server json.dumps() escapes non-ASCII characters, causing 2.5-3x token overhead for CJK content\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e9fbf659fbb40aba437886a87f8e2d7 | https://github.com/unclecode/crawl4ai/issues/1962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] AsyncLogger writes to stdout, breaking MCP stdio transport\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af29278fd7294d4a8f0f6f37ab987b5c | https://github.com/unclecode/crawl4ai/issues/1968 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: The install with pip on just about any system rarely works. It requires an env or it only partial installs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_97d44cedb21a4908a7743fde11209954 | https://github.com/unclecode/crawl4ai/issues/1950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: enable_stealth=True is a silent no-op — StealthAdapter imports symbols that don't exist in playwright-stealth 2.x\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ae45861377894b99a57d6bbdc06af313 | https://github.com/unclecode/crawl4ai/issues/1959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.1:Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.1:Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ae9133fff54443b712725f51769fa1 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：v0.7.2: CI/CD & Dependency Optimization Update\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.2: CI/CD & Dependency Optimization Update\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14954e0431ca426ebeaa4bb31778d4af | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 来源证据：[Bug]: Markdown export loses heading hierarchy and table structure\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Markdown export loses heading hierarchy and table structure\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c3eac8ab81e34bf3b6cc050f7f8e9826 | https://github.com/unclecode/crawl4ai/issues/1964 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:798201435 | https://github.com/unclecode/crawl4ai | README/documentation is current enough for a first validation pass.\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:798201435 | https://github.com/unclecode/crawl4ai | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：Release v0.7.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.3\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e2b75670cbcc4814a86423818b9f6f48 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：Release v0.7.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.5\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_056d1470d7534cacb39eeb894e054496 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Release v0.7.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v0.7.7\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e157445f88744795b5c6234783eca692 | https://github.com/unclecode/crawl4ai/releases/tag/v0.7.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：[Bug]: Markdown text extraction drops text when element contains empty elements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Markdown text extraction drops text when element contains empty elements\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dffa926853d147ebb487a03fdfd1818e | https://github.com/unclecode/crawl4ai/issues/1966 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:798201435 | https://github.com/unclecode/crawl4ai | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# crawl4ai - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 crawl4ai 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的流程自动化任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: 🚀🤖 Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-async-webcrawler：异步网页爬虫核心。围绕“异步网页爬虫核心”模拟一次用户任务，不展示安装或运行结果。\n5. page-deep-crawling：深度爬取策略。围绕“深度爬取策略”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-async-webcrawler\n输入：用户提供的“异步网页爬虫核心”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-deep-crawling\n输入：用户提供的“深度爬取策略”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-async-webcrawler：Step 4 必须围绕“异步网页爬虫核心”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-deep-crawling：Step 5 必须围绕“深度爬取策略”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/unclecode/crawl4ai\n- https://github.com/unclecode/crawl4ai#readme\n- README.md\n- CHANGELOG.md\n- crawl4ai/__init__.py\n- crawl4ai/__version__.py\n- ROADMAP.md\n- setup.py\n- pyproject.toml\n- requirements.txt\n- Dockerfile\n- docker-compose.yml\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 crawl4ai 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：unclecode/crawl4ai\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install -U crawl4ai\n```\n\n来源：https://github.com/unclecode/crawl4ai#readme\n\n## 来源\n\n- repo: https://github.com/unclecode/crawl4ai\n- docs: https://github.com/unclecode/crawl4ai#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_854bda8c953f459280cd4085d3ec4f00"
}