@kg-ai/kugou-skill 0.1.12 → 0.1.13

package/SKILL.md

@@ -40,14 +40,17 @@ description: |
    注意：状态 b/c/d 互斥；不要在用户未明确给 secret 时擅自走 set-secret。
 4. 引导登录——扫码（详见 references/auth.md）：
    - 执行 `auth login`，从输出读 `qrcode_img_url` 和 `qrcode_img_path`，按当前客户端能力选一种方式把二维码**直接展示给用户**
-    - **阶段 A（主动轮询）**：图片刚展示，**主动**重试几次 `auth status`（每次隔几秒），覆盖用户秒扫场景
+     - **阶段 A（主动轮询）**：图片刚展示，**主动**重试几次 `auth status`（每次隔几秒），覆盖用户秒扫场景
       - 任意一次返回 `logged_in: true` → 跳到第 6 步
-      - 几次都返回 `waiting` 且未出现 `scanned` → 进入阶段 B
-    - **阶段 B（等用户回复）**：停下，告诉用户"请用酷狗 APP 扫码登录，扫完后告诉我已扫码"，**不再调 status**，等用户**主动回复"已扫码"**
-    - **阶段 C（验证一次）**：用户回复"已扫码"后，**调一次** `auth status`：
+      - 见到 `status: failed` → **不要换新图**，隔 1-2 秒用同一个本地 qrcode 再调一次（计入阶段 A 的 5 次预算）
+      - 见到 `status: expired` → 告诉用户二维码已失效，调 `auth login` 拿新图，从阶段 A 重新开始
+      - 几次都返回 `waiting` / `failed` 且未出现 `scanned` / `logged_in` / `expired` → 进入阶段 B
+     - **阶段 B（等用户回复）**：停下，告诉用户"请用酷狗 APP 扫码登录，扫完后告诉我已扫码"，**不再调 status**，等用户**主动回复"已扫码"**
+      - **阶段 C（验证一次）**：用户回复"已扫码"后，**调一次** `auth status`：
       - `logged_in: true` → 完成，跳到第 6 步
-     - `scanned`（已扫但未确认）→ 等几秒再调一次，最多**额外**调几次，仍是 scanned 就告诉用户"手机端是否已点确认？"
-     - `failed` 或 `{"logged_in": false}` → 重新 `auth login` 拿新图，从阶段 A 重新开始
+      - `scanned`（已扫但未确认）→ 等几秒再调一次，最多**额外**调几次，仍是 scanned 就告诉用户"手机端是否已点确认？"
+      - `failed` → **不要换新图**，隔 1-2 秒用同一个本地 qrcode 再调一次，最多重试 2-3 次；仍 failed 则告诉用户稍后重试
+      - `expired` / `{"logged_in": false}`（无 status 字段，说明本地 qrcode 已被上游清掉）→ 重新 `auth login` 拿新图（覆盖本地），从阶段 A 重新开始
 5. **首次要展示歌曲/歌单前探测本机客户端可用性**（详见 [references/control.md §13](references/control.md#13-client-detection-control-detect)）：
    - **触发时机**：本会话中第一次要向用户展示歌曲列表、歌单列表或歌单内歌曲列表之前。后续展示**复用本次探测结果**（会话内探测一次即可，不要每条命令前都跑）
    - **命令**：`kugou-cli control detect`（零副作用，不启动客户端、不抢焦点）

package/package.json

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

package/references/auth.md

@@ -63,19 +63,22 @@ kugou-cli auth status
    - **避免**只输出“请打开 xxx URL”或“图片路径是 xxx”这种纯文字提示，用户应直接看到二维码图片
    - 选择的方式展示失败时，切换到另一种方式：远程图片加载失败则尝试本地文件，本地文件无法读取则尝试远程 Markdown 图片
    - 如果当前客户端既不能读取本地文件，也不能渲染远程 Markdown 图片 → 放弃扫码，切换到 §3 `set-secret` 路径
-3. **阶段 A — 主动轮询（覆盖秒扫）**：图片展示后，**主动**外层循环调用 `auth status`，每次间隔 2-3 秒，**最多 5 次**：
+3. **阶段 A — 主动轮询（覆盖秒扫）**：图片展示后，**主动**外层循环调用 `auth status`，每次间隔 2-3 秒，**最多 5 次**（与 `failed` 重试合并计数）：
    - 看到 `logged_in: true` → 完成，继续执行用户请求
    - 看到 `status: success` → 完成，继续执行用户请求
    - 看到 `status: scanned` → 等几秒再调一次 status
-   - 5 次都是 `waiting` → 进入阶段 B
+   - 看到 `status: failed` → **不要换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（计入 5 次轮询预算）
+   - 看到 `status: expired` → **不再继续轮询**，主动告诉用户"二维码已失效，正在重新获取"，调 `auth login` 拿新图，回到步骤 1
+   - 5 次都是 `waiting` / `failed` → 进入阶段 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
+   - `status: failed` → **不要换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（最多重试 2-3 次）
+   - `status: expired` → 上游明确说过期（CLI 已清理本地），重新 `auth login` 拿新图，回到步骤 1
+   - `logged_in: false`（无 status 字段）→ qrcode 已被清理（通常是上一步 `expired` 后状态），提示用户"二维码可能已过期，正在重新获取"并回到步骤 1
 6. **若用户在阶段 B 回复"没看到图片" / "图片打不开"** → 先切换到另一种二维码展示方式；两种方式都失败后，再切换到 §3 `set-secret` 路径
 7. **若用户在阶段 B 回复"已扫码"**但阶段 C 验证发现没登录成功（`scanned` / `failed`），按阶段 C 各项处理，不要替用户做"再扫一次"之类的猜测
 
@@ -87,8 +90,9 @@ kugou-cli auth status
 | `{"logged_in": true, "status": "success", "nickname": "..."}` | 扫码刚完成登录（**本轮 status 检查中完成 token 持久化**） | 继续执行用户请求 |
 | `{"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": false, "status": "expired", "message": "..."}` | 二维码被上游明确判定为过期（**CLI 会自动清理本地 qrcode**） | **不再重试**：调 `auth login` 拿新图（覆盖本地 qrcode），回到 §2.2 步骤 1 |
+| `{"logged_in": false, "status": "failed", "message": "..."}` | 上游返回了 CLI 不识别的 status 码（**CLI 不会清理本地 qrcode**，本地缓存仍可用） | **重试** 1-2 秒后再调一次 status（用同一个本地 qrcode）；阶段 A 中计入 5 次预算，阶段 C 中最多 2-3 次。**不要调 `auth login` 换新图** |
+| `{"logged_in": false}` | 无登录态（未登录过 / 登录过期被清理 / qrcode 刚被 expired 清理掉） | 走完整登录流程（§2.1 决策点） |
 
 > **判定"已登录"**：`logged_in: true` 即算成功，**不管有没有 `status: success` 字段**——两种 JSON shape 都合法。
 >
@@ -98,19 +102,28 @@ kugou-cli auth status
 > - 阶段 A：图片刚展示，主动循环 status 最多 5 次（2-3s 间隔）→ 覆盖秒扫场景
 > - 阶段 B：5 次仍 `waiting` → 主动告诉用户"请扫码登录，扫完后告诉我已扫码"，**不再调 status**，等用户**主动回复**
 
-### 2.3.1 边界提醒：status: failed 会清掉 qrcode
+### 2.3.1 边界提醒：`expired` 会清掉 qrcode 并需换新图，`failed` 不清且应重试
 
-**关键事实**：`status: failed` 时 CLI 会自动清理本地 qrcode 文件（**不是清理登录态**）。
+**关键事实**：
 
-**在阶段 A / 阶段 C 见到 `failed` 时的处理**：
+- `status: expired` 时 CLI 会自动清理本地 qrcode 文件（**不是清理登录态**）。这是上游**明确**判定二维码失效（协议层不可恢复）→ **必须换新图**。
+- `status: failed` 时 CLI **不会**清理本地 qrcode 文件。这是上游返回了 CLI 不识别的 status 码（短暂异常 / 未知协议值 / 上游 gateway 抖动）。本地 qrcode 字符串**没失效** → **不应换新图，应重试同一 qrcode**。
 
-| 见到位置 | 原因可能性 | Agent 应做 |
-|---------|-----------|-----------|
-| 阶段 A 主动轮询中 | 用户没扫 / qrcode 真过期 / 上游短暂异常 | **不再继续轮询**，主动告诉用户"二维码已失效或上游异常，正在重新获取"，调 `auth login` 拿新图，回到 §2.2 步骤 1 |
-| 阶段 C 用户说"已扫码"后验证 | 登录过程中上游返回非预期 / 已过期 | 同上，重新 `auth login` 拿新图 |
-| 阶段 A 之后阶段 B 之前 | （不应发生） | 视为阶段 A 见到 failed 处理 |
+**两种返回在阶段 A / 阶段 C 的处理**：
 
-> 不要因为"看到 failed → 看到 logged_in: false"就误判"用户没登录"，按"qrcode 失效需重拿"处理——failed 是 qrcode 状态，不是登录态。
+| 见到位置 | 状态值 | 原因可能性 | Agent 应做 |
+|---------|--------|-----------|-----------|
+| 阶段 A 主动轮询中 | `expired` | 上游明确说过期 | **不再继续轮询**，主动告诉用户"二维码已失效，正在重新获取"，调 `auth login` 拿新图，回到 §2.2 步骤 1 |
+| 阶段 A 主动轮询中 | `failed` | 上游短暂异常 / 未知 status 码 | **不换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status（计入阶段 A 的 5 次主动轮询预算） |
+| 阶段 C 用户说"已扫码"后验证 | `expired` | 登录过程中上游判定过期 | 重新 `auth login` 拿新图 |
+| 阶段 C 用户说"已扫码"后验证 | `failed` | 登录过程中上游返回非预期 | **不换新图**，隔 1-2 秒后用同一个本地 qrcode 再调一次 status，最多重试 2-3 次；仍 `failed` 再按上游持续异常处理（建议告诉用户稍后重试或切 `set-secret`） |
+| 阶段 A 之后阶段 B 之前 | `expired` / `failed` | （不应发生） | 视为阶段 A 见到对应状态值处理 |
+
+> **判定要点**：
+> - 不要因为"看到 expired/failed → 看到 logged_in: false"就误判"用户没登录"。expired/failed 都是 qrcode 状态，不是登录态。
+> - `expired` 后下次 `auth status` 会拿到 `{"logged_in": false}`（无 status 字段，本地已被清）。
+> - `failed` 后下次 `auth status` **可能仍返回 failed**（上游持续异常），也可能恢复 `waiting`（上游恢复后用同一个 qrcode 仍可扫码登录）。**不要假设 `failed` 后本地一定被清**。
+> - 关键决策：`expired` 是**协议层不可恢复** → 换新图；`failed` 是**传输层/未知码** → 重试同一 qrcode。
 
 ### 备选路径：用户已持有 secret