# Sxsc Tushare Analysis

> 对用户提到的标的（沪深股票、指数、公募基金、期货）进行综合分析，输出带 ECharts 图表的 HTML 分析报告。 触发条件：用户说"分析""研究""评估""看看XX怎么样""XX基本面""XX技术面""XX估值""XX财务""深度研究""对比"等分析类请求，且标的属于 A 股/指数/公募基金/期货。 本 skill 自动调用 sxsc_tushare 取数并输出完整报告，接管数据获取与分析全流程。当本 skill 被触发时，数据获取类 skill 不应同时激活——分析已包含数据。

- Skill: `truehooha/sxsc-tushare-analysis` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add truehooha/sxsc-tushare-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/truehooha/sxsc-tushare-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: TrueHOOHA (https://skillmd.com/u/truehooha)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/truehooha/sxsc-tushare-analysis

---


# 山西证券 Tushare 综合分析技能

本 skill 配合 `shanxi-securities-tushare` 数据 skill 使用，在后者提供的数据接口之上增加**多维度交叉分析层**，将分散的指标整合为结构化分析报告。

## 工作原理

把"帮我分析 XX"转化为可执行的**标的识别 → 维度加载 → 取数 → 计算 → 解读 → 报告**流程。

**重要**：本 skill 不封装取数逻辑。取数时引用 `shanxi-securities-tushare/SKILL.md` 的流程规范：
1. 先运行 `python shanxi-securities-tushare/scripts/check_env.py` 校验环境，**token 缺失时停下**，先提示用户配置。
2. 调用接口前必须查 `shanxi-securities-tushare/references/API接口对应表.md`，**禁止凭记忆写接口**。
3. 取数参考 `shanxi-securities-tushare/scripts/` 下 demo 模板，按环境校验结果选择 SDK 或 HTTP 方式。

## 快速入口（默认调用）

本 skill 已封装统一 Runner，Agent 识别标的类型后**直接调用对应入口**，无需再从原始接口逐条取数：

| 标的类型 | 模块 | 默认入口 | 示例 |
|---------|------|---------|------|
| 股票 | `analysis_runner.py` | `stock_report(ts_code, end_date=None, dimensions=None)` | `stock_report("600519.SH")` |
| 基金（场外 .OF / 场内 ETF .SH/.SZ） | `fund_analysis_runner.py` | `fund_report(ts_code, end_date=None, dimensions=None)` | `fund_report("110011.OF")` |
| 指数 | `index_analysis_runner.py` | `index_report(ts_code, end_date=None, dimensions=None)` | `index_report("000300.SH")` |
| 期货（主力连续合约） | `fut_analysis_runner.py` | `fut_report(ts_code, end_date=None, dimensions=None)` | `fut_report("SR.ZCE")` |

- `dimensions` 为可选维度白名单，默认使用 Runner 内置维度；用户明确"只看估值/技术面"时再传入裁剪。
- `*_report()` 返回 **HTML 字符串**（含 ECharts 图表，内联在对应维度章节），Agent 将其写入 `<ts_code>_report.html` 落盘；浏览器直接打开。
- 旧入口 `stock_analyzer.py` 仍保留为兼容包装，新代码优先使用 `analysis_runner.stock_report`。
- 各 Runner 内部已实现维度级并行取数，无需 Agent 手动并发。

## 核心工作流

每次分析按此顺序：

1. **环境校验** — 运行 `python shanxi-securities-tushare/scripts/check_env.py`，确认 token 可用，确定 mode（sdk/http）。
2. **标的识别** — 解析用户表述，确定标的类型 + ts_code。根据代码格式或名称搜索确定。
3. **维度加载** — 默认加载该标的类型的摘要维度；用户明确指定（如"只看技术面""只看估值"）时仅加载指定维度，避免权限/配额不足与超长输出。"全套固定"为默认上限，可裁剪。
4. **调用 Runner 分析** — 直接调用对应 Runner 的 `*_report()` / `*_analyze()` 入口；Runner 内部按默认维度并行取数、计算并生成结构化结果。如需自定义维度，通过 `dimensions` 参数裁剪。
5. **综合报告** — 按结构化模板输出 HTML 报告（时间序列图表内联在各维度章节）。

> **报告必须落盘（强制）**：每份分析报告**必须**以 HTML 文件保存到当前项目目录，文件名 `<ts_code>_report.html`（如 `600519.SH_report.html`）。CLI 已默认自动保存到当前工作目录并打印保存路径；若通过 Python 接口调用 `*_report()` 返回 HTML 字符串，则必须由 Agent 将该字符串写入项目目录下的 `<ts_code>_report.html` 文件。禁止只打印到终端不落盘。报告为独立 HTML（ECharts CDN 渲染，需联网打开），时间序列维度自动生成图表并**内联在对应维度章节**（如 K线在"行情趋势"、PE/PB 在"估值分析"），其余维度为表格。

## 标的识别规则

| 用户表述 | 标的类型 | 说明 |
|---------|---------|------|
| `600519.SH` / `000001.SZ` / `920575.BJ` | 股票 | 已标准格式，直接识别。`.BJ` 为北交所 |
| `600519` / `000001` | 股票 | 补全为 `.SH`/`.SZ`/`.BJ`（沪市 600/601/603/605/688，深市 000/001/002/003/300/301，北交所 8 开头） |
| "茅台"/"贵州茅台"/"平安" | 股票 | 调 `stock_basic` 按名称模糊匹配，取上市状态 L 的股票 |
| `000300.SH` / `399001.SZ` | 指数 | 标准指数代码，后缀 `.SH`/`.SZ`/`.SI` |
| "沪深300"/"上证50" | 指数 | 调 `index_basic` 按名称匹配 |
| `000001.OF` / `110011.OF` | 基金 | 标准基金代码，后缀 `.OF` 场外/`.SZ` 场内 |
| "易方达蓝筹"/"招商白酒" | 基金 | 调 `fund_basic` 按名称匹配 |
| `RB2501.SHF` / `CU2403.SHF` | 期货 | 标准期货合约代码 |
| "螺纹钢"/"沪铜"/"原油" | 期货 | 调 `fut_basic` 按名称匹配，获取主力合约 |

> **多义性消歧**：名称匹配返回多个结果时（如"平安"= 平安银行 000001.SZ / 中国平安 601318.SH），优先按市值排序取最大标的，但必须在报告中注明"匹配到 N 个结果，默认分析市值最大的 XX，如需分析其他请指定代码"。

> **基金名称匹配的宽匹配陷阱（`fund_basic` 为子串模糊匹配）**：名称会命中所有含该词的基金，分析单一标的时必须收敛口径，否则误拉一堆同类基金：
> 
> | 用户表述 | 陷阱 | 正确处理 |
> |---------|------|---------|
> | "创业板ETF" | "创业板" 会命中 87 只主题 ETF/混合基金 | 用精确代码或名称含"创业板ETF"筛选，且仅取场内 ETF（排除 LOF/联接基金） |
> | "科创50" | Tushare 全称"上证科创板50成份ETF"，名称含"科创50"的可能是其他产品 | 用名称含"科创板50"或直接按代码识别 |
> | "黄金ETF" | 会误匹配"黄金产业股票ETF"等主题产品 | 名称精确含"黄金ETF" |
> | "沪深300" | 名称含该词的基金几十只（场内 ETF + 场外联接 + 多只跟踪基金） | 先定目标类型（场内/场外），再按基金类型字段收敛 |
> 
> 名称匹配结果 > 1 时：先按基金类型（场内/场外/联接）与上市状态收敛，仍不唯一再按上述"多义性消歧"规则处理，并在报告中注明匹配数与最终口径。

## 分析维度（默认全套，按需裁剪）

### 一、股票（默认 11 维）

每个维度均输出：**描述句 → 数据表 → 分析评价**

| # | 维度 | 数据接口 | 关键分析指标 |
|---|------|---------|------------|
| 1 | 概况 | `stock_basic`、`stock_company` | 公司全称、行业（申万）、上市日期、注册地、员工数、主营业务简介 |
| 2 | 行情趋势 | `daily`、`weekly`、`monthly`、`daily_basic`、**`adj_factor`**、`index_daily`(沪深300+行业指数) | 近 20/60/250 日涨跌幅（基于复权价）、MA5/MA20/MA60、**MACD/RSI/KDJ/布林带**、换手率、振幅、波动率、阶段最高/最低；**基准对比**：对沪深300及所属行业指数计算相同口径的涨跌幅、年化波动率、最大回撤、夏普比率，与标的并列对比（判断超额收益与相对风险） |
| 3 | 估值分析 | `daily_basic`、`index_dailybasic`(行业)、`index_member`(行业成分股) | PE(TTM)、PB、PS(TTM)、股息率、总市值、流通市值；**与行业均值对比**（取 `index_classify` 获取行业指数代码 → `index_member` 取成分股 → 各取 `daily_basic` PE/PB，先 `winsorize_cross_section` 截面去极值再求均值/中位数，避免单只异常股拉偏）；**PE/PB 双口径分位**（`valuation_percentiles`：近 5 年历史分位 + 当日同行业截面分位，双口径背离时需找原因） |
| 4 | 财务质量 | `fina_indicator`、`income`、`balancesheet`、`cashflow`、**`forecast`** | ROE、毛利率、净利率、营收/利润增速（YoY）、资产负债率、经营现金流；业绩预告类型及变动幅度；**Piotroski F-Score（9 项量化打分，≥7 强/≤2 弱）** |
| 5 | 资金面 | `moneyflow`、`moneyflow_hsgt`、**`block_trade`** | 近 5-20 日主力净流入（注意：`net_mf_amount` 为全口径净流入，`buy_elg_amount - sell_elg_amount` 为超大单口径，两者方向可能相反，需按分析目标选择口径）、北向持股变化、大宗交易折溢价/机构买卖方向 |
| 6 | 股东/筹码 | `top10_holders`、`top10_floatholders`、`stk_holdernumber`、**`stk_holdertrade`** | 前十大股东/流通股东集中度、**股东户数时间序列分析（筹码集中度指标）**、大股东增减持方向与比例 |

### 筹码集中度分析（股东户数时间序列）

股东户数的时间序列变化是判断筹码集中/分散的核心指标，比单点数值更有意义：

- **股东户数减少（与筹码集中方向一致）**：人均持股数增加。这通常是筹码趋于集中的信号，但户数变化仅为相关性，**不能直接断言主力吸筹**；需结合成交、股价走势与股东结构交叉验证。
- **股东户数增加（与筹码分散方向一致）**：人均持股数减少。通常与筹码趋于分散一致，但同样**不能直接断言主力派发**；需结合量价验证。
- **分析要点**：
  - 对比近 4 个季度股东户数变化率，判断趋势方向
  - 结合股价走势交叉验证（均为相关性观察，非因果结论）：户数持续下降 + 股价上涨 = 可能筹码锁定（健康上涨特征之一）；户数持续下降 + 股价下跌 = 可能主力被套（阶段见底信号之一）；户数持续上升 + 股价上涨 = 可能散户接盘（警惕见顶）
  - 使用 `stk_holdernumber` 接口获取历史数据，按 `end_date` 排序后计算环比变化率
| 7 | 两融/杠杆情绪 | `margin_detail` | 融资余额及变化率、融券余额、近5日融资余额变化 |
| 8 | 市场异动 | `limit_list_d`、`top_list`、`top_inst` | 近期涨停/跌停记录、龙虎榜上榜次数、机构净买卖 |
| 9 | 解禁压力 | **`share_float`** | 未来 3 个月即将解禁股份数量及占比 |
| 10 | 宏观/市场环境 | `index_daily`(沪深300)、`cn_cpi`、`cn_ppi`、`shibor_lpr`、`cn_gdp` | 大盘近期走势、CPI/PPI 走势与方向、LPR 利率水平、GDP 同比 |
| 11 | 风险提示 | 汇总以上维度 | 综合风险分级：高/中/低，列出具体风险信号 |

### 二、指数（默认 8 维）

| # | 维度 | 数据接口 | 关键分析指标 |
|---|------|---------|------------|
| 1 | 概况 | `index_basic` | 发布方、基期、基点、类别、上市日期 |
| 2 | 行情趋势 | `index_daily` | 近 20/60/250 日涨跌幅、MA 排列、年化波动率、最大回撤、夏普比率；**基准对比**：对沪深300计算相同口径指标并列对比 |
| 3 | 估值 | `index_dailybasic` | PE(TTM)、PB 历史分位数。**注意：`index_dailybasic` 不覆盖科创板指数**（如科创50 000688.SH），此类指数估值降级为用成分股 `daily_basic` 聚合估算（截面中位数 + 历史分位），并标注数据源 |
| 4 | 成分权重 | `index_weight` | 前十大权重股及权重占比，补充股票名称（`stock_basic` 批量查询） |
| 5 | 行业分布 | `index_weight` 获取成分股 + `stock_basic` 查行业 | 成分股按申万行业归类，统计各行业数量及占比（前三行业占比） |
| 6 | 两融/市场杠杆 | `margin`（全市场两融汇总） | 两市融资余额合计、近一年（250 交易日）变化方向、杠杆情绪判断 |
| 7 | 对比 | `index_global` | 与同类指数/国际指数近期表现对比。**`index_global` 的 `ts_code` 无点前缀**（如 `DJI`/`SPX`/`IXIC`/`N225`/`HSI`，非 `.DJI`），代码格式需查 `references/国际指数.md` 文档。**注意：`index_global` 返回数据为降序（最新在前），计算前必须 `.sort_values('trade_date')`，否则 `iloc` 索引取到的日期方向相反，导致涨跌幅方向错误** |
| 8 | 风险提示 | 汇总以上维度 | 波动偏高/回撤较深/估值偏高等风险信号 |
### 三、公募基金（默认 9 维）

| # | 维度 | 数据接口 | 关键分析指标 |
|---|------|---------|------------|
| 1 | 概况 | `fund_basic` | 基金类型、成立日期、上市日期、基金简称 |
| 2 | 净值走势 | `fund_nav`、**`fund_adj`**、**`fund_daily`**（场内ETF） | 近 1/3/6 月、近 1/3 年收益率（基于复权净值）；**场内 ETF 必须用 `fund_daily` + `apply_etf_adj` 复权**（`daily` 接口对 ETF 返回空，且不复权价在份额拆分时严重失真） |
| 3 | 业绩指标 | 基于 `fund_nav`/`fund_daily` 计算 | 年化波动率、夏普比率、最大回撤 |
| 4 | 同类对比 | `fund_basic`(筛同类型)、`fund_daily`/`fund_nav`(逐只) | 同类排名（近 20/60/120/250 日分位）；ETF 优先选同后缀场内基金对比，按成立日期排序优先选上市早的 |
| 5 | 基金经理 | `fund_manager` | 任职起始日、任职年限 |
| 6 | 持仓分析 | `fund_portfolio` | 前十大重仓股及占比（`stk_mkv_ratio`）、补充股票名称；字段为 `symbol`/`mkv`/`stk_mkv_ratio`（非 name/ratio/market_val） |
| 7 | 规模变化 | `fund_share` | 按季度采样（`groupby` 季度末），近4季份额变化趋势 |
| 8 | 分红 | `fund_div` | 累计分红次数、分红金额；字段为 `ex_date`/`div_cash`（非 div_date） |
| 9 | 风险提示 | 汇总以上维度 | 回撤较深/波动偏高/份额缩水等风险信号 |

> **份额口径声明（规模变化/同类对比维度的评价句必写）**：`fund_share.fd_share` 为**单只基金**份额。同一指数常有场内 ETF + 场外联接 + 多只跟踪基金并存（如名称含"沪深300"的基金几十只），份额/规模数据均为单只口径，不得表述为"该指数全部基金合计"。评价句必须注明是"XX基金单只份额"还是"场内外合计"，避免用户误读为指数整体规模。
### 四、期货（默认 7 维）

| # | 维度 | 数据接口 | 关键分析指标 |
|---|------|---------|------------|
| 1 | 概况 | `fut_basic` | 合约标的、交易所、合约乘数、最小变动价位、交易单位、保证金率 |
| 2 | 行情趋势 | `fut_daily`（主力连续合约如 `JM.DCE`/`RB.SHF`，非具体合约） | 近 20/60 日涨跌幅、结算价走势、日内振幅、波动率 |
| 3 | 持仓分析 | `fut_holding` | 持仓量变化、成交量/持仓量比、前 20 会员持仓多空比 |
| 4 | 主力合约 | `fut_mapping` | 主力合约代码、换月日期、基差（现货 vs 期货） |
| 5 | 仓单库存 | `fut_wsr` | 注册仓单量变化、库存/消费比 |
| 6 | 结算参数 | `fut_settle` | 当日结算价、交割结算价、保证金调整 |
| 7 | 风险提示 | 汇总以上维度 | 波动偏高/换月跳空/持仓异常等风险信号 |

## 报告结构
每份分析报告输出为独立 HTML 文件（浏览器直接打开，时间序列图表内联在各维度章节内）。内容结构如下，每个维度按 **描述句 → 数据表 → 分析评价** 的格式，最后附整体分析评价：

```markdown
# 标的名称 全景研究报告

> 数据日期：YYYY-MM-DD（Tushare 数据为 T-1 日）

## 1. 概况
描述句（如：银行ETF，华宝基金发行，跟踪中证银行指数，规模居同类前列）
- 关键指标汇总表

## 2. 行情趋势
描述句（近20日涨跌幅、波动率、回撤等核心指标概述）
- 涨跌幅对比表（标的 vs 沪深300并列）
- 风控指标对比表（波动率/回撤/夏普 vs 基准）
- 技术指标表（MACD/RSI/KDJ/布林带合并一张表）
- 进阶量化指标（Beta/Alpha/Sortino/滚动Beta/RS/VaR等）
- **分析评价**：对本维度数据的解读，包含明确的投资参考含义

## 3. 估值分析
描述句（PE/PB/历史分位等概述）
- 估值指标表
- 行业截面估值对比表（如适用）
- **分析评价**：（如"PE历史分位23.7%偏低，PB低于行业中位数，估值需结合业绩增速判断"）

## N. 风险提示
- 风险信号 1
- 风险信号 2
- 数据缺失说明（如有维度失败）

## N+1. 整体分析评价
**综合判断**：一句话定位标的特征标签（如"低估值、防御型、高股息"）
- 分维度要点列表（趋势/估值/财务/资金/筹码/杠杆/宏观各一行）
**风格定位**：标的属于什么风格型资产
**结论**：综合各维度给出投资参考含义和适用场景

---
*本报告由AI基于山西证券Tushare平台数据自动生成，基于 T-1 日历史数据，仅供技术交流与学习参考，不构成任何投资建议或财务指导。*
```

每维度分析评价必须包含对投资者的明确参考含义（如"估值处于历史低位，但需结合行业景气度判断"），而非罗列数据。
---
*本报告由AI基于山西证券Tushare平台数据自动生成，基于 T-1 日历史数据，仅供技术交流与学习参考，不构成任何投资建议或财务指导。*
```

多列数据示例（列数必须对齐，如份额一栏拆成两列）：

| 标的 | 最新份额 | 份额变化 |
|------|---------|---------|
| 沪深300ETF | 248亿份 | -0.1% |

每维度分析评价必须包含对投资者的明确参考含义（如"估值处于历史低位，但需结合行业景气度判断"），而非罗列数据。

**报告表格约束**：每个 markdown 表格的表头行与数据行的列数必须一致。如果一列有多项数据（如"份额 + 变化率"），要么拆成两列分别填入，要么合并到一列中并调整表头，避免出现空列。
**表格合并建议**：同一维度内的数据优先合并为一张表（如涨跌幅 + 风控指标 + 技术指标合并），避免拆成多个独立表格造成视觉割裂。若列数过多导致横向过长，可分组但需紧邻排列。

## 关键默认值

| 模糊中文 | 默认口径 |
|---------|---------|
| "最近"/"近期" | 近 20 个交易日 |
| "最近三个月" | 近 60 个交易日 |
| "今年" | 当年 1 月 1 日至今 |
| "历史"（股票/指数） | 近 3 年 |
| "历史"（基金） | 成立以来 |
| 证券代码 | 标准 `600519.SH` 格式 |
| 基金代码 | 场外 `.OF`，场内 `.SZ`/`.SH` |
| 期货代码 | 标准 `RB2501.SHF` 格式 |
| 行业分类 | 申万 2021 版 |
| 对比基准（股票） | 所属申万一级行业均值 |
| 对比基准（基金） | 同类基金（同类型+同投资方向） |
| 对比基准（指数） | 沪深 300（000300.SH） |

> **数据充分性**：取数时按最大周期（如"近 250 日"）再往前多取 30 个交易日，确保有足够数据计算。寒武纪从 20250801 到 20260812 仅 249 个交易日，不足以计算近 250 日涨跌幅，此时应前移起始日期（如 `start_date = '20250601'`）获取更多数据，或降级为"近 120 日"并标注"数据不足"。
> **数据不足时的报告处理**：若某标的上市不足请求周期（如具体期货合约仅 197 日不足 250 日），则：
> 1. **优先改用主力连续合约**（期货场景）或前移 start_date（股票场景）补充数据
> 2. 若仍不足，计算自上市以来的全长收益率，标注为"数据不足(仅 N 日,自上市 X%)"
> 3. 不可直接显示 N/A——用户无法判断是数据问题还是计算结果问题

## 量化分析方法

### 纵向对比（单标的时间序列）

单标的历史走势分析必须消除除权除息（送股/转增/分红/配股）导致的价格跳变，否则区间收益率和技术指标会失真。

- **股票复权**：`daily` 返回的是**未复权**数据（含除权除息跳变），趋势/收益率/技术指标计算前**必须复权**，否则除权日会产生虚假跳空。取 `adj_factor` 自行计算：
  - 后复权价 = 原始价 × 当日复权因子（`apply_adj_factor` 一并复权 open/high/low/close/pre_close，`*_post` 列同 scale，可安全用于 OHLC 类指标如 KDJ/布林带）
  - 前复权价 = 原始价 × 当日复权因子 / 最新复权因子
  - 长期收益率、定投收益、回撤、技术指标均应基于复权价；⚠️ 切勿用 `close_post` 配合未复权的 `high/low`——scale 不一致会令 KDJ 等指标失真
- **基金复权**：`fund_nav` 返回单位净值和累计净值。计算区间收益率时用 `fund_adj` 复权因子构建复权净值序列，消除分红除权影响：
  - 复权净值 = 单位净值 × 当日复权因子 / 最新复权因子
  - 夏普、最大回撤、Calmar 等指标均基于复权净值序列计算
- **ETF 复权**：`fund_daily` 返回的是不复权价，`apply_etf_adj`（`fund_adj` 因子）产出 `close_post`。**ETF 的 `fund_adj` 因子口径与股票 `adj_factor` 不同（实测方向/量级不统一，如 510500 ~0.34、512100 ~0.373、510300 ~1.27），`close_post` 绝对值非后复权价，仅供收益/夏普/回撤等 scale-invariant 计算（全程同列 pct_change 与因子绝对值无关）；展示价用未复权 `close`。** 股票 `adj_factor` 则是标准后复权因子（单调递增，`后复权价=原始价×adj_factor`，可展示）。`apply_*_adj` 返回 trade_date/nav_date 索引的 df，可直接喂给 `rebase_series`/`compare_returns`（二者校验日期索引，传整数索引会抛 TypeError）。
  - **函数选型**：`apply_etf_adj` **只复权 close**（产出 close_post，供收益/夏普/回撤）；KDJ/布林带等需 high/low/close 同 scale 的 OHLC 类指标，**改用 `apply_adj_factor`**（它复权全部 open/high/low/close/pre_close，`*_post` 列同 scale，fund_daily 同样适用）。误用 `apply_etf_adj` 喂 KDJ 会因 high_post/low_post 不存在而 KeyError。
- **基金规模取数**：`fund_nav.total_netasset` 是季报口径（稀疏，多为 NaN），仅作季度规模快照；需连续日度规模时用 `fund_share.fd_share`（万份）× `fund_nav.unit_nav` 计算：`规模亿元 = fd_share × unit_nav / 1e4`（先按 trade_date 对齐）。`fund_nav` 同 nav_date 可能有重复行，使用前按 nav_date 去重。
- **期货连续合约**：期货存在换月跳空，纵向分析时用 `fut_mapping` 识别主力合约区间，跨主力合约的连续走势需拼接或用 `fut_daily` 按合约分段分析，不得简单拼接。

### 横向对比（多标的归一化）

多标的横向对比时，不同标的价格量纲不同（如茅台 1500 元 vs 农业银行 4 元），直接比较价格序列无意义，必须归一化。

- **序列归一化（rebase）**：将各标的复权价格序列统一缩放到基准日 = 100，公式：`归一化净值 = 当日复权价 / 基准日复权价 × 100`。基准日取对比区间起点，使得所有标的从同一起跑线出发。
- **收益率对比**：计算各标的同期收益率（近 1 月/3 月/6 月/1 年/YTD），放同一张表横向排序。
- **估值分位数对比**：不同标的 PE/PB 不可直接比绝对值（行业属性不同），应转换为各自近 5 年历史分位数，再横排对比。跨标的截面均值/分位计算前，对截面值先 `winsorize_cross_section` 去极值（MAD 3σ）或直接取截面中位数，避免单只异常股拉偏；估值优先给"历史分位 + 同业截面分位"双口径（`valuation_percentiles`）。
- **财务指标对比**：ROE、毛利率等已是比率指标，可直接横排；营收/利润等绝对值指标应转换为增速（YoY/QoQ）或人均值后再对比。
- **波动率/回撤对比**：年化波动率、最大回撤本身量纲统一，可直接横排；但夏普比率等需确认无风险利率口径一致。

### 进阶量化指标

在基础指标之上，以下方法用于提升分析的深度与科学性：

- **技术指标**：MACD（趋势动能/金叉死叉）、RSI（超买>70/超卖<30）、KDJ（随机指标）、布林带（波动区间/触及上下轨）。MA 单独不足以判断买卖时机，技术指标组合可提供更丰富的信号。
- **历史分位数**：当前 PE/PB 等估值指标在近 5 年历史序列中的百分位排名（`percentile_rank`）。85 分位 = 当前估值高于历史 85% 的时间 → 偏高。
- **Sortino 比率**：夏普的改进版，分母仅用下行波动（仅亏损日的波动率），对不对称收益分布更合理。适合评估基金下行风险控制能力。
- **信息比率（IR）**：超额收益年化 / 跟踪误差年化。衡量基金经理主动选股能力，IR > 0.5 为优秀。
- **Piotroski F-Score**：9 项财务健康量化打分——盈利能力(ROA>0、经营现金流>0、ΔROA>0、经营现金流>净利润)、杠杆/流动/融资(Δ资产负债率≤0、Δ流动比率>0、未新增股本)、运营效率(Δ毛利率>0、Δ总资产周转率>0)，总分 0-9，≥7 为强，≤2 为弱。按年报(end_date 1231)去重后取最近 2 期同比，数据来自 `fina_indicator`/`income`/`cashflow`/`balancesheet`(可选)。
- **量价分析**：OBV（能量潮，价升量增=趋势健康）、量比（当日量/近 5 日均量，>2 放量/<0.5 缩量）、量价背离（价升量缩=顶部信号/价跌量缩=底部信号）。
- **Beta/Alpha 归因**：CAPM 回归分解，Beta = 个股对市场的敏感度（>1.2 高弹性/<0.8 防御型），Alpha = 扣除市场收益后的超额收益年化。需取个股与沪深 300 同期日收益率对齐回归。

### 风险建模与分布分析

- **VaR/CVaR（在险价值）**：历史法计算 95%/99% 置信水平的最大日亏损。VaR = 损失分位数，CVaR = 超过 VaR 的平均损失（更保守）。是风险管理的国际标准指标。
- **尾部风险（偏度/峰度）**：偏度 < 0 = 左偏（亏损侧尾部更长，崩盘风险大）；峰度 > 0（超额）= 厚尾（极端事件概率高于正态假设）。两者结合可判断收益分布是否偏离正态。
- **回撤深度分析**：在最大回撤之外，补充回撤持续期（水下天数）、痛苦指数（平均回撤深度），衡量"被套牢"的实际体感。
- **Amihud 非流动性**：|日收益率| / 日成交额，衡量单位资金引起的价格变动。值大 = 流动性差，大资金进出成本高。

### 滚动分析与动态监控

- **滚动 Beta**：60 日滚动窗口计算 Beta 变化趋势，展示市场敏感度随时间演变（上升 = 波动加大或防御减弱）。
- **滚动夏普**：60 日滚动窗口的风险调整收益趋势，比单点夏普更能反映稳定性。
- **相对强度（RS）**：标的累计收益 / 基准累计收益，RS > 1 跑赢、< 1 跑输，趋势走强 = 相对优势扩大。

### 统计检验方法

- **Z-Score 标准化**：将指标转为与群体均值的标准差倍数。|Z| > 1.96 = 在 5% 显著性水平下显著偏离。用于跨标的估值/财务指标对比。
- **事件研究法**：估计窗口（事件前 30 日）用市场模型回归估算正常收益，事件窗口（后 10 日）计算异常收益 AR 与累计异常收益 CAR。CAR > 2% = 事件正向显著。适用于财报发布、解禁、增减持等事件冲击分析。
- **CAGR（复合年化增长率）**：基于持有天数精确年化，比简单区间收益率更适合跨周期对比。

## 分析原则

1. **结论先行**：每个维度先写结论句，再给数据，不要只列数据让用户自己判断。
2. **交叉验证**：单一维度信号不充分时，结合多个维度交叉判断（如"资金面流入但估值已高"）。
3. **数据时效**：Tushare 数据为 T-1 日，报告顶部注明数据日期。
4. **风险汇总独立成节**：**风险提示必须在报告末尾单独一节**，清晰列出。"前置"指分析过程中随时收集风险信号、最终在末尾汇总呈现，二者不矛盾。
5. **不替用户决策**：分析结论用"表明""反映""风险信号"等描述性语言，不用"建议买入/卖出"。
6. **空结果处理**：空结果不一定是失败——可能是非交易日/标未上市/参数错误/权限不足。区分清楚再下结论。

## 维度状态与部分失败策略

每个维度执行后必须标注以下四态之一，并在报告中体现：

| 状态 | 含义 | 处理 |
|------|------|------|
| `success` | 取数 + 计算均成功 | 正常输出结论与数据表 |
| `empty` | 接口返回空（非交易日/标的未覆盖/无业务） | 该维度标注"无数据（原因）"并跳过，不阻断报告 |
| `permission_denied` | 接口提示无权限/配额不足 | 该维度标注"权限不足"，跳过并提示用户，不伪造数据，不终止整份报告 |
| `insufficient_history` | 历史数据不足请求周期 | 降级为可用区间（如近 120 日）并标注"数据不足(仅 N 日)"，不直接显示 N/A |

**部分失败原则**：单个维度失败不终止整份报告——已成功的维度照常输出，失败维度按上表降级或跳过，并在"整体分析评价"中说明哪些维度缺失及对结论可信度的影响。仅当核心维度（行情趋势/估值）全部失败时才终止并提示用户。

## 分析反模式（禁止）

- **前视偏差（look-ahead bias）**：计算任何时点指标时，只能用该时点及之前的数据；禁止用未来期财报/未来价格反推当前结论。
- **幸存者偏差**：回看历史表现时，不得只统计仍上市标的，忽略已退市/停牌标的；对比同类时需说明样本是否含退市。
- **报告发布日期泄露**：财报有 `ann_date`（公告日）与 `end_date`（报告期）之别；时点对齐必须用 `ann_date`（公告后才可用），禁止用 `end_date` 当作可用日，否则会"提前"看到未公布的财报。
- **过期业绩预告当最新**：`forecast` 返回该公司**所有历史预告**（按 `ann_date` 窗口筛选），若此后未再发新预告，最新一条可能已很旧。展示必须标注**报告期 + 公告日**；距公告日超 150 天未更新须标注"可能已过期"，且不得用它驱动当前的风险/结论信号。
- **基准选择偏差**：对比基准须与标的口径匹配（股票对所属申万一级、指数对沪深 300、基金对同类），不得随意选有利基准美化结论。
- **相关性当因果**：户数变化、资金流向、技术信号与涨跌仅为相关性，禁止表述为"主力在吸筹/派发""必然上涨/下跌"等因果结论。


## 接口调用规则

- 每次调用前必须查 `shanxi-securities-tushare/references/API接口对应表.md` 确认接口名和文档路径。
- 环境校验走 `python shanxi-securities-tushare/scripts/check_env.py`。
- 取数统一走 `sxsc-tushare-analysis/scripts/data_api.py` 的 `DataAPI` 类（SDK/HTTP 双模式自动选择，内置 T-0 占位行过滤、安全调用）。
  - 各 Runner 通过 `DataAPI` 实例调用接口，如 `api.get_daily(ts_code, start, end)`。
  - 日期推算用 `data_api.shift_date(end_date, -n_days)` 回溯交易日。
- 分析计算参考 `sxsc-tushare-analysis/scripts/` 下按方法分模块的参考模板：
  - `basic_metrics.py` — 收益率/MA/波动率/回撤/夏普/Sortino/IR/财务趋势/风险信号
  - `adjustment.py` — 复权处理/序列归一化/收益率对比/历史分位数/Z-Score/`clean_panel`(清洗)/`winsorize_cross_section`(截面去极值)/`valuation_percentiles`(双口径分位)
  - `technical_indicators.py` — MACD/RSI/KDJ/布林带/OBV/量比
  - `risk_modeling.py` — VaR/CVaR/尾部风险/回撤深度/Amihud/滚动Beta/滚动夏普/RS
  - `attribution.py` — CAPM Beta-Alpha/Piotroski F-Score/事件研究法
  - `composite.py` — 跨维度组合分析：技术共振/量价模式/多因子综合评分/三维定位/业绩拐点/配对相对价值/风险预算/筹码-股价交叉
- **字段单位注意**：各接口字段单位不同，取数后必须确认字段含义与单位再计算。常见单位差异：
  - `moneyflow` 的 `*_amount` 字段单位为**万元**，换算亿元需 `/1e4`
  - `daily` 的 `amount` 字段单位为**千元**（即元×1000），换算亿元需 `/1e5`
  - `daily_basic` 的 `total_mv` 字段单位为**万元**，换算亿元需 `/1e4`
  - `margin_detail` 的 `rzye` 字段单位为**元**，换算亿元需 `/1e8`
  - `fund_share` 的 `fd_share` 字段单位为**万份**，换算亿份需 `/1e4`
  - 其他接口以对应接口文档标注为准，不得猜单位
- **场内基金（ETF）特殊处理**：
  - 取数必须用 `fund_daily` 接口（`daily` 对 ETF 返回空）
  - 价格必须用 `apply_etf_adj` 复权（`fund_adj` 复权因子校正），否则份额拆分/分红会导致不复权价严重失真
  - 基金接口字段名与股票不同，**必须查文档确认**（如 `fund_manager` 字段是 `name` 非 `manager_name`，`fund_div` 字段是 `div_cash` 非 `div_amount`）
- **指数成分权重注意**：
  - `index_weight` 的入参是 `index_code`（非 ts_code），输出字段为 `trade_date`/`con_code`/`weight`，无 `con_name` 字段——需用 `con_code` 调 `stock_basic` 获取名称
  - `index_weight` 为**月度数据**（月末发布）：取数需用**整月范围**（`start_date`=月初、`end_date`=月末），半月范围或未发布月份返回空；取最新一期权重：先按 `trade_date` 降序取最大日期，再按 `weight` 降序取前 N 行
- **期货接口注意**：
  - 上期所交易所代码是 `SHFE`（非 SHF），大商所是 `DCE`，郑商所 `CZCE`，中金所 `CFFEX`
  - **期货分析必须用主力连续合约**（`fut_basic` 的 `fut_type='2'`，合约代码如 `JM.DCE`/`RB.SHF`），而非具体合约（如 `JM2610.DCE`）。具体合约仅上市约 10 个月（~200 日），不足 250 个交易日；主力连续合约拼接了各时期主力合约，有足够历史数据，且消除换月跳空。
  - 主力合约查询：`fut_mapping` 可能返回空，需用 `fut_basic(exchange=..., fut_type='2')` 获取连续合约代码
  - `fut_holding` 仅覆盖大商所（DCE）合约，SHFE 螺纹钢等无持仓排名数据，需在报告中注明接口覆盖限制
- **北交所股票特殊处理**：
  - 代码后缀为 `.BJ`（如 `920575.BJ`），区别于沪深主板
  - `moneyflow`（个股资金流向）接口不覆盖北交所，资金面维度不可用，需在报告中注明
  - `margin_detail`（融资融券明细）接口对北交所股票通常无数据，两融维度不可用
  - 北交所股票流动性通常低于沪深主板，分析评价中需提示流动性风险
  - 其他接口（`daily`/`daily_basic`/`fina_indicator`/`stk_holdernumber` 等）正常可用
  - `fut_wsr` 用 `trade_date` + `symbol`（产品代码如 `JM`/`RB`），返回各仓库明细须按 `symbol` 汇总 `vol`；`ts_code` 参数无效
  - `fut_settle` 返回降序数据（最新在前），取最新行需 `iloc[0]`；最新交易日结算中时 settle/保证金率为 NaN，需 `dropna(subset=['settle'])` 取最近有值行
- **宏观/市场接口参数注意**（参数风格不统一，易错）：
  - `cn_cpi`/`cn_ppi` 用 `start_m`/`end_m`（**月份 YYYYMM，非 start_date/end_date**）；CPI 同比字段是 `nt_yoy`（非 nt_m），PPI 同比字段是 `ppi_yoy`（非 ppi）
  - `shibor_lpr` 用标准 `start_date`/`end_date`（与 cn_cpi/cn_ppi 不同，勿混用）
  - `margin`（全市场两融汇总）的交易所参数/字段是 `exchange_id`（非 `exchange`），`rzye` 单位为元
- **指数成分权重参数注意**：`index_weight` 的入参是 `index_code`（**非 ts_code**，传 ts_code 会报 "index_code required"）；输出字段为 `trade_date`/`con_code`/`weight`
- 日期格式统一 `YYYYMMDD`。
- 未来日期自动裁剪到最近可用日期并提示用户。
- **T-0 占位行处理**：Tushare 数据为 T-1，`end_date` 传当天时行情接口（`daily`/`fund_daily`/`index_daily` 等）会返回当天行但全字段为 NaN（T-0 数据未出）。取数后必须 `dropna(subset=['close'])` 去掉占位行，否则 `iloc[-1]` 取到 NaN 导致后续计算全错。
- **交易日计数**："近 N 个交易日"需调 `trade_cal` 获取交易日历，按实际交易日回溯，不得按自然日估算。
- **数据排序规范**：所有 `pro.*` 接口均返回**降序**数据（最新在前），包括 `index_daily`、`daily`、`index_global`、`fut_settle` 等。**任何涉及 `iloc[-1]`（取最新）或区间涨跌幅的计算前，必须先 `.sort_values('trade_date')` 确认升序**，否则取到的日期方向相反，导致结论方向错误。取数函数（如 `get_daily_for_period`）已内置排序，但直接调用 `pro.*` 时必须自行处理。

## 边缘情况处理

- **ST/*ST 股票**：2026-07-06 起 ST 股涨跌停幅度已调整为 10%（与普通股一致），此前为 5%；分析涨跌停维度时需注意日期界限，`stk_limit` 返回的涨停价会体现对应时期的幅度。
- **次新股/上市不足 1 年**：历史数据不足 250 个交易日时，MA250、年化波动率等指标不可用或不稳定，应标注"数据不足"并降级为可用区间（如近 60 日）。
- **停复牌**：停牌期间价格序列出现断裂，`suspend_d` 接口可查停复牌记录；计算收益率/MA 时需跳过停牌日，不得用停牌前价格填充。
- **数据质量异常**：如 `fund_portfolio` 返回 ratio 全为 0（IPO 打新微量持仓等场景），应标注"数据异常"而非当作正常持仓分析。

## What this skill is NOT for

- 买卖建议、替代投资顾问
- 自动下单或交易执行
- 实时行情（仅 T-1 日数据）
- 回测引擎、组合优化系统的实现
- 公告/新闻/研报直连数据（应告知限制，建议改查价格异动、资金流等替代）
- 无 token / 无权限时伪造数据

## 依赖

- `shanxi-securities-tushare` 数据 skill（必须在本项目同级目录下）
- 环境变量 `SXSC_TUSHARE_TOKEN` 已配置
- `sxsc_tushare` 库或 HTTP 协议通道（按环境校验结果自动选择）