@kg-ai/kugou-skill 0.1.0 → 0.1.2

package/SKILL.md

@@ -10,6 +10,7 @@ description: |
   - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）
   - 用户要求查看收藏、最近播放、听歌统计
   - 用户要求创建歌单、自建歌单
+  - 用户提供 secret（base64 字符串）要求登录或导入身份
   - 用户提到"酷狗"、"kugou"、"每日推荐"、"相似歌曲"
   
   **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。
@@ -36,7 +37,12 @@ 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`、`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 +63,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 +80,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.0",
+  "version": "0.1.2",
   "description": "Kugou Skill CLI",
   "main": "index.js",
   "bin": {
@@ -24,4 +24,4 @@
   "engines": {
     "node": ">=16"
   }
-}
+}

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,54 @@ 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. 文件存储
+## 3. 直接设置 secret
+
+**适用场景**：
+- 用户在其他设备/工具上已登录酷狗，导出或复制了一份 base64 secret
+- 测试、调试、自动化场景下需要直接注入 secret
+- 任何不便于扫码的终端环境（如 SSH 远端、容器、CI）
+
+**命令**:
+
+```bash
+kugou-cli auth set-secret "{secret}"
+```
 
-| 文件 | 路径 | 说明 |
-|------|------|------|
-| 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） |
+**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>` 时由上游校验；secret 失效/过期会返回 `errcode: 30001`（密钥错误）
+
+---

package/references/music.md

@@ -294,7 +294,7 @@ kugou-cli music charts 52144 --page 1 --size 20
 kugou-cli music create-playlist "我的空歌单"
 
 # 创建歌单并添加歌曲
-kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060,64263573,146061840"
+kugou-cli music create-playlist "我的批量歌单" --songs "123,456,789"
 ```
 
 **参数**: