# 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** - 状态管理