nano-deepresearch

📋 项目介绍

nano-deepresearch 是一个轻量级（nano）深度研究（deepresearch）代理系统，基于 PocketFlow 框架构建，旨在通过结构化的研究流程，为用户提供高质量、深度的研究报告。

系统采用主代理+子代理架构，由 Researcher 主代理协调 Searcher、Reporter 等子代理，完成从研究计划生成到报告撰写的全流程。通过多维度搜索、证据收集和智能分析，实现对复杂问题的深度研究。

核心功能

• 🧠 智能研究规划：根据用户问题自动生成结构化研究计划
• 🔍 多维度搜索：基于研究计划生成并执行多个搜索查询
• 📚 证据收集与管理：自动收集、整理和存储搜索结果
• 📄 智能报告生成：基于收集的证据生成结构化研究报告
• 🌐 交互式 HTML 结果：将研究结果转换为美观的 HTML 页面
• 📁 会话管理：为每个研究任务创建独立的会话目录，存储完整的研究过程

🛠️ 技术架构

系统架构

┌─────────────────────────────────────────────────────────┐
│                      Main.py                            │
└─────────────────┬───────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────┐
│                   Flow.py (OptimizedResearchFlow)       │
└─────────────────┬───────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────┐
│                      Nodes.py                           │
│ ┌──────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────┴─────────┐
│ │ResearcherNode│ │SearcherNode │ │ReporterNode │ │GenerateHTMLNode│
│ └──────────────┘ └─────────────┘ └─────────────┘ └────────────────┘
└─────────────────────────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────┐
│                      Context.py                         │
│                  (FileSystemContextManager)             │
└─────────────────────────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────┐
│                      Config/                            │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────────┐  │
│ │prompts.yaml │ │  loader.py  │ │html_template.html  │  │
│ └─────────────┘ └─────────────┘ └────────────────────┘  │
└─────────────────────────────────────────────────────────┘

核心组件

1. Flow (研究流程)

   • 定义了完整的研究流程，连接各个节点
   • 负责流程的初始化、执行和最终处理

2. Nodes (研究节点)

   • ResearcherNode：生成研究计划
   • TodoNode：管理和调度研究任务
   • SearcherNode：执行网络搜索，收集信息
   • EvidenceNode：整理和管理收集的证据
   • ReporterNode：基于证据生成研究报告
   • GenerateHTMLNode：将结果转换为 HTML 格式

3. Context (上下文管理)

   • 基于文件系统的上下文管理器
   • 负责创建会话目录、存储证据、日志和最终结果

4. Config (配置管理)

   • YAML 配置驱动的系统参数和 prompt 管理
   • 支持模板变量替换和配置热更新

🚀 快速开始

环境要求

• Python 3.8+
• PocketFlow 框架
• 网络连接（用于执行搜索查询）

安装步骤

1. 克隆项目

   git clone <repository-url>
   cd nano-deepresearch

2. 安装依赖

   pip install -r requirements.txt

3. 配置环境变量

   • 根据需要配置搜索 API 的相关环境变量

使用方法

基本用法

# 使用默认问题
python main.py

# 使用自定义问题
python main.py --<your-question>

# 示例
python main.py --人工智能在医疗领域的应用现状

输出结果

执行完成后，系统会在 output/ 目录下创建一个会话目录，包含以下内容：

• research_plan.yaml：生成的研究计划
• evidence/：收集的搜索结果
• final_report.md：生成的研究报告
• research_results.html：交互式 HTML 结果
• logs/：研究过程的日志
• artifacts/：会话状态和其他产物

⚙️ 配置管理

系统使用 YAML 配置文件统一管理所有节点的 prompt 和系统参数。

配置文件结构

# config/prompts.yaml
researcher:
  prompt: |
    ### CONTEXT
    You are an expert research orchestrator.
    Question: {question}
    Context: {context}
    
    ### TASK
    Create a research plan.
    
    tasks:
      - description: Search for information
        type: search
        details: Comprehensive search
        priority: high
  fallback: '{"tasks": [{"description": "Search for information", "type": "search", "details": "Comprehensive search", "priority": "high"}]}'

searcher:
  prompt: |
    ### CONTEXT
    You are an expert search strategist.
    Question: {question}
    Task: {task_description}
    
    ### TASK
    Generate 3-5 search queries.
    
    queries:
      - <query 1>
      - <query 2>
      - <query 3>
  fallback: '{"queries": ["{task_description}", "{task_description} latest", "{task_description} research"]}'

reporter:
  prompt: |
    ### CONTEXT
    You are an expert research reporter.
    Question: {question}
    Context: {context}
    Evidence: {evidence_summary}
    
    ### TASK
    Generate a comprehensive report.
  fallback: "### CONTEXT\nYou are an expert research reporter.\nQuestion: {question}\n\n### TASK\nGenerate a summary report.\n\n1. Executive Summary\n2. Key Findings\n3. Conclusion"

system:
  max_evidence_length: 10000
  max_context_length: 2000
  max_queries: 5
  retry_attempts: 3
  retry_delay: 1

自定义配置

1. 修改 prompt：编辑 config/prompts.yaml 文件中的相应节点 prompt
2. 调整系统参数：修改 system 部分的参数值
3. 配置热更新：系统会自动检测配置文件的变化，无需重启即可应用新配置

📊 系统特性

1. 轻量级架构 (nano)

• 基于 PocketFlow 轻量级框架构建，资源占用低
• 模块化设计，便于部署和扩展
• 配置驱动开发，通过 YAML 配置文件统一管理所有节点的 prompt 和系统参数

2. 深度研究能力 (deepresearch)

• 多维度搜索策略，确保信息的全面性和深度
• 智能证据收集与管理，自动整理和存储搜索结果
• 基于证据的深度分析，生成结构化、高质量的研究报告

3. 鲁棒性设计

• 实现了多层 fallback 机制，确保系统在各种异常情况下仍能正常运行
• 支持配置文件缺失、格式错误等情况的优雅降级
• 内置错误处理和重试机制，提高系统稳定性

4. 上下文感知

• 基于文件系统的上下文管理，通过结构化文件存储研究过程中的证据、报告、日志等
• 为每个研究任务创建独立的会话目录，便于跟踪和管理
• 支持会话状态持久化，可在系统重启后继续未完成的研究

5. 智能输出

• 基于收集的证据生成结构化研究报告，包含执行摘要、介绍、方法论、关键发现、分析与解释、建议、结论和参考文献
• 支持将报告转换为美观的 HTML 页面，提供更好的阅读体验
• 报告内容基于实际收集的证据，确保信息的准确性和可靠性

🎯 应用场景

1. 学术研究

• 快速收集和整理相关领域的研究资料
• 深度分析学术文献，生成结构化研究综述
• 支持多维度研究视角，提供全面的学术见解

2. 市场调研

• 深度分析特定产品或行业的最新动态
• 收集多源市场信息，确保数据的全面性和准确性
• 生成结构化市场分析报告，支持决策制定

3. 技术评估

• 深度评估新技术的应用前景和挑战
• 收集技术发展趋势和专家观点
• 提供技术可行性分析和建议

4. 政策分析

• 深度分析政策的影响和实施情况
• 收集政策相关的多方面信息
• 生成政策影响评估报告

5. 知识获取

• 快速获取特定主题的全面、深度信息
• 整理和结构化复杂的知识体系
• 提供易于理解的知识摘要和分析

🔧 开发指南

扩展节点

1. 创建新节点类：继承自 Node 基类
2. 实现核心方法：prep、exec、post
3. 添加到流程：在 flow.py 中注册新节点并连接到流程
4. 配置 prompt：在 config/prompts.yaml 中添加新节点的配置

自定义搜索工具

1. 修改搜索函数：在 utils.py 中实现自定义搜索逻辑
2. 更新引用：在 nodes.py 中更新搜索工具的调用

📝 示例输出

研究报告结构

# 研究报告：人工智能在医疗领域的应用现状

## 1. Executive Summary

## 2. Introduction

## 3. Methodology

## 4. Key Findings

## 5. Analysis and Interpretation

## 6. Recommendations

## 7. Conclusion

## 8. References

交互式 HTML 结果

系统会生成一个美观的 HTML 页面，包含：

• 研究问题和回答
• 完整的研究报告
• 研究过程的上下文信息
• 交互式导航和搜索功能

🤝 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进 nano-deepresearch 项目！

贡献指南

• 遵循项目的代码风格和结构
• 提交前确保代码能够正常运行
• 提供清晰的 commit 信息和 PR 描述

📄 许可证

本项目采用 MIT 许可证。

📞 联系方式

如有问题或建议，请通过以下方式联系：

• 项目地址：
• 邮箱：

---

Made with ❤️ using PocketFlow Framework