Skip to content

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 不应同时激活——分析已包含数据。

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)}")
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall