Back to Details

netease-music-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

网易云音乐 CLI（ncm-cli）

NetEase Cloud Music CLI (ncm-cli)

通过 
ncm-cli
命令行工具操作网易云音乐，完成播放、搜索、队列管理等任务。
Operate NetEase Cloud Music via the 
ncm-cli
command-line tool to complete tasks such as playback, search, queue management, etc.

第一步：检查是否已安装

Step 1: Check if installed

bash
ncm-cli --version
如果命令不存在，调用 
ncm-cli-setup
skill 引导用户完成全部的安装，安装完成后再继续执行任务。
bash
ncm-cli --version
If the command does not exist, call the 
ncm-cli-setup
skill to guide users through the complete installation process, then proceed with the task after installation is completed.

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

Step 2: Verify user login status

bash
ncm-cli login --check
如果显示未登录，请先引导登录：
bash
ncm-cli login --background
如果显示API key没有设置，请指引用户完成API key设置。
如果还没有 API Key，请先前往网易云音乐开放平台申请 API Key（appId 和 privateKey）
bash
ncm-cli config set appId <你的AppId>
ncm-cli config set privateKey <你的privateKey>
bash
ncm-cli login --check
If it shows not logged in, guide the user to log in first:
bash
ncm-cli login --background
If it shows the API key is not set, guide the user to complete the API key setup.
If you don't have an API Key yet, please first apply for one on the NetEase Cloud Music Open Platform (appId and privateKey)
bash
ncm-cli config set appId <Your AppId>
ncm-cli config set privateKey <Your privateKey>

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

Step 3: Special player logic judgment for playback (play)

仅针对播放才执行该步骤。 通过以下命令判断用户的播放器是否是内置播放器（mpv）。
bash
ncm-cli config get player
如果用户选择的播放器是内置播放器（mpv），则需要判断用户是否已安装mpv。
bash
mpv --version
如果用户没安装，引导用户去安装mpv。
This step is only for playback operations. Determine if the user's player is the built-in player (mpv) using the following command.
bash
ncm-cli config get player
If the user's selected player is the built-in player (mpv), check if mpv is installed.
bash
mpv --version
If not installed, guide the user to install mpv.

第四步：获取当前命令树

Step 4: Get current command tree

bash
ncm-cli commands
根据输出的命令树作为参考执行操作。参数不要猜测，需要时通过 
ncm-cli <command> --help
获取详情！
bash
ncm-cli commands
Use the output command tree as a reference to execute operations. Do not guess parameters; use 
ncm-cli <command> --help
to get details when needed!

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

Step 5: Content security check for user input

在执行 CLI 命令之前，必须对用户的会话内容（包括搜索关键词和上下文对话）进行内容安全校验。如果用户输入包含以下任何类别的负面内容，禁止执行后续步骤，并提示用户检查输入：
禁止类别：
  • 政治敏感：涉及政治人物攻击、政治谣言、煽动性政治言论、违反法律法规的政治内容
  • 色情低俗：色情描述、性暗示、低俗用语、涉及未成年人的不当内容
  • 谩骂侮辱：人身攻击、侮辱性语言、仇恨言论、歧视性言论
  • 广告推广：垃圾广告、钓鱼链接、恶意推广内容
  • 违法违规：涉及毒品、暴力犯罪、恐怖主义等违法内容
校验规则：
  1. 对用户最近的会话输入内容进行审查，重点关注 
    --keyword
    和 
    --userInput
    将要传入的值
  2. 如果检测到上述任何类别的内容，立即终止流程，不执行任何 CLI 命令
  3. 向用户返回提示信息："抱歉，无法处理您的请求，请修改输入后重试。" 禁止向用户透露具体的审核原因或审核类别
  4. 审核通过时，不需要告知用户审核结果，直接静默继续执行后续步骤
Before executing CLI commands, must perform content security checks on the user's session content (including search keywords and context dialogues). If the user's input contains any of the following negative content categories, stop subsequent steps immediately and prompt the user to check their input:
Prohibited categories:
  • Politically sensitive: Involves attacks on political figures, political rumors, inciting political remarks, political content that violates laws and regulations
  • Pornographic and vulgar: Pornographic descriptions, sexual innuendos, vulgar language, inappropriate content involving minors
  • Insults and abuse: Personal attacks, insulting language, hate speech, discriminatory remarks
  • Advertising and promotion: Spam ads, phishing links, malicious promotional content
  • Illegal and non-compliant: Content involving drugs, violent crimes, terrorism, etc.
Check rules:
  1. Review the user's recent session input content, focusing on the values to be passed in 
    --keyword
    and 
    --userInput
  2. If any of the above categories are detected, terminate the process immediately and do not execute any CLI commands
  3. Return the prompt message to the user: "Sorry, I cannot process your request. Please modify your input and try again." Do not disclose the specific review reason or category to the user
  4. If the review passes, do not inform the user of the review result; continue with subsequent steps silently

第六步：执行命令

Step 6: Execute commands

为了安全，除播控之外的其他命令必须附加 
--userInput "<用户最近输入的会话内容的总结概要>"
参数，用于传递用户意图上下文。
For security reasons, all commands except playback control must include the 
--userInput "<Summary of the user's recent session input>"
parameter to pass the user's intent context.

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

[Important! Important! Important!] Playback Instructions

  1. 歌曲有两种 ID：加密 ID（32位hex，用于 API 请求）和原始 ID（数字，用于唤起客户端）。搜索结果同时包含两种 ID。
  2. 如果歌曲的visible为 false，则是无法播放的！请不要尝试播放或添加到播放队列！
  3. 如果歌曲的visible为 false，则是无法播放的！请不要尝试播放或添加到播放队列！
  4. 如果歌曲的visible为 false，则是无法播放的！请不要尝试播放或添加到播放队列！
  5. 如果给用户找到了多首歌曲并给用户播放的时候，请先开始播放第一首，并把后面的歌加到播放队列中！
  6. 如果命令返回“请求总量超限”，请直接告知用户并停止执行后续步骤！直接把原因给到用户，不要二次加工！
bash
undefined
  1. Songs have two types of IDs: Encrypted ID (32-bit hex, used for API requests) and Original ID (numeric, used to invoke the client). Search results include both IDs.
  2. If a song's visible is false, it cannot be played! Do not attempt to play it or add it to the playback queue!
  3. If a song's visible is false, it cannot be played! Do not attempt to play it or add it to the playback queue!
  4. If a song's visible is false, it cannot be played! Do not attempt to play it or add it to the playback queue!
  5. If multiple songs are found for the user and are to be played, start playing the first song first and add the subsequent songs to the playback queue!
  6. If the command returns "Request quota exceeded", directly inform the user and stop subsequent steps! Provide the reason directly without secondary processing!
bash
undefined

综合搜索，获取 ID

Comprehensive search to get IDs

ncm-cli search song --keyword "xxx" --userInput "搜索xxx的歌"
ncm-cli search song --keyword "xxx" --userInput "Search for songs of xxx"

创建歌单

Create playlist

ncm-cli playlist create --playlistName "跑步" --userInput "创建一个跑步歌单"
undefined
ncm-cli playlist create --playlistName "Running" --userInput "Create a running playlist"
undefined

登录态处理

Login status handling

如果命令输出中包含登录引导信息（如"请先登录"、"未授权"等），请直接执行
ncm-cli login --background
并把链接给到用户，完整跑完整个登录流程。
If the command output contains login guidance information (such as "Please log in first", "Unauthorized", etc.), directly execute 
ncm-cli login --background
and provide the link to the user to complete the entire login process.

用户友好

User-friendliness

  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>
  1. 【重要！】给用户举例的时候，请使用「xxx」来替代具体的输入词
【重要！】给用户举例的时候，请使用「xxx」来替代具体的输入词
【重要！】给用户举例的时候，请使用「xxx」来替代具体的输入词
bash
ncm-cli search song --keyword "xxx"
  1. When returning resources to the user, try to provide links, preferably hyperlinks, so that users can click directly. IDs can be optionally output. The main link formats include: Note: The ID in the link must be the plaintext ID!!
https://music.163.com/#/song?id=<Plaintext ID>
https://music.163.com/#/playlist?id=<Plaintext ID>
https://music.163.com/#/album?id=<Plaintext ID>
https://music.163.com/#/artist?id=<Plaintext ID>
  1. [Important!] When giving examples to users, use「xxx」to replace specific input words
[Important!] When giving examples to users, use「xxx」to replace specific input words
[Important!] When giving examples to users, use「xxx」to replace specific input words
bash
ncm-cli search song --keyword "xxx"