@kg-ai/kugou-skill 0.1.4 → 0.1.5

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

@@ -11,6 +11,7 @@ description: |
   - 用户要求查看收藏、最近播放、听歌统计
   - 用户要求创建歌单、自建歌单
   - 用户提供 secret（base64 字符串）要求登录或导入身份
+  - Agent 在尝试扫码登录时遇到环境限制（无法发图片）→ 主动询问用户是否可提供 secret
   - 用户提到"酷狗"、"kugou"、"每日推荐"、"相似歌曲"
   
   **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。
@@ -27,19 +28,46 @@ description: |
 ```
 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）
+3. 登录决策（关键决策点，不要跳过）：
+   ├─ 已登录（logged_in: true）→ 直接进入第 4 步
+   ├─ 未登录 → 先询问用户："你手上是否已有可用的 base64 secret？"
+   │   - 用户明确说"有" → 调 kugou-cli auth set-secret "<secret>"，跳过扫码
+   │   - 用户说"没有"或不确定 → 走标准扫码流程
+   │   - 当前环境无法发送图片（纯文本 agent / SSH 远端 / 容器）→ 强制走 set-secret
+   └─ 默认行为：除非用户明确说"我有 secret"，否则优先走扫码
+4. 引导登录（详见 references/auth.md）：
+   - 扫码：auth login 拿图片 → 直接 inline 给用户（不要只给路径）
+   → 阶段 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_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`），无需手动清理。
+  1. `auth login` - 获取二维码图片，输出包含 `qrcode` 和 `qrcode_img_path`
+  2. **必须把二维码图片直接渲染到聊天窗口**（用户在窗口里能看到图片本身），**禁止**只输出文件路径让用户手动打开：
+     - 优先：使用当前平台原生图片附件能力（Claude Code 的 `Read` 工具读图自动 inline、workbuddy / mavis 的 image attach 工具）将图片作为附件直接展示
+     - 次优：在消息正文中输出 `![酷狗登录二维码](file://<qrcode_img_path>)` 这种 Markdown 图片语法，让客户端自动渲染
+     - **绝对禁止**：输出"二维码已保存到 xxx，请打开扫码"这种纯文字提示 —— 用户必须能直接在聊天窗口看到图片
+     - **若当前 agent 工具集确认没有图片渲染能力**（纯文本通道、SSH 远端、容器内、无文件访问能力）→ **跳过扫码**，直接告诉用户"当前环境无法显示二维码，请提供你的 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"、当前环境无法发图片、用户之前已经登录过想换设备。
+- **登出 (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`
@@ -79,7 +107,7 @@ description: |
 ```bash
 # 1. 登录（极简流程，详见 references/auth.md）
 kugou-cli auth login                      # 获取二维码
-# 循环执行以下命令直到 logged_in=true
+# auth status 是单次查询，agent 需要外层循环调用，每次间隔 2-3 秒
 kugou-cli auth status
 
 # 1'. 或者直接导入已持有的 secret（跳过扫码）

package/package.json

@@ -1,27 +1,27 @@
-{
-  "name": "@kg-ai/kugou-skill",
-  "version": "0.1.4",
-  "description": "Kugou Skill CLI",
-  "main": "index.js",
-  "bin": {
-    "kugou-cli": "./scripts/run.js"
-  },
-  "scripts": {
-    "postinstall": "node ./scripts/install.js"
-  },
-  "keywords": [
-    "cli",
-    "kugou"
-  ],
-  "files": [
-    "bin",
-    "scripts",
-    "SKILL.md",
-    "references"
-  ],
-  "author": "",
-  "license": "MIT",
-  "engines": {
-    "node": ">=16"
-  }
-}
+{
+  "name": "@kg-ai/kugou-skill",
+  "version": "0.1.5",
+  "description": "Kugou Skill CLI",
+  "main": "index.js",
+  "bin": {
+    "kugou-cli": "./scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/install.js"
+  },
+  "keywords": [
+    "cli",
+    "kugou"
+  ],
+  "files": [
+    "bin",
+    "scripts",
+    "SKILL.md",
+    "references"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/references/auth.md

@@ -7,7 +7,7 @@
 | 命令 | 说明 | 需要登录 |
 |------|------|---------|
 | `kugou-cli auth login` | 获取二维码图片 | 否 |
-| `kugou-cli auth status` | 检查登录状态（已完成则登录，未完成则继续轮询） | 否 |
+| `kugou-cli auth status` | 检查登录状态（**单次查询，不内部轮询**，agent 需外层循环 2-3s 间隔） | 否 |
 | `kugou-cli auth set-secret <secret>` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |
 | `kugou-cli auth logout` | 登出 | 否 |
 
@@ -21,7 +21,8 @@
 # Step 1: 获取二维码图片
 kugou-cli auth login
 
-# Step 2: 检查登录状态（Agent 可循环调用直到 logged_in=true）
+# Step 2: 循环调用 status（**单次查询不内部轮询**，agent 自己外层循环）
+# 每次间隔 2-3 秒，看到 logged_in=true / status=success 即完成
 kugou-cli auth status
 ```
 
@@ -30,40 +31,81 @@ kugou-cli auth status
 {"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 即可。
+### 2.1 决策点：先问 secret，再选路径
+
+在调用任何 auth 命令之前，**先询问用户**：
+
+> "你手上是否已有可用的 base64 secret 字符串？（从其他设备/工具导出的）"
+
+- **用户明确说"有"** → 直接走 §3 `set-secret`，跳过 §1 扫码
+- **用户说"没有"或不确定** → 走 §2.2 扫码流程
+- **当前环境无法发送图片**（纯文本 agent、SSH 远端、容器）→ 强制走 §3 `set-secret`，不要走扫码
+
+> **默认行为**：除非用户明确说"我有 secret"，否则优先走扫码。
+
+### 2.2 扫码流程（含图片自检）
+
+1. 调用 `auth login` 获取二维码图片，拿到 `qrcode_img_path`
+2. **图片自检（关键）**：在向用户展示之前，**先确认**你具备以下能力之一：
+   - (a) 原生图片附件工具（如 `Read` 工具支持图片自动 inline、专用 `image_attach` 工具等）
+   - (b) Markdown 渲染能力（聊天客户端能识别 `![alt](url)` 语法）
+   - 若两者都没有 → **跳过第 3 步**，直接进入 §3 走 `set-secret`
+3. 用上述任一能力把图片直接展示给用户：
+   - 工具 (a)：调用工具读图，结果会自动渲染
+   - 工具 (b)：在消息中输出 `![酷狗登录二维码](file://<qrcode_img_path>)`
+   - **禁止**只输出"请打开 xxx 路径"这种文字
+4. **阶段 A — 主动轮询（覆盖秒扫）**：图片展示后，**主动**外层循环调用 `auth status`，每次间隔 2-3 秒，**最多 5 次**：
+   - 看到 `logged_in: true` → 完成，继续执行用户请求
+   - 看到 `status: success` → 完成，继续执行用户请求
+   - 看到 `status: scanned` → 等几秒再调一次 status
+   - 5 次都是 `waiting` → 进入阶段 B
+5. **阶段 B — 等待用户反馈（关键）**：5 次主动轮询后仍未登录，**停下来**，不再调任何 auth 命令。主动告诉用户：
+   > "请用酷狗 APP 扫码登录，扫完后告诉我已扫码"
+   然后**等用户主动回复**。**不要**自己继续轮询。
+6. **阶段 C — 验证登录**：用户回复"已扫码"后，调一次 `auth status` 验证：
+   - `logged_in: true` → 完成，继续执行用户请求
+   - `status: scanned` → 用户在手机上还没点确认，等几秒再调一次
+   - `status: failed` → qrcode 失效（CLI 已清理），重新 `auth login` 拿新图，回到步骤 1
+   - `logged_in: false`（无 status 字段）→ qrcode 已被清理，提示用户"二维码可能已过期，正在重新获取"并回到步骤 1
+7. **若用户在阶段 B 阶段回复"没看到图片" / "图片打不开"** → 立即放弃扫码，切换到 §3 `set-secret` 路径
+8. **若用户在阶段 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
 
@@ -73,7 +115,22 @@ kugou-cli auth status
 kugou-cli auth set-secret "<base64-secret>"
 ```
 
-调用成功后 secret 会被持久化到 `~/.config/kugou-cli/auth.json`，所有 music 命令立即可用，效果与扫码登录一致。
+调用成功后 secret 会被持久化（路径见 §3），所有 music 命令立即可用，效果与扫码登录一致。
+
+---
+
+## 2.4 二维码图片渲染速查
+
+| 平台/agent | 推荐方式 | 禁止方式 |
+|-----------|---------|---------|
+| Claude Code | 用 `Read` 工具读 `qrcode_img_path`，结果自动 inline | 不要只输出路径 |
+| workbuddy / mavis | 调平台 `image_attach` 工具（若有），或 Markdown `![二维码](file://<path>)` | 不要输出"请打开 C:\..." |
+| 纯文本/SSH 容器 | **不支持图片**，跳过扫码直接 `set-secret` | 不要试图贴路径 |
+| 支持 Markdown 的 IM | `![酷狗登录二维码](file://<qrcode_img_path>)` | 不要贴裸路径 |
+
+> **判断原则**：发送出去的内容里**必须**包含图片本身（base64 / inline / Markdown 语法 / 原生附件），**不能**只是一个文件路径字符串。
+>
+> **若不确定工具能力** → 走 §2.2 第 2 步"图片自检"；自检不通过 → 改走 §3 `set-secret`。
 
 ---
 
@@ -83,6 +140,7 @@ kugou-cli auth set-secret "<base64-secret>"
 - 用户在其他设备/工具上已登录酷狗，导出或复制了一份 base64 secret
 - 测试、调试、自动化场景下需要直接注入 secret
 - 任何不便于扫码的终端环境（如 SSH 远端、容器、CI）
+- 当前 agent 工具集无法渲染图片（见 §2.4）
 
 **命令**:
 
@@ -106,7 +164,10 @@ secret cannot be empty
 ```
 
 **与扫码登录的等价性**：
-- secret 落到同一份 `~/.config/kugou-cli/auth.json`
+- 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 字段为空（因为导入途径不带昵称），不影响功能
@@ -118,7 +179,7 @@ secret cannot be empty
 **登录态过期处理**：
 - 当任意 `music` 命令遇到登录态过期时，CLI 会**自动清理**本地登录态，并在 stderr 输出 `账号登录过期，请重新登录`，以非 0 exit code 退出
 - Agent 收到该错误后应**直接引导用户重新登录**（`auth login` 走扫码，或 `auth set-secret` 导入新 secret），无需手动清理本地文件
-- 之后调用 `auth status` 会得到 `{"logged_in": false}`（本地已无登录态）
+- 之后调用 `auth status` 会得到 `{"logged_in": false}`（**无 status 字段**，对应 §2.3 状态表最后一行）
 
 ---
 
@@ -142,6 +203,7 @@ kugou-cli auth logout
 **AI 引导建议**：
 - 用户说"登出 / 退出登录 / 注销"时直接执行 `auth logout`
 - 看到 `{"status": "logged out"}` 后，告诉用户已成功登出，可继续 `auth login` 重新登录
-- 看到错误时告知用户登出失败、本地登录态保留，可稍后重试或检查网络
-
----
+- 看到错误时：
+  1. **自动重试 1 次**（网络抖动常见）
+  2. 仍失败 → 告知用户"登出失败，本地登录态保留，可能是网络问题"，**询问**用户："是否要稍后重试？"
+  3. **不要**擅自清理本地文件或调任何 music 命令