@kg-ai/kugou-skill 0.0.17 → 0.0.19

package/SKILL.md

@@ -25,18 +25,20 @@ description: |
 ```
 1. 检查安装 → npm install -g @kg-ai/kugou-skill
 2. 检查登录 → kugou-cli auth status
-3. 未登录 → 引导用户执行 kugou-cli auth login，等待 status: success
+3. 未登录 → 引导用户执行以下步骤：
+   a. kugou-cli auth login（获取二维码图片，输出包含 qrcode 字段）
+   b. 将二维码图片（qrcode_img_path）发送给用户
+   c. 从 login 输出中提取 qrcode 字段值，执行 kugou-cli auth check -q <qrcode>（轮询等待确认，直到 status: success）
 4. 执行用户请求的音乐命令
 5. 解析 JSON 输出，格式化展示给用户
 ```
 
 ### 关键注意事项
 
-- **登录是阻塞操作**：`kugou-cli auth login` 会持续轮询直到用户扫码确认。必须等到输出 `"status":"success"` 才能继续后续音乐操作。
-  - **默认模式（file）**：只保存二维码到临时文件，**需将图片发送给用户扫码**
-  - **`--output open` 模式**：保存二维码到临时文件并自动打开图片查看器
-  - **TUI 模式判断**：如果 Agent 当前为命令行交互模式（TUI），应使用 `--output open` 自动打开图片；如果是文件交互或需要用户主动获取图片的场景，应使用默认模式并**主动发送图片给用户**
-- **音乐命令依赖登录**：除了 `auth`、`install`、`version`、`--help` 以外，所有 `music` 子命令都需要先登录。如果收到 `"not logged in"` 错误，引导用户执行 `kugou-cli auth login`。
+- **登录流程分为两步**：
+  1. `auth login` - 获取二维码图片，输出包含 `qrcode` 和 `qrcode_img_path`（**必须将图片发送给用户**）
+  2. `auth check -q <qrcode>` - 从 login 输出中提取 qrcode 值，传入此命令轮询等待扫码确认，必须等到 `"status":"success"` 才能继续
+- **音乐命令依赖登录**：除了 `auth`、`install`、`version`、`--help` 以外，所有 `music` 子命令都需要先登录。如果收到 `"not logged in"` 错误，引导用户执行登录流程。
 - **输出均为 JSON**：所有命令输出原始 JSON 到 stdout，错误输出到 stderr。解析 `errcode` 字段判断成功与否（`0` 为成功）。
 - **链接展示**：输出中的 `play_link` 字段，展示给用户时转为可点击格式：
   - Markdown: `[歌曲名](https://www.kugou.com/...)`
@@ -53,26 +55,28 @@ description: |
 
 ### 登录
 
-使用前需要扫码登录。登录采用轮询机制，需等待用户扫码确认。
+使用前需要扫码登录。流程分为两步：
 
 ```bash
-kugou-cli auth login                    # 默认，只保存二维码图片到临时文件（需发送图片给用户扫码）
-kugou-cli auth login --output open    # 保存并打开图片查看器（适合 TUI 模式）
+# Step 1: 获取二维码图片
+kugou-cli auth login
+
+# Step 2: 轮询等待用户扫码确认（使用 Step 1 返回的 qrcode）
+kugou-cli auth check -q <qrcode>
 ```
 
-**登录轮询流程**（`kugou-cli auth login` 内部自动处理）：
+**登录流程**：
 
 ```
-1. 输出 {"qrcode": "...", "qrcode_img_path": "...", "status": "waiting"}
-2. 每 2 秒轮询一次，持续等待用户扫码
-3. 用户扫码后输出 {"status": "scanned", ...}  → 继续等待确认
-4. 用户确认后输出 {"status": "success", "nickname": "...", ...} → 登录完成
-5. 若超时/二维码过期输出 {"status": "failed", "message": "..."}
+1. auth login → 输出 {"qrcode": "...", "qrcode_img_path": "..."}
+2. 将 qrcode_img_path 对应的图片发送给用户扫码
+3. auth check -q <qrcode> → 轮询等待用户确认
+4. 用户扫码后输出 {"status": "scanned", ...} → 继续等待确认
+5. 用户确认后输出 {"status": "success", ...} → 登录完成
+6. 若超时/二维码过期输出 {"status": "failed", "message": "..."}
 ```
 
-> **TUI 模式判断**：Agent 应根据当前交互模式选择合适的输出模式：
-> - **TUI 模式**（命令行交互，用户可直接看到弹窗）：使用 `--output open` 自动打开二维码
-> - **其他模式**（文件交互、需要用户主动操作）：使用默认模式（file），**必须将 `qrcode_img_path` 对应的图片文件发送给用户**
+> **重要**：`auth login` 只获取二维码图片，**必须将 `qrcode_img_path` 对应的图片文件发送给用户**。轮询检查由 `auth check` 命令完成。
 
 ---
 
@@ -84,7 +88,8 @@ kugou-cli auth login --output open    # 保存并打开图片查看器（适合
 
 | 命令 | 说明 | 需要登录 |
 |------|------|---------|
-| `kugou-cli auth login` | 扫码登录（轮询等待确认） | 否 |
+| `kugou-cli auth login` | 获取二维码图片 | 否 |
+| `kugou-cli auth check -q <qrcode>` | 轮询等待扫码确认 | 否 |
 | `kugou-cli auth status` | 查看登录状态 | 否 |
 | `kugou-cli auth logout` | 登出 | 否 |
 
@@ -126,31 +131,21 @@ kugou-cli auth login --output open    # 保存并打开图片查看器（适合
 ### 1. 扫码登录
 
 ```bash
-kugou-cli auth login                      # 默认，只保存二维码图片（需发送图片给用户扫码）
-kugou-cli auth login --output open       # 保存并打开图片查看器（适合 TUI 模式）
-```
-
-**参数**:
-- `-o, --output`: 输出模式
-  - `(默认)`: 只保存二维码图片到临时目录，**需将图片文件发送给用户扫码**
-  - `open`: 保存二维码图片到临时目录并打开图片查看器
+# Step 1: 获取二维码图片
+kugou-cli auth login
 
-**输出示例** (默认模式 - 保存文件):
-```json
-{"qrcode": "xxx", "qrcode_img_path": "C:\\Users\\xxx\\AppData\\Local\\Temp\\kugou-qrcode.png", "status": "waiting"}
+# Step 2: 轮询等待扫码确认（使用 Step 1 返回的 qrcode）
+kugou-cli auth check -q <qrcode>
 ```
 
-**输出示例** (open 模式):
+**auth login 输出示例**:
 ```json
-{"qrcode": "xxx", "qrcode_img_path": "C:\\Users\\xxx\\AppData\\Local\\Temp\\kugou-qrcode.png", "status": "waiting"}
+{"qrcode": "xxx", "qrcode_img_path": "C:\\Users\\xxx\\AppData\\Local\\Temp\\kugou-qrcode.png"}
 ```
 
-> **TUI 模式判断**：Agent 应根据当前交互模式选择：
-> - **TUI 模式**：使用 `--output open` 自动打开二维码，用户可直接扫码
-> - **其他模式**：使用默认模式，**必须将 `qrcode_img_path` 对应的图片文件发送给用户**
+> **重要**：必须将 `qrcode_img_path` 对应的图片文件**发送给用户**供扫码登录。
 
-**轮询过程中的状态输出**:
-- `{"status": "waiting", ...}` — 等待扫码
+**auth check 轮询状态输出**:
 - `{"status": "scanned", "nickname": "...", ...}` — 已扫码，等待用户在手机上确认
 - `{"status": "success", "nickname": "...", "secret": "..."}` — 登录成功，token 已持久化
 - `{"status": "failed", "message": "QR code expired or login failed"}` — 登录失败（二维码过期），需重新执行
@@ -483,8 +478,9 @@ echo $?  # 非 0 表示出错
 ### 完整使用流程
 
 ```bash
-# 1. 登录
-kugou-cli auth login
+# 1. 登录（两步流程）
+kugou-cli auth login                      # 获取二维码
+kugou-cli auth check -q <qrcode>          # 轮询等待确认
 
 # 2. 查看登录状态
 kugou-cli auth status

package/package.json

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