@kg-ai/kugou-skill 0.0.25 → 0.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kg-ai/kugou-skill",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "description": "Kugou Skill CLI",
   "main": "index.js",
   "bin": {
@@ -16,7 +16,8 @@
   "files": [
     "bin",
     "scripts",
-    "SKILL.md"
+    "SKILL.md",
+    "references"
   ],
   "author": "",
   "license": "MIT",

package/references/auth.md

@@ -0,0 +1,75 @@
+# 认证命令 (auth)
+
+> 🔐 = 需要先登录
+
+## 命令列表
+
+| 命令 | 说明 | 需要登录 |
+|------|------|---------|
+| `kugou-cli auth login` | 获取二维码图片 | 否 |
+| `kugou-cli auth status` | 检查登录状态（已完成则登录，未完成则继续轮询） | 否 |
+| `kugou-cli auth logout` | 登出 | 否 |
+
+---
+
+## 1. 扫码登录
+
+登录流程极简：
+
+```bash
+# Step 1: 获取二维码图片
+kugou-cli auth login
+
+# Step 2: 检查登录状态（Agent 可循环调用直到 logged_in=true）
+kugou-cli auth status
+```
+
+**auth login 输出示例**:
+```json
+{"qrcode": "xxx", "qrcode_img_path": "C:\\Users\\xxx\\AppData\\Local\\Temp\\kugou-qrcode.png"}
+```
+
+> **重要**：必须将 `qrcode_img_path` 对应的图片文件**发送给用户**供扫码登录。
+
+**auth status 状态输出**:
+
+已登录：
+```json
+{"logged_in": true, "nickname": "沙墨", "login_time": "2024-01-01 12:00:00"}
+```
+
+未登录但有 pending qrcode（等待扫码）：
+```json
+{"logged_in": false, "status": "waiting", "qrcode": "xxx"}
+```
+
+未登录但已扫码（等待确认）：
+```json
+{"logged_in": false, "status": "scanned", "nickname": "xxx", "qrcode": "xxx"}
+```
+
+未登录且 qrcode 失效：
+```json
+{"logged_in": false, "status": "failed", "message": "QR code expired"}
+```
+
+---
+
+## 2. AI 引导流程
+
+1. 调用 `auth login` 获取二维码图片
+2. **必须**将 `qrcode_img_path` 对应的二维码图片发送给用户
+3. 循环调用 `auth status` 等待用户扫码
+4. 当输出 `logged_in: true` 后，登录完成，可继续执行音乐命令
+
+> **简化说明**：本工具将"轮询检查扫码状态"逻辑内置到 `auth status` 中，Agent 只需简单循环调用 status 即可。
+
+---
+
+## 3. 文件存储
+
+| 文件 | 路径 | 说明 |
+|------|------|------|
+| auth.json | `~/.config/kugou-cli/auth.json` | 登录 token 持久化 |
+| qrcode.json | `~/.config/kugou-cli/qrcode.json` | 待扫码的 qrcode（临时，登录成功后自动删除） |
+| device.json | `~/.config/kugou-cli/device.json` | 设备信息（mid/dfid） |

package/references/error-handling.md

@@ -0,0 +1,21 @@
+# 错误处理
+
+错误信息输出到 stderr，程序 exit code 为 1：
+
+```bash
+kugou-cli music search "xxx" 2>&1
+echo $?  # 非 0 表示出错
+```
+
+---
+
+## 常见错误及处理
+
+| 错误信息 | 原因 | 处理方式 |
+|---------|------|---------|
+| `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/references/install.md

@@ -0,0 +1,54 @@
+# 安装命令 (install)
+
+> 安装 SKILL.md 到各平台 skills 目录
+
+## 命令列表
+
+| 命令 | 说明 |
+|------|------|
+| `kugou-cli install` | 显示平台选择提示 |
+| `kugou-cli install --all` | 安装 SKILL.md 到所有平台 |
+| `kugou-cli install --claude` | 安装到 Claude skills 目录 |
+| `kugou-cli install --mavis` | 安装到 Mavis skills 目录 |
+| `kugou-cli install --hermes` | 安装到 Hermes skills 目录 |
+| `kugou-cli install --openclaw` | 安装到 Openclaw skills 目录 |
+| `kugou-cli install --codex` | 安装到 Codex skills 目录 |
+
+---
+
+## 详细用法
+
+```bash
+kugou-cli install                    # 显示平台选择提示
+kugou-cli install --all              # 安装到所有平台
+kugou-cli install --claude           # 仅安装到 Claude
+kugou-cli install --hermes --claude  # 安装到 Hermes 和 Claude
+```
+
+**参数**:
+- `--claude`: 安装到 `~/.claude/skills/kugou-skill/`
+- `--mavis`: 安装到 `~/.mavis/skills/kugou-skill/`
+- `--hermes`: 安装到 `~/.hermes/skills/kugou-skill/`
+- `--openclaw`: 安装到 `~/.openclaw/skills/kugou-skill/`
+- `--codex`: 安装到 `~/.codex/skills/kugou-skill/`
+- `--workbuddy`: 安装到 `~/.workbuddy/skills/kugou-skill/`
+- `--all`: 安装到以上所有平台
+
+---
+
+## 行为说明
+
+- 无参数时输出"平台选择提示"，列出可用平台选项，不会进行任何安装操作
+- 只会在目标平台的 skills 父目录存在时才安装（不自动创建父目录）
+- npm 安装时会自动调用 install.js 安装 SKILL.md
+- `kugou-cli install` 命令用于手动重新安装或更新 SKILL.md
+
+---
+
+## 通用命令
+
+| 命令 | 说明 |
+|------|------|
+| `kugou-cli --version` / `kugou-cli version` | 输出版本号 |
+| `kugou-cli --help` | 显示帮助信息 |
+| `kugou-cli <子命令> --help` | 显示子命令帮助（如 `kugou-cli music search --help`）|

package/references/music.md

@@ -0,0 +1,273 @@
+# 音乐命令 (music)
+
+> 🔐 = 所有 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>` | 榜单 |
+
+---
+
+## 1. 搜索歌曲
+
+```bash
+kugou-cli music search "周杰伦"
+kugou-cli music search "周杰伦" --page 1 --size 20
+```
+
+**参数**:
+- `<keyword>`: 搜索关键词（必填）
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "song_name": "晴天",
+        "mix_song_id": "32100650",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html"
+      }
+    ],
+    "total": 480,
+    "page": 1,
+    "size": 20
+  },
+  "status": 1
+}
+```
+
+---
+
+## 2. 歌曲推荐
+
+支持三种推荐模式：
+
+| 类型 | 说明 | 必填参数 |
+|------|------|---------|
+| `guess` | 猜你喜欢，基于用户喜好推荐 | 无 |
+| `similar` | 相似推荐，根据指定歌曲推荐相似歌曲 | `--song` |
+| `text` | 文本推歌，根据文本描述推荐歌曲 | `--text` |
+
+### 2.1 猜你喜欢
+
+```bash
+kugou-cli music recommend guess
+kugou-cli music recommend guess --num 10
+```
+
+**参数**:
+- `--num`: 推荐数量，默认 10
+
+### 2.2 相似推荐
+
+```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`: 描述文本（可选），用于进一步细化相似方向
+
+### 2.3 文本推歌
+
+```bash
+kugou-cli music recommend text --text "适合跑步时听的快节奏歌曲"
+kugou-cli music recommend text --text "安静的钢琴曲" --num 5
+```
+
+**参数**:
+- `-t, --text`: 文本描述（必填）
+- `-n, --num`: 推荐数量，默认 10
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "song_name": "稻香",
+        "mix_song_id": "8889",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/xxx.html"
+      }
+    ]
+  },
+  "status": 1
+}
+```
+
+---
+
+## 4. 我的收藏
+
+```bash
+kugou-cli music favorites
+kugou-cli music favorites --page 1 --size 20
+```
+
+**参数**:
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20
+
+> 注意：固定返回最近 10 首收藏，查看更多请前往酷狗App
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "song_name": "晴天",
+        "mix_song_id": "32100650",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html"
+      }
+    ],
+    "total": 50,
+    "msg": "当前仅显示最近的10首收藏，查看更多内容，请前往酷狗App"
+  },
+  "status": 1
+}
+```
+
+---
+
+## 5. 最近播放
+
+```bash
+kugou-cli music recent
+kugou-cli music recent --page 1 --size 20
+```
+
+**参数**:
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20
+
+> 注意：固定返回最近 10 首播放记录，查看更多请前往酷狗App
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "song_name": "七里香",
+        "mix_song_id": "32100651",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html"
+      }
+    ],
+    "total": 100,
+    "msg": "当前仅显示最近的10首最近播放，查看更多内容，请前往酷狗App"
+  },
+  "status": 1
+}
+```
+
+---
+
+## 6. 听歌统计
+
+```bash
+kugou-cli music stats                    # 默认查当月
+kugou-cli music stats --date-type 1 --date 20260501  # 指定周查询
+```
+
+**参数**:
+- `--date-type`: 日期类型，0=日、1=周、2=月，默认 2（月）
+- `--date`: 查询日期，YYYYMMDD 格式，如 "20260501"（不填默认当月第一天）
+  - 日类型：每天日期，如 "20260501"
+  - 周类型：必须是周一日期，如 "20260505"（周一）
+  - 月类型：必须是月份第一天，如 "20260501"（5月1日）
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "server_time": 1779977674,
+    "listen_duration": 80776,
+    "accumulate_listen_days": 30,
+    "continue_listen_days": 7,
+    "listen_total": 342,
+    "last_listen_total": 387,
+    "top_clocks": [
+      "今日08:00-10:00听歌30分钟",
+      "今日14:00-16:00听歌25分钟",
+      "今日20:00-22:00听歌20分钟"
+    ],
+    "rank_song": [
+      {
+        "song_info": {"song_name": "晴天", "mix_song_id": "8888", "artist_name": "周杰伦", "play_link": "https://www.kugou.com/..."},
+        "count": 50
+      }
+    ],
+    "rank_singer": [
+      {"singer_id": 123, "name": "周杰伦", "avatar": "https://xxx.jpg", "total": 120}
+    ],
+    "rank_style": [
+      {"style": "流行", "total": 200, "count": 80}
+    ],
+    "rank_language": [
+      {"language": "华语", "total": 400, "count": 150}
+    ]
+  },
+  "status": 1
+}
+```
+
+**关键字段**:
+- `listen_duration`: 今日/周/月听歌时长（秒）
+- `top_clocks`: 听歌时长最长的 Top3 时段描述（日类型格式如"今日08:00-10:00听歌30分钟"，周/月类型格式如"2026-02月听歌38213分钟"）
+- `accumulate_listen_days`: 累计听歌天数
+- `continue_listen_days`: 连续听歌天数
+- `listen_total`: 累计听歌次数
+- `last_listen_total`: 昨日/上周/上月听歌次数
+- `rank_song`: 播放最多的歌曲排行（`count` 为播放次数）
+- `rank_singer`: 播放最多的歌手排行
+- `rank_style`: 曲风分布统计
+- `rank_language`: 语言分布统计
+
+---
+
+## 7. 榜单
+
+```bash
+kugou-cli music charts 6666
+kugou-cli music charts 52144 --page 1 --size 20
+```
+
+**可用榜单 ID**:
+
+| rank_id | 榜单名称 |
+|---------|----------|
+| 8888 | TOP500榜 |
+| 90379 | 星耀星光榜 |
+| 6666 | 飙升榜 |
+| 85432 | 百万收藏榜 |
+| 74534 | 新歌榜 |
+| 52144 | 抖音热歌酷狗榜 |
+
+**参数**:
+- `<rank_id>`: 榜单 ID（必填）
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20

package/references/output-format.md

@@ -0,0 +1,42 @@
+# 输出格式与展示规范
+
+## 通用响应结构
+
+所有 API 命令输出标准 JSON 结构：
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "",
+  "data": { ... },
+  "status": 1
+}
+```
+
+**响应状态**:
+- `errcode: 0` 表示成功
+- `data` 包含实际业务数据
+- `status: 1` 表示接口调用成功
+
+---
+
+## 展示规范
+
+向用户展示结果时，**必须遵循以下规范**：
+
+### 1. 歌曲列表展示（强制要求）
+
+- **禁止**只返回歌曲名、歌手名
+- **必须**以 Markdown 链接格式展示播放链接
+- 正确格式：`[歌曲名 - 歌手名](https://www.kugou.com/...)`
+- 禁止格式：`晴天 - 周杰伦`（无链接）、`歌曲名: 晴天, 歌手: 周杰伦`（无链接）
+
+### 2. 统计数据
+
+提取关键字段并以结构化方式呈现（如"累计听歌 342 首，时长 22.4 小时"）
+
+### 3. 二维码
+
+使用 `qrcode_img_path` 对应的图片文件发送给用户
+
+---

package/references/update.md

@@ -0,0 +1,128 @@
+# 更新命令 (update)
+
+> 自动检查并更新 kugou-cli
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `kugou-cli update --check` | 仅检查更新，不执行 |
+| `kugou-cli update` | 检查并提示（不自动执行） |
+| `kugou-cli update --force` | 直接执行更新（仅 npm 安装） |
+
+---
+
+## 工作机制
+
+### 1. 启动时检查
+
+每次执行任意 `kugou-cli` 命令时，**后台异步**检查 npm registry 上的最新版本。
+
+- **不阻塞** 主命令
+- 有更新时输出到 **stderr**（避免污染 stdout JSON 输出）
+- 提示格式：
+  ```
+  [kugou-cli] update available: 0.0.22 → 0.0.23 (run `kugou-cli update` to upgrade)
+  ```
+
+### 2. 检查频率限制
+
+- 缓存文件：`~/.config/kugou-cli/update_check.json`
+- 缓存有效期：**24 小时**
+- 24 小时内不会重复访问 npm registry
+
+### 3. 跳过检查
+
+在以下情况跳过启动检查：
+- `CI=true` 环境变量
+- `KUGOU_CLI_NO_UPDATE_CHECK=1` 环境变量
+- 命令行指定 `--no-update-check` flag
+
+---
+
+## 显式检查更新
+
+```bash
+kugou-cli update --check
+```
+
+**输出示例**：
+
+有更新时：
+```json
+{
+  "current_version": "0.0.22",
+  "latest_version": "0.0.23",
+  "update_available": true,
+  "install_method": "npm",
+  "update_command": "npm install -g @kg-ai/kugou-skill@latest"
+}
+```
+
+无更新时：
+```json
+{
+  "current_version": "0.0.22",
+  "latest_version": "0.0.22",
+  "update_available": false,
+  "install_method": "npm"
+}
+```
+
+---
+
+## 执行更新
+
+### 方式 1：Agent / 脚本（推荐）
+
+```bash
+# 步骤 1: 检查
+info=$(kugou-cli update --check)
+update_available=$(echo "$info" | jq -r '.update_available')
+
+# 步骤 2: 如果有更新，提示用户确认后执行
+if [ "$update_available" = "true" ]; then
+  echo "有可用更新，正在升级..."
+  kugou-cli update --force
+fi
+```
+
+### 方式 2：手动
+
+```bash
+# 提示但不执行
+kugou-cli update
+# 显示: About to run: npm install -g @kg-ai/kugou-skill@latest
+
+# 强制执行
+kugou-cli update --force
+```
+
+### 方式 3：标准 npm 命令
+
+无需 `update` 子命令，直接：
+```bash
+npm install -g @kg-ai/kugou-skill@latest
+```
+
+---
+
+## 安装方式检测
+
+CLI 自动检测安装方式：
+
+| 安装方式 | 检测方法 | 是否支持自动更新 |
+|---------|---------|------------------|
+| **npm** | 二进制路径包含 `node_modules/@kg-ai/kugou-skill` | ✅ 支持 |
+| **其他**（源码编译 / 手动下载） | 其他路径 | ❌ 仅提示 |
+
+非 npm 安装时，CLI 只会提示，不会自动更新。请使用对应方式更新。
+
+---
+
+## 注意事项
+
+1. **网络要求**：检查更新需要访问 `https://registry.npmjs.org`，在受限网络下可能失败
+2. **离线友好**：网络失败时静默忽略，不影响主命令
+3. **CI 友好**：CI 环境默认跳过检查，避免污染日志
+4. **不强制**：默认仅提示，更新需用户/Agent 显式确认