# Firecrawl 研究模式在研究工作流程中使用自托管 Firecrawl 的编程模式 - 搜索、抓取、路由学术论文、运行递归深度研究以及保留原始结果以供将来重新分析。还涵盖自托管部署、运行状况检查和恢复。有关存档 AI 聊天对话（ChatGPT/Gemini 共享）的信息，请参阅“技能(gh-tools:research-archival)”。 ** ** ## 首先 — TodoWrite 任务模板 **强制**：在任何研究工作之前选择并加载适当的模板。 ### 模板 A — 单一 Firecrawl 搜索 + 持久 1. 健康检查 — GET http://172.25.236.1:3002/v1/health（后备：测试搜索） 2. 执行搜索 — POST /v1/search 并带有查询、限制、scrapeOptions 3. 保留原始结果——使用 frontmatter 将每个结果页面保存到 docs/research/corpus/ 4.更新语料库索引——将条目追加到 docs/research/corpus-index.jsonl 5. 提取结果——总结原始语料库文件中的关键知识 ### 模板 B — 学术论文检索 + 坚持 1. 识别来源 — 根据学术论文路由.md 决策树对 URL/DOI 进行分类 2. 路由至抓取工具 — arxiv direct HTML、Semantic Scholar API、Firecrawl 或 Jina Reader 3. 抓取内容 — 使用适当的方法和超时执行获取 4. 保留原始结果 - 保存到 docs/research/corpus/ 以及学术特定的 frontmatter 5.更新语料库索引——将条目追加到corpus-index.jsonl 6. 总结论文——从原始语料库文件中提取关键主张、方法、结果 ### 模板 C — 使用语料库进行全面递归深度研究 1. 健康检查 — 验证 Firecrawl 可在 172.25.236.1:3002 上访问 2.初始化参数——设置广度（默认4）、深度（默认2）、并发（默认2） 3.生成搜索查询——LLM根据主题+先前的学习生成N个查询 4. 执行搜索 — Firecrawl /v1/search 通过 p-limit(concurrency) 对每个查询进行搜索 5. 保留原始结果——将所有抓取的页面保存到 docs/research/corpus/ 并注明出处 6. 提取学习内容——法学硕士提取每个结果集的关键发现+后续问题 7. 递归——对于每个后续，递归宽度=ceil(宽度/2)，深度=深度-1 8. 基础案例——深度=0，返回累积的学习值 9. 综合报告——LLM从所有学习中生成最终的markdown 10. 编写会话报告——保存到 docs/research/sessions/ 并包含语料库文件引用 11.更新语料库索引——将所有新条目追加到 corpus-index.jsonl ### 模板 D — 语料库审查/重新分析 1. 库存语料库 — 阅读 docs/research/corpus-index.jsonl，按会话/主题/日期过滤 2.读取原始文件——从docs/research/corpus/加载匹配的语料库文件 3. 重新分析——根据当前的背景/问题提取新的见解 4. 更新会话报告——在 docs/research/sessions/ 中修改或创建新的会话报告 ** ** ## 第 1 节 — 程序化 Firecrawl 的使用 **实例**：通过 ZeroTier 自托管于“http://172.25.236.1:3002”。无需 API 密钥。 ### 为什么使用 `fetch()` 而不是 `@mendable/firecrawl-js` SDK 官方SDK使用`jiti`进行动态导入，与Bun的模块解析不兼容。直接“fetch()”调用更简单、更可靠，并且具有零依赖性。 ### 两个端点端点|目的|何时使用 ---|---|--- `POST /v1/search` |搜索+抓取组合 |研究查询——返回多个抓取的页面 `POST /v1/scrape` |单个 URL 抓取 |已知 URL — 从一页中提取 Markdown 有关完整的请求/响应合约，请参阅 [api-endpoint-reference.md]()。 ### 简单示例 **搜索**（返回带有 markdown 的多个结果）： const res = 等待 fetch("http://172.25.236.1:3002/v1/search", { 方法：“POST”， headers: { "Content-Type": "application/json" }, 正文：JSON.stringify({ 查询：“专家混合比例定律”，限制：5， scrapeOptions: { 格式: ["markdown"] }, }), }); const { 数据 } = 等待 res.json(); // 数据: [{ url, markdown, 元数据 }] **抓取**（单个 URL）： const res = 等待 fetch("http://172.25.236.1:3002/v1/scrape", { 方法：“POST”， headers: { "Content-Type": "application/json" }, 正文：JSON.stringify({ 网址：“https://arxiv.org/abs/2401.12345”，格式：[“降价”]， waitFor: 3000, // ms — 对于 JS 较多的页面 }), }); const { 数据 } = 等待 res.json(); // 数据: { markdown, 元数据 } ### 错误处理 // 始终设置超时 const 控制器 = new AbortController(); const timeoutId = setTimeout(() =>controller.abort(), 15_000); 尝试{ const res = wait fetch(url, { ...opts, signal:controller.signal }); if (!res.ok) throw new Error(`Firecrawl: ${res.status} ${res.statusText}`); const json = 等待 res.json(); if (!json.data || (Array.isArray(json.data) && json.data.length === 0)) { // 空结果 — 不是错误，但没有要处理的内容 } }最后{ 清除超时(timeoutId); } ### 健康检查 // 开始研究之前进行快速健康检查 const res = wait fetch("http://172.25.236.1:3002/v1/health"); 如果（！res.ok）抛出新的错误（ “Firecrawl 不健康 - 请参阅 self-hosted-operations.md 和 self-hosted-troubleshooting.md 参考资料”，）； ** ** ## 第 2 部分 — 学术论文路由根据来源将论文检索路由到最有效的方法。完整决策树位于 [academic-paper-routing.md]()。 ### 快速参考来源 |最佳方法|回退 ---|---|--- arxiv.org |直接 HTML (`/html/ID`) | Firecrawl `/v1/scrape` 语义学者| API (`api.semanticscholar.org`) |按标题进行 Firecrawl 搜索 ACL 选集 | Firecrawl `/v1/scrape` |直接PDF下载 NeurIPS/ICML/ICLR |使用 `waitFor` 进行 Firecrape `/v1/scrape` |按标题搜索 IEEE Xplore |使用 `waitFor: 3000` 进行 Firecrawl |作者的网站 ACM DL |使用 `waitFor: 3000` 进行 Firecrawl |作者的网站作者博客 | Jina 读者 (`r.jina.ai`) | Firecrawl `/v1/scrape` 谷歌学术| Firecrawl `/v1/search` |直接搜索查询 ### DOI 解析 // DOI → 发布者 URL → 路由到适当的抓取工具 const res = wait fetch(`https://doi.org/${doi}`, { 重定向: "follow" }); constpublisherUrl = res.url; // 例如，https://dl.acm.org/doi/10.1145/... // 然后通过上面的决策树路由publisherUrl ** ** ## 第 3 节 — 递归研究协议迭代搜索→提取→递归→合成模式。 [recursive-research-protocol.md]()中的完整分步协议。 ### 算法概述 deepResearch（主题，广度=4，深度=2，并发=2）： 1. 根据主题+先前的学习生成 N 个搜索查询（N = 广度） 2. 对于每个查询（通过 p-limit 并发）： a. Firecrawl /v1/search → 获取结果 b.将每个原始结果持久保存到 docs/research/corpus/ c.提取学习内容+后续问题 3. 对于每个后续问题： → 递归，宽度=ceil(宽度/2)，深度=深度-1 4. 基本情况：深度=0→返回累积学习值 5. 综合所有学习成果的最终报告 6. 将会话报告写入 docs/research/sessions/ ### 默认参数（来自工作实现）参数|默认 |最大|基本原理 ---|---|---|--- `广度` | 4 | — |每个级别的并行搜索查询数 `深度` | 2 | 5 |递归级别（深度 > 5 会产生收益递减） `并发` | 2 | — |并行 Firecrawl 请求（自托管，温和） `限制` | 5 | — |每个搜索查询的结果 `超时` | 15000 毫秒 | — |每次搜索超时 ### 代币预算每次搜索最多返回 5 页。在 LLM 处理之前将每个页面修剪为约 25,000 个标记：函数trimToTokenLimit（文本：字符串，maxTokens：数字）：字符串{ if (!text) 返回 ""; constestimatedTokens = Math.ceil(text.length / 3.5); if (estimatedTokens <= maxTokens) 返回文本； const maxChars = Math.floor(maxTokens * 3.5 * 0.8); 返回 text.slice(0, maxChars); } ### 部分失败原则 **部分结果比完全失败要好。** 如果查询失败，请将其记录下来并继续执行其余查询。永远不要因为一个查询超时而中止整个研究会话。 ** ** ## 第 4 节 — 原始语料库持久化 **关键原则**：每个 Firecrawl 抓取的页面都必须保留其**原始原始降价** 以及出处元数据。综合报告引用了这些原始报告，但从未取代它们。完整格式规范位于 [corpus-persistence-format.md]()。 ### 目录布局 {项目根目录}/ ├── 文档/研究/ │ ├── corpus/ # 原始抓取页面（已提交） │ │ └── YYYY-MM-DD-{slug}.md # 每个抓取的 URL 一个文件 │ ├──sessions/ # 研究会议报告（已提交） │ │ └── YYYY-MM-DD-{topic-slug}.md # 带有语料库参考的综合报告 │ └── corpus-index.jsonl # 仅附加注册表（已提交） ### 语料库文件 Frontmatter --- 来源网址：https://arxiv.org/html/2401.12345 scraped_at：“2026-02-25T14：30：00Z” 刮刀：火爬行 firecrawl_endpoint：/v1/搜索 search_query：“专家混合缩放” 结果索引：2 研究会议：“2026-02-25-moe-scaling” 深度级别：1 claude_code_uuid：SESSION_UUID 内容令牌大约：4200 --- [Firecrawl 的原始降价 — 从未修改] ### 关键规则 1. `---` 下面的内容是 **Firecrawl 返回的精确降价** — 没有摘要、修剪或重新格式化 2. 每次抓取每个 URL 一个文件 - 如果在多个会话中抓取相同的 URL，则每个会话都会获取自己的带时间戳的文件 3. 文件命名：`YYYY-MM-DD-{slug}.md`，其中 slug 是页面标题或 URL 路径中的短横线大小写（最多 60 个字符） 4. `docs/research/sessions/`中的Session报告通过相对路径引用语料库文件 ### 语料库索引 (JSONL) { “网址”：“https://arxiv.org/html/2401.12345”， “文件”：“语料库/2026-02-25-moe-scaling-arxiv-2401-12345.md”， “scraped_at”：“2026-02-25T14：30：00Z”， “会话”：“2026-02-25-moe-scaling”， “代币”：4200， “刮刀”：“火爬行” } ### 为什么这很重要 * **LLM 重新分析**：未来的课程可以重新读取原始语料库文件，并通过更好的提示或更新的模型提取不同的见解 * **无信息丢失** ：综合丢弃细节； raw 文件保留 Firecrawl 捕获的所有内容 * **重复数据删除意识**：JSONL 索引允许代理跳过语料库中已有的 URL * **Git 友好** ：Markdown 文件差异清晰，JSONL 只能附加 ** ** ## 第 5 节 — 自托管操作 Firecrawl 实例通过 ZeroTier 在 **littleblack** (172.25.236.1) 上运行。无需 API 密钥。港口|服务 |类型 |目的 ---|---|---|--- 3002 | 3002火爬 API |码头工人 |核心抓取引擎 3003 | 3003刮刀包装|包子|保存到文件，返回 URL 8080|球童 |二进制|提供已保存的降价有关架构图、运行状况检查、恢复命令和部署详细信息，请参阅： * [自托管操作]() — 架构、运行状况检查、恢复命令 * [自托管引导指南]() — 全新安装（7 个步骤） * [自托管最佳实践]() — Docker 重启策略、监控 * [自托管故障排除]() — 基于症状的诊断 ** ** ## 反模式＃|反模式|为什么失败 |正确的做法 ---|---|---|--- 1 |使用`@mendable/firecrawl-js` SDK | Bun 中的 `jiti` 动态导入中断 |直接调用 fetch() 2 |无需“waitFor”即可搜索付费网站 | JS SPA 返回空壳 |对 IEEE、ACM DL 使用 `waitFor: 3000` 3 |设置深度 > 5 |指数级查询爆炸，收益递减 |深度为 5 的盖子（`clampDepth()`） 4 | `fetch()` 没有超时 |无限期地挂在无法访问的页面上 |始终使用 15 秒超时的“AbortController” 5 |不修剪长页面内容 |超出LLM上下文窗口|每页 `trimToTokenLimit(text, 25_000)` 6 |因部分失败而中止 |丢失所有已完成的工作 |记录失败，继续剩余的查询 7 |不首先检查 Firecrawl 运行状况 |在全部失败的查询上浪费时间 | `GET /v1/health` 或在开始之前测试搜索 8 |仅保存合成而不保存原始原件 |丢失源材料，无法进行重新分析 |始终将原始 Firecrawl 降价保留到语料库 ** ** ## 参考文献 * [API 端点参考]() — `/v1/search` 和 `/v1/scrape` 合约 * [学术论文路由]() - 论文来源的决策树 * [递归研究协议]() — 逐步递归模式 * [Corpus Persistence Format]() — 原始内容归档格式+目录布局 * [自托管操作]() — 架构、运行状况检查、恢复 * [自托管引导指南]() — 全新安装指南 * [自托管最佳实践]() — Docker 重启策略、监控 * [自托管故障排除]() — 基于症状的诊断和恢复

火行研究模式

包含技能