hithink finance

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

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

任务路由

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

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

用户意图	选路重点
股票、指数或基金名称与代码	先搜索并消歧为唯一 `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。实际远端取数或认证诊断前按顺序检查，找到后复用，不再提示用户重复配置：

当前操作通过安全输入临时提供的 Key。
环境变量 HITHINK_FINANCE_API_KEY。
用户级 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。
兼容已有 FUYAO_TOKEN、API_KEY 或 CLI 系统凭据；新配置使用统一来源。

只报告来源和存在状态。不得强制用户在对话中提供 API Key；全部缺失、首次创建、需要 Agent 代办或需要用户逐步操作时，读取首次登录、创建与持久配置。用户可以为了便利直接把 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 入口读取当前能力与官方内置 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客户端，或需求/响应明确命中端内能力时，读取客户端能力路由。同花顺AI客户端已接入当前数据源；匹配端内能力后，说明该能力已在客户端提供、公开 API/MCP/CLI/Python SDK 不提供，并给出客户端入口。

hithink-finance