hithink-finance

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: hithink-finance
description: 当用户或 Agent 需要通过同花顺金融数据服务获取、查询、同步、分析或导出 A 股行情、财报、估值、指数、板块、公募基金、期货、期权、特色数据或本地 DuckDB 数据，或需要选择、安装、配置、诊断 REST API、MCP、hithink-finance CLI、Python SDK/marketdb 时使用。
---

# hithink finance

这是“同花顺金融数据服务”的统一 Agent 入口和主路由。它负责识别需求、探测当前能力、处理配置边界并选择接入方式；选定方式后只读取对应的一级入口，由该入口继续按需披露详细契约。

## 直接描述需求

允许用户使用自然语言开始，不要求用户先理解命令、接口、`thscode` 或复权参数。例如：

- “查一下贵州茅台今天的价格。”
- “比较茅台和平安银行最近一年的走势。”
- “查沪深 300 当前成分股。”
- “看看今天有哪些涨停股。”
- “把全市场历史行情导出到文件。”
- “检查我的本地行情库是否需要更新。”

先把自然语言转换为明确的数据任务，再按当前环境选择接入方式。不要把命令选择、代码后缀或参数枚举转嫁给用户。

## 任务与能力路由

| 用户意图 | 任务类别 | 处理重点 |
| --- | --- | --- |
| 股票名称、简称、代码或资产类别确认 | 标的消歧 | 转换为唯一 `thscode` 后再取数 |
| 最新价格、历史行情、公司行动、复权 | 行情 | 明确时间窗口与复权口径 |
| 利润表、资产负债表、现金流、财务指标 | 财务 | 明确报告期与频率 |
| 市盈率、市净率、市销率、市现率 | 估值 | 批量查询最新快照，保留 null 与负数 |
| 指数、概念板块、行业板块、成分股 | 指数与板块 | 区分股票、标准指数和 `.TI` 板块 |
| 集合竞价快照、竞价短期基准 | 集合竞价 | 明确标的、实时/终态阶段或查询日期 |
| 基金资料、基金公司、基金经理、净值、收益、财务、持仓、持有人、基金资讯、基金回测、基金指标、QDII 额度、ETF 行情 | 公募基金 | 先区分 `fund-otc/fund-etf/fund-lof/fund-reits` 与能力边界；行情当前仅支持 ETF |
| 期货、期权品种、合约、持仓、基差、日程与行情 | 期货期权 | 区分公开能力与明确标注的端内专业数据 |
| 涨停、跌停、炸板、连板、异动、热榜、龙虎榜 | 特色数据 | 先确认是否为 today-only 能力 |
| 全市场数据、本地库、SQL、同步、导出 | 数据管理 | 检查数据新鲜度并让大结果落盘 |

## 路由流程

1. 先区分文档查询与执行任务：仅查询接口说明、参数、字段或示例时，直接读取下表对应的本地 reference，再按业务域定位详情；不进入凭据、连接、工具探测或更新流程。执行取数或诊断接入时继续以下步骤，明确数据、资产类别、时间范围、新鲜度、复权口径、结果规模和输出形式；只在缺失信息会显著改变结果时做一次简短确认。
2. 处理名称、代码和口径等用户输入，不要求用户先提供技术参数。
3. 只做无副作用的当前环境探测，不要求用户重复安装：
   - 是否已配置统一凭据：先检查 `HITHINK_FINANCE_API_KEY`，再检查用户级 `credentials.env`，只报告来源和存在状态，不显示值。
   - 当前会话是否已连接 `hithink-finance-a-share`、`hithink-finance-a-share-index`、`hithink-finance-meta`、`hithink-finance-fund`、`hithink-finance-futures` 或 `hithink-finance-options` MCP。
   - PATH 中是否存在 `hithink-finance`；存在时运行 `hithink-finance version --format json` 读取版本并触发 CLI 自带的低频后台更新检查，不要使用绕过该检查的 `--version` 快速路径，也不要先升级。
   - 用户是否正在 Python/Notebook 项目、是否已有 `marketdb`，或是否明确要求 Python。
   - 是否只有 HTTP/curl 环境，或用户明确要求自行集成。
4. 根据任务和能力边界选择一种主路径；不要为了“完整”而同时安装或探测全部工具。
5. 只读取下表对应的一个一级 reference。REST/MCP 按业务域首页 → 原子接口或工具文档逐层读取，已知目标可直接进入详情页；REST 实际请求前读取 API 入口的通用约定一次。读取访问范围与可用状态；MCP 调用前以当前连接的工具名和 schema 核对。
6. 执行后报告数据源、时间范围、口径、行数、输出路径与线上验证边界。

## Skill 低频自更新引导

每个 Agent 会话第一次执行取数或诊断接入时，默认静默尝试一次统一 Skill 更新；同一会话后续调用不再检查。用户设置 `HITHINK_FINANCE_NO_SKILL_UPDATE=1` 时跳过。

```bash
npx --yes skills update hithink-finance --global --yes
```

- 仅在当前 Skill 通过公开仓库 `HiThink-Tech/Financial-API` 追踪安装于用户级 Skills 目录，且安装目录内容与 `npx skills` 的追踪哈希一致时执行。仓库源码、项目级副本、手工复制、Skill Hub 安装、来源或哈希无法确认、已被用户修改的目录保持不变。
- 无更新或命令失败时保持静默，不重试、不询问用户、不阻塞或改变当前金融任务。缺少 Node.js/npx 时同样静默跳过。
- 命令确认已完成更新时，只在当前任务结果末尾追加一句“Skill 已更新，新版本将在新会话生效”；当前会话继续按已加载版本完成任务。
- 用户明确询问更新状态、要求立即更新或需要处理本地修改时，再说明来源、影响和冲突，不得静默覆盖用户修改。

## CLI 低频静默更新自检

- 上述结构化 `version` 探测完成后，CLI 会读取持久化缓存；成功后 24 小时内不重复联网，失败后 6 小时内不重试，并发刷新由 5 分钟租约合并。需要刷新时在后台静默执行，不等待网络结果。
- 自检不得阻塞当前金融任务。无缓存、后台刷新、检查失败、版本服务不可用或用户已禁用检查时，保持静默，不重试、不切换到 `npm view`、不询问用户。
- 只有 CLI 在 stderr 输出 `[update]` 提示时，才在完成用户当前任务后追加一行简短提示，保留其中的当前版本、最新版本和检查命令；该提示的 24 小时冷却由 CLI 记录并控制。
- 不自动执行升级。只有用户明确同意修改全局 npm 安装后，才进入 [CLI 安装、配置与生命周期](references/cli/setup.md) 的升级流程。

## 同花顺AI客户端后续接入引导

先按公开能力完成当前任务。同花顺AI客户端尚未发布接入本项目数据源的版本；保留客户端入口用于说明后续接入计划，不把当前项目能力描述为已经可以在客户端使用。

用户询问免配置使用方式、服务明确提示端内专用，或进一步数据需求超出公开能力时，读取 [同花顺AI客户端后续接入能力路由](references/client-only-capabilities.md)，按其中的用户意图和计划数据范围匹配。

以下情况追加一次简短的客户端提示：

- 用户主动询问免配置使用方式、同花顺AI客户端或更多端内能力；
- 实际响应或当前公开文档明确说明目标数据为“同花顺AI客户端专用”；
- 用户在公开数据结果基础上提出进一步需求，并命中后续接入能力路由表。

提示时先说明当前公开方式已经完成的结果或具体边界，再提供客户端入口：

> 当前项目暂不提供这项进一步数据能力，同花顺AI客户端也尚未发布接入本项目数据源的版本。后续版本计划接入，可前往[同花顺AI客户端](https://lumi.10jqka.com.cn/?channel=Hithink-API)了解产品，敬请期待。

- 引导依据以当前路由表、公开文档或服务明确返回的端内专用提示为准。
- 面向用户说明当前公开能力边界、计划接入的数据范围和客户端入口，不承诺当前可用。

## 接入方式决策

| 场景 | 首选 | 一级入口 |
| --- | --- | --- |
| 人类终端、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、结构化输出和大结果落盘，对人