@kg-ai/kugou-skill 0.1.6 → 0.1.7

package/README.md

@@ -24,7 +24,7 @@ kugou-cli auth login
 kugou-cli auth status
 ```
 
-> 必须将 Step 1 输出中 `qrcode_image_url` 渲染给用户扫码（用 `![酷狗登录二维码](<qrcode_image_url>)`）。token 会自动持久化存储。
+> 必须将 Step 1 输出中 `qrcode_img_url` 渲染给用户扫码（用 `![酷狗登录二维码](<qrcode_img_url>)`）。token 会自动持久化存储。
 
 ## 命令
 

package/SKILL.md

@@ -33,14 +33,15 @@ description: |
    ├─ 未登录 → 先询问用户："你手上是否已有可用的 base64 secret？"
    │   - 用户明确说"有" → 调 kugou-cli auth set-secret "<secret>"，跳过扫码
    │   - 用户说"没有"或不确定 → 走标准扫码流程
-   │   - 当前环境无法渲染远程 URL 图片（纯文本 agent / 客户端无法访问外网 / 不支持 Markdown 渲染）→ 强制走 set-secret
+    │   - 当前环境既无法渲染远程 URL 图片，也无法读取本地二维码文件 → 强制走 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>" 一次完成
+   4. 引导登录（详见 references/auth.md）：
+    - 扫码：执行 `auth login`，根据当前客户端的图片能力，在 `qrcode_img_url` 和 `qrcode_img_path` 中选择一种展示二维码，不要只输出 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）
 ```
@@ -48,19 +49,24 @@ description: |
 ### 关键注意事项
 
 - **登录流程极简**（详见 [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`、用户之前已经登录过想换设备。
+  1. `auth login` - 获取二维码，输出包含：
+     - `qrcode`：字符串标识，仅供 CLI 持久化和后续状态查询，Agent 不要将它作为图片展示
+     - `qrcode_img_path`：本地二维码 PNG 文件路径
+     - `qrcode_img_url`：酷狗上游返回的远程二维码图片 URL
+  2. **根据当前客户端能力选择一种方式，把二维码图片直接展示在聊天窗口中**：
+     - 客户端支持读取或附加本地图片（如 Codex）→ 使用 `qrcode_img_path`，通过客户端的本地图片读取/附件能力展示
+     - 客户端支持 Markdown 外链图片（如 WorkBuddy）→ 在消息正文中输出 `![酷狗登录二维码](<qrcode_img_url>)`
+     - Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码
+     - **不要**只把 URL 或本地路径作为普通文本发给用户，用户应直接看到二维码图片
+     - 首选方式展示失败时，立即切换到另一种方式：远程图片加载失败则尝试本地文件，本地文件无法读取则尝试远程 Markdown 图片
+     - 若两种方式都不可用 → 告诉用户“当前环境无法显示二维码，请提供 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_img_url` 远程图片也无法读取 `qrcode_img_path` 本地图片、用户之前已经登录过想换设备。
 - **登出 (auth logout)**：会**先**与服务端同步登出，**确认成功后才**清理本地登录态。失败时本地态保留、可重试；未登录时幂等直接返回成功。失败时 Agent **自动重试 1 次**（网络抖动常见），仍失败再询问用户是否重试，**不要**擅自清理本地文件。
 - **登录态自动失效**：当任意 `music` 命令遇到登录态过期时，CLI 会**自动清理**本地登录态，并在 stderr 输出 `账号登录过期，请重新登录`，exit code 非 0。Agent 收到该错误后：
   1. **不要**自己再调一次 `music` 命令（会再次失败）

package/package.json

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

package/references/auth.md

@@ -6,7 +6,7 @@
 
 | 命令 | 说明 | 需要登录 |
 |------|------|---------|
-| `kugou-cli auth login` | 获取二维码（`qrcode` 字符串 + `qrcode_image_url` 远程图片 URL） | 否 |
+| `kugou-cli auth login` | 获取二维码（`qrcode` 内部字符串 + `qrcode_img_url` 远程图片 URL + `qrcode_img_path` 本地 PNG 路径） | 否 |
 | `kugou-cli auth status` | 检查登录状态（**单次查询，不内部轮询**，agent 需外层循环 2-3s 间隔） | 否 |
 | `kugou-cli auth set-secret <secret>` | 直接导入已持有的 base64 secret 登录（跳过扫码） | 否 |
 | `kugou-cli auth logout` | 登出 | 否 |
@@ -18,7 +18,7 @@
 登录流程极简：
 
 ```bash
-# Step 1: 获取二维码（拿到 qrcode_image_url 用于渲染图片）
+# Step 1: 获取二维码，同时得到远程 URL 和本地 PNG 路径
 kugou-cli auth login
 
 # Step 2: 循环调用 status（**单次查询不内部轮询**，agent 自己外层循环）
@@ -28,12 +28,14 @@ kugou-cli auth status
 
 **auth login 输出示例**:
 ```json
-{"qrcode": "xxx", "qrcode_image_url": "https://static.kugou.com/.../qrcode.png"}
+{"qrcode": "xxx", "qrcode_img_path": "C:\\Temp\\kugou-qrcode.png", "qrcode_img_url": "https://static.kugou.com/.../qrcode.png"}
 ```
 
 字段说明：
-- `qrcode`：二维码字符串标识，**Agent 不要使用** —— 仅供 CLI 内部持久化以便后续 status 调上游 check 接口
-- `qrcode_image_url`：酷狗上游返回的图片 URL，**Agent 用它渲染二维码图片**
+- `qrcode`：二维码字符串标识，**Agent 不要使用** —— 仅供 CLI 内部持久化，以便后续 status 调上游 check 接口
+- `qrcode_img_path`：CLI 生成的本地二维码 PNG 文件绝对路径。当前客户端支持读取或附加本地图片时使用它，例如 Codex 等本地文件能力较强的客户端
+- `qrcode_img_url`：酷狗上游返回的远程二维码图片 URL。当前客户端支持 Markdown 外链图片时使用它，例如 WorkBuddy 等客户端
+- `qrcode_img_path` 和 `qrcode_img_url` 是两种并行的图片展示方式，Agent 根据当前客户端能力自行选择一种，不要同时展示两张二维码
 
 ---
 
@@ -53,11 +55,14 @@ kugou-cli auth status
 
 ### 2.2 扫码流程
 
-1. 调用 `auth login` 拿到 `qrcode_image_url`
-2. **建议**用以下任一能力把 `qrcode_image_url` 直接展示给用户：
-   - 首选：Markdown 语法——在消息中输出 `![酷狗登录二维码](<qrcode_image_url>)`
-   - 备选：原生图片附件（若有 image attach 工具）——把 URL 作为附件直接展示
-   - **避免**只输出"请打开 xxx URL"这种纯文字提示
+1. 调用 `auth login`，读取返回的 `qrcode_img_path` 和 `qrcode_img_url`
+2. **根据当前客户端能力选择一种方式展示二维码图片**：
+   - 客户端支持读取或附加本地文件（如 Codex 等）→ 优先使用 `qrcode_img_path`，通过客户端的本地图片读取/附件能力展示。不要只把路径作为普通文本发给用户
+   - 客户端支持 Markdown 外链图片（如 WorkBuddy 等）→ 使用 `qrcode_img_url`，在消息中输出 `![酷狗登录二维码](<qrcode_img_url>)`
+   - Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码
+   - **避免**只输出“请打开 xxx URL”或“图片路径是 xxx”这种纯文字提示，用户应直接看到二维码图片
+   - 选择的方式展示失败时，切换到另一种方式：远程图片加载失败则尝试本地文件，本地文件无法读取则尝试远程 Markdown 图片
+   - 如果当前客户端既不能读取本地文件，也不能渲染远程 Markdown 图片 → 放弃扫码，切换到 §3 `set-secret` 路径
 3. **阶段 A — 主动轮询（覆盖秒扫）**：图片展示后，**主动**外层循环调用 `auth status`，每次间隔 2-3 秒，**最多 5 次**：
    - 看到 `logged_in: true` → 完成，继续执行用户请求
    - 看到 `status: success` → 完成，继续执行用户请求
@@ -71,8 +76,8 @@ kugou-cli auth status
    - `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 各项处理，不要替用户做"再扫一次"之类的猜测
+6. **若用户在阶段 B 回复"没看到图片" / "图片打不开"** → 先切换到另一种二维码展示方式；两种方式都失败后，再切换到 §3 `set-secret` 路径
+7. **若用户在阶段 B 回复"已扫码"**但阶段 C 验证发现没登录成功（`scanned` / `failed`），按阶段 C 各项处理，不要替用户做"再扫一次"之类的猜测
 
 ### 2.3 状态表
 
@@ -126,7 +131,7 @@ kugou-cli auth set-secret "<base64-secret>"
 - 用户在其他设备/工具上已登录酷狗，导出或复制了一份 base64 secret
 - 测试、调试、自动化场景下需要直接注入 secret
 - 任何不便于扫码的终端环境（如 SSH 远端、容器、CI）
-- 当前 agent 工具集无法渲染 `qrcode_image_url` 远程图片（不联网 / 不支持 Markdown 渲染，见 §2.4）
+- 当前 agent 工具集无法渲染 `qrcode_img_url` 远程图片，或无法读取 `qrcode_img_path` 本地图片（不联网、不支持 Markdown 渲染或不支持本地图片附件，见 §2.2）
 
 **命令**:
 

package/references/output-format.md

@@ -37,6 +37,6 @@
 
 ### 3. 二维码
 
-使用 `qrcode_image_url` 渲染给用户：Markdown `![酷狗登录二维码](<qrcode_image_url>)`，让客户端拉取并渲染
+使用 `qrcode_img_url` 渲染给用户：Markdown `![酷狗登录二维码](<qrcode_img_url>)`，让客户端拉取并渲染
 
 ---