@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 的现成控件搭成。

本项目是主仓库里那份单文件音景网页（index.html）的 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-* 那几个语义色，没有可互相区分的分类色，所以卷帘图的轨道色必须自带。

支持的 DSH 版本

0.1.5 与 0.1.7 用同一份构建同时支持（2026-09-28 起）。两版的差异集中在客户端 primitives 的 导出名上，最容易踩的是图标：0.1.5 叫 IconPlayOutline16，0.1.7 把 16 后缀删了、 改成 IconPlayOutline / …Regular / …Medium / …Artwork。 取错名字不会报错，只会拿到 undefined；React 拿到 undefined 的组件类型会在渲染时抛错， 整张卡片当场消失（0.1.7 上播放卡「不见了」就是这么来的）。

规则只有一条：静态导入的名字必须两版都有；只在一版存在的，只能走 src/client/icons.ts 的 pick 表。 pick 按存在性取名（新版写法优先、旧版兜底），兜底顺序在两版上都不会取空。

怎么保证不退化：

手段	守什么
test/verify-card-surface.mjs 5a	任何 primitives 静态导入的名字必须在「新版 + 0.1.5」两份名单里都在
test/verify-card-surface.mjs 5a-2	pick 表每一组都要在新旧两份名单里各命中一个
test/verify-icons-resolve.mjs	拿两份真实导出名单各造一个桩、跑真实源码：新版世界必须解析到 …Regular、0.1.5 世界必须解析到 …16、两版都没有时必须退化成空组件（不能是 undefined）
两份名单	docs/dsh-plugin-research/platform-module-exports.json：primitives = 0.1.7 运行时、primitivesLegacy = 0.1.5；刷新方法写在 verify-card-surface.mjs 头注释里

两版都做过端到端实测（真实浏览器、各自独立 DSH_HOME 的沙箱）：写一段曲子 → 卡片渲染出卷帘图， 播放 / 停止 / 循环 / 进度 / 音量 / 下载 WAV / 导出乐谱 JSON 全部可用。

判据一览

判据	脚本	守什么
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	test/verify-icons-resolve.mjs	图标兼容层在 0.1.5 / 0.1.7 两份真实名单上都解析得出，取不到时退化成空组件
10	pnpm exec tsc --noEmit	对着真实的 DSH 类型校验（工具契约、槽位、组件 props）