# cmesdata 常见问题排障

配合 [SKILL.md](SKILL.md)、[api-reference.md](api-reference.md)。  
原则：**先信报错原文**；失败时不编造数据、不调用非 `cmesdata` 接口顶替、不改包、不绕鉴权。

官网：https://cmes-data.com/api.html · 下载页 https://cmes-data.com/download.html?type=vip

---

## 0. 环境与安装（最先检查）

```bash
python -c "import cmesdata; print('cmesdata OK', getattr(cmesdata, '__file__', ''))"
```

若 `ModuleNotFoundError`：

1. 有权限时执行：`pip install cmesdata` 或 `python -m pip install cmesdata`  
2. 无权限时明确告知用户自行安装并验证。

未安装成功前，不要用其它库「先跑通」冒充 CMES。

---

## 0.1 用户未提供 token

- 需鉴权时主动问：「请提供您的 CMES token」。  
- 历史：`token_str=`；实时/tick/短历史/期货：`cs.login(token)`。  
- 不要用空串、假 token 演示「成功」。

---

## 1. 提示无权限 / 未开通 / 已到期

**常见文案**

- `您未开通接口权限或已到期，请先开通权限`
- `您未开通接口权限或已到期，请先开通期货权限`
- `请先使用token登录或先开通股票接口权限`
- 历史：`HistoryDataError` 含无权限、积分目录不符等

**处理**

1. token 完整、未过期；网站可查权限。  
2. 实时/tick/短历史：先 `login`，开通股票接口权限（https://cmes-data.com/api.html）。  
3. 期货推送：需期货权限；VIP 历史打包 ≠ 期货推送。  
4. 历史批量：VIP/SVIP 或对应积分目录；`symbol` 须在授权种类内。  
5. 不要建议改本地包跳过校验。

---

## 2. 获取不到实时行情（空表）与长连接

- `login` 后为**长连接**；同一进程复用，反复调 `get_real_hq` / `get_real_kzz`。  
- **不要频繁 login**；**不要**短进程「login → 取数 → 退出」拆连接。  
- 查：是否 login 返回 1？是否交易时段？代码前缀？列表是否过长/含错码停牌？网络是否拦长连接？  
- 非交易时段空表属预期，**禁止编造盘口**。

---

## 3. 历史下载失败 / 空表 / 跨年被裁

| 现象 | 可能原因 | 做法 |
|------|----------|------|
| `RateLimitError` / 「频繁」「请求处理中」 | 限流 | `sleep` 后重试；降并发 |
| `ValueError: 未知数据标识` | symbol 写错 | 对照 [api-catalog.md](api-catalog.md) 或下载页 |
| `ValueError: 请先提供 token` | 未传 token | 询问并传入 |
| `HistoryDataError` 无数据 | 代码/日期不对 | 先 `get_symbol_list` |
| 打印「不超过一个自然年」「已将区间裁剪」 | 分钟跨年被裁 | **按年多次请求**再 concat（见 SKILL.md） |
| 裁剪后空表 | 区间无 K 线 | 放宽日期 / 换交易日 |
| 仍写 before+behind | 旧文档习惯 | **已取消**双目录；勿再写分段逻辑 |

```python
import time
from cmesdata import RateLimitError, HistoryDataError
import cmesdata as cs

for i in range(5):
    try:
        df = cs.get_historical_data(
            'a_stock_1min', 'SH.600000', '2025-01-01', '2025-06-30', token_str='您的token',
        )
        break
    except RateLimitError:
        time.sleep(5 * (i + 1))
    except HistoryDataError as e:
        print(e)
        raise
```

---

## 4. 接口失败：自查 → 极简 demo

禁止捏造 DataFrame；禁止换 akshare/tushare 冒充。  
仍不明时写极简 demo **真实运行**，把源码 + 控制台交给用户：

```python
import cmesdata as cs
TOKEN = '请替换为真实token'
print('login =>', cs.login(TOKEN))
df = cs.get_history_data('SH.600000', '2025-06-01', '2025-06-02', 'D')
print(df.head() if hasattr(df, 'head') else df)
```

历史批量：

```python
try:
    df = cs.get_historical_data(
        'a_stock_1min', 'SH.600000', '2025-06-01', '2025-06-02', token_str=TOKEN,
    )
    print(df.head())
except Exception as e:
    print(type(e).__name__, ':', e)
```

---

## 5. login 失败或总要重新登录

- 成功一次即可，勿循环 login。  
- 限流：等待后重试。  
- 无 `autu_token`/`fu_autu_token`：未开通对应权限。

---

## 6. get_tick / get_history_data 空表

- 未 login 或权限不足。  
- `get_tick` 日期 `'YYYY-MM-DD'`。  
- 非交易日/错码 → 空表；勿造 tick。  
- 需要更长历史 → 用 `get_historical_data`，不要死磕短周期接口。

---

## 7. 日更 `get_update_data` 失败

- 核对近 N 日、`date`、`data_path` 可写。  
- 403/未开通：网站开通更新项。  
- 404：当日可能尚未更新。  
- 注意限流。

---

## 8. 期货推送无数据

1. login 成功且有期货权限。  
2. 先订阅再回调（或按官网顺序），主进程保持运行。  
3. 合约须有效；过期无推送属正常。  
4. 订阅码为交易所标准码（如 `rb2601`），勿与历史包名随意混用。

---

## 9. AI / 脚本协作禁忌

| 禁止 | 应做 |
|------|------|
| 失败后手写假行情 | 报错 + 自查 + 极简 demo |
| 换其它数据源顶替 CMES | 只用公开 `cs.*` |
| 未装库就「演示」 | 先安装或告知安装命令 |
| 不问 token 硬跑 | 主动询问 |
| 一次跨多年分钟却期望全量 | 按年循环 |
| 写 2025-before/behind | 已取消，用现行单根/年包规则 |

---

## 10. 仍无法解决时

请用户提供：完整报错、函数名、`symbol`、代码、是否 login、是否交易时段、极简 demo 真实输出。  
引导 https://cmes-data.com/api.html 核权限或联系客服；仍不得伪造数据或绕过系统。