381 lines
17 KiB
Markdown
381 lines
17 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
|
||
|
||
## 项目概述
|
||
|
||
大时代 是一个自进化多智能体交易系统，由 6 个 AI Agent（4 名分析师 + 投资经理 + 风控经理）协作完成交易决策。Agent 基于 AgentScope 框架构建，配合 ReMe 记忆系统实现持续学习。
|
||
|
||
## 常用命令
|
||
|
||
### Backend (Python)
|
||
|
||
```bash
|
||
# 安装依赖
|
||
uv pip install -e .
|
||
|
||
# 运行回测 / 实盘
|
||
python backend/main.py --mode backtest --config-name smoke_fullstack --start-date 2025-11-01 --end-date 2025-12-01
|
||
python backend/main.py --mode backtest --config-name smoke_fullstack --start-date 2025-11-01 --end-date 2025-12-01 --enable-memory
|
||
python backend/main.py --mode live --config-name live
|
||
python backend/main.py --mode live --config-name live --trigger-time 22:30
|
||
|
||
# 启动前端
|
||
cd frontend && npm run dev
|
||
|
||
# 开发服务器
|
||
./start-dev.sh # 启动全部 4 个微服务 (agent, runtime, trading, news)
|
||
|
||
# Gateway WebSocket 服务器
|
||
python backend/main.py --mode live --config-name live
|
||
|
||
# 单独启动微服务
|
||
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 - 核心编排器（分析→沟通→决策→执行→评估），支持断点 Checkpoint |
|
||
| `apo.py` | PolicyOptimizer - (APO) 自动策略优化器，根据 P&L 自动修改 Agent POLICY.md |
|
||
| `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（核心编排器，支持恢复）
|
||
│ ├── apo.py # PolicyOptimizer（自动调优）
|
||
│ ├── 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 # 轮询价格管理
|
||
│ ├── 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** - 状态管理
|