@kg-ai/kugou-skill 0.1.4 → 0.1.6

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_image_url` 渲染给用户扫码（用 `![酷狗登录二维码](<qrcode_image_url>)`）。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

@@ -1,109 +1,137 @@
----
-name: kugou-skill
-description: |
-  酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手
-  提供歌曲搜索、每日推荐、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单等功能。
-  
-  **触发场景**（满足任一即使用本技能）：
-  - 用户要求推荐歌曲、听歌建议
-  - 用户要求搜索歌曲、查找歌手作品
-  - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）
-  - 用户要求查看收藏、最近播放、听歌统计
-  - 用户要求创建歌单、自建歌单
-  - 用户提供 secret（base64 字符串）要求登录或导入身份
-  - 用户提到"酷狗"、"kugou"、"每日推荐"、"相似歌曲"
-  
-  **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。
-  
-  安装方式：npm install -g @kg-ai/kugou-skill
----
-
-# kugou-skill
-
-## AI 使用工作流（优先阅读）
-
-使用本工具时的标准流程：
-
-```
-1. 检查安装 → npm install -g @kg-ai/kugou-skill
-2. 检查登录 → kugou-cli auth status
-3. 未登录 → 引导用户执行登录流程（详见 references/auth.md）
-4. 执行用户请求的音乐命令（详见 references/music.md）
-5. 解析 JSON 输出，按展示规范展示给用户（详见 references/output-format.md）
-```
-
-### 关键注意事项
-
-- **登录流程极简**（详见 [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-创建歌单)）：
-  1. **被动调用**：必须用户**明确**要求创建歌单时才调用 `music create-playlist`，禁止在用户仅说"推荐/搜歌"时主动创建
-  2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户是否需要将当前这批歌曲创建为歌单，等用户确认后再调用 `music create-playlist --songs "<mix_song_id 列表>"`
-
----
-
-## 基础信息
-
-- **npm 包**: @kg-ai/kugou-skill
-- **二进制命令**: kugou-cli
-- **安装方式**: `npm install -g @kg-ai/kugou-skill`
-
----
-
-## 详细文档索引
-
-| 文档 | 说明 |
-|------|------|
-| [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) | 更新命令：检查/执行自动更新 |
-| [references/output-format.md](references/output-format.md) | 输出格式与展示规范 |
-| [references/error-handling.md](references/error-handling.md) | 错误处理与常见错误 |
-
----
-
-## 完整使用流程
-
-```bash
-# 1. 登录（极简流程，详见 references/auth.md）
-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 "周杰伦"
-
-# 3. 获取猜你喜欢
-kugou-cli music recommend guess
-
-# 4. 查看我的收藏
-kugou-cli music favorites
-
-# 5. 查看最近播放
-kugou-cli music recent
-
-# 6. 查看听歌统计
-kugou-cli music stats
-
-# 7. 查看抖音热歌榜
-kugou-cli music charts 52144
-
-# 8. 创建歌单
-kugou-cli music create-playlist "我的空歌单"
-kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
-```
+---
+name: kugou-skill
+description: |
+  酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手
+  提供歌曲搜索、每日推荐、相似推荐、收藏管理、听歌统计、酷狗榜单、创建歌单等功能。
+  
+  **触发场景**（满足任一即使用本技能）：
+  - 用户要求推荐歌曲、听歌建议
+  - 用户要求搜索歌曲、查找歌手作品
+  - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）
+  - 用户要求查看收藏、最近播放、听歌统计
+  - 用户要求创建歌单、自建歌单
+  - 用户提供 secret（base64 字符串）要求登录或导入身份
+  - Agent 在尝试扫码登录时遇到环境限制（无法发图片）→ 主动询问用户是否可提供 secret
+  - 用户提到"酷狗"、"kugou"、"每日推荐"、"相似歌曲"
+  
+  **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。
+  
+  安装方式：npm install -g @kg-ai/kugou-skill
+---
+
+# kugou-skill
+
+## AI 使用工作流（优先阅读）
+
+使用本工具时的标准流程：
+
+```
+1. 检查安装 → npm install -g @kg-ai/kugou-skill
+2. 检查登录 → kugou-cli auth status
+3. 登录决策（关键决策点，不要跳过）：
+   ├─ 已登录（logged_in: true）→ 直接进入第 4 步
+   ├─ 未登录 → 先询问用户："你手上是否已有可用的 base64 secret？"
+   │   - 用户明确说"有" → 调 kugou-cli auth set-secret "<secret>"，跳过扫码
+   │   - 用户说"没有"或不确定 → 走标准扫码流程
+   │   - 当前环境无法渲染远程 URL 图片（纯文本 agent / 客户端无法访问外网 / 不支持 Markdown 渲染）→ 强制走 set-secret
+   └─ 默认行为：除非用户明确说"我有 secret"，否则优先走扫码
+4. 引导登录（详见 references/auth.md）：
+   - 扫码：auth login 拿 `qrcode_image_url` → 用 Markdown 图片语法直接 inline 给用户（不要只给 URL）
+   → 阶段 A：主动循环 auth status 最多 5 次（2-3s 间隔），覆盖秒扫
+   → 阶段 B：5 次仍 waiting → 停下，主动提示用户扫码，等用户**主动回复"已扫码"**
+   → 阶段 C：用户回复后调一次 status 验证；logged_in: true 即完成
+   - 导入 secret：auth set-secret "<secret>" 一次完成
+5. 执行用户请求的音乐命令（详见 references/music.md）
+6. 解析 JSON 输出，按展示规范展示给用户（详见 references/output-format.md）
+```
+
+### 关键注意事项
+
+- **登录流程极简**（详见 [references/auth.md](references/auth.md)）：
+  1. `auth login` - 获取二维码，输出包含 `qrcode`（字符串标识，给上游用）和 `qrcode_image_url`（**酷狗上游的图片 URL**，Agent 用它渲染）
+  2. **建议把二维码图片直接渲染到聊天窗口**（用户在窗口里能看到图片本身），**避免**只输出 URL 让用户手动打开：
+     - 首选：在消息正文中输出 `![酷狗登录二维码](<qrcode_image_url>)` 这种 Markdown 图片语法，让客户端拉取并渲染该 URL
+     - 备选：若平台支持把 URL 转为原生图片附件（image attach 工具等），可作为附件直接展示
+     - **避免**输出"二维码 URL 是 xxx，请打开扫码"这种纯文字提示 —— 用户最好能直接在聊天窗口看到图片
+     - **若当前 agent 工具集确认没有 URL 图片渲染能力**（纯文本通道、不支持 Markdown、客户端无法访问外网 URL）→ **跳过扫码**，直接告诉用户"当前环境无法显示二维码，请提供 base64 secret 字符串"并改走 `auth set-secret`
+   3. **图片发送后两阶段行为（关键）**：
+      - **阶段 A（主动轮询）**：图片刚展示，**先主动**循环调 `auth status` 最多 5 次（每次间隔 2-3 秒），覆盖用户秒扫的情况
+      - **阶段 B（等待用户反馈）**：5 次仍 `waiting` → **停下来**，主动告诉用户："请用酷狗 APP 扫码登录，扫完后告诉我已扫码"，**不再调 status**，等用户**主动回复"已扫码"**才进入阶段 C
+      - **阶段 C（验证登录）**：用户回复"已扫码" → 调一次 `auth status` 验证；返回 `logged_in: true` 继续执行，`scanned` 等几秒再调，`failed` 重新 `auth login` 拿新图
+      - 若用户回复"没看到图片" / "图片打不开" → 立即放弃扫码，切换到 `set-secret` 路径
+   4. `auth status` - **单次查询，不内部轮询**：每次调用只查一次扫码状态。完整流程见上方"两阶段行为"。**不要**等"内部已轮询"——根本不会自动轮询。
+- **直接导入 secret 登录**：当用户**已经持有**一个有效的 base64 secret 字符串（从别处获取的），直接调用 `kugou-cli auth set-secret "<secret>"` 即可完成登录，**跳过扫码流程**。这与扫码登录保存到同一份 `auth.json`，效果完全一致。secret 字符串含 `+` `/` `=` 是正常的，shell 里务必用引号包起来。**何时考虑用 set-secret**：用户明确说"我有 secret"、当前环境无法渲染 `qrcode_image_url`、用户之前已经登录过想换设备。
+- **登出 (auth logout)**：会**先**与服务端同步登出，**确认成功后才**清理本地登录态。失败时本地态保留、可重试；未登录时幂等直接返回成功。失败时 Agent **自动重试 1 次**（网络抖动常见），仍失败再询问用户是否重试，**不要**擅自清理本地文件。
+- **登录态自动失效**：当任意 `music` 命令遇到登录态过期时，CLI 会**自动清理**本地登录态，并在 stderr 输出 `账号登录过期，请重新登录`，exit code 非 0。Agent 收到该错误后：
+  1. **不要**自己再调一次 `music` 命令（会再次失败）
+  2. **不要**手动清理本地文件
+  3. **直接**引导用户重新登录：先问"你手上是否已有新 secret？"，有则 `auth set-secret`，没有则 `auth login` 走扫码
+  4. 重新登录后，**先调 `auth status` 确认** `logged_in: true`，再重试之前失败的 `music` 命令
+  - **状态字段差异**：`auth status` 在"无登录态"和"登录态过期被自动清理"两种场景下都返回 `{"logged_in": false}`（**不带 status 字段**）；"等待扫码"才返回 `{"logged_in": false, "status": "waiting"}`。Agent 区分场景应看 `music` 命令的 stderr 输出，不要只看 status 字段。完整状态表见 [references/auth.md#状态表](references/auth.md#状态表)。
+- **音乐命令依赖登录**：除了 `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-创建歌单)）：
+  1. **被动调用**：必须用户**明确**要求创建歌单时才调用 `music create-playlist`，禁止在用户仅说"推荐/搜歌"时主动创建
+  2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户是否需要将当前这批歌曲创建为歌单，等用户确认后再调用 `music create-playlist --songs "<mix_song_id 列表>"`
+
+---
+
+## 基础信息
+
+- **npm 包**: @kg-ai/kugou-skill
+- **二进制命令**: kugou-cli
+- **安装方式**: `npm install -g @kg-ai/kugou-skill`
+
+---
+
+## 详细文档索引
+
+| 文档 | 说明 |
+|------|------|
+| [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) | 更新命令：检查/执行自动更新 |
+| [references/output-format.md](references/output-format.md) | 输出格式与展示规范 |
+| [references/error-handling.md](references/error-handling.md) | 错误处理与常见错误 |
+
+---
+
+## 完整使用流程
+
+```bash
+# 1. 登录（极简流程，详见 references/auth.md）
+kugou-cli auth login                      # 获取二维码
+# auth status 是单次查询，agent 需要外层循环调用，每次间隔 2-3 秒
+kugou-cli auth status
+
+# 1'. 或者直接导入已持有的 secret（跳过扫码）
+kugou-cli auth set-secret "<base64-secret>"
+
+# 2. 搜索歌曲
+kugou-cli music search "周杰伦"
+
+# 3. 获取猜你喜欢
+kugou-cli music recommend guess
+
+# 4. 查看我的收藏
+kugou-cli music favorites
+
+# 5. 查看最近播放
+kugou-cli music recent
+
+# 6. 查看听歌统计
+kugou-cli music stats
+
+# 7. 查看抖音热歌榜
+kugou-cli music charts 52144
+
+# 8. 创建歌单
+kugou-cli music create-playlist "我的空歌单"
+kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"
+```

package/package.json

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

package/references/auth.md

@@ -1,147 +1,195 @@
-# 认证命令 (auth)
-
-> 🔐 = 需要先登录
-
-## 命令列表
-
-| 命令 | 说明 | 需要登录 |
-|------|------|---------|
-| `kugou-cli auth login` | 获取二维码图片 | 否 |
-| `kugou-cli auth status` | 检查登录状态（已完成则登录，未完成则继续轮询） | 否 |
-| `kugou-cli auth set-secret <secret>` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |
-| `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 即可。
-
-### 备选路径：用户已持有 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}`（本地已无登录态）
-
----
-
-## 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` 重新登录
-- 看到错误时告知用户登出失败、本地登录态保留，可稍后重试或检查网络
-
----
+# 认证命令 (auth)
+
+> 🔐 = 需要先登录
+
+## 命令列表
+
+| 命令 | 说明 | 需要登录 |
+|------|------|---------|
+| `kugou-cli auth login` | 获取二维码（`qrcode` 字符串 + `qrcode_image_url` 远程图片 URL） | 否 |
+| `kugou-cli auth status` | 检查登录状态（**单次查询，不内部轮询**，agent 需外层循环 2-3s 间隔） | 否 |
+| `kugou-cli auth set-secret <secret>` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |
+| `kugou-cli auth logout` | 登出 | 否 |
+
+---
+
+## 1. 扫码登录
+
+登录流程极简：
+
+```bash
+# Step 1: 获取二维码（拿到 qrcode_image_url 用于渲染图片）
+kugou-cli auth login
+
+# Step 2: 循环调用 status（**单次查询不内部轮询**，agent 自己外层循环）
+# 每次间隔 2-3 秒，看到 logged_in=true / status=success 即完成
+kugou-cli auth status
+```
+
+**auth login 输出示例**:
+```json
+{"qrcode": "xxx", "qrcode_image_url": "https://static.kugou.com/.../qrcode.png"}
+```
+
+字段说明：
+- `qrcode`：二维码字符串标识，**Agent 不要使用** —— 仅供 CLI 内部持久化以便后续 status 调上游 check 接口
+- `qrcode_image_url`：酷狗上游返回的图片 URL，**Agent 用它渲染二维码图片**
+
+---
+
+## 2. AI 引导流程
+
+### 2.1 决策点：先问 secret，再选路径
+
+在调用任何 auth 命令之前，**先询问用户**：
+
+> "你手上是否已有可用的 base64 secret 字符串？（从其他设备/工具导出的）"
+
+- **用户明确说"有"** → 直接走 §3 `set-secret`，跳过 §1 扫码
+- **用户说"没有"或不确定** → 走 §2.2 扫码流程
+- **当前环境无法发送图片**（纯文本 agent、SSH 远端、容器）→ 强制走 §3 `set-secret`，不要走扫码
+
+> **默认行为**：除非用户明确说"我有 secret"，否则优先走扫码。
+
+### 2.2 扫码流程
+
+1. 调用 `auth login` 拿到 `qrcode_image_url`
+2. **建议**用以下任一能力把 `qrcode_image_url` 直接展示给用户：
+   - 首选：Markdown 语法——在消息中输出 `![酷狗登录二维码](<qrcode_image_url>)`
+   - 备选：原生图片附件（若有 image attach 工具）——把 URL 作为附件直接展示
+   - **避免**只输出"请打开 xxx URL"这种纯文字提示
+3. **阶段 A — 主动轮询（覆盖秒扫）**：图片展示后，**主动**外层循环调用 `auth status`，每次间隔 2-3 秒，**最多 5 次**：
+   - 看到 `logged_in: true` → 完成，继续执行用户请求
+   - 看到 `status: success` → 完成，继续执行用户请求
+   - 看到 `status: scanned` → 等几秒再调一次 status
+   - 5 次都是 `waiting` → 进入阶段 B
+4. **阶段 B — 等待用户反馈（关键）**：5 次主动轮询后仍未登录，**停下来**，不再调任何 auth 命令。主动告诉用户：
+   > "请用酷狗 APP 扫码登录，扫完后告诉我已扫码"
+   然后**等用户主动回复**。**不要**自己继续轮询。
+5. **阶段 C — 验证登录**：用户回复"已扫码"后，调一次 `auth status` 验证：
+   - `logged_in: true` → 完成，继续执行用户请求
+   - `status: scanned` → 用户在手机上还没点确认，等几秒再调一次
+   - `status: failed` → qrcode 失效（CLI 已清理），重新 `auth login` 拿新图，回到步骤 1
+   - `logged_in: false`（无 status 字段）→ qrcode 已被清理，提示用户"二维码可能已过期，正在重新获取"并回到步骤 1
+6. **若用户在阶段 B 阶段回复"没看到图片" / "图片打不开"** → 立即放弃扫码，切换到 §3 `set-secret` 路径
+7. **若用户在阶段 B 阶段回复"已扫码"**但阶段 C 验证发现没登录成功（`scanned` / `failed`），按阶段 C 各项处理，不要替用户做"再扫一次"之类的猜测
+
+### 2.3 状态表
+
+| 返回 | 含义 | Agent 应做 |
+|------|------|-----------|
+| `{"logged_in": true, "nickname": "...", "login_time": "..."}` | 已登录（**已有 token 持久化**，通常是之前登录过） | 继续执行用户请求 |
+| `{"logged_in": true, "status": "success", "nickname": "..."}` | 扫码刚完成登录（**刚 SaveAuth 落盘**，本轮 status 检查中完成） | 继续执行用户请求 |
+| `{"logged_in": false, "status": "waiting", "qrcode": "..."}` | 二维码待扫码 | **阶段 A**：2-3s 后重试 status，最多 5 次；5 次后**进入阶段 B**，停下来等用户主动反馈 |
+| `{"logged_in": false, "status": "scanned", "nickname": "...", "qrcode": "..."}` | 已扫码待确认 | 等几秒再调一次 status（用户还没在手机上点确认） |
+| `{"logged_in": false, "status": "failed", "message": "..."}` | 二维码失效（**CLI 会自动清理本地 qrcode**） | **阶段 C 验证时**才见此返回 → 重新 `auth login` 拿新图，回到 §2.2 步骤 1 |
+| `{"logged_in": false}` | 无登录态（未登录过 / 登录过期被清理 / qrcode 刚被 failed 清理掉） | 走完整登录流程（§2.1 决策点） |
+
+> **判定"已登录"**：`logged_in: true` 即算成功，**不管有没有 `status: success` 字段**——两种 JSON shape 都合法。
+>
+> 区分"无登录态"和"等待扫码"的关键：前者**没有** `status` 字段，后者有。
+>
+> **轮询逻辑（两阶段）**：
+> - 阶段 A：图片刚展示，主动循环 status 最多 5 次（2-3s 间隔）→ 覆盖秒扫场景
+> - 阶段 B：5 次仍 `waiting` → 主动告诉用户"请扫码登录，扫完后告诉我已扫码"，**不再调 status**，等用户**主动回复**
+
+### 2.3.1 边界提醒：status: failed 会清掉 qrcode
+
+**关键事实**：`cmd/auth/status.go` 在 `status != 1/3/4` 时会调 `authstore.Logout()`，**自动清理本地 qrcode 文件**（不是清理登录态）。
+
+**在阶段 A / 阶段 C 见到 `failed` 时的处理**：
+
+| 见到位置 | 原因可能性 | Agent 应做 |
+|---------|-----------|-----------|
+| 阶段 A 主动轮询中 | 用户没扫 / qrcode 真过期 / 上游短暂异常 | **不再继续轮询**，主动告诉用户"二维码已失效或上游异常，正在重新获取"，调 `auth login` 拿新图，回到 §2.2 步骤 1 |
+| 阶段 C 用户说"已扫码"后验证 | 登录过程中上游返回非预期 / 已过期 | 同上，重新 `auth login` 拿新图 |
+| 阶段 A 之后阶段 B 之前 | （不应发生） | 视为阶段 A 见到 failed 处理 |
+
+> 不要因为"看到 failed → 看到 logged_in: false"就误判"用户没登录"，按"qrcode 失效需重拿"处理——failed 是 qrcode 状态，不是登录态。
+
+### 备选路径：用户已持有 secret
+
+当用户**已经持有**一个有效的 base64 secret 字符串时（例如从其他设备、其他工具导出的），可以直接用 `auth set-secret` 跳过整个扫码流程，**不需**调用 `auth login` / `auth status`：
+
+```bash
+kugou-cli auth set-secret "<base64-secret>"
+```
+
+调用成功后 secret 会被持久化（路径见 §3），所有 music 命令立即可用，效果与扫码登录一致。
+
+---
+
+
+## 3. 直接设置 secret
+
+**适用场景**：
+- 用户在其他设备/工具上已登录酷狗，导出或复制了一份 base64 secret
+- 测试、调试、自动化场景下需要直接注入 secret
+- 任何不便于扫码的终端环境（如 SSH 远端、容器、CI）
+- 当前 agent 工具集无法渲染 `qrcode_image_url` 远程图片（不联网 / 不支持 Markdown 渲染，见 §2.4）
+
+**命令**:
+
+```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 落到本地登录态文件，**跨平台位置**：
+  - Linux/macOS：`~/.config/kugou-cli/auth.json`
+  - Windows：`%AppData%\kugou-cli\auth.json`（通常为 `C:\Users\<user>\AppData\Roaming\kugou-cli\auth.json`）
+  - 若用户询问"登录态存在哪"，按平台给对应路径，**不要**直接说 `~/.config/...` 在 Windows 下不准确
+- 后续 `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}`（**无 status 字段**，对应 §2.3 状态表最后一行）
+
+---
+
+## 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` 重新登录
+- 看到错误时：
+  1. **自动重试 1 次**（网络抖动常见）
+  2. 仍失败 → 告知用户"登出失败，本地登录态保留，可能是网络问题"，**询问**用户："是否要稍后重试？"
+  3. **不要**擅自清理本地文件或调任何 music 命令

package/references/output-format.md

@@ -37,6 +37,6 @@
 
 ### 3. 二维码
 
-使用 `qrcode_img_path` 对应的图片文件发送给用户
+使用 `qrcode_image_url` 渲染给用户：Markdown `![酷狗登录二维码](<qrcode_image_url>)`，让客户端拉取并渲染
 
 ---