Initial commit of integrated agent system
This commit is contained in:
cillin
359
README_zh.md
Normal file
359
README_zh.md
Normal file
@@ -0,0 +1,359 @@
|
||||
<p align="center">
|
||||
<img src="./docs/assets/bigtime_logo.jpg" width="45%">
|
||||
</p>
|
||||
|
||||
<h2 align="center">大时代：自进化多智能体交易系统</h2>
|
||||
|
||||
<p align="center">
|
||||
📌 <a href="http://trading.evoagents.cn">访问大时代官网</a>
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
大时代 是一个开源的金融交易智能体框架，结合多智能体协作、run 级工作区和记忆机制，支持回测与实盘两类交易运行模式。
|
||||
|
||||
---
|
||||
|
||||
## 核心特性
|
||||
|
||||
**多智能体交易团队**
|
||||
系统默认包含 6 个角色：4 个分析师（基本面、技术面、情绪、估值）+ 投资经理 + 风控经理。
|
||||
|
||||
**持续学习**
|
||||
可选接入 ReMe 长期记忆，智能体会在每轮结束后反思、复盘并沉淀经验。
|
||||
|
||||
**统一运行时**
|
||||
同一套运行时模型支持历史回测和实时行情驱动的实盘流程。
|
||||
|
||||
**可操作前端**
|
||||
前端不只是展示层，还包含交易室、运行控制、日志、审批、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
|
||||
# 克隆仓库后进入项目目录
|
||||
cd evotraders
|
||||
|
||||
# 安装后端运行时依赖
|
||||
uv pip install -r requirements.txt
|
||||
|
||||
# 安装项目入口（可编辑模式）
|
||||
uv pip install -e .
|
||||
|
||||
# 可选
|
||||
# uv pip install -e ".[dev]"
|
||||
# pip install -e .
|
||||
```
|
||||
|
||||
前端依赖：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm ci
|
||||
cd ..
|
||||
```
|
||||
|
||||
生产环境部署建议后端使用 `requirements.txt`，前端使用 `npm ci`，这样拉起的环境会严格跟随仓库中锁定的依赖版本。
|
||||
|
||||
### 2. 配置环境变量
|
||||
|
||||
```bash
|
||||
cp env.template .env
|
||||
```
|
||||
|
||||
根目录 `env.template` 是当前本地开发的主模板，仓库里也保留了 `.env.example` 作为参考。
|
||||
|
||||
最常用的配置项：
|
||||
|
||||
```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
|
||||
|
||||
# 长期记忆（只有启用 --enable-memory 才需要）
|
||||
MEMORY_API_KEY=
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- live 模式必须配置 `FINNHUB_API_KEY`
|
||||
- `POLYGON_API_KEY` 用于长期 market store 的补数和刷新
|
||||
- `MEMORY_API_KEY` 仅在启用长期记忆时需要
|
||||
|
||||
如果要用更接近生产的本地启动方式，也可以直接执行：
|
||||
|
||||
```bash
|
||||
./start.sh
|
||||
```
|
||||
|
||||
### 3. 启动服务栈
|
||||
|
||||
本地开发推荐直接使用：
|
||||
|
||||
```bash
|
||||
./start-dev.sh
|
||||
```
|
||||
|
||||
该脚本会启动：
|
||||
|
||||
- `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
|
||||
RUNS_RETENTION_COUNT=20
|
||||
```
|
||||
|
||||
只有形如 `YYYYMMDD_HHMMSS` 的时间戳目录会被自动清理；`live`、`smoke_fullstack`、`reload_demo_*` 这类命名 run 会保留。
|
||||
|
||||
---
|
||||
|
||||
## 前端服务路由
|
||||
|
||||
前端始终会使用 control plane 和 runtime API，同时可以选择直连拆分服务读取只读数据。
|
||||
|
||||
常用前端环境变量：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
如果不配置，前端会按本地默认值和兼容回退逻辑运行。
|
||||
|
||||
---
|
||||
|
||||
## 决策流程
|
||||
|
||||
```text
|
||||
市场数据 -> 分析师独立分析 -> 团队沟通 -> 投资决策 ->
|
||||
风控审核 -> 执行/结算 -> 复盘/记忆更新
|
||||
```
|
||||
|
||||
运行时管理器还会跟踪：
|
||||
|
||||
- agent 注册和状态
|
||||
- 待审批项
|
||||
- run 事件
|
||||
- 当前 session key
|
||||
|
||||
---
|
||||
|
||||
## 自定义配置
|
||||
|
||||
### 新增或修改分析师角色
|
||||
|
||||
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:
|
||||
- multi-factor synthesis
|
||||
preferred_tools:
|
||||
- get_stock_price
|
||||
- get_company_financials
|
||||
description: |
|
||||
A generalist analyst that combines multiple signals.
|
||||
```
|
||||
|
||||
### 配置各 Agent 使用的模型
|
||||
|
||||
模型覆盖在 `.env` 中配置：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
初始化一个 run 工作区：
|
||||
|
||||
```bash
|
||||
evotraders init-workspace --config-name my_run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
evotraders/
|
||||
├── backend/
|
||||
│ ├── 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 许可与免责
|
||||
|
||||
大时代 是研究和教育用途项目。再次分发或商用前，请先核对仓库中的实际 license 文件。
|
||||
|
||||
**风险提示**：本项目不构成投资建议。任何实盘部署前都应进行充分测试和风险评估，历史表现不代表未来收益。
|
||||
Reference in New Issue
Block a user