kugou-skill

AI 使用工作流（优先阅读）

使用本工具时的标准流程：

1. 检查安装 → npm install -g @kg-ai/kugou-skill
2. 检查登录态 → kugou-cli auth status
3. 登录决策（按以下优先级严格判断，不要跳步）：
    ├─ 状态 a：已登录（logged_in: true）→ 跳到第 6 步
    ├─ 状态 b：未登录 + 用户**明确**说"我有 secret" → 调 `kugou-cli auth set-secret "<secret>"` 一次完成 → 跳到第 6 步
   ├─ 状态 c：未登录 + 当前环境**无法**渲染远程 URL 图片 **且** 无法读取本地二维码文件 → **强制**走 set-secret（同上）
   └─ 状态 d：未登录 + 其他所有情况 → 走扫码流程（第 4 步）

   注意：状态 b/c/d 互斥；不要在用户未明确给 secret 时擅自走 set-secret。
4. 引导登录——扫码（详见 references/auth.md）：
   - 执行 `auth login`，从输出读 `qrcode_img_url` 和 `qrcode_img_path`，按当前客户端能力选一种方式把二维码**直接展示给用户**
     - **阶段 A（主动轮询）**：图片刚展示，**主动**重试几次 `auth status`（每次隔几秒），覆盖用户秒扫场景
      - 任意一次返回 `logged_in: true` → 跳到第 6 步
      - 见到 `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` → **不要换新图**，隔 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`（零副作用，不启动客户端、不抢焦点）
   - **判定**：
     - 退出码 `0` → 本机有客户端，标记 `client_available = true`
     - 退出码 `2` → 本机没装客户端，标记 `client_available = false`
     - 退出码 `1` → 探测过程出错（注册表权限等），按 `false` 处理并继续
    - **不影响 control 命令本身**：当用户主动要求 `control play` 等命令时，仍按原本的 `control` 错误处理（找不到客户端会由 `control start` 报"handshake file not found"，不要用探测结果跳过 `control` 调用）
   - **何时不探测**：用户请求只查询统计数据、查收藏/最近播放、看错误页等**不展示歌曲列表**的纯查询场景；登录流程本身；debug / 排错场景

6. 按请求类型分流：
   - **请求类型 A：控制已有歌 / 歌单 / 收藏**（用户已有 mixsongid 或 global_id）→ 直接执行 `control` 命令（详见 [references/control.md](references/control.md)），不需要先调 `music` 拿 ID
     - 例：`control play`、`control player --action pause`、`control favorite song --mixsongid <id>`、`control play-playlist --global-id <id>`
   - **请求类型 B：搜索后做某件事**（搜索歌曲/推荐/榜单 → 拿到 ID 后再做后续动作，如播放、收藏、建歌单）→ 先执行 `music` 命令拿数据，再按需转 `control`，详见 [references/music.md](references/music.md)
     - 例：先 `music search` 拿 mixsongid，再 `control play` 播放
     - 例：先 `music search-playlist` 拿 global_id，再 `control play-playlist` 播放
     - 例：先 `music search` 拿 mixsongids，再 `control playlist create --mixsongids` 创建客户端歌单
   - **请求类型 C：纯查询 / 统计 / 榜单**（不涉及本地客户端）→ 只走 `music` 命令
7. 解析 JSON 输出，按展示规范展示给用户（详见 [references/output-format.md](references/output-format.md)）

关键提醒：不要在没有 mixsongid / global_id 的情况下盲目调用 control 命令（如 control play --mixsongid ""）—— control 命令在 ID 缺失时会报错。先用 music 命令把 ID 查出来，再传给 control。

关键注意事项

登录流程

auth login 命令输出三个字段供 Agent 选择二维码展示方式（详见 references/auth.md）：

根据当前客户端能力选择一种方式，把二维码图片直接展示在聊天窗口中：

• 客户端支持读取或附加本地图片（如 Codex）→ 使用 qrcode_img_path，通过客户端的本地图片读取/附件能力展示
• 客户端支持 Markdown 外链图片（如 WorkBuddy）→ 在消息正文中输出 ![酷狗登录二维码](<qrcode_img_url>)
• Agent 可以自行选择最适合当前环境的方式，不要同时展示两张二维码
• 不要只把 URL 或本地路径作为普通文本发给用户，用户应直接看到二维码图片
• 首选方式展示失败时，立即切换到另一种方式：远程图片加载失败则尝试读取本地图片，本地图片无法读取则尝试远程 Markdown 图片
• 若两种方式都不可用 → 告诉用户"当前环境无法显示二维码，请提供 base64 secret 字符串"，改走 auth set-secret

auth status 的调用约束：

• 每次调用只查一次扫码状态，不会内部自动轮询。Agent 需要在外层按"阶段 A → 阶段 B → 阶段 C"循环调用（详见上方工作流第 4 步）
• 阶段 B 之后不要自己继续调用 status，等用户回复

直接导入 secret 登录

当用户已经持有一个有效的 base64 secret 字符串（从别处获取的），直接调用 kugou-cli auth set-secret "<secret>" 即可完成登录，跳过扫码流程——效果与扫码登录完全一致。secret 字符串含 + / = 是正常的，shell 里务必用引号包起来。

何时考虑用 set-secret：

• 用户明确说"我有 secret"
• 当前环境既无法展示远程图片也无法读取本地图片
• 用户之前已经登录过想换设备

登出

auth logout 命令：先与服务端同步登出，确认成功后才清理登录状态。失败时登录状态保留、可重试；未登录时幂等直接返回成功。

登录态自动失效

当任意 music 命令遇到登录态过期时，CLI 会自动取消登录（退出码非 0 + stderr 提示登录已过期）。Agent 收到该错误后：

1. 不要自己再调一次 music 命令（会再次失败）
2. 直接引导用户重新登录：先问"你手上是否已有新 secret？"，有则 auth set-secret，没有则 auth login 走扫码
3. 重新登录后，先调 auth status 确认 logged_in: true，再重试之前失败的 music 命令

错误判定以退出码 + references/error-handling.md 中的错误码说明为准，不要依赖 stderr 文案字面量匹配。

音乐命令依赖登录

除了 auth、install、version、--help 以外，所有 music 子命令都需要先登录。如果 CLI 返回"未登录"错误，引导用户执行登录流程。

输出格式与成功判定

所有命令输出原始 JSON 到 stdout，错误输出到 stderr。成功判定以退出码和 JSON 内的成功状态字段为准（详见 references/output-format.md）。

歌曲/歌单展示规范

向用户展示音乐命令返回的歌曲列表或歌单列表时，按以下规则（详见 references/output-format.md §1）：

• 结果 ≥ 2 条 → 用 Markdown 表格展示
  • 歌曲表格列：| 序号 | 歌曲名 | 歌手 |
  • 歌单表格列：| 序号 | 歌单名 | 创建人昵称 |
  • 表格内的歌曲名 / 歌单名一律不加链接（避免列宽过长、可读性差；详见下方解释）
• 结果 = 1 条 → 用单行 Markdown 链接展示
  • 有客户端（探测结果 client_available = true）→ 歌曲名/歌单名不加链接（可直接调 control play 等本地命令）
  • 无客户端（探测结果 client_available = false）→ 歌曲名/歌单名必须加链接，方便用户手动打开
  • 歌曲正确格式：[歌曲名 - 歌手名](https://www.kugou.com/...)
  • 歌单正确格式：[歌单名](<song_list_url>)
• 结果 = 0 条 → 告诉用户"未找到结果"，不需要展示表格或链接

为什么表格不加链接？

• 表格单元格加 Markdown 链接会让列宽自适应 URL，中文长字符串下表的可读性变差
• 表格场景下用户通常是要浏览/筛选，ID 由 agent 内部持有，等用户明确说"播放这首" / "打开这个歌单"再走对应命令

客户端可用性探测怎么用？

• 首次要展示歌曲/歌单列表前，按工作流第 5 步跑 kugou-cli control detect，记下 client_available
• 单条结果（= 1）时根据 client_available 决定加不加链接
• 表格结果（≥ 2）时无视 client_available，表格单元格不加链接
• 探测结果不影响用户主动调用 control * 命令的逻辑——那是另一条独立路径（由 control start 自己报错）

播放 / 切歌后必须告知当前曲目

触发条件：以下命令成功后必须告知用户当前正在播放的歌曲：

• control play（播放单首）
• control play-playlist（播放整个歌单）
• control continue-play（续播另一设备列表）
• control player --action next/prev（切歌）

操作：调用 kugou-cli control current 拿到 song_name / singer_name，向用户输出：

� 正在播放：<歌曲名> - <歌手>

注意：

• 必须用 control current 重新拿当前曲目，不要用 control play 命令里 --song-name / --singer-name 字段直接展示——后者只是客户端展示用的标签，不保证与实际播放一致（特别是播放歌单 / 续播 / 切歌之后）
• 若 control current 返回非 code: 0（如客户端断开 / 命令未支持），告知用户"已开始播放（无法读取当前曲目详情）"，不要假装知道

详见 references/control.md §3 current。

推荐理由规范

仅在 agent 主动推荐场景下，歌曲列表之后必须追加一段 220-260 字的推荐理由（详见 references/output-format.md#5-推荐理由主动推荐场景必写）：

• 触发：recommend guess / similar / text、charts、recommend-playlist
• 不触发：search / search-playlist / favorites / recent / stats / playlist-songs——用户主动查询不写
• 三层内容：整体歌曲风格 + 匹配逻辑 + 挑 2-3 首基于行业认知的解读
• 字数硬约束：220-260（含标点），超出或不足需重写

创建歌单的调用原则

详见 references/music.md#7-创建歌单：

1. 被动调用：必须用户明确要求创建歌单时才调用，禁止在用户仅说"推荐/搜歌"时主动创建
2. 主动询问：当通过搜索、推荐（猜你喜欢/相似/文本）等方式给出一批歌曲后，必须询问用户是否需要将当前这批歌曲创建为歌单，等用户确认后再调用
3. 硬性默认：优先客户端创建：用户同意后必须先尝试 kugou-cli control playlist create（在本地酷狗客户端内创建，详见 references/control.md#10-playlist-create--创建歌单），仅当客户端不可用（不支持的操作系统 / 未运行 / 无响应 / 调用失败）时才回退到云端 music create-playlist
4. 创建成功后主动询问是否播放：无论走 control playlist create 还是 music create-playlist，创建成功（返回成功状态）后必须主动询问用户"是否要播放这个歌单"，等用户明确回复后再决定走哪条播放命令；用户拒绝则不做任何动作。播放路径选择：
   • 客户端可用：优先 kugou-cli control play-playlist --global-id "<id>"（详见 references/control.md#12-play-playlist--播放整个歌单）
   • 客户端不可用 / play-playlist 拿不到可用 ID：按 references/music.md#72-云端歌单的播放控制浏览器打开-h5-链接 走"先探后告知"——用浏览器工具打开 H5 song_list_url 尝试点击播放；工具不可用时明确告知用户手动复制链接打开

调整偏好的调用原则

详见 references/music.md#11-提交偏好：

1. 被动调用：必须用户明确表达偏好调整意愿时才调用 kugou-cli music submit-preference，禁止在用户仅说"推荐/搜歌/听歌"时主动改写用户偏好
2. 解析用户意图 → 落到 dimension/degree/name：按 references/music.md#11-提交偏好 调用流程 里的"用户原话 → dimension/degree/name"映射表翻译，不确定时主动询问（"你说的『少推点 XX』是指歌手还是语种/曲风？"）
3. name 用服务端能识别的标准名：用户口语里的昵称/简称（"老周"）必须先问清楚再调，因为上游 name 必须是服务端能识别的标准名（如"周杰伦"）
4. weight-ratio 配对：reduce→(0,1)、forbid/add→(1,2)。不匹配时 CLI 仅 warning 不阻断，最终以服务端校验为准
5. 提交成功后的呈现优先级：
   • 第一优先：用响应 data.msg（上游确认话术）展示给用户，例如"收到！将减少推荐歌手「周杰伦」的歌曲，猜你喜欢以下歌曲~"
   • 第二优先：把响应 data.list（重新推荐的歌曲列表）按 references/output-format.md#1-歌曲歌单列表展示批量优先用表格 的展示规范呈现（≥ 2 条用表格，= 1 条按 client_available 决定加不加链接）
   • 表格里不加 <em> 高亮 / play_link / mix_song_id，agent 内部持有
6. 复用 list，不要再调 recommend：拿到新推荐的 list[] 后，主动询问用户"要按这个新偏好播放一些吗？"，用户同意后直接用 list[] 里的 mix_song_id 走 control play 等命令，不要再调一次 recommend 浪费调用
7. 多次提交会叠加：本接口是实时反馈给推荐引擎，不会持久化为用户画像规则；同一歌手多次提交会叠加效果，不要替用户循环重提

能力边界提示

当用户提出的需求在 kugou-cli 整体能力边界之外时，Agent 必须明确告知用户"暂不支持该能力"，不得擅自用其他命令拼凑代替，也不得假装能完成。

典型场景：

• kugou-cli 没有对应子命令（用户要的功能不在 auth / music / control / install 任何子命令中）
• control 子命令在当前操作系统不支持（如 control 系列仅支持 Windows / macOS，Linux 不支持）
• 命令存在但参数 / 取值已下线（如 control open --target-type url 已被移除）
• CLI 整体没有相关云端 API（如批量下载、歌词编辑、播客等）

正确回应：

这个能力 kugou-cli 暂不支持。如果你需要该功能，可以去酷狗客户端里手动操作。

反例（不要这样做）：

• 不要用「推荐相似歌曲」伪装成「按场景生成歌单」之类的能力替代
• 不要反复尝试不同参数 / 多次重试来"碰运气"绕过不支持
• 不要把 CLI 报错（"unknown flag" / "unsupported"）原样翻译后甩给用户——先判断这是"能力不存在"还是"用法不对"再回应

与「客户端不可用」的区别：本节是「命令/能力本身不存在」；「客户端不可用」是「命令存在但本机客户端未运行 / 未登录」，后者有 fallback 路径（详见上方「创建歌单的调用原则」第 3 条 + references/control.md）。两者不要混用。

基础信息

• npm 包: @kg-ai/kugou-skill
• 二进制命令: kugou-cli
• 安装方式: npm install -g @kg-ai/kugou-skill

关于更新：CLI 安装后会自动保持最新。具体行为与关闭开关见 references/update.md。如有版本相关问题，向该文档查证。

详细文档索引

完整使用流程

# 1. 登录（详见 references/auth.md）
kugou-cli auth login                      # 获取二维码
kugou-cli auth status

# 1'. 或者直接导入已持有的 secret（跳过扫码）
kugou-cli auth set-secret "<base64-secret>"

# 2. 搜索歌曲
kugou-cli music search "周杰伦"

# 3. 获取猜你喜欢
kugou-cli music recommend guess

# 4. 查看我的收藏（返回最近若干首，不支持分页）
kugou-cli music favorites

# 5. 查看最近播放（返回最近若干条，不支持分页）
kugou-cli music recent

# 6. 查看听歌统计
kugou-cli music stats

# 7. 查看抖音热歌榜
kugou-cli music charts 52144

# 8. 创建歌单
# 优先走客户端路径（默认）：见 references/control.md §10
kugou-cli control playlist create --name "我的批量歌单" --mixsongids "32068120,233125060"
# 客户端不可用时才回退到云端（详见 references/music.md §7.1）：
kugou-cli music create-playlist "我的空歌单"
kugou-cli music create-playlist "我的批量歌单" --songs "32068120,233125060"

# 9. 搜索歌单（拿到 global_id 后可透传给 control play-playlist）
kugou-cli music search-playlist "周杰伦"
kugou-cli music playlist-songs "collection_3_938985631_304_0"

# 10. 控制本机酷狗客户端（仅 Windows / macOS，详见 references/control.md）
kugou-cli control play --mixsongid 32100650 --song-name "晴天" --singer-name "周杰伦"
kugou-cli control player --action pause
kugou-cli control favorite song --mixsongid 32100650

# 11. 调整音乐偏好（用户明确表达"少推点/别再推/多推点"时调用，详见 references/music.md#11-提交偏好）
kugou-cli music submit-preference --dimension singer --degree reduce --name "周杰伦" --weight-ratio 0.5
kugou-cli music submit-preference --dimension language --degree add --name "粤语" --weight-ratio 1.8