@kg-ai/kugou-skill 0.1.2 → 0.1.4

package/README.md

@@ -1,139 +1,139 @@
-# Kugou CLI
-
-酷狗音乐 API CLI 工具，用于搜索、推荐、收藏、统计、榜单等功能。
-
-## 安装
-
-### npm 安装（推荐）
-
-```bash
-npm install -g @kg-ai/kugou-skill
-```
-
-安装后使用 `kugou-cli` 命令。npm 安装时会自动安装 SKILL.md 到各平台的 skills 目录。
-
-## 前置条件
-
-使用前需要扫码登录（极简流程）：
-
-```bash
-# Step 1: 获取二维码图片
-kugou-cli auth login
-
-# Step 2: 循环检查登录状态（直到 logged_in=true）
-kugou-cli auth status
-```
-
-> 必须将 Step 1 输出中 `qrcode_img_path` 对应的图片发送给用户扫码。token 会自动持久化存储。
-
-## 命令
-
-### 认证
-
-```bash
-# 获取二维码图片
-kugou-cli auth login
-
-# 检查登录状态（未完成登录时内部自动轮询）
-kugou-cli auth status
-
-# 登出
-kugou-cli auth logout
-```
-
-### 音乐
-
-```bash
-# 搜索歌曲
-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 similar --song "晴天"
-kugou-cli music recommend similar -s "晴天" -n 5
-
-# 我的收藏
-kugou-cli music favorites
-kugou-cli music favorites --page 1 --size 20
-
-# 最近播放
-kugou-cli music recent
-kugou-cli music recent --page 1 --size 20
-
-# 听歌统计
-kugou-cli music stats
-
-# 酷狗榜单
-kugou-cli music charts 6666    # 飙升榜
-kugou-cli music charts 8888    # TOP500榜
-kugou-cli music charts 52144  # 抖音热歌酷狗榜
-kugou-cli music charts 90379  # 星耀星光榜
-kugou-cli music charts 85432  # 百万收藏榜
-kugou-cli music charts 74534  # 新歌榜
-
-# 创建歌单
-kugou-cli music create-playlist "我的空歌单"
-kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
-```
-
-### 安装 SKILL.md
-
-```bash
-# 安装到所有平台
-kugou-cli install --all
-
-# 安装到指定平台
-kugou-cli install --claude
-kugou-cli install --mavis
-kugou-cli install --hermes --openclaw --codex
-```
-
-### 全局
-
-```bash
-kugou-cli --version
-kugou-cli --help
-
-# 检查更新
-kugou-cli update --check
-
-# 更新（仅 npm 安装支持）
-kugou-cli update --force
-```
-
-## 输出格式
-
-所有命令输出 JSON 格式，方便其他程序调用：
-
-```json
-{
-  "errcode": 0,
-  "data": {
-    "list": [
-      {
-        "song_name": "晴天",
-        "mix_song_id": "32100650",
-        "artist_name": "周杰伦",
-        "play_link": "https://www.kugou.com/mixsong/agent_gateway/xxx.html"
-      }
-    ],
-    "total": 480,
-    "page": 1,
-    "size": 20
-  },
-  "status": 1
-}
-```
-
-## 错误处理
-
-错误信息输出到 stderr，程序 exit code 为 1：
-
-```bash
-kugou-cli music search "xxx" 2>&1
-echo $?  # 非 0 表示出错
-```
+# Kugou CLI
+
+酷狗音乐 API CLI 工具，用于搜索、推荐、收藏、统计、榜单等功能。
+
+## 安装
+
+### npm 安装（推荐）
+
+```bash
+npm install -g @kg-ai/kugou-skill
+```
+
+安装后使用 `kugou-cli` 命令。npm 安装时会自动安装 SKILL.md 到各平台的 skills 目录。
+
+## 前置条件
+
+使用前需要扫码登录（极简流程）：
+
+```bash
+# Step 1: 获取二维码图片
+kugou-cli auth login
+
+# Step 2: 循环检查登录状态（直到 logged_in=true）
+kugou-cli auth status
+```
+
+> 必须将 Step 1 输出中 `qrcode_img_path` 对应的图片发送给用户扫码。token 会自动持久化存储。
+
+## 命令
+
+### 认证
+
+```bash
+# 获取二维码图片
+kugou-cli auth login
+
+# 检查登录状态（未完成登录时内部自动轮询）
+kugou-cli auth status
+
+# 登出
+kugou-cli auth logout
+```
+
+### 音乐
+
+```bash
+# 搜索歌曲
+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 similar --song "晴天"
+kugou-cli music recommend similar -s "晴天" -n 5
+
+# 我的收藏
+kugou-cli music favorites
+kugou-cli music favorites --page 1 --size 20
+
+# 最近播放
+kugou-cli music recent
+kugou-cli music recent --page 1 --size 20
+
+# 听歌统计
+kugou-cli music stats
+
+# 酷狗榜单
+kugou-cli music charts 6666    # 飙升榜
+kugou-cli music charts 8888    # TOP500榜
+kugou-cli music charts 52144  # 抖音热歌酷狗榜
+kugou-cli music charts 90379  # 星耀星光榜
+kugou-cli music charts 85432  # 百万收藏榜
+kugou-cli music charts 74534  # 新歌榜
+
+# 创建歌单
+kugou-cli music create-playlist "我的空歌单"
+kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
+```
+
+### 安装 SKILL.md
+
+```bash
+# 安装到所有平台
+kugou-cli install --all
+
+# 安装到指定平台
+kugou-cli install --claude
+kugou-cli install --mavis
+kugou-cli install --hermes --openclaw --codex
+```
+
+### 全局
+
+```bash
+kugou-cli --version
+kugou-cli --help
+
+# 检查更新
+kugou-cli update --check
+
+# 更新（仅 npm 安装支持）
+kugou-cli update --force
+```
+
+## 输出格式
+
+所有命令输出 JSON 格式，方便其他程序调用：
+
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "song_name": "晴天",
+        "mix_song_id": "32100650",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/xxx.html"
+      }
+    ],
+    "total": 480,
+    "page": 1,
+    "size": 20
+  },
+  "status": 1
+}
+```
+
+## 错误处理
+
+错误信息输出到 stderr，程序 exit code 为 1：
+
+```bash
+kugou-cli music search "xxx" 2>&1
+echo $?  # 非 0 表示出错
+```

package/SKILL.md

@@ -38,6 +38,8 @@ description: |
   1. `auth login` - 获取二维码图片，输出包含 `qrcode` 和 `qrcode_img_path`（**必须将图片发送给用户**）
   2. `auth status` - 循环调用此命令检查登录状态：已登录返回 `logged_in: true`；未登录但有 pending qrcode 时内部自动检查扫码状态，扫码成功则自动完成登录
 - **直接导入 secret 登录**：当用户**已经持有**一个有效的 base64 secret 字符串（从别处获取的），直接调用 `kugou-cli auth set-secret "<secret>"` 即可完成登录，**跳过扫码流程**。这与扫码登录保存到同一份 `auth.json`，效果完全一致。secret 字符串含 `+` `/` `=` 是正常的，shell 里务必用引号包起来。
+- **登出 (auth logout)**：会**先**与服务端同步登出，**确认成功后才**清理本地登录态。失败时本地态保留、可重试；未登录时幂等直接返回成功。
+- **登录态自动失效**：当任意 `music` 命令遇到登录态过期时，CLI 会**自动清理**本地登录态，并在 stderr 输出 `账号登录过期，请重新登录`。Agent 收到该错误后**直接引导用户重新登录**（`auth login` / `auth set-secret`），无需手动清理。
 - **音乐命令依赖登录**：除了 `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`

package/package.json

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

package/references/auth.md

@@ -113,6 +113,35 @@ secret cannot be empty
 
 **上游校验时机**：
 - CLI 不做本地格式校验（不做 base64 解码、不解密），只做"非空"检查
-- secret 实际有效性在**第一次**调用 `music <sub>` 时由上游校验；secret 失效/过期会返回 `errcode: 30001`（密钥错误）
+- secret 实际有效性在**第一次**调用 `music <sub>` 时由上游校验
+
+**登录态过期处理**：
+- 当任意 `music` 命令遇到登录态过期时，CLI 会**自动清理**本地登录态，并在 stderr 输出 `账号登录过期，请重新登录`，以非 0 exit code 退出
+- Agent 收到该错误后应**直接引导用户重新登录**（`auth login` 走扫码，或 `auth set-secret` 导入新 secret），无需手动清理本地文件
+- 之后调用 `auth status` 会得到 `{"logged_in": false}`（本地已无登录态）
+
+---
+
+## 4. 登出 (logout)
+
+**命令**：
+
+```bash
+kugou-cli auth logout
+```
+
+**行为**：
+1. **未登录时**：幂等直接返回 `{"status": "logged out"}`
+2. **已登录时**：CLI 会先与服务端同步登出，**确认成功后才**清理本地登录态。任何一步失败都会在 stderr 报错并保留本地登录态，以便用户重试
+3. 成功输出：`{"status": "logged out"}`
+
+**失败场景**：
+- 网络/服务端异常 → stderr 报错，**不清理**本地，提示用户稍后重试
+- 此时再次执行 `auth status` 仍会显示 `logged_in: true`，本地登录态被保留
+
+**AI 引导建议**：
+- 用户说"登出 / 退出登录 / 注销"时直接执行 `auth logout`
+- 看到 `{"status": "logged out"}` 后，告诉用户已成功登出，可继续 `auth login` 重新登录
+- 看到错误时告知用户登出失败、本地登录态保留，可稍后重试或检查网络
 
 ---

package/references/error-handling.md

@@ -13,9 +13,10 @@ echo $?  # 非 0 表示出错
 
 | 错误信息 | 原因 | 处理方式 |
 |---------|------|---------|
+| `账号登录过期，请重新登录` | 登录态已过期。CLI 已**自动**清理本地登录态 | 引导用户重新登录：`kugou-cli auth login`（扫码）或 `kugou-cli auth set-secret "<新 secret>"` |
 | `not logged in` / `auth file not found` | 未登录 | 引导用户执行 `kugou-cli auth login` |
 | `HTTP error: 400` | 请求参数有误 | 检查命令参数是否正确 |
 | `HTTP error: 500` | 服务端错误 | 稍后重试，或告知用户 |
-| `API error: ...` | 业务错误（errcode 非 0） | 根据 errmsg 提示用户 |
+| `API error: ...` | 业务错误 | 根据 errmsg 提示用户 |
 | `network error: ...` | 网络连接问题 | 检查网络，可尝试 `--proxy` |
 | `failed to get device info` | 设备信息获取失败 | 运行时环境异常，检查权限 |

package/references/install.md

@@ -1,54 +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`）|
+# 安装命令 (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`）|