@kg-ai/kugou-skill 0.1.13 → 0.1.15

package/README.md

@@ -89,6 +89,14 @@ kugou-cli music recommend-playlist --module-id 6
 
 # 歌单内歌曲列表
 kugou-cli music playlist-songs "collection_3_938985631_304_0"
+
+# 调整音乐偏好（用户明确表达"少推点/别再推/多推点"时调用）
+# 减少推荐某位歌手
+kugou-cli music submit-preference --dimension singer --degree reduce --name "周杰伦" --weight-ratio 0.5
+# 屏蔽某类曲风
+kugou-cli music submit-preference --dimension genre --degree forbid --weight-ratio 1.5
+# 增加某语种
+kugou-cli music submit-preference --dimension language --degree add --name "粤语" --weight-ratio 1.8
 ```
 
 ### 安装 SKILL.md

package/SKILL.md

@@ -2,7 +2,7 @@
 name: kugou-skill
 description: |
   酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手
-  提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单等功能。
+  提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单、调整音乐偏好等功能。
 
   **触发场景**（满足任一即使用本技能）：
   - 用户要求推荐歌曲、听歌建议
@@ -10,6 +10,7 @@ description: |
   - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）
   - 用户要求查看收藏、最近播放、听歌统计
   - 用户要求创建歌单、自建歌单
+  - 用户要求调整音乐偏好（"少推点 XX 歌手"、"多推点 XX 语种"、"别再推 XX 曲风" 等）
   - 用户提供 base64 secret 字符串要求登录或导入身份
   - Agent 在尝试扫码登录时遇到环境限制（无法发图片）→ 主动询问用户是否可提供 secret
   - 用户提到"酷狗"、"kugou"、"猜你喜欢"、"相似歌曲"
@@ -17,7 +18,7 @@ description: |
   - 用户提到酷狗 URL scheme（"kugou://" 或 "mackugou://"）
   - 用户提到"本机控制"、"控制酷狗客户端"
 
-  **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。
+  **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐；同时支持把用户偏好（歌手/语种/曲风等）实时反馈给推荐引擎。
 
   安装方式：npm install -g @kg-ai/kugou-skill
 ---
@@ -200,6 +201,21 @@ description: |
    - 客户端可用：优先 `kugou-cli control play-playlist --global-id "<id>"`（详见 [references/control.md#12-play-playlist--播放整个歌单](references/control.md#12-play-playlist--播放整个歌单)）
    - 客户端不可用 / `play-playlist` 拿不到可用 ID：按 [references/music.md#72-云端歌单的播放控制浏览器打开-h5-链接](references/music.md#72-云端歌单的播放控制浏览器打开-h5-链接) 走"先探后告知"——用浏览器工具打开 H5 `song_list_url` 尝试点击播放；工具不可用时明确告知用户手动复制链接打开
 
+### 调整偏好的调用原则
+
+详见 [references/music.md#11-提交偏好](references/music.md#11-提交偏好)：
+
+1. **被动调用**：必须用户**明确**表达偏好调整意愿时才调用 `kugou-cli music submit-preference`，禁止在用户仅说"推荐/搜歌/听歌"时主动改写用户偏好
+2. **解析用户意图 → 落到 dimension/degree/name**：按 [references/music.md#11-提交偏好 调用流程](references/music.md#11-提交偏好) 里的"用户原话 → dimension/degree/name"映射表翻译，不确定时**主动询问**（"你说的『少推点 XX』是指歌手还是语种/曲风？"）
+3. **name 用服务端能识别的标准名**：用户口语里的昵称/简称（"老周"）必须**先问清楚**再调，因为上游 name 必须是服务端能识别的标准名（如"周杰伦"）
+4. **weight-ratio 配对**：reduce→`(0,1)`、forbid/add→`(1,2)`。不匹配时 CLI 仅 warning 不阻断，最终以服务端校验为准
+5. **提交成功后的呈现优先级**：
+   - **第一优先**：用响应 `data.msg`（上游确认话术）展示给用户，例如"收到！将减少推荐歌手「周杰伦」的歌曲，猜你喜欢以下歌曲~"
+   - **第二优先**：把响应 `data.list`（重新推荐的歌曲列表）按 [references/output-format.md#1-歌曲歌单列表展示批量优先用表格](references/output-format.md#1-歌曲歌单列表展示批量优先用表格) 的展示规范呈现（≥ 2 条用表格，= 1 条按 `client_available` 决定加不加链接）
+   - 表格里**不**加 `<em>` 高亮 / `play_link` / `mix_song_id`，agent 内部持有
+6. **复用 list，不要再调 recommend**：拿到新推荐的 `list[]` 后，**主动询问**用户"要按这个新偏好播放一些吗？"，用户同意后**直接用 list[] 里的 `mix_song_id`** 走 [`control play`](./references/control.md#1-play--播放指定歌曲) 等命令，**不要**再调一次 `recommend` 浪费调用
+7. **多次提交会叠加**：本接口是**实时反馈**给推荐引擎，不会持久化为用户画像规则；同一歌手多次提交会**叠加效果**，不要替用户循环重提
+
 ### 能力边界提示
 
 当用户提出的需求在 `kugou-cli` **整体能力边界之外**时，Agent 必须**明确告知用户"暂不支持该能力"**，不得擅自用其他命令拼凑代替，也不得假装能完成。
@@ -292,4 +308,8 @@ kugou-cli music playlist-songs "collection_3_938985631_304_0"
 kugou-cli control play --mixsongid 32100650 --song-name "晴天" --singer-name "周杰伦"
 kugou-cli control player --action pause
 kugou-cli control favorite song --mixsongid 32100650
+
+# 11. 调整音乐偏好（用户明确表达"少推点/别再推/多推点"时调用，详见 references/music.md#11-提交偏好）
+kugou-cli music submit-preference --dimension singer --degree reduce --name "周杰伦" --weight-ratio 0.5
+kugou-cli music submit-preference --dimension language --degree add --name "粤语" --weight-ratio 1.8
 ```

package/package.json

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

package/references/music.md

@@ -17,6 +17,7 @@
 | `kugou-cli music search-playlist <keyword>` | 搜索歌单 |
 | `kugou-cli music recommend-playlist` | 歌单推荐 |
 | `kugou-cli music playlist-songs <global_collection_id>` | 歌单内歌曲列表 |
+| `kugou-cli music submit-preference` | 提交偏好（减少/屏蔽/增加） |
 
 ---
 
@@ -524,3 +525,119 @@ kugou-cli music playlist-songs "collection_3_938985631_304_0" --page 1 --size 10
 - **artist_name 拼接**: 多歌手时上游用 `/` 拼接（例如 `周杰伦/方文山`）
 - **分页去重**: 上游按服务端数组下标分页，但歌曲可能在分页期间被增删，调用方需自行按 `mix_song_id` 去重
 - **播放链接**: `play_link` 由服务端拿到 `mix_song_id` 后批量生成，单条失败不影响其他歌曲
+
+---
+
+## 11. 提交偏好
+
+> 🔐 = 需要先登录
+
+把用户对音乐偏好的调整（减少 / 屏蔽 / 增加 某位歌手、语种、曲风等）提交到上游推荐引擎，**服务端**先把 `name` 解析为上游 id（例如 singer → 歌手搜索取第 0 个结果的 `author_id`）再透传，上游处理后**返回一条确认话术 + 重新推荐的歌曲列表**。
+
+适用于用户表达"最近想多听 XX 语种 / 不想再听 XX 歌手的 / 多推点 XX 曲风"等诉求的场景。
+
+```bash
+# 减少推荐某位歌手（weight 越小减得越多）
+kugou-cli music submit-preference \
+  --dimension singer --degree reduce \
+  --name "周杰伦" --weight-ratio 0.5
+
+# 屏蔽某类曲风
+kugou-cli music submit-preference \
+  --dimension genre --degree forbid \
+  --weight-ratio 1.5
+
+# 增加某语种
+kugou-cli music submit-preference \
+  --dimension language --degree add \
+  --name "粤语" --weight-ratio 1.8
+```
+
+**参数**（全部为 flag，无位置参数）:
+
+| 参数 | 必填 | 取值 | 说明 |
+|------|------|------|------|
+| `--dimension` | 是 | `singer` / `language` / `genre` / `ai` / `dj` / `fc` / `abs` / `old` | 偏好维度（强枚举） |
+| `--degree` | 是 | `reduce`（减少）/ `forbid`（屏蔽）/ `add`（增加） | 操作类型（强枚举） |
+| `--name` | 条件必填 | string | `singer` 传歌手名 / `language` 传语种名；其余维度**必须为空** |
+| `--weight-ratio` | 是 | float64，范围 `(0, 2)` | 权重系数。`reduce` 配 `(0,1)` / `forbid` & `add` 配 `(1,2)` |
+| `--area-code` | 否 | int | 地区码；不传时不出现在 body 中 |
+
+**`name` 必填/必空规则**:
+
+| `--dimension` | 是否需要 `--name` | 说明 |
+|--------------|------------------|------|
+| `singer` | **必填**（歌手名） | 服务端查歌手搜索取第 0 个结果 `author_id` |
+| `language` | **必填**（语种名） | 服务端查下方「语种映射表」取 id |
+| `genre` / `ai` / `dj` / `fc` / `abs` / `old` | **必须为空** | 服务端不取 name，传了会被 CLI 拦截 |
+
+**`weight-ratio` 与 `--degree` 的配对**:
+
+| `--degree` | 配对范围 | 不匹配时的处理 |
+|-----------|---------|---------------|
+| `reduce` | `(0, 1)` | CLI 给 warning（不阻断），最终可能服务端拒 |
+| `forbid` | `(1, 2)` | CLI 给 warning（不阻断），最终可能服务端拒 |
+| `add` | `(1, 2)` | CLI 给 warning（不阻断），最终可能服务端拒 |
+
+> CLI 只做基础的 `(0, 2)` 范围校验 + 不匹配时的 warning；**业务侧具体配对由服务端校验**，避免本地硬规则与服务端不一致时把"reduce 0.99"这种边界值也堵掉。
+
+**语种映射表**（`--dimension=language` 时 `--name` 取值）:
+
+`国语` / `英语` / `粤语` / `纯音乐` / `韩语` / `日语` / `其他语种` / `小语种` / `方言` / `闽南语` / `俄语` / `伴奏` / `西班牙语` / `藏语` / `越南语` / `葡萄牙语` / `德语` / `泰语` / `意大利语` / `蒙古语`
+
+**输出示例**:
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "",
+  "data": {
+    "status": 801,
+    "msg": "收到！将减少推荐歌手「周杰伦」的歌曲，猜你喜欢以下歌曲~",
+    "list": [
+      {
+        "song_name": "稻香",
+        "mix_song_id": "595244683",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/xxx.html"
+      }
+    ]
+  },
+  "status": 1
+}
+```
+
+**关键字段**:
+- `data.status`: 上游 `msgtype`，取第一条确认话术对应的消息类型（如 `801`）
+- `data.msg`: 上游确认话术（如「收到！将减少推荐歌手「周杰伦」的歌曲，猜你喜欢以下歌曲~」），**直接展示给用户**
+- `data.list`: 重新推荐的歌曲列表，结构同通用 `SongInfo`（`song_name` / `mix_song_id` / `artist_name` / `play_link`）
+
+**调用流程**（agent 必读）:
+
+```
+1. 解析用户意图：识别"减少 / 屏蔽 / 增加" + "对象（歌手 / 语种 / 曲风等）"
+2. 按下表确定 dimension / degree / name：
+   ┌────────────────────────────────────────┬──────────┬────────────┬────────────────┐
+   │ 用户原话（例）                          │ dimension│ degree     │ name           │
+   ├────────────────────────────────────────┼──────────┼────────────┼────────────────┤
+   │ "少推点周杰伦的歌"                      │ singer   │ reduce     │ 周杰伦         │
+   │ "别再给我推民谣了"                      │ genre    │ forbid     │ （空）         │
+   │ "多来点粤语歌"                          │ language │ add        │ 粤语           │
+   │ "屏蔽一下英文歌"                        │ language │ forbid     │ 英语           │
+   └────────────────────────────────────────┴──────────┴────────────┴────────────────┘
+3. 选 weight_ratio：
+   - reduce → 0 < x < 1（值越小减得越多；常用 0.5）
+   - forbid / add → 1 < x < 2（值越大越强；常用 1.5）
+4. 调 submit-preference
+5. 拿到响应后，**优先用 data.msg 展示确认话术**给用户；
+   data.list 是重新推荐的歌曲列表，按 [§0.1 / §0.2 / §1](#1-搜索歌曲) 的展示规范呈现
+```
+
+**特殊说明**:
+- **上游返回 SSE 流式**：响应体上游为多行 `data:` 流。服务端取**第一条**确认话术（`msgtype=801`）作为对外 `status`/`msg`，避免被后续推荐话术覆盖
+- **歌曲组装**：`list` 中的 `mixsongid` 与「歌曲推荐」接口共用同一套组装逻辑（kmr 拉歌名/歌手/hash + `GenerateBatch` 生成播放链接）；未命中歌曲详情（audioMap miss）的条目会被跳过，因此最终 `list` 条数可能小于上游返回数量
+- **name 解析**：`singer` / `language` 维度的 `name` 会在 logic 层被解析为上游 id 后透传，客户端只传 `name` 即可，不需要先去查歌手 id
+- **name 输入规范**：用户口语里说"少推点老周"时，agent 应**询问清楚**再调用——上游 name 必须是服务端能识别的标准名（如"周杰伦"），不是昵称/简称
+- **不是「保存为规则」**：本接口是**实时反馈**给推荐引擎，不会持久化为用户画像规则；同一歌手多次提交会**叠加效果**
+- **不要主动调用**：必须用户**明确**表达偏好调整意愿时才调用（"少推点 XX" / "别再推 XX" / "多推点 XX"），禁止在用户仅说"推荐/搜歌/听歌"时主动改写用户偏好
+- **改完偏好 → 主动问是否要听**：提交成功（`errcode: 0`）后，服务端已返回重新推荐的 `data.list`；agent 应**主动询问**用户"要按这个新偏好播放一些吗？"，等用户确认后**复用 `list[]` 里的 mix_song_id** 直接走 [`control play`](./control.md#1-play--播放指定歌曲) 等命令，不要再调一次 `recommend`

package/scripts/install.js

@@ -49,12 +49,27 @@ const skillDirs = [
 if (fs.existsSync(skillSrc)) {
   const referencesSrc = path.join(pkgRoot, 'references');
 
+  // workbuddy 平台:kugou-skill 与 kugou-skill__skillhub 二选一
+  // 若 ~/.workbuddy/skills/kugou-skill__skillhub 已存在,只装到那里,跳过 kugou-skill
+  // 反之只装到 kugou-skill,__skillhub 是 opt-in 不自动创建
+  const workbuddyAltDir = path.join(os.homedir(), '.workbuddy', 'skills', 'kugou-skill__skillhub');
+  const workbuddyUseAlt = fs.existsSync(workbuddyAltDir);
+
   for (const skillDir of skillDirs) {
     // 只在 skills 目录存在时才复制，不创建目录
     const parentDir = path.dirname(skillDir);
     if (fs.existsSync(parentDir)) {
+      const baseName = path.basename(skillDir);
+
+      // workbuddy 互斥:__skillhub 存在时跳过 kugou-skill,只装 __skillhub
+      const isWorkbuddyPrimary = baseName === 'kugou-skill' && skillDir === path.join(os.homedir(), '.workbuddy', 'skills', 'kugou-skill');
+      if (isWorkbuddyPrimary && workbuddyUseAlt) {
+        console.log(`Skipping ${skillDir}: ${workbuddyAltDir} exists, installing only to ${workbuddyAltDir}`);
+        continue;
+      }
+
       // __skillhub 子目录是 opt-in:仅在已存在时同步,绝不自动创建
-      if (path.basename(skillDir) === 'kugou-skill__skillhub' && !fs.existsSync(skillDir)) {
+      if (baseName === 'kugou-skill__skillhub' && !fs.existsSync(skillDir)) {
         continue;
       }
       try {