Deep-research

你的 AI 驱动的研究助手。 使用搜索引擎、网络爬取和 Gemini LLMs 进行迭代式的深度研究，所有这些都在一个轻量级且易于理解的代码库中完成。

该工具使用 Firecrawl 进行高效的网络数据提取，并使用 Gemini 进行高级语言理解和报告生成。

该项目的目标是提供 最简单 但 最有效 的深度研究代理实现。它旨在易于理解、修改和扩展，目标是将代码库控制在 500 行代码 (LoC) 以下。

主要特点：

• MCP 集成： 无缝集成到 AI 代理生态系统中，作为模型上下文协议 (MCP) 工具。
• 迭代式深度挖掘： 通过迭代查询优化和结果处理，深入探索主题。
• Gemini 驱动的查询： 利用 Gemini LLMs 生成智能、有针对性的搜索查询。
• 深度和广度控制： 可配置的深度和广度参数，用于精确的研究范围。
• 智能后续问题： 智能生成后续问题，用于查询优化。
• 全面的 Markdown 报告： 生成详细的、可直接使用的 Markdown 报告。
• 并发处理以提高速度： 通过并行处理最大化研究效率。

工作流程图

flowchart TB
    subgraph Input
        Q[用户查询]
        B[广度参数]
        D[深度参数]
    end

    DR[深度研究] -->
    SQ[SERP 查询] -->
    PR[处理结果]

    subgraph Results[结果]
        direction TB
        NL((学习内容))
        ND((方向))
    end

    PR --> NL
    PR --> ND

    DP{深度 > 0?}

    RD["下一个方向：
    - 先前目标
    - 新问题
    - 学习内容"]

    MR[Markdown 报告]

    %% Main Flow
    Q & B & D --> DR

    %% Results to Decision
    NL & ND --> DP

    %% Circular Flow
    DP -->|是| RD
    RD -->|新上下文| DR

    %% Final Output
    DP -->|否| MR

    %% Styling
    classDef input fill:#7bed9f,stroke:#2ed573,color:black
    classDef process fill:#70a1ff,stroke:#1e90ff,color:black
    classDef recursive fill:#ffa502,stroke:#ff7f50,color:black
    classDef output fill:#ff4757,stroke:#ff6b81,color:black
    classDef results fill:#a8e6cf,stroke:#3b7a57,color:black

    class Q,B,D input
    class DR,SQ,PR process
    class DP,RD recursive
    class MR output
    class NL,ND results

open-deep-research 中的 Persona 代理

什么是 Persona 代理？

在 deep-research 中，我们利用“persona 代理”的概念来指导 Gemini 语言模型的行为。我们不是简单地提示 LLM 执行任务，而是赋予它特定的角色、技能、个性、沟通风格和价值观。 这种方法有助于：

• 聚焦 LLM 的输出： 通过定义清晰的 persona，我们鼓励 LLM 生成与期望的专业知识和视角相符的响应。
• 提高一致性： Persona 有助于在整个研究过程中保持一致的语气和风格。
• 增强特定任务的性能： 针对特定任务（例如，查询生成、学习内容提取、反馈）定制 persona，可以优化 LLM 在研究的该阶段的输出。

正在使用的 Persona 示例：

• 专家研究策略师和查询生成器： 用于生成搜索查询，此 persona 强调战略思维、全面覆盖和查询制定的精确性。
• 专家研究助理和洞察力提取器： 在处理网页内容时，此 persona 侧重于细致的分析、事实准确性以及提取与研究查询相关的关键学习内容。
• 专家研究查询优化器和战略顾问： 对于生成后续问题，此 persona 体现了战略思维、用户意图理解以及引导用户提出更清晰、更有效的研究问题的能力。
• 专业博士级研究员（系统提示）： 此总体 persona 应用于主系统提示，为整个研究过程定下基调，强调专家级分析、逻辑结构和深入调查。

通过利用 persona 代理，deep-research 旨在从 Gemini 语言模型中获得更有针对性、更一致和更高质量的研究成果。

工作原理

功能

• MCP 集成：可用作模型上下文协议工具，与 AI 代理无缝集成
• 迭代研究：通过迭代生成搜索查询、处理结果并根据发现进行更深入的研究来进行深度研究
• 智能查询生成：使用 Gemini LLMs 根据研究目标和先前的发现生成有针对性的搜索查询
• 深度和广度控制：可配置的参数来控制研究的范围（广度）和深度（深度）
• 智能后续：生成后续问题以更好地理解研究需求
• 综合报告：生成包含发现和来源的详细 markdown 报告
• 并发处理：并行处理多个搜索和结果处理以提高效率

要求

• Node.js 环境（推荐 v22.x）
• 以下 API 密钥：
  • Firecrawl API（用于网络搜索和内容提取）
  • Gemini API（用于 o3 mini 模型，知识截止日期：2024 年 8 月）

设置

Node.js

1. 克隆存储库：

   git clone [your-repo-link-here]
   

2. 安装依赖项：

   npm install
   

3. 设置环境变量： 在项目根目录中创建一个 .env.local 文件并添加您的 API 密钥：

   GEMINI_API_KEY="your_gemini_key"
   FIRECRAWL_KEY="your_firecrawl_key"
   # Optional: If you want to use your self-hosted Firecrawl instance
   # FIRECRAWL_BASE_URL=http://localhost:3002
   

4. 构建项目：

   npm run build
   

用法

作为 MCP 工具

要将 deep-research 作为 MCP 工具运行，请启动 MCP 服务器：

node --env-file .env.local dist/mcp-server.js

然后，您可以使用以下参数从任何 MCP 兼容的代理调用 deep-research 工具：

• query（字符串，必需）：研究查询。
• depth（数字，可选，1-5）：研究深度（默认：中等）。
• breadth（数字，可选，1-5）：研究广度（默认：中等）。
• existingLearnings（字符串数组，可选）：用于指导研究的预先存在的研究发现。

MCP 工具调用示例（TypeScript）：

const mcp = new ModelContextProtocolClient(); // Assuming MCP client is initialized

async function invokeDeepResearchTool() {
  try {
    const result = await mcp.invoke("deep-research", {
      query: "Explain the principles of blockchain technology",
      depth: 2,
      breadth: 4
    });

    if (result.isError) {
      console.error("MCP Tool Error:", result.content[0].text);
    } else {
      console.log("Research Report:\n", result.content[0].text);
      console.log("Sources:\n", result.metadata.sources);
    }
  } catch (error) {
    console.error("MCP Invoke Error:", error);
  }
}

invokeDeepResearchTool();

独立 CLI 用法

要直接从命令行运行 deep-research：

npm run start "your research query"

示例：

npm run start "what are latest developments in ai research agents"

MCP Inspector 测试

对于 MCP 服务器的交互式测试和调试，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js

许可证

MIT 许可证 - 免费和开源。 随意使用！

---

**🚀 让我们深入研究！ 🚀

最近的改进 (v0.2.0)

增强的研究验证：

• 🧪 添加了学术输入/输出验证
• ✅ 输入验证：最少 10 个字符 + 3 个单词
• 📈 输出验证：引文密度（每 100 个单词 1.5+）
• 🔍 最近的来源检查（3 个以上 2019 年后的参考文献）
• ⚖️ 冲突披露执行

Gemini 集成升级：

• 🧠 在研究工作流程中嵌入了 Gemini 分析
• 🔄 集成了 Gemini Flash 2.0 以加快处理速度
• 📊 添加了语义文本分割以进行 LLM 上下文管理
• 🛠️ 改进了 API 调用的错误处理

代码质量改进：

• 🚀 添加了并发处理管道
• 🧹 删除了冗余的 academic-validators 模块
• 🛡️ 增强了跨接口的类型安全性
• 📦 优化了依赖项（node_modules 缩小 30%）

新功能：

• 📊 研究指标跟踪（来源/学习内容比率）
• 📑 自动生成的冲突披露声明
• 🔄 递归研究深度控制（1-5 级）
• 📈 研究指标跟踪（来源/学习内容比率）
• 🤖 MCP 工具集成改进

性能：

• 🚀 研究周期加快 30%
• ⚡ 初始研究周期加快 40%
• 📉 API 错误减少 60%
• 🧮 令牌使用效率提高 25%