Skip to content

Commit 9bbae84

Browse files
author
FutuAPI Developer
committed
docs: rewrite README with Skill-first guide, add skill/ directory
- README restructured: Skill (primary) > SDK > MCP Server - Add skill/ directory for easy installation via curl from GitHub - Include trigger words table, scheduled fetch setup, standalone usage - Update daily-snapshot cron to 20:00 Beijing time
1 parent b23682b commit 9bbae84

6 files changed

Lines changed: 646 additions & 143 deletions

File tree

‎.github/workflows/daily-snapshot.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ name: Daily Snapshot Update
22

33
on:
44
schedule:
5-
# 每天 UTC 12:30 = 北京时间 20:30（盘后数据更新后）
6-
- cron: '30 12 * * 1-5'
5+
# 每天 UTC 12:00 = 北京时间 20:00（盘后数据更新）
6+
- cron: '0 12 * * 1-5'
77
workflow_dispatch:
88

99
permissions:

‎README.md‎

Lines changed: 136 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,129 @@
1-
# hhxg — A 股日报快照 SDK
1+
# hhxg — A 股日报快照
22

3-
> 零配置、类型安全、AI 原生的 A 股市场数据 Python SDK
3+
> 零配置获取 A 股每日市场数据 — 赚钱效应、热门题材、连板天梯、游资龙虎榜、焦点新闻
44
5-
[![PyPI](https://img.shields.io/pypi/v/hhxg?color=blue)](https://pypi.org/project/hhxg/)
6-
[![Python](https://img.shields.io/pypi/pyversions/hhxg)](https://pypi.org/project/hhxg/)
75
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
8-
[![CI](https://github.com/hhxg-top/hhxg-python/actions/workflows/ci.yml/badge.svg)](https://github.com/hhxg-top/hhxg-python/actions)
6+
[![CI](https://github.com/Niceck/hhxg-top-hhxg-python/actions/workflows/ci.yml/badge.svg)](https://github.com/Niceck/hhxg-top-hhxg-python/actions)
7+
[![Daily Update](https://github.com/Niceck/hhxg-top-hhxg-python/actions/workflows/daily-snapshot.yml/badge.svg)](https://github.com/Niceck/hhxg-top-hhxg-python/actions)
98

109
---
1110

12-
## 为什么选 hhxg？
11+
## 三种使用方式
1312

14-
| 特性 | tushare | akshare | **hhxg** |
15-
|------|---------|---------|----------|
16-
| 需要注册 | 是（Token） | 否 | **否** |
17-
| 需要配置 | 是 | 否 | **否** |
18-
| 返回类型 | DataFrame | DataFrame | **Pydantic 模型** |
19-
| 类型提示 | 无 | 无 | **完整类型安全** |
20-
| AI 友好 | 否 | 否 | **MCP + GPT + SDK** |
21-
| 数据范围 | 全量历史 | 全量历史 | **日报快照** |
13+
| 方式 | 适用场景 | 需要安装 |
14+
|------|----------|----------|
15+
| **Claude Code Skill** | Claude Code / 小龙虾 CLI | 无需安装 |
16+
| **Python SDK** | 量化研究、数据分析 | `pip install hhxg` |
17+
| **MCP Server** | Claude Desktop / Cursor | `pip install hhxg[mcp]` |
2218

23-
**hhxg 的定位**：不追求全量历史数据，专注于**每日市场快照**——赚钱效应、热门题材、资金流向、连板天梯、游资龙虎榜、焦点新闻，一个函数调用获取全部。
19+
---
20+
21+
## 方式一：Claude Code Skill（推荐）
22+
23+
**零安装，复制即用。**
24+
25+
### 安装
26+
27+
```bash
28+
# 复制 skill 到 Claude Code skills 目录
29+
mkdir -p ~/.claude/skills/hhxg-market/scripts ~/.claude/skills/hhxg-market/references
30+
curl -sL https://raw.githubusercontent.com/Niceck/hhxg-top-hhxg-python/main/skill/SKILL.md \
31+
-o ~/.claude/skills/hhxg-market/SKILL.md
32+
curl -sL https://raw.githubusercontent.com/Niceck/hhxg-top-hhxg-python/main/skill/scripts/fetch_snapshot.py \
33+
-o ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py
34+
curl -sL https://raw.githubusercontent.com/Niceck/hhxg-top-hhxg-python/main/skill/references/data-schema.md \
35+
-o ~/.claude/skills/hhxg-market/references/data-schema.md
36+
curl -sL https://raw.githubusercontent.com/Niceck/hhxg-top-hhxg-python/main/skill/references/scheduled-fetch.md \
37+
-o ~/.claude/skills/hhxg-market/references/scheduled-fetch.md
38+
chmod +x ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py
39+
```
40+
41+
### 使用
42+
43+
安装后重启 Claude Code，直接对话即可：
44+
45+
```
46+
你：今天 A 股怎么样？
47+
你：热门题材有哪些？
48+
你：连板天梯
49+
你：龙虎榜游资动向
50+
你：/hhxg-market
51+
```
52+
53+
### 触发词
54+
55+
以下关键词会自动触发 skill：
56+
57+
| 类别 | 触发词 |
58+
|------|--------|
59+
| 大盘 | 今天 A 股怎么样、今天市场如何、大盘怎么样 |
60+
| 日报 | A 股日报、A 股复盘、盘后复盘、盘后总结 |
61+
| 情绪 | 市场情绪、赚钱效应、涨跌分布 |
62+
| 题材 | 热门题材、热门概念、主线题材 |
63+
| 连板 | 连板天梯、最高连板、涨停板、连板股 |
64+
| 游资 | 龙虎榜、游资动向、游资席位、知名游资 |
65+
| 资金 | 行业资金流向、板块资金、强势板块、弱势板块 |
66+
| 新闻 | 焦点新闻、市场新闻、今日要闻 |
67+
| 速览 | 股市快报、股市速递、市场快照、每日快报 |
68+
69+
### 独立使用脚本
70+
71+
不依赖 Claude Code，直接在终端运行（仅需 Python 3，无第三方依赖）：
72+
73+
```bash
74+
# 完整快照
75+
python3 ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py
76+
77+
# 只看特定板块
78+
python3 ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py market # 赚钱效应
79+
python3 ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py themes # 热门题材
80+
python3 ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py ladder # 连板天梯
81+
python3 ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py hotmoney # 游资龙虎榜
82+
python3 ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py sectors # 行业资金
83+
python3 ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py news # 焦点新闻
84+
```
85+
86+
### 定时获取（每日 20:00）
87+
88+
**macOS launchd：**
89+
90+
```bash
91+
cat > ~/Library/LaunchAgents/com.hhxg.snapshot.plist << 'EOF'
92+
<?xml version="1.0" encoding="UTF-8"?>
93+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
94+
<plist version="1.0">
95+
<dict>
96+
<key>Label</key>
97+
<string>com.hhxg.snapshot</string>
98+
<key>ProgramArguments</key>
99+
<array>
100+
<string>/usr/bin/python3</string>
101+
<string>~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py</string>
102+
</array>
103+
<key>StartCalendarInterval</key>
104+
<dict>
105+
<key>Hour</key>
106+
<integer>20</integer>
107+
<key>Minute</key>
108+
<integer>0</integer>
109+
</dict>
110+
<key>StandardOutPath</key>
111+
<string>/tmp/hhxg-snapshot.log</string>
112+
</dict>
113+
</plist>
114+
EOF
115+
launchctl load ~/Library/LaunchAgents/com.hhxg.snapshot.plist
116+
```
117+
118+
**cron：**
119+
120+
```bash
121+
(crontab -l 2>/dev/null; echo "0 20 * * 1-5 /usr/bin/python3 ~/.claude/skills/hhxg-market/scripts/fetch_snapshot.py > /tmp/hhxg-snapshot.log 2>&1") | crontab -
122+
```
24123

25124
---
26125

27-
## 30 秒上手
126+
## 方式二：Python SDK
28127

29128
```bash
30129
pip install hhxg
@@ -38,16 +137,7 @@ print(f"赚钱效应: {snapshot.market.sentiment_index}%")
38137
print(f"最高连板: {snapshot.ladder.top_streak.name} {snapshot.ladder.max_streak}板")
39138
```
40139

41-
输出：
42-
43-
```
44-
赚钱效应: 61.8%
45-
最高连板: 豫能控股 7板
46-
```
47-
48-
---
49-
50-
## 完整 API
140+
完整 API：
51141

52142
| 函数 | 返回类型 | 说明 |
53143
|------|----------|------|
@@ -59,29 +149,10 @@ print(f"最高连板: {snapshot.ladder.top_streak.name} {snapshot.ladder.max_str
59149
| `get_hotmoney()` | `Hotmoney` | 游资龙虎榜（含席位明细） |
60150
| `get_news()` | `list[NewsItem]` | 焦点新闻 |
61151

62-
所有函数零配置、开箱即用，返回 Pydantic 模型，IDE 自动补全。
63-
64-
---
65-
66-
## 数据内容
67-
68-
每日快照涵盖：
69-
70-
- **市场赚钱效应** — 情绪指数、涨跌家数分布、结构差值
71-
- **热门题材** — TOP 题材及涨停数、净流入、龙头股
72-
- **行业/板块资金** — 强势/弱势板块、净流入排名、领涨股
73-
- **连板天梯** — 各级连板股票、晋级率、地域/概念分布
74-
- **游资龙虎榜** — 净买入 TOP、知名游资席位操作明细
75-
- **焦点新闻** — 市场焦点 + 宏观新闻
76-
- **AI 摘要** — 一句话概括当日市场
77-
78-
---
79-
80-
## 搭配 Pandas
152+
搭配 Pandas：
81153

82154
```python
83-
import hhxg
84-
import pandas as pd
155+
import hhxg, pandas as pd
85156

86157
themes = hhxg.get_hot_themes()
87158
df = pd.DataFrame([
@@ -91,130 +162,54 @@ df = pd.DataFrame([
91162
print(df.to_string(index=False))
92163
```
93164

94-
```
95-
题材 涨停数 净流入(亿)
96-
绿色电力 16 0.22
97-
风电 16 8.17
98-
小金属概念 15 19.38
99-
昨日高振幅 14 30.84
100-
最近多板 13 13.80
101-
核电 11 4.18
102-
```
103-
104-
---
105-
106-
## 高级用法
107-
108-
### 自定义客户端
109-
110-
```python
111-
from hhxg import HhxgClient
112-
113-
client = HhxgClient(
114-
base_url="https://your-mirror.com/snapshot.json",
115-
timeout=30.0,
116-
)
117-
snapshot = client.get_snapshot()
118-
```
119-
120-
### 强制刷新缓存
121-
122-
```python
123-
from hhxg import HhxgClient
124-
125-
client = HhxgClient()
126-
snapshot = client.get_snapshot(force=True) # 跳过内存缓存
127-
```
128-
129165
---
130166

131-
## MCP Server — AI 工具直接调用
132-
133-
安装 MCP 依赖：
167+
## 方式三：MCP Server
134168

135169
```bash
136170
pip install hhxg[mcp]
137171
```
138172

139-
### Claude Desktop
140-
141-
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
173+
**Claude Desktop** — 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
142174

143175
```json
144-
{
145-
"mcpServers": {
146-
"hhxg": {
147-
"command": "hhxg-mcp"
148-
}
149-
}
150-
}
176+
{ "mcpServers": { "hhxg": { "command": "hhxg-mcp" } } }
151177
```
152178

153-
### Cursor
154-
155-
在 Cursor Settings > MCP 中添加：
156-
157-
```json
158-
{
159-
"mcpServers": {
160-
"hhxg": {
161-
"command": "hhxg-mcp"
162-
}
163-
}
164-
}
165-
```
179+
**Cursor** — Settings > MCP 添加同上配置。
166180

167-
### Claude Code
181+
**Claude Code：**
168182

169183
```bash
170184
claude mcp add hhxg hhxg-mcp
171185
```
172186

173-
### 可用 MCP 工具
174-
175-
| 工具 | 说明 |
176-
|------|------|
177-
| `get_snapshot` | 完整日报快照（最全面） |
178-
| `get_market` | 市场赚钱效应、涨跌分布 |
179-
| `get_hot_themes` | 热门题材及龙头股 |
180-
| `get_sectors` | 行业/板块资金流向 |
181-
| `get_ladder` | 连板天梯 |
182-
| `get_hotmoney` | 游资龙虎榜 |
183-
| `get_news` | 焦点新闻 |
184-
185-
配置完成后，直接对 AI 说「今天 A 股怎么样」「哪些题材最热」即可。
187+
配置完成后直接说「今天 A 股怎么样」即可。
186188

187189
---
188190

189-
## AI 生态联动
191+
## 数据内容
190192

191-
hhxg 是[恢恢量化](https://hhxg.top) AI 生态的一部分：
193+
每日快照涵盖 5000+ 只 A 股，交易日盘后 **20:00** 更新：
192194

193-
| 接入方式 | 适用场景 | 状态 |
194-
|----------|----------|------|
195-
| **Python SDK**（本项目） | 量化研究、数据分析 | ✅ 可用 |
196-
| **MCP Server**（本项目） | Claude Desktop / Cursor / Claude Code | ✅ 可用 |
197-
| **GPT Action** | ChatGPT 自定义 GPT | 🚧 开发中 |
195+
| 板块 | 内容 |
196+
|------|------|
197+
| 市场赚钱效应 | 情绪指数、涨跌家数分布、涨停/炸板/跌停、结构差值 |
198+
| 热门题材 | TOP 题材排行、涨停数、净流入、龙头股 |
199+
| 行业资金 | 强势/弱势板块、净流入排名、领涨股、偏离度 |
200+
| 连板天梯 | 各级连板股票、晋级率、地域分布、概念分布 |
201+
| 游资龙虎榜 | 净买入 TOP、知名游资席位操作明细 |
202+
| 焦点新闻 | 市场焦点 + 宏观新闻 |
198203

199204
---
200205

201206
## 数据来源
202207

203-
数据由 [恢恢量化](https://hhxg.top) 每日盘后更新，覆盖 5000+ 只 A 股。
208+
数据由 [恢恢量化](https://hhxg.top) 每日盘后更新。
204209

205210
> 数据仅供研究参考，不构成投资建议。
206211
207-
---
208-
209-
## 更多功能
210-
211-
SDK 提供每日市场快照数据。如需以下高级功能，请访问 [hhxg.top](https://hhxg.top)：
212-
213-
- 可视化图表与趋势分析
214-
- AI 多因子选股工具
215-
- ETF 资金流向筛选
216-
- 历史数据回溯
217-
- AI 智能问答
212+
如需可视化图表、AI 选股、历史回溯等高级功能，请访问 [hhxg.top](https://hhxg.top)。
218213

219214
---
220215

0 commit comments

Comments
 (0)