@kg-ai/kugou-skill 0.1.1 → 0.1.3

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

@@ -10,6 +10,7 @@ description: |
   - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）
   - 用户要求查看收藏、最近播放、听歌统计
   - 用户要求创建歌单、自建歌单
+  - 用户提供 secret（base64 字符串）要求登录或导入身份
   - 用户提到"酷狗"、"kugou"、"每日推荐"、"相似歌曲"
   
   **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。
@@ -36,7 +37,14 @@ description: |
 - **登录流程极简**（详见 [references/auth.md](references/auth.md)）：
   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`
+  - 手动检查/触发：`kugou-cli update` 跳过本地缓存直接查远端并自动安装；`kugou-cli update --check` 仅检查不安装
+  - 非 npm 安装（手动编译/容器）会打印提示和升级命令但不会自动执行
 - **输出均为 JSON**：所有命令输出原始 JSON 到 stdout，错误输出到 stderr。解析 `errcode` 字段判断成功与否（`0` 为成功）。
 - **歌曲展示规范**（详见 [references/output-format.md](references/output-format.md)）：**禁止**只返回歌曲名、歌手名，**必须**以 Markdown 链接格式展示播放链接。
 - **创建歌单的调用原则**（详见 [references/music.md#8-创建歌单](references/music.md#8-创建歌单)）：
@@ -57,7 +65,7 @@ description: |
 
 | 文档 | 说明 |
 |------|------|
-| [references/auth.md](references/auth.md) | 认证命令：扫码登录、查看状态、登出 |
+| [references/auth.md](references/auth.md) | 认证命令：扫码登录、直接设置 secret、查看状态、登出 |
 | [references/music.md](references/music.md) | 音乐命令：搜索、推荐、收藏、统计、榜单、创建歌单 |
 | [references/install.md](references/install.md) | 安装命令：SKILL.md 安装到各平台 |
 | [references/update.md](references/update.md) | 更新命令：检查/执行自动更新 |
@@ -74,6 +82,9 @@ kugou-cli auth login                      # 获取二维码
 # 循环执行以下命令直到 logged_in=true
 kugou-cli auth status
 
+# 1'. 或者直接导入已持有的 secret（跳过扫码）
+kugou-cli auth set-secret "<base64-secret>"
+
 # 2. 搜索歌曲
 kugou-cli music search "周杰伦"
 

package/package.json

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

package/references/auth.md

@@ -8,6 +8,7 @@
 |------|------|---------|
 | `kugou-cli auth login` | 获取二维码图片 | 否 |
 | `kugou-cli auth status` | 检查登录状态（已完成则登录，未完成则继续轮询） | 否 |
+| `kugou-cli auth set-secret <secret>` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |
 | `kugou-cli auth logout` | 登出 | 否 |
 
 ---
@@ -64,12 +65,83 @@ kugou-cli auth status
 
 > **简化说明**：本工具将"轮询检查扫码状态"逻辑内置到 `auth status` 中，Agent 只需简单循环调用 status 即可。
 
+### 备选路径：用户已持有 secret
+
+当用户**已经持有**一个有效的 base64 secret 字符串时（例如从其他设备、其他工具导出的），可以直接用 `auth set-secret` 跳过整个扫码流程，**不需**调用 `auth login` / `auth status`：
+
+```bash
+kugou-cli auth set-secret "<base64-secret>"
+```
+
+调用成功后 secret 会被持久化到 `~/.config/kugou-cli/auth.json`，所有 music 命令立即可用，效果与扫码登录一致。
+
+---
+
+## 3. 直接设置 secret
+
+**适用场景**：
+- 用户在其他设备/工具上已登录酷狗，导出或复制了一份 base64 secret
+- 测试、调试、自动化场景下需要直接注入 secret
+- 任何不便于扫码的终端环境（如 SSH 远端、容器、CI）
+
+**命令**:
+
+```bash
+kugou-cli auth set-secret "{secret}"
+```
+
+**shell 引号注意事项**：
+- secret 字符串含 `+`、`/`、`=` 等 base64 字符是**正常的**，**不会**被 shell 误解析
+- 但 `+` 在 bash 中是通配符、`=` 在 cmd.exe 中会触发变量赋值，**务必用引号包起来**
+- 推荐使用双引号 `"..."`（除非 secret 中含 `$`，那就用单引号 `'...'`）
+
+**输出示例**:
+```json
+{"status": "ok", "message": "secret saved"}
+```
+
+**失败示例**（secret 为空）:
+```
+secret cannot be empty
+```
+
+**与扫码登录的等价性**：
+- secret 落到同一份 `~/.config/kugou-cli/auth.json`
+- 后续 `auth status` 输出 `{"logged_in": true}`
+- 所有 `music` 子命令立即可用，无需任何额外步骤
+- nickname 字段为空（因为导入途径不带昵称），不影响功能
+
+**上游校验时机**：
+- CLI 不做本地格式校验（不做 base64 解码、不解密），只做"非空"检查
+- secret 实际有效性在**第一次**调用 `music <sub>` 时由上游校验
+
+**登录态过期处理**：
+- 当任意 `music` 命令遇到登录态过期时，CLI 会**自动清理**本地登录态，并在 stderr 输出 `账号登录过期，请重新登录`，以非 0 exit code 退出
+- Agent 收到该错误后应**直接引导用户重新登录**（`auth login` 走扫码，或 `auth set-secret` 导入新 secret），无需手动清理本地文件
+- 之后调用 `auth status` 会得到 `{"logged_in": false}`（本地已无登录态）
+
 ---
 
-## 3. 文件存储
+## 4. 登出 (logout)
 
-| 文件 | 路径 | 说明 |
-|------|------|------|
-| 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） |
+**命令**：
+
+```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`）|