# kore-stock-analysis · 三种 Skills 详细使用说明

> 给 AI / 开发者消费的详细文档。三个 zip 是同源内容的不同封装：
> 1. **workbuddy-skill**（用户私有 skill 系统）2. **anthropic-skill**（Anthropic Claude Skills 标准）3. **cursor-rule**（Cursor .mdc 规则）

---

## 0. 通用信息（所有 skill 共享）

| 项 | 值 |
|---|---|
| Base URL | `https://sj.139.ink` |
| Swagger UI | `https://sj.139.ink/docs` |
| OpenAPI JSON | `https://sj.139.ink/openapi.json`（可下载到本地）|
| 鉴权头 | `X-API-Key: <key>`（无 key 仍可调，限速 100 次/分） |
| 测试 key | `GET /api/test_key`（公开，每日 50 次，0 点重置） |
| 正式 key | 100 次/分（`history/*` 为 30 次/分） |
| 接口总数 | 241（OpenAPI 抓出 255 paths / 259 endpoints） |
| 数据来源 | KPL 开盘啦 (longhuvip.com) + 东财快照 + TDX 板块库 |
| 免责声明 | ⚠ 非交易通道，所有输出仅供研究参考，不构成投资建议 |

### 触发词（所有 skill 通用）

```
股票分析、行情、K线、主力资金、四象限、涨停、打板、
题材板块、龙虎榜、市场情绪、出票、选股
```

### 共同客户端

`scripts/kore_api.py`（零依赖，仅标准库）：

```bash
python kore_api.py quote 600519              # 单股行情
python kore_api.py snapshot 1.600519         # 东财快照（量比换手）；secid: 沪=1. 深=0.
python kore_api.py flow 600519               # 主力净流入（net_inflow_wan 单位：万）
python kore_api.py quadrant 600519           # 四象限 A主升 / C出货 等
python kore_api.py kline 1.600519 101 20260801 20260926 1   # 历史K
# klt: 101日/102周/103月 | fqt: 0不复权/1前复权/2后复权
python kore_api.py chart 600519 day 60       # KPL K线（注意核对返回区间）
python kore_api.py mood                      # 市场情绪
python kore_api.py plates                    # 板块实时排名
python kore_api.py tianti                    # 涨停天梯（连板高度）
python kore_api.py daban                     # 打板聚合概览
python kore_api.py topic 5                   # 明天炒什么
python kore_api.py today                     # 当日出票
python kore_api.py gene 600519               # 个股涨停基因
python kore_api.py concept 600519            # 个股所属概念
python kore_api.py info 600519               # 股票基本信息
python kore_api.py search "储能"             # 综合搜索
python kore_api.py raw /api/kpl/daban/zt_reason  # 任意接口透传
```

---

## 1. workbuddy-skill（用户私有 skill 系统）

**zip**: `workbuddy-package.zip` · 48 KB

### 安装

```powershell
# Windows PowerShell
$workbuddySkills = "$env:USERPROFILE\.workbuddy\skills"
New-Item -ItemType Directory -Path $workbuddySkills -Force
Expand-Archive "D:\cf\workbuddy-package.zip" -DestinationPath $workbuddySkills

# macOS / Linux
mkdir -p ~/.workbuddy/skills
unzip workbuddy-package.zip -d ~/.workbuddy/skills/
```

### 目录结构

```
~/.workbuddy/skills/
├── kore-stock-analysis/
│   ├── SKILL.md          # AI 读取此文件（frontmatter + 详细说明）
│   ├── LICENSE.txt       # MIT
│   ├── .cursor-rule.mdc  # 同内容的 Cursor 格式
│   └── scripts/
│       └── kore_api.py   # Python 客户端
├── kore-market-openapi.json   # 机器可读接口定义
├── API_STOCK_ANALYSIS.md     # 速查手册
└── README.md                  # 包说明
```

### 用法（workbuddy 自动加载）

1. 启动 workbuddy → AI 自动发现 `kore-stock-analysis/SKILL.md`
2. 在 workbuddy 中说"分析贵州茅台" → AI 加载 skill → 按 SKILL.md 的"五步法"组织调用
3. AI 调用 `kore_api.py quote 600519` 拿数据
4. 返回结构化分析

### Python 调用（脚本直接用）

```python
import sys
sys.path.insert(0, "/path/to/skills/kore-stock-analysis/scripts")
import kore_api

print(kore_api.quote("600519"))      # 行情
print(kore_api.quadrant("600519"))   # 四象限
print(kore_api.flow("600519"))        # 资金流
```

---

## 2. anthropic-skill（Anthropic Claude Skills 标准）

**zip**: `anthropic-skill.zip` · 44 KB · 符合 [anthropics/skills](https://github.com/anthropics/skills) 规范

### 安装

#### A. Claude.ai（网页，零代码）

1. 解压 zip（保持目录结构）
2. 打开 https://claude.ai → Settings → Capabilities → Skills
3. 点 "Upload custom skill"
4. 选择解压后的 `kore-stock-analysis/` 文件夹

#### B. Claude Code（CLI，推荐）

```bash
# macOS / Linux
mkdir -p ~/.claude/skills
unzip anthropic-skill.zip -d ~/.claude/skills/

# Windows
mkdir "$env:USERPROFILE\.claude\skills" -Force
Expand-Archive anthropic-skill.zip -DestinationPath "$env:USERPROFILE\.claude\skills\"

# 重启 Claude Code
# 触发："查贵州茅台的实时行情" / "分析一下 600519"
```

#### C. Claude API（开发者）

参考 https://docs.claude.com/en/api/skills-guide#creating-a-skill

### 文件结构

```
kore-stock-analysis/            # skill 根目录
├── SKILL.md                    # 必填（YAML frontmatter + 指令）
├── LICENSE.txt                 # 可选（MIT 含免责声明）
├── scripts/
│   └── kore_api.py            # 可选资源（CLI 客户端）
├── kore-market-openapi.json   # 配套（AI 可直接消费）
├── API_STOCK_ANALYSIS.md      # 配套（速查）
└── INSTALL.md                  # 安装说明
```

### SKILL.md frontmatter 要求

```yaml
---
name: kore-stock-analysis            # 必填（小写 + hyphens）
description: |                       # 必填（描述何时触发）
  A股/股票数据分析取数技能...
  触发词：股票分析、行情、K线、主力资金、四象限、涨停、打板、题材板块...
---
# Skill Name
[Markdown 指令]
```

### AI 行为

加载后 AI 会：
1. 读 `SKILL.md` 了解调用约定 + 触发词
2. 用户说"分析 XX"时，AI 按"五步法"组织调用
3. 调 `kore_api.py`（或用 `kore-market-openapi.json` 直接 curl）
4. 输出结构化分析

---

## 3. cursor-rule（Cursor .mdc 规则格式）

**zip**: `cursor-skill.zip` · 40 KB

### 安装

```bash
# 1) 解压
unzip cursor-skill.zip
# 或 Windows: Expand-Archive cursor-skill.zip

# 2) 把 .cursor/ 复制到你的项目根
cp -r .cursor/ /path/to/your/project/

# 3) 配套脚本（可选）
cp -r scripts/ /path/to/your/project/skills/kore-stock-analysis/
```

### 文件结构

```
your-project/
├── .cursor/
│   └── rules/
│       └── kore-stock-analysis.mdc   # Cursor 规则
├── skills/kore-stock-analysis/
│   └── scripts/kore_api.py
└── kore-market-openapi.json   # 可选
```

### .mdc 格式

```markdown
---
description: A股/股票数据分析取数技能——调用智核API (kore-market) 替代通达信接口。触发词：...
globs:
  - "**/*.py"
alwaysApply: false
---

[Markdown 指令]
```

### Cursor 用法

1. 重启 Cursor → 自动加载 `.cursor/rules/kore-stock-analysis.mdc`
2. 在 Cursor Chat (Cmd/Ctrl+L) 说："股票分析 600519"
3. Cursor 应用 rule：优先用 kore_api.py 调数据，不用 tdx-connector
4. 调 `python kore_api.py quote 600519` 拿数据
5. 输出分析

### globs 行为

- `globs: ["**/*.py"]` → 只在编辑 Python 文件时**自动应用**（不自动，需触发词）
- `globs: ["**/*.md"]` → 编辑 markdown 也自动应用
- `alwaysApply: false` → 不默认加载，按需触发
- `alwaysApply: true` → 总是自动应用（不推荐，会消耗 token）

---

## 4. OpenAPI 机器可读（额外）

**OpenAPI JSON**: `kore-market-openapi.json` · 396 KB

### 内容

- **OpenAPI 3.1.0** · 255 paths / 259 endpoints
- **info**: title `智核API · 241 接口` · version `1.0.6`
- **servers**: `https://sj.139.ink`
- **securitySchemes**: `APIKeyHeader` (X-API-Key)
- **32 个 tags**: 📊 个股盘口 / 📈 东财快照 / 🎯 打板 / 🌐 市场全景 / 💰 资金面 / 🐉 龙虎榜 / 🔍 选股 / 🎯 四象限 ...

### 喂给 AI 直接用

把 `kore-market-openapi.json` 丢给任意 AI（GPT-4 / Claude / Gemini / Cursor Composer / OpenAI o1 / DeepSeek ...）：

```
"This is the OpenAPI spec for a stock data API. Use X-API-Key auth.
Get a test key from GET /api/test_key (50/day).
Help me analyze 600519: get quote + quadrant + fund_flow + kline for last 30 days."
```

AI 能直接读懂 schema，组织调用。

### 编程方式

```python
import json, urllib.request
spec = json.load(urllib.request.urlopen("https://sj.139.ink/openapi.json"))

# 列出所有路径
for path, ops in spec["paths"].items():
    for method in ("get", "post", "put", "delete"):
        if method in ops:
            print(f"{method.upper():6s} {path}  — {ops[method].get('summary', '')}")
```

---

## 5. 五步法（标准分析流程）

**所有 skill 都按这个调用链组织**：

```
1. 看情绪
   market_mood              # 整体情绪（贪婪/恐惧）
   → daban/zdt_count        # 涨跌停数
   → daban/zhang_ting_tianti  # 连板高度

2. 找方向
   plate_ranking_realtime   # 板块涨幅排名
   → tdx/dc_concept         # 题材热度 + 主力净流入
   → tomorrow_topic         # 明天炒什么

3. 选个股
   today_stocks             # 当日出票
   → search_tuyere          # 风口
   → daban/zt_reason        # 涨停原因

4. 验个股
   quote + snapshot         # 价/量/换手
   → fund_flow              # 主力净流入
   → quadrant_judge         # A/B/C/D 象限
   → stock_zt_gene          # 涨停基因

5. 看历史
   eastmoney/kline          # 历史 K（区间+复权可控）
   → history/his_* 系列     # 30 次/分限速
```

---

## 6. 关键坑（必看）

1. **`/api/kpl/kline_history` 的 count 从历史起点取数**（600519 → 2022 年起）→ 近期 K 线用 `eastmoney/kline`（区间+复权可控）或 `stock_chart` 并核对返回区间
2. **KPL 上游转发偶发 HTTP 000** → 重试即可；脚本内置重试 + 45s 超时
3. **测试 key 每日仅 50 次**：批量分析先规划调用数；正式 key 100 次/分
4. **`eastmoney/snapshot` 的 secid 格式**：沪市前缀 `1.`，深市前缀 `0.`（如 `1.600519`、`0.300750`）
5. **DC 题材库数据从 20260203 起**；`/api/kpl/daban/*` 在非交易时段返回最近交易日数据
6. **`fund_flow` 返回 `net_inflow_wan`（zhuli_in/out/net）单位为万**，分钟级 241 个采样点

---

## 7. 安全

- **X-API-Key 头**在 HTTP header，**不在 URL**（避免日志泄漏）
- 测试 key 公开可领（每日 50 次）
- 生产用正式 key（限速 100 次/分）
- 任何 401/403/429 错误**停止重试**，避免浪费配额

---

## 8. 数据下载 + 服务

- **Skills 下载页**: `https://sj.139.ink/static/skills/`
- **OpenAPI JSON**: `https://sj.139.ink/openapi.json`
- **Swagger UI**: `https://sj.139.ink/docs`
- **健康检查**: `https://sj.139.ink/health`

---

## 9. 已知限制

- 测试 key 每日 50 次（生产用正式 key）
- `fund_flow` 只能查**最近交易日的分钟级**，历史分钟数据需 `history/his_*`（30 次/分）
- DC 题材库 20260203 之前无数据
- `daban/*` 非交易时段返回最近交易日
- 部分 KPL 上游转发偶发连接中断（HTTP 000）→ 重试

---

## 10. 版本

- **API 版本**: v1.0.6（2026-09-26）
- **Skills 包版本**: v1.0.0（2026-09-26）
- **OpenAPI 规范版本**: 3.1.0