Allanli1011/us_commodities_scan

# 美国 / 全球期货扫描器 交易信号逻辑与 [Allanli1011/cn_stock_scan](https://github.com/Allanli1011/cn_stock_scan) 相同（MACD三重背离 + PA三推75%回撤 + ICT周线/月线 PDA），但其操作对象是 **Yahoo Finance 上的所有连续近月期货合约**（`=F` 代码）， 而不是 A 股。 标的池涵盖约 57 个合约，覆盖能源、金属、谷物、软商品、 牲畜、股指、货币、利率、波动率和加密货币等领域。 ## 综合评分（最高 3.0） | 信号 | 评分 | 备注 | |---|---|---| | MACD 严格 5/5 背离 | +1.0 | 图表上的紫色标记 | | MACD 宽松 4/5 背离 | +0.5 | 橙色标记 | | 60-90% 回撤的三推 | +1.0 | H1/H2/H3 标记 | | 周线/月线 OB+FVG 重叠 | +1.0 | “Premium-discount array” | | 周线/月线单边 OB 或 FVG | +0.5 | | 评分 ≥ 2.5 被标记为 **三重收敛**。 ## 快速开始 ``` pip install -r requirements.txt # 首次运行：构建 universe + 下载每日历史数据 python scripts/scan_full.py --refresh-data --min-score 1.5 --plot-top 5 # 后续运行：仅增量更新价格 python scripts/scan_full.py --update-prices --min-score 1.5 # 扫描单个 category python scripts/scan_full.py --category Energy --plot-top 3 python scripts/scan_full.py --category Metals python scripts/scan_full.py --category Grains # 仅显示 short 信号 python scripts/scan_full.py --direction top ``` ## 输出 * `output/futures_signals_.csv` — 满足 `--min-score` 的每一个合约， 按综合评分排序 * `output/charts/__.png` — 带注释的 K 线图， 包含 MACD 副图、三推标记、PDA 区域以及入场/止损/目标 交易计划 ## 每日自动化（GitHub Actions） 位于 `.github/workflows/daily_scan.yml` 的定时工作流会在 **每个工作日 UTC 时间 23:00**（≈ 美东时间下午 6 点 / 美东夏令时下午 7 点，在美国期货 结算后）运行扫描。它将当天的 CSV 和前 5 张图表提交到仓库的 `signals/` 文件夹中，并将其作为 90 天的 artifact 上传。 * 浏览历史信号 → [`signals/`](signals/) 文件夹 * 触发临时运行 → Actions 标签页 → **Daily Futures Scan** → "Run workflow" * 调整计划时间、评分阈值或绘图数量 → 编辑工作流 文件（`cron`、`--min-score`、`--plot-top`） 为了使自动提交生效，**Settings → Actions → General → Workflow permissions** 必须设置为 *"Read and write permissions"*。该工作流 声明了 `permissions: contents: write`，因此这是唯一需要的仓库级别 开关。 ## 标的池 期货列表位于 `src/universe.py`（`FUTURES_UNIVERSE`）中。Yahoo Finance 偶尔会下架或重命名合约；如果某个代码不再 返回数据，只需删除其对应行即可。 | 类别 | 示例 | |---|---| | 能源 | CL=F WTI原油, BZ=F 布伦特原油, NG=F 天然气, HO=F, RB=F | | 金属 | GC=F 黄金, SI=F 白银, HG=F 铜, PL=F, PA=F | | 谷物 | ZC=F 玉米, ZS=F 大豆, ZW=F 小麦, ZL=F, ZM=F, ZO=F, ZR=F | | 软商品 | KC=F 咖啡, SB=F 糖, CC=F 可可, CT=F 棉花, OJ=F | | 牲畜 | LE=F 活牛, HE=F 瘦猪, GF=F 饲牛 | | 指数 | ES=F 标普, NQ=F 纳斯达克, YM=F 道琼斯, RTY=F 罗素, NKD=F | | 货币 | 6E=F 欧元, 6J=F 日元, 6B=F 英镑, DX=F 美元指数 | | 利率 | ZN=F 10年期, ZB=F 30年期, ZF=F 5年期, ZT=F 2年期, TN=F, UB=F | | 加密货币 | BTC=F 比特币, ETH=F 以太坊 | `DX=F`（美元指数）和 `VX=F`（VIX）目前无法从 Yahoo Finance 获取数据，因此被排除在外。如果你需要相关敞口，请使用对应的指数/ETF 替代代码（`DX-Y.NYB`、 `^VIX`、`UUP`、`VXX`）。 ## 关键参数 (config.yaml) | 设置 | 默认值 | 备注 | |---|---|---| | `swing.pct_threshold` | 0.03 | ZigZag 阈值 —— 如果 NG=F/VX=F 噪音过大，可调高至 0.04–0.05 | | `macd.divergence.min_area_reduction` | 0.10 | 每根直方图柱的面积必须缩小 ≥10% | | `macd.divergence.recency_bars` | 30 | 第 3 次推力必须发生在过去 30 根日线之内 | | `three_push.pullback_target_pct` | 0.75 | 75% 回撤目标 | | `three_push.pullback_tolerance` | 0.15 | 接受 [60%, 90%] 范围内的回撤 | | `ob_fvg.ob_displacement_atr` | 2.0 | OB 需要 2 倍 ATR 的后续走势确认 | | `prices.lookback_days` | 800 | 约 3 年的日线数据 | ## 与 cn_stock_scan 的差异 * **数据源**：使用 yfinance 而非 akshare * **标的池**：精选的期货列表（无市值过滤器） * **周线重采样基准**：`W-SUN`（期货在 Globex 的交易时间为周日至周五）vs `W-FRI` * **颜色惯例**：绿色=涨，红色=跌（美国惯例；A 股使用 相反颜色） * **货币符号**：`$` 而非 `¥` * **输出语言**：英语 MACD 背离规则、三推回撤逻辑以及 OB/FVG/PDA 机制在代码实现上完全一致。

标签：MACD, Python, 技术分析, 无后门, 期货扫描器, 自动化交易, 逆向工具, 量化金融, 雅虎财经