Skip to content

Update ncm-converter to v2.4.0: 修复 files 指令 schema + 右下角完成提示窗 - #719

Merged
lzx8589561 merged 1 commit into
ZToolsCenter:mainfrom
akahoz94:plugin/ncm-converter-v2.4.0
Nov 4, 2026
Merged

lzx8589561 merged 1 commit into
ZToolsCenter:mainfrom
akahoz94:plugin/ncm-converter-v2.4.0

Conversation

@akahoz94

@akahoz94 akahoz94 commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

修复 ncm-converter v2.3.0 导致的插件失效,并新增完成提示窗

一、为什么必须升到 2.4.0(版本号不能往回走)

插件市场的版本号直接取自 plugin.json(scripts/build-plugins.js 用它给 zip 命名 →
scripts/generate-plugins-json.js 用它写进 plugins.json),ZTools 客户端用语义化版本比较
(comparePluginVersions,2.4.0 > 2.3.0)决定是否推送更新。

线上当前版本是 2.3.0。如果这次沿用 2.2.1 推上去,市场清单会从 2.3.0 降到 2.2.1,
已经装了 2.3.0 的用户永远收不到修复,这就是「版本号往下降」。

所以本次版本号提到 2.4.0(> 2.3.0),保证推送链路通畅。规则:版本号只能递增。

二、v2.3.0 为什么会让插件「用不了」

v2.3.0 把 files 指令的扩展名从平铺改成了嵌进 match 对象:

// v2.3.0(坏的)
{
  "type": "files",
  "label": "音频转 MP3",
  "fileType": "file",
  "match": { "type": "files", "fileType": "file", "extensions": [ "ncm", "wav", ... ] }
}

但 ZTools 客户端的解析逻辑(out/main/chunks/searchWorker.js)是:

// 扩展名读的是平铺在指令对象上的 cmd.extensions
if (Array.isArray(cmd.extensions) && cmd.extensions.length > 0 && !file.isDirectory) { ... }

// 而 cmd.match 被当成【正则字符串】处理
function parseMatchPattern(pattern, options = {}) {
  const slashMatch = pattern.match(/^\/(.*)\/([dgimsuvy]*)$/);   // ← 对象没有 .match 方法
  ...
}

// 编译规则时还会做字段类型校验
validateRuleFields(rule, { match: "string", extensions: "strings", ... });
// → 抛 InvalidContextRuleError: 字段 match 应为 string

因此 v2.3.0 有两个后果:

  1. 规则编译直接抛错(字段 match 应为 string),type:files 指令注册失败 → 插件整体用不了。
  2. 扩展名过滤同时失效(cmd.extensions 变成了 undefined),任意文件都能触发该指令。

本次改回 v2.2.1 的平铺写法(已被证实可用):

// v2.4.0(好的)
{
  "type": "files",
  "label": "音频转 MP3",
  "fileType": "file",
  "extensions": [ "ncm", "wav", "wave", "ogg", ... ]
}

补充:想用 match 做文件名匹配时,它必须是正则字符串(如 "/\\.ncm$/"),不是嵌套对象。

三、新增:转换完成后的右下角提示窗 + 提示音

对齐「音频提取」插件的反馈方式,三条通道互为兜底:

  • 右下角自毁小窗:createBrowserWindow 弹出无边框、置顶、不占任务栏、不抢焦点的小窗,
    列出每个文件的成功/失败(失败项标红),5 秒后自动关闭。可用 dbStorage 的 toast_corner
    切成左下角(br / bl)。
  • 提示音:shellBeep()。
  • Windows 通知中心原生 toast:PowerShell WinRT 发送,横幅消失后仍可在通知中心查历史。

关键实现细节:小窗属于插件进程,宿主要等 enter 的 Promise resolve 后才退出插件,
所以 handle() 里 dwell 5.5 秒再返回,否则窗口会被一起销毁、用户根本看不到提示。

四、保留 v2.3.0 的健壮性改进

  • 输出目录不可写(网盘 / 只读目录)自动回退桌面,避免整单失败
  • flac 等多轨格式加 -map 0:a:0,跳过封面流导致的转码失败
  • 错误提示保留 ffmpeg 原始 stderr,不再过滤掉中文错误
  • 转换前提示「开始转换 N 个文件…」,避免大文件转码时看起来像没反应
  • 诊断日志写 %TEMP%/ncm-converter-debug.log

五、验证

用 ZTools 客户端的真实解析逻辑(逐字抄自 searchWorker.js)跑新旧两份 plugin.json:

===== 旧版 2.3.0(对照组,预期失败)=====
  ✗ 编译 rule (type=files) → InvalidContextRuleError: 字段 match 应为 string
  ✗ 拒绝 .txt 文件 → 扩展名过滤失效
===== 新版 2.4.0(本次提交)=====
  ✓ 编译 rule (type=files) → ok
  ✓ 匹配 .ncm / .flac 文件 → 命中
  ✓ 拒绝 .txt 文件 / 目录 → 已拒绝

全链路自检(真实 ffmpeg):

✓ wav → mp3            输出为 mp3、无封面流
✓ 重名避让             测试音频 (1).mp3
✓ flac(带封面流)→ mp3
✓ 损坏的 .ncm 报错      Not netease protected file
✓ toast 窗口            x=1524 y=946 380x118(右下角)
✓ 弹窗位置可配          br / bl
✓ 端到端 handle()       beep=1 toast=1 dwell=5657ms

六、影响面

只改 plugins/ncm-converter/,不涉及其他插件,也不改动任何 workflow。
合并后 build-and-release.yml 会自动打包发布 ncm-converter-2.4.0.zip,
并把市场清单里的版本更新为 2.4.0。

七、关于 CHANGELOG.md(未包含在本 PR 内)

plugins/ncm-converter/CHANGELOG.md 没有放进这个 PR,原因是它在上游是在本分支基线之后
才新增的,两边都算「新增」会导致 add/add 冲突(GitHub 标记为 CONFLICTING)。
为保证本 PR 零冲突、可以直接合并,这里只提交了 4 个文件。

CHANGELOG.md 需要补的 2.4.0 条目内容如下,合并后追加即可(或后续单独提一个 PR):

## 2.4.0 - 2026-10-31

- **修复 2.3.0 引入的致命问题**:plugin.json 里 `files` 指令把 `extensions` 错误地嵌进了 `match` 对象。
  ZTools 客户端读的是 **平铺在指令对象上的 `cmd.extensions`**,而 `cmd.match` 只接受**正则字符串**;
  嵌套对象会让规则编译抛 `字段 match 应为 string`,指令整体失效(插件表现为「用不了」)。
  同时扩展名过滤也随之失效(任意文件都能触发)。已改回 2.2.1 的平铺写法并验证通过。
- 转换完成后新增**右下角结果提示窗**(自毁小窗)并播放**提示音**,与「音频提取」插件的反馈方式一致。
- 版本号从 2.3.0 提到 **2.4.0**:插件市场的版本号直接取自 plugin.json,若沿用 2.2.1 会低于线上版本,
  客户端按语义化版本比较后不会推送更新(版本号「往下降」)。同理,版本号只能递增,不能回退。

@akahoz94
akahoz94 force-pushed the plugin/ncm-converter-v2.4.0 branch 2 times, most recently from 1d3a0b3 to 2c96519 Compare October 30, 2026 18:20
@akahoz94
akahoz94 force-pushed the plugin/ncm-converter-v2.4.0 branch from 2c96519 to f593a5c Compare October 30, 2026 18:22
@lzx8589561
lzx8589561 merged commit 3d888f9 into ZToolsCenter:main Nov 4, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants