# Skill Macro Futures Scenario Analysis

> 基于 PandaData 的宏观事件—期货预期分析：读取宏观经济日历的实际值、市场预期与前值，结合期货价格、成交量、持仓量、基差、期限结构、库存与仓单，对沪金、沪铜、原油及用户指定品种输出基准、偏强、偏弱情景。当用户询问「美国CPI对期货影响」「宏观事件期货预期」「美联储对商品影响」「期货供需与宏观共振」「事件公布前情景」时触发。仅作条件化研究，不承诺涨跌或生成自动交易指令。

- Skill: `quantskills/skill-macro-futures-scenario-analysis` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx get-skill add quantskills/skill-macro-futures-scenario-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/quantskills/skill-macro-futures-scenario-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: quantskills (https://skillmd.com/u/quantskills)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/quantskills/skill-macro-futures-scenario-analysis

---


# 宏观事件—期货预期分析

> QuantSkills 社区项目，由 GitHub 用户 `cikeqi` 维护。项目尚未经过独立审核，不代表 QuantSkills 官方认证，也不承诺收益或生产环境适用性。

本 Skill 用于做**证据约束的概率分析**，不是预测必然涨跌、提供下单指令、保证收益或替代用户的风险管理。核心链条是：

```text
事件/数据 → surprise 与政策含义 → 宏观传导 → 品种供需 → 当前市场定价
→ 期货价格/持仓/基差/期限结构确认 → 分周期情景与失效条件
```

必须把“基本面方向”和“价格已经交易了多少”分开。宏观数据利多不等于期货当日必涨；已充分定价、期限结构、库存和仓位都可能令价格反应相反。

## 一、分析模式与输入门槛

根据用户输入选择一种或多种模式：

1. **事件模式**：用户给出已发生、即将发布或指定日期的宏观/政策/产业事件，并给出期货品种或合约。
2. **指标模式**：用户给出一个宏观指标或指标代码、日期区间和期货对象，分析指标变化与传导。
3. **供需模式**：用户要求分析某品种的库存、产量、开工、进口、基差或期限结构。
4. **综合模式**：事件/宏观指标 + 供需 + 期货市场数据。默认优先使用综合模式，但只在数据确实取到并通过校验时这样表述。

至少需要：

- 一个可识别的事件、指标、政策主题或供需问题；
- 一个明确的期货品种/合约或用户允许的候选品种范围；
- 分析时点或日期区间。未给区间时，要求用户确认，或在报告中明确采用的观察区间，不自行假设“今日”；
- 日期标准化为 `YYYYMMDD`，并确认 `start_date <= end_date`。

如果品种根代码和交易所/合约无法唯一解析，先用已批准的期货基础信息或主力接口解析；无法唯一解析时停止，不凭经验拼接代码。事件名称或指标无法唯一映射时，列出候选并要求用户确认，不把相似指标当成同一指标。

## 二、PandaData 只读调用边界

只使用当前环境中已批准且实际可用的 PandaData MCP 能力。通过 `mcp__pandadata__call_pandadata` 调用已文档化的方法；调用前可用 `mcp__pandadata__get_method_doc` 或 `mcp__pandadata__search_methods` 核对参数。不得声称调用了没有实际返回结果的方法。

凭证只能由已批准运行时从环境变量或 `~/.pandadata/pandadata.env` 读取。禁止要求用户在聊天中粘贴 token、输出 token/cookie/header、把凭证写入报告、日志或新文件。不得自动安装、自动登录或修改 PandaData 配置。

禁止使用 WebSearch、任意网页、第三方行情源、券商/交易 API、用户未声明的缓存、fixture、合成数据或插值数据作为静默 fallback。PandaData 不可用时必须说明能力/认证/套餐阻塞，不填充猜测。

本 Skill 只读：禁止下单、撤单、修改账户/持仓、自动执行策略、回测、统计胜率或给出保证收益的交易指令。

## 三、已批准的数据路由

### 1. 事件日历与宏观指标

宏观事件优先走：

```text
get_macro_cal_config(event_code=[...])
get_macro_cal(event_code=[...], start_date="YYYYMMDD", end_date="YYYYMMDD")
get_macro_cal_info(event_code=[...], start_date="YYYYMMDD", end_date="YYYYMMDD")
```

`get_macro_cal` 可返回：事件代码、中文事件/指标名、北京时间发布时间、报告期、实际值 `actual_value`、市场预期 `consensus_value`、前值 `previous_value`、重要性、国家、分类和来源。只在字段存在且同口径可比时计算：

```text
surprise = actual_value - consensus_value
revision = previous_value（仅作前值背景，不当作修订值）
```

不同单位、同比/环比、累计/当期、季调/未季调不可直接相减。若预期为空，报告“无法计算 surprise”，不要用前值替代预期。若数据尚未公布，只分析“预期情景”，不伪造实际值。

对于已知指标代码，先用 `get_macro_detail(symbol=[...], category=对应前缀, fields=[...])` 确认指标名称、频率、单位、国家/地区、来源、起止日期和 `api_name`，再按返回的 `api_name` 查询时间序列。指标代码前缀不是接口名；不得把国家代码、分类代码和 API 名称混用。

已验证的宏观序列接口包括：

```text
get_macro_na   # 中国国民经济核算
get_macro_in   # 中国工业
get_macro_ci   # 中国景气指数
get_macro_pi   # 中国价格指数
get_macro_fa   # 中国固定资产投资
get_macro_fi   # 中国财政
get_macro_mb   # 中国货币与银行
get_macro_ir   # 中国利率与汇率
get_macro_fe   # 中国对外经济
get_macro_dt   # 中国国内贸易
get_macro_gb   # 国际宏观
```

这些接口通常返回 `symbol, period_date, data_value`，不能把 `period_date` 当作发布日期；宏观指标的报告期和日历发布时间要分开记录。

### 2. 期货对象与行情

- 明确合约：用 `get_future_daily(symbol=[contract], start_date, end_date, fields=[...])`。
- 只给品种根代码：先用 `get_future_dominant(underlying_symbol=[root], start_date, end_date)` 获取逐日主力映射，再按每个日期的 `symbol` 查询行情；不得自行拼接月份或交易所后缀。
- 需要当日或分钟证据时，只有在接口和权限确实可用时才用 `get_future_min(..., frequency="1m"|"5m"|"15m"|"60m")`。不能把日线冒充分钟线。
- 期货品种/合约信息用 `get_future_detail` 核对交易所、品种、乘数、到期日和交易时间。
- 可补充 `get_future_basis`、`get_future_term_structure`、`get_future_inventory`、`get_future_warehouse_receipt`、`get_future_calendar_arbitrage`、`get_future_dominant_corr`、`get_future_variety_posi`、`get_future_netposi_rank` 等已文档化接口，但每个接口都必须单独记录实际返回状态与字段含义。

期货行情优先字段：`date, symbol, dominant_id, underlying_symbol, open, high, low, close, settlement, pre_settlement, volume, open_interest, amount`。若缺少持仓量、成交量、现货价或期限结构，只能说“该维度无法确认”。

### 3. 特色与行业供需

按已确认的数据覆盖，按需查询对应的 `get_macro_*` 行业接口，并先用 `get_macro_detail` 验证代码和 `api_name`：

- `CM` 宏观特色/大宗数据：大宗商品、能源、建材、钢铁、有色、农副及国内外现货参考价；
- `EN` 能源：WTI/Brent、OPEC 基准、EIA 原油/汽油/精炼油/库欣/天然气库存及变动、煤炭和天然气产业链；
- `ST` 钢铁：螺纹/热卷/铁矿价格、粗钢和螺纹产量、高炉开工、钢材/螺纹社会库存、铁矿港口库存；
- 有色金属行业接口：铜、铝、锌等产量、库存、进口、开工和价格；
- 农林牧渔行业接口：大豆、豆粕、玉米、棕榈油、生猪、鸡蛋等供需、产量、库存、进口和养殖数据；
- 化工行业接口：原料价格、产能/开工、库存、产量、进口和加工利润。

不要因为文件中存在指标就声称该指标当前可查询；调用返回空或错误时按状态报告。现货、外盘和期货价格必须保留 `country`、`region`、`source`、单位和货币，不能把外盘价格当作国内现货，也不能把参考价当作交易所结算价。

## 四、数据校验和调用状态

每次调用都保留脱敏 envelope：

```text
status, method, purpose, requested_symbol, resolved_symbol,
start_date, end_date, frequency, returned_rows, valid_rows, reason
```

状态固定为：

- `ok`：调用成功、字段和口径可解释、数据通过校验；
- `empty`：返回零行、指定区间无记录、无事件或无主力映射；
- `error`：认证、套餐、SDK、参数、字段、日期、重复键、非有限值或口径冲突导致调用不能用于分析；
- `unsupported`：未批准方法、未知资产、请求频率/维度超出当前能力或需要未提供的外部信息。

对时间序列至少检查：日期/报告期可解析、日期排序、重复键、数值有限、单位和频率一致、请求区间内过滤。期货 OHLC 必须满足：

```text
high >= max(open, low, close)
low <= min(open, high, close)
```

库存、产量、开工、持仓等非价格数据应检查有限性、单位、非负约束是否适用，并保留原始符号和报告期。简单倒序且无重复可以排序并记录；冲突重复、缺关键字段、跨口径拼接必须报错。不得复制、插值、合成或跨来源凑数。

数据日和事件发布时间不可混淆。事件公布后才可使用 actual；分析“事件前预期”时不得把事件后数据倒灌。最后一根行情可能未收盘时，不能视作已确认的价格反应。

## 五、分析编排

### 第一步：定义事件和预期差

明确：

- 事件/指标名称、国家/地区、发布时间和报告期；
- 实际值、预期值、前值、修订信息（如有）；
- surprise 方向和大小，是否能与历史同口径比较；
- 市场可能如何重新定价：利率、汇率、风险偏好、增长预期、通胀预期或政策预期；
- 影响期限：日内/1—5 个交易日、数周、数月。

对于政策、地缘事件、天气等没有结构化实际值的主题，必须区分“用户描述/已知事实”“分析假设”和“待确认信息”，不能虚构新闻文本或事件结果。

### 第二步：建立传导链

至少写出一条可检验的链条，并列出反向链条：

```text
事件 → 利率/汇率/风险偏好或增长预期 → 全球/国内定价锚
→ 直接需求或成本 → 库存/供应约束 → 期货曲线与资金确认
```

示例（仅为机制模板，不是当前结论）：

```text
美国通胀超预期
→ 降息预期后移、实际利率/美元可能上行
→ 黄金估值承压、工业品风险偏好受压
→ 但供给扰动或低库存可能抵消宏观利空
→ 检查价格、持仓、库存、基差和期限结构是否一致
```

### 第三步：检查品种供需

对每个品种至少回答：

- 需求：宏观增长、下游开工、消费、出口或替代关系如何变化？
- 供给：产量、产能、开工、进口、天气、政策或运输是否变化？
- 库存：库存方向、绝对水平和季节性位置是否支持？
- 现货/期货：基差是扩大还是收窄？现货是否验证期货？
- 期限结构：升水/贴水、近远月价差是否反映紧张或宽松？
- 资金确认：价格变化是否伴随成交量、持仓量或净持仓方向变化？

不要把单一指标机械映射成方向；至少寻找一个支持证据和一个反证/风险证据。

### 第四步：评估当前定价

区分：

1. **方向逻辑**：事件对基本面或估值的理论影响；
2. **市场事实**：调用得到的价格、收益率、美元、持仓、基差、库存和曲线；
3. **预期差**：事实是否已提前反映事件；
4. **反应函数**：若实际结果高于/低于预期，哪些变量先动，哪些品种可能相对敏感。

不要以“过去某次事件后上涨”推出稳定胜率；历史相似期只能作为背景，且必须说明样本口径和不可比之处。当前接口没有可靠的事件—收益历史回测时，不得声称历史胜率或统计显著性。

### 第五步：输出情景而非单点预测

至少给出基准、利多/偏强、利空/偏弱三个情景；事件前用结果情景，事件后用实际值与预期差情景。每个情景包含：

- 触发条件；
- 宏观与供需传导；
- 可能受影响的品种和相对强弱；
- 时间窗口；
- 需要观察的确认指标；
- 失效条件和替代解释；
- 置信度（高/中/低）及原因。

如果不同品种的传导方向冲突，保留冲突，不强行合成一个“商品整体方向”。

## 六、固定中文报告格式

```markdown
# 宏观事件—期货预期分析报告

## 1. 请求与分析范围
- 分析模式：事件 / 指标 / 供需 / 综合
- 用户问题：
- 分析时点与日期区间：
- 期货品种/合约及解析证据：
- 观察周期：日内 / 1—5个交易日 / 数周 / 数月

## 2. 数据与来源状态
| 用途 | PandaData方法 | 标的/指标 | 请求区间 | 频率 | 返回/有效行数 | 状态 | 阻塞或口径说明 |
|---|---|---|---|---|---:|---|---|

## 3. 事件与预期差
- 事件、国家/地区、发布时间、报告期：
- 实际值 / 市场预期 / 前值 / 单位：
- surprise：可计算值或“无法计算及原因”：
- 已知事实、分析假设、未知信息：

## 4. 宏观传导链
- 主传导链：
- 反向/抵消链：
- 影响期限：

## 5. 当前市场定价
| 变量 | 数据事实 | 对预期的含义 | 可信度/限制 |
|---|---|---|---|

## 6. 品种供需与验证
| 品种/合约 | 需求 | 供给 | 库存 | 基差/期限结构 | 价格/持仓确认 | 支持证据 | 反证与风险 |
|---|---|---|---|---|---|---|---|

## 7. 情景分析
| 情景 | 触发条件 | 传导与相对影响 | 时间窗口 | 确认条件 | 失效条件 | 置信度 |
|---|---|---|---|---|---|---|

## 8. 条件化观察
1. 若……，则……；若……不成立，则……。
2. 若……，则……；需同时观察……，不能仅凭……确认。
3. 在……之前，不把……视为已确认方向。

## 9. 风险边界与结论
- 主要不确定性：
- 数据缺失/降级说明：
- 结论：用“偏强/偏弱/震荡/方向不明 + 条件 + 时间窗口”表达，不写必然涨跌或直接买卖指令。
```

当关键数据为 `empty/error/unsupported` 时，先报告阻塞原因，停止依赖该数据的完整判断；仍可使用已验证的其他数据，但必须明确是部分分析或降级分析。任何数值结论都要注明来源、日期、单位和频率。

## 七、典型传导框架（仅作检查清单）

- **利率/美元/贵金属**：政策路径 → 实际利率/美元 → 黄金白银估值；同时检查避险需求、央行购金和供给扰动。
- **全球增长/有色**：增长预期 → 制造业/投资/库存 → 铜铝锌需求；同时检查矿端、冶炼、进口、现货升贴水和库存。
- **中国地产/基建/黑色**：地产与基建 → 钢材需求 → 铁矿/焦煤/焦炭成本和钢厂利润；同时检查产量、开工、社会库存、港口库存和基差。
- **通胀/能源**：通胀与供给冲击 → 原油/成品油成本 → 化工和运输；同时检查 EIA/OPEC、炼厂利用率、库存、裂解和期限结构。
- **天气/农产品**：天气与种植 → 产量预期 → 进口/压榨/库存 → 豆粕、玉米、棕榈油等；同时区分预报、已发生损失和市场已定价程度。
- **生猪/鸡蛋**：存栏/出栏 → 供应节奏 → 现货与养殖利润 → 期货；同时考虑季节性消费、交割品和基差。

这些框架不能替代数据验证。没有对应字段时明确写“该传导环节未被当前数据确认”。

