@kg-ai/kugou-skill 0.1.8 → 0.1.10
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 +291 -222
- 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/auth.md +0 -4
- package/references/control.md +723 -680
- package/references/error-handling.md +18 -22
- package/references/music.md +526 -526
- package/references/output-format.md +101 -6
- package/references/update.md +2 -2
|
@@ -25,13 +25,108 @@
|
|
|
25
25
|
|
|
26
26
|
向用户展示结果时，**必须遵循以下规范**：
|
|
27
27
|
|
|
28
|
-
### 1.
|
|
28
|
+
### 1. 歌曲/歌单列表展示（批量优先用表格）
|
|
29
29
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
30
|
+
> **强制规则**：结果 ≥ 2 条 → 表格；结果 = 1 条 → 单行链接（按客户端可用性决定是否加链接）。
|
|
31
|
+
|
|
32
|
+
#### 1.1 客户端可用性探测（前置条件）
|
|
33
|
+
|
|
34
|
+
**首次**要向用户展示歌曲列表、歌单列表或歌单内歌曲列表之前，**必须**先探测本机是否有可用的酷狗客户端（详见 [SKILL.md#5-首次要展示歌曲歌单前探测本机客户端可用性](../SKILL.md)）：
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
kugou-cli control detect
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
根据退出码记下 `client_available`：
|
|
41
|
+
|
|
42
|
+
| 退出码 | 含义 | `client_available` |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| `0` | 已安装 | `true` |
|
|
45
|
+
| `1` | 探测出错（注册表权限等） | `false`（按没客户端处理） |
|
|
46
|
+
| `2` | 没装客户端 | `false` |
|
|
47
|
+
|
|
48
|
+
**会话内只探测一次**，后续展示复用本次结果。`control detect` 是零副作用探测，不会启动客户端、不会抢焦点。
|
|
49
|
+
|
|
50
|
+
#### 1.2 规则总览
|
|
51
|
+
|
|
52
|
+
| 结果条数 | 展示形式 | 客户端可用？ | 歌曲名/歌单名是否加链接 |
|
|
53
|
+
|---|---|---|---|
|
|
54
|
+
| **≥ 2** | Markdown 表格（**必须**） | 无关 | **一律不加**（保持列宽整洁） |
|
|
55
|
+
| **= 1** | 单行 Markdown 链接 | 是 | **不加**（可直接走 `control play`） |
|
|
56
|
+
| **= 1** | 单行 Markdown 链接 | 否 | **必须加**（用户手动打开） |
|
|
57
|
+
| **= 0** | 自然语言提示 | 无关 | 不适用 |
|
|
58
|
+
|
|
59
|
+
#### 1.3 表格格式（结果 ≥ 2 条）
|
|
60
|
+
|
|
61
|
+
**歌曲列表**（来自 `search` / `recommend guess|similar|text` / `charts` / `favorites` / `recent` / `playlist-songs`）：
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
| 序号 | 歌曲名 | 歌手 |
|
|
65
|
+
|------|--------|------|
|
|
66
|
+
| 1 | 晴天 | 周杰伦 |
|
|
67
|
+
| 2 | 七里香 | 周杰伦 |
|
|
68
|
+
| 3 | 稻香 | 周杰伦 |
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**歌单列表**（来自 `search-playlist` / `recommend-playlist`）：
|
|
72
|
+
|
|
73
|
+
```markdown
|
|
74
|
+
| 序号 | 歌单名 | 创建人昵称 |
|
|
75
|
+
|------|--------|------------|
|
|
76
|
+
| 1 | 周杰伦经典30首 | 酷狗小编 |
|
|
77
|
+
| 2 | 慢摇车载DJ | DJ阿圣 |
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
**硬性规则**：
|
|
81
|
+
|
|
82
|
+
- 表格单元格里的歌曲名/歌单名**不加** Markdown 链接——加了会让列宽自适应 URL，可读性反而变差
|
|
83
|
+
- 表格里也不列 `play_link` / `song_list_url` / `mix_song_id` / `global_id`——这些字段是给后续 `control *` 命令用的，由 agent 内部持有，**不展示给用户**
|
|
84
|
+
- 序号从 1 开始连续递增
|
|
85
|
+
- 如果返回总条数 > 表格展示条数（例如 `search` 默认 20 条），**只展示实际返回的那部分**，不要截断也不要用省略号
|
|
86
|
+
|
|
87
|
+
#### 1.4 单条结果格式（结果 = 1 条）
|
|
88
|
+
|
|
89
|
+
**有客户端时**（`client_available = true`）—— 歌曲名/歌单名**不加链接**：
|
|
90
|
+
|
|
91
|
+
```markdown
|
|
92
|
+
晴天 - 周杰伦
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
```markdown
|
|
96
|
+
周杰伦经典30首 —— 酷狗小编
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**无客户端时**（`client_available = false`）—— 歌曲名/歌单名**必须加链接**：
|
|
100
|
+
|
|
101
|
+
```markdown
|
|
102
|
+
[晴天 - 周杰伦](https://www.kugou.com/mixsong/xxxx.html)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
```markdown
|
|
106
|
+
[周杰伦经典30首](https://www.kugou.com/songlist/xxxx.html)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
#### 1.5 为什么表格不加链接？
|
|
110
|
+
|
|
111
|
+
- 表格的目标是**浏览/筛选**，不是立即跳转；用户在表格里通常要做的是"挑一首播放"或"挑一个歌单打开"，而非"挨个点开"
|
|
112
|
+
- 加链接会让列宽按 URL 自适应，中文长字符串场景下整张表可读性急剧下降
|
|
113
|
+
- ID（`mix_song_id` / `global_id`）由 agent 内部持有，等用户明确说"播放第 3 首" / "打开第 2 个歌单"时再走 `control play` / `control play-playlist` 或浏览器跳转
|
|
114
|
+
|
|
115
|
+
#### 1.6 反例（禁止）
|
|
116
|
+
|
|
117
|
+
| 禁止 | 错误原因 |
|
|
118
|
+
|---|---|
|
|
119
|
+
| 表格里写 `[晴天](https://...)` 形式的可点击单元格 | 列宽爆炸、可读性差 |
|
|
120
|
+
| 表格里把 `play_link` / `global_id` 也单列出来 | ID 是 agent 内部数据，不该展示给用户 |
|
|
121
|
+
| 结果 ≥ 2 条却用列表式 `[歌名 - 歌手](link)` 堆叠 | 表格才是 ≥ 2 条的标准形式 |
|
|
122
|
+
| 单条结果（= 1）时仍用表格 | 杀鸡用牛刀，单行更直接 |
|
|
123
|
+
| 单条无客户端时不加链接 | 用户没有客户端可控制，必须给链接让用户手动打开 |
|
|
124
|
+
| 单条有客户端时仍加链接 | 既然有客户端可以直接 `control play`，加链接反而多余 |
|
|
125
|
+
| 不探测就硬性决定加不加链接 | 必须先 `control detect`，不能凭猜测 |
|
|
126
|
+
|
|
127
|
+
#### 1.7 control 操作响应不受本节约束
|
|
128
|
+
|
|
129
|
+
`control play` / `control favorite song` 等**操作响应**不包含 `play_link`，按 control 协议原始 JSON 字段原样展示即可（见 [references/control.md](./control.md)）。本节规范只适用于 `music *` 命令返回的列表类结果。
|
|
35
130
|
|
|
36
131
|
### 2. 统计数据
|
|
37
132
|
|