@chenhao6682108/dsh-skill-musicbee 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -47,6 +47,27 @@ party playlist and it loads the skill itself.
47
47
 
48
48
  Uninstall with `dsh plugin --profile web remove @chenhao6682108/dsh-skill-musicbee`.
49
49
 
50
+ ## First run
51
+
52
+ Do not guess paths — ask the machine:
53
+
54
+ ```bat
55
+ scripts\mb-doctor.cmd :: MusicBee exe, library, Playlists, Python
56
+ scripts\mb-doctor.cmd -StyleRoot "D:\music\1blues" :: also lists the style subfolders
57
+ scripts\mb-doctor.cmd -Json :: machine-readable
58
+ ```
59
+
60
+ It reads `<ENV_LibPath>` out of `%APPDATA%\MusicBee\MusicBee3Settings.ini`, so the library and the
61
+ `Playlists` folder come out right with no configuration, and every line says which party-config field
62
+ it feeds (`playlists_dir`, `library_root`, `python` → `MUSICBEE_PY`).
63
+
64
+ Then copy `references/party-2026-11-20-final.json`, change only the path fields and `library_root`,
65
+ and keep the rule fields (`req`, `ending`, `body`, `share`, `long_sec`, `no_repeat_style`,
66
+ `ballroom_gap_max`) as they are. `party_build.py -h` lists every accepted field, and each failure
67
+ message names the exact next command to run. `party_build.py` also **refuses to write a playlist**
68
+ until `mb-doctor.cmd -Accept` has recorded the confirmed paths in `~/.musicbee-skill/paths.json`,
69
+ and it rejects a config whose `playlists_dir` / `library_root` disagree with that record.
70
+
50
71
  ## How it works
51
72
 
52
73
  `lib/index.js` is a dependency-free Cordis function plugin. On `apply()` it reads the packaged
package/README.zh.md CHANGED
@@ -41,6 +41,25 @@ dsh plugin --profile web add . # 从本地 c
41
41
 
42
42
  卸载:`dsh plugin --profile web remove @chenhao6682108/dsh-skill-musicbee`。
43
43
 
44
+ ## 首次使用
45
+
46
+ 别猜路径,让机器自己报:
47
+
48
+ ```bat
49
+ scripts\mb-doctor.cmd :: MusicBee 可执行文件、库、Playlists、Python
50
+ scripts\mb-doctor.cmd -StyleRoot "D:\曲库\1blues" :: 顺便列出风格子目录名
51
+ scripts\mb-doctor.cmd -Json :: 给程序读的 JSON
52
+ ```
53
+
54
+ 它从 `%APPDATA%\MusicBee\MusicBee3Settings.ini` 的 `<ENV_LibPath>` 解析库路径,所以库和 `Playlists` 目录零配置就能对上;
55
+ 每行都标明了喂给配置的哪个字段(`playlists_dir`、`library_root`、`python` → 环境变量 `MUSICBEE_PY`)。
56
+
57
+ 然后把 `references/party-2026-11-20-final.json` 复制一份,只改路径字段和 `library_root`,
58
+ 规则字段(`req`、`ending`、`body`、`share`、`long_sec`、`no_repeat_style`、`ballroom_gap_max`)原样保留。
59
+ `party_build.py -h` 会列出所有可用字段;每条报错都会写清楚下一步该跑什么命令。
60
+ 另外,**路径未确认前 `party_build.py` 拒绝写歌单**——`mb-doctor.cmd -Accept` 会把确认结果记到 `~/.musicbee-skill/paths.json`,
61
+ 配置里的 `playlists_dir` / `library_root` 与记录不一致时同样拒绝,并打印两个值。
62
+
44
63
  ## 实现方式
45
64
 
46
65
  `lib/index.js` 是一个零依赖的 Cordis 函数式插件:`apply()` 读取包内 `skills/musicbee/SKILL.md`,解析 frontmatter,
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@chenhao6682108/dsh-skill-musicbee",
3
- "version": "0.1.0",
4
- "description": "MusicBee playlist and library toolkit as a DSH skill plugin: scan a music library into a JSON index, write ID3/Vorbis/MP4 tags, build validated dsh (3dj) party playlists, rewrite and remap .mbp playlist files, and make MusicBee re-read them. Windows and a local MusicBee install required; no network access and no audio data is modified.",
3
+ "version": "0.1.2",
4
+ "description": "MusicBee playlist and library toolkit as a DSH skill plugin: scan a music library into a JSON index, write ID3/Vorbis/MP4 tags, build validated dsh (3dj) party playlists, rewrite and remap .mbp playlist files, and make MusicBee re-read them. Ships mb-doctor to auto-detect the MusicBee library, Playlists folder and Python. Windows and a local MusicBee install required; no network access and no audio data is modified.",
5
5
  "keywords": [
6
6
  "deepseek",
7
7
  "harness",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: musicbee
3
- description: 🎵 MusicBee 歌单与曲库工具 — 扫曲库建索引、把网易云歌单导入本地库(写标签)并刷新 MusicBee、排整场舞会歌单、管理 .mbp 歌单文件。① 扫描:音乐目录 → JSON 索引(标题/艺人/专辑/风格/年代/BPM/时长),可导出 CSV;② 导入:网易云歌单下载 → 写 ID3 标签(标题/演出者/专辑)→ 生成 .mbp 进 MusicBee 分组,含 Rescan 刷新实测;③ 标签:可写标签(批量/单文件),写后一条命令自动刷新 MusicBee 库;④ 舞会整场歌单:风格配额/时长占比/能量与 ballroom 连排上限/结尾序列/跨歌单去重/同类型不连排/ballroom 间距上限一次校验,写 3dj 分组 .mbp + 逐曲理由说明 md(party_build.py);⑤ 歌单文件:改完 .mbp 一键重启生效,曲库整理后按路径映射批量重写/清理引用。不联网、不改音频数据。需 Windows 与本机 MusicBee;脚本按加载时给出的 Base directory 定位。
3
+ description: 🎵 MusicBee 歌单与曲库工具 — 扫曲库建索引、把网易云歌单导入本地库(写标签)并刷新 MusicBee、排整场舞会歌单、管理 .mbp 歌单文件。① 扫描:音乐目录 → JSON 索引(标题/艺人/专辑/风格/年代/BPM/时长),可导出 CSV;② 导入:网易云歌单下载 → 写 ID3 标签(标题/演出者/专辑)→ 生成 .mbp 进 MusicBee 分组,含 Rescan 刷新实测;③ 标签:可写标签(批量/单文件),写后一条命令自动刷新 MusicBee 库;④ 舞会整场歌单:风格配额/时长占比/能量与 ballroom 连排上限/结尾序列/跨歌单去重/同类型不连排/ballroom 间距上限一次校验,写 3dj 分组 .mbp + 逐曲理由说明 md(party_build.py);⑤ 歌单文件:改完 .mbp 一键重启生效,曲库整理后按路径映射批量重写/清理引用。不联网、不改音频数据。需 Windows 与本机 MusicBee;脚本按加载时给出的 Base directory 定位;内置 `scripts\mb-doctor.cmd` 自动探测库/Playlists/Python 路径。
4
4
  triggers:
5
5
  - 歌单
6
6
  - 生成歌单
@@ -51,6 +51,59 @@ CLI 入口:`scripts\mb-tools.cmd`(内部 `python -X utf8 -m mb_tools`;命
51
51
 
52
52
  ---
53
53
 
54
+ ## 零、首次使用(先跑这条,别猜路径)
55
+
56
+ 本技能要三样本机信息:MusicBee 的 `Playlists` 目录、曲库根目录(**风格子目录的父目录**)、一个装有 `mutagen` 的 Python。
57
+ **不要手猜路径**,先自检——它从 `%APPDATA%\MusicBee\MusicBee3Settings.ini` 的 `<ENV_LibPath>` 自动解析:
58
+
59
+ ```bat
60
+ scripts\mb-doctor.cmd :: 人读的清单
61
+ scripts\mb-doctor.cmd -StyleRoot "D:\你的曲库\1blues" :: 同时列出风格子目录名
62
+ scripts\mb-doctor.cmd -Json :: 给程序读的 JSON
63
+ ```
64
+
65
+ | 输出项 | 含义 | 填到配置的哪 |
66
+ |---|---|---|
67
+ | `MusicBeeLibrary` | MusicBee 库目录 | (用来推导 `Playlists`) |
68
+ | `PlaylistsDir` | `.mbp` 所在目录,须已存在 | `playlists_dir` |
69
+ | `PlaylistGroups` | 已有分组(如 `1blues`、`3dj`) | 决定 `prefix_mbp` 和 `out_mbp` |
70
+ | `StyleRoot` / `StyleSubfolders` | 风格子目录的父目录及其子目录名 | `library_root` 与 `styles` |
71
+ | `Python` | 可用解释器路径 | 设环境变量 `MUSICBEE_PY`,或直接用它 |
72
+
73
+ 三项齐了再改配置:复制 `references/party-2026-11-20-final.json` 一份,**只改路径字段和 `library_root`**,
74
+ `req` / `ending` / `body` / `share` / `long_sec` / `no_repeat_style` / `ballroom_gap_max` 这些规则原样保留。
75
+
76
+ > ⚠️ **动手前必须让用户确认路径**。`mb-doctor` 探测到的是机器侧事实,但下面两件事只有用户知道:
77
+ > ① `library_root` 的**层级**对不对(是 `…\1blues` 还是它的上一层/下一层,决定风格池能不能命中);
78
+ > ② `playlists_dir` 是不是**用户想写入的那个库**(一台机器可能有多个 MusicBee 库/多份 Playlists)。
79
+ >
80
+ > 所以:先把 `mb-doctor` 的 `MusicBeeLibrary` / `PlaylistsDir` / `StyleRoot` / `StyleSubfolders` 贴给用户确认,
81
+ > **得到「对」的答复后**再读索引、再跑 `party_build.py`、再写 `.mbp`。写歌单会直接改变 MusicBee 面板里的内容,
82
+ > 宁可多问一句,也不要按探测结果直接落盘。
83
+
84
+ **确认是硬门槛,不是靠自觉**:`party_build.py` 会读 `~/.musicbee-skill/paths.json`,**没有这个文件就拒绝写歌单**,并提示跑:
85
+
86
+ ```bat
87
+ scripts\mb-doctor.cmd -StyleRoot "D:\你的曲库\1blues" -Accept
88
+ ```
89
+
90
+ 它会再次列出探测结果,你输入 `y` 后把路径记下来(含时间戳与风格子目录列表)。之后配置里的
91
+ `playlists_dir` / `library_root` 必须与记录一致,**不一致同样拒绝**并同时打印两个值,让你选。
92
+ 换库或路径变了就重跑一次 `-Accept`。确实要跳过这道门:设环境变量 `MUSICBEE_SKIP_CONFIRM=1`。
93
+
94
+ ### 报错 → 该做什么
95
+
96
+ | 报错 | 修法 |
97
+ |---|---|
98
+ | `配置缺少字段:library_root…` | 填「风格子目录的父目录」;用 `mb-doctor.cmd -StyleRoot <目录>` 确认 |
99
+ | `索引文件不存在:…` | 先 `mb-tools.cmd scan --dir <曲库根> --out <那个 index 路径>` |
100
+ | `playlists_dir 不存在:…` | 跑 `mb-doctor.cmd` 看探测结果;MusicBee 至少启动过一次才会写 settings ini |
101
+ | `取不到 52 字节文件头…` | `prefix_mbp` 要指向 `<playlists_dir>` 下任意同库 `.mbp`(如 `1blues/ballroomin.mbp`) |
102
+ | `曲目无法唯一定位:…` | `set` 里的标题必须与索引完全一致;`scan` 后曲库改过要重扫 |
103
+ | `风格池不存在于索引:…` | `library_root` 指错了层级(少了/多了 `1blues` 这层),或 `styles` 名与子目录名不符 |
104
+
105
+ ---
106
+
54
107
  ## 一、能做什么(功能清单)
55
108
 
56
109
  | # | 功能 | 命令 | 是否写文件 |
@@ -516,6 +569,8 @@ scripts\refresh-musicbee.cmd -Dir "<目录>" -NoSendKeys # 只改 mtime +
516
569
  |---|---|
517
570
  | `SKILL.md` | 本说明(功能、命令、刷新方法、整理流程) |
518
571
  | `scripts/mb-tools.cmd` | CLI 入口(scan / export / tag) |
572
+ | `scripts/mb-doctor.cmd` | 环境自检:MusicBee 库 / Playlists / 风格目录 / Python(人读;`-Json` 给程序) |
573
+ | `scripts/mb-doctor.ps1` | 上一脚本的实现(纯 ASCII,兼容 PS 5.1) |
519
574
  | `scripts/bootstrap.ps1` | 首次使用建 venv、装 mutagen |
520
575
  | `scripts/restart-musicbee.ps1` | 重启 MusicBee(纯 ASCII,兼容 PS 5.1) |
521
576
  | `scripts/restart-musicbee.cmd` | 上一脚本的 cmd 包装 |
@@ -0,0 +1,6 @@
1
+ @echo off
2
+ setlocal
3
+ chcp 65001 >nul
4
+ powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0mb-doctor.ps1" %*
5
+ set "RC=%ERRORLEVEL%"
6
+ endlocal & exit /b %RC%
@@ -0,0 +1,151 @@
1
+ # mb-doctor.ps1 - show the paths this skill needs on THIS machine, and what is missing.
2
+ # ASCII-only on purpose: Windows PowerShell 5.1 decodes BOM-less UTF-8 as ANSI,
3
+ # so keep this file ASCII or the parser breaks. Chinese explanations live in SKILL.md.
4
+ param(
5
+ [string]$StyleRoot = "",
6
+ [switch]$Json,
7
+ [switch]$Accept
8
+ )
9
+
10
+ $ErrorActionPreference = "Stop"
11
+
12
+ function Get-MusicBeeExe {
13
+ $p = @(Get-Process MusicBee -ErrorAction SilentlyContinue)
14
+ if ($p.Count -gt 0 -and $p[0].Path) { return $p[0].Path }
15
+ $c = @(
16
+ "$env:LOCALAPPDATA\MusicBee\MusicBee.exe",
17
+ "$env:LOCALAPPDATA\Programs\MusicBee\MusicBee.exe",
18
+ "$env:ProgramFiles\MusicBee\MusicBee.exe",
19
+ "${env:ProgramFiles(x86)}\MusicBee\MusicBee.exe"
20
+ )
21
+ foreach ($x in $c) { if (Test-Path $x) { return $x } }
22
+ return ""
23
+ }
24
+
25
+ function Get-SettingsIni {
26
+ $ini = Join-Path $env:APPDATA "MusicBee\MusicBee3Settings.ini"
27
+ if (Test-Path $ini) { return $ini }
28
+ return ""
29
+ }
30
+
31
+ function Get-LibraryDir {
32
+ $ini = Get-SettingsIni
33
+ if ($ini) {
34
+ $m = [regex]::Match((Get-Content $ini -Raw), '<ENV_LibPath>([^<]*)</ENV_LibPath>')
35
+ if ($m.Success -and $m.Groups[1].Value.Trim()) { return $m.Groups[1].Value.Trim() }
36
+ }
37
+ $guess = Join-Path $env:USERPROFILE "Music\myMusic"
38
+ if (Test-Path (Join-Path $guess "MusicBeeLibrary.mbl")) { return $guess }
39
+ return ""
40
+ }
41
+
42
+ function Get-Python {
43
+ if ($env:MUSICBEE_PY -and (Test-Path $env:MUSICBEE_PY)) { return $env:MUSICBEE_PY }
44
+ $local = Join-Path $PSScriptRoot ".venv\Scripts\python.exe"
45
+ if (Test-Path $local) { return $local }
46
+ foreach ($name in @("py", "python", "python3")) {
47
+ $cmd = Get-Command $name -ErrorAction SilentlyContinue
48
+ if ($cmd) {
49
+ try {
50
+ $v = & $cmd.Source -c "import sys;print(sys.version.split()[0])" 2>$null
51
+ if ($LASTEXITCODE -eq 0 -and $v) { return $cmd.Source }
52
+ } catch { }
53
+ }
54
+ }
55
+ return ""
56
+ }
57
+
58
+ $exe = Get-MusicBeeExe
59
+ $ini = Get-SettingsIni
60
+ $lib = Get-LibraryDir
61
+ $playlists = if ($lib) { Join-Path $lib "Playlists" } else { "" }
62
+ $hasPlaylists = $playlists -ne "" -and (Test-Path $playlists)
63
+ $groups = @()
64
+ if ($hasPlaylists) {
65
+ $groups = @(Get-ChildItem $playlists -Directory -ErrorAction SilentlyContinue | ForEach-Object { $_.Name })
66
+ }
67
+ $styleSub = @()
68
+ $styleOk = $StyleRoot -ne "" -and (Test-Path $StyleRoot)
69
+ if ($styleOk) {
70
+ $styleSub = @(Get-ChildItem $StyleRoot -Directory -ErrorAction SilentlyContinue | ForEach-Object { $_.Name })
71
+ }
72
+ $py = Get-Python
73
+ $pyVer = ""
74
+ if ($py) {
75
+ try { $pyVer = (& $py -c "import sys;print(sys.version.split()[0])" 2>$null | Select-Object -First 1) } catch { }
76
+ }
77
+
78
+ $summary = [ordered]@{
79
+ musicBeeExe = $exe
80
+ settingsIni = $ini
81
+ musicBeeLibrary = $lib
82
+ playlistsDir = $playlists
83
+ playlistsExists = $hasPlaylists
84
+ playlistGroups = $groups
85
+ styleRoot = $StyleRoot
86
+ styleRootExists = $styleOk
87
+ styleCandidates = $styleSub
88
+ python = $py
89
+ pythonVersion = $pyVer
90
+ musicBeePyEnv = $(if ($env:MUSICBEE_PY) { $env:MUSICBEE_PY } else { "" })
91
+ }
92
+
93
+ if ($Json) {
94
+ $summary | ConvertTo-Json -Depth 4
95
+ exit 0
96
+ }
97
+
98
+ Write-Host "== MusicBee skill environment =="
99
+ Write-Host ("MusicBeeExe : " + $(if ($exe) { $exe } else { "NOT FOUND (restart-musicbee.cmd accepts -MusicBeeExe <path>)" }))
100
+ Write-Host ("SettingsIni : " + $(if ($ini) { $ini } else { "NOT FOUND (%APPDATA%\MusicBee\MusicBee3Settings.ini)" }))
101
+ Write-Host ("MusicBeeLibrary : " + $(if ($lib) { $lib } else { "UNKNOWN (no <ENV_LibPath> in the settings ini)" }))
102
+ Write-Host ("PlaylistsDir : " + $(if ($playlists) { $playlists } else { "UNKNOWN (needs MusicBeeLibrary)" }) + $(if ($playlists) { " [exists=" + $hasPlaylists + "]" }))
103
+ if ($groups.Count -gt 0) { Write-Host ("PlaylistGroups : " + ($groups -join ", ")) }
104
+ Write-Host ("StyleRoot : " + $(if ($styleOk) { $StyleRoot + " [exists=True]" } else { "NOT GIVEN (pass -StyleRoot <folder whose subfolders are styles>)" }))
105
+ if ($styleSub.Count -gt 0) { Write-Host ("StyleSubfolders : " + ($styleSub -join ", ")) }
106
+ Write-Host ("Python : " + $(if ($py) { $py + " (" + $pyVer + ")" } else { "NOT FOUND (set MUSICBEE_PY or run scripts\bootstrap.ps1)" }))
107
+ Write-Host ("MUSICBEE_PY env : " + $(if ($env:MUSICBEE_PY) { $env:MUSICBEE_PY } else { "unset" }))
108
+ Write-Host ""
109
+ Write-Host "-- what to do next --"
110
+ if (-not $hasPlaylists) { Write-Host " playlists_dir : start MusicBee once, or pass the folder that holds the .mbp files" }
111
+ if (-not $styleOk) { Write-Host " library_root : pass -StyleRoot to see its subfolders; party config needs that folder" }
112
+ if (-not $py) { Write-Host " python : set MUSICBEE_PY=%LOCALAPPDATA%\Programs\Python\...\python.exe, or run scripts\bootstrap.ps1" }
113
+ if (-not $exe) { Write-Host " MusicBee.exe : install MusicBee, or pass -MusicBeeExe to restart-musicbee.cmd" }
114
+ if ($hasPlaylists -and $styleOk -and $py -and $exe) { Write-Host " everything needed was found. Next: fill a party config and run party_build.py <config.json>" }
115
+ Write-Host ""
116
+ Write-Host "IMPORTANT: show these paths to the user and get an explicit yes before writing any config or .mbp."
117
+ Write-Host " A machine can hold several MusicBee libraries, and library_root must name the folder that"
118
+ Write-Host " directly contains the style subfolders - only the user can confirm both."
119
+
120
+ if ($Accept) {
121
+ if (-not $hasPlaylists) {
122
+ Write-Host ""
123
+ Write-Host "cannot record: PlaylistsDir is unknown. Start MusicBee once so it writes its settings ini."
124
+ exit 1
125
+ }
126
+ Write-Host ""
127
+ Write-Host "-- record confirmed paths --"
128
+ Write-Host (" playlists_dir : " + $playlists)
129
+ Write-Host (" library_root : " + $(if ($styleOk) { $StyleRoot } else { "(not given; pass -StyleRoot to record it)" }))
130
+ $ans = Read-Host "Are these the paths this machine should write to? type y to record"
131
+ if ($ans -notin @("y", "Y", "yes", "YES")) { Write-Host "not recorded."; exit 1 }
132
+ $dir = Join-Path $env:USERPROFILE ".musicbee-skill"
133
+ New-Item -ItemType Directory -Force -Path $dir | Out-Null
134
+ $record = [ordered]@{
135
+ confirmedAt = (Get-Date).ToString("s")
136
+ musicBeeExe = $exe
137
+ musicBeeLibrary = $lib
138
+ playlistsDir = $playlists
139
+ libraryRoot = $StyleRoot
140
+ styleSubfolders = $styleSub
141
+ python = $py
142
+ pythonVersion = $pyVer
143
+ }
144
+ $file = Join-Path $dir "paths.json"
145
+ $record | ConvertTo-Json -Depth 4 | Set-Content -Path $file -Encoding UTF8
146
+ Write-Host ("recorded -> " + $file)
147
+ Write-Host "party_build.py now accepts configs whose playlists_dir/library_root match this record."
148
+ exit 0
149
+ }
150
+
151
+ if ($hasPlaylists -and $py) { exit 0 } else { exit 1 }
@@ -177,18 +177,74 @@ def mmss(t):
177
177
 
178
178
 
179
179
  # ---------------------------------------------------------------- 校验
180
+ # ------------------------------------------------------------ 路径确认
181
+ CONFIRM_FILE = os.path.join(os.path.expanduser("~"), ".musicbee-skill", "paths.json")
182
+
183
+
184
+ def load_confirmed_paths():
185
+ """The paths the user confirmed with `mb-doctor.cmd -Accept`, or None."""
186
+ if not os.path.exists(CONFIRM_FILE):
187
+ return None
188
+ try:
189
+ with open(CONFIRM_FILE, encoding="utf-8-sig") as f:
190
+ return json.load(f)
191
+ except Exception:
192
+ return None
193
+
194
+
195
+ def same_path(a, b):
196
+ return os.path.normcase(os.path.normpath(a)) == os.path.normcase(os.path.normpath(b))
197
+
198
+
199
+ def require_confirmed_paths(cfg):
200
+ """First-run gate: nothing is written until the user confirmed the machine's paths."""
201
+ if os.environ.get("MUSICBEE_SKIP_CONFIRM"):
202
+ return
203
+ confirmed = load_confirmed_paths()
204
+ if confirmed is None:
205
+ die("首次使用:先确认路径,确认前不会写任何歌单文件。\n"
206
+ " 跑这条:scripts\\mb-doctor.cmd -StyleRoot <曲库根> -Accept\n"
207
+ " 它会列出探测到的 MusicBee 库 / Playlists / 风格目录,输入 y 后记录到\n"
208
+ " " + CONFIRM_FILE + "\n"
209
+ " (确实不想确认:设环境变量 MUSICBEE_SKIP_CONFIRM=1)")
210
+ for cfg_key, rec_key in (("playlists_dir", "playlistsDir"), ("library_root", "libraryRoot")):
211
+ got = cfg.get(cfg_key) or ""
212
+ want = confirmed.get(rec_key) or ""
213
+ if got and want and not same_path(got, want):
214
+ die("配置里的 " + cfg_key + " 与已确认的路径不一致:\n"
215
+ " 已确认:" + want + "\n"
216
+ " 配置里:" + got + "\n"
217
+ " 哪个才对就留哪个:改配置,或重跑 scripts\\mb-doctor.cmd -Accept 更新记录。")
218
+
219
+
180
220
  def run(cfg):
181
221
  need = ["index", "playlists_dir", "out_mbp", "prefix_mbp", "name", "styles", "req", "body", "set"]
182
- for k in need:
183
- if k not in cfg:
184
- die("配置缺少字段:" + k)
222
+ missing = [k for k in need if k not in cfg]
223
+ if missing:
224
+ die("配置缺少字段:" + "、".join(missing) +
225
+ "\n 必填:" + " / ".join(need) +
226
+ "\n 不知道路径填什么?先跑 scripts\\mb-doctor.cmd 看本机探测结果。")
185
227
 
186
- tracks = json.load(open(cfg["index"], encoding="utf-8"))
187
- if isinstance(tracks, dict):
188
- tracks = tracks.get("tracks") or tracks.get("items") or []
189
228
  library_root = cfg.get("library_root")
190
229
  if not library_root:
191
- die("配置缺少字段:library_root(1blues 风格目录所在的曲库根目录)")
230
+ die("配置缺少字段:library_root(风格子目录的父目录,例如 ...\\1blues)" +
231
+ "\n 先跑 scripts\\mb-doctor.cmd -StyleRoot <那个目录> 确认风格子目录名")
232
+ if not os.path.isdir(library_root):
233
+ die("library_root 不是有效目录:" + library_root)
234
+ if not os.path.isdir(cfg["playlists_dir"]):
235
+ die("playlists_dir 不存在:" + cfg["playlists_dir"] +
236
+ "\n 先跑 scripts\\mb-doctor.cmd 查看探测到的 Playlists 目录")
237
+
238
+ require_confirmed_paths(cfg)
239
+
240
+ index_path = cfg["index"]
241
+ if not os.path.exists(index_path):
242
+ die("索引文件不存在:" + index_path +
243
+ "\n 它是 mb-tools scan 的产物,先生成:mb-tools.cmd scan --dir <曲库根> --out " + index_path)
244
+
245
+ tracks = json.load(open(index_path, encoding="utf-8"))
246
+ if isinstance(tracks, dict):
247
+ tracks = tracks.get("tracks") or tracks.get("items") or []
192
248
  pools = load_pools(tracks, library_root)
193
249
  for st in cfg["styles"]:
194
250
  if st not in pools:
@@ -357,6 +413,9 @@ def run(cfg):
357
413
  prefix = cfg["prefix_mbp"]
358
414
  if not os.path.isabs(prefix):
359
415
  prefix = os.path.join(cfg["playlists_dir"], prefix)
416
+ if not os.path.exists(prefix):
417
+ die("取不到 52 字节文件头,来源 .mbp 不存在:" + prefix +
418
+ "\n prefix_mbp 要指向 <playlists_dir> 下任意一个同库 .mbp(例如 \"1blues/ballroomin.mbp\")")
360
419
  size = write_mbp(prefix, cfg["out_mbp"], paths)
361
420
  print(f"wrote {cfg['out_mbp']} {size} bytes round-trip OK")
362
421
 
@@ -503,9 +562,20 @@ def write_md(cfg, st):
503
562
  f.write("\n".join(L) + "\n")
504
563
 
505
564
 
565
+ USAGE = """用法:party_build.py <config.json>
566
+
567
+ 必填字段:index / playlists_dir / out_mbp / prefix_mbp / name / styles / req / body / set
568
+ 可选字段:library_root / exclude / share / ending / long_sec / total_window /
569
+ no_repeat_style / ballroom_gap_max / out_md / md_title / intro / sections / oneliner / display
570
+
571
+ 示例配置:references/party-2026-11-20-final.json
572
+ 不知道路径填什么:先跑 scripts\\mb-doctor.cmd 看本机探测结果。"""
573
+
574
+
506
575
  def main():
507
- if len(sys.argv) != 2:
508
- die("用法:party_build.py <config.json>")
576
+ if len(sys.argv) != 2 or sys.argv[1] in ("-h", "--help"):
577
+ print(USAGE)
578
+ sys.exit(0 if len(sys.argv) > 1 else 2)
509
579
  # utf-8-sig so a config saved by Notepad/PowerShell (which add a BOM) loads.
510
580
  cfg = json.load(open(sys.argv[1], encoding="utf-8-sig"))
511
581
  run(cfg)