@kg-ai/kugou-skill 0.0.27 → 0.0.28

package/README.md

@@ -74,6 +74,10 @@ kugou-cli music charts 52144  # 抖音热歌酷狗榜
 kugou-cli music charts 90379  # 星耀星光榜
 kugou-cli music charts 85432  # 百万收藏榜
 kugou-cli music charts 74534  # 新歌榜
+
+# 创建歌单
+kugou-cli music create-playlist "我的空歌单"
+kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
 ```
 
 ### 安装 SKILL.md

package/SKILL.md

@@ -2,13 +2,14 @@
 name: kugou-skill
 description: |
   酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手
-  提供歌曲搜索、每日推荐、相似推荐、收藏管理、听歌统计、酷狗榜单等功能。
+  提供歌曲搜索、每日推荐、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单等功能。
   
   **触发场景**（满足任一即使用本技能）：
   - 用户要求推荐歌曲、听歌建议
   - 用户要求搜索歌曲、查找歌手作品
   - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）
   - 用户要求查看收藏、最近播放、听歌统计
+  - 用户要求创建歌单、自建歌单
   - 用户提到"酷狗"、"kugou"、"每日推荐"、"相似歌曲"
   
   **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。
@@ -38,6 +39,9 @@ description: |
 - **音乐命令依赖登录**：除了 `auth`、`install`、`version`、`--help` 以外，所有 `music` 子命令都需要先登录。如果收到 `"not logged in"` 错误，引导用户执行登录流程。
 - **输出均为 JSON**：所有命令输出原始 JSON 到 stdout，错误输出到 stderr。解析 `errcode` 字段判断成功与否（`0` 为成功）。
 - **歌曲展示规范**（详见 [references/output-format.md](references/output-format.md)）：**禁止**只返回歌曲名、歌手名，**必须**以 Markdown 链接格式展示播放链接。
+- **创建歌单的调用原则**（详见 [references/music.md#8-创建歌单](references/music.md#8-创建歌单)）：
+  1. **被动调用**：必须用户**明确**要求创建歌单时才调用 `music create-playlist`，禁止在用户仅说"推荐/搜歌"时主动创建
+  2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户是否需要将当前这批歌曲创建为歌单，等用户确认后再调用 `music create-playlist --songs "<mix_song_id 列表>"`
 
 ---
 
@@ -45,7 +49,6 @@ description: |
 
 - **npm 包**: @kg-ai/kugou-skill
 - **二进制命令**: kugou-cli
-- **API 域名**: https://agentgateway.kugou.com（固定，无需配置）
 - **安装方式**: `npm install -g @kg-ai/kugou-skill`
 
 ---
@@ -55,7 +58,7 @@ description: |
 | 文档 | 说明 |
 |------|------|
 | [references/auth.md](references/auth.md) | 认证命令：扫码登录、查看状态、登出 |
-| [references/music.md](references/music.md) | 音乐命令：搜索、推荐、收藏、统计、榜单 |
+| [references/music.md](references/music.md) | 音乐命令：搜索、推荐、收藏、统计、榜单、创建歌单 |
 | [references/install.md](references/install.md) | 安装命令：SKILL.md 安装到各平台 |
 | [references/update.md](references/update.md) | 更新命令：检查/执行自动更新 |
 | [references/output-format.md](references/output-format.md) | 输出格式与展示规范 |
@@ -88,4 +91,8 @@ kugou-cli music stats
 
 # 7. 查看抖音热歌榜
 kugou-cli music charts 52144
+
+# 8. 创建歌单
+kugou-cli music create-playlist "我的空歌单"
+kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kg-ai/kugou-skill",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "description": "Kugou Skill CLI",
   "main": "index.js",
   "bin": {

package/references/music.md

@@ -13,6 +13,7 @@
 | `kugou-cli music recent` | 最近播放 |
 | `kugou-cli music stats` | 听歌统计 |
 | `kugou-cli music charts <rank_id>` | 榜单 |
+| `kugou-cli music create-playlist <name>` | 创建歌单（可附加歌曲） |
 
 ---
 
@@ -271,3 +272,52 @@ kugou-cli music charts 52144 --page 1 --size 20
 - `<rank_id>`: 榜单 ID（必填）
 - `--page`: 页码，默认 1
 - `--size`: 每页数量，默认 20
+
+---
+
+## 8. 创建歌单
+
+> 🔐 = 需要先登录
+
+### 调用原则（AI 必读）
+
+1. **被动调用**：必须用户**明确**要求创建歌单时才调用本命令，禁止在用户仅说"推荐/搜歌/听歌"时主动创建
+2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户"是否需要将当前这批歌曲创建为歌单"，等用户确认后再执行 `create-playlist --songs "<mix_song_id 列表>"`
+3. **示例化推荐**：询问时建议给出歌单名建议（如"跑步歌单"、"周杰伦精选"），让用户更容易确认
+
+### 接口说明
+
+创建一个新的自建歌单，并可选择在创建后往歌单里添加歌曲。
+
+```bash
+# 创建空歌单
+kugou-cli music create-playlist "我的空歌单"
+
+# 创建歌单并添加歌曲
+kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060,64263573,146061840"
+```
+
+**参数**:
+- `<name>`: 歌单名称（必填）
+- `--songs`: 待添加的歌曲 mix_song_id 列表，逗号分隔（可选）。不传则只创建空歌单
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "errmsg": "",
+  "data": {
+    "name": "我的批量歌单",
+    "song_list_url": "https://m.kugou.com/songlist/gcid_abc123def45"
+  },
+  "status": 1
+}
+```
+
+**关键字段**:
+- `name`: 歌单名称
+- `song_list_url`: 歌单播放地址（H5 链接），可分享给用户打开
+
+**异常说明**:
+- 歌单创建成功但添加歌曲失败：返回 200 状态 + 错误信息，body 仍包含已创建歌单的 `name` 与 `song_list_url`
+- 歌单创建失败：返回对应错误码（参数错误 20010 / 网络错误 90000 等）