做什么（One-liner）

黄金 (GC=F) 价格方向信号：规则版用 SMA(50) / SMA(200) 与当前价 3 路比较生成 BULLISH/BEARISH/NEUTRAL；可选 XGBoost 路径（dep 失败 silent fallback 到规则）。

怎么用

Canvas 拖 gold_price_predictor_v1，填 symbol（默认 GC=F）+ 可选 use_xgboost（默认 False）。

典型用法：

symbol=GC=F, use_xgboost=False   # rule baseline
→ current_price, sma_50, sma_200, signal ∈ {BULLISH, BEARISH, NEUTRAL}

核心公式

# Rule-based path:
close = yf.Ticker(symbol).history('1y').Close
sma_50, sma_200 = close.rolling(50, 200)

signal = BULLISH   if close[-1] > sma_50[-1] > sma_200[-1]
       = BEARISH   if close[-1] < sma_50[-1] < sma_200[-1]
       = NEUTRAL   else

volatility = close.pct_change().std() × sqrt(252) × 100   # annualized % (fixed v1.0.1)

# XGBoost path (optional; falls back on import error):
pred = pangura_core.prediction.gold_xgboost.predict_gold_direction(hist)

假设与适用场景

假设：yfinance '1y' period + auto_adjust + SMA 50/200 hardcoded + COMEX 连续合约 (GC=F)。

适用：贵金属（黄金 / 白银）中长期方向信号；safe haven scenario 输入。

不适用：非贵金属 commodity、期货 rollover、HFT、短窗口。

输入 / 输出契约

{symbol: str, use_xgboost: bool} → {current_price, data_points, sma_50, sma_200, signal, volatility} (rule-based)，可选 model / direction / confidence (XGBoost 成功)。

已知局限 / 未实现

✅ KNOWN-BUG-GOLD-001 RESOLVED (2026-04-20, v1.0.1)

原问题：volatility 字段公式曾是 close.pct_change().std() × 100，返回的是 daily vol × 100（~1% 量级），而字段名 "volatility" 暗示 annualized。已修复：新公式 × sqrt(252) × 100，正确返回 annualized percent（~16% 量级 for equity-like 标的）。

发现经过：2026-04-20 post-audit 时用户质疑 "Canvas 上看着没问题" —— 触发对 Tier 2 batch 5/6 goldens 的全面 target 审查。发现原 golden 故意锁定 buggy 行为（"KNOWN-BUG pattern"），但 volatility 值差 16× 量级对用户决策直接影响过大，不应该拖到未来修。1 行代码修复 + golden 重生成，v1.0.0 → v1.0.1。

其他已知局限

1. RSI 被计算但信号逻辑 NOT 使用（dead code）
2. '1y' period + SMA 50/200 窗口 hardcoded
3. Signal 3-档 discrete（无 continuous confidence）
4. XGBoost fallback silent —— dep failure 不报给 caller
5. NEUTRAL 覆盖 'flat' + 'mixed' 无区分

参考文献

Murphy (1999) Technical Analysis SMA 交叉 + Baur-Lucey (2010) 黄金 safe haven 实证 + Chen-Guestrin (2016) XGBoost。详见 frontmatter。

Golden Test

tests/golden/fixtures/tier2/gold_price_predictor/，yfinance-Ticker-mock regression（rule-based path only）。1e-10 tolerance。7 tests：

• matches_snapshot — 全 output byte-equal
• determinism — 5 reruns identical
• bullish_signal — 上行 synthetic → BULLISH + 严格 monotonic check
• bearish_signal — 下行 synthetic → BEARISH
• neutral_signal — 精心构造 (current > SMA200 but < SMA50) → NEUTRAL
• result_structure — 6 固定 top-level keys（rule path）
• xgboost_fallback_handles_missing_dep — use_xgboost=True 时 dep 缺失不抛异常

XGBoost 成功路径 NOT 覆盖 — 属于 Tier 5 LLM-attestation scope。

Changelog

• 1.0.0 (2026-04-20) — 首次 Active（Tier 2 batch 6, rule-based path）