@chenhao6682108/dsh-skill-musicbee 0.1.0 → 0.1.1

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,25 @@ 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.
68
+
50
69
  ## How it works
51
70
 
52
71
  `lib/index.js` is a dependency-free Cordis function plugin. On `apply()` it reads the packaged
package/README.zh.md CHANGED
@@ -41,6 +41,23 @@ 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
+
44
61
  ## 实现方式
45
62
 
46
63
  `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.1",
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,41 @@ 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
+ ### 报错 → 该做什么
77
+
78
+ | 报错 | 修法 |
79
+ |---|---|
80
+ | `配置缺少字段:library_root…` | 填「风格子目录的父目录」;用 `mb-doctor.cmd -StyleRoot <目录>` 确认 |
81
+ | `索引文件不存在:…` | 先 `mb-tools.cmd scan --dir <曲库根> --out <那个 index 路径>` |
82
+ | `playlists_dir 不存在:…` | 跑 `mb-doctor.cmd` 看探测结果;MusicBee 至少启动过一次才会写 settings ini |
83
+ | `取不到 52 字节文件头…` | `prefix_mbp` 要指向 `<playlists_dir>` 下任意同库 `.mbp`(如 `1blues/ballroomin.mbp`) |
84
+ | `曲目无法唯一定位:…` | `set` 里的标题必须与索引完全一致;`scan` 后曲库改过要重扫 |
85
+ | `风格池不存在于索引:…` | `library_root` 指错了层级(少了/多了 `1blues` 这层),或 `styles` 名与子目录名不符 |
86
+
87
+ ---
88
+
54
89
  ## 一、能做什么(功能清单)
55
90
 
56
91
  | # | 功能 | 命令 | 是否写文件 |
@@ -516,6 +551,8 @@ scripts\refresh-musicbee.cmd -Dir "<目录>" -NoSendKeys # 只改 mtime +
516
551
  |---|---|
517
552
  | `SKILL.md` | 本说明(功能、命令、刷新方法、整理流程) |
518
553
  | `scripts/mb-tools.cmd` | CLI 入口(scan / export / tag) |
554
+ | `scripts/mb-doctor.cmd` | 环境自检:MusicBee 库 / Playlists / 风格目录 / Python(人读;`-Json` 给程序) |
555
+ | `scripts/mb-doctor.ps1` | 上一脚本的实现(纯 ASCII,兼容 PS 5.1) |
519
556
  | `scripts/bootstrap.ps1` | 首次使用建 venv、装 mutagen |
520
557
  | `scripts/restart-musicbee.ps1` | 重启 MusicBee(纯 ASCII,兼容 PS 5.1) |
521
558
  | `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,115 @@
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
+ )
8
+
9
+ $ErrorActionPreference = "Stop"
10
+
11
+ function Get-MusicBeeExe {
12
+ $p = @(Get-Process MusicBee -ErrorAction SilentlyContinue)
13
+ if ($p.Count -gt 0 -and $p[0].Path) { return $p[0].Path }
14
+ $c = @(
15
+ "$env:LOCALAPPDATA\MusicBee\MusicBee.exe",
16
+ "$env:LOCALAPPDATA\Programs\MusicBee\MusicBee.exe",
17
+ "$env:ProgramFiles\MusicBee\MusicBee.exe",
18
+ "${env:ProgramFiles(x86)}\MusicBee\MusicBee.exe"
19
+ )
20
+ foreach ($x in $c) { if (Test-Path $x) { return $x } }
21
+ return ""
22
+ }
23
+
24
+ function Get-SettingsIni {
25
+ $ini = Join-Path $env:APPDATA "MusicBee\MusicBee3Settings.ini"
26
+ if (Test-Path $ini) { return $ini }
27
+ return ""
28
+ }
29
+
30
+ function Get-LibraryDir {
31
+ $ini = Get-SettingsIni
32
+ if ($ini) {
33
+ $m = [regex]::Match((Get-Content $ini -Raw), '<ENV_LibPath>([^<]*)</ENV_LibPath>')
34
+ if ($m.Success -and $m.Groups[1].Value.Trim()) { return $m.Groups[1].Value.Trim() }
35
+ }
36
+ $guess = Join-Path $env:USERPROFILE "Music\myMusic"
37
+ if (Test-Path (Join-Path $guess "MusicBeeLibrary.mbl")) { return $guess }
38
+ return ""
39
+ }
40
+
41
+ function Get-Python {
42
+ if ($env:MUSICBEE_PY -and (Test-Path $env:MUSICBEE_PY)) { return $env:MUSICBEE_PY }
43
+ $local = Join-Path $PSScriptRoot ".venv\Scripts\python.exe"
44
+ if (Test-Path $local) { return $local }
45
+ foreach ($name in @("py", "python", "python3")) {
46
+ $cmd = Get-Command $name -ErrorAction SilentlyContinue
47
+ if ($cmd) {
48
+ try {
49
+ $v = & $cmd.Source -c "import sys;print(sys.version.split()[0])" 2>$null
50
+ if ($LASTEXITCODE -eq 0 -and $v) { return $cmd.Source }
51
+ } catch { }
52
+ }
53
+ }
54
+ return ""
55
+ }
56
+
57
+ $exe = Get-MusicBeeExe
58
+ $ini = Get-SettingsIni
59
+ $lib = Get-LibraryDir
60
+ $playlists = if ($lib) { Join-Path $lib "Playlists" } else { "" }
61
+ $hasPlaylists = $playlists -ne "" -and (Test-Path $playlists)
62
+ $groups = @()
63
+ if ($hasPlaylists) {
64
+ $groups = @(Get-ChildItem $playlists -Directory -ErrorAction SilentlyContinue | ForEach-Object { $_.Name })
65
+ }
66
+ $styleSub = @()
67
+ $styleOk = $StyleRoot -ne "" -and (Test-Path $StyleRoot)
68
+ if ($styleOk) {
69
+ $styleSub = @(Get-ChildItem $StyleRoot -Directory -ErrorAction SilentlyContinue | ForEach-Object { $_.Name })
70
+ }
71
+ $py = Get-Python
72
+ $pyVer = ""
73
+ if ($py) {
74
+ try { $pyVer = (& $py -c "import sys;print(sys.version.split()[0])" 2>$null | Select-Object -First 1) } catch { }
75
+ }
76
+
77
+ $summary = [ordered]@{
78
+ musicBeeExe = $exe
79
+ settingsIni = $ini
80
+ musicBeeLibrary = $lib
81
+ playlistsDir = $playlists
82
+ playlistsExists = $hasPlaylists
83
+ playlistGroups = $groups
84
+ styleRoot = $StyleRoot
85
+ styleRootExists = $styleOk
86
+ styleCandidates = $styleSub
87
+ python = $py
88
+ pythonVersion = $pyVer
89
+ musicBeePyEnv = $(if ($env:MUSICBEE_PY) { $env:MUSICBEE_PY } else { "" })
90
+ }
91
+
92
+ if ($Json) {
93
+ $summary | ConvertTo-Json -Depth 4
94
+ exit 0
95
+ }
96
+
97
+ Write-Host "== MusicBee skill environment =="
98
+ Write-Host ("MusicBeeExe : " + $(if ($exe) { $exe } else { "NOT FOUND (restart-musicbee.cmd accepts -MusicBeeExe <path>)" }))
99
+ Write-Host ("SettingsIni : " + $(if ($ini) { $ini } else { "NOT FOUND (%APPDATA%\MusicBee\MusicBee3Settings.ini)" }))
100
+ Write-Host ("MusicBeeLibrary : " + $(if ($lib) { $lib } else { "UNKNOWN (no <ENV_LibPath> in the settings ini)" }))
101
+ Write-Host ("PlaylistsDir : " + $(if ($playlists) { $playlists } else { "UNKNOWN (needs MusicBeeLibrary)" }) + $(if ($playlists) { " [exists=" + $hasPlaylists + "]" }))
102
+ if ($groups.Count -gt 0) { Write-Host ("PlaylistGroups : " + ($groups -join ", ")) }
103
+ Write-Host ("StyleRoot : " + $(if ($styleOk) { $StyleRoot + " [exists=True]" } else { "NOT GIVEN (pass -StyleRoot <folder whose subfolders are styles>)" }))
104
+ if ($styleSub.Count -gt 0) { Write-Host ("StyleSubfolders : " + ($styleSub -join ", ")) }
105
+ Write-Host ("Python : " + $(if ($py) { $py + " (" + $pyVer + ")" } else { "NOT FOUND (set MUSICBEE_PY or run scripts\bootstrap.ps1)" }))
106
+ Write-Host ("MUSICBEE_PY env : " + $(if ($env:MUSICBEE_PY) { $env:MUSICBEE_PY } else { "unset" }))
107
+ Write-Host ""
108
+ Write-Host "-- what to do next --"
109
+ if (-not $hasPlaylists) { Write-Host " playlists_dir : start MusicBee once, or pass the folder that holds the .mbp files" }
110
+ if (-not $styleOk) { Write-Host " library_root : pass -StyleRoot to see its subfolders; party config needs that folder" }
111
+ if (-not $py) { Write-Host " python : set MUSICBEE_PY=%LOCALAPPDATA%\Programs\Python\...\python.exe, or run scripts\bootstrap.ps1" }
112
+ if (-not $exe) { Write-Host " MusicBee.exe : install MusicBee, or pass -MusicBeeExe to restart-musicbee.cmd" }
113
+ 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>" }
114
+
115
+ if ($hasPlaylists -and $py) { exit 0 } else { exit 1 }
@@ -179,16 +179,29 @@ def mmss(t):
179
179
  # ---------------------------------------------------------------- 校验
180
180
  def run(cfg):
181
181
  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)
185
-
186
- tracks = json.load(open(cfg["index"], encoding="utf-8"))
182
+ missing = [k for k in need if k not in cfg]
183
+ if missing:
184
+ die("配置缺少字段:" + "、".join(missing) +
185
+ "\n 必填:" + " / ".join(need) +
186
+ "\n 不知道路径填什么?先跑 scripts\\mb-doctor.cmd 看本机探测结果。")
187
+
188
+ index_path = cfg["index"]
189
+ if not os.path.exists(index_path):
190
+ die("索引文件不存在:" + index_path +
191
+ "\n 它是 mb-tools scan 的产物,先生成:mb-tools.cmd scan --dir <曲库根> --out " + index_path)
192
+ if not os.path.isdir(cfg["playlists_dir"]):
193
+ die("playlists_dir 不存在:" + cfg["playlists_dir"] +
194
+ "\n 先跑 scripts\\mb-doctor.cmd 查看探测到的 Playlists 目录")
195
+
196
+ tracks = json.load(open(index_path, encoding="utf-8"))
187
197
  if isinstance(tracks, dict):
188
198
  tracks = tracks.get("tracks") or tracks.get("items") or []
189
199
  library_root = cfg.get("library_root")
190
200
  if not library_root:
191
- die("配置缺少字段:library_root(1blues 风格目录所在的曲库根目录)")
201
+ die("配置缺少字段:library_root(风格子目录的父目录,例如 ...\\1blues)" +
202
+ "\n 先跑 scripts\\mb-doctor.cmd -StyleRoot <那个目录> 确认风格子目录名")
203
+ if not os.path.isdir(library_root):
204
+ die("library_root 不是有效目录:" + library_root)
192
205
  pools = load_pools(tracks, library_root)
193
206
  for st in cfg["styles"]:
194
207
  if st not in pools:
@@ -357,6 +370,9 @@ def run(cfg):
357
370
  prefix = cfg["prefix_mbp"]
358
371
  if not os.path.isabs(prefix):
359
372
  prefix = os.path.join(cfg["playlists_dir"], prefix)
373
+ if not os.path.exists(prefix):
374
+ die("取不到 52 字节文件头,来源 .mbp 不存在:" + prefix +
375
+ "\n prefix_mbp 要指向 <playlists_dir> 下任意一个同库 .mbp(例如 \"1blues/ballroomin.mbp\")")
360
376
  size = write_mbp(prefix, cfg["out_mbp"], paths)
361
377
  print(f"wrote {cfg['out_mbp']} {size} bytes round-trip OK")
362
378
 
@@ -503,9 +519,20 @@ def write_md(cfg, st):
503
519
  f.write("\n".join(L) + "\n")
504
520
 
505
521
 
522
+ USAGE = """用法:party_build.py <config.json>
523
+
524
+ 必填字段:index / playlists_dir / out_mbp / prefix_mbp / name / styles / req / body / set
525
+ 可选字段:library_root / exclude / share / ending / long_sec / total_window /
526
+ no_repeat_style / ballroom_gap_max / out_md / md_title / intro / sections / oneliner / display
527
+
528
+ 示例配置:references/party-2026-11-20-final.json
529
+ 不知道路径填什么:先跑 scripts\\mb-doctor.cmd 看本机探测结果。"""
530
+
531
+
506
532
  def main():
507
- if len(sys.argv) != 2:
508
- die("用法:party_build.py <config.json>")
533
+ if len(sys.argv) != 2 or sys.argv[1] in ("-h", "--help"):
534
+ print(USAGE)
535
+ sys.exit(0 if len(sys.argv) > 1 else 2)
509
536
  # utf-8-sig so a config saved by Notepad/PowerShell (which add a BOM) loads.
510
537
  cfg = json.load(open(sys.argv[1], encoding="utf-8-sig"))
511
538
  run(cfg)