新增主力合约自动选取并补全项目文档

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tushare/src/contracts.py

@@ -0,0 +1,31 @@
+from datetime import date
+from typing import Optional
+
+# 品种主力合约轮换规则。
+# 每个品种维护:
+#   exchange: tushare 合约后缀(交易所)
+#   active: 当月 -> (主力合约月, 年份偏移)
+#           例 FG 12 月用次年 5 月,故 12 -> (5, 1)
+ROLLOVER_RULES: dict[str, dict] = {
+    "FG": {
+        "exchange": "ZCE",
+        "active": {
+            1: (5, 0), 2: (5, 0), 3: (5, 0),
+            4: (9, 0), 5: (9, 0), 6: (9, 0), 7: (9, 0),
+            8: (1, 1), 9: (1, 1), 10: (1, 1), 11: (1, 1),
+            12: (5, 1),
+        },
+    },
+}
+
+
+def active_contract(symbol: str, today: Optional[date] = None) -> str:
+    """按主力轮换规则,返回当日 ts_code(含交易所后缀)。"""
+    if symbol not in ROLLOVER_RULES:
+        raise ValueError(f"未配置 {symbol} 的主力轮换规则,可在 contracts.ROLLOVER_RULES 中追加")
+
+    today = today or date.today()
+    rule = ROLLOVER_RULES[symbol]
+    contract_month, year_offset = rule["active"][today.month]
+    year = today.year + year_offset
+    return f"{symbol}{year % 100:02d}{contract_month:02d}.{rule['exchange']}"

tushare/src/main.py

@@ -1,7 +1,7 @@
 import argparse
 import sys
 
-from . import fetcher, notifier, scorer, storage
+from . import contracts, fetcher, notifier, scorer, storage
 
 
 def run(ts_code: str) -> int:
@@ -76,9 +76,22 @@ def run(ts_code: str) -> int:
 
 def main() -> int:
     parser = argparse.ArgumentParser(description="期货合约三层打分模型")
-    parser.add_argument("ts_code", help="合约代码,如 FG2609.ZCE")
+    parser.add_argument(
+        "ts_code",
+        nargs="?",
+        help="合约代码,如 FG2609.ZCE;不传则按 --symbol 当月主力自动选取",
+    )
+    parser.add_argument(
+        "--symbol",
+        default="FG",
+        help="品种代号,在未传 ts_code 时按 contracts.ROLLOVER_RULES 选当月主力,默认 FG",
+    )
     args = parser.parse_args()
-    return run(args.ts_code)
+
+    ts_code = args.ts_code or contracts.active_contract(args.symbol)
+    if not args.ts_code:
+        print(f"[AUTO] {args.symbol} 当月主力 -> {ts_code}")
+    return run(ts_code)
 
 
 if __name__ == "__main__":