前言¶
在 DSH 里长时间挂着对话界面时，如果还想听网易云歌单，常见做法是单独开浏览器或客户端，窗口之间来回切换。ncm-player 系列把播放器做成客户端插件，浮在界面一角，歌单、歌词、队列和登录都留在 DSH 里完成。ncm-player4 已经具备完整浮窗交互，但遇到下架或无版权曲目时只会提示错误并停住，长歌单里坏歌一多就要反复手动点下一首。ncm-player5 在完整保留 ncm-player4 能力的前提下，只在这一处做了增强：判定不可播后自动切到下一首。下面介绍插件定位、能力与安装方式。
这是什么¶
ncm-player5 是 DSH 客户端插件，维护者为 Doctor-Pan-code，npm 包名 @wolfgenerals/ncm-player5，当前版本 1.4.0，许可证 MIT。实现上基于 WolfGenerals/ncm-player 的 ncm-player4 1.3.1 原样派生，自动跳过等改动在 Doctor-Pan-code/ncm-player5 仓库维护。
插件通过 host 半部对接 music.163.com API，在 Web 客户端注入浮窗 UI，颜色跟随 DSH 皮肤主题。登录 Cookie 仅用于请求网易云，README 说明不发送给第三方。
继承自 ncm-player4 的能力¶
除自动跳过外，行为与 ncm-player4 1.3.1 一致，主要包括：
播放与队列：播放/暂停、上一首/下一首、进度与音量；顺序、单曲循环、随机三种模式；队列增删与清空，状态持久化，重启后恢复队列、进度、模式与音量。
发现与账号：搜索单曲/歌单/专辑、热门歌单；App 扫码或粘贴 Cookie 登录；登录后可看「我的」歌单与收藏专辑。
歌词：逐行高亮、点击跳转、歌词翻译；迷你模式显示当前行，超长横向滚动，字号可调。
浮窗形态（自 ncm-player2～4 逐代叠加）：
- 点击播放窗口外任意区域，窗口收起为迷你条。
- 迷你条状态下 3 秒内无鼠标点击或移动，自动触发退出，界面变为右下角音符按钮，播放不中断。
- 隐藏为音符按钮且仍在播放时，图标随音乐低频节奏跳动。
- 右下角图标支持左键长按拖动，位置会记住。
设置：音质、歌词翻译、迷你歌词、无操作自动退出等；ncm-player5 在此基础上增加「自动跳过不可播放的歌曲」（默认开启）。
核心新增：自动跳过不可播歌曲¶
背景¶
ncm-player4 遇到下架或无版权时弹出「播放出错(可能无版权或需会员)」后停止，需用户手动下一首。ncm-player5 在可判定为无版权/下架时自动推进队列。
判定方式¶
第一道（主判据）：host 调用 /api/song/enhance/player/url。不可播时网易云返回 url: null 且 code: -110。host 向 client 透传 songUrl 的 { url, playable, reason, code }，并新增 songStatus 查询 op。当 playable === false 且 reason === 'copyright' 时直接跳过，不发起音频请求。同时做多档音质降级（设定码率 → 320k → 192k → 128k → 96k），避免「只是没有高音质」被误判为不能播。
第二道（兜底）：<audio> 的 error 事件在原有 Web Audio / CORS 重试用尽后，或错误为 MEDIA_ERR_SRC_NOT_SUPPORTED(4) / MEDIA_ERR_DECODE(3) 时，才视为不可播并跳过。
网络异常不算不可播：接口超时、断网、解析失败按「未知」处理，仍弹提示，不会因断网整表跳歌。
跳过规则与开关¶
- 顺序模式：下一首，到队尾回到队首继续找可播项；随机模式：随机换一首（避开当前）；单曲循环遇到坏歌也会跳到下一首，避免死循环同一首。
- 跳过时提示「已跳过《歌名》：无版权/已下架」，约 2.8 秒后消失。
- 防死循环：连续跳过次数达到队列长度（上限 30）仍无可播项时停止，并提示「队列中没有可播放的歌曲」；队列仅一首坏歌时直接停止。
- 设置页 → 播放 →「自动跳过不可播放的歌曲」，默认开启；关闭后与 ncm-player4 行为一致。
- host 侧判定结果缓存 5 分钟。
VIP 专享曲在未登录或非会员时同样可能得到 -110，会被跳过；登录会员账号后可正常播放。收藏（❤）受账号风控影响，失败时会有提示，属 README 所述正常现象。
安装与启用¶
与 ncm-player2/3/4 不能同时启用：各版本的 host 都注册 /ncm/api 前缀，并存会路由冲突。安装 ncm-player5 时应停用 ncm-player4。
从 GitHub 安装（README 原文命令）：
dsh plugin add Doctor-Pan-code/ncm-player5
cordis 加载 id 为 ncm-player5。若从 ncm-player4 迁移，可在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 中为 ncm-player4 设置 disabled: true，并重启 DSH。
本地 link 安装步骤见仓库 README：将目录放到 $DSH_HOME/plugins/ncm-player5，在 profile 的 package.json 与 cordis.patch.yml 中声明 @wolfgenerals/ncm-player5 并禁用 ncm-player4，然后完全退出并重启 DSH。
数据与升级¶
登录态与播放队列保存在本机浏览器 localStorage，key 仍为 ncmply2-settings；音符按钮位置 key 仍为 ncmply4-disc-pos。从 ncm-player4 升级到 ncm-player5 时，登录、队列、设置与图标位置可沿用，无需重新登录或拖图标。
state 中新增 autoSkip（默认 true），其余字段与 ncm-player4 一致，例如：
{
"state": {
"queue": [],
"index": -1,
"mode": "order",
"vol": 0.8,
"quality": 320000,
"autoExit": true,
"autoSkip": true
}
}
host 半部相对 ncm-player4 新增的 op 包括 songUrl（含 playable/reason/code）与 songStatus（纯查询，缓存 5 分钟）；其余 op 行为不变。
典型用法¶
安装并重启 DSH 后，在客户端界面使用浮窗入口（与 ncm-player4 相同交互）：搜索或打开歌单加入队列，扫码或 Cookie 登录后播放「我的」内容；需要时可展开完整播放器看歌词与队列，点击窗外收起迷你条，无操作后缩到右下角音符按钮继续听。
遇到不可播曲目且开关开启时，播放器会自动下一首并短暂提示歌名；若希望与旧版一样停在错误处，在设置里关闭「自动跳过不可播放的歌曲」即可。
适用场景与注意¶
适合在 DSH 对话界面旁常驻听网易云、又不想单独开浏览器标签的用户。插件依赖本机 Node.js 与可访问 music.163.com 的网络；README 注明仅供个人学习，需遵守网易云服务条款与当地法规。
DSH 生态是「一切皆插件」；社区目录 SkillHub 上的 ncm-player5 页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系。安装前建议自行查看源码与 MIT 许可证；插件以当前 DSH 进程权限运行，Cookie 等敏感数据存于本机 localStorage，使用前应确认是否符合你的安全策略。
结尾¶
ncm-player5 在 ncm-player4 浮窗体验不变的前提下，用 host 可播性判定与 client 双阶段兜底，把「下架/无版权停住」改成可配置的自动跳歌，并保留网络异常时不误跳的保护。更多信息见 GitHub：Doctor-Pan-code/ncm-player5 与 SkillHub 目录页。
