Funds Holding Analysis

2. 接口调用

本 Skill 提供了 Python 脚本封装 API 调用逻辑,支持自动处理基金列表的循环查询。

方式一: 使用 Python 脚本(推荐)

脚本位置: scripts/query_fund_holdings.py

脚本特性:

• ✅ 自动检查环境变量 TTFUND_APIKEY
• ✅ 支持单只基金和基金列表查询
• ✅ 自动循环调用单只基金接口(底层 API 仅支持单只查询)
• ✅ 聚合查询结果并生成报告
• ✅ 支持部分失败容错
• ✅ 支持 JSON 格式输出

使用示例:

# 查询单只基金
python scripts/query_fund_holdings.py 015916

# 查询多只基金(自动循环调用)
python scripts/query_fund_holdings.py 015916 018419 110011

# 指定报告期和持仓类型
python scripts/query_fund_holdings.py 015916 --report-period 2024-Q3 --holding-type stock

# 输出 JSON 格式
python scripts/query_fund_holdings.py 015916 --json

# 仅输出汇总信息
python scripts/query_fund_holdings.py 015916 018419 --summary-only

# 保存报告为 Markdown 文件
python scripts/query_fund_holdings.py 015916 018419 --save

脚本参数说明:

方式二: 直接调用 API

使用 POST 请求调用统一网关接口,apikey 放入 X-API-Key 请求头。

请求要求:

• 每次请求必须携带 skill_id 和 _skill_version
• _skill_version 必须填写: 1.1.0
• 注意: 底层 API 仅支持单只基金查询(fund_id 参数),批量查询需循环调用

调用示例:

# 单只基金查询
curl --location 'https://skills.tiantianfunds.com/ai-smart-skill-service/openapi/skill/invoke' \
--header "X-API-Key: $TTFUND_APIKEY" \
--header 'Content-Type: application/json' \
--data '{
  "skill_id": "FUND_HOLDING_INFO",
  "_skill_version": "1.1.0",
  "fund_id": "025209",
  "holding_type": "all"
}'

请求参数

编排流程说明

该 skill 使用服务端 workflow 自动完成名称解析、数据获取与结果聚合,对调用方透明。

• 若已提供 fcode,服务端优先直查;缺少时可根据 fund_id 自动解析候选代码
• 服务端自动执行内部步骤并完成聚合,当前配置共包含 4 个业务步骤
• 文档中的返回字段说明仅面向最终业务结果 data.raw_result.body,不展开内部字段映射关系

参数列表

单只基金查询(底层 API)

重要说明:

• 底层 API 仅支持单只基金查询(fund_id 参数)
• 批量查询需通过脚本循环调用,脚本会自动处理并聚合结果
• 脚本使用方式: python scripts/query_fund_holdings.py 015916 018419 000001

问句示例

返回结果

业务结果根节点

返回数据位于 data.raw_result.body:

核心字段说明

基金基础信息 (data.fund_profile)

持仓概览 (data.holding_overview)

持仓明细 (data.top_holdings)

股票持仓 (stock):

• GPJC: 股票名称列表
• GPDM: 股票代码列表
• JZBL: 占净值比例列表(百分比)
• PCTNVCHGTYPE: 变化类型(新增/增持/减持/不变)
• PCTNVCHG: 较上期变化幅度
• INDEXCODE: 所属行业代码
• INDEXNAME: 所属行业名称
• HOLDCOUNT: 进入重仓列表的期数

其他持仓:

• bond: 债券重仓列表
• fof: FOF 底层基金持仓列表
• etf_code: ETF 联接基金对应的 ETF 代码
• etf_shortname: ETF 联接基金对应的 ETF 简称

配置信息

AI 摘要 (data.ai_summary)

其他信息

输出规范

单只基金报告

按以下顺序展示:

1. 基金基础信息

• 基金代码、名称、类型
• 报告期

2. AI 持仓摘要 ⭐

• 展示 data.ai_summary.text 完整内容
• 标注摘要对应日期

3. 行业配置明细 ⭐

• 按配置比例降序排列
• 前 8 大行业必须标注具体百分比
• 展示:行业名称、配置比例、较上期变化、代表持仓股

示例格式:

行业配置(前8大):
1. 电子信息  25.3%  ↑2.1%  代表:贵州茅台、立讯精密
2. 医药生物  18.7%  ↓1.5%  代表:恒瑞医药、药明康德
3. 消费      15.2%  —      代表:五粮液、美的集团
...

4. 资产配置结构

• 股票、债券、现金、其他资产占比

5. 十大重仓股

• 股票名称、代码、占净值比例、变化类型、所属行业

6. 风险提示

• 数据滞后说明
• 风险提示语

基金列表批量报告

1. 汇总概览表

2. 逐只基金详细报告

对每只基金按"单只基金报告"格式依次展示

3. 对比分析(可选)

• 行业配置差异对比
• 持仓集中度比较
• 投资风格区分
• 风险收益特征对比

4. 批量处理说明

• 成功/失败基金数量
• 失败基金及原因(如有)
• 数据截止日期

输出顺序: 汇总概览表 → 详细报告 → 对比分析

交互规范

1. 优先检查环境变量 TTFUND_APIKEY
2. 存在则继续,不存在则中断并提示配置
3. 每次请求必须带上 skill_id 和 _skill_version: 1.1.0
4. 缺少参数时提示补充 fund_id 或 fund_list
5. 返回结果时优先提炼核心信息,不堆砌所有字段
6. 结果解释顺序:业务结果 → version_info → 升级建议

基金列表处理规范

• 底层 API 限制: 底层 API 仅支持 fund_id 参数(单只基金)
• 脚本自动处理: 使用 scripts/query_fund_holdings.py 脚本时,传入多个基金代码会自动循环调用
• 查询完成后,先生成汇总概览表,再展示详细报告
• 重点突出 AI 持仓摘要和行业配置比例
• 提供可选的对比分析视角
• 部分基金失败时不影响其他基金的查询和展示

错误处理

批量查询特殊处理

• 脚本自动处理: 使用 scripts/query_fund_holdings.py 脚本时自动处理以下逻辑
• 部分基金失败时,继续展示成功的基金报告
• 在报告开头明确列出失败基金及原因
• 不得因单只基金失败而中断整体查询
• 提示示例: 共查询 X 只基金,成功 Y 只,失败 Z 只。失败基金:[基金代码] - [失败原因]
• 脚本会在 stderr 输出进度信息,stdout 输出结果

版本升级提示

• 若 data.version_info.is_outdated = true,完成本次回答后附加升级提醒
• 若返回升级导向错误,不要盲重试,直接提示用户升级 skill
• 若为普通业务错误且无版本归因信号,按原逻辑处理

安全与边界

• 返回数据仅供参考,不构成投资建议
• AI 持仓摘要为智能分析结果,仅供参考
• 行业配置数据基于最新披露定期报告,可能存在滞后,注意 data_lag_notice
• 批量查询建议单次不超过 20 只基金,脚本会自动检查并提示
• 不伪造结果或输出未验证内容
• 数据仅用于当前请求的查询与分析

版本历史

v1.1.0 (当前版本)

• ✨ 新增基金列表批量查询功能(通过脚本循环调用实现)
• ✨ 提供 Python 脚本封装 API 调用逻辑(scripts/query_fund_holdings.py)
• ✨ 强化 AI 持仓摘要输出展示
• ✨ 完善行业配置明细比例数字展示要求
• ✨ 新增批量报告汇总概览表
• 🔧 优化错误处理,支持部分失败容错展示
• 🔧 明确底层 API 仅支持单只基金查询,批量查询通过脚本实现