hithink-tech/financial-apiVor der Ausführung prüfen
SKILL DETAIL
hithink-finance
hithink-tech/financial-api/hithink-finance
当用户或 Agent 需要通过同花顺金融数据服务获取、查询、同步、分析或导出 A 股行情、财报、估值、指数、板块、公募基金、特色数据或本地 DuckDB 数据，或需要选择、安装、配置、诊断 REST API、MCP、hithink-finance CLI、Python SDK/marketdb 时使用。
Installationen · 135Quelle ansehen
Installation
npx skills add https://github.com/hithink-tech/financial-api --skill hithink-finance
Skill-Dateien
SKILL.md
Zuletzt synchronisiert · 07.09.2026
agents/openai.yaml›
interface:
display_name: "同花顺金融数据服务"
short_description: "查询、分析与导出 A 股、指数、板块及本地市场数据"
default_prompt: "使用 $hithink-finance 查询贵州茅台的最新行情，并说明数据时间和来源。"
references/api.md›
# REST API 契约
本 Skill 内置契约是“同花顺金融数据服务”上游 REST API 在本仓库中的唯一契约源。它面向直接 HTTP 调用者、SDK/CLI 维护者和 AI Agent，统一维护端点、参数、响应字段、错误码与能力边界。
## 通用协议
| 项目 | 契约 |
| --- | --- |
| Base URL | `https://fuyao.aicubes.cn` |
| 方法 | 当前公开数据端点均为 `GET` |
| 认证 | HTTP Header `X-api-key: <API_KEY>` |
| 成功判断 | HTTP 200 且响应 `code == 0` |
| 响应信封 | `{code, message, request_id, data}` |
| 标的代码 | 完整 `thscode`，例如 `600519.SH`；不要猜交易所后缀 |
| 时间戳 | 毫秒 Unix 时间戳；具体日期字符串格式以端点页为准 |
| 空值 | `null` 表示未披露或上游无值，不得自动补零 |
`data` 字段始终存在：成功时承载端点数据，业务错误时为 `null`。调用方不得以“字段缺失”判断旧版错误信封，也不得在错误时把 `null` 当作成功空结果。
获取统一 API Key：<https://fuyao.aicubes.cn/admin>。API Key 不得写入代码、Prompt、日志、公开配置或 Git 提交。
最小请求：
```bash
curl 'https://fuyao.aicubes.cn/api/meta/tickers/search?q=600519&limit=1' \
-H 'X-api-key: <API_KEY>'
```
## 契约导航
先读 [能力与意图路由](api/capability-map.md)，再按需要打开一个端点组：
| 领域 | 契约 |
| --- | --- |
| 标的检索、代码消歧、代码表 | [元信息端点](api/endpoints-meta.md) |
| 个股行情、历史 K 线、公司行动 | [行情与公司行为端点](api/endpoints-prices.md) |
| 利润表、资产负债表、现金流量表、财务指标 | [财务数据端点](api/endpoints-financials.md) |
| A 股市盈率、市净率、市销率和市现率快照 | [估值数据端点](api/endpoints-valuations.md) |
| 交易日历 | [交易日历端点](api/endpoints-calendar.md) |
| A 股集合竞价快照与短期基准 | [集合竞价端点](api/endpoints-auction.md) |
| 指数/板块目录、成分股、指数行情 | [指数与板块端点](api/endpoints-index.md) |
| 基金资料、经理、净值、收益、持仓、财务、资讯和场内行情 | [公募基金端点](api/endpoints-fund.md) |
| 涨停、跌停、炸板、连板、异动、热榜、龙虎榜 | [特色数据端点](api/endpoints-special-data.md) |
| 全市场 Parquet 与本地建库数据源 | [全市场数据导出](api/endpoints-market-dumps.md) |
## 错误处理
所有响应先检查 `code`。HTTP 200 不代表业务成功。
| `code` | 含义 | 调用方处理 |
| --- | --- | --- |
| `0` | 成功 | 使用 `data` |
| `1001` | 缺少必填参数 | 补齐参数，不重试原请求 |
| `1002` | 参数格式无效 | 规范化代码、枚举、日期或时间戳 |
| `1003` | 参数超出范围 | 缩小分页或拆分允许拆分的时间窗口 |
| `1004` | 参数冲突 | 按端点互斥规则重组参数 |
| `2001` | 未认证 | 检查 `X-api-key` 是否存在且格式正确 |
| `2003` | 无权限或 Key 无效 | 前往 API Key 管理页检查授权或重新签发 |
| `3001` | 标的不存在 | 先通过元信息端点消歧并核对资产类别与 `thscode` |
| `3002` | 数据尚未准备 | 保留 `request_id` 与口径，稍后再查，不得补零或使用模拟数据 |
| `3004` | 目标类型不支持该能力 | 选择适用于该资产类型的端点，不重试原请求 |
| `4001` | 限流 | 指数退避，最多重试 3 次 |
| `5001`/`5002`/`5003` | 服务端或上游异常 | 退避重试；持续失败时保留 `request_id` |
`1xxx` 和 `2xxx` 属于调用方可修复错误，不应无条件重试。网络错误、`4001` 和 `5xxx` 可在有界次数内退避重试。
## 大结果规则
全市场、分页全集、多标的或多年数据必须落盘。调用者只在终端或对话中报告文件路径、行数、时间窗口和摘要，不展开原始结果。全市场历史建库优先使用 [Market Dumps](api/endpoints-market-dumps.md)，不要逐标的请求多年 REST 数据。
## 维护规则
1. 先根据上游变更更新本目录。
2. 运行 `python scripts/sync_skill_contracts.py` 镜像到独立 Skill。
3. 运行 `python scripts/sync_skill_contracts.py --check` 和相关契约测试。
4. CLI/Python 文档只同步命令或运行方式，不复制本目录的字段契约。
references/api/capability-map.md›
# 能力与意图路由
> 根据用户意图快速定位到具体 REST 端点。本页只做路由，参数与字段细节在各端点详情页。
## 全部端点一览（59 个）
### 元信息（2 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/meta/tickers/search` | 按 thscode / ticker / 中英文名做跨市场检索与消歧 | 「同花顺这只股票的 thscode 是什么」「帮我确认这个代码属于股票还是指数」 |
| `GET /api/meta/tickers/list` | 按交易所 / 资产类别批量获取代码表 | 「A 股全部代码列表」「沪深两市的股票有哪些」 |
详情：[endpoints-meta.md](endpoints-meta.md)
### 行情与公司行为（3 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/a-share/prices/snapshot` | 单只 / 多只 / 全市场 A 股最新行情快照 | 「贵州茅台最新价多少」「今天涨停的股票行情」 |
| `GET /api/a-share/prices/historical` | 单只 A 股历史日 K 线（支持前复权 / 后复权） | 「茅台最近一个月日 K」「三年前到现在的周线」 |
| `GET /api/a-share/corporate-actions/adjustment-factors` | 分红、送股、配股等复权事件流 | 「茅台历年分红记录」「某股票的除权除息事件」 |
详情：[endpoints-prices.md](endpoints-prices.md)
### 财务数据（4 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/a-share/financials/income-statements` | 整体合并利润表多期序列 | 「茅台最近 4 期年报利润表」 |
| `GET /api/a-share/financials/balance-sheets` | 整体合并资产负债表多期序列 | 「平安银行近 5 年资产负债表」 |
| `GET /api/a-share/financials/cash-flow-statements` | 整体合并现金流量表多期序列 | 「某股票近 3 年现金流」 |
| `GET /api/a-share/financials/indicators` | 指定报告期的五类财务指标 | 「茅台 2024 年报的财务指标」 |
详情：[endpoints-financials.md](endpoints-financials.md)
### 估值数据（1 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/a-share/valuations/snapshot` | 批量查询 A 股最新市盈率、市净率、市销率和市现率快照 | 「茅台和平安银行当前估值是多少」「批量获取这些股票的五项估值指标」 |
详情：[endpoints-valuations.md](endpoints-valuations.md)
### 交易日历（1 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/a-share/calendar/trading-days` | A 股近一年交易日序列 | 「最近有哪些交易日」「今天是否开盘」 |
详情：[endpoints-calendar.md](endpoints-calendar.md)
### 集合竞价（2 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/a-share/auction/snapshot` | 批量查询 A 股集合竞价实时或终态快照 | 「这几只股票今天竞价表现如何」 |
| `GET /api/a-share/auction/short-term-benchmark` | 查询指定日期的集合竞价短期强弱基准 | 「今天竞价涨幅靠前的股票有哪些」 |
详情：[endpoints-auction.md](endpoints-auction.md)
### 指数与板块（4 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/a-share-index/catalog/ths-index-list` | 按类别列出同花顺概念 / 区域 / 特色 / 行业指数 | 「有哪些概念板块」「同花顺行业指数列表」 |
| `GET /api/a-share-index/constituents/ths-stock-list` | 查询单个板块或标准指数的当前成分股 | 「沪深 300 成分股有哪些」「某概念板块包含哪些股票」 |
| `GET /api/a-share-index/prices/snapshot` | 批量查询指数 / 板块最新行情 | 「沪深 300 今天涨多少」「某板块最新行情」 |
| `GET /api/a-share-index/prices/historical` | 单只指数 / 板块历史日 / 周 / 月 K 线 | 「沪深 300 最近一年走势」「某概念板块历史 K 线」 |
详情：[endpoints-index.md](endpoints-index.md)
### 公募基金（28 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/fund/profile/detail` | 基金基本资料 | 「这只基金的管理人和基金经理是谁」 |
| `GET /api/fund/portfolio/holdings` | 定期披露重仓股 | 「这只基金披露了哪些重仓股」 |
| `GET /api/fund/performance/nav` | 最新或固定区间净值 | 「这只基金近一年单位净值走势」 |
| `GET /api/fund/performance/returns` | 固定区间收益 | 「这只基金近一月、近一年和成立以来收益」 |
| `GET /api/fund/holders/detail` | 持有人结构 | 「机构和个人持有比例是多少」 |
| `GET /api/fund/market/snapshot` | ETF/LOF 场内快照 | 「510300.SH 当前价格多少」 |
| `GET /api/fund/market/historical` | ETF 历史日线 | 「510300.SH 最近一年的日线行情」 |
| `GET /api/fund/companies/detail` | 基金公司详情 | 「这家基金公司的管理规模和负责人是谁」 |
| `GET /api/fund/portfolio/industry-allocation` | 行业配置 | 「这只基金主要配置哪些行业」 |
| `GET /api/fund/performance/indicators-historical` | 指定日期区间的历史业绩指标 | 「近三年风险收益指标如何变化」 |
| `GET /api/fund/performance/drawdowns` | 回撤区间 | 「这只基金历史主要回撤有哪些」 |
| `GET /api/fund/holders/top` | 前十大持有人 | 「这只基金前十大持有人是谁」 |
| `GET /api/fund/corporate-actions/dividends` | 分红记录 | 「这只基金历次分红情况」 |
| `GET /api/fund/diagnostics/detail` | 基金诊断详情 | 「这只基金的诊断雷达如何」 |
| `GET /api/fund/financials/indicators` | 基金财务指标 | 「这只基金最新财务指标」 |
| `GET /api/fund/financials/income-statements` | 基金利润表 | 「这只基金的利润表」 |
| `GET /api/fund/financials/balance-sheets` | 基金资产负债表 | 「这只基金的资产负债表」 |
| `GET /api/fund/managers/investment-style` | 基金经理投资风格 | 「这位基金经理偏好什么风格」 |
| `GET /api/fund/managers/performance` | 基金经理业绩 | 「这位基金经理的任职业绩」 |
| `GET /api/fund/managers/experience` | 基金经理任职经历 | 「这位基金经理管理过哪些产品」 |
| `GET /api/fund/managers/detail` | 基金经理详情 | 「这位基金经理的履历」 |
| `GET /api/fund/news/article-list` | 基金资讯列表 | 「这只基金最近有哪些公开资讯」 |
| `GET /api/fund/offerings/list` | 在售或待售基金列表 | 「当前有哪些在售基金」 |
| `GET /api/fund/portfolio/stock-history` | 股票持仓历史 | 「这只基金某报告期持有哪些股票」 |
| `GET /api/fund/portfolio/stock-report-dates` | 股票持仓报告期 | 「有哪些可用的股票持仓报告期」 |
| `GET /api/fund/portfolio/bond-history` | 债券持仓历史 | 「这只基金某报告期持有哪些债券」 |
| `GET /api/fund/portfolio/bond-report-dates` | 债券持仓报告期 | 「有哪些可用的债券持仓报告期」 |
| `GET /api/fund/portfolio/asset-allocation` | 大类资产配置 | 「股票、债券和现金各占多少」 |
详情：[endpoints-fund.md](endpoints-fund.md)
### 特色数据（11 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/a-share/special-data/limit-up-pool` | 指定交易日的涨停 / 连板股票池 | 「今天有哪些涨停股」「某天的涨停股清单」 |
| `GET /api/a-share/special-data/limit-down-pool` | 指定交易日的跌停股票池 | 「今天有哪些跌停股」 |
| `GET /api/a-share/special-data/limit-break-pool` | 指定交易日的炸板股票池 | 「今天有哪些股票炸板」 |
| `GET /api/a-share/special-data/limit-up-ladder` | 近 30 个交易日的连板梯队矩阵 | 「最近连板情况如何」「连板天梯」 |
| `GET /api/a-share/special-data/anomaly-analysis-list` | 当日全市场个股异动原因（REST only） | 「今天哪些股票异动了」 |
| `GET /api/a-share/special-data/anomaly-analysis-stock` | 按 thscode 批量查询当日个股异动原因 | 「茅台今天为什么异动」「这几只股票的异动原因」 |
| `GET /api/a-share/special-data/skyrocket-list` | A 股飙升榜 | 「今天哪些股票飙升」 |
| `GET /api/a-share/special-data/hot-stock-list` | 当前热股榜 | 「今天的热门股票有哪些」 |
| `GET /api/a-share/special-data/hot-stock-list-history` | 指定日期的历史热股排名 | 「上周某天的热股榜」 |
| `GET /api/a-share/special-data/hot-stock-rank-trend` | 单只股票在日期区间的热榜排名走势 | 「茅台最近热度排名变化」 |
| `GET /api/a-share/special-data/dragon-tiger-list` | 龙虎榜（全部 / 机构 / 游资） | 「今天的龙虎榜」「某天的游资榜」 |
详情：[endpoints-special-data.md](endpoints-special-data.md)
### 全市场数据导出（3 个）
| 端点 | 用途 | 典型问题 |
| --- | --- | --- |
| `GET /api/dump/market-dumps/daily-k/download-url` | 全市场 10 年日K Parquet 下载链接 | 「下载全市场历史日K」「批量导出 A 股数据」「自建数据库」 |
| `GET /api/dump/market-dumps/daily-k-10d/download-url` | 全市场近 10 交易日 Parquet 下载链接 | 「增量同步最新行情」「每天更新全市场数据」 |
| `GET /api/dump/market-dumps/adjustment-factors/download-url` | 全市场复权事件 Parquet 下载链接 | 「下载所有股票分红送股记录」「批量获取复权因子」 |
> ⚠️ 这些端点返回 S3 预签名下载 URL（有效期约 5 分钟），不直接返回数据。拿到 URL 后需再次 HTTP GET 下载 Parquet 文件。**不要用逐只 `prices-historical` 拉全市场**——全市场约 5000+ 只票，逐只调需数千次 HTTP 请求，用本端点 3 次请求即可。
详情：[endpoints-market-dumps.md](endpoints-market-dumps.md)
## 常见组合流程
### 名称到数据
1. 用 `/api/meta/tickers/search?q=<名称>` 消歧为唯一 `thscode`。
2. 判断 `asset_type`：`a-share` 走个股端点，`a-share-index` 走指数端点，`fund-*` 走基金端点。
3. 调用对应行情、财务、估值或特色数据端点。
### 概念板块到成分股行情
1. 用 `/api/a-share-index/catalog/ths-index-list?tag=cn_concept` 找到板块 `thscode`。
2. 用 `/api/a-share-index/constituents/ths-stock-list?thscode=<板块代码>` 取当前成分股。
3. 仅对用户需要的有限成分调用 `/api/a-share/prices/snapshot?thscodes=<逗号列表>` 获取行情；全量结果落盘，不写入对话。
### 财务与行情联合分析
1. 用财报端点获取指定报告期数据。
2. 用行情端点获取明确时间窗口的数据。
3. 明确报告期、行情日期、复权口径和数据时间，避免把不同口径直接比较。
### 多股票估值快照
1. 用元信息端点把名称或纯 ticker 消歧为唯一 A 股 `thscode`。
2. 把有限标的合并为逗号分隔列表调用 `/api/a-share/valuations/snapshot`；原始 token 最多 100 个。
3. 保留 `null` 和负数，按 `timestamp` 标记数据时间，不把估值指标直接解释为投资建议。
## 能力边界
- 覆盖 **A 股**（沪深京）、**A 股指数 / 板块**和公募基金资料、经理、披露、财务、净值、收益与公开资讯；场内行情覆盖 ETF/LOF 快照与 ETF 日线。
- **不覆盖**：分钟 K、tick、Level-2、港股、美股、基金申赎交易、期货、期权。
- 财务指标端点不返回行业均值、评分、排名或点评。
- 端点提供数据，不提供回测引擎、alpha 模型或确定性投资建议。
- 异动分析（`anomaly-analysis-list` / `anomaly-analysis-stock`）仅支持当日快照，不支持历史查询。
## 参数语义提醒
- `thscode` 必须带交易所后缀（`.SH` / `.SZ` / `.BJ` / `.TI`），纯 6 位代码不被接受。
- 毫秒时间戳（`start` / `end` / `date_ms`）与 `YYYY-MM-DD` 字符串（`from` / `to` / `date`）不可互换，按端点详情页要求传参。
- `limit/offset` 与 `page/size` 是两种不同分页模型，不要混用。
- 端点名相似时先确认资产类别、是否支持批量、是否允许省略代码，以及时间窗口上限。
references/api/endpoints-auction.md›
# A 股集合竞价端点
> 查询一个或多个 A 股标的的集合竞价快照，或查询指定日期的短线风向标竞价基准。标的代码必须是带交易所后缀的 A 股 `thscode`。
## 1. 个股/多股集合竞价快照
```text
GET /api/a-share/auction/snapshot
```
operationId：`get_a_share_auction_snapshot`。
| 参数 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- |
| `thscodes` | string | 是 | 1–100 个 A 股 `thscode`，英文逗号分隔；去重后按首次出现顺序查询。 | — |
| `stage` | string | 否 | `live` 表示竞价实时阶段，`final` 表示竞价终态。 | `final` |
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/auction/snapshot?thscodes=600519.SH,000001.SZ&stage=final' \
-H 'X-api-key: <your-api-key>'
```
`data` 为 `{timestamp, auction_phase, data_status, total, item[]}`。`timestamp` 始终是接口响应组装时间，在 `live`、`final`、`suspended` 和 `not_ready` 场景都会返回；上游行情时间仅用于判断数据新鲜度，不表示响应时间。`data_status` 用于区分数据尚未就绪、竞价完成或停牌等状态。`item[]` 字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` / `ticker` / `name` | string | 标的唯一代码、纯代码和名称。 |
| `auction_price` | number/null | 竞价价格。 |
| `auction_pct` | number/null | 竞价涨跌幅，百分数原值。 |
| `auction_volume` | number/null | 竞价成交量，单位为手。 |
| `auction_amount` | number/null | 竞价成交额。 |
| `auction_unmatched` | number/null | 未匹配量。 |
| `auction_turnover_pct` | number/null | 竞价换手率，百分数原值。 |
| `auction_yesterday_ratio_pct` | number/null | 相对昨日成交量比例，百分数原值。 |
| `auction_volume_ratio` | number/null | 竞价量比。 |
| `pre_close_price` / `open_price` / `last_price` | number/null | 昨收、开盘和最新价。 |
| `float_market_cap` | number/null | 流通市值。 |
### 避错要点
- 只支持 `.SH`、`.SZ`、`.BJ` A 股代码；指数、板块和基金代码返回参数错误。
- 原始 token 超过 100、空 token 或格式错误会在请求层失败；不要先去重再规避数量上限。
- 非竞价时段可能返回未就绪或停牌状态；不得用零值或模拟行情补齐空字段。
## 2. 短线风向标竞价基准
```text
GET /api/a-share/auction/short-term-benchmark
```
operationId：`get_a_share_auction_short_term_benchmark`。
| 参数 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- |
| `date` | string | 否 | 查询日期，格式 `YYYY-MM-DD`；缺失或空字符串时使用 `Asia/Shanghai` 当日。 | 上海时区当日 |
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/auction/short-term-benchmark?date=2026-08-14' \
-H 'X-api-key: <your-api-key>'
```
`data` 为 `{timestamp, date, date_ms, item[]}`。`timestamp` 是接口响应组装时间；`date` 是最终查询日期，格式 `YYYY-MM-DD`；`date_ms` 是该日期在 `Asia/Shanghai` 当日零点的毫秒 Unix 时间戳。`item[]` 字段为 `thscode`、`ticker`、`name`、`auction_pct`、`tags`。
### 避错要点
- `date` 是 `YYYY-MM-DD` 字符串，不是毫秒时间戳。
- 显式日期按原值查询，非交易日不自动回退；业务为空时不得擅自改查前一交易日。
- `tags` 保留服务端返回的标签集合；不要根据涨跌幅自行推导或替换标签。
references/api/endpoints-calendar.md›
# 交易日历端点
> A 股近一年交易日序列。参数定义、响应字段以本文档为准。
## 交易日历
```text
GET /api/a-share/calendar/trading-days
```
返回 A 股近一年的交易日序列，同时返回毫秒戳与可读日期，方便展示与对账。
### 请求参数
无入参。窗口固定为 `[今日 - 1 年, 今日]`（Asia/Shanghai 时区）。
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/calendar/trading-days' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`，`item` 按日期升序（ASC）排列：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 数据就绪时间（毫秒）。 |
| `item` | array | 交易日列表。 |
`item[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `date_ms` | long | 交易日，Asia/Shanghai 00:00:00 毫秒 Unix 时间戳。 |
| `date` | string | 可读日期，格式 `yyyyMMdd`（如 `20250701`）。 |
### 避错要点
- 查询任意十年日历：窗口固定为近一年，不支持自定义时间范围。
- 把非交易日空数据当服务故障：非交易日不在列表中是正常行为，不代表接口异常。
- 用它判断「今天是否开盘」：先确认今天是否在返回的 `item` 列表中。
references/api/endpoints-financials.md›
# 财务数据端点
> A 股财务报表（利润表 / 资产负债表 / 现金流量表）多期序列与财务指标。参数定义、响应字段以本文档为准。
## 通用说明
三张报表端点共享相同的参数模型和互斥规则：
- **必填**：`thscode`（单个，不接受逗号）、`period`（报告周期）。
- **互斥模式**：
- 最近 N 期：省略 `start`/`end`，传 `limit`（1–20，默认 4）。
- 时间区间：同时传 `start` AND `end`（毫秒时间戳），窗口 ≤ 10 年。
- 同时传 `(start|end)` 和 `limit` → `code=1004`。
- 只传 `start` 或 `end` 之一 → `code=1004`。
- `null` 字段表示「该报告期未披露」，**不要**补零。
- 三张报表的时间区间参数使用毫秒时间戳。
---
## 1. 利润表
```text
GET /api/a-share/financials/income-statements
```
获取单只 A 股的整体合并利润表多期序列。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscode` | query | string | 是 | 单只标的 thscode。 | — |
| `period` | query | string | 否 | 报告周期，枚举 `annual` / `quarterly`。 | `annual` |
| `limit` | query | integer | 否 | 最近 N 期，1–20。仅最近期模式可用。 | `4` |
| `start` | query | long | 否 | 区间起始时间（毫秒）。仅区间模式可用。 | — |
| `end` | query | long | 否 | 区间结束时间（毫秒）。仅区间模式可用，`end - start` ≤ 10 年。 | — |
### 请求示例
```bash
# 茅台最近 4 期年报利润表
curl 'https://fuyao.aicubes.cn/api/a-share/financials/income-statements?thscode=600519.SH&period=annual&limit=4' \
-H 'X-api-key: <your-api-key>'
# 区间模式
curl 'https://fuyao.aicubes.cn/api/a-share/financials/income-statements?thscode=600519.SH&period=annual&start=1577836800000&end=1893456000000' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`，`item` 按 `period_end_ms` 降序排列（最新在前）。`null` 表示该报告期未披露。
`item[]` 元素字段（共 21 个）：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `period` | string | 报告周期（`annual` / `quarterly`）。 |
| `period_end_ms` | long | 报告期末毫秒时间戳。 |
| `report_date_ms` | long | 报告日期毫秒时间戳。 |
| `fiscal_year` | integer | 会计年度。 |
| `fiscal_period` | string | 会计期间（如 `FY` 表示年报）。 |
| `currency` | string | 币种（A 股恒为 `CNY`）。 |
| `basic_eps` | number | 基本每股收益。 |
| `operating_income` | number | 营业收入。 |
| `operating_costs` | number | 营业成本。 |
| `operating_expenses` | number | 营业支出。 |
| `operating_profit` | number | 营业利润。 |
| `profit_total` | number | 利润总额。 |
| `net_profit` | number | 净利润。 |
| `parent_holder_net_profit` | number | 归属于母公司所有者的净利润。 |
| `income_tax_expense` | number | 所得税费用。 |
| `interest_expenses` | number | 利息支出。 |
| `manage_fee` | number | 管理费用。 |
| `sales_fee` | number | 销售费用。 |
| `research_and_development_expenses` | number | 研发费用。 |
---
## 2. 资产负债表
```text
GET /api/a-share/financials/balance-sheets
```
获取单只 A 股的整体合并资产负债表多期序列。
### 请求参数
参数结构与利润表完全一致：`thscode`、`period`、`limit` / `start`+`end`（互斥）。
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/financials/balance-sheets?thscode=600519.SH&period=annual&limit=5' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`，`item` 按 `period_end_ms` 降序排列。`null` 表示该报告期未披露。
`item[]` 元素字段（共 15 个）：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `period` | string | 报告周期。 |
| `period_end_ms` | long | 报告期末毫秒时间戳。 |
| `report_date_ms` | long | 报告日期毫秒时间戳。 |
| `fiscal_year` | integer | 会计年度。 |
| `fiscal_period` | string | 会计期间。 |
| `currency` | string | 币种。 |
| `total_current_assets` | number | 流动资产合计。 |
| `non_current_nets_total` | number | 非流动资产净值合计。 |
| `assets_total` | number | 资产总计。 |
| `total_debt` | number | 负债合计。 |
| `holder_equity_total` | number | 所有者权益合计。 |
| `cash` | number | 货币资金。 |
| `accounts_receivable` | number | 应收账款。 |
### 避错要点
- 把报告期模式理解为自然月数据：报表按报告期返回，不是按日历月。
- `limit` 最近期数通常 1–20，区间最长 10 年。
---
## 3. 现金流量表
```text
GET /api/a-share/financials/cash-flow-statements
```
获取单只 A 股的整体合并现金流量表多期序列。
### 请求参数
参数结构与利润表完全一致：`thscode`、`period`、`limit` / `start`+`end`（互斥）。
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/financials/cash-flow-statements?thscode=600519.SH&period=quarterly&limit=8' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`，`item` 按 `period_end_ms` 降序排列。`null` 表示该报告期未披露。
`item[]` 元素字段（共 14 个）：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `period` | string | 报告周期。 |
| `period_end_ms` | long | 报告期末毫秒时间戳。 |
| `report_date_ms` | long | 报告日期毫秒时间戳。 |
| `fiscal_year` | integer | 会计年度。 |
| `fiscal_period` | string | 会计期间。 |
| `currency` | string | 币种。 |
| `act_cash_flow_net` | number | 经营活动产生的现金流量净额。 |
| `invest_cash_flow_net` | number | 投资活动产生的现金流量净额。 |
| `financing_cash_flow_net` | number | 筹资活动产生的现金流量净额。 |
| `cash_equivalents_net_addition` | number | 现金及现金等价物净增加额。 |
| `pay_dividends_profits_interest_cash` | number | 分配股利、利润或偿付利息支付的现金。 |
| `pay_fixed_assets_etc_cash` | number | 购建固定资产等支付的现金。 |
### 避错要点
- 未对齐不同报表的报告期就直接拼接：三张报表的报告期可能不完全一致，拼接前确认 `period_end_ms`。
---
## 4. 财务指标
```text
GET /api/a-share/financials/indicators
```
按单只 A 股与报告期返回成长、盈利、偿债、运营和现金流五类指标。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscode` | query | string | 是 | 单只标的 thscode。 | — |
| `report` | query | string | 是 | 报告期，格式 `YYYY-[1-4]`。`1`=一季报、`2`=中报、`3`=三季报、`4`=年报。例如 `2025-1`。 | — |
### 请求示例
```bash
# 茅台 2024 年报财务指标
curl 'https://fuyao.aicubes.cn/api/a-share/financials/indicators?thscode=600519.SH&report=2024-4' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{thscode, report, abilities}`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `report` | string | 报告期标识。 |
| `abilities` | **array** | 指标块列表，固定顺序返回 5 个元素。 |
> **重要**：`abilities` 是**数组**（list），不是对象（object）。每个元素结构为 `{ability: string, indicators: [{index_id, value}...]}`。遍历方式为 `for ab in abilities: ab["ability"]` / `ab["indicators"]`，**不能**用 `abilities["growth"]` 访问。
`abilities[]` 元素结构：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `ability` | string | 指标类别，枚举值见下表。 |
| `indicators` | array | 指标列表，每项为 `{index_id, value}`。 |
`abilities[]` 固定按以下顺序返回 5 个元素：
| 顺序 | `ability` 值 | 说明 |
| --- | --- | --- |
| 1 | `growth` | 成长能力指标 |
| 2 | `profitability` | 盈利能力指标 |
| 3 | `solvency` | 偿债能力指标 |
| 4 | `operation` | 运营能力指标 |
| 5 | `cash-flow` | 现金流指标 |
`indicators[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `index_id` | string | 指标 ID（如 `calculate_operating_income_yoy_growth_ratio`）。 |
| `value` | string \| null | 指标值（字符串类型）；上游缺失值返回 `null`，不是 `""` 或 `0`。 |
### 避错要点
- 用 `abilities["growth"]` 访问：`abilities` 是数组不是对象，必须用 `for ab in abilities: if ab["ability"] == "growth"` 遍历。
- 期待行业均值、评分、排名或点评：财务指标端点只返回标的自身指标，不返回行业数据。
- 把 `2025-12-31` 当 report：`report` 是专用字符串格式 `YYYY-[1-4]`，不是日期。
- 传毫秒时间戳：`report` 不是时间戳，是报告期枚举。
references/api/endpoints-fund.md›
# 公募基金端点
> 基金基本资料、披露数据、净值、收益、持有人结构以及场内基金行情。先通过元信息端点把名称或代码消歧为带后缀的唯一 `thscode`。
## 公共参数与类型
需要 `fund_type` 的端点使用以下枚举：
| 值 | 含义 |
| --- | --- |
| `otc` | 场外公募基金，对应 `asset_type=fund-otc` |
| `exchange` | 场内 ETF/LOF，对应 `fund-etf` 或 `fund-lof` |
| `reits` | 公募 REITs，对应 `fund-reits` |
`fund_type` 与 `thscode` 共同定位基金，不能传逗号分隔的多个 `fund_type`。场内行情端点不接收 `fund_type`，由服务端按 `thscode` 识别 ETF/LOF。
## 1. 基金基本资料
```text
GET /api/fund/profile/detail
```
参数：`fund_type`（必填）和单个 `thscode`（必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/profile/detail?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data` 为 `{timestamp, item[]}`，`item[]` 字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 基金唯一代码。 |
| `ticker` | string | 不带市场后缀的基金代码。 |
| `fund_name` | string/null | 基金名称。 |
| `estab_date` | integer/null | 成立日期，毫秒 Unix 时间戳。 |
| `company_id` | string/null | 基金公司 ID；用于基金公司详情能力。 |
| `mgmt_name` | string/null | 基金管理人名称。 |
| `manager_name` | string/null | 兼容字段；首位基金经理名称。 |
| `fund_scale` | number/null | 基金规模。 |
| `unit_nav` | number/null | 最新单位净值。 |
| `manager_info` | array | 全部当前经理引用；含 `manager_id`、`manager_name`、`tenure_return_pct`、`tenure_days`、`start_date_ms`、`end_date_ms`。 |
| `trade_rule` | array | 交易规则；含 `title`、`display_time`、`time_ms`。 |
| `rate_info` | array | 费率；含 `rate_type`、`charge_mode`、`condition`、`standard_rate`、`discounted_rate`。 |
### 避错要点
- 不要仅凭 `.OF`/`.SH` 后缀猜 `fund_type`；先查元信息的 `asset_type`。
- 可选资料字段可能为 `null`，不得补写虚构管理人或成立日。
## 2. 基金定期披露重仓股
```text
GET /api/fund/portfolio/holdings
```
参数：`fund_type`（必填）和单个 `thscode`（必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/portfolio/holdings?fund_type=exchange&thscode=510300.SH' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段：`thscode`、`ticker`、`stock_name`、`hold_ratio`、`asset_type`、`position_capital`、`position_count`、`security_market_value_rate_pct`、`period_increase_rate_pct`、`investment_rank`、`start_date_ms`、`end_date_ms`、`publish_date_ms`、`modify_time_ms`。`hold_ratio=8.88` 表示 8.88%，不是 0.0888。
`data` 还可能包含 `total_stock_ratio_pct`、`total_bond_ratio_pct`、`total_fund_ratio_pct`、`turnover_rate_pct`、`stock_ratio_pct`、`main_industry`、`concentration_ratio` 等披露汇总字段；未披露时保持 `null` 或省略。
### 避错要点
- 该端点是定期披露持仓，不是实时组合；回答中应注明披露口径和返回时间。
- 暂无可用披露时返回 `code=3002`，不要用相近基金或模拟持仓替代。
## 3. 基金净值
```text
GET /api/fund/performance/nav
```
| 参数 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- |
| `fund_type` | string | 是 | `otc` / `exchange` / `reits`。 | — |
| `thscode` | string | 是 | 单个基金代码。 | — |
| `range` | string | 否 | `week` / `month` / `tmonth` / `hyear` / `year` / `twoyear` / `tyear` / `fyear`。省略时只返回最新点。 | — |
| `nav_type` | string | 否 | `unit` / `adj` / `unit,adj`。 | `unit,adj` |
```bash
curl 'https://fuyao.aicubes.cn/api/fund/performance/nav?fund_type=otc&thscode=025480.OF&range=year&nav_type=unit%2Cadj' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `nav_date`、`unit_nav`、`adj_nav`。未选择的净值类型不出现在响应中；字段为空也不自动补零。
### 避错要点
- `range` 不是自然日期区间；不要传 `YYYY-MM-DD`。
- `nav_type=unit,adj` 含逗号，手写 URL 时应正确编码。
## 4. 基金区间收益
```text
GET /api/fund/performance/returns
```
参数：`fund_type`（必填）和单个 `thscode`（必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/performance/returns?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段：
| 字段 | 口径 |
| --- | --- |
| `return_month` | 近一月 |
| `return_tmonth` | 近三月 |
| `return_hyear` | 近半年 |
| `return_year` | 近一年 |
| `return_tyear` | 近三年 |
| `return_fyear` | 近五年 |
| `return_nowyear` | 今年以来 |
| `return_now` | 成立以来 |
兼容扩展还包含 `return_week`、`return_twoyear`，以及近周/月/三月/半年/一年/两年/三年/五年的同类平均 `peer_average_*`、名次 `rank_*` 和同类总数 `rank_total_*`；例如 `peer_average_week`、`rank_total_fyear`。所有收益和同类平均均为百分数原值，排名字段为整数或 `null`。
### 避错要点
- 收益字段来自不同固定区间，不能把它们当成自定义起止日期收益。
- 收益数据未准备好时返回 `3002`；不要据此宣称基金收益为零。
## 5. 基金持有人结构
```text
GET /api/fund/holders/detail
```
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fund_type` | string | 是 | 基金类型：`otc`（场外基金）、`exchange`（ETF/LOF）或 `reits`（公募 REITs）。 |
| `thscode` | string | 是 | 完整基金 `thscode`，必须保留市场后缀；例如 `161725.SZ`。 |
| `merge_scope` | string | 否 | 持有人披露口径：`all`（默认，分别返回合并/独立份额的最新记录）、`merged`（A 类、C 类等份额合并披露）或 `separate`（当前份额独立披露）。 |
```bash
curl 'https://fuyao.aicubes.cn/api/fund/holders/detail?fund_type=otc&thscode=025480.OF&merge_scope=all' \
-H 'X-api-key: <your-api-key>'
```
`data.timestamp` 是返回记录中最新的报告日，使用毫秒 Unix 时间戳。`data.item[]` 是持有人结构记录；当 `merge_scope=all` 时，最多分别返回一条 `merged` 和 `separate` 的最新记录。
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `merge_scope` | string | 实际命中的披露口径：`merged` 或 `separate`。 |
| `report_date_ms` | integer | 当前记录的报告日，毫秒 Unix 时间戳。 |
| `ins_position` | number | 机构投资者占比，百分数原值。 |
| `holder_amount` | integer | 基金份额持有人户数。 |
| `avg_holder_share` | number | 平均每户持有基金份额。 |
| `psnl_rate` | number | 个人投资者占比，百分数原值。 |
| `mgmt_staff_hold_rate` | number | 管理人员工持有比例，百分数原值。 |
### 避错要点
- 持有人数据是披露数据，不是实时账户统计。
- 百分比字段按上游百分数值解释，缺失值保持 `null`。
- `all` 是聚合查询口径，不是第三种披露记录；返回项的实际口径只会是 `merged` 或 `separate`。
## 6. 场内基金行情快照
```text
GET /api/fund/market/snapshot
```
参数：单个 `thscode`（必填）。支持 ETF 和 LOF；场外基金或 REITs 不支持时返回 `3004`。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/market/snapshot?thscode=510300.SH' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段：`thscode`、`ticker`、`last_price`、`open_price`、`high_price`、`low_price`、`prev_price`、`price_change_ratio_pct`、`price_change`、`price_amplitude_ratio_pct`、`volume`、`turnover`、`turnover_ratio_pct`。
### 避错要点
- 单次只接收一个 `thscode`，逗号分隔批量代码返回 `1002`。
- 场外基金没有交易所实时行情；先看 `asset_type`，不要盲目重试 `3004`。
## 7. ETF 历史日线行情
```text
GET /api/fund/market/historical
```
| 参数 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- |
| `thscode` | string | 是 | 单个 ETF `thscode`。 | — |
| `interval` | string | 否 | 当前只支持 `1d`。 | `1d` |
| `start` | integer | 是 | 起始毫秒 Unix 时间戳。 | — |
| `end` | integer | 是 | 结束毫秒 Unix 时间戳；不得早于 `start`。 | — |
单次 `[start,end]` 最多 5 年。LOF、场外基金和 REITs 不支持该历史行情能力时返回 `3004`。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/market/historical?thscode=510300.SH&interval=1d&start=1704038400000&end=1735660799000' \
-H 'X-api-key: <your-api-key>'
```
`data` 为 `{timestamp, thscode, interval, item[]}`；基金历史行情不提供 `adjust`。`item[]` 字段为 `date_ms`、`open_price`、`high_price`、`low_price`、`close_price`、`volume`、`turnover`。
### 避错要点
- 不要传复权参数；ETF 历史端点没有 `adjust`。
- 超过 5 年时拆成不重叠窗口，合并后按 `date_ms` 去重排序。
- 不要把 LOF 快照可用误解为 LOF 历史也可用；历史当前仅 ETF。
## 8. 基金公司详情
```text
GET /api/fund/companies/detail
```
参数：`company_id`（必填），从基金资料的 `company_id` 获取。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/companies/detail?company_id=<company-id>' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `company_id`、`company_name`、`company_type`、`established_date_ms`、`fund_count`、`scale`。
### 避错要点
- `company_id` 不是基金 ticker 或 `thscode`；先从基金资料发现。
## 9. 基金行业配置
```text
GET /api/fund/portfolio/industry-allocation
```
参数：`fund_type` 和单个 `thscode`（均必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/portfolio/industry-allocation?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `report_period`、`industry_name`、`ratio_pct`。
### 避错要点
- 行业配置按报告期披露，不是实时行业暴露；`ratio_pct` 是百分数原值。
## 10. 历史业绩指标
```text
GET /api/fund/performance/indicators-historical
```
参数：`fund_type`、`thscode`、毫秒时间戳 `start`、`end` 均必填。区间必须有序且最多 5 年。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/performance/indicators-historical?fund_type=otc&thscode=025480.OF&start=1704038400000&end=1735660799000' \
-H 'X-api-key: <your-api-key>'
```
`data` 仅包含 `timestamp` 和 `item[]`；固定上游周期 `DAY_1` 不作为顶层响应字段，也不返回顶层 `thscode`、`interval`。`data.timestamp` 保留明确的上游数据时间；`item[]` 字段为 `date_ms`、`rsi_pct`、`donchian_channel`、`track_index_pe_ttm_five_year_percentile`。
### 避错要点
- `start/end` 缺一不可；超过 5 年应拆成不重叠窗口。
## 11. 最大回撤
```text
GET /api/fund/performance/drawdowns
```
参数：`fund_type` 和单个 `thscode`（均必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/performance/drawdowns?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 含 `thscode`、`ticker` 及固定十个区间：`week`、`month`、`tmonth`、`hyear`、`year`、`twoyear`、`tyear`、`fyear`、`nowyear`、`now`。
### 避错要点
- 这些是固定区间回撤，不接收客户端自定义时间范围。
## 12. 前十大持有人
```text
GET /api/fund/holders/top
```
参数：`fund_type`、`thscode` 必填；`limit` 可选，最大 10。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/holders/top?fund_type=exchange&thscode=588000.SH&limit=10' \
-H 'X-api-key: <your-api-key>'
```
`data` 为 `{timestamp, limit, item[]}`；`limit` 回显服务端实际采用的返回条数上限。`item[]` 字段为 `holder_id`、`holder_code`、`holder_name`、`holder_type`、`rank`、`hold_share`、`hold_rate_pct`、`report_date_ms`、`publish_date_ms`。
### 避错要点
- 持有人榜是报告期披露；`limit>10` 返回参数范围错误。
## 13. 基金分红
```text
GET /api/fund/corporate-actions/dividends
```
参数：`fund_type` 和单个 `thscode`（均必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/corporate-actions/dividends?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data` 可含汇总字段 `dividend_count`、`dividend_total`；`item[]` 字段为 `per_ten_cash_before_tax`、`per_ten_cash_after_tax`、`progress`、`publish_date_ms`、`registration_date_ms`、`ex_dividend_date_ms`、`payment_date_ms`、`reinvestment_date_ms`、`profit_base_date_ms`、`in_dividend_date_ms`。
### 避错要点
- 每十份现金分红与汇总金额口径不同，不要混为每份分红。
## 14. 基金诊断
```text
GET /api/fund/diagnostics/detail
```
参数：`fund_type` 和单个 `thscode`（均必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/diagnostics/detail?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `thscode`、`ticker`、`fund_type`、`peer_code`、`dimensions`、`peer_dimensions`、`probabilities`、`ranges`、`resilience`、`peer_resilience`。
### 避错要点
- 诊断维度是数据服务返回值，不等于基金推荐、风险承诺或投资建议。
## 15. 基金主要财务指标
```text
GET /api/fund/financials/indicators
```
参数：`fund_type` 和单个 `thscode`（均必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/financials/indicators?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `start_date_ms`、`end_date_ms`、`publish_date_ms`、`distribution_profit`、`current_profit`、`current_income`、`distribution_share_profit`、`average_nav_profit_margin`、`average_share_current_profit`、`share_nav`、`sum_nav_rate`、`asset_nav`、`sum_share_nav`、`nav_rate`。
### 避错要点
- 财务数据按披露期返回，空值不补零。
## 16. 基金利润表
```text
GET /api/fund/financials/income-statements
```
参数：`fund_type` 和单个 `thscode`（均必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/financials/income-statements?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 含 `start_date_ms`、`end_date_ms`、`publish_date_ms`，以及 `income`、`investment_income`、`stock_investment_income`、`bond_investment_income`、`fund_investment_income`、`dividend_income`、`interest_income`、`fair_value_income`、`exchange_income`、`other_income`、`total_income`、`fee`、`manager_reward`、`custodian_fee`、`transaction_cost`、`tax_surcharge`、`total_fee`、`total_profit`、`net_profit`。
### 避错要点
- 这是基金财务报表，不是上市公司利润表；不要混用 A 股财务端点。
## 17. 基金资产负债表
```text
GET /api/fund/financials/balance-sheets
```
参数：`fund_type` 和单个 `thscode`（均必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/financials/balance-sheets?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 含 `start_date_ms`、`end_date_ms`、`publish_date_ms`、`total_assets`、`bank_deposit`、`fund_investment`、`stock_investment`、`bond_investment`、`transactional_financial_assets`、`other_assets`、`total_liability`、`other_liability`、`owner_total_equity`、`undistributed_profit`、`liability_and_owner_equity`。
### 避错要点
- 按报告日对齐利润表和资产负债表，不要按返回数组下标直接拼接。
## 18. 基金经理投资风格
```text
GET /api/fund/managers/investment-style
```
参数：`manager_id`（必填），从基金资料的 `manager_info[]` 获取。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/managers/investment-style?manager_id=<manager-id>' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `representative_fund_thscode`、`representative_fund_ticker`、`representative_fund_name`、`investment_idea`、`total_fund_scale`、`industry_preferences`。关联基金无法唯一解析时 `representative_fund_thscode=null`，主能力仍成功。
### 避错要点
- `manager_id` 不是经理姓名；关联基金代码为空不等于经理能力失败。
## 19. 基金经理业绩
```text
GET /api/fund/managers/performance
```
参数：`manager_id` 和 `range` 必填；`range` 可选 `month`、`tmonth`、`year`、`nowyear`、`now`。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/managers/performance?manager_id=<manager-id>&range=year' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `date_ms`、`manager_return_pct`、`peer_return_pct`、`benchmark_return_pct`。
### 避错要点
- `range` 是固定枚举，不接收任意起止日期。
## 20. 基金经理从业经历
```text
GET /api/fund/managers/experience
```
参数：`manager_id`（必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/managers/experience?manager_id=<manager-id>' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `awards`、`heavy_assets`、`investment_history`。
### 避错要点
- 未配置奖项或经历可为空，不应改写为请求失败。
## 21. 基金经理详情与雷达对比
```text
GET /api/fund/managers/detail
```
参数：`manager_id`（必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/managers/detail?manager_id=<manager-id>' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `manager_id`、`manager_name`、`sex`、`degree`、`company_id`、`company_name`、`resume`、`photo_url`、`annual_return_pct`、`maximum_return_pct`、`radar_comparison`。`radar_comparison[]` 按 `fund_category + horizon` 对齐，含 `manager_metrics`、`manager_scores`、`peer_average_scores`。
### 避错要点
- 雷达节点只返回实际覆盖的类别和周期；不要补造缺失节点。
## 22. 基金资讯列表
```text
GET /api/fund/news/article-list
```
参数：`fund_type`、`thscode` 必填；`limit` 可选，默认 20、范围 1–100；`offset` 是可选不透明翻页游标。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/news/article-list?fund_type=otc&thscode=025480.OF&limit=20' \
-H 'X-api-key: <your-api-key>'
```
`data` 含 `timestamp`、`limit`、`offset`、`has_more`、`item[]`，不提供不可靠的总条数。条目字段为 `id`、`content_type`、`title`、`summary`、`source`、`url`、`image_url`、`author`、`publish_time_ms`、`top`。
### 避错要点
- `offset` 不是整数页码；下一页必须使用响应返回的游标。
- 分页结束只以 `has_more=false` 为准，不根据本页条数推断，也不要读取不存在的 `total`。
- 资讯元数据不等于新闻原文授权，按返回 URL 和账号权限使用。
## 23. 基金募集列表
```text
GET /api/fund/offerings/list
```
参数：`subscribe`（必填），枚举 `active` / `upcoming`。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/offerings/list?subscribe=active' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `thscode`、`ticker`、`subscription_start_ms`、`subscription_end_ms`。新基金尚未进入权威代码表时 `thscode` 可以为 `null`。
### 避错要点
- `active/upcoming` 是募集状态；不要传上游数字枚举。
- `thscode=null` 不等于整批失败，保留 ticker 和募集时间。
## 24. 历史股票持仓
```text
GET /api/fund/portfolio/stock-history
```
参数：`fund_type`、`thscode`、`report_type`、`end_date` 均必填。`report_type` 与 `end_date` 应先从股票持仓报告日期端点发现。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/portfolio/stock-history?fund_type=otc&thscode=025480.OF&report_type=<type>&end_date=<date>' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `thscode`、`ticker`、`name`、`asset_type`、`hold_ratio`、`market_value`、`period_increase_pct`、`rank`、`report_type`、`end_date_ms`。
### 避错要点
- 不要猜报告类型或截止日期；先调用 report-dates 能力。
## 25. 股票持仓报告日期
```text
GET /api/fund/portfolio/stock-report-dates
```
参数：`fund_type`、`thscode` 必填；`report_type` 可选。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/portfolio/stock-report-dates?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `report_type`、`report_type_name`、`start_date_ms`、`end_date_ms`。
### 避错要点
- 返回列表是下一步历史持仓查询的有效参数来源。
## 26. 历史债券持仓
```text
GET /api/fund/portfolio/bond-history
```
参数与股票历史持仓一致：`fund_type`、`thscode`、`report_type`、`end_date` 均必填。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/portfolio/bond-history?fund_type=otc&thscode=025480.OF&report_type=<type>&end_date=<date>' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段与股票历史持仓一致，`asset_type` 用于区分资产类型。
### 避错要点
- 债券代码不能假定具备 A 股交易所后缀；以返回的 `thscode`/`ticker` 为准。
## 27. 债券持仓报告日期
```text
GET /api/fund/portfolio/bond-report-dates
```
参数：`fund_type`、`thscode` 必填；`report_type` 可选。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/portfolio/bond-report-dates?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `report_type`、`report_type_name`、`start_date_ms`、`end_date_ms`。
### 避错要点
- 股票与债券报告日期是不同能力，不要交叉复用发现结果。
## 28. 基金资产配置
```text
GET /api/fund/portfolio/asset-allocation
```
参数：`fund_type` 和单个 `thscode`（均必填）。
```bash
curl 'https://fuyao.aicubes.cn/api/fund/portfolio/asset-allocation?fund_type=otc&thscode=025480.OF' \
-H 'X-api-key: <your-api-key>'
```
`data.item[]` 字段为 `report_date_ms`、`stock_ratio_pct`、`bond_ratio_pct`、`deposit_ratio_pct`、`other_ratio_pct`。
### 避错要点
- 各比例按报告期披露且为百分数原值；空值不补零，也不要强制归一化为 100。
## 基金专用错误语义
| `code` | 含义 | 调用方处理 |
| --- | --- | --- |
| `3001` | 未找到对应基金 | 先用 meta 搜索核对 `fund_type`、`asset_type` 与 `thscode`。 |
| `3002` | 数据尚未准备 | 保留 `request_id` 和数据口径，稍后再查；不得补零或用模拟数据。 |
| `3004` | 目标基金类型不支持该能力 | 改用适用于该 `asset_type` 的端点，不重试原请求。 |
references/api/endpoints-index.md›
# 指数与板块端点
> 同花顺指数 / 板块的目录、成分股、行情快照与历史 K 线。参数定义、响应字段以本文档为准。
## 通用说明
- 指数 `thscode` 支持同花顺后缀（`.TI`，如 `886042.TI`）和标准交易所后缀（`.SH` / `.SZ`，如 `000300.SH`）。
- 指数端点**没有**复权概念，`adjust` 参数不适用。
- 指数快照**不支持**全市场模式，必须显式传 `thscodes`。
---
## 1. 同花顺指数列表
```text
GET /api/a-share-index/catalog/ths-index-list
```
按类别列出同花顺概念、区域、特色或行业指数清单。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `tag` | query | string | 否 | 指数类别，枚举 `cn_concept` / `region` / `tszs` / `industry`（大小写不敏感）。 | `cn_concept` |
> 单个 `tag` 全量返回，无分页。返回可能较大，应落盘或只保留目标匹配项。
### 请求示例
```bash
# 概念板块列表
curl 'https://fuyao.aicubes.cn/api/a-share-index/catalog/ths-index-list?tag=cn_concept' \
-H 'X-api-key: <your-api-key>'
# 行业指数列表
curl 'https://fuyao.aicubes.cn/api/a-share-index/catalog/ths-index-list?tag=industry' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 数据就绪时间（毫秒）。 |
| `item` | array | 指数列表。 |
`item[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 指数 thscode，如 `886042.TI`。 |
| `name` | string | 指数名称。 |
> 指数维度不暴露纯 `ticker`。
---
## 2. 指数成分股
```text
GET /api/a-share-index/constituents/ths-stock-list
```
查询单个 THS 板块或标准指数的当前成分股。**单次一个 `thscode`**，不接受逗号。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscode` | query | string | 是 | 单个指数 thscode。支持 `886042.TI`（同花顺板块）或 `000300.SH`（沪深 300 等标准指数）。 | — |
### 请求示例
```bash
# 沪深 300 成分股
curl 'https://fuyao.aicubes.cn/api/a-share-index/constituents/ths-stock-list?thscode=000300.SH' \
-H 'X-api-key: <your-api-key>'
# 某概念板块成分股
curl 'https://fuyao.aicubes.cn/api/a-share-index/constituents/ths-stock-list?thscode=886042.TI' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 数据就绪时间（毫秒）。 |
| `item` | array | 成分股列表。 |
`item[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 成分股 thscode，如 `600519.SH`。 |
| `ticker` | string | 纯代码，如 `600519`。 |
| `name` | string | 成分股名称。 |
### 避错要点
- 逗号分隔多个指数：端点仅接受单个 `thscode`。
- 把结果当历史成分：返回的是当前成分，不提供历史调入调出序列。
---
## 3. 指数行情快照
```text
GET /api/a-share-index/prices/snapshot
```
批量查询有限数量指数 / 板块的最新行情。**必须传 `thscodes`**，不支持全市场模式。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscodes` | query | string | 是 | 逗号分隔的指数 thscode 列表。支持 `.SH` / `.SZ` / `.TI`。 | — |
| `limit` | query | integer | 否 | 仅为签名兼容，**无实际效果**。 | — |
| `offset` | query | integer | 否 | 仅为签名兼容，**无实际效果**。 | — |
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share-index/prices/snapshot?thscodes=000300.SH,000001.SH' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `SnapshotData`，`item[]` 为 `PriceSnapshotItem`，字段结构与 [A 股行情快照](endpoints-prices.md#1-行情快照) 的 `PriceSnapshotItem` 一致。
### 避错要点
- 省略 `thscodes` 期望全量：指数快照**不支持**全市场模式，空输入会被拒绝。
- 把股票代码交给指数端点：股票代码应使用 `/api/a-share/prices/snapshot`。
---
## 4. 指数历史 K 线
```text
GET /api/a-share-index/prices/historical
```
获取单只指数 / 板块的历史日 K 线。**单次一个 `thscode`**，窗口 ≤ 10 年。指数无复权概念。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscode` | query | string | 是 | 单只指数 thscode，**不接受逗号**。 | — |
| `interval` | query | string | 是 | K 线周期，固定为 `1d`（日线）。 | `1d` |
| `start` | query | long | 是 | 起始时间（毫秒）。`end - start` > 10 年返回 `code=1003`。 | — |
| `end` | query | long | 是 | 结束时间（毫秒）。 | — |
> 无 `adjust`、无 `offset` — 指数没有复权语义；响应 `data.adjust` 恒为 `null`，不代表数据缺失。
### 请求示例
```bash
# 沪深 300 近一年日 K
curl 'https://fuyao.aicubes.cn/api/a-share-index/prices/historical?thscode=000300.SH&interval=1d&start=1716105600000&end=1747641600000' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `HistoricalData`，`item[]` 为 `PriceBarItem`，字段结构与 [A 股历史 K 线](endpoints-prices.md#2-历史-k-线) 的 `PriceBarItem` 一致。
### 避错要点
- 传 `adjust` 参数：指数无复权概念，传 `adjust` 无意义。
- 一次传多个指数：端点仅接受单个 `thscode`。
references/api/endpoints-market-dumps.md›
# 全市场数据导出（Market Dumps）
> 一次性获取全市场 Parquet 格式的日K和复权事件数据。适合批量回测、离线分析、自建数据仓库。**不要用逐只 `prices-historical` 拉全市场**——全市场约 5000+ 只票，逐只调需数千次 HTTP 请求，用本端点 3 次请求即可完成。
## 端点概览（3 个）
| 端点 | dump 类型 | 内容 | 规模 | 用途 |
|------|-----------|------|------|------|
| `GET /api/dump/market-dumps/daily-k/download-url` | `daily-k` | 全市场 10 年日K（未复权） | ~945 万行 | 首次全量 |
| `GET /api/dump/market-dumps/daily-k-10d/download-url` | `daily-k-10d` | 全市场最近 10 交易日 | ~25 万行 | 日常增量 |
| `GET /api/dump/market-dumps/adjustment-factors/download-url` | `adjustment-factors` | 全市场复权事件（分红/送股/配股） | ~5.2 万行 | 复权计算 |
## 通用流程（3 步）
```
1. GET 签名端点 → 获取 S3 预签名下载 URL
2. GET 预签名 URL → 下载 Parquet 文件到本地
3. 用 pandas/pyarrow/DuckDB 读取 Parquet 文件
```
⚠️ **预签名 URL 有效期只有约 5 分钟**，拿到立刻下载，不要缓存 URL。
---
## 1. 全市场 10 年日K
```text
GET /api/dump/market-dumps/daily-k/download-url
```
返回全 A 股最近约 10 年的日K Parquet 文件下载链接。数据为**原始未复权**价格。
### 请求参数
无请求参数。认证仅通过 Header。
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/dump/market-dumps/daily-k/download-url' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | int | 0=成功。2002/2004=认证失败。4040=数据尚未就绪。5xxx=服务端错误。 |
| `message` | string | 错误信息（code≠0 时） |
| `data.presigned_url` | string | S3 预签名下载链接，有效期约 5 分钟 |
| `data.presigned_url_expires_at` | string | URL 过期时间（ISO 8601 UTC） |
### 完整下载流程
```bash
# Step 1: 签出 URL
DOWNLOAD_URL=$(curl -s 'https://fuyao.aicubes.cn/api/dump/market-dumps/daily-k/download-url' \
-H 'X-api-key: <your-api-key>' | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['presigned_url'])")
# Step 2: 下载 Parquet（大文件，可能需要几分钟）
curl -L -o /tmp/a_share_daily_k_full.parquet "$DOWNLOAD_URL"
# Step 3: 验证
python3 -c "import pandas as pd; df=pd.read_parquet('/tmp/a_share_daily_k_full.parquet'); print(f'rows={len(df)}, cols={list(df.columns)}')"
```
### Parquet Schema（日K）
| 列名 | 类型 | 说明 |
|------|------|------|
| `thscode` | string | 带交易所后缀的完整代码，如 `600519.SH` |
| `currency` | string | 币种代码，A 股固定为 `CNY` |
| `interval` | string | 周期代码，固定为 `1d` |
| `adjusted` | string | 复权方式，固定为 `none`（未复权） |
| `date_ms` | long | K 线日期（毫秒，Asia/Shanghai 零点） |
| `open_price` | number | 开盘价（原始货币） |
| `high_price` | number | 最高价（原始货币） |
| `low_price` | number | 最低价（原始货币） |
| `close_price` | number | 收盘价（原始货币） |
| `volume` | number | 成交量（股） |
| `turnover` | number | 成交额（原始货币） |
---
## 2. 全市场近 10 交易日日K
```text
GET /api/dump/market-dumps/daily-k-10d/download-url
```
与全量日K共用同一 Parquet Schema，仅数据范围缩小为最近 10 个交易日。适合每天增量同步。
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/dump/market-dumps/daily-k-10d/download-url' \
-H 'X-api-key: <your-api-key>'
```
### 避错要点
- 本地数据落后 >7 个交易日时，`daily-k-10d` 不能完全覆盖缺口，应改用 `daily-k`（全量）重新拉。
- 增量 Parquet 内的日期可能与本地数据重叠，建议入库时按 `(thscode, date_ms)` 去重或 UPSERT。
---
## 3. 全市场复权因子事件
```text
GET /api/dump/market-dumps/adjustment-factors/download-url
```
返回全 A 股全部历史的复权事件（现金分红、送股、配股）。调用方可用这些事件自行推算日频复权因子。
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/dump/market-dumps/adjustment-factors/download-url' \
-H 'X-api-key: <your-api-key>'
```
### Parquet Schema（复权因子）
| 列名 | 类型 | 说明 |
|------|------|------|
| `thscode` | string | 带交易所后缀的完整代码 |
| `ticker` | string | 展示用代码 |
| `ex_date_ms` | long | 除权除息日（毫秒，Asia/Shanghai 零点） |
| `dividend_per_share` | number | 每股现金分红（税前） |
| `per_share_bonus` | number | 每股送股比例 |
| `allotment_ratio` | number | 配股比例 |
| `allotment_price` | number | 配股价格（原始货币） |
| `currency` | string | 币种代码，A 股固定为 `CNY` |
---
## 避错要点
| 错误 | 正确处理 |
|------|----------|
| 预签名 URL 过期（HTTP 403） | 重新调签名端点获取新 URL，再下载 |
| 想用 JSON 格式拿全市场 | 本端点只出 Parquet。需要 JSON 的逐只数据用 `/api/a-share/prices/historical` |
| 把 dump 端点当成返回 JSON 数据的 REST 端点 | 它只返回签名 URL，实际数据需通过第二步 GET 预签名 URL 获取 |
| 复权因子用逐只 `corporate-actions` 端点拉全市场 | 也是 ~5000 次请求，应该用 `adjustment-factors` dump |
| `daily-k-10d` 的 Parquet 增量入库时未去重 | 按 `(thscode, date_ms)` UPSERT，避免主键冲突 |
| 预签名 URL 存下来跨天用 | 重新签名，不要存 URL |
references/api/endpoints-meta.md›
# 元信息端点
> 标的检索与代码表获取。参数定义、响应字段以本文档为准。
## 1. 标的检索
```text
GET /api/meta/tickers/search
```
按完整 `thscode`、纯 ticker、中文名或英文名做跨市场检索与消歧。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `q` | query | string | 是 | 检索词，支持 thscode / ticker / 中英文名子串。 | — |
| `exchange` | query | string | 否 | 交易所过滤，枚举 `SH` / `SZ` / `BJ`。 | — |
| `asset_type` | query | string | 否 | 资产类别过滤；支持逗号分隔多个值：`a-share` / `a-share-index` / `forex` / `fund-otc` / `fund-etf` / `fund-lof` / `fund-reits`。 | — |
| `limit` | query | integer | 否 | 返回条数上限，≤ 50。 | `10` |
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/meta/tickers/search?q=贵州茅台&limit=5' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`，`item[]` 元素为 `TickerItem`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode，如 `600519.SH`。 |
| `ticker` | string | 纯代码，如 `600519`。 |
| `name` | string | 展示名称。 |
| `exchange` | string | 交易所后缀（`SH` / `SZ` / `BJ`），无后缀指数为 `null`。 |
| `asset_type` | string | 资产类别：A 股、指数、外汇或基金叶子类型。 |
| `currency` | string | 币种代码。 |
### 避错要点
- 看到首条模糊匹配就调用业务端点：先结合 `asset_type`、`exchange` 和名称筛选唯一结果。
- 凭名称猜交易所后缀：必须通过搜索消歧，不要自行拼 `.SH` / `.SZ`。
- 多结果仍可能成立时：把候选的代码、名称和资产类别列出，请用户确认，不要自行选择。
- 查基金时优先传基金 `asset_type`；需要同时搜索 ETF 与 LOF 时传 `fund-etf,fund-lof`，不要传抽象值 `fund`。
---
## 2. 标的列表
```text
GET /api/meta/tickers/list
```
按交易所与资产类别批量获取代码表，支持分页。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `exchange` | query | string | 否 | 交易所过滤，逗号分隔列表。 | `SH,SZ` |
| `asset_type` | query | string | 否 | 资产类别；支持逗号分隔多个值，枚举同检索端点。 | — |
| `limit` | query | integer | 否 | 每页条数，≤ 10000。 | `1000` |
| `offset` | query | integer | 否 | 分页偏移。 | `0` |
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/meta/tickers/list?exchange=SH,SZ&asset_type=a-share&limit=1000&offset=0' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`，`item[]` 元素结构与 `tickers/search` 的 `TickerItem` 一致。
### 分页规则
- 终止条件：当前页 `item` 数量小于 `limit`，或返回空页。
- 迭代方式：`offset += limit`，直到终止。
- 完整代码表属于大结果，应写入文件供后续程序读取，只报告文件路径和行数，不要把完整列表写入对话上下文。
### 避错要点
- 一次把完整代码表写入上下文：应落盘，只报告路径和行数。
- 忘记递增 `offset`：每页取完后必须 `offset += limit`。
- 需要多个交易所时：确认逗号分隔值格式，默认仅 `SH,SZ`，不含 `BJ`。
- 需要多个资产类别时：在同一个 `asset_type` 中使用逗号分隔并去重；任一未知或空 token 都会返回 `1003`。
references/api/endpoints-prices.md›
# 行情与公司行为端点
> A 股行情快照、历史 K 线、复权因子事件流。参数定义、响应字段以本文档为准。
## 1. 行情快照
```text
GET /api/a-share/prices/snapshot
```
获取单只、多只或全市场 A 股最新行情快照。支持两种模式：按 `thscodes` 显式批量，或 `limit/offset` 全市场分页。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscodes` | query | string | 否 | 逗号分隔的 thscode 列表，批量模式。传此参数时忽略分页。 | — |
| `limit` | query | integer | 否 | 每页条数（全市场分页模式）。 | `100` |
| `offset` | query | integer | 否 | 分页偏移（全市场分页模式）。 | `0` |
> `thscodes` 与 `limit/offset` 二选一。省略 `thscodes` 时进入全市场分页模式。
### 请求示例
```bash
# 批量模式：指定股票
curl 'https://fuyao.aicubes.cn/api/a-share/prices/snapshot?thscodes=600519.SH,000001.SZ' \
-H 'X-api-key: <your-api-key>'
# 全市场分页模式
curl 'https://fuyao.aicubes.cn/api/a-share/prices/snapshot?limit=100&offset=0' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `SnapshotData`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long \| null | 数据就绪时间（毫秒）。按 `thscodes` 显式取数时为 `null`；分页模式下为序列中最新有效时间。 |
| `total` | int | 全市场代码表总数（分页模式用于估算页数）。 |
| `item` | array | 快照记录列表。 |
`item[]` 为 `PriceSnapshotItem`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 带交易所后缀的完整 thscode，如 `600519.SH`。 |
| `ticker` | string | 纯代码（无后缀），如 `600519`。 |
| `last_price` | number | 最新成交价（原始货币）。 |
| `price_change` | number | 相对前收盘价的涨跌额。 |
| `price_change_ratio_pct` | number | 涨跌幅（百分比数值，如 `1.74` 表示 +1.74%）。 |
| `open_price` | number | 当日开盘价。 |
| `high_price` | number | 当日最高价。 |
| `low_price` | number | 当日最低价。 |
| `prev_price` | number | 前收盘价。 |
| `volume` | number | 成交量（股）。 |
| `turnover` | number | 成交额（原始货币）。 |
> **注意**：快照响应**不返回**标的中文名 `name`。需要中文名时配合 `/api/meta/tickers/search` 或 `/api/meta/tickers/list` 解析。
### 全市场分页规则
- 终止条件：当前页 `item` 数量小于 `limit`。
- 全市场快照属于大结果，应写入文件，只报告路径和行数。
### 避错要点
- 认证探测时省略 `thscodes`：意外拉取全市场，应指定单一 `thscode` 探测。
- 批量模式期望 `name`：快照不含名称字段。
---
## 2. 历史 K 线
```text
GET /api/a-share/prices/historical
```
获取单只标的的 A 股历史 K 线序列。**每次请求仅一个 thscode**，且时间窗口 ≤ 10 年。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscode` | query | string | 是 | 单只标的 thscode，**不接受逗号**。多标的请分多次请求。 | — |
| `interval` | query | string | 是 | K 线周期，当前仅支持 `1d`（日线）。 | `1d` |
| `start` | query | long | 是 | 起始时间，毫秒 Unix 时间戳。缺失返回 `code=1001`。 | — |
| `end` | query | long | 是 | 结束时间，毫秒 Unix 时间戳。`end - start` > 10 年返回 `code=1003`。 | — |
| `adjust` | query | string | 否 | 复权方式：`none` / `forward`（前复权）/ `backward`（后复权）。 | `forward` |
| `offset` | query | integer | 否 | 分页偏移。 | `0` |
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/prices/historical?thscode=600519.SH&interval=1d&start=1716105600000&end=1747641600000&adjust=forward' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `HistoricalData`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 数据就绪时间（毫秒），为序列中最新一根 K 线的上游有效时间。 |
| `item` | array | K 线列表。 |
`item[]` 为 `PriceBarItem`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `date_ms` | long | K 线日期（毫秒）。 |
| `open_price` | number | 开盘价。 |
| `high_price` | number | 最高价。 |
| `low_price` | number | 最低价。 |
| `close_price` | number | 收盘价。 |
| `volume` | number | 成交量（股）。 |
| `turnover` | number | 成交额（原始货币）。 |
### 避错要点
- 一次传多只股票：端点仅接受单个 `thscode`。
- 时间窗口 > 10 年：返回 `code=1003`，客户端需按 10 年切片分次请求。
- 传纯 6 位代码：必须带交易所后缀。
---
## 3. 复权因子事件流
```text
GET /api/a-share/corporate-actions/adjustment-factors
```
获取单只标的的 A 股复权因子事件流（现金分红 / 送股 / 配股）。**每次请求仅一个 thscode**。
返回原始事件流，供调用方自行推导复权因子。若只需复权后价格，直接调用历史 K 线端点并传 `adjust=forward|backward`。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscode` | query | string | 是 | 单只标的 thscode，**不接受逗号**。 | — |
| `from` | query | string | 否 | 事件起始日，格式 `YYYY-MM-DD`。 | — |
| `to` | query | string | 否 | 事件截止日，格式 `YYYY-MM-DD`。 | — |
### 请求示例
```bash
# 茅台全部历史复权事件
curl 'https://fuyao.aicubes.cn/api/a-share/corporate-actions/adjustment-factors?thscode=600519.SH' \
-H 'X-api-key: <your-api-key>'
# 平安银行近 5 年事件
curl 'https://fuyao.aicubes.cn/api/a-share/corporate-actions/adjustment-factors?thscode=000001.SZ&from=2021-01-01&to=2026-01-01' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `AdjustmentFactorsData`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 带交易所后缀的完整 thscode。 |
| `ticker` | string | 纯代码（无后缀）。 |
| `item` | array | 事件列表，按 `ex_date_ms` 降序排列（最新在前）。 |
`item[]` 为 `AdjustmentFactorItem`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `ticker` | string | 纯代码。 |
| `ex_date_ms` | long | 除权除息日，Asia/Shanghai 00:00:00 毫秒 Unix 时间戳。 |
| `dividend_per_share` | number | 每股现金分红（税前，原始货币）。非现金事件为 `0`。 |
| `per_share_bonus` | number | 每股送股比例（如 `0.1` 表示 10 送 1）。纯现金分红事件为 `0`。 |
> **字段约定**：响应**不返回** `event_type` / `record_date` / `adjust_factor`。事件类型由 `dividend_per_share` 与 `per_share_bonus` 两个数值字段隐式区分：`dividend_per_share > 0` 为现金分红，`per_share_bonus > 0` 为送股。
### 避错要点
- 把事件流当作服务端已计算好的每日复权因子：事件流是原始事件，需调用方自行推导。
- 把月线写成 `1mo`：个股历史 K 线当前仅支持 `1d`。
- 一次传多只股票：端点仅接受单个 `thscode`。
references/api/endpoints-special-data.md›
# 特色数据端点
> A 股涨停股票池、连板天梯、当日个股异动、市场热榜与龙虎榜。参数定义、响应字段以本文档为准。
## 1. 涨停股票池
```text
GET /api/a-share/special-data/limit-up-pool
```
按交易日返回 A 股涨停 / 连板股票池。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `date_ms` | query | long | 否 | 交易日，Asia/Shanghai 00:00 毫秒戳。省略则取服务器今日。 | 今日 |
| `page` | query | integer | 否 | 页码，≥ 1。 | `1` |
| `size` | query | integer | 否 | 每页条数，1–200。 | `50` |
| `sort_field` | query | string | 否 | 排序字段，枚举 `last_price` / `continue_day_cnt` / `seal_money` / `limit_up_time`。 | `last_price` |
| `sort_dir` | query | string | 否 | 排序方向，枚举 `asc` / `desc`。 | `desc` |
> 后端池固定为全部连板 + `main,chinext,ssestar,north` 四类板块，不可配置。
### 请求示例
```bash
# 今日涨停池，按涨停时间排序
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/limit-up-pool?sort_field=limit_up_time&sort_dir=asc&size=50' \
-H 'X-api-key: <your-api-key>'
# 指定交易日
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/limit-up-pool?date_ms=1718294400000&page=1&size=100' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, pagination, item[]}`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 数据就绪时间（毫秒）。 |
| `pagination` | object | 分页信息：`{total, pages, size, page}`。 |
| `item` | array | 涨停股列表。 |
`item[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `name` | string | 股票名称。 |
| `is_st` | boolean | 是否 ST 股。 |
| `is_new` | boolean | 是否次新股。 |
| `last_price` | number | 最新价。 |
| `price_change_ratio_pct` | number | 涨跌幅（百分比数值）。 |
| `limit_up_time` | string | 涨停时间。 |
| `limit_up_reason` | string | 涨停原因。 |
| `continue_day_text` | string | 连板天数文本（如「2 连板」）。 |
| `continue_day_cnt` | integer | 连板天数。 |
| `seal_money` | number | 封单金额。 |
| `max_seal_money` | number | 最大封单金额。 |
### 避错要点
- 在非交易日期待报错：非交易日返回空集，不报错。
- 混用 `limit/offset` 分页：本端点使用 `page/size` 分页，不是 `limit/offset`。
- `sort_field` 传非枚举值：返回 `code=1002`。
---
## 2. 连板天梯
```text
GET /api/a-share/special-data/limit-up-ladder
```
返回近 30 个交易日的连板梯队矩阵。
### 请求参数
无入参。返回固定窗口矩阵。
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/limit-up-ladder' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, window, item[]}`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 数据就绪时间（毫秒）。 |
| `window` | object | 窗口信息：`{length, date_list, board_caps}`。 |
| `item` | array | 按日期排列的连板矩阵。 |
`item[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `date` | string | 日期。 |
| `boards` | object | 各梯队股票：`{two_board, three_board, four_board, five_board, six_board, seven_over}`。 |
> 每个 `boards.*` 最多返回 4 只股票；无该梯队时返回 `[]`。
> `boards.*[].seal_nextday` 在最近一个交易日为 `null`（无次日参考）。
`boards.*[]` 元素（每只股票，共 6 个字段）：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `name` | string | 股票名称。 |
| `board_num` | integer | 连板天数。 |
| `sign_level` | string | 标记级别。 |
| `seal_nextday` | string \| null | 次日封板情况（最近交易日为 `null`）。 |
### 避错要点
- 期待逐股明细或自定义时间窗口：本端点返回固定 30 日矩阵，不支持自定义。
- 把缺失梯队当数据错误：无该梯队返回 `[]` 是正常行为。
---
## 3. 当日个股异动原因（列表）
```text
GET /api/a-share/special-data/anomaly-analysis-list
```
返回当日全市场个股异动原因。**仅 REST 端点，无对应 MCP 工具。**
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `tag_codes` | query | string | 否 | 异动标签，逗号分隔列表。省略或传空返回全量当日记录。 | — |
`tag_codes` 允许值（大小写不敏感，去重，OR 语义）：
| 标签 | 含义 |
| --- | --- |
| `LIMIT_UP` | 涨停 |
| `LIMIT_DOWN` | 跌停 |
| `SHARP_RISE` | 大幅上涨 |
| `SHARP_FALL` | 大幅下跌 |
| `RAPID_RALLY` | 快速反弹 |
| `RAPID_DECLINE` | 快速下跌 |
### 请求示例
```bash
# 全部当日异动
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/anomaly-analysis-list' \
-H 'X-api-key: <your-api-key>'
# 仅涨停和跌停
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/anomaly-analysis-list?tag_codes=LIMIT_UP,LIMIT_DOWN' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`，仅返回当日快照：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 数据就绪时间（毫秒）。 |
| `item` | array | 异动记录列表。 |
`item[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `stock_name` | string | 股票名称。 |
| `analysis_content` | string | 异动原因分析。 |
| `keyword_list` | array | 关键词列表。 |
| `thscode` | string | 完整 thscode。 |
| `tag_name` | string | 异动标签名称。 |
### 避错要点
- 空的 token（连续逗号 / 末尾逗号）或未知标签：返回 `code=1002`。
- 期待历史异动查询：本端点仅支持当日快照，不提供历史查询。
---
## 4. 当日个股异动原因（按标的）
```text
GET /api/a-share/special-data/anomaly-analysis-stock
```
按 1–50 个 thscode 批量查询当日个股异动原因。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscodes` | query | string | 是 | 1–50 个 thscode，逗号分隔。格式为 6 位数字 + `.SH`/`.SZ`/`.BJ`（后缀大小写不敏感，服务端归一化为大写）。 | — |
> 数量上限在去重前检查：传入 50 个原始 token（即使有重复）即达上限，超过返回 `code=1003`。
### 请求示例
```bash
# 单只股票异动原因
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/anomaly-analysis-stock?thscodes=600519.SH' \
-H 'X-api-key: <your-api-key>'
# 批量查询
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/anomaly-analysis-stock?thscodes=600519.SH,000001.SZ,300750.SZ' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`，结构与 `anomaly-analysis-list` 一致，结果按去重后的输入顺序分组。
### 避错要点
- 传指数代码：本端点仅支持股票 thscode，不支持指数。
- 超过 50 个 token：返回 `code=1003`。
- 缺失 `thscodes`：返回 `code=1001`。
---
## 5. 飙升榜
```text
GET /api/a-share/special-data/skyrocket-list
```
返回 A 股飙升榜。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `period` | query | string | 否 | 统计周期，枚举 `day` / `hour`。 | `day` |
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/skyrocket-list?period=day' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 数据就绪时间（毫秒）。 |
| `item` | array | 飙升榜列表。 |
`item[]` 元素（共 7 个字段）：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `name` | string | 股票名称。 |
| `rank` | integer | 排名。 |
| `heat` | number | 热度值。 |
| `rank_change` | integer | 排名变化。 |
| `rank_trend` | string | 排名趋势。 |
### 避错要点
- 把榜单排名当作无延迟交易信号：榜单数据有延迟，不构成交易信号。
---
## 6. 热股榜
```text
GET /api/a-share/special-data/hot-stock-list
```
返回当前热股榜。`day` 表示 24 小时榜。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `period` | query | string | 否 | 统计周期，枚举 `day` / `hour`。`day` 表示 24 小时榜。 | `day` |
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/hot-stock-list?period=hour' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 结构与飙升榜一致：`{timestamp, item[]}`，`item[]` 字段相同（共 7 个字段：`thscode`、`ticker`、`name`、`rank`、`heat`、`rank_change`、`rank_trend`）。
### 避错要点
- 与飙升榜混淆：两者排名逻辑不同，`hot-stock-list` 是热股榜，`skyrocket-list` 是飙升榜。
- 忽略数据时间：注意 `timestamp` 表示的数据时间。
---
## 7. 历史热股榜
```text
GET /api/a-share/special-data/hot-stock-list-history
```
按指定日期返回历史热股排名。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `date` | query | string | 是 | 自然日，格式 `YYYY-MM-DD`，需在服务器最近一年窗口内。 | — |
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/hot-stock-list-history?date=2025-06-30' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{date, date_ms, item[]}`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `date` | string | 日期。 |
| `date_ms` | long | 日期毫秒戳。 |
| `item` | array | 热股排名列表。 |
`item[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `name` | string | 股票名称。 |
| `rank` | integer | 排名。 |
### 避错要点
- 用毫秒时间戳传 `date`：`date` 必须用 `YYYY-MM-DD` 字符串。
- 期待区间走势：本端点按单日返回，区间走势用 `hot-stock-rank-trend`。
---
## 8. 热股排名趋势
```text
GET /api/a-share/special-data/hot-stock-rank-trend
```
查询单只股票在日期区间内的热榜排名走势。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscode` | query | string | 是 | 单只 A 股 thscode。 | — |
| `start_date` | query | string | 是 | 起始日，`YYYY-MM-DD`，需在服务器最近一年窗口内。 | — |
| `end_date` | query | string | 是 | 结束日，`YYYY-MM-DD`，`start_date ≤ end_date`，区间 ≤ 1 年。 | — |
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/hot-stock-rank-trend?thscode=600519.SH&start_date=2025-01-01&end_date=2025-06-30' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, item[]}`，`timestamp` 为起始日 Asia/Shanghai 00:00 毫秒戳：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 起始日毫秒戳。 |
| `item` | array | 排名走势列表。 |
`item[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `date` | string | 日期。 |
| `date_ms` | long | 日期毫秒戳。 |
| `rank` | integer | 当日排名。 |
### 避错要点
- 一次传多只股票：端点仅接受单个 `thscode`。
- 把无排名日期误作接口缺失：某些日期可能无排名数据，属正常行为。
---
## 9. 龙虎榜
```text
GET /api/a-share/special-data/dragon-tiger-list
```
查询全部榜、机构榜或游资榜。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `board_type` | query | string | 否 | 榜单类型，枚举 `all` / `org` / `hot_money`。 | `all` |
| `date` | query | string | 否 | 交易日，`YYYY-MM-DD`。省略则取最新可用交易日；显式日期需为最近一年内的交易日。 | 最新交易日 |
### 请求示例
```bash
# 今日全部龙虎榜
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/dragon-tiger-list?board_type=all' \
-H 'X-api-key: <your-api-key>'
# 指定日期游资榜
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/dragon-tiger-list?board_type=hot_money&date=2025-06-30' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, board_type, trade_date, count, stock_count, stock_items, hot_money_items}`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long | 数据就绪时间（毫秒）。 |
| `board_type` | string | 榜单类型。 |
| `trade_date` | string | 交易日期。 |
| `count` | integer | 记录总数。 |
| `stock_count` | integer | 股票数量。 |
| `stock_items` | array | 个股明细列表。 |
| `hot_money_items` | array | 游资明细列表（`board_type=hot_money` 或 `all` 时返回）。 |
`stock_items[]` 元素（共 14 个字段）：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `name` | string | 股票名称。 |
| `concept_list` | array | 概念列表。 |
| `change` | number | 涨跌幅。 |
| `buy_value` | number | 买入额。 |
| `sell_value` | number | 卖出额。 |
| `net_value` | number | 净额。 |
| `net_rate` | number | 净额占比。 |
| `org_net_value` | number | 机构净额。 |
| `hot_money_net_value` | number | 游资净额。 |
| `hot_rank` | integer | 热度排名。 |
| `range_days` | integer | 上榜天数。 |
| `limit_reason` | string | 涨跌停原因。 |
`hot_money_items[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `name` | string | 游资名称。 |
| `buying` | number | 买入额。 |
| `rows` | array | 该游资关联的股票明细列表。 |
`hot_money_items[].rows[]` 元素：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 thscode。 |
| `ticker` | string | 纯代码。 |
| `name` | string | 股票名称。 |
| `concept_list` | array | 概念列表。 |
| `change` | number | 涨跌幅。 |
| `amount` | number | 金额。 |
| `buy_value` | number | 买入额。 |
| `sell_value` | number | 卖出额。 |
| `net_value` | number | 净额。 |
| `net_rate` | number | 净额占比。 |
| `org_net_value` | number | 机构净额。 |
| `hot_money_net_value` | number | 游资净额。 |
| `hot_money_net_rate` | number | 游资净额占比。 |
| `hot_money_item_net_value` | number | 游资单项净额。 |
| `hot_money_item_net_rate` | number | 游资单项净额占比。 |
| `hot_rank` | integer | 热度排名。 |
| `range_days` | integer | 上榜天数。 |
### 避错要点
- 假设省略 `date` 一定等于今天：省略 `date` 时服务端取最新可用交易日，不一定是今天（非交易日时取前一交易日）。
- 显式传非交易日：需为最近一年内的交易日，非交易日无数据。
---
## 10. 跌停股票池
```text
GET /api/a-share/special-data/limit-down-pool
```
按交易日返回 A 股跌停池。参数使用 `page/size` 分页：`date_ms` 可选；`page` 默认 `1`；`size` 默认 `50`、范围 1–200；`sort_dir=asc/desc`，默认 `desc`。`sort_field` 可选 `last_limit_time`、`first_limit_time`、`last_price`、`price_change_ratio_pct`、`turnover_ratio_pct`，默认 `last_limit_time`。
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/limit-down-pool?page=1&size=50&sort_field=last_limit_time&sort_dir=desc' \
-H 'X-api-key: <your-api-key>'
```
`data` 为 `{timestamp, pagination, item[]}`，分页结构与涨停池一致。`item[]` 字段为 `thscode`、`ticker`、`name`、`last_price`、`price_change_ratio_pct`、`first_limit_time`、`last_limit_time`、`turnover_ratio_pct`；两个跌停时间均为上海时区 `HH:mm`。
### 避错要点
- 本端点只返回跌停池，不要用涨停池加价格条件自行推导。
- `date_ms` 是上海时区自然日零点毫秒戳；不要传 `YYYY-MM-DD`。
- 混用 `limit/offset`、`size>200` 或非白名单排序字段会返回参数错误。
---
## 11. 涨停炸板股票池
```text
GET /api/a-share/special-data/limit-break-pool
```
按交易日返回曾触及涨停但已开板的 A 股股票池。`date_ms`、`page`、`size`、`sort_dir` 与跌停池相同；`sort_field` 可选 `price_change_ratio_pct`、`open_times`、`last_price`、`turnover_ratio_pct`、`turnover`，默认 `price_change_ratio_pct`。
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/special-data/limit-break-pool?page=1&size=50&sort_field=open_times&sort_dir=desc' \
-H 'X-api-key: <your-api-key>'
```
`data` 为 `{timestamp, pagination, item[]}`。`item[]` 字段为 `thscode`、`ticker`、`name`、`last_price`、`price_change_ratio_pct`、`open_times`、`turnover_ratio_pct`、`turnover`。
### 避错要点
- 股票集合由上游直接提供；不要在客户端用盘口或收盘价重建炸板规则。
- `open_times` 是开板次数，不是连续涨停天数。
- 无数据时保留空集合语义，不使用涨停池近似替代。
references/api/endpoints-valuations.md›
# A 股估值数据端点
> 批量查询 A 股最新估值快照。当前只提供最新快照，不提供历史估值、分页或客户端指标选择。
## 估值快照
```text
GET /api/a-share/valuations/snapshot
```
能力与 OpenAPI operationId：`get_a_share_valuations_snapshot`。
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 默认值 |
| --- | --- | --- | --- | --- | --- |
| `thscodes` | query | string | 是 | 英文逗号分隔的 A 股 `thscode` 列表；每项为 6 位数字加 `.SH`、`.SZ` 或 `.BJ`。原始 token 默认最多 100 个。 | — |
服务端先按原始 token 数量检查 100 个上限，再逐项去除首尾空白、转为大写并校验格式，最后去重且保留首次出现顺序。空 token、纯 6 位代码、非 A 股后缀或超过上限分别按既有 `1002` / `1003` 参数错误处理。
### 请求示例
```bash
curl 'https://fuyao.aicubes.cn/api/a-share/valuations/snapshot?thscodes=600519.SH,000001.SZ' \
-H 'X-api-key: <your-api-key>'
```
### 响应字段
`data` 为 `{timestamp, total, item[]}`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `timestamp` | long \| null | 返回行的固定五项指标中最新有效上游时间，毫秒 Unix 时间戳；无有效时间时为 `null`。 |
| `total` | integer | 实际返回的股票行数。 |
| `item` | array | 按规范化、去重后的请求顺序返回的股票估值行。 |
`item[]` 固定包含：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `thscode` | string | 完整 A 股 `thscode`。 |
| `ticker` | string | 6 位股票代码。 |
| `name` | string \| null | 股票名称。 |
| `pe_ttm` | number \| null | 市盈率 TTM。 |
| `pe_mrq` | number \| null | 市盈率 MRQ。 |
| `pb_mrq` | number \| null | 市净率 MRQ。 |
| `ps_ttm` | number \| null | 市销率 TTM。 |
| `pcf_ttm` | number \| null | 市现率 TTM。 |
五项估值指标允许为 `null` 或负数。`null` 表示上游没有有效值，负数可能反映亏损或负现金流；调用方不得自动补零、取绝对值或据此推断数据错误。
### 避错要点
- 先去重再判断上限：错误。上限按原始 token 计算，101 个重复代码仍然超限。
- 传指数代码或 `.TI` 板块：本端点只接受 A 股股票，不接受指数、板块或基金。
- 期待 `roe_ttm`、历史序列或自选指标：当前固定返回上述五项估值指标，不提供这些能力。
- 把 `timestamp` 当每一项指标自己的时间：它是本次返回中最新有效上游时间，不代表所有指标在该时点同时更新。
references/cli.md›
# hithink-finance CLI 入口
CLI 是人类终端、Agent 执行与自动化的推荐路径，统一远端数据、本地 DuckDB、认证、稳定 JSON 信封和大结果落盘。
## 先判断处于哪种状态
1. 检查 PATH 中是否存在 `hithink-finance`，存在时读取 `hithink-finance --version`。
2. 未安装、版本异常、需要配置认证、检查内置 Skills、诊断、升级或卸载时，读取 [安装、配置与生命周期](cli/setup.md)。
3. **已经安装且确定使用 CLI 完成金融任务时，不要把本入口当成功能契约。**先运行：
```bash
hithink-finance skills status --format json
hithink-finance capabilities --format json
```
`skills status` 的 `canonical` 只定位已安装包内的官方来源，不能证明当前 Agent 已发现 10 个 CLI 配套 Skill。先按 [安装、配置与生命周期](cli/setup.md) 核验当前 Agent 的 Skills 目录；通过后再读取 [CLI 内置 Skills 路由](cli/builtin-skills.md)，按用户意图打开对应 Skill。内置 Skill 与当前 CLI 版本同步，具有更准确的命令、参数、输出和本地数据指引。
4. 当前 Agent 缺少任一配套 Skill 时，先按 setup 契约运行 `hithink-finance skills sync` 并复查同一目录。同步无法覆盖该 Agent 时，Agent 必须从 `canonical` 主动复制缺失的完整官方 Skill 目录到当前 Agent 的 Skills 目录；只补缺失目录，不覆盖无关 Skills。仅在 Skills 路径未知或不可写时报告阻塞，不要把 `capabilities`、`schema <command-id>` 或 `<command> --help` 当成已安装 Skill 的替代证明。
## 长时间本地初始化
`data init` 的远端全量路径包含下载、导入和复权重建；下载完成不表示进程已完成或 DuckDB 已解锁。
- 使用前台、可等待全部子进程的执行器，超时不少于 15 分钟；不要让外层 shell 超时后遗留 `node.exe`。
- 只有退出码 0 且 JSON 信封 `ok=true` 后，才可对同一 `--db` 运行 `data status`、`market history`、`db query` 或其他本地命令。
- 若执行器超时或返回非 0，先检查锁文件/报错中的存活 PID。PID 仍存活时继续等待，不得在该 DB 上继续执行，也不得删除活锁；只有用户明确要求取消时才终止该进程。
## 功能简述
- `symbol`：标的搜索与代码表。
- `market`：行情、公司行为、交易日历和本地面板。
- `financials`：三张财务报表与财务指标。
- `valuation`：A 股最新估值快照。
- `index`：指数/板块目录、成分和行情。
- `special`：涨停、异动、热榜与龙虎榜。
- `data` / `db`：本地数据初始化、同步、校验、修复、查询与导出。
- `auth` / `skills` / `doctor` / `update` / `uninstall`：安装后配置和生命周期。
机器读取显式使用 `--format json`。成功条件是进程退出码 0 且信封 `ok=true`；不要按上游 `code=0` 解析 CLI 输出。只有具体命令声明的 `--output` 才能落盘，它不是全局选项。
references/cli/builtin-skills.md›
# CLI 内置 Skills 路由
当 `hithink-finance` 已安装且本次确定使用 CLI 时，先用 `hithink-finance skills status --format json` 找到官方 `canonical` 来源，再按 [安装、配置与生命周期](setup.md) 核验当前 Agent 的 Skills 目录中下列 Skills 可用，才读取与意图匹配的 Skill。`skills status` 不能证明当前 Agent 已发现这些目录。它们由 CLI 包发布和维护，是 CLI 命令契约的首选来源。
| 用户意图 | 读取的内置 Skill | 主要职责 |
| --- | --- | --- |
| 名称、ticker、代码消歧与代码表 | `hithink-finance-symbol` | `symbol search/list` |
| 行情、K 线、公司行为、交易日历、面板 | `hithink-finance-market` | `market *` 与远端/本地路由 |
| 利润表、资产负债表、现金流量表、指标 | `hithink-finance-financials` | `financials *` |
| A 股市盈率、市净率、市销率和市现率快照 | `hithink-finance-valuation` | `valuation *` |
| 指数/板块目录、成分与行情 | `hithink-finance-index` | `index *` |
| 涨停、异动、热榜、龙虎榜 | `hithink-finance-special-data` | `special *` |
| 基金资料、净值、收益、持仓、持有人、ETF/LOF 行情 | `hithink-finance-fund` | `fund *` |
| 建库、同步、状态、校验、修复、SQL、导出 | `hithink-finance-data` | `data *` 与 `db *` |
| 多步骤研究、口径组合与大结果工作流 | `hithink-finance-research` | 跨领域研究编排 |
| 认证、全局规则、Skills 与生命周期 | `hithink-finance-shared` | `auth/skills/doctor/update/uninstall` |
## 读取规则
- 单一领域只读一个领域 Skill；跨领域研究再增加 `hithink-finance-research`。
- 认证、输出信封、生命周期或共用配置问题读取 `hithink-finance-shared`。
- 内置 Skill 与运行时帮助冲突时，用 `hithink-finance capabilities --format json`、`schema <command-id>` 和具体命令 `--help` 校验当前安装。
- 未安装或状态异常时返回 [安装、配置与生命周期](setup.md) 修复，不使用本入口复制旧命令契约。
references/cli/setup.md›
# CLI 安装、配置与生命周期
本页只处理 CLI 是否可用、是否为合适版本、认证、内置 Skills、最小验证和卸载。安装完成后的金融功能必须转到 CLI 内置 Skills。
## 1. 安装状态与运行要求
先检查，不改变环境：
```bash
hithink-finance --version
hithink-finance version --format json
node --version
npm --version
```
- 命令存在且能返回版本：继续检查版本、认证和 Skills。
- 命令不存在：要求 Node.js `>=22.12.0` 与可用 npm。
- 不要仅凭目录存在判断全局命令已安装；应以 PATH 中可执行命令为准。
## 2. 版本检查
```bash
hithink-finance update --check --format json
npm view @hithink-tech/hithink-finance-cli version
```
`update --check` 用于比较当前安装和可用版本，不执行升级。版本正常时不要重装。需要修复或升级时先向用户说明将修改全局 npm 安装，得到授权后再使用 `hithink-finance update --repair` 或指定 `--target-version`。
## 3. 从 npm 安装
首选 npm，不默认使用源码安装：
```bash
npm install -g @hithink-tech/hithink-finance-cli
hithink-finance --version
```
用户明确选择其他接入方式时不安装 CLI。用户直接提出金融任务、未指定方式且 CLI 不存在时，先简短告知“将安装官方 CLI 并继续完成任务”，随后执行安装；平台需要授权时遵循平台授权机制，不再追加一次相同确认。遇到 `EACCES`、PATH 或 registry 问题时报告原始错误并回退到已有 MCP、REST 或 Python 路径；遇到 `E404` 时检查 registry 与包发布状态，不擅自切换未知来源。
## 4. 统一凭据
API Key 在 <https://fuyao.aicubes.cn/admin> 获取。CLI 不是统一凭据的前置条件；先检查 `HITHINK_FINANCE_API_KEY`，再检查用户级凭据文件：
| 平台 | 用户级凭据文件 |
| --- | --- |
| Windows | `%APPDATA%\hithink-finance\credentials.env` |
| macOS | `~/Library/Application Support/hithink-finance/credentials.env` |
| Linux | `${XDG_CONFIG_HOME:-~/.config}/hithink-finance/credentials.env` |
文件只写一行 `HITHINK_FINANCE_API_KEY=...`，等号右侧直接填写原始 Key，不加单引号或双引号；不放在项目目录。Unix 权限设为 `0600`；Windows 仅允许当前用户访问。
需要自行配置当前用户的持久环境变量时，按当前平台使用隐藏输入。Windows PowerShell：
```powershell
$secureKey = Read-Host 'API Key' -AsSecureString
$key = [System.Net.NetworkCredential]::new('', $secureKey).Password
[Environment]::SetEnvironmentVariable('HITHINK_FINANCE_API_KEY', $key, 'User')
$env:HITHINK_FINANCE_API_KEY = $key
Remove-Variable key, secureKey
```
macOS 默认 zsh：
```zsh
read -s 'HITHINK_FINANCE_API_KEY?API Key: '; echo
export HITHINK_FINANCE_API_KEY
printf '\nexport HITHINK_FINANCE_API_KEY=%q\n' "$HITHINK_FINANCE_API_KEY" >> ~/.zshenv
chmod 600 ~/.zshenv
```
Linux Bash：
```bash
read -rsp 'API Key: ' HITHINK_FINANCE_API_KEY; echo
export HITHINK_FINANCE_API_KEY
printf '\nexport HITHINK_FINANCE_API_KEY=%q\n' "$HITHINK_FINANCE_API_KEY" >> ~/.bashrc
chmod 600 ~/.bashrc
```
也可以直接发给我，由 Agent 使用 stdin、进程环境或受限凭据文件完成配置。Agent 不复述 Key，不把它放进命令参数、日志、项目文件或 Git。聊天平台可能保留消息记录，因此隐藏输入或环境变量方式更安全。
## 5. CLI 无感登录
先读取 CLI 自身状态：
```bash
hithink-finance auth status --format json
```
统一凭据已经存在而 CLI 尚未登录时，不再次询问用户；将统一凭据只通过 stdin 传给 CLI：
```bash
printf '%s' "$HITHINK_FINANCE_API_KEY" | \
hithink-finance auth login --api-key-stdin --format json
```
统一凭据刚更新且 CLI 已登录时，原子替换系统凭据，不先 logout：
```bash
printf '%s' "$HITHINK_FINANCE_API_KEY" | \
hithink-finance auth login --api-key-stdin --replace --format json
```
凭据来自用户级文件时，Agent 在进程内读取后直接写入 CLI stdin，不经 stdout 或命令参数。同步只发生在 CLI 安装完成、统一凭据新增/更新或认证恢复时，普通调用不重复写入系统凭据。
CLI 独立使用时仍可运行隐藏输入：
```bash
hithink-finance auth login
```
登录后再次运行 `auth status`，并做一个有界真实请求。验证 CLI 系统凭据能独立工作时，不向该验证子进程注入 `HITHINK_FINANCE_API_KEY`，避免环境变量掩盖系统凭据失败。
系统凭据库不可用时，不再次索取 Key；当前任务可向 CLI 子进程注入统一环境变量继续，或回退到其他接入方式，同时说明 CLI 独立登录尚未持久化。退出认证可用 `hithink-finance auth logout`，执行前确认清理范围。
## 6. CLI 内置 Skills 检查
```bash
hithink-finance skills status --format json
```
输出中的 `canonical` 是随 CLI 发布的官方 Skills 来源；它不能证明当前 Agent 已发现 10 个 CLI 配套 Skill。确定使用 CLI 后，Agent 必须先从自身运行时配置定位**当前 Agent 的 Skills 目录**，并检查下列每个目录都存在且含有 `SKILL.md`：`hithink-finance-shared`、`hithink-finance-symbol`、`hithink-finance-market`、`hithink-finance-financials`、`hithink-finance-valuation`、`hithink-finance-index`、`hithink-finance-special-data`、`hithink-finance-fund`、`hithink-finance-data`、`hithink-finance-research`。
任何目录缺失时，先执行：
```bash
hithink-finance skills sync --format json
```
随后必须对同一个当前 Agent 的 Skills 目录复查，而不是把同步命令的退出码当成安装证明。`skills sync` 可能没有当前 Agent 的发现目录或无法覆盖该工具；若 `canonical/<skill-name>/SKILL.md` 存在、当前 Agent 的 Skills 目录已知且可写，Agent 必须主动复制每个缺失 Skill 的完整目录（含 `references/`）到当前 Agent 的目录。只复制缺失的官方目录，不覆盖无关 Skills，也不向项目目录、其他 Agent 目录或未知路径写入。已存在但被用户修改的同名目录不做手工覆盖；先用 `hithink-finance skills sync --repair --format json`，仍无法确认时报告冲突和路径。复制后再次逐目录核验，并在 Agent 需要时新建会话以重新发现。
完整领域路由见 [内置 Skills 路由](builtin-skills.md)。
## 7. 配置与最小验证
先做离线诊断：
```bash
hithink-finance doctor --format json
hithink-finance capabilities --format json
```
再做一个有界的线上最小验证：
```bash
hithink-finance symbol search --q 600519 --limit 1 --format json
```
只有退出码 0、信封 `ok=true` 且返回真实结果，才能说明当前认证和远端访问可用。`doctor`、help 或离线 schema 通过不能代替线上验证。
## 8. 安装后建议
1. 运行 `hithink-finance skills status --format json`；核验当前 Agent 的 Skills 目录，必要时同步并主动复制缺失 Skills。
2. 新建 Agent 会话，让新安装的内置 Skills 被重新发现。
3. 在新会话直接描述需求，或快速开始：
```bash
hithink-finance symbol search --q "贵州茅台" --limit 5 --format json
hithink-finance market snapshot --thscodes 600519.SH --format json
hithink-finance data status --format json
```
4. 选定功能后读取对应 CLI 内置 Skill，而不是继续依赖本 setup 页猜命令。
## 9. 卸载
先预览，不修改任何内容：
```bash
hithink-finance uninstall --plan --format json
```
确认计划后，默认卸载 CLI 与其管理的 Skills：
```bash
hithink-finance uninstall --yes --format json
```
`--purge-data`、`--purge-config` 和 `--purge-credentials` 会额外删除用户数据、配置或凭据，只能在用户明确指定对应范围后添加。不要用手工递归删除替代内置卸载流程。
references/mcp.md›
# MCP 接入与 Agent 路由契约
同花顺金融数据服务提供 4 个托管 MCP 端点，适合 Claude Desktop、Cursor、Windsurf 等支持 HTTP MCP 的 Chat/Agent 客户端。四个端点共用在 <https://fuyao.aicubes.cn/admin> 获取的 API Key，无需在本地运行 MCP Server。
本页既是项目中的 MCP 主入口，也是 `hithink-finance` Skill 的内置入口契约。详细能力快照位于 [`docs/mcp/`](mcp/capability-map.md)，由脚本完整镜像到 Skill，Agent 不需要为了理解能力而加载官网长文档。
## 四个服务
| 客户端服务名 | 地址 | 职责 | 工具数 |
| --- | --- | --- | ---: |
| `hithink-finance-a-share` | `https://fuyao.aicubes.cn/mcp/a-share` | A 股行情、公司行为、财务、估值、集合竞价、日历和特色数据 | 21 |
| `hithink-finance-a-share-index` | `https://fuyao.aicubes.cn/mcp/a-share-index` | 指数/板块目录、成分和行情 | 4 |
| `hithink-finance-meta` | `https://fuyao.aicubes.cn/mcp/meta` | 标的搜索、名称消歧和代码表 | 2 |
| `hithink-finance-fund` | `https://fuyao.aicubes.cn/mcp/fund` | 基金资料、经理、披露、财务、净值、收益、资讯和场内行情 | 28 |
`hithink-finance-*` 是推荐写入客户端配置的本地服务名；URL 路径保持不变。
## 默认配置
不同客户端的配置文件位置和 Secret 插值语法不同。下面给出通用 HTTP MCP 结构，默认一次配置全部四个端点，之后由 Agent 按意图只调用需要的服务：
```json
{
"mcpServers": {
"hithink-finance-a-share": {
"type": "http",
"url": "https://fuyao.aicubes.cn/mcp/a-share",
"headers": { "X-api-key": "${HITHINK_FINANCE_API_KEY}" }
},
"hithink-finance-a-share-index": {
"type": "http",
"url": "https://fuyao.aicubes.cn/mcp/a-share-index",
"headers": { "X-api-key": "${HITHINK_FINANCE_API_KEY}" }
},
"hithink-finance-meta": {
"type": "http",
"url": "https://fuyao.aicubes.cn/mcp/meta",
"headers": { "X-api-key": "${HITHINK_FINANCE_API_KEY}" }
},
"hithink-finance-fund": {
"type": "http",
"url": "https://fuyao.aicubes.cn/mcp/fund",
"headers": { "X-api-key": "${HITHINK_FINANCE_API_KEY}" }
}
}
}
```
`HITHINK_FINANCE_API_KEY` 是 REST、MCP、CLI 和 Python 共用的推荐变量。若客户端不继承用户级环境变量，由 Agent 从已经配置的统一凭据来源写入客户端 Secret，不要求用户重新提供；若客户端不支持环境变量插值，应使用它提供的 Secret/凭据功能。不得把真实 Key 写入仓库、Prompt、Issue、日志或可共享配置。
## Agent 决策流程
1. **先理解意图**：用 [能力与意图总览](mcp/capability-map.md) 选择服务和工具，不要先把四个服务全部探测一遍。
2. **先消歧再取数**：用户只给名称、ticker 或不完整代码时，先调用 `hithink-finance-meta` 的搜索工具确认唯一 `thscode`。
3. **只读取相关快照**：确定服务后，只加载对应的一份详细契约：
- [A 股工具](mcp/hithink-finance-a-share.md)
- [指数与板块工具](mcp/hithink-finance-a-share-index.md)
- [标的元数据工具](mcp/hithink-finance-meta.md)
- [基金工具](mcp/hithink-finance-fund.md)
4. **按需检查连接**：只有准备使用某个服务，或用户明确要求诊断连接时，才检查该服务是否连接并读取当前 `tools/list`。
5. **执行最小调用**：认证检查也使用目标任务所需的最小有界请求，禁止用省略标的的全市场快照做探针。
6. **控制结果规模**：分页全集、全市场、长时间序列或大量成分股必须落盘，只返回路径、行数和必要摘要。
Skill 中的能力快照用于意图识别、工具选择和参数避错；当前连接的 `tools/list` 只用于确认工具是否实际存在，以及调用时的参数名、类型、必填项和枚举是否发生变化。不要在每次请求前重复读取所有 schema。
## 认证与恢复
- 所有服务使用请求头 `X-api-key`。
- 业务成功条件是响应信封 `code=0`，不能只看 HTTP 200。
- `code=2003`、`Invalid or revoked API key`、401 或 403 通常表示 Key 缺失、无效、已撤销或客户端没有正确传递请求头。
- 认证失败时，先重新检查 `HITHINK_FINANCE_API_KEY` 和 Skill 的用户级凭据文件。仍未配置时，引导用户前往 <https://fuyao.aicubes.cn/admin> 创建 Key，并说明既可以按平台命令配置，也可以交给 Agent 代为安全配置；不得强制用户在对话中粘贴，也不得复述收到的 Key。
- 更新配置后通常需要重启或重连 MCP 客户端，再对目标服务执行一次最小验证。
## 能力边界
- 当前固化快照共 55 个 MCP 工具：A 股 21 个、指数 4 个、元数据 2 个、基金 28 个。
- MCP 适合 Chat 场景和自然语言调用；终端自动化、本地 DuckDB 与大结果工作流优先考虑 `hithink-finance` CLI。
- 当前快照不覆盖分钟 K、tick、Level-2、港股、美股、基金申赎交易、期货、研报或回测引擎；基金资讯仅提供已公开文章的元数据列表。
- 文档或静态快照不能证明当前会话已经连接，也不能证明账号具有相应权限；只有实际授权请求才能完成线上验证。
- 未支持能力必须明确说明，不得用近似数据、静态示例或模拟数据冒充。
references/mcp/capability-map.md›
# MCP 能力与意图总览
本页是同花顺金融数据服务 4 个 MCP 端点、55 个工具的固化功能契约，用于 Agent 的意图识别和工具路由。当前连接的 `tools/list` 用于确认实际可用性与调用 schema，不应取代本页的任务语义。
## 先选服务
| 用户目标 | 服务 | 工具选择 |
| --- | --- | --- |
| 名称、代码或 `thscode` 消歧 | `hithink-finance-meta` | `get_meta_tickers_search` |
| 批量获取 A 股或指数代码表 | `hithink-finance-meta` | `get_meta_tickers_list`，按分页迭代 |
| A 股最新行情或历史 K 线 | `hithink-finance-a-share` | `get_a_share_prices_snapshot` / `get_a_share_prices_historical` |
| 分红、送股、配股等复权事件 | `hithink-finance-a-share` | `get_a_share_corporate_actions_adjustment_factors` |
| 利润表、资产负债表、现金流量表 | `hithink-finance-a-share` | 对应 `get_a_share_financials_*` 工具 |
| 指定报告期的财务指标 | `hithink-finance-a-share` | `get_a_share_financials_indicators` |
| 批量查询 A 股最新估值快照 | `hithink-finance-a-share` | `get_a_share_valuations_snapshot` |
| 交易日历 | `hithink-finance-a-share` | `get_a_share_calendar_trading_days` |
| 集合竞价快照或短期基准 | `hithink-finance-a-share` | `get_a_share_auction_snapshot` / `get_a_share_auction_short_term_benchmark` |
| 涨停池、跌停池、炸板池、连板、个股异动、热榜、龙虎榜 | `hithink-finance-a-share` | 对应 `get_a_share_special_data_*` 工具 |
| 查找概念、区域、特色或行业指数 | `hithink-finance-a-share-index` | `get_a_share_index_catalog_ths_index_list` |
| 查询指数或板块成分股 | `hithink-finance-a-share-index` | `get_a_share_index_constituents_ths_stock_list` |
| 指数/板块最新行情或历史 K 线 | `hithink-finance-a-share-index` | `get_a_share_index_prices_snapshot` / `get_a_share_index_prices_historical` |
| 基金资料、公司、经理、披露、财务、净值、收益、诊断或持有人结构 | `hithink-finance-fund` | 对应 `get_fund_*` 工具 |
| 基金公开资讯、发行状态或历史持仓 | `hithink-finance-fund` | 对应 `get_fund_news_*`、`get_fund_offerings_*` 或 `get_fund_portfolio_*` 工具 |
| ETF/LOF 实时行情 | `hithink-finance-fund` | `get_fund_market_snapshot` |
| ETF 历史日线 | `hithink-finance-fund` | `get_fund_market_historical` |
## 常见组合流程
### 名称到数据
1. 用 `get_meta_tickers_search` 将名称消歧为唯一 `thscode`。
2. 根据 `asset_type` 选择 A 股或指数服务。
3. 调用对应行情、财务、估值或特色数据工具。
### 基金名称到数据
1. 用 `get_meta_tickers_search` 查询名称，可传 `asset_type=fund-otc,fund-etf,fund-lof,fund-reits`。
2. 根据唯一结果把 `fund-*` 叶子类型映射到 `fund_type=otc/exchange/reits`。
3. 资料/披露/净值/收益/持有人走基金业务工具；ETF/LOF 快照走 `get_fund_market_snapshot`，ETF 日线走 `get_fund_market_historical`。
### 概念板块到成分股行情
1. 用 `get_a_share_index_catalog_ths_index_list` 按 tag 找板块代码。
2. 用 `get_a_share_index_constituents_ths_stock_list` 取当前成分股。
3. 仅对用户需要的有限成分调用 A 股行情；全量结果落盘，不写入对话。
### 财务与行情联合分析
1. 用三张报表或财务指标工具获取指定报告期数据。
2. 用 A 股行情工具获取明确时间窗口的数据。
3. 明确报告期、行情日期、复权口径和数据时间，避免把不同口径直接比较。
## 按需连接检查
- 不要在任务开始时对四个服务执行全量连接探测。
- 仅检查意图命中的服务；若名称尚未消歧，先检查 `hithink-finance-meta`。
- `tools/list` 只需在首次调用、连接诊断或参数错误后读取，不要每次重复加载完整 schema。
- 遇到 `code=2003` 或 `Invalid or revoked API key`，按主入口的认证恢复流程处理，不要改用模拟数据。
## 参数语义提醒
- `thscode` 通常包含交易所或指数后缀；股票、标准指数和 `.TI` 板块的可用工具不同。
- 毫秒时间戳与 `YYYY-MM-DD` 字符串不可互换，按对应工具契约传参。
- `limit/offset` 与 `page/size` 是不同分页模型，不要混用。
- 工具名相似时先确认资产类别、是否支持批量、是否允许省略代码以及时间窗口上限。
## 能力边界
- 当前快照覆盖 A 股、A 股指数/板块和公募基金资料、经理、披露、财务、净值、收益与公开资讯；场内行情覆盖 ETF/LOF 快照与 ETF 日线。
- 不覆盖分钟 K、tick、Level-2、港股、美股、基金申赎交易或期货。
- 财务指标工具不返回行业、评分、排名、行业均值或点评。
- 工具提供数据，不提供回测引擎、alpha 模型或确定性投资建议。
- 若当前 `tools/list` 出现本快照未登记的新工具，可报告潜在版本差异；在契约更新前不要猜测其业务语义。
references/mcp/hithink-finance-a-share-index.md›
# hithink-finance-a-share-index 工具契约
用于指数和板块的工具选型。实际调用参数以当前连接的 schema 校验结果为准。
## 工具全览
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_a_share_index_catalog_ths_index_list` | 按类别列出同花顺概念、区域、特色或行业指数 | `tag` 为 `cn_concept`/`region`/`tszs`/`industry`；单个 tag 全量返回、无分页 | 把标准指数名称搜索完全依赖此目录；忽略返回可能较大 |
| `get_a_share_index_constituents_ths_stock_list` | 查询单个 THS 板块或标准指数的当前成分股 | 单次一个 `thscode`；支持如 `886042.TI`、`000300.SH` | 逗号分隔多个指数，或把结果当历史成分 |
| `get_a_share_index_prices_snapshot` | 批量查询有限数量指数/板块最新行情 | `thscodes` 必填；支持 `.SH/.SZ/.TI`；不支持省略代码枚举全集 | 误以为 `limit/offset` 可拉全量指数，或把股票代码交给指数工具 |
| `get_a_share_index_prices_historical` | 单只指数/板块历史日 K 线 | `start/end` 为毫秒时间戳；窗口最长 10 年；`interval` 固定 `1d`；指数无复权 | 传 `adjust`，或一次传多个指数 |
## 典型流程
### 找概念板块并查询成分
1. 按正确 `tag` 获取目录并把完整目录落盘。
2. 根据名称选择唯一板块 `thscode`，不要仅靠模糊字符串猜代码。
3. 查询当前成分；需要行情时，将有限股票代码交给 A 股快照工具。
### 标准指数查询
已知沪深 300 等标准 `thscode` 时可直接查成分或行情；名称不确定时先使用元数据搜索交叉确认。
## 能力边界
- 成分工具返回当前成分，不提供历史调入调出序列。
- 指数历史 K 线没有复权概念，响应中的 adjust 为空不代表数据缺失。
- 目录工具单 tag 全量返回，应落盘或只保留目标匹配项，不要把完整目录写入会话。
references/mcp/hithink-finance-a-share.md›
# hithink-finance-a-share 工具契约
用于 A 股行情、公司行为、财务、估值、交易日历和特色数据的选型与避错。历史研究若本地 `marketdb` 已覆盖，应优先使用本地数据，不要为相同历史窗口重复调用远端 MCP。
## 行情与公司行为
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_a_share_prices_snapshot` | 单只或有限多只 A 股最新快照 | `thscodes` 为逗号分隔列表；省略时才使用 `limit/offset` 遍历全市场 | 认证探测时省略 `thscodes`，意外拉取全市场 |
| `get_a_share_prices_historical` | 单只 A 股日 K 线 | 单次一个 `thscode`；`start/end` 为毫秒时间戳；窗口最长 10 年；`adjust` 为 `none/forward/backward`；当前仅支持 `interval=1d` | 一次传多只股票，或误用其他周期枚举 |
| `get_a_share_corporate_actions_adjustment_factors` | 获取现金分红、送股、配股事件，供调用方推导复权因子 | 单次一个 `thscode`；`from/to` 使用 `YYYY-MM-DD` | 将事件流误当作服务端已计算好的每日复权因子 |
## 财务数据
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_a_share_financials_income_statements` | 整体合并利润表多期序列 | 单只股票；`period` 为 `annual/quarterly`；最近 N 期模式与 `start+end` 区间模式互斥 | 同时传 `limit` 和时间区间，或只传 start/end 之一 |
| `get_a_share_financials_balance_sheets` | 整体合并资产负债表多期序列 | 与利润表相同；最近期数通常 1–20，区间最长 10 年 | 把报告期模式理解为自然月数据 |
| `get_a_share_financials_cash_flow_statements` | 整体合并现金流量表多期序列 | 与利润表相同 | 未对齐不同报表的报告期就直接拼接 |
| `get_a_share_financials_indicators` | 指定报告期的成长、盈利、偿债、营运和现金流指标 | `report` 格式 `yyyy-{1|2|3|4}`；`abilities` 为数组，每项含 `ability` 与 `indicators` | 期待行业均值、评分、排名或点评；把日期当 report；把 `abilities` 当 object |
三张报表的时间区间使用毫秒时间戳；财务指标使用专用报告期字符串，不可互换。
## 估值数据
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_a_share_valuations_snapshot` | 批量查询 A 股最新估值快照 | `thscodes` 必填、英文逗号分隔，原始 token 默认最多 100 个；去重保序；固定返回 `pe_ttm`、`pe_mrq`、`pb_mrq`、`ps_ttm`、`pcf_ttm` | 查询历史估值、传指数/板块/基金代码、期待 `roe_ttm`、把 `null` 或负数改写为零 |
## 日历
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_a_share_calendar_trading_days` | 判断最近一年 A 股交易日 | 无参数，固定为 Asia/Shanghai 今日向前一年 | 用它查询任意十年日历，或把非交易日空数据当服务故障 |
## 集合竞价
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_a_share_auction_snapshot` | 批量查询集合竞价快照 | `thscodes` 必填且最多 100 个；`stage=live/final`，默认 `final`；`timestamp` 是响应组装时间，上游行情时间仅用于判断新鲜度 | 把 `timestamp` 当上游竞价发生时间，或省略标的拉全市场 |
| `get_a_share_auction_short_term_benchmark` | 查询集合竞价短期强弱基准 | `date` 可选且为 `YYYY-MM-DD`，缺失或空字符串时使用 `Asia/Shanghai` 当日；返回 `timestamp/date/date_ms/item` | 用毫秒戳传日期、期待非交易日自动回退，或把基准榜直接当投资建议 |
## 涨停与连板
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_a_share_special_data_limit_up_pool` | 指定交易日的全市场涨停股清单 | `date_ms` 为上海时区自然日零点毫秒戳；`page/size` 分页；排序字段有白名单 | 在非交易日期待报错；混用 `limit/offset` |
| `get_a_share_special_data_limit_down_pool` | 指定交易日的全市场跌停股清单 | `date_ms` 可选；`page>=1`、`size=1..200`；可按 `first_limit_time/last_limit_time/turnover_ratio_pct` 排序 | 把 `last_limit_time` 当毫秒戳，或混用 `limit/offset` |
| `get_a_share_special_data_limit_break_pool` | 指定交易日的全市场炸板股清单 | `date_ms` 可选；`page>=1`、`size=1..200`；返回 `open_times` 等字段 | 把开板次数当连续涨停数，或忽略分页 |
| `get_a_share_special_data_limit_up_ladder` | 观察近 30 个交易日、2/3/4/5/6/7+ 板梯队 | 无参数，返回固定窗口矩阵 | 期待逐股明细或自定义时间窗口 |
## 异动与热榜
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_a_share_special_data_anomaly_analysis_stock` | 批量查询当日个股异动原因 | `thscodes` 必填、逗号分隔、仅股票；去重后数量受服务端上限约束 | 查询历史异动、传指数代码或超量标的 |
| `get_a_share_special_data_skyrocket_list` | A 股飙升榜 | `period` 为 `day/hour`，缺省 day；条目含代码、名称、排名、热度和排名趋势等 7 个字段 | 把榜单排名当作无延迟交易信号，或虚构分析字段 |
| `get_a_share_special_data_hot_stock_list` | 当前热股榜 | `period` 为 `day/hour`；day 表示 24 小时榜；字段与飙升榜一致 | 与飙升榜混淆，或忽略数据时间 |
| `get_a_share_special_data_hot_stock_list_history` | 指定自然日的历史热股排名 | `date` 必填，格式 `YYYY-MM-DD` | 用毫秒时间戳传 date，或期待区间走势 |
| `get_a_share_special_data_hot_stock_rank_trend` | 单只股票在日期区间内的热榜排名走势 | 单个 `thscode`；`start_date/end_date` 为 `YYYY-MM-DD` | 一次传多只股票，或把无排名日期误作接口缺失 |
## 龙虎榜
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_a_share_special_data_dragon_tiger_list` | 查询全部榜、机构榜或游资榜 | `board_type` 为 `all/org/hot_money`；`date` 可选且为 `YYYY-MM-DD` | 假设省略 date 一定等于今天；服务端取最新可用日期 |
## 选型检查
- 名称未消歧：先用 `hithink-finance-meta`。
- 代码是指数或 `.TI`：改用 `hithink-finance-a-share-index`。
- 需要分钟 K、tick 或连续多年批量研究：当前 MCP 契约不覆盖；优先评估本地数据库或 REST 导出能力。
- 工具报参数错误：读取当前目标服务的 `tools/list` 后修正，不要全量探测其他服务。
references/mcp/hithink-finance-fund.md›
# hithink-finance-fund 工具契约
用于公募基金资料、公司、经理、披露数据、财务、净值、收益、公开资讯和场内基金行情。服务地址为 `https://fuyao.aicubes.cn/mcp/fund`。名称或代码未消歧时，先调用 `hithink-finance-meta`，根据 `asset_type` 选择基金类型和能力。
## 工具
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_fund_profile_detail` | 查询基金基本资料 | `fund_type=otc/exchange/reits`；单个 `thscode` | 根据代码后缀猜类型，或把可空资料补写为确定值 |
| `get_fund_portfolio_holdings` | 查询定期披露重仓股 | `fund_type` + 单个 `thscode`；`hold_ratio` 是百分数值 | 把披露持仓当实时组合，或把 8.88 解释为 0.0888% |
| `get_fund_performance_nav` | 查询最新或固定区间净值 | `range=week/month/tmonth/hyear/year/twoyear/tyear/fyear`；`nav_type=unit/adj/unit,adj`，默认二者 | 把 range 当自定义日期；忽略未选择字段会被省略 |
| `get_fund_performance_returns` | 查询固定区间收益 | `fund_type` + 单个 `thscode`；返回月/季/半年/年/三年/五年/今年/成立以来 | 把固定区间字段当任意起止日期收益 |
| `get_fund_holders_detail` | 查询持有人结构 | `fund_type` + 单个 `thscode`；`merge_scope=all/merged/separate`，默认 `all`；返回实际口径与报告日 | 把持有人结构当实时账户统计，或把 `all` 误当作实际记录口径 |
| `get_fund_market_snapshot` | 查询 ETF/LOF 场内快照 | 单个 `thscode`；不接收 `fund_type` | 对场外基金或 REITs 重试 `3004` |
| `get_fund_market_historical` | 查询 ETF 历史日线 | 单个 ETF；`interval=1d`；`start/end` 为毫秒戳；最多 5 年；无 `adjust` | 传 LOF、复权参数、批量代码或超过 5 年窗口 |
| `get_fund_companies_detail` | 查询基金公司详情 | `company_id` 必填 | 用基金代码代替公司 ID |
| `get_fund_portfolio_industry_allocation` | 查询基金行业配置 | `fund_type` + 单个 `thscode` | 把定期披露占比当实时配置 |
| `get_fund_performance_indicators_historical` | 查询日期区间内历史业绩指标 | `start`/`end` 必填且最多 5 年；固定周期 `DAY_1`，data 仅含 timestamp/item，不返回顶层 thscode/interval | 只传一个边界、查询超长窗口或期待固定请求上下文字段回显 |
| `get_fund_performance_drawdowns` | 查询主要回撤区间 | `fund_type` + 单个 `thscode` | 把历史回撤解释为未来风险承诺 |
| `get_fund_holders_top` | 查询前十大持有人 | `limit` 可选且不超过 10 | 请求完整账户明细 |
| `get_fund_corporate_actions_dividends` | 查询基金分红记录 | `fund_type` + 单个 `thscode` | 把累计分红当总收益 |
| `get_fund_diagnostics_detail` | 查询基金诊断详情 | `fund_type` + 单个 `thscode`；含 `radar_comparison` | 将诊断字段改写为买卖建议 |
| `get_fund_financials_indicators` | 查询基金财务指标 | `fund_type` + 单个 `thscode` | 与 A 股财务指标混用 |
| `get_fund_financials_income_statements` | 查询基金利润表 | `fund_type` + 单个 `thscode` | 期待公司主营业务字段 |
| `get_fund_financials_balance_sheets` | 查询基金资产负债表 | `fund_type` + 单个 `thscode` | 把可空披露值补零 |
| `get_fund_managers_investment_style` | 查询基金经理投资风格 | `manager_id` 必填 | 用基金代码代替经理 ID |
| `get_fund_managers_performance` | 查询基金经理区间业绩 | `manager_id`；`range=month/tmonth/year/nowyear/now` | 把 range 当自定义日期 |
| `get_fund_managers_experience` | 查询基金经理任职经历 | `manager_id` 必填 | 把历史任职产品当当前在管 |
| `get_fund_managers_detail` | 查询基金经理详情 | `manager_id` 必填 | 根据姓名猜测不唯一的 ID |
| `get_fund_news_article_list` | 查询基金公开资讯元数据列表 | `limit=1..100`；`offset` 是不透明游标；不返回 total，按 `has_more=false` 结束分页 | 期待正文、读取不存在的总数或自行拼接游标 |
| `get_fund_offerings_list` | 查询在售或待售基金 | `subscribe=active/upcoming` | 把发行状态当可直接交易 |
| `get_fund_portfolio_stock_history` | 查询指定报告期股票持仓 | `report_type` 与 `end_date` 必填 | 把历史披露当实时持仓 |
| `get_fund_portfolio_stock_report_dates` | 查询股票持仓可用报告期 | `report_type` 可选 | 猜测不存在的报告期 |
| `get_fund_portfolio_bond_history` | 查询指定报告期债券持仓 | `report_type` 与 `end_date` 必填 | 与股票持仓字段混用 |
| `get_fund_portfolio_bond_report_dates` | 查询债券持仓可用报告期 | `report_type` 可选 | 猜测不存在的报告期 |
| `get_fund_portfolio_asset_allocation` | 查询大类资产配置 | `fund_type` + 单个 `thscode` | 把定期披露占比当实时仓位 |
## 参数与错误语义
- `fund_type` 与 `thscode` 共同定位基金；`fund_type` 不支持逗号分隔多值。
- `get_fund_holders_detail` 的 `merge_scope=all` 最多返回 `merged`、`separate` 各一条最新披露记录；每条记录的 `merge_scope` 是实际口径，`report_date_ms` 是该条报告日，顶层 `timestamp` 取返回记录中的最新报告日（均为毫秒戳）。
- `market/snapshot` 支持 ETF 与 LOF，`market/historical` 当前只支持 ETF。
- `3001` 表示基金未找到；回到 meta 搜索核对 `asset_type` 和 `thscode`。
- `3002` 表示数据尚未准备；保留 `request_id`，不要补零或使用模拟数据。
- `3004` 表示目标基金类型不支持该能力；改选适用工具，不重试原参数。
## Agent 选型
1. 名称、纯 ticker 或不确定代码先用 `get_meta_tickers_search`；可用 `asset_type=fund-otc,fund-etf,fund-lof,fund-reits` 缩小范围。
2. 用户问资料、经理、披露、财务、净值、收益、诊断、持有人或公开资讯时，根据搜索结果或已知 ID 选择对应工具。
3. 用户问交易所价格时，ETF/LOF 用 snapshot；只有 ETF 能用 historical。
4. 长结果或多基金循环必须落盘，只摘要路径、数量、窗口和口径。
## 边界
- 不提供基金申购、赎回、交易执行、基金推荐或收益承诺；资讯工具只返回公开文章元数据列表。
- 工具契约不等于当前会话已连接；首次调用或参数错误后读取该服务的 `tools/list`。
references/mcp/hithink-finance-meta.md›
# hithink-finance-meta 工具契约
用于标的消歧和代码表获取。实际调用前可用当前连接的 `tools/list` 确认参数 schema；无需重复加载其他服务。
## 工具全览
| 工具 | 适用场景 | 关键参数与边界 | 常见错误 |
| --- | --- | --- | --- |
| `get_meta_tickers_search` | 按完整 `thscode`、ticker、中文名或英文名做跨市场检索与消歧 | `q` 必填；可按 `asset_type`、`exchange` 缩小范围；`limit` 通常不超过 50 | 看到首条模糊匹配就调用业务工具，或凭名称猜交易所后缀 |
| `get_meta_tickers_list` | 批量获取 A 股或指数代码表 | 按 `asset_type`、交易所过滤；使用 `limit/offset` 分页，直到本页数量小于 limit | 一次把完整代码表写入上下文，或忘记递增 offset |
## 消歧规则
1. 用户给完整 `thscode` 时仍可用精确搜索确认资产类别，尤其要区分股票、标准指数和 `.TI` 板块。
2. 用户给 ticker、简称或名称时，结合 `asset_type`、`exchange` 和返回名称筛选唯一结果。
3. 多个结果仍可能成立时，把候选代码、名称和资产类别简要列出，请用户确认；不要自行选择。
4. 消歧后只把必要的 `thscode` 交给业务工具，不传播整份搜索响应。
## 代码表分页
- 完整代码表属于大结果，应写入文件供后续程序读取，只报告文件路径和行数。
- 终止条件是当前页 `item` 数量小于 `limit`；空页也表示结束。
- 需要多个交易所时，先确认实时 schema 是否接受逗号分隔值。
## 能力边界
- 元数据工具负责发现和消歧，不提供行情、财务或指数成分。
- 子串匹配可能返回同名或相近标的；结果非唯一时必须保留歧义。
- 当前契约只列 A 股与 A 股指数资产类别；出现新枚举时先确认当前 `tools/list`，不要自行推断语义。
references/python-sdk.md›
# Python SDK 入口
Python 路径适合 Notebook、Python 应用、研究脚本和已经使用 `marketdb` 的项目。先按需求二选一，只加载一份子契约：
| 需求 | 路径 | 详细契约 |
| --- | --- | --- |
| 最新行情、集合竞价、财报、估值、指数、公募基金、特色数据和自定义远端取数 | Fuyao Python toolkit | [remote-toolkit.md](python-sdk/remote-toolkit.md) |
| 本地历史 OHLCV、复权、面板、SQL 和研究数据集 | marketdb CLI/Python SDK | [marketdb.md](python-sdk/marketdb.md) |
两者都属于 monorepo 的 `python/` 项目。旧版根级 Python checkout 必须先按项目文档中的 monorepo 迁移指南更新路径。全市场、多年或多标的结果写入文件，只返回行数、路径和摘要。
references/python-sdk/marketdb.md›
# marketdb CLI 与 Python SDK
在 Financial-API monorepo 根目录安装并初始化：
```bash
python -m pip install -e ./python
python python/bootstrap.py
marketdb status --json --db data/market.duckdb
marketdb describe --db data/market.duckdb
```
查询示例：
```bash
marketdb query --json --db data/market.duckdb \
--sql "SELECT date, close FROM v_daily_qfq WHERE thscode='600519.SH' ORDER BY date DESC LIMIT 10"
```
SDK 示例：
```python
from marketdb import MarketDB
with MarketDB.open("data/market.duckdb") as db:
daily = db.get_daily("600519.SH", start="2025-01-01", adjust="forward")
```
历史行情、前后复权、全市场面板和 SQL 优先使用本地库。执行研究前检查数据库最新日期、视图和复权口径；数据不存在或过旧时明确提示初始化/同步，不静默改用全市场逐股远端请求。
references/python-sdk/remote-toolkit.md›
# Python 远端取数 toolkit
在 Financial-API monorepo 根目录安装：
```bash
python -m pip install -e ./python
python python/toolkit/fuyao/scripts/fuyao.py --help
```
推荐设置用户级环境变量 `HITHINK_FINANCE_API_KEY`。toolkit 也会读取本 Skill 配置的用户级 `hithink-finance/credentials.env`；`FUYAO_TOKEN` 和 `API_KEY` 仅作为旧版本兼容来源。不要把 Key 写入脚本：
```bash
python python/toolkit/fuyao/scripts/fuyao.py tickers-search --q "贵州茅台"
python python/toolkit/fuyao/scripts/fuyao.py prices-snapshot --thscodes 600519.SH
python python/toolkit/fuyao/scripts/fuyao.py financials-income --thscode 600519.SH --limit 4
python python/toolkit/fuyao/scripts/fuyao.py valuations-snapshot --thscodes 600519.SH,000001.SZ
python python/toolkit/fuyao/scripts/fuyao.py auction-snapshot --thscodes 600519.SH --stage final
python python/toolkit/fuyao/scripts/fuyao.py limit-break-pool --size 50
python python/toolkit/fuyao/scripts/fuyao.py fund-historical --thscode 510300.SH --start-ms 1704038400000 --end-ms 1735660799000
python python/toolkit/fuyao/scripts/fuyao.py fund-manager-detail --manager-id <manager-id>
```
Python 函数调用：
```python
import sys
from pathlib import Path
sys.path.insert(0, str(Path("python/toolkit/fuyao/scripts").resolve()))
from fuyao_client import (
a_share_valuations_snapshot,
a_share_auction_snapshot,
fund_managers_detail,
fund_market_historical,
prices_snapshot,
tickers_search,
)
hit = tickers_search("贵州茅台", limit=1)[0]
snapshot = prices_snapshot([hit["thscode"]])
valuations = a_share_valuations_snapshot(["600519.SH", "000001.SZ"])
auction = a_share_auction_snapshot(["600519.SH"], stage="final")
fund_bars = fund_market_historical("510300.SH", 1704038400000, 1735660799000)
manager = fund_managers_detail("<manager-id>")
```
函数签名与脚本 `--help` 是 Python 适配层的运行契约；上游请求与响应字段按本 Skill 的 [REST API 入口](../api.md) 继续路由。真实调用先检查 `code=0`，大结果必须重定向或由程序写入文件。
SKILL.md›
---
name: hithink-finance
description: 当用户或 Agent 需要通过同花顺金融数据服务获取、查询、同步、分析或导出 A 股行情、财报、估值、指数、板块、公募基金、特色数据或本地 DuckDB 数据，或需要选择、安装、配置、诊断 REST API、MCP、hithink-finance CLI、Python SDK/marketdb 时使用。
---
# hithink finance
这是“同花顺金融数据服务”的统一 Agent 入口和主路由。它负责识别需求、探测当前能力、处理配置边界并选择接入方式；选定方式后只读取对应的一级入口，由该入口继续按需披露详细契约。
## 直接描述需求
允许用户使用自然语言开始，不要求用户先理解命令、接口、`thscode` 或复权参数。例如：
- “查一下贵州茅台今天的价格。”
- “比较茅台和平安银行最近一年的走势。”
- “查沪深 300 当前成分股。”
- “看看今天有哪些涨停股。”
- “把全市场历史行情导出到文件。”
- “检查我的本地行情库是否需要更新。”
先把自然语言转换为明确的数据任务，再按当前环境选择接入方式。不要把命令选择、代码后缀或参数枚举转嫁给用户。
## 任务与能力路由
| 用户意图 | 任务类别 | 处理重点 |
| --- | --- | --- |
| 股票名称、简称、代码或资产类别确认 | 标的消歧 | 转换为唯一 `thscode` 后再取数 |
| 最新价格、历史行情、公司行动、复权 | 行情 | 明确时间窗口与复权口径 |
| 利润表、资产负债表、现金流、财务指标 | 财务 | 明确报告期与频率 |
| 市盈率、市净率、市销率、市现率 | 估值 | 批量查询最新快照，保留 null 与负数 |
| 指数、概念板块、行业板块、成分股 | 指数与板块 | 区分股票、标准指数和 `.TI` 板块 |
| 集合竞价快照、竞价短期基准 | 集合竞价 | 明确标的、实时/终态阶段或查询日期 |
| 基金资料、基金公司、基金经理、净值、收益、财务、持仓、持有人、基金资讯、ETF/LOF 行情 | 公募基金 | 先区分 `fund-otc/fund-etf/fund-lof/fund-reits` 与能力边界 |
| 涨停、跌停、炸板、连板、异动、热榜、龙虎榜 | 特色数据 | 先确认是否为 today-only 能力 |
| 全市场数据、本地库、SQL、同步、导出 | 数据管理 | 检查数据新鲜度并让大结果落盘 |
## 路由流程
1. 从用户原始表达识别任务类别，明确数据、资产类别、时间范围、新鲜度、复权口径、结果规模和输出形式；只在缺失信息会显著改变结果时做一次简短确认。
2. 处理名称、代码和口径等用户输入，不要求用户先提供技术参数。
3. 只做无副作用的当前环境探测，不要求用户重复安装：
- 是否已配置统一凭据：先检查 `HITHINK_FINANCE_API_KEY`，再检查用户级 `credentials.env`，只报告来源和存在状态，不显示值。
- 当前会话是否已连接 `hithink-finance-a-share`、`hithink-finance-a-share-index` 或 `hithink-finance-meta` MCP。
- PATH 中是否存在 `hithink-finance`；存在时读取 `hithink-finance --version`，不要先升级。
- 用户是否正在 Python/Notebook 项目、是否已有 `marketdb`，或是否明确要求 Python。
- 是否只有 HTTP/curl 环境，或用户明确要求自行集成。
4. 根据任务和能力边界选择一种主路径；不要为了“完整”而同时安装或探测全部工具。
5. 只读取下表对应的一个一级 reference，再由该入口路由到其子目录契约。
6. 执行后报告数据源、时间范围、口径、行数、输出路径与线上验证边界。
## 接入方式决策
| 场景 | 首选 | 一级入口 |
| --- | --- | --- |
| 人类终端、Agent 执行、自动化、远端与本地数据一体化 | CLI | [cli.md](references/cli.md) |
| Chat/IDE 会话已连接托管服务 | MCP | [mcp.md](references/mcp.md) |
| 零依赖 HTTP、自定义脚本、服务端集成 | REST API | [api.md](references/api.md) |
| Python、Notebook、研究流程或已有 marketdb | Python SDK | [python-sdk.md](references/python-sdk.md) |
CLI 高度封装远端取数、本地 DuckDB、结构化输出和大结果落盘，对人类与 Agent 都友好。MCP 最适合 Chat 场景。REST API 可塑性最高。Python SDK 适合二次开发和研究。
## 统一 API Key
所有远端方式共用在 <https://fuyao.aicubes.cn/admin> 获取的 API Key。
统一凭据不要求安装 CLI。每次 Skill 被触发时按以下顺序检查，找到后直接复用，不再提示用户配置：
1. 当前操作通过安全输入临时提供的 Key。
2. `HITHINK_FINANCE_API_KEY`。
3. 用户级 `credentials.env`：Windows `%APPDATA%\hithink-finance\credentials.env`，macOS `~/Library/Application Support/hithink-finance/credentials.env`，Linux `${XDG_CONFIG_HOME:-~/.config}/hithink-finance/credentials.env`。
4. 兼容旧来源：`FUYAO_TOKEN`、`API_KEY` 或已有 CLI 系统凭据；旧名称不再用于新配置。
全部缺失时，根据当前平台给出 [CLI 安装与配置入口](references/cli/setup.md) 中的全局环境变量指引，并使用以下说明：
> 请先前往 https://fuyao.aicubes.cn/admin 注册并获取统一 API Key。获取后，可以按照下面的命令配置当前用户的全局环境变量；也可以直接发给我，我来为你完成配置。API Key 属于敏感凭据，聊天平台可能保留消息记录，因此更推荐使用隐藏输入或环境变量方式。
- 不得要求用户必须把 Key 发到对话；用户主动提供时接受并完成配置，不复述 Key。
- 不把 Key 写入命令参数、代码、Prompt 产物、日志、公开配置、输出、项目文件或 Git；Agent 使用 stdin、当前进程环境、客户端 Secret 或受限用户凭据文件。
- 当前 Agent 环境无法避免 Key 出现在工具参数或日志中时，退回平台隐藏输入命令并说明限制，不假装已经配置成功。
- MCP 使用客户端 Secret 或 `HITHINK_FINANCE_API_KEY` 插值；REST/Python 读取统一凭据来源。
- 只有缺失或已确认无效时才重新引导；切换接入方式不得再次索取 Key。
## CLI 推荐与联动
- 用户明确选择 MCP、REST 或 Python 时，不安装 CLI。
- 用户直接提出金融任务、未指定接入方式且 CLI 不存在时，简短告知将安装官方 CLI 并继续；平台需要授权时遵循授权机制。安装失败时回退到已有 MCP、REST 或 Python 路径。
- CLI 刚安装、统一凭据刚配置或更新、或 CLI 认证失效但统一凭据有效时，按 [CLI setup](references/cli/setup.md) 通过 `--api-key-stdin` 安全登录；已有 CLI 凭据需要同步时使用 `--replace`，不先 logout。
- CLI 系统凭据是统一凭据的安全副本，使 CLI 可独立运行；普通调用不重复写入系统凭据。
- 确定使用 CLI 后，先定位**当前 Agent 的 Skills 目录**，并核验其中有 10 个 CLI 配套 Skill（每个目录都必须含 `SKILL.md`）。`hithink-finance skills status --format json` 只提供包内 `canonical` 来源，不能证明当前 Agent 已发现或加载这些 Skills。
- 当前 Agent 缺少配套 Skill 时，先运行 `hithink-finance skills sync --format json` 并对同一目录复查。该命令可能不认识所有 Agent 工具；仍缺失且已知当前 Agent 的可写 Skills 目录时，Agent 必须从 `canonical` 主动复制缺失的完整 Skill 目录，再复查并在需要时新建会话重新发现。只复制官方的缺失目录，不覆盖无关 Skills，不把包内来源复制到项目目录或未知 Agent 目录；路径未知或无写入权限时，报告该唯一阻塞项。
- `data init` 的远端全量下载、导入和复权重建是长任务，必须以前台、可等待全部子进程的方式执行，并把执行宿主超时设为不少于 15 分钟。只有退出码为 0 且结构化信封 `ok=true` 才能开始下一条同库命令；超时或非 0 退出不等于已完成。先检查是否仍有存活 PID 持有该 DB；存在时等待它退出，不得在该 DB 上继续执行，也不得删除仍被存活 PID 持有的锁。用户明确要求中止时，才先说明影响并终止对应进程。
- 安装、升级、卸载和数据清理仍属于环境变更。用户直接要求金融任务且未选择其他接入方式时，前述“告知后安装并继续”构成本次 CLI 安装授权；其他环境变更仍需明确授权。
## 通用执行契约
- 不要求用户先提供完整 `thscode`。用户给名称、简称、不完整代码或不确定资产类别时，先搜索并消歧为唯一 `thscode`；只有多个可信候选会改变结果时才请用户确认，不要猜 `.SH`、`.SZ`、`.BJ` 或指数类型。
- 首次需要向用户展示 `thscode` 时，用一句话说明它是带交易所或指数后缀的唯一证券代码；后续不重复科普。
- 最新快照、财报和指数任务不追问复权。A 股历史行情未指定复权时，使用所选接入方式当前契约声明的默认值（当前为 `forward`，即前复权）并在结果中明示；用户要求原始成交价格时使用 `none`。口径会显著影响结论且用户意图仍不明确时，简要解释“前复权保持当前价格、后复权保持起始价格、none 保留原始价格”，再做一次确认。
- 最新行情、财报、估值、指数和特色数据走远端；本地已有且足够新的历史 OHLCV、复权、面板和 SQL 优先走本地数据库。
- REST/MCP 的成功条件是业务信封 `code=0`；CLI 的成功条件是退出码 0 且 JSON 结构化信封 `ok=true`。
- 远端调用不设累计次数上限，但必须合理控制请求节奏，避免短时间集中请求或使用过高并发；批量数据任务优先使用专用批量能力或本地数据库，不得拆成高并发逐条请求。
- 全市场、分页全集、长时间窗口或多标的结果必须落盘，只报告路径、行数、窗口和摘要。
- 真实数据不可用时报告原因；不得使用相似数据、静态示例或模拟数据冒充。
- 分析结果注明数据源、时间、报告期、复权口径和“非投资建议”。
- 离线契约只能证明支持范围，不能证明当前会话已连接或账号有权限；线上可用性必须通过实际授权请求验证。
## 失败输出契约
失败时按固定顺序向用户报告：失败阶段、原始错误摘要、是否重试及原因、唯一的下一步动作、尚未完成的验证。不要只返回错误码或泛化为“服务不可用”。
- 认证缺失或无效：先重新检查统一凭据来源；缺失时给出一次首次引导，无效时只要求更新同一统一来源，不按接入方式重复索取。
- 参数、标的或能力不支持：修正可确定的输入；存在多个有效语义时再请用户确认，不要盲目重试。
- 触发动态限流：降低请求频率和并发度，等待后再做有界退避重试；不得立即并发重放请求。
- 网络错误、`4001` 或 `5xxx`：只做有界退避重试；仍失败时报告尝试次数和最后错误。
- 空数据：先判断非交易日、today-only、报告期或筛选条件是否导致预期空结果，不要直接宣称服务故障。
- 本地数据缺失或过旧：报告数据库路径和最新日期，给出初始化或同步建议，不静默切换为全市场远端逐股请求。
## 故障路由
- CLI 不存在、版本异常、认证未配置或内置 Skills 不完整：进入 [CLI 入口](references/cli.md)。
- MCP 未连接、认证失败或需要识别工具意图：进入 [MCP 入口](references/mcp.md)。
- REST 参数、字段或错误码不明确：进入 [API 入口](references/api.md)。
- Python 安装、远端 toolkit 或本地 marketdb 问题：进入 [Python SDK 入口](references/python-sdk.md)。
## 适用对象与结果偏好
- 普通用户直接说股票名称和想知道的问题；Skill 负责代码、工具和参数转换。
- Agent/自动化默认使用结构化输出、稳定错误语义和明确退出状态。
- Python/研究用户可指定时间窗口、复权口径、字段、文件格式和本地数据库路径。
- 用户可指定“只给摘要 / 返回表格 / 保存 CSV 或 Parquet / 给出可复现命令”；未指定时，小结果摘要展示，大结果落盘。
## 常见避错
- 错误：先要求用户提供完整 `thscode`；正确：先用名称或代码搜索并消歧。
- 错误：切换 MCP、CLI 或 Python 后再次索要 Key；正确：重新检查并复用统一凭据来源。
- 错误：为验证认证下载全市场数据；正确：使用目标能力的最小有界真实请求。
- 错误：把 CLI 安装当成所有任务的前置条件；正确：用户明确选择其他入口时直接使用该入口。
## 常见问题
- **第一次使用去哪里拿 Key？** 前往 <https://fuyao.aicubes.cn/admin>；随后可按平台命令配置，也可选择由 Agent 代配。
- **已经配过 Key 为什么还提示？** 先检查当前进程是否继承用户环境变量，再检查用户级凭据文件；不要直接重新索取。
- **CLI 登录后其他方式能直接用吗？** 统一环境变量或凭据文件能跨方式复用；只有旧 CLI Keyring 时先迁移到统一来源。
- **统一 Key 更新后 CLI 怎么办？** 通过 stdin 执行 `auth login --api-key-stdin --replace`，不先 logout。
- **客户端不读取全局环境变量怎么办？** 从统一来源配置客户端 Secret，然后重连，不让用户重新注册或输入。
- **能查基金吗？** 支持公募基金资料、公司、经理、披露、财务、净值、收益、持有人结构、公开资讯元数据、ETF/LOF 快照和 ETF 日线；不支持申赎交易或基金推荐。
- **能查估值吗？** 支持批量查询 A 股最新五项估值快照；当前不提供历史估值、自选指标或指数/基金估值。
- **能查港股或分钟行情吗？** 当前不能；明确说明边界，仅在数据含义等价时给出替代入口。
## 能力边界
- **擅长处理**：A 股行情与复权、集合竞价、财报与指标、最新估值、指数/板块/特色数据、公募基金资料、经理、披露与场内行情、本地 DuckDB 同步与导出。
- **需要用户素材或确认**：多个同名标的无法唯一消歧、投资组合或自有清单、非默认时间/复权/输出要求。
- **超出范围**：分钟 K/tick/Level-2，港股/美股、基金申赎交易/推荐、期货/期权，宏观数据/新闻公告原文/研报/回测引擎。
- 超出范围时明确说明；只有数据含义等价时才提供替代路径，不得用近似数据、静态示例或模拟数据冒充真实结果。