Vibe-Trading 实战：基于 Tushare kpl_list 接口的开盘啦打板榜单数据量化研究指南
【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading
开盘啦（KPL）榜单数据是短线打板研究的核心数据源之一。本指南以 Vibe-Trading 仓库内收录的 Tushare 打板专题接口文档为骨架，系统讲解kpl_list接口的限量与权限规则、全部输入/输出参数语义、实战调用范式与历史数据循环抓取方案，并结合仓库源码说明 Token 配置与数据源接入方式。读完本文，你将能在自己的量化研究环境中稳定、合规地拉取 A 股每日涨停、跌停、炸板、竞价等榜单快照，并落地为连板梯队、板块归因与资金强度分析。
一、接口概览：开盘啦榜单数据能做什么
kpl_list是 Tushare 数据源在股票数据-打板专题数据分类下提供的接口（接口 ID 347，见 Tushare 技能文档 的数据接口列表），其数据由知名打板 App开盘啦整理并授权提供。该接口的核心能力是：按交易日返回全市场涨停、跌停、炸板、自然涨停、竞价等维度的榜单明细，并附带每个标的的涨停时间、封单、竞价成交、主力净额、所属板块（theme）、涨停原因（lu_desc）、连板状态等打板研究必需的字段。
与同专题的其他接口相比，kpl_list的特点是字段粒度最细、信息密度最高：
- 它给出了涨停/跌停/开板的发生时间（
lu_time/ld_time/open_time/last_time），可以还原当天个股的封板—炸板—回封过程； - 它给出竞价阶段数据（
bid_amount竞价成交额、bid_change竞价净额、bid_turnover竞价换手、bid_pct_chg竞价涨幅），可用于开盘前的集合竞价强弱预判； - 它给出封单质量指标（
lu_bid_vol涨停委买额、limit_order封单、lu_limit_order最大封单）； - 它给出资金与流通盘信息（
net_change主力净额、free_float实际流通、amount成交额、turnover_rate换手率）； - 它直接给出板块归属与上涨原因（
theme、lu_desc），是板块轮动归因的一手素材。
数据更新时效：当日数据在次日 8:30入库，因此该接口适合做次日盘前的研究复盘与策略信号刷新，不适合盘中实时盯盘（实时场景可搭配同专题的 开盘竞价成交(当日).md) 等接口）。
合规提示：文档明确注明，开盘啦是一个专业的打板 App，本接口仅限用于量化研究；如需商业用途，请自行联系开盘啦官方。
二、权限与限量规则：调用前必须了解的硬约束
在使用kpl_list之前，需要先明确 Tushare 积分体系下的调用额度（原文档"限量/积分"章节）：
| 项目 | 规则 |
|---|---|
| 单次最大返回 | 8000 条数据 |
| 历史数据获取 | 可根据交易日期循环获取（按日分页即可覆盖全历史） |
| 5000 积分档 | 每分钟 200 次请求，每天总量 1 万次 |
| 8000 积分及以上档 | 每分钟 500 次请求，每天总量不限制 |
积分获取办法详见 Tushare 官方积分文档，本文不展开外部链接，实际操作时以官方最新规则为准。
由此可以推导出两个重要的工程约束：
- 单日榜单通常远小于 8000 条：从下方数据样例看，2024-09-27 当天
tag='涨停'的榜单约 131 行，即使全市场涨停日（通常数百只）也不会突破单次上限，因此按trade_date单日拉取即可覆盖一个完整交易日； - “按日期循环”是拉全历史的唯一可靠方式：若需要多年历史，应遍历交易日历（可参考同分类下 交易日历 接口）逐日调用，同时注意在 5000 积分档下控制每日总调用量不超过 1 万次，并为每次调用设置合理间隔以避免触发分钟级限频。
三、环境准备：Token 配置与 Tushare 客户端初始化
在 Vibe-Trading 仓库中，Tushare 被作为 A 股行情与专题数据的标准化数据源接入。Token 通过环境变量TUSHARE_TOKEN声明，定义位置在 agent/src/config/env_schema.py：
tushare_token: str = Field(alias="TUSHARE_TOKEN", default="")即在 Vibe-Trading 的配置体系中，只需设置环境变量TUSHARE_TOKEN，即可被数据访问层读取并注入 Tushare 客户端。配置方式：
export TUSHARE_TOKEN=your_token仓库自带的示例脚本 agent/src/skills/tushare/scripts/stock_data_example.py 给出了客户端初始化的标准姿势——优先读取 Vibe-Trading 配置中的 Token，回退到 Tushare 本地缓存 Token：
import tushare as ts from src.config.accessor import get_env_config token = get_env_config().data.tushare_token or ts.get_token() pro = ts.pro_api(token)独立于 Vibe-Trading 环境时，最简单的初始化方式是：
pip install tushare # 推荐 Python 3.7+，可用清华 PyPI 镜像加速import tushare as ts pro = ts.pro_api() # 会读取 ~/.tushare/token 或环境变量中的 tokenTushare 的数据返回统一为pandas DataFrame，日期参数统一使用YYYYMMDD格式（如20240927），股票代码使用ts_code格式（如000762.SZ、600801.SH），这是所有接口调用的通用约定。
四、输入参数详解：五种榜单维度的组合查询
kpl_list共支持 5 个输入参数，全部为可选参数，通过自由组合实现不同粒度的查询。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
ts_code | str | N | 股票代码（如000762.SZ） |
trade_date | str | N | 交易日期（YYYYMMDD） |
tag | str | N | 板单类型，取值：涨停 / 炸板 / 跌停 / 自然涨停 / 竞价，默认为涨停 |
start_date | str | N | 开始日期 |
end_date | str | N | 结束日期 |
tag参数的语义是理解本接口的关键：
- 涨停：当日封住涨停的股票榜单（默认值）；
- 跌停：当日封住跌停的股票榜单；
- 炸板：盘中曾涨停但收盘未封住（或盘中反复开板）的股票；
- 自然涨停：剔除一字板后的自然换手涨停（通常不含开盘即一字涨停的品种，用于筛选有真实资金博弈的标的）；
- 竞价：集合竞价阶段表现特殊的股票（竞价涨停/竞价异动等）。
参数组合的典型用法：
| 查询目标 | 参数写法 |
|---|---|
| 查询某一天全部涨停股 | trade_date='20240927'（tag 缺省即涨停） |
| 查询某一天全部炸板股 | trade_date='20240927', tag='炸板' |
| 查询某一天全部跌停股 | trade_date='20240927', tag='跌停' |
| 查询某一只股票的历史上榜记录 | ts_code='000762.SZ', start_date=..., end_date=... |
| 查询某区间内所有涨停（含起始日） | start_date='20240901', end_date='20240927', tag='涨停' |
注意：tag的取值是中文语义标签而非代码，这在批量脚本中需要硬编码为上述五选一；同时由于接口是快照型数据，start_date/end_date区间查询本质上是多日榜单的合并结果，实际使用中更推荐"按日循环 + 本地合并"的模式，便于控制单次返回规模与请求频率。
五、输出参数详解：22 个字段的量化学含义
kpl_list单条记录包含 22 个字段，覆盖了"谁、何时、以何种方式、多少资金、什么板块、什么逻辑"上榜的完整信息。全部字段默认显示（默认显示 = Y）：
| 名称 | 类型 | 描述 | 量化解读 |
|---|---|---|---|
ts_code | str | 代码 | 股票唯一标识，格式如000762.SZ |
name | str | 名称 | 股票名称 |
trade_date | str | 交易时间 | 榜单所属交易日（YYYYMMDD） |
lu_time | str | 涨停时间 | 当日首次涨停的时间点，越早说明越强势 |
ld_time | str | 跌停时间 | 跌停发生时间（跌停/炸板榜中有效） |
open_time | str | 开板时间 | 炸板（开板）的时间点 |
last_time | str | 最后涨停时间 | 最后一次回封涨停的时间，配合lu_time可还原封板过程 |
lu_desc | str | 涨停原因 | 开盘啦归纳的上涨驱动逻辑，是题材归因的基础 |
tag | str | 标签/类别 | 本条记录所属榜单类型 |
theme | str | 板块 | 所属概念/题材板块，如“锂矿、盐湖提锂” |
net_change | float | 主力净额(元) | 主力资金净流入，衡量资金真实做多力度 |
bid_amount | float | 竞价成交额(元) | 集合竞价阶段的成交金额，体现竞价人气 |
status | str | 状态（N连板） | 如“首板”“2连板”，直接刻画高度 |
bid_change | float | 竞价净额 | 竞价阶段资金净买卖差额 |
bid_turnover | float | 竞价换手% | 竞价成交量占流通盘比例，反映抢筹热度 |
lu_bid_vol | float | 涨停委买额 | 涨停价位未成交买盘挂单金额（涨停意愿） |
pct_chg | float | 涨跌幅% | 当日涨跌幅 |
bid_pct_chg | float | 竞价涨幅% | 竞价结束时的涨幅，高开幅度的直接度量 |
rt_pct_chg | float | 实时涨幅% | 数据生成时点的实时涨幅 |
limit_order | float | 封单 | 收盘/当前时刻的封单金额 |
amount | float | 成交额 | 当日总成交额 |
turnover_rate | float | 换手率% | 当日换手，与流通盘配合刻画筹码交换 |
free_float | float | 实际流通 | 实际流通股本/市值，判断盘子大小 |
lu_limit_order | float | 最大封单 | 当日涨停期间的最大封单金额，代表资金封板的最大决心 |
字段组合的使用建议：
- 判断涨停强度：对比
lu_time（越早越强）+lu_limit_order（最大封单越大越稳）+open_time是否为空（无开板说明一字未破或封死）； - 判断炸板风险：
open_time非空 +limit_order骤降的组合，说明盘中反复开板，次日溢价预期通常偏弱； - 判断竞价情绪：
bid_pct_chg（竞价涨幅）、bid_turnover（竞价换手）、bid_amount（竞价成交额）三字段组合，是开盘情绪温度计； - 判断资金真实性：
net_change（主力净额）与bid_change（竞价净额）为正且放大，通常意味着有真实资金承接而非单纯情绪脉冲； - 判断题材属性：
theme+lu_desc是板块内部分层与龙头识别的输入，可与同专题的 题材成分(开盘啦).md) 接口（kpl_concept_cons）联动，展开题材成分股明细。
六、接口调用实战：从单日快照到全历史
6.1 基础调用：拉取单日涨停榜单
原文档给出的标准用法如下：
import tushare as ts pro = ts.pro_api() df = pro.kpl_list(trade_date='20240927', tag='涨停', fields='ts_code,name,trade_date,tag,theme,status') print(df)trade_date='20240927'锁定交易日；tag='涨停'明确榜单类型；fields参数用于裁剪返回列，减少传输与内存开销——这是高频调用的最佳实践。
执行后得到的数据样例（原文档实测输出，2024-09-27 部分涨停榜）：
ts_code name trade_date tag theme status 0 000762.SZ 西藏矿业 20240927 涨停 锂矿、盐湖提锂 首板 1 300399.SZ 天利科技 20240927 涨停 互联网金融、金融概念 首板 2 002673.SZ 西部证券 20240927 涨停 证券、控参股基金 首板 3 002050.SZ 三花智控 20240927 涨停 汽车热管理、比亚迪产业链 首板 4 600801.SH 华新水泥 20240927 涨停 水泥、地产链 首板 .. ... ... ... ... ... ... 126 600696.SH 岩石股份 20240927 涨停 白酒、酿酒 2连板 127 600606.SH 绿地控股 20240927 涨停 房地产、地产链 2连板 128 000882.SZ 华联股份 20240927 涨停 零售、互联网金融 2连板 129 000069.SZ 华侨城Ａ 20240927 涨停 房地产、地产链 2连板 130 002570.SZ 贝因美 20240927 涨停 多胎概念、乳业 首板从样例中可以直观读出：当天涨停股集中在锂矿/盐湖提锂、互联网金融、证券、地产链等方向，且仅少数个股晋级 2 连板（status字段），这正是判断"当日主线板块"和"高度梯队"的第一手截面。
6.2 分 tag 遍历：一次拉取全部榜单维度
涨停、跌停、炸板、自然涨停、竞价是五个互斥视图，分别调用即可获得当日完整的多空全景：
pro = ts.pro_api() date = '20240927' for tag in ['涨停', '炸板', '跌停', '自然涨停', '竞价']: df = pro.kpl_list(trade_date=date, tag=tag) print(f"[{tag}] {len(df)} 条") # 本地落盘：df.to_csv(f'kpl_{date}_{tag}.csv', index=False)6.3 按日期循环：拉取全历史榜单
由于单次最多返回 8000 条、且历史数据支持按日期循环，完整的全历史回补脚本框架如下（实际运行时建议加入限速与断点续传）：
import time import tushare as ts pro = ts.pro_api() def fetch_kpl_history(trade_dates, tag='涨停', sleep=0.3): """trade_dates: 交易日列表（可用 trade_cal 接口生成）""" frames = [] for d in trade_dates: try: df = pro.kpl_list(trade_date=d, tag=tag) frames.append(df) time.sleep(sleep) # 控制请求频率，避免触及分钟级限额 except Exception as e: print(f"{d} 拉取失败: {e}") return __import__('pandas').concat(frames, ignore_index=True)交易日列表可由 交易日历（trade_cal）接口生成，从而精确遍历 A 股实际交易日，避免对非交易日发起无效请求。
6.4 个股视角：追踪特定标的的上榜历史
通过ts_code可以反查某只股票历史上所有上榜记录，用于验证“该股历史上封板后的次日表现”等事件研究：
df = pro.kpl_list(ts_code='000762.SZ', start_date='20240101', end_date='20241231', fields='trade_date,tag,status,lu_time,lu_desc,theme,net_change')七、在 Vibe-Trading 中接入与联动的策略视角
kpl_list在 Vibe-Trading 的 Tushare 技能体系中与打板专题的其他接口构成一个完整的短线研究数据族，合理联动可以覆盖“榜单—梯队—板块—资金—游资”的全链路：
| 研究环节 | 推荐接口 | 对应文档 |
|---|---|---|
| 每日涨跌停/炸板基础统计（含行业、封单金额、炸板次数、涨停统计） | limit_list_d | 涨跌停和炸板数据 |
| 连板晋级梯队（每日各连板高度的个股清单） | limit_step | 涨停股票连板天梯 |
| 题材成分股展开（开盘啦概念 → 成分股） | kpl_concept_cons | 题材成分(开盘啦).md) |
| 游资席位/名录（主力身份识别） | hm_list、hm_detail | 同目录下市场游资最全名录、游资交易每日明细 |
| 龙虎榜机构/营业部明细 | top_list、top_inst | 同目录下龙虎榜相关文档 |
从仓库源码结构看，Vibe-Trading 将 Tushare 作为 A 股数据链路的默认数据源之一（见 agent/src/market_data.py 中的数据源路由注释与 agent/src/config/env_schema.py 中MARKET_DATA_ORDER_A_SHARE的源优先级配置），因此kpl_list这类专题数据既可以在独立的 Python 脚本中直接调用，也可以作为 Agent 调用的数据技能被注入研究流程——技能目录本身（agent/src/skills/tushare）就是 Tushare 全部接口索引的可检索知识库。
八、注意事项与最佳实践小结
- 权限与合规：本接口仅限量化研究用途；商用请联系开盘啦官方；数据版权归开盘啦所有。
- 更新时效：当日数据次日 8:30 更新，请勿在盘中期冀获取当日完整榜单；盘前复盘脚本建议安排在 8:30 之后触发。
- 限量管理：单次 8000 条上限对单日榜单足够；全历史必须按交易日循环；5000 积分档需控制每日 1 万次总量与每分钟 200 次频率，脚本中务必加入
sleep。 tag语义：五种标签互斥且区分严格（涨停/跌停/炸板/自然涨停/竞价），构建指标库时注意不要把“自然涨停”混入“涨停”口径。- 字段口径：
net_change（主力净额）、bid_amount（竞价成交额）单位均为元，pct_chg、turnover_rate、bid_turnover、bid_pct_chg均为百分比，入库前建议统一单位换算并记录口径，避免下游因子计算错误。 - 联动扩展：榜单数据与 涨跌停和炸板数据、涨停股票连板天梯 等接口结合使用，可构建从单日截面到历史序列的完整打板研究数据集。
【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
