cillin/evotraders
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/check-dev
evotraders/CLAUDE.md
cillin 16bb3c4211 docs(README): 更新项目说明文档，完善架构与启动指南 
- 调整 CLAUDE.md 内容，增加使用指导和架构概览
- 补充微服务启动说明及单服务启动命令
- 明确 Gateway 服务器四阶段启动流程和职责划分
- 细化后端目录结构说明，补充主要文件职责描述
- 新增系统分层结构图，优化整体架构理解
- 更新 .gitignore，添加 runs 目录忽略规则
- 同步 .omc 相关状态文件，更新项目状态跟踪信息
2026-03-24 17:19:31 +08:00

379 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
## 项目概述
EvoTraders 是一个自进化多智能体交易系统，由 6 个 AI Agent（4 名分析师 + 投资经理 + 风控经理）协作完成交易决策。Agent 基于 AgentScope 框架构建，配合 ReMe 记忆系统实现持续学习。
## 常用命令
### Backend (Python)
```bash
# 安装依赖
uv pip install -e .
# 运行命令
evotraders backtest --start 2025-11-01 --end 2025-12-01 # 回测模式
evotraders backtest --start 2025-11-01 --end 2025-12-01 --enable-memory # 带记忆回测
evotraders live # 实盘交易
evotraders live --mock # 模拟/测试模式
evotraders live -t 22:30 # 定时每日交易
evotraders frontend # 启动可视化界面
# 开发服务器
./start-dev.sh # 启动全部 4 个微服务 (agent, runtime, trading, news)
# Gateway WebSocket 服务器
python backend/main.py --mode live --config-name mock --mock
# 单独启动微服务
python -m uvicorn backend.apps.runtime_service:app --host 0.0.0.0 --port 8003 --reload
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
# 测试
pytest backend/tests # 运行全部测试
pytest backend/tests/test_news_service_app.py -v # 运行单个测试
```
### Frontend (React)
```bash
cd frontend
npm run dev # Vite 开发服务器 (http://localhost:5173)
npm run build # 生产构建
npm run lint # ESLint 检查
npm run lint:fix # ESLint 自动修复
npm run test # Vitest 单元测试
```
## 架构概览
### 系统分层
```
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React) │
│ WebSocket ws://localhost:8765 连接 Gateway │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Gateway (backend/services/gateway.py) │
│ WebSocket 服务器，编排 Pipeline，4 阶段启动 │
└─────────────────────────────────────────────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ Market │ │ Storage │ │ Pipeline │ │ Scheduler │
│ Service │ │ Service │ │ │ │ │
└────────────┘ └────────────┘ └────────────┘ └────────────┘
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Analysts │ │ PM │ │ Risk │
│ (4 个) │ │ │ │ Manager │
└──────────┘ └──────────┘ └──────────┘
```
### 微服务架构 (`backend/apps/`)
| 服务 | 端口 | 职责 |
|------|------|------|
| runtime_service | 8003 | 运行时配置、任务启动、Pipeline Runner |
| agent_service | 8000 | Agent 生命周期、工作区管理 |
| trading_service | 8001 | 市场数据、交易操作 |
| news_service | 8002 | 新闻、新闻富化、解释功能 |
### Gateway 4 阶段启动 (`backend/services/gateway.py`)
1. **WebSocket Server** - 前端立即可连接
2. **Market Service** - 价格数据开始推送
3. **Market Status Monitor** - 市场状态监控
4. **Scheduler** - 交易周期开始
### 运行时管理层 (`backend/runtime/`)
| 文件 | 职责 |
|------|------|
| `manager.py` | TradingRuntimeManager - 全局运行时管理器，agent 注册、会话、事件快照 |
| `agent_runtime.py` | AgentRuntimeState - 单 agent 状态（status、last_session） |
| `context.py` | TradingRunContext - 运行上下文 |
| `session.py` | TradingSessionKey - 交易日会话键 |
| `registry.py` | RuntimeRegistry - agent 状态注册表 |
快照持久化到 `runs/<run_id>/state/runtime_state.json`。
### Pipeline 执行 (`backend/core/`)
| 文件 | 职责 |
|------|------|
| `pipeline.py` | TradingPipeline - 核心编排器（分析→沟通→决策→执行→评估） |
| `pipeline_runner.py` | REST API 触发的独立执行，5 阶段启动 |
| `scheduler.py` | BacktestScheduler、Scheduler - 回测/实盘调度 |
| `state_sync.py` | StateSync - 状态同步和广播 |
## 后端结构
```
backend/
├── agents/ # 多智能体实现
│ ├── analyst.py # AnalystAgent 基类
│ ├── portfolio_manager.py # PMAgent 投资经理
│ ├── risk_manager.py # RiskAgent 风控经理
│ ├── factory.py # Agent 实例工厂
│ ├── toolkit_factory.py # 工具集工厂
│ ├── skills_manager.py # 技能加载管理
│ ├── workspace_manager.py # 工作区管理
│ ├── skill_loader.py # 技能加载器
│ ├── agent_workspace.py # Agent 工作区
│ ├── prompt_loader.py # Prompt 加载器
│ ├── prompt_factory.py # Prompt 工厂
│ ├── skill_metadata.py # 技能元数据
│ ├── registry.py # Agent 注册表
│ ├── team_pipeline_config.py # 团队 Pipeline 配置
│ ├── compat.py # 兼容性层
│ ├── templates.py # 模板
│ ├── workspace.py # 工作区
│ ├── base/ # 核心类、Hooks
│ │ ├── evo_agent.py # 基于 AgentScope 的核心实现
│ │ └── hooks.py # 生命周期 Hooks
│ └── prompts/ # Agent 提示词
│ └── analyst/personas.yaml
│
├── apps/ # 微服务入口
│ ├── runtime_service.py # 运行时服务（端口 8003）
│ ├── agent_service.py # Agent 服务（端口 8000）
│ ├── trading_service.py # 交易服务（端口 8001）
│ ├── news_service.py # 新闻服务（端口 8002）
│ └── cors.py
│
├── runtime/ # 运行时管理层
│ ├── manager.py # TradingRuntimeManager
│ ├── agent_runtime.py # AgentRuntimeState
│ ├── context.py # TradingRunContext
│ ├── session.py # TradingSessionKey
│ └── registry.py # RuntimeRegistry
│
├── process/ # 进程监管层
│ ├── supervisor.py # ProcessSupervisor
│ ├── registry.py # RunRegistry
│ └── models.py # ProcessRun、ProcessRunState
│
├── core/ # Pipeline 执行
│ ├── pipeline.py # TradingPipeline（核心编排器）
│ ├── pipeline_runner.py # 独立 Pipeline 执行
│ ├── scheduler.py # 调度器
│ └── state_sync.py # 状态同步
│
├── services/ # Gateway 和服务
│ ├── gateway.py # WebSocket 网关
│ ├── gateway_*.py # Gateway 子模块
│ ├── market.py # 市场数据服务
│ ├── storage.py # 存储服务
│ ├── runtime_db.py # 运行时数据库
│ └── research_db.py # 研究数据库
│
├── data/ # 市场数据处理
│ ├── provider_router.py # 数据源路由
│ ├── provider_utils.py # 数据源工具
│ ├── market_store.py # 市场数据存储
│ ├── market_ingest.py # 数据采集
│ ├── cache.py # 缓存
│ ├── schema.py # 数据 schema
│ ├── historical_price_manager.py # 历史价格管理
│ ├── polling_price_manager.py # 轮询价格管理
│ ├── mock_price_manager.py # Mock 价格管理
│ ├── news_alignment.py # 新闻对齐
│ ├── polygon_client.py # Polygon.io 客户端
│ └── ret_data_updater.py # 离线数据更新
│
├── config/ # 配置
│ ├── constants.py # Agent 配置、显示名称
│ ├── bootstrap_config.py # 启动配置解析
│ ├── env_config.py # 环境变量配置
│ ├── data_config.py # 数据源配置
│ └── agent_profiles.yaml # Agent Profile 配置
│
├── domains/ # 领域业务逻辑
│ ├── news.py
│ └── trading.py
│
├── llm/ # LLM 集成
│ └── models.py # RetryChatModel、TokenRecordingModelWrapper
│
├── skills/ # 技能定义
├── tools/ # 交易和分析工具
├── enrich/ # LLM 响应富化
├── explain/ # 交易决策解释
├── utils/ # 工具函数
│ ├── settlement.py # 结算协调器
│ ├── trade_executor.py # 交易执行器
│ ├── terminal_dashboard.py # 终端仪表板
│ ├── analyst_tracker.py # 分析师追踪
│ ├── baselines.py # 基准线
│ ├── msg_adapter.py # 消息适配器
│ └── progress.py # 进度追踪
│
├── api/ # FastAPI 端点
│ └── runtime.py
│
└── main.py # 主入口点
```
## 前端结构
```
frontend/src/
├── App.jsx # 主应用（LiveTradingApp）
├── AppShell.jsx # App 外壳（布局、侧边栏）
├── components/
│ ├── RuntimeView.jsx # 交易运行时 UI
│ ├── TraderView.jsx # 交易员界面
│ ├── RoomView.jsx # 聊天室视图
│ ├── StockExplainView.jsx # 股票解释视图
│ ├── RuntimeSettingsPanel.jsx # 运行时设置面板
│ ├── RuntimeLogsModal.jsx # 运行时日志弹窗
│ ├── WatchlistPanel.jsx # 关注列表
│ ├── PerformanceView.jsx # 绩效视图
│ ├── StatisticsView.jsx # 统计视图
│ ├── NetValueChart.jsx # 净值曲线图
│ ├── AgentCard.jsx # Agent 卡片
│ ├── AgentFeed.jsx # Agent 动态
│ ├── Header.jsx # 头部
│ ├── MarkdownModal.jsx # Markdown 弹窗
│ ├── StockLogo.jsx # 股票 Logo
│ └── explain/ # 解释组件
│ ├── ExplainNewsSection.jsx
│ ├── ExplainRangeSection.jsx
│ ├── ExplainSimilarDaysSection.jsx
│ ├── ExplainStorySection.jsx
│ └── useExplainModel.js
├── hooks/ # React Hooks
│ ├── useWebSocketConnection.js # WebSocket 连接管理
│ ├── useRuntimeControls.js # 运行时配置管理
│ ├── useAgentDataRequests.js # Agent 数据请求
│ ├── useStockDataRequests.js # 股票数据请求
│ ├── useStockExplainData.js # 股票解释数据
│ ├── useAgentWorkspacePanel.js # Agent 工作区面板
│ ├── useWebsocketSessionSync.js # WebSocket 会话同步
│ └── useFeedProcessor.js # Feed 事件处理
├── store/ # Zustand 状态管理
│ ├── runtimeStore.js # 连接状态、运行时配置
│ ├── marketStore.js # 市场数据、股票价格
│ ├── portfolioStore.js # 组合、持仓、交易
│ ├── agentStore.js # Agent 技能、工作区
│ └── uiStore.js # UI 状态、视图切换
├── services/
│ ├── websocket.js # WebSocket 客户端
│ ├── runtimeApi.js # 运行时 API
│ ├── runtimeControls.js # 运行时控制
│ ├── newsApi.js # 新闻 API
│ └── tradingApi.js # 交易 API
├── utils/
│ ├── formatters.js # 格式化工具
│ └── modelIcons.js # 模型图标
└── config/
└── constants.js # Agent 定义、配置
```
## Agent 系统
### 6 种 Agent 角色
| 角色 ID | 名称 | 职责 |
|---------|------|------|
| `fundamentals_analyst` | 基本面分析师 | 财务健康、盈利能力、成长质量 |
| `technical_analyst` | 技术分析师 | 价格趋势、技术指标、动量分析 |
| `sentiment_analyst` | 情绪分析师 | 市场情绪、新闻情绪、内幕交易 |
| `valuation_analyst` | 估值分析师 | DCF、EV/EBITDA、intrinsic value |
| `portfolio_manager` | 投资经理 | 决策执行、交易协调 |
| `risk_manager` | 风控经理 | 实时价格/波动率监控、仓位限制 |
### 添加自定义分析师
1. `backend/agents/prompts/analyst/personas.yaml` 注册
2. `backend/config/constants.py` 的 `ANALYST_TYPES` 字典添加
3. `frontend/src/config/constants.js` 可选更新
### LLM 模型封装 (`backend/llm/models.py`)
- **RetryChatModel**: 自动重试瞬态 LLM 错误，指数退避
- **TokenRecordingModelWrapper**: 追踪 token 消耗和成本
## 技能系统 (`backend/skills/`)
技能定义在 `SKILL.md`，包含 `instructions`、`triggers`、`parameters`、`available_tools`。
技能管理器支持 6 种作用域：builtin、customized、installed、active、disabled、local。
## 运行时数据布局
- `data/market_research.db` - 持久研究数据
- `runs/<run_id>/` - 每次任务运行的状态
- `runs/<run_id>/team_dashboard/*.json` - 仪表板导出层（非权威源）
- `runs/<run_id>/state/runtime_state.json` - 运行时快照
- 运行时 API 优先使用 `server_state.json` 和 `runtime.db`
```bash
RUNS_RETENTION_COUNT=20 # 时间戳格式文件夹自动清理
```
## 环境配置
### Backend (`env.template`)
```bash
# 金融数据源（支持多源fallback）
FIN_DATA_SOURCE=finnhub|financial_datasets|yfinance|local_csv
ENABLED_DATA_SOURCES=financial_datasets,finnhub,yfinance,local_csv
FINANCIAL_DATASETS_API_KEY= # 回测必需
FINNHUB_API_KEY= # 实盘必需
POLYGON_API_KEY= # Polygon市场库采集可选
# LLM 配置
OPENAI_API_KEY=
OPENAI_BASE_URL=
MODEL_NAME=qwen3-max-preview
# Agent 特定模型
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
# ReMe 记忆系统
MEMORY_API_KEY=
MEMORY_MODEL_NAME=qwen3-max
MEMORY_EMBEDDING_MODEL=text-embedding-v4
# 交易参数
MAX_COMM_CYCLES=2
MARGIN_REQUIREMENT=0.5
DATA_START_DATE=2022-01-01
AUTO_UPDATE_DATA=true
```
### Frontend (`frontend/env.template`)
```bash
VITE_WS_URL=ws://localhost:8765
```
## 关键依赖
- **AgentScope** - 多智能体框架
- **ReMe** - 持续学习记忆系统
- **FastAPI** + **uvicorn** - 后端 API
- **websockets** - 实时通信
- **React 19** + **Vite** + **TailwindCSS** - 前端
- **Zustand** - 状态管理
Reference in New Issue View Git Blame Copy Permalink