TradingAgents-CN 项目目录文档
项目概述
TradingAgents-CN 是一个多智能体 AI 股票分析平台，支持 A股、港股、美股的多市场分析。采用前后端分离架构。
| 层次 | 技术栈 | 端口 |
|---|---|---|
| 前端 | Vue 3 + TypeScript + Element Plus + Vite + Pinia + ECharts | 3000 (Nginx) |
| 后端 API | FastAPI + Uvicorn + APScheduler | 8000 |
| 数据库 | MongoDB 4.4 (持久化) + Redis 7 (缓存/会话/实时) | 27017 / 6379 |
| 管理面板 | Mongo Express + Redis Commander (可选) | 8082 / 8081 |
根目录结构
TradingAgents-CN/
├── app/ # FastAPI 后端服务（专有许可）
├── frontend/ # Vue 3 前端（专有许可）
├── tradingagents/ # 核心 AI Agent 库（Apache 2.0）
├── cli/ # 命令行工具
├── web/ # 旧版 Streamlit Web 应用（已废弃）
├── scripts/ # 运维脚本集合（300+）
├── tests/ # 测试文件（200+）
├── docs/ # 项目文档
├── config/ # 日志配置（TOML）
├── docker/ # Docker 配置（Nginx）
├── nginx/ # 额外的 Nginx 配置
├── install/ # 安装辅助脚本
├── examples/ # 使用示例脚本
├── data/ # 数据目录
├── reports/ # 报告输出目录
├── results/ # 结果输出目录
├── assets/ # 静态资源
├── images/ # 图片资源
├── .streamlit/ # 旧版 Streamlit 配置
├── .github/ # GitHub CI/CD 配置
├── pyproject.toml # Python 项目定义 & 依赖
├── requirements.txt # 已废弃，指向 pyproject.toml
├── docker-compose.yml # Docker 全栈编排
├── .env.example # 环境变量模板（570+ 行）
├── Dockerfile.backend # 后端 Docker 镜像
├── Dockerfile.frontend # 前端 Docker 镜像
├── VERSION # 版本号：v1.0.1
└── main.py # 简单演示入口（非生产用）app/ --- FastAPI 后端服务
后端入口，提供 REST API、调度器、WebSocket、SSE 等功能。
app/main.py
FastAPI 应用入口。包含：
- 应用生命周期管理（lifespan）：启动时初始化数据库、配置桥接、调度器
- APScheduler 定时任务：股票基础信息同步（多数据源）、实时行情入库、Tushare/AKShare/BaoStock 数据同步、新闻同步
- 中间件注册：CORS、TrustedHost、操作日志、请求日志、请求ID
- 30+ 路由注册
- 全局异常处理
app/core/ --- 核心基础设施
| 文件 | 内容 | 作用 |
|---|---|---|
config.py |
Pydantic Settings 类 | 全部配置项：MongoDB、Redis、JWT、队列、速率限制、日志、代理、SSE、数据源调度等 |
database.py |
MongoDB/Redis 连接管理 | 初始化数据库连接池、健康检查、关闭清理 |
redis_client.py |
Redis 客户端封装 | 连接池管理、常用 Redis 操作 |
config_bridge.py |
配置桥接 | 将 Web 配置写入环境变量，供 TradingAgents 核心库读取 |
config_compat.py |
配置兼容层 | 旧版环境变量别名映射 |
dev_config.py |
开发环境配置 | 开发模式特殊设置 |
logging_config.py |
日志配置 | 统一日志格式、级别、文件输出 |
logging_context.py |
日志上下文 | 请求级别日志追踪（traceId） |
rate_limiter.py |
速率限制器 | 基于 Redis 的滑动窗口限流 |
response.py |
统一响应格式 | 标准化 API 响应结构 |
startup_validator.py |
启动验证器 | 应用启动前校验配置合法性 |
unified_config.py |
统一配置 | 多源配置统一管理 |
app/models/ --- 数据模型（ORM/Pydantic）
| 文件 | 内容 | 作用 |
|---|---|---|
user.py |
User 模型 | 用户信息、角色、权限 |
analysis.py |
Analysis 模型 | 分析任务、分析结果 |
screening.py |
Screening 模型 | 筛选任务、筛选结果 |
config.py |
Config 模型 | 系统配置（LLM、数据源等） |
notification.py |
Notification 模型 | 系统通知、消息 |
operation_log.py |
OperationLog 模型 | 操作审计日志 |
stock_models.py |
股票数据模型 | 股票基本信息、行情、财务数据 |
app/schemas/ --- API 请求/响应 Schema
Pydantic 模型，定义所有 API 接口的入参和出参结构。
app/routers/ --- REST API 路由（30+ 接口）
| 文件 | 功能 | 主要接口 |
|---|---|---|
health.py |
健康检查 | GET /api/health |
auth_db.py |
用户认证 | 登录、注册、Token 刷新、密码修改 |
analysis.py |
AI 分析 | 单个/批量分析任务创建、查询、SSE 流 |
screening.py |
股票筛选 | 创建筛选任务、查询结果 |
queue.py |
任务队列 | 队列状态、任务进度 |
sse.py |
SSE 实时流 | 服务端推送事件流 |
favorites.py |
自选股 | 添加/删除/查询自选股 |
stocks.py |
股票信息 | 股票列表、详情、搜索 |
stock_data.py |
股票数据 | K线、行情数据 |
stock_sync.py |
股票同步 | 股票数据同步控制 |
multi_market_stocks.py |
多市场股票 | A股/港股/美股统一查询 |
tags.py |
标签管理 | 自选股标签 |
config.py |
系统配置 | LLM配置、数据源配置的增删改查 |
model_capabilities.py |
模型能力 | 查询各 LLM 支持的功能 |
usage_statistics.py |
使用统计 | Token 消耗、调用次数统计 |
database.py |
数据库管理 | 数据库状态、备份、清理 |
cache.py |
缓存管理 | 缓存查看、清除 |
operation_logs.py |
操作日志 | 操作日志查询、导出 |
logs.py |
系统日志 | 日志文件查看 |
system_config.py |
系统配置只读摘要 | 运行时配置快照 |
notifications.py |
通知管理 | 通知增删查 |
websocket_notifications.py |
WebSocket 通知 | WebSocket 实时推送 |
scheduler.py |
定时任务管理 | 任务启停、状态查询 |
sync.py |
数据同步控制 | 手动触发同步 |
multi_source_sync.py |
多数据源同步 | 跨数据源同步 |
paper.py |
模拟交易 | 模拟买卖、持仓查询 |
tushare_init.py |
Tushare 数据初始化 | 首次数据导入 |
akshare_init.py |
AKShare 数据初始化 | 首次数据导入 |
baostock_init.py |
BaoStock 数据初始化 | 首次数据导入 |
historical_data.py |
历史数据 | 历史K线查询 |
multi_period_sync.py |
多周期同步 | 多时间周期数据同步 |
financial_data.py |
财务数据 | 财务报表查询 |
news_data.py |
新闻数据 | 新闻查询 |
social_media.py |
社交媒体数据 | 舆情数据查询 |
internal_messages.py |
内部消息 | 系统内部消息 |
reports.py |
报告导出 | Markdown/Word/PDF 导出 |
app/services/ --- 业务逻辑层
| 文件/目录 | 作用 |
|---|---|
analysis_service.py |
核心分析服务：协调多 Agent 执行股票分析 |
simple_analysis_service.py |
简化版分析服务 |
auth_service.py |
认证服务：JWT 生成验证、密码哈希 |
user_service.py |
用户服务：用户 CRUD |
basics_sync_service.py |
股票基础信息同步服务 |
multi_source_basics_sync_service.py |
多数据源基础信息同步（支持自动切换） |
basics_sync/ |
基础信息同步子模块：处理逻辑、工具函数 |
config_service.py |
配置服务：系统配置 CRUD |
config_provider.py |
配置提供者：动态读取运行时设置 |
queue_service.py |
队列服务：任务队列管理 |
queue/ |
队列子模块：辅助函数、键管理 |
scheduler_service.py |
调度器服务：APScheduler 管理 |
favorites_service.py |
自选股服务 |
screening_service.py |
股票筛选服务 |
enhanced_screening_service.py |
增强筛选服务 |
database_service.py |
数据库管理服务 |
database/ |
数据库子模块：备份、清理、序列化、状态检查 |
quotes_ingestion_service.py |
实时行情入库服务 |
quotes_service.py |
行情查询服务 |
news_data_service.py |
新闻数据服务 |
social_media_service.py |
社交媒体服务 |
historical_data_service.py |
历史数据服务 |
stock_data_service.py |
股票数据服务 |
foreign_stock_service.py |
港股/美股服务 |
unified_stock_service.py |
统一股票服务（多市场） |
financial_data_service.py |
财务数据服务 |
tags_service.py |
标签服务 |
operation_log_service.py |
操作日志服务 |
notifications_service.py |
通知服务 |
websocket_manager.py |
WebSocket 连接管理器 |
internal_message_service.py |
内部消息服务 |
usage_statistics_service.py |
使用统计服务 |
model_capability_service.py |
模型能力服务 |
progress/ |
进度追踪子模块：日志处理、追踪器 |
redis_progress_tracker.py |
Redis 进度追踪 |
progress_log_handler.py |
进度日志处理 |
memory_state_manager.py |
内存状态管理 |
data_consistency_checker.py |
数据一致性检查 |
data_sources/ |
数据源适配：Tushare、AKShare、BaoStock 适配器及管理 |
analysis/ |
分析子模块：状态更新工具 |
log_export_service.py |
日志导出服务 |
app/worker/ --- 后台 Worker 服务
| 文件 | 作用 |
|---|---|
worker.py |
Worker 入口 |
analysis_worker.py |
分析任务后台执行 |
tushare_sync_service.py |
Tushare 数据同步（基础信息、行情、历史、财务） |
akshare_sync_service.py |
AKShare 数据同步 |
baostock_sync_service.py |
BaoStock 数据同步 |
tushare_init_service.py |
Tushare 数据初始化 |
akshare_init_service.py |
AKShare 数据初始化 |
baostock_init_service.py |
BaoStock 数据初始化 |
hk_data_service.py |
港股数据服务 |
hk_sync_service.py |
港股数据同步 |
us_data_service.py |
美股数据服务 |
us_sync_service.py |
美股数据同步 |
multi_period_sync_service.py |
多周期数据同步 |
financial_data_sync_service.py |
财务数据同步 |
news_data_sync_service.py |
新闻数据同步 |
example_sdk_sync_service.py |
示例 SDK 同步（模板） |
app/middleware/ --- 中间件
| 文件 | 作用 |
|---|---|
error_handler.py |
全局异常处理 |
operation_log_middleware.py |
操作日志记录 |
rate_limit.py |
请求速率限制 |
request_id.py |
请求 ID 追踪（Trace-ID） |
app/utils/ --- 工具函数
| 文件 | 作用 |
|---|---|
api_key_utils.py |
API Key 工具 |
error_formatter.py |
错误格式化 |
report_exporter.py |
报告导出（Markdown/Word/PDF） |
timezone.py |
时区处理 |
trading_time.py |
交易时间判断 |
app/scripts/ --- 数据库脚本
| 文件 | 作用 |
|---|---|
migrate_mongo_db.py |
MongoDB 数据库迁移 |
normalize_provider_keys.py |
提供者 Key 标准化 |
init_providers.py |
提供者初始化 |
app/constants/
| 文件 | 作用 |
|---|---|
model_capabilities.py |
各 LLM 模型支持的能力常量 |
frontend/ --- Vue 3 前端
技术栈
Vue 3 + TypeScript + Element Plus + Vite + Pinia + Vue Router + ECharts + Mermaid
frontend/src/main.ts
前端入口。注册 Element Plus、Pinia、Router、全局组件，初始化认证状态和主题。
frontend/src/App.vue
根组件，包含路由视图和全局通知组件。
frontend/src/router/index.ts
路由配置。定义所有页面路由、认证守卫、进度条、页面标题。
frontend/src/api/ --- HTTP 客户端（Axios）
| 文件 | 作用 |
|---|---|
request.ts |
Axios 实例配置、拦截器、错误处理 |
auth.ts |
认证接口（登录、注册、Token刷新） |
analysis.ts |
分析任务接口 |
screening.ts |
股票筛选接口 |
stocks.ts |
股票信息接口 |
favorites.ts |
自选股接口 |
config.ts |
系统配置接口 |
database.ts |
数据库管理接口 |
cache.ts |
缓存管理接口 |
logs.ts |
日志接口 |
operationLogs.ts |
操作日志接口 |
scheduler.ts |
定时任务接口 |
sync.ts |
数据同步接口 |
stockSync.ts |
股票同步接口 |
multiMarket.ts |
多市场接口 |
news.ts |
新闻接口 |
notifications.ts |
通知接口 |
paper.ts |
模拟交易接口 |
usage.ts |
使用统计接口 |
modelCapabilities.ts |
模型能力接口 |
tags.ts |
标签接口 |
templates.ts |
模板接口 |
frontend/src/views/ --- 页面组件
| 目录 | 作用 |
|---|---|
Dashboard/index.vue |
仪表板首页 |
Analysis/SingleAnalysis.vue |
单个股票分析页面 |
Analysis/BatchAnalysis.vue |
批量分析页面 |
Analysis/AnalysisHistory.vue |
分析历史 |
Screening/index.vue |
股票筛选页面 |
Favorites/index.vue |
自选股管理 |
Reports/index.vue |
报告列表 |
Reports/ReportDetail.vue |
报告详情 |
Reports/TokenStatistics.vue |
Token 消耗统计 |
PaperTrading/index.vue |
模拟交易 |
Settings/index.vue |
设置首页 |
Settings/ConfigManagement.vue |
配置管理 |
Settings/UsageStatistics.vue |
使用统计 |
Settings/CacheManagement.vue |
缓存管理 |
Settings/components/ |
设置子组件：LLM配置、数据源配置、模型目录、市场分类等对话框 |
System/DatabaseManagement.vue |
数据库管理 |
System/OperationLogs.vue |
操作日志 |
System/LogManagement.vue |
系统日志 |
System/SchedulerManagement.vue |
定时任务管理 |
System/MultiSourceSync.vue |
多数据源同步监控 |
Tasks/TaskCenter.vue |
任务中心 |
Stocks/Detail.vue |
股票详情页 |
Auth/Login.vue |
登录页 |
Learning/index.vue |
学习中心列表 |
Learning/Category.vue |
学习分类 |
Learning/Article.vue |
文章详情 |
Queue/index.vue |
队列状态 |
About/index.vue |
关于页面 |
Error/404.vue |
404 错误页 |
frontend/src/components/ --- 可复用组件
| 目录 | 作用 |
|---|---|
Layout/HeaderActions.vue |
顶部导航栏 |
Layout/AppFooter.vue |
底部栏 |
Layout/SidebarMenu.vue |
侧边栏菜单 |
Layout/UserProfile.vue |
用户信息 |
Layout/Breadcrumb.vue |
面包屑导航 |
Global/GlobalNotification.vue |
全局通知 |
Global/GlobalConfirm.vue |
全局确认对话框 |
Global/MarketSelector.vue |
市场选择器（A股/港股/美股） |
Global/MultiMarketStockSearch.vue |
多市场股票搜索 |
Global/TaskReportDialog.vue |
任务报告对话框 |
Global/TaskResultDialog.vue |
任务结果对话框 |
Sync/SyncControl.vue |
同步控制面板 |
Sync/DataSourceStatus.vue |
数据源状态 |
Sync/SyncHistory.vue |
同步历史 |
Sync/SyncRecommendations.vue |
同步建议 |
ConfigWizard.vue |
配置向导 |
ConfigValidator.vue |
配置校验 |
ModelConfig.vue |
模型配置 |
DeepModelSelector.vue |
深度模型选择器 |
NetworkStatus.vue |
网络状态指示 |
Dev/DevPanel.vue |
开发调试面板 |
Dashboard/MultiSourceSyncCard.vue |
仪表板多数据源卡片 |
frontend/src/stores/ --- Pinia 状态管理
| 文件 | 作用 |
|---|---|
app.ts |
应用全局状态（主题、API连接、网络状态、当前路由） |
auth.ts |
认证状态（Token、用户信息、登录/登出） |
notifications.ts |
通知状态管理 |
frontend/src/types/ --- TypeScript 类型定义
| 文件 | 作用 |
|---|---|
analysis.ts |
分析相关类型 |
auth.ts |
认证相关类型 |
config.ts |
配置相关类型 |
router.d.ts |
路由类型扩展 |
frontend/src/utils/ --- 工具函数
| 文件 | 作用 |
|---|---|
auth.ts |
认证工具（Token 存储、刷新定时器） |
datetime.ts |
日期时间格式化 |
market.ts |
市场判断（A股/港股/美股） |
stock.ts |
股票代码处理 |
stockValidator.ts |
股票代码校验 |
frontend/src/constants/ --- 常量
| 文件 | 作用 |
|---|---|
analysts.ts |
分析师类型常量 |
frontend/src/layouts/ --- 布局组件
| 文件 | 作用 |
|---|---|
BasicLayout.vue |
基础布局（侧边栏 + 顶部 + 内容区） |
tradingagents/ --- 核心 AI Agent 库（Apache 2.0）
多智能体交易分析框架，是整个系统的 AI 分析引擎。
tradingagents/graph/ --- LangGraph 状态机
| 文件 | 作用 |
|---|---|
trading_graph.py |
主图编排：构建 Agent 工作流（分析 → 研究 → 辩论 → 决策） |
conditional_logic.py |
条件逻辑：分支判断 |
signal_processing.py |
信号处理：Agent 输出信号解析 |
reflection.py |
反思机制：Agent 自我校正 |
propagation.py |
状态传播：跨节点数据传递 |
setup.py |
图初始化配置 |
tradingagents/agents/ --- AI Agent 定义
agents/analysts/ --- 分析师 Agent
| 文件 | 作用 |
|---|---|
market_analyst.py |
市场分析师：技术分析（K线、指标） |
fundamentals_analyst.py |
基本面分析师：财务数据、估值分析 |
news_analyst.py |
新闻分析师：新闻舆情分析 |
social_media_analyst.py |
社交媒体分析师：舆情分析 |
china_market_analyst.py |
中国市场分析师：A股特色分析 |
agents/managers/ --- 管理 Agent
| 文件 | 作用 |
|---|---|
research_manager.py |
研究主管：协调研究员工作 |
risk_manager.py |
风险管理主管 |
agents/researchers/ --- 研究 Agent
| 文件 | 作用 |
|---|---|
bull_researcher.py |
看多研究员：寻找利好因素 |
bear_researcher.py |
看空研究员：寻找利空因素 |
agents/risk_mgmt/ --- 风险管理辩论者
| 文件 | 作用 |
|---|---|
aggresive_debator.py |
激进派辩论者 |
conservative_debator.py |
保守派辩论者 |
neutral_debator.py |
中立派辩论者 |
agents/trader/ --- 交易 Agent
| 文件 | 作用 |
|---|---|
trader.py |
交易员：最终给出买卖建议 |
agents/utils/ --- Agent 工具
| 文件 | 作用 |
|---|---|
agent_states.py |
Agent 状态定义 |
agent_utils.py |
Agent 辅助函数 |
memory.py |
Agent 记忆管理 |
chromadb_config.py |
ChromaDB 向量数据库配置 |
google_tool_handler.py |
Google 工具处理器 |
instrument_utils.py |
金融工具辅助 |
tradingagents/llm_clients/ --- LLM 客户端
| 文件 | 作用 |
|---|---|
base_client.py |
LLM 客户端基类 |
openai_client.py |
OpenAI 客户端 |
anthropic_client.py |
Anthropic Claude 客户端 |
google_client.py |
Google Gemini 客户端 |
factory.py |
LLM 客户端工厂 |
model_catalog.py |
模型目录 |
provider_keys.py |
多提供者 Key 管理 |
validators.py |
输入验证 |
tradingagents/llm_adapters/ --- LLM 兼容适配
| 文件 | 作用 |
|---|---|
openai_compatible_base.py |
OpenAI 兼容基类 |
dashscope_openai_adapter.py |
阿里 DashScope 适配 |
deepseek_adapter.py |
DeepSeek 适配 |
google_openai_adapter.py |
Google OpenAI 兼容封装 |
tradingagents/dataflows/ --- 数据流
| 文件 | 作用 |
|---|---|
interface.py |
数据接口统一入口 |
stock_api.py |
股票数据 API |
stock_data_service.py |
股票数据服务 |
data_source_manager.py |
数据源管理器 |
optimized_china_data.py |
优化版中国 A 股数据 |
realtime_metrics.py |
实时指标 |
realtime_news_utils.py |
实时新闻工具 |
data_completeness_checker.py |
数据完整性检查 |
cache/db_cache.py |
数据库缓存 |
_compat_imports.py |
兼容导入 |
tradingagents/config/ --- 配置管理
| 文件 | 作用 |
|---|---|
config_manager.py |
配置管理器 |
database_config.py |
数据库配置 |
database_manager.py |
数据库管理 |
mongodb_storage.py |
MongoDB 存储 |
providers_config.py |
提供者配置 |
runtime_settings.py |
运行时设置 |
tushare_config.py |
Tushare 配置 |
usage_models.py |
使用量模型 |
env_utils.py |
环境变量工具 |
tradingagents/tools/ --- 工具
| 文件 | 作用 |
|---|---|
analysis/indicators.py |
技术指标计算（MA、MACD、RSI 等） |
unified_news_tool.py |
统一新闻工具 |
tradingagents/api/ --- 股票 API 层
| 文件 | 作用 |
|---|---|
stock_api.py |
股票 API 接口 |
tradingagents/models/ --- 数据模型
| 文件 | 作用 |
|---|---|
stock_data_models.py |
股票数据模型 |
tradingagents/utils/ --- 工具
| 文件 | 作用 |
|---|---|
dataflow_utils.py |
数据流工具 |
enhanced_news_filter.py |
增强新闻过滤 |
enhanced_news_retriever.py |
增强新闻检索 |
logging_init.py |
日志初始化 |
logging_manager.py |
日志管理 |
news_filter_integration.py |
新闻过滤集成 |
news_filter.py |
新闻过滤 |
stock_utils.py |
股票工具 |
stock_validator.py |
股票校验 |
tool_logging.py |
工具日志 |
tradingagents/constants/ --- 常量
| 文件 | 作用 |
|---|---|
data_sources.py |
数据源常量定义 |
tradingagents/default_config.py
默认配置字典。
cli/ --- 命令行工具
| 文件 | 作用 |
|---|---|
main.py |
CLI 主入口（~84K 行），支持股票分析、配置管理、数据同步、系统管理等命令 |
data_init/ |
数据初始化脚本（Tushare、AKShare、BaoStock） |
web/ --- 旧版 Streamlit Web 应用
| 文件 | 作用 |
|---|---|
app.py |
Streamlit 主入口 |
components/ |
Streamlit 组件 |
modules/ |
功能模块 |
| 其他 | 旧版工具函数、配置 |
已被
frontend/（Vue 3）取代，但仍保留。
scripts/ --- 运维脚本（300+）
按功能分子目录：
| 子目录 | 作用 |
|---|---|
setup/ |
环境安装、初始化 |
deployment/ |
Docker 构建、部署 |
development/ |
开发辅助 |
debug/ |
调试工具 |
docker/ |
Docker 相关 |
git/ |
Git 操作 |
maintenance/ |
数据维护、迁移 |
validation/ |
数据验证 |
windows-installer/ |
Windows 安装包 |
tests/ --- 测试（200+）
| 类型 | 覆盖 |
|---|---|
| API 集成测试 | 各 REST 接口 |
| 数据源测试 | AKShare、BaoStock、Tushare |
| LLM 测试 | 工具调用、多提供者 |
| 功能测试 | 港股、缓存、配置、进度追踪 |
docs/ --- 项目文档
| 子目录 | 内容 |
|---|---|
releases/ |
版本发布说明 |
guides/ |
使用指南 |
configuration/ |
配置说明 |
deployment/ |
部署指南 |
troubleshooting/ |
故障排查 |
architecture/ |
架构文档 |
design/ |
设计文档 |
blog/ |
博客文章 |
learning/ |
学习材料 |
community/ |
社区文档 |
security/ |
安全说明 |
config/ --- 日志配置
| 文件 | 作用 |
|---|---|
logging.conf |
常规日志配置 |
logging_docker.conf |
Docker 日志配置 |
docker/ --- Docker 配置
| 文件 | 作用 |
|---|---|
nginx.conf |
前端 SPA 的 Nginx 配置 |