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/index_analysis_runner.py

View on GitHub
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
指数综合分析 Runner。

维度:
1. 概况
2. 行情趋势
3. 估值分析
4. 成分权重
5. 行业分布
6. 国际对比
7. 风险提示
"""

import os
import sys
import threading
from concurrent.futures import ThreadPoolExecutor, as_completed
from datetime import datetime
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 factor_signals import calc_amplitude_momentum, calc_quantitative_momentum
from result_model import DimensionResult, ResultStatus, safe_result
from report_html import df_to_md_table, render_html_report


# index_weight 是月度数据且被"成分权重""行业分布"两个维度并行消费;
# 进程级缓存避免同一份报告里重复取数(审计发现每次多调一次接口)。
_INDEX_WEIGHT_CACHE: Dict[tuple, Optional[pd.DataFrame]] = {}
_INDEX_WEIGHT_LOCK = threading.Lock()


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


class IndexAnalysisRunner:
    """指数综合分析 Runner。"""

    PERIODS = (5, 20, 60, 120, 250)
    DEFAULT_DIMENSIONS = ["overview", "trend", "valuation", "weight", "sector", "global", "margin", "momentum_quality", "risk"]

    def __init__(
        self,
        ts_code: str,
        end_date: Optional[str] = None,
        dimensions: Optional[List[str]] = None,
        api: Optional[DataAPI] = None,
    ):
        self.ts_code = ts_code
        self.end_date = end_date or _today()
        self.dimensions = dimensions or self.DEFAULT_DIMENSIONS.copy()
        self.api = api or DataAPI()

        self.index_name: Optional[str] = None
        self.results: Dict[str, DimensionResult] = {}

    # ---------- 维度:概况 ----------

    @safe_result("概况")
    def analyze_overview(self) -> DimensionResult:
        df = self.api.get_index_basic(self.ts_code)
        if df is None or df.empty:
            return DimensionResult.empty("概况", note="无法获取指数基础信息")

        row = df.iloc[0]
        self.index_name = row.get("name")
        data = {
            "ts_code": self.ts_code,
            "name": self.index_name,
            "publisher": row.get("publisher"),
            "category": row.get("category"),
            "base_date": row.get("base_date"),
            "base_point": row.get("base_point"),
            "list_date": row.get("list_date"),
        }
        return DimensionResult.success("概况", data=data)

    # ---------- 维度:行情趋势 ----------

    @safe_result("行情趋势")
    def analyze_trend(self) -> DimensionResult:
        start = shift_date(self.end_date, -max(self.PERIODS) * 2)
        df = self.api.get_index_daily(self.ts_code, start, self.end_date)
        if df is None or df.empty:
            return DimensionResult.empty("行情趋势", note="无法获取指数行情")

        series = df.set_index("trade_date")["close"].sort_index()
        if len(series) < 2:
            return DimensionResult.insufficient_history("行情趋势", note="历史数据不足")

        returns = calc_returns(series, periods=self.PERIODS)
        ma = calc_ma(series)
        volatility = calc_volatility(series)
        max_dd = calc_max_drawdown(series)
        sharpe = calc_sharpe(series)

        # 基准对比:沪深300
        bench_code = "000300.SH"
        bench_data = None
        if bench_code != self.ts_code:
            df_bench = self.api.get_index_daily(bench_code, start, self.end_date)
            if df_bench is not None and not df_bench.empty:
                bench_series = df_bench.set_index("trade_date")["close"].sort_index()
                bench_returns = calc_returns(bench_series, periods=self.PERIODS)
                bench_vol = calc_volatility(bench_series)
                bench_mdd = calc_max_drawdown(bench_series)
                bench_sharpe = calc_sharpe(bench_series)
                bench_data = {
                    "ts_code": bench_code,
                    "returns": bench_returns,
                    "volatility": bench_vol,
                    "max_drawdown": bench_mdd,
                    "sharpe": bench_sharpe,
                }

        conclusion = "近20日涨幅 " + (f"{returns.get('近20日涨幅%')}%" if returns.get('近20日涨幅%') not in (None, "N/A") else "数据不足")
        conclusion += f",年化波动 {volatility if volatility is not None else '数据不足'}%,最大回撤 {max_dd if max_dd is not None else '数据不足'}%"
        data = {
            "returns": returns,
            "ma": ma,
            "volatility": volatility,
            "max_drawdown": max_dd,
            "sharpe": sharpe,
            "benchmark": bench_data,
            "chart": {
                "title": "指数日线收盘",
                "type": "line",
                "dates": [str(d) for d in series.index.tolist()],
                "series": [{"name": self.index_name or self.ts_code, "data": series.tolist()}],
            },
        }
        return DimensionResult.success("行情趋势", conclusion=conclusion, data=data)

    # ---------- 维度:估值 ----------

    @safe_result("估值分析")
    def analyze_valuation(self) -> DimensionResult:
        # 取近 5 年估值序列。⚠️ 注意:shift_date 是自然日,5 年 = 365*5 自然日;
        # 旧实现写 -250*5 会只取到约 3.4 年(1250 自然日 ≈ 856 交易日),
        # "近5年"分位实际是"近3年多"的分位。不足时按实际返回量降级标注。
        start = shift_date(self.end_date, -365 * 5)
        df = self.api.get_index_dailybasic(self.ts_code, start, self.end_date)
        if df is None or df.empty:
            # ⚠️ SKILL.md:115:index_dailybasic 不覆盖的指数(实测 科创100 000698.SH 为空)
            # 降级为成分股 daily_basic 聚合估算(截面中位数 + 历史分位),并标注数据源;
            # 不再直接判 empty(旧注释"不做聚合估算"与 SKILL 要求相悖)。
            return self._valuation_from_constituents(start)

        df = df.sort_values("trade_date").reset_index(drop=True)
        latest = df.iloc[-1]
        # ⚠️ PE 取 TTM 口径:SKILL 要求 PE(TTM);服务端返回 pe(静态)与 pe_ttm 两列,
        # 优先 pe_ttm,缺时才回退静态 pe(与股票 runner 的估值口径一致)
        pe_raw = _safe_float(latest.get("pe_ttm")) or _safe_float(latest.get("pe"))
        pe = round(pe_raw, 2) if pe_raw is not None else None
        pb_raw = _safe_float(latest.get("pb"))
        pb = round(pb_raw, 2) if pb_raw is not None else None
        total_mv = _safe_float(latest.get("total_mv"))
        total_mv_yi = round(total_mv / 1e8, 0) if total_mv is not None else None  # index_dailybasic.total_mv 单位为元
        hist_count = len(df)

        # 历史分位需 ≥250 日数据才统计可靠;不足则置 None 并标注
        pe_hist = None
        pb_hist = None
        if hist_count >= 250:
            if pe is not None:
                pe_hist = round((df["pe_ttm"].fillna(df["pe"]) < pe).sum() / len(df) * 100, 1) if "pe_ttm" in df.columns else None
                if pe_hist is None:
                    pe_hist = round((df["pe"] < pe).sum() / len(df) * 100, 1)
            if pb is not None:
                pb_hist = round((df["pb"] < pb).sum() / len(df) * 100, 1)
        hist_note = f"(数据不足,仅 {hist_count} 日)" if hist_count < 250 else ""

        data = {"pe": pe, "pb": pb, "total_mv_yi": total_mv_yi, "pe_hist_percentile": pe_hist, "pb_hist_percentile": pb_hist, "hist_sample_days": hist_count}
        data["chart"] = {
            "title": "近5年 PE/PB 走势",
            "type": "line",
            "dates": df["trade_date"].tolist(),
            "series": [
                {"name": "PE", "yAxisIndex": 0, "data": (df["pe_ttm"].fillna(df["pe"]) if "pe_ttm" in df.columns else df["pe"]).tolist()},
                {"name": "PB", "yAxisIndex": 1, "data": df["pb"].tolist()},
            ],
        }
        # 不直显 "N/A":无值时分位给出原因(数据不足/无 PE),PE/PB 本身缺失时给出明确口径
        conclusion = f"PE(TTM) {pe if pe is not None else '数据缺失'}"
        conclusion += f",PB {pb if pb is not None else '数据缺失'}"
        if pe_hist is not None:
            conclusion += f",PE近5年历史分位 {pe_hist}%"
        elif pe is not None and hist_count < 250:
            conclusion += f",PE近5年历史分位{hist_note}"
        if pb_hist is not None:
            conclusion += f",PB近5年历史分位 {pb_hist}%"
        elif pb is not None and hist_count < 250:
            conclusion += f",PB近5年历史分位{hist_note}"
        return DimensionResult.success("估值分析", conclusion=conclusion, data=data)

    def _valuation_from_constituents(self, start: str) -> DimensionResult:
        """成分股聚合估值(SKILL.md:115 降级路径,仅当 index_dailybasic 未覆盖时触发)。

        index_weight 取最新一期成分(前 20 大权重股控制取数成本)→ 并行拉 daily_basic
        (含 pe_ttm/pb 历史)→ 逐日截面中位数 → 当前中位数的历史分位。
        数据源必须标注"成分股聚合估算",与官方指数级估值区分。
        """
        import concurrent.futures
        end = self.end_date
        iw = self.api.get_index_weight(self.ts_code, shift_date(end, -40), end)
        if iw is None or iw.empty:
            return DimensionResult.empty("估值分析", note="该指数无指数级估值数据,且无法获取成分股权重(index_weight 未覆盖)")
        iw = iw.sort_values("trade_date")
        latest_wd = iw.iloc[-1]["trade_date"]
        cons = iw[iw["trade_date"] == latest_wd].sort_values("weight", ascending=False).head(20)["con_code"].tolist()
        if not cons:
            return DimensionResult.empty("估值分析", note="该指数无指数级估值数据,且成分股列表为空")

        def _fetch(code: str):
            try:
                d = self.api.get_daily_basic(code, start, end)
                if d is not None and not d.empty and {"trade_date", "pe_ttm", "pb"}.issubset(d.columns):
                    return d[["trade_date", "pe_ttm", "pb"]]
            except Exception:
                return None
            return None

        with concurrent.futures.ThreadPoolExecutor(max_workers=8) as ex:
            frames = [f for f in ex.map(_fetch, cons) if f is not None and not f.empty]
        if not frames:
            return DimensionResult.empty("估值分析", note="该指数无指数级估值数据,且成分股 daily_basic 不可用")
        # 逐日截面中位数(pe_ttm/pb 分别取当日成分股中位数)
        med = pd.concat(frames).groupby("trade_date")[["pe_ttm", "pb"]].median().sort_index()
        med = med.replace([float("inf"), float("-inf")], float("nan")).dropna(how="all")
        if med.empty:
            return DimensionResult.empty("估值分析", note="该指数成分股估值聚合结果为空")
        latest = med.iloc[-1]
        pe = round(float(latest["pe_ttm"]), 2) if pd.notna(latest["pe_ttm"]) else None
        pb = round(float(latest["pb"]), 2) if pd.notna(latest["pb"]) else None
        hist_count = len(med)
        hist_note = f"(数据不足,仅 {hist_count} 日)" if hist_count < 250 else ""
        pe_hist = pb_hist = None
        if hist_count >= 250:
            if pe is not None:
                pe_hist = round(float((med["pe_ttm"] < pe).sum() / len(med) * 100), 1)
            if pb is not None:
                pb_hist = round(float((med["pb"] < pb).sum() / len(med) * 100), 1)

        data = {
            "pe": pe, "pb": pb,
            "pe_hist_percentile": pe_hist, "pb_hist_percentile": pb_hist,
            "hist_sample_days": hist_count,
            "source": "成分股聚合估算", "constituent_count": len(frames),
            "chart": {
                "title": "成分股聚合 PE/PB 中位数走势(估算)",
                "type": "line",
                "dates": med.index.tolist(),
                "series": [
                    {"name": "PE(TTM)中位数", "yAxisIndex": 0, "data": [round(float(v), 2) if pd.notna(v) else None for v in med["pe_ttm"]]},
                    {"name": "PB中位数", "yAxisIndex": 1, "data": [round(float(v), 2) if pd.notna(v) else None for v in med["pb"]]},
                ],
            },
        }
        conclusion = f"PE(TTM) {pe if pe is not None else '无数据'},PB {pb if pb is not None else '无数据'}(成分股聚合估算,{len(frames)} 只成分股,非官方指数估值)"
        if pe_hist is not None:
            conclusion += f",PE近5年历史分位 {pe_hist}%"
        elif pe is not None:
            conclusion += f",PE近5年历史分位{hist_note}"
        if pb_hist is not None:
            conclusion += f",PB近5年历史分位 {pb_hist}%"
        elif pb is not None:
            conclusion += f",PB近5年历史分位{hist_note}"
        return DimensionResult.success("估值分析", conclusion=conclusion, data=data)

    # ---------- 维度:成分权重 ----------

    def _get_index_weight_cached(self, start: str, end: str) -> Optional[pd.DataFrame]:
        """index_weight 区间取数(进程级缓存)。

        "成分权重"与"行业分布"两个维度并行执行都会取同区间权重,
        不缓存会重复调用接口(审计发现)。键 = (index_code, start, end)。
        """
        key = (self.ts_code, start, end)
        with _INDEX_WEIGHT_LOCK:
            if key in _INDEX_WEIGHT_CACHE:
                return _INDEX_WEIGHT_CACHE[key].copy() if _INDEX_WEIGHT_CACHE[key] is not None else None
        df = self.api.get_index_weight(self.ts_code, start, end)
        with _INDEX_WEIGHT_LOCK:
            _INDEX_WEIGHT_CACHE[key] = df
        return df

    @safe_result("成分权重")
    def analyze_weight(self) -> DimensionResult:
        # index_weight 为月度数据,取最近一个月末
        start = shift_date(self.end_date, -40)
        df = self._get_index_weight_cached(start, self.end_date)
        if df is None or df.empty:
            return DimensionResult.empty("成分权重", note="无法获取成分权重")

        df = df.sort_values("trade_date").reset_index(drop=True)
        latest_date = df.iloc[-1]["trade_date"]
        latest = df[df["trade_date"] == latest_date].sort_values("weight", ascending=False).head(10)

        # 批量补充股票名称(单次API调用,避免逐只查被限流)
        all_codes = ", ".join(latest["con_code"].tolist())
        name_map = {}
        try:
            sb = self.api.get_stock_basic(all_codes, fields="ts_code,name")
            if sb is not None and not sb.empty:
                name_map = dict(zip(sb["ts_code"], sb["name"]))
        except Exception:
            pass
        # 逐只补充缺失的名称(批量查可能因退市等原因遗漏)
        for code in latest["con_code"]:
            if code not in name_map:
                import time; time.sleep(0.3)
                try:
                    sb = self.api.get_stock_basic(code, fields="ts_code,name")
                    if sb is not None and not sb.empty:
                        name_map[code] = sb.iloc[0].get("name", "")
                except Exception:
                    pass
        weight_records = [{"con_code": r["con_code"], "name": name_map.get(r["con_code"], ""), "weight": _safe_float(r["weight"])} for _, r in latest.iterrows()]

        data = {
            "date": latest_date,
            "top_weights": weight_records,
            "top10_total_weight": round(float(latest["weight"].sum()), 2),
        }
        conclusion = f"最新权重日期 {latest_date},前十大成分股权重合计 {latest['weight'].sum():.2f}%"
        return DimensionResult.success("成分权重", conclusion=conclusion, data=data)

    # ---------- 维度:行业分布 ----------

    @safe_result("行业分布")
    def analyze_sector(self) -> DimensionResult:
        # 用 index_weight 获取成分股(index_member 仅适用于申万行业指数)
        start = shift_date(self.end_date, -40)
        df_w = self._get_index_weight_cached(start, self.end_date)
        if df_w is None or df_w.empty:
            return DimensionResult.empty("行业分布", note="无法获取指数成分股")

        # 取最新一期成分股
        df_w = df_w.sort_values("trade_date")
        latest_date = df_w.iloc[-1]["trade_date"]
        latest = df_w[df_w["trade_date"] == latest_date]
        codes = latest["con_code"].unique().tolist()  # 全量成分股,不截断

        # ⚠️ SKILL.md:117 要求申万 2021 口径。实现:index_classify(SW2021) 取申万一级
        # 行业指数列表 → index_member 逐行业取在册成分 → 本地把指数成分股映射到申万行业。
        # 任一步失败则回退 Tushare 自有分类并如实标注,绝不冒充申万。
        ind_map = {}
        src_label = "Tushare分类(申万映射失败)"
        try:
            clf = self.api.get_index_classify(level="L1", src="SW2021")
            if clf is not None and not clf.empty and {"index_code", "industry_name"}.issubset(clf.columns):
                sw_rows = clf[["index_code", "industry_name"]].drop_duplicates("index_code").values.tolist()

                def _members(code: str):
                    try:
                        m = self.api.get_index_member(code)
                        if m is not None and not m.empty and "con_code" in m.columns:
                            cur = m[m["out_date"].isna()] if "out_date" in m.columns else m
                            return set(cur["con_code"].astype(str))
                    except Exception:
                        return set()
                    return set()

                # ⚠️ index_member 单独限速 20 次/秒(实测 8 路并行会触发
                # "每秒最多访问该接口20次"导致约 1/3 行业取不到 → 匹配率掉到 ~70%)。
                # 必须串行 + 间隔,不能与其它维度并行抢配额。
                import time
                member_sets = []
                for r in sw_rows:
                    member_sets.append((r[1], _members(r[0])))
                    time.sleep(0.06)
                for _name, _members_ in member_sets:
                    for c in _members_:
                        ind_map.setdefault(c, _name)
                if ind_map:
                    src_label = "申万2021一级"
        except Exception:
            ind_map = {}

        if not ind_map:
            # 回退:Tushare 自有分类(一次性查全市场,本地匹配,避免逐只查被限流)
            try:
                all_basic = self.api.get_stock_basic(list_status="L", fields="ts_code,name,industry")
                if all_basic is not None and not all_basic.empty:
                    ind_map = dict(zip(all_basic["ts_code"], all_basic["industry"]))
            except Exception:
                pass
            if not ind_map:
                return DimensionResult.empty("行业分布", note="无法获取成分股行业信息")

        industries = [{"ts_code": c, "industry": ind_map.get(c, "未匹配" if src_label.startswith("申万") else "未知")} for c in codes]
        ind_df = pd.DataFrame(industries)
        sector_dist = ind_df["industry"].value_counts().head(10).reset_index()
        sector_dist.columns = ["行业", "成分股数量"]
        sector_dist["家数占比%"] = round(sector_dist["成分股数量"] / len(ind_df) * 100, 2)
        # 权重口径:最新一期成分权重按行业聚合(资金分布视角,与家数口径并列)
        latest_w = df_w.sort_values("trade_date").groupby("con_code").tail(1)[["con_code", "weight"]]
        ind_w = latest_w.merge(ind_df, left_on="con_code", right_on="ts_code", how="left")
        w_dist = ind_w.groupby("industry")["weight"].sum().sort_values(ascending=False).reset_index()
        w_dist.columns = ["行业", "权重占比%"]
        w_dist["权重占比%"] = w_dist["权重占比%"].round(2)
        sector_dist = sector_dist.merge(w_dist, on="行业", how="left")

        matched_count = int((ind_df["industry"] != ("未匹配" if src_label.startswith("申万") else "未知")).sum())
        data = {"distribution": sector_dist.to_dict("records"), "total_members": len(codes), "matched": matched_count,
                "industry_source": src_label}
        conclusion = (f"成分股覆盖 {len(ind_df)} 只(匹配行业 {matched_count} 只),"
                      f"前三大行业({src_label}):{', '.join(sector_dist['行业'].head(3).tolist())}")
        return DimensionResult.success("行业分布", conclusion=conclusion, data=data)

    # ---------- 维度:国际对比 ----------

    @safe_result("国际对比")
    def analyze_global(self) -> DimensionResult:
        # 仅对 A 股主要指数做国际对比
        peers = {
            "000300.SH": [("SPX", "标普500"), ("IXIC", "纳斯达克"), ("DJI", "道琼斯"), ("HSI", "恒生指数")],
            "000001.SH": [("SPX", "标普500"), ("DJI", "道琼斯"), ("HSI", "恒生指数")],
            "399001.SZ": [("IXIC", "纳斯达克"), ("HSI", "恒生指数")],
            "399006.SZ": [("IXIC", "纳斯达克"), ("SPX", "标普500"), ("HSI", "恒生指数")],
            "399005.SZ": [("IXIC", "纳斯达克"), ("SPX", "标普500")],
            "000016.SH": [("DJI", "道琼斯"), ("HSI", "恒生指数")],
            "000688.SH": [("IXIC", "纳斯达克"), ("SPX", "标普500"), ("HSI", "恒生指数")],
            "000905.SH": [("SPX", "标普500"), ("HSI", "恒生指数")],
        }
        peer_codes = peers.get(self.ts_code)
        if not peer_codes:
            return DimensionResult.empty("国际对比", note="未配置该指数的国际对比标的")

        start = shift_date(self.end_date, -max(self.PERIODS) * 2)
        rows = []
        for code, name in [(self.ts_code, self.index_name or self.ts_code)] + peer_codes:
            if code == self.ts_code:
                df = self.api.get_index_daily(code, start, self.end_date)
            else:
                df = self.api.get_index_global(code, start, self.end_date)
            if df is None or df.empty:
                continue
            series = df.set_index("trade_date")["close"].sort_index()
            ret = calc_returns(series, periods=self.PERIODS)
            rows.append({
                "标的": name,
                "近20日%": ret.get("近20日涨幅%", "N/A"),
                "近60日%": ret.get("近60日涨幅%", "N/A"),
                "近250日%": ret.get("近250日涨幅%", "N/A"),
            })

        if not rows:
            return DimensionResult.empty("国际对比", note="无法获取国际指数数据")

        data = {"comparison": rows}
        conclusion = "近20日国际/跨市场涨跌幅对比见表"
        return DimensionResult.success("国际对比", conclusion=conclusion, data=data)


    # ---------- 维度:两融/市场杠杆 ----------

    @safe_result("两融/市场杠杆")
    def analyze_margin(self) -> DimensionResult:
        # 上交所全市场两融汇总
        # 近一年两融:250 交易日 ≈ 365 自然日(shift_date 是自然日),
        # 用默认 lookback_days=250(自然日 ≈ 166 交易日)会显著短于"近一年"
        sse_df = self.api.get_margin(self.end_date, exchange_id="SSE", lookback_days=365)
        szse_df = self.api.get_margin(self.end_date, exchange_id="SZSE", lookback_days=365)

        def _summary(df):
            if df is None or df.empty:
                return None
            df = df.sort_values("trade_date").reset_index(drop=True)
            latest = df.iloc[-1]
            rzye = _safe_float(latest.get("rzye"))
            start_rzye = _safe_float(df.iloc[0].get("rzye")) if len(df) > 1 else None
            chg = None
            if rzye is not None and start_rzye and start_rzye > 0:
                chg = round((rzye / start_rzye - 1) * 100, 2)
            return {
                "latest_rzye_billion": rzye / 1e8 if rzye else None,
                "latest_rzrqye_billion": _safe_float(latest.get("rzrqye")) / 1e8 if latest.get("rzrqye") else None,
                "rzye_chg_pct": chg,
            }

        data = {}
        if sse_df is not None and not sse_df.empty:
            data["sse"] = _summary(sse_df)
        if szse_df is not None and not szse_df.empty:
            data["szse"] = _summary(szse_df)

        if not data:
            return DimensionResult.empty("两融/市场杠杆", note="无法获取全市场两融数据")

        # 计算两市合计
        total_rzye = sum(s["latest_rzye_billion"] for s in data.values() if s and s.get("latest_rzye_billion"))
        total_rzrqye = sum(s["latest_rzrqye_billion"] for s in data.values() if s and s.get("latest_rzrqye_billion"))
        # 取平均变化方向
        chgs = [s["rzye_chg_pct"] for s in data.values() if s and s.get("rzye_chg_pct") is not None]
        avg_chg = round(sum(chgs) / len(chgs), 2) if chgs else None
        data["total_rzye_billion"] = total_rzye
        data["total_rzrqye_billion"] = total_rzrqye
        data["avg_rzye_chg_pct"] = avg_chg

        parts = [f"两市融资余额合计 {total_rzye:.0f}亿"]
        if avg_chg is not None:
            direction = "上升" if avg_chg > 0 else "下降"
            parts.append(f"近一年融资余额{direction} {abs(avg_chg)}%")
        # 两市融资余额走势(亿元);两所数据天数可能差一天,按日期对齐避免错位
        _m_dates = []
        _m_raw = {}  # label -> {trade_date: rzye}
        for _label, _df in (("上交所", sse_df), ("深交所", szse_df)):
            if _df is None or _df.empty:
                continue
            _d = _df.sort_values("trade_date")
            _m_raw[_label] = dict(zip(_d["trade_date"], _d["rzye"]))
            if len(_d["trade_date"]) > len(_m_dates):
                _m_dates = _d["trade_date"].tolist()
        _m_series = []
        for _label, _m in _m_raw.items():
            _vals = [_m.get(d) for d in _m_dates]
            _m_series.append({"name": _label,
                             "data": [round(v / 1e8, 2) if v is not None and v == v else None for v in _vals]})
        if _m_series:
            data["chart"] = {
                "title": "两市融资余额走势(亿元)",
                "type": "line",
                "dates": _m_dates,
                "series": _m_series,
            }
        conclusion = ",".join(parts)
        return DimensionResult.success("两融/市场杠杆", conclusion=conclusion, data=data)

    # ---------- 维度:动量质量(因子化) ----------

    @safe_result("动量质量")
    def analyze_momentum_quality(self) -> DimensionResult:
        start = shift_date(self.end_date, -max(self.PERIODS) * 2)
        df = self.api.get_index_daily(self.ts_code, start, self.end_date)
        if df is None or df.empty:
            return DimensionResult.empty("动量质量", note="无法获取指数行情")
        df = df.set_index("trade_date").sort_index()
        price = df["close"]
        has_ohlc = "high" in df.columns and "low" in df.columns
        high = df["high"] if has_ohlc else None
        low = df["low"] if has_ohlc else None
        _src = "指数日线" if has_ohlc else "指数日线(缺 high/low,振幅切割不适用)"
        if len(price) < 121:
            return DimensionResult.insufficient_history("动量质量", note="需至少121日数据")

        qm = calc_quantitative_momentum(price, window=60)
        am = calc_amplitude_momentum(price, high, low, n=120, lam=0.3) if has_ohlc else None
        data = {"quantitative_momentum": qm, "amplitude_momentum": am, "source": _src}
        conclusion = f"动量质量因子原始值(数据源:{_src})。"
        insights = []
        if qm:
            insights.append(f"高质量动量因子:{qm['momentum']}(60日收益 {qm['raw_return'] * 100:.2f}%、"
                            f"日收益标准差 {qm['sigma'] * 100:.2f}%;计算式 = 60日收益 − 3000×日收益方差)")
        if am:
            insights.append(f"振幅切割因子:A={am['a_factor']}(低振幅日收益合计)、"
                            f"B={am['b_factor']}(高振幅日收益合计)")
        elif not has_ohlc:
            insights.append("行情缺 high/low 列,振幅切割因子不适用")
        return DimensionResult.success("动量质量", conclusion=conclusion, data=data, insights=insights)


    # ---------- 维度:风险提示 ----------

    @safe_result("风险提示")
    def analyze_risk(self) -> DimensionResult:
        risks = []
        notes = []

        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")
            if isinstance(vol, (int, float)):
                risks.append(f"指数年化波动 {vol}%")
            if isinstance(mdd, (int, float)):
                risks.append(f"指数近一年最大回撤 {mdd}%")

        valuation = self.results.get("valuation")
        if valuation and valuation.is_ok() and valuation.data:
            pe_hist = valuation.data.get("pe_hist_percentile")
            pb_hist = valuation.data.get("pb_hist_percentile")
            if isinstance(pe_hist, (int, float)):
                risks.append(f"PE 历史分位 {pe_hist}%")
            if isinstance(pb_hist, (int, float)):
                risks.append(f"PB 历史分位 {pb_hist}%")

        if not risks:
            risks.append("未发现显著风险信号(基于已有维度)")

        for dim, res in self.results.items():
            if dim == "risk":
                continue
            if res.status != ResultStatus.SUCCESS:
                # 用中文维度名,不能把内部 key 直接印进报告
                label = self.DIM_TITLES.get(dim, res.title or dim)
                notes.append(f"{label}:{res.note or '无数据'}")

        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()

        parallel_dims = [d for d in self.dimensions if d not in ("overview", "risk")]
        dim_methods = {
            "trend": self.analyze_trend,
            "valuation": self.analyze_valuation,
            "weight": self.analyze_weight,
            "sector": self.analyze_sector,
            "global": self.analyze_global,
            "margin": self.analyze_margin,
            "momentum_quality": self.analyze_momentum_quality,
        }
        to_run = {d: dim_methods[d] for d in parallel_dims if d in dim_methods}
        if to_run:
            max_workers = min(5, 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.index_name,
            "end_date": self.end_date,
            "dimensions": {k: v.to_dict() for k, v in self.results.items()},
        }

    # ---------- 报告渲染 ----------

    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):
        """安全转 float,失败返回 None。"""
        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 _v(self, d, *keys, default="N/A"):
        """安全取嵌套值。"""
        cur = d
        for k in keys:
            if cur is None:
                return default
            cur = cur.get(k) if isinstance(cur, dict) else None
        return cur if cur is not None else default

    def _md(self, df):
        """输出 markdown 表格。"""
        if df is None or df.empty:
            return ""
        df = df.copy()
        df = df.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))
                )
        return df_to_md_table(df)

    DIM_TITLES = {
        "overview": "概况",
        "trend": "行情趋势",
        "valuation": "估值分析",
        "weight": "成分权重",
        "sector": "行业分布",
        "global": "国际对比",
        "margin": "两融/市场杠杆",
        "momentum_quality": "动量质量",
        "risk": "风险提示",
    }

    # 各维度含义描述(面向非专业读者,标题后以引用块呈现)
    DIM_DESCRIPTIONS = {
        "overview": "指数基础档案:代码、发布机构、基期与基点。",
        "trend": "指数走势:区间涨跌幅、波动率、回撤、均线与沪深300对比的读数。",
        "valuation": "估值指标:指数整体 PE/PB 及历史分位。",
        "weight": "成分权重:前十大成分股及权重占比。",
        "sector": "行业分布:成分股按申万行业归类的家数与权重占比。",
        "global": "国际对比:与标普500/纳斯达克/恒生等指数的收益与位次对比。",
        "margin": "两融数据:全市场融资融券余额读数。",
        "momentum_quality": "动量质量:风险调整动量与振幅切割因子的原始数值。",
        "risk": "风险指标:列示可复核的风险指标读数,不做综合评级。",
    }

    def _overall_conclusion(self) -> str:
        parts = []
        trend = self.results.get("trend")
        if trend and trend.is_ok() and trend.data:
            ret20 = trend.data.get("returns", {}).get("近20日涨幅%", "N/A")
            vol = trend.data.get("volatility")
            parts.append(f"近20日涨幅 {ret20}%,年化波动 {vol}%")
        valuation = self.results.get("valuation")
        if valuation and valuation.is_ok() and valuation.data:
            pe = valuation.data.get("pe", "N/A")
            pe_hist = valuation.data.get("pe_hist_percentile")
            parts.append(f"PE {pe}" + (f"(历史分位 {pe_hist}%)" if pe_hist is not None else ""))
        weight = self.results.get("weight")
        if weight and weight.is_ok() and weight.data:
            tw = weight.data.get("top_weights", [])
            if tw:
                top1 = tw[0]
                top1_label = f"{top1.get('name', '')}({top1.get('con_code', 'N/A')})" if top1.get('name') else top1.get('con_code', 'N/A')
                parts.append(f"第一大权重股 {top1_label}({top1.get('weight', 'N/A')}%)")
        parts = [p for p in parts if p]
        return ";".join(parts) + "。" if parts else "数据不足,无法生成综合结论。"

    def report(self) -> str:
        if not self.results:
            self.run()

        name = self.index_name or self.ts_code
        _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))
                if res.insights:
                    lines.append("")
                    lines.append("**因子数值说明**:")
                    for _ins in res.insights:
                        lines.append(f"- {_ins}")
            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}")
            else:
                lines.append(f"- {res.note or '未列示额外风险指标'}")
            lines.append("")

        idx += 1
        lines.append(f"## {idx}. 指标摘要")
        try:
            lines.append(self._overall_evaluation())
        except Exception as e:
            # 指标摘要是装饰性汇总,任何异常都不该让整份报告崩溃(SKILL 部分失败原则)
            print(f"[index_runner] 指标摘要生成失败: {type(e).__name__}: {e}", file=sys.stderr)
            lines.append("**指标摘要**:部分维度数据不完整,本次未生成汇总。")
        lines.append("")
        lines.append("---")
        lines.append("*本报告由程序基于山西证券 Tushare 平台的 T-1 历史数据自动生成,仅作数据统计与展示:不含证券估值意见、投资评级、目标价、买卖建议或收益预测,不构成任何投资建议、投资顾问服务或要约。报告未经人工分析师审核,不得作为对外发布的证券研究报告使用。*")
        return "\n".join(lines)

    def _overall_evaluation(self) -> str:
        """跨维度指标摘要:只汇总原始读数,不做综合评级或风格定位。"""
        trend = self.results.get("trend")
        valuation = self.results.get("valuation")
        weight = self.results.get("weight")
        margin = self.results.get("margin")

        trend_ok = trend and trend.is_ok() and trend.data
        val_ok = valuation and valuation.is_ok() and valuation.data
        wt_ok = weight and weight.is_ok() and weight.data

        lines = [f"**指标摘要**:{self.index_name or self.ts_code} 各维度原始读数如下。"]

        # 分维度要点
        points = []
        if trend_ok:
            ret20 = self._v(trend.data, "returns", "近20日涨幅%")
            ret250 = self._v(trend.data, "returns", "近250日涨幅%")
            vol = self._v(trend.data, "volatility")
            mdd = self._v(trend.data, "max_drawdown")
            sharpe = self._v(trend.data, "sharpe")
            bench = trend.data.get("benchmark") or {}
            bench20 = self._v(bench, "returns", "近20日涨幅%")
            bench250 = self._v(bench, "returns", "近250日涨幅%")
            points.append(f"- **趋势**:近20日 {self._fmt(ret20)}%,近250日 {self._fmt(ret250)}%,年化波动 {self._fmt(vol)}%,最大回撤 {self._fmt(mdd)}%,夏普 {self._fmt(sharpe)}")
            if bench:
                points.append(f"- **基准(沪深300)**:近20日 {self._fmt(bench20)}%,近250日 {self._fmt(bench250)}%")
        if val_ok:
            pe = self._v(valuation.data, "pe")
            pb = self._v(valuation.data, "pb")
            pe_hist = self._v(valuation.data, "pe_hist_percentile")
            pb_hist = self._v(valuation.data, "pb_hist_percentile")
            points.append(f"- **估值**:PE {self._fmt(pe)}(历史分位 {self._fmt(pe_hist)}%),PB {self._fmt(pb)}(历史分位 {self._fmt(pb_hist)}%)")
        if wt_ok:
            tw = weight.data.get("top_weights", [])
            top1 = tw[0] if tw else {}
            top_name = top1.get("name", "") or top1.get("con_code", "N/A")
            top_code = top1.get("con_code", "N/A")
            top_w = self._fmt(top1.get("weight"))
            total_w = self._fmt(weight.data.get("top10_total_weight"))
            points.append(f"- **权重**:第一大权重 {top_name}({top_code},{top_w}%),前十大合计 {total_w}%")
        if margin and margin.is_ok() and margin.data:
            sse = margin.data.get("sse") or {}
            szse = margin.data.get("szse") or {}
            sse_rzye = self._fmt(self._v(sse, "latest_rzye_billion"))
            szse_rzye = self._fmt(self._v(szse, "latest_rzye_billion"))
            points.append(f"- **杠杆**:上交所融资余额 {sse_rzye}亿,深交所融资余额 {szse_rzye}亿")

        if points:
            lines.append("")
            lines.extend(points)

        lines.append("")
        lines.append("以上均为 T-1 历史数据的统计描述,不含估值意见、投资评级、目标价、买卖建议或收益预测。")
        return "\n".join(lines)

    def _render_dimension(self, res) -> list:
        """渲染单个维度的数据表 + 指标说明。"""
        lines = []
        data = res.data or {}

        if res.title == "概况":
            # 概况数据直接在顶层,遍历生成表
            label_map = {
                "ts_code": "指数代码",
                "name": "指数简称",
                "publisher": "发布机构",
                "category": "类别",
                "base_date": "基期",
                "base_point": "基点",
                "list_date": "上市日期",
            }
            rows = []
            for k, v in data.items():
                if v is None or str(v) == "nan":
                    continue
                if k in ("base_date", "list_date") and str(v).isdigit() and len(str(v)) == 8:
                    v = f"{str(v)[:4]}-{str(v)[4:6]}-{str(v)[6:]}"
                rows.append({"项目": label_map.get(k, k), "内容": str(v)})
            if rows:
                lines.append(self._md(pd.DataFrame(rows)))

        elif res.title == "行情趋势":
            returns = data.get("returns", {})
            bench = data.get("benchmark") or {}
            bench_returns = bench.get("returns") or {}
            all_keys = [k for k in ["近5日涨幅%", "近20日涨幅%", "近60日涨幅%", "近120日涨幅%", "近250日涨幅%"] if k in returns or k in bench_returns]
            rows = []
            for k in all_keys:
                row = {"区间": k}
                row[self.index_name or "指数"] = self._fmt(returns.get(k, "N/A"))
                if bench:
                    row[bench.get("ts_code", "沪深300")] = self._fmt(bench_returns.get(k, "N/A"))
                rows.append(row)
            lines.append(self._md(pd.DataFrame(rows)))


            # 风控指标对比
            lines.append("")
            bench_col = bench.get("ts_code", "沪深300") if bench else None
            risk_rows = [
                {"指标": "年化波动率%", "指数": self._fmt(data.get("volatility"))},
                {"指标": "最大回撤%", "指数": self._fmt(data.get("max_drawdown"))},
                {"指标": "夏普比率", "指数": self._fmt(data.get("sharpe"))},
            ]
            if bench_col:
                for _i, _key in enumerate(["volatility", "max_drawdown", "sharpe"]):
                    risk_rows[_i][bench_col] = self._fmt(bench.get(_key))
            lines.append(self._md(pd.DataFrame(risk_rows)))

            # 均线
            ma = data.get("ma")
            if isinstance(ma, dict):
                lines.append("")
                ma_rows = [{"均线": k, "数值": self._fmt(v)} for k, v in ma.items()]
                lines.append(self._md(pd.DataFrame(ma_rows)))

            # 指标说明
            lines.append("")
            lines.append(self._trend_eval(data))

        elif res.title == "估值分析":
            pe_label = "PE(加权)" if data.get("source") else "PE"
            pb_label = "PB(加权)" if data.get("source") else "PB"
            table = {
                "指标": [pe_label, pb_label, "PE历史分位", "PB历史分位"],
                "数值": [self._fmt(data.get("pe")), self._fmt(data.get("pb")), self._fmt(data.get("pe_hist_percentile")), self._fmt(data.get("pb_hist_percentile"))],
            }
            lines.append(self._md(pd.DataFrame(table)))
            if data.get("source"):
                lines.append("")
                lines.append(f"*数据源:{data['source']},非官方指数级估值*")
            lines.append("")
            lines.append(self._valuation_eval(data))

        elif res.title == "成分权重":
            weights = data.get("top_weights", [])
            if weights:
                # 列名中文化,含股票名称
                w_rows = [{"成分代码": w.get("con_code", "N/A"), "股票名称": w.get("name", ""), "权重%": self._fmt(w.get("weight"))} for w in weights]
                lines.append(self._md(pd.DataFrame(w_rows)))
            total = self._fmt(data.get("top10_total_weight"))
            lines.append("")
            weights = data.get("top_weights", [])
            top1_name = weights[0].get("name", "") if weights else ""
            top1_code = weights[0].get("con_code", "N/A") if weights else "N/A"
            top1_w = self._fmt(weights[0].get("weight")) if weights else "N/A"
            top1_desc = f"第一大权重{top1_name}({top1_code},{top1_w}%)" if top1_name else f"第一大权重{top1_code}({top1_w}%)"
            lines.append(f"**指标说明**:前十大成分股权重合计 {total}%。{top1_desc}。")

        elif res.title == "行业分布":
            dist = data.get("distribution", [])
            if dist:
                lines.append(self._md(pd.DataFrame(dist)))
                lines.append("")
                top3 = [d.get("行业", "") for d in dist[:3]]
                top1_name = dist[0].get("行业", "") if dist else ""
                top1_cnt = dist[0].get("家数占比%", "N/A")
                top1_w = dist[0].get("权重占比%", "N/A")
                _wd_txt = f"(家数占比 {top1_cnt}%,权重占比 {top1_w}%)" if top1_w != "N/A" else f"(家数占比 {top1_cnt}%)"
                # 分类口径必须在报告中标注(申万2021 / Tushare回退)
                _src = data.get("industry_source") or "分类口径未标注"
                lines.append(f"**指标说明**:按{_src}分类,前三大行业为{'、'.join(top3)},"
                             f"第一大行业({top1_name}){_wd_txt}。")
            else:
                lines.append("- 无法获取指数成分股")

        elif res.title == "国际对比":
            comp = data.get("comparison", [])
            if comp:
                lines.append(self._md(pd.DataFrame(comp)))
                lines.append("")
                # 按近250日涨幅列出本指数在对比样本中的位次(只陈述数值与排名)
                eval_parts = []
                for c in comp:
                    name = c.get("标的", "")
                    r250 = self._f(c.get("近250日%"))
                    if r250 is not None:
                        eval_parts.append((name, r250))
                if eval_parts:
                    eval_parts.sort(key=lambda x: x[1], reverse=True)
                    idx_name = self.index_name or self.ts_code
                    idx_entry = next((x for x in eval_parts if x[0] == idx_name), None)
                    if idx_entry:
                        _rank = [x[0] for x in eval_parts].index(idx_name) + 1
                        lines.append(f"**指标说明**:{idx_name}近250日涨幅 {idx_entry[1]}%,"
                                     f"在 {len(eval_parts)} 个对比标的中列第 {_rank} 位。")
            else:
                lines.append("- 未配置该指数的国际对比标的")

        elif res.title == "两融/市场杠杆":
            table_rows = []
            for ex in ["sse", "szse"]:
                s = data.get(ex)
                if s:
                    table_rows.append({
                        "交易所": {"SSE": "上交所", "SZSE": "深交所"}.get(ex.upper(), ex.upper()),
                        "融资余额(亿)": self._fmt(s.get("latest_rzye_billion")),
                        "融资融券余额(亿)": self._fmt(s.get("latest_rzrqye_billion")),
                        "区间变化%": self._fmt(s.get("rzye_chg_pct")),
                    })
            if table_rows:
                lines.append(self._md(pd.DataFrame(table_rows)))
            lines.append("")
            lines.append(self._margin_eval(data))

        elif res.title == "风险提示":
            for r in data.get("risks", []):
                lines.append(f"- {r}")
            notes = data.get("notes", [])
            if notes:
                lines.append("")
                lines.append("**数据说明**:")
                for n in notes:
                    lines.append(f"- {n}")

        elif res.title == "动量质量":
            rows = []
            qm = data.get("quantitative_momentum", {})
            if qm:
                rows.append({"指标": "高质量动量得分(r_60-3000σ²)", "数值": self._fmt(qm.get("momentum"), digits=4)})
                rows.append({"指标": "原始60日收益", "数值": self._fmt(qm.get("raw_return"), digits=4)})
                rows.append({"指标": "60日收益标准差", "数值": self._fmt(qm.get("sigma"), digits=4)})
            am = data.get("amplitude_momentum", {})
            if am:
                rows.append({"指标": "振幅切割A因子(低振幅日)", "数值": self._fmt(am.get("a_factor"), digits=4)})
                rows.append({"指标": "振幅切割B因子(高振幅日)", "数值": self._fmt(am.get("b_factor"), digits=4)})
            if data.get("source"):
                rows.append({"指标": "数据源", "数值": data["source"]})
            if rows:
                lines.append(self._md(pd.DataFrame(rows)))

        return [l for l in lines if l is not None]

    def _trend_eval(self, data):
        parts = [f"近20日 {self._fmt(data.get('returns', {}).get('近20日涨幅%'))}%,"
                 f"近250日 {self._fmt(data.get('returns', {}).get('近250日涨幅%'))}%,"
                 f"年化波动 {self._fmt(data.get('volatility'))}%,"
                 f"最大回撤 {self._fmt(data.get('max_drawdown'))}%。"]
        ma = data.get("ma", {})
        if ma:
            parts.append(f"均线:MA5={self._fmt(ma.get('MA5'))},"
                         f"MA20={self._fmt(ma.get('MA20'))},MA60={self._fmt(ma.get('MA60'))}。")
        bench = data.get("benchmark") or {}
        if bench:
            bench250 = self._v(bench, "returns", "近250日涨幅%")
            parts.append(f"近250日相对沪深300 {self._fmt(data.get('returns', {}).get('近250日涨幅%'))}% "
                         f"vs {self._fmt(bench250)}%。")
        return "**指标说明**:" + "".join(parts)

    def _valuation_eval(self, data):
        parts = []
        if data.get("pe_hist_percentile") is not None:
            parts.append(f"PE 历史分位 {self._fmt(data.get('pe_hist_percentile'))}%。")
        if data.get("pb_hist_percentile") is not None:
            parts.append(f"PB 历史分位 {self._fmt(data.get('pb_hist_percentile'))}%。")
        parts.append("历史分位为当前值在样本区间内的百分位读数。")
        return "**指标说明**:" + "".join(parts)

    def _margin_eval(self, data):
        parts = []
        if data.get("total_rzye_billion") is not None:
            parts.append(f"两市融资余额合计 {self._fmt(data.get('total_rzye_billion'))}亿。")
        if data.get("avg_rzye_chg_pct") is not None:
            parts.append(f"两所融资余额区间变化 {self._fmt(data.get('avg_rzye_chg_pct'))}%。")
        parts.append("两融余额为市场杠杆水平的统计读数。")
        return "**指标说明**:" + "".join(parts)

# ---------- 便捷函数 ----------

def analyze_index(ts_code: str, end_date: Optional[str] = None, dimensions: Optional[List[str]] = None) -> Dict[str, Any]:
    runner = IndexAnalysisRunner(ts_code=ts_code, end_date=end_date, dimensions=dimensions)
    return runner.run()


def index_report(ts_code: str, end_date: Optional[str] = None, dimensions: Optional[List[str]] = None) -> str:
    runner = IndexAnalysisRunner(ts_code=ts_code, end_date=end_date, dimensions=dimensions)
    md = runner.report()
    return render_html_report(md, runner.results)


if __name__ == "__main__":
    import sys
    if hasattr(sys.stdout, "reconfigure"):
        sys.stdout.reconfigure(encoding="utf-8")
    import argparse
    parser = argparse.ArgumentParser(description="指数综合分析 Runner")
    parser.add_argument("ts_code", help="指数代码,如 000300.SH")
    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 = index_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