@kg-ai/kugou-skill 0.0.3 → 0.0.5

package/SKILL.md

@@ -8,6 +8,29 @@ description: |
 
 # kugou-skill
 
+## AI 使用工作流（优先阅读）
+
+使用本工具时的标准流程：
+
+```
+1. 检查安装 → npm install -g @kg-ai/kugou-skill
+2. 检查登录 → kugou-cli auth status
+3. 未登录 → 引导用户执行 kugou-cli auth login，等待 status: success
+4. 执行用户请求的音乐命令
+5. 解析 JSON 输出，格式化展示给用户
+```
+
+### 关键注意事项
+
+- **登录是阻塞操作**：`kugou-cli auth login` 会持续轮询直到用户扫码确认。必须等到输出 `"status":"success"` 才能继续后续音乐操作。
+- **音乐命令依赖登录**：除了 `auth`、`install`、`version`、`--help` 以外，所有 `music` 子命令都需要先登录。如果收到 `"not logged in"` 错误，引导用户执行 `kugou-cli auth login`。
+- **输出均为 JSON**：所有命令输出原始 JSON 到 stdout，错误输出到 stderr。解析 `errcode` 字段判断成功与否（`0` 为成功）。
+- **链接展示**：输出中的 `play_link` 字段，展示给用户时转为可点击格式：
+  - Markdown: `[歌曲名](https://www.kugou.com/...)`
+  - HTML: `<a href="https://www.kugou.com/...">歌曲名</a>`
+
+---
+
 ## 基础信息
 
 - **npm 包**: @kg-ai/kugou-skill
@@ -15,46 +38,73 @@ description: |
 - **API 域名**: https://agentgateway.kugou.com（固定，无需配置）
 - **安装方式**: `npm install -g @kg-ai/kugou-skill`
 
-## 前置条件
+### 登录
+
+使用前需要扫码登录。登录采用轮询机制，需等待用户扫码确认。
 
-使用前需要扫码登录：
 ```bash
 kugou-cli auth login
+kugou-cli auth login --output image    # 默认，保存二维码图片到临时目录
+kugou-cli auth login --output base64  # 输出 base64 图片数据（含 data:image/png;base64, 前缀）
+kugou-cli auth login --output terminal # 打开系统图片查看器扫码
+```
+
+**登录轮询流程**（`kugou-cli auth login` 内部自动处理）：
+
+```
+1. 输出 {"qrcode": "...", "qrcode_img_path": "...", "status": "waiting"}
+2. 每 2 秒轮询一次，持续等待用户扫码
+3. 用户扫码后输出 {"status": "scanned", ...}  → 继续等待确认
+4. 用户确认后输出 {"status": "success", "nickname": "...", ...} → 登录完成
+5. 若超时/二维码过期输出 {"status": "failed", "message": "..."}
 ```
-登录后 token 会自动持久化存储。
+
+> **重要**：登录成功后 token 自动持久化到 `~/.config/kugou-cli/auth.json`，后续无需重复登录。
+
+---
 
 ## 命令列表
 
+> 🔐 = 需要先登录
+
 ### 认证命令 (auth)
 
-| 命令 | 说明 |
-|------|------|
-| `kugou-cli auth login` | 扫码登录（返回二维码信息） |
-| `kugou-cli auth status` | 查看登录状态 |
-| `kugou-cli auth logout` | 登出 |
+| 命令 | 说明 | 需要登录 |
+|------|------|---------|
+| `kugou-cli auth login` | 扫码登录（轮询等待确认） | 否 |
+| `kugou-cli auth status` | 查看登录状态 | 否 |
+| `kugou-cli auth logout` | 登出 | 否 |
 
 ### 音乐命令 (music)
 
-| 命令 | 说明 |
-|------|------|
-| `kugou-cli music search <keyword>` | 搜索歌曲 |
-| `kugou-cli music recommend daily` | 每日推荐 |
-| `kugou-cli music recommend similar -s <song>` | 相似歌曲推荐 |
-| `kugou-cli music favorites` | 我的收藏 |
-| `kugou-cli music recent` | 最近播放 |
-| `kugou-cli music stats` | 听歌统计 |
-| `kugou-cli music charts <rank_id>` | 榜单 |
+| 命令 | 说明 | 需要登录 |
+|------|------|---------|
+| `kugou-cli music search <keyword>` | 搜索歌曲 | 🔐 |
+| `kugou-cli music recommend daily` | 每日推荐 | 🔐 |
+| `kugou-cli music recommend similar -s <song>` | 相似歌曲推荐 | 🔐 |
+| `kugou-cli music favorites` | 我的收藏 | 🔐 |
+| `kugou-cli music recent` | 最近播放 | 🔐 |
+| `kugou-cli music stats` | 听歌统计 | 🔐 |
+| `kugou-cli music charts <rank_id>` | 榜单 | 🔐 |
 
 ### 安装命令 (install)
 
+| 命令 | 说明 | 需要登录 |
+|------|------|---------|
+| `kugou-cli install` | 显示平台选择提示 | 否 |
+| `kugou-cli install --all` | 安装 SKILL.md 到所有平台 | 否 |
+| `kugou-cli install --claude` | 安装到 Claude skills 目录 | 否 |
+| `kugou-cli install --hermes` | 安装到 Hermes skills 目录 | 否 |
+| `kugou-cli install --openclaw` | 安装到 Openclaw skills 目录 | 否 |
+| `kugou-cli install --codex` | 安装到 Codex skills 目录 | 否 |
+
+### 通用命令
+
 | 命令 | 说明 |
 |------|------|
-| `kugou-cli install` | 显示帮助信息 |
-| `kugou-cli install --all` | 安装 SKILL.md 到所有平台 |
-| `kugou-cli install --claude` | 安装到 Claude skills 目录 |
-| `kugou-cli install --hermes` | 安装到 Hermes skills 目录 |
-| `kugou-cli install --openclaw` | 安装到 Openclaw skills 目录 |
-| `kugou-cli install --codex` | 安装到 Codex skills 目录 |
+| `kugou-cli --version` / `kugou-cli version` | 输出版本号 |
+| `kugou-cli --help` | 显示帮助信息 |
+| `kugou-cli <子命令> --help` | 显示子命令帮助（如 `kugou-cli music search --help`）|
 
 ---
 
@@ -85,15 +135,18 @@ kugou-cli auth login --output terminal # 打开图片查看器扫码（Windows/m
 {"qrcode": "xxx", "qrcode_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "status": "waiting"}
 ```
 
+> **base64 二维码展示指导**：`qrcode_base64` 已包含 `data:image/png;base64,` 前缀，可直接作为 `<img>` 标签的 `src` 属性，或通过 Markdown `![QR](data:image/png;base64,...)` 展示。
+
 **输出示例** (terminal 模式):
 ```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", "status": "waiting"}
 ```
 
-**轮询状态**:
-- `status: scanned` - 已扫码，等待确认
-- `status: success` - 登录成功
-- `status: failed` - 登录失败（二维码过期）
+**轮询过程中的状态输出**:
+- `{"status": "waiting", ...}` — 等待扫码
+- `{"status": "scanned", "nickname": "...", ...}` — 已扫码，等待用户在手机上确认
+- `{"status": "success", "nickname": "...", "secret": "..."}` — 登录成功，token 已持久化
+- `{"status": "failed", "message": "QR code expired or login failed"}` — 登录失败（二维码过期），需重新执行
 
 ---
 
@@ -110,7 +163,7 @@ kugou-cli auth status
 
 ---
 
-### 3. 搜索歌曲
+### 3. 搜索歌曲 🔐
 
 ```bash
 kugou-cli music search "周杰伦"
@@ -145,34 +198,36 @@ kugou-cli music search "周杰伦" --page 1 --size 20
 
 ---
 
-### 4. 每日推荐
+### 4. 每日推荐 🔐
 
 ```bash
 kugou-cli music recommend daily
 kugou-cli music recommend daily --num 10
+kugou-cli music recommend daily --text "轻快的中文歌" --num 5
 ```
 
 **参数**:
 - `--num`: 推荐数量，默认 10
-- `--text`: 描述文本（可选）
+- `--text`: 描述文本（可选），用于个性化推荐偏好。例如 `"轻快的"` / `"安静的"` / `"粤语歌"` 等，来影响推荐结果。
 
 ---
 
-### 5. 相似推荐
+### 5. 相似推荐 🔐
 
 ```bash
 kugou-cli music recommend similar -s "晴天"
 kugou-cli music recommend similar --song "晴天" -n 5
+kugou-cli music recommend similar --song "晴天" --text "风格相似的" -n 5
 ```
 
 **参数**:
 - `-s, --song`: 歌曲名称（必填）
 - `-n, --num`: 推荐数量，默认 10
-- `-t, --text`: 描述文本（可选）
+- `-t, --text`: 描述文本（可选），用于进一步细化相似方向。
 
 ---
 
-### 6. 我的收藏
+### 6. 我的收藏 🔐
 
 ```bash
 kugou-cli music favorites
@@ -185,7 +240,7 @@ kugou-cli music favorites --page 1 --size 20
 
 ---
 
-### 7. 最近播放
+### 7. 最近播放 🔐
 
 ```bash
 kugou-cli music recent
@@ -198,7 +253,7 @@ kugou-cli music recent --page 1 --size 20
 
 ---
 
-### 8. 听歌统计
+### 8. 听歌统计 🔐
 
 ```bash
 kugou-cli music stats
@@ -211,14 +266,29 @@ kugou-cli music stats
   "data": {
     "server_time": 1779977674,
     "listen_duration": 80776,
+    "clocks": [
+      {"clock": 0, "listen_duration": 1200},
+      {"clock": 1, "listen_duration": 800}
+    ],
     "accumulate_listen_days": 1,
     "continue_listen_days": 1,
     "listen_total": 342,
     "last_listen_total": 387,
-    "rank_song": [...],
-    "rank_singer": [...],
-    "rank_style": [...],
-    "rank_language": [...]
+    "rank_song": [
+      {
+        "song_info": {"song_name": "晴天", "mix_song_id": "xxx", "artist_name": "周杰伦", "play_link": "https://..."},
+        "count": 50
+      }
+    ],
+    "rank_singer": [
+      {"singer_id": 123, "name": "周杰伦", "avatar": "https://...", "total": 120}
+    ],
+    "rank_style": [
+      {"style": "流行", "total": 200, "count": 80}
+    ],
+    "rank_language": [
+      {"language": "国语", "total": 180, "count": 70}
+    ]
   },
   "status": 1
 }
@@ -227,12 +297,15 @@ kugou-cli music stats
 **关键字段**:
 - `listen_duration`: 累计听歌时长（秒）
 - `listen_total`: 累计听歌数量
-- `rank_song`: 播放最多的歌曲排行
+- `clocks`: 每个小时的听歌时长分布（`clock`: 0-23，`listen_duration`: 秒）
+- `rank_song`: 播放最多的歌曲排行（`count` 为播放次数）
 - `rank_singer`: 播放最多的歌手排行
+- `rank_style`: 曲风分布统计
+- `rank_language`: 语言分布统计
 
 ---
 
-### 9. 榜单
+### 9. 榜单 🔐
 
 ```bash
 kugou-cli music charts 6666
@@ -260,6 +333,7 @@ kugou-cli music charts 52144 --page 1 --size 20
 ### 10. 安装 SKILL.md
 
 ```bash
+kugou-cli install                    # 显示平台选择提示
 kugou-cli install --all              # 安装到所有平台
 kugou-cli install --claude           # 仅安装到 Claude
 kugou-cli install --hermes --claude # 安装到 Hermes 和 Claude
@@ -272,10 +346,11 @@ kugou-cli install --hermes --claude # 安装到 Hermes 和 Claude
 - `--codex`: 安装到 `~/.codex/skills/kugou-skill/`
 - `--all`: 安装到以上所有平台
 
-**说明**:
+**行为说明**:
+- 无参数时输出"平台选择提示"，列出可用平台选项，不会进行任何安装操作
+- 只会在目标平台的 skills 父目录存在时才安装（不自动创建父目录）
 - npm 安装时会自动调用 install.js 安装 SKILL.md
 - `kugou-cli install` 命令用于手动重新安装或更新 SKILL.md
-- 只在目标平台目录存在时才安装，不自动创建目录
 
 ---
 
@@ -288,11 +363,12 @@ kugou-cli install --hermes --claude # 安装到 Hermes 和 Claude
   kugou-cli music search "周杰伦" --proxy "http://127.0.0.1:7890"
   ```
 
-## 输出格式
+## 输出格式与展示规范
+
+### 通用响应结构
 
-所有命令输出原始 JSON 响应，方便程序解析。
+所有 API 命令输出标准 JSON 结构：
 
-**通用响应结构**:
 ```json
 {
   "errcode": 0,
@@ -307,6 +383,16 @@ kugou-cli install --hermes --claude # 安装到 Hermes 和 Claude
 - `data` 包含实际业务数据
 - `status: 1` 表示接口调用成功
 
+### 展示规范
+
+向用户展示结果时：
+
+1. **歌曲列表**：整理为表格或列表，包含歌曲名、歌手、播放链接
+2. **播放链接**：将 `play_link` 转为可点击的超链接
+   - Markdown: `[歌曲名 - 歌手名](https://www.kugou.com/...)`
+3. **统计数据**：提取关键字段并以结构化方式呈现（如"累计听歌 342 首，时长 22.4 小时"）
+4. **二维码**（base64 输出）：`qrcode_base64` 已含 `data:image/png;base64,` 前缀，可直接作为 `<img>` 的 `src`
+
 ---
 
 ## 错误处理
@@ -318,10 +404,16 @@ kugou-cli music search "xxx" 2>&1
 echo $?  # 非 0 表示出错
 ```
 
-**常见错误**:
-- `not logged in`: 需要先登录
-- `HTTP error: 400/500`: 服务端错误
-- `network error`: 网络连接问题
+**常见错误及处理**:
+
+| 错误信息 | 原因 | 处理方式 |
+|---------|------|---------|
+| `not logged in` / `auth file not found` | 未登录 | 引导用户执行 `kugou-cli auth login` |
+| `HTTP error: 400` | 请求参数有误 | 检查命令参数是否正确 |
+| `HTTP error: 500` | 服务端错误 | 稍后重试，或告知用户 |
+| `API error: ...` | 业务错误（errcode 非 0） | 根据 errmsg 提示用户 |
+| `network error: ...` | 网络连接问题 | 检查网络，可尝试 `--proxy` |
+| `failed to get device info` | 设备信息获取失败 | 运行时环境异常，检查权限 |
 
 ---
 

package/package.json

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