evotraders/README_zh.md

大时代：自进化多智能体交易系统

📌 访问大时代官网

大时代 是一个开源的金融交易智能体框架，结合多智能体协作、run 级工作区和记忆机制，支持回测与实盘两类交易运行模式。

---

核心特性

多智能体交易团队 系统默认包含 6 个角色：4 个分析师（基本面、技术面、情绪、估值）+ 投资经理 + 风控经理。

持续学习 可选接入 ReMe 长期记忆，智能体会在每轮结束后反思、复盘并沉淀经验。

统一运行时 同一套运行时模型支持历史回测和实时行情驱动的实盘流程。

可操作前端 前端不只是展示层，还包含交易室、运行控制、日志、审批、Agent 工作区和 explain/news 视图。

---

当前架构

仓库目前使用 split-service 运行时模型 进行本地开发，这是默认支持的运行路径。

运行时 vs 设计时

• runtime — 活跃的执行层（scheduler、gateway、pipeline、实盘运行期间的审批）
• run — 一次具体的执行实例（runs/<run_id>/）
• design-time — 启动特定 runtime 之前的配置和控制面概念
• workspace — agent_service 暴露的设计时注册表（workspaces/）

服务表面

服务	端口	职责
backend.apps.agent_service	:8000	workspaces、agents、skills 和 guard/approval API 的控制面
backend.apps.trading_service	:8001	只读交易数据 API
backend.apps.news_service	:8002	只读 explain/news API
backend.apps.runtime_service	:8003	运行时生命周期 API
backend.apps.openclaw_service	:8004	只读 OpenClaw facade
WebSocket gateway	:8765	前端实时事件/feed 通道

活跃运行时路径

frontend -> runtime_service/control APIs -> gateway/runtime manager -> market service + pipeline + storage

运行时状态存储在 runs/<run_id>/ — 这是 运行时唯一真相源。workspaces/ 目录是 设计时注册表，不是运行时执行路径。

文档

• docs/current-architecture.md — 权威架构事实
• services/README.md — 服务边界和迁移详情
• docs/current-architecture.excalidraw — 架构图
• docs/development-roadmap.md — 下一步执行计划
• docs/terminology.md — 术语规范指南

---

快速开始

1. 安装

# 克隆仓库后进入项目目录
cd evotraders

# 安装后端运行时依赖
uv pip install -r requirements.txt

# 安装项目入口（可编辑模式）
uv pip install -e .

# 可选
# uv pip install -e ".[dev]"
# pip install -e .

前端依赖：

cd frontend
npm ci
cd ..

生产环境部署建议后端使用 requirements.txt，前端使用 npm ci，这样拉起的环境会严格跟随仓库中锁定的依赖版本。

2. 配置环境变量

cp env.template .env

根目录 env.template 是当前本地开发的主模板，仓库里也保留了 .env.example 作为参考。

最常用的配置项：

# 自选股
TICKERS=AAPL,MSFT,GOOGL,NVDA,TSLA,META,AMZN

# 行情数据
FIN_DATA_SOURCE=finnhub
FINANCIAL_DATASETS_API_KEY=
FINNHUB_API_KEY=
POLYGON_API_KEY=

# Agent 模型
OPENAI_API_KEY=
OPENAI_BASE_URL=
MODEL_NAME=qwen3-max-preview

# 长期记忆（只有启用 --enable-memory 才需要）
MEMORY_API_KEY=

# 实验性：将选定的 analyst / risk 角色切换到 EvoAgent
EVO_AGENT_IDS=

说明：

• live 模式必须配置 FINNHUB_API_KEY
• POLYGON_API_KEY 用于长期 market store 的补数和刷新
• MEMORY_API_KEY 仅在启用长期记忆时需要
• EVO_AGENT_IDS 目前支持 analyst 角色以及 risk_manager 和 portfolio_manager，用于分阶段灰度发布

特定 EvoAgent 灰度目标的冒烟测试：

python3 scripts/smoke_evo_runtime.py --agent-id fundamentals_analyst

该脚本启动临时运行时，验证 gateway 日志包含选定的 EvoAgent，检查 runtime_state.json，验证审批唤醒路径，然后停止运行时。

你也可以将其包含在本地发布检查中：

./scripts/check-prod-env.sh --smoke-evo

未设置 EVO_AGENT_IDS 时，此发布检查默认运行 fundamentals_analyst、risk_manager 和 portfolio_manager 的冒烟路径。

如果要用更接近生产的本地启动方式，也可以直接执行：

./start.sh

3. 启动服务栈

本地开发推荐直接使用：

./start-dev.sh

该脚本会启动：

• agent_service：http://localhost:8000
• trading_service：http://localhost:8001
• news_service：http://localhost:8002
• runtime_service：http://localhost:8003
• gateway WebSocket：ws://localhost:8765

然后在另一个终端启动前端：

cd frontend && npm run dev

访问 http://localhost:5173。

也可以手动分别启动：

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
python -m uvicorn backend.apps.runtime_service:app --host 0.0.0.0 --port 8003 --reload
# 兼容性 gateway 路径，不是推荐的主要开发入口
python -m backend.main --mode live --host 0.0.0.0 --port 8765

仓库里部署脚本使用的 production 只是一个示例 run label，不应再把它理解成 系统规定的根目录运行目录名。

4. 运行回测或实盘

回测：

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 --enable-memory
python backend/main.py --mode live --config-name live --interval-minutes 60
python backend/main.py --mode live --config-name live --trigger-time 22:30

帮助：

python backend/main.py --help

离线回测数据

如果只是想快速体验回测，不依赖外部行情 API，可以下载离线数据包并解压到 backend/data：

wget "https://agentscope-open.oss-cn-beijing.aliyuncs.com/ret_data.zip"
unzip ret_data.zip -d backend/data

---

运行时数据布局

• 长期研究数据保存在 data/market_research.db
• 每次 run 的状态写入 runs/<run_id>/
• runs/<run_id>/BOOTSTRAP.md 保存该 run 的 bootstrap 值和 prompt body
• runs/<run_id>/state/runtime_state.json 保存运行时快照
• runs/<run_id>/team_dashboard/*.json 主要是给 dashboard 用的兼容导出层，不是运行时唯一真相源
• 在受控环境里可通过 ENABLE_DASHBOARD_COMPAT_EXPORTS=false 关闭这层兼容 JSON 导出，而不影响 runtime state 持久化

遗留的根级目录如 live/、production/ 和 backtest/ 应被视为历史兼容性产物，不是新工作的默认运行时位置。

可选保留策略：

RUNS_RETENTION_COUNT=20

只有形如 YYYYMMDD_HHMMSS 的时间戳目录会被自动清理；live、smoke_fullstack、reload_demo_* 这类命名 run 会保留。

---

前端服务路由

前端始终会使用 control plane 和 runtime API，同时可以选择直连拆分服务读取只读数据。

常用前端环境变量：

VITE_CONTROL_API_BASE_URL=http://localhost:8000/api
VITE_RUNTIME_API_BASE_URL=http://localhost:8003/api/runtime
VITE_NEWS_SERVICE_URL=http://localhost:8002
VITE_TRADING_SERVICE_URL=http://localhost:8001
VITE_WS_URL=ws://localhost:8765

如果未设置这些变量，前端会回退到本地默认值和兼容性路径。

---

决策流程

市场数据 -> 分析师独立分析 -> 团队沟通 -> 投资决策 ->
风控审核 -> 执行/结算 -> 复盘/记忆更新

运行时管理器还会跟踪：

• agent 注册和状态
• 待审批项
• run 事件
• 当前 session key

---

自定义配置

新增或修改分析师角色

1. 在 backend/agents/prompts/analyst/personas.yaml 中定义 persona
2. 在 backend/config/constants.py 中注册角色
3. 如有需要，在 frontend/src/config/constants.js 中补充前端展示元数据

示例：

comprehensive_analyst:
  name: "Comprehensive Analyst"
  focus:
    - multi-factor synthesis
  preferred_tools:
    - get_stock_price
    - get_company_financials
  description: |
    A generalist analyst that combines multiple signals.

配置各 Agent 使用的模型

模型覆盖在 .env 中配置：

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

run 级 BOOTSTRAP 配置

每个 run 都可以通过 runs/<run_id>/BOOTSTRAP.md 覆盖默认值。该文件由 backend/config/bootstrap_config.py 解析，front matter 可配置：

tickers:
  - AAPL
  - MSFT
initial_cash: 100000
margin_requirement: 0.5
max_comm_cycles: 2
schedule_mode: daily
trigger_time: "09:30"
enable_memory: false

运行时作用域工作区会在首次运行 pipeline 或服务时自动创建，无需手动初始化。

---

项目结构

evotraders/
├── backend/
│   ├── agents/      # agent 角色、prompts、skills、workspaces
│   ├── api/         # FastAPI 路由层
│   ├── apps/        # 拆分服务 app surface
│   ├── core/        # pipeline、scheduler、state sync
│   ├── runtime/     # runtime manager 和 agent runtime state
│   ├── services/    # gateway、market/storage/db 服务
├── frontend/        # React + Vite 前端
├── shared/          # 拆分服务共用 client 和 schema
├── runs/            # run-scoped 状态和 dashboards
├── data/            # 长期研究数据
└── services/README.md

---

测试

后端测试位于 backend/tests，覆盖 service app、shared client、domain、路由、enrichment、gateway 支撑模块和 runtime 支撑模块。

常用命令：

pytest
pytest backend/tests/test_runtime_service_app.py
pytest backend/tests/test_trading_service_app.py

前端测试：

cd frontend
npm test

---

许可与免责

大时代 是研究和教育用途项目。再次分发或商用前，请先核对仓库中的实际 license 文件。

风险提示：本项目不构成投资建议。任何实盘部署前都应进行充分测试和风险评估，历史表现不代表未来收益。