From e07e9426c7a9e22a3e06aa92003f47ed92fed241 Mon Sep 17 00:00:00 2001 From: xiaowu Date: Sat, 22 Aug 2026 11:38:39 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=90=8C=E8=8A=B1?= =?UTF-8?q?=E9=A1=BA=E9=87=91=E8=9E=8D=E6=95=B0=E6=8D=AE=E6=9C=8D=E5=8A=A1?= =?UTF-8?q?(hithink-finance)=E6=8E=A5=E5=85=A5=E6=8C=87=E5=8D=97=EF=BC=88?= =?UTF-8?q?=E5=AE=9E=E6=B5=8B=E7=89=88=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- quantitative_data/hithink_finance接入指南.md | 168 +++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 quantitative_data/hithink_finance接入指南.md diff --git a/quantitative_data/hithink_finance接入指南.md b/quantitative_data/hithink_finance接入指南.md new file mode 100644 index 0000000..fff149f --- /dev/null +++ b/quantitative_data/hithink_finance接入指南.md @@ -0,0 +1,168 @@ +# 同花顺金融数据服务（hithink-finance）接入指南 + +> 同花顺官方 A 股金融数据服务，一个 API Key 打通行情/财报/估值/特色数据。 +> 官网：https://fuyao.aicubes.cn ｜ GitHub：https://github.com/HiThink-Tech/Financial-API（开源工具链） +> 更新：2026-08-22 ｜ 状态：✅ 已实测可用（沙箱已配置） + +## 1. 概述 + +面向 AI Agent、量化研究和应用开发的 A 股数据服务，覆盖： + +- **行情**：实时快照、历史 K 线、复权因子、公司行动、交易日历 +- **财务**：利润表、资产负债表、现金流量表、财务指标 +- **估值**：市盈率 TTM/MRQ、市净率、市销率、市现率 +- **特色数据**：集合竞价、涨跌停池、炸板池、连板天梯、个股异动、热榜、龙虎榜 +- **指数/板块**：目录、成分股、行情、历史 K 线 +- **公募基金**：资料、公司、经理、财务、持仓、净值、业绩、场内行情 +- **全市场导出**：全量/增量日 K、公司行动等标准数据文件 + +**明确不覆盖**：分钟 K、tick、海外行情、宏观数据、新闻公告原文、研报。 +（请求未支持的数据时明确说明，不得用模拟数据冒充。） + +## 2. API Key + +- 申请：https://fuyao.aicubes.cn/admin/ 一键签发 +- 统一环境变量：`HITHINK_FINANCE_API_KEY`（API / MCP / CLI / Python 共用一把 Key） +- **安全要求**：Key 只写入用户级凭据来源（credentials.env / CLI 凭据库）， + **严禁**写入代码、日志、公开配置或 Git 仓库；Agent 不得复述 Key。 + +家庭环境现状（2026-08-22 已配好）： +- 沙箱（小五所在环境）：`~/.openclaw/credentials.env`（600 权限）+ CLI 凭据库 +- 小强如需独立使用：向爸爸要 Key，按 4.1 节 `auth login` 配置自己的凭据 + +## 3. 接入方式速览 + +| 场景 | 推荐方式 | +|------|---------| +| Agent 自动查数 | hithink-finance Skill（npx skills add HiThink-Tech/Financial-API --skill hithink-finance -g --yes） | +| Claude/Cursor 对话查数 | MCP（4 个托管端点，见 4.4） | +| Python/Notebook 研究 | Python SDK（见 4.3） | +| 网站/App/后端接入 | REST API（见 4.5） | +| 终端批量查询/导出 | CLI（见 4.1） | +| 本地长期保存 + SQL 研究 | marketdb / 本地 DuckDB（见 4.2） | + +## 4. 详细接入 + +### 4.1 CLI（沙箱已装 ✅） + +```bash +npm install -g @hithink-tech/hithink-finance-cli --registry=https://registry.npmmirror.com +hithink-finance auth login # 录入 API Key（--api-key-stdin 支持 stdin） +hithink-finance capabilities --format json # 查看本版本能力目录 +``` + +常用命令（全部支持 `--format json` 稳定输出）： + +```bash +# 按代码/名称/关键词找标的（返回唯一 thscode） +hithink-finance symbol search --q 600519 --limit 5 --format json + +# 最新行情快照（单只/多只/全市场） +hithink-finance market snapshot --thscodes 600519.SH --format json + +# 历史 K 线 +hithink-finance market history --thscode 600519.SH --kline daily --limit 30 --format json + +# 财务报表（最近 N 期） +hithink-finance financials income --thscode 600519.SH --limit 4 --format json + +# 初始化本地 DuckDB（回测数据库） +hithink-finance data init --format json + +# SQL 查询本地前复权日线 +hithink-finance db query --sql "SELECT * FROM v_daily_qfq LIMIT 10" --format json +``` + +> 具体命令/参数以 `hithink-finance capabilities --format json` 返回的机器可读能力目录为准。 + +### 4.2 本地 DuckDB（marketdb）—— 回测数据方案 + +```bash +hithink-finance data init # 初始化本地库 +hithink-finance data sync # 增量同步（可定时） +hithink-finance db query --sql "SELECT ..." --format json # 只读 SQL +# 导出：data export / dump 相关命令（见 capabilities） +``` + +适合：长期保存历史行情、复权计算、SQL 因子研究、回测数据集。 +替代/互补现有 quantitative_data 的 Tushare 导入链路（importer.py / incremental_import.py）。 + +### 4.3 Python SDK + +```bash +git clone https://github.com/HiThink-Tech/Financial-API +cd Financial-API && pip install -e ./python +``` + +```bash +python python/toolkit/fuyao/scripts/fuyao.py tickers-search --q "贵州茅台" +python python/toolkit/fuyao/scripts/fuyao.py prices-snapshot --thscodes 600519.SH +``` + +### 4.4 MCP（Claude Desktop / Cursor / Windsurf） + +```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}" } + } + } +} +``` + +### 4.5 REST API + +- Base：`https://fuyao.aicubes.cn`，鉴权 Header：`X-api-key` +- 统一 ApiResponse 信封：业务结果（含错误）HTTP 200 返回，用 `code` 字段分发 +- 路径风格：`/api/<标的宇宙>/<数据类型>/<动作>`，如 `/api/a-share/prices/snapshot` +- snake_case 字段、显式 currency、毫秒级 Unix 时间戳（LLM-friendly） +- 完整契约：https://fuyao.aicubes.cn/llms-full.txt ｜ 仓库 docs/api/ + +```bash +curl 'https://fuyao.aicubes.cn/api/a-share/prices/snapshot?thscodes=600519.SH' \ + -H "X-api-key: $HITHINK_FINANCE_API_KEY" +``` + +## 5. 与小强现有架构的衔接建议 + +1. **回测数据**：用 marketdb 本地 DuckDB 替代/补充 Tushare 日线导入（现有 importer.py 继续保留，两者可交叉校验） +2. **实时因子**：行情快照 API 做实时打分；涨跌停池/炸板池/连板天梯做情绪与事件因子 +3. **龙虎榜/异动/热榜**：事件驱动策略的增量数据源（Tushare 免费版这些覆盖弱） +4. **财报/估值**：`financials` + `valuation` 命令批量拉全市场，喂多因子模型 +5. **全市场导出**：需要全量数据做研究时用 CLI Market Dumps，大结果落盘，避免上下文过载 + +## 6. 实测验证记录（2026-08-22） + +```json +{"thscode":"600519.SH","ticker":"600519","volume":3347231,"turnover":4278311000, + "last_price":1272.83,"price_change":-18.67,"price_change_ratio_pct":-1.445606, + "open_price":1291.5,"high_price":1291.5,"low_price":1272.01,"prev_price":1291.5} +``` + +- ✅ auth login：`{"ok":true,"method":"api-key","configured":true}` +- ✅ capabilities：symbol.search / market.snapshot / market.history / financials.* 等全量可用 +- ✅ 查询：贵州茅台 600519.SH 实时快照正常返回（周六休市=周五收盘数据） + +## 7. 安全与合规提醒 + +- API Key 只存用户级凭据；不进代码、日志、公开配置、Git 仓库 +- Agent 交互时不得复述 Key；配置 Key 用 stdin 或环境变量 +- 数据仅用于研究/回测用途，遵守同花顺服务条款；不支持也不应伪造范围外数据（分钟K/tick/海外等）