用途
FireCrawl Research 用于通过 FireCrawl API 自动搜索和抓取网络来源，为研究文档补充资料。它从 Markdown 文件中提取研究主题，然后系统性地对每个主题进行检索、抓取并生成研究文档。
适用情况包括：用户要求“使用 FireCrawl 研究这个主题”；请求为笔记或文档补充网络来源；想收集 Markdown 文件中列出主题的信息；需要系统性地搜索和抓取多个主题。
主要能力
主题提取
脚本通过两种方式自动从 Markdown 文件中提取研究主题：
方式一：标题。二级标题和三级标题都会成为研究主题，例如 ## Spatial Reasoning in AI 与 ### Computer Vision Applications。
方式二：研究标签。例如 - [research] Large Language Models for robotics 和 - [search] Theory of Mind in autonomous driving，两种带标签的条目都会成为研究主题。
搜索与抓取
对每个主题：以该主题为查询词搜索 FireCrawl；检索最多 N 条结果（默认 5 条）；自动抓取每条结果的完整内容；提取 Markdown 格式内容（仅正文）。
输出生成
在指定输出目录中创建新的 Markdown 文件：每个主题一个文件；文件名为 {topic}_{timestamp}.md；内容包含标题、日期、来源数量以及抓取的完整内容；每个来源包含标题、URL 和 Markdown 内容。
学术写作模板与参考文献
技能内置 Markdown 格式的科学论文模板，并提供参考文献生成和文档转换脚本。
使用方式
基本用法
python scripts/firecrawl_research.py research.md 输出到当前目录。
指定输出目录：python scripts/firecrawl_research.py research.md ./output 在 ./output/ 文件夹中创建文件。
限制每个主题的结果数：python scripts/firecrawl_research.py research.md ./output 3 每个主题最多检索 3 条结果。
配置
复制 .env.example 为 .env：cp .env.example .env，然后加入 FireCrawl API 密钥：FIRECRAWL_API_KEY=fc-your-actual-api-key。脚本会自动从技能的 .env 文件加载密钥。
限流：脚本内置针对 FireCrawl 免费层的自动限流，免费层限制为 5 请求/分钟，内置主题间延迟 12 秒，防止 API 报错和额度耗尽。处理多个主题时的预期耗时：5 个主题约 1 分钟；10 个主题约 2 分钟；20 个主题约 4 分钟。
工作流示例
用户请求“使用 FireCrawl 研究这些 AI 主题”。输入文件 ai-research.md：
# AI Research Topics
## Spatial Reasoning in Vision-Language Models
- [research] Embodied AI for robotics
- [research] Computer Use Agents
命令：python scripts/firecrawl_research.py ai-research.md ./research_output 5
输出目录示例：
research_output/
├── Spatial_Reasoning_in_Vision-Language_Models_20251122_140530.md
├── Embodied_AI_for_robotics_20251122_140542.md
└── Computer_Use_Agents_20251122_140554.md
每个文件包含主题标题、时间戳、来源数量、最多 5 个来源的完整抓取内容以及来源 URL。
常见模式
快速研究：python scripts/firecrawl_research.py my-notes.md，从现有笔记提取主题、研究并保存到当前文件夹。
有组织的研究：python scripts/firecrawl_research.py topics.md ./research_results，为研究结果创建专门输出文件夹。
深度调研：python scripts/firecrawl_research.py topics.md ./deep_research 10，增加每个主题的结果数以获得更全面覆盖。
Obsidian 库集成：python scripts/firecrawl_research.py topics.md ~/Brains/brain/Research，直接输出到库的研究文件夹。
错误处理
“API key not found”：在技能文件夹创建 .env 文件并写入 FIRECRAWL_API_KEY=...。
“Rate limit exceeded”：免费层 5 请求/分钟；脚本内置 12 秒延迟；若仍触发限制，减少主题数或在多次运行之间等待。
“Insufficient credits”：检查 FireCrawl 账户额度；升级方案或等待额度重置。
“No topics found”：使用 ## Header 格式、- [research] Topic 格式或 - [search] Topic 格式向 Markdown 添加主题。
学术写作模板
技能包含 Markdown 格式科学论文模板。
模板一：Pandoc Scholarly Paper（assets/templates/pandoc-scholarly-paper.md）。标准学术论文格式；兼容 Pandoc 转换器；通过 BibTeX 支持引用；可导出 PDF、DOCX、HTML。
模板二：MyST Scientific Paper（assets/templates/myst-scientific-paper.md）。MyST（Markedly Structured Text）格式；支持高级交叉引用；面向专业科学出版；多格式导出（PDF、LaTeX、DOCX）。
使用模板：复制模板到项目，例如 cp assets/templates/pandoc-scholarly-paper.md my-paper.md 或 cp assets/templates/myst-scientific-paper.md my-paper.md；编辑内容，更新 YAML 前言信息（标题、作者、单位）、按章节撰写、使用 [@AuthorYear]（Pandoc）或 {cite}AuthorYear（MyST）添加引用；转换：
python scripts/convert_academic.py my-paper.md pdf
python scripts/convert_academic.py my-paper.md docx
python scripts/convert_academic.py my-paper.md pdf --myst
参考文献生成
将 FireCrawl 研究结果转换为 BibTeX 条目：python scripts/generate_bibliography.py research_output/*.md -o references.bib。其作用：从 FireCrawl Markdown 文件提取 URL 和标题；生成 BibTeX @misc 条目；自动创建引用键；添加访问日期。
示例工作流：
# 1. 研究主题
python scripts/firecrawl_research.py topics.md ./research
# 2. 生成参考文献
python scripts/generate_bibliography.py research/*.md -o refs.bib
# 3. 复制模板
cp assets/templates/pandoc-scholarly-paper.md paper.md
# 4. 编辑 paper.md（添加内容、引用来源）
# 5. 转换为 PDF
python scripts/convert_academic.py paper.md pdf
引用示例。Pandoc 语法：Recent research [@Smith2024] shows...；Multiple studies [@Jones2023; @Brown2024] indicate...。MyST 语法：Recent research {cite}Smith2024 shows...；Multiple studies {cite}Jones2023,Brown2024 indicate...。
示例参考文献文件位于 assets/references.bib，包含常见条目类型：期刊文章（@article）、会议论文（@inproceedings）、书籍（@book）、博士论文（@phdthesis）、网络资源（@misc）、预印本（@article with arXiv）。
脚本细节
位置：scripts/firecrawl_research.py。
依赖：python-dotenv（环境变量管理）、requests（向 FireCrawl API 发送 HTTP 请求）。
安装依赖：pip install python-dotenv requests。
使用的 FireCrawl 功能：/v1/search 端点（搜索并自动抓取）；scrapeOptions.formats: ['markdown']（Markdown 输出）；scrapeOptions.onlyMainContent: true（过滤噪声）。
适用场景
为笔记或 Markdown 文档补充网络来源；对多个主题进行系统性检索与抓取；需要将研究结果整理为带引用的学术论文；需要从检索结果生成 BibTeX 参考文献；在 Obsidian 库中直接输出研究资料。
限制
不进行摘要：返回原始抓取内容而非摘要。不去重：同一来源可能出现在不同主题中。不进行质量排序：所有结果同等对待。仅创建新文件：不追加到已有文件。免费层限制：限流会影响处理速度。内容审查时结果按每来源 3000 字符截断以保持可读性。
提示
以层级方式组织主题——用 ## 表示主主题，### 表示子主题。使用描述性名称——主题文本会成为文件名，应保持清晰。批量处理——将相关主题放在一个文件中以提高效率。输出组织——为不同研究项目创建不同文件夹。学术工作流——使用参考文献生成器在论文中引用研究来源。模板定制——根据所在领域的引用风格修改模板。