jypjypjypjyp/dsh-music-studio

@jypjypjypjyp/dsh-music-studio

在对话里作曲：模型按内置作曲规范写乐谱，工具校验后交给对话里的内联卡片播放与导出。

短曲（≤16 小节）一次成谱：写完整乐谱 JSON → play_score。
长曲（>16 小节）分格写，像改代码一样：score_new 建骨架（调性 / 和弦循环 / 乐器表 / 段表）→ score_edit 一次只写一格（某段 × 某乐器，拍位相对本段起算）→ score_read 随时看进度 → score_export 合成交给卡片（写齐第 1 段时导出就是样张）。
每格写完立刻体检：不在调内的音、钳位/丢弃的音，以及与已写某格逐音一致（复读开头）会被直接退回重写。

卡片只负责呈现与播放（卷帘图 + 播放条 + 导出），作曲是模型在对话里干的活；UI 全部由 @deepseek-ai/dsh-client-ui-primitives 的现成控件搭成。

本项目是「弦外」单文件音景工坊的 DSH 插件形态。音频引擎（2012 行纯逻辑、无 DOM 依赖）在主仓库构建时从那个单文件网页抽取；本仓库带着已生成的引擎，因此可以脱离主仓库独立构建与安装。

怎么装

dsh plugin --profile web add github:jypjypjypjyp/dsh-music-studio
dsh plugin --profile web remove @jypjypjypjyp/dsh-music-studio   # 卸载

装完必须重启服务：插件行是启动时装配进 cordis 树的
dsh web

本地开发则把上面的 github:... 换成插件包路径（dsh plugin --profile web add ./，必须在插件包根目录执行）。

更新到仓库最新提交（实测结论）：从 GitHub 装的依赖会被钉到具体提交，pnpm update （含 --latest）都挪不动它，必须卸了重装：

dsh plugin --profile web remove @jypjypjypjyp/dsh-music-studio
dsh plugin --profile web add github:jypjypjypjyp/dsh-music-studio

改客户端代码不必重启：pnpm watch（tsdown --watch）重写 lib/client.js 后，@deepseek-ai/dsh-client-hmr 会把新包热替换进运行中的页面。

怎么构建

pnpm install
pnpm build        # = （有引擎真源就抽取）+ tsdown（宿主半 ESM + 客户端半 CJS 工厂）
pnpm test         # = 构建 + 类型检查 + 8 条判据

引擎从哪来

src/engine.js 是生成物，不要直接编辑。它的唯一真源是主仓库的 index.html：引擎写在该文件的 /* ==ENGINE-START== / 与 / ==ENGINE-END== / 之间（2012 行纯逻辑，不含任何 DOM 引用），由 scripts/extract-engine.mjs 抽出并在末尾追加导出语句与一份手写 .d.ts。

- 在主仓库里：pnpm build 每次重新抽取，test/verify-engine-copy.mjs 守着「生成物与 index.html 的引擎块逐字节相同」。这条成立时，跑在 index.html 上的 141 项引擎验收就自动覆盖了插件里的引擎。
- 在本仓库（独立发布版）里：没有 index.html，抽取脚本会大声跳过并继续使用已提交的 src/engine.js，判据 1 打印 SKIP 而不是假装通过。改引擎请回主仓库改。

怎么装 / 卸

见上方「怎么装」。本地开发与从 GitHub 安装共用同一条命令，只换依赖来源。

结构

| 文件 | 职责 |
|---|---|
| src/engine.js / engine.d.ts | 生成物：index.html 的引擎 + 导出与类型 |
| src/shared/score-info.ts | 乐谱读数：countEvents / fmtDur / usedTimbres / isRenderable |
| src/index.ts | 宿主半：常驻提示词段 + 五个乐谱工具 + music-studio skill |
| src/tool.ts | 工具定义：play_score（短曲一次成谱）+ score_new / score_read / score_edit / score_export（长篇工作流）；校验 / 钳位 / 把规范化乐谱投影进结果 meta |
| SKILL.md | 作曲手艺：乐谱格式、32 音色、拍号、律动、音乐性、修订流程 |
| src/check.ts | 长篇判据：调性解析、调外音、重复指纹、逐格钳位 |
| src/draft.ts | 长篇草稿：骨架校验、进度视图、落格、合成与裁剪 |
| src/client/index.tsx | 客户端半：注册 tool.call.toolview（key = play_score 与 score_export，同一个卡片） |
| src/client/Card.tsx | 卡片：标题行 + 卷帘图 + 播放条 + 导出 |
| src/client/roll.ts | 卷帘图与播放头自绘（搬自 index.html 的 drawRoll） |
| src/client/audio.ts | 播放排程（搬自 index.html 的滚动排程，含实测常数） |
| src/client/theme.ts | 明暗判定（量 --dsw-alias-bg-base 亮度）+ 音轨配色 |
| src/client/card.module.css | 只放布局；视觉值一律取 --dsw- 令牌 |

样式约束（硬要求，有判据守着）

- 控件一律复用 @deepseek-ai/dsh-client-ui-primitives，不重造。用到的导出名必须在本机运行时的 123 个名单里（test/verify-card-surface.mjs 守这条，防版本漂移变成 undefined）。
- 自写 CSS 只允许布局属性；一切视觉值必须是 --dsw- 令牌，不许出现字面颜色/字号/阴影。
- 唯一豁免是 theme.ts 里那张音轨配色表：它来自 index.html，是用 CIE Lab ΔE76 算过的（两两最小 25.4 / 25.1、相对底色最低对比度 4.65:1 / 3.70:1，见 tools/audit-palette.py）。DSH 只有 state- 那几个语义色，没有可互相区分的分类色，所以卷帘图的轨道色必须自带。

判据一览

| 判据 | 脚本 | 守什么 |
|---|---|---|
| 1 | test/verify-engine-copy.mjs | 引擎与 index.html 逐字节一致（主仓库；独立发布版打印 SKIP） |
| 2 | ../verify-engine.mjs | 现有 141 项引擎验收仍全绿 |
| 3 | test/verify-score-contract.mjs | 乐谱校验三分支：合法通过 / 越界钳位且明说 / 结构错退回 |
| 4 | test/verify-skill-timbres.mjs | SKILL.md 的音色、拍号、律动清单与引擎一致 |
| 5 | test/verify-card-surface.mjs | 只用本机存在的组件；无跨插件值导入；无字面视觉值 |
| 6 | test/verify-theme-color.mjs | 明暗判定的颜色解析（DSH 令牌是 8 位带 alpha 的十六进制，只认 3/6 位会永远走兜底） |
| 7 | test/verify-host-load.mjs | 宿主半冷加载：apply 不抛、注册物形状正确、presenter 是纯函数 |
| 8 | test/verify-groove.mjs | 律动真的生效：乐谱写 swing8_2，半拍上的音必须被挪；名字写错必须明说不许静默忽略 |
| 9 | pnpm exec tsc --noEmit | 对着真实的 DSH 类型校验（工具契约、槽位、组件 props） |