# firecrawl - Doramagic AI Context Pack

> 定位：给用户宿主 AI 装载的开工前上下文。它不代表已经安装、运行或验证目标项目。

## 项目

- canonical_name: `firecrawl/firecrawl`
- capability: 🔥 The API to search, scrape, and interact with the web for AI
- expected_user_outcome: 🔥 The API to search, scrape, and interact with the web for AI

## 基础边界

- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。
- 项目事实必须来自 repo evidence、Claim Graph 或明确来源。
- 遇到未验证能力时，必须标记为待验证，而不是补全为事实。
- publish_status: `publishable`
- blocking_gaps: none

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概览**：importance `high`
  - source_paths: README.md, apps/api/package.json, CLAUDE.md
- **系统架构**：importance `high`
  - source_paths: apps/api/src/index.ts, apps/api/src/harness.ts, apps/api/native/src/lib.rs, apps/api/src/services/index.ts, apps/api/src/services/queue-service.ts
- **API路由与版本控制**：importance `high`
  - source_paths: apps/api/src/routes/v0.ts, apps/api/src/routes/v1.ts, apps/api/src/routes/v2.ts, apps/api/src/routes/admin.ts, apps/api/openapi.json
- **抓取引擎**：importance `high`
  - source_paths: apps/api/src/scraper/scrapeURL/index.ts, apps/api/src/scraper/scrapeURL/engines/fetch/index.ts, apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts, apps/api/src/scraper/scrapeURL/engines/playwright/index.ts, apps/api/src/scraper/scrapeURL/engines/pdf/index.ts
- **搜索与爬取功能**：importance `high`
  - source_paths: apps/api/src/search/index.ts, apps/api/src/search/execute.ts, apps/api/src/search/fireEngine.ts, apps/api/src/search/searxng.ts, apps/api/src/scraper/WebScraper/crawler.ts
- **数据提取系统**：importance `high`
  - source_paths: apps/api/src/lib/extract/extraction-service.ts, apps/api/src/lib/extract/build-document.ts, apps/api/src/lib/extract/build-prompts.ts, apps/api/src/lib/extract/completions/analyzeSchemaAndPrompt.ts, apps/api/src/lib/extract/completions/batchExtract.ts
- **监控与Webhook**：importance `medium`
  - source_paths: apps/api/src/services/monitoring/scheduler.ts, apps/api/src/services/monitoring/runner.ts, apps/api/src/services/monitoring/store.ts, apps/api/src/services/monitoring/diff.ts, apps/api/src/services/webhook/delivery.ts
- **多语言SDK**：importance `high`
  - source_paths: apps/python-sdk/firecrawl/__init__.py, apps/python-sdk/firecrawl/v2/client.py, apps/js-sdk/firecrawl/src/index.ts, apps/js-sdk/firecrawl/src/v2/client.ts, apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: false
- repo_inspection_verified: false
- repo_commit: `unknown`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 来源证据：RFC: Lightweight External Memory Capsule Pattern for Firecrawl Agent Workflows

- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RFC: Lightweight External Memory Capsule Pattern for Firecrawl Agent Workflows
- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Why it matters: 可能影响升级、迁移或版本选择。
- Evidence: community_evidence:github | cevd_0bf31b0e8c3b45fb8da04cebb259c8a4 | https://github.com/firecrawl/firecrawl/issues/3500 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 来源证据：v2.4.0

- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.4.0
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | cevd_e1e417d6cea44fb79118e4daeac083a0 | https://github.com/firecrawl/firecrawl/releases/tag/v2.4.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 来源证据：[Bug] /interact with language="python" flakily fails with TargetClosedError on scrape-bound sessions

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] /interact with language="python" flakily fails with TargetClosedError on scrape-bound sessions
- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | cevd_aa487261676d400197da5f3646baff2f | https://github.com/firecrawl/firecrawl/issues/3498 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | github_repo:787076358 | https://github.com/firecrawl/firecrawl | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 来源证据：[Feat] Emit batch scrape failures of each page to webhook

- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Feat] Emit batch scrape failures of each page to webhook
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | cevd_80c638d597cc432b9a74e7e336b043ee | https://github.com/firecrawl/firecrawl/issues/2576 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | github_repo:787076358 | https://github.com/firecrawl/firecrawl | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 下游验证发现风险项

- Trigger: no_demo
- Host AI rule: 进入安全/权限治理复核队列。
- Why it matters: 下游已经要求复核，不能在页面中弱化。
- Evidence: downstream_validation.risk_items | github_repo:787076358 | https://github.com/firecrawl/firecrawl | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 存在安全注意事项

- Trigger: No sandbox install has been executed yet; downstream must verify before user use.
- Host AI rule: 转成明确权限清单和安全审查提示。
- Why it matters: 用户安装前需要知道权限边界和敏感操作。
- Evidence: risks.safety_notes | github_repo:787076358 | https://github.com/firecrawl/firecrawl | No sandbox install has been executed yet; downstream must verify before user use.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: 存在评分风险

- Trigger: no_demo
- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。
- Why it matters: 风险会影响是否适合普通用户安装。
- Evidence: risks.scoring_risks | github_repo:787076358 | https://github.com/firecrawl/firecrawl | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 来源证据：[Feat] Support custom HTTP headers in Node.js SDK for self-hosted instances behind reverse proxies

- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feat] Support custom HTTP headers in Node.js SDK for self-hosted instances behind reverse proxies
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能影响授权、密钥配置或安全边界。
- Evidence: community_evidence:github | cevd_ef6deffa53c147b29e617225612e55b0 | https://github.com/firecrawl/firecrawl/issues/2814 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。