chore: sync current workspace changes

This commit is contained in:
2026-03-27 11:27:26 +08:00
parent 6ecc224427
commit 5c08c1865c
33 changed files with 1450 additions and 724 deletions

View File

@@ -4,291 +4,337 @@
<h2 align="center">EvoTraders自我进化的多智能体交易系统</h2>
<p align="center">
📌 <a href="http://trading.evoagents.cn">Visit us at EvoTraders website !</a>
📌 <a href="http://trading.evoagents.cn">访问 EvoTraders 官网</a>
</p>
![系统演示](./docs/assets/evotraders_demo.gif)
EvoTraders是一个开源的金融交易智能体框架通过多智能体协作和记忆系统,构建能够在真实市场中持续学习与进化的交易系统
EvoTraders 是一个开源的金融交易智能体框架,结合多智能体协作、run 级工作区和记忆机制,支持回测与实盘两类交易运行模式
---
## 核心特性
**多智能体协作交易**
6名成员包含4种专业分析师角色(基本面、技术面、情绪、估值)+ 投资组合经理 + 风险管理,像真实交易团队一样协作决策
**多智能体交易团队**
系统默认包含 6 个角色4 个分析师(基本面、技术面、情绪、估值)+ 投资经理 + 风控经理
你可以在这里自定义你的Agents支持配置不同大模型如 Qwen、DeepSeek、GPT、Claude等协同分析[自定义配置](#自定义配置)
**持续学习**
可选接入 ReMe 长期记忆,智能体会在每轮结束后反思、复盘并沉淀经验。
**持续学习与进化**
基于 ReMe 记忆框架,智能体在每次交易后反思总结,跨回合保留经验,形成独特的投资方法论
通过这样的设计,我们希望当 AI Agents 组成团队进入实时市场,它们会逐渐形成自己的交易风格和决策偏好,而不是一次性的随机推理
**实时市场交易**
支持实时行情接入,提供回测模式和实盘模式,让 AI Agents 在真实市场波动中学习和决策。
**可视化交易信息**
实时观察 Agents 的分析过程、沟通记录和决策演化,完整追踪收益曲线和分析师表现。
**统一运行时**
同一套运行时模型支持历史回测和实时行情驱动的实盘流程
**可操作前端**
前端不只是展示层还包含交易室、运行控制、日志、审批、Agent 工作区和 explain/news 视图。
<p>
<img src="docs/assets/performance.jpg" width="45%">
<img src="./docs/assets/dashboard.jpg" width="45%">
</p>
---
## 当前架构
仓库目前处于“模块化单体 -> 拆分服务”的迁移阶段,本地开发默认走 split-service 路径。
当前 app surface
- `backend.apps.agent_service`,端口 `8000`:控制面,负责 workspaces、agents、skills、审批接口
- `backend.apps.trading_service`,端口 `8001`:只读交易数据接口
- `backend.apps.news_service`,端口 `8002`:只读 explain/news 接口
- `backend.apps.runtime_service`,端口 `8003`:运行时生命周期接口
- `backend.apps.openclaw_service`,端口 `8004`:只读 OpenClaw facade
- WebSocket gateway端口 `8765`:前端实时事件和 feed 通道
当前最关键的主链路是:
`frontend -> runtime_service/control APIs -> gateway/runtime manager -> market service + pipeline + storage`
迁移背景可参考 [services/README.md](./services/README.md)。
---
## 快速开始
### 安装
### 1. 安装
```bash
# 克隆仓库
git clone https://github.com/agentscope-ai/agentscope-samples
cd agentscope-samples/EvoTraders
# 克隆仓库后进入项目目录
cd evotraders
# 安装依赖(推荐使用uv
# 推荐
uv pip install -e .
# (可选pip install -e .
# 配置环境变量
# 可选
# uv pip install -e ".[dev]"
# pip install -e .
```
### 2. 配置环境变量
```bash
cp env.template .env
# 编辑 .env 文件,添加你的 API Keys,以下的配置项为必填项
```
# finance data API:至少需要FINANCIAL_DATASETS_API_KEY对应FIN_DATA_SOURCE=financial_datasets推荐添加FINNHUB_API_KEY对应至少需要FINANCIAL_DATASETS_API_KEY对应FIN_DATA_SOURCE填为finnhub;如果使用live 模式必须添加FINNHUB_API_KEY
FIN_DATA_SOURCE= #finnhub or financial_datasets
FINANCIAL_DATASETS_API_KEY= #必需
FINNHUB_API_KEY= #可选
根目录 `env.template` 是当前本地开发的主模板,仓库里也保留了 `.env.example` 作为参考。
# LLM API for Agents
最常用的配置项:
```bash
# 自选股
TICKERS=AAPL,MSFT,GOOGL,NVDA,TSLA,META,AMZN
# 行情数据
FIN_DATA_SOURCE=finnhub
FINANCIAL_DATASETS_API_KEY=
FINNHUB_API_KEY=
POLYGON_API_KEY=
# Agent 模型
OPENAI_API_KEY=
OPENAI_BASE_URL=
MODEL_NAME=qwen3-max-preview
# LLM & embedding API for Memory
# 长期记忆(只有启用 --enable-memory 才需要)
MEMORY_API_KEY=
```
### 运行
说明:
- live 模式必须配置 `FINNHUB_API_KEY`
- `POLYGON_API_KEY` 用于长期 market store 的补数和刷新
- `MEMORY_API_KEY` 仅在启用长期记忆时需要
### 3. 启动服务栈
本地开发推荐直接使用:
**回测模式:**
```bash
evotraders backtest --start 2025-11-01 --end 2025-12-01
evotraders backtest --start 2025-11-01 --end 2025-12-01 --enable-memory # 使用记忆
./start-dev.sh
```
如果没有可用的行情 API想快速体验回测 demo可直接下载离线数据并解压到 `backend/data`
该脚本会启动
- `agent_service``http://localhost:8000`
- `trading_service``http://localhost:8001`
- `news_service``http://localhost:8002`
- `runtime_service``http://localhost:8003`
- gateway WebSocket`ws://localhost:8765`
然后在另一个终端启动前端:
```bash
evotraders frontend
```
访问 `http://localhost:5173`
也可以手动分别启动:
```bash
python -m uvicorn backend.apps.agent_service:app --host 0.0.0.0 --port 8000 --reload
python -m uvicorn backend.apps.trading_service:app --host 0.0.0.0 --port 8001 --reload
python -m uvicorn backend.apps.news_service:app --host 0.0.0.0 --port 8002 --reload
python -m uvicorn backend.apps.runtime_service:app --host 0.0.0.0 --port 8003 --reload
python -m backend.main --mode live --host 0.0.0.0 --port 8765
```
### 4. 使用 CLI 运行回测或实盘
回测:
```bash
evotraders backtest --start 2025-11-01 --end 2025-12-01
evotraders backtest --start 2025-11-01 --end 2025-12-01 --enable-memory
evotraders backtest --config-name smoke_fullstack --start 2025-11-01 --end 2025-12-01
```
实盘:
```bash
evotraders live
evotraders live --enable-memory
evotraders live --schedule-mode intraday --interval-minutes 60
evotraders live --trigger-time 22:30
```
帮助:
```bash
evotraders --help
evotraders backtest --help
evotraders live --help
evotraders frontend --help
```
### 离线回测数据
如果只是想快速体验回测,不依赖外部行情 API可以下载离线数据包并解压到 `backend/data`
```bash
wget "https://agentscope-open.oss-cn-beijing.aliyuncs.com/ret_data.zip"
unzip ret_data.zip -d backend/data
```
该压缩包提供基础的股票行情数据,解压后即可直接用于回测演示。
**实盘交易:**
---
## 运行时数据布局
- 长期研究数据保存在 `data/market_research.db`
- 每次 run 的状态写入 `runs/<run_id>/`
- `runs/<run_id>/BOOTSTRAP.md` 保存该 run 的 bootstrap 值和 prompt body
- `runs/<run_id>/state/runtime_state.json` 保存运行时快照
- `runs/<run_id>/team_dashboard/*.json` 主要是给 dashboard 用的兼容导出层,不是唯一真相源
可选保留策略:
```bash
evotraders live # 立即运行(默认)
evotraders live --enable-memory # 使用记忆
evotraders live --mock # Mock 模式(测试)
evotraders live -t 22:30 # 每天本地时间 22:30 运行(自动转换为 NYSE 时区)
evotraders live --schedule-mode intraday --interval-minutes 60 # 每隔 1 小时触发一次;仅交易时段执行交易,其他时段只分析
RUNS_RETENTION_COUNT=20
```
前端的“运行设置”面板也支持热更新 `schedule_mode``interval_minutes``max_comm_cycles`;其中 daily 模式时间当前按 NYSE/ET 配置
只有形如 `YYYYMMDD_HHMMSS` 的时间戳目录会被自动清理;`live``smoke_fullstack``reload_demo_*` 这类命名 run 会保留
**获取帮助:**
```bash
evotraders --help # 查看整体命令行帮助
evotraders backtest --help # 查看回测模式的参数说明
evotraders live --help # 查看实盘/Mock 运行的参数说明
```
---
**启动可视化界面:**
```bash
# 确保已安装 npm, 否则请安装:
# npm install
evotraders frontend # 默认连接 8765 端口, 你可以修改 ./frontend/env.local 中的地址从而修改端口号
```
## 前端服务路由
访问 `http://localhost:5173/` 查看交易大厅,选择日期并点击 Run/Replay 观察决策过程
前端始终会使用 control plane 和 runtime API同时可以选择直连拆分服务读取只读数据
### 迁移期服务边界说明
当前仓库正处于从模块化单体向独立服务迁移的阶段,当前默认开发路径已经切到独立 app surface
- `backend.apps.agent_service`
- `backend.apps.runtime_service`
- `backend.apps.trading_service`
- `backend.apps.news_service`
当前本地开发默认推荐直接运行拆分后的服务:
常用前端环境变量:
```bash
./start-dev.sh split
# 或分别手动启动
python -m uvicorn backend.apps.agent_service:app --port 8000 --reload
python -m uvicorn backend.apps.runtime_service:app --port 8003 --reload
python -m uvicorn backend.apps.trading_service:app --port 8001 --reload
python -m uvicorn backend.apps.news_service:app --port 8002 --reload
```
迁移期关键环境变量:
```bash
# 后端 Gateway 优先走独立服务读取
NEWS_SERVICE_URL=http://localhost:8002
TRADING_SERVICE_URL=http://localhost:8001
# 前端浏览器直连控制面 / 运行时面
VITE_CONTROL_API_BASE_URL=http://localhost:8000/api
VITE_RUNTIME_API_BASE_URL=http://localhost:8003/api/runtime
# 前端浏览器优先直连独立服务
VITE_NEWS_SERVICE_URL=http://localhost:8002
VITE_TRADING_SERVICE_URL=http://localhost:8001
VITE_WS_URL=ws://localhost:8765
```
目前前端已支持直连 `news-service` 的 explain 只读路径包括:
- runtime panel / gateway port 查询已可独立指向 `runtime-service`
- story
- similar days
- range explain
- news for date
- news categories
如果没有配置这些变量,系统会继续走当前保留的本地回退逻辑。
如果不配置,前端会按本地默认值和兼容回退逻辑运行。
---
## 系统架构
## 决策流程
![架构图](docs/assets/evotraders_pipeline.jpg)
### 智能体设计
**分析师团队:**
- **基本面分析师**:财务健康度、盈利能力、增长质量
- **技术分析师**:价格趋势、技术指标、动量分析
- **情绪分析师**:市场情绪、新闻舆情、内部人交易
- **估值分析师**DCF、剩余收益、EV/EBITDA
**决策层:**
- **投资组合经理**:整合来自分析师的分析信号,执行沟通策略,结合分析师和团队历史表现、近期投资记忆和长期投资经验,进行最终决策
- **风险管理**:实时价格与波动率监控、头寸限制,多层风险预警
### 决策流程
```
实时行情 → 独立分析 → 智能沟通 (1v1/1vN/NvN) → 决策执行 → 收益评估 → 学习与进化(记忆更新)
```text
市场数据 -> 分析师独立分析 -> 团队沟通 -> 投资决策 ->
风控审核 -> 执行/结算 -> 复盘/记忆更新
```
每个交易日经历五个阶段
1. **分析阶段**:各智能体基于各自工具和历史经验独立分析
2. **沟通阶段**:通过私聊、通知、会议等方式交换观点
3. **决策阶段**:投资组合经理综合判断,给出最终交易
4. **评估阶段**
- **业绩图表**: 追踪组合收益曲线 vs. 基准策略(等权、市值加权、动量)。用于评估整体策略有效性。
- **分析师排名**: 在 Trading Room 点击头像查看分析师表现(胜率、牛/熊市胜率)。用于了解哪些分析师提供最有价值的洞察。
- **统计数据**: 详细的持仓和交易历史。用于深入分析仓位管理和执行质量。
4. **复盘阶段**Agents 根据当日实际收益反思决策、总结经验,并存入 ReMe 记忆框架以持续改进
---
### 模块支持
- **智能体框架**[AgentScope](https://github.com/agentscope-ai/agentscope)
- **记忆系统**[ReMe](https://github.com/agentscope-ai/reme)
- **LLM 支持**OpenAI、DeepSeek、Qwen、Moonshot、Zhipu AI 等
运行时管理器还会跟踪
- agent 注册和状态
- 待审批项
- run 事件
- 当前 session key
---
## 自定义配置
### 自定义分析师角色
### 新增或修改分析师角色
1. 在 [./backend/agents/prompts/analyst/personas.yaml](./backend/agents/prompts/analyst/personas.yaml) 中注册角色信息,例如:
1. 在 [backend/agents/prompts/analyst/personas.yaml](./backend/agents/prompts/analyst/personas.yaml) 中定义 persona
2. 在 [backend/config/constants.py](./backend/config/constants.py) 中注册角色
3. 如有需要,在 [frontend/src/config/constants.js](./frontend/src/config/constants.js) 中补充前端展示元数据
示例:
```yaml
comprehensive_analyst:
name: "Comprehensive Analyst"
focus:
- ...
preferred_tools: # Flexibly select based on situation
- multi-factor synthesis
preferred_tools:
- get_stock_price
- get_company_financials
description: |
As a comprehensive analyst ...
A generalist analyst that combines multiple signals.
```
2. 在 [./backend/config/constants.py](./backend/config/constants.py) 添加角色定义
```python
ANALYST_TYPES = {
# 增加新的分析师
"comprehensive_analyst": {
"display_name": "Comprehensive Analyst",
"agent_id": "comprehensive_analyst",
"description": "Uses LLM to intelligently select analysis tools, performs comprehensive analysis",
"order": 15
}
}
```
### 配置各 Agent 使用的模型
3. 在前端配置 [./frontend/src/config/constants.js](./frontend/src/config/constants.js) 中引入新角色(可选)
```javascript
export const AGENTS = [
// 覆盖掉其中某一个agent
{
id: "comprehensive_analyst",
name: "Comprehensive Analyst",
role: "Comprehensive Analyst",
avatar: `${ASSET_BASE_URL}/...`,
colors: { bg: '#F9FDFF', text: '#1565C0', accent: '#1565C0' }
}
]
```
### 自定义模型
在 [.env](.env) 文件中配置不同智能体使用的模型:
模型覆盖在 `.env` 中配置:
```bash
AGENT_SENTIMENT_ANALYST_MODEL_NAME=qwen3-max-preview
AGENT_FUNDAMENTAL_ANALYST_MODEL_NAME=deepseek-chat
AGENT_TECHNICAL_ANALYST_MODEL_NAME=glm-4-plus
AGENT_VALUATION_ANALYST_MODEL_NAME=moonshot-v1-32k
AGENT_SENTIMENT_ANALYST_MODEL_NAME=deepseek-v3.2-exp
AGENT_TECHNICAL_ANALYST_MODEL_NAME=glm-4.6
AGENT_FUNDAMENTALS_ANALYST_MODEL_NAME=qwen3-max-preview
AGENT_VALUATION_ANALYST_MODEL_NAME=Moonshot-Kimi-K2-Instruct
AGENT_RISK_MANAGER_MODEL_NAME=qwen3-max-preview
AGENT_PORTFOLIO_MANAGER_MODEL_NAME=qwen3-max-preview
```
### 项目结构
### run 级 BOOTSTRAP 配置
每个 run 都可以通过 `runs/<run_id>/BOOTSTRAP.md` 覆盖默认值。该文件由 [backend/config/bootstrap_config.py](./backend/config/bootstrap_config.py) 解析front matter 可配置:
```yaml
tickers:
- AAPL
- MSFT
initial_cash: 100000
margin_requirement: 0.5
max_comm_cycles: 2
schedule_mode: daily
trigger_time: "09:30"
enable_memory: false
```
EvoTraders/
初始化一个 run 工作区:
```bash
evotraders init-workspace --config-name my_run
```
---
## 项目结构
```text
evotraders/
├── backend/
│ ├── agents/ # 智能体实现
│ ├── communication/ # 通信系统
│ ├── memory/ # 记忆系统 (ReMe)
│ ├── tools/ # 分析工具集
│ ├── servers/ # WebSocket 服务
── cli.py # CLI 入口
├── frontend/ # React 可视化界面
── logs_and_memory/ # 日志和记忆数据
│ ├── agents/ # agent 角色、prompts、skills、workspaces
│ ├── api/ # FastAPI 路由层
│ ├── apps/ # 拆分服务 app surface
│ ├── core/ # pipeline、scheduler、state sync
│ ├── runtime/ # runtime manager 和 agent runtime state
── services/ # gateway、market/storage/db 服务
│ └── cli.py # Typer CLI 入口
── frontend/ # React + Vite 前端
├── shared/ # 拆分服务共用 client 和 schema
├── runs/ # run 级状态和 dashboard 导出
├── data/ # 长期研究数据
└── services/README.md
```
---
## 测试
后端测试位于 `backend/tests`,覆盖 service app、shared client、domain、路由、enrichment、gateway 支撑模块和 runtime 支撑模块。
常用命令:
```bash
pytest
pytest backend/tests/test_runtime_service_app.py
pytest backend/tests/test_trading_service_app.py
```
前端测试:
```bash
cd frontend
npm test
```
---
## 许可与免责
EvoTraders 是一个研究和教育项目,采用 Apache 2.0 许可协议开源
EvoTraders 是研究和教育用途项目。再次分发或商用前,请先核对仓库中的实际 license 文件
**风险提示**在实际资金交易前,请务必进行充分测试和风险评估历史表现不代表未来收益,投资有风险,决策需谨慎
**风险提示**本项目不构成投资建议。任何实盘部署前都应进行充分测试和风险评估历史表现不代表未来收益。