做什么（One-liner）

宏观一键看板聚合：单次 /mfle/snapshot 返回体制 + 周期 + CLI + 产出缺口 + 关键指标（GDP / UNRATE / FEDFUNDS / CPI）。5 个 MFLE 子模块串联，FRED 不可用时静默退化为仅 regime，logic_lineage 记录哪些 upstream 成功贡献。

怎么用

Canvas 拖 macro_snapshot_v1（或 macro_factor_v1，共享同一端点）。可选 regime_source=yfinance|fred。典型用法：

macro_snapshot_v1 → institution_composite (宏观 overlay 输入)
                 ↘
        casa_strategy_v1 / meta_strategy (策略池 context)

核心公式

# 5-step aggregator (see frontmatter for full flow):

1. regime    = detect_regime_from_{yfinance|fred}()
2. cycles    = cycles_from_gdp()                 if fred_available
3. cli       = get_composite_cli()                if fred_available
4. gap       = get_output_gap()                   if fred_available
5. indicators = get_series_recent(['GDPC1', 'UNRATE', 'FEDFUNDS', 'CPIAUCSL'])
                + aliases (unrate → unemployment_rate; fedfunds → fed_funds)
                + round(2) on yoy_pct fields

logic_lineage 记录每个成功 upstream tag，order = [regime, cycles, cli, gap]

假设与适用场景

假设：FRED_API_KEY 配置 + US FRED 系列 + 每 upstream 提供自己的 available 标志。

适用：Canvas 宏观 overlay 节点、前端 dashboard 一次拉取、跨模块 context 输入。

不适用：单独 upstream 调用（直接调各自端点）、完整离线、非美国、历史时点快照。

输入 / 输出契约

{regime_source?='yfinance'} → {regime, regime_confidence, cycle_phase, cycle_peak_date, cycle_trough_date, months_in_phase, leading_indicator_direction, output_gap_pct, key_indicators, logic_lineage}。

FRED 不可用时：cycle_* / leading_indicator_direction / output_gap_pct 全 None + key_indicators = {} + logic_lineage = ['tvp_kfavar_yfinance']。

已知局限

1. regime_source='fred' silent fallback：FRED 不可用时静默改用 yfinance（仅 logic_lineage 能辨）
2. FRED 不可用 → key_indicators 空 dict + 所有 FRED-dependent 字段 None
3. US 系列硬编码，无 regime override
4. key_indicators alias 2-way duplicate：unrate + unemployment_rate 同值（客户端需决定用哪个）
5. round(2) 仅作用于 yoy_pct；recent values 原样精度
6. logic_lineage 只记 Pangura-level 算法名（不追 FRED fetch 细节）
7. 无 as_of / time_travel 参数（总是取最新）

参考文献

Burns-Mitchell (1946) NBER Business Cycles 日期认定 + Primiceri (2005) TVP-SVAR 方法 + OECD (2012) CLI System。详见 frontmatter。

Golden Test

tests/golden/fixtures/tier3/macro_snapshot/，7 upstream monkey-patched。1e-12 tolerance（纯聚合，field copy + round）。9 tests：

• yfinance_all_available — full snapshot byte-equal
• fred_all_available — regime_source='fred' + lineage[0]='tvp_kfavar_fred'
• fred_unavailable — 退化 snapshot（仅 regime + 空 key_indicators）
• cycles_unavailable — cycles.available=False 但 CLI/gap 仍贡献
• determinism — 5 reruns 字节一致
• result_structure — 10 固定 top-level keys
• logic_lineage_ordering — 追加顺序 regime → cycles → cli → gap
• key_indicators_aliasing — unrate==unemployment_rate / fedfunds==fed_funds
• regime_source_fallback_when_fred_unavailable — 'fred' + FRED 断 → 静默 fallback yfinance

Changelog

• 1.0.0 (2026-04-20) — 首次 Active（Tier 3 batch 1.3, aggregator contract locked）