TradingAgents-CN 设计文档体系解析:提示词模版系统、股票数据模型与多源数据架构全景指南

原创2026-09-09 20:37:451,614 阅读
文章标签:金融科技多智能体AI Agent人工智能大模型后端前端数据分析

TradingAgents-CN 设计文档体系解析:提示词模版系统、股票数据模型与多源数据架构全景指南

TradingAgents-CN 在 docs/design/ 目录下沉淀了一套覆盖系统架构、数据模型、API 规范与提示词模版系统的完整设计文档体系,本文以该设计目录为脉络,系统讲解其中三大核心板块:面向 13 个 Agent 的提示词模版系统设计(v1.0.1)、支撑 CN/HK/US 多市场的股票数据模型设计,以及"数据获取与使用解耦"的多层数据架构,并逐一对照仓库源码给出实现级证据。读完本文,你将掌握该项目的设计组织方式、核心数据结构的字段语义与索引策略,以及提示词模版系统的版本规划与实现路线,可直接据此定位到对应源码和设计文档进行二次开发。

设计文档体系的组织方式

文档索引结构

设计文档目录 是整个项目设计资产的入口,按四类主题组织:

按该目录的统计,提示词模版系统 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 示例见原文档):

  1. 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)、沪深港通标记与数据版本号。
  2. stock_daily_quotes(历史行情):以 (symbol, market, trade_date) 唯一约束,含开高低收、涨跌额/涨跌幅、成交量额、换手率、量比、PE/PB/PS、股息率、市值与复权因子。
  3. stock_realtime_quotes(实时行情):在日线字段基础上扩展五档盘口(bid_prices/bid_volumes/ask_prices/ask_volumes 各 5 档)与行情时间戳。
  4. stock_financial_data(财务数据):按 report_period + report_type 组织,内嵌资产负债表、利润表、现金流量表三大报表子对象,并附带 ROE/ROA/毛利率/净利率/资产负债率/流动比率等财务指标。
  5. stock_news(新闻数据):含标题、正文、摘要、来源、情绪分析与得分、关键词、重要性分级与语言标记。
  6. social_media_messages(社媒消息):覆盖微博/微信/抖音/小红书/知乎/Twitter/Reddit 等平台,记录消息类型(post/comment/repost/reply)、作者画像(认证、粉丝数、影响力评分)、互动数据(点赞/转发/评论/互动率)、情绪与可信度、地理位置及抓取元数据。
  7. internal_messages(内部消息):面向研究报告、内幕信息、分析师纪要等内部数据,设计来源可靠性、影响范围、时效性、访问级别与权限控制。
  8. 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 将数据获取体系梳理为五层:

  1. 用户接口层:后端 API 路由(app/)、Web 界面、CLI 工具,以及 tradingagents/api/stock_api.py 提供的统一 API(get_stock_info / get_stock_data)。
  2. 统一接口层: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 负责数据源切换与可用源枚举。
  3. 优化数据提供器层:optimized_china_data.py 与 optimized_us_data.py 提供带缓存与限流控制的数据提供器,如 OptimizedChinaDataProvider.get_stock_data(symbol, start_date, end_date, force_refresh=False)。
  4. 数据源适配器层:对接 Tushare、AKShare、Yahoo、Finnhub、SimFin 等 SDK,负责原始数据抓取与格式转换。
  5. 缓存层:承载缓存优先级与数据源降级策略,减少 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/ 目录下按上文导航继续深入阅读。

登录后查看全文
TradingAgents-CN