Vibe-Trading 港股基本面数据接入实战：Tushare hk_cashflow 现金流量表接口完全指南

Vibe-Trading 港股基本面数据接入实战：Tushare hk_cashflow 现金流量表接口完全指南

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

本文为 Vibe-Trading 个人交易 Agent 内置数据技能（Tushare Skill）中的港股财务数据接口实战指南，核心围绕hk_cashflow接口展开。通过本文，读者将完整掌握港股上市公司现金流量表数据的接口参数、调用方式、返回结构与数据解读方法，并能在此基础上构建面向港股标的的盈利质量与现金流分析流程。

接口概览：从 Skill 注册表到hk_cashflow

在 Vibe-Trading 仓库中，Tushare 数据源以技能（Skill）形式组织，其入口文档 SKILL.md 中维护了一张完整的"数据接口列表"，覆盖行情、财务、宏观、基金、债券等数百个接口。其中：

• 接口 ID：391
• 接口名：hk_cashflow
• 接口标题：港股现金流量表
• 所属分类：港股数据
• 接口描述：获取港股上市公司现金流量表数据

该接口与同属港股财务数据族的 港股利润表（hk_income，ID 390）、港股资产负债表（hk_balancesheet，ID 389）、港股财务指标数据（hk_fina_indicator，ID 388）共同构成港股三张报表的完整数据能力，可满足港股基本面的量化研究、回测因子构建与实时分析需求。

权限说明

调用hk_cashflow需要单独开通接口权限，或账户积分达到15000 分。该接口并非所有 Tushare 用户默认可用，接入前请先在 Tushare 账户中确认权限状态，避免运行时出现权限异常。

数据特征

• 当前接口按单只股票获取其历史数据；
• 单次请求最大返回 10000 行数据；
• 历史数据较长时，可通过循环分页提取（配合start_date/end_date参数分批拉取）。

输入参数详解

hk_cashflow共支持 5 个输入参数，其中仅ts_code为必选，其余参数均可选，用于精确筛选数据范围。

各参数实战要点：

• ts_code（必选）：港股代码采用「数字代码 +.HK」后缀格式，例如腾讯控股为00700.HK。注意与 A 股代码格式（如000001.SZ、600000.SH）区分。如需获取全部港股代码清单，可配合 港股基础信息（hk_basic）接口取得。
• period（可选）：指定精确报告期，格式为YYYYMMDD，如20241231表示 2024 年年度报告。港股财年并非全部与自然年一致，个别公司财报期可能为 3 月、6 月等截止日，需按标的实际报告期传入。
• ind_name（可选）：按财务科目名称过滤，如新增借款、经营业务现金净额等。通过该参数可以一次性提取某一科目跨多个报告期的历史序列，非常适合做指标时序分析。
• start_date/end_date（可选）：报告期范围过滤。当需要拉取多年历史数据且单次请求可能超过 10000 行上限时，用这两个参数配合循环分页最为稳妥。

输出参数与返回结构

接口返回为长表（tidy）结构的 pandas DataFrame，每一行对应"某只股票 + 某个报告期 + 某个财务科目"的一条记录：

需要特别理解的是长表结构：同一报告期内，现金流量表的所有科目（数十个）会被拆成多行返回，通过ind_name字段区分科目、ind_value字段给出数值。这种结构天然适合用pivot操作将"科目"转置为列，再与其他指标合并构建面板数据。仓库中的财务分析技能 financial-statement/SKILL.md 正是基于此类三表数据开展盈利质量与现金流分析。

数据样例解读：以腾讯控股 2024 年报为例

原文档给出的数据样例为腾讯控股（00700.HK）2024 年度（20241231）现金流量表，节选科目完整覆盖了经营、投资、融资三大活动，非常适合用来理解港版现金流科目命名习惯：

ts_code end_date name ind_name ind_value 0 00700.HK 20241231 腾讯控股 除税前溢利(业务利润) 2.414850e+11 ... 11 00700.HK 20241231 腾讯控股 营运资金变动前经营溢利 2.828240e+11 19 00700.HK 20241231 腾讯控股 经营产生现金 3.047050e+11 21 00700.HK 20241231 腾讯控股 经营业务现金净额 2.585210e+11 ... 32 00700.HK 20241231 腾讯控股 投资业务现金净额 -1.221870e+11 44 00700.HK 20241231 腾讯控股 融资业务现金净额 -1.764940e+11 45 00700.HK 20241231 腾讯控股 现金净额 -4.016000e+10 ... 49 00700.HK 20241231 腾讯控股 应收帐款减少 -1.048000e+09

经营业务（CFO）部分

从"除税前溢利（业务利润）"出发，经过利息支出、折旧及摊销（5.621300e+10）、减值及拨备等加回项，以及投资收益、汇兑收益、出售资产之溢利等减除项，得到"营运资金变动前经营溢利"（2.828240e+11）；再叠加存货、应收应付、递延收入等营运资本变动，得到"经营产生现金"（3.047050e+11）；扣除"已付税项"（4.618400e+10）后，最终得到经营业务现金净额2.585210e+11。该数值与利润表中的"股东应占溢利1.940730e+11"（见 港股利润表 样例）明显同向且规模相当，符合"净利润 ≈ CFO（长期来看）"的黄金公式。

投资业务（CFI）部分

涵盖已收利息、已收股息（投资）、存款减少（增加）、购建无形资产及其他资产、收购附属公司、收回投资所得现金等科目，最终投资业务现金净额为-1.221870e+11，反映了公司持续对外扩张投资的现金流出特征。

融资业务（CFF）部分

包含新增借款（1.145840e+11）、偿还借款（1.146910e+11）、已付利息（融资）、已付股息（融资）、回购股份（1.057510e+11）、赎回债券、偿还融资租赁等科目，最终融资业务现金净额为-1.764940e+11。腾讯 2024 年大规模回购与派息直接体现在该板块。

勾稽关系验证

按financial-statement/SKILL.md中的勾稽公式：

期末现金 = 期初现金 + CFO + CFI + CFF 1.325190e+11 ≈ 1.723200e+11 + 2.585210e+11 + (-1.221870e+11) + (-1.764940e+11)

三者之和与期末现金高度吻合，说明该接口数据可用于跨报表一致性校验。这也印证了 financial-statement/SKILL.md 中"三表勾稽关系"章节的实操价值——将现金流量表与利润表、资产负债表联合使用，可检验财务数据质量、识别盈利质量异常。

接口用法与代码实战

原文档给出的标准调用方式如下：

pro = ts.pro_api() # 获取腾讯控股00700.HK股票的2024年度现金流量表数据 df = pro.hk_cashflow(ts_code='00700.HK', period='20241231') # 获取腾讯控股00700.HK股票历年新增借款数据 df = pro.hk_cashflow(ts_code='00700.HK', ind_name='新增借款')

进阶一：带 token 的完整初始化

参照仓库示例脚本 scripts/stock_data_example.py 与 SKILL.md 的快速上手章节，生产环境建议显式传入 token（从环境变量或本地配置读取），而非依赖默认配置：

import os import tushare as ts # 方式一：环境变量（推荐） token = os.getenv('TUSHARE_TOKEN') # 方式二：仓库示例脚本采用的配置读取方式（见 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) df = pro.hk_cashflow(ts_code='00700.HK', period='20241231') print(df)

在 Vibe-Trading 项目中，Token 可通过 Tushare 官网注册获取后，配置环境变量TUSHARE_TOKEN（参照 SKILL.md 中的export TUSHARE_TOKEN=your_token说明），或复用项目配置体系中tushare_token的读取逻辑。

进阶二：长表转宽表，构建指标面板

由于接口返回长表结构，做跨报告期分析时通常需要透视：

# 获取腾讯控股 2022-2024 三个年度的全部现金流量表数据 df = pro.hk_cashflow(ts_code='00700.HK', start_date='20220101', end_date='20241231') # 透视：行 = 报告期，列 = 财务科目 pivot = df.pivot_table(index='end_date', columns='ind_name', values='ind_value', aggfunc='first') print(pivot[['经营业务现金净额', '投资业务现金净额', '融资业务现金净额', '现金净额', '期末现金']])

进阶三：按报告期循环分页提取全历史

对于上市时间长的标的，单只股票全历史数据可能超过 10000 行的单次上限。此时应结合start_date/end_date按年度或按区间循环提取，再concat合并：

import pandas as pd pro = ts.pro_api(token) frames = [] for year in range(2010, 2025): start, end = f"{year}0101", f"{year}1231" part = pro.hk_cashflow(ts_code='00700.HK', start_date=start, end_date=end) if part is not None and not part.empty: frames.append(part) full = pd.concat(frames, ignore_index=True) print(f"共提取 {len(full)} 行记录，报告期范围：", full['end_date'].min(), "~", full['end_date'].max())

实战应用：将港股现金流数据接入 Agent 分析流程

在 Vibe-Trading 的 Agent 体系内，Tushare Skill 作为标准化的数据资产服务入口（详见 SKILL.md 概述），其港股财务数据可直接服务于以下分析场景：

1. 盈利质量检验：结合 financial-statement/SKILL.md 中的现金流质量矩阵（CFO/CFI/CFF 正负组合判断企业处于优秀、扩张、危险还是困境状态），对港股标的进行现金流画像。例如样例中腾讯 "CFO 为正、CFI/CFF 为负" 的组合对应"优秀（赚钱、投资、还债/回报股东）"状态。
2. 应计比率计算：利用经营业务现金净额与利润表中净利润的差构造应计比率（accrual_ratio = (net_income - cfo) / total_assets），识别盈利质量恶化信号。
3. 跨市场对照：A 股对应接口为 股票数据/财务数据/现金流量表.md（cashflow），美股对应 美股现金流量表.md（us_cashflow）。由于 A 股采用中国会计准则、港股/美股采用 IFRS/US GAAP，科目名称与口径存在差异，跨市场比较前需要做科目映射与口径调整——这一点在 financial-statement/SKILL.md 的财报会计准则差异说明中亦有提示。
4. 回购与分红跟踪：通过回购股份、已付股息(融资)等科目筛选高股东回报标的，可作为价值型策略的补充信号。

相关接口与延伸阅读

常见问题与注意事项

• 权限不足：报错提示权限问题时，请检查 Tushare 账户积分（需 15000 分）或单独开通hk_cashflow接口权限，可用官方数据工具在线调试接口确认数据与权限状态。
• 代码格式：港股代码必须带.HK后缀（如00700.HK），与 A 股、美股代码体系不同，混淆会导致查无数据。
• 长表与透视：返回的是"科目 × 报告期"的长表，分析前建议用pivot_table转宽，并用ind_name精确匹配科目名称（如经营业务现金净额、期末现金）。
• 单次行数上限：单次最多返回 10000 行，全历史拉取务必按start_date/end_date分片循环。
• 财年口径：港股公司财年截止日不统一，period参数请按目标公司的实际报告期传入，避免与自然年混用。

至此，从接口注册信息、参数语义、返回结构、代码调用到财务分析实战，hk_cashflow接口的完整链路已经打通。读者可直接基于本文示例，在 Vibe-Trading 的 Agent 工作流中构建属于自己的港股现金流分析模块。

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