基于 AgentScope Java 的多智能体深度研究应用。输入一个研究问题 → 五个智能体协作完成「规划 → 联网搜索 → 阅读提炼 → 事实核查 → 撰写」→ 产出一份带可点击引用的结构化研究报告，全过程通过 SSE 实时流式呈现。
同时是一个端到端的 AgentScope Java 教学样本（ReAct、Function Calling、Memory、多智能体编排、流式），也是一个可自部署的调研工具。
输入问题 → 看着智能体实时工作 → 报告边写边出 → 完成。
- 5 个智能体协作：Planner 规划 · Researcher 检索 · Reader 阅读 · FactChecker 核查 · Writer 撰写
- 联网搜索（Tavily）+ 网页抓取（Jsoup），通过
@ToolFunction Calling 暴露 - 事实核查回环：发现信息缺口时自动补搜，最多 2 轮
- 带可点击
[n]引用的报告 + 来源列表（含 URL） - 实时 SSE：逐个 Agent 步骤实时可见；报告边生成边推送
- Last-Event-ID 断线重连（事件走共享 Redis Stream，断连不丢）
- 分布式预留：Agent/工具接口化、状态全外置（MySQL + Redis）
- Docker Compose 一键起：client(:9090) + 5 个角色 server + Nacos + MySQL + Redis
[用户浏览器] ──HTTP + SSE──► [orchestrator-client :9090]
WebFlux · REST + SSE · 编排 · MySQL/Redis
│
│ A2A JSON-RPC（经 Nacos 发现 agent card）
│ namespace=research
┌────────────┬────────────┬──────┴─────┬────────────┬────────────┐
▼ ▼ ▼ ▼ ▼
[planner] [researcher] [reader] [factchecker] [writer]
:8081 :8082 :8083 :8084 :8085
│ │ │ │ │
└────────────┴───────┬────┴────────────┘
▼
Nacos（注册中心 + 配置中心，namespace=research）＋ MySQL ＋ Redis
5 个 Agent 各运行在独立 server 进程，client 经 A2A 远程调用（Nacos 发现 agent card）；业务配置（含 application.name/autoconfigure.exclude/server.port）全在 Nacos 配置中心（namespace research）。设计文档：docs/design/07-v2-distributed.md；单模块时期（M0–M5）见 docs/code-architecture.md。
1. Planner → 把问题拆成 3–5 个可搜索子问题
2. Researcher→ 对每个子问题并行搜索 + 抓取来源
3. Reader → 把来源提炼成结构化研究笔记
4. FactChecker → 核查笔记、找缺口；必要时回到 Researcher 补搜（≤2 轮）
5. Writer → 流式产出带引用的 Markdown 报告（REPORT_CHUNK 事件）
5 个 Agent 各自运行在独立 server 进程，由 client 编排（A2A 远程调用）；每个阶段的事件发到 Redis Stream，SSE 端点实时推给浏览器。状态存 Redis（研究上下文）+ MySQL（任务/笔记/来源/报告）。
export DASHSCOPE_API_KEY=xxx # 必须（LLM）
export TAVILY_API_KEY=xxx # 必须（联网搜索）
docker compose up --build # v2 分布式：client(:9090) + 5 个 role server + nacos + mysql + redis
# 首次启动 nacos-config-init 会自动把 nacos-config/*.yaml 推送到 Nacos 配置中心（group=RESEARCH_GROUP）
# 浏览器打开 http://localhost:9090/选项 1：Nacos 模式（默认，与方式 A 同架构，配置全在 Nacos）
docker compose up -d mysql redis nacos # 起依赖（含 nacos）
./scripts/init-nacos-config.sh # 首次/改配置后把 nacos-config/*.yaml 推送到 Nacos（命名空间 research）
export DASHSCOPE_API_KEY=xxx
export TAVILY_API_KEY=xxx
# 依次在 planner/researcher/reader/factchecker/writer-server、orchestrator-client 目录 ./mvnw spring-boot:run
# （默认 profile=nacos → application-nacos.yaml → 从 Nacos 拉全部业务配置）选项 2：本地模式（无 Nacos，SPRING_PROFILES_ACTIVE=local）
docker compose up -d mysql redis # 只需 mysql/redis（无需 nacos）
export DASHSCOPE_API_KEY=xxx
export TAVILY_API_KEY=xxx
# 依次在 5 个 server、orchestrator-client 目录 SPRING_PROFILES_ACTIVE=local ./mvnw spring-boot:run
# （走 application-local.yaml，A2A 用 wellknown 直连，client 自动指向各 server 的 localhost:8081-8085）接口冒烟：
# 完整研究（异步）
curl -XPOST http://localhost:9090/api/research -H 'Content-Type: application/json' -d '{"query":"向量数据库如何选型"}'
# 然后 GET http://localhost:9090/api/research/{taskId}（状态/报告）
# 或订阅过程：curl -N http://localhost:9090/api/research/{taskId}/stream| 变量 | 必需 | 说明 |
|---|---|---|
DASHSCOPE_API_KEY |
✅ | 阿里通义 DashScope key —— 获取 |
TAVILY_API_KEY |
✅ | Tavily 搜索 key —— 获取 |
DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD |
— | MySQL（默认 localhost:3306/research，root/rootpass） |
REDIS_HOST / REDIS_PORT |
— | Redis（默认 localhost:6379） |
NACOS_SERVER_ADDR / NACOS_USERNAME / NACOS_PASSWORD |
— | Nacos 注册 + 配置中心（默认 127.0.0.1:8848，nacos/nacos） |
NACOS_NAMESPACE |
— | 项目专属命名空间（配置 + A2A 注册/发现统一，默认 research，seed 自动创建） |
密钥绝不入库——
application.yaml里只有${ENV_VAR}占位。把.env.example复制为.env。Nacos 配置中心：各模块业务配置几乎全在 Nacos（数据源
nacos-config/*.yaml，namespace=research（NACOS_NAMESPACE可配）、group=RESEARCH_GROUP，密钥仍是${ENV_VAR}占位）——application.yaml只留 Nacos 自举 + 默认profile=nacos（走application-nacos.yaml拉配置，含application.name/autoconfigure.exclude/server.port等）；application-local.yaml是完整自包含配置（SPRING_PROFILES_ACTIVE=local即可无 Nacos 运行，A2A 走 wellknown 直连）。docker compose up自动 seed（seed 自动创建命名空间）；本地 Nacos 模式需先./scripts/init-nacos-config.sh；改配置后docker compose run --rm nacos-config-init重推；server 侧@RefreshScope热更新无需重启。控制台按命名空间research筛选即可看到本项目全部配置。
| 运行时 | Java 21 · Spring Boot 3.5 · WebFlux（响应式，Netty） |
| Agent | AgentScope Java agentscope-spring-boot-starter:1.0.12（含 DashScope） |
| LLM | 通义 Qwen（qwen-plus），经 DashScope |
| 存储 | MySQL 8（MyBatis-Plus）· Redis 7（上下文 + Redis Stream） |
| 注册/配置中心 | Nacos（服务发现 + 配置中心，SCA nacos-config） |
| 工具 | Tavily（搜索）· Jsoup（抓取） |
| 前端 | 原生 HTML/JS + marked.js（零构建，打进 jar） |
AgentScope-Java-DeepResearch
├── common/common-core/ 契约：5 个 role 接口 + DTO + 枚举 + 工具（WebSearcher/Jsoup…）
├── orchestrator-client/ 编排 + Web（REST/SSE）+ 5 个 A2A 远程 Client + MySQL/Redis 仓储
├── planner-server/ 角色 server：Planner（A2A + Nacos 注册）
├── researcher-server/ 角色 server：Researcher（web_search/web_fetch 工具）
├── reader-server/ 角色 server：Reader
├── factchecker-server/ 角色 server：FactChecker
├── writer-server/ 角色 server：Writer
├── nacos-config/ 进 git 的配置数据源（seed 推送 Nacos 的唯一事实源，namespace=research）
└── scripts/init-nacos-config.sh 推配置到 Nacos（自动创建命名空间，幂等）
文档：docs/ —— 设计、编码规范、代码架构、路线图。
项目启动完毕之后，访问 http://localhost:9090 端口即可
- ✅ M0 基础设施 · ✅ M1 工具+单 Agent · ✅ M2 多 Agent 编排
- ✅ M3 响应式 SSE · ✅ M4 前端 Demo · ✅ M5 开源化
- ✅ v2 分布式：A2A 远程化 + 多模块 + Nacos 注册/配置中心（
docs/design/07-v2-distributed.md）
后续可选：报告历史、多模型路由。
Apache License 2.0 —— 与 AgentScope 一致。
- AgentScope —— 本项目所基于的多智能体框架。
- Spring AI Alibaba 生态。
- Tavily · marked.js。