Vibe-Trading 龙虎榜每日数据实战指南：基于 Tushare top_list 接口的 A 股打板数据接入与源码解析

Vibe-Trading 龙虎榜每日数据实战指南：基于 Tushare top_list 接口的 A 股打板数据接入与源码解析

【免费下载链接】Vibe-Trading"Vibe-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_id=13）

与同目录下的 龙虎榜机构交易单文档（接口top_inst）不同，top_list提供的是股票维度的每日上榜明细（一只股票可能因多种理由多次上榜、出现多行记录），而top_inst提供的是营业部席位维度的买卖明细。两者配合使用，可以同时回答"今天哪些股票上了龙虎榜"与"是哪家营业部在买、哪家在卖"两个问题。

输入参数详解

top_list的请求参数非常精简，只有两个：

其中trade_date为必填，格式遵循仓库 Tushare 技能的通用约定：日期使用 YYYYMMDD 紧凑格式（如20180928），这在 SKILL.md 参数格式说明 中有明确约定。ts_code为可选项，格式如002219.SZ（6 位数字 + 点号 + 交易所后缀，.SH代表上交所、.SZ代表深交所）。

组合使用规则：

• 只传trade_date：返回该交易日全部上榜股票，适合每日收盘后做全市场扫描；
• trade_date+ts_code：返回指定股票在该日的上榜记录，适合对持仓或候选标的做定向核查。

输出参数详解：14 个字段的业务含义

接口返回一张 DataFrame，每个字段的类型与含义如下（沿用原文档表格并补充量纲说明）：

值得重点辨析的字段关系：

• 金额类字段（close、amount、l_sell、l_buy、l_amount、net_amount、float_values）均以元为量纲。以数据样例中第 1 行000017.SZ 深中华A为例，amount=101054192.0即约 1.01 亿元总成交额。
• 比率类字段（pct_change、turnover_rate、net_rate、amount_rate）以百分数为量纲。如net_rate（龙虎榜净买额占比）=net_amount / amount × 100，amount_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_date='20180928') # 方式二：通用 query 调用 df = pro.query('top_list', trade_date='20180928', ts_code='002219.SZ')

两种方式返回的都是 pandas DataFrame，pro.query的第一参数传入接口名，其余参数与直接调用完全一致。

前置准备：Token 与环境配置

调用前需完成 Tushare 环境初始化。根据 SKILL.md 快速上手 与 stock_data_example.py 示例脚本，标准流程是：

1. 安装依赖（推荐从清华 PyPI 镜像安装）：

pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 注册 Tushare 账号获取 token，并配置环境变量：

export TUSHARE_TOKEN=your_token

3. 初始化 pro 接口并读取 token：

import os import tushare as ts token = os.getenv('TUSHARE_TOKEN') or ts.get_token() pro = ts.pro_api(token) df = pro.top_list(trade_date='20180928') print(df.head())

仓库内示例脚本更进一步，会优先通过src.config.accessor的get_env_config().data.tushare_token读取配置化的 token，再回退到ts.get_token()，这与生产环境中密钥统一管理的最佳实践一致。

数据样例逐行解读

以下为原文档提供的trade_date='20180928'返回样例（节选关键列，单位如上所述）：

从样例中可以提炼出若干实操要点：

1. 同日多行 = 多规则命中：恒康医疗当日出现两行，分别对应"日涨幅偏离值达到 7%"与"三日累计涨幅偏离达到 20%"，两行的amount不同（5.50 亿 vs 8.01 亿），因为三日累计口径覆盖的是区间累计成交额。做统计时若按股票去重，需明确采用哪一行口径。
2. net_amount符号即多空方向：深中华A净买入 2103 万（净买额占比 +20.81%），科力尔净卖出 2907 万（-14.60%），可用于区分"上榜资金进场"与"上榜资金离场"两类标的。
3. float_values可用于规模分层：同日上榜股中流通市值从 7.65 亿（路畅科技）到 81.3 亿（恒康医疗）不等，可按流通市值切分小盘/中盘样本。

龙虎榜数据在 Vibe-Trading 中的工程化落地

龙虎榜数据不仅是研究文档中的接口说明，在 Vibe-Trading 仓库中已经完成了完整的工程化集成，形成了"工具层 → 适配层 → 数据源回退"的三层架构。

第一层：龙虎榜工具get_dragon_tiger

agent/src/tools/dragon_tiger_tool.py 定义了DragonTigerTool（名称get_dragon_tiger），它是面向 Agent 的统一入口，docstring 明确指出其语义为"获取 A 股龙虎榜（上海/深圳）披露榜单"：

• 必选参数date（YYYY-MM-DD 格式交易日期）；
• 可选参数code（A 股代码或裸代码，如600519.SH或600519）；
• 不传code：返回当日全市场上榜证券列表（最多 200 条，_MAX_APPEARANCES）；
• 传入code：额外返回该证券按净买卖额排序的前 30 个营业部席位（_MAX_SEATS）。

主数据源为东方财富 datacenter API（RPT_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→.SH，0/2/3→.SZ，4/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_date=d) 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_index=True)

实操注意事项：

1. 频控与重试：Tushare 对高积分用户有较高的日调用量，但仍建议在循环中加入 sleep 与异常重试，避免触发限流被临时封禁；
2. 增量更新：生产环境建议记录本地最大trade_date，每日收盘后（一般 18 点后数据更新完毕）仅增量拉取最近交易日，而非全量重跑；
3. 字段落库口径：ts_code应保留后缀以区分沪深，reason建议原样存储便于后续文本分类，金额字段统一按元存储。

与其他打板专题接口的联动

龙虎榜数据在打板研究中的价值往往通过组合释放。仓库 打板专题数据目录 下还有一批可与之联动的接口：

• 龙虎榜机构交易单（top_inst，5000 积分）：营业部维度明细，side字段区分买入/卖出前五席位，配合top_list可还原"游资买、机构卖"等资金博弈结构；
• 市场游资最全名录（hm_list）：游资分类名录，可与席位名称做匹配，识别知名游资动向；
• 游资交易每日明细（hm_detail）：每日游资交易明细，数据自 2022 年 8 月开始；
• 涨停股票连板天梯（limit_step）：每日连板进阶统计，用于判断情绪周期与题材强度；
• 涨跌停和炸板数据（limit_list_d）：涨停、跌停、炸板统计。

一个典型的打板研究流水线是：用limit_step/limit_list_d定位当日市场情绪与连板梯队 → 用top_list找出上榜且net_amount显著为正的标的 → 用top_inst+hm_list判断主导资金属性 → 结合daily日线数据回看价格位置。这条链路正是 Vibe-Trading 将 Tushare 数据接口文档 完整沉淀为 Agent 可检索技能的意义所在。

常见问题与注意事项

1. 积分不足报错：top_list要求至少 2000 积分，低于门槛会返回权限类错误。可先通过积分获取办法提升积分，或改用仓库内基于东财免费接口的get_dragon_tiger工具（dragon_tiger_tool.py 主路径无需积分、只读、走共享限流）。
2. amount_rate超过 100% 的解释：龙虎榜成交额占比基于上榜席位买卖额汇总计算，席位间存在对倒交易时占比可超 100%，属正常现象，做因子时不宜直接当作普通占比截断。
3. 同日多行去重：同一股票因命中多条规则出现多行时，需明确去重口径（按reason保留一条、或按口径拆分统计），否则会出现重复计数。
4. 历史数据完整性：数据自 2005 年开始，早期年份披露规则与近年不同（如深交所与上交所规则差异），做长周期回测时建议按披露规则变化分段处理。
5. 字段量纲：金额单位为元、比率单位为百分数，跨接口拼接时需与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-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading