exposure-coach

Exposure Coach

概述

Exposure Coach 会将 market-breadth-analyzer、uptrend-analyzer、macro-regime-detector、market-top-detector、ftd-detector、theme-detector、sector-analyst 和 institutional-flow-tracker 的输出综合为统一的控制平面决策。这项技能旨在回答个人交易者的核心问题：“我现在应该投入多少资金买入股票？”——在开始分析任何个股之前。

适用场景

• 建立任何新的股票头寸之前，确定合适的资金投入规模
• 每个交易周开始时，校准投资组合的敞口
• 多个市场信号相互冲突，需要统一的应对策略时
• 发生重大宏观或市场事件后，重新评估敞口上限
• 市场状态切换期间（扩散、集中、收缩）

前置条件

• Python 3.9+
• FMP API 密钥（设置 FMP_API_KEY 环境变量），用于 institutional-flow-tracker 数据
• 上游技能的输入 JSON 文件（见工作流步骤 1）
• 标准库 + argparse、json、datetime

工作流

步骤 1：收集上游技能的输出

收集集成技能最新的 JSON 输出。每个文件提供一个特定的信号维度：

技能	输出文件模式	提供的信号
market-breadth-analyzer	breadth_*.json	上涨/下跌比率、新高/新低数量
uptrend-analyzer	uptrend_*.json	上升趋势参与度百分比
macro-regime-detector	regime_*.json	当前市场状态（集中、扩散等）
market-top-detector	top_risk_*.json	派发日数量、顶部概率评分
ftd-detector	ftd_*.json	跟进日质量（确认市场底部）
theme-detector	theme_detector_*.json 或 theme_*.json	活跃投资主题及轮动情况
sector-analyst	sector_*.json	板块表现排名
institutional-flow-tracker	institutional_*.json	机构净买入/卖出情况

步骤 2：运行敞口评分引擎

运行敞口评分脚本，并传入上游输出文件的路径：

python3 skills/exposure-coach/scripts/calculate_exposure.py \
  --breadth reports/breadth_latest.json \
  --uptrend reports/uptrend_latest.json \
  --regime reports/regime_latest.json \
  --top-risk reports/top_risk_latest.json \
  --ftd reports/ftd_latest.json \
  --theme reports/theme_latest.json \
  --sector reports/sector_latest.json \
  --institutional reports/institutional_latest.json \
  --output-dir reports/

脚本接受不完整的输入；缺少文件会降低置信度，但不会阻止脚本运行。

规范的宏观市场状态报告必须包含嵌套字段 regime.confidence 和 composite.data_quality，且其中必须包含有效的整数分量计数。缺失或格式错误的 可用性元数据、very_low 置信度以及可用分量数为零，都将被视为缺少关键输入。这些输入 既不会计入市场状态评分，也不会造成偏差；正常的缺失输入扣减和置信度上限仍会生效。切勿 通过手动将报告中的市场状态标签复制到敞口决策中，来覆盖这种降级处理。

**验证时的注意事项：**每次运行后，检查生成的 JSON 字段 inputs_provided 和 inputs_missing。如果通过 CLI 传入的文件仍出现在 inputs_missing 中（例如，敞口引擎无法识别的 theme-detector JSON），应将受影响的维度报告为已降级，并维持置信度上限；不要仅因 CLI 参数中包含该文件，就假设输入已被纳入计算。

**theme-detector 输入注意事项：**主题检测器通常会生成包含 themes 对象的 theme_detector_YYYY-MM-DD_HHMMSS.json。如果 calculate_exposure.py 无法识别该文件，且 theme 仍出现在 inputs_missing 中，请勿手动将主题强度纳入敞口上限。应维持 Exposure Coach 的置信度上限，说明主题维度未被纳入，并在更全面的交易简报中单独总结主题和板块的分析结果。

步骤 3：解读市场态势摘要

查看生成的态势报告，其中包含：

1. 敞口上限——建议的最高股票配置比例（0-100%）
2. 倾向方向——根据市场状态和资金流向，偏向成长股还是价值股
3. 市场参与度评估——市场广度（健康）还是狭窄（脆弱）
4. 操作建议——NEW_ENTRY_ALLOWED、REDUCE_ONLY 或 CASH_PRIORITY
5. 置信度——根据输入完整度评定为 HIGH、MEDIUM 或 LOW

步骤 4：应用敞口指引

将态势建议映射为投资组合操作：

建议	操作
NEW_ENTRY_ALLOWED	继续进行个股分析并建立新仓位
REDUCE_ONLY	不建立新仓位；趁势减持现有仓位
CASH_PRIORITY	大幅提高现金比例；避免所有新的资金承诺

输出格式

JSON 报告

{
  "schema_version": "1.0",
  "generated_at": "2026-03-16T07:00:00Z",
  "exposure_ceiling_pct": 70,
  "bias": "GROWTH",
  "participation": "BROAD",
  "recommendation": "NEW_ENTRY_ALLOWED",
  "confidence": "HIGH",
  "component_scores": {
    "breadth_score": 65,
    "uptrend_score": 72,
    "regime_score": 80,
    "top_risk_score": 25,
    "ftd_score": 10,
    "theme_score": 68,
    "sector_score": 70,
    "institutional_score": 75
  },
  "inputs_provided": ["breadth", "uptrend", "regime", "top_risk"],
  "inputs_missing": ["ftd", "theme", "sector", "institutional"],
  "rationale": "Broad participation with low top risk supports elevated exposure."
}

Markdown 报告

Markdown 报告提供一页式摘要，便于快速查看：

# Market Posture Summary
**Date:** 2026-03-16 | **Confidence:** HIGH

## Exposure Ceiling: 70%

| Dimension | Score | Status |
|-----------|-------|--------|
| Breadth | 65 | Healthy |
| Uptrend Participation | 72% | Broad |
| Regime | Broadening | Favorable |
| Top Risk | 25 | Low |

## Recommendation: NEW_ENTRY_ALLOWED

**Bias:** Growth > Value
**Participation:** Broad (healthy internals)

### Rationale
Broad participation with low distribution day count supports elevated equity exposure.
New positions allowed within the 70% ceiling.

报告保存在 reports/ 中，文件名为 exposure_posture_YYYY-MM-DD_HHMMSS.{json,md}。

资源

• scripts/calculate_exposure.py——负责评分和汇总输入的主协调脚本
• references/exposure_framework.md——评分规则和阈值定义
• references/regime_exposure_map.md——市场状态与敞口上限的映射

关键原则

1. 安全优先——输入不完整或相互冲突时，默认采用较低敞口
2. 与市场状态保持一致——以宏观市场状态设定基准；市场广度只在限定范围内调整
3. 输出可执行建议——始终给出明确建议，而不只是汇总数据

market-regime-daily 的严格溯源验证

添加 --require-provenance --run-id daily-20261017-unique --as-of 2026-10-17T13:00:00Z --max-age-days 3，在评分前验证市场广度和上升趋势。 两个数据生成方必须接收相同的唯一运行 ID；传入它们准确打印出的 JSON 路径。--as-of 是带时区的评估时刻，不会覆盖源数据的业务日期。

验证关卡会检查 schema 1.0、预期运行 ID、UTC 检索时间不晚于评估时刻、源日期非未来日期，以及是否在配置的时效范围内。默认的三日历日是保守策略，并非交易所假期日历。验证失败会在生成报告前终止。验证成功的输出会记录已接受的溯源信息和验证限制。

可选的 top-risk/other 输入和辅助摘要日期不在此验证关卡范围内；未知质量标记仍保持为 false。旧版模式保留现有 schema。运行 ID 用于一致性标记，不代表真实性或时点证明。