feat: Refactor services architecture and update project structure
- Remove Docker-based microservices (docker-compose.yml, Makefile, Dockerfiles) - Update start-dev.sh to use backend.app:app entry point - Add shared schema and client modules for service communication - Add team coordination modules (messenger, registry, task_delegator, coordinator) - Add evaluation hooks and skill adaptation hooks - Add skill template and gateway server - Update frontend WebSocket URL configuration - Add explain components for insider and technical analysis Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
170
CLAUDE.md
Normal file
170
CLAUDE.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
EvoTraders is a self-evolving multi-agent trading system where 6 AI agents (4 analysts + portfolio manager + risk manager) collaborate to make trading decisions. Agents use the AgentScope framework with a ReMe memory system for continuous learning.
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Backend (Python)
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
uv pip install -e .
|
||||
|
||||
# Run commands
|
||||
evotraders backtest --start 2025-11-01 --end 2025-12-01 # Backtest mode
|
||||
evotraders backtest --start 2025-11-01 --end 2025-12-01 --enable-memory
|
||||
evotraders live # Live trading
|
||||
evotraders live --mock # Mock/testing mode
|
||||
evotraders live -t 22:30 # Scheduled daily trading
|
||||
evotraders frontend # Launch visualization UI
|
||||
|
||||
# Dev server (starts FastAPI on port 8000)
|
||||
./start-dev.sh
|
||||
# Or manually:
|
||||
python -m uvicorn backend.app:app --host 0.0.0.0 --port 8000 --reload --reload-dir backend
|
||||
|
||||
# Testing
|
||||
pytest backend/tests
|
||||
```
|
||||
|
||||
### Frontend (React)
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run dev # Vite dev server (http://localhost:5173)
|
||||
npm run build # Production build
|
||||
npm run lint # ESLint
|
||||
npm run test # Vitest
|
||||
npm run test:watch # Watch mode
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Multi-Agent System (`backend/agents/`)
|
||||
|
||||
**6 Agent Roles** (configured in `prompts/analyst/personas.yaml`):
|
||||
- **fundamentals_analyst** - Financial health, profitability, growth quality
|
||||
- **technical_analyst** - Price trends, indicators, momentum
|
||||
- **sentiment_analyst** - Market sentiment, news, insider trading
|
||||
- **valuation_analyst** - DCF, EV/EBITDA, intrinsic value
|
||||
- **portfolio_manager** - Decision execution, trade coordination
|
||||
- **risk_manager** - Real-time risk monitoring, position limits
|
||||
|
||||
**Key Agent Files**:
|
||||
- `base/evo_agent.py` - Core agent implementation extending AgentScope
|
||||
- `base/hooks.py` - Lifecycle hooks for agent execution (BootstrapHook, MemoryCompactionHook, HeartbeatHook, WorkspaceWatchHook)
|
||||
- `base/evaluation_hook.py` - Post-execution evaluation
|
||||
- `base/skill_adaptation_hook.py` - Dynamic skill adaptation
|
||||
- `factory.py` - Agent factory for creating agent instances
|
||||
- `skills_manager.py` - Skill loading and management (6 scopes: builtin/customized/installed/active/disabled/local)
|
||||
- `toolkit_factory.py` - Tool collection factory for agents
|
||||
- `team/` - Team coordination (registry, coordinator, messenger, task_delegator)
|
||||
|
||||
**Hook System** (`base/hooks.py`):
|
||||
- **MemoryCompactionHook**: 基于 CoPaw 设计的内存压缩，支持:
|
||||
- `memory_compact_ratio`: 压缩目标比例 (默认 0.75)
|
||||
- `memory_reserve_ratio`: 保留比例 (默认 0.1)
|
||||
- `enable_tool_result_compact`: 工具结果压缩
|
||||
- `tool_result_compact_keep_n`: 保留最近 N 条工具结果
|
||||
|
||||
**Adding Custom Analysts**:
|
||||
1. Register in `backend/agents/prompts/analyst/personas.yaml`
|
||||
2. Add to `ANALYST_TYPES` dict in `backend/config/constants.py`
|
||||
3. Optionally update frontend config in `frontend/src/config/constants.js`
|
||||
|
||||
### Backend Structure
|
||||
|
||||
```
|
||||
backend/
|
||||
├── agents/ # Multi-agent implementation
|
||||
│ ├── base/ # Base classes, hooks, evaluation
|
||||
│ ├── prompts/ # Agent prompts and personas
|
||||
│ └── team/ # Team coordination logic
|
||||
├── api/ # FastAPI endpoints
|
||||
├── config/ # Constants and configuration
|
||||
├── core/ # Pipeline execution logic
|
||||
├── data/ # Market data handling
|
||||
├── enrich/ # LLM response enrichment
|
||||
├── explain/ # Decision explanation
|
||||
├── llm/ # LLM integrations (with RetryChatModel, TokenRecordingModelWrapper)
|
||||
├── services/ # Gateway, WebSocket services
|
||||
├── skills/ # Skill definitions (builtin + custom)
|
||||
└── tools/ # Trading and analysis tools
|
||||
```
|
||||
|
||||
### LLM Model Wrappers (`backend/llm/models.py`)
|
||||
|
||||
Based on CoPaw's model wrapper design:
|
||||
- **RetryChatModel**: 自动重试瞬态 LLM 错误（rate limit、timeout、502/503 等），指数退避
|
||||
- `max_retries`: 最大重试次数 (默认 3)
|
||||
- `initial_delay`: 初始延迟秒数 (默认 1.0)
|
||||
- `backoff_multiplier`: 退避倍数 (默认 2.0)
|
||||
- **TokenRecordingModelWrapper**: 追踪每个 provider 的 token 消耗和成本
|
||||
|
||||
```python
|
||||
from backend.llm.models import create_model, RetryChatModel
|
||||
|
||||
model = RetryChatModel(create_model("gpt-4o", "OPENAI"), max_retries=3)
|
||||
```
|
||||
|
||||
### Frontend Structure
|
||||
|
||||
```
|
||||
frontend/src/
|
||||
├── App.jsx # Main React application
|
||||
├── components/ # React components
|
||||
│ ├── RuntimeView.jsx # Trading runtime UI
|
||||
│ ├── TraderView.jsx # Trader interface
|
||||
│ └── RuntimeSettingsPanel.jsx
|
||||
├── services/ # API and WebSocket services
|
||||
│ ├── runtimeApi.js # Backend API calls
|
||||
│ └── websocket.js # Real-time communication
|
||||
└── config/
|
||||
└── constants.js # Agent definitions, configuration
|
||||
```
|
||||
|
||||
### Skill System (`backend/skills/`)
|
||||
|
||||
Skills are defined in `SKILL.md` files with:
|
||||
- `instructions` - What the skill does
|
||||
- `triggers` - When to invoke
|
||||
- `parameters` - Input/output schema
|
||||
- `available_tools` - Tools the skill can use
|
||||
|
||||
Skills are loaded by `skills_manager.py` and attached to agents via `skill_adaptation_hook.py`.
|
||||
|
||||
### Pipeline Execution (`backend/core/`)
|
||||
|
||||
The daily trading flow:
|
||||
1. **Analysis Stage** - Each agent analyzes independently
|
||||
2. **Communication Stage** - Agent-to-agent messaging (1v1, 1vN, NvN)
|
||||
3. **Decision Stage** - Portfolio manager makes final trades
|
||||
4. **Evaluation Stage** - Performance tracking
|
||||
5. **Review Stage** - Memory updates via ReMe
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Required in `.env`:
|
||||
```bash
|
||||
FIN_DATA_SOURCE=finnhub|financial_datasets
|
||||
FINANCIAL_DATASETS_API_KEY= # Required for backtest
|
||||
FINNHUB_API_KEY= # Required for live trading
|
||||
OPENAI_API_KEY= # Agent LLM
|
||||
OPENAI_BASE_URL=
|
||||
MODEL_NAME=qwen3-max-preview
|
||||
MEMORY_API_KEY= # For ReMe memory system
|
||||
```
|
||||
|
||||
## Key Dependencies
|
||||
|
||||
- **AgentScope** - Multi-agent framework
|
||||
- **ReMe** - Memory system for continuous learning
|
||||
- **FastAPI** + **uvicorn** - Backend API server
|
||||
- **websockets** - Real-time communication
|
||||
- **React 19** + **Vite** + **TailwindCSS** - Frontend
|
||||
- **Zustand** - Frontend state management
|
||||
- **Three.js** / **React-Three-Fiber** - 3D visualizations
|
||||
Reference in New Issue
Block a user