同花顺金融数据服务（hithink-finance） 是由同花顺官方提供和维护的 A 股金融数据服务，面向 AI Agent、量化研究者和应用开发者。

通过统一 API Key，可以查询 A 股行情、集合竞价、财务报表、估值、指数与板块、公募基金、公开期货期权、特色数据及 A 股和港股新股资料，并通过 REST API、MCP、CLI、Python SDK、本地 DuckDB 或 Agent Skill 接入现有工作流。

一站式同花顺官方金融数据能力，覆盖查询、研究、批量导出和 AI Agent 自动调用。

• 官网：https://fuyao.aicubes.cn/
• 在线文档：https://fuyao.aicubes.cn/docs/
• API Key 管理：https://fuyao.aicubes.cn/admin/
• 仓库文档中心：docs/
• 同花顺AI客户端：下载并体验

API、MCP、CLI、Python SDK 和 Agent Skill 适合自主接入；同花顺AI客户端已接入当前数据源，金融数据与分析能力已内置，打开客户端即可使用。

Agent 和终端任务优先使用 CLI 及其内置 Skills；REST 文档与 HTTP 接口选路使用 hithink-finance，MCP 配置及工具调用使用 hithink-finance-mcp。

当前公开方式不提供分钟 K、tick、Level-2、港股或美股行情、宏观数据、新闻公告原文、研报原文、基金申赎交易和投资推荐。标记为“端内专用”的能力已内置于同花顺AI客户端，不通过公开 API、MCP、CLI 或 Python SDK 提供。数据权限及实际可访问能力以官网和账号授权为准；请求未支持的数据时，不使用模拟数据或静态示例冒充真实结果。

CLI 默认推荐 OAuth：先运行 hithink-finance auth status --format json 复用当前有效凭据；首次登录使用 hithink-finance auth login --method oauth，按提示完成浏览器授权。

REST、MCP、Python 及 CLI 的 API Key 方式共用在 API Key 管理 获取的 Key。选择此方式后，Agent 可完成 Key 签发、安全交接、用户级持久配置和真实请求验证。具体流程见 API Key 创建与持久配置。

用户可以直接把 API Key 提供给 Agent 上下文以便代配；Agent 不应复述，并应提示聊天平台可能保留消息记录。Key 不要写入代码、README、Issue、日志、产物或 Git；本地持久化优先使用用户级环境变量、用户级凭据文件、系统凭据库或客户端 Secret。

按实际接入方式使用独立 Skill：

各自安装或分发时保留完整目录及 references/。MCP 契约按业务分类组织，每个工具保留包含参数、返回字段和关联结构的独立小节，可以独立使用。

CLI 配套领域 Skills 随 npm 包安装，并由 CLI 发布到用户级共享目录，再链接到已安装 Agent：

npm install -g @hithink-tech/hithink-finance-cli
hithink-finance skills status --format json

CLI 的业务请求由宿主按内置 Skill 的 description 直接选择领域。CLI 配套 Skills 的同步规则见 CLI 文档。

重新打开 Agent 会话后即可直接描述需求：

查询贵州茅台的最新行情，并分析近一年的涨跌幅、最大回撤和均线趋势。

CLI 是人类终端、Agent 和自动化任务的默认推荐入口：

npm install -g @hithink-tech/hithink-finance-cli
hithink-finance auth login
hithink-finance capabilities --format json

常见命令：

# 根据代码或名称查找股票
hithink-finance symbol search --q 600519 --limit 5 --format json

# 查询最新行情
hithink-finance market snapshot --thscodes 600519.SH --format json

# 查询最近四期利润表
hithink-finance financials income --thscode 600519.SH --limit 4 --format json

# 初始化本地数据库
hithink-finance data init --format json

# 查询本地前复权日线
hithink-finance db query \
  --sql "SELECT * FROM v_daily_qfq LIMIT 10" \
  --format json

CLI 会为已检测到的 Agent 同步配套领域 Skills。支持目标、自定义目录、修复、移除和手工兜底安装方式见 CLI Skills 管理说明。

仅在参与仓库开发或 npm 暂不可用时从源码验证：

cd hithink-finance-cli
npm ci --ignore-scripts
npm run build
node dist/cli/main.js capabilities --format json

完整命令和生命周期说明见 hithink-finance-cli/README.md。

REST API 适合服务端、自定义语言和零依赖 HTTP 集成。以下示例查询贵州茅台最新行情：

curl 'https://fuyao.aicubes.cn/api/a-share/prices/snapshot?thscodes=600519.SH' \
  -H 'X-api-key: <API_KEY>'

• 仓库内契约：REST API 文档
• 在线文档：https://fuyao.aicubes.cn/docs/
• 文档全文聚合：https://fuyao.aicubes.cn/llms-full.txt

docs/api/ 按业务域提供单接口页与多接口模块页；字段、参数和错误语义以目标接口小节为准。

MCP 适合 Claude Desktop、Cursor、Windsurf 和其他支持 MCP 的客户端。按七个数据域提供接入配置，连接后以实时 tools/list 确认可用工具：

单个服务的配置结构如下：

{
  "mcpServers": {
    "hithink-finance-a-share": {
      "type": "http",
      "url": "https://fuyao.aicubes.cn/mcp/a-share",
      "headers": {
        "X-api-key": "${HITHINK_FINANCE_API_KEY}"
      }
    }
  }
}

完整配置、安全方式、服务路由和验证步骤见 MCP 接入说明。实际调用或排查参数变化时，以当前连接返回的 tools/list 为准。

安装 Python 子项目：

python -m pip install -e ./python

查询远端数据：

python python/toolkit/fuyao/scripts/fuyao.py tickers-search --q "贵州茅台"
python python/toolkit/fuyao/scripts/fuyao.py prices-snapshot --thscodes 600519.SH

初始化并检查本地数据库：

python python/bootstrap.py
marketdb status --json --db data/market.duckdb
marketdb validate --json --db data/market.duckdb

更多说明：

• Python README
• toolkit 路由
• marketdb 文档
• Python 可执行示例

examples/inspirations/ 提供可以复制使用的 Prompt、预览图和静态 HTML；python/examples/ 提供 SDK、marketdb 和远端数据组合示例。

该示例组合展示最新行情、近一年日 K、均线、区间表现和最大回撤。

• 完整说明与 Prompt
• 直接打开静态 HTML

示例用于说明数据组合方式，不是数据能力契约、投资建议或固定视觉标准。

• 本项目不设置累计调用次数上限，但调用方应避免短时间集中请求或使用过高并发；触发动态限流后应降低频率和并发度，并在适当延迟后重试。
• 全市场、分页全集、多标的或长时间窗口结果必须落盘，只在终端或对话中展示路径、行数、窗口和摘要。
• 首次使用名称或不完整代码时，应先检索并确认唯一 thscode，不要猜测交易所或指数后缀。
• 历史行情结果应注明时间窗口和复权口径；财务结果应注明报告期。
• 离线文档、测试和帮助信息只能证明支持范围；线上可用性需要通过实际授权请求验证。
• 真实数据不可用时应说明原因，不使用近似数据、静态示例或模拟数据替代。
• 本项目提供金融数据访问和研究数据准备工具，不提供投资建议。

• CLI 与 Python toolkit 新增涨停统计、个股机构与营业部记录、严重异动、竞价机会及 A 股和港股新股入口；热榜支持按条数查询。对应 REST/MCP 与 Agent Skill 契约同步更新。

项目对外可见的重要变化按时间倒序记录在 CHANGELOG.md，避免在多个入口重复维护易过期的版本摘要。

旧版根级 Python 用户、脚本和 Agent Prompt 请先阅读 Monorepo 版本升级指南；本地数据库和数据文件不需要随代码目录迁移。

docs/                    公共文档中心；REST 与 MCP 契约和接入说明
skills/hithink-finance/  可独立安装的统一 Agent Skill；包含契约镜像
hithink-finance-cli/     Node.js CLI 子项目，运行时不依赖 Python
python/                  Python SDK、远端 toolkit、marketdb、示例和测试
examples/                monorepo 级示例导航和静态灵感
scripts/                 仓库级维护脚本

详细参数和契约下沉到对应子项目 README 或 docs/。REST 页面同步到 hithink-finance；MCP 工具按业务分类合并到 hithink-finance-mcp，每个工具小节包含参数、返回字段和关联结构。契约更新后从仓库根目录运行：

python scripts/sync_skill_contracts.py
python scripts/sync_skill_contracts.py --check
python -m pytest python/tests/

cd hithink-finance-cli
npm run verify

internal/ 和 sdd-docs/ 属于内部治理与开发记录，不是公开使用入口。

• 文档中心
• REST API 契约
• MCP 接入说明
• CLI README
• Python README
• Python toolkit
• marketdb 文档
• Agent Skill
• Monorepo 升级指南
• 更新日志

本仓库采用 MIT License。