企业官网建设流程全解析

Vibe-Trading 港股实时日线数据接入：Tushare rt_hk_k 接口通配符取数与盘中监控实战

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

港股市场实行 T+0 交易且日内波动频繁，实时行情是盘中监控、异动预警与短周期策略的重要数据源。本文以仓库内 Tushare 技能文档 为核心骨架，系统讲解 Vibe-Trading 项目中对 Tusharert_hk_k接口的调用方式：从 token 初始化、.HK后缀与通配符代码语法、8 个输出字段的业务含义，到单股取数、全市场批量快照、盘中轮询监控的完整实战代码。读完本文，你将能够在 Vibe-Trading 环境中独立搭建一条港股实时日线数据链路，并理解它与hk_daily历史行情接口的定位差异。

接口概览：rt_hk_k 是什么

在 Tushare 技能文档 的数据接口列表中，rt_hk_k的登记信息如下：

与收盘后批量入库的hk_daily不同，rt_hk_k返回的是从今日开盘到当前时刻的实时日线截面数据：每一行代表一只港股在当日的实时 OHLC 快照。由于支持通配符，一个请求即可拉取港股全市场的当日实时状态，天然适合做全市场扫描。

环境准备：token 初始化与 pro 接口

在调用任何 Tushare 数据接口前，需要先完成 SDK 安装与 token 配置。根据 SKILL.md 中的快速上手说明，推荐 Python 3.7+ 环境，可优先从清华 PyPI 镜像安装：

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

在 Tushare 官网注册后获取 token，并配置环境变量：

export TUSHARE_TOKEN=your_token

仓库中的 股票数据获取示例脚本 展示了项目内标准的数据访问方式——先读取环境变量中的 token（支持get_env_config().data.tushare_token或ts.get_token()），再初始化 pro 接口：

import tushare as ts import os from src.config.accessor import get_env_config # 读取环境变量中的 token, 或者读取本地记录的 token token = get_env_config().data.tushare_token or ts.get_token() # 初始化 pro 接口实例 pro = ts.pro_api(token)

初始化完成后，pro.rt_hk_k(...)即可直接调用港股实时日线接口。

输入参数：ts_code 与通配符语法

rt_hk_k只有一个输入参数，但这一参数承载了接口最核心的能力——通配符批量取数。

使用要点：

• 必须携带.HK后缀：ts_code代码一定要带.HK后缀，否则无法正确路由到港交所代码空间。这与项目内"港股00700.HK（零填充至 5 位）"的代码约定一致。
• 精确查询：传完整代码（如00001.HK）获取单只股票的实时日线。
• 通配符查询：使用*匹配任意字符序列，例如01*.HK匹配所有以01开头的港股代码，02*.HK匹配所有02开头的代码。接口文档给出的示例即用01*.HK一次性提取"今日开盘以来部分港股实时日线"。
• 全市场提取：由于通配符可以覆盖全部代码形态，结合 5000 条的限量（覆盖全部在交易港股绰绰有余），理论上一个请求即可拉取港股全市场实时快照。

输出参数全解析

rt_hk_k返回 8 个字段，全部默认显示：

字段的业务解读（结合接口文档的数据示例）：

• OHLC 语义：open为今日开盘价；high/low为开盘以来至今的日内最高 / 最低价；close在盘中表示最新成交价，收盘后等同于收盘价。由此可计算当日涨跌幅：(close - pre_close) / pre_close。
• 量额单位：vol单位是股（shares），amount单位是元（港币计价）。由二者可得全市场均价的近似值amount / vol。
• 无成交股票的哨兵值：数据示例中01653.HK一行close=0.0、vol=0.0、amount=0.0而pre_close=0.260，说明该股当日尚无成交（停牌或尚未开市），处理时应将其视为"今日无成交"而非真实价格为 0，否则会误算涨跌幅。
• 返回值形态：与 Tushare 其他接口一致，返回 pandas DataFrame，行索引为记录序号，可直接与 pandas 生态无缝衔接。

接口文档给出的数据示例（节选，通配符查询结果，共 751 行）：

ts_code pre_close close high open low vol amount 0 01508.HK 1.040 1.030 1.050 1.040 1.030 14971000.0 15564320.00 1 01314.HK 0.210 0.211 0.211 0.210 0.210 40000.0 8420.00 2 01848.HK 3.940 3.910 3.950 3.940 3.890 300500.0 1176380.00 ... 746 01653.HK 0.260 0.000 0.000 0.000 0.000 0.0 0.00 747 01729.HK 5.440 5.790 5.800 5.440 5.380 6778621.0 37845706.87

实战一：单股实时日线获取

接口文档给出的标准调用如下，获取特定股票的实时日线：

# 获取特定股票实时日线 df = pro.rt_hk_k(ts_code='00001.HK') # 获取今日开盘以来部分港股实时日线 df = pro.rt_hk_k(ts_code='01*.HK')

将其封装为带异常处理的函数，便于在策略与监控脚本中复用：

def get_hk_realtime_daily(ts_code: str): """ 获取港股实时日线（rt_hk_k） ts_code: 单只代码(00001.HK) 或 通配符(01*.HK) """ try: df = pro.rt_hk_k(ts_code=ts_code) if df is None or df.empty: print(f"无数据返回: {ts_code}") return None # 派生盘中涨跌幅 df['pct_chg'] = (df['close'] - df['pre_close']) / df['pre_close'] * 100 return df except Exception as e: print(f"获取港股实时日线失败 ({ts_code}): {e}") return None

注意：对close=0的无成交股票，计算涨跌幅前应过滤或置空，避免-100%的假信号。

实战二：全市场批量快照与盘中轮询监控

通配符接口最常见的用途是全市场扫描。由于单次限量 5000 条且覆盖全部在交易港股，可以这样拉取全市场快照：

# 提取港股全市场实时日线快照（单次请求） market_snapshot = pro.rt_hk_k(ts_code='*.HK')

在盘中做定时轮询，即可构建简单的异动监控：

import time import datetime def monitor_hk_market(interval_seconds=60, max_rounds=120): """ 盘中轮询港股全市场实时快照，输出当日涨幅榜前 10 """ for i in range(max_rounds): now = datetime.datetime.now() df = pro.rt_hk_k(ts_code='*.HK') if df is not None and not df.empty: live = df[df['close'] > 0].copy() live['pct_chg'] = (live['close'] - live['pre_close']) / live['pre_close'] * 100 top = live.nlargest(10, 'pct_chg')[['ts_code', 'close', 'pre_close', 'pct_chg', 'amount']] print(f"[{now:%H:%M:%S}] 全市场 {len(live)} 只有效成交，涨幅榜前10：") print(top.to_string(index=False)) time.sleep(interval_seconds) # 调用前需确保 pro 已初始化 # monitor_hk_market(interval_seconds=60)

建议将轮询结果持久化到 DataFrame 并追加保存，盘中结束时即获得一份完整的当日逐笔快照序列，可直接与收盘后入库的hk_daily数据做交叉校验。

数据边界与适用场景

与 hk_daily 历史行情的定位差异

仓库 港股日线行情文档 明确了hk_daily的定位：获取港股每日增量与历史行情，每日 18 点左右更新当日数据，单次最大提取 5000 行记录（可多次提取，总量不限制），且该接口同样需要单独开权限。两者对比如下：

因此正确的数据链路是：盘中用rt_hk_k做实时监控，收盘后用hk_daily拉取并归档当日正式数据，二者结合覆盖完整的数据闭环。

与配套港股接口联动

在 Tushare 技能目录 的港股数据分类下，rt_hk_k与其他接口可组合出更完整的港股研究链路：

• 港股基础信息（hk_basic）：获取港股列表、名称、交易单位、ISIN、货币代码等基础信息，可将实时快照中的ts_code关联出股票名称与交易单位。
• 港股交易日历（hk_tradecal）：返回cal_date、is_open、pretrade_date，用于判断当日是否为港股交易日，避免非交易日的空轮询。
• 港股日线行情（hk_daily）：收盘后正式归档数据，输出多出trade_date、change、pct_chg三个字段，字段描述中的pct_chg为涨跌幅(%)。
• 港股复权因子（hk_adjfactor）与港股复权行情（hk_daily_adj）：中长期策略需复权处理时使用。

典型组合用法：先用hk_basic()拿到全部在交易港股列表 → 盘中用rt_hk_k(ts_code='*.HK')拉实时快照并关联名称 → 收盘后用hk_daily(trade_date=...)归档 → 用hk_tradecal判断下一个交易日。

在 Vibe-Trading 项目中的落地方式

本仓库将 Tushare 封装为 Agent 可调用的数据源技能，入口为 agent/src/skills/tushare/SKILL.md。该技能文档以统一格式登记了全部数据接口（含接口 ID、名称、标题链接、分类、描述），其中rt_hk_k的登记 ID 为 383，接口文档位于 agent/src/skills/tushare/references/港股数据/港股实时日线.md。references/目录下按业务分类存放各接口的详细参数与示例文档，港股数据分类下共收录 11 个港股相关接口文档。

调用数据时，可参考仓库提供的 股票数据获取示例脚本 的编码范式：读取 token →ts.pro_api(token)初始化 → 在try/except中调用接口 → 打印并返回 DataFrame。整个数据源技能通过标准化 API 统一对外服务，帮助 Agent 更实时、简洁、轻量地获取行情与基本面数据。

常见问题与注意事项

• 必须带.HK后缀：rt_hk_k要求ts_code必须携带.HK后缀（如00001.HK），不带后缀或使用其他市场后缀无法正确取数。
• 权限问题：本接口是单独开权限的数据，需要按 Tushare 权限列表单独申请，未开通权限会报权限错误，而非参数错误。
• 5000 条限量：单次最大 5000 条，覆盖全部在交易港股绰绰有余；如需更细粒度处理，可用0*.HK、1*.HK、2*.HK分段拉取，避免一次请求过大。
• 停牌 / 无成交股：close、high、low、vol、amount可能为 0，属正常业务状态而非数据缺失，计算涨跌幅前务必过滤。
• 数据时效：盘中返回的是实时快照，收盘后调用得到当日最终数据；若需要含change、pct_chg的正式字段，请使用收盘后更新的hk_daily。
• 日期格式约定：项目内 Tushare 技能的日期参数统一使用YYYYMMDD格式（如20241231），股票代码使用带后缀的ts_code格式，返回格式统一为 pandas DataFrame，这些约定在编写跨接口调用代码时需保持一致。

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