datayes-data

---
name: datayes-data
description: 通联数据金融数据查询技能 - A股/港股、基金、债券、指数、期货期权、因子、实时行情、宏观、公告与政策
version: "1.0.0"
author: "通联数据 DataYes"
---

# 通联数据 MCP Skill

本 Skill 提供中国金融市场数据的查询能力，覆盖 A股与港股、沪深港通、基金、债券、指数、
期货期权、量化因子、实时行情、宏观行业指标、公告、分析师预测与政策法规。

## 三步调用流程（必须按顺序）

本连接器不是「一个问题一个工具」，而是把上百个数据接口收在统一入口下，需三步取数：

1. **选域检索**：根据问题所属业务域，调用对应的 `{domain}_search_api`，传入中文业务关键词，
   拿到 Top 5 候选接口（含 `name` / `summary` / `required_parameters`）。
2. **查参数**：对选定的接口调用 `get_api_info`，拿到完整参数定义。
3. **取数**：调用 `api_call`，按参数定义传参。

**不要跳过第 2 步凭空猜测参数名**，接口参数名多为通联特有命名（如 `secID`、`ticker`、
`beginDate`、`endDate`、`indicID`），猜错会直接报参数错误。

## 可用工具

### 业务域检索工具

| 工具 | 覆盖范围 |
|------|----------|
| `astock_search_api` | A股基本资料、财务、盘后行情、股本股东与公司重大事项 |
| `hkstock_search_api` | 港股基本面与盘后行情，以及沪深港通（陆股通/北向资金、港股通/南向资金） |
| `fund_search_api` | 基金基本资料、净值业绩、持仓配置与风险绩效归因 |
| `bond_search_api` | 债券档案、估值行情、信用资质、可转债条款与债券事件 |
| `index_search_api` | 指数基本要素、成分构成、盘后行情估值与收益率 |
| `futopt_search_api` | 国内期货与期权合约规则、盘后行情、持仓与波动率 |
| `factor_search_api` | 股票量化因子（技术、价值、质量、动量、成长、情绪等） |
| `quotes_search_api` | 沪深京证券日内实时快照与分钟级行情序列 |
| `macro_search_api` | 宏观行业指标、时序数据与经济日历（GDP、CPI、PMI、社融、M2、进出口等） |
| `announcement_search_api` | A股、基金与债券公告原文及公告列表 |
| `analystfcst_search_api` | 分析师一致预期、盈利预测与评级（研报衍生结构化指标） |
| `policy_search_api` | 政策法规结构化信息与原文 |

**参数说明**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| query | string | 是 | 中文业务关键词，如「净利润」「十大重仓股」「陆股通持股」 |
| limit | number | - | 返回候选数，默认 5，最多可放宽到 10 |

**选域要点**：
- 陆股通 / 北向资金 / 港股通 / 南向资金的接口挂在 `hkstock_search_api`，不在 `astock_search_api`。
- `query` 里不要重复域名本身（如在 `astock_search_api` 里搜「股票 净利润」），
  域已由所选工具确定，泛化词只会稀释排序，直接搜「净利润」即可。
- 首轮没有合适候选时，换更具体的业务词重搜，或把 `limit` 放宽，不要直接猜接口名。

### get_api_info - 获取接口参数定义

**参数说明**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| api_name | string | 是 | 域检索结果中的 `results[].name` |

返回该接口的全部参数（名称、类型、是否必填、中文含义、可选枚举值）。

### api_call - 调用接口取数

**参数说明**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| api_name | string | 是 | 接口名，须与 `get_api_info` 查询的一致 |
| api_parameters | object | 是 | 按参数定义构造的参数对象 |
| user_question | string | - | 用户的原始提问，用于服务侧问题归因，建议原样填写 |

**分页**：单次最多返回 50 行，更多数据用 `pagenum` 翻页（从 1 开始）。
大文本类接口（研报原文、政策法规）单页 20 条。

## 使用示例

- **查财务数据**：用户问「贵州茅台去年的净利润」
  → `astock_search_api(query="净利润 利润表")`
  → 选定接口后 `get_api_info`
  → `api_call`，传 `ticker="600519"` 与报告期区间。

- **查基金持仓**：用户问「易方达蓝筹二季度前十大重仓股」
  → `fund_search_api(query="重仓股 持仓明细")` → `get_api_info` → `api_call`。

- **查宏观指标**：用户问「最近的 CPI 同比」
  → `macro_search_api(query="CPI 居民消费价格指数")`，先用检索类接口确认 `indicID`，
  再用取数接口拿时序数据。

- **查北向资金**：用户问「陆股通持股比例」
  → `hkstock_search_api(query="陆股通 持股")`（不要用 `astock_search_api`）。

## 证券代码解析

多数接口需要证券代码（`secID` / `ticker`），而不是中文简称。
当用户只给了中文名称时，**先用 `astock_search_api(query="证券编码 secID")` 找到代码查询接口
（如 `getSecIDEqu`），用中文简称换取代码，再去调目标接口**；仅在确实无法解析时才向用户追问代码。
基金与指数同理。

## 错误处理

服务返回体中的 `retCode` 表示上游数据接口的状态，失败时同时带 `error_type` 与 `suggestion`：

| retCode | 含义 | 处理建议 |
|---------|------|----------|
| 1 | 成功 | 正常解析 `data` |
| -1 | 无数据返回 | 查询条件范围内确实没有数据。放宽时间范围或核对代码后重试；**不要反复重试相同参数**，也不要编造数据 |
| -2 / -9 | 参数无效 / 缺少必填参数 | 回到 `get_api_info` 核对参数名与格式（日期为 `YYYYMMDD`） |
| -5 | 系统繁忙 | 稍后重试一次即可 |
| -7 | 查询超时 | 结果集过大，缩小时间范围或增加过滤条件（如指定证券代码） |
| 402 | 积分不足 | 本次未返回数据且未计费，请提示用户到通联数据控制台充值 |

其他情况：
- 返回业务错误 `INSUFFICIENT_CREDITS`：积分不足，提示用户充值后再重试，不要重复提交相同请求。
- 返回 `code: "CONCURRENCY_LIMITED"` 或 HTTP 429：并发请求数达上限，稍后串行重试，不要并发重发。
- 提示「未开通该服务权限」：该 Token 未订阅对应数据服务，请提示用户联系通联数据开通，不要换接口硬试。

## 认证说明

- 本连接器使用长期有效的访问令牌（Token），在连接时由 WorkBuddy 注入请求头
  `Authorization: Bearer <token>`，Token 仅保存在用户本机。
- Token 同时决定数据权限范围与积分账户，取数会按接口单价 × 返回行数扣减积分。
- **Token 失效或需要更换时**：到 https://mcp.datayes.com/#/personal-center
  （个人中心 → 个人信息 → Token）点「重新生成」，然后在 WorkBuddy 的连接器设置中更新即可，
  无需重启 WorkBuddy。注意重新生成会使旧 Token 立即失效。
- 若出现「权限验证失败」类提示，通常是 Token 未填写、填错或已被撤销，请引导用户重新配置。