crypto-regime-analyzer

加密市场状态分析技能

用途

使用数据驱动的 6 项评分系统（0-100）量化加密市场状态。这相当于 market-breadth-analyzer + exposure-coach 的加密市场版本：它会在进行任何币种层面的分析之前，回答“当前加密市场支持何种风险姿态？”

**分数方向：**100 = 风险偏好最强的健康状态（参与面广、趋势健康、杠杆适度），0 = 严重规避风险状态。

无需 API 密钥——使用 CoinGecko 的免费公共 API 和 Binance 的公共期货端点。

何时使用此技能

• 用户询问“当前加密市场是风险偏好还是规避风险？”或“加密市场状况有多健康？”
• 用户询问“现在是山寨币季吗？”或询问 BTC 主导率的走势
• 用户询问资金费率是否过热
• 用户想在筛选单个币种之前，了解加密资产配置的风险姿态
• 用户想在进行股票 market-regime-daily 工作流的同时，每日检查加密市场状态

此技能不会做什么

• 不推荐币种，不提供买入/卖出信号，不预测目标价
• 不执行交易或更改投资组合——仅描述市场状态
• 与项目愿景一致，人的决策关卡仍居于核心地位

前置条件

• Python 3.9+ 和 requests（仅实时模式；离线模式仅使用标准库）
• 互联网连接，可访问 api.coingecko.com 和 fapi.binance.com（实时模式）
• 无需 API 密钥

组件模型

#	组件	权重	回答的问题
1	BTC 趋势结构	25%	储备资产的主要趋势是否完好？（价格相对于 50/200DMA 的排列、200DMA 斜率）
2	山寨币广度参与度	20%	山寨币的参与面有多广？（市值排名前 N 的币种中，高于 200DMA 的比例，以及 50DMA 确认情况）
3	BTC 主导率状态	15%	资金正在向何处轮动？（结合 BTC 趋势解读主导率方向）
4	永续合约资金费率状态	15%	杠杆交易有多拥挤？（主要币种的平均资金费率；极端情况下采用逆向解读）
5	回撤与波动率位置	15%	我们处于周期的哪个阶段？（距 1 年高点的回撤、已实现波动率百分位）
6	动量推力 / 恐慌抛售	10%	短期趋势确认情况如何？（过去 30 天表现为正的币种占比）

缺失组件的权重将按比例重新分配（与 market-breadth-analyzer 采用相同约定）。完整评分逻辑见：references/crypto_regime_methodology.md。

市场状态区间

分数	区间	风险姿态
80-100	RISK_ON	观察到广泛的风险偏好条件；做出决策前请检查风险限额
40-79	NEUTRAL	观察到的市场条件不一；无法得出明确的市场状态结论
0-39	RISK_OFF	观察到防御性市场条件；请检查现有风险控制措施

这些区间是启发式描述，并非经验证的资产配置规则。请参阅 references/VALIDATION.md，了解当前证据边界，以及在提出量化绩效主张前 所需的材料。

---

执行工作流

阶段 1：运行分析脚本

实时模式（获取 CoinGecko + Binance 数据；默认使用 --top-n 20 时，当天首次运行约需 2-4 分钟，因为免费套餐受到速率限制；当天再次运行会命中缓存并即时完成）：

mkdir -p reports/<routine-or-date>
python3 skills/crypto-regime-analyzer/scripts/crypto_regime_analyzer.py \
  --output-dir reports/<routine-or-date>

离线模式（不联网；快照架构见方法参考文档）：

python3 skills/crypto-regime-analyzer/scripts/crypto_regime_analyzer.py \
  --input-json snapshot.json \
  --output-dir reports/<routine-or-date>

选项：--top-n <int> 设置分析范围大小（默认 20），--cache-dir <path> 设置获取缓存位置（默认 .crypto_regime_cache），--quiet。

阶段 2：解读输出

脚本会写入 crypto_regime.json（机器可读，可用于串联其他技能）和 crypto_regime.md（单页报告），并打印一行摘要：

CRYPTO REGIME: NEUTRAL (score 68.4/100) — Mixed conditions observed; no strong regime conclusion

展示结果时，先说明市场状态区间和风险姿态，然后使用各组件的 signal 字符串，解释对分数影响最大的 1-2 个组件。标出任何报告 data_available: false 的组件，并说明这对置信度意味着什么。

第 3 阶段（可选）：传递给下游

JSON 综合结果可作为一个描述性加密市场输入，纳入类似 exposure-coach 的仓位总结中。不得单独据此授权、阻止、确定交易规模或执行交易。

输出

脚本会将两份产物写入 --output-dir，并打印一行摘要以便在工作流中传递：

• crypto_regime.json — 完整的机器可读分析：metadata、各组成部分的结果（score、signal、data_available 及各组成部分专属字段），以及 composite 区块（score、zone、guidance、effective_weights）。
• crypto_regime.md — 一页式报告：综合得分及区间条、仓位提示行、各组成部分表格（权重 / 得分 / 信号）以及置信度说明。
• 控制台：CRYPTO REGIME: <ZONE> (score <N>/100) — <posture>，并针对任何被跳过的组成部分显示警告。

资源

• references/VALIDATION.md — 验证状态、证据边界和复现要求。
• references/crypto_regime_methodology.md — 完整的评分依据、所有阈值表、离线快照 JSON 架构以及实时数据源端点列表。
• scripts/crypto_regime_analyzer.py — CLI 协调器（入口点）。
• scripts/data_client.py — CoinGecko/Binance 数据获取器、每日缓存、主导率历史累积器、离线加载器。
• scripts/calculators/ — 每个组成部分对应一个模块；均为纯函数，且已通过完整单元测试。
• scripts/scorer.py — 通过按比例重新分配权重来计算加权综合结果。
• scripts/tests/ — 涵盖每个组成部分、评分器、稀疏数据时的失败关闭行为，以及端到端的牛市 / 熊市 / 降级快照测试。

已知限制

• 主导率历史在本地累积。 CoinGecko 免费层级仅提供当前主导率，因此客户端会在缓存目录中按运行日期存储一条观测记录。主导率组成部分在累积 31 条每日观测记录前会报告 data_available: false（在此之前会重新分配权重）。可通过 --input-json 更快地填充数据。
• 资金费率数据尽力获取。 如果无法访问 Binance 的端点（地区限制或服务中断），则会正常跳过该组成部分。
• 资产范围按市值排名取前 N 名，并排除稳定币及封装 / 质押资产；这不是固定指数，因此成分会随市场变化。
• 阈值为启发式设定，并记录在方法论参考文档中；它们是保守的默认值，并非经过回测的最优值。

免责声明

仅供教育和改进流程之用。本技能用于描述市场状况，不提供财务建议、信号或买卖指令。所有决策仍由用户自行负责。