ths-advanced-analysis

# THS Advanced Analysis Skill

## 对话引导规范

### 澄清意图（意图模糊时必问）

| 用户说 | 可能的意图 | 必问 |
|--------|-----------|------|
| "帮我看看XX股票" | 实时行情？K线？大单？ | ✅ |
| "分析一下XX" | 技术面？资金面？和谁对比？ | ✅ |
| "XX板块怎么样" | 整体涨跌？成分股？领涨股？ | ✅ |
| "选一些好股票" | 短线？价值？哪个行业？条件？ | ✅ |
| "XX的5分钟K线" | 意图明确 | ❌ 直接执行 |
| "今日涨停股" | 意图明确 | ❌ 直接执行 |

**话术示例：**
```
用户："帮我分析一下宁德时代"
Claude："好的，请问你主要想看哪个方向？
  1. 今日实时行情 + 资金流向
  2. 分钟K线（盘中走势）
  3. 近期日K线趋势
  4. 和比亚迪、亿纬锂能等对比
  5. 用问财筛选相关概念股"
```

### 调用后的后续提示（有延伸价值时才提）

| 场景 | 提示 |
|------|------|
| 展示行业排名 | "需要查某个行业的成分股行情吗？" |
| 展示分钟K线 | "需要同时看大单流向或盘口深度吗？" |
| 展示多股对比表格 | "需要展示归一化走势图或相关性吗？" |
| 问财选出候选股 | "需要对这些股票做K线技术验证吗？" |
| 展示竞价异动 | "需要对某只异动股拉盘前分时看细节吗？" |

---

## 完整调用案例

| 文件 | 场景 |
|------|------|
| `examples/01_minute_kline.py` | 分钟K线 + 均线 + 成交量异动标注 |
| `examples/02_sector_industry.py` | 行业排名 + 概念板块成分股 + 指数行情 |
| `examples/03_multi_stock_compare.py` | 多股批量对比：表格 + 归一化走势 + 相关性 |
| `examples/04_bigorder_auction.py` | 大单流向 + 竞价异动扫描 + 分时/盘口 + 资讯 |
| `examples/05_wencai_nlp.py` | 问财NLP：选股/行情/财务/技术/复杂组合 |

---

## 场景速查

| 用户需求 | 方法 |
|---------|------|
| 今日涨停/连板/竞价强势股 | `wencai_nlp("今日涨停，非ST")` |
| 财务选股（ROE/PE/PB） | `wencai_nlp("连续3年ROE大于15%，非ST")` |
| 技术形态选股 | `wencai_nlp("均线多头排列，MACD金叉")` |
| 分钟K线 | `klines(code, interval="5m", count=78)` |
| 今日分时 | `intraday_data(code)` |
| 历史某日分时 | `min_snapshot(code, date="20250101")` |
| 五档盘口 | `depth(code)` |
| 买方/卖方深度详情 | `order_book_bid(code)` / `order_book_ask(code)` |
| 大单流向 | `big_order_flow(code)` |
| 竞价异动扫描 | `call_auction_anomaly("USHA")` |
| 申万行业列表 | `ths_industry()` |
| 概念板块列表 | `ths_concept()` |
| 板块行情（涨幅/市值） | `market_data_block(link_code)` |
| 板块成分股 | `block_constituents(link_code)` |
| 指数行情 | `market_data_index(ths_code)` |
| 多股票对比 | 批量 `market_data_cn` + `klines` |
| 港股行情 | `market_data_hk(code)` |
| 美股行情 | `market_data_us(code)` |
| 外汇汇率 | `market_data_forex(code)` |
| 期货行情 | `market_data_future(code)` |
| 实时资讯/快讯 | `news()` |
| 权息资料 | `corporate_action(code)` |
| 今日IPO / 待申购 | `ipo_today()` / `ipo_wait()` |

---

## 安装

```bash
pip install --upgrade thsdk
```

> 包来源：[PyPI](https://pypi.org/project/thsdk/)
> 系统要求：Python 3.9+，支持 Linux(x86_64/arm64)、macOS(Intel/Apple Silicon)、Windows

---

## 连接

```python
from thsdk import THS

with THS() as ths:   # 游客模式，无需账户配置
    ...
```

---

## 第一步：代码解析

所有中文名/缩写/短代码先用 `search_symbols` 获得完整 THSCODE：

```python
with THS() as ths:
    resp = ths.search_symbols("同花顺")
    # data → [
    #   {'THSCODE': 'USZA300033', 'Name': '同花顺',
    #    'MarketStr': 'USZA', 'Code': '300033', 'MarketDisplay': '深A'},
    #   {'THSCODE': 'URFI883404', 'Name': '同花顺情绪指数', 'MarketDisplay': '同指'},
    # ]
```

**选码规则：**

| 情况 | 处理 |
|------|-----|
| 0条 | 告知未找到 |
| 1条 | 直接使用 |
| 多条，只有1只A股（MarketDisplay含"沪A"或"深A"） | 自动选A股 |
| 多条，多只A股 | 展示列表，等用户选择 |

**市场前缀说明：**

| 前缀 | 含义 |
|------|------|
| `USHA` | 上海A股 |
| `USZA` | 深圳A股 |
| `USHI` | 上海指数 |
| `USZI` | 深圳指数 |
| `USTM` | 北交所 |
| `UHKG` | 港股 |
| `URFI` | 行业/概念板块 |
| `UFXB` | 外汇（基本汇率） |

**常用指数 THSCODE（直接使用，无需 search_symbols）：**

| 指数 | THSCODE |
|------|---------|
| 上证指数 | `USHI000001` |
| 深证成指 | `USZI399001` |
| 创业板指 | `USZI399006` |
| 科创50 | `USHI000688` |
| 沪深300 | `USHI000300` |
| 中证500 | `USHI000905` |
| 上证50 | `USHI000016` |

> ⚠️ 指数前缀是 `USHI`/`USZI`，需调用 `market_data_index`，不能用 `market_data_cn`

---

## K线数据

**interval 参数：** `"1m"` / `"5m"` / `"15m"` / `"30m"` / `"60m"` / `"120m"` / `"day"` / `"week"` / `"month"` / `"quarter"` / `"year"`

> ⚠️ 必须写 `"5m"`，不能写 `"5min"`

**count 与 start/end 二选一，不可混用：**

```python
from datetime import datetime
from zoneinfo import ZoneInfo
tz = ZoneInfo('Asia/Shanghai')

with THS() as ths:
    # 按条数
    resp = ths.klines("USZA300033", interval="5m", count=78)

    # 按时间范围
    resp = ths.klines("USZA300033", interval="day",
                      start_time=datetime(2025, 1, 1, tzinfo=tz),
                      end_time=datetime(2025, 3, 1, tzinfo=tz))

    # 前复权（量化回测用）
    resp = ths.klines("USHA600519", interval="day", count=250, adjust="forward")

    df = resp.df
    # 返回字段：时间, 收盘价, 成交量, 总金额, 开盘价, 最高价, 最低价
    # 分钟K线"时间"自动转为 datetime；日K"时间"为 datetime(YYYYMMDD)
```

---

## 分时与盘口数据

### 日内分时（当日）

```python
with THS() as ths:
    resp = ths.intraday_data("USZA300033")
    df = resp.df
    # 字段：时间(datetime+tz), 价格, 成交量, 总金额, 领先指标
```

### 历史分时（近一年）

```python
with THS() as ths:
    resp = ths.min_snapshot("USZA300033", date="20240315")
    df = resp.df
    # 字段：时间(timestamp), 价格, 成交量, 外盘成交量, 内盘成交量, 总金额
```

### 五档盘口

```python
with THS() as ths:
    resp = ths.depth("USZA300033")              # 单只
    resp = ths.depth(["USZA300033", "USHA600519"])  # 多只
    df = resp.df
    # 字段：买1~5价/量, 卖1~5价/量, 代码, 昨收价
```

### 买卖深度详情

```python
with THS() as ths:
    resp = ths.order_book_bid("USZA300033")   # 买方深度
    resp = ths.order_book_ask("USZA300033")   # 卖方深度
    df = resp.df
```

### 3秒 Tick

```python
with THS() as ths:
    resp = ths.tick_level1("USZA300033")
    df = resp.df
    # 字段：时间(timestamp), 价格, 成交方向, 交易笔数, 当前量
```

### 超级盘口（含委托档位）

```python
with THS() as ths:
    resp = ths.tick_super_level1("USZA300033")                   # 实时
    resp = ths.tick_super_level1("USZA300033", date="20240315")  # 历史
    df = resp.df
    # ⚠️ 部分字段值为 4294967295 表示无效数据，需过滤
```

---

## 大单与竞价

### 大单流向

```python
with THS() as ths:
    resp = ths.big_order_flow("USZA300033")
    df = resp.df
    # 字段：时间, 成交方向, 成交量, 总金额, 委托买入价, 委托卖出价
```

### 集合竞价异动（9:15~9:25）

```python
with THS() as ths:
    resp_sh = ths.call_auction_anomaly("USHA")   # 沪市
    resp_sz = ths.call_auction_anomaly("USZA")   # 深市
    df = resp_sh.df
    # 字段：时间, 价格, 总金额, 代码, 名称, 异动类型1(已映射中文)
    # 异动类型：涨停试盘/竞价抢筹/大幅高开/急速上涨/大买单试盘 等13种
```

### 早盘集合竞价快照

```python
with THS() as ths:
    resp = ths.call_auction("USZA300033")
    df = resp.df
    # 字段：时间, 成交方向, 成交量, 总金额, 委托买入价, 委托卖出价
```

---

## 板块与指数

### 行业/概念板块列表

```python
with THS() as ths:
    resp = ths.ths_industry()   # 同花顺行业，约90个
    resp = ths.ths_concept()    # 概念板块，约390个
    df = resp.df
    # ⚠️ 仅返回：代码(URFIXXXXXX), 名称
    # 涨幅/行情需另调 market_data_block(link_code)
    # extra['total_count'] = 板块总数
```

### 板块行情（两步走）

```python
with THS() as ths:
    # Step 1：获取板块列表
    resp = ths.ths_industry()
    target = next(r for r in resp.data if '半导体' in r['名称'])
    link_code = target['代码']   # 格式 URFIXXXXXX

    # Step 2：查板块行情
    resp = ths.market_data_block(link_code, "基础数据")
    df = resp.df
    # 字段：价格, 涨幅, 成交量, 板块总市值, 板块流通市值,
    #        上涨家数, 下跌家数, 领涨股
    # query_key 也支持 "扩展"（含板块涨速、主力净流入等）
```

### 板块成分股

```python
with THS() as ths:
    resp = ths.block_constituents("URFI883404")
    df = resp.df
    # 字段：代码(完整THSCODE), 名称
    # extra['total_count'] = 成分股总数
```

### 指数列表 & 行情

```python
with THS() as ths:
    # 全部指数列表（约580个）
    resp = ths.index_list()
    df = resp.df   # 字段：代码, 名称

    # 指数行情（单只或同市场批量）
    resp = ths.market_data_index("USHI000001")
    resp = ths.market_data_index(["USHI000001", "USHI000300", "USHI000905"])
    df = resp.df
    # 字段：价格, 涨幅, 涨跌, 成交量, 总金额, 最高价, 最低价
    # query_key 也支持 "扩展"（含量比、振幅等）
```

---

## A股行情（market_data_cn）

```python
with THS() as ths:
    resp = ths.market_data_cn("USZA300033", "基础数据")
    # 也支持列表（同市场）
    resp = ths.market_data_cn(["USZA300033", "USZA000001"], "汇总")
    df = resp.df
    # 基础数据字段：价格, 成交方向, 成交量, 交易笔数, 总金额,
    #               涨速, 当前量, 代码, 名称, 昨收价, 开盘价, 最高价, 最低价
```

**query_key 选项：**

| query_key | 含义 |
|-----------|------|
| `"基础数据"` | 价格、涨跌幅、成交量、金额、开高低、涨速 |
| `"基础数据2"` | 精简版基础数据 |
| `"基础数据3"` | 极简（价格、昨收、成交量） |
| `"扩展1"` | 涨幅、涨跌、换手率、量比、主力净流入、委比 |
| `"扩展2"` | 涨幅、换手率、总市值、流通市值、委比 |
| `"汇总"` | 全量字段，多股对比首选 |

> ⚠️ 同市场限制：USHA 和 USZA 不能在同一次调用中混合

---

## 多市场行情

### 港股

```python
with THS() as ths:
    # 港股列表
    resp = ths.stock_hk_lists()
    # 港股行情
    resp = ths.market_data_hk("UHKG00700", "基础数据")
    df = resp.df
    # query_key 支持："基础数据" / "每股净资产" / "净利润" / "财务指标"
```

### 美股 / 纳斯达克

```python
with THS() as ths:
    resp = ths.stock_us_lists()      # 美股列表
    resp = ths.nasdaq_lists()        # 纳斯达克列表
    resp = ths.market_data_us("UNQQAAPL", "基础数据")
    df = resp.df
    # query_key 支持："基础数据" / "每股净资产" / "每股收益" / "净利润" / "财务指标"
```

### 外汇

```python
with THS() as ths:
    resp = ths.forex_list()          # 外汇列表（约25个，UFXB前缀）
    resp = ths.market_data_forex("UFXBGBPUSD", "基础数据")
    df = resp.df
    # 字段：价格, 委托买入价, 委托卖出价, 代码, 名称, 昨收价, 开盘价, 最高价, 最低价
    # query_key 也支持 "扩展"
```

### 期货

```python
with THS() as ths:
    resp = ths.futures_lists()        # 主力合约列表
    resp = ths.market_data_future("UCFSAU2506", "基础数据")
    df = resp.df
    # query_key 支持："基础数据" / "日增仓" / "扩展"
```

### 债券 / ETF

```python
with THS() as ths:
    resp = ths.bond_lists()           # 可转债列表
    resp = ths.fund_etf_lists()       # ETF基金列表
    resp = ths.fund_etf_t0_lists()    # ETF T+0基金列表
    resp = ths.market_data_bond("USHD123456", "基础数据")
    resp = ths.market_data_fund("USHA510300", "基础数据")
```

---

## 多股票批量对比

```python
import pandas as pd
from collections import defaultdict
from thsdk import THS

stock_names = ["贵州茅台", "五粮液", "泸州老窖"]

with THS() as ths:
    # Step 1: 批量解析代码
    stock_codes = []
    for name in stock_names:
        resp = ths.search_symbols(name)
        a_shares = [s for s in resp.data
                    if any(m in s.get('MarketDisplay', '') for m in ['沪A', '深A'])]
        if a_shares:
            stock_codes.append({'name': name, 'code': a_shares[0]['THSCODE']})

    # Step 2: 按市场分组
    by_market = defaultdict(list)
    for s in stock_codes:
        by_market[s['code'][:4]].append(s)

    # Step 3: 批量行情
    rows = []
    for market, stocks in by_market.items():
        codes = [s['code'] for s in stocks]
        resp = ths.market_data_cn(codes, "汇总")
        for i, row in enumerate(resp.data):
            row['股票名称'] = stocks[i]['name']
            rows.append(row)
    quote_df = pd.DataFrame(rows)

    # Step 4: 批量K线
    klines_data = {}
    for s in stock_codes:
        resp = ths.klines(s['code'], interval="day", count=30, adjust="forward")
        klines_data[s['name']] = resp.df

# Step 5: 归一化走势（起点=100）
for name, df in klines_data.items():
    df['归一化'] = df['收盘价'] / df['收盘价'].iloc[0] * 100

# Step 6: 相关性矩阵
returns = pd.DataFrame({name: df['收盘价'].pct_change() for name, df in klines_data.items()})
corr_matrix = returns.corr()
```

**输出规范：**
1. 表格：股票 / 最新价 / 涨幅% / 成交额 / 换手率 / 量比 / 主力净流入 / 总市值
2. 归一化走势折线图（多线，颜色区分）
3. 相关性热力图（量化场景）

---

## 问财自然语言查询（wencai_nlp）

对接 iwencai.com 同一接口，多条件用逗号/分号分隔。

```python
with THS() as ths:
    resp = ths.wencai_nlp("连续3日主力净流入，换手率大于5%，非ST")
    df = resp.df
    # ⚠️ 股票代码格式为 "605366.SH"，需转换
```

**返回代码转换：**

```python
def to_ths_code(code_str: str) -> str:
    # wencai 返回：'300033.SZ' / '600519.SH' / '835975.BJ'
    try:
        code, market = str(code_str).split('.')
        mapping = {'SH': 'USHA', 'SZ': 'USZA', 'BJ': 'USTM'}
        prefix = mapping.get(market.upper(), '')
        return f"{prefix}{code}" if prefix else None
    except Exception:
        return None

df['ths_code'] = df['股票代码'].apply(to_ths_code)
```

**六大查询类型：**

**① 行情 & 盘面**
```python
"今日涨停，非ST"
"连续2日涨停，非一字板，非ST"
"今日涨停原因类别，涨停封单额，封单量"
"竞价涨幅大于3%，竞价量大于昨日成交量5%，非ST"
"主力净流入由大到小排名前20，非ST"
"近10日区间主力资金流向大于5000万，市值大于100亿"
```

**② 板块 & 行业**
```python
"今日申万行业涨跌幅排名"
"今日概念板块涨幅排名前20"
"人工智能概念股，今日涨跌幅，成交额，主力净流入"
"今日涨幅最大的5个概念板块，涨幅，成分股数量"
```

**③ 财务指标**
```python
"连续3年ROE大于15%，非ST，上市大于3年"
"市盈率小于15，股息率大于3%，市净率小于2，非ST"
"市净率小于1，非ST，流通市值大于20亿"
"连续5年分红，股息率大于4%，资产负债率小于60%"
```

**④ 技术形态**
```python
"均线多头排列，MACD金叉，换手率大于3%，非ST"
"均线粘合，平台突破，成交量大于5日均量1.5倍"
"仙人指路，非ST，非停牌"
"250日新高，非ST，沪深A，上市超过250天"
```

**⑤ 复杂组合**
```python
# 短线强势
"均线多头排列，MACD金叉，DIFF上穿中轴，换手率大于1%且小于10%，30日内有2个交易日涨幅大于4%，非ST"
# 竞价打板
"昨日非一字板涨停，今日竞价涨幅大于等于0%且小于等于9.9%，今日隔夜买单额小于10亿，非ST，非科创板"
```

**⑥ 信息查询**
```python
"涨停原因归类前20"
"今日龙虎榜"
"今日大宗交易"
"近一周北向资金净买入前20"
```

| 方法 | 用途 |
|------|------|
| `wencai_nlp(condition)` | **主要用法**。完整自然语言，返回股票列表+字段 |
| `wencai_base(condition)` | 简单字段查询，如 `"所属行业"` |

---

## 实时资讯（news）

```python
import re

with THS() as ths:
    resp = ths.news()   # 默认：上证指数相关快讯
    # 指定个股资讯：
    # resp = ths.news(text_id=0x3814, code="300033", market="USZA")

    for item in resp.data:
        props = dict(re.findall(r'(\w+)=([^\n]+)', item.get('Properties', '')))
        print(f"[{props.get('source','')}] {item['Title']}")
        print(f"  {props.get('summ','')}\n")
    # 字段：Op, Time(timestamp), Title, ID, Code, Stock, Properties
    # Properties 含：ctime, summ(摘要), source(来源)
```

---

## 其他实用 API

### 权息资料

```python
with THS() as ths:
    resp = ths.corporate_action("USZA300033")
    df = resp.df
    # 字段：时间(int YYYYMMDD), 权息资料(文字)
    # 示例：20100312 → "2010-03-12(每十股 转增10.00股 红利3.00元)$"
```

### IPO 数据

```python
with THS() as ths:
    resp = ths.ipo_today()   # 今日申购/上市
    resp = ths.ipo_wait()    # 待申购
    df = resp.df
    # 字段：stock_name, stock_code, order_date, issue_price,
    #       issue_pe_static, success_rate, order_limit_up,
    #       industry_name, exchange 等
```

### 市场列表

```python
with THS() as ths:
    resp = ths.stock_cn_lists()    # 全部A股（约5198只）
    resp = ths.stock_hk_lists()    # 港股
    resp = ths.stock_us_lists()    # 美股
    resp = ths.stock_bj_lists()    # 北交所
    resp = ths.nasdaq_lists()      # 纳斯达克
    resp = ths.stock_b_lists()     # B股
    resp = ths.bond_lists()        # 可转债
    resp = ths.fund_etf_lists()    # ETF基金
    resp = ths.fund_etf_t0_lists() # ETF T+0基金
    resp = ths.futures_lists()     # 期货主力合约
    resp = ths.forex_list()        # 外汇（约25个）
    df = resp.df   # 字段：代码(完整THSCODE), 名称
```

### 代码补全工具

```python
with THS() as ths:
    resp = ths.complete_ths_code("USZA300033")
    # 用于验证/补全代码信息
```

---

## 错误处理

```python
with THS() as ths:
    resp = ths.klines("USZA300033", interval="5m", count=60)
    if not resp:
        print(f"调用失败: {resp.error}")
    elif resp.df.empty:
        print("数据为空，可能是非交易时间")
    else:
        df = resp.df
```

**常见报错：**

| 错误 | 原因 | 解决 |
|------|------|------|
| `"未登录"` | 未 connect | 确保用 `with THS() as ths` |
| `"证券代码必须为10个字符"` | 格式错误 | 先过 `search_symbols` |
| `"一次性查询多支股票必须市场代码相同"` | 沪深混合 | 按市场分组查询 |
| `"无效的周期类型: 5min"` | interval 写法错 | 改为 `"5m"` |
| `"'count' 参数不能与 'start_time' 同时使用"` | 参数冲突 | 二选一 |

**注意事项：**
- 游客账户在部分专业数据/实时数据上可能有权限限制
- 批量拉取时建议加 `time.sleep(0.5)` 避免限流
- `THS` 为同步阻塞，在 FastAPI/asyncio 中需放入线程池

---

## 与 ths-financial-data 的分工

| 场景 | skill |
|------|-------|
| 单只A股行情/资金流向/日K | `ths-financial-data` |
| 分钟K线 / 盘中监控 | **本 skill** |
| 盘口深度 / 大单 / 竞价异动 | **本 skill** |
| 板块/指数行情及成分股 | **本 skill** |
| 多股票批量对比 | **本 skill** |
| 港股/美股/外汇/期货行情 | **本 skill** |
| 实时资讯快讯 | **本 skill** |
| 问财自然语言查询 | 两者均可 |