@kg-ai/kugou-skill 0.1.7 → 0.1.9

package/README.md

@@ -20,11 +20,11 @@ npm install -g @kg-ai/kugou-skill
 # Step 1: 获取二维码图片
 kugou-cli auth login
 
-# Step 2: 循环检查登录状态（直到 logged_in=true）
+# Step 2: 循环检查登录状态（单次查询不内部轮询，agent 外层循环直到 logged_in=true）
 kugou-cli auth status
-```
 
 > 必须将 Step 1 输出中 `qrcode_img_url` 渲染给用户扫码（用 `![酷狗登录二维码](<qrcode_img_url>)`）。token 会自动持久化存储。
+> `auth status` 是单次查询，调用方需在外层循环（2-3 秒间隔）直到 `logged_in=true`；不要等"内部已轮询"——根本不会自动轮询。
 
 ## 命令
 
@@ -34,7 +34,7 @@ kugou-cli auth status
 # 获取二维码图片
 kugou-cli auth login
 
-# 检查登录状态（未完成登录时内部自动轮询）
+# 检查登录状态（单次查询，不内部轮询；agent 需外层循环 2-3s 间隔）
 kugou-cli auth status
 
 # 登出
@@ -48,21 +48,19 @@ kugou-cli auth logout
 kugou-cli music search "周杰伦"
 kugou-cli music search "周杰伦" --page 1 --size 20
 
-# 每日推荐
-kugou-cli music recommend daily
-kugou-cli music recommend daily --num 10
+# 猜你喜欢
+kugou-cli music recommend guess
+kugou-cli music recommend guess --num 10
 
 # 相似推荐（需要指定歌曲）
 kugou-cli music recommend similar --song "晴天"
 kugou-cli music recommend similar -s "晴天" -n 5
 
-# 我的收藏
+# 我的收藏（上游固定返回最近 10 首，不支持分页）
 kugou-cli music favorites
-kugou-cli music favorites --page 1 --size 20
 
-# 最近播放
+# 最近播放（上游固定返回最近 10 条，不支持分页）
 kugou-cli music recent
-kugou-cli music recent --page 1 --size 20
 
 # 听歌统计
 kugou-cli music stats
@@ -76,8 +74,21 @@ kugou-cli music charts 85432  # 百万收藏榜
 kugou-cli music charts 74534  # 新歌榜
 
 # 创建歌单
+# ⚠️ 默认走客户端路径：kugou-cli control playlist create（见下方"控制"节）
+# 客户端不可用时才回退到云端：
 kugou-cli music create-playlist "我的空歌单"
 kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
+
+# 搜索歌单
+kugou-cli music search-playlist "周杰伦"
+kugou-cli music search-playlist "跑步" --filter 1
+
+# 歌单推荐
+kugou-cli music recommend-playlist
+kugou-cli music recommend-playlist --module-id 6
+
+# 歌单内歌曲列表
+kugou-cli music playlist-songs "collection_3_938985631_304_0"
 ```
 
 ### 安装 SKILL.md
@@ -92,6 +103,54 @@ kugou-cli install --mavis
 kugou-cli install --hermes --openclaw --codex
 ```
 
+### 控制 PC/Mac 酷狗客户端
+
+通过本机 HTTP 服务控制本地酷狗桌面客户端（播放、暂停、收藏、创建歌单等）。仅支持 macOS 和 Windows，Linux 不支持。
+
+**前置条件**：需先完成 CLI 登录（`kugou-cli auth login`）且酷狗客户端在后台运行。
+
+**子命令列表**：
+
+| 子命令 | 说明 |
+|--------|------|
+| `start` | 触发 URL-scheme 握手，预热通道 |
+| `status` | 获取客户端状态 |
+| `current` | 获取当前播放曲目 |
+| `play` | 播放指定歌曲 |
+| `play-playlist` | 播放整个歌单（按 global_collection_id） |
+| `player` | 控制播放（播放/暂停/切歌等） |
+| `seek` | 跳转或快进/快退播放位置 |
+| `volume` | 调节音量或静音 |
+| `continue-play` | 拉取"另一设备续播"列表并开始播放 |
+| `favorite song` | 收藏/取消收藏歌曲 |
+| `favorite songlist` | 收藏/取消收藏歌单 |
+| `playlist create` | 在客户端创建新歌单 |
+| `open` | 在客户端内打开页面（搜索/歌手/专辑等） |
+
+**示例**：
+
+```bash
+# 预热握手（首次使用前建议执行）
+kugou-cli control start
+
+# 播放歌曲
+kugou-cli control play --mixsongid 32100650 --song-name "晴天" --singer-name "周杰伦"
+
+# 播放整个歌单
+kugou-cli control play-playlist --global-id "collection_3_938985631_304_0"
+
+# 收藏歌曲
+kugou-cli control favorite song --mixsongid 32100650
+
+# 创建歌单
+kugou-cli control playlist create --name "精选" --mixsongids "32100650,32068120"
+
+# 在客户端内打开搜索页面
+kugou-cli control open --target-type search --keyword "周杰伦"
+```
+
+完整命令文档见 `references/control.md`。
+
 ### 全局
 
 ```bash

package/SKILL.md

@@ -2,20 +2,23 @@
 name: kugou-skill
 description: |
   酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手
-  提供歌曲搜索、每日推荐、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单等功能。
-  
+  提供歌曲搜索、猜你喜欢、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单等功能。
+
   **触发场景**（满足任一即使用本技能）：
   - 用户要求推荐歌曲、听歌建议
   - 用户要求搜索歌曲、查找歌手作品
   - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）
   - 用户要求查看收藏、最近播放、听歌统计
   - 用户要求创建歌单、自建歌单
-  - 用户提供 secret（base64 字符串）要求登录或导入身份
+  - 用户提供 base64 secret 字符串要求登录或导入身份
   - Agent 在尝试扫码登录时遇到环境限制（无法发图片）→ 主动询问用户是否可提供 secret
-  - 用户提到"酷狗"、"kugou"、"每日推荐"、"相似歌曲"
-  
+  - 用户提到"酷狗"、"kugou"、"猜你喜欢"、"相似歌曲"
+  - 用户要求让 PC/Mac 客户端播放歌曲、暂停、切歌、收藏、创建歌单
+  - 用户提到酷狗 URL scheme（"kugou://" 或 "mackugou://"）
+  - 用户提到"本机控制"、"控制酷狗客户端"
+
   **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。
-  
+
   安装方式：npm install -g @kg-ai/kugou-skill
 ---
 
@@ -27,63 +30,148 @@ description: |
 
 ```
 1. 检查安装 → npm install -g @kg-ai/kugou-skill
-2. 检查登录 → kugou-cli auth status
-3. 登录决策（关键决策点，不要跳过）：
-   ├─ 已登录（logged_in: true）→ 直接进入第 4 步
-   ├─ 未登录 → 先询问用户："你手上是否已有可用的 base64 secret？"
-   │   - 用户明确说"有" → 调 kugou-cli auth set-secret "<secret>"，跳过扫码
-   │   - 用户说"没有"或不确定 → 走标准扫码流程
-    │   - 当前环境既无法渲染远程 URL 图片，也无法读取本地二维码文件 → 强制走 set-secret
-
-   └─ 默认行为：除非用户明确说"我有 secret"，否则优先走扫码
-   4. 引导登录（详见 references/auth.md）：
-    - 扫码：执行 `auth login`，根据当前客户端的图片能力，在 `qrcode_img_url` 和 `qrcode_img_path` 中选择一种展示二维码，不要只输出 URL 或文件路径
-    → 阶段 A：主动循环 auth status 最多 5 次（2-3s 间隔），覆盖秒扫
-    → 阶段 B：5 次仍 waiting → 停下，主动提示用户扫码，等用户**主动回复"已扫码"**
-    → 阶段 C：用户回复后调一次 status 验证；logged_in: true 即完成
-    - 导入 secret：auth set-secret "<secret>" 一次完成
-5. 执行用户请求的音乐命令（详见 references/music.md）
-6. 解析 JSON 输出，按展示规范展示给用户（详见 references/output-format.md）
+2. 检查登录态 → kugou-cli auth status
+3. 登录决策（按以下优先级严格判断，不要跳步）：
+   ├─ 状态 a：已登录（logged_in: true）→ 跳到第 5 步
+   ├─ 状态 b：未登录 + 用户**明确**说"我有 secret" → 调 `kugou-cli auth set-secret "<secret>"` 一次完成 → 跳到第 5 步
+   ├─ 状态 c：未登录 + 当前环境**无法**渲染远程 URL 图片 **且** 无法读取本地二维码文件 → **强制**走 set-secret（同上）
+   └─ 状态 d：未登录 + 其他所有情况 → 走扫码流程（第 4 步）
+
+   注意：状态 b/c/d 互斥；不要在用户未明确给 secret 时擅自走 set-secret。
+4. 引导登录——扫码（详见 references/auth.md）：
+   - 执行 `auth login`，从输出读 `qrcode_img_url` 和 `qrcode_img_path`，按当前客户端能力选一种方式把二维码**直接展示给用户**
+   - **阶段 A（主动轮询）**：图片刚展示，**主动**重试几次 `auth status`（每次隔几秒），覆盖用户秒扫场景
+     - 任意一次返回 `logged_in: true` → 跳到第 5 步
+     - 几次都返回 `waiting` 且未出现 `scanned` → 进入阶段 B
+   - **阶段 B（等用户回复）**：停下，告诉用户"请用酷狗 APP 扫码登录，扫完后告诉我已扫码"，**不再调 status**，等用户**主动回复"已扫码"**
+   - **阶段 C（验证一次）**：用户回复"已扫码"后，**调一次** `auth status`：
+     - `logged_in: true` → 完成，跳到第 5 步
+     - `scanned`（已扫但未确认）→ 等几秒再调一次，最多**额外**调几次，仍是 scanned 就告诉用户"手机端是否已点确认？"
+     - `failed` 或 `{"logged_in": false}` → 重新 `auth login` 拿新图，从阶段 A 重新开始
+5. 按请求类型分流：
+   - **请求类型 A：控制已有歌 / 歌单 / 收藏**（用户已有 mixsongid 或 global_id）→ 直接执行 `control` 命令（详见 [references/control.md](references/control.md)），不需要先调 `music` 拿 ID
+     - 例：`control play`、`control player --action pause`、`control favorite song --mixsongid <id>`、`control play-playlist --global-id <id>`
+   - **请求类型 B：搜索后做某件事**（搜索歌曲/推荐/榜单 → 拿到 ID 后再做后续动作，如播放、收藏、建歌单）→ 先执行 `music` 命令拿数据，再按需转 `control`，详见 [references/music.md](references/music.md)
+     - 例：先 `music search` 拿 mixsongid，再 `control play` 播放
+     - 例：先 `music search-playlist` 拿 global_id，再 `control play-playlist` 播放
+     - 例：先 `music search` 拿 mixsongids，再 `control playlist create --mixsongids` 创建客户端歌单
+   - **请求类型 C：纯查询 / 统计 / 榜单**（不涉及本地客户端）→ 只走 `music` 命令
+6. 解析 JSON 输出，按展示规范展示给用户（详见 [references/output-format.md](references/output-format.md)）
 ```
 
-### 关键注意事项
-
-- **登录流程极简**（详见 [references/auth.md](references/auth.md)）：
-  1. `auth login` - 获取二维码，输出包含：
-     - `qrcode`：字符串标识，仅供 CLI 持久化和后续状态查询，Agent 不要将它作为图片展示
-     - `qrcode_img_path`：本地二维码 PNG 文件路径
-     - `qrcode_img_url`：酷狗上游返回的远程二维码图片 URL
-  2. **根据当前客户端能力选择一种方式，把二维码图片直接展示在聊天窗口中**：
-     - 客户端支持读取或附加本地图片（如 Codex）→ 使用 `qrcode_img_path`，通过客户端的本地图片读取/附件能力展示
-     - 客户端支持 Markdown 外链图片（如 WorkBuddy）→ 在消息正文中输出 `![酷狗登录二维码](<qrcode_img_url>)`
-     - Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码
-     - **不要**只把 URL 或本地路径作为普通文本发给用户，用户应直接看到二维码图片
-     - 首选方式展示失败时，立即切换到另一种方式：远程图片加载失败则尝试本地文件，本地文件无法读取则尝试远程 Markdown 图片
-     - 若两种方式都不可用 → 告诉用户“当前环境无法显示二维码，请提供 base64 secret 字符串”，改走 `auth set-secret`
-  3. **图片发送后两阶段行为（关键）**：
-     - **阶段 A（主动轮询）**：图片刚展示，**先主动**循环调 `auth status` 最多 5 次（每次间隔 2-3 秒），覆盖用户秒扫的情况
-     - **阶段 B（等待用户反馈）**：5 次仍 `waiting` → **停下来**，主动告诉用户：“请用酷狗 APP 扫码登录，扫完后告诉我已扫码”，**不再调 status**，等用户**主动回复“已扫码”**才进入阶段 C
-     - **阶段 C（验证登录）**：用户回复“已扫码” → 调一次 `auth status` 验证；返回 `logged_in: true` 继续执行，`scanned` 等几秒再调，`failed` 重新 `auth login` 拿新图
-     - 若用户回复“没看到图片” / “图片打不开” → 先切换到另一种二维码展示方式；两种方式都失败后再切换到 `set-secret`
-  4. `auth status` - **单次查询，不内部轮询**：每次调用只查一次扫码状态。完整流程见上方“两阶段行为”。**不要**等“内部已轮询”——根本不会自动轮询。
-- **直接导入 secret 登录**：当用户**已经持有**一个有效的 base64 secret 字符串（从别处获取的），直接调用 `kugou-cli auth set-secret "<secret>"` 即可完成登录，**跳过扫码流程**。这与扫码登录保存到同一份 `auth.json`，效果完全一致。secret 字符串含 `+` `/` `=` 是正常的，shell 里务必用引号包起来。**何时考虑用 set-secret**：用户明确说“我有 secret”、当前环境既无法展示 `qrcode_img_url` 远程图片也无法读取 `qrcode_img_path` 本地图片、用户之前已经登录过想换设备。
-- **登出 (auth logout)**：会**先**与服务端同步登出，**确认成功后才**清理本地登录态。失败时本地态保留、可重试；未登录时幂等直接返回成功。失败时 Agent **自动重试 1 次**（网络抖动常见），仍失败再询问用户是否重试，**不要**擅自清理本地文件。
-- **登录态自动失效**：当任意 `music` 命令遇到登录态过期时，CLI 会**自动清理**本地登录态，并在 stderr 输出 `账号登录过期，请重新登录`，exit code 非 0。Agent 收到该错误后：
-  1. **不要**自己再调一次 `music` 命令（会再次失败）
-  2. **不要**手动清理本地文件
-  3. **直接**引导用户重新登录：先问"你手上是否已有新 secret？"，有则 `auth set-secret`，没有则 `auth login` 走扫码
-  4. 重新登录后，**先调 `auth status` 确认** `logged_in: true`，再重试之前失败的 `music` 命令
-  - **状态字段差异**：`auth status` 在"无登录态"和"登录态过期被自动清理"两种场景下都返回 `{"logged_in": false}`（**不带 status 字段**）；"等待扫码"才返回 `{"logged_in": false, "status": "waiting"}`。Agent 区分场景应看 `music` 命令的 stderr 输出，不要只看 status 字段。完整状态表见 [references/auth.md#状态表](references/auth.md#状态表)。
-- **音乐命令依赖登录**：除了 `auth`、`install`、`version`、`--help` 以外，所有 `music` 子命令都需要先登录。如果收到 `"not logged in"` 错误，引导用户执行登录流程。
-- **自动更新机制**：每次启动任意命令时会自动检测 npm 远端版本，若有新版会**自动执行** `npm install -g @kg-ai/kugou-skill@latest`，无需手动 `kugou-cli update`：
-  - 关闭自动检查：加 `--no-update-check` 标志，或设置环境变量 `KUGOU_CLI_NO_UPDATE_CHECK=1`
-  - 手动检查/触发：`kugou-cli update` 跳过本地缓存直接查远端并自动安装；`kugou-cli update --check` 仅检查不安装
-  - 非 npm 安装（手动编译/容器）会打印提示和升级命令但不会自动执行
-- **输出均为 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 列表>"`
+> **关键提醒**：**不要**在没有 mixsongid / global_id 的情况下盲目调用 `control` 命令（如 `control play --mixsongid ""`）—— `control` 命令在 ID 缺失时会报错。先用 `music` 命令把 ID 查出来，再传给 `control`。
+
+---
+
+## 关键注意事项
+
+### 登录流程
+
+`auth login` 命令输出三个字段供 Agent 选择二维码展示方式（详见 [references/auth.md](references/auth.md)）：
+
+| 字段 | 用途 |
+|------|------|
+| `qrcode_img_path` | 本地二维码 PNG 文件路径 |
+| `qrcode_img_url` | 远程二维码图片 URL |
+| `qrcode` | 字符串标识，**Agent 不要使用**（仅供 CLI 内部） |
+
+**根据当前客户端能力选择一种方式，把二维码图片直接展示在聊天窗口中**：
+
+- 客户端支持读取或附加本地图片（如 Codex）→ 使用 `qrcode_img_path`，通过客户端的本地图片读取/附件能力展示
+- 客户端支持 Markdown 外链图片（如 WorkBuddy）→ 在消息正文中输出 `![酷狗登录二维码](<qrcode_img_url>)`
+- Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码
+- **不要**只把 URL 或本地路径作为普通文本发给用户，用户应直接看到二维码图片
+- 首选方式展示失败时，立即切换到另一种方式：远程图片加载失败则尝试读取本地图片，本地图片无法读取则尝试远程 Markdown 图片
+- 若两种方式都不可用 → 告诉用户"当前环境无法显示二维码，请提供 base64 secret 字符串"，改走 `auth set-secret`
+
+**`auth status` 的调用约束**：
+
+- 每次调用只查一次扫码状态，**不会内部自动轮询**。Agent 需要在外层按"阶段 A → 阶段 B → 阶段 C"循环调用（详见上方工作流第 4 步）
+- 阶段 B 之后**不要**自己继续调用 status，等用户回复
+
+### 直接导入 secret 登录
+
+当用户**已经持有**一个有效的 base64 secret 字符串（从别处获取的），直接调用 `kugou-cli auth set-secret "<secret>"` 即可完成登录，**跳过扫码流程**——效果与扫码登录完全一致。secret 字符串含 `+` `/` `=` 是正常的，shell 里务必用引号包起来。
+
+**何时考虑用 set-secret**：
+
+- 用户明确说"我有 secret"
+- 当前环境既无法展示远程图片也无法读取本地图片
+- 用户之前已经登录过想换设备
+
+### 登出
+
+`auth logout` 命令：先与服务端同步登出，**确认成功后才**清理登录状态。失败时登录状态保留、可重试；未登录时幂等直接返回成功。
+
+### 登录态自动失效
+
+当任意 `music` 命令遇到登录态过期时，CLI 会自动取消登录（退出码非 0 + stderr 提示登录已过期）。Agent 收到该错误后：
+
+1. **不要**自己再调一次 `music` 命令（会再次失败）
+2. **直接**引导用户重新登录：先问"你手上是否已有新 secret？"，有则 `auth set-secret`，没有则 `auth login` 走扫码
+3. 重新登录后，**先调 `auth status` 确认** `logged_in: true`，再重试之前失败的 `music` 命令
+
+> Agent 不应依赖 stderr 文案字面量判断错误类型——以退出码和 references/error-handling.md 中的错误码说明为准。
+
+### 音乐命令依赖登录
+
+除了 `auth`、`install`、`version`、`--help` 以外，所有 `music` 子命令都需要先登录。如果 CLI 返回"未登录"错误，引导用户执行登录流程。
+
+### 输出格式与成功判定
+
+所有命令输出原始 JSON 到 stdout，错误输出到 stderr。**成功判定以退出码和 JSON 内的成功状态字段为准**（详见 [references/output-format.md](references/output-format.md)）。
+
+### 歌曲展示规范
+
+向用户展示音乐命令返回的歌曲列表时（详见 [references/output-format.md](references/output-format.md)）：
+
+- **禁止**只返回歌曲名、歌手名
+- **必须**以 Markdown 链接格式展示播放链接
+- 正确格式：`[歌曲名 - 歌手名](https://www.kugou.com/...)`
+- 禁止格式：`晴天 - 周杰伦`（无链接）、`歌曲名: 晴天, 歌手: 周杰伦`（无链接）
+
+### 推荐理由规范
+
+仅在 agent **主动推荐**场景下，歌曲列表之后**必须**追加一段 220-260 字的推荐理由（详见 [references/output-format.md#5-推荐理由主动推荐场景必写](references/output-format.md#5-推荐理由主动推荐场景必写)）：
+
+- **触发**：`recommend guess / similar / text`、`charts`、`recommend-playlist`
+- **不触发**：`search` / `search-playlist` / `favorites` / `recent` / `stats` / `playlist-songs`——用户主动查询不写
+- **三层内容**：整体歌曲风格 + 匹配逻辑 + 挑 2-3 首基于行业认知的解读
+- **字数硬约束**：220-260（含标点），超出或不足需重写
+
+### 创建歌单的调用原则
+
+详见 [references/music.md#7-创建歌单](references/music.md#7-创建歌单)：
+
+1. **被动调用**：必须用户**明确**要求创建歌单时才调用，禁止在用户仅说"推荐/搜歌"时主动创建
+2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户是否需要将当前这批歌曲创建为歌单，等用户确认后再调用
+3. **硬性默认：优先客户端创建**：用户同意后**必须先尝试** `kugou-cli control playlist create`（在本地酷狗客户端内创建，详见 [references/control.md#10-playlist-create--创建歌单](references/control.md#10-playlist-create--创建歌单)），仅当客户端不可用（不支持的操作系统 / 未运行 / 无响应 / 调用失败）时才回退到云端 `music create-playlist`
+4. **创建成功后主动询问是否播放**：无论走 `control playlist create` 还是 `music create-playlist`，**创建成功（返回成功状态）后必须主动询问用户"是否要播放这个歌单"**，等用户明确回复后再决定走哪条播放命令；用户拒绝则不做任何动作。播放路径选择：
+   - 客户端可用：优先 `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` 尝试点击播放；工具不可用时明确告知用户手动复制链接打开
+
+### 能力边界提示
+
+当用户提出的需求在 `kugou-cli` **整体能力边界之外**时，Agent 必须**明确告知用户"暂不支持该能力"**，不得擅自用其他命令拼凑代替，也不得假装能完成。
+
+**典型场景**：
+
+- `kugou-cli` 没有对应子命令（用户要的功能不在 `auth` / `music` / `control` / `install` 任何子命令中）
+- `control` 子命令在当前操作系统不支持（如 `control` 系列仅支持 Windows / macOS，Linux 不支持）
+- 命令存在但参数 / 取值已下线（如 `control open --target-type url` 已被移除）
+- CLI 整体没有相关云端 API（如批量下载、歌词编辑、播客等）
+
+**正确回应**：
+
+> 这个能力 kugou-cli 暂不支持。如果你需要该功能，可以去酷狗客户端里手动操作。
+
+**反例（不要这样做）**：
+
+- 不要用「推荐相似歌曲」伪装成「按场景生成歌单」之类的能力替代
+- 不要反复尝试不同参数 / 多次重试来"碰运气"绕过不支持
+- 不要把 CLI 报错（"unknown flag" / "unsupported"）原样翻译后甩给用户——先判断这是"能力不存在"还是"用法不对"再回应
+
+**与「客户端不可用」的区别**：本节是「命令/能力本身不存在」；「客户端不可用」是「命令存在但本机客户端未运行 / 未登录」，后者有 fallback 路径（详见上方「创建歌单的调用原则」第 3 条 + [references/control.md](references/control.md)）。两者不要混用。
 
 ---
 
@@ -93,6 +181,8 @@ description: |
 - **二进制命令**: kugou-cli
 - **安装方式**: `npm install -g @kg-ai/kugou-skill`
 
+> 关于更新：CLI 安装后会自动保持最新。具体更新机制与关闭开关见 [references/update.md](references/update.md)。如有版本相关问题，向该文档查证。
+
 ---
 
 ## 详细文档索引
@@ -101,8 +191,9 @@ description: |
 |------|------|
 | [references/auth.md](references/auth.md) | 认证命令：扫码登录、直接设置 secret、查看状态、登出 |
 | [references/music.md](references/music.md) | 音乐命令：搜索、推荐、收藏、统计、榜单、创建歌单 |
+| [references/control.md](references/control.md) | 控制命令：控制 PC/Mac 客户端播放、暂停、切歌、收藏、创建歌单等 |
 | [references/install.md](references/install.md) | 安装命令：SKILL.md 安装到各平台 |
-| [references/update.md](references/update.md) | 更新命令：检查/执行自动更新 |
+| [references/update.md](references/update.md) | 更新机制、版本检查、关闭自动更新 |
 | [references/output-format.md](references/output-format.md) | 输出格式与展示规范 |
 | [references/error-handling.md](references/error-handling.md) | 错误处理与常见错误 |
 
@@ -111,9 +202,9 @@ description: |
 ## 完整使用流程
 
 ```bash
-# 1. 登录（极简流程，详见 references/auth.md）
+# 1. 登录（详见 references/auth.md）
 kugou-cli auth login                      # 获取二维码
-# auth status 是单次查询，agent 需要外层循环调用，每次间隔 2-3 秒
+# auth status 不会内部轮询；Agent 按"阶段 A → 阶段 B → 阶段 C"自行循环
 kugou-cli auth status
 
 # 1'. 或者直接导入已持有的 secret（跳过扫码）
@@ -125,10 +216,10 @@ kugou-cli music search "周杰伦"
 # 3. 获取猜你喜欢
 kugou-cli music recommend guess
 
-# 4. 查看我的收藏
+# 4. 查看我的收藏（返回最近若干首，不支持分页）
 kugou-cli music favorites
 
-# 5. 查看最近播放
+# 5. 查看最近播放（返回最近若干条，不支持分页）
 kugou-cli music recent
 
 # 6. 查看听歌统计
@@ -138,6 +229,18 @@ kugou-cli music stats
 kugou-cli music charts 52144
 
 # 8. 创建歌单
+# 优先走客户端路径（默认）：见 references/control.md §10
+kugou-cli control playlist create --name "我的批量歌单" --mixsongids "32068120,233125060"
+# 客户端不可用时才回退到云端（详见 references/music.md §7.1）：
 kugou-cli music create-playlist "我的空歌单"
 kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
+
+# 9. 搜索歌单（拿到 global_id 后可透传给 control play-playlist）
+kugou-cli music search-playlist "周杰伦"
+kugou-cli music playlist-songs "collection_3_938985631_304_0"
+
+# 10. 控制本机酷狗客户端（仅 Windows / macOS，详见 references/control.md）
+kugou-cli control play --mixsongid 32100650 --song-name "晴天" --singer-name "周杰伦"
+kugou-cli control player --action pause
+kugou-cli control favorite song --mixsongid 32100650
 ```

package/package.json

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

package/references/auth.md

@@ -84,7 +84,7 @@ kugou-cli auth status
 | 返回 | 含义 | Agent 应做 |
 |------|------|-----------|
 | `{"logged_in": true, "nickname": "...", "login_time": "..."}` | 已登录（**已有 token 持久化**，通常是之前登录过） | 继续执行用户请求 |
-| `{"logged_in": true, "status": "success", "nickname": "..."}` | 扫码刚完成登录（**刚 SaveAuth 落盘**，本轮 status 检查中完成） | 继续执行用户请求 |
+| `{"logged_in": true, "status": "success", "nickname": "..."}` | 扫码刚完成登录（**本轮 status 检查中完成 token 持久化**） | 继续执行用户请求 |
 | `{"logged_in": false, "status": "waiting", "qrcode": "..."}` | 二维码待扫码 | **阶段 A**：2-3s 后重试 status，最多 5 次；5 次后**进入阶段 B**，停下来等用户主动反馈 |
 | `{"logged_in": false, "status": "scanned", "nickname": "...", "qrcode": "..."}` | 已扫码待确认 | 等几秒再调一次 status（用户还没在手机上点确认） |
 | `{"logged_in": false, "status": "failed", "message": "..."}` | 二维码失效（**CLI 会自动清理本地 qrcode**） | **阶段 C 验证时**才见此返回 → 重新 `auth login` 拿新图，回到 §2.2 步骤 1 |
@@ -100,7 +100,7 @@ kugou-cli auth status
 
 ### 2.3.1 边界提醒：status: failed 会清掉 qrcode
 
-**关键事实**：`cmd/auth/status.go` 在 `status != 1/3/4` 时会调 `authstore.Logout()`，**自动清理本地 qrcode 文件**（不是清理登录态）。
+**关键事实**：`status: failed` 时 CLI 会自动清理本地 qrcode 文件（**不是清理登录态**）。
 
 **在阶段 A / 阶段 C 见到 `failed` 时的处理**：