TrueHOOHA/shanxi-securities-tushare-skill / sxsc-tushare-analysis
sxsc-tushare-analysis
Verified对用户提到的标的(沪深股票、指数、公募基金、期货)进行综合分析,输出带 ECharts 图表的 HTML 分析报告。 触发条件:用户说"分析""研究""评估""看看XX怎么样""XX基本面""XX技术面""XX估值""XX财务""深度研究""对比"等分析类请求,且标的属于 A 股/指数/公募基金/期货。 本 skill 自动调用 sxsc_tushare 取数并输出完整报告,接管数据获取与分析全流程。当本 skill 被触发时,数据获取类 skill 不应同时激活——分析已包含数据。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 43.8 KB |
| scripts/adjustment.py | script | 8.7 KB |
| scripts/analysis_runner.py | script | 120.8 KB |
| scripts/attribution.py | script | 10.1 KB |
| scripts/basic_metrics.py | script | 4.3 KB |
| scripts/check_env.py | script | 8.8 KB |
| scripts/data_api.py | script | 41.2 KB |
| scripts/factor_signals.py | script | 10.3 KB |
| scripts/fund_analysis_runner.py | script | 61.7 KB |
| scripts/fut_analysis_runner.py | script | 41.4 KB |
| scripts/index_analysis_runner.py | script | 54.6 KB |
| scripts/report_html.py | script | 38.0 KB |
| scripts/result_model.py | script | 4.4 KB |
| scripts/risk_modeling.py | script | 6.3 KB |
| scripts/stock_analyzer.py | script | 1.1 KB |
| scripts/technical_indicators.py | script | 5.9 KB |
| scripts/token_util.py | script | 4.0 KB |
scripts/fut_analysis_runner.py
View on GitHub#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
期货综合分析 Runner(以主力连续合约为标的)。
架构:
data_api.DataAPI 取数(期货接口SDK不传fields)
-> 各维度 analyze_* 方法返回 DimensionResult
-> FutAnalysisRunner 汇总并渲染 markdown
用法:
from fut_analysis_runner import fut_report
print(fut_report("SR.ZCE")) # 白糖主力连续
print(fut_report("RB.SHF")) # 螺纹钢主力连续
print(fut_report("JM.DCE")) # 焦煤主力连续
输入:主力连续合约 ts_code(如 SR.ZCE / RB.SHF / JM.DCE),也接受纯 symbol(SR/RB)自动匹配连续合约。
"""
import os
import sys
from concurrent.futures import ThreadPoolExecutor, as_completed
from datetime import datetime, timedelta
from typing import Any, Dict, List, Optional
import numpy as np
import pandas as pd
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from basic_metrics import calc_ma, calc_max_drawdown, calc_returns, calc_sharpe, calc_volatility
from data_api import DataAPI, shift_date
from result_model import DimensionResult, ResultStatus, safe_result
from report_html import df_to_md_table, render_html_report
from technical_indicators import calc_boll, calc_kdj, calc_macd, calc_rsi
# 交易所后缀 -> (服务端 exchange 代码, 中文名)
# ⚠️ 原映射缺 INE(上海国际能源交易中心)与 GFEX(广州期货交易所),
# SC.INE/LU.INE/SI.GFEX/LC.GFEX 会因 exchange=None 使 fut_basic 调用失败。
EXCHANGE_MAP = {".ZCE": ("CZCE", "郑州商品交易所"), ".SHF": ("SHFE", "上海期货交易所"),
".DCE": ("DCE", "大连商品交易所"), ".CFE": ("CFFEX", "中国金融期货交易所"),
".INE": ("INE", "上海国际能源交易中心"), ".GFEX": ("GFEX", "广州期货交易所")}
# fut_holding 仅覆盖大商所
HOLDING_COVERED = {".DCE"}
def _today() -> str:
return datetime.now().strftime("%Y%m%d")
def _safe_float(value: Any) -> Optional[float]:
try:
if value is None or (isinstance(value, float) and np.isnan(value)):
return None
return float(value)
except Exception:
return None
def _resolve_ts_code(ts_code: str, api: DataAPI) -> str:
"""含后缀直接用;纯 symbol(如 SR/RB)按 fut_basic fut_type=2 匹配连续合约。
⚠️ fut_basic 的 exchange 是**必选**入参(服务端对缺 exchange 的调用返回错误),
纯 symbol 无法预知交易所,需逐个交易所尝试匹配。
"""
if "." in ts_code:
return ts_code
for _suf, (_ex, _) in EXCHANGE_MAP.items():
try:
df = api.get_fut_basic(exchange=_ex, fut_type="2")
if df is not None and not df.empty and "symbol" in df.columns:
m = df[df["symbol"] == ts_code.upper()]
if not m.empty:
return str(m.iloc[0]["ts_code"])
except Exception:
continue
return ts_code
class FutAnalysisRunner:
"""期货综合分析 Runner(主力连续合约为标的)。"""
PERIODS = (5, 20, 60, 120, 250)
DEFAULT_DIMENSIONS = ["overview", "trend", "holding", "mapping", "wsr", "settle", "risk"]
def __init__(self, ts_code: str, end_date: Optional[str] = None,
dimensions: Optional[List[str]] = None, api: Optional[DataAPI] = None):
self.api = api or DataAPI()
self.ts_code = _resolve_ts_code(ts_code, self.api)
self.end_date = end_date or _today()
self.dimensions = dimensions or self.DEFAULT_DIMENSIONS.copy()
self.symbol = self.ts_code.split(".")[0]
self.fut_name: Optional[str] = None
self.exchange: Optional[str] = None
self.main_contract: Optional[str] = None
self.results: Dict[str, DimensionResult] = {}
# ---------- 维度:概况 ----------
@safe_result("概况")
def analyze_overview(self) -> DimensionResult:
# 交易所(从ts_code后缀推断,用于get_fut_basic筛选)
suf = "." + self.ts_code.split(".")[-1]
ex_pair = EXCHANGE_MAP.get(suf)
self.exchange = ex_pair[0] if ex_pair else None
# 连续合约信息(传exchange精确匹配,否则fut_type=2全量可能不含本品种)
fb2 = self.api.get_fut_basic(exchange=self.exchange, fut_type="2") if self.exchange else self.api.get_fut_basic(fut_type="2")
cont_row = None
if fb2 is not None and not fb2.empty and "symbol" in fb2.columns:
m = fb2[fb2["symbol"] == self.symbol]
if not m.empty:
cont_row = m.iloc[0]
self.fut_name = cont_row.get("name") or self.symbol
# 当前主力合约
fm = self.api.get_fut_mapping(self.ts_code, shift_date(self.end_date, -60), self.end_date)
if fm is not None and not fm.empty and "mapping_ts_code" in fm.columns:
fm = fm.sort_values("trade_date")
self.main_contract = fm.iloc[-1]["mapping_ts_code"]
# 主力合约具体参数
cont_detail = None
if self.main_contract:
# fut_basic 需同时传 exchange(仅 ts_code 返回空)
tmp = self.api.get_fut_basic(ts_code=self.main_contract, exchange=self.exchange)
if tmp is not None and not tmp.empty:
cont_detail = tmp.iloc[0]
rows = [
{"项目": "品种", "内容": self.fut_name or self.symbol},
{"项目": "产品代码", "内容": self.symbol},
{"项目": "交易所", "内容": (ex_pair[1] if ex_pair else self.exchange or "未知") + f"({self.exchange or '未知'})"},
{"项目": "主力连续合约", "内容": self.ts_code},
{"项目": "当前主力合约", "内容": self.main_contract or "N/A"},
]
if cont_detail is not None:
# 字段名以实际接口为准:per_unit(每手)/trade_unit(计量单位)/quote_unit_desc(最小报价说明)
for k, label in [("per_unit", "交易单位(每手)"), ("trade_unit", "交易计量单位"),
("multiplier", "合约乘数(国债/指数期货)"), ("quote_unit_desc", "最小报价单位说明"),
("d_month", "交割月份"), ("last_ddate", "最后交割日")]:
v = cont_detail.get(k)
if v is not None and str(v) != "nan":
rows.append({"项目": label, "内容": v})
return DimensionResult.success("概况", data={"rows": rows, "main_contract": self.main_contract},
conclusion=f"主力连续合约 {self.ts_code}({self.fut_name or self.symbol}),当前主力 {self.main_contract or 'N/A'}。")
# ---------- 维度:行情趋势 ----------
@safe_result("行情趋势")
def analyze_trend(self) -> DimensionResult:
start = shift_date(self.end_date, -max(self.PERIODS) * 2)
daily = self.api.get_fut_daily(self.ts_code, start, self.end_date)
if daily is None or daily.empty:
return DimensionResult.empty("行情趋势", note="无法获取期货日线行情")
daily = daily.sort_values("trade_date").reset_index(drop=True)
if "close" not in daily.columns:
return DimensionResult.empty("行情趋势", note="日线无close字段")
daily = daily.dropna(subset=["close"])
s = daily.set_index("trade_date")["close"].sort_index()
if len(s) < 2:
return DimensionResult.insufficient_history("行情趋势", note="历史数据不足")
h = daily.set_index("trade_date")["high"].sort_index() if "high" in daily.columns else s
low = daily.set_index("trade_date")["low"].sort_index() if "low" in daily.columns else s
ret = calc_returns(s, periods=self.PERIODS)
vol = calc_volatility(s); mdd = calc_max_drawdown(s); sh = calc_sharpe(s)
ma = calc_ma(s); macd = calc_macd(s); rsi = calc_rsi(s)
kdj = calc_kdj(h, low, s); boll = calc_boll(s)
latest_close = float(s.iloc[-1])
# ⚠️ 最新结算价要先 dropna:最新交易日结算中时 settle 为 NaN,
# 直接取 iloc[-1] 会得到 NaN,经 _safe_float 变 None → 展示成"N/A"
_set = daily.dropna(subset=["settle"]) if "settle" in daily.columns else daily
latest_settle = _safe_float(_set.iloc[-1].get("settle")) if "settle" in daily.columns and not _set.empty else None
latest_oi = _safe_float(daily.iloc[-1].get("oi")) if "oi" in daily.columns else None
# ⚠️ SKILL.md:143 要求"结算价走势、日内振幅":行情趋势各指标基于收盘价
# (未复权),补上最新交易日日内振幅((high-low)/pre_close),口径在文案中说明。
_amp = None
if {"high", "low", "pre_close"}.issubset(daily.columns):
_last_row = daily.iloc[-1]
_pc = _safe_float(_last_row.get("pre_close"))
if _pc and _pc > 0:
_amp = round((float(_last_row["high"]) - float(_last_row["low"])) / _pc * 100, 2)
data = {"returns": ret, "latest_close": latest_close, "latest_settle": latest_settle,
"latest_oi": latest_oi, "intraday_amplitude_pct": _amp,
"volatility": vol, "max_drawdown": mdd, "sharpe": sh,
"ma": ma, "macd": macd, "rsi": rsi, "kdj": kdj, "boll": boll, "daily": daily,
"chart": {
"title": "主力连续合约日线(未复权)",
"type": "candlestick",
"dates": daily["trade_date"].tolist(),
"ohlc": daily[["open", "close", "low", "high"]].values.tolist(),
"vol": daily["vol"].tolist() if "vol" in daily.columns else [],
},
}
_r20 = ret.get("近20日涨幅%") if ret.get("近20日涨幅%") not in (None, "N/A") else "数据不足"
_r250 = ret.get("近250日涨幅%") if ret.get("近250日涨幅%") not in (None, "N/A") else "数据不足"
conclusion = (f"最新收盘 {latest_close},近20日 {_r20}%,"
f"近250日 {_r250}%,年化波动 {vol if vol is not None else '数据不足'}%,"
f"最大回撤 {mdd if mdd is not None else '数据不足'}%")
if _amp is not None:
conclusion += f",最新日内振幅 {_amp}%"
if latest_settle is not None:
conclusion += f",最新结算价 {latest_settle}"
conclusion += "。行情指标均基于收盘价(未复权),结算价另列。"
return DimensionResult.success("行情趋势", conclusion=conclusion, data=data)
# ---------- 维度:持仓分析 ----------
@safe_result("持仓分析")
def analyze_holding(self) -> DimensionResult:
suf = "." + self.ts_code.split(".")[-1]
covered = suf in HOLDING_COVERED
# fut_holding 对连续合约通常无数据,尝试主力合约
holding_df = None
if self.main_contract:
holding_df = self.api.get_fut_holding(self.main_contract, shift_date(self.end_date, -20), self.end_date)
if (holding_df is None or holding_df.empty):
# ⚠️ 状态必须如实标注:拿不到持仓排名数据就是 EMPTY(含降级产物),
# 不能再返回 success——否则风险节"数据说明"(status != SUCCESS)永不触发。
# fut_holding 现在按 symbol 查询(服务端 schema 是 symbol 非 ts_code,见 data_api),
# DCE 品种应能取到数据;取不到多数是该品种确实无持仓排名。
note = (f"fut_holding 持仓排名接口仅覆盖大商所(DCE),{EXCHANGE_MAP.get(suf,(None,'该交易所'))[1]}无持仓排名数据"
if not covered else "持仓排名数据暂缺(主力合约较新或接口未更新),已降级为持仓量(oi)序列")
# 退而求其次:从日线取持仓量(oi)序列
daily = self.api.get_fut_daily(self.ts_code, shift_date(self.end_date, -60), self.end_date)
oi_series = None
if daily is not None and not daily.empty and "oi" in daily.columns:
d = daily.sort_values("trade_date").dropna(subset=["oi"])
if not d.empty:
oi_series = d.set_index("trade_date")["oi"].tail(30)
# 量仓比(成交量/持仓量)与近5日持仓变化
vr_latest = oi_chg5 = None
if daily is not None and not daily.empty and "oi" in daily.columns and "vol" in daily.columns:
d2 = daily.sort_values("trade_date").dropna(subset=["oi"])
if len(d2) >= 6:
_last = d2.iloc[-1]
vr_latest = round(float(_last["vol"] / _last["oi"]), 4) if _last["oi"] else None
oi_chg5 = round((float(_last["oi"]) / float(d2.iloc[-6]["oi"]) - 1) * 100, 2) if d2.iloc[-6]["oi"] else None
_vr_parts = []
if oi_chg5 is not None:
_vr_parts.append(f"近5日持仓量变化 {oi_chg5:+.2f}%")
if vr_latest is not None:
_vr_parts.append(f"最新量仓比(成交量/持仓量) {vr_latest}")
_vr_txt = ("。" + ",".join(_vr_parts)) if _vr_parts else ""
note = note.rstrip("。") + _vr_txt + ("。" if _vr_txt else "")
return DimensionResult(
status=ResultStatus.EMPTY, title="持仓分析", conclusion=note, note=note,
data={"holding_records": None, "oi_series": (oi_series.tail(10).to_dict() if oi_series is not None else None),
"vr_latest": vr_latest, "oi_chg5": oi_chg5},
)
holding_df = holding_df.sort_values("trade_date") if "trade_date" in holding_df.columns else holding_df
data = {"holding_records": holding_df.tail(20).to_dict("records"), "covered_exchange": True}
# ⚠️ SKILL.md:144 要求"前20会员多空持仓排名与多空比"——此前只 dump 原始行,
# 从未聚合出多空比。fut_holding 是"每会员每日持仓排名"(前 N 会员),
# 取最新交易日合计多/空持仓,计算多空比与多单前5会员集中度。
long_short_ratio = None
holding_date = None
top_long_brokers = []
top_long_share_pct = None
_hl = ("long_hld" in holding_df.columns and "short_hld" in holding_df.columns
and "broker" in holding_df.columns)
if _hl:
lr = holding_df.dropna(subset=["long_hld", "short_hld"])
if not lr.empty:
holding_date = lr["trade_date"].max()
lr_latest = lr[lr["trade_date"] == holding_date].sort_values("long_hld", ascending=False)
long_total = float(pd.to_numeric(lr_latest["long_hld"], errors="coerce").sum())
short_total = float(pd.to_numeric(lr_latest["short_hld"], errors="coerce").sum())
if long_total > 0 and short_total > 0:
long_short_ratio = round(long_total / short_total, 2)
data["holding_date"] = holding_date
data["long_total"] = long_total
data["short_total"] = short_total
data["long_short_ratio"] = long_short_ratio
if long_total > 0:
top_long_brokers = [
{"broker": r.get("broker"), "long_hld": _safe_float(r.get("long_hld")),
"short_hld": _safe_float(r.get("short_hld"))}
for _, r in lr_latest.head(5).iterrows()
]
data["top_long_brokers"] = top_long_brokers
top_long_share_pct = round(sum(b["long_hld"] for b in top_long_brokers if b["long_hld"]) / long_total * 100, 1) if long_total else None
data["top_long_share_pct"] = top_long_share_pct
conclusion = f"持仓排名数据 {len(holding_df)} 条({EXCHANGE_MAP.get(suf,(None,''))[1]})。"
if long_short_ratio is not None:
conclusion += (f" 最新交易日 {holding_date} 前{len(lr_latest)}会员多空比 {long_short_ratio}"
f"(多单 {data['long_total']:.0f} / 空单 {data['short_total']:.0f})。")
if top_long_share_pct is not None:
_top_txt = "、".join(f"{b['broker']}(多单 {b['long_hld']:.0f})" for b in top_long_brokers[:3])
conclusion += f" 多单前3会员占比 {top_long_share_pct}%({_top_txt})。"
return DimensionResult.success("持仓分析", conclusion=conclusion, data=data)
# ---------- 维度:主力合约 ----------
@safe_result("主力合约")
def analyze_mapping(self) -> DimensionResult:
fm = self.api.get_fut_mapping(self.ts_code, shift_date(self.end_date, -max(self.PERIODS) * 2), self.end_date)
if fm is None or fm.empty:
return DimensionResult.empty("主力合约", note="无法获取主力合约映射数据")
fm = fm.sort_values("trade_date")
changes = fm[["trade_date", "mapping_ts_code"]].drop_duplicates("mapping_ts_code", keep="last").sort_values("trade_date")
data = {"changes": changes.tail(8).to_dict("records"), "current_main": self.main_contract}
conclusion = f"当前主力合约 {self.main_contract},近{len(changes)}期换月记录。基差(现货-期货)需现货价,Tushare无现货接口,暂缺。"
return DimensionResult.success("主力合约", conclusion=conclusion, data=data)
# ---------- 维度:仓单库存 ----------
@safe_result("仓单库存")
def analyze_wsr(self) -> DimensionResult:
# ⚠️ 改用区间取数(get_fut_wsr_range,实测可用):原实现按自然日每 7 天
# 单日调用 13 次,非交易日返回空被静默丢弃,"近 N 期"的 N 随样本浮动。
# 区间一次取数后按交易日采样,N 稳定且数据完整。
end_d = datetime.strptime(min(self.end_date, self.api._t_minus_1), "%Y%m%d")
start_d = (end_d - timedelta(days=90)).strftime("%Y%m%d")
w = self.api.get_fut_wsr_range(self.symbol, start_d, end_d.strftime("%Y%m%d"))
rows = []
if w is not None and not w.empty and {"trade_date", "vol"}.issubset(w.columns):
# 保险:服务端可能忽略 symbol 参数,本地再按产品代码过滤
if "symbol" in w.columns:
w = w[w["symbol"].astype(str) == self.symbol]
if w.empty:
return DimensionResult.empty("仓单库存", note=f"无 {self.symbol} 仓单数据")
daily = w.groupby("trade_date", sort=False)["vol"].sum().reset_index()
daily = daily.sort_values("trade_date")
# 交易日采样(约每 5 个交易日一条,保持"近 N 期"的均匀性)。
# ⚠️ iloc[::5] 从首行起采样,尾部不足 5 行的交易日会被丢弃,
# 导致"最新仓单"实际落后数个交易日(实测 RB 报告 20260928、实际 20260930;
# JM 报告 20260916、实际 20260922)。采样后强制补上真正的最后一条。
_sampled = daily.iloc[::5]
if _sampled.iloc[-1]["trade_date"] != daily.iloc[-1]["trade_date"]:
_sampled = pd.concat([_sampled, daily.tail(1)], ignore_index=True)
daily = _sampled.sort_values("trade_date")
for _, r in daily.iterrows():
_sub = w[w["trade_date"] == r["trade_date"]]
_unit = str(_sub.iloc[0].get("unit")) if "unit" in _sub.columns else None
rows.append({"trade_date": r["trade_date"], "覆盖仓库数": int(_sub["warehouse"].nunique()) if "warehouse" in _sub.columns else len(_sub),
"vol": int(r["vol"]), "unit": _unit})
if not rows:
return DimensionResult.empty("仓单库存", note="无法获取仓单数据")
wdf = pd.DataFrame(rows).sort_values("trade_date")
chg = int(wdf["vol"].iloc[-1]) - int(wdf["vol"].iloc[0])
# 合规:只陈述可交割量的增减,不下"偏空/偏多"的方向性判断
trend = "增加(可交割量上升)" if chg > 0 else "减少(可交割量下降)" if chg < 0 else "稳定"
data = {"wsr_series": wdf.to_dict("records"), "chg": chg, "trend": trend}
latest_vol = wdf["vol"].iloc[-1]
_unit = (wdf["unit"].dropna().iloc[-1] if "unit" in wdf.columns and not wdf["unit"].dropna().empty else "张")
conclusion = f"最新仓单 {latest_vol} {_unit},近{len(wdf)}期变化 {chg:+d} {_unit},{trend}。"
return DimensionResult.success("仓单库存", conclusion=conclusion, data=data)
# ---------- 维度:结算参数 ----------
@safe_result("结算参数")
def analyze_settle(self) -> DimensionResult:
# fut_settle 对连续合约通常返回空,优先用主力合约
code = self.main_contract or self.ts_code
fs = self.api.get_fut_settle(code, shift_date(self.end_date, -30), self.end_date)
if fs is not None and not fs.empty:
if "settle" in fs.columns:
fs = fs.sort_values("trade_date").dropna(subset=["settle"])
# ⚠️ 空表兜底:最新交易日结算中时 settle 全为 NaN,dropna 后为空表,
# 直接 iloc[-1] 会抛 IndexError 并把内部异常文本当报告正文展示
if fs.empty:
fs = None
if fs is not None and not fs.empty:
_lmr = _safe_float(fs.iloc[-1].get("long_margin_rate")) if "long_margin_rate" in fs.columns else None
data = {"settle_records": fs.tail(5).to_dict("records"), "source": "fut_settle", "latest_margin_rate": _lmr}
conclusion = f"结算参数来自 fut_settle({code}),最新 {len(fs)} 条。"
return DimensionResult.success("结算参数", conclusion=conclusion, data=data)
# 降级:从日线取结算价(连续合约通常无 fut_settle 结算参数)
daily = self.api.get_fut_daily(self.ts_code, shift_date(self.end_date, -10), self.end_date)
latest_settle = None
latest_delv_settle = None
if daily is not None and not daily.empty:
if "settle" in daily.columns:
d = daily.sort_values("trade_date").dropna(subset=["settle"])
if not d.empty:
latest_settle = _safe_float(d.iloc[-1]["settle"])
# 交割结算价(SKILL.md:147 要求输出;fut_daily 含 delv_settle 列)
if "delv_settle" in daily.columns:
_dd = daily.sort_values("trade_date").dropna(subset=["delv_settle"])
if not _dd.empty:
latest_delv_settle = _safe_float(_dd.iloc[-1]["delv_settle"])
if latest_settle is None:
trend = self.results.get("trend")
if trend and trend.is_ok() and trend.data:
latest_settle = trend.data.get("latest_settle")
data = {"latest_settle": latest_settle, "latest_delv_settle": latest_delv_settle, "source": "fut_daily(降级)"}
# 不直显 "N/A":给出可解释的缺失文案
_settle_txt = f"最新结算 {latest_settle}" if latest_settle is not None else "最新结算价暂缺(最新交易日结算中或数据未更新)"
conclusion = f"fut_settle 对连续/主力合约无数据,结算价取自 fut_daily:{_settle_txt}。保证金率等参数暂缺。"
if latest_delv_settle is not None:
conclusion += f" 最新交割结算价 {latest_delv_settle}。"
return DimensionResult.success("结算参数", data=data, conclusion=conclusion)
# ---------- 维度:风险提示 ----------
@safe_result("风险提示")
def analyze_risk(self) -> DimensionResult:
risks = []
trend = self.results.get("trend")
if trend and trend.is_ok() and trend.data:
vol = trend.data.get("volatility"); mdd = trend.data.get("max_drawdown")
rsi = trend.data.get("rsi", {})
if isinstance(vol, (int, float)):
risks.append(f"年化波动率 {vol}%")
if isinstance(mdd, (int, float)):
risks.append(f"最大回撤 {mdd}%")
rsi_v = rsi.get("RSI")
if isinstance(rsi_v, (int, float)):
if rsi_v > 70:
risks.append(f"RSI {rsi_v}(高于 70)")
elif rsi_v < 30:
risks.append(f"RSI {rsi_v}(低于 30)")
_settle_res = self.results.get("settle")
_mr_v = self._f((_settle_res.data or {}).get("latest_margin_rate")) if _settle_res and _settle_res.is_ok() else None
risks.append("期货为保证金交易" + (f"(最新保证金率 {_mr_v*100:.0f}%,名义杠杆约 {1/_mr_v:.1f} 倍)" if _mr_v and _mr_v > 0 else ",盈亏随杠杆同步放大") + ",交易制度上实行每日无负债结算")
risks.append("主力连续合约有换月跳空,技术指标可能失真")
# 数据缺失
notes = []
holding = self.results.get("holding")
if holding and holding.status != ResultStatus.SUCCESS:
notes.append(f"持仓分析:{holding.note or '数据缺失'}")
settle = self.results.get("settle")
if settle and settle.is_ok() and settle.data and settle.data.get("source", "").startswith("fut_daily"):
notes.append("结算参数:fut_settle 无连续合约数据,保证金率等暂缺")
notes.append("主力合约:基差需现货价,Tushare无现货接口")
if not risks:
risks.append("未列示额外风险指标")
return DimensionResult.success("风险提示", data={"risks": risks, "notes": notes}, risks=risks)
# ---------- 执行入口 ----------
def run(self) -> Dict[str, Any]:
self.results = {}
if "overview" in self.dimensions:
self.results["overview"] = self.analyze_overview()
if "trend" in self.dimensions:
self.results["trend"] = self.analyze_trend() # trend 先跑,供 settle 降级复用
parallel_dims = [d for d in self.dimensions if d not in ("overview", "trend", "risk")]
dim_methods = {"holding": self.analyze_holding, "mapping": self.analyze_mapping,
"wsr": self.analyze_wsr, "settle": self.analyze_settle}
to_run = {d: dim_methods[d] for d in parallel_dims if d in dim_methods}
if to_run:
max_workers = min(4, len(to_run))
with ThreadPoolExecutor(max_workers=max_workers) as executor:
futures = {executor.submit(method): d for d, method in to_run.items()}
for future in as_completed(futures):
d = futures[future]
self.results[d] = future.result()
if "risk" in self.dimensions:
self.results["risk"] = self.analyze_risk()
return {"ts_code": self.ts_code, "name": self.fut_name, "symbol": self.symbol,
"end_date": self.end_date, "dimensions": {k: v.to_dict() for k, v in self.results.items()}}
# ---------- 报告渲染 ----------
DIM_TITLES = {"overview": "概况", "trend": "行情趋势", "holding": "持仓分析",
"mapping": "主力合约", "wsr": "仓单库存", "settle": "结算参数", "risk": "风险提示"}
# 各维度含义描述(面向非专业读者,标题后以引用块呈现)
DIM_DESCRIPTIONS = {
"overview": "合约基础档案:品种、交易所、主力合约与乘数等参数。",
"trend": "价格走势:结算价/收盘价区间涨跌幅、波动率、回撤与技术指标读数。",
"holding": "持仓数据:前20会员多空持仓排名或持仓量序列。",
"mapping": "主力合约:当前成交量最大的具体合约及换月记录。",
"wsr": "仓单库存:注册仓单量变化(可交割量增减的统计读数)。",
"settle": "结算参数:每日结算价与保证金相关参数。",
"risk": "风险指标:列示可复核的风险指标读数,不做综合评级。",
}
def _fmt(self, x, digits=2):
if x is None:
return "N/A"
try:
if isinstance(x, float) and (x != x or x == float("inf") or x == float("-inf")):
return "N/A"
except Exception:
return "N/A"
if isinstance(x, (int, np.integer)):
return f"{int(x):,}"
if isinstance(x, (float, np.floating)):
return f"{x:,.{digits}f}"
return str(x)
def _f(self, x):
if x is None or x == "N/A":
return None
try:
v = float(x)
return None if (v != v or v == float("inf") or v == float("-inf")) else v
except Exception:
return None
def _md(self, df):
if df is None or df.empty:
return ""
df = df.copy().dropna(axis=1, how="all")
for col in df.columns:
if df[col].dtype.kind in "iufc":
df[col] = df[col].apply(lambda x: self._fmt(x))
else: # 兜底:pandas 3.x 新 str dtype 不属于 object,也需清洗 NaN
df[col] = df[col].apply(lambda x: self._fmt(x) if isinstance(x, (int, float, np.integer, np.floating))
else ("N/A" if x is None or (isinstance(x, float) and x != x) else str(x)))
try:
return df_to_md_table(df)
except Exception:
return df.to_string(index=False)
def report(self) -> str:
if not self.results:
self.run()
name = self.fut_name or self.symbol
_dts = self.results.get("trend")
_ds = _dts.data.get("chart", {}).get("dates") if (_dts and _dts.is_ok() and _dts.data) else None
lines = [f"# {name} 全景研究报告", "",
f"> 数据日期:{_ds[-1] if _ds else self.end_date}(Tushare 数据为 T-1 日,即最新已发布数据)", "",
"> 合规说明:本报告仅展示 T-1 历史数据的统计结果,不含证券估值意见、投资评级、目标价、买卖建议或收益预测,不构成投资建议或投资顾问服务;未经人工分析师审核,不得作为对外发布的证券研究报告使用。", ""]
dim_order = [d for d in self.dimensions if d in self.results]
risk_dim = "risk" if "risk" in dim_order else None
ordered = [d for d in dim_order if d != "risk"]
idx = 0
for dim in ordered:
idx += 1
res = self.results[dim]
title = self.DIM_TITLES.get(dim, res.title)
lines.append(f"## {idx}. {title}")
desc = self.DIM_DESCRIPTIONS.get(dim)
if desc:
lines.append(f"> {desc}")
if res.conclusion:
lines.append(res.conclusion)
if res.is_ok() and res.data:
lines.extend(self._render_dimension(res))
elif res.note:
lines.append(f"- {res.note}")
lines.append("")
if risk_dim:
idx += 1
res = self.results[risk_dim]
lines.append(f"## {idx}. 风险提示")
risk_desc = self.DIM_DESCRIPTIONS.get("risk")
if risk_desc:
lines.append(f"> {risk_desc}")
if res.is_ok() and res.data:
for r in res.data.get("risks", []):
lines.append(f"- {r}")
notes = res.data.get("notes", [])
if notes:
lines.append("")
lines.append("**数据说明**:")
for n in notes:
lines.append(f"- {n}")
lines.append("")
idx += 1
lines.append(f"## {idx}. 指标摘要")
lines.append(self._overall_evaluation())
lines.append("")
lines.append("---")
lines.append("*本报告由程序基于山西证券 Tushare 平台的 T-1 历史数据自动生成,仅作数据统计与展示:不含证券估值意见、投资评级、目标价、买卖建议或收益预测,不构成任何投资建议、投资顾问服务或要约。报告未经人工分析师审核,不得作为对外发布的证券研究报告使用。*")
return "\n".join(lines)
def _render_dimension(self, res) -> list:
lines = []
data = res.data or {}
if res.title == "概况":
rows = data.get("rows", [])
if rows:
lines.append(self._md(pd.DataFrame(rows)))
elif res.title == "行情趋势":
ret = data.get("returns", {})
ret_rows = [{"区间": k, "涨幅%": v} for k, v in ret.items() if k.startswith("近")]
if ret_rows:
lines.append(self._md(pd.DataFrame(ret_rows)))
lines.append("")
lines.append(self._md(pd.DataFrame([
{"指标": "最新收盘", "数值": self._fmt(data.get("latest_close"))},
{"指标": "最新结算价", "数值": self._fmt(data.get("latest_settle"))},
{"指标": "最新持仓量(手)", "数值": self._fmt(data.get("latest_oi"))},
{"指标": "年化波动率%", "数值": self._fmt(data.get("volatility"))},
{"指标": "最大回撤%", "数值": self._fmt(data.get("max_drawdown"))},
{"指标": "夏普比率", "数值": self._fmt(data.get("sharpe"))},
])))
ma = data.get("ma", {})
tech = [{"技术指标": "MACD", "信号": (data.get("macd") or {}).get("signal", "N/A")},
{"技术指标": "RSI", "信号": (data.get("rsi") or {}).get("RSI", "N/A")},
{"技术指标": "KDJ", "信号": (data.get("kdj") or {}).get("signal", "N/A")},
{"技术指标": "布林带", "信号": (data.get("boll") or {}).get("position", "N/A")}]
if ma:
tech.append({"技术指标": "均线", "信号": f"MA5={self._fmt(ma.get('MA5'))},MA20={self._fmt(ma.get('MA20'))},MA60={self._fmt(ma.get('MA60'))}"})
lines.append("")
lines.append(self._md(pd.DataFrame(tech)))
lines.append("")
lines.append("**指标说明**:主力连续合约拼接各时期主力,换月跳空会影响技术指标的连续性。RSI 高于70/低于30为常见的技术状态读数。")
elif res.title == "持仓分析":
if res.status == ResultStatus.SUCCESS and data.get("holding_records"):
# 精选列并中文标注:原始行含 vol_chg/long_chg 等大量 NaN 字段,
# 直接 dump 会产生整排 N/A(不是"无数据",是这些变动字段服务端未披露)
_hr = data.get("holding_records", [])
_rows = [{"交易日": r.get("trade_date"), "会员": r.get("broker"),
"成交量(手)": self._fmt(r.get("vol")),
"多单持仓(手)": self._fmt(r.get("long_hld")),
"空单持仓(手)": self._fmt(r.get("short_hld"))} for r in _hr[:10]]
lines.append(self._md(pd.DataFrame(_rows)))
lines.append("")
lines.append("**指标说明**:多空比为最新交易日多头持仓合计 / 空头持仓合计。")
else:
oi = data.get("oi_series")
if oi:
lines.append(self._md(pd.DataFrame([{"trade_date": k, "持仓量(手)": int(v)} for k, v in oi.items()])))
lines.append("")
lines.append("**指标说明**:持仓量(oi)为未平仓合约数量。")
elif res.title == "主力合约":
ch = data.get("changes", [])
if ch:
lines.append(self._md(pd.DataFrame(ch)))
lines.append("")
lines.append("**指标说明**:主力合约为当前成交量最大的具体合约,定期换月。基差 = 现货价 − 期货价;本数据源无现货价,基差暂缺。")
elif res.title == "仓单库存":
ws = data.get("wsr_series", [])
if ws:
_ws_df = pd.DataFrame(ws).rename(columns={"trade_date": "日期", "vol": "仓单量(张)"})
lines.append(self._md(_ws_df))
lines.append("")
lines.append(f"**指标说明**:注册仓单量{data.get('trend','')}。仓单为可交割库存的统计读数。")
elif res.title == "结算参数":
src = data.get("source", "")
if src.startswith("fut_settle"):
rec = data.get("settle_records", [])
if rec:
# ⚠️ 保证金率是小数(如 0.07=7%),表格与正文必须统一展示为百分比,
# 旧实现表格原样显示 0.07、正文却说 7%,自相矛盾。
def _rate_pct(v):
_f = _safe_float(v)
return f"{_f * 100:.2f}%" if _f is not None and 0 < _f < 1 else self._fmt(v)
_recs = [{"日期": r.get("trade_date"), "结算价": self._fmt(r.get("settle")),
"多头保证金率": _rate_pct(r.get("long_margin_rate")),
"空头保证金率": _rate_pct(r.get("short_margin_rate"))} for r in rec]
lines.append(self._md(pd.DataFrame(_recs)))
_mr = _safe_float(rec[-1].get("long_margin_rate")) if "long_margin_rate" in rec[-1] else None
if _mr and _mr > 0:
lines.append("")
lines.append(f"最新保证金率 {_mr*100:.0f}% → 名义杠杆约 {1/_mr:.1f} 倍(保证金交易,盈亏同步放大)。")
lines.append("")
lines.append("**指标说明**:结算价为每日无负债结算的基准价;保证金率以交易所公告为准,连续合约暂以日线结算价近似。")
return [l for l in lines if l is not None]
def _overall_evaluation(self) -> str:
trend = self.results.get("trend")
wsr = self.results.get("wsr")
t_ok = trend and trend.is_ok() and trend.data
w_ok = wsr and wsr.is_ok() and wsr.data
name = self.fut_name or self.symbol
lines = [f"**指标摘要**:{name} 各维度原始读数如下。"]
pts = []
if t_ok:
ret = trend.data.get("returns", {})
pts.append(f"- **趋势**:近5日 {ret.get('近5日涨幅%','N/A')}%,近20日 {ret.get('近20日涨幅%','N/A')}%,近250日 {ret.get('近250日涨幅%','N/A')}%")
pts.append(f"- **波动**:年化波动 {self._fmt(trend.data.get('volatility'))}%,最大回撤 {self._fmt(trend.data.get('max_drawdown'))}%,夏普 {self._fmt(trend.data.get('sharpe'))}")
pts.append(f"- **技术**:MACD {(trend.data.get('macd') or {}).get('signal','N/A')},RSI {self._fmt((trend.data.get('rsi') or {}).get('RSI'))},KDJ {(trend.data.get('kdj') or {}).get('signal','N/A')}")
if w_ok:
_ws = wsr.data.get("wsr_series") or []
_latest_ws_vol = _ws[-1].get("vol", "N/A") if _ws else "N/A"
_ws_unit = (_ws[-1].get("unit") or "张") if _ws else "张"
pts.append(f"- **仓单**:最新 {_latest_ws_vol} {_ws_unit},{wsr.data.get('trend','')}")
# 数据口径按实际状态描述:持仓维度成功/降级/未覆盖要区分,不再硬编码"已降级"
_holding = self.results.get("holding")
if _holding is not None and _holding.is_ok() and _holding.data and _holding.data.get("holding_records"):
_hd_txt = "持仓排名已取到(前20会员多空持仓)"
elif _holding is not None and _holding.data and _holding.data.get("oi_series"):
_hd_txt = "持仓排名缺失,已降级为持仓量(oi)序列"
else:
_hd_txt = "持仓排名接口仅覆盖大商所(DCE),本品种无持仓排名数据"
pts.append(f"- **数据口径**:{_hd_txt};基差需现货价(本数据源无现货接口);结算参数取自当前主力具体合约")
lines.extend(pts)
lines.append("")
lines.append("以上均为 T-1 历史数据的统计描述,不含估值意见、投资评级、目标价、买卖建议或收益预测。")
return "\n".join(lines)
# ---------- 便捷函数 ----------
def analyze_futures(ts_code: str, end_date: Optional[str] = None,
dimensions: Optional[List[str]] = None) -> Dict[str, Any]:
runner = FutAnalysisRunner(ts_code=ts_code, end_date=end_date, dimensions=dimensions)
return runner.run()
def fut_report(ts_code: str, end_date: Optional[str] = None,
dimensions: Optional[List[str]] = None) -> str:
runner = FutAnalysisRunner(ts_code=ts_code, end_date=end_date, dimensions=dimensions)
md = runner.report()
return render_html_report(md, runner.results)
if __name__ == "__main__":
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8")
import argparse
parser = argparse.ArgumentParser(description="期货综合分析 Runner(主力连续合约)")
parser.add_argument("ts_code", help="主力连续合约代码,如 SR.ZCE / RB.SHF / JM.DCE,或纯symbol如 SR")
parser.add_argument("--end-date", default=None, help="分析截止日期 YYYYMMDD")
parser.add_argument(
"--output",
default=None,
help="HTML 报告输出路径,默认保存到当前目录 {ts_code}_report.html",
)
args = parser.parse_args()
try:
report = fut_report(args.ts_code, args.end_date)
except RuntimeError as exc: # token 文件缺失/无效等环境问题,给可操作提示而非 traceback
print(f"错误:{exc}", file=sys.stderr)
sys.exit(1)
output = args.output or f"{args.ts_code}_report.html"
with open(output, "w", encoding="utf-8") as f:
f.write(report)
print(f"HTML 报告已保存: {os.path.abspath(output)}")
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |