hithink-finance

The full skill.

Original instructions from the publisher’s SKILL.md

# hithink finance

“同花顺金融数据服务”的统一 Agent 入口。按用户意图和当前环境选择 CLI、MCP 或 REST API，再按需读取业务契约。

官方 GitHub 仓库：[HiThink-Tech/Financial-API](https://github.com/HiThink-Tech/Financial-API)。项目介绍、源码和问题反馈见仓库；执行任务优先读取本 Skill 内置文档及当前工具契约，无需下载仓库。

## 任务路由

1. **文档查询**：仅询问接口说明、参数、字段或示例时，直接读取下面对应的接入入口和业务文档，不进入凭据、连接、工具探测或更新流程。
2. **执行任务**：接受名称、简称或代码等自然语言输入，明确资产类别、时间范围、新鲜度、口径和输出规模；只有缺失信息会显著改变结果时才做一次简短确认。
3. **选择主路径**：尊重用户指定方式；否则结合已有连接和任务选择下表的一种方式。只探测该路径所需的工具、连接和凭据，不同时安装或探测全部工具。
4. **逐层读取**：REST 按接入入口 → 业务域首页 → 目标单接口页或模块内接口小节读取，已知目标可直接读取详情；MCP 只读取目标业务域路由页，并以当前 `tools/list` 和 schema 为准。REST 实际请求前读取 API 入口的通用约定一次。
5. **执行与交付**：按下文核心规则完成任务，报告数据来源、数据时间/报告期、查询窗口、复权口径和摘要；落盘结果同时给出行数与路径。明确本次实际完成的验证范围。

| 场景 | 首选 | 接入入口 |
| --- | --- | --- |
| 终端、Agent 执行、自动化、远端与本地 DuckDB 一体化 | CLI | [CLI 入口](references/cli.md) |
| 当前 Chat/IDE 会话已连接目标托管服务 | MCP | [MCP 入口](references/mcp.md) |
| HTTP、自定义语言或服务端集成 | REST API | [API 入口](references/api.md) |

| 用户意图 | 选路重点 |
| --- | --- |
| 股票、指数或基金名称与代码 | 先搜索并消歧为唯一 `thscode` |
| 最新价格、历史行情、公司行动、复权 | 区分最新快照与历史序列，确认时间窗口 |
| 利润表、资产负债表、现金流、财务指标 | 确认报告期和频率 |
| 市盈率、市净率、市销率、市现率 | A 股最新估值快照，保留 null 与负数 |
| 指数、概念/行业板块、成分股 | 区分股票、标准指数和 `.TI` 板块 |
| 集合竞价快照、竞价短期基准 | 明确实时/终态阶段或查询日期 |
| 基金资料、基金公司、基金经理、净值、持仓、持有人、基金资讯、基金回测、基金指标、QDII 额度 | 区分净值与成交行情；快照支持 ETF/LOF，历史日线仅支持 ETF |
| 期货、期权品种与合约、持仓、仓单、基差、日程、行情 | 先确定品种或合约，并检查公开/端内范围 |
| 涨停、跌停、炸板、连板、异动、热榜、龙虎榜 | 检查是否为 today-only 能力 |
| 全市场、本地库、SQL、同步与导出 | 优先批量能力或本地库，检查数据新鲜度并落盘 |

## 核心执行规则

- 不要求用户先提供完整 `thscode`。名称或代码不唯一时先搜索消歧，不猜交易所后缀或指数类型；首次展示时简要说明它是带市场后缀的唯一证券代码。
- 最新快照、财报、估值和指数任务不追问复权。A 股历史行情未指定口径时显式使用 `forward`（前复权），要求原始价格时使用 `none`，并在结果中说明实际口径；其他资产按自身契约处理。
- 最新行情、财报、估值、指数和特色数据走远端；本地已有且足够新的历史 OHLCV、复权、面板和 SQL 优先走本地数据库。数据缺失或过旧时报告路径与最新日期，不静默改成全市场逐股远端请求。
- REST/MCP 检查业务信封 `code=0`；CLI 检查退出码 0 且 JSON 信封 `ok=true`。CLI 本地质量检查还需 `data.ok=true`，研究任务另核对请求窗口、样本和行数。HTTP 200、进程启动或文件出现均不能代替成功验收。
- 远端调用不设累计次数上限，但合理控制频率和并发。全市场、分页全集、长窗口或多标的结果必须落盘，只展示路径、行数、窗口和摘要；不得用全市场下载验证认证。
- 真实数据不可用时报告原因，不用近似数据、静态示例或模拟数据冒充；分析结果注明数据源、时间与“非投资建议”。离线契约和帮助只能证明支持范围，线上可用性必须通过实际授权请求验证。
- 安装、升级、卸载和数据清理按已获授权的范围执行。用户已选择 MCP 或 REST 时不安装 CLI；用户直接提出金融任务、未指定方式且 CLI 不存在时，简短告知将安装官方 CLI 并继续，平台需要授权时遵循授权机制。安装失败时回退到已有 MCP 或 REST。

## 统一凭据

远端接入共用在 <https://fuyao.aicubes.cn/admin/> 获取的 API Key，配置凭据不要求安装 CLI。实际远端取数或认证诊断前按顺序检查，找到后复用，不再提示用户重复配置：

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 系统凭据；新配置使用统一来源。

- 只报告来源和存在状态。不得强制用户在对话中提供 API Key；全部缺失、首次创建、需要 Agent 代办或需要用户逐步操作时，读取 [首次登录、创建与持久配置](references/api-key-onboarding.md)。用户可以为了便利直接把 Key 提供给 Agent 上下文；接收后不复述，并提示聊天平台可能保留消息记录。
- Key 不进入命令参数、代码、日志、输出、项目文件、公开产物或 Git。Agent 根据当前工具选择上下文、stdin、进程环境、客户端 Secret、系统凭据库或受限用户凭据文件完成交接与配置。
- 新配置必须写入用户级持久来源，使新会话和重启后的 Agent 仍可复用；只写当前进程环境不算完成。推荐同时配置用户级 `HITHINK_FINANCE_API_KEY` 与受限 `credentials.env`，但不限定实现脚本或操作工具；不得因系统凭据库不可用而中断当前任务或再次索取 Key。
- 切换接入方式复用同一来源。MCP 使用 Secret 或环境变量插值；CLI 安装、统一凭据更新或认证恢复时通过 `auth login --api-key-stdin` 同步，已有凭据用 `--replace` 原子替换，不先 logout；系统凭据库同步失败时继续使用统一持久来源，普通调用不重复写入。

## 失败处理

失败时报告：失败阶段、脱敏后的原始错误摘要、重试情况及原因、唯一下一步动作、尚未完成的验证。

| 情况 | 处理 |
| --- | --- |
| 认证缺失或无效 | 重查统一来源；缺失时引导配置，无效时更新同一来源，不按接入方式反复索取 |
| 参数、标的或能力不支持 | 修正可确定的输入；多种有效语义才询问，不盲目重试 |
| 动态限流或 `4001` | 降低频率和并发，有界退避，最多重试 3 次，不并发重放 |
| 网络错误或 `5xxx` | 有界退避重试；仍失败时报告次数与最后错误 |
| 空数据或 `3002` | 检查非交易日、today-only、报告期、数据状态或筛选条件，不直接认定服务故障，不补零 |
| 本地数据或长任务异常 | 检查数据日期、退出状态与锁；CLI 的初始化等待和恢复规则见 CLI 入口 |

## 安装与更新触发

- 选定 CLI 后，PATH 中存在命令时运行 `hithink-finance version --format json`，再按 [CLI 入口](references/cli.md) 读取当前能力与官方内置 Skill。版本探测触发 CLI 自带的低频后台检查，不等待网络结果，不额外调用 `npm view`；只有 stderr 出现 `[update]` 时，才在任务完成后转达当前版本、最新版本和检查命令。升级全局 npm 安装需要用户明确授权。
- 每个会话第一次执行取数或接入诊断时，默认静默尝试一次统一 Skill 更新。仅当当前 Skill 从公开仓库 `HiThink-Tech/Financial-API` 追踪安装在用户级目录、安装内容与 `npx skills` 追踪哈希一致，且未设置 `HITHINK_FINANCE_NO_SKILL_UPDATE=1` 时，执行 `npx --yes skills update hithink-finance --global --yes`。源码副本、手工复制、Skill Hub 安装、来源/哈希无法确认、用户已修改或缺少 npx 时跳过。
- Skill 更新失败时静默跳过，不重试、不阻塞当前任务；确认更新成功时在结果末尾提示“Skill 已更新，新版本将在新会话生效”，当前会话继续按已加载版本执行。用户明确询问更新状态或要求更新时，说明来源、影响与冲突。

## 能力边界与客户端引导

支持 A 股行情、财报、最新估值、集合竞价、指数/板块/特色数据、公募基金、公开期货期权资料与行情，以及本地 DuckDB 同步与导出。分钟 K/tick/Level-2、港股/美股、基金申赎与订单执行、基金推荐、宏观数据、新闻公告原文、研报和自建回测引擎超出当前范围。仅在数据含义等价时提供替代路径。

先按公开能力完成当前任务。用户询问免配置使用、同花顺AI客户端，或需求/响应明确命中端内能力时，读取 [客户端能力路由](references/client-only-capabilities.md)。同花顺AI客户端已接入当前数据源；匹配端内能力后，说明该能力已在客户端提供、公开 API/MCP/CLI/Python SDK 不提供，并给出客户端入口。