TradingAgents-CN 统一数据标准与实施路径：跨市场（CN/HK/US）标识、行业、单位、时区与冲突仲裁工程指南-育师

TradingAgents-CN 统一数据标准与实施路径：跨市场（CN/HK/US）标识、行业、单位、时区与冲突仲裁工程指南

【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN

日期：2025-10-19 · 项目：TradingAgents-CN · 文档定位：数据一致性标准（PIT）与跨源融合的工程指南

导读

本文是 TradingAgents-CN 在构建 CN/HK/US 三市场统一数据层时的工程标准与实施路径说明，围绕「标识、市场交易所、行业分类、单位时区、指标定义、冲突仲裁」六大不一致问题，定义了基于full_symbol = exchange_mic:symbol主键的 Canonical Schema，并给出从字典发布、适配器规范化到数据服务接口、黄金样本测试、前后端交付的四阶段落地计划。读完本文，你将掌握一套可直接用于多源行情、财务与基础信息融合的字段标准、枚举字典、规范化函数签名、仲裁与置信度评分规则，以及项目当前在 app/models/stock_models.py、app/services/data_sources/tushare_adapter.py 与 app/routers/multi_market_stocks.py 中的对应落地证据。

1. 核心问题拆解：六类数据不一致

跨市场、跨数据源的金融数据融合，首先面对的是「同一事物、多种说法」。文档将问题收敛为六类：

维度	不一致表现
行业分类	中文/英文/GICS/NAICS/自定义口径不一致，且层级不同（行业/板块/子行业语义错位）
市场与交易所	CN/HK/US 与 SSE/SZSE/HKEX/NASDAQ/NYSE 的字段、符号各说各话
标识	`ts_code`、`symbol`、`full_symbol`、`yfinance`规范不同；港股是否补零、A 股是否带后缀不一致
单位与时区	币种（CNY/HKD/USD）、金额单位（元/百万/亿）、时间与时区格式不统一
字段定义	财务指标口径（GAAP/IFRS/CAS）、“行业/板块”语义层级不同
值冲突	不同源给出名称/行业/财务数据不一致，需要仲裁与置信度规则

这些问题的本质是缺乏一个权威的中间表示（Canonical Form）：每个数据源各自携带一套隐式约定，直接消费必然产生歧义。文档给出的解法是建立统一数据模型，让所有来源在进入系统时先“翻译”到规范口径。

2. 统一数据模型（Canonical Schema）

统一数据模型分为七个域，各域解决一类问题。

2.1 标识与命名（Identity）

主键：采用full_symbol = exchange_mic:symbol；exchange_mic使用 ISO 10383 标准（如XSHG、XSHE、XHKG、XNAS、XNYS）。
symbol规则：
- A 股：不带后缀的 6 位数字（如600519）；full_symbol形如XSHG:600519或XSHE:000001。
- 港股：不做左侧补零的纯数字字符串（如5、0005、2388）；full_symbol形如XHKG:0005。保留vendor_symbols.hk_pad_left=4的适配能力（如yfinance: 0005.HK）。
- 美股：字母代码（如AAPL）；full_symbol形如XNAS:AAPL或XNYS:MSFT。
扩展标识：isin（推荐）、country（ISO 3166-1）、currency（ISO 4217）。
供应商映射：保留vendor_symbols = { tushare: 600519.SH, yfinance: 600519.SS, akshare: 600519 }，便于反向解析与对账。

这一设计与仓库现有模型方向一致：app/models/stock_models.py 中StockBasicInfoExtended已同时维护symbol（6 位数字，pattern=r"^\d{6}$"）、full_symbol与兼容字段code，并通过extra = "allow"保持向后兼容；MarketInfo子模型则承载market/exchange/exchange_name/currency/timezone的规范描述。

2.2 市场与交易所（Market/Exchange）

market取值：CN、HK、US；exchange_mic与exchange_name对齐；timezone使用 IANA（如Asia/Shanghai）。
交易日历统一由日历服务提供，含竞价/连续竞价/收盘阶段。

仓库中的枚举已先行落地：app/models/stock_models.py 定义了MarketType = Literal["CN", "HK", "US"]、ExchangeType = Literal["SZSE", "SSE", "SEHK", "NYSE", "NASDAQ"]、CurrencyType = Literal["CNY", "HKD", "USD"]；而 app/routers/multi_market_stocks.py 的/api/markets端点以元数据形式返回三市场的currency（CNY/HKD/USD）、timezone（Asia/Shanghai、Asia/Hong_Kong、America/New_York）与trading_hours，正是该标准的运行时体现。

2.3 行业分类（Industry Taxonomy）

采用GICS 作为规范口径，四级：sector、industry_group、industry、sub_industry，含gics_code。
原始行业字段保留：source_industry.name、source_industry.taxonomy（如 CN-Industry/GICS/NAICS）、source_industry.level、source_industry.code、map_confidence。
提供映射表：CN/自定义 → GICS；无法精确映射时标注approximate=true与置信区间。

设计要点是**“规范口径唯一、原始信息不丢”**：GICS 只作为对外输出的统一视图，来源口径全部留痕，映射过程显式记录置信度，避免在映射链路上二次丢失信息。

2.4 单位与币种（Units/Currency）

金额统一以数值 + 单位乘数表示：value+unit_multiplier（如1e6/1e8）；保留原始单位unit_hint（如元/百万/亿）。
currency统一为 ISO 4217；区别report_currency与trading_currency；提供fx_rate_timestamp以便需要时折算。

仓库中的 Tushare 适配器已经展示了“单位不一致必须显式转换”的实践：app/services/data_sources/tushare_adapter.py 在get_realtime_quotes中对成交量做了「手 → 股」的换算（vol = vol * 100），并在代码注释中明确标注这一单位语义，避免下游把“手”当“股”使用。

2.5 时间与时区（Time/Timezone）

所有事件与行情时间戳采用UTC；保留timezone以描述来源时区；支持session_id与阶段枚举（auction/open/regular/close）。
支持 PIT（Point-in-Time）：asof、effective_date、data_version、feature_version，确保复现实验可重放。

PIT 是金融数据分析与回测的关键：同一标的在不同时点看到的“最新”数据可能不同，只有冻结data_version/feature_version才能让历史实验精确复现。这与 app/models/stock_models.py 中为股票基础信息与行情模型预留的data_version字段形成呼应。

2.6 指标定义（Metric Definitions）

accounting_standard：GAAP/IFRS/CAS（中国会计准则）；保留definition_notes与restatement=true/false。
规范字段示例：revenue、net_income、eps_basic、eps_diluted、gross_margin、book_value_per_share；必要时提供normalized_value与转换说明。

三市场财务数据最隐蔽的坑在会计口径：同一“净利润”，CAS 与 IFRS/GAAP 的确认时点与范围可能不同，因此规范字段必须同时携带accounting_standard与重述标记，跨市场对比前先做口径归一。

2.7 值冲突仲裁（Arbitration）

加权聚合：综合source_priority（可信度预设）、freshness（时间新鲜度）、cross_validation（与第二来源校验）、variance（来源间差异）。
输出confidence_score（0–1）与source_of_truth（最终取值来源）；保留conflict_log以便审核。
提供人工覆盖台帐：manual_override，含审计字段与过期策略。

仲裁不是简单“取平均”，而是四要素加权：source_priority决定来源可信底座（仓库中 Tushare 适配器通过_get_default_priority()返回 3，注释明确“数字越大优先级越高”，可作为优先级语义的参考实现）；freshness惩罚过时数据；cross_validation鼓励多源一致；variance抑制离群值。最终输出置信度与来源留痕，供审计与人工兜底。

3. 实施路径（Phased Plan）

标准要落地，需按四个阶段渐进推进：

Phase 0：字典与规范

产出exchange_mic、market、timezone枚举字典；确定full_symbol规则与港股补零适配选项。
行业映射初稿：CN/自定义 → GICS；定义不可映射与近似映射标记。
指标口径定义与度量单位规范；PIT 与版本字段约定。

Phase 1：适配器与规范化函数

normalize_symbol(source, code)：解析并生成full_symbol与vendor_symbols。
map_industry(source_field)：映射到 GICS 并产出map_confidence。
normalize_units(value, unit_hint, currency)：标准化数值与单位乘数；区分报告币与交易币。
normalize_time(ts, timezone)：统一到 UTC 并保留来源时区。

Phase 2：数据服务接口

GET /meta/symbol/resolve：输入任意ts_code/symbol/yfinance，输出规范化身份与映射。
GET /data/candles：入参full_symbol/start/end/granularity/adjustment；返回ts(open/high/low/close/volume/turnover/currency)，timezone=UTC，含exchange_mic/market/unit_multiplier元数据。
GET /data/industry：返回 GICS 规范字段与来源映射。

Phase 3：校验与测试

构建黄金样本集（CN/HK/US 各 50–100 标的）；覆盖多来源差异与典型边界。
单元/集成测试：符号解析、行业映射、单位标准化、时间归一化与仲裁评分。
观测与审计：生成冲突报告与人工覆盖审计台帐。

Phase 4：交付与集成

前后端联调：统一模型接入回测与模拟交易服务；SSE/WebSocket 推送采用规范字段。
文档与版本：发布标准与字典文件；冻结data_version/feature_version与兼容策略。

仓库中的配套规划文档 docs/tech_reviews/2025-10-21-multi-market-data-architecture-guide.md 进一步给出了混合架构图：UnifiedMarketDataService作为统一查询接口层，向下路由到 A 股/港股/美股三套独立数据服务与各自 MongoDB 集合（*_cn/*_hk/*_us），其代码模板可参考 docs/tech_reviews/2025-10-21-multi-market-code-templates.md（含parse_full_symbol/normalize_symbol的调用方式、字段映射trade_date→date、vol→volume、turnover→amount的 DataFrame 归一化逻辑）。

4. 关键枚举与规则（摘要）

枚举/规则	取值
`market`	`CN`、`HK`、`US`
`exchange_mic`	`XSHG`（SSE）、`XSHE`（SZSE）、`XHKG`（HKEX）、`XNAS`（NASDAQ）、`XNYS`（NYSE）
`full_symbol`	`exchange_mic:symbol`；A 股不带后缀、港股不强制补零、美股字母代码
`timezone`	IANA 时区；所有时间戳以`UTC`存储
行业	采用 GICS 四级，保留来源字段与映射置信度

5. 快速示例

美股 AAPL：symbol=AAPL，full_symbol=XNAS:AAPL，yfinance=AAPL。
A 股贵州茅台：symbol=600519，full_symbol=XSHG:600519，tushare=600519.SH，yfinance=600519.SS。
港股长江和记：symbol=0005，full_symbol=XHKG:0005，yfinance=0005.HK（适配器支持左补零 4）。

注意港股示例中“不强制补零”与“vendor 适配补零”同时成立：规范层symbol为0005，仅在对接yfinance时按hk_pad_left=4适配为0005.HK——这正是「规范主键 + vendor 映射」设计的价值所在。仓库配套文档中的前端工具函数formatSymbolDisplay也展示了展示层可自行决定补零（如港股补 5 位），与存储层规范解耦，可参考 docs/tech_reviews/2025-10-21-multi-market-code-templates.md。

6. 落地检查清单（Checklist）

明确full_symbol与exchange_mic作为唯一主键，完成字典发布。
完成 CN/HK/US 的符号解析与来源映射适配器。
发布 GICS 映射表与map_confidence规则；标注不可映射场景。
金额单位标准化与币种处理；记录unit_multiplier与fx_rate_timestamp。
时间归一化至UTC；保留timezone与session_id。
启用仲裁与置信度评分；生成冲突与覆盖审计报告。
冻结data_version/feature_version，确保 PIT 可复现。

7. 结语与当前仓库落地状态

统一数据标准是 TradingAgents-CN 从“单市场 A 股框架”走向“跨市场多源融合”的地基工程。从当前仓库代码看，标准的关键骨架已部分落地：

枚举与模型：MarketType/ExchangeType/CurrencyType、MarketInfo、带full_symbol与data_version的扩展模型，见 app/models/stock_models.py；
多市场接口：/api/markets提供三市场元数据与跨市场搜索路由，见 app/routers/multi_market_stocks.py；
单位与优先级实践：Tushare 适配器中的“手→股”换算与优先级设定，见 app/services/data_sources/tushare_adapter.py；
统一服务与代码模板：UnifiedMarketDataService的拆分路由与字段归一化设计，见 docs/tech_reviews/2025-10-21-multi-market-data-architecture-guide.md 与 docs/tech_reviews/2025-10-21-multi-market-code-templates.md。