Vibe-Trading 数据接入实战：Tushare AH 股比价接口（stk_ah_comparison）从调用到策略应用全解析-港品优选

Vibe-Trading 数据接入实战：Tushare AH 股比价接口（stk_ah_comparison）从调用到策略应用全解析

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

本文围绕 Vibe-Trading 开源项目中 Tushare 技能体系内的AH 股比价接口（stk_ah_comparison）展开，完整讲解其权限门槛、更新机制、输入/输出参数、Python 调用方式与数据样例解读，并结合仓库源码揭示 A/H 比价与溢价指标的计算逻辑、token 配置与限流退避机制，以及其在跨市场估值与信号构建中的实际用法。读完本文，你将能够独立完成 AH 股比价数据的批量提取、字段含义解读，并掌握将比价数据接入双地上市股票研究流程的完整方案。

一、接口概览：用一条接口对齐 A 股与 H 股两个市场

AH 股比价数据描述的是同一家公司分别在内地（A 股）与香港（H 股）两地上市时，两市场价格之间的相对关系。Vibe-Trading 项目将 Tushare 作为数据源技能之一，在 agent/src/skills/tushare/SKILL.md 的接口总表中登记了该接口（ID 399），所属分类为「股票数据 > 特色数据」，标题即「AH股比价」，接口名stk_ah_comparison。

该接口的核心能力与约束如下：

属性	说明
接口名	`stk_ah_comparison`
数据描述	AH 股比价数据，可根据交易日期获取历史
权限要求	5000 积分起
更新机制	每天盘后 17:00 更新
单次请求上限	最大返回 1000 行数据，可循环提取
历史起点	数据从 20250812 开始，历史不好补充，只能累积

值得特别注意的是「只能累积」这一约束：该接口没有可回溯的早期历史，数据自 2025-08-12 起逐日累积。因此任何依赖该接口的历史回测，都只能覆盖该起始日之后的区间；想要更长时间维度的 AH 溢价研究，需要通过持续每日抓取来自建时间序列。

二、输入参数详解

接口共提供 5 个可选输入参数，全部为非必填，可通过自由组合定位数据范围：

名称	类型	必选	描述
`hk_code`	str	N	港股股票代码（`xxxxx.HK`，如`02068.HK`）
`ts_code`	str	N	A 股股票代码（`xxxxxx.SH/SZ/BJ`，如`601068.SH`）
`trade_date`	str	N	交易日期（格式`YYYYMMDD`，下同）
`start_date`	str	N	开始日期
`end_date`	str	N	结束日期

参数组合的典型用法包括：

不传任何参数无法直接调用，通常需要至少一个定位条件；
传trade_date可获取单日全市场 AH 比价快照（这正是文档示例中的用法）；
传hk_code或ts_code可锁定单只双地上市股票；
传start_date/end_date可提取一段日期区间内全部或单只股票的比价历史；
代码后缀遵循 Tushare 统一约定：A 股为.SH/.SZ/.BJ（沪、深、北交所），港股为.HK，这一约定与仓库中 agent/backtest/loaders/tushare.py 的符号识别逻辑一致——该 Loader 通过_is_hk_equity()识别以.HK结尾的港股代码，通过_is_index()区分以000xxx.SH/399xxx.SZ开头的指数代码，确保不同市场的数据路由到正确的数据源。

三、输出参数详解：读懂比价与溢价两个核心字段

接口每次返回一行记录，代表一个「交易日期 × 双地股票对」，共 10 个输出字段：

名称	类型	默认显示	描述
`hk_code`	str	Y	港股股票代码
`ts_code`	str	Y	A 股股票代码
`trade_date`	str	Y	交易日期
`hk_name`	str	Y	港股股票名称
`hk_pct_chg`	float	Y	港股股票涨跌幅
`hk_close`	float	Y	港股股票收盘价
`name`	str	Y	A 股股票名称
`close`	float	Y	A 股股票收盘价
`ah_comparison`	float	Y	比价(A/H)
`ah_premium`	float	Y	溢价(A/H)%

其中hk_close与close分别为港股（港元计价）与 A 股（人民币计价）的收盘价，涨跌幅hk_pct_chg与pct_chg反映两市场当日走势分歧。而两个核心衍生指标ah_comparison与ah_premium则是跨市场估值分析的关键：

ah_comparison（比价 A/H）：A 股价格相对 H 股价格（经汇率换算后）的倍数。当它大于 1 时，表示 A 股相对更贵；小于 1 时，表示 H 股相对更贵。
ah_premium（溢价 A/H %）：A 股相对 H 股的溢价率，从文档数据样例可以推断ah_premium ≈ (ah_comparison − 1) × 100。例如中铝国际（601068.SH / 02068.HK）当日ah_comparison = 2.16、ah_premium = 115.84，即 A 股相对 H 股溢价约 115%。

注意：比价需要将港元计价换算为人民币口径，因此实际数值隐式包含了当日的汇率因素。这一口径与仓库中 agent/src/skills/adr-hshare/SKILL.md 给出的通用公式一致：AH Premium = (A-share price / H-share price in CNY terms - 1) × 100%，该技能文档还提供了将 HKD 换算为 CNY 的汇率处理代码（h_price_cny = h_price_hkd * (usdcny / usdhkd)），可用于自行验证或重算比价。

四、Python 调用实战

4.1 基础用法：拉取单日全市场快照

文档给出的最简用法是直接按trade_date提取某一天全部 AH 股比价数据：

import tushare as ts pro = ts.pro_api() # 获取 20250812 日所有的 AH 股比价数据 df = pro.stk_ah_comparison(trade_date='20250812') print(df.head())

返回结果是一个 pandas DataFrame，列即第三节中的 10 个输出字段。

4.2 按股票或日期区间定向提取

对于单只双地上市股票的历史比价跟踪，可以组合ts_code（或hk_code）与起止日期：

# 单只 A 股对应的 H 股比价历史 df = pro.stk_ah_comparison(ts_code='601068.SH', start_date='20250812', end_date='20250930') # 单只港股对应的 A 股比价历史 df = pro.stk_ah_comparison(hk_code='03993.HK', start_date='20250812', end_date='20250930')

4.3 应对 1000 行上限：按日循环全量累积

文档提示「单次请求最大返回 1000 行数据，可循环提取」。当前 A + H 双地上市股票对约百余组（见文档样例行号延伸至 159 行），单日调用通常不会触顶，但当提取跨多日长区间时，应按交易日逐日循环，并对每次返回的行数做检查，将结果累积拼接：

import pandas as pd import tushare as ts pro = ts.pro_api() # 以 Tushare 交易日历（trade_cal）为准，也可用 start/end 区间配合循环 frames = [] for trade_date in ['20250812', '20250813', '20250814']: # 实际应循环交易日历 batch = pro.stk_ah_comparison(trade_date=trade_date) if batch is not None and len(batch): frames.append(batch) df = pd.concat(frames, ignore_index=True)

这种「逐日循环 + 增量累积」的方式，正好契合该接口「只能累积」的数据特性：从 20250812 起每天盘后 17:00 更新后及时抓取，即可逐步构建起自己的 AH 比价时间序列数据库。

4.4 在 Vibe-Trading 环境中配置 token

仓库中所有 Tushare 调用的统一凭证入口是TUSHARE_TOKEN环境变量。技能示例脚本 agent/src/skills/tushare/scripts/stock_data_example.py 展示了标准初始化方式：

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

对应的环境变量声明位于 agent/src/config/env_schema.py（tushare_token: str = Field(alias="TUSHARE_TOKEN", default="")），并在 agent/src/preflight.py 的_check_tushare()预检中被校验——预检会识别空值或your-tushare-token这类占位符并给出提示，引导用户到 Tushare 官网注册并配置真实 token。

五、仓库源码支撑：比价数据在 Vibe-Trading 中的落地路径

虽然stk_ah_comparison属于「特色数据」类目、并不在行情 Loader 的常规 OHLCV 路径上，但仓库为整个 Tushare 数据接入提供了完整的工程化支撑，理解这些机制有助于把 AH 比价接口稳定地跑在生产级流程中：

Token 统一管理与占位符防御：agent/backtest/loaders/tushare.py 定义了TUSHARE_TOKEN_PLACEHOLDERS = {"", "your-tushare-token"}，凡是未配置真实 token 的调用都会被判定为不可用，防止静默失败。
限流退避机制：Tushare 积分体系决定了每分钟调用频次上限。Loader 中实现了_call_with_backoff()，通过_is_rate_limited()匹配「每分钟/每天/抽取/频率/rate limit」等特征文案识别配额拒绝，并按(5.0, 20.0, 40.0)秒的退避序列重试——跨越一分钟的配额窗口后恢复调用。调用stk_ah_comparison做批量循环提取时，同样适用这一「遇限流即退避」的工程经验，避免高频请求触发风控。
积分与权限分级：Tushare 各接口按积分分级开放（AH 股比价要求 5000 积分起），stk_ah_comparison属于高权限特色接口。积分决定单位时间流量上限，「积分越高流量越大」，因此对于需要全市场批量循环的场景，建议优先保证积分充足，再配合退避策略稳妥提取。

六、数据样例解读：一份真实的 AH 比价快照

以下为文档提供的 20250812 当日部分数据样例（节选）：

hk_code	ts_code	hk_name	hk_pct_chg	hk_close	name	close	pct_chg	ah_comparison	ah_premium
02068.HK	601068.SH	中铝国际	0.78	2.60	中铝国际	5.14	0.00	2.16	115.84
03993.HK	603993.SH	洛阳钼业	0.60	10.07	洛阳钼业	9.85	0.31	1.07	6.80
06066.HK	601066.SH	中信建投证券	1.77	13.25	中信建投	26.09	0.66	2.15	114.99
06680.HK	300748.SZ	金力永磁	-5.67	18.30	金力永磁	27.30	-3.05	1.63	62.88
02333.HK	601633.SH	长城汽车	3.55	14.60	长城汽车	22.93	1.82	1.71	71.48
01065.HK	600874.SH	天津创业环保股份	2.24	4.10	创业环保	6.01	0.00	1.60	60.05

解读要点：

溢价水平的横截面差异：同一交易日不同股票对的溢价差异极大（从洛阳钼业的 6.80% 到中铝国际的 115.84%），说明 AH 溢价既有系统性因素（投资者结构、流动性、汇率预期），也有个股层面的独立因素，横截面排序本身就是一条有用的研究线索。
A 股普遍溢价现象：从样例看绝大多数 A 股相对 H 股存在溢价，这与仓库 agent/src/skills/hk-connect-flow/SKILL.md 中对恒生 AH 溢价指数（HSAHP）的解读框架一致：A 股高零售参与度带来流动性溢价、历史上外资准入受限带来稀缺性溢价、CNY 贬值预期会进一步拉大溢价。
两地市场当日涨跌分歧：金力永磁当日 A 股下跌 3.05% 而港股下跌 5.67%，两地价格同步波动但幅度不同，为观察跨市场情绪传导提供了直接素材。

七、从比价数据到策略信号：AH 溢价分析框架

拿到ah_premium时间序列后，可以借助仓库中已有的分析技能将其转化为可执行的信号：

1. 溢价区间解读（agent/src/skills/adr-hshare/SKILL.md）：

溢价水平	解读	倾向性动作
>50%	A 股高溢价极端，A 股投机泡沫或 H 股极端低估	偏多 H、回避 A
30%–50%	高溢价，对高散户参与度标的是常态	同等基本面下温和偏好 H
10%–30%	大多数 AH 组合的正常区间	中性，无强套利信号
0%–10%	溢价压缩，A 股相对便宜	异常，需研究催化剂
<0%	H 股反超 A 股	极少见，通常为事件驱动

2. 均值回归 z-score 信号：该技能给出了基于历史均值和标准差的信号生成方式——当某只股票溢价相对其 12 个月均值偏离超过 2 个标准差时，发出「fade premium」（做多 H 回避 A）或「buy premium」信号。

3. 与南北向资金联动（agent/src/skills/hk-connect-flow/SKILL.md）：当 AH 溢价指数超过 130 时，套利资金倾向经港股通（南向）买入更便宜的 H 股；反之溢价压缩到 110 以下时，A 股相对便宜，需要重点调查原因。该技能还提供多维打分框架，将南北向资金流、AH 溢价、汇率方向综合为 −10 到 +10 的跨境风险偏好得分。

需要说明的是，AH 股之间不可自由互换（与 ADR/H 股的存托转换不同），真正的套利需要两套独立的资金池，因此溢价更多被用作估值参照与情绪信号，而非可执行的瞬时套利工具——这一点在 agent/src/skills/adr-hshare/SKILL.md 的 Notes 中有明确提示。

八、实战注意事项与 FAQ

历史窗口有限：数据自 20250812 起，无法回补更早历史。做长期研究需从启用日起每日盘后（17:00 后）持续累积。
积分门槛：stk_ah_comparison需要 5000 积分起，且单位分钟有流控，积分越高流量越大；未达标时接口会返回权限类错误，需先提升积分。
单次 1000 行上限：长区间提取务必按交易日循环并拼接结果，同时结合退避策略控制调用频率（参考 agent/backtest/loaders/tushare.py 的限流识别与重试实现）。
汇率口径：ah_comparison/ah_premium已隐含汇率换算（港元折算为人民币），如需自建指标或验证数据，可参照 agent/src/skills/adr-hshare/SKILL.md 中的换算公式。
代码格式：港股代码为xxxxx.HK（如02068.HK），A 股代码为xxxxxx.SH/SZ/BJ，混用格式会导致查不到数据。
与常规行情接口的关系：A 股日线（daily）、港股日线（hk_daily）等行情接口只提供单市场价格，stk_ah_comparison的价值在于一次性给出配对后的双市场收盘价、涨跌幅与比价/溢价衍生指标，省去了自行按股票对配对的繁琐步骤。

九、总结

stk_ah_comparison是 Vibe-Trading Tushare 技能体系中「股票数据 > 特色数据」类目下的高频价值接口，它把双地上市公司的 A/H 收盘价、涨跌幅与比价、溢价浓缩在单次调用内，配合 5000 积分门槛、每日盘后更新与单次 1000 行的限制，构成了稳定的每日增量数据源。通过本文的调用示例、字段拆解与源码佐证，你可以直接在仓库的 Tushare 技能框架（agent/src/skills/tushare/SKILL.md、agent/src/skills/tushare/scripts/stock_data_example.py）之上构建属于自己的 AH 溢价时间序列，并进一步结合 agent/src/skills/adr-hshare/SKILL.md 与 agent/src/skills/hk-connect-flow/SKILL.md 的分析框架，将原始比价数据转化为可解释、可验证的跨市场策略信号。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析