[Report] Windows 环境 + TUI 场景下多个核心功能失效的完整调查报告

[Ch1ronWang]

问题概述

以下问题在 Windows 环境下通过 Claude Code + ncm-cli 使用时陆续发现，经过完整的链路追踪和社区 Issue 调研，确认为 ncm-cli 本身的 bug，而非配置问题。

---

问题 1：Windows 下 play 命令 mpv 无法启动（关键）

严重级别： 🔴 核心功能完全失效

现象：

• 执行 ncm-cli play <song> 返回 exit 0，但 mpv 进程未启动
• 播放状态始终为 stopped
• 官方 Issue [ncm-cli] Windows: play command fails without TUI - mpv not spawned #5（2026/03/28 报告）至今 2 个月无官方回复

根因分析：
根据 Issue #10 的描述，play 命令触发的是后台守护进程（daemon）模式，该模式在 Windows 无 TUI 时会超时 3s 后退出——这正是 mpv 不启动的根本原因。

Workaround（目前唯一可行的方式）：

ncm-cli tui  # 启动 TUI 常驻
# 然后在 TUI 运行时用 queue add 添加歌曲
ncm-cli queue add --encrypted-id <id> --original-id <id>

但这个 workaround 也有缺陷：

• next 命令在队列有历史内容时会跳过队首新加入的歌曲
• TUI 运行后 play 命令会被拦截，必须用 queue add

复现环境：

• OS: Windows 11
• ncm-cli: v0.1.3
• mpv: 已安装（PATH 中可用）
• Node.js: >=18

---

问题 2：VIP 账号的 Original tracks 返回 visible:false

严重级别： 🔴 核心功能失效

现象：

• 客户端（App/Web）能正常播放的歌曲
• ncm-cli 搜索结果返回 visible: false、playFlag: false
• 即使账号有黑胶 VIP 也无法播放
• 相关 Issue: Original tracks searchable but returned as visible:false / unaddable even when VIP is recognized #3、Bug: ncm-cli API版权判断与App不一致 #6、客户端能够播放的歌曲为什么在ncm-cli里播放不了 #7（均为 Open，零官方回复）

复现示例：

• 鷺巣詩郎 - Will of the Heart（BLEACH OST，originalId: 504519）
• 多个用户报告华语歌曲也有同样问题

错误日志示例（来自 Issue #3）：

[_fetchUrl] 获取失败 BD3380105202D286B3B3D02596446ACC: 该歌曲暂无音源或暂无播放权限
已跳过：BD3380105202D286B3B3D02596446ACC（获取链接失败）

---

问题 3：play --song 后台播放 daemon 无响应（3s 超时）

严重级别： 🔴 核心功能失效

现象：

• 使用 play --song 命令时，后台 daemon 3 秒无响应后退出
• 这个问题独立于 Windows/mpv 问题存在
• 相关 Issue: [play --song] 后台播放失败: daemon 无响应（3s 超时 #10（2026/04/09，5 小时前有人跟帖确认同样的问题）

备注：
这个问题可能是所有播放问题的共同根因——无论是 Windows + mpv 还是其他平台 + daemon 模式，都是 play 命令的守护进程模式有问题。

---

问题 4：TUI 队列逻辑缺陷

严重级别： 🟡 体验问题

现象：

• 在 TUI 运行时，queue add 添加的歌曲不一定会立即播放
• next 命令会从当前队列中跳转，而不是按顺序播放
• 新加入的歌曲可能被 next 跳过

---

项目活跃度观察

维度	数据
最新提交	2026/03/31（距今约 5 周）
Issue 响应	所有 11 个 Open Issue 零官方回复
PR 状态	PR #1 提交于 2026/03/23，至今 OPEN 未合并
新用户流量	每周都有新 Issue 提交，说明需求真实存在

---

建议优先级

1. P0（必须修复）：Issue [play --song] 后台播放失败: daemon 无响应（3s 超时 #10 的 play daemon 超时问题——这是所有播放问题的根因
2. P0（必须修复）：Windows + mpv 路径问题（Issue [ncm-cli] Windows: play command fails without TUI - mpv not spawned #5）——Windows 用户完全无法播放
3. P1（重要）：VIP 歌曲权限问题（Issue Original tracks searchable but returned as visible:false / unaddable even when VIP is recognized #3、Bug: ncm-cli API版权判断与App不一致 #6、客户端能够播放的歌曲为什么在ncm-cli里播放不了 #7）——影响核心听歌需求
4. P2（改进）：TUI 队列逻辑优化

---

复现方式

可以在任意 Windows + Node.js 18+ 环境快速复现：

npm install -g @music163/ncm-cli
ncm-cli configure  # 配置 API Key
ncm-cli login     # 完成登录
ncm-cli search song --keyword "鷺巣詩郎 Will of the Heart" --userInput "搜索"
ncm-cli play --song <encrypted-id>  # 观察 mpv 是否启动

---

Issue 由 Claude Code + ncm-cli 实际使用中编写，附完整复现路径和根因分析。