Java Deep Research

一个用 Java 17 写的轻量级 Deep Research 命令行工具。

它会围绕一个问题自动生成搜索关键词，调用 Firecrawl 获取网页内容，再用大模型提炼关键信息和后续研究方向，最后生成 Markdown 报告或简短答案。

功能特性

• 自动生成多条搜索 query，减少手动拆题成本。
• 支持 breadth 控制每轮搜索广度。
• 支持 depth 控制递归研究深度。
• 使用 Firecrawl 搜索并抓取网页 Markdown 内容。
• 使用 OpenAI-compatible Chat Completions 接口提炼信息。
• 支持生成长报告 report.md 或简短答案 answer.md。
• 支持交互式运行，也支持命令行参数直接运行。
• 代码结构简单，适合学习 Agent / Deep Research 的基础实现。

工作流程

flowchart TD
    A["用户输入研究问题"] --> B["生成搜索 queries"]
    B --> C["Firecrawl 搜索并抓取网页内容"]
    C --> D["大模型提炼 learnings"]
    D --> E["生成后续研究问题"]
    E --> F{"depth 是否继续？"}
    F -->|继续| B
    F -->|结束| G["汇总所有 learnings 和 sources"]
    G --> H["生成 report.md 或 answer.md"]

Loading

环境要求

• JDK 17+
• Maven 3.8+
• OpenAI-compatible API Key
• Firecrawl API Key

环境变量

PowerShell 示例：

$env:OPENAI_KEY="你的模型 API Key"
$env:OPENAI_MODEL="gpt-4o-mini"
$env:OPENAI_ENDPOINT="https://api.openai.com/v1"

$env:FIRECRAWL_KEY="你的 Firecrawl Key"
$env:FIRECRAWL_BASE_URL="https://api.firecrawl.dev/v2"
$env:FIRECRAWL_CONCURRENCY="2"

常用配置说明：

变量	必填	默认值	说明
OPENAI_KEY	是	无	大模型接口 Key。
OPENAI_MODEL	否	gpt-4o-mini	Chat Completions 模型名。
OPENAI_ENDPOINT	否	https://api.openai.com/v1	OpenAI-compatible 服务地址。
FIRECRAWL_KEY	是	无	Firecrawl API Key。
FIRECRAWL_BASE_URL	否	https://api.firecrawl.dev/v2	Firecrawl API 地址。
FIRECRAWL_CONCURRENCY	否	2	Firecrawl 搜索并发数。
FIRECRAWL_SEARCH_LIMIT	否	5	每个 query 返回的搜索结果数量。
CONTEXT_CHAR_LIMIT	否	120000	发给模型的 prompt 最大字符数。
REQUEST_TIMEOUT_SECONDS	否	90	HTTP 请求超时时间。

如果你使用 OpenRouter、本地模型服务或其他兼容 OpenAI Chat Completions 的服务，只需要替换 OPENAI_ENDPOINT 和 OPENAI_MODEL。

快速开始

cd D:\workspace\java-deep-research
mvn -q test
mvn -q exec:java

交互式运行时会依次询问：

1. 你想研究什么。
2. 研究广度 breadth。
3. 研究深度 depth。
4. 生成长报告还是简短答案。
5. 如果选择长报告，还会先生成追问，帮助收窄研究方向。

命令行示例

生成长报告：

mvn -q exec:java -Dexec.args='--query "Java Agent 框架有哪些" --breadth 3 --depth 2 --mode report'

跳过追问，直接研究：

mvn -q exec:java -Dexec.args='--query "PocketFlow 的学习价值" --breadth 3 --depth 1 --mode report --no-feedback'

只生成简短答案：

mvn -q exec:java -Dexec.args='--query "2024 年诺贝尔物理学奖得主是谁？" --mode answer --breadth 2 --depth 1'

参数说明

参数	默认值	说明
--query	交互输入	要研究的问题。
--breadth	4	每轮生成多少条搜索 query。
--depth	2	递归研究多少层。
--mode	report	report 生成长报告，answer 生成简短答案。
--no-feedback	false	跳过开场追问，直接进入研究。

输出文件

• report.md：长报告模式输出。
• answer.md：简短答案模式输出。

输出文件会生成在当前运行目录下。

项目结构

java-deep-research/
├── docs/
│   └── learning-map.md
├── src/main/java/com/example/deepresearch/
│   ├── AppConfig.java
│   ├── CliOptions.java
│   ├── DeepResearchApp.java
│   ├── DeepResearchService.java
│   ├── FirecrawlClient.java
│   ├── JsonUtils.java
│   ├── OpenAiCompatibleClient.java
│   └── *.java
├── src/test/java/com/example/deepresearch/
│   └── JsonUtilsTest.java
└── pom.xml

核心文件：

• DeepResearchApp：命令行入口，负责读取参数、询问用户、写出文件。
• DeepResearchService：研究主流程，负责生成 query、搜索、提炼、递归和汇总。
• FirecrawlClient：调用 Firecrawl 搜索接口。
• OpenAiCompatibleClient：调用 OpenAI-compatible Chat Completions 接口。
• JsonUtils：从模型输出中提取 JSON。

学习建议

建议按这个顺序阅读：

1. 先看 DeepResearchApp，理解程序怎么从命令行启动。
2. 再看 DeepResearchService#deepResearch，理解递归研究主循环。
3. 接着看 generateSerpQueries 和 processSerpResult，理解大模型分别承担什么任务。
4. 最后看 FirecrawlClient 和 OpenAiCompatibleClient，理解外部 API 是怎么接入的。

继续改造时，可以优先尝试：

• 给每条 learning 绑定来源 URL。
• 给搜索结果和模型调用加本地缓存。
• 把报告里的来源改成脚注引用格式。
• 增加流式进度输出。
• 增加真实 API 的集成测试开关。

本地验证

mvn test

当前测试只覆盖本地 JSON 解析等纯逻辑，不会真实调用 OpenAI 或 Firecrawl。