@kg-ai/kugou-skill 0.1.8 → 0.1.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +198 -198
- package/SKILL.md +246 -223
- package/bin/darwin-arm64/kugou-cli +0 -0
- package/bin/darwin-x64/kugou-cli +0 -0
- package/bin/linux-arm64/kugou-cli +0 -0
- package/bin/linux-x64/kugou-cli +0 -0
- package/bin/win32-x64/kugou-cli.exe +0 -0
- package/package.json +1 -1
- package/references/control.md +676 -680
- package/references/error-handling.md +22 -22
- package/references/music.md +526 -526
package/README.md
CHANGED
|
@@ -1,198 +1,198 @@
|
|
|
1
|
-
# Kugou CLI
|
|
2
|
-
|
|
3
|
-
酷狗音乐 API CLI 工具，用于搜索、推荐、收藏、统计、榜单等功能。
|
|
4
|
-
|
|
5
|
-
## 安装
|
|
6
|
-
|
|
7
|
-
### npm 安装（推荐）
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
npm install -g @kg-ai/kugou-skill
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
安装后使用 `kugou-cli` 命令。npm 安装时会自动安装 SKILL.md 到各平台的 skills 目录。
|
|
14
|
-
|
|
15
|
-
## 前置条件
|
|
16
|
-
|
|
17
|
-
使用前需要扫码登录（极简流程）：
|
|
18
|
-
|
|
19
|
-
```bash
|
|
20
|
-
# Step 1: 获取二维码图片
|
|
21
|
-
kugou-cli auth login
|
|
22
|
-
|
|
23
|
-
# Step 2: 循环检查登录状态（单次查询不内部轮询，agent 外层循环直到 logged_in=true）
|
|
24
|
-
kugou-cli auth status
|
|
25
|
-
|
|
26
|
-
> 必须将 Step 1 输出中 `qrcode_img_url` 渲染给用户扫码（用 ``）。token 会自动持久化存储。
|
|
27
|
-
> `auth status` 是单次查询，调用方需在外层循环（2-3 秒间隔）直到 `logged_in=true`；不要等"内部已轮询"——根本不会自动轮询。
|
|
28
|
-
|
|
29
|
-
## 命令
|
|
30
|
-
|
|
31
|
-
### 认证
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
# 获取二维码图片
|
|
35
|
-
kugou-cli auth login
|
|
36
|
-
|
|
37
|
-
# 检查登录状态（单次查询，不内部轮询；agent 需外层循环 2-3s 间隔）
|
|
38
|
-
kugou-cli auth status
|
|
39
|
-
|
|
40
|
-
# 登出
|
|
41
|
-
kugou-cli auth logout
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
### 音乐
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
# 搜索歌曲
|
|
48
|
-
kugou-cli music search "周杰伦"
|
|
49
|
-
kugou-cli music search "周杰伦" --page 1 --size 20
|
|
50
|
-
|
|
51
|
-
# 猜你喜欢
|
|
52
|
-
kugou-cli music recommend guess
|
|
53
|
-
kugou-cli music recommend guess --num 10
|
|
54
|
-
|
|
55
|
-
# 相似推荐（需要指定歌曲）
|
|
56
|
-
kugou-cli music recommend similar --song "晴天"
|
|
57
|
-
kugou-cli music recommend similar -s "晴天" -n 5
|
|
58
|
-
|
|
59
|
-
# 我的收藏（上游固定返回最近 10 首，不支持分页）
|
|
60
|
-
kugou-cli music favorites
|
|
61
|
-
|
|
62
|
-
# 最近播放（上游固定返回最近 10 条，不支持分页）
|
|
63
|
-
kugou-cli music recent
|
|
64
|
-
|
|
65
|
-
# 听歌统计
|
|
66
|
-
kugou-cli music stats
|
|
67
|
-
|
|
68
|
-
# 酷狗榜单
|
|
69
|
-
kugou-cli music charts 6666 # 飙升榜
|
|
70
|
-
kugou-cli music charts 8888 # TOP500榜
|
|
71
|
-
kugou-cli music charts 52144 # 抖音热歌酷狗榜
|
|
72
|
-
kugou-cli music charts 90379 # 星耀星光榜
|
|
73
|
-
kugou-cli music charts 85432 # 百万收藏榜
|
|
74
|
-
kugou-cli music charts 74534 # 新歌榜
|
|
75
|
-
|
|
76
|
-
# 创建歌单
|
|
77
|
-
# ⚠️ 默认走客户端路径：kugou-cli control playlist create（见下方"控制"节）
|
|
78
|
-
# 客户端不可用时才回退到云端：
|
|
79
|
-
kugou-cli music create-playlist "我的空歌单"
|
|
80
|
-
kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
|
|
81
|
-
|
|
82
|
-
# 搜索歌单
|
|
83
|
-
kugou-cli music search-playlist "周杰伦"
|
|
84
|
-
kugou-cli music search-playlist "跑步" --filter 1
|
|
85
|
-
|
|
86
|
-
# 歌单推荐
|
|
87
|
-
kugou-cli music recommend-playlist
|
|
88
|
-
kugou-cli music recommend-playlist --module-id 6
|
|
89
|
-
|
|
90
|
-
# 歌单内歌曲列表
|
|
91
|
-
kugou-cli music playlist-songs "collection_3_938985631_304_0"
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
### 安装 SKILL.md
|
|
95
|
-
|
|
96
|
-
```bash
|
|
97
|
-
# 安装到所有平台
|
|
98
|
-
kugou-cli install --all
|
|
99
|
-
|
|
100
|
-
# 安装到指定平台
|
|
101
|
-
kugou-cli install --claude
|
|
102
|
-
kugou-cli install --mavis
|
|
103
|
-
kugou-cli install --hermes --openclaw --codex
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
### 控制 PC/Mac 酷狗客户端
|
|
107
|
-
|
|
108
|
-
通过本机 HTTP 服务控制本地酷狗桌面客户端（播放、暂停、收藏、创建歌单等）。仅支持 macOS 和 Windows，Linux 不支持。
|
|
109
|
-
|
|
110
|
-
**前置条件**：需先完成 CLI 登录（`kugou-cli auth login`）且酷狗客户端在后台运行。
|
|
111
|
-
|
|
112
|
-
**子命令列表**：
|
|
113
|
-
|
|
114
|
-
| 子命令 | 说明 |
|
|
115
|
-
|--------|------|
|
|
116
|
-
| `start` | 触发 URL-scheme 握手，预热通道 |
|
|
117
|
-
| `status` | 获取客户端状态 |
|
|
118
|
-
| `current` | 获取当前播放曲目 |
|
|
119
|
-
| `play` | 播放指定歌曲 |
|
|
120
|
-
| `play-playlist` | 播放整个歌单（按 global_collection_id） |
|
|
121
|
-
| `player` | 控制播放（播放/暂停/切歌等） |
|
|
122
|
-
| `seek` | 跳转或快进/快退播放位置 |
|
|
123
|
-
| `volume` | 调节音量或静音 |
|
|
124
|
-
| `continue-play` | 拉取"另一设备续播"列表并开始播放 |
|
|
125
|
-
| `favorite song` | 收藏/取消收藏歌曲 |
|
|
126
|
-
| `favorite songlist` | 收藏/取消收藏歌单 |
|
|
127
|
-
| `playlist create` | 在客户端创建新歌单 |
|
|
128
|
-
| `open` | 在客户端内打开页面（搜索/歌手/专辑等） |
|
|
129
|
-
|
|
130
|
-
**示例**：
|
|
131
|
-
|
|
132
|
-
```bash
|
|
133
|
-
# 预热握手（首次使用前建议执行）
|
|
134
|
-
kugou-cli control start
|
|
135
|
-
|
|
136
|
-
# 播放歌曲
|
|
137
|
-
kugou-cli control play --mixsongid 32100650 --song-name "晴天" --singer-name "周杰伦"
|
|
138
|
-
|
|
139
|
-
# 播放整个歌单
|
|
140
|
-
kugou-cli control play-playlist --global-id "collection_3_938985631_304_0"
|
|
141
|
-
|
|
142
|
-
# 收藏歌曲
|
|
143
|
-
kugou-cli control favorite song --mixsongid 32100650
|
|
144
|
-
|
|
145
|
-
# 创建歌单
|
|
146
|
-
kugou-cli control playlist create --name "精选" --mixsongids "32100650,32068120"
|
|
147
|
-
|
|
148
|
-
# 在客户端内打开搜索页面
|
|
149
|
-
kugou-cli control open --target-type search --keyword "周杰伦"
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
完整命令文档见 `references/control.md`。
|
|
153
|
-
|
|
154
|
-
### 全局
|
|
155
|
-
|
|
156
|
-
```bash
|
|
157
|
-
kugou-cli --version
|
|
158
|
-
kugou-cli --help
|
|
159
|
-
|
|
160
|
-
# 检查更新
|
|
161
|
-
kugou-cli update --check
|
|
162
|
-
|
|
163
|
-
# 更新（仅 npm 安装支持）
|
|
164
|
-
kugou-cli update --force
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
## 输出格式
|
|
168
|
-
|
|
169
|
-
所有命令输出 JSON 格式，方便其他程序调用：
|
|
170
|
-
|
|
171
|
-
```json
|
|
172
|
-
{
|
|
173
|
-
"errcode": 0,
|
|
174
|
-
"data": {
|
|
175
|
-
"list": [
|
|
176
|
-
{
|
|
177
|
-
"song_name": "晴天",
|
|
178
|
-
"mix_song_id": "32100650",
|
|
179
|
-
"artist_name": "周杰伦",
|
|
180
|
-
"play_link": "https://www.kugou.com/mixsong/agent_gateway/xxx.html"
|
|
181
|
-
}
|
|
182
|
-
],
|
|
183
|
-
"total": 480,
|
|
184
|
-
"page": 1,
|
|
185
|
-
"size": 20
|
|
186
|
-
},
|
|
187
|
-
"status": 1
|
|
188
|
-
}
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
## 错误处理
|
|
192
|
-
|
|
193
|
-
错误信息输出到 stderr，程序 exit code 为 1：
|
|
194
|
-
|
|
195
|
-
```bash
|
|
196
|
-
kugou-cli music search "xxx" 2>&1
|
|
197
|
-
echo $? # 非 0 表示出错
|
|
198
|
-
```
|
|
1
|
+
# Kugou CLI
|
|
2
|
+
|
|
3
|
+
酷狗音乐 API CLI 工具，用于搜索、推荐、收藏、统计、榜单等功能。
|
|
4
|
+
|
|
5
|
+
## 安装
|
|
6
|
+
|
|
7
|
+
### npm 安装（推荐）
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install -g @kg-ai/kugou-skill
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
安装后使用 `kugou-cli` 命令。npm 安装时会自动安装 SKILL.md 到各平台的 skills 目录。
|
|
14
|
+
|
|
15
|
+
## 前置条件
|
|
16
|
+
|
|
17
|
+
使用前需要扫码登录（极简流程）：
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
# Step 1: 获取二维码图片
|
|
21
|
+
kugou-cli auth login
|
|
22
|
+
|
|
23
|
+
# Step 2: 循环检查登录状态（单次查询不内部轮询，agent 外层循环直到 logged_in=true）
|
|
24
|
+
kugou-cli auth status
|
|
25
|
+
|
|
26
|
+
> 必须将 Step 1 输出中 `qrcode_img_url` 渲染给用户扫码（用 ``）。token 会自动持久化存储。
|
|
27
|
+
> `auth status` 是单次查询，调用方需在外层循环（2-3 秒间隔）直到 `logged_in=true`；不要等"内部已轮询"——根本不会自动轮询。
|
|
28
|
+
|
|
29
|
+
## 命令
|
|
30
|
+
|
|
31
|
+
### 认证
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# 获取二维码图片
|
|
35
|
+
kugou-cli auth login
|
|
36
|
+
|
|
37
|
+
# 检查登录状态（单次查询，不内部轮询；agent 需外层循环 2-3s 间隔）
|
|
38
|
+
kugou-cli auth status
|
|
39
|
+
|
|
40
|
+
# 登出
|
|
41
|
+
kugou-cli auth logout
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### 音乐
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# 搜索歌曲
|
|
48
|
+
kugou-cli music search "周杰伦"
|
|
49
|
+
kugou-cli music search "周杰伦" --page 1 --size 20
|
|
50
|
+
|
|
51
|
+
# 猜你喜欢
|
|
52
|
+
kugou-cli music recommend guess
|
|
53
|
+
kugou-cli music recommend guess --num 10
|
|
54
|
+
|
|
55
|
+
# 相似推荐（需要指定歌曲）
|
|
56
|
+
kugou-cli music recommend similar --song "晴天"
|
|
57
|
+
kugou-cli music recommend similar -s "晴天" -n 5
|
|
58
|
+
|
|
59
|
+
# 我的收藏（上游固定返回最近 10 首，不支持分页）
|
|
60
|
+
kugou-cli music favorites
|
|
61
|
+
|
|
62
|
+
# 最近播放（上游固定返回最近 10 条，不支持分页）
|
|
63
|
+
kugou-cli music recent
|
|
64
|
+
|
|
65
|
+
# 听歌统计
|
|
66
|
+
kugou-cli music stats
|
|
67
|
+
|
|
68
|
+
# 酷狗榜单
|
|
69
|
+
kugou-cli music charts 6666 # 飙升榜
|
|
70
|
+
kugou-cli music charts 8888 # TOP500榜
|
|
71
|
+
kugou-cli music charts 52144 # 抖音热歌酷狗榜
|
|
72
|
+
kugou-cli music charts 90379 # 星耀星光榜
|
|
73
|
+
kugou-cli music charts 85432 # 百万收藏榜
|
|
74
|
+
kugou-cli music charts 74534 # 新歌榜
|
|
75
|
+
|
|
76
|
+
# 创建歌单
|
|
77
|
+
# ⚠️ 默认走客户端路径：kugou-cli control playlist create（见下方"控制"节）
|
|
78
|
+
# 客户端不可用时才回退到云端：
|
|
79
|
+
kugou-cli music create-playlist "我的空歌单"
|
|
80
|
+
kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
|
|
81
|
+
|
|
82
|
+
# 搜索歌单
|
|
83
|
+
kugou-cli music search-playlist "周杰伦"
|
|
84
|
+
kugou-cli music search-playlist "跑步" --filter 1
|
|
85
|
+
|
|
86
|
+
# 歌单推荐
|
|
87
|
+
kugou-cli music recommend-playlist
|
|
88
|
+
kugou-cli music recommend-playlist --module-id 6
|
|
89
|
+
|
|
90
|
+
# 歌单内歌曲列表
|
|
91
|
+
kugou-cli music playlist-songs "collection_3_938985631_304_0"
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### 安装 SKILL.md
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
# 安装到所有平台
|
|
98
|
+
kugou-cli install --all
|
|
99
|
+
|
|
100
|
+
# 安装到指定平台
|
|
101
|
+
kugou-cli install --claude
|
|
102
|
+
kugou-cli install --mavis
|
|
103
|
+
kugou-cli install --hermes --openclaw --codex
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### 控制 PC/Mac 酷狗客户端
|
|
107
|
+
|
|
108
|
+
通过本机 HTTP 服务控制本地酷狗桌面客户端（播放、暂停、收藏、创建歌单等）。仅支持 macOS 和 Windows，Linux 不支持。
|
|
109
|
+
|
|
110
|
+
**前置条件**：需先完成 CLI 登录（`kugou-cli auth login`）且酷狗客户端在后台运行。
|
|
111
|
+
|
|
112
|
+
**子命令列表**：
|
|
113
|
+
|
|
114
|
+
| 子命令 | 说明 |
|
|
115
|
+
|--------|------|
|
|
116
|
+
| `start` | 触发 URL-scheme 握手，预热通道 |
|
|
117
|
+
| `status` | 获取客户端状态 |
|
|
118
|
+
| `current` | 获取当前播放曲目 |
|
|
119
|
+
| `play` | 播放指定歌曲 |
|
|
120
|
+
| `play-playlist` | 播放整个歌单（按 global_collection_id） |
|
|
121
|
+
| `player` | 控制播放（播放/暂停/切歌等） |
|
|
122
|
+
| `seek` | 跳转或快进/快退播放位置 |
|
|
123
|
+
| `volume` | 调节音量或静音 |
|
|
124
|
+
| `continue-play` | 拉取"另一设备续播"列表并开始播放 |
|
|
125
|
+
| `favorite song` | 收藏/取消收藏歌曲 |
|
|
126
|
+
| `favorite songlist` | 收藏/取消收藏歌单 |
|
|
127
|
+
| `playlist create` | 在客户端创建新歌单 |
|
|
128
|
+
| `open` | 在客户端内打开页面（搜索/歌手/专辑等） |
|
|
129
|
+
|
|
130
|
+
**示例**：
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
# 预热握手（首次使用前建议执行）
|
|
134
|
+
kugou-cli control start
|
|
135
|
+
|
|
136
|
+
# 播放歌曲
|
|
137
|
+
kugou-cli control play --mixsongid 32100650 --song-name "晴天" --singer-name "周杰伦"
|
|
138
|
+
|
|
139
|
+
# 播放整个歌单
|
|
140
|
+
kugou-cli control play-playlist --global-id "collection_3_938985631_304_0"
|
|
141
|
+
|
|
142
|
+
# 收藏歌曲
|
|
143
|
+
kugou-cli control favorite song --mixsongid 32100650
|
|
144
|
+
|
|
145
|
+
# 创建歌单
|
|
146
|
+
kugou-cli control playlist create --name "精选" --mixsongids "32100650,32068120"
|
|
147
|
+
|
|
148
|
+
# 在客户端内打开搜索页面
|
|
149
|
+
kugou-cli control open --target-type search --keyword "周杰伦"
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
完整命令文档见 `references/control.md`。
|
|
153
|
+
|
|
154
|
+
### 全局
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
kugou-cli --version
|
|
158
|
+
kugou-cli --help
|
|
159
|
+
|
|
160
|
+
# 检查更新
|
|
161
|
+
kugou-cli update --check
|
|
162
|
+
|
|
163
|
+
# 更新（仅 npm 安装支持）
|
|
164
|
+
kugou-cli update --force
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## 输出格式
|
|
168
|
+
|
|
169
|
+
所有命令输出 JSON 格式，方便其他程序调用：
|
|
170
|
+
|
|
171
|
+
```json
|
|
172
|
+
{
|
|
173
|
+
"errcode": 0,
|
|
174
|
+
"data": {
|
|
175
|
+
"list": [
|
|
176
|
+
{
|
|
177
|
+
"song_name": "晴天",
|
|
178
|
+
"mix_song_id": "32100650",
|
|
179
|
+
"artist_name": "周杰伦",
|
|
180
|
+
"play_link": "https://www.kugou.com/mixsong/agent_gateway/xxx.html"
|
|
181
|
+
}
|
|
182
|
+
],
|
|
183
|
+
"total": 480,
|
|
184
|
+
"page": 1,
|
|
185
|
+
"size": 20
|
|
186
|
+
},
|
|
187
|
+
"status": 1
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## 错误处理
|
|
192
|
+
|
|
193
|
+
错误信息输出到 stderr，程序 exit code 为 1：
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
kugou-cli music search "xxx" 2>&1
|
|
197
|
+
echo $? # 非 0 表示出错
|
|
198
|
+
```
|