@kg-ai/kugou-skill 0.1.7 → 0.1.8

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` 命令不走缓存。
+
 **输出示例**：
 
 有更新时：