TradingAgents-CN 设计文档体系解析:提示词模版系统、股票数据模型与多源数据架构全景指南
TradingAgents-CN 设计文档体系解析:提示词模版系统、股票数据模型与多源数据架构全景指南
TradingAgents-CN 在 docs/design/ 目录下沉淀了一套覆盖系统架构、数据模型、API 规范与提示词模版系统的完整设计文档体系,本文以该设计目录为脉络,系统讲解其中三大核心板块:面向 13 个 Agent 的提示词模版系统设计(v1.0.1)、支撑 CN/HK/US 多市场的股票数据模型设计,以及"数据获取与使用解耦"的多层数据架构,并逐一对照仓库源码给出实现级证据。读完本文,你将掌握该项目的设计组织方式、核心数据结构的字段语义与索引策略,以及提示词模版系统的版本规划与实现路线,可直接据此定位到对应源码和设计文档进行二次开发。
设计文档体系的组织方式
文档索引结构
设计文档目录 是整个项目设计资产的入口,按四类主题组织:
- 系统架构设计:包括 stock_analysis_system_design.md(整体架构)、api_specification.md(API 规范)、configuration_management.md(配置管理)、timezone-strategy.md(时区策略)。
- 数据模型设计:包括 stock_data_model_design.md(数据模型方案)、stock_data_methods_analysis.md(数据获取方法分析)、stock_data_quick_reference.md(快速参考手册)。
- 提示词模版系统设计:围绕 v1.0.1 形成 9 份主文档(系统设计、架构对比、实现指南、技术规范、检查清单、使用示例等),并有版本化目录
v1.0.1/与v0.1.16/承载历史版本。 - 版本化设计:
v1.0.1/为最新版本,明确标注"支持所有 13 个 Agent";v0.1.16/存放早期版本设计。
按该目录的统计,提示词模版系统 v1.0 共 9 份文档(约 1200 行)、v1.0.1 新增 4 份(约 800 行)、股票数据系统 3 份(约 800 行)、系统架构 4 份(约 600 行),合计约 3400 行、20 份文档,全部标记为"完成"状态。
阅读路径与角色分工
README 同时给出了面向不同角色的推荐阅读顺序,例如:
- 快速了解 →
QUICK_REFERENCE.md→ 系统总结 → 系统设计 → 架构设计 → 实现指南 → 技术规范 → 检查清单 → 使用示例; - 股票数据系统 → 系统架构 → 数据模型 → API 设计 → 数据获取 → 快速参考。
命令行查看方式同样明确:cat docs/design/QUICK_REFERENCE.md、cat docs/design/prompt_template_implementation_guide.md 等(注意本文涉及的文档均位于 docs/design/,其中提示词模版系统的快速参考位于 docs/design/v1.0.1/QUICK_REFERENCE.md)。
提示词模版系统设计(v1.0.1)
设计目标与核心能力
提示词模版系统 v1.0.1 的目标是"为所有 13 个 Agent 提供可配置的提示词模版",其核心功能清单包括:数据库存储、用户管理、分析偏好、模版管理、历史记录、版本管理、Web API(27 个端点)与前端集成。相比 v1.0,v1.0.1 扩展支持全部 Agent,并新增了 5 个 MongoDB 集合的存储设计、与现有用户系统的集成方案、3 种分析偏好类型、历史记录与版本管理,以及 6 个前端 UI 组件。
从源码结构看,13 个 Agent 的分类与设计文档完全对应(详见 tradingagents/agents/):
| 角色组 | 数量 | 源码位置 | 职责 |
|---|---|---|---|
| 分析师 | 4 | analysts/(market_analyst、fundamentals_analyst、news_analyst、social_media_analyst、china_market_analyst 等) | 数据收集和分析 |
| 研究员 | 2 | researchers/(bull_researcher、bear_researcher) | 观点生成和辩论 |
| 辩手 | 3 | risk_mgmt/(aggresive_debator、conservative_debator、neutral_debator) | 风险评估和反驳 |
| 管理者 | 2 | managers/(research_manager、risk_manager) | 综合决策 |
| 交易员 | 1 | trader/trader.py | 交易决策 |
三种分析偏好与 31 个预设模版
系统设计了三档分析偏好,直接影响 Agent 的风险与收益取向:
- 激进型(Aggressive):高风险、高收益;
- 中性型(Neutral):平衡风险收益;
- 保守型(Conservative):低风险、稳定收益。
每个 Agent 规划了 2-3 个预设模版,合计 31 个预设模版,同时支持用户自定义模版与模版版本管理,并支持 A/B 测试、热更新、快速切换等灵活机制。v1.0.1 为此新增了 AGENT_TEMPLATE_SPECIFICATIONS.md(每个 Agent 的模版规范、模版变量定义、模版类型说明)、EXTENDED_AGENTS_SUPPORT.md(13 个 Agent 体系)与 IMPLEMENTATION_ROADMAP.md(8 阶段实现计划)。
Web API 与前端集成
设计文档规划了 27 个 API 端点(详见 ENHANCED_API_DESIGN.md),覆盖模版的增删改查、版本回滚、预览与渲染;前端规划 6 个组件(详见 FRONTEND_UI_DESIGN.md),支持 Web 端编辑与模版预览。集成的关键路径文档是 INTEGRATION_WITH_EXISTING_SYSTEM.md 与 IMPLEMENTATION_IN_APP_DIRECTORY.md,后者明确要求在 app/ 目录内实现模版管理功能——与当前仓库 app/models/、app/routers/、app/services/ 的分层结构一致,便于复用既有的数据库访问与 API 路由基建。
实现阶段规划
v1.0.1 的增强版路线图(见 ENHANCED_IMPLEMENTATION_ROADMAP.md)将实现拆分为 11 周、215 个任务:
- Phase 1-2(3 周):基础设施与用户管理——数据库设计与创建、用户管理、偏好管理;
- Phase 3-5(3 周):模版创建——创建所有 Agent 的模版并完成 Agent 集成;
- Phase 6-7(2 周):历史记录与 Web API;
- Phase 8-9(3 周):前端 UI、性能优化与发布准备。
股票数据模型设计:8 类集合与多市场统一架构
设计目标
stock_data_model_design.md 提出五个设计目标:数据标准化(统一不同数据源格式)、解耦架构(数据获取服务与使用服务分离)、易于扩展(新增数据源只需实现标准接口)、高性能(优化索引与查询结构)、数据完整性(完整的数据验证和约束)。其整体架构是"数据获取服务 → MongoDB 数据库 → 数据使用服务"三段式,获取侧对接 Tushare、AKShare、Yahoo、Finnhub 等 SDK,使用侧对接分析服务、API 服务、Web 界面与 CLI 工具。
核心集合与关键字段
设计文档定义了 8 类核心集合,本文按字段语义归并说明(完整 JSON 示例见原文档):
- stock_basic_info(基础信息):以
symbol(原始代码)与full_symbol(标准化代码,如000001.SZ)为核心标识,内嵌market_info统一市场区分——market(CN/HK/US)、exchange(SZSE/SSE/SEHK/NYSE/NASDAQ)、currency(CNY/HKD/USD)、timezone及trading_hours,并包含板块、行业、市值、股本、上市状态(L/D/P)、沪深港通标记与数据版本号。 - stock_daily_quotes(历史行情):以
(symbol, market, trade_date)唯一约束,含开高低收、涨跌额/涨跌幅、成交量额、换手率、量比、PE/PB/PS、股息率、市值与复权因子。 - stock_realtime_quotes(实时行情):在日线字段基础上扩展五档盘口(
bid_prices/bid_volumes/ask_prices/ask_volumes各 5 档)与行情时间戳。 - stock_financial_data(财务数据):按
report_period+report_type组织,内嵌资产负债表、利润表、现金流量表三大报表子对象,并附带 ROE/ROA/毛利率/净利率/资产负债率/流动比率等财务指标。 - stock_news(新闻数据):含标题、正文、摘要、来源、情绪分析与得分、关键词、重要性分级与语言标记。
- social_media_messages(社媒消息):覆盖微博/微信/抖音/小红书/知乎/Twitter/Reddit 等平台,记录消息类型(post/comment/repost/reply)、作者画像(认证、粉丝数、影响力评分)、互动数据(点赞/转发/评论/互动率)、情绪与可信度、地理位置及抓取元数据。
- internal_messages(内部消息):面向研究报告、内幕信息、分析师纪要等内部数据,设计来源可靠性、影响范围、时效性、访问级别与权限控制。
- stock_technical_indicators(技术指标):见下节"分类扩展机制"。
此外还有 data_source_config(数据源配置,含优先级、限流、超时与重试参数)与 data_sync_logs(同步日志,记录任务耗时、成功率、API 调用次数与缓存命中数)两个配套集合。
技术指标分类扩展机制
设计将技术指标按功能分为 6 类,每类可独立扩展(原文档给出的 JSON 骨架):
"indicators": {
"trend": {}, // 趋势指标 - MACD, EMA, DMI, Aroon等
"oscillator": {}, // 震荡指标 - RSI, KDJ, Williams%R, CCI等
"channel": {}, // 通道指标 - 布林带, 唐奇安通道, 肯特纳通道等
"volume": {}, // 成交量指标 - OBV, VWAP, MFI, CMF等
"volatility": {}, // 波动率指标 - ATR, 标准差, 方差等
"custom": {} // 自定义指标 - 策略信号, 风险评分等
}
新增指标的流程为:确定分类 → 在对应分类下添加字段(如新增 TRIX 则写入 trend.trix 等)→ 更新 indicator_metadata.parameters(如 trix_period: 14)→ 可选地在 technical_indicator_configs 集合注册指标配置(含展示名、计算公式、数据类型、启用状态)。同时支持市场差异化指标(如 A 股连续涨停天数、美股盘后涨跌幅与期权看跌看涨比)和指标版本管理(version_history 与 deprecated_indicators)。
该分类扩展设计在源码中有直接印证:app/models/stock_models.py 中的 TechnicalIndicators 模型定义了 trend/oscillator/channel/volume/volatility/custom 六个可选字典字段,注释与设计文档完全一致。
多市场支持与股票代码标准化
设计文档给出统一的代码标准化规则:A 股 6 位原始代码(如 000001 → 000001.SZ),港股 4 位(如 0700 → 0700.HK),美股字母代码(如 AAPL → AAPL.US);市场元数据表如下:
| 市场代码 | 市场名称 | 交易所代码 | 货币 | 时区 |
|---|---|---|---|---|
| CN | 中国A股 | SZSE/SSE | CNY | Asia/Shanghai |
| HK | 港股 | SEHK | HKD | Asia/Hong_Kong |
| US | 美股 | NYSE/NASDAQ | USD | America/New_York |
源码侧,app/models/stock_models.py 定义了 MarketType = Literal["CN", "HK", "US"]、ExchangeType = Literal["SZSE", "SSE", "SEHK", "NYSE", "NASDAQ"]、StockStatus = Literal["L", "D", "P"]、CurrencyType = Literal["CNY", "HKD", "USD"] 等枚举,以及 MarketInfo 内嵌模型——与设计文档的 market_info 结构逐字段对应;StockBasicInfoExtended 与 MarketQuotesExtended 则采用"在现有集合上扩展字段、保持向后兼容"的策略,保留 code 等兼容字段并允许额外字段(extra = "allow")。
索引优化与查询策略
设计文档针对每类集合给出了复合索引建议,核心是"唯一约束 + 高频查询路径"双管齐下,例如:
// stock_basic_info 索引
db.stock_basic_info.createIndex({ "symbol": 1, "market": 1 }, { unique: true })
db.stock_basic_info.createIndex({ "full_symbol": 1 }, { unique: true })
// stock_daily_quotes 索引
db.stock_daily_quotes.createIndex({ "symbol": 1, "market": 1, "trade_date": -1 }, { unique: true })
db.stock_daily_quotes.createIndex({ "market": 1, "trade_date": -1 })
// stock_financial_data 索引
db.stock_financial_data.createIndex({ "symbol": 1, "market": 1, "report_period": -1 }, { unique: true })
// stock_technical_indicators 索引
db.stock_technical_indicators.createIndex({ "symbol": 1, "market": 1, "trade_date": -1, "period": 1 }, { unique: true })
查询策略上,单市场查询({"market": "CN", "trade_date": "..."})性能最优,跨市场使用 $in,特定股票直接以 full_symbol 精确匹配。仓库中存在大量与此对应的数据同步与查询实现,例如 app/services/stock_data_service.py、app/services/historical_data_service.py、app/services/financial_data_service.py 与 app/routers/multi_market_stocks.py 等,可作为进一步研读入口。
股票数据获取方法分析:五层架构与数据流向
stock_data_methods_analysis.md 将数据获取体系梳理为五层:
- 用户接口层:后端 API 路由(
app/)、Web 界面、CLI 工具,以及 tradingagents/api/stock_api.py 提供的统一 API(get_stock_info/get_stock_data)。 - 统一接口层:
tradingagents/dataflows/interface.py提供市场自动识别的get_stock_data_by_market,以及按市场拆分的统一函数(A 股get_china_stock_data_unified、港股get_hk_stock_data_unified、美股get_YFin_data);tradingagents/dataflows/data_source_manager.py中的DataSourceManager负责数据源切换与可用源枚举。 - 优化数据提供器层:optimized_china_data.py 与 optimized_us_data.py 提供带缓存与限流控制的数据提供器,如
OptimizedChinaDataProvider.get_stock_data(symbol, start_date, end_date, force_refresh=False)。 - 数据源适配器层:对接 Tushare、AKShare、Yahoo、Finnhub、SimFin 等 SDK,负责原始数据抓取与格式转换。
- 缓存层:承载缓存优先级与数据源降级策略,减少 API 调用压力。
文档同时给出数据类型五分类(基础信息、历史数据、财务数据、实时数据、新闻情绪)与数据流向设计(缓存优先级与降级策略),性能优化建议集中在 API 限制、缓存策略与批量处理。这与设计目录中"数据获取与使用服务解耦、支持动态扩展新数据源 SDK"的演进方向一致。
设计演进脉络
README 记录的最新设计演进(2025-01-15)包括:
- 提示词模版系统 v1.0 落地:9 份设计文档、4 个分析师的模版规划、分步实现指南、10 个使用场景示例;
- 股票数据模型 v2.0:新增 CN/HK/US 多市场支持、技术指标分类扩展机制、索引优化与数据标准化、版本管理;
- 架构优化:数据获取与使用服务解耦、MongoDB 标准化数据模型、支持动态扩展新数据源 SDK。
当前源码已实现的设计要点可对照以下路径继续深入:Agent 体系见 tradingagents/agents/,数据模型见 app/models/stock_models.py,数据获取调用链见 tradingagents/dataflows/ 与 tradingagents/api/stock_api.py,API 与同步服务见 app/routers/ 与 app/services/。设计文档则可在 docs/design/ 目录下按上文导航继续深入阅读。