bitcoin-risk-brief

Bitcoin Risk Brief

Bitcoin Risk Brief 是一款免费开源产品，可将规范的每日 BTC/USD 数据转换为透明的风险评分、数据新鲜度状态和情景价格阶梯。永久免费：无付费套餐、无账号、无 SLA。自有源代码、文档和配置采用 Apache-2.0 许可；捆绑的第三方 BTC/USD 市场数据不在此许可范围内。

首屏截取于 2026-08-09；所示数值为特定时点的示例。

在线产品：bitcoinriskbrief.minihub.app

使用任何当前数值前，请先检查就绪状态：

curl --fail --silent --show-error https://bitcoinriskbrief.minihub.app/api/readiness

于 2026-08-09 截取的响应：

{
  "status": "ready",
  "checks": {
    "risk_data_available": true,
    "validation_available": true,
    "risk_range_ok": true,
    "validation_has_rows": true,
    "latest_matches_validation_end": true,
    "source_is_canonical": true,
    "data_fresh": true
  },
  "data": {
    "latest_date": "2026-08-08",
    "covered_end": "2026-08-08",
    "data_age_days": 1,
    "max_age_days": 2,
    "source": "coinmarketcap_csv",
    "row_count": 5871,
    "methodology_version": "crypto-scout-canonical-v1.1"
  }
}

功能

• 根据规范的 collector/btc-csv/btc_usd_daily.csv 历史数据计算每日 0.0–1.0 的 Bitcoin 风险指标。
• 显示最新的 low、neutral 或 high 状态，并提供两年风险历史图表。
• 展示基于已完成蜡烛图的 HLC3 模型价格背景，以及以 0.025 为增量的风险等级情景阶梯。
• 以英语、俄语、简体中文、德语、法语、西班牙语和阿拉伯语发布每日报告。
• 提供只读分析端点，并在服务端接收电子邮件候补名单联系人信息，绝不将其存储在浏览器中；用户不应提交敏感信息。

与众不同之处

• 数据新鲜度和就绪状态清晰可见。 UI 显示最近一个已完成日期和验证状态；数据新鲜度或验证检查失败时，/api/readiness 会返回 HTTP 503。
• 确定且可复现。 版本化的方法会根据相同的规范每日历史数据重新计算指标，并通过验证元数据记录每次导入。
• 情景，而非预测。 价格阶梯使用同一模型运行假设价格，以展示风险等级可能发生变化的位置；它不是预测，也不是交易指引。

当前状态

当前运行状态、证据和已接受的限制：生产就绪状态。

面向 AI Agent

请从仓库的 llms.txt 开始。此分支定义了机器可读的 /api/openapi.json 端点；部署仍待运维人员处理。有关端点示例、缓存语义和解读边界，请参阅 Agent 访问包。

Agent 必须先调用 /api/readiness，将报告的数值与其日期及数据新鲜度状态关联起来，并保留“分析而非建议”的表述。

架构

服务	技术栈	用途
timescaledb	TimescaleDB/PostgreSQL	BTC OHLCV、风险记录、验证状态、简报快照、候补名单联系人信息
data-collector	Python、asyncpg、APScheduler、httpx	每日 CSV 刷新、完整 CSV 导入、风险重新计算
backend	FastAPI、asyncpg	API、就绪状态、候补名单存储、风险和简报读取
frontend	React、Vite、ECharts、nginx	面向公众的七种语言界面和 API 代理

flowchart LR
    Source[CoinMarketCap public download<br/>or optional API] --> CSV[Canonical BTC daily CSV]
    Schedule[Daily collector schedule] --> Collector[data-collector]
    CSV --> Collector
    Collector --> DB[(TimescaleDB)]
    DB --> API[FastAPI backend]
    API --> UI[React frontend]
    API --> Agents[AI agents and API clients]

规范 CSV 仍是持久化的事实来源；采集器会刷新并验证该文件、重新计算风险，并写入供 API 使用的每日快照。

快速开始

cp .env.example .env
./scripts/manage.sh validate
./scripts/manage.sh start
./scripts/manage.sh migrate
./scripts/manage.sh backfill

打开：http://localhost:3001

文档

• 文档索引
• 产品概览
• 风险方法论
• 架构
• API 参考
• 数据时效性与验证
• Agent 文档
• 运维与生产就绪证据

免责声明与许可

Bitcoin Risk Brief 仅提供分析和研究背景，不构成财务建议、投资建议、价格预测或交易建议。

自有源代码、文档和配置根据 Apache-2.0 许可。随附的第三方 BTC/USD 市场数据仍受数据来源提供方的条款约束；请参阅 NOTICE。