股票市场数据源¶

📎 引用文件

本文引用的文件 - agent/backtest/loaders/yahoo_loader.py - agent/backtest/loaders/yahoo_client.py - agent/backtest/loaders/tushare.py - agent/backtest/loaders/eastmoney_loader.py - agent/backtest/loaders/eastmoney_client.py - agent/backtest/loaders/akshare_loader.py - agent/backtest/loaders/baostock_loader.py - agent/backtest/loaders/cn_adjust.py - agent/backtest/loaders/base.py - agent/backtest/loaders/registry.py

简介¶

本文件面向 Vibe-Trading 的股票市场数据源集成，覆盖 Yahoo Finance、Tushare、东方财富、AKShare、BaoStock 等主流数据源的实现细节。重点说明各数据源的认证方式、数据格式差异、时区处理、复权因子计算逻辑；并给出获取策略、频率限制、错误恢复机制；以及 A 股、美股、港股等多市场数据同步的最佳实践（一致性保证与增量更新）。最后提供常见问题诊断方法与性能调优建议（连接池、缓存、并发控制）。

项目结构¶

数据源以“加载器（Loader）+ 客户端（Client）”的层次组织： - Loader：负责将外部数据源映射为统一的 OHLCV DataFrame（trade_date 索引 + open/high/low/close/volume），并封装日期校验、缓存、重试等通用逻辑。 - Client：封装特定数据源的 HTTP/TCP 协议、鉴权、符号解析、节流等底层细节。 - Registry：维护市场到数据源的降级链（fallback chain），自动选择可用数据源。 - Base：提供统一的数据验证、重试预算、本地 Parquet 缓存等基础设施。

graph TB subgraph "加载器层" YL["Yahoo Loader"] TS["Tushare Loader"] EM["Eastmoney Loader"] AK["AKShare Loader"] BS["BaoStock Loader"] end subgraph "客户端层" YC["Yahoo Client"] EC["Eastmoney Client"] end subgraph "基础设施" REG["Registry(降级链)"] BASE["Base(校验/重试/缓存)"] ADJ["CN Adjust(前复权)"] end YL --> YC EM --> EC TS --> ADJ YL --> BASE TS --> BASE EM --> BASE AK --> BASE BS --> BASE REG --> YL REG --> TS REG --> EM REG --> AK REG --> BS

图表来源 - agent/backtest/loaders/yahoo_loader.py:173-271 - agent/backtest/loaders/yahoo_client.py:156-205 - agent/backtest/loaders/tushare.py:116-202 - agent/backtest/loaders/eastmoney_loader.py:51-143 - agent/backtest/loaders/eastmoney_client.py:208-325 - agent/backtest/loaders/akshare_loader.py:74-157 - agent/backtest/loaders/baostock_loader.py:32-108 - agent/backtest/loaders/cn_adjust.py:27-78 - agent/backtest/loaders/base.py:31-119 - agent/backtest/loaders/registry.py:136-155

章节来源 - agent/backtest/loaders/registry.py:136-155 - agent/backtest/loaders/base.py:31-119

核心组件¶

统一接口与校验
DataLoaderProtocol：定义 name/markets/requires_auth/is_available/fetch 的统一契约。
validate_date_range：确保起止日期合法且顺序正确。
validate_ohlc：对 OHLC 不变量进行校验（高低于低、价格非正等），保障下游回测稳定性。
重试与预算
retry_with_budget：基于单调时钟的超时预算与指数退避，仅对声明的瞬时异常重试。
本地缓存
cached_loader_fetch/loader_cache_*：按 source/symbol/timeframe/date range 生成内容寻址键，落盘为 Parquet，避免重复拉取。
市场降级链
FALLBACK_CHAINS：按市场类型定义数据源优先级，优先使用轻量、免认证的公共接口，再回退到 key-gated 或付费源。

章节来源 - agent/backtest/loaders/base.py:122-236 - agent/backtest/loaders/base.py:243-439 - agent/backtest/loaders/registry.py:136-155

架构总览¶

下图展示从调用方到具体数据源的请求路径，包括符号路由、客户端节流、数据标准化与缓存。

sequenceDiagram participant Caller as "调用方" participant Reg as "Registry" participant Ldr as "DataLoader" participant Cli as "Client" participant Cache as "本地缓存" participant API as "外部API" Caller->>Reg : resolve_loader(market) Reg-->>Caller : 返回可用Loader实例 Caller->>Ldr : fetch(codes, start, end, interval) Ldr->>Cache : 查询缓存 alt 命中缓存 Cache-->>Ldr : 返回DataFrame else 未命中 Ldr->>Cli : 发起请求(带节流/鉴权) Cli->>API : HTTP/TCP 请求 API-->>Cli : 原始数据 Cli-->>Ldr : 标准化行/列 Ldr->>Cache : 写入缓存(可选) Cache-->>Ldr : 确认写入 end Ldr-->>Caller : {symbol : DataFrame}

图表来源 - agent/backtest/loaders/registry.py:158-193 - agent/backtest/loaders/base.py:401-439 - agent/backtest/loaders/yahoo_client.py:156-205 - agent/backtest/loaders/eastmoney_client.py:269-325

详细组件分析¶

Yahoo Finance（yahoo_loader + yahoo_client）¶

认证方式：无认证，直接访问公开 v8 chart 端点；quoteSummary/options 需要 cookie+crumb，由客户端自动握手并在 401 时刷新。
数据格式：返回 epoch 秒时间戳与 OHLCV 数组；Loader 将其转为 tz-naive 的 DatetimeIndex，日级时间归一化至午夜，分钟/小时级保留真实时间戳。
时区处理：UTC 时间戳转本地无时区索引，日级对齐 midnight，避免跨时区合并问题。
频率限制：通过共享 host_key 的最小间隔门控与会话复用，避免 IP 限流。
错误恢复：单只失败不影响批量；日志记录并跳过。
适用市场：美股、港股、印度、韩国、加拿大等（后缀识别）。

flowchart TD Start(["开始"]) --> CheckSupported{"是否支持的后缀?"} CheckSupported -- 否 --> ReturnNone["返回 None"] CheckSupported -- 是 --> MapInterval["映射区间(1D/1H/4H→1h/1W/1M)"] MapInterval --> BuildWindow["计算 period1/period2(epoch)"] BuildWindow --> FetchChart["调用 Yahoo v8 chart"] FetchChart --> ParseRows["解析为行列表"] ParseRows --> Normalize["构建DataFrame<br/>索引归一化/裁剪窗口"] Normalize --> Result{"是否有数据?"} Result -- 否 --> ReturnNone Result -- 是 --> ReturnDF["返回OHLCV DataFrame"]

图表来源 - agent/backtest/loaders/yahoo_loader.py:44-106 - agent/backtest/loaders/yahoo_loader.py:125-170 - agent/backtest/loaders/yahoo_loader.py:240-271 - agent/backtest/loaders/yahoo_client.py:71-92 - agent/backtest/loaders/yahoo_client.py:156-205

章节来源 - agent/backtest/loaders/yahoo_loader.py:173-271 - agent/backtest/loaders/yahoo_client.py:95-153 - agent/backtest/loaders/yahoo_client.py:253-308

Tushare（tushare.py + cn_adjust.py）¶

认证方式：需要 TUSHARE_TOKEN；初始化 pro_api。
数据格式：A 股/基金/指数/港股日线；分钟线需更高权限；字段名含 vol → volume。
复权因子：日线默认返回未复权价，需调用 adj_factor/fund_adj 并通过 apply_qfq 做前复权；若因子不可用则丢弃该标的，避免跨除权日的收益失真。
频率限制：针对每分钟/每天配额拒绝，内置关键词识别与退避重试（5s/20s/40s）。
错误恢复：单只失败不影响整体；分钟线不支持 ETF/指数/HK/US/crypto 会跳过。
适用市场：A 股、港股、期货、基金（部分分钟线受限）。

flowchart TD S(["开始"]) --> Type{"标的类型"} Type -- A股/基金 --> Daily["调用 daily/fund_daily"] Type -- 指数 --> IndexDaily["index_daily(无需复权)"] Type -- 港股 --> HKDaily["hk_daily(无复权因子)"] Type -- US/加密 --> Skip["跳过(Tushare不支持)"] Daily --> Adj["获取adj_factor并apply_qfq"] IndexDaily --> Frame["标准化为OHLCV"] HKDaily --> Frame Adj --> Frame Frame --> Out["返回DataFrame"] Skip --> Out

图表来源 - agent/backtest/loaders/tushare.py:116-202 - agent/backtest/loaders/tushare.py:204-265 - agent/backtest/loaders/tushare.py:322-383 - agent/backtest/loaders/cn_adjust.py:27-78

章节来源 - agent/backtest/loaders/tushare.py:116-202 - agent/backtest/loaders/cn_adjust.py:27-78

东方财富（eastmoney_loader + eastmoney_client）¶

认证方式：无认证，免费 push2his 接口；严格 IP 限速，通过共享 host_key 节流。
数据格式：secid 标识（如 1.600519 / 116.00700 / 105.AAPL）；klt 周期码映射；fqt=1 表示前复权。
符号解析：A 股 SH/SZ/BJ 映射到 1./0.；港股五位数补零；美股通过搜索接口发现市场前缀并缓存。
错误恢复：单只失败不影响批量；不支持的区间直接跳过。
适用市场：A 股、港股、美股。

sequenceDiagram participant L as "Eastmoney Loader" participant C as "Eastmoney Client" participant E as "push2his" L->>C : resolve_secid(symbol) C-->>L : secid(如 1.600519) L->>C : fetch_kline(secid, klt, fqt=1, beg/end) C->>E : GET /api/qt/stock/kline/get E-->>C : JSON(klines字符串数组) C-->>L : 解析为行列表 L-->>L : 标准化为OHLCV DataFrame L-->>L : 写入缓存(可选)

图表来源 - agent/backtest/loaders/eastmoney_loader.py:51-143 - agent/backtest/loaders/eastmoney_client.py:208-325

章节来源 - agent/backtest/loaders/eastmoney_loader.py:51-143 - agent/backtest/loaders/eastmoney_client.py:105-205

AKShare（akshare_loader.py）¶

认证方式：无认证，完全免费聚合器。
数据格式：A 股/美股/港股/ETF/外汇；中文/英文列名兼容；外汇无成交量，合成 0。
区间限制：美股/港股/ETF/外汇仅支持日线；A 股支持 daily/weekly/monthly。
错误恢复：单只失败不影响批量；外汇通过 forex_hist_em 获取。
适用市场：A 股、美股、港股、期货、基金、宏观、外汇。

章节来源 - agent/backtest/loaders/akshare_loader.py:74-157 - agent/backtest/loaders/akshare_loader.py:158-292

BaoStock（baostock_loader.py）¶

认证方式：无认证，TCP 协议（绕过 CDN IP 封禁）。
数据格式：A 股日线；支持 sh.601398 与 601398.SH 两种形式；前复权 adjustflag="2"。
区间限制：仅日线；其他区间会被拒绝。
错误恢复：登录失败或查询失败记录日志并跳过。
适用市场：A 股。

章节来源 - agent/backtest/loaders/baostock_loader.py:32-108 - agent/backtest/loaders/baostock_loader.py:110-164

依赖关系分析¶

市场到数据源的降级链（FALLBACK_CHAINS）：
a_share: tencent → mootdx → eastmoney → baostock → akshare → tushare → local
us_equity: yahoo → stooq → sina → eastmoney → yfinance → tiingo → fmp → finnhub → alphavantage → longbridge → akshare → local
hk_equity: tencent → eastmoney → yahoo → futu → akshare → yfinance → tushare → longbridge → local
其他市场类似，优先无认证公共接口，再回退 key-gated 或付费源。
加载器注册：所有 loader 通过 @register 装饰器注入全局 LOADER_REGISTRY；resolve_loader 按市场遍历降级链，首个 is_available() 为真即返回。

graph LR M_a["a_share"] --> TENC["tencent"] M_a --> MOOT["mootdx"] M_a --> EM["eastmoney"] M_a --> BS["baostock"] M_a --> AK["akshare"] M_a --> TS["tushare"] M_a --> LOC["local"] M_us["us_equity"] --> YH["yahoo"] M_us --> STQ["stooq"] M_us --> SIN["sina"] M_us --> EM M_us --> YF["yfinance"] M_us --> TI["tiingo"] M_us --> FMP["fmp"] M_us --> FH["finnhub"] M_us --> AV["alphavantage"] M_us --> LB["longbridge"] M_us --> AK M_us --> LOC M_hk["hk_equity"] --> TENC M_hk --> EM M_hk --> YH M_hk --> FUTU["futu"] M_hk --> AK M_hk --> YF M_hk --> TS M_hk --> LB M_hk --> LOC

图表来源 - agent/backtest/loaders/registry.py:136-155

章节来源 - agent/backtest/loaders/registry.py:136-155

性能与并发优化¶

连接与会话
Yahoo/Eastmoney 通过共享 host_key 与最小间隔门控复用会话，降低握手开销与触发限流概率。
BaoStock 使用 TCP 直连，规避 HTTP CDN 封禁。
缓存策略
启用 VIBE_TRADING_DATA_CACHE=true 后，按 content-addressed 键存储 Parquet，避免重复拉取历史数据；end_date 必须已结算才缓存。
读写失败均不中断主流程，自动回退到在线获取。
重试与预算
通用 retry_with_budget 提供超时预算与指数退避；Tushare 针对配额拒绝自定义退避序列。
并发优化建议
批量拉取时利用 per-symbol 循环与缓存命中减少网络调用。
合理设置环境变量调整最小间隔（如 VIBE_TRADING_YAHOO_MIN_INTERVAL、VIBE_TRADING_EASTMONEY_MIN_INTERVAL）。
对分钟级数据谨慎并发，避免触发更严格的速率限制。

章节来源 - agent/backtest/loaders/base.py:122-236 - agent/backtest/loaders/base.py:243-439 - agent/backtest/loaders/yahoo_client.py:66-69 - agent/backtest/loaders/eastmoney_client.py:76-79

故障排查指南¶

常见错误与定位
日期范围无效或倒序：validate_date_range 抛出 ValueError，检查传入日期格式与顺序。
OHLC 异常：validate_ohlc 检测 high<low、价格非正等，必要时采用 drop/warn/raise 策略。
数据源不可用：NoAvailableSourceError 提示尝试过的数据源，检查网络与 Token 配置。
Yahoo 401：quoteSummary/options 需要 crumb，客户端会自动刷新一次；若仍失败，检查网络与 UA/Cookie。
Tushare 配额限制：识别“每分钟/每天/抽取/访问该接口/频率/rate limit/too many requests”，执行退避重试。
Eastmoney 美国代码解析失败：search 接口未找到匹配，检查 ticker 拼写与网络。
日志与调试
各 Loader 在失败时记录警告日志，包含 symbol 与错误信息，便于快速定位。
启用本地缓存可显著减少重复请求，便于对比线上与离线结果。

章节来源 - agent/backtest/loaders/base.py:31-119 - agent/backtest/loaders/tushare.py:18-35 - agent/backtest/loaders/yahoo_client.py:253-308 - agent/backtest/loaders/eastmoney_client.py:179-205

结论¶

Vibe-Trading 的数据源层通过统一的 Loader 接口、健壮的校验与缓存、灵活的降级链与节流策略，实现了多市场、多数据源的稳定接入。Yahoo 适合全球权益与外汇，Tushare 提供 A 股深度与基本面扩展，东方财富覆盖 A/HK/US 且免费高效，AKShare 作为免费聚合补充广泛资产类别，BaoStock 以 TCP 直连规避封禁。结合本地缓存与重试预算，可在保证一致性的同时提升吞吐与鲁棒性。

附录：多市场同步最佳实践¶

数据一致性保证
统一 OHLCV 规范：所有 Loader 输出 trade_date 索引与 open/high/low/close/volume 列，便于跨源对齐。
时区对齐：Yahoo 日级时间归一化至午夜；分钟级保留真实时间戳，避免跨时区错位。
复权一致：A 股优先使用前复权（Tushare 通过 apply_qfq；Eastmoney 通过 fqt=1；BaoStock adjustflag="2"；AKShare 使用 qfq），确保收益可比。
增量更新策略
使用 end_date 为已结算日方可缓存；当日数据不缓存，避免钉住未完成 K 线。
按 market 维度维护 last_update_time，仅拉取新增区间；结合缓存命中减少重复请求。
对分钟级数据，建议分时段增量拉取，避免单次过大窗口导致限流。
多市场调度建议
A 股：优先 tencent/mootdx/eastmoney/baostock，其次 akshare/tushare。
美股：优先 yahoo/stooq/eastmoney/yfinance，再回退 tiingo/fmp/finnhub/alphavantage。
港股：优先 tencent/eastmoney/yahoo/futu，再回退 akshare/yfinance/tushare。
外汇/期货/基金：优先 akshare/tushare/local。
性能调优清单
设置合适的最小间隔（Yahoo/Eastmoney），避免触发 IP 限流。
开启本地缓存，减少重复拉取。
批量拉取时分片与并行度控制，避免瞬时峰值。
监控日志中的配额拒绝与 401 次数，动态调整并发与间隔。

← 数据源架构设计基本面数据源 →