SIFmonitor — 股指期货贴水价差监控

Purpose

当用户需要可视化对比不同到期时间的股指期货贴水情况时，本 skill 负责：

1. 从配置的双数据源（互相兜底 + 交叉验证）获取中金所股指期货（IF / IH / IC / IM）全部合约及挂钩指数的历史与当日收盘价；
2. 计算基差、年化升贴水率、剩余天数等衍生指标；
3. 生成一份规范 CSV（所有标的源数据合并）与一份交互式 Plotly 看板；
4. 看板含两大板块：① 指定品种全部在交易合约价格变化汇总图（叠加挂钩指数）；② 指定两合约价差变化趋势图。

> 本 skill 仅做历史与当日数据的可视化与测算，不构成任何投资建议。

Context

领域：中金所（CFFEX）股指期货交易数据可视化与升贴水分析。

数据依赖（🔒 必须声明）：
- ✅ 配置数据源 A：akshare（Python 库）——futures_zh_daily_sina 取合约日线、stock_zh_index_daily 取挂钩指数日线。
- ✅ 配置数据源 B：新浪财经 HTTP 接口（独立代码路径，标准库 urllib 直接请求）——合约日线与指数日线。
- ✅ 双源交叉验证：fetch_data.py 同时取两源，逐日比对收盘价，偏差超阈值（默认 0.02 元或 0.1%）告警；以 A 为主、B 校验。
- ❌ 严禁 WebSearch / 网络搜索获取价格；禁止引用网页文章中的价格数字；禁止编造或估算数据。
- 精度：所有价格精确到小数点后两位。

适用场景：用户要监控股指期货贴水、对比不同到期合约基差、分析升贴水率或价差走势时。

文件结构

详见 README.md。脚本与映射的单一事实来源见 scripts/contracts.py（品种→指数映射、合约代码生成、到期日推算）。

数据源（🔒 强约束）

🔒 所有分析数据仅来源于本 skill 配置的数据源，绝对禁止使用 WebSearch / 网络搜索获取价格数据。

1. 数据源 A（主）— akshare 库
   - 合约日线：ak.futures_zh_daily_sina(symbol="IC2608")
   - 挂钩指数日线：ak.stock_zh_index_daily(symbol="sh000905")（沪深300=sh000300 / 上证50=sh000016 / 中证500=sh000905 / 中证1000=sh000852）
2. 数据源 B（校验/兜底）— 新浪财经 HTTP 接口（标准库 urllib，无第三方依赖）
   - 合约日线：https://stock2.finance.sina.com.cn/futures/api/json.php/InnerFuturesNewService.getDailyKLine?symbol=IC2608
   - 指数日线：https://money.finance.sina.com.cn/quotes_service/api/json_v2.php/CN_MarketData.getKLineData?symbol=sh000905&scale=240&ma=no&datalen=N
3. 交叉验证：两源逐交易日比对收盘价，最大绝对偏差超阈值则告警；取主源值，缺失时用另一源补齐。
4. 合约与指数映射：见 scripts/contracts.py（单一事实来源）。品种→指数：IF→沪深300、IH→上证50、IC→中证500、IM→中证1000。
5. 在交易合约识别：按中金所挂牌规则，每个品种同时有 4 个合约（当月、下月、随后两个季月），由 contracts.py 依参考日期推算合约代码与到期日（合约月份第三个星期五）。
6. 精度：所有价格统一 round(x, 2)。

> ⚠️ 若两数据源均无法取得某合约/指数真实数据，必须明确告知用户该标的缺失，不得用估算值填充图表。

工作流

步骤 1：解析品种、合约与区间

1. 解析用户关注的品种（IF / IH / IC / IM，可指定 1~2 个）与分析区间（默认：今年以来至当日）。
2. 若用户指定「比较两个标的的价差」，记录标的 A、B（可为合约代码或挂钩指数，如 IC2608/IC2612/中证500）；看板板块二亦可交互式任选。否则默认取该品种最近两合约。
3. 用 scripts/contracts.py 推算各品种在交易合约代码与到期日（见 references/data-sources.md）。

步骤 2：采集历史与当日收盘价（双源交叉验证）

运行 scripts/fetch_data.py：

python scripts/fetch_data.py --varieties IF,IC --start 2026-01-01 --end 2026-07-19 \
       -o raw_futures.json

• 输出 raw_futures.json（schema 见 references/data-sources.md）：含各品种全部在交易合约日线与挂钩指数日线，已做两源交叉验证。
• 校验：每个合约/指数须含 ≥2 个交易日的 close，且均为两位小数精度；缺失标的显式告警，不静默填充。

步骤 3：生成交付物

运行 scripts/build_dashboard.py：

python scripts/build_dashboard.py raw_futures.json ./output \
       --spread IC2608,IC2612

• 产出 规范 CSV futures_source.csv：所有标的源数据合并为一个文件（字段见「输出文件约定」）。
• 产出 交互式 Plotly 看板 futures_dashboard.html，满足下方全部可视化规范。
• --spread A,B：指定板块二绘制价差的两个合约（默认取首个品种的最近两合约）。

步骤 4：交付与说明

1. 通过 present_files 同时给出 futures_dashboard.html 与 futures_source.csv。
2. 用文字简述关键结论（如当前各合约贴水幅度、年化升贴水率最高/最低合约），但结论须完全基于 CSV/看板中的真实数据。

交互式可视化规范（🔒 强制）

所有图表支持中文显示（标题、坐标轴标签、图例、表格均无乱码），由 futures_dashboard.html 实现：

板块一：指定品种全部在交易合约价格变化汇总图

• 同一图表叠加显示一个品种下全部在交易合约及挂钩指数的价格走势（如 中证500、IC2608、IC2609、IC2612）。
• 若用户指定两个品种，以两张图分别展示（每个品种一张）。
• 每个图下方以表格列出当日该品种不同到期时间合约的：合约代码、价格、当日涨跌额、涨跌幅、挂钩指数价格、基差、年化升贴水率、剩余天数、到期时间。
• 图表右侧配置数据提示框（固定定位、不与图表重叠）：
• 鼠标悬停时显示竖直参考线；
• 提示框内显示该日期图上各标的（合约+指数）的价格。
• 右上角配置「区间涨跌幅模式」开关：
• 开启后，鼠标拖选时间区间时显示两根竖直参考线标记起止时间；
• 提示框内显示起止日期及区间内各标的涨跌幅。

板块二：指定两标的价差变化趋势图（可任选标的 A / 标的 B）

• 每个品种一个面板，下拉框可选标的 A 与标的 B，选项覆盖「该品种全部到期时间合约 + 挂钩指数本身」。
• 例如针对 IC：可分别选择 IC2609 与 IC2608 计算两合约价差，也可选 IC2609 与 中证500 指数计算合约−指数价差。
• 价差 = 标的A收盘价 − 标的B收盘价，图表展示价差变化曲线；切换选项即时重绘。
• 命令行 --spread A,B 仅作为首个品种的默认选择（其余品种取默认两标的：优先两个有数据的合约）。
• 图表右侧配置数据提示框（不与图表重叠）：
• 鼠标悬停时显示竖直参考线；
• 提示框内显示该日期价差。
• 右上角配置「区间涨跌幅模式」开关：开启后拖选时间区间显示两根竖直参考线，提示框内显示起止日期及区间内价差变化的绝对值（|结束价差 − 起始价差|）。

Output

本 skill 的最终交付物为两个文件（通过 present_files 一并给出）：

futures_dashboard.html   交互式 Plotly 看板（板块一合约+指数叠加 + 板块二价差趋势 + 右侧提示框 + 区间涨跌幅拖选）
futures_source.csv       规范源数据（所有标的合并，含非交易日行与衍生指标）

文字结论须完全基于上述 CSV/看板中的真实数据，不臆测。

输出文件约定

🔒 本 skill 涉及文件产出，约定如下：

• 输出目录：用户指定目录；未指定时使用当前工作目录。脚本内置 os.makedirs(out_dir, exist_ok=True)。
• 文件命名：
• futures_source.csv — 所有标的合并的规范源数据（含非交易日行）。
• futures_dashboard.html — 交互式 Plotly 看板。
• raw_futures.json — 中间数据（由 fetch_data.py 产出，供 build_dashboard.py 读取）。
• 文件格式：
• CSV 表头：交易日期,是否交易日,品种,合约代码,合约收盘价,当日涨跌额,涨跌幅,挂钩指数代码,挂钩指数收盘价,基差,年化升贴水率,剩余天数,到期时间
• 每行一条「品种-合约-日期」记录；非交易日保留该行，字段 是否交易日 标注「非交易日」，合约/指数价格取最近交易日收盘价（前向填充，两位小数）。
• 覆盖策略：同名文件直接覆盖，并在控制台提示已覆盖路径。
• 错误输出：脚本以 {"ok": false, "error": "..."} 结构化 JSON 输出到 stderr，不抛出未捕获异常、不暴露系统路径。

Notes

• 边界：本 skill 仅做历史与当日数据可视化与升贴水/价差测算，不构成任何投资建议。
• 关键定义：基差 = 期货收盘价 − 挂钩指数收盘价（<0 即贴水、>0 即升水）；年化升贴水率 = (基差 / 挂钩指数收盘价) / 剩余天数 × 365（以百分比展示，即再 ×100）；剩余天数 = 到期时间 − 交易日期；到期时间 = 合约月份第三个星期五（见 scripts/contracts.py）。
• 数据时效：看板数据截止于 raw_futures.json 的生成时间，不含实时行情。
• 看板加载：Plotly.js 走 CDN 并带 SRI 校验；数据已内嵌 HTML。
• 🔒 修改纪律：本 skill 由 skill-creator-king 创建。修改后必须加载 SCK 运行 validate.py + quality-audit.py，修到 0 HIGH、测试全绿为止。

Further Reading

• references/data-sources.md — 品种/指数映射、合约推算、交叉验证与 raw_futures.json schema
• references/chart-spec.md — 看板交互实现细则（供维护参考）
• scripts/contracts.py — 品种→指数映射、合约代码生成、到期日推算的单一数据源
• scripts/fetch_data.py — 双源取数 + 交叉验证，产出 raw_futures.json
• scripts/build_dashboard.py — 计算衍生指标，产出 CSV + HTML
• assets/dashboard_template.html — 看板 HTML 模板（build_dashboard.py 注入数据）
• data/sources.yaml — 数据源配置与禁止项声明