企业官网建设流程全解析

Vibe-Trading 中的 Tushare 前十大股东数据实战：top10_holders 接口从取数到股权结构分析

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

前十大股东（top10_holders）是 Tushare 提供的上市公司股权结构核心接口，在 Vibe-Trading 项目中作为 tushare 数据源技能 下"股票数据/参考数据"类目的一等公民被收录。本文将以该接口文档为骨架，完整讲解其输入输出参数、两种调用方式与数据样例，并结合 Vibe-Trading 仓库中的 token 配置、环境变量注入与健康检查实现，给出可直接落地的 A 股股权集中度分析与实盘研究示例。

接口定位与权限门槛

接口名：top10_holders

官方描述：获取上市公司前十大股东数据，包括持有数量和比例等信息。该接口在 Vibe-Trading 的 tushare 技能接口列表中被登记为 ID 61，归类为"股票数据,参考数据"（见 SKILL.md 中top10_holders一行）。

积分要求：需 2000 积分以上才可调取本接口，5000 积分以上频次会更高。这意味着该接口属于 Tushare 的高阶权限数据，普通基础积分用户无法直接访问，需要先通过 Tushare 积分体系升级账户。

从数据结构上看，top10_holders披露的是上市公司定期报告（季报/年报）中按持股数量排序的前十大股东名单，包含每家股东的名称、持股数量、占总股本比例、占流通股本比例、持股变动等信息，是股权结构、筹码集中度和"国家队"持股追踪等研究的基础数据。它与同目录下的 前十大流通股东（top10_floatholders，接口 ID 62）互为补充：前者面向总股本口径，后者面向流通股本口径，两者结合可以拆分"限售/非流通"与"流通"两个维度的大股东持仓。

输入参数详解

其中ts_code为必填参数，格式遵循 Tushare 全库统一约定：交易所后缀区分市场，例如600000.SH（上交所）、000001.SZ（深交所）。period是报告期，即财务报表的截止日，由于 A 股季报披露存在滞后，period与ann_date（公告日期）并不相同，例如 2017 年年报的报告期是20171231，公告日期则可能到 2018 年 4 月底。start_date/end_date用于按报告期区间批量拉取，适合做多期历史对比。

输出参数详解

输出字段的实战含义：

• hold_amount为绝对持股量（单位：股），在样例数据中因数值巨大以科学计数法呈现（如2.779437e+09即约 27.79 亿股）；
• hold_ratio与hold_float_ratio分别是占总股本、占流通股本的比例（百分比），二者差额可用于判断股东所持股份中限售流通的规模；
• hold_change表示相对上一报告期的持股变动，结合holder_type（股东类型，如保险、投资公司等）可以追踪机构资金动向；
• holder_name可用于识别"国家队"席位（如中国证券金融、中央汇金）或产业资本席位。

接口用法

方式一：直接调用接口方法

pro = ts.pro_api() df = pro.top10_holders(ts_code='600000.SH', start_date='20170101', end_date='20171231')

方式二：通过 query 通用入口

df = pro.query('top10_holders', ts_code='600000.SH', start_date='20170101', end_date='20171231')

两种方式等价，pro.query以字符串形式传入接口名，适合在需要动态拼接接口名的场景下使用；直接方法调用则享受 IDE 补全与参数校验。返回结果均为 pandas DataFrame。

数据样例解读

以浦发银行（600000.SH）2017 年年报（end_date=20171231，公告日ann_date=20180428）为例：

ts_code ann_date end_date holder_name hold_amount hold_ratio 0 600000.SH 20180428 20171231 富德生命人寿保险股份有限公司-传统 2.779437e+09 9.47 1 600000.SH 20180428 20171231 上海国鑫投资发展有限公司 9.455690e+08 3.22 2 600000.SH 20180428 20171231 富德生命人寿保险股份有限公司-万能H 1.270429e+09 4.33 3 600000.SH 20180428 20171231 富德生命人寿保险股份有限公司-资本金 1.763232e+09 6.01 4 600000.SH 20180428 20171231 上海国际集团有限公司 6.331323e+09 21.57 5 600000.SH 20180428 20171231 中国移动通信集团广东有限公司 5.334893e+09 18.18 6 600000.SH 20180428 20171231 中国证券金融股份有限公司 1.216979e+09 4.15 7 600000.SH 20180428 20171231 梧桐树投资平台有限责任公司 8.861313e+08 3.02 8 600000.SH 20180428 20171231 中央汇金资产管理有限责任公司 3.985214e+08 1.36 9 600000.SH 20180428 20171231 上海上国投资产管理有限公司 1.395571e+09 4.75

从样例可以提炼出的信息价值：

• 股权集中度：前十大股东合计持股比例可通过对hold_ratio求和得到（本例约为 76%），远高于一般上市公司，说明浦发银行股权高度集中；
• 股东类型结构：既有国资平台（上海国际集团、上海上国投资产管理），也有产业资本（中国移动广东）、保险资金（富德生命人寿多个账户）与"国家队"（证金、汇金、梧桐树），可据此构建股东性质画像；
• 同一主体的多账户披露：富德生命人寿以"传统/万能H/资本金"三个账户分别列示，分析单一险资合计持仓时应按holder_name前缀聚合。

结合 Vibe-Trading 仓库的工程化实践

1. Token 配置与环境变量注入

在 Vibe-Trading 中调用该接口前，需要正确注入 Tushare Token。仓库在 env_schema.py 中将TUSHARE_TOKEN声明为数据源配置项：

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

即通过环境变量TUSHARE_TOKEN或agent/.env文件配置。启动前的健康检查 preflight.py 会校验该 token：未设置或仍为占位值your-tushare-token时，报告TUSHARE_TOKEN not set (optional)，影响项为 "A-share data unavailable"；若tushare包未安装则标记为skipped；配置正确则状态为ready。此外，settings_routes.py 会把空串与your-tushare-token识别为占位符，确保 token 不会被当作真实凭据误报；cli_handlers.py 在因子命令行工具遇到TUSHARE_TOKEN错误时会给出"注册 token 并写入 agent/.env"的引导提示。示例脚本 stock_data_example.py 展示了标准初始化流程：

import os 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)

2. 落地示例：股权集中度与股东类型分析

结合接口文档与上述 token 配置，一个可直接运行的完整示例（建议在 Vibe-Trading 的agent目录下执行）如下：

import os 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) # 拉取浦发银行 2017 年前十大股东 df = pro.top10_holders(ts_code='600000.SH', start_date='20170101', end_date='20171231') # 前十大股东合计持股比例（股权集中度） print("前十大股东合计持股比例: %.2f%%" % df['hold_ratio'].sum()) # 按股东名称前缀聚合（合并同一主体多账户） df['holder_group'] = df['holder_name'].str.split('-').str[0] grouped = df.groupby('holder_group')['hold_ratio'].sum().sort_values(ascending=False) print(grouped) # 识别国家队席位 nation_team = df[df['holder_name'].str.contains('中国证券金融|中央汇金|梧桐树', na=False)] print(nation_team[['holder_name', 'hold_ratio']])

3. 与周边参考数据接口的组合使用

top10_holders不应孤立使用。在 Vibe-Trading 的 tushare 技能"股票数据/参考数据"目录下，它与以下接口组合可构成完整的股东研究链路：

• 前十大流通股东：同一股票同一报告期下，比较"总股本口径"与"流通股本口径"的十大股东名单差异，识别限售股份分布；
• 股东增减持（stk_holdertrade）：用hold_change定位到发生变动的股东后，进一步通过增减持接口获取变动数量、平均价格与变动后持股比例，验证减持是否发生在股价高位；
• 股东人数（stk_holdernumber）：十大股东集中度上升且股东户数下降，是筹码集中的经典信号组合。

这套"十大股东 + 流通股东 + 增减持 + 股东户数"的数据组合，可作为基本面研究、因子库构建或投研 Agent 的参考数据输入。在 Vibe-Trading 中，tushare 技能通过标准化 API 方式统一了数据资产的对外服务方式，Agent 可根据任务需要从 SKILL.md 的接口列表中按分类检索并调用对应接口，top10_holders即属于其中 A 股股权结构研究的高价值数据源之一。

注意事项

• 数据时点口径：end_date为报告期（一般取季度最后一天），ann_date为公告日期，两者存在数月时间差。进行事件研究时应以ann_date作为信息可得性时点，避免用未来信息回填；
• 积分与频次：2000 积分是硬门槛，5000 积分以上调用频次更高。批量拉取全市场数据时建议按ts_code分片、按period循环，配合start_date/end_date控制请求量，并做好重试与休眠策略，以免触发限流；
• 返回列完整性：数据样例仅展示了ts_code / ann_date / end_date / holder_name / hold_amount / hold_ratio六个字段，实际输出还包含hold_float_ratio、hold_change、holder_type等字段，可按需通过fields参数裁剪；
• 数量单位：hold_amount单位为"股"，hold_ratio、hold_float_ratio单位为百分比，样例中的科学计数法需在分析时统一换算。

小结

本文以 Vibe-Trading 仓库中 前十大股东.md 文档为骨架，完整覆盖了top10_holders接口的权限要求、输入输出参数、两种调用方式与真实数据样例，并结合仓库的 token 配置、环境变量注入、健康检查与示例脚本，给出了可运行的股权集中度分析代码和与流通股东、增减持、股东户数等接口的组合用法。掌握了这些内容，即可在 Vibe-Trading 中稳定获取 A 股前十大股东数据，并进一步构建机构持仓追踪、筹码集中度因子等量化研究能力。

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