技能介绍

解决的问题

在 Agent 或 CLI 工作流里接入酷狗时，常见卡点不只是“能不能搜歌”，而是登录态、客户端状态和 ID 依赖容易让自动化失败：没有 mixsongid / global_id 就调 control play 会报错；二维码登录在不同客户端里可能无法直接展示；音乐查询、歌单创建、播放控制又分云端和本地两条路径。kugou-skill 把这些步骤拆成可执行的命令与约束，让 Agent 能按登录、查询、控制、展示的固定顺序调用 kugou-cli。

技能如何工作

技能主要围绕三类命令展开：

认证：auth login 输出二维码路径和 URL，Agent 根据客户端能力展示本地图片或远程 Markdown 图片；用户已有 secret 时可用 auth set-secret 直接登录；auth status 只查一次状态，需要外层循环判断。
音乐查询：music 子命令覆盖搜索、推荐、收藏、统计、榜单和歌单内容。返回结果通常是 JSON，适合继续提取歌曲名、歌手、歌单名、创建人和 ID。
播放控制：control 子命令面向本地酷狗客户端，可播放、暂停、切歌、读取当前曲目、创建歌单。播放或切歌成功后，应调用 control current 获取当前 song_name 和 singer_name，而不是直接展示命令参数。

展示时也有明确规则：多条结果用表格，单条结果根据 client_available 决定是否加链接，零结果直接说明未找到。主动推荐场景还需要补充固定长度的推荐理由，而用户主动搜索、收藏、统计等场景不需要。

适用边界与注意点

control 依赖本地客户端，通常适用于 Windows / macOS；Linux 或不支持客户端时，不应假装可播放。
命令能力之外，例如批量下载、歌词编辑、播客等，应明确告知暂不支持，不要用其他命令拼凑替代。
登录态过期后，不要重复原 music 命令，而应先引导 set-secret 或 auth login，再确认 logged_in: true 后重试。
成功判定优先看退出码与 JSON 状态字段，不要依赖 stderr 文案字面量。