Vibe-Trading 龙虎榜每日数据实战指南基于 Tushare top_list 接口的 A 股打板数据接入与源码解析【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading龙虎榜每日统计是 A 股打板短线题材交易研究中最重要的数据源之一它记录了每个交易日因异动而触发信息披露的证券以及这些证券的成交、龙虎榜买卖额与上榜理由。本文以 Vibe-Trading 仓库中 龙虎榜每日统计单文档 为核心系统讲解 Tusharetop_list接口的入参、出参、调用方式与数据量纲并结合仓库内 dragon_tiger_tool.py、tushare_fallbacks.py 及对应测试的源码实现说明龙虎榜数据在真实交易 Agent 工程中如何落地、如何做字段映射与多数据源回退。读完本文你将掌握从拉取单日龙虎榜、解读每个字段的业务含义到批量回灌历史数据、嵌入自动化策略的全链路方法。接口概览龙虎榜每日明细是什么在 Tushare 接口体系中龙虎榜每日统计单对应的接口名为top_list属于「股票数据 / 打板专题数据」分类。其核心定义如下见 SKILL.md 数据接口列表 中 ID 106 一行接口名top_list描述龙虎榜每日交易明细数据历史2005 年至今覆盖 A 股全部龙虎榜披露历史限量单次请求最大返回 10000 行数据可通过参数循环获取全部历史积分门槛用户需要至少 2000 积分才可以调取具体积分获取办法参见 Tushare 官方「积分获取办法」文档doc_id13与同目录下的 龙虎榜机构交易单文档接口top_inst不同top_list提供的是股票维度的每日上榜明细一只股票可能因多种理由多次上榜、出现多行记录而top_inst提供的是营业部席位维度的买卖明细。两者配合使用可以同时回答今天哪些股票上了龙虎榜与是哪家营业部在买、哪家在卖两个问题。输入参数详解top_list的请求参数非常精简只有两个名称类型必选描述trade_datestrY交易日期ts_codestrN股票代码其中trade_date为必填格式遵循仓库 Tushare 技能的通用约定日期使用 YYYYMMDD 紧凑格式如20180928这在 SKILL.md 参数格式说明 中有明确约定。ts_code为可选项格式如002219.SZ6 位数字 点号 交易所后缀.SH代表上交所、.SZ代表深交所。组合使用规则只传trade_date返回该交易日全部上榜股票适合每日收盘后做全市场扫描trade_datets_code返回指定股票在该日的上榜记录适合对持仓或候选标的做定向核查。输出参数详解14 个字段的业务含义接口返回一张 DataFrame每个字段的类型与含义如下沿用原文档表格并补充量纲说明名称类型默认显示描述trade_datestrY交易日期ts_codestrYTS 代码namestrY名称closefloatY收盘价元pct_changefloatY涨跌幅%turnover_ratefloatY换手率%amountfloatY总成交额元l_sellfloatY龙虎榜卖出额元l_buyfloatY龙虎榜买入额元l_amountfloatY龙虎榜成交额元net_amountfloatY龙虎榜净买入额元net_ratefloatY龙虎榜净买额占比%amount_ratefloatY龙虎榜成交额占比%float_valuesfloatY当日流通市值元reasonstrY上榜理由值得重点辨析的字段关系金额类字段close、amount、l_sell、l_buy、l_amount、net_amount、float_values均以元为量纲。以数据样例中第 1 行000017.SZ 深中华A为例amount101054192.0即约 1.01 亿元总成交额。比率类字段pct_change、turnover_rate、net_rate、amount_rate以百分数为量纲。如net_rate龙虎榜净买额占比net_amount / amount × 100amount_rate龙虎榜成交额占比l_amount / amount × 100。值得注意的是amount_rate可能超过 100样例中第 0 行为 166.03、第 8 行为 126.16说明上榜席位间存在对倒/重复计数龙虎榜买卖额统计口径并非单纯的当日二级市场成交。reason上榜理由是驱动因子构建的关键文本字段常见取值包括日涨幅偏离值达到 7% 的前五只证券日跌幅偏离值达到 7% 的前五只证券日换手率达到 20% 的前五只证券连续三个交易日内涨幅偏离值累计达到 20% 的证券连续三个交易日内跌幅偏离值累计达到 20% 的证券日振幅值达到 15% 的证券等同一股票可同时满足多条规则此时会以多行记录出现如样例第 6、7 行都是002219.SZ 恒康医疗一条对应单日涨幅偏离、一条对应三日累计涨幅偏离。调用方式与数据获取两种等价调用形式原文档给出两种完全等价的写法pro ts.pro_api() # 方式一直接方法调用 df pro.top_list(trade_date20180928) # 方式二通用 query 调用 df pro.query(top_list, trade_date20180928, ts_code002219.SZ)两种方式返回的都是 pandas DataFramepro.query的第一参数传入接口名其余参数与直接调用完全一致。前置准备Token 与环境配置调用前需完成 Tushare 环境初始化。根据 SKILL.md 快速上手 与 stock_data_example.py 示例脚本标准流程是安装依赖推荐从清华 PyPI 镜像安装pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple注册 Tushare 账号获取 token并配置环境变量export TUSHARE_TOKENyour_token初始化 pro 接口并读取 tokenimport os import tushare as ts token os.getenv(TUSHARE_TOKEN) or ts.get_token() pro ts.pro_api(token) df pro.top_list(trade_date20180928) print(df.head())仓库内示例脚本更进一步会优先通过src.config.accessor的get_env_config().data.tushare_token读取配置化的 token再回退到ts.get_token()这与生产环境中密钥统一管理的最佳实践一致。数据样例逐行解读以下为原文档提供的trade_date20180928返回样例节选关键列单位如上所述trade_datets_codenameclosepct_changeturnover_rateamountl_selll_buyl_amountnet_amountnet_rateamount_ratefloat_valuesreason20180928000007.SZ全新好7.83-10.000.2413,736,95213,736,9529,071,05522,808,014-4,665,897-33.97166.032.42e9日跌幅偏离值达到7%的前五只证券20180928000017.SZ深中华A4.669.90577.44101,054,1927,329,63928,361,20035,690,84021,031,56020.8135.321.41e9日涨幅偏离值达到7%的前五只证券20180928002219.SZ恒康医疗4.3610.10107.11550,236,63141,801,39039,420,85181,222,230-2,380,538-0.4314.768.13e9日涨幅偏离值达到7%的前五只证券20180928002219.SZ恒康医疗4.3610.10107.11800,737,93567,244,86257,635,001124,879,903-9,609,865-1.2015.608.13e9连续三个交易日内涨幅偏离值累计达到20%的证券20180928002892.SZ科力尔29.972.813025.67199,046,72859,732,77830,663,44090,396,230-29,069,340-14.6045.417.89e8日换手率达到20%的前五只证券20180928002930.SZ宏川智慧30.9910.010612.22226,882,18414,560,10065,026,30179,586,40450,466,21022.2435.081.89e9日涨幅偏离值达到7%的前五只证券从样例中可以提炼出若干实操要点同日多行 多规则命中恒康医疗当日出现两行分别对应日涨幅偏离值达到 7%与三日累计涨幅偏离达到 20%两行的amount不同5.50 亿 vs 8.01 亿因为三日累计口径覆盖的是区间累计成交额。做统计时若按股票去重需明确采用哪一行口径。net_amount符号即多空方向深中华A净买入 2103 万净买额占比 20.81%科力尔净卖出 2907 万-14.60%可用于区分上榜资金进场与上榜资金离场两类标的。float_values可用于规模分层同日上榜股中流通市值从 7.65 亿路畅科技到 81.3 亿恒康医疗不等可按流通市值切分小盘/中盘样本。龙虎榜数据在 Vibe-Trading 中的工程化落地龙虎榜数据不仅是研究文档中的接口说明在 Vibe-Trading 仓库中已经完成了完整的工程化集成形成了工具层 → 适配层 → 数据源回退的三层架构。第一层龙虎榜工具get_dragon_tigeragent/src/tools/dragon_tiger_tool.py 定义了DragonTigerTool名称get_dragon_tiger它是面向 Agent 的统一入口docstring 明确指出其语义为获取 A 股龙虎榜上海/深圳披露榜单必选参数dateYYYY-MM-DD 格式交易日期可选参数codeA 股代码或裸代码如600519.SH或600519不传code返回当日全市场上榜证券列表最多 200 条_MAX_APPEARANCES传入code额外返回该证券按净买卖额排序的前 30 个营业部席位_MAX_SEATS。主数据源为东方财富 datacenter APIRPT_DAILYBILLBOARD_DETAILS/RPT_BILLBOARD_TRADEDETAIL两个报表走共享限流的eastmoney_client。工具内部把date统一规范化为YYYY-MM-DD紧凑格式_compact_date并把600519.SH之类的带后缀代码剥成裸代码_bare_code保证与下游适配层的数据格式一致。第二层Tushare 回退适配fetch_dragon_tiger当东财数据源失败时工具会自动降级到 Tushare。降级逻辑在 agent/src/tools/dragon_tiger_tool.py 的 execute 方法捕获东财请求异常后调用tushare_fallbacks.fetch_dragon_tiger成功时在返回 JSON 中标记source: tushare并附上warnings提示。这正是本文主题top_list接口在仓库中最直接的调用点。agent/src/tools/tushare_fallbacks.py 的 fetch_dragon_tiger 函数 完整展示了top_list与top_inst的字段映射逻辑def fetch_dragon_tiger(trade_date: str, code: str | None) - dict[str, Any]: compact _compact_date(trade_date) # 归一化为 YYYYMMDD ts_code _ts_code(code) if code else None # 裸代码补全交易所后缀 pro _pro_api() kwargs: dict[str, str] {trade_date: compact} if ts_code: kwargs[ts_code] ts_code appearances_raw _records(pro.top_list(**kwargs)) # ← 本文核心接口 appearances [ { code: str(row.get(ts_code, )).split(., 1)[0] or None, name: row.get(name), close: row.get(close), change_pct: row.get(pct_change), net_buy: row.get(net_amount), buy_amount: row.get(l_buy), sell_amount: row.get(l_sell), turnover: row.get(amount), reason: row.get(reason), } for row in appearances_raw ] ...这段代码对理解top_list的工程使用极具参考价值日期归一化外部传入2024-01-02或20240102都会被统一成 Tushare 要求的YYYYMMDD紧凑格式代码补全_ts_code()根据 6 位数字前缀推断交易所后缀5/6/9→.SH0/2/3→.SZ4/8→.BJ把裸代码600519补成600519.SH字段重命名Tushare 的pct_change → change_pct、net_amount → net_buy、l_buy → buy_amount、l_sell → sell_amount、amount → turnover对外暴露统一 schema席位明细传入ts_code时还会调用pro.top_inst即 龙虎榜机构交易单文档 中的接口把exalter营业部名称、side买卖方向、buy、sell、net_buy映射为席位数组。第三层测试保障仓库用内存假数据对映射逻辑做了完整验证见 test_tushare_fallbacks.py 中的 test_dragon_tiger_maps_top_list_and_top_inst通过SimpleNamespace伪造top_list/top_inst返回值断言fetch_dragon_tiger正确完成日期格式、代码剥离、字段重命名与席位组装。该测试全程不触网、不需要真实 token验证了top_list各字段到统一 schema 的映射正确性——这也是使用 Tushare 数据时的推荐做法把数据源 API 隔离在适配层后面用契约测试锁定字段映射。实战场景批量回灌历史龙虎榜数据由于单次请求最多返回 10000 行而一个交易日全市场龙虎榜通常只有几十到几百行top_list的 10000 行限额基本不会成为障碍但若要拉取 2005 年至今的全部历史仍应按交易日逐日循环 本地落盘。参考 SKILL.md 中通过参数循环获取全部历史的说明一个稳健的回灌流程是import os import time import pandas as pd import tushare as ts pro ts.pro_api(os.getenv(TUSHARE_TOKEN)) # 先用交易日历接口取全量交易日或维护一个交易日期列表 trade_dates [...] # 例如来自 pro.trade_cal 的 YYYYMMDD 序列 frames [] for d in trade_dates: try: df pro.top_list(trade_dated) except Exception as exc: print(f{d} failed: {exc}) # 按错误码做退避重试或跳过 time.sleep(1) continue if df is not None and not df.empty: frames.append(df) time.sleep(0.3) # 注意 Tushare 频控 history pd.concat(frames, ignore_indexTrue)实操注意事项频控与重试Tushare 对高积分用户有较高的日调用量但仍建议在循环中加入 sleep 与异常重试避免触发限流被临时封禁增量更新生产环境建议记录本地最大trade_date每日收盘后一般 18 点后数据更新完毕仅增量拉取最近交易日而非全量重跑字段落库口径ts_code应保留后缀以区分沪深reason建议原样存储便于后续文本分类金额字段统一按元存储。与其他打板专题接口的联动龙虎榜数据在打板研究中的价值往往通过组合释放。仓库 打板专题数据目录 下还有一批可与之联动的接口龙虎榜机构交易单top_inst5000 积分营业部维度明细side字段区分买入/卖出前五席位配合top_list可还原游资买、机构卖等资金博弈结构市场游资最全名录hm_list游资分类名录可与席位名称做匹配识别知名游资动向游资交易每日明细hm_detail每日游资交易明细数据自 2022 年 8 月开始涨停股票连板天梯limit_step每日连板进阶统计用于判断情绪周期与题材强度涨跌停和炸板数据limit_list_d涨停、跌停、炸板统计。一个典型的打板研究流水线是用limit_step/limit_list_d定位当日市场情绪与连板梯队 → 用top_list找出上榜且net_amount显著为正的标的 → 用top_insthm_list判断主导资金属性 → 结合daily日线数据回看价格位置。这条链路正是 Vibe-Trading 将 Tushare 数据接口文档 完整沉淀为 Agent 可检索技能的意义所在。常见问题与注意事项积分不足报错top_list要求至少 2000 积分低于门槛会返回权限类错误。可先通过积分获取办法提升积分或改用仓库内基于东财免费接口的get_dragon_tiger工具dragon_tiger_tool.py 主路径无需积分、只读、走共享限流。amount_rate超过 100% 的解释龙虎榜成交额占比基于上榜席位买卖额汇总计算席位间存在对倒交易时占比可超 100%属正常现象做因子时不宜直接当作普通占比截断。同日多行去重同一股票因命中多条规则出现多行时需明确去重口径按reason保留一条、或按口径拆分统计否则会出现重复计数。历史数据完整性数据自 2005 年开始早期年份披露规则与近年不同如深交所与上交所规则差异做长周期回测时建议按披露规则变化分段处理。字段量纲金额单位为元、比率单位为百分数跨接口拼接时需与moneyflow万元/百万元等其他 Tushare 接口保持一致换算避免数量级错误。小结本文以 龙虎榜每日统计单文档 为主线完整覆盖了 Tusharetop_list接口的参数、字段、调用与数据解读并通过 Vibe-Trading 仓库中的 dragon_tiger_tool.py、tushare_fallbacks.py 与 test_tushare_fallbacks.py 展示了从裸接口到生产级 Agent 工具的完整链路日期与代码归一化、字段映射、数据源回退、契约测试。无论是手写脚本做研究还是在 Vibe-Trading 中通过get_dragon_tiger工具直接驱动 Agent 获取龙虎榜情报本文给出的调用范式与字段语义都能直接复用。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考