Vibe-Trading 数据技能实战：Tushare stock_hsgt 沪深港通股票列表接口深度解析与调用指南-育师

Vibe-Trading 数据技能实战：Tushare stock_hsgt 沪深港通股票列表接口深度解析与调用指南

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading

沪深港通（Stock Connect）是外资通过北向通道买卖 A 股、内地资金通过南向通道买卖港股的跨境互联互通机制，而标的池的准确名单是研究外资持仓、构建跨境策略的基础前提。本文以 Vibe-Trading 仓库中 Tushare 技能文档沪深港通股票列表为核心骨架，结合仓库内环境配置、回退适配器与关联接口实现，系统讲解stock_hsgt接口的权限门槛、入参约束、类型语义、分页循环策略与实战调用方式，帮助读者在量化研究中快速获取沪股通、深股通、港股通的完整标的列表。

一、沪深港通机制与标的列表的量化意义

在进入接口细节之前，先明确该数据在投资研究中的位置。Vibe-Trading 仓库中的 hk-connect-flow 技能文档对沪深港通架构有清晰概括：

沪股通（HK_SH）/ 深股通（HK_SZ）：北向通道，外资买入上交所、深交所 A 股，被普遍视为 A 股市场机构资金情绪的“聪明钱”指标；
港股通（SH_HK / SZ_HK）：南向通道，内地资金买入港股，体现内地投资者对港股的配置偏好（高股息、科技平台、AH 溢价套利）。

stock_hsgt接口提供的正是这四条通道各自的合格标的股票名单，它是进一步计算北向/南向资金流（moneyflow_hsgt）、十大活跃成交股（hsgt_top10）、个股持股明细（hk_hold）等数据的“股票域（universe）”基础——只有先确定某只股票属于哪个通道的标的池，才能合理解读其资金流数据的含义。

二、接口速览：权限、更新机制与数据起始日

根据沪深港通股票列表文档，stock_hsgt接口的关键约束如下：

属性	说明
接口名	`stock_hsgt`（Python SDK 中通过`pro.stock_hsgt(...)`调用）
功能描述	获取沪深港通股票列表
权限要求	3000 积分起
数据更新	每天上午9:20更新
单次返回上限	最大返回2000 行数据，可根据类型循环提取
数据起始日期	从20250812开始

两点实践要点值得注意：

积分门槛：该接口需要 3000 积分，属于中高权限接口。相比之下，仓库中另一关联接口moneyflow_hsgt（沪深港通资金流向文档）仅需 2000 积分起，而 5000 积分可获得每分钟 500 次的更高提取频率。在规划数据获取任务时，应结合账号积分与接口权限做好取舍。
每日更新时点：9:20 更新意味着当日上午开盘前即可获取当日最新标的名单，适合盘前构建当天的候选股票域。

三、输入参数详解与类型语义

接口输入参数如下（摘自沪深港通股票列表文档）：

名称	类型	必选	描述
`ts_code`	str	N	股票代码
`trade_date`	str	N	交易日期（格式：YYYYMMDD）
`type`	str	Y	类型（见下表）
`start_date`	str	N	开始时间
`end_date`	str	N	结束时间

类型（type）参数是唯一必选参数，其取值范围与语义如下：

类型	类型名称	通道方向
`HK_SZ`	深股通（港>深）	香港 → 深圳，外资买深市 A 股
`SZ_HK`	港股通（深>港）	深圳 → 香港，深市资金买港股
`HK_SH`	沪股通（港>沪）	香港 → 上海，外资买沪市 A 股
`SH_HK`	港股通（沪>港）	上海 → 香港，沪市资金买港股

参数组合策略（从源码/文档结构推断的推荐用法）：

单日全量获取：传trade_date+type，即可得到该类型当日全部标的（样例数据单次返回约 1000 行，未超过 2000 行上限）；
代码级过滤：传ts_code+type，查询单只股票当前是否属于某通道标的池；
历史区间回溯：传start_date/end_date+type，配合文档中“数据从 20250812 开始”的提示，可观察标的池随时间的调整（如被调入/调出通道的股票）。

需要特别说明：由于type必选且单次请求最大返回 2000 行，若某类型标的数量可能超过上限，应采用“按类型 + 按日期循环提取”的方式分批拉取，这与沪深港通资金流向文档中“每次最多返回 300 条记录，总量不限制，可按日期循环提取”的分页思路一致。

四、输出字段说明

接口返回的 DataFrame 包含以下字段：

名称	类型	默认显示	描述
`ts_code`	str	Y	股票代码
`trade_date`	str	Y	交易日期
`type`	str	Y	类型
`name`	str	Y	股票名称
`type_name`	str	Y	类型名称

其中type_name直接给出了“深股通(港>深)”“港股通(深>港)”等可读描述，便于直接用于报表展示或 Agent 的自然语言输出，无需再做类型码到中文名的映射。

五、环境与鉴权：在 Vibe-Trading 中配置 Tushare Token

调用任何 Tushare 接口前都需要完成 token 鉴权。Vibe-Trading 仓库对 Tushare 凭据的管理方式是环境变量注入，具体位于环境变量模式定义：

tushare_token: str = Field(alias="TUSHARE_TOKEN", default="")

即通过TUSHARE_TOKEN环境变量配置 token。安装并初始化方式可参考 Tushare 技能主文档：

pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple export TUSHARE_TOKEN=your_token

import os import tushare as ts # 读取环境变量中的 token, 或者读取本地记录的 token token = os.getenv('TUSHARE_TOKEN') or ts.get_token() # 初始化 pro 接口实例 pro = ts.pro_api(token)

仓库中的股票数据获取示例脚本给出了更贴合本项目风格的初始化方式——通过配置访问器统一读取：

from src.config.accessor import get_env_config import tushare as ts token = get_env_config().data.tushare_token or ts.get_token() pro = ts.pro_api(token)

值得一提的是，仓库中的 Tushare 回退适配器展示了 token 校验的健壮性实践：它会把空字符串、"your-tushare-token"等占位值判定为“未配置”并抛出TushareFallbackUnavailable异常，避免用无效凭据发起无意义的请求；同时该文件中的_ts_code()函数给出了 Tushare 代码后缀的规范——5/6/9开头归SH、0/2/3开头归SZ、4/8开头归BJ，理解这套规则有助于正确识别沪深港通名单中 A 股代码的归属市场。

六、接口调用实战

1. 基础调用：获取单日某类型的标的列表

沿用沪深港通股票列表文档中的官方示例，获取 2025 年 8 月 13 日深股通（外资买深市）的股票列表：

import tushare as ts pro = ts.pro_api() # 获取20250813日深股通的股票列表 df = pro.stock_hsgt(trade_date='20250813', type='HK_SZ') print(df)

2. 循环提取：覆盖全部四种类型

由于type必选且单次有 2000 行上限，完整的“沪深港通股票列表”应按类型循环拉取并合并：

import pandas as pd pro = ts.pro_api() trade_date = '20250813' types = ['HK_SZ', 'SZ_HK', 'HK_SH', 'SH_HK'] frames = [] for t in types: part = pro.stock_hsgt(trade_date=trade_date, type=t) if part is not None and not part.empty: frames.append(part) full = pd.concat(frames, ignore_index=True) print(full) print(full['type_name'].value_counts()) # 按通道统计标的数量

3. 组合使用：单股标的池查询与历史回溯

# 按股票代码查询：某只股票当前属于哪条通道 df_1 = pro.stock_hsgt(ts_code='000338.SZ', type='HK_SZ') # 按日期区间回溯标的池变化（注意数据自 20250812 起） df_2 = pro.stock_hsgt(start_date='20250812', end_date='20250813', type='SH_HK')

4. 数据样例解读

文档中给出的样例数据（trade_date=20250813）可以直观看出四类通道数据的混合形态：

ts_code trade_date type name type_name 0 001258.SZ 20250813 HK_SZ 立新能源 深股通(港>深) 1 00019.HK 20250813 SZ_HK 太古股份公司A 港股通(深>港) 2 000513.SZ 20250813 HK_SZ 丽珠集团 深股通(港>深) ... 996 02331.HK 20250813 SH_HK 李宁 港股通(沪>港) 997 01855.HK 20250813 SH_HK 中庆股份 港股通(沪>港) 999 06127.HK 20250813 SH_HK 昭衍新药 港股通(沪>港)

从样例可以提取两个重要识别规律：

A 股代码后缀：.SZ结尾为深交所股票（如001258.SZ），.SH结尾为上交所股票，出现在HK_SZ/HK_SH（北向）类型中；
港股代码后缀：.HK结尾为港交所股票（如00019.HK、02331.HK），出现在SZ_HK/SH_HK（南向）类型中。

因此在聚合分析时，可依据ts_code后缀快速区分 A 股与港股标的，与 Tushare 回退适配器中_ts_code()的后缀判断逻辑互为印证。

七、与关联接口联动：构建完整的沪深港通研究流水线

stock_hsgt提供“股票池”，要完成资金流研究还需联动以下关联接口（均收录于 Tushare 技能主文档的接口列表）：

接口	仓库文档	作用
`moneyflow_hsgt`	沪深港通资金流向	每日北向/南向资金净流入（`hgt`、`sgt`、`north_money`、`south_money`，单位百万元）
`hsgt_top10`	沪深股通十大成交股	沪股通/深股通每日前十大活跃成交股及净买卖额
`hk_hold`	沪深股通持股明细	港交所披露的北向个股持股明细

一个典型的应用链路是：先用stock_hsgt确定当日各通道标的域 → 用hsgt_top10定位外资当日重点交易的个股 → 用hk_hold跟踪重点个股的持股变化 → 结合moneyflow_hsgt判断整体资金方向。这与 hk-connect-flow 技能文档中“北向 20 日累计净买入判断持续建仓/派发、AH 溢价指数指导跨市场配置”的分析框架完全兼容，stock_hsgt在其中承担了最底层的标的筛选职责。

八、注意事项与最佳实践总结

积分与频率：stock_hsgt需 3000 积分；正式任务前先在 Tushare 数据工具（tushare.pro/webclient）中调试确认参数与返回，避免浪费调用额度。
数据起始日：本接口数据从20250812开始，历史回溯窗口不要早于该日期。
分页循环：单次请求最多返回 2000 行，务必按type（必要时叠加trade_date循环）分段拉取并合并，防止数据截断。
更新时点：数据每天 9:20 更新，盘前任务应安排在更新完成后执行。
Agent 集成：在 Vibe-Trading 的 Agent 工作流中，本接口作为 Tushare 技能下“股票数据 / 基础数据”分类的技能文档存在，Agent 可直接依据文档中的参数表、类型表与代码示例生成可运行的 Python 调用；生产环境中建议通过 Tushare 回退适配器的鉴权模式统一管理 token，避免凭据散落。