dzhng/deep-research：用不到 500 行代码写一个会自我迭代的深度研究 Agent

项目地址：
作者：Duet（）

一个 AI 研究助手：把搜索引擎、网页抓取和大模型拼在一起，对任意主题做多轮迭代式的深度研究。

这个仓库的目标是给出 deep research agent 最简单的实现——也就是一个能在研究过程中不断修正方向、并往主题深处钻的 agent。代码规模刻意控制在 500 LoC 以内，方便读懂、也方便在它上面继续搭东西。

工作流程

整条链路是：

用户 Query + Breadth 参数 + Depth 参数
→ Deep Research
→ 生成 SERP 查询
→ 处理搜索结果
→ 得到 Learnings 与 Directions
→ depth > 0 ?
是 → 用 Next Direction（Prior Goals + New Questions + Learnings）回到 Deep Research
否 → 输出 Markdown 报告

功能

• Iterative Research：迭代生成搜索查询、处理结果，并根据已有发现继续往下钻。
• Intelligent Query Generation：由 LLM 结合研究目标和当前发现，生成有针对性的查询。
• Depth & Breadth Control：广度 width 与深度 depth 都可配置。
• Smart Follow-up：自动生成 follow-up 问题，用来澄清研究需求。
• Comprehensive Reports：输出带发现条目和来源链接的详细 markdown 报告。
• Concurrent Processing：多个搜索和结果处理并发执行。

环境要求

• Node.js 环境
• API keys：
• Firecrawl API —— 用于网页搜索与内容抽取
• OpenAI API —— 使用 o3 mini 模型

安装（Node.js）

1. Clone 仓库
2. npm install
3. 在 .env.local 中设置环境变量：

FIRECRAWL_KEY="your_firecrawl_key"
# 自托管 Firecrawl 时加上：
FIRECRAWL_BASE_URL="http://localhost:3002"
OPENAI_KEY="your_openai_key"

使用本地 LLM：注释掉 OPENAI_KEY，改用 OPENAI_ENDPOINT 和 OPENAI_MODEL。OPENAI_ENDPOINT 填本地服务地址（例如 http://localhost:1234/v1），OPENAI_MODEL 填实际加载的模型名。

Docker

1. Clone 仓库
2. 把 .env.example 改名为 .env.local，填好 API keys
3. docker build -f Dockerfile
4. docker compose up -d
5. docker exec -it deep-research npm run docker

使用

npm start

启动后会依次提示输入：

1. 研究问题
2. research breadth —— 建议 3–10，默认 4
3. research depth —— 建议 1–5，默认 2
4. 回答 follow-up 问题，进一步细化研究方向

随后系统会：生成并执行搜索查询 → 处理和分析结果 → 基于发现递归深入 → 生成 markdown 报告。

最终报告保存在工作目录下，文件名是 report.md 或 answer.md，取决于所选模式。

并发

付费版 Firecrawl 或本地自托管 Firecrawl 可以调高并发上限，环境变量是 CONCURRENCY_LIMIT，用来加速。免费版容易撞限流，可以降到 1（速度会慢很多）。

DeepSeek R1

Deep research 在 R1 上表现很好，作者主要用 Fireworks 作为 R1 的提供方。设置：

FIREWORKS_KEY="api_key"

检测到这个 key 时，系统会自动切换到 R1，而不再使用 o3-mini。

自定义 endpoint 与模型

OPENAI_ENDPOINT="custom_endpoint"
CUSTOM_MODEL="custom_model"

用这两个变量可以接 OpenRouter、Gemini 等任何 OpenAI 兼容 API。

社区实现

Python 版本：

License

MIT License