cillin/evotraders
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(README): 更新项目说明文档，完善架构与启动指南

Browse Source 
- 调整 CLAUDE.md 内容，增加使用指导和架构概览
- 补充微服务启动说明及单服务启动命令
- 明确 Gateway 服务器四阶段启动流程和职责划分
- 细化后端目录结构说明，补充主要文件职责描述
- 新增系统分层结构图，优化整体架构理解
- 更新 .gitignore，添加 runs 目录忽略规则
- 同步 .omc 相关状态文件，更新项目状态跟踪信息
This commit is contained in:
cillin
2026-03-24 17:19:31 +08:00
parent da6d642aaa
commit 16bb3c4211
20 changed files with 556 additions and 563 deletions
Download Patch File Download Diff File Expand all files Collapse all files

426
CLAUDE.md
View File

@@ -1,5 +1,7 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
## 项目概述
@@ -23,18 +25,20 @@ evotraders live -t 22:30 # 定时每日交易
evotraders frontend # 启动可视化界面
# 开发服务器
./start-dev.sh # 启动全部 4 个微服务
./start-dev.sh # 启动全部 4 个微服务 (agent, runtime, trading, news)
# 单独启动某个服务
python -m uvicorn backend.apps.agent_service:app --host 0.0.0.0 --port 8000 --reload
# 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 # 运行单个测试文件
pytest backend/tests/test_news_service_app.py::test_news_service_routes_are_exposed -v # 运行单个测试
pytest backend/tests/test_news_service_app.py -v # 运行单个测试
```
### Frontend (React)
@@ -46,142 +50,237 @@ 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
```
┌─────────────────────────────────────────────────────────────┐
│ 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 │
└──────────┘ └──────────┘ └──────────┘
```
### Gateway 网关 (`backend/services/gateway.py`)
### 微服务架构 (`backend/apps/`)
Gateway 是统一的请求路由器，根据路径前缀将请求转发到对应的微服务：
- `/control/*` → agent_service
- `/runtime/*` → runtime_service
- `/trading/*` → trading_service
- `/news/*` → news_service
| 服务 | 端口 | 职责 |
|------|------|------|
| runtime_service | 8003 | 运行时配置、任务启动、Pipeline Runner |
| agent_service | 8000 | Agent 生命周期、工作区管理 |
| trading_service | 8001 | 市场数据、交易操作 |
| news_service | 8002 | 新闻、新闻富化、解释功能 |
新增接口时应注册到对应的 service app，而非直接添加到 gateway。
### Gateway 4 阶段启动 (`backend/services/gateway.py`)
### 共享客户端 (`shared/client/`)
1. **WebSocket Server** - 前端立即可连接
2. **Market Service** - 价格数据开始推送
3. **Market Status Monitor** - 市场状态监控
4. **Scheduler** - 交易周期开始
统一的服务客户端库，所有前端和后端服务间通信都使用此处定义的客户端：
### 运行时管理层 (`backend/runtime/`)
| 客户端 | 用途 |
|--------|------|
| `ControlPlaneClient` | Agent 服务通信 |
| `RuntimeServiceClient` | 运行时服务通信 |
| `TradingServiceClient` | 交易服务通信 |
| `NewsServiceClient` | 新闻服务通信 |
| 文件 | 职责 |
|------|------|
| `manager.py` | TradingRuntimeManager - 全局运行时管理器，agent 注册、会话、事件快照 |
| `agent_runtime.py` | AgentRuntimeState - 单 agent 状态（status、last_session） |
| `context.py` | TradingRunContext - 运行上下文 |
| `session.py` | TradingSessionKey - 交易日会话键 |
| `registry.py` | RuntimeRegistry - agent 状态注册表 |
### 领域层 (`backend/domains/`)
快照持久化到 `runs/<run_id>/state/runtime_state.json`。
业务逻辑按领域分离：
### Pipeline 执行 (`backend/core/`)
- `news.py` - 新闻领域操作
- `trading.py` - 交易领域操作
| 文件 | 职责 |
|------|------|
| `pipeline.py` | TradingPipeline - 核心编排器（分析→沟通→决策→执行→评估） |
| `pipeline_runner.py` | REST API 触发的独立执行，5 阶段启动 |
| `scheduler.py` | BacktestScheduler、Scheduler - 回测/实盘调度 |
| `state_sync.py` | StateSync - 状态同步和广播 |
## 后端结构
```
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/ # 领域业务逻辑
├── 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
├── 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/ # 工具函数
│
├── 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 # React 主应用
├── components/ # React 组件
│ ├── RuntimeView.jsx # 交易运行时 UI
│ ├── TraderView.jsx # 交易员界面
│ ├── RoomView.jsx # 聊天室视图
│ ├── StockExplainView.jsx # 股票解释视图
├── App.jsx # 主应用（LiveTradingApp）
├── AppShell.jsx # App 外壳（布局、侧边栏）
├── components/
│ ├── 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/ # 解释相关组件
│ ├── 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
├── services/ # API 服务
│ ├── runtimeApi.js # 运行时 API 调用
│ ├── websocket.js # WebSocket 实时通信
│ ├── newsApi.js # 新闻服务客户端
│ └── tradingApi.js # 交易服务客户端
├── config/
│ └── constants.js # Agent 定义、配置
└── hooks/ # React Hooks
├── 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 系统
@@ -193,110 +292,87 @@ frontend/src/
| `fundamentals_analyst` | 基本面分析师 | 财务健康、盈利能力、成长质量 |
| `technical_analyst` | 技术分析师 | 价格趋势、技术指标、动量分析 |
| `sentiment_analyst` | 情绪分析师 | 市场情绪、新闻情绪、内幕交易 |
| `valuation_analyst` | 估值分析师 | DCF、EV/EBITDA、 intrinsic value |
| `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 条工具结果
| `risk_manager` | 风控经理 | 实时价格/波动率监控、仓位限制 |
### 添加自定义分析师
1. 在 `backend/agents/prompts/analyst/personas.yaml` 注册
2. 在 `backend/config/constants.py` 的 `ANALYST_TYPES` 字典中添加
3. 可选：在 `frontend/src/config/constants.js` 中更新前端配置
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)
```
- **RetryChatModel**: 自动重试瞬态 LLM 错误，指数退避
- **TokenRecordingModelWrapper**: 追踪 token 消耗和成本
## 技能系统 (`backend/skills/`)
技能定义在 `SKILL.md` 文件中，包含：
- `instructions` - 技能说明
- `triggers` - 触发条件
- `parameters` - 输入/输出 schema
- `available_tools` - 技能可使用的工具
技能由 `skills_manager.py` 加载，通过 `skill_adaptation_hook.py` 绑定到 Agent。
技能定义在 `SKILL.md`，包含 `instructions`、`triggers`、`parameters`、`available_tools`。
技能管理器支持 6 种作用域：builtin、customized、installed、active、disabled、local。
## Pipeline 执行 (`backend/core/`)
## 运行时数据布局
每日交易流程：
1. **分析阶段** - 各 Agent 基于工具和历史经验独立分析
2. **沟通阶段** - 通过私聊、通知、会议等方式交换观点（1v1/1vN/NvN）
3. **决策阶段** - 投资经理综合判断，给出最终交易
4. **评估阶段** - 绩效跟踪
5. **复盘阶段** - Agent 根据当日实际收益反思总结，通过 ReMe 记忆框架更新经验
## 前端状态管理
项目正在向 Zustand 状态管理过渡，已创建的 store：
- `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
frontend/src/store/
├── index.js # 导出所有 store
├── runtimeStore.js # 连接状态、运行时配置
├── marketStore.js # 市场数据、股票价格
├── portfolioStore.js # 组合、持仓、交易
├── agentStore.js # Agent 技能、工作区
└── uiStore.js # UI 状态、视图切换
RUNS_RETENTION_COUNT=20 # 时间戳格式文件夹自动清理
```
**迁移状态**：
- Stores 已创建但尚未在 App.jsx 中使用
- 计划：逐步迁移 60+ 个 useState 到对应 store
## 环境配置
`.env` 必需配置：
### Backend (`env.template`)
```bash
# 金融数据源
FIN_DATA_SOURCE=finnhub|financial_datasets
# 金融数据源（支持多源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= # 实盘必需
FINNHUB_API_KEY= # 实盘必需
POLYGON_API_KEY= # Polygon市场库采集可选
# Agent LLM
# 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
# 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 服务器
- **FastAPI** + **uvicorn** - 后端 API
- **websockets** - 实时通信
- **React 19** + **Vite** + **TailwindCSS** - 前端
- **React Context** - 前端状态管理（App.jsx 中使用 useState + useCallback）
- **Three.js** / **React-Three-Fiber** - 3D 可视化
- **Zustand** - 状态管理