# multi-agent-financial-report

**Repository Path**: hacker__007/multi-agent-financial-report

## Basic Information

- **Project Name**: multi-agent-financial-report
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Multi-Agent Financial Report System

## 多Agent金融研究报告自动生成系统

> 从零到面试的完整指南 | Python / Java / Go 三语言实现 | Pipeline + Fan-out 并行架构

**一个输入股票代码，就能自动生成专业投资研究报告的AI系统。**

5个AI Agent协作完成：数据采集 → 舆情分析 → 市场分析 → 报告撰写 → 合规审查

---

## 目录

- [项目介绍](#项目介绍)
- [系统架构](#系统架构)
- [快速开始（3步运行）](#快速开始)
- [三种语言版本](#三种语言版本)
- [Agent角色详解](#agent角色详解)
- [核心代码解读](#核心代码解读)
- [面试准备材料](#面试准备材料)
- [技术栈详解](#技术栈详解)
- [项目结构](#项目结构)
- [常见问题FAQ](#常见问题faq)
- [参考资料](#参考资料)

---

## 项目介绍

### 这个项目是什么？

这是一个**多Agent金融研究报告自动生成系统**。你只需要输入一个股票代码（比如 AAPL），系统会自动：

1. 从Yahoo Finance、SEC等平台**采集金融数据**
2. 从新闻媒体**分析市场舆情**
3. 计算技术指标并**综合分析市场趋势**
4. 自动**撰写专业投资研究报告**
5. **合规审查**确保报告符合监管要求
6. 输出 **PDF / Markdown / JSON** 三种格式

### 为什么做这个项目？

| 痛点 | 解决方案 |
|------|---------|
| 人工写研报需要4-6小时 | 自动化，3分钟完成 |
| 需要查阅多个数据源 | 自动集成5+数据源 |
| 合规审查容易遗漏 | Agent自动检查 |
| 单Agent无法处理复杂流程 | 5-Agent协作分工 |
| 面试缺少项目经验 | 完整的企业级项目 |

### 关键指标

| 指标 | 数值 |
|------|------|
| Agent数量 | 5个 |
| 延迟优化 | 降低45%（Fan-out并行） |
| 报告生成时间 | ~3分钟（人工需4小时） |
| 数据源 | 5+（Yahoo Finance, SEC EDGAR, Tavily等） |
| 合规准确率 | 92% |
| 实现语言 | Python, Java, Go |
| 输出格式 | PDF, Markdown, JSON |

---

## 系统架构

### 整体架构图

```
用户输入(股票代码)
      │
      ▼
 ┌─────────────────────────────────────────────┐
 │            Orchestrator（编排器）              │
 │                                              │
 │  ┌─── Stage 1: Fan-out 并行 ───────────────┐ │
 │  │                                          │ │
 │  │  ┌──────────────┐  ┌──────────────────┐ │ │
 │  │  │Data Collector │  │ Sentiment Agent  │ │ │
 │  │  │ (数据采集)     │  │ (舆情分析)        │ │ │
 │  │  │              │  │                  │ │ │
 │  │  │ Yahoo Finance│  │ Tavily新闻搜索    │ │ │
 │  │  │ SEC EDGAR    │  │ LLM情感分析      │ │ │
 │  │  └──────┬───────┘  └────────┬─────────┘ │ │
 │  │         └──────┬────────────┘            │ │
 │  └───────────────│──────────────────────────┘ │
 │                  ▼                             │
 │  ┌─── Stage 2: Pipeline 串行 ──────────────┐  │
 │  │  ┌────────────────┐                     │  │
 │  │  │ Market Analyst  │ ← 需要上面两者的数据  │  │
 │  │  │ (市场分析)       │                     │  │
 │  │  └───────┬────────┘                     │  │
 │  │          ▼                               │  │
 │  │  ┌────────────────┐                     │  │
 │  │  │ Report Writer   │                     │  │
 │  │  │ (报告撰写)       │                     │  │
 │  │  └───────┬────────┘                     │  │
 │  │          ▼                               │  │
 │  │  ┌────────────────┐                     │  │
 │  │  │Compliance Agent │                     │  │
 │  │  │ (合规审查)       │                     │  │
 │  │  └───────┬────────┘                     │  │
 │  └──────────│──────────────────────────────┘  │
 │             ▼                                  │
 │       FinalReport                              │
 └─────────────────────────────────────────────────┘
      │            │            │
      ▼            ▼            ▼
    PDF         Markdown       JSON
```

### 为什么这样设计？

- **Data Collector 和 Sentiment Agent 并行执行**：两者数据源独立，没有依赖关系，并行可以把延迟从 A+B 变成 max(A,B)
- **Market Analyst 等待上游**：分析需要数据和舆情两方面信息
- **Report Writer 和 Compliance 串行**：报告先写完再审查

---

## 快速开始

### 前提条件

- Python 3.10+（Python版本）
- Java 21+（Java版本）
- Go 1.22+（Go版本）
- 一个 OpenAI API Key（用于LLM调用）

### Python版本（推荐先体验这个）

```bash
# 第1步：克隆项目
git clone https://github.com/bcefghj/multi-agent-financial-report.git
cd multi-agent-financial-report

# 第2步：安装依赖
cd python-version
pip install -r requirements.txt

# 第3步：配置API Key
cp ../.env.example .env
# 编辑 .env 文件，填入你的 OPENAI_API_KEY

# 第4步：运行！
python main.py AAPL          # 分析苹果公司
python main.py TSLA --period 6mo   # 分析特斯拉，6个月
python main.py MSFT -v        # 详细日志模式
```

### Java版本

```bash
cd java-version
# 配置环境变量
export OPENAI_API_KEY=sk-your-key

# 编译运行
mvn spring-boot:run

# 调用API
curl -X POST "http://localhost:8080/api/report/generate?ticker=AAPL"
```

### Go版本

```bash
cd go-version
export OPENAI_API_KEY=sk-your-key

go run main.go AAPL
go run main.go TSLA -period 6mo
```

---

## 三种语言版本

| 特性 | [Python版本](python-version/) | [Java版本](java-version/) | [Go版本](go-version/) |
|------|-----|------|------|
| **并行实现** | asyncio.gather() | CompletableFuture.allOf() | goroutine + WaitGroup |
| **并发模型** | 单线程协程 | 多线程+线程池 | M:N调度 |
| **LLM框架** | LangChain + OpenAI | Spring AI | go-openai |
| **数据模型** | Pydantic v2 | Lombok + Jackson | struct + JSON tags |
| **重试机制** | tenacity | 手写/spring-retry | 手写 |
| **HTTP** | httpx/aiohttp | OkHttp/WebClient | net/http |
| **PDF** | ReportLab | iText | (Markdown输出) |
| **部署方式** | CLI命令行 | REST API (Spring Boot) | CLI命令行 |
| **推荐场景** | 快速原型、AI团队 | 企业级Java团队 | 高性能、云原生 |

### 如何选择？

- **面试Java岗** → 重点看Java版本
- **面试AI/ML岗** → 重点看Python版本
- **面试Go岗** → 重点看Go版本
- **都想了解** → 先看Python版本（最易理解），再对比其他两个

---

## Agent角色详解

### 1. Data Collector Agent（数据采集Agent）

| 项目 | 说明 |
|------|------|
| **职责** | 从多个数据源收集金融数据 |
| **数据源** | Yahoo Finance（行情/财务）、SEC EDGAR（监管文件） |
| **输入** | StockQuery（股票代码 + 周期） |
| **输出** | CollectedData（公司信息 + 财务指标 + 股价历史 + SEC文件） |
| **特点** | 与Sentiment Agent并行执行 |
| **代码** | [Python](python-version/agents/data_collector.py) / [Java](java-version/src/main/java/com/finreport/agents/DataCollectorAgent.java) / [Go](go-version/agents/data_collector.go) |

### 2. Sentiment Agent（舆情分析Agent）

| 项目 | 说明 |
|------|------|
| **职责** | 分析新闻和社交媒体的情感倾向 |
| **数据源** | Tavily API（新闻搜索） |
| **输入** | StockQuery |
| **输出** | SentimentAnalysis（情感评分 + 新闻列表 + 关键话题） |
| **特点** | 与Data Collector并行执行，使用LLM进行情感分析 |
| **代码** | [Python](python-version/agents/sentiment_agent.py) / [Java](java-version/src/main/java/com/finreport/agents/SentimentAgent.java) / [Go](go-version/agents/sentiment.go) |

### 3. Market Analyst Agent（市场分析Agent）

| 项目 | 说明 |
|------|------|
| **职责** | 综合分析市场数据和舆情，给出投资建议 |
| **输入** | CollectedData + SentimentAnalysis |
| **输出** | MarketAnalysis（趋势方向 + 技术指标 + 风险评估 + 投资建议） |
| **特点** | 包含纯数学计算（RSI/MA）+ LLM综合分析 |
| **代码** | [Python](python-version/agents/market_analyst.py) / [Java](java-version/src/main/java/com/finreport/agents/MarketAnalystAgent.java) / [Go](go-version/agents/market_analyst.go) |

### 4. Report Writer Agent（报告撰写Agent）

| 项目 | 说明 |
|------|------|
| **职责** | 综合所有分析结果生成结构化投资报告 |
| **输入** | CollectedData + SentimentAnalysis + MarketAnalysis |
| **输出** | InvestmentReport（7个章节的完整报告） |
| **特点** | 使用LLM生成专业中文投资报告 |
| **代码** | [Python](python-version/agents/report_writer.py) / [Java](java-version/src/main/java/com/finreport/agents/ReportWriterAgent.java) / [Go](go-version/agents/report_writer.go) |

### 5. Compliance Agent（合规审查Agent）

| 项目 | 说明 |
|------|------|
| **职责** | 检查报告合规性 |
| **检查项** | 免责声明、数据引用、监管合规、偏见检查、前瞻性声明 |
| **输出** | ComplianceReport（合规评分 + 问题列表） |
| **特点** | Pipeline最后一步，确保报告可对外发布 |
| **代码** | [Python](python-version/agents/compliance_agent.py) / [Java](java-version/src/main/java/com/finreport/agents/ComplianceAgent.java) / [Go](go-version/agents/compliance.go) |

---

## 核心代码解读

### 并行编排 - 项目最核心的代码

这是面试中100%会被问到的代码，三种语言各有不同的实现：

**Python - asyncio.gather()**
```python
# orchestrator.py 核心代码
collected_data, sentiment = await asyncio.gather(
    self.data_collector.execute(query),    # Agent 1
    self.sentiment_agent.execute(query),   # Agent 2
)
# 总延迟 = max(Agent1时间, Agent2时间)
```

**Java - CompletableFuture.allOf()**
```java
// ReportOrchestrator.java 核心代码
CompletableFuture<CollectedData> dataFuture =
    CompletableFuture.supplyAsync(() -> dataCollector.execute(query));
CompletableFuture<SentimentAnalysis> sentimentFuture =
    CompletableFuture.supplyAsync(() -> sentimentAgent.execute(query));

CompletableFuture.allOf(dataFuture, sentimentFuture).join();
```

**Go - goroutine + WaitGroup**
```go
// orchestrator.go 核心代码
var wg sync.WaitGroup
wg.Add(2)

go func() {
    defer wg.Done()
    collectedData, dataErr = o.dataCollector.Execute(query)
}()
go func() {
    defer wg.Done()
    sentiment, sentimentErr = o.sentiment.Execute(query)
}()

wg.Wait()
```

> 更详细的代码讲解请看 [docs/code-walkthrough.md](docs/code-walkthrough.md)

---

## 面试准备材料

本项目配套了完整的面试准备材料，建议按以下顺序阅读：

| 序号 | 文档 | 内容 | 预计时间 | 链接 |
|------|------|------|---------|------|
| 1 | **面试完全指南** | 从零开始的准备路线图 | 15分钟 | [docs/interview-guide.md](docs/interview-guide.md) |
| 2 | **简历模板** | 中英文简历写法，含量化指标 | 15分钟 | [docs/resume-template.md](docs/resume-template.md) |
| 3 | **STAR法回答** | 8个核心问题的STAR法回答 | 1小时 | [docs/star-method.md](docs/star-method.md) |
| 4 | **八股文** | 12个多Agent核心知识点 | 1小时 | [docs/baguwen.md](docs/baguwen.md) |
| 5 | **代码讲解** | 逐行讲解核心代码 | 30分钟 | [docs/code-walkthrough.md](docs/code-walkthrough.md) |
| 6 | **架构解析** | 架构设计深度解读 | 30分钟 | [docs/architecture-deep-dive.md](docs/architecture-deep-dive.md) |
| 7 | **常见问题** | 35+面试问题+标准答案 | 1小时 | [docs/common-questions.md](docs/common-questions.md) |

**总准备时间：约4-5小时**

---

## 技术栈详解

### Python版本

| 技术 | 用途 | 为什么选它 |
|------|------|-----------|
| asyncio | 异步并行编排 | Python原生，轻量高效 |
| LangChain + OpenAI | LLM调用 | 生态最成熟 |
| yfinance | 股票数据 | 免费，API简单 |
| Tavily | 新闻搜索 | 为AI优化的搜索API |
| Pydantic v2 | 数据模型 | 类型安全，自动验证 |
| ReportLab | PDF生成 | Python最常用的PDF库 |
| tenacity | 重试机制 | 装饰器模式，简洁 |
| Rich | 终端美化 | 漂亮的进度条和输出 |

### Java版本

| 技术 | 用途 | 为什么选它 |
|------|------|-----------|
| Spring Boot 3 | Web框架 | 企业级标准 |
| Spring AI | LLM集成 | Spring生态原生 |
| CompletableFuture | 异步并行 | Java 8+标准API |
| OkHttp | HTTP客户端 | 高性能，连接池 |
| Jackson | JSON处理 | Spring默认 |
| Lombok | 减少样板代码 | @Data, @Builder |
| iText | PDF生成 | Java最常用 |

### Go版本

| 技术 | 用途 | 为什么选它 |
|------|------|-----------|
| goroutine | 并行编排 | Go原生，最轻量 |
| sync.WaitGroup | 协调并发 | 标准库 |
| go-openai | LLM调用 | 社区最活跃 |
| net/http | HTTP请求 | 标准库够用 |
| encoding/json | JSON序列化 | 标准库 |

---

## 项目结构

```
multi-agent-financial-report/
│
├── README.md                              ← 你正在看的文件
├── plan.md                                ← 项目计划文档
├── .gitignore                             ← Git忽略配置
├── .env.example                           ← 环境变量模板
│
├── python-version/                        ← Python完整实现
│   ├── README.md                          ← Python版说明
│   ├── requirements.txt                   ← Python依赖
│   ├── main.py                            ← 入口文件
│   ├── orchestrator.py                    ← 编排器（核心）
│   ├── agents/                            ← 5个Agent
│   │   ├── data_collector.py
│   │   ├── sentiment_agent.py
│   │   ├── market_analyst.py
│   │   ├── report_writer.py
│   │   └── compliance_agent.py
│   ├── tools/                             ← 数据源工具
│   │   ├── yahoo_finance_tool.py
│   │   ├── news_tool.py
│   │   └── sec_edgar_tool.py
│   ├── models/                            ← Pydantic数据模型
│   │   └── report_schema.py
│   └── tests/                             ← 单元测试
│       └── test_agents.py
│
├── java-version/                          ← Java完整实现
│   ├── README.md
│   ├── pom.xml                            ← Maven配置
│   └── src/main/java/com/finreport/
│       ├── FinReportApplication.java      ← Spring Boot启动类
│       ├── controller/                    ← REST API
│       ├── orchestrator/                  ← 编排器
│       ├── agents/                        ← 5个Agent
│       ├── tools/                         ← 数据源工具
│       ├── models/                        ← 数据模型
│       └── config/                        ← 配置类
│
├── go-version/                            ← Go完整实现
│   ├── README.md
│   ├── go.mod
│   ├── main.go                            ← 入口文件
│   ├── orchestrator/                      ← 编排器
│   ├── agents/                            ← 5个Agent
│   └── models/                            ← 数据结构
│
├── docs/                                  ← 面试全套材料
│   ├── interview-guide.md                 ← 面试完全指南
│   ├── resume-template.md                 ← 简历模板
│   ├── star-method.md                     ← STAR法回答
│   ├── baguwen.md                         ← 八股文
│   ├── code-walkthrough.md                ← 代码讲解
│   ├── architecture-deep-dive.md          ← 架构解析
│   └── common-questions.md                ← 常见问题35+
│
└── assets/                                ← 图片资源
```

---

## 常见问题FAQ

### Q: 没有OpenAI API Key能运行吗？

可以。所有Agent都有降级（fallback）逻辑。没有API Key时会使用模拟数据，你仍然可以看到完整的Pipeline执行流程和输出格式。

### Q: 这个项目适合什么水平的人？

面向有基础编程能力的求职者。你需要了解：
- 至少一种语言（Python/Java/Go）的基本语法
- 基本的HTTP/API概念
- 基本的异步/并发概念

### Q: 可以用国产LLM吗？

可以。代码中通过环境变量切换LLM提供商。支持任何兼容OpenAI API格式的模型，包括MiniMax、文心一言、通义千问等。

### Q: 数据是实时的吗？

Yahoo Finance和SEC EDGAR是实时数据。新闻搜索（Tavily）也是实时的。技术指标基于实时股价计算。

### Q: 可以分析A股吗？

当前版本主要支持美股。分析A股需要替换数据源（如Tushare/Wind），合规规则改为证监会标准。架构设计上已经预留了扩展点。

---

## 参考资料

### 企业级多Agent框架

- [LangGraph](https://github.com/langchain-ai/langgraph) - 有向图/状态机编排（~28K stars）
- [CrewAI](https://github.com/crewAIInc/crewAI) - 角色扮演+班组编排（~48K stars）
- [AutoGen](https://github.com/microsoft/autogen) - 微软对话式多Agent（~57K stars）
- [MetaGPT](https://github.com/FoundationAgents/MetaGPT) - 软件公司隐喻（~67K stars）
- [Spring AI](https://github.com/spring-projects/spring-ai) - Java AI框架（~8K stars）
- [Google ADK Go](https://github.com/google/adk-go) - Go Agent框架（~7K stars）

### 金融AI项目

- [FinRobot](https://github.com/AI4Finance-Foundation/FinRobot) - 金融分析多Agent
- [FinGPT](https://github.com/AI4Finance-Foundation/FinGPT) - 开源金融LLM

### 学习资源

- [LangChain 文档](https://python.langchain.com/)
- [Spring AI 文档](https://docs.spring.io/spring-ai/reference/)
- [Go ADK 文档](https://google.github.io/adk-docs/)

---

## License

MIT License - 可自由使用、修改和分发。

---

**如果这个项目对你有帮助，请给一个 Star！**