# DataBull 金融数据Skill

**Repository Path**: yc-chan/databull-skill

## Basic Information

- **Project Name**: DataBull 金融数据Skill
- **Description**: 让 AI Agent 一句话查询中国资本市场数据的技能（Skill）：A 股 / ETF / 指数 / 港股美股行情、财经快讯、板块涨跌、实时 Tick、交易日历，全部通过 DataBull 对外 REST API 提供。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://www.databull.cn/
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DataBull 金融数据 Skill

让 AI Agent 一句话查询中国资本市场数据的技能（Skill）：**A 股 / ETF / 指数 / 港股美股行情、财经快讯、板块涨跌、实时 Tick、交易日历**，全部通过 [DataBull](https://www.databull.cn) 对外 REST API 提供。

适用于 Claude Code、Cursor、WorkBuddy 等支持 Agent Skills 的编程助手——安装后直接用自然语言提问即可，例如：

> 「查一下平安银行最近一个月的日线」
> 「申万一级行业今天哪些涨得最好」
> 「列出所有名字带『新能源』的 ETF」

## 仓库结构

```
.
├── SKILL.md             # 技能说明文件（Agent 读取的入口）
├── databull_client.py   # 参考客户端：25 个 REST 端点 + 5 个 MCP 工具的 Python 封装
├── install.sh           # 一键安装脚本
├── _icon.png            # 技能图标
└── LICENSE              # Apache License 2.0
```

## 安装

### 1. 获取 API Key

所有数据端点需鉴权（`Authorization: Bearer <Key>` 或等价的 `X-API-Key`）。
免费注册即得 Key：**https://www.databull.cn/console/register**

免费档 **100 次/天**；超限返回 `429`，响应头带 `Retry-After`。

### 2. 一键安装（推荐）

```bash
curl -fsSL "https://www.databull.cn/skill/install" | bash
```

脚本会把 `SKILL.md` 和 `databull_client.py` 下载到当前目录的 `.claude/skills/databull/` 下。

### 3. 手动安装

把以下两个文件下载到 Agent 技能目录（如 Claude Code 的 `.claude/skills/databull/`，WorkBuddy 的 `~/.workbuddy/skills/databull-data/`）：

- https://www.databull.cn/skill/files/SKILL.md
- https://www.databull.cn/skill/files/databull_client.py

### 4. 配置环境变量

```bash
export DATABULL_API_KEY="your_api_key_here"
```

## 使用

### 方式一：在 Agent 里用自然语言提问（零代码）

安装技能后，直接对 Agent 说：

- 「贵州茅台（600519）最近的市盈率是多少」
- 「上证综指最近半年的走势」
- 「拉一下最新的财经快讯」

### 方式二：Python 客户端

依赖：Python 3.8+，`requests`（可选 `pandas`，仅行情类方法返回 DataFrame 时需要）。

```python
from databull_client import DataBull

db = DataBull()  # 自动读取 DATABULL_API_KEY

# 平安银行最近一个月日线（个股用裸代码，不带 .SZ）
df = db.get_stock_history("000001", "2026-08-21", "2026-09-21")
print(df.tail())

# 申万一级行业今日涨跌
data = db.get_sector_data("sw1")

# 财经快讯
flash = db.get_news_flash(limit=5)
```

### 方式三：命令行（一次性 JSON 查询）

```bash
export DATABULL_API_KEY="your_api_key_here"
python databull_client.py cn/stock/info --params '{"symbol": "000001"}'
python databull_client.py cn/index/history --params '{"index_code": "000001", "start_date": "2026-01-01", "end_date": "2026-09-21"}'
python databull_client.py cn/market/sector_data/sw1
```

出错时非零退出并在 stderr 打印 `DataBullError`，便于脚本化处理。

## 可用端点（25 个 REST + 5 个 MCP，均已生产验证）

| 分类 | 客户端方法 | API 路径 |
| --- | --- | --- |
| 指数 | `get_index_history()` | `GET /cn/index/history` |
| A股清单 | `get_stock_list()` | `GET /cn/stocks` |
| 个股信息 | `get_stock_info()` | `GET /cn/stock/info` |
| 公司简介 | `get_company_profile()` | `GET /cn/stock/profile` |
| 个股历史行情 | `get_stock_history()` | `GET /cn/stock/history` |
| 个股财报 | `get_stock_financial_data()` | `GET /cn/stock/financial_data` |
| 美股信息 / 行情 | `get_us_stock_info()` / `get_us_stock_history()` | `GET /us/stock/info` / `GET /us/stock/history` |
| 港股信息 / 行情 | `get_hk_stock_info()` / `get_hk_stock_history()` | `GET /hk/stock/info` / `GET /hk/stock/history` |
| ETF | `get_etf_list()` / `get_etf_info()` / `get_etf_pcf()` / `get_etf_composition()` / `get_etf_history()` | `GET /cn/etfs`、`/cn/etfs/info`、`/cn/etfs/etf_pcf`、`/cn/etfs/etf_composition`、`/cn/etf/history` |
| 财经快讯 | `get_news_flash()` / `get_news_flash_sources()` | `GET /v2/news/flash`、`GET /v2/news/flash/sources` |
| 市场新闻 | `get_market_news()` / `get_market_news_detail()` | `GET /cn/market/news`、`GET /cn/market/news/{news_id}` |
| 恐惧与贪婪指数 | `get_fear_greed()` | `GET /cn/market/fear_greed` |
| 申万板块 | `get_sector_data()` / `get_sector_catalog()` | `GET /cn/market/sector_data/{type}`、`GET /cn/market/sector_catalog/{type}` |
| 实时 Tick | `get_realtime()` / `get_tick_all()` | `GET /cn/stock/tick`、`GET /cn/tick/tickall` |
| 交易日历 | `get_trading_calendar()` | `GET /cn/tick/trading_calendar` |

5 个 MCP 工具（`get_stock_list` / `get_stock_detail` / `get_stock_history` / `get_index_history` / `get_financial_data`）经 `client.call_mcp_tool(name, params)` 调用，托管在 `POST /mcp/call`。

> ⚠️ 官网早期营销页还列过 moneyflow / margin / concepts / limit_list / northbound_holdings 等约 30 个方法，**当前没有对应后端路由**，请勿调用，视为 roadmap。

## 注意事项

### ⚠️ 代码必须用裸代码，不带交易所后缀

DataBull **所有**代码参数（`symbol` / `index_code`）都要求裸代码，市场由 URL 路径决定（`/cn`、`/us`、`/hk`）：

- ✅ 正确：`000001`（平安银行）、`600519`（茅台）、`510300`（沪深300ETF）、`AAPL`、`00700`（港股）
- ❌ 错误：`000001.SZ`、`600519.SH` —— 个股会返回 `400 Bad Request`；
  **指数传 `000001.SH` 不报错但静默返回空数组**，比 400 更隐蔽，容易误判成「没数据」。

客户端已内置 `_normalize_symbol` 自动剥掉尾部 `.SZ/.SH/.BJ/.SS`（保留美股 `BRK.B` 里的点），但写代码时请务必用裸代码。

### 空结果怎么看

接口在「没有数据」时返回空数组/空对象而不是报错，但会附带**空原因**：

- 数组型响应：看响应头 `X-Empty-Reason`（如 `index_not_found`、`no_data_in_range`、`tick_not_uploaded`）；
- 对象型响应：看体内 `empty_reason`（如 `catalog_not_synced`）；
- 客户端会把最近一次的空原因记在 `client.last_empty_reason` 上。

### 常见错误码

| 状态码 | 含义 | 处理 |
| --- | --- | --- |
| `401` | 缺少/无效 Key | 检查 `DATABULL_API_KEY` |
| `400` | 参数非法（如代码带后缀、`sector_type` 非 sw1/sw2/sw3） | 核对参数 |
| `429` | 超配额（免费档 100 次/天） | 读 `Retry-After` 退避 |
| `5xx` | 服务端错误 | 客户端已内置指数退避重试 |

## 参与贡献

1. Fork 本仓库
2. 新建 `feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request

## 许可证

[Apache License 2.0](./LICENSE)