前言¶

在 DSH 里搭一个能听歌的浮窗界面，通常会先想到 ncm-player 系列。前几版有一个反复出现的问题：歌单里一旦混进下架或无版权的歌，播放器只弹出一句「播放出错(可能无版权或需会员)」，然后停在原地，需要手动点下一首。歌单越长、这类歌越多，手动次数就越多。

ncm-player5 是 doctorpancode 维护的派生版本，在 ncm-player4 1.3.1 基础上只做一处功能改动：检测到不可播放时自动跳过，继续播下一首。下面介绍它的定位、继承的能力、跳过逻辑和安装方式。

这是什么¶

一句话定位：DSH（DeepSeek Harness）的网易云音乐浮窗播放器，完整继承 ncm-player4，新增自动跳过不可播放歌曲。维护者 doctorpancode，分类为客户端插件。

上游是 WolfGenerals/ncm-player。README 把派生链写成一条完整的线性提交历史，并打了三个 tag：

upstream-1.2.0：上游 WolfGenerals/ncm-player@main 原样导入，18 个文件逐字节相同，作为 1.2.0 的公开参照点。
ncm-player4-v1.3.1：ncm-player4 1.3.1，相对 1.2.0 派生出点击窗口外收起、无操作自动退出、播放心跳、长按拖动、无声修复。
ncm-player5-v1.4.1：本插件当前版本，相对 1.3.1 的唯一功能改动是自动跳过，另加包名 scope 调整。

也就是说可以执行 git diff ncm-player4-v1.3.1 main，直接审本插件相对基线的全部改动。当前版本 1.4.1，包名 @doctor-pan-code/ncm-player5（早期沿用上游 @wolfgenerals/ scope，但该 scope 属于上游作者且本插件从未发布到 npm，故自 1.4.1 起改回投稿人自己的 scope），cordis 加载 id 仍是 ncm-player5。

继承自 ncm-player4 的能力¶

以下能力与 ncm-player4 1.3.1 一致，均为 README 列出的既有功能：

播放：播放/暂停、上一首/下一首、进度拖拽、音量与静音；顺序、单曲循环、随机三种模式。
发现：搜索单曲/歌单/专辑，热门歌单推荐；登录后可查看「我的」歌单与收藏的专辑。
歌词：逐行同步高亮、点击跳转、歌词翻译；迷你模式显示当前歌词，超长歌词横向滚动，字号可调。
队列：添加、移除、清空，自动持久化，重启后恢复队列、进度、播放模式、音量。
账号：网易云 App 扫码登录，或粘贴 Cookie。
浮窗：展开/迷你条/隐藏三种形态，均可拖拽，颜色跟随 DSH 皮肤主题。
设置：音质、歌词翻译、迷你歌词开关/滚动/字号、无操作自动退出、自动跳过不可播放的歌曲。

既有交互细节：点击播放窗口以外的区域会收起为迷你条；收起后 3 秒内无鼠标点击或移动，自动退出为右下角音符按钮，播放不中断；播放中该按钮随音乐低频鼓点跳动；右下角图标支持左键长按拖动，位置自动记住。

ncm-player5 的新增功能：自动跳过¶

跳过判定分两道关卡，主判据在地址获取阶段：

地址获取阶段（主判据）：host 半部调用 /api/song/enhance/player/url，网易云对不可播放的歌曲返回 url: null 且 code: -110。host 把这个信号透传给前端，songUrl 返回 { url, playable, reason, code }，并新增 songStatus op。当 playable === false 且 reason === 'copyright' 时判定为无版权/下架，直接跳过，不发起任何音频请求。
为了避免把「只是没有高音质」误判成「不能播」，songUrl 做了多档音质降级：请求码率 → 320k → 192k → 128k → 96k，某档拿不到地址时自动尝试更低码率，全部失败才算不可播。
播放出错阶段（兜底）：<audio> 的 error 事件里，先走原有的两条重试分支（Web Audio 接管后换新元素、CORS 兜底重载一次），只有重试也用尽，或错误码是 MEDIA_ERR_SRC_NOT_SUPPORTED(4) / MEDIA_ERR_DECODE(3)，才判定为不可播并跳过。

网络异常不算不可播：接口本身失败（超时/断网/解析失败）时按「未知」处理，不跳歌，只照旧弹提示。

跳过规则：

按当前播放模式推进。顺序模式走下一首，到队尾回到队首循环找可播放的；随机模式随机换一首并避开当前这首；单曲循环模式下遇到坏歌也会跳到下一首，避免一直重播同一首。
跳过时提示「已跳过《歌名》：无版权/已下架」，2.8 秒后自动消失。
防死循环：连续跳过次数达到队列长度（上限 30）仍没有一首能播时，停止播放并只提示一次「队列中没有可播放的歌曲」；队列只有 1 首坏歌时直接停止，不反复重试。
开关在设置页 → 播放 →「自动跳过不可播放的歌曲」，默认开启；关闭后行为与 ncm-player4 完全一致。
判定结果在 host 侧缓存 5 分钟，避免连跳时对同一首歌反复请求。

安装与启用¶

包名 @doctor-pan-code/ncm-player5，cordis 加载 id 为 ncm-player5。

注意：本插件与 ncm-player2/3/4 不能同时启用。host 半部都会注册 /ncm/api 前缀路由，同时启用会互相抢占，安装本插件时应停用 ncm-player4。

从 GitHub 安装：

dsh plugin add Doctor-Pan-code/ncm-player5

本地 / 手动安装（link 方式）与 profile 内其他本地插件一致。先把目录放到插件目录，例如 $DSH_HOME/plugins/ncm-player5，然后：

在 $DSH_HOME/profiles/<profile>/package.json 中声明依赖，并把包追加进 dsh.profile.bundles：

   "dependencies": { "@doctor-pan-code/ncm-player5": "link:C:/Users/<你>/.dsh/plugins/ncm-player5" }

在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 中追加加载项与停用项：

   - insert:
       - id: ncm-player5
         name: '@doctor-pan-code/ncm-player5'
   - id: ncm-player4
     disabled: true

完全退出并重启 DSH。

数据保存与升级兼容¶

登录态与播放队列存放在本机浏览器 localStorage，key 仍是 ncmply2-settings；右下角音符按钮位置 key 仍是 ncmply4-disc-pos。因此从 ncm-player4 升级到 ncm-player5 时，登录态、播放队列、各项设置、图标位置全部自动沿用，不需要重新登录或重新拖动图标。

ncm-player5 在 state 里新增一个字段 autoSkip（默认 true），整体 shape 如下：

{
  "account": { "cookie": "...", "uid": 123, "nickname": "..." },
  "state": {
    "queue": [ { "id": 1, "name": "...", "artists": "...", "album": "...", "cover": "...", "duration": 0 } ],
    "index": -1, "mode": "order", "vol": 0.8, "quality": 320000, "time": 0,
    "showTrans": true, "showMiniLrc": true, "miniLrcScroll": true, "miniLrcSize": 11,
    "autoExit": true, "autoSkip": true
  }
}

host 半部新增的 API¶

本插件在 host 半部新增两个 op，其余 search / playlistDetail / albumDetail / lyric / like / 登录相关 / saveState 等行为与 ncm-player4 完全一致。

op	入参	返回
`songUrl`	`{ id, br }`	`{ url, playable, reason, code }`；多个码率依次尝试，全部失败时 `url` 仍按旧行为返回 `song/media/outer/url` 兜底地址以兼容旧前端
`songStatus`	`{ id, br }`	`{ playable, reason, code, fee, freeTrial }`；纯查询，不返回地址，结果缓存 5 分钟

reason 取值：copyright（code -110，无版权/下架）、error（code -200）、unavailable（其它）、null（可播放或未知）。

适用场景与注意¶

适合想在 DSH 里挂一个网易云音乐浮窗、并且希望歌单尽量自动放完的人。插件依赖本机可用的 Node.js 运行时，以及可访问 music.163.com 的网络。登录 Cookie 只用于请求 music.163.com，不发送给任何第三方。收藏（点 ❤）受网易云账号风控影响，失败时会有提示，属正常现象。仅供个人学习使用，需遵守网易云音乐服务条款与当地法律法规。

几点注意：

VIP 专享歌曲在未登录或非会员时，网易云同样返回 -110，因此会被当作不可播放跳过；登录会员账号后这些歌可正常播放。
插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证（本插件为 MIT License）。
本仓库是社区衍生版本，与 DeepSeek / 幻方无官方从属关系。

小结¶

ncm-player5 没有重写播放器，而是在已成熟的 ncm-player4 基线上补上「遇到下架/无版权歌曲自动跳过」这一个长期痛点。它把跳过判据、音质降级、按模式推进和防死循环处理得比较清楚，同时保留了 ncm-player4 的浮窗交互与全部既有功能。目录页与仓库如下：

目录页：https://www.skillhub.cn/plugins/doctorpancode/ncm-player5
GitHub：https://github.com/doctorpancode/ncm-player5

ncm-player5：DSH 里的网易云音乐浮窗播放器，核心是自动跳过不可播放歌曲

前言¶

这是什么¶

继承自 ncm-player4 的能力¶

ncm-player5 的新增功能：自动跳过¶

安装与启用¶

数据保存与升级兼容¶

host 半部新增的 API¶

适用场景与注意¶

小结¶

精选优惠券

ncm-player5：DSH 里的网易云音乐浮窗播放器，核心是自动跳过不可播放歌曲

前言¶

这是什么¶

继承自 ncm-player4 的能力¶

ncm-player5 的新增功能：自动跳过¶

安装与启用¶

数据保存与升级兼容¶

host 半部新增的 API¶

适用场景与注意¶

小结¶

精选优惠券

相关文章