DataAcquisition 子系统设计
本文档承接「为什么 FinBayes 反复取不到数」的根因整改，记录 FinBayes 代码仓（
finbayes/data/）中弹性取数 + venue 感知这一层的设计与落地状态。它是数据落地层（出处信封）之上、工具/技能层之下的一层：出处信封负责「忠实标注取到/没取到」，本层负责「尽力把数据取回来，穷尽后才诚实降级」。代码事实源在工程仓，本文档是 L3 设计层记录。
0. 为什么做这个（根因）
团队真实问答暴露：FinBayes 用对了工具、也诚实降级了，但一类问题（如「BTC 多交易所订单簿深度」）全交易所取不到数。逐交易所实测发现失败不是一类，是四类，没有一类靠诚实降级能解决：
- 可达性 / 地理封锁：交易所对代理出口 IP 地理限制（如 Binance 451、Bybit 403）——一个代理出口满足不了所有交易所。
- 品种模型不匹配：向只有衍生品的交易所要现货（如 Deribit 无现货 BTC/USD）→ ccxt
BadSymbol。 - 并发瞬时：并发取数下的限频 / 超时，单次尝试无重试就放弃。
- （非失败） 交易所深度返回封顶——已被既有
covered_pct+ caveat 处理，无需重做。
根因：此前对数据落地 / 工具 / 技能 / sub-agent / provider 五层的整改，把数据正确性（出处、归约、不编造）做透了，但取数本身是单源、单次、单端点，从没建过取数容错 + venue 感知这一层。可复用的容错模式此前只零散存在两处——宏观的 Data Horizon → FRED 回退链、LLM 的 ResilientProvider——从没被抽象成数据层通用能力。所以「诚实降级」被太早够到：一次脆弱的尝试失败后，链上没有「再试别的」。
设计立场：诚实降级是地板（不编造），不是目标（真把数取到）。本层在地板之上补「尽力取回」的弹性，只有弹性链穷尽后才落到地板。
1. 职责定义
- 弹性取数原语：把单源单次的取数升级为「多源有序、瞬时失败重试退避、非瞬时立即跳源、首成功胜、穷尽才诚实失败」，且市场中立（crypto / 股票 / 宏观 / 外汇共用）。
- venue / 品种感知：单一处掌握各交易所的市场现实（现货 / 合约）与原生符号语法，让取数在进网络前就跳过某交易所根本没有的品种。
- 多市场数据接口：在上述两者之上，落地 crypto 技术分析所需的市场数据 + 指标接口（K线 / OI / 资金费率 / 清算 / 订单簿 / EMA / RSI / Key Levels）。
2. 架构
2.1 弹性取数原语（finbayes/data/acquisition.py）
把宏观专用的 run_chain / QuoteSource 泛化为通用原语，镜像 ResilientProvider 已验证的重试 + 故障分类，但按 FetchError.kind 而非解析文本判断：
DataSource(name, fetch, is_available, max_attempts, kind_hint)：链上一个有序源。is_available按配置或可达性门控（无 key 的 vendor、被墙的交易所）——链跳过它，不把配置 / 区域缺口误标成数据回退。RetryPolicy：只重试瞬时类（timeout / network / rate_limited，即RETRYABLE_KINDS），指数退避封顶；其余（auth / not_found / bad_request 等）立即跳源（重试修不了地理封锁或拼写错）。resilient_fetch(symbol, sources, ...)：可达源按序尝试，瞬时失败原地重试（受max_attempts+ 策略约束），首成功胜（后续源标fallback_used），穷尽才诚实 typed failure。clock/sleep注入 → 全离线可测。
向后兼容：run_chain 保留为「重试关闭」的薄封装，每源默认 max_attempts=1 时与原行为字节等价，宏观链与既有测试零改动。
2.2 venue / 品种模型（finbayes/data/venues.py）
VenueSpec（supports {spot, perp} + 符号语法）+ resolve(base, venue, market)：
- 对已编目但确无该品种的交易所（Deribit 现货）返回
None，调用方进网络前跳过 / 标not_found，零 round-trip —— 结构化根治第 2 类失败。 - 对未编目交易所保持宽容（假定有该品种、用 ccxt 默认语法），所以「编目」是增强而非闸门。
available_venues(market, region_blocked=...)：可预跳被墙交易所（第 1 类）——但弹性链本就能在尝试失败后优雅降级，故region_blocked是优化、默认空、零行为变化。
三处此前散落的 venue 符号表（cross-venue quote / depth / 工具内）统一从本模块派生（单一事实源）。
2.3 fetch vs compute 分离
- 取（需 provider）：OHLCV、OI、资金费率、清算、订单簿。
- 算（本地、确定性、无 provider）：EMA / RSI（复用 stockstats，与股票指标工具同库口径）、Key Levels（纯 UTC 日期分桶）。指标从 OHLCV 本地算，出处为「从 <交易所> OHLCV 算」（composite SourceRef，method=
computed:*，as_of=末 bar）；窗口不足时诚实返回None，不报误导值。
3. 八个 crypto 技术分析接口（契约 → 实现）
| # | 接口 | 实现（finbayes/data/） | 源 |
|---|---|---|---|
| 1 | K线 / OHLCV | crypto_ohlcv.fetch_ohlcv | ccxt 弹性单源重试 |
| 2 | Open Interest | crypto_derivs.fetch_open_interest | ccxt fetchOpenInterestHistory |
| 3 | Funding Rate | crypto_derivs.fetch_funding | ccxt fetchFundingRateHistory（退化到最新单点） |
| 4 | Liquidations | crypto_derivs.fetch_liquidations | vendor-only（CoinAnk 爆仓数据，待 tier/key 激活）；无 vendor → 诚实 no_source（ccxt 无统一清算流） |
| 5 | 订单簿深度 | order_book.fetch_depth_summary（既有） | ccxt 跨交易所归约 |
| 6 | EMA | indicators_compute.compute_ema | 本地（从 OHLCV） |
| 7 | Key Levels | indicators_compute.compute_key_levels | 本地（日 / 周 bar 分桶） |
| 8 | RSI | indicators_compute.compute_rsi | 本地（从 OHLCV） |
模型侧由 CryptoTool 暴露为 action（ohlcv / open_interest / funding / liquidations / ema / rsi / key_levels + 既有 quote / depth），渲染有界（每框架摘要 + 近若干根），完整序列与出处进 provenance。
4. Data Horizon 整合立场
依据 Data Horizon 的差异化红线「优先生产他处难自助获取、高杠杆的资产，不重复路由已商品化、第三方可自助获取的数据」，分工为：
- Data Horizon：作为生态内provider 配置 / 鉴权的事实源（哪些源、key、回退顺序——对齐其 provider 配置中心方向），并生产高价值衍生资产（私域信号 / 事件研判 / 跨源互证）。
- FinBayes：自持取数容错 + 缓存；商品化数据（OHLCV / OI / 资金费率）用 Data Horizon 管理的配置直连第三方（ccxt / vendor），保留独立可达性与回退；高价值资产经 Data Horizon Open API 消费。
第三方聚合 vendor（CoinAnk 等）按数据类别分工，不是一刀切的回退：对商品化 + 可达数据（OHLCV / OI / 资金费率，ccxt 免费且能取）ccxt 主、vendor 回退（避免把付费依赖塞进最常用路径）；对 ccxt 做不了 / 难做的数据（清算、原生跨交易所聚合、订单流 / CVD、清算热力图）CoinAnk 主——它才是这类数据的「对的 provider 类别」。能力全景与接入分层见 §4.1，分工立场见 ADR-030 — DataHorizon ↔ FinBayes 数据接口分工。
4.1 CoinAnk 能力全景与接入分层（2026-06-22 重析 + 范围扩展）
CoinAnk（open-api.coinank.com）经核实是完整的加密数据聚合站（非单一报价端点，早期误判已纠正），按套餐分层（套餐 1–4，付费）。其能力既覆盖八接口、又原生做跨交易所聚合 + 提供大量订单流 / 持仓结构信号——后者正是 ccxt 做不了、且属 Data Horizon 差异化红线里「他处难自助获取、高杠杆」的类别。
八接口对应（CoinAnk 分类 → 接口）：K线→①；未平仓合约（含币种/交易对/聚合持仓历史 + 持仓 K 线）→②；资金费率→③；爆仓数据（实时统计 / 聚合历史 / 交易对历史 / 爆仓订单 / 清算地图 / 清算热力图）→④；订单本（交易对差值 / 交易所聚合差值 / 挂单流动性热力图）→⑤；指标数据 + RSI 选币器→⑥⑧。
范围扩展（owner 2026-06-22 拍：同步扩到高价值数据）——八接口之外，crypto 数据层目标纳入 CoinAnk 这批对技术分析更高杠杆的信号（作为「Phase 6」推进）：
| 高价值数据 | CoinAnk 分类 | 套餐 | 价值 |
|---|---|---|---|
| CVD / 主动买卖（量/额/笔数 + 聚合） | 市价单统计指标 | 套餐3 | 订单流买卖失衡 |
| 清算地图 / 清算热力图 / 挂单流动性热力图 | 爆仓数据 / 订单本 | 套餐4 | 止损 / 爆仓位 = 支撑阻力核心 |
| 多空比 / 净多空 | 多空比 / 净多头净空头 | — | 持仓结构 / 拥挤度 |
| 大额订单 | 大额订单 | — | 巨鲸挂单 |
| 资金流 / 订单流 | 资金流 / 订单流 | — | 资金流向 |
| ETF / 新闻快讯 | ETF / 新闻快讯 | — | 资金面 / 事件 |
接入分层判据：能接哪些取决于订哪档套餐（套餐1=OI/资金费率/基础爆仓/K线；套餐3=CVD/订单本差值/爆仓订单；套餐4=清算地图/热力图/挂单热力图）。当前 owner 套餐 / key 待定——故 CoinAnk 端点按 seam 设计就绪、不预先臆造：每个端点待定档/拿到 key 且核对其文档页的参数/响应后逐个接（coinank.py 已建客户端骨架 + 已验证 getLastPrice 参考形态）。
代码仓 5 个本地提交（Phase 0–4），8 接口收口、7 个真做零付费依赖、清算诚实地板：
- Phase 0 弹性取数原语
acquisition.py（宏观链字节等价）。 - Phase 1 venue / 品种模型
venues.py（结构化根治 Deribit BadSymbol，三处散表归一）。 - Phase 2 OHLCV
crypto_ohlcv.fetch_ohlcv（替换无出处的字符串 history）。 - Phase 3 本地指标
indicators_compute（EMA / RSI / Key Levels）。 - Phase 4 衍生品
crypto_derivs（OI / 资金费率 ccxt 真做、清算诚实地板）+ CoinAnk vendor seamcoinank.py（transport 注入 + 已验证的 getLastPrice 参考端点；CoinAnk 全站 API 经核实覆盖 8 接口 + 高价值数据，待 tier/key 激活逐个接入——见 §4.1）+ 配置coinank_api_key（就绪，空 = ccxt-only）。
live 验证（okx 经代理）：OHLCV 现货 / 合约、OI、资金费率、EMA / RSI / Key Levels 全真值；Deribit 现货零网络 not_found；清算诚实 no_source。
未决：① CoinAnk 套餐选型（决定可接端点，owner 评估中）+ vendor 端点逐个激活（待 tier/key 或 Data Horizon 整合）；② 接口 4 清算接 CoinAnk 真做（替换诚实地板）；③ Phase 6 高价值数据（CVD / 订单流 / 清算热力图 / 多空比 / 大额订单——owner 2026-06-22 已拍同步扩，见 §4.1）；④ 被墙交易所走 CoinAnk 原生跨所聚合覆盖；⑤ Data Horizon provider 配置契约对接（待其暴露契约）。
6. 测试要求
- 全部离线可测：弹性原语注入
sleep/clock；取数注入client_factory（venue → fake exchange 或 Exception）；vendor 注入 transport。 - 覆盖：重试-退避调度、非瞬时跳源、
fallback_used、穷尽 typed failure、venue 解析（无现货 → None / 未编目宽容 / region_blocked）、OHLCV 形状 + UTC + 出处、指标对 stockstats 金标值 + 窗口不足 → None、Key Levels 日期分桶、OI / 资金费率（含最新退化）、清算诚实 no_source、CoinAnk auth / parse / key 门控。
7. 相关
- 上游骨架：ADR-025 agent 骨架范式定型
- 接口分工决议：ADR-030 — DataHorizon ↔ FinBayes 数据接口分工
- 工程架构主稿：FinBayes 工程架构