---
name: cmesdata-api
description: >-
  Guides correct use of the CMES Python package cmesdata (历史下载、实时行情、日更、期货推送).
  Use when writing or debugging cmesdata / cs.login / get_historical_data / get_symbol_list /
  get_daily_pack / get_update_data / get_real_hq / get_tick / subscribe_future_code, or when
  the user reports 无权限、限流、拿不到实时行情、空表、RateLimitError、未安装 cmesdata、跨年分钟裁剪.
---

# CMES `cmesdata` 接口助手

面向用户侧 AI：只根据**本 Skill 已列接口**与**官网文档**帮用户写调用与排障代码。

安装：`pip install cmesdata`（或 `pip install -U cmesdata`）  
导入：`import cmesdata as cs`

---

## 官方文档网址（AI 必须先知道）

本 Skill **自带完整接口说明**（见下方「本包文件」）。若需对照官网页面或让用户自己打开文档，使用：

| 用途 | URL |
|------|-----|
| 官网首页 | https://cmes-data.com/ |
| **股票 / 期货接口介绍**（login、实时、短历史、tick、期货推送） | https://cmes-data.com/api.html |
| VIP 数据下载页（每类数据右侧有「数据接口」示例） | https://cmes-data.com/download.html?type=vip |
| SVIP 数据下载页 | https://cmes-data.com/download.html?type=svip |
| 积分数据下载页 | https://cmes-data.com/download.html?type=vwe |
| 本 Skill 在线版 SKILL.md | https://cmes-data.com/skill/cmesdata-api/SKILL.md |
| 本 Skill 接口详解（在线） | https://cmes-data.com/skill/cmesdata-api/api-reference.md |
| 本 Skill symbol 目录（在线） | https://cmes-data.com/skill/cmesdata-api/api-catalog.md |
| 本 Skill 排障（在线） | https://cmes-data.com/skill/cmesdata-api/troubleshooting.md |

**说明：**

- AI **优先读本包内 markdown**（离线可用，内容与官网规则一致）。  
- 需要核对某品种 `symbol` 示例时，打开对应 `download.html?type=...` 页面，在该类数据的「数据接口」区块查看。  
- **不要**臆造未列出的 HTTP 路径或内部函数；用户业务一律走 `cmesdata` 公开 API。

### 本包文件

| 文件 | 内容 |
|------|------|
| [SKILL.md](SKILL.md) | 红线、选型、流程（本文件） |
| [api-reference.md](api-reference.md) | **全部已发布接口的详细参数 / 返回 / 示例 / 注意** |
| [api-catalog.md](api-catalog.md) | 历史批量 `symbol` key 全表 |
| [troubleshooting.md](troubleshooting.md) | 安装、权限、限流、空表、跨年裁剪等排障 |

---

## 硬性红线（必须遵守）

1. **调用接口失败时，不能强行编造数据**  
   空表、异常、超时、无权限时：如实说明原因与下一步；禁止用假行情、假财报、随机数或「示例编造表」冒充接口返回。

2. **不能调用文档中未发布的接口**  
   只用 [api-reference.md](api-reference.md) 与官网写明的函数/参数。禁止：
   - 下划线开头的内部函数（如 `_download_named_data`、`_fetch_file_list`）
   - 自拼 Flask/HQ HTTP 路径绕过 SDK（除非官网明确给出 HTTP 文档）
   - 源码里存在但文档未写的实验函数
   - **任何不属于 `cmesdata` 的其它行情/数据接口**来顶替 CMES 结果

3. **不能篡改底层代码**  
   禁止改 `site-packages/cmesdata`、补丁鉴权、改 `debug` 指本地、替换 token 校验逻辑。用户环境只写**自己的业务脚本**。

4. **不能通过深入了解底层代码找破绽**  
   禁止为绕过 VIP/积分/限流去读服务端或客户端源码找漏洞、伪造权限、刷接口。排障只基于公开报错文案与本 Skill。

违反任一条：拒绝该做法，改走正规开通权限 / 修正参数 / 限流重试。

---

## 开始前必做

1. **检查是否已安装 `cmesdata`**（见 [troubleshooting.md](troubleshooting.md)）。未安装则 `pip install cmesdata`；无权限时明确告知用户自行安装。  
2. **用户未提供 token 时必须主动询问**：「请提供您的 CMES token（网站「我的」/权限页可查看）」。没有 token 不要假装已连通。  
3. 确认需求对应哪类接口（下表），再写代码；细节查 [api-reference.md](api-reference.md)。

---

## 接口怎么选（先定场景）

| 用户目标 | 用这些接口 | 是否要先 `login` |
|---------|------------|------------------|
| 下历史包 / 按代码拉一段 K 线（多数品种） | `get_symbol_list` → `get_historical_data`；按日总包用 `get_daily_pack` | 否（传 `token_str`） |
| 近几日增量更新 zip 落到本地目录 | `get_update_data` / `get_update_sym` | 否（传 `token_str`） |
| 沪深股票/可转债**实时五档** | `login` → `get_real_hq` / `get_real_kzz` | **是** |
| 单日分笔 tick | `login` → `get_tick` | **是** |
| 通达信风格历史 K（近约 5 个月短周期） | `login` → `get_history_data` / `get_index_data` | **是** |
| 国内期货主连推送 | `login` → `register_push_callback` → `subscribe_future_code` | **是**（需期货权限） |

历史批量下载的 `down_type` 在 SDK 内固定为「打包」通道；用户只需选对 **`symbol` key**（见 [api-catalog.md](api-catalog.md)）与代码/日期。

---

## 关键规则（2026 布局，必读）

1. **数据存储已统一为单根目录**，按品种扁平或 `{年份}/{code}.zip` 年包；**不再有** `2025-before` / `2025-behind` 双目录，也不要再写「分段 before+behind」逻辑。  
2. **分钟类大数据**（沪深/ETF/可转债/指数、期货主连、港美股、外汇、数字货币等带 `_1min`…`_60min` 的品种，以及 `vip_gg_min_*`）：  
   - **单次请求区间不超过一个自然年**；  
   - 跨年时接口会裁到起始年（例如请求 `2025-05-02`~`2026-03-02` → 实际 `2025-05-02`~`2025-12-31`），并打印提示；  
   - 需要多年请 **按年多次调用** 再自行拼接。  
3. 财务报表类（`*_finance_*`）一般返回全量，可不传日期裁剪。  
4. 实时行情为 **长连接**：进程内 `login` 一次即可；勿频繁 login、勿短进程反复拆连。

---

## 已发布接口速查

完整参数表、返回值、注意事项与样例：**一律以 [api-reference.md](api-reference.md) 为准**。下面仅作入口记忆：

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

# —— 需 login ——
cs.login('您的token')          # 返回 1 成功
cs.get_real_hq(['SH.600000'])
cs.get_real_kzz(['SH.110075'])
cs.get_tick('SZ.000001', '2025-11-17')
cs.get_history_data('SH.600000', '2025-01-01', '2025-01-31', 'D')
cs.get_index_data('SH.000001', '2025-01-01', '2025-01-31', '1min')
cs.register_push_callback(lambda df: print(df))
cs.subscribe_future_code(['ag2601'])
cs.login_out()

# —— 历史批量（可不 login，传 token_str）——
codes = cs.get_symbol_list('a_stock_1min', token_str='您的token')
df = cs.get_historical_data(
    'a_stock_1min', 'SH.600000', '2025-01-01', '2025-06-30', token_str='您的token',
)
df = cs.get_daily_pack('a_stock_daily', '20260522', token_str='您的token')
df = cs.get_daily_pack('fut_basic', token_str='您的token')  # 库内仅单包时可省略 date

# —— 日更落盘 ——
cs.get_update_data('a_stock_1min', '2026-06-01', data_path=r'D:\daily_update', token_str='您的token')
cs.get_update_sym('...', 'SYM', '2026-06-01', data_path=r'D:\daily_update', token_str='您的token')
cs.get_update_expiry('您的token', 'a_stock_1min')
```

跨年分钟示例（正确做法）：

```python
import pandas as pd
import cmesdata as cs

TOKEN = '您的token'
frames = []
for y0, y1 in [('2024-01-01', '2024-12-31'), ('2025-01-01', '2025-12-31')]:
    frames.append(cs.get_historical_data(
        'a_stock_1min', 'SH.600000', y0, y1, token_str=TOKEN,
    ))
df = pd.concat(frames, ignore_index=True)
```

---

## 调用失败时 AI 怎么做

1. 对照 [troubleshooting.md](troubleshooting.md) 自查（安装、token、symbol、login、交易时段、限流、跨年裁剪）。  
2. **禁止**捏造数据；**禁止**改调 akshare/tushare 等冒充 CMES。  
3. 仍不明：写极简 demo，真实运行后把 **demo + 报错/返回全文** 交给用户。  
4. 仍无解：引导查 https://cmes-data.com/api.html 权限或联系客服。

---

## AI 协助用户时的标准流程

1. 检查 `cmesdata` 是否已安装。  
2. 未给 token → **先问 token**。  
3. 定接口类型 → 打开 [api-reference.md](api-reference.md) 写最小示例。  
4. 分钟跨年 → 按年循环；捕获 `RateLimitError`。  
5. 失败则排障 → 极简 demo → 真实输出，不编造、不换库。

---

## 代码格式约定

- 向用户索取真实 token 用于本地调试；写入可分享文件时用占位符。  
- 风格：`import cmesdata as cs`。  
- 不要引入其它数据源假装 CMES 已接通，除非用户**明确**要求并对接其它数据商（须声明那不是 CMES）。