cillin
0f1bc2bb39
- 创建 5 个领域 store：runtimeStore, marketStore, portfolioStore, agentStore, uiStore - 更新 CLAUDE.md 记录架构改进 - Zustand 已安装但 stores 尚未在 App.jsx 中使用（渐进迁移） Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
303 lines
12 KiB
Markdown
303 lines
12 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件为 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 个微服务
|
||
|
||
# 单独启动某个服务
|
||
python -m uvicorn backend.apps.agent_service:app --host 0.0.0.0 --port 8000 --reload
|
||
python -m uvicorn backend.apps.runtime_service:app --host 0.0.0.0 --port 8003 --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 # 运行单个测试文件
|
||
pytest backend/tests/test_news_service_app.py::test_news_service_routes_are_exposed -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 单元测试
|
||
npm run test:watch # 监听模式
|
||
```
|
||
|
||
## 架构概览
|
||
|
||
### 微服务架构 (`backend/apps/`)
|
||
|
||
项目采用 split-first 微服务架构，4 个独立的 FastAPI 服务：
|
||
|
||
| 服务 | 入口 | 端口 | 职责 |
|
||
|------|------|------|------|
|
||
| agent_service | `backend.apps.agent_service:app` | 8000 | Agent 生命周期、工作区管理 |
|
||
| runtime_service | `backend.apps.runtime_service:app` | 8003 | 运行时配置、任务启动 |
|
||
| trading_service | `backend.apps.trading_service:app` | 8001 | 市场数据、交易操作 |
|
||
| news_service | `backend.apps.news_service:app` | 8002 | 新闻、新闻富化、解释功能 |
|
||
|
||
服务间通过环境变量通信（详见 `start-dev.sh`）：
|
||
```bash
|
||
export TRADING_SERVICE_URL=http://localhost:8001
|
||
export NEWS_SERVICE_URL=http://localhost:8002
|
||
export RUNTIME_SERVICE_URL=http://localhost:8003
|
||
```
|
||
|
||
### Gateway 网关 (`backend/services/gateway.py`)
|
||
|
||
Gateway 是统一的请求路由器，根据路径前缀将请求转发到对应的微服务：
|
||
- `/control/*` → agent_service
|
||
- `/runtime/*` → runtime_service
|
||
- `/trading/*` → trading_service
|
||
- `/news/*` → news_service
|
||
|
||
新增接口时应注册到对应的 service app，而非直接添加到 gateway。
|
||
|
||
### 共享客户端 (`shared/client/`)
|
||
|
||
统一的服务客户端库，所有前端和后端服务间通信都使用此处定义的客户端：
|
||
|
||
| 客户端 | 用途 |
|
||
|--------|------|
|
||
| `ControlPlaneClient` | Agent 服务通信 |
|
||
| `RuntimeServiceClient` | 运行时服务通信 |
|
||
| `TradingServiceClient` | 交易服务通信 |
|
||
| `NewsServiceClient` | 新闻服务通信 |
|
||
|
||
### 领域层 (`backend/domains/`)
|
||
|
||
业务逻辑按领域分离：
|
||
|
||
- `news.py` - 新闻领域操作
|
||
- `trading.py` - 交易领域操作
|
||
|
||
## 后端结构
|
||
|
||
```
|
||
backend/
|
||
├── agents/ # 多智能体实现
|
||
│ ├── base/ # 核心类、Hooks、评估
|
||
│ │ ├── evo_agent.py # 基于 AgentScope 的核心实现
|
||
│ │ ├── hooks.py # 生命周期 Hooks
|
||
│ │ │ ├── BootstrapHook # 启动初始化
|
||
│ │ │ ├── MemoryCompactionHook # 内存压缩（基于 CoPaw）
|
||
│ │ │ ├── HeartbeatHook # 心跳检测
|
||
│ │ │ └── WorkspaceWatchHook # 工作区监控
|
||
│ │ ├── evaluation_hook.py # 执行后评估
|
||
│ │ ├── skill_adaptation_hook.py # 动态技能适配
|
||
│ │ └── tool_guard.py # 工具调用守卫
|
||
│ ├── prompts/ # Agent 提示词和角色定义
|
||
│ │ ├── analyst/personas.yaml # 分析师角色配置
|
||
│ │ └── portfolio_manager/
|
||
│ ├── team/ # 团队协作逻辑
|
||
│ │ ├── registry.py # Agent 注册表
|
||
│ │ ├── coordinator.py # 协作协调器
|
||
│ │ ├── messenger.py # 消息传递
|
||
│ │ └── task_delegator.py # 任务分发
|
||
│ ├── factory.py # Agent 实例工厂
|
||
│ ├── skills_manager.py # 技能加载管理（6 种作用域）
|
||
│ └── toolkit_factory.py # 工具集工厂
|
||
├── apps/ # 微服务入口（split-first）
|
||
│ ├── agent_service.py
|
||
│ ├── runtime_service.py
|
||
│ ├── trading_service.py
|
||
│ └── news_service.py
|
||
├── domains/ # 领域业务逻辑
|
||
│ ├── news.py
|
||
│ └── trading.py
|
||
├── services/ # Gateway 和辅助服务
|
||
│ ├── gateway.py # 统一路由网关
|
||
│ ├── gateway_*.py # Gateway 子模块
|
||
│ └── market.py # 市场数据服务
|
||
├── api/ # FastAPI 端点
|
||
├── config/ # 常量和配置
|
||
│ └── constants.py # Agent 配置、显示名称等
|
||
├── core/ # Pipeline 执行逻辑
|
||
├── data/ # 市场数据处理
|
||
│ ├── provider_router.py # 数据源路由
|
||
│ └── schema.py # 数据 schema
|
||
├── enrich/ # LLM 响应富化
|
||
├── explain/ # 交易决策解释
|
||
├── llm/ # LLM 集成
|
||
│ └── models.py # RetryChatModel、TokenRecordingModelWrapper
|
||
├── skills/ # 技能定义（内置 + 自定义）
|
||
├── tools/ # 交易和分析工具
|
||
└── utils/ # 工具函数
|
||
```
|
||
|
||
## 前端结构
|
||
|
||
```
|
||
frontend/src/
|
||
├── App.jsx # React 主应用
|
||
├── components/ # React 组件
|
||
│ ├── RuntimeView.jsx # 交易运行时 UI
|
||
│ ├── TraderView.jsx # 交易员界面
|
||
│ ├── RoomView.jsx # 聊天室视图
|
||
│ ├── StockExplainView.jsx # 股票解释视图
|
||
│ ├── RuntimeSettingsPanel.jsx # 运行时设置面板
|
||
│ ├── WatchlistPanel.jsx # 关注列表
|
||
│ ├── PerformanceView.jsx # 绩效视图
|
||
│ ├── StatisticsView.jsx # 统计视图
|
||
│ ├── NetValueChart.jsx # 净值曲线图
|
||
│ ├── AgentCard.jsx # Agent 卡片
|
||
│ ├── AgentFeed.jsx # Agent 动态
|
||
│ └── explain/ # 解释相关组件
|
||
│ ├── ExplainNewsSection.jsx
|
||
│ ├── ExplainRangeSection.jsx
|
||
│ ├── ExplainSimilarDaysSection.jsx
|
||
│ ├── ExplainStorySection.jsx
|
||
│ └── useExplainModel.js
|
||
├── services/ # API 服务
|
||
│ ├── runtimeApi.js # 运行时 API 调用
|
||
│ ├── websocket.js # WebSocket 实时通信
|
||
│ ├── newsApi.js # 新闻服务客户端
|
||
│ └── tradingApi.js # 交易服务客户端
|
||
├── config/
|
||
│ └── constants.js # Agent 定义、配置
|
||
└── hooks/ # React Hooks
|
||
```
|
||
|
||
## Agent 系统
|
||
|
||
### 6 种 Agent 角色
|
||
|
||
| 角色 ID | 名称 | 职责 |
|
||
|---------|------|------|
|
||
| `fundamentals_analyst` | 基本面分析师 | 财务健康、盈利能力、成长质量 |
|
||
| `technical_analyst` | 技术分析师 | 价格趋势、技术指标、动量分析 |
|
||
| `sentiment_analyst` | 情绪分析师 | 市场情绪、新闻情绪、内幕交易 |
|
||
| `valuation_analyst` | 估值分析师 | DCF、EV/EBITDA、 intrinsic value |
|
||
| `portfolio_manager` | 投资经理 | 决策执行、交易协调 |
|
||
| `risk_manager` | 风控经理 | 实时价格/波动率监控、仓位限制、多层风险预警 |
|
||
|
||
### Hook 系统 (`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 条工具结果
|
||
|
||
### 添加自定义分析师
|
||
|
||
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`)
|
||
|
||
基于 CoPaw 的模型封装设计：
|
||
|
||
- **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)
|
||
```
|
||
|
||
## 技能系统 (`backend/skills/`)
|
||
|
||
技能定义在 `SKILL.md` 文件中，包含：
|
||
- `instructions` - 技能说明
|
||
- `triggers` - 触发条件
|
||
- `parameters` - 输入/输出 schema
|
||
- `available_tools` - 技能可使用的工具
|
||
|
||
技能由 `skills_manager.py` 加载，通过 `skill_adaptation_hook.py` 绑定到 Agent。
|
||
|
||
技能管理器支持 6 种作用域：builtin、customized、installed、active、disabled、local。
|
||
|
||
## Pipeline 执行 (`backend/core/`)
|
||
|
||
每日交易流程：
|
||
|
||
1. **分析阶段** - 各 Agent 基于工具和历史经验独立分析
|
||
2. **沟通阶段** - 通过私聊、通知、会议等方式交换观点（1v1/1vN/NvN）
|
||
3. **决策阶段** - 投资经理综合判断，给出最终交易
|
||
4. **评估阶段** - 绩效跟踪
|
||
5. **复盘阶段** - Agent 根据当日实际收益反思总结，通过 ReMe 记忆框架更新经验
|
||
|
||
## 前端状态管理
|
||
|
||
项目正在向 Zustand 状态管理过渡，已创建的 store：
|
||
|
||
```bash
|
||
frontend/src/store/
|
||
├── index.js # 导出所有 store
|
||
├── runtimeStore.js # 连接状态、运行时配置
|
||
├── marketStore.js # 市场数据、股票价格
|
||
├── portfolioStore.js # 组合、持仓、交易
|
||
├── agentStore.js # Agent 技能、工作区
|
||
└── uiStore.js # UI 状态、视图切换
|
||
```
|
||
|
||
**迁移状态**：
|
||
- Stores 已创建但尚未在 App.jsx 中使用
|
||
- 计划：逐步迁移 60+ 个 useState 到对应 store
|
||
|
||
## 环境配置
|
||
|
||
`.env` 必需配置：
|
||
|
||
```bash
|
||
# 金融数据源
|
||
FIN_DATA_SOURCE=finnhub|financial_datasets
|
||
FINANCIAL_DATASETS_API_KEY= # 回测必需
|
||
FINNHUB_API_KEY= # 实盘必需
|
||
|
||
# Agent LLM
|
||
OPENAI_API_KEY=
|
||
OPENAI_BASE_URL=
|
||
MODEL_NAME=qwen3-max-preview
|
||
|
||
# 可为不同 Agent 指定不同模型
|
||
AGENT_SENTIMENT_ANALYST_MODEL_NAME=qwen3-max-preview
|
||
AGENT_FUNDAMENTALS_ANALYST_MODEL_NAME=deepseek-chat
|
||
|
||
# ReMe 记忆系统
|
||
MEMORY_API_KEY=
|
||
```
|
||
|
||
## 关键依赖
|
||
|
||
- **AgentScope** - 多智能体框架
|
||
- **ReMe** - 持续学习记忆系统
|
||
- **FastAPI** + **uvicorn** - 后端 API 服务器
|
||
- **websockets** - 实时通信
|
||
- **React 19** + **Vite** + **TailwindCSS** - 前端
|
||
- **React Context** - 前端状态管理（App.jsx 中使用 useState + useCallback）
|
||
- **Three.js** / **React-Three-Fiber** - 3D 可视化
|