ckvd-fcp-monitor

用途

ckvd-fcp-monitor 用于监控和诊断 FCP（Failover Control Protocol，故障转移控制协议）的行为、缓存健康状态以及数据源性能。它属于 crypto-kline-vision-data 数据获取体系，适合在拉取加密 K 线历史数据出现异常或变慢时进行定位。

主要能力

按交易对检查 FCP 行为，判断请求实际命中的数据源。
检查缓存目录健康状况，包括目录是否存在、是否可写、是否包含预期交易对与周期、Arrow 文件大小是否合理（非零字节）等。
提供 FCP 决策流程说明：先查缓存 → Vision API（S3 批量）→ REST API（实时），逐级失败后抛出 DataSourceError。文档给出的参考比例为：缓存命中约 99%（约 1ms 返回）；Vision API 成功约 95%（约 2s 返回并写缓存）；Vision 失败约 5% 时回退 REST API，成功约 99%（约 200ms 返回）；REST 再失败约 1% 时抛错。
汇总常见问题及处理方向：缓存未被使用、Vision API 403 错误、限流 429 错误。
提供性能优化方式：缓存预热、批量并发拉取。
说明流式（Streaming）与 FCP 的关系。

使用方式

快速诊断命令：

# 检查某交易对的 FCP 行为
uv run -p 3.13 python docs/skills/ckvd-usage/scripts/diagnose_fcp.py BTCUSDT futures_usdt 1h

# 检查缓存健康
uv run -p 3.13 python docs/skills/ckvd-fcp-monitor/scripts/cache_health.py

脚本说明：cache_health.py 用于检查缓存目录健康，支持 --verbose 输出完整报告。

缓存排查示例（macOS 路径，经 platformdirs）：

ls -la ~/Library/Caches/crypto-kline-vision-data/data/binance/futures_usdt/daily/klines/BTCUSDT/1h/
uv run -p 3.13 python docs/skills/ckvd-fcp-monitor/scripts/cache_health.py --verbose

缓存未命中时的排查方向：确认缓存目录权限（应可写）、检查请求周期是否与已缓存周期一致、确保日期范围与已缓存数据有重叠。

Vision API 403：常见原因为 Binance Vision API 存在地区限制，文档说明 FCP 会自动处理，无需额外操作。

限流 429 的处理示例：

# 使用更小的日期范围
for chunk in date_chunks(start, end, chunk_days=7):
    df = manager.get_data(symbol="BTCUSDT", start_time=chunk[0], end_time=chunk[1])
    time.sleep(0.5)  # Rate-limit friendly

# 或使用更低频的周期
df = manager.get_data(symbol="BTCUSDT", interval=Interval.HOUR_1)  # vs MINUTE_1

缓存预热示例：

from datetime import datetime, timedelta, timezone
from ckvd import CryptoKlineVisionData, DataProvider, MarketType, Interval

symbols = ["BTCUSDT", "ETHUSDT", "SOLUSDT"]
manager = CryptoKlineVisionData.create(DataProvider.BINANCE, MarketType.FUTURES_USDT)

end = datetime.now(timezone.utc) - timedelta(days=2)  # Avoid recent data
start = end - timedelta(days=365)

for symbol in symbols:
    print(f"Warming cache for {symbol}...")
    df = manager.get_data(symbol=symbol, start_time=start, end_time=end, interval=Interval.HOUR_1)
    print(f"  Cached {len(df)} bars")

manager.close()

批量拉取示例：

from concurrent.futures import ThreadPoolExecutor

def fetch_symbol(symbol: str) -> tuple[str, int]:
    manager = CryptoKlineVisionData.create(DataProvider.BINANCE, MarketType.FUTURES_USDT)
    df = manager.get_data(symbol=symbol, start_time=start, end_time=end, interval=Interval.HOUR_1)
    manager.close()
    return symbol, len(df)

with ThreadPoolExecutor(max_workers=3) as executor:
    results = list(executor.map(fetch_symbol, symbols))

适用场景

历史回测、批量分析时数据拉取变慢或异常，需要判断命中的数据源与延迟来源。
怀疑缓存未被使用、缓存目录异常或缓存覆盖不足。
需要排查 Vision API 403、REST 限流 429 等数据源问题。
需要为高频访问的交易对提前做缓存预热，或用并发方式批量拉取。

限制与注意事项

流式（Streaming）走并行数据通路，不与 FCP 交互：FCP 使用 get_data()，数据流为缓存 → Vision → REST，使用缓存（Arrow IPC），具备 Vision → REST 回退；流式使用 stream_data_sync()、create_stream()，数据流为 WebSocket → KlineUpdate，不使用缓存，无回退。监控 FCP 不会影响流式性能；若流式为慢，应检查 WebSocket 连接而非 FCP 数据源。
Vision API 对较新数据存在延迟，文档的模板提到需确认数据是否早于 48 小时。
文档中的比例数字（99%、95% 等）为说明性参考，来自资料原文。
修改本技能后需执行文末检查清单：脚本命令引用存在的脚本、缓存路径与 platformdirs 输出一致、FCP 决策流程图与实际实现一致、并将变更追加到 evolution-log.md。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项

相关文件