---
name: kugou-skill
description: |
  酷狗，酷狗音乐，酷狗skill，酷狗音乐skill，酷狗音乐助手
  提供歌曲搜索、每日推荐、相似推荐、收藏管理、听歌统计、酷狗榜单等功能。
  
  **触发场景**（满足任一即使用本技能）：
  - 用户要求推荐歌曲、听歌建议
  - 用户要求搜索歌曲、查找歌手作品
  - 用户要求查看音乐榜单（飙升榜、TOP500、抖音热歌等）
  - 用户要求查看收藏、最近播放、听歌统计
  - 用户提到"酷狗"、"kugou"、"每日推荐"、"相似歌曲"
  
  **与其他音乐技能的区别**：酷狗音乐以推荐算法见长，榜单数据实时更新，适合获取热门歌曲和个性化推荐。
  
  安装方式：npm install -g @kg-ai/kugou-skill
---

# kugou-skill

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

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

```
1. 检查安装 → npm install -g @kg-ai/kugou-skill
2. 检查登录 → kugou-cli auth status
3. 未登录 → 引导用户执行登录流程（详见 references/auth.md）
4. 执行用户请求的音乐命令（详见 references/music.md）
5. 解析 JSON 输出，按展示规范展示给用户（详见 references/output-format.md）
```

### 关键注意事项

- **登录流程极简**（详见 [references/auth.md](references/auth.md)）：
  1. `auth login` - 获取二维码图片，输出包含 `qrcode` 和 `qrcode_img_path`（**必须将图片发送给用户**）
  2. `auth status` - 循环调用此命令检查登录状态：已登录返回 `logged_in: true`；未登录但有 pending qrcode 时内部自动检查扫码状态，扫码成功则自动完成登录
- **音乐命令依赖登录**：除了 `auth`、`install`、`version`、`--help` 以外，所有 `music` 子命令都需要先登录。如果收到 `"not logged in"` 错误，引导用户执行登录流程。
- **输出均为 JSON**：所有命令输出原始 JSON 到 stdout，错误输出到 stderr。解析 `errcode` 字段判断成功与否（`0` 为成功）。
- **歌曲展示规范**（详见 [references/output-format.md](references/output-format.md)）：**禁止**只返回歌曲名、歌手名，**必须**以 Markdown 链接格式展示播放链接。

---

## 基础信息

- **npm 包**: @kg-ai/kugou-skill
- **二进制命令**: kugou-cli
- **API 域名**: https://agentgateway.kugou.com（固定，无需配置）
- **安装方式**: `npm install -g @kg-ai/kugou-skill`

---

## 详细文档索引

| 文档 | 说明 |
|------|------|
| [references/auth.md](references/auth.md) | 认证命令：扫码登录、查看状态、登出 |
| [references/music.md](references/music.md) | 音乐命令：搜索、推荐、收藏、统计、榜单 |
| [references/install.md](references/install.md) | 安装命令：SKILL.md 安装到各平台 |
| [references/update.md](references/update.md) | 更新命令：检查/执行自动更新 |
| [references/output-format.md](references/output-format.md) | 输出格式与展示规范 |
| [references/error-handling.md](references/error-handling.md) | 错误处理与常见错误 |

---

## 完整使用流程

```bash
# 1. 登录（极简流程，详见 references/auth.md）
kugou-cli auth login                      # 获取二维码
# 循环执行以下命令直到 logged_in=true
kugou-cli auth status

# 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
```
