@kg-ai/kugou-skill 0.1.7 → 0.1.9

package/references/error-handling.md

@@ -1,22 +1,22 @@
-# 错误处理
-
-错误信息输出到 stderr，程序 exit code 为 1：
-
-```bash
-kugou-cli music search "xxx" 2>&1
-echo $?  # 非 0 表示出错
-```
-
----
-
-## 常见错误及处理
-
-| 错误信息 | 原因 | 处理方式 |
-|---------|------|---------|
-| `账号登录过期，请重新登录` | 登录态已过期。CLI 已**自动**清理本地登录态 | 引导用户重新登录：`kugou-cli auth login`（扫码）或 `kugou-cli auth set-secret "<新 secret>"` |
-| `not logged in` / `auth file not found` | 未登录 | 引导用户执行 `kugou-cli auth login` |
-| `HTTP error: 400` | 请求参数有误 | 检查命令参数是否正确 |
-| `HTTP error: 500` | 服务端错误 | 稍后重试，或告知用户 |
-| `API error: ...` | 业务错误 | 根据 errmsg 提示用户 |
-| `network error: ...` | 网络连接问题 | 检查网络，可尝试 `--proxy` |
-| `failed to get device info` | 设备信息获取失败 | 运行时环境异常，检查权限 |
+# 错误处理
+
+错误信息输出到 stderr，程序 exit code 为 1：
+
+```bash
+kugou-cli music search "xxx" 2>&1
+echo $?  # 非 0 表示出错
+```
+
+---
+
+## 常见错误及处理
+
+| 错误信息 | 原因 | 处理方式 |
+|---------|------|---------|
+| `账号登录过期，请重新登录` | 登录态已过期（errcode 语义由上游约定）。CLI 已**自动**清理本地登录态 | 引导用户重新登录：`kugou-cli auth login`（扫码）或 `kugou-cli auth set-secret "<新 secret>"` |
+| `not logged in` / `auth file not found` | 未登录 | 引导用户执行 `kugou-cli auth login` |
+| `HTTP error: 400` | 请求参数有误 | 检查命令参数是否正确 |
+| `HTTP error: 500` | 服务端错误 | 稍后重试，或告知用户 |
+| `API error: <errmsg> (code=<N>)` | 业务错误（上游 errcode ≠ 0） | 根据 errmsg 提示用户 |
+| `network error: ...` | 网络连接问题 | 检查网络，可尝试 `--proxy` |
+| `failed to get device info` | 设备信息获取失败（仅 control） | 运行时环境异常，检查权限 |

package/references/install.md

@@ -13,6 +13,7 @@
 | `kugou-cli install --hermes` | 安装到 Hermes skills 目录 |
 | `kugou-cli install --openclaw` | 安装到 Openclaw skills 目录 |
 | `kugou-cli install --codex` | 安装到 Codex skills 目录 |
+| `kugou-cli install --workbuddy` | 安装到 Workbuddy skills 目录 |
 
 ---
 
@@ -40,7 +41,7 @@ kugou-cli install --hermes --claude  # 安装到 Hermes 和 Claude
 
 - 无参数时输出"平台选择提示"，列出可用平台选项，不会进行任何安装操作
 - 只会在目标平台的 skills 父目录存在时才安装（不自动创建父目录）
-- npm 安装时会自动调用 install.js 安装 SKILL.md
+- npm 安装时会自动安装 SKILL.md
 - `kugou-cli install` 命令用于手动重新安装或更新 SKILL.md
 
 ---
@@ -49,6 +50,6 @@ kugou-cli install --hermes --claude  # 安装到 Hermes 和 Claude
 
 | 命令 | 说明 |
 |------|------|
-| `kugou-cli --version` / `kugou-cli version` | 输出版本号 |
+| `kugou-cli --version` / `kugou-cli version` | 输出版本号（`--version` 是 root flag，`version` 是子命令，两者输出相同） |
 | `kugou-cli --help` | 显示帮助信息 |
 | `kugou-cli <子命令> --help` | 显示子命令帮助（如 `kugou-cli music search --help`）|

package/references/music.md

@@ -7,13 +7,16 @@
 | 命令 | 说明 |
 |------|------|
 | `kugou-cli music search <keyword>` | 搜索歌曲 |
-| `kugou-cli music recommend daily` | 每日推荐 |
+| `kugou-cli music recommend guess` | 猜你喜欢（个性化推荐） |
 | `kugou-cli music recommend similar -s <song>` | 相似歌曲推荐 |
 | `kugou-cli music favorites` | 我的收藏 |
 | `kugou-cli music recent` | 最近播放 |
 | `kugou-cli music stats` | 听歌统计 |
 | `kugou-cli music charts <rank_id>` | 榜单 |
 | `kugou-cli music create-playlist <name>` | 创建歌单（可附加歌曲） |
+| `kugou-cli music search-playlist <keyword>` | 搜索歌单 |
+| `kugou-cli music recommend-playlist` | 歌单推荐 |
+| `kugou-cli music playlist-songs <global_collection_id>` | 歌单内歌曲列表 |
 
 ---
 
@@ -116,16 +119,13 @@ kugou-cli music recommend text --text "安静的钢琴曲" --num 5
 
 ---
 
-## 4. 我的收藏
+## 3. 我的收藏
 
 ```bash
 kugou-cli music favorites
-kugou-cli music favorites --page 1 --size 20
 ```
 
-**参数**:
-- `--page`: 页码，默认 1
-- `--size`: 每页数量，默认 20
+**参数**: 无（上游接口固定返回最近 10 首收藏，不支持分页）
 
 > 注意：固定返回最近 10 首收藏，查看更多请前往酷狗App
 
@@ -151,16 +151,13 @@ kugou-cli music favorites --page 1 --size 20
 
 ---
 
-## 5. 最近播放
+## 4. 最近播放
 
 ```bash
 kugou-cli music recent
-kugou-cli music recent --page 1 --size 20
 ```
 
-**参数**:
-- `--page`: 页码，默认 1
-- `--size`: 每页数量，默认 20
+**参数**: 无（上游接口固定返回最近 10 条播放记录，不支持分页）
 
 > 注意：固定返回最近 10 首播放记录，查看更多请前往酷狗App
 
@@ -186,7 +183,7 @@ kugou-cli music recent --page 1 --size 20
 
 ---
 
-## 6. 听歌统计
+## 5. 听歌统计
 
 ```bash
 kugou-cli music stats                    # 默认查当月
@@ -194,8 +191,8 @@ kugou-cli music stats --date-type 1 --date 20260501  # 指定周查询
 ```
 
 **参数**:
-- `--date-type`: 日期类型，0=日、1=周、2=月，默认 2（月）
-- `--date`: 查询日期，YYYYMMDD 格式，如 "20260501"（不填默认当月第一天）
+- `--date-type`: 日期类型，0=日、1=周、2=月（默认查当月）
+- `--date`: 查询日期，YYYYMMDD 格式，如 "20260501"。不传则查当月
   - 日类型：每天日期，如 "20260501"
   - 周类型：必须是周一日期，如 "20260505"（周一）
   - 月类型：必须是月份第一天，如 "20260501"（5月1日）
@@ -250,7 +247,7 @@ kugou-cli music stats --date-type 1 --date 20260501  # 指定周查询
 
 ---
 
-## 7. 榜单
+## 6. 榜单
 
 ```bash
 kugou-cli music charts 6666
@@ -269,25 +266,40 @@ kugou-cli music charts 52144 --page 1 --size 20
 | 52144 | 抖音热歌酷狗榜 |
 
 **参数**:
-- `<rank_id>`: 榜单 ID（必填）
-- `--page`: 页码，默认 1
-- `--size`: 每页数量，默认 20
+- `<keyword>`: 搜索关键词（必填）
+- `--page`: 页码，默认 1（**无简写**）
+- `--size`: 每页数量，默认 20（**无简写**）
 
 ---
 
-## 8. 创建歌单
+## 7. 创建歌单
 
-> 🔐 = 需要先登录
+> 🔐 = 需要先登录（CLI 登录 `auth login` / `auth set-secret`）
 
-### 调用原则（AI 必读）
+### 7.0 调用原则（AI 必读）
 
-1. **被动调用**：必须用户**明确**要求创建歌单时才调用本命令，禁止在用户仅说"推荐/搜歌/听歌"时主动创建
-2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户"是否需要将当前这批歌曲创建为歌单"，等用户确认后再执行 `create-playlist --songs "<mix_song_id 列表>"`
+1. **被动调用**：必须用户**明确**要求创建歌单时才调用，禁止在用户仅说"推荐/搜歌/听歌"时主动创建
+2. **主动询问**：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，**必须**询问用户"是否需要将当前这批歌曲创建为歌单"，等用户确认后再调用
 3. **示例化推荐**：询问时建议给出歌单名建议（如"跑步歌单"、"周杰伦精选"），让用户更容易确认
+4. **硬性默认：优先客户端创建**：用户一旦同意创建歌单，**必须先尝试** [`control playlist create`](./control.md#10-playlist-create--创建歌单)（在本地酷狗客户端内创建）。当以下**任一**条件成立时，回退到本节的 `music create-playlist`（云端创建）：
+   - **(a)** 当前系统不是 Windows / macOS（control 不支持 Linux）
+   - **(b)** 本地酷狗客户端未运行，或未通过 `kugou-cli control start` 完成握手（前置条件详见 [control.md §10](./control.md#10-playlist-create--创建歌单)）
+   - **(c)** `control playlist create` 调用失败（如 409/4091"login required"、网络错误等）—— 此时把 stderr 原样回给用户，并询问是否改走云端
+
+   简单说：**默认 `control`；客户端不可用或失败时，才退到 `music`**。不要在用户没问的情况下主动解释为什么走云端，先尝试 client 路径即可。
+
+5. **创建成功后主动询问是否播放**：无论走 `control playlist create` 还是 `music create-playlist`，**只要创建成功（返回 0/成功状态）就必须主动询问用户"是否要播放这个歌单"**，等用户明确回复后再决定走哪条播放命令：
+   - 用户同意 → 按场景选播放路径：
+     - **客户端路径优先**：`kugou-cli control play-playlist --global-id "<id>"`（详见 [control.md §12](./control.md#12-play-playlist--播放整个歌单)），可叠加 `--playlist-mode` 控制是否打断当前播放
+     - **云端歌单（`music create-playlist` 创建的）**：走浏览器 H5 路径（详见下方 7.2）——**不要**再用 `control play-playlist`，因为本地客户端没有这首歌单
+   - 用户拒绝 / 不回复 → 不做任何动作，不要替用户决定
+   - 仅在"创建歌单成功"时才询问；建失败时不询问（直接展示错误，等用户决定下一步）
+
+### 7.1 接口说明（云端备选，仅在 7.0 第 4 条任一条件成立时使用）
 
-### 接口说明
+> ⚠️ 本节是**云端备选路径**。优先走 [`control playlist create`](./control.md#10-playlist-create--创建歌单)（详见 [7.0 第 4 条](#70-调用原则ai-必读)）。仅当客户端不可用时使用本节。
 
-创建一个新的自建歌单，并可选择在创建后往歌单里添加歌曲。
+创建一个新的自创建歌单，并可选择在创建后往歌单里添加歌曲。
 
 ```bash
 # 创建空歌单
@@ -321,3 +333,194 @@ kugou-cli music create-playlist "我的批量歌单" --songs "123,456,789"
 **异常说明**:
 - 歌单创建成功但添加歌曲失败：返回 200 状态 + 错误信息，body 仍包含已创建歌单的 `name` 与 `song_list_url`
 - 歌单创建失败：返回对应错误码（参数错误 20010 / 网络错误 90000 等）
+
+### 7.2 云端歌单的播放：控制浏览器打开 H5 链接
+
+> 适用场景：用户同意播放的歌单是 `music create-playlist` 创建的（响应里有 `song_list_url`），且本地没有可用的酷狗客户端（7.0 第 4 条 (a)(b)(c) 任一成立）。
+
+**Agent 必须遵循"先探后告知"原则**：
+
+1. **先探测浏览器控制能力**：当前 Agent 工具栈是否能控制本地浏览器（playwright / dev-browser / chrome-devtools MCP 等任一可用）。可用 = 可用；都不可用 = 当前环境不支持浏览器控制
+2. **可用时**：
+   - 用浏览器工具打开响应里的 `song_list_url`（H5 链接，格式如 `https://m.kugou.com/songlist/gcid_...`）
+   - 等待 H5 页面加载完成（`networkidle` / 出现"播放全部"按钮）
+   - **轻量职责**：点击页面上的"播放" / "播放全部"按钮（若有），控制到"页面已渲染出播放控制"为止
+   - 页面登录、付费、版权屏蔽等后续问题**不归 Agent 管**，告诉用户"已打开 H5 歌单并尝试点击播放，如未自动播放请手动点一下"
+3. **不可用时**（无浏览器控制工具 / 浏览器控制调用失败）：
+   - 明确告知用户："当前环境无法控制浏览器，请手动复制链接在浏览器打开：[song_list_url]"
+   - **不要**伪装已经打开或点击了播放
+
+> **为什么不写死"先 playwright 再 chrome-devtools"？** 不同 Agent 工具栈内置的浏览器工具名不同，文档只规定行为契约（"打开 + 点击播放"），具体工具由 Agent 现场选择。
+
+---
+
+## 8. 搜索歌单
+
+根据关键词搜索歌单。
+
+```bash
+kugou-cli music search-playlist "周杰伦"
+kugou-cli music search-playlist "周杰伦" --page 1 --size 20
+kugou-cli music search-playlist "跑步" --filter 1   # 只搜 UGC
+kugou-cli music search-playlist "钢琴" --filter 2   # 只搜非 UGC
+```
+
+**参数**:
+- `<keyword>`: 搜索关键词（必填）
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20
+- `--filter`: 过滤方式，`0=全部（默认） / 1=只搜 UGC / 2=只搜非 UGC`
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "list_id": 2651286,
+        "global_id": "collection_3_938985631_304_0",
+        "name": "<em>周杰伦</em>：无与伦比，为杰沉沦。",
+        "creator_id": "938985631",
+        "creator_name": "慕情超爱撒花",
+        "intro": "",
+        "song_list_url": "https://m.kugou.com/songlist/gcid_3z938985631z304z2"
+      }
+    ],
+    "total": 1000,
+    "page": 1,
+    "size": 20
+  },
+  "status": 1
+}
+```
+
+**关键字段**:
+- `list_id`: 歌单 ID（数字 string）
+- `global_id`: 全局歌单 ID（字符串，跨客户端兼容的稳定标识）
+- `name`: 歌单名
+- `creator_id`: 创建者用户 ID（字符串）
+- `creator_name`: 创建者昵称
+- `intro`: 歌单简介
+- `song_list_url`: 歌单链接（H5），格式 `https://m.kugou.com/songlist/gcid_{encoded(global_id)}`；`global_id` 为空时返回空字符串
+
+> **提示**: 歌单搜索/推荐只返回基础信息用于卡片展示。需要歌曲数、播放量、收藏数、封面图、歌单内歌曲等详细信息时，调用方拿到 `global_id` 后调用 [第 10 章](#10-歌单内歌曲列表) 或直接打开 `song_list_url`。
+
+**特殊说明**:
+- 上游高亮：服务端固定传 `tag=em`，返回的 `name` 字段带 `<em>...</em>` 高亮标签，前端可直接渲染
+- 上游错误码：146/147=被屏蔽地区，148=非法关键字，149=页码超出范围。出现时返回 90000 网络错误，建议引导用户重试或更换关键词
+
+---
+
+## 9. 歌单推荐
+
+根据用户喜好个性化推荐歌单。
+
+```bash
+kugou-cli music recommend-playlist
+kugou-cli music recommend-playlist --page 1 --size 20
+kugou-cli music recommend-playlist --module-id 6   # 我-最近播放-歌单下方
+```
+
+**参数**:
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20
+- `--module-id`: 上游模块 ID，由客户端透传。常见值：
+  - `1` = 歌单广场（默认）
+  - `5` = 酷狗 X 首页为你推荐
+  - `6` = 我 - 最近播放 - 歌单下方
+  - `15` = 酷狗 12 听首页为你推荐
+
+  不传时服务端默认填 `1`。
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "list_id": 2651286,
+        "global_id": "collection_3_938985631_304_0",
+        "name": "周杰伦：无与伦比，为杰沉沦。",
+        "creator_id": "938985631",
+        "creator_name": "慕情超爱撒花",
+        "intro": "",
+        "song_list_url": "https://m.kugou.com/songlist/gcid_3z938985631z304z2"
+      }
+    ],
+    "total": 100,
+    "has_next": 1,
+    "session": "1706428800",
+    "refresh_time": 0,
+    "page": 1,
+    "size": 20
+  },
+  "status": 1
+}
+```
+
+**关键字段（顶层）**:
+- `total`: 总数；`has_next`: 是否有下一页（1=是 / 0=否）
+- `session`: 会话标识（暂时返回时间戳）
+- `refresh_time`: 客户端刷新时间（秒），`0` 或缺失表示不刷新
+
+**关键字段（list[]）**:
+- 与歌单搜索（[第 8 章](#8-搜索歌单)）共用同一套 `PlaylistInfo` 基础字段（`list_id` / `global_id` / `name` / `creator_id` / `creator_name` / `intro` / `song_list_url`），调用方可使用同一套反序列化逻辑
+- 已登录时上游根据 userid 做个性化推荐；未登录时可能返回空数据或通用推荐
+- 上游可能附带 `cache` 等字段，CLI 不解析、不保证
+
+---
+
+## 10. 歌单内歌曲列表
+
+通过歌单全局 ID（`global_collection_id`）获取歌单内歌曲列表。一般先调用 [第 8 章](#8-搜索歌单) 或 [第 9 章](#9-歌单推荐) 拿到 `global_id`，再透传给本接口。
+
+```bash
+kugou-cli music playlist-songs "collection_3_938985631_304_0"
+kugou-cli music playlist-songs "collection_3_938985631_304_0" --page 1 --size 100
+```
+
+**参数**:
+- `<global_collection_id>`: 歌单全局 ID（必填，从 `search-playlist` / `recommend-playlist` 响应的 `global_id` 字段透传）
+- `--page`: 页码，从 1 开始，默认 1
+- `--size`: 每页数量，默认 100（上游建议值）
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "song_name": "晴天",
+        "mix_song_id": "8888",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html"
+      },
+      {
+        "song_name": "七里香",
+        "mix_song_id": "8890",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html"
+      }
+    ],
+    "total": 164,
+    "page": 1,
+    "size": 100
+  },
+  "status": 1
+}
+```
+
+**关键字段**:
+- `list[]`: 通用 `SongInfo` 结构（`song_name` / `mix_song_id` / `artist_name` / `play_link`）
+- `total`: 上游返回的歌曲总数（不含被过滤的屏蔽歌曲）
+
+> **关于上游附带字段**：CLI 透传上游原始 JSON 字符串，响应里**可能**含其他字段（如 `hash`、`singer_id` 等），但 CLI 不解析、不保证存在。Agent 不要依赖未在 `SongInfo` 中列出的字段。
+
+**特殊说明**:
+- **屏蔽歌曲过滤**: 上游可能跳过被屏蔽的歌曲（不返回），`total` 不含被过滤项，`list` 长度可能小于 `size`
+- **artist_name 拼接**: 多歌手时上游用 `/` 拼接（例如 `周杰伦/方文山`）
+- **分页去重**: 上游按服务端数组下标分页，但歌曲可能在分页期间被增删，调用方需自行按 `mix_song_id` 去重
+- **播放链接**: `play_link` 由服务端拿到 `mix_song_id` 后批量生成，单条失败不影响其他歌曲

package/references/output-format.md

@@ -2,7 +2,7 @@
 
 ## 通用响应结构
 
-所有 API 命令输出标准 JSON 结构：
+`music` / `auth` / `install` 等"上游 API 类"命令输出标准 JSON 结构：
 
 ```json
 {
@@ -13,10 +13,11 @@
 }
 ```
 
-**响应状态**:
-- `errcode: 0` 表示成功
+**响应状态判定**:
+- **成功判定只看 `errcode == 0`**——这是 Agent 唯一可信的成功依据
 - `data` 包含实际业务数据
-- `status: 1` 表示接口调用成功
+- `status: 1` 是上游接口调用状态提示，**仅作辅助参考**（部分上游错误响应里 `status` 可能不是 1，但仍由 `errcode` 决定 CLI 成功与否）
+- **`control` 命令不走这个结构**——它透传酷狗客户端本地 HTTP 协议的原始 JSON，成功字段通常是 `code` 而不是 `errcode`。见 [references/control.md](./control.md)
 
 ---
 
@@ -30,6 +31,7 @@
 - **必须**以 Markdown 链接格式展示播放链接
 - 正确格式：`[歌曲名 - 歌手名](https://www.kugou.com/...)`
 - 禁止格式：`晴天 - 周杰伦`（无链接）、`歌曲名: 晴天, 歌手: 周杰伦`（无链接）
+- **仅适用于 `music` 命令返回的歌曲列表**；`control` 操作响应（如 play / favorite）没有 play_link，按 control 协议原样展示即可
 
 ### 2. 统计数据
 
@@ -39,4 +41,48 @@
 
 使用 `qrcode_img_url` 渲染给用户：Markdown `![酷狗登录二维码](<qrcode_img_url>)`，让客户端拉取并渲染
 
+### 4. 错误展示
+
+- CLI 错误输出到 **stderr**，stdout 只放原始 JSON（或原始 body）
+- Agent 解析失败时同时检查：退出码（0 = 成功，非 0 = 失败）、stdout body 的 `errcode` 字段、stderr 输出
+- 不要把 stderr 输出原样展示给用户；转化为自然语言说明（如"账号登录过期，请重新登录"）
+
+---
+
+### 5. 推荐理由（主动推荐场景必写）
+
+**触发条件**：仅当 agent **主动**给用户推荐歌曲时才写推荐理由，包括以下命令的返回结果：
+
+- `kugou-cli music recommend guess`（猜你喜欢）
+- `kugou-cli music recommend similar -s <song>`（相似推荐）
+- `kugou-cli music recommend text --text <描述>`（文本推歌）
+- `kugou-cli music charts <rank_id>`（榜单，详见 [music.md#7](music.md#7)）
+- `kugou-cli music recommend-playlist`（歌单推荐）—— 歌单本身就是主动推荐行为
+
+**不触发**：用户**主动搜索**（`search` / `search-playlist`）、查自己数据（`favorites` / `recent` / `stats`）、查指定歌单内容（`playlist-songs`）的结果**不写**推荐理由——用户来找东西，不需要再被解释一遍。
+
+#### 写法要求
+
+在歌曲列表**之后**追加一段 Markdown 引用块（`>`）作为推荐理由，必须包含以下三层信息：
+
+1. **整体歌曲风格**：用一句话概括本批推荐的整体风格/情绪基调（例如「以华语流行慢歌为主，情绪偏舒缓治愈」）。
+2. **匹配逻辑**：依据当前推荐场景说明匹配来源——
+   - 猜你喜欢 / 歌单推荐 → 「基于你的听歌偏好/历史播放」
+   - 相似推荐 → 「延续《XXX》的 XXX 风格/主题」
+   - 文本推歌 → 「贴合你描述的『XXX』场景」
+   - 榜单 → 「来自 XXX 榜第 N 名，XXX 类热度风向」
+3. **挑 2-3 首解读**：从本批返回中挑选 2-3 首，**结合行业认知**（歌手常见风格、歌曲广为人知的标签、所属专辑/年代等）做一句解读，帮助用户判断是否合口味。
+
+> ⚠️ 解读内容**仅基于歌名 + 歌手名调用 agent 自身行业认知**，不要捏造歌词、不要引用未经验证的曲风标签。如对歌曲不熟悉，宁可写得笼统一些也不要硬编细节。
+
+#### 字数硬约束
+
+**总字数控制在 220-260 字（含标点）**。超出或不足都需要重写到区间内。撰写时不必分段，整体作为一段引用块即可。
+
+#### 输出示例
+
+```markdown
+> 为你挑选了 5 首华语流行慢歌，整体偏舒缓、情绪内敛，节奏不快不躁，编曲以钢琴和原声吉他为主，更适合午后或深夜一个人安静循环。匹配逻辑来自你最近的播放记录和猜你喜欢数据，我们从中挑出与历史偏好契合度最高的几首组成了这张清单。其中《晴天》是周杰伦 2003 年的代表作，校园民谣的底色配钢琴铺陈，几乎成了一代人的青春共同记忆；《七里香》延续了同期的中国风与诗意意象，副歌弦乐层层推进，听感最为饱满宏大；《稻香》则把视角拉回乡村童年，节奏轻快但内核温暖，是整张清单里最治愈的一首作品。
+```
+
 ---

package/references/update.md

@@ -27,7 +27,6 @@
 
 ### 2. 检查频率限制
 
-- 缓存文件：`~/.config/kugou-cli/update_check.json`
 - 缓存有效期：**24 小时**
 - 24 小时内不会重复访问 npm registry
 
@@ -46,6 +45,8 @@
 kugou-cli update --check
 ```
 
+> **绕过 24h 缓存**：显式调用 `kugou-cli update [--check]` **总是**绕过本地 24h 缓存，强制访问 npm registry。这与"启动时被动检查"的语义不同——启动检查走缓存（24h 内不重复访问 npm），显式 `update` 命令不走缓存。
+
 **输出示例**：
 
 有更新时：