# Netease Music CLI

> 使用 ncm-cli 操作网易云音乐。当用户想播放歌曲、搜索歌曲、控制播放（暂停、下一首、上一首、调音量）、管理播放队列、查看播放状态、播放歌单时，使用此 skill。

- Skill: `netease/netease-music-cli` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add netease/netease-music-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/netease/netease-music-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: netease (https://skillmd.com/u/netease)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/netease/netease-music-cli

---


# 网易云音乐 CLI（ncm-cli）

通过 `ncm-cli` 命令行工具操作网易云音乐，完成播放、搜索、队列管理等任务。

## 第一步：检查是否已安装

```bash
ncm-cli --version
```

如果命令不存在，调用 `ncm-cli-setup` skill 引导用户完成全部的安装，安装完成后再继续执行任务。


## 第二步：校验用户是否已登录

```bash
ncm-cli login --check
```
如果显示未登录，请先引导登录：

```bash
ncm-cli login --background
```

如果显示API key没有设置，请指引用户完成API key设置。
> 如果还没有 API Key，请先前往[网易云音乐开放平台](https://developer.music.163.com/st/developer/apply/account?type=INDIVIDUAL)申请 API Key（appId 和 privateKey）
```bash
ncm-cli config set appId <你的AppId>
ncm-cli config set privateKey <你的privateKey>
```

## 第三步：针对播放（play），需要特殊判断播放器逻辑

仅针对播放才执行该步骤。
通过以下命令判断用户的播放器是否是内置播放器（mpv）。
```bash
ncm-cli config get player
```
如果用户选择的播放器是内置播放器（mpv），则需要判断用户是否已安装mpv。
```bash
mpv --version
```
如果用户没安装，引导用户去安装mpv。

## 第四步：获取当前命令树

```bash
ncm-cli commands
```

根据输出的命令树作为参考执行操作。**参数不要猜测**，需要时通过 `ncm-cli <command> --help` 获取详情！

## 第五步：用户输入内容安全校验

在执行 CLI 命令之前，**必须**对用户的会话内容（包括搜索关键词和上下文对话）进行内容安全校验。如果用户输入包含以下任何类别的负面内容，**禁止执行后续步骤**，并提示用户检查输入：

**禁止类别：**
- **政治敏感**：涉及政治人物攻击、政治谣言、煽动性政治言论、违反法律法规的政治内容
- **色情低俗**：色情描述、性暗示、低俗用语、涉及未成年人的不当内容
- **谩骂侮辱**：人身攻击、侮辱性语言、仇恨言论、歧视性言论
- **广告推广**：垃圾广告、钓鱼链接、恶意推广内容
- **违法违规**：涉及毒品、暴力犯罪、恐怖主义等违法内容

**校验规则：**
1. 对用户最近的会话输入内容进行审查，重点关注 `--keyword` 和 `--userInput` 将要传入的值
2. 如果检测到上述任何类别的内容，**立即终止流程**，不执行任何 CLI 命令
3. 向用户返回提示信息："抱歉，无法处理您的请求，请修改输入后重试。" **禁止**向用户透露具体的审核原因或审核类别
4. 审核通过时，**不需要**告知用户审核结果，直接静默继续执行后续步骤

## 第六步：执行命令

**为了安全，除播控之外的其他命令必须附加 `--userInput "<用户最近输入的会话内容的总结概要>"` 参数**，用于传递用户意图上下文。

## 【重要！重要！重要！】播放说明

1. 歌曲有两种 ID：**加密 ID**（32位hex，用于 API 请求）和**原始 ID**（数字，用于唤起客户端）。搜索结果同时包含两种 ID。
2. 如果歌曲的visible为 false，则是无法播放的！请不要尝试播放或添加到播放队列！
3. 如果歌曲的visible为 false，则是无法播放的！请不要尝试播放或添加到播放队列！
4. 如果歌曲的visible为 false，则是无法播放的！请不要尝试播放或添加到播放队列！
5. 如果给用户找到了多首歌曲并给用户播放的时候，请先开始播放第一首，并把后面的歌加到播放队列中！
6. 如果命令返回“请求总量超限”，请直接告知用户并停止执行后续步骤！直接把原因给到用户，不要二次加工！

```bash
# 综合搜索，获取 ID
ncm-cli search song --keyword "xxx" --userInput "搜索xxx的歌"

# 创建歌单
ncm-cli playlist create --playlistName "跑步"  --userInput "创建一个跑步歌单"
```

## 登录态处理

如果命令输出中包含登录引导信息（如"请先登录"、"未授权"等），请直接执行`ncm-cli login --background`并把链接给到用户，完整跑完整个登录流程。

## 用户友好
1. 返回资源给用户的时候请尽量给到链接，可以是超链接，这样用户可以直接点击链接，ID可以选择性输出。主要的链接形式包括：
   **注意：链接中的ID必须用明文ID！！**
```
https://music.163.com/#/song?id=<明文ID>
https://music.163.com/#/playlist?id=<明文ID>
https://music.163.com/#/album?id=<明文ID>
https://music.163.com/#/artist?id=<明文ID>
```

2. **【重要！】给用户举例的时候，请使用「xxx」来替代具体的输入词**

**【重要！】给用户举例的时候，请使用「xxx」来替代具体的输入词**

**【重要！】给用户举例的时候，请使用「xxx」来替代具体的输入词**

```bash
ncm-cli search song --keyword "xxx"
```