@kg-ai/kugou-skill 0.0.15 → 0.0.17

package/SKILL.md

@@ -32,7 +32,10 @@ description: |
 
 ### 关键注意事项
 
-- **登录是阻塞操作**：`kugou-cli auth login` 会持续轮询直到用户扫码确认。必须等到输出 `"status":"success"` 才能继续后续音乐操作。默认模式会自动打开系统图片查看器供扫码。`file` 模式只保存文件不打开。`base64` 模式适合 Web 前端场景。
+- **登录是阻塞操作**：`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`。
 - **输出均为 JSON**：所有命令输出原始 JSON 到 stdout，错误输出到 stderr。解析 `errcode` 字段判断成功与否（`0` 为成功）。
 - **链接展示**：输出中的 `play_link` 字段，展示给用户时转为可点击格式：
@@ -53,9 +56,8 @@ description: |
 使用前需要扫码登录。登录采用轮询机制，需等待用户扫码确认。
 
 ```bash
-kugou-cli auth login                    # 默认，保存二维码图片并打开图片查看器
-kugou-cli auth login --output file    # 只保存二维码图片，不打开
-kugou-cli auth login --output base64  # 输出 base64 图片数据（含 data:image/png;base64, 前缀）
+kugou-cli auth login                    # 默认，只保存二维码图片到临时文件（需发送图片给用户扫码）
+kugou-cli auth login --output open    # 保存并打开图片查看器（适合 TUI 模式）
 ```
 
 **登录轮询流程**（`kugou-cli auth login` 内部自动处理）：
@@ -68,7 +70,9 @@ kugou-cli auth login --output base64  # 输出 base64 图片数据（含 data:im
 5. 若超时/二维码过期输出 {"status": "failed", "message": "..."}
 ```
 
-> **输出模式选择建议**：默认模式会自动打开图片查看器弹出二维码，用户直接扫码即可，适合桌面端 Agent 使用。`file` 模式只保存到临时文件，需手动打开。`base64` 模式适合需要内嵌二维码图片展示的场景。
+> **TUI 模式判断**：Agent 应根据当前交互模式选择合适的输出模式：
+> - **TUI 模式**（命令行交互，用户可直接看到弹窗）：使用 `--output open` 自动打开二维码
+> - **其他模式**（文件交互、需要用户主动操作）：使用默认模式（file），**必须将 `qrcode_img_path` 对应的图片文件发送给用户**
 
 ---
 
@@ -122,33 +126,28 @@ kugou-cli auth login --output base64  # 输出 base64 图片数据（含 data:im
 ### 1. 扫码登录
 
 ```bash
-kugou-cli auth login
-kugou-cli auth login --output file    # 只保存二维码图片，不打开
-kugou-cli auth login --output base64  # 输出 base64 编码的图片数据（含 data:image/png;base64, 前缀）
+kugou-cli auth login                      # 默认，只保存二维码图片（需发送图片给用户扫码）
+kugou-cli auth login --output open       # 保存并打开图片查看器（适合 TUI 模式）
 ```
 
 **参数**:
 - `-o, --output`: 输出模式
-  - (默认): 保存二维码图片到临时目录并打开图片查看器，供扫码
-  - `file`: 只保存二维码图片到临时目录，不打开
-  - `base64`: 输出 base64 编码的图片数据（含 `data:image/png;base64,` 前缀）
+  - `(默认)`: 只保存二维码图片到临时目录，**需将图片文件发送给用户扫码**
+  - `open`: 保存二维码图片到临时目录并打开图片查看器
 
-**输出示例** (默认模式 - 保存并打开):
+**输出示例** (默认模式 - 保存文件):
 ```json
 {"qrcode": "xxx", "qrcode_img_path": "C:\\Users\\xxx\\AppData\\Local\\Temp\\kugou-qrcode.png", "status": "waiting"}
 ```
 
-**输出示例** (file 模式):
-```json
-{"qrcode": "xxx", "qrcode_img_path": "/tmp/kugou-qrcode.png", "status": "waiting"}
-```
-
-**输出示例** (base64 模式):
+**输出示例** (open 模式):
 ```json
-{"qrcode": "xxx", "qrcode_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "status": "waiting"}
+{"qrcode": "xxx", "qrcode_img_path": "C:\\Users\\xxx\\AppData\\Local\\Temp\\kugou-qrcode.png", "status": "waiting"}
 ```
 
-> **base64 二维码展示指导**：`qrcode_base64` 已包含 `data:image/png;base64,` 前缀，可直接作为 `<img>` 标签的 `src` 属性，或通过 Markdown `![QR](data:image/png;base64,...)` 展示。
+> **TUI 模式判断**：Agent 应根据当前交互模式选择：
+> - **TUI 模式**：使用 `--output open` 自动打开二维码，用户可直接扫码
+> - **其他模式**：使用默认模式，**必须将 `qrcode_img_path` 对应的图片文件发送给用户**
 
 **轮询过程中的状态输出**:
 - `{"status": "waiting", ...}` — 等待扫码
@@ -439,13 +438,21 @@ kugou-cli install --hermes --claude # 安装到 Hermes 和 Claude
 
 ### 展示规范
 
-向用户展示结果时：
+向用户展示结果时，**必须遵循以下规范**：
+
+1. **歌曲列表展示（强制要求）**：
+   - **禁止**只返回歌曲名、歌手名
+   - **必须**以 Markdown 链接格式展示播放链接
+   - 正确格式：`[歌曲名 - 歌手名](https://www.kugou.com/...)`
+   - 禁止格式：`晴天 - 周杰伦`（无链接）、`歌曲名: 晴天, 歌手: 周杰伦`（无链接）
 
-1. **歌曲列表**：整理为表格或列表，包含歌曲名、歌手、播放链接
-2. **播放链接**：将 `play_link` 转为可点击的超链接
+2. **播放链接转为可点击超链接**：
    - Markdown: `[歌曲名 - 歌手名](https://www.kugou.com/...)`
+   - HTML: `<a href="https://www.kugou.com/...">歌曲名 - 歌手名</a>`
+
 3. **统计数据**：提取关键字段并以结构化方式呈现（如"累计听歌 342 首，时长 22.4 小时"）
-4. **二维码**（base64 输出）：`qrcode_base64` 已含 `data:image/png;base64,` 前缀，可直接作为 `<img>` 的 `src`
+
+4. **二维码**：使用 `qrcode_img_path` 对应的图片文件发送给用户
 
 ---
 
@@ -506,10 +513,10 @@ kugou-cli music charts 52144
 ```bash
 #!/bin/bash
 
-# 搜索并提取歌曲名
+# 搜索并提取第一首歌曲的完整信息（歌曲名、歌手、播放链接）
 result=$(kugou-cli music search "周杰伦" --size 1)
-echo "$result" | jq -r '.data.list[0].song_name'
+echo "$result" | jq -r '.data.list[0] | "\(.song_name) - \(.artist_name): \(.play_link)"'
 
-# 获取榜单第一首
-kugou-cli music charts 6666 --size 1 | jq -r '.data.list[0].song_name'
+# 获取榜单第一首的 Markdown 格式
+kugou-cli music charts 6666 --size 1 | jq -r '.data.list[0] | "[\(.song_name) - \(.artist_name)](\(.play_link))"'
 ```

package/package.json

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