@chenhao6682108/dsh-skill-musicbee 0.0.0-stage → 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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 chenhao
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,99 @@
1
- # Temporary Holding Version
1
+ # dsh-skill-musicbee
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ English | [中文](README.zh.md)
4
+
5
+ A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) plugin that ships the
6
+ `musicbee` skill: a local toolkit for MusicBee libraries and playlists. It is a **skill plugin** — it
7
+ registers one agent skill (and its scripts) into the harness, so the agent picks it up like any other
8
+ skill and drives MusicBee through the bundled scripts.
9
+
10
+ No network access, no models, no GPU. It reads and writes file tags and playlist files, and never
11
+ touches audio data.
12
+
13
+ ## What the skill does
14
+
15
+ | Capability | Command | Writes files |
16
+ |---|---|---|
17
+ | Scan a music library into a JSON index (title/artist/album/genre/year/BPM/duration) | `mb-tools.cmd scan` | JSON only |
18
+ | Export an index as CSV | `mb-tools.cmd export` | — |
19
+ | Write tags (title/artist/album/track), batch or single file | `mb-tools.cmd tag` | ID3 / Vorbis / MP4 tags |
20
+ | Build a whole dance-party playlist in the `3dj` group with rule validation | `party_build.py <config.json>` | `.mbp` + share write-up `.md` |
21
+ | Rewrite / remap / prune playlist paths after a library reshuffle | `mbp-remap.ps1` | `.mbp` (with backup) |
22
+ | Restart MusicBee so playlist files are re-read | `restart-musicbee.cmd` | — |
23
+ | Make MusicBee re-read edited tags (`Tools → Rescan`, automated) | `refresh-musicbee.cmd -Dir <dir>` | — |
24
+
25
+ The skill body documents the verified internals: the `.mbp` binary format (52-byte prefix, int32
26
+ count, per-track 1-byte length + UTF-8 absolute path), why a restart is required for playlist files
27
+ while tags need `Tools → Rescan`, and the "date granularity" gotcha that makes a same-day rewrite
28
+ invisible to MusicBee.
29
+
30
+ ## Requirements
31
+
32
+ - **Windows** — the scripts are `.cmd` / PowerShell and drive a local MusicBee install.
33
+ - **MusicBee** installed (portable builds are fine; `-MusicBeeExe <path>` overrides detection).
34
+ - **Python 3.11+ with `mutagen`** for the index / tag / party-build tools:
35
+ `scripts\bootstrap.ps1` creates a local `.venv`, or set `MUSICBEE_PY` to an existing interpreter.
36
+
37
+ ## Install
38
+
39
+ ```sh
40
+ dsh plugin --profile web add @chenhao6682108/dsh-skill-musicbee # npm (once published)
41
+ dsh plugin --profile web add github:chenhao6682108/dsh-skill-musicbee # straight from the repo
42
+ dsh plugin --profile web add . # from a local checkout
43
+ ```
44
+
45
+ Restart `dsh web`. The skill catalog now lists `musicbee`; ask the agent for a library scan or a
46
+ party playlist and it loads the skill itself.
47
+
48
+ Uninstall with `dsh plugin --profile web remove @chenhao6682108/dsh-skill-musicbee`.
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
+
69
+ ## How it works
70
+
71
+ `lib/index.js` is a dependency-free Cordis function plugin. On `apply()` it reads the packaged
72
+ `skills/musicbee/SKILL.md`, parses its frontmatter, and calls `ctx.skills.register()` with a
73
+ directory resource base pointing at the package — so the `scripts/…` paths in the body resolve to the
74
+ installed copy. `cordis.patch.yml` is what makes `dsh plugin add` mount the package as a bundle.
75
+
76
+ ## Layout
77
+
78
+ ```text
79
+ package.json dsh.bundle.patch + engines.dsh
80
+ cordis.patch.yml inserts the plugin into the profile layer stack
81
+ lib/index.js registers the bundled skill (no dependencies, no build)
82
+ skills/musicbee/
83
+ SKILL.md the skill body the agent loads
84
+ scripts/ mb-tools (scan/export/tag), party_build.py, mbp-remap.ps1,
85
+ restart/refresh helpers, reference JSON configs
86
+ ```
87
+
88
+ ## Notes
89
+
90
+ - Paths inside the shipped SKILL.md and the two reference configs are placeholders
91
+ (`C:\path\to\…`, `<skills dir>`, `<library root>`); substitute your own locations.
92
+ - A profile-level copy of the same skill under `~/.dsh/skills` is shadowed by this plugin while it is
93
+ installed (plugin-provided skills outrank user files) — remove one of the two if you want the other.
94
+ - Pairs with [`@chenhao6682108/dsh-skill-netease-playlist`](../dsh-skill-netease-playlist) for the
95
+ "download a NetEase playlist → tag it → publish it into MusicBee" loop.
96
+
97
+ ## License
98
+
99
+ MIT
package/README.zh.md ADDED
@@ -0,0 +1,87 @@
1
+ # dsh-skill-musicbee
2
+
3
+ [English](README.md) | 中文
4
+
5
+ 一个把 `musicbee` 技能打包成 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)插件的仓库。
6
+ 它是**技能型插件**:装上之后 `musicbee` 和其它技能一样出现在会话技能目录里,模型按需加载并调用包内脚本操作 MusicBee。
7
+
8
+ 不联网、不跑模型、不碰音频数据——只读写文件标签和歌单文件。
9
+
10
+ ## 技能能做什么
11
+
12
+ | 能力 | 命令 | 写文件 |
13
+ |---|---|---|
14
+ | 扫曲库建 JSON 索引(标题/艺人/专辑/风格/年代/BPM/时长) | `mb-tools.cmd scan` | 只写 JSON |
15
+ | 索引导出 CSV | `mb-tools.cmd export` | — |
16
+ | 写标签(标题/演出者/专辑/曲目号,批量或单文件) | `mb-tools.cmd tag` | ID3 / Vorbis / MP4 |
17
+ | 排一整场舞会歌单(3dj 分组,逐条规则校验) | `party_build.py <config.json>` | `.mbp` + 分享说明 md |
18
+ | 曲库整理后按映射重写/清理歌单路径 | `mbp-remap.ps1` | `.mbp`(可备份) |
19
+ | 重启 MusicBee 让它重扫 `Playlists\` | `restart-musicbee.cmd` | — |
20
+ | 写标签后让 MusicBee 重读(Tools → Rescan 自动化) | `refresh-musicbee.cmd -Dir <目录>` | — |
21
+
22
+ 技能正文里记录了实测过的细节:`.mbp` 二进制格式(52 字节前缀 + int32 数量 + 每条 1 字节长度 + UTF-8 绝对路径)、
23
+ 为什么"歌单文件必须重启才生效"而"标签必须 Rescan"、以及 Rescan 只认「日期」粒度这个坑。
24
+
25
+ ## 环境要求
26
+
27
+ - **Windows**:脚本是 `.cmd` / PowerShell,直接驱动本机 MusicBee。
28
+ - **已安装 MusicBee**(便携版也行,`-MusicBeeExe <路径>` 可显式指定)。
29
+ - **Python 3.11+ 且装了 `mutagen`**(索引 / 写标签 / 舞会歌单用):
30
+ `scripts\bootstrap.ps1` 会建本地 `.venv`,也可以用环境变量 `MUSICBEE_PY` 指向已有解释器。
31
+
32
+ ## 安装
33
+
34
+ ```sh
35
+ dsh plugin --profile web add @chenhao6682108/dsh-skill-musicbee # npm(发布后)
36
+ dsh plugin --profile web add github:chenhao6682108/dsh-skill-musicbee # 直接从仓库装
37
+ dsh plugin --profile web add . # 从本地 checkout 装
38
+ ```
39
+
40
+ 重启 `dsh web`,技能目录里就有 `musicbee` 了;直接跟模型说"扫一下我的曲库"或"排一场舞会歌单",它会自己加载。
41
+
42
+ 卸载:`dsh plugin --profile web remove @chenhao6682108/dsh-skill-musicbee`。
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
+
61
+ ## 实现方式
62
+
63
+ `lib/index.js` 是一个零依赖的 Cordis 函数式插件:`apply()` 读取包内 `skills/musicbee/SKILL.md`,解析 frontmatter,
64
+ 用 `ctx.skills.register()` 注册技能,并把 `resourceBase` 指向包目录——所以正文里的 `scripts\…` 相对路径能解析到安装副本。
65
+ `cordis.patch.yml` 才是让 `dsh plugin add` 能把它当 bundle 挂进 profile 层栈的关键。
66
+
67
+ ## 目录结构
68
+
69
+ ```text
70
+ package.json dsh.bundle.patch + engines.dsh
71
+ cordis.patch.yml 把插件插入 profile 层栈
72
+ lib/index.js 注册包内技能(零依赖、零构建)
73
+ skills/musicbee/
74
+ SKILL.md 模型加载的技能正文
75
+ scripts/ mb-tools(scan/export/tag)、party_build.py、mbp-remap.ps1、
76
+ 重启/刷新脚本、参考配置 JSON
77
+ ```
78
+
79
+ ## 注意
80
+
81
+ - 包内 SKILL.md 与两份参考配置里的路径都是占位符(`C:\path\to\…`、`<技能目录>`、`<曲库根>`),用前换成自己的目录。
82
+ - 如果 `~/.dsh/skills/musicbee` 还留着同名技能,装上插件后会被插件版覆盖(插件提供的技能优先于本地文件);只想用其中一份就删掉另一份。
83
+ - 和 [`@chenhao6682108/dsh-skill-netease-playlist`](../dsh-skill-netease-playlist) 配套使用,构成「网易云下载 → 补标签 → 进 MusicBee」的闭环。
84
+
85
+ ## 许可
86
+
87
+ MIT
@@ -0,0 +1,5 @@
1
+ # DSH bundle patch: inserts this plugin into a profile's plugin layer stack.
2
+ # Installed with: dsh plugin --profile <profile> add <package-or-tarball>
3
+ - insert:
4
+ - id: skill-musicbee
5
+ name: '@chenhao6682108/dsh-skill-musicbee'
package/lib/index.js ADDED
@@ -0,0 +1,104 @@
1
+ /**
2
+ * `@chenhao6682108/dsh-skill-musicbee` — ships the `musicbee` skill as an installable
3
+ * DSH plugin.
4
+ *
5
+ * A Cordis function plugin with no dependencies and no build step: `apply()`
6
+ * reads this package's bundled `skills/musicbee/SKILL.md`, parses its
7
+ * frontmatter, and registers the body into the harness skill registry
8
+ * (`ctx.skills`) with a directory resource base, so the relative `scripts/`
9
+ * and `references/` paths in the body resolve against the installed package.
10
+ *
11
+ * The plugin is a bundle: `cordis.patch.yml` inserts it into a profile's layer
12
+ * stack when installed with `dsh plugin add`.
13
+ *
14
+ * @module @chenhao6682108/dsh-skill-musicbee
15
+ */
16
+
17
+ import { readFileSync } from 'node:fs'
18
+ import { fileURLToPath } from 'node:url'
19
+
20
+ /** Plugin name shown by the loader. */
21
+ export const name = 'skill-musicbee'
22
+
23
+ /** The skill registry is the only host service this plugin touches. */
24
+ export const inject = ['skills']
25
+
26
+ const SKILL_DIR = new URL('../skills/musicbee/', import.meta.url)
27
+
28
+ /** Shown only when the bundled SKILL.md loses its frontmatter description. */
29
+ const FALLBACK_DESCRIPTION =
30
+ 'MusicBee playlist and library toolkit: scan a music library into a JSON index, ' +
31
+ 'write ID3/Vorbis/MP4 tags, build validated dsh (3dj) party playlists, rewrite .mbp ' +
32
+ 'playlists and make MusicBee re-read them. Windows plus a local MusicBee install required.'
33
+
34
+ /**
35
+ * Parse leading YAML frontmatter into flat fields.
36
+ *
37
+ * Only the subset a SKILL.md uses is understood: `key: value` scalars and
38
+ * `key:` followed by `- item` lists. Deeper YAML (nested maps, block scalars)
39
+ * is not needed by any argument this plugin ships, so it is left alone rather
40
+ * than half-parsed.
41
+ *
42
+ * @param {string} raw - full SKILL.md text.
43
+ * @returns {{ fields: Record<string, string | string[]>, body: string }}
44
+ */
45
+ function parseFrontmatter(raw) {
46
+ const text = raw.replace(/^\uFEFF/, '')
47
+ const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text)
48
+ if (match === null) return { fields: {}, body: text }
49
+
50
+ /** @type {Record<string, string | string[]>} */
51
+ const fields = {}
52
+ let key = null
53
+ for (const line of match[1].split(/\r?\n/)) {
54
+ if (line.trim() === '' || /^[ \t]*#/.test(line)) continue
55
+
56
+ const item = /^[ \t]*-[ \t]+(.*)$/.exec(line)
57
+ if (item !== null && key !== null) {
58
+ const list = Array.isArray(fields[key]) ? fields[key] : []
59
+ list.push(unquote(item[1].trim()))
60
+ fields[key] = list
61
+ continue
62
+ }
63
+
64
+ const pair = /^([A-Za-z][\w-]*)[ \t]*:[ \t]*(.*)$/.exec(line)
65
+ if (pair === null) continue
66
+ key = pair[1]
67
+ const value = pair[2].trim()
68
+ fields[key] = value === '' ? [] : unquote(value)
69
+ }
70
+ return { fields, body: text.slice(match[0].length) }
71
+ }
72
+
73
+ /**
74
+ * Strip one layer of matching single or double quotes.
75
+ * @param {string} value - raw scalar.
76
+ * @returns {string} the unquoted scalar.
77
+ */
78
+ function unquote(value) {
79
+ const quoted = /^(['"])([\s\S]*)\1$/.exec(value)
80
+ return quoted === null ? value : quoted[2]
81
+ }
82
+
83
+ /**
84
+ * Register the bundled skill into the harness skill registry.
85
+ * @param {import('@deepseek-ai/cordis').Context} ctx - plugin context.
86
+ */
87
+ export function apply(ctx) {
88
+ const source = readFileSync(new URL('SKILL.md', SKILL_DIR), 'utf8')
89
+ const { fields, body } = parseFrontmatter(source)
90
+
91
+ ctx.skills.register({
92
+ name: typeof fields.name === 'string' ? fields.name : 'musicbee',
93
+ description:
94
+ typeof fields.description === 'string' && fields.description !== ''
95
+ ? fields.description
96
+ : FALLBACK_DESCRIPTION,
97
+ ...(typeof fields.whenToUse === 'string' ? { whenToUse: fields.whenToUse } : {}),
98
+ content: body.trim(),
99
+ source: 'bundled',
100
+ path: fileURLToPath(new URL('SKILL.md', SKILL_DIR)),
101
+ resourceBase: { kind: 'directory', path: fileURLToPath(SKILL_DIR) },
102
+ metadata: { triggers: fields.triggers ?? [] },
103
+ })
104
+ }
package/package.json CHANGED
@@ -1,6 +1,47 @@
1
1
  {
2
2
  "name": "@chenhao6682108/dsh-skill-musicbee",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
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
+ "keywords": [
6
+ "deepseek",
7
+ "harness",
8
+ "dsh",
9
+ "dsh-plugin",
10
+ "skill",
11
+ "musicbee",
12
+ "playlist",
13
+ "mbp",
14
+ "id3",
15
+ "flac",
16
+ "mutagen"
17
+ ],
18
+ "license": "MIT",
19
+ "type": "module",
20
+ "main": "./lib/index.js",
21
+ "exports": {
22
+ ".": "./lib/index.js",
23
+ "./cordis.patch.yml": "./cordis.patch.yml",
24
+ "./package.json": "./package.json"
25
+ },
26
+ "files": [
27
+ "lib",
28
+ "skills",
29
+ "cordis.patch.yml",
30
+ "README.md",
31
+ "README.zh.md",
32
+ "LICENSE"
33
+ ],
34
+ "engines": {
35
+ "node": ">=24.9.0",
36
+ "dsh": ">=0.1.2-rc.1 <0.2.0"
37
+ },
38
+ "repository": {
39
+ "type": "git",
40
+ "url": "git+https://github.com/chenhao6682108/dsh-skill-musicbee.git"
41
+ },
42
+ "dsh": {
43
+ "bundle": {
44
+ "patch": "./cordis.patch.yml"
45
+ }
46
+ }
47
+ }