futures-arbitrage-pipeline

name	futures-arbitrage-pipeline
description	端到端生成期货跨月套利结论表的入口 skill。输入是四大期货交易所(上期所 / 大商所 / 郑商所 / 广期所)当日的原始行情和合约参数,产出是项目根目录下的「套利结论.xlsx」。内部由两步流水线组成,分别对应两个子 skill —— step 1 `excel-template-contract-fill` 把原始数据整理为统一模板,step 2 `excel-arbitrage-conclusion` 把统一模板转成套利结论表。触发词:期货套利、套利结论、生成套利表格、跑套利流水线、/futures-arbitrage-pipeline。

futures-arbitrage-pipeline

这个 skill 干什么

从用户准备好的四大交易所原始数据开始,一键产出 项目根目录下的 套利结论.xlsx —— 也就是可以直接给交易员看的那张按利润率降序的跨月套利机会表。

整件事分成两步,每一步有自己的 reference skill,本 skill 只做"编排"——告诉你两步之间怎么衔接、哪里出错找谁、最终文件应该在哪里。

---

流水线总览

原始数据/                                ← 用户自行准备(从四大交易所官网下载)
  ├─ 期货数据/{上期所,大商所,郑商所,广期所}.{xlsx|csv}
  └─ 合约信息/{上期所,大商所,郑商所,广期所}.{xlsx|csv}
       │
       │  Step 1 · skill: excel-template-contract-fill
       │  参考脚本: tools/convert_raw_futures_to_template.py
       ▼
合约数据(整理后)/                        ← 中间产物(可复用、可审查)
  ├─ 上期所.xlsx   (sheet: 数据 + 映射表)
  ├─ 大商所.xlsx
  ├─ 郑商所.xlsx
  ├─ 广期所.xlsx
  └─ 缺失原因汇总.csv
       │
       │  Step 2 · skill: excel-arbitrage-conclusion
       │  参考脚本: tools/build_arbitrage_table.py
       ▼
套利结论.xlsx                            ← 最终产出(项目根目录)
  └─ sheet「结论」:10 列,按利润率降序,82 行左右

---

前置条件

⚠️ 不属于本 skill 的职责:四大交易所原始数据需要用户自己从交易所官网下载并放到 原始数据/ 下。

下载地址、命名约定、字段要求都写在 CLAUDE.md 的"前置准备"章节,这里不重复。

开始跑本 skill 之前请确认:

• 原始数据/期货数据/ 下有 4 个文件(上期所 / 大商所 / 郑商所 / 广期所)
• 原始数据/合约信息/ 下有 4 个文件
• 安装了 openpyxl(pip install openpyxl)
• 当前工作目录是项目根(aitaoli/)

---

执行方式

A. 一键跑(默认)

两条命令,先 step 1 再 step 2:

python tools/convert_raw_futures_to_template.py
python tools/build_arbitrage_table.py

跑完应当看到:

• 合约数据(整理后)/ 下 4 个 xlsx + 1 个 csv
• 合约数据(整理后)/缺失原因汇总.csv 理想情况只有表头
• 项目根 套利结论.xlsx,sheet 结论,82 行左右无空值

B. 换 AI / 脚本坏了

Step 1 脚本因为交易所改格式挂了 → 先修 step 1,然后再跑 step 2(因为 step 2 的输入就是 step 1 的产物)。

如果你不是 Claude,是别的 AI(Kimi / GLM / ...),可以照着两个子 skill 的 SKILL.md 各自重写一份等价脚本:

• Step 1 规则:.claude/skills/excel-template-contract-fill/SKILL.md
• Step 2 规则:.claude/skills/excel-arbitrage-conclusion/SKILL.md

两个 SKILL.md 都是语义化的 —— 描述"字段应该长什么样、怎么识别、怎么算、怎么校验",而不是"在第几列"。不同 AI 写出来的代码细节可以不同,但两个阶段的产物应当语义等价:

阶段	产物语义
Step 1	4 个 xlsx × 7 列 × N 行,无空值;一份可能为空的缺失原因 csv
Step 2	1 个 xlsx,sheet「结论」,10 列表头固定,N 行按利润率降序,无空值

---

两个子 skill 的分工

子 skill	干什么	读	写	参考脚本
excel-template-contract-fill	把四家交易所的异构原始文件统一成 7 列模板	原始数据/	合约数据(整理后)/	tools/convert_raw_futures_to_template.py
excel-arbitrage-conclusion	基于统一模板生成套利结论表	合约数据(整理后)/	套利结论.xlsx(项目根)	tools/build_arbitrage_table.py

分工原则:

• Step 1 的关注点是 "识别数据" —— 哪一列是收盘价、哪一列是保证金率、遇到 0 怎么回退,等等
• Step 2 的关注点是 "决策逻辑" —— 怎么挑主力 + 次主力、方向怎么判、风险标签怎么打、商品名称怎么规范化

这两层关注点不能混。step 1 不应该知道"什么是套利对",step 2 也不应该知道"上期所行情文件是品种段结构"。中间的 合约数据(整理后)/ 就是契约。

---

全链路自检

跑完整条流水线之后至少过一遍这些检查(每一条都有对应子 skill 的详细校验规则):

Step 1 产物(参考 excel-template-contract-fill/SKILL.md §自检规则)

• 4 个 xlsx 都存在,数据 sheet 行数 ≥ 该交易所合约信息的 95%
• 缺失原因汇总.csv 理想只有表头
• 随机抽 3 个合约(cu2605、a2605、AP605)手算 价格 × 保证金率 × 交易单位

Step 2 产物(参考 excel-arbitrage-conclusion/SKILL.md §自检规则)

• 套利结论.xlsx 在 项目根目录(不是 合约数据(整理后)/ 下!)
• sheet 名 结论、表头 10 列完全对齐模板
• 数据区零空值
• 利润率降序
• 抽 3 行总保证金,应当等于对应两个合约在 step 1 产物里的最低保证金之和
• 风险品种行数 ≤ 8,全部属于 CLAUDE.md 的风险清单

端到端对账

• 套利结论表的品种数 ≈ 82(当日有效可套利品种数)
• 找一个成交活跃的品种(比如 沪铜 / 豆粕 / 苹果),肉眼对比 step 1 产物里该品种的合约列表和 step 2 里挑出的套利对,应当是持仓量前 2 大的那两个

---

禁止事项

• ❌ 不要跳过 step 1 直接写 step 2 —— 合约数据(整理后)/ 是契约,step 2 不应该读 原始数据/
• ❌ 不要让最终产物 套利结论.xlsx 落到 合约数据(整理后)/ 或 20260411目标产出文件/ 之类 —— 用户明确要求最终文件在 项目根目录
• ❌ 脚本跑挂时不要"让 AI 自己凑数据",修脚本 / 重写脚本是唯一出路
• ❌ 不要在本 skill 里重复两个子 skill 的细节规则 —— 要改规则就去改对应子 skill 的 SKILL.md,本 skill 只描述"编排"

---

相关文件

• 项目背景和原始数据获取说明: CLAUDE.md
• Step 1 reference: .claude/skills/excel-template-contract-fill/
• Step 2 reference: .claude/skills/excel-arbitrage-conclusion/
• Step 1 参考脚本: tools/convert_raw_futures_to_template.py
• Step 2 参考脚本: tools/build_arbitrage_table.py
• 最终输出模板: .claude/skills/excel-arbitrage-conclusion/template/预期最后结果.xlsx