Trading_Agents_for_Futures — 期货分析数据引擎

你是哪种用户？根据你的身份选择对应模式。

快速开始

# 默认：数据模式（给 AI Agent 用）
python main.py -s RB

# 决策模式：辩论 + 风控 + CIO 建议（给人类看）
python main.py -s RB --decision

# 批量分析多个品种
python main.py -s RB,CU,M

# 全市场扫描 38 个品种
python main.py -s ALL

执行后输出纯 JSON（字段含义见下文）。首次运行会自动下载约 1 年历史数据，耗时 5~10 分钟；后续秒级。

输出 JSON 结构

{
  "symbol": "RB",
  "timestamp": "2026-05-14T15:43:59",
  "success": true,
  "analysis_details": {
    "technical_analysis": {
      "close": 3257.0,
      "MA5": 3266.8,
      "MA20": 3192.1,
      "MA60": 3131.7,
      "EMA20": 3207.3,
      "MACD": 37.8,
      "MACD_Signal": 30.8,
      "MACD_Hist": 7.0,
      "RSI14": 70.5,
      "BB_Upper": 3312.0,
      "BB_Middle": 3192.1,
      "BB_Lower": 3072.1,
      "ATR14": 30.2,
      "VOL_MA20": 685669,
      "OI_delta": -49216,
      "trend_20d": "up",
      "change_20d_pct": 5.1,
      "data_points": 245
    },
    "basis_analysis": {
      "spot_price": 3280.0,
      "futures_price": 3260.0,
      "current_basis": -20.0,
      "basis_pct": -0.6,
      "basis_zscore_180d": -0.8,
      "structure": "backwardation"
    },
    "term_structure_analysis": {
      "front_contract": "RB2605",
      "back_contract": "RB2704",
      "front_price": 3150,
      "back_price": 3307,
      "spread": 157,
      "spread_pct": 5.0,
      "structure": "contango"
    },
    "inventory_analysis": {
      "latest_inventory": 520000,
      "inv_change_wow": 0.7,
      "inv_change_mom": -2.3,
      "inv_zscore_180d": 1.6,
      "latest_warehouse_receipt": 82000,
      "wr_change_5d": 1500
    },
    "positioning_analysis": {
      "net_position": -3367,
      "net_change": -3466,
      "concentration_idx": 0.0068,
      "top20_long": 245143,
      "top20_short": 241185,
      "top20_long_pct": 0.5041,
      "top20_members_count": 20
    },
    "news_analysis": {
      "total_news_count": 10,
      "bullish_news_count": 1,
      "bearish_news_count": 0,
      "neutral_news_count": 9,
      "sentiment_ratio": 0.1
    }
  }
}

输出是纯指标字典，不含任何方向判断、置信度评分、辩论文本。 每个 skill 的本地规则逻辑（_rule_based_signal）仍在内部运行但不对外暴露。

六大分析维度 & 方法论框架

你是 AI 分析师，以下是你可以用来解读数据的完整方法论。

一、技术面分析 (technical_analysis)

数据指标： close, MA5/MA20/MA60, EMA20, MACD/Signal/Hist, RSI14, BB_Upper/Middle/Lower, ATR14, VOL_MA20, OI_delta, trend_20d, change_20d_pct

分析框架（你需要做的）：

1. 均线系统判断： 价格 > MA20 → 多头格局；价格 \x3C MA20 → 空头格局。MA5 > MA20 > MA60 → 多头排列，趋势强势。MA5 \x3C MA20 \x3C MA60 → 空头排列。
2. 趋势强度评估： MACD > Signal 且 Hist > 0 → 动能偏多；MACD \x3C Signal 且 Hist \x3C 0 → 动能偏空。change_20d_pct 反映近期趋势方向和幅度。
3. 超买超卖识别： RSI > 70 → 超买，回调风险；RSI \x3C 30 → 超卖，反弹可能。RSI > 80 视为极度超买/超卖。
4. 布林带位置： 价格接近 BB_Upper → 高估/阻力；接近 BB_Lower → 低估/支撑。
5. 波动率评估： ATR14 / close 的比值衡量波动率。>2% 为高波动，\x3C1% 为低波动。
6. 量仓配合： 价格涨 + 持仓增 → 多头主动；价格涨 + 持仓减 → 空头回补。偏离 5 万手以上视为显著变化。

二、基差分析 (basis_analysis)

数据指标： spot_price, futures_price, current_basis, basis_pct, latest_basis, basis_zscore_180d, basis_slope_20d, structure(contango/backwardation/flat)

分析框架（你需要做的）：

1. 基差率绝对判断： basis_pct > 5% → 期货大幅升水(Contango)，现货供应充裕，偏空。basis_pct \x3C -5% → 期货大幅贴水(Backwardation)，现货偏紧，偏多。±2% 以内视为合理区间。
2. 历史分位判断： Z-score > 2 → 基差处于历史极高（期货升水极端），回归压力大。Z-score \x3C -2 → 历史极低（现货升水极端）。
3. 基差趋势： slope_20d > 0 → 基差走强（现货相对走强），偏多。slope_20d \x3C 0 → 基差走弱（期货相对走强），偏空。
4. 期限结构与基差联动： Backwardation + 基差 Z-score 低位 → 现货紧张信号加强。Contango + 基差 Z-score 高位 → 库存充裕信号加强。

三、期限结构分析 (term_structure_analysis)

数据指标： structure(contango/backwardation/flat), front_contract/back_contract, front_price/back_price, spread, spread_pct, carry_score, 各合约间价差(spread_xxx)

分析框架（你需要做的）：

1. 结构类型判断： Contango（远月 > 近月）→ 库存充裕、持有成本定价、偏空；Backwardation（近月 > 远月）→ 现货紧张、便利收益 > 持有成本、偏多。
2. 展期收益： Contango → 多头展期亏损（展期收益为负），空头有利；Backwardation → 多头展期获利（展期收益为正），多头有利。
3. 价差幅度解读： spread_pct > 5% → 结构信号强烈。spread_pct \x3C 2% → 结构信号弱，市场可能平坦。
4. Full Carry 理论验证： 实际价差 > 理论 Full Carry → 存在仓储利润空间，库存意愿强 → 偏空。实际价差 \x3C Full Carry → 供给不足信号 → 偏多。
5. 跨合约价差异常： 某两个合约间价差异常放大 → 可能存在结构性供需扭曲，需要结合品种特性判断。

四、库存仓单分析 (inventory_analysis)

数据指标： latest_inventory(吨), inv_change_wow(%), inv_change_mom(%), inv_zscore_180d, latest_warehouse_receipt(吨), wr_change_5d(吨)

分析框架（你需要做的）：

1. 历史分位（Z-score）是核心信号： Z > 2.5 → 库存历史极高，供给严重过剩，强看空。Z > 1.5 → 偏高，偏空。Z \x3C -2.5 → 库存历史极低，供给紧张，强看多。Z \x3C -1.5 → 偏低，偏多。±0.5 附近 → 供需平衡。
2. 周度变化反映边际变化： WoW > 15% → 短期供给激增，利空。WoW \x3C -15% → 快速去库，利多。注意节假日和交割前后可能出现的异常值。
3. 月度变化反映趋势： MoM > 20% → 月度累库趋势，偏空。MoM \x3C -20% → 趋势性去库，偏多。
4. 仓单变化补充验证： 仓单增加 + 库存增加 → 可交割品充裕，空头交货方便。仓单减少 + 库存低位 → 虚实盘比高，近月逼仓风险。
5. 库存周期理论： 库存高位 + 价格低位 → 被动去库初期；库存低位 + 价格高位 → 被动累库初期。结合价格判断周期阶段。
6. 投机性库存 vs 真实消费： 若库存增加伴随价格下跌 → 可能是被动累库（需求弱），信号更偏空。

五、持仓席位分析 (positioning_analysis)

数据指标： net_position(手), net_change(手), concentration_idx, top20_long(手), top20_short(手), top20_long_pct, top20_short_pct, data_points

分析框架（你需要做的）：

1. 净持仓绝对值判断： net > 10000 → 机构资金明显看涨（强多信号）。300010000 → 偏多。03000 → 略偏多。负值同理反向。
2. 净持仓变化体现"聪明钱"动向： net_change > 8000 → 资金积极做多（强烈信号）。net_change \x3C -8000 → 积极做空。变动在 ±3000 以内视为正常波动。
3. 前 20 会员多空比： long_pct > 65% → 主力一致看多（但注意拥挤风险）。long_pct \x3C 35% → 主力一致看空。45%~55% → 多空均衡。
4. 持仓集中度： concentration_idx > 0.3 → 持仓集中在少数席位，方向性风险大（一方拥挤可能反转）。\x3C 0.1 → 持仓分散，无集中风险。
5. 拥挤度策略： 前 20 极度偏多 + 行情在高位 → 多头拥挤，回调风险增加。前 20 极度偏空 + 行情在低位 → 空头拥挤，轧空风险。

六、新闻情绪分析 (news_analysis)

数据指标： total_news_count, bullish_news_count, bearish_news_count, neutral_news_count, sentiment_ratio

分析框架（你需要做的）：

1. 情绪比率： sentiment_ratio > 0.2 → 利多新闻占优势。> 0.5 → 强烈偏多。\x3C -0.2 → 利空。\x3C-0.5 → 强烈偏空。
2. 新闻总量： total \x3C 5 → 信息不足，此维度权重应降低。> 20 → 信息充裕，可信度高。
3. 中性占比： neutral > 60% → 市场缺乏明确方向，情绪以观望为主。

软数据补充指南

重要原则：硬数据（价格/持仓/库存/基差）必须来自 API，绝不编造。模型只能解读和搜索真实存在的信息。

当 AKShare 新闻不足时

AKShare 的新闻接口（futures_news_shmet）来自上海金属网，对非有色金属品种覆盖极弱。当 news_analysis 的 quality 字段为 "insufficient" 或 "unavailable" 时，你（AI Agent）应该自行搜索补全。

各品类搜索策略

搜索要求

• 按时间排序，只返回 48 小时内 的信息
• 每条标注来源网址和发布日期
• 不要编造任何数字（库存吨数、持仓手数、价格等）
• 对拿不准的信息，明确标注"未经核实"

情绪评分方法

搜索到新闻后，按以下框架评分（替代 keyword matching）：

1. 利多信号（+1~+3 分）：交易所库存下降、进口政策收紧、天气减产、地缘冲突加剧避险、下游开工超预期
2. 利空信号（-1~-3 分）：库存累积、政策抛储、替代品价格下跌、需求数据低于预期、交易所提高保证金
3. 中性/观望（0 分）：信息量不足、多空交织、仅是例行公告
4. 最终 sentiment_score = sum(score) / article_count，保留 2 位小数
5. 若信息仍不足（\x3C 3 条有效新闻），明确标注"信息不足，此维度不参与决策"

数据缺失处理

当某个维度因 AKShare 不支持而返回 {"status": "empty"} 时：

数据来源标注规范

每个维度的每个数值字段都必须标明来源。不编数据，不混淆来源。

来源类型

各维度数据来源模板

输出 JSON 的 analysis_details 中，每个维度必须带有 data_source 字段：

{
  "technical_analysis": {
    "data_source": "api",
    "RSI14": 70.5,
    "MACD": 37.8,
    "close": 3257.0,
    ...
  },
  "basis_analysis": {
    "data_source": "api",
    "spot_price": 3280.0,
    "basis_pct": -0.6,
    ...
  },
  "news_analysis": {
    "data_source": "mixed",
    "akshare": {
      "total_news_count": 3,
      "sentiment_ratio": 0.1,
      "quality": "insufficient"
    },
    "ai_search": {
      "search_query": "菜粕 5月 2026 进口政策 新闻",
      "content_count": 12,
      "sentiment_score": 0.35,
      "key_findings": [
        "加拿大油菜籽产量预估下调 200 万吨（来源：USDA 5月报告）",
        "海关数据显示 4 月进口到港量环比下降 18%（来源：中国海关总署）"
      ]
    }
  }
}

标注规则

1. API 能取到的数据，绝不编。 取不到的字段标 "status": "N/A" 并注明原因。
2. AI 搜索补充的数据，必须带搜索来源。 每条信息标注出处 URL 和日期。
3. 搜索不到也不编。 明确写上 "ai_search": {"note": "搜索后仍未找到相关数据"}。
4. API 和 AI 搜索的分界线要清楚。 同一个维度里既有 API 字段又有 AI 搜索字段时，用 api / ai_search / computed 三级标注。
5. 所有数字必须是 JSON 原生类型（number/string/boolean），不能是 numpy/pandas 特殊类型。

综合决策框架

动态权重系统

本引擎内部使用三维动态权重（品种品类 × 各模块置信度 × 市场状态）：

市场状态自适应加成

• 高波动（ATR/close > 2%）→ 技术面+10%，新闻情绪+50%
• 趋势市场（20日有明确方向）→ 技术面+15%
• 低波动/震荡（ATR/close \x3C 1%）→ 基差+10%，库存+10%

决策选择框架

拿到 6 个维度的结构化数据后，你应该：

1. 逐维度评估： 按上述方法论对每个维度独立判断多空方向和置信度。
2. 加权聚合： 考虑上述动态权重，不要简单数票数。黑色系的库存维度空头信号比农产品新闻维度多头信号更可信。
3. 分歧度评估： 如果多空维度数量接近（差距 ≤1），信号不可靠，建议"观望"。
4. 极端信号优先： 当某个维度出现极端信号（Z-score > 2.5 或 RSI > 80），该维度的权重应该进一步提升。
5. 仓位与风险匹配： 分歧度越高 → 仓位越低。信号一致度越高 → 可适当加仓。最大仓位不超过 20%。

支持的品种代码

注意事项

• 数据时效：期货数据在交易日收盘后更新，分析前确认数据日期
• 持仓数据：前 20 会员持仓 T+1 日公布
• 风险提示：输出结果仅供参考，不构成投资建议
• 缓存位置：所有数据缓存在 cache/ 目录，删除可重新获取

分析风格指南

你的输出形式是"期货投资决策委员会会议实录"——六个分析师依次发言，裁判长最终裁决。

核心语言要求

• 纯中文，绝对禁止任何英文单词、缩写或术语。 用"远期升水结构"而非"contango"，用"现货升水"而非"backwardation"，用"持仓量"而非"open interest"
• 禁止出现任何 markdown 符号（如 **、#、-），纯文本输出
• 所有结论必须有具体数字支撑，严禁编造数据

角色设定

每个分析维度有一个独立角色，在陈述时使用以下身份和语气：

辩论结构

1. 序章：以"⚔️ 期货投资决策委员会 | XX 多空辩论实录"开场
2. 分轮辩论：六个维度依次展开，每个维度先由多头代表发言，再由空头代表发言
3. 裁判裁决：裁判长综合各方论述，指出最关键的分歧点，给出最终判断
4. 风控审核：风控总监独立评估风险
5. CIO 最终决策：方向、仓位、止损止盈、监控要点

裁决原则

• 不简单数票数。黑色系的库存维度空头信号比农产品新闻维度多头信号更可信
• 分歧度过高（多空维度数接近）时，选择观望而非强判方向
• 极端信号（Z-score > 2.5、RSI > 80 等）应被重点强调
• 最终决策必须包含仓位比例和止损位，不能只给方向不给操作