跳到主要内容

外部数据源单点规约（Data Providers）

§0 范围与定位​

本文件是 FinBayes 所有外部数据源的单点派生源：字段映射 / API 版本 / freshness SLA / 凭证治理 / v1 工程回退五维一站规约。事实源是 ADR-007 supplement §5.3「已知工程依赖」清单 + 4 个子系统文档零散提及。本文件不新增治理决定，只把散落字段聚拢；字段口径冲突以上位事实源（ADR-007 supplement / 主架构 §15-§18）为准。命名约定：数据源 ID 用 kebab-case，内部字段用 snake_case（与 ADR-008 supplement 一致）。

§1 数据源全清单​

M0 不消费任何外部数据，全部走 Mock Provider Fixture（详见 M0 Walking Skeleton 工程包 §7）。本表所有数据源均在 M2+ 阶段接入，M0 仅在 Provider Adapter 接口层留 placeholder。

数据源 ID全称提供方主要用途涉及子系统接入里程碑
cftc-tffCFTC Traders in Financial FuturesCFTCM5.3(a) 急性流动性 / MCA 轴 6KG / MCAM2
sec-13fSEC Form 13F 机构持仓季报SEC EDGARM1 持有人结构 / M5.3(b) / MCA 轴 1KG / MCAM2
fx-swap外汇掉期 / 跨境资金成本央行 + Bloomberg/Refinitiv 代理M5 跨境资本反向力 / MCA 轴 7KG / MCAM3
etf-flowETF 资金流向（含 spot BTC ETF）issuer / SoSoValue / FarsideM5.3(b) / Attention 二阶分支KG / ConsistencyM2
gbtc-premiumGBTC 折溢价Grayscale + 二级行情M5.5 反向力量（套利者）KG / MCAM2
onchain-first-sign链上首签 / funding / 集中度 / KOLGlassnode / Nansen / Dune / 交易所Attention 二阶分支 5 信号Consistency / KGM2
margin-balance-cnA 股两融余额沪深交易所M5.3(d) 代理 / 任务 BKGM2
csi300-tail沪深 300 单日跌幅尾部沪深交易所 + Wind/通联M5.3(d) 代理 / MCA 轴 1KG / MCAM2
limit-updown-count涨跌停 / 千股停牌计数沪深交易所M5.3(d) 代理 / MCA 轴 3KG / MCAM2
iv-surface隐含波动率曲面交易所 + Bloomberg/RefinitivM6.3 衍生品支柱 / MCA 轴 6KG / MCAM2
cross-border-quota跨境通道额度（沪深港通 / QFII）港交所 + SAFEMCA 轴 7MCAM3
policy-announcement-freq政策公告频次 + 监管盘中表态央行 / 证监会 / Fed / ECBM2.4 政策语义 / M5.3(c) 代理KGM2
industry-abs-spread行业 ABS 信用利差中证指数 + WindM5.3(c) 代理KGM2
property-usd-bond-yield房企美元债收益率iBoxx / Bloomberg / RefinitivM5.3(c) 代理（A-2 校准）KGM2
sovereign-fund-disclosure主权基金披露各 SWF + SWF InstituteMCA 轴 4 N2MCAM3
cb-fx-data央行汇率与利率Fed / ECB / BOJ / PBOC / SAFEM3 利率时钟 / M6.7 双轨 / 轴 7KG / MCAM2
disclosure-quality-rating披露质量评级交易所考核 + 第三方MCA 轴 5 信息环境MCAM3
wind-augmented万得 / 信达 增值字段（商用）万得 / 信达v2 升级 M5.3(c)(d) 自动判定KG / MCAv2
external-judge-corpusD7 外部独立标答源Damodaran / Marks / Stratechery / FT Alphaville评测 D7EvalHarnessM6

§2 每个数据源的详细规约​

字段示例只列与 FinBayes 内部强相关的关键字段；完整 schema 待工程实施仓 Provider Adapter 落地时锁定。每条规约统一含「版本/形态 · 字段映射 · freshness · 凭证 · 坑点 · v1 回退」六维。

§2.1 cftc-tff​

CFTC TFF 报告 v1（自 2010），CFTC 官网 CSV 周下载 + Socrata Open Data API（可选）。字段映射：report_date_as_yyyy_mm_dd → report_date；dealer_intermediary_positions_long/_short → dealer_long_oi/dealer_short_oi；asset_manager_*/leveraged_funds_* 类推。freshness：周频（每周五美东 15:30 发布上周二快照）。凭证：公开免登录。速率：CSV 无限制；Socrata 默认 1000 req/h。坑点：节假日延后 1 个工作日；2020 起 cryptocurrency contracts 单独报表。v1 回退：不可得时改用 13F 持仓变动作弱代理；M5.3(a) 降级为半人工标注（任务 A）。

§2.2 sec-13f​

SEC EDGAR Form 13F-HR / 13F-NT；EDGAR API（按 endpoint 区分）。字段映射：cik → filer_cik；periodOfReport → report_period；infoTable.cusip → holding_cusip；infoTable.value → holding_value_usd（2022Q4 起单位由千美元改为完整美元）；sshPrnamt → holding_shares。freshness：季频，季末 T+45 完整可得。凭证：公开，SEC 要求 User-Agent 标识联系方式（写入 Config Store，不进 Credential Store）。速率：10 req/s per IP。坑点：仅披露多头股票仓位；CUSIP→ticker 需第三方映射。v1 回退：不可得时改用 8-K / DEF 14A 大股东披露作粗粒度代理。

§2.3 fx-swap​

央行公开 + Bloomberg BFIX / Refinitiv FX 代理（商用）。字段映射：currency_pair → pair_code；tenor → tenor_code（1W/1M/3M/6M/1Y）；bid_swap_points/ask_swap_points → bid_swap_pts/ask_swap_pts；implied_yield_diff → implied_yield_spread_bps。freshness：日频（伦敦 16:00 BST 快照），商用源可实时。凭证：商用 API key 走 Credential Store（OS Keychain，参见主架构 §15）。坑点：央行端只发主要货币对；EM 货币流动性稀薄；SOFR 替代 LIBOR 后利差基准重定义。v1 回退：v1 仅消费 G7 主要货币对央行端公开数据；EM 货币降级为 MCA 轴 7 半人工标注。

§2.4 etf-flow​

issuer 官网 / SoSoValue / Farside Investors。字段映射：ticker → etf_ticker；as_of_date → flow_date；net_flow_usd → net_flow_usd；aum_usd → aum_usd。freshness：日频（T+1 美东 18:00 后稳定）。凭证：issuer 公开；第三方聚合源注册型 API key 走 Credential Store。坑点：2024-01 spot BTC ETF 上线后 11 只发行人口径不齐；GBTC 二级流动 ≠ creations/redemptions。v1 回退：聚合源不可得时逐 issuer 爬；BTC spot ETF 不可得时退到 gbtc-premium。

§2.5 gbtc-premium​

Grayscale 官网 NAV + 二级行情，HTTPS 公开。字段映射：nav_per_share → nav_per_share_usd；market_price → market_price_usd；premium_discount_pct → premium_discount_pct。freshness：日频（NAV 下午 T+0；市场价实时）。凭证：公开。坑点：2024-01 转 spot ETF 后折溢价机制结构性变化（套利通道开放）。v1 回退：纳入 M5.5 反向力量案例库即可。

§2.6 onchain-first-sign​

Glassnode v1 / Nansen v1 / Dune / 交易所 perpetual 公开。字段映射：funding_rate_8h → funding_rate_8h_bps；first_sign_address_count → first_sign_addr_count；top10_concentration_pct → top10_holder_concentration_pct；kol_mention_count_24h → kol_mention_24h。freshness：实时到 15 分钟；KOL 信号 1 小时。凭证：Glassnode / Nansen 商用 key + Dune 注册 key，全部走 Credential Store。速率：Glassnode 10 req/s 免费 / 100 req/s 商用；交易所 perpetual 通常 20 req/s。坑点：「first-sign」定义跨 provider 口径不一致；funding rate 跨所归一化要按合约规模加权。v1 回退：单一商用源不可得时降级为 Dune SQL + 交易所公开 API；阈值校准 fallback 到默认值（详见 一致性中间件 待校准项）。

§2.7 margin-balance-cn​

沪深交易所每日融资融券公告，HTTPS CSV / JSON 公开。字段映射：trade_date → report_date；financing_balance_yuan → margin_long_balance_yuan；securities_balance_yuan → margin_short_balance_yuan。freshness：日频（T+1 上午 9:00 前发布前一日）。凭证：公开。坑点：场外配资数据不公开（v1 回退根因）；融资融券标的范围动态扩缩。v1 回退：作为 M5.3(d) 公开代理触发条件之一；触发后由 reviewer 在 24 小时内补全场外配资细节（任务 B）。

§2.8 csi300-tail / limit-updown-count​

沪深交易所公开 + Wind / 通联代理。字段映射：daily_return_pct → daily_return_pct；count_limit_up/count_limit_down → limit_up_count/limit_down_count；count_suspended → suspended_count。freshness：日频（收盘后 1 小时内）。凭证：交易所端公开；商用代理 key 走 Credential Store。坑点：A 股 2020 起涨跌停规则板块差异化（主板 ±10% / 创业板 / 科创板 ±20%），计数需按板块归类。v1 回退：与 margin-balance-cn 联合作为 M5.3(d) 代理。

§2.9 iv-surface​

交易所自有 + Bloomberg / Refinitiv 代理。字段映射：underlying_code → underlying_code；expiry_date → expiry_date；strike → strike；iv → implied_vol_pct；delta → delta。freshness：实时（商用）/ 收盘日频（自拟合）。凭证：商用 API key 走 Credential Store。坑点：A 股期权品种少（50ETF / 300ETF / 个股期权），曲面自由度低；加密期权（Deribit）流动性集中。v1 回退：M6.3 衍生品支柱在 IV 不可得时按 M6.4 输出 applicable=not-applicable。

§2.10 cross-border-quota​

港交所沪深港通每日额度 + SAFE QFII / RQFII 月度披露，HTTPS 公开。字段映射：northbound_quota_used_yuan → northbound_used_yuan；southbound_quota_used_yuan → southbound_used_yuan；daily_quota_yuan → daily_quota_yuan。freshness：日频（沪深港通收盘后）/ 月频（QFII / RQFII）。凭证：公开。坑点：2018 沪深港通额度扩容口径变化；2020 起 QFII / RQFII 整合监管。v1 回退：MCA 轴 7 主信号；不可得时退到半人工标注。

§2.11 policy-announcement-freq​

央行 / 证监会 / 国新办 / Fed FOMC / ECB / BOJ 公开 RSS + 官网。字段映射：publication_timestamp → published_at；regulator_code → regulator_code（PBOC/CSRC/FED/ECB 等）；document_type → doc_type；raw_text → raw_text。freshness：事件驱动（公告 ≤ 15 分钟入库）。凭证：公开 RSS；第三方政策语义聚合 key 走 Credential Store。坑点：盘中表态（行长答记者问 / 非正式发言）无结构化公告，需 reviewer 人工抽取。v1 回退：M2.4 政策语义降级为「正则触发 + LLM 摘要」；M5.3(c) 形态走半人工标注（任务 A）。

§2.12 industry-abs-spread / property-usd-bond-yield​

中证指数 / iBoxx / Bloomberg / Refinitiv，商用 API。字段映射：index_code → index_code；oas_bps → option_adjusted_spread_bps；yield_to_worst → yield_to_worst_pct。freshness：日频；凭证：商用 API key 走 Credential Store。坑点：中资美元债 2021 起多次跨境违约 / 重组事件后样本结构变化。v1 回退：M5.3(c) 公开代理；不可得时降级为信用利差总指数 + reviewer 标注。

§2.13 sovereign-fund-disclosure​

各 SWF 官网 + SWF Institute 聚合（半年频），HTTPS / PDF 抽取。字段映射：fund_id → swf_id；as_of_date → disclosure_date；holding_value_usd → holding_value_usd。freshness：半年到年度；凭证：公开。坑点：披露范围按国家差异巨大（挪威 GPFG 全披露 / 中投 / 沙特 PIF 部分披露）。v1 回退：MCA 轴 4 = N2 主信号；不可得时降级到轴 4 N3 走半人工标注（任务 D）。

§2.14 cb-fx-data​

Fed H.15 / ECB SDW / BOJ TKR / PBOC + SAFE 中间价，HTTPS CSV / JSON / API 公开。字段映射：fixing_date → fixing_date；currency_pair → pair_code；mid_rate → mid_rate。freshness：日频（央行 fixing）；凭证：公开；速率：通常 60 req/min。坑点：人民币中间价 vs 离岸 CNH 价差是 MCA 轴 7 关键子维度；2015-08 汇改 / 2018 中间价机制调整需作为时间窗切片。v1 回退：M3 利率时钟 + M6.7 双轨主输入；不可得时退到第三方代理。

§2.15 disclosure-quality-rating​

交易所披露考核（深交所 / 上交所信息披露考核结果，年度）+ 第三方 ESG / 财务质量评级。字段映射：ticker → ticker；disclosure_grade → disclosure_grade（A/B/C/D）；as_of_year → as_of_year。freshness：年度；凭证：交易所公开；商用 key 走 Credential Store。坑点：评级口径 2021 沪深交易所改革后变更。v1 回退：MCA 轴 5 子信号；不可得时退到 reviewer 标注。

§2.16 wind-augmented​

万得资讯 EDB / 信达证券增值字段（商用），API + 桌面终端。字段映射：v1 不固化，待 v2 数据通路扩展时锁定。freshness：因字段而异；凭证：商用 API key 走 Credential Store；终端 license 不进 FinBayes。坑点：license 条款限制重新分发，接入前必须确认 license 范围允许在 FinBayes runtime 内消费。v1 回退：v1 完全不依赖；列入清单仅为 v2 升级路径占位（与 M5.3(c)(d) 自动判定升级路径绑定，详见 Phase 7 半人工标注 SLA 附录「路径升级」段）。

§2.17 external-judge-corpus​

Damodaran NYU Stern / Howard Marks Memos / Stratechery / FT Alphaville 公开文章。字段映射：用作 D7 评测样本独立标答源；字段定义见 评测台架子系统。freshness：事件驱动（按作者发布节奏）；凭证：公开。坑点：版权与抓取频率合规。v1 回退：评测体系外部独立标答源，非生产数据通路。

§3 跨数据源协同​

必须组合使用的数据源对：

  • cftc-tff + sec-13f：组合校验机构衍生品 net positioning 与现货持仓的方向一致性，用于 M5.3(a)(b) 形态判定
  • etf-flow + gbtc-premium：校验数字资产代理工具的「申赎流」vs「二级溢价」结构性置换信号，用于 M5.3(b)
  • margin-balance-cn + csi300-tail + limit-updown-count：三源联合触发 M5.3(d) 代理信号，任一单源不足以触发 reviewer 工作流
  • policy-announcement-freq + industry-abs-spread + property-usd-bond-yield：联合触发 M5.3(c) 政策信用触发型代理
  • cross-border-quota + cb-fx-data + fx-swap：联合判定 MCA 轴 7 子维度
  • onchain-first-sign 内 5 子信号联合触发 Attention 二阶分支启用（参见 一致性中间件子系统）

§4 数据更新调度建议​

runtime 单用户模式下凌晨低峰窗口；调度由工程实施仓在 Provider Adapter 层实现，本仓只规约频率。

数据源类频率cron 建议
日频公开（A 股端）每日0 2 * * *
日频商用（FX / ETF / IV / 信用利差）每日30 2 * * *
周频（CFTC TFF）每周六0 4 * * 6
季频（13F）季末 + 45 日0 5 15 2,5,8,11 *
实时（链上 / funding / 政策公告）持续轮询15 分钟间隔；事件驱动入库

§5 与 MCA 轴 / 半人工标注 SLA 的接入​

MCA 轴主信号数据源不可得时回退
轴 1（投资者结构）sec-13f / margin-balance-cn任务 D 季度刷新
轴 2（衍生品成熟度）iv-surface / cftc-tffM6.3 输出 not-applicable
轴 3（制度摩擦）limit-updown-count / 交易所规则数据规则数据为静态资产，随版本入库
轴 4（非市场参与者注入）sovereign-fund-disclosure / policy-announcement-freqN3 走任务 D 半人工标注（参见 MCAClassifier 子系统）
轴 5（信息环境质量）disclosure-quality-ratingreviewer 标注
轴 6（衍生品支柱适用性）iv-surfaceM6.3 输出 not-applicable
轴 7（货币与跨境约束）cb-fx-data + cross-border-quota + fx-swap半人工标注

S1 横切 Attention 二阶分支由 onchain-first-sign 5 子信号供给；不可得时退到默认阈值（详见 一致性中间件「Attention 二阶分支信号阈值校准」待校准项）。

所有「不可得」分支统一汇入 Phase 7 半人工标注 SLA 附录 任务 A / B / C / D 的 reviewer 工作流。

§6 关联资产​

§7 已知治理空白​

事实源中提及但尚无独立 ADR / SLA 收口的事项，留待后续提案：

  • 商用数据源（wind-augmented / Bloomberg / Refinitiv）的 license 合规审查流程
  • 第三方爬取（external-judge-corpus / policy-announcement-freq 部分源）的 robots.txt 与 rate-limit 合规基线
  • 跨数据源「同一事件不同口径」的优先级仲裁规则（v1 仅规约组合触发，未规约冲突取舍）
  • 历史回填窗口策略：哪些数据源需要全量历史 / 哪些只需滚动 N 季度