@dsh-gis/dsh-video-studio-skill 0.4.0 → 0.7.2

package/skills/video-studio/scripts/scorekit.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""scorekit.py — 程序化配乐（v0.3.0）。
+"""scorekit.py — 程序化配乐（v0.7.0）。
 
 用代码写一张能贯穿整部片子的配乐：调性/和弦表、段落能量、节拍网格、律动层、
 段落过门、自动电平与"吸气"，全部由 numpy + sfxkit 现场合成，不用任何采样。
@@ -21,6 +21,30 @@
     class Score: section / plan_from_anchors / suck / render / report
     render(duration, bpm=120, key="Dm", anchors=None, sections=None, seed=7) -> (samples, report)
     save(path, x, sr=SR) / load(path, sr=SR) / selftest()
+
+v0.5 新增（配乐风格层）：
+    MUSIC_STYLES / MUSIC_STYLE_IDS           9 个配乐风格（8 个与 stylekit 同名 + legacy）
+    render_styled(duration, *, style, bpm=None, key=None, mood=None, anchors=None,
+                  sections=None, seed=7, fingerprint=None, sucks=None,
+                  music_plan=None, pace=None) -> (samples, report)
+        music_plan = stylekit.resolve_script_style(script)["music"]（非 None 时盖过 bpm/key/mood/seed）
+        pace      = stylekit 的 pacing dict（只用 min_dur+hold 合并过碎段落，不改片长）
+    render(..., style=None, mood="steady", fingerprint=None)
+        style 为 None / "legacy" 时走 v0.4 原路径（逐样本一致）；否则走风格化合成。
+    KEYS_MAJOR / KEYS_ALL                    6 个大调 + 全部 10 个调
+    spectral_centroid(x, sr=SR)              频谱质心（量"亮度"，验证风格差异用）
+
+v0.7 新增（内容指纹变奏，references/audio-variation.md §3.3）：
+    fingerprint 不再只派生音色 seed —— 同一风格换内容指纹时，结构层也稳定地变：
+      * 进行档：按指纹从 style["progressions"] 的 calm/body/drive 里另选一档
+        （整片一个偏移、climax 仍复用 drive，片内各段的进行关系保持连贯）；
+      * 和弦：每两小节一次稳定替换（i<->i7 / VI<->VI7 / III<->III7 / VII<->VII7；
+        大调侧 I<->Imaj7 / IV<->IVmaj7），不覆盖乐句末属和弦与片尾主和弦；
+      * 动机：每个 (拍, 级数, 时值) 做 ±1 级数偏移（只改级数不改节奏；问句/答句/
+        片尾三种动机独立派生，跨主音的上下行用八度偏移修正）；
+      * 鼓型：kick 最多加一记 ghost 落点（0.5 拍网格、不与现有落点重复），clap ±0.5 拍。
+    report["variation"] = {"chord_swaps", "motif_shifts", "drum_ghosts"} 记实际发生数。
+    style=None 的 legacy 路径不经过这些代码，仍然逐字节兼容（selfcheck 20 条）。
 """
 from __future__ import annotations
 
@@ -38,7 +62,7 @@ import numpy as np
 
 import sfxkit as S                      # 唯一音频依赖：numpy + sfxkit
 
-__version__ = "0.3.0"
+__version__ = "0.7.0"
 
 SR = 48000                             # 采样率（与 filmkit / sfxkit 一致）
 BEATS_PER_BAR = 4                      # 4/4
@@ -102,8 +126,30 @@ _DEGREE_TABLE = (
     ("VII", 10, (0, 4, 7, 12), ""),
     ("I", 0, (0, 4, 7, 12), ""),          # 结尾大三和弦（皮卡迪三度）
     ("sus2", 0, (0, 2, 7, 12), "sus2"),   # 悬留色彩，过门/段首可用
+    # ---- v0.5：大调级数与七和弦色彩。只允许在表尾追加；前 10 项顺序不许动（_build_key 依赖） ----
+    ("ii", 2, (0, 3, 7, 12), "m"),
+    ("iii", 4, (0, 3, 7, 12), "m"),
+    ("IV", 5, (0, 4, 7, 12), ""),
+    ("vi", 9, (0, 3, 7, 12), "m"),
+    ("vii", 11, (0, 3, 6, 12), "dim"),
+    ("sus4", 0, (0, 5, 7, 12), "sus4"),
+    ("Imaj7", 0, (0, 4, 7, 11), "maj7"),
+    ("ii7", 2, (0, 3, 7, 10), "m7"),
+    ("iii7", 4, (0, 3, 7, 10), "m7"),
+    ("IVmaj7", 5, (0, 4, 7, 11), "maj7"),
+    ("V7", 7, (0, 4, 7, 10), "7"),
+    ("vi7", 9, (0, 3, 7, 10), "m7"),
+    ("i7", 0, (0, 3, 7, 10), "m7"),
+    # ---- v0.7：和弦替换用的七和弦色彩。同根音、同三音，只把五度后的音换成小七度；
+    # 只允许在表尾追加（前 10 项顺序被 _build_key / 老报告依赖），供 _CHORD_SWAPS 使用。 ----
+    ("VI7", 8, (0, 4, 7, 10), "7"),
+    ("III7", 3, (0, 4, 7, 10), "7"),
+    ("VII7", 10, (0, 4, 7, 10), "7"),
 )
 
+# 级数名 -> 定义行（旋律生成/mood 色彩/自测校验用；只读映射，不参与 _build_key）
+_DEGREE_BY_NAME = {row[0]: row for row in _DEGREE_TABLE}
+
 
 # ============================================================================
 # 小工具（全部确定性、无副作用）
@@ -177,7 +223,8 @@ def _build_key(root_name: str, root_pc: int, accidentals: str, cn_name: str) ->
     for degree, base, intervals, quality in _DEGREE_TABLE:
         notes = [_semi_note(root_pc, 3, base + iv, names) for iv in intervals]
         bass_pc = (root_pc + base) % 12
-        suffix = {"m": "m", "dim": "dim", "sus2": "sus2", "": ""}[quality]
+        suffix = {"m": "m", "dim": "dim", "sus2": "sus2", "sus4": "sus4",
+                  "maj7": "maj7", "m7": "m7", "7": "7", "": ""}[quality]
         chords[degree] = {
             "degree": degree,
             "name": f"{names[bass_pc]}{suffix}",
@@ -204,6 +251,32 @@ KEYS = {
     "Em": _build_key("E", 4, "sharp", "E 小调"),
 }
 
+# 大调三档和声进行（v0.5）。小调那边 PROGRESSIONS 保持原样：legacy 路径只读 PROGRESSIONS。
+PROGRESSIONS_MAJOR = {
+    "calm": ("I", "vi", "IV", "V"),
+    "body": ("I", "V", "vi", "IV"),
+    "drive": ("I", "IV", "V", "I"),
+}
+
+# v0.5：6 个大调（与 stylekit.MAJOR_KEYS 同名同义）。用同一个 _build_key 构建，
+# 语义与小调键完全一致（级数表 -> 和弦名/低音/音名）；只是 progression 换成大调级数。
+# 写法按惯例挑：C/F/Bb 用降号、G/D/A 用升号。
+KEYS_MAJOR = {
+    "C": _build_key("C", 0, "flat", "C 大调"),
+    "G": _build_key("G", 7, "sharp", "G 大调"),
+    "D": _build_key("D", 2, "sharp", "D 大调"),
+    "F": _build_key("F", 5, "flat", "F 大调"),
+    "A": _build_key("A", 9, "sharp", "A 大调"),
+    "Bb": _build_key("Bb", 10, "flat", "Bb 大调"),
+}
+for _kname in KEYS_MAJOR:
+    KEYS_MAJOR[_kname]["progression"] = dict(PROGRESSIONS_MAJOR)
+del _kname
+
+# 全部可用调：4 个小调 + 6 个大调。KEYS 本身保持 v0.4 的 4 个小调不变（兼容性锚点）。
+KEYS_ALL = dict(KEYS)
+KEYS_ALL.update(KEYS_MAJOR)
+
 
 # ============================================================================
 # 电平测量（简化 K 加权；只用于段落间相对电平匹配与报告，不追求 BS.1770 精度）
@@ -220,6 +293,10 @@ def _decimate_mono(x: np.ndarray, k: int = 4) -> np.ndarray:
 def _moving_avg(v: np.ndarray, w: int) -> np.ndarray:
     """移动平均（边界复制），O(n)，用来做"一阶高通/低通"的近似。"""
     w = max(2, int(w))
+    if len(v) == 0:
+        # 空输入：np.pad(mode="edge") 对空数组直接抛 "can't extend empty axis 0"，
+        # 而空数组只在 duration*sr < 4（不足 4 个采样）时出现（duration=1e-6 实测崩这）。
+        return np.zeros(0, dtype=np.float64)
     pad = w // 2
     vp = np.pad(v, (pad, w - pad), mode="edge")
     c = np.cumsum(vp)
@@ -335,6 +412,7 @@ class _Bank:
         self._cache: dict = {}
         self._pad_cores: dict = {}
         self._pad_envs: dict = {}
+        self._str_cores: dict = {}
         self._pad_n = max(16, _ns(self.bar_s * 1.02 + 1.3, self.sr))
         self._pad_dur = self.bar_s * 1.02
         # 鼓组：预渲染几套变体，交替使用，避免机械重复
@@ -565,6 +643,211 @@ class _Bank:
         self._cache[key] = tex
         return tex
 
+
+    # ---------------- v0.5 风格化音色（只用已有原语组合；不碰老乐器的 RNG 序列） ----------------
+    #
+    # 三个约定，保证 legacy 逐样本不变：
+    #   1) 每个新音色都走 self._cached(...) / self._cache，种子用 self._seed("<新名字>", ...)，
+    #      名字前缀与老乐器不重叠，老乐器一次都不读新缓存；
+    #   2) 不在 __init__ 里预渲染任何新素材（既有 rng 调用次序不变）；
+    #   3) 新方法只在 render_styled 里被调用。
+    def strings(self, chord: dict, bright: float, attack: float, release: float = 0.7,
+                octave: int = 0) -> np.ndarray:
+        """弦乐铺底：5 声部超级锯齿（detune 0.06）过低通，比合成器 pad 更宽、更"有机"。"""
+        key = ("strings", chord["name"], int(round(bright * 10)),
+               int(round(attack * 100)), int(octave))
+        hit = self._cache.get(key)
+        if hit is not None:
+            return hit
+        core = self._strings_core(chord, bright, octave)
+        env = self._pad_env(attack, release)
+        tex = self._edge_fade(_f32(core * env[:, None]), 0.002, 0.02)
+        self._cache[key] = tex
+        return tex
+
+    def _strings_core(self, chord: dict, bright: float, octave: int) -> np.ndarray:
+        key = ("strcore", chord["name"], int(round(bright * 10)), int(octave))
+        hit = self._str_cores.get(key)
+        if hit is not None:
+            return hit
+        names = [_up(nt, octave) for nt in chord["notes"]] if octave else list(chord["notes"])
+        n = self._pad_n
+        out = np.zeros((n, 2), np.float32)
+        for c in range(2):
+            g = S.rng(self._seed("strings", chord["name"], int(round(bright * 10)), octave, c))
+            acc = np.zeros(n, np.float64)
+            for nt in names:
+                acc += S.supersaw(S.hz(nt), n, voices=5, detune=0.06, seed=g, sr=self.sr)
+            acc = S.lowpass(acc, 420.0 + 2600.0 * bright, 0.8, sr=self.sr)
+            acc = S.highpass(acc, 70.0, sr=self.sr)
+            out[:, c] = _f32(acc)
+        out *= np.float32(1.9 / max(1, len(names)))
+        self._str_cores[key] = out
+        return out
+
+    def cello(self, note: str, dur: float, bright: float) -> np.ndarray:
+        """大提琴式低音：锯齿 + 脉冲、带一点揉弦，慢起音。"""
+        key = ("cello", note, round(float(dur), 3), int(round(bright * 10)))
+        return self._cached(key, lambda: self._make_cello(note, dur, bright))
+
+    def _make_cello(self, note: str, dur: float, bright: float) -> np.ndarray:
+        f = S.hz(note)
+        n = _ns(dur + 0.06, self.sr)
+        t = _t(n, self.sr)
+        vib = 1.0 + 0.0045 * np.sin(2.0 * np.pi * 5.1 * t)
+        osc = (0.70 * S.saw(f * vib, n, sr=self.sr)
+               + 0.35 * S.pulse(f * vib * 1.001, n, 0.42, sr=self.sr))
+        x = S.lowpass(osc, 260.0 + 1500.0 * bright, 1.1, sr=self.sr)
+        env = np.minimum(1.0, t / 0.025) * np.clip((dur + 0.05 - t) / 0.06, 0.0, 1.0)
+        x = np.tanh(x * 1.6) * 0.5 * env
+        return self._edge_fade(_f32(x), 0.002, 0.01)
+
+    def sub_bass(self, note: str, dur: float) -> np.ndarray:
+        """808 式超低音：正弦轻微下滑 + tanh 饱和（lo-fi / 电子底的"地基"）。"""
+        key = ("subbass", note, round(float(dur), 3))
+        return self._cached(key, lambda: self._make_sub_bass(note, dur))
+
+    def _make_sub_bass(self, note: str, dur: float) -> np.ndarray:
+        f = S.hz(note)
+        d = float(min(1.2, max(0.08, dur)))
+        n = _ns(d + 0.08, self.sr)
+        t = _t(n, self.sr)
+        fr = f + (f * 1.03 - f) * np.exp(-t / 0.04)
+        x = S.sine(fr, n, sr=self.sr) * np.exp(-t / max(0.08, d * 0.55))
+        x = np.tanh(x * 1.8) * 0.8 * np.minimum(1.0, t / 0.003)
+        return self._edge_fade(_f32(x), 0.001, 0.01)
+
+    def pulse_bass(self, note: str, dur: float, bright: float) -> np.ndarray:
+        """脉冲贝斯：方波为主 + 时变低通，比老 bass 更"电子"。"""
+        key = ("pulsebass", note, round(float(dur), 3), int(round(bright * 10)))
+        return self._cached(key, lambda: self._make_pulse_bass(note, dur, bright))
+
+    def _make_pulse_bass(self, note: str, dur: float, bright: float) -> np.ndarray:
+        f = S.hz(note)
+        n = _ns(dur + 0.07, self.sr)
+        t = _t(n, self.sr)
+        osc = (0.80 * S.pulse(f, n, 0.34, sr=self.sr)
+               + 0.35 * S.saw(f * 1.002, n, sr=self.sr))
+        cut = 190.0 + (420.0 + 1700.0 * bright) * np.exp(-t / 0.1)
+        x = S.tv_filter(osc, "lowpass", cut, 1.0, block=64, sr=self.sr)
+        env = np.minimum(1.0, t / 0.004) * np.clip((dur + 0.05 - t) / 0.05, 0.0, 1.0)
+        x = np.tanh(x * 1.7) * 0.55 * env
+        return self._edge_fade(_f32(x), 0.001, 0.005)
+
+    def pluck_note(self, note: str, dur: float, bright: float) -> np.ndarray:
+        """Karplus-Strong 拨弦（sfxkit.pluck）—— 民谣 / 手作的木头感。"""
+        key = ("plucknote", note, round(float(dur), 3), int(round(bright * 10)))
+        return self._cached(key, lambda: self._make_pluck(note, dur, bright))
+
+    def _make_pluck(self, note: str, dur: float, bright: float) -> np.ndarray:
+        f = S.hz(note)
+        d = float(min(0.9, max(0.12, dur)))
+        x = S.pluck(f, d, brightness=_clip01(0.35 + 0.55 * bright), decay=0.9962,
+                    seed=self._seed("pluck", note, int(round(bright * 10))), sr=self.sr)
+        x = np.asarray(x, dtype=np.float64)
+        want = _ns(d, self.sr)
+        if len(x) < want:
+            x = np.pad(x, (0, want - len(x)))
+        return self._edge_fade(_f32(x * 0.9), 0.0005, 0.01)
+
+    def epiano(self, note: str, dur: float) -> np.ndarray:
+        """电钢：FM 钟的变体 + 低八度正弦托底（杂志 / lo-fi 的"暖"）。"""
+        key = ("epiano", note, round(float(dur), 3))
+        return self._cached(key, lambda: self._make_epiano(note, dur))
+
+    def _make_epiano(self, note: str, dur: float) -> np.ndarray:
+        f = S.hz(note)
+        d = float(min(3.0, max(0.25, dur)))
+        n = _ns(d, self.sr)
+        t = _t(n, self.sr)
+        idx = 1.5 * np.exp(-t / 0.12)
+        x = S.fm(f, 2.0, idx, n, sr=self.sr) * np.exp(-t / (d * 0.45))
+        x += 0.42 * S.sine(f * 0.5, n, sr=self.sr) * np.exp(-t / (d * 0.7))
+        x += 0.12 * S.fm(f * 2.0, 1.0, 0.35, n, sr=self.sr) * np.exp(-t / 0.25)
+        x *= np.minimum(1.0, t / 0.003)
+        return self._edge_fade(_f32(x * 0.6), 0.001, 0.02)
+
+    def marimba(self, note: str, dur: float) -> np.ndarray:
+        """马林巴：正弦基音 + 很短的 FM 敲击泛音。"""
+        key = ("marimba", note, round(float(dur), 3))
+        return self._cached(key, lambda: self._make_marimba(note, dur))
+
+    def _make_marimba(self, note: str, dur: float) -> np.ndarray:
+        f = S.hz(note)
+        d = float(min(2.0, max(0.35, dur)))
+        n = _ns(d, self.sr)
+        t = _t(n, self.sr)
+        x = S.sine(f, n, sr=self.sr) * np.exp(-t / 0.30)
+        x += 0.45 * S.fm(f, 3.0, 1.1 * np.exp(-t / 0.02), n, sr=self.sr) * np.exp(-t / 0.06)
+        x += 0.20 * S.sine(4.0 * f, n, sr=self.sr) * np.exp(-t / 0.05)
+        x *= np.minimum(1.0, t / 0.0015)
+        return self._edge_fade(_f32(x * 0.7), 0.0008, 0.02)
+
+    def glock(self, note: str, dur: float = 1.0) -> np.ndarray:
+        """钟琴：高比率 FM + 非谐波正弦，短促闪亮（vivid 的"活力"）。"""
+        key = ("glock", note, round(float(dur), 2))
+        return self._cached(key, lambda: self._make_glock(note, dur))
+
+    def _make_glock(self, note: str, dur: float) -> np.ndarray:
+        f = S.hz(note)
+        d = float(min(1.6, max(0.25, dur)))
+        n = _ns(d, self.sr)
+        t = _t(n, self.sr)
+        x = S.fm(f, 3.5, 1.8 * np.exp(-t / 0.09), n, sr=self.sr) * np.exp(-t / 0.28)
+        x += 0.30 * S.sine(2.76 * f, n, sr=self.sr) * np.exp(-t / 0.16)
+        x *= np.minimum(1.0, t / 0.001)
+        return self._edge_fade(_f32(x * 0.55), 0.0005, 0.02)
+
+    def strings_bell(self, note: str, dur: float) -> np.ndarray:
+        """弦乐 + 钟的混合主奏：有弓弦的持续感，又有钟的起音（cinema / magazine）。"""
+        key = ("strbell", note, round(float(dur), 2))
+        return self._cached(key, lambda: self._make_strbell(note, dur))
+
+    def _make_strbell(self, note: str, dur: float) -> np.ndarray:
+        f = S.hz(note)
+        d = float(min(3.4, max(0.8, dur)))
+        n = _ns(d, self.sr)
+        t = _t(n, self.sr)
+        g = S.rng(self._seed("strbell", note, round(d, 2)))
+        osc = S.supersaw(f, n, voices=3, detune=0.05, seed=g, sr=self.sr)
+        osc = S.lowpass(osc, 1500.0, 0.8, sr=self.sr) * np.exp(-t / (d * 0.55))
+        bell = S.fm(f, 3.5, 1.6 * np.exp(-t / 0.3), n, sr=self.sr) * np.exp(-t / (d * 0.4))
+        x = (0.55 * osc + 0.85 * bell) * np.minimum(1.0, t / 0.004)
+        return self._edge_fade(_f32(x * 0.6), 0.002, 0.03)
+
+    def brass(self, note: str, dur: float, bright: float) -> np.ndarray:
+        """铜管：锯齿 + 脉冲过带通，起音短促（epic 的"定格重音"）。"""
+        key = ("brass", note, round(float(dur), 3), int(round(bright * 10)))
+        return self._cached(key, lambda: self._make_brass(note, dur, bright))
+
+    def _make_brass(self, note: str, dur: float, bright: float) -> np.ndarray:
+        f = S.hz(note)
+        n = _ns(dur + 0.06, self.sr)
+        t = _t(n, self.sr)
+        osc = (0.85 * S.saw(f, n, sr=self.sr)
+               + 0.40 * S.pulse(f * 1.001, n, 0.42, sr=self.sr))
+        x = S.tv_filter(osc, "lowpass", 900.0 + 2600.0 * bright, 1.2, block=64, sr=self.sr)
+        x = S.bandpass(x, 900.0 + 1200.0 * bright, 0.8, sr=self.sr)
+        env = np.minimum(1.0, t / 0.035) * np.clip((dur + 0.04 - t) / 0.06, 0.0, 1.0)
+        x = np.tanh(x * 1.5) * 0.5 * env
+        return self._edge_fade(_f32(x), 0.002, 0.01)
+
+    def stab(self, note: str, dur: float, bright: float) -> np.ndarray:
+        """和弦短切音：极短带通脉冲，琶音层用它做"打点"。"""
+        key = ("stab", note, round(float(dur), 3), int(round(bright * 10)))
+        return self._cached(key, lambda: self._make_stab(note, dur, bright))
+
+    def _make_stab(self, note: str, dur: float, bright: float) -> np.ndarray:
+        f = S.hz(note)
+        d = float(min(0.6, max(0.12, dur)))
+        n = _ns(d, self.sr)
+        t = _t(n, self.sr)
+        osc = (0.70 * S.pulse(f, n, 0.30, sr=self.sr)
+               + 0.50 * S.saw(f * 1.003, n, sr=self.sr))
+        x = S.bandpass(osc, 1000.0 + 2400.0 * bright, 1.1, sr=self.sr) * np.exp(-t / 0.06)
+        x *= np.minimum(1.0, t / 0.001)
+        return self._edge_fade(_f32(x * 0.8), 0.0005, 0.008)
+
     # ---------------- 效果素材 ----------------
     def sub_boom(self, dur: float = 2.2, f0: float = 55.0, f1: float = 30.0) -> np.ndarray:
         """低频轰鸣：音高下滑的正弦（重击的"地基"）。"""
@@ -693,7 +976,7 @@ class Score:
         _require(isinstance(bpm, (int, float)) and math.isfinite(float(bpm))
                  and float(bpm) > 0.0,
                  f"bpm 必须是有限正数，收到 {bpm!r}")
-        _require(key in KEYS, f"未知调性 {key!r}；可选：{'/'.join(KEYS)}")
+        _require(key in KEYS_ALL, f"未知调性 {key!r}；可选：{'/'.join(KEYS_ALL)}")
         self.duration = float(duration)
         self.bpm = float(bpm)
         self.key = key
@@ -710,7 +993,7 @@ class Score:
     # ---------------- 公开属性 ----------------
     @property
     def k(self) -> dict:
-        return KEYS[self.key]
+        return KEYS_ALL[self.key]
 
     def __repr__(self) -> str:  # 只用于调试输出
         return (f"Score(duration={self.duration:g}, bpm={self.bpm:g}, key={self.key!r}, "
@@ -1153,7 +1436,10 @@ class Score:
         peak = float(np.max(np.abs(master))) if n else 0.0
         if peak > 1e-9:
             master *= np.float32(_db_amp(TARGET_PEAK_DB) / peak)
-        peak_db = float(20.0 * math.log10(max(float(np.max(np.abs(master))), 1e-12)))
+        # 亚采样时长（duration*sr < 1）时 master 是 (0,2)：np.max 对空数组直接抛
+        # "zero-size array to reduction operation maximum"（duration=1e-6 实测崩这）。
+        peak_db = (float(20.0 * math.log10(max(float(np.max(np.abs(master))), 1e-12)))
+                   if n else -240.0)
         lufs = _approx_lufs(master, self.sr)
         meas = [{"name": s["name"], "start": round(s["start"], 3), "end": round(s["end"], 3),
                  "energy": round(s["energy"], 3), "gain_db": round(lv["gain"], 2),
@@ -1162,7 +1448,7 @@ class Score:
             "rendered": True,
             "peak_dbfs": round(peak_db, 2),
             "lufs_approx": round(lufs, 1),
-            "dc_max": round(float(np.max(np.abs(master.mean(axis=0)))), 9),
+            "dc_max": round(float(np.max(np.abs(master.mean(axis=0)))), 9) if n else 0.0,
             "render_s": round(time.perf_counter() - t_start, 3),
             "measured_sections": meas,
         }
@@ -1327,7 +1613,7 @@ class Score:
         plan = self._build_plan()
         rep = {
             "version": 1,
-            "generator": f"scorekit {__version__}",
+            "generator": "scorekit",
             "bpm": self.bpm,
             "key": self.key,
             "key_name": self.k["name"],
@@ -1358,6 +1644,1392 @@ class Score:
         return rep
 
 
+
+# ============================================================================
+# v0.5 配乐风格层（MUSIC_STYLES）：一个 style id = 一种"配乐性格"
+# ============================================================================
+#
+# 为什么要这一层：v0.4 的配乐只有一套和声进行 / 一套动机 / 一张 energy 查表，
+# 所以「不管什么内容，听众听到的都是同一首曲子的不同时长」。v0.5 把"写什么"拆成
+# 风格包：和弦进行、动机、鼓型、音色、空间、动态各自成表，同一部片的配乐由 style 决定。
+#
+# 与 stylekit.STYLES 的关系：
+#   * 本模块不 import stylekit（scorekit 要能单独拷走运行，且 stylekit 是本模块的上游）；
+#     style id 与调池手工对齐，selftest 在 stylekit 存在时会交叉核对（缺失则 skip）；
+#   * stylekit 管"策展层"（BPM 梯度 / 调池 / 情绪），这里管"合成层"（和弦 / 鼓型 / 音色 /
+#     空间 / 动态），两边用同一个 style id 对齐。
+#
+# 数据契约（每个风格一个纯数据 dict，无 RNG 副作用）：
+#   bpm_hint      仅供文档 / CLI 显示；真正 BPM 由 stylekit 决定后传给 render_styled
+#   keys          调池（与 STYLES[sid]["music"]["keys"] 一致；不在池里的调也能渲，只是不"正宗"）
+#   progressions  {"calm"/"body"/"drive": 级数元组}，级数必须在 _DEGREE_TABLE 里
+#   motif         {"q"/"a"/"end": ((拍, 级数, 时值拍), ...)}：级数相对主音，供主奏轮换
+#   layers        层 -> 最低能量（0~1）；过线才出现，进出各花 1 小节渐入渐出
+#   voices        {"pad"/"bass"/"arp"/"lead": 音色名}，可选值见 _STYLE_VOICES
+#   lead_cycle    主奏音色轮换表（每 phrase_bars 轮换一个）
+#   drums         {"calm"/"body"/"drive"/"climax": {kick,hat,clap,bass,arp}}
+#   space         {"delay_beats","delay_db","taps"} 乒乓延迟（拍为单位）
+#   phrase_bars   4 / 8
+#   duck          {"bass","pad"} 侧链深度
+#   level_span_db 段落能量 -> 电平的跨度（dB）；8.5 与 legacy 的 energy_target_db 同口径
+#   swing         0.0 / 0.08~0.16：奇数列踩镲与琶音延后（拍），只改位置不改 RNG 调用次数
+
+MUSIC_STYLES = {
+    # 科技深蓝：电子、切分、拨弦琶音；小调，四四拍推进
+    "tech-deep": {
+        "label": "科技深蓝",
+        "bpm_hint": (104, 112, 120),
+        "keys": ("Dm", "Am", "Em", "Cm"),
+        "progressions": {
+            "calm": ("i", "VI", "iv", "v"),
+            "body": ("i", "VI", "III", "VII"),
+            "drive": ("i", "VII", "VI", "V"),
+        },
+        "motif": {
+            "q": ((0.0, "v", 0.75), (1.0, "i", 0.75), (2.0, "III", 0.75), (3.0, "iv", 1.75),
+                  (5.0, "III", 0.75), (6.0, "v", 0.75), (7.0, "i", 1.5)),
+            "a": ((0.0, "v", 0.75), (1.0, "i", 0.75), (2.0, "III", 0.75), (3.0, "v", 0.75),
+                  (4.0, "VII", 2.0)),
+            "end": ((0.0, "v", 1.0), (1.5, "i", 1.0), (2.5, "III", 1.5), (4.0, "i", 3.0)),
+        },
+        "layers": {"pad": 0.0, "bass": 0.24, "kick": 0.36, "hat": 0.46,
+                   "arp": 0.54, "melody": 0.66, "shine": 0.86},
+        "voices": {"pad": "pad_saw", "bass": "pulse", "arp": "pluck", "lead": "bell"},
+        "lead_cycle": ("bell", "marimba"),
+        "drums": {
+            "calm": {"kick": (), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "body": {"kick": (0.0, 2.0), "hat": 1.0, "clap": (), "bass": "half", "arp": 0.5},
+            "drive": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.5, "clap": (1.0, 3.0),
+                      "bass": "off8", "arp": 0.25},
+            "climax": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                       "bass": "16", "arp": 0.25},
+        },
+        "space": {"delay_beats": 0.75, "delay_db": -15.0, "taps": 3},
+        "phrase_bars": 4,
+        "duck": {"bass": 0.44, "pad": 0.30},
+        "level_span_db": 8.5,
+        "swing": 0.0,
+    },
+    # 杂志暖白：大调七和弦、电钢、大提琴贝斯；慢速、留白多
+    "magazine": {
+        "label": "杂志暖白",
+        "bpm_hint": (88, 92, 96, 100),
+        "keys": ("C", "G", "D", "F"),
+        "progressions": {
+            "calm": ("Imaj7", "vi7", "ii7", "V7"),
+            "body": ("I", "vi", "IV", "V"),
+            "drive": ("I", "IV", "V", "vi"),
+        },
+        "motif": {
+            "q": ((0.0, "V", 0.9), (0.9, "VI", 0.9), (1.8, "V", 0.9), (2.7, "III", 0.9),
+                  (3.5, "I", 1.5), (5.0, "ii", 0.9), (5.9, "III", 0.9), (6.8, "V", 2.2)),
+            "a": ((0.0, "V", 0.9), (0.9, "VI", 0.9), (1.8, "iii", 0.9), (2.7, "ii", 0.9),
+                  (3.5, "I", 1.5), (5.0, "III", 0.9), (6.0, "V", 2.4)),
+            "end": ((0.0, "V", 1.2), (1.5, "VI", 0.9), (2.5, "V", 1.0), (3.5, "I", 3.0)),
+        },
+        "layers": {"pad": 0.0, "bass": 0.30, "kick": 0.42, "hat": 0.52,
+                   "arp": 0.50, "melody": 0.30, "shine": 0.90},
+        "voices": {"pad": "strings", "bass": "cello", "arp": "epiano", "lead": "celesta"},
+        "lead_cycle": ("celesta", "strings_bell"),
+        "drums": {
+            "calm": {"kick": (), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "body": {"kick": (0.0, 2.0), "hat": 1.0, "clap": (), "bass": "half", "arp": 0.5},
+            "drive": {"kick": (0.0, 2.0), "hat": 0.5, "clap": (1.0, 3.0),
+                      "bass": "off8", "arp": 0.5},
+            "climax": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                       "bass": "off8", "arp": 0.25},
+        },
+        "space": {"delay_beats": 1.0, "delay_db": -17.0, "taps": 2},
+        "phrase_bars": 8,
+        "duck": {"bass": 0.34, "pad": 0.24},
+        "level_span_db": 7.0,
+        "swing": 0.0,
+    },
+    # 手绘纸感：木吉他拨弦、马林巴、轻微摇摆；大调，温暖
+    "paper": {
+        "label": "手绘纸感",
+        "bpm_hint": (84, 88, 92),
+        "keys": ("G", "D", "C"),
+        "progressions": {
+            "calm": ("I", "IV", "vi", "V"),
+            "body": ("I", "IV", "V", "vi"),
+            "drive": ("I", "V", "IV", "I"),
+        },
+        "motif": {
+            "q": ((0.0, "I", 1.0), (1.0, "III", 1.0), (2.0, "V", 1.0), (3.0, "VI", 1.5),
+                  (4.5, "V", 0.75), (5.25, "III", 0.75), (6.0, "I", 2.0)),
+            "a": ((0.0, "III", 1.0), (1.0, "V", 1.0), (2.0, "VI", 1.0), (3.0, "V", 1.5),
+                  (4.5, "III", 0.75), (5.25, "V", 0.75), (6.0, "I", 2.0)),
+            "end": ((0.0, "V", 1.0), (1.5, "VI", 1.0), (2.5, "V", 1.5), (4.0, "I", 3.5)),
+        },
+        "layers": {"pad": 0.0, "bass": 0.28, "kick": 0.50, "hat": 0.62,
+                   "arp": 0.45, "melody": 0.30, "shine": 0.88},
+        "voices": {"pad": "strings", "bass": "cello", "arp": "pluck", "lead": "marimba"},
+        "lead_cycle": ("marimba", "celesta"),
+        "drums": {
+            "calm": {"kick": (), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "body": {"kick": (0.0, 2.0), "hat": 0.5, "clap": (), "bass": "half", "arp": 0.5},
+            "drive": {"kick": (0.0, 2.0), "hat": 0.25, "clap": (1.0, 3.0),
+                      "bass": "off8", "arp": 0.25},
+            "climax": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                       "bass": "off8", "arp": 0.25},
+        },
+        "space": {"delay_beats": 0.5, "delay_db": -18.0, "taps": 2},
+        "phrase_bars": 4,
+        "duck": {"bass": 0.28, "pad": 0.22},
+        "level_span_db": 7.5,
+        "swing": 0.10,
+    },
+    # 活力撞色：大调 4/4、短切和弦、钟琴主奏；高能量、明亮
+    "vivid": {
+        "label": "活力撞色",
+        "bpm_hint": (120, 126, 132),
+        "keys": ("D", "G", "A"),
+        "progressions": {
+            "calm": ("I", "vi", "IV", "V"),
+            "body": ("I", "V", "vi", "IV"),
+            "drive": ("I", "IV", "V", "I"),
+        },
+        "motif": {
+            "q": ((0.0, "V", 0.5), (0.5, "V", 0.25), (1.0, "VI", 0.5), (1.5, "V", 0.5),
+                  (2.0, "III", 0.5), (2.5, "I", 1.5), (4.0, "V", 0.5), (4.5, "VI", 0.5),
+                  (5.0, "V", 1.0), (6.0, "I", 2.0)),
+            "a": ((0.0, "III", 0.5), (0.5, "III", 0.25), (1.0, "V", 0.5), (1.5, "III", 0.5),
+                  (2.0, "V", 0.5), (2.5, "VI", 1.5), (4.0, "V", 0.5), (5.0, "III", 1.0),
+                  (6.0, "I", 2.0)),
+            "end": ((0.0, "V", 0.5), (1.0, "VI", 0.75), (2.0, "V", 1.5), (4.0, "I", 3.0)),
+        },
+        "layers": {"pad": 0.0, "bass": 0.20, "kick": 0.30, "hat": 0.40,
+                   "arp": 0.44, "melody": 0.48, "shine": 0.78},
+        "voices": {"pad": "pad_saw", "bass": "pulse", "arp": "stab", "lead": "glock"},
+        "lead_cycle": ("glock", "bell"),
+        "drums": {
+            "calm": {"kick": (), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "body": {"kick": (0.0, 2.0), "hat": 0.5, "clap": (1.0, 3.0),
+                     "bass": "off8", "arp": 0.5},
+            "drive": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                      "bass": "16", "arp": 0.25},
+            "climax": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                       "bass": "16", "arp": 0.25},
+        },
+        "space": {"delay_beats": 0.5, "delay_db": -16.0, "taps": 3},
+        "phrase_bars": 4,
+        "duck": {"bass": 0.50, "pad": 0.32},
+        "level_span_db": 9.0,
+        "swing": 0.0,
+    },
+    # 极简黑白：只有必要的声音，长音、留白、钢片琴；慢速
+    "mono": {
+        "label": "极简黑白",
+        "bpm_hint": (60, 64, 68),
+        "keys": ("C", "F", "Am"),
+        "progressions": {
+            "calm": ("I", "IV", "I", "V"),
+            "body": ("I", "IV", "V", "IV"),
+            "drive": ("I", "IV", "V", "I"),
+        },
+        "motif": {
+            "q": ((0.0, "I", 1.5), (1.5, "III", 1.5), (3.0, "V", 2.0),
+                  (6.0, "III", 1.0), (7.0, "V", 3.0)),
+            "a": ((0.0, "V", 1.5), (1.5, "III", 1.5), (3.0, "I", 2.0),
+                  (6.0, "V", 1.0), (7.0, "I", 3.0)),
+            "end": ((0.0, "V", 2.0), (2.0, "III", 1.5), (3.5, "I", 4.0)),
+        },
+        "layers": {"pad": 0.0, "bass": 0.34, "kick": 0.55, "hat": 0.70,
+                   "arp": 0.60, "melody": 0.25, "shine": 0.92},
+        "voices": {"pad": "strings", "bass": "cello", "arp": "epiano", "lead": "celesta"},
+        "lead_cycle": ("celesta", "bell"),
+        "drums": {
+            "calm": {"kick": (), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "body": {"kick": (0.0,), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "drive": {"kick": (0.0, 2.0), "hat": 1.0, "clap": (), "bass": "half", "arp": 0.5},
+            "climax": {"kick": (0.0, 2.0), "hat": 0.5, "clap": (),
+                       "bass": "half", "arp": 0.5},
+        },
+        "space": {"delay_beats": 2.0, "delay_db": -20.0, "taps": 2},
+        "phrase_bars": 8,
+        "duck": {"bass": 0.30, "pad": 0.20},
+        "level_span_db": 6.0,
+        "swing": 0.0,
+    },
+    # 电影青橙：小调、弦乐铺底、大空间；安静到爆发跨度最大
+    "cinema": {
+        "label": "电影青橙",
+        "bpm_hint": (76, 80, 84),
+        "keys": ("Dm", "Am"),
+        "progressions": {
+            "calm": ("i", "VI", "III", "VII"),
+            "body": ("i", "VII", "VI", "V"),
+            "drive": ("i", "VI", "III", "VII"),
+        },
+        "motif": {
+            "q": ((0.0, "i", 1.5), (1.5, "III", 1.0), (2.5, "iv", 2.0),
+                  (5.0, "III", 1.0), (6.0, "i", 3.0)),
+            "a": ((0.0, "III", 1.5), (1.5, "VI", 1.0), (2.5, "VII", 2.0),
+                  (5.0, "v", 1.0), (6.0, "i", 3.0)),
+            "end": ((0.0, "VI", 1.5), (1.5, "VII", 1.0), (2.5, "v", 1.5), (4.0, "i", 4.0)),
+        },
+        "layers": {"pad": 0.0, "bass": 0.26, "kick": 0.52, "hat": 0.68,
+                   "arp": 0.62, "melody": 0.30, "shine": 0.88},
+        "voices": {"pad": "strings", "bass": "cello", "arp": "epiano",
+                   "lead": "strings_bell"},
+        "lead_cycle": ("strings_bell", "celesta"),
+        "drums": {
+            "calm": {"kick": (), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "body": {"kick": (0.0,), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "drive": {"kick": (0.0, 2.0), "hat": 0.5, "clap": (), "bass": "half", "arp": 0.5},
+            "climax": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                       "bass": "off8", "arp": 0.25},
+        },
+        "space": {"delay_beats": 1.5, "delay_db": -14.0, "taps": 3},
+        "phrase_bars": 8,
+        "duck": {"bass": 0.40, "pad": 0.26},
+        "level_span_db": 10.0,
+        "swing": 0.0,
+    },
+    # 暖灰薄荷：lo-fi 摇摆、电钢、808 贝斯；轻鼓、留白
+    "lo-fi": {
+        "label": "暖灰薄荷",
+        "bpm_hint": (72, 78, 84),
+        "keys": ("C", "F", "G"),
+        "progressions": {
+            "calm": ("Imaj7", "vi7", "ii7", "V7"),
+            "body": ("Imaj7", "IVmaj7", "iii7", "vi7"),
+            "drive": ("ii7", "V7", "Imaj7", "IVmaj7"),
+        },
+        "motif": {
+            "q": ((0.0, "III", 1.0), (1.0, "V", 1.0), (2.0, "VI", 1.0), (3.0, "V", 1.0),
+                  (4.0, "I", 1.0), (5.0, "ii", 1.0), (6.0, "III", 1.0), (7.0, "I", 2.0)),
+            "a": ((0.0, "V", 1.0), (1.0, "VI", 1.0), (2.0, "V", 1.0), (3.0, "III", 1.0),
+                  (4.0, "ii", 1.0), (5.0, "III", 1.0), (6.0, "V", 1.0), (7.0, "I", 2.0)),
+            "end": ((0.0, "V", 1.0), (1.0, "VI", 1.0), (2.0, "V", 1.0), (3.0, "I", 4.0)),
+        },
+        "layers": {"pad": 0.0, "bass": 0.24, "kick": 0.40, "hat": 0.48,
+                   "arp": 0.44, "melody": 0.32, "shine": 0.90},
+        "voices": {"pad": "pad_saw", "bass": "sub", "arp": "epiano", "lead": "marimba"},
+        "lead_cycle": ("marimba", "celesta"),
+        "drums": {
+            "calm": {"kick": (), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "body": {"kick": (0.0, 2.0), "hat": 0.5, "clap": (), "bass": "half", "arp": 0.5},
+            "drive": {"kick": (0.0, 2.0), "hat": 0.5, "clap": (1.0, 3.0),
+                      "bass": "off8", "arp": 0.5},
+            "climax": {"kick": (0.0, 2.0), "hat": 0.25, "clap": (1.0, 3.0),
+                       "bass": "off8", "arp": 0.25},
+        },
+        "space": {"delay_beats": 0.75, "delay_db": -16.0, "taps": 2},
+        "phrase_bars": 4,
+        "duck": {"bass": 0.38, "pad": 0.26},
+        "level_span_db": 6.5,
+        "swing": 0.12,
+    },
+    # 深黑鎏金：小调、铜管主奏、四四拍重击；动态跨度最大
+    "epic": {
+        "label": "深黑鎏金",
+        "bpm_hint": (88, 92, 96),
+        "keys": ("Cm", "Dm"),
+        "progressions": {
+            "calm": ("i", "VI", "iv", "V"),
+            "body": ("i", "VI", "III", "VII"),
+            "drive": ("i", "VII", "VI", "V"),
+        },
+        "motif": {
+            "q": ((0.0, "i", 1.0), (1.0, "III", 1.0), (2.0, "v", 1.0), (3.0, "VI", 2.0),
+                  (5.0, "v", 1.0), (6.0, "i", 3.0)),
+            "a": ((0.0, "v", 1.0), (1.0, "VI", 1.0), (2.0, "VII", 1.0), (3.0, "V", 2.0),
+                  (5.0, "VII", 1.0), (6.0, "i", 3.0)),
+            "end": ((0.0, "VI", 1.5), (1.5, "VII", 1.0), (2.5, "v", 1.0), (3.5, "i", 4.0)),
+        },
+        "layers": {"pad": 0.0, "bass": 0.20, "kick": 0.32, "hat": 0.42,
+                   "arp": 0.50, "melody": 0.30, "shine": 0.80},
+        "voices": {"pad": "strings", "bass": "cello", "arp": "stab", "lead": "brass"},
+        "lead_cycle": ("brass", "strings_bell"),
+        "drums": {
+            "calm": {"kick": (), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "body": {"kick": (0.0, 2.0), "hat": 0.5, "clap": (), "bass": "half", "arp": 0.5},
+            "drive": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                      "bass": "16", "arp": 0.25},
+            "climax": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                       "bass": "16", "arp": 0.25},
+        },
+        "space": {"delay_beats": 0.75, "delay_db": -13.0, "taps": 3},
+        "phrase_bars": 4,
+        "duck": {"bass": 0.46, "pad": 0.34},
+        "level_span_db": 11.0,
+        "swing": 0.0,
+    },
+    # legacy：给 render_styled 用的"v0.4 近似包"（真实兼容路径不经过这里；
+    # render(style=None) / render(style="legacy") 直接走老的 Score.render()）
+    "legacy": {
+        "label": "v0.4 兼容",
+        "bpm_hint": (120,),
+        "keys": ("Dm", "Am", "Cm", "Em"),
+        "progressions": {
+            "calm": ("i", "VI", "iv", "v"),
+            "body": ("i", "VI", "III", "VII"),
+            "drive": ("i", "VII", "VI", "V"),
+        },
+        "motif": {
+            "q": ((0.0, "i", 0.9), (1.0, "v", 0.9), (2.0, "I", 0.9), (3.0, "III", 1.8),
+                  (5.0, "i", 0.9), (6.0, "VII", 0.9), (7.0, "v", 1.6)),
+            "a": ((0.0, "v", 0.9), (1.0, "i", 0.9), (2.0, "III", 0.9), (3.0, "iv", 0.9),
+                  (4.0, "v", 2.4)),
+            "end": ((0.0, "v", 0.9), (1.0, "i", 0.9), (2.0, "III", 0.9), (3.0, "iv", 1.6),
+                    (5.0, "i", 3.0)),
+        },
+        "layers": {"pad": 0.0, "bass": 0.22, "kick": 0.34, "hat": 0.44,
+                   "arp": 0.55, "melody": 0.66, "shine": 0.82},
+        "voices": {"pad": "pad_saw", "bass": "pulse", "arp": "fm", "lead": "bell"},
+        "lead_cycle": ("bell", "celesta"),
+        "drums": {
+            "calm": {"kick": (), "hat": None, "clap": (), "bass": "whole", "arp": None},
+            "body": {"kick": (0.0, 2.0), "hat": 1.0, "clap": (), "bass": "half", "arp": 0.5},
+            "drive": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                      "bass": "16", "arp": 0.25},
+            "climax": {"kick": (0.0, 1.0, 2.0, 3.0), "hat": 0.25, "clap": (1.0, 3.0),
+                       "bass": "16", "arp": 0.25},
+        },
+        "space": {"delay_beats": 0.56, "delay_db": -15.0, "taps": 3},
+        "phrase_bars": 4,
+        "duck": {"bass": 0.42, "pad": 0.30},
+        "level_span_db": 8.5,
+        "swing": 0.0,
+    },
+}
+
+MUSIC_STYLE_IDS = tuple(MUSIC_STYLES)
+LEGACY_MUSIC_STYLE = "legacy"
+
+# 情绪修饰：不改和弦功能，只改亮度 / 层数 / 鼓密度 / 主奏电平
+MOOD_IDS = ("steady", "calm", "reflective", "hopeful", "uplifting", "driving", "tense")
+_MOOD = {
+    "steady":     {"bright": 0.00, "layer": 0.00, "drum": 0.00, "lead_db": 0.0},
+    "calm":       {"bright": -0.18, "layer": 0.06, "drum": -0.06, "lead_db": -1.5},
+    "reflective": {"bright": -0.12, "layer": 0.04, "drum": -0.04, "lead_db": -1.0},
+    "hopeful":    {"bright": 0.04, "layer": -0.02, "drum": 0.00, "lead_db": 0.5},
+    "uplifting":  {"bright": 0.14, "layer": -0.05, "drum": 0.05, "lead_db": 1.0},
+    "driving":    {"bright": 0.22, "layer": -0.07, "drum": 0.07, "lead_db": 1.2},
+    "tense":      {"bright": 0.02, "layer": 0.00, "drum": 0.03, "lead_db": 0.5},
+}
+
+# 音色槽 -> 可选音色（实现见 _Bank 的 v0.5 方法；"fm" 复用老 FM 琶音）
+_STYLE_VOICES = {
+    "pad": {"pad_saw": "pad", "strings": "strings"},
+    "bass": {"pulse": "pulse", "cello": "cello", "sub": "sub"},
+    "arp": {"pluck": "pluck", "epiano": "epiano", "stab": "stab", "fm": "fm"},
+    "lead": {"bell": "bell", "celesta": "celesta", "marimba": "marimba",
+             "glock": "glock", "strings_bell": "strings_bell", "brass": "brass",
+             "epiano": "epiano"},
+}
+
+
+def _normalize_style_id(style):
+    """None / "" / "legacy" -> None（走 v0.4 原路径）；其余必须是 MUSIC_STYLES 的键。"""
+    if style is None:
+        return None
+    sid = str(style).strip()
+    if sid in ("", LEGACY_MUSIC_STYLE):
+        return None
+    _require(sid in MUSIC_STYLES, f"未知配乐风格 {style!r}；可选：{'/'.join(MUSIC_STYLE_IDS)}")
+    return sid
+
+
+def _styled_tier(energy: float) -> str:
+    """风格化四档：calm / body / drive / climax（比 legacy 多一档，给 epic / vivid 用）。"""
+    if energy < 0.40:
+        return "calm"
+    if energy < 0.70:
+        return "body"
+    if energy < 0.88:
+        return "drive"
+    return "climax"
+
+
+def _styled_layers(pack: dict, energy: float, mood: str) -> list:
+    """按"层阈值 + mood 偏移"算本段出现的层；pad 恒在（配乐不能没有和声底）。"""
+    m = _MOOD.get(mood, _MOOD["steady"])
+    out = []
+    for name in LAYER_ORDER:
+        thr = float(pack["layers"][name])
+        if name == "pad":
+            out.append(name)
+            continue
+        if name == "bass":
+            adj = 0.5 * m["layer"]
+        elif name in ("kick", "hat"):
+            adj = m["layer"] * 1.5 - m["drum"]
+        else:
+            adj = m["layer"]
+        if energy >= max(0.0, thr + adj):
+            out.append(name)
+    return out
+
+
+# ---- v0.7 内容指纹变奏（references/audio-variation.md §3.3）----------------
+# v0.6 及以前指纹只进 seed（只改音色细节）：同风格 / 同 bpm / 同调、只换内容指纹，
+# 两段配乐相关性 0.966 —— 因为和弦进行 / 动机 / 鼓型全写死。
+# v0.7 把指纹推到"结构层"：和弦做每两小节一次的稳定替换、动机级数做 ±1 稳定偏移、
+# 鼓型加 ghost 落点。三处决策全部走 _hash_int（FNV-1a，跨进程稳定），所以
+# 同指纹逐采样一致、不同指纹稳定地不同；没有引入额外随机源（变奏全部由指纹决定）。
+_VARIATION_SALT = "v0.7"
+
+# 和弦替换对：同根音、同三音，只在"三和弦 <-> 七和弦色彩"之间换（契约 §3.3 的替代级数集）
+_CHORD_SWAPS = {
+    "minor": {"i": "i7", "i7": "i", "VI": "VI7", "VI7": "VI",
+              "III": "III7", "III7": "III", "VII": "VII7", "VII7": "VII"},
+    "major": {"I": "Imaj7", "Imaj7": "I", "IV": "IVmaj7", "IVmaj7": "IV"},
+}
+
+# 动机级数邻接表：只走"调内级数"的上下各一级（只换级数，节奏 / 时值不动）。
+# 值是 ((下方级数, 八度偏移), (上方级数, 八度偏移))；跨主音时八度偏移 ±1，
+# 否则 i 下行一级会变成高 10 个半音的 VII（旋律轮廓会翻掉）。
+_MOTIF_NEIGHBORS = {
+    "minor": {
+        "i": (("VII", -1), ("ii°", 0)), "ii°": (("i", 0), ("III", 0)),
+        "III": (("ii°", 0), ("iv", 0)), "iv": (("III", 0), ("v", 0)),
+        "v": (("iv", 0), ("VI", 0)), "V": (("iv", 0), ("VI", 0)),
+        "VI": (("v", 0), ("VII", 0)), "VII": (("VI", 0), ("i", 1)),
+        "I": (("VII", -1), ("ii°", 0)), "i7": (("VII", -1), ("ii°", 0)),
+    },
+    "major": {
+        "I": (("vii", -1), ("ii", 0)), "vii": (("vi", 0), ("I", 1)),
+        "ii": (("I", 0), ("iii", 0)), "iii": (("ii", 0), ("IV", 0)),
+        "IV": (("iii", 0), ("V", 0)), "V": (("IV", 0), ("vi", 0)),
+        "vi": (("V", 0), ("vii", 0)), "VI": (("V", 0), ("VII", 0)),
+        "III": (("ii", 0), ("IV", 0)), "iv": (("iii", 0), ("V", 0)),
+        "Imaj7": (("vii", -1), ("ii", 0)), "IVmaj7": (("iii", 0), ("V", 0)),
+    },
+}
+
+# 进行档位（按"安静 -> 推进"排）；climax 复用 drive（v0.5 语义：高潮靠鼓与层数）
+_PROG_TIERS = ("calm", "body", "drive")
+
+
+def _styled_mode(pack: dict) -> str:
+    """风格包是小调还是大调：看 progressions 的主和弦写法（i/i7 = 小调，I/Imaj7 = 大调）。
+
+    调式只决定"替换对 / 级数邻接表"用哪一套；真正的调性仍由 key 决定，两者不改动。
+    """
+    degs = {str(d) for seq in pack["progressions"].values() for d in seq}
+    return "minor" if (degs & {"i", "i7"}) else "major"
+
+
+def _styled_has_fp(fingerprint) -> str:
+    """指纹归一化：None / "" -> ""（= 关掉全部结构变奏，与 v0.5 逐字节一致）。"""
+    if fingerprint is None:
+        return ""
+    s = str(fingerprint)
+    return s if s != "" else ""
+
+
+def _styled_progression(pack: dict, tier: str, mood: str, fingerprint=None) -> tuple:
+    """取该 tier 的级数进行；climax 复用 drive（高潮靠鼓与层数，不靠换和弦）。
+
+    v0.7：给了指纹时，按指纹从该风格的 progressions 里另选一档（契约 §3.3）——
+    同一风格的两部片可以拿到不同的和弦功能顺序，但调式 / 音色 / 鼓型 / 段落结构不变。
+    偏移量对整部片只有一个（哈希里不带段落号），片内各段的进行关系因此仍然连贯；
+    无指纹 -> 与 v0.5 完全同一结果（只按能量档取）。
+    """
+    progs = pack["progressions"]
+    key = tier if tier in progs else ("drive" if tier == "climax" else "body")
+    fp = _styled_has_fp(fingerprint)
+    tiers = [t for t in _PROG_TIERS if t in progs]
+    if fp and tiers and tier != "climax":      # climax 仍复用 drive（v0.5 语义：高潮靠鼓与层数）
+        base = tiers.index(key) if key in tiers else min(1, len(tiers) - 1)
+        off = _hash_int(_VARIATION_SALT, "tier", fp) % len(tiers)
+        key = tiers[(base + off) % len(tiers)]
+    return tuple(progs[key])
+
+
+def _styled_chord_rules(deg: str, j: int, nb: int, ph: int, tier: str,
+                        mood: str, is_last_sec: bool) -> str:
+    """单小节的硬规则（与 v0.5 逐字同序）：乐句末属和弦 -> mood 色彩 -> 片尾主和弦。
+
+    单独拆出来是为了让"变奏前 / 变奏后"各跑一遍：替换是否真的落地、有没有被
+    硬规则吃掉（乐句末收 V、片尾落 I）都能算清楚，report 里的计数才是真数。
+    """
+    # 每两乐句收一次属和弦（制造张力，与 legacy 的写法同源）
+    if j % ph == ph - 1 and (j // ph) % 2 == 1:
+        deg = "V"
+    # mood 色彩：hopeful 加 maj7 / sus2；tense 用 sus4 悬留
+    if mood == "hopeful":
+        if deg == "I":
+            deg = "Imaj7"
+        elif deg == "IV":
+            deg = "IVmaj7"
+        elif deg == "i":
+            deg = "i7"
+        elif j == 0 and tier == "calm":
+            deg = "sus2"
+    elif mood == "tense" and j % ph == ph - 2 and deg in ("i", "I"):
+        deg = "sus4"
+    # 片尾落主和弦（与 legacy 同口径：I = 皮卡迪三度 / 大调主）
+    if is_last_sec and nb >= 2 and j >= nb - 2:
+        deg = "I"
+    return deg
+
+
+def _styled_chords(sec: dict, si: int, secs: list, prog: tuple, pack: dict, mood: str,
+                   fingerprint=None, mode: str = "minor") -> tuple:
+    """一小节一个和弦：级数循环 + 乐句末收属和弦 + mood 色彩 + 片尾落 I。
+
+    v0.7：给了指纹时，**每两小节做一次稳定替换**（契约 §3.3）：按指纹决定替换
+    块内第 1 小节还是第 2 小节，被选中的小节在 _CHORD_SWAPS 里换成同根音的七和弦
+    色彩（该小节级数不在替代集里就跳过）。替换先于硬规则执行，所以乐句末属和弦与
+    片尾主和弦永远不被改坏（契约的"只在不冲突时替换"）。
+    返回 (和弦级数列表, 实际替换次数)；无指纹时替换次数恒 0、列表与 v0.5 逐项一致。
+    """
+    nb = len(sec["bars"])
+    ph = int(pack["phrase_bars"])
+    tier = sec["tier"]
+    is_last_sec = (si == len(secs) - 1)
+    fp = _styled_has_fp(fingerprint)
+    smap = _CHORD_SWAPS.get(mode, {})
+    out = []
+    swaps = 0
+    for j in range(nb):
+        base = prog[j % len(prog)]
+        deg = _styled_chord_rules(base, j, nb, ph, tier, mood, is_last_sec)
+        if fp and smap:
+            # 每两小节一次稳定替换：按指纹决定替换块内第 1 还是第 2 小节
+            # （该小节级数不在替代集里就跳过，不硬造不存在的替代级数）
+            pick = _hash_int(_VARIATION_SALT, "chord", fp, si, j // 2) % 2
+            if pick == (j % 2) and base in smap:
+                alt = _styled_chord_rules(smap[base], j, nb, ph, tier, mood, is_last_sec)
+                if alt != deg:                  # 被硬规则吃掉的替换不算一次替换
+                    deg = alt
+                    swaps += 1
+        out.append(deg)
+    return out, swaps
+
+
+def _styled_kick_ghost(cfg: dict, fp: str, si: int, j: int,
+                       fill_bar: bool, breath: bool):
+    """按指纹给这一小节加一个 kick ghost 落点；返回落点（拍）或 None。
+
+    ghost 只落在 0.5 拍网格上、不与 cfg["kick"] 现有落点重合；fill / breath 小节
+    只允许落在 [0, 3) 拍内（那几个位置要留给鼓加花与呼吸，契约 §3.3）。
+    每小节最多一记，1/3 的小节不加 —— 否则"每小节都多一记"会变成另一种机械。
+    """
+    used = [float(x) for x in cfg.get("kick", ())]
+    cand = []
+    for k in range(int(round(BEATS_PER_BAR / 0.5))):
+        pos = 0.5 * k
+        if any(abs(pos - u) < 1e-9 for u in used):
+            continue
+        if (fill_bar or breath) and pos >= 3.0 - 1e-9:
+            continue
+        cand.append(pos)
+    if not cand:
+        return None
+    h = _hash_int(_VARIATION_SALT, "ghost", fp, si, j)
+    if h % 3 == 0:
+        return None
+    return cand[(h >> 3) % len(cand)]
+
+
+def _styled_clap_shift(fp: str, si: int, j: int, idx: int) -> float:
+    """拍手位置的指纹位移：±0.5 拍（契约 §3.3）；1/3 不动，保留原律动的稳定感。"""
+    h = _hash_int(_VARIATION_SALT, "clap", fp, si, j, idx)
+    m = h % 3
+    return 0.0 if m == 2 else (0.5 if m == 0 else -0.5)
+
+
+def _styled_target_db(energy: float, span: float) -> float:
+    """能量 -> 相对电平（dB）。span = 最安静段到最响段的电平跨度；
+
+    span=8.5 时与 legacy 的 energy_target_db() 完全同式：-8.5 * (1 - energy)。
+    """
+    return -float(span) * (1.0 - _clip01(energy))
+
+
+def _styled_swing_shift(swing: float, step: float, k: int) -> float:
+    """摇摆：只延后"奇数细分"（不影响 RNG 调用次数，只改落点）。"""
+    if swing <= 0.0 or step >= 1.0 or (k % 2) == 0:
+        return 0.0
+    return float(swing) * min(1.0, step / 0.5)
+
+
+def _degree_note(kval: dict, degree: str, octave: int = 4) -> str:
+    """级数 -> 音名（相对主音，跨八度自动进位）。"""
+    row = _DEGREE_BY_NAME[degree]
+    return _semi_note(kval["root_pc"], int(octave), int(row[1]), kval["names"])
+
+
+def _check_voice(slot: str, voice: str) -> str:
+    """校验风格音色名并返回内部实现名（未知音色直接报错，不静默回落）。"""
+    table = _STYLE_VOICES[slot]
+    _require(voice in table, f"风格音色 {slot}={voice!r} 未知；可选：{'/'.join(table)}")
+    return table[voice]
+
+
+def _bass_texture(bank: "_Bank", voice: str, note: str, dur: float, bright: float) -> np.ndarray:
+    if voice == "cello":
+        return bank.cello(note, dur, bright)
+    if voice == "sub":
+        return bank.sub_bass(note, dur)
+    return bank.pulse_bass(note, dur, bright)
+
+
+def _arp_texture(bank: "_Bank", voice: str, note: str, bright: float, dur: float = 0.3) -> np.ndarray:
+    if voice == "pluck":
+        return bank.pluck_note(note, dur, bright)
+    if voice == "epiano":
+        return bank.epiano(note, max(0.35, dur))
+    if voice == "stab":
+        return bank.stab(note, dur, bright)
+    return bank.arp(note, bright, dur)
+
+
+def _lead_texture(bank: "_Bank", voice: str, note: str, dur: float, bright: float) -> np.ndarray:
+    if voice == "celesta":
+        return bank.celesta(note, max(2.8, dur))
+    if voice == "marimba":
+        return bank.marimba(note, max(0.6, dur))
+    if voice == "glock":
+        return bank.glock(note, max(0.5, dur))
+    if voice == "strings_bell":
+        return bank.strings_bell(note, max(1.2, dur))
+    if voice == "brass":
+        return bank.brass(note, max(0.5, dur), bright)
+    if voice == "epiano":
+        return bank.epiano(note, max(0.8, dur))
+    return bank.bell(note, max(2.4, dur))
+
+
+def _styled_motif_shift(motif, kind: str, fingerprint, style: str, mode: str) -> tuple:
+    """按指纹给动机的每个事件派生 ±1 级数偏移；返回 (事件列表, 偏移次数)。
+
+    只改级数不改节奏：拍位与时值原样保留。偏移方向按 "指纹 + 风格 + 动机类型 + 事件序号"
+    哈希派生，所以问句(q) / 答句(a) / 片尾(end) **各自独立**（契约 §3.3 的"独立派生"）：
+    同一部片里同种动机稳定，两部片不会同步变形（q 上移的片子 a 未必也上移）。
+    返回的事件是 (拍, 级数, 时值, 八度偏移)：跨主音上行 / 下行时用八度偏移修正，
+    否则"小调 i 下行一级"会变成高 10 个半音的 VII，旋律轮廓会翻掉。
+    """
+    fp = _styled_has_fp(fingerprint)
+    table = _MOTIF_NEIGHBORS.get(mode, {})
+    if not fp or not table:
+        return [(float(ev[0]), str(ev[1]), float(ev[2]), 0) for ev in motif], 0
+    # 整句的偏移方向只由 "指纹 + 风格 + 动机类型" 决定（同种动机稳定），
+    # 每个事件在±1 里取哪边由事件序号决定 —— q 与 a 的方向各自独立派生。
+    up = _hash_int(_VARIATION_SALT, "motif-dir", fp, style, kind) % 2 == 1
+    out = []
+    shifted = 0
+    for idx, ev in enumerate(motif):
+        pos, deg, dur = float(ev[0]), str(ev[1]), float(ev[2])
+        pair = table.get(deg)
+        h = _hash_int(_VARIATION_SALT, "motif", fp, style, kind, idx)
+        if pair is None:                    # 邻接表没收录的级数不动，绝不瞎编级数
+            out.append((pos, deg, dur, 0))
+            continue
+        name, oct_delta = pair[1] if (up != bool(h % 2)) else pair[0]
+        out.append((pos, name, dur, int(oct_delta)))
+        shifted += 1
+    return out, shifted
+
+
+def _emit_styled_motif(bus: "_Bus", bank: "_Bank", motif, kval: dict, voice: str,
+                       t0: float, beat: float, db: float, bright: float,
+                       fingerprint=None, style: str = "", kind: str = "",
+                       mode: str = "minor") -> int:
+    """把风格动机铺到主奏总线：级数 -> 音名，乐器由 lead_cycle 指定。
+
+    v0.7：先按指纹做级数 ±1 偏移（_styled_motif_shift）再铺；返回被偏移的事件数，
+    供 report["variation"]["motif_shifts"] 审计。无指纹时偏移数恒 0、逐音与 v0.5 相同。
+    """
+    events, shifted = _styled_motif_shift(motif, kind, fingerprint, style, mode)
+    for idx, ev in enumerate(events):
+        pos_beats = float(ev[0])
+        degree, dur_beats, oct_delta = str(ev[1]), float(ev[2]), int(ev[3])
+        note = _degree_note(kval, degree, 4 + oct_delta)
+        tex = _lead_texture(bank, voice, note, dur_beats * beat, bright)
+        pan = 0.18 if idx % 2 == 0 else -0.18
+        bus.add(tex, t0 + pos_beats * beat, db, pan)
+    return shifted
+
+
+def _styled_gate_env(n: int, secs: list, present: list, bar: float, sr: int = SR) -> np.ndarray:
+    """层进出门控：某层在相邻段缺席时，用 1 小节线性坡道渐入 / 渐出。"""
+    env = np.ones(int(n), np.float32)
+    L = max(2, _ns(bar, sr))
+    nsec = len(secs)
+    for si, sec in enumerate(secs):
+        s = max(0, min(int(n), int(round(float(sec["start"]) * sr))))
+        e = max(0, min(int(n), int(round(float(sec["end"]) * sr))))
+        if e - s < 2:
+            continue
+        if not present[si]:
+            env[s:e] = 0.0
+            continue
+        prev = present[si - 1] if si > 0 else present[si]
+        nxt = present[si + 1] if si + 1 < nsec else present[si]
+        if not prev:
+            seg = env[s:min(e, s + L)]
+            seg *= _f32(np.linspace(0.0, 1.0, len(seg)) ** 1.5)
+        if not nxt:
+            seg = env[max(s, e - L):e]
+            seg *= _f32(np.linspace(1.0, 0.0, len(seg)) ** 1.5)
+    return env
+
+
+def _styled_seed(seed: int, fingerprint, style: str, mood: str) -> int:
+    """内容指纹 -> 音色细节 seed（只影响 v0.5 风格路径；legacy 不参与）。"""
+    base = int(seed)
+    if fingerprint is None or str(fingerprint) == "":
+        return base
+    h = _hash_int("v0.5", style, mood, str(fingerprint))
+    return base * 1000 + (h % 1000)
+
+
+def _styled_params(style: str, bpm, key, mood, seed, music_plan) -> dict:
+    """合并显式参数与 stylekit 的 music dict：plan 优先，显式参数只在 plan 缺项时兜底。
+
+    music_plan 可以是 resolve_script_style()["music"]（推荐），也可以是整份 plan（含 music 子字典）。
+    缺省回退顺序：plan -> 显式参数 -> 风格包自带值（bpm_hint 中位 / 调池首个 / steady / 7）。
+    """
+    pack = MUSIC_STYLES[style]
+    hint = pack["bpm_hint"]
+    eff = {
+        "bpm": None if bpm is None else float(bpm),
+        "key": None if key is None else str(key),
+        "mood": "steady" if mood is None else str(mood),
+        "seed": 7 if seed is None else int(seed),
+    }
+    plan = music_plan
+    if isinstance(plan, dict):
+        if isinstance(plan.get("music"), dict):
+            plan = plan["music"]
+        if plan.get("bpm") not in (None, ""):
+            eff["bpm"] = float(plan["bpm"])
+        if plan.get("key") not in (None, ""):
+            eff["key"] = str(plan["key"])
+        if plan.get("mood") not in (None, ""):
+            eff["mood"] = str(plan["mood"]).strip().lower() or "steady"
+        # seed_effective 是 stylekit 已经掺过内容指纹的最终种子；没有就退回 seed
+        for fld in ("seed_effective", "seed"):
+            if plan.get(fld) is not None:
+                try:
+                    eff["seed"] = abs(int(plan[fld]))
+                    break
+                except (TypeError, ValueError):
+                    continue
+    if eff["bpm"] is None:
+        eff["bpm"] = float(hint[len(hint) // 2])
+    if eff["key"] is None:
+        eff["key"] = str(pack["keys"][0])
+    eff["mood"] = str(eff["mood"] or "steady").strip().lower() or "steady"
+    return eff
+
+
+def _apply_pace(blocks: list, pace) -> list:
+    """按 pacing 的 min_dur + hold 把过碎的段落合并到下限（不改片长、不挪时间轴）。
+
+    stylekit 的 min_dur 是"一条字幕至少停留多久"，hold 是"句末额外留白"；
+    这里只用两者之和当"段落最短长度"：太碎的锚点（例如 1 小节一个）会被并进前一段，
+    名字保留前一段，energy 取较高者（合并后的段要能代表最响的那一刻）。
+    """
+    if not pace or not isinstance(pace, dict) or not blocks:
+        return blocks
+    try:
+        lo = float(pace.get("min_dur", 0.0)) + float(pace.get("hold", 0.0))
+    except (TypeError, ValueError):
+        return blocks
+    if lo <= 0.0:
+        return blocks
+    out = [dict(blocks[0])]
+    for b in blocks[1:]:
+        prev = out[-1]
+        if float(prev["end"]) - float(prev["start"]) < lo - 1e-9:
+            prev["end"] = float(b["end"])
+            prev["energy"] = max(float(prev["energy"]), float(b["energy"]))
+        else:
+            out.append(dict(b))
+    while len(out) > 1 and (float(out[-1]["end"]) - float(out[-1]["start"])) < lo - 1e-9:
+        last = out.pop()
+        out[-1]["end"] = float(last["end"])
+        out[-1]["energy"] = max(float(out[-1]["energy"]), float(last["energy"]))
+    return out
+
+
+def render_styled(duration, *, style, bpm=None, key=None, mood=None, anchors=None,
+                  sections=None, seed=7, fingerprint=None, sucks=None,
+                  music_plan=None, pace=None) -> tuple:
+    """按风格渲一条配乐（v0.5）：返回 (samples, report)。
+
+    与 render() 的区别只在"怎么写"，对外保证相同：
+      * 时长精确（ceil(duration*sr) 采样）、峰值 <= -1.5 dBFS、同 seed 逐样本一致；
+      * 复用老 _Bank 的鼓组与 _Bus 总线，只新增音色方法，不重写任何老乐器；
+      * 老路径（render(style=None) / "legacy"）完全不受影响，逐样本与 v0.4 相同。
+
+    anchors / sections 语义与 render() 一致；mood 见 MOOD_IDS。
+    fingerprint（v0.7）：参与 seed 派生 + 结构层变奏（契约 §3.3）——和弦每两小节一次
+        七和弦色彩替换、按指纹选进行档、动机级数 ±1 稳定偏移、鼓型 ghost 落点 / clap 位移。
+        None / "" 时三处变奏全部关闭，逐样本与 v0.5 相同；报告里的 variation 是这三项的计数。
+
+    music_plan：stylekit.resolve_script_style(script) 的 "music" 子字典（整份 plan 也接受）。
+        非 None 时 bpm / key / mood / seed 以它为准（优先级高于显式参数）——render.py 只需
+        传一个 dict，不必和两处默认值打架；显式参数退化成"plan 里没写时的缺省"。
+    pace：stylekit 的 pacing dict（至少含 min_dur / hold）。只按"min_dur + hold"把过碎的段落
+        合并到下限，不改 anchors 时间轴、不改片长；没有 pacing 需求时传 None 即可。
+
+    性能：styled 比 legacy 慢约 1.5~2.5x（多声部弦乐 + 新音色是主要成本）；
+        本机实测 60 s 片 3~6 s、388 s 片约 20~40 s（legacy 60 s ≈ 2.4 s），属预期。
+    """
+    t_start = time.perf_counter()
+    _require(style in MUSIC_STYLES, f"未知配乐风格 {style!r}；可选：{'/'.join(MUSIC_STYLE_IDS)}")
+    eff = _styled_params(style, bpm, key, mood, seed, music_plan)
+    bpm, key, mood, seed = eff["bpm"], eff["key"], eff["mood"], eff["seed"]
+    _require(mood in MOOD_IDS, f"未知情绪 {mood!r}；可选：{'/'.join(MOOD_IDS)}")
+    _require(isinstance(bpm, (int, float)) and math.isfinite(float(bpm)) and float(bpm) > 0.0,
+             f"bpm 必须是有限正数，收到 {bpm!r}")
+    _require(key in KEYS_ALL, f"未知调性 {key!r}；可选：{'/'.join(KEYS_ALL)}")
+    pack = MUSIC_STYLES[style]
+    # v0.7：调式决定和弦替换对 / 级数邻接表用哪一套；fp_s 为空 = 全部结构变奏关闭
+    mode = _styled_mode(pack)
+    fp_s = _styled_has_fp(fingerprint)
+    dur = float(duration)
+    sr = SR
+    sc = Score(duration, bpm=float(bpm), key=key, seed=int(seed))
+    # _merge_sections 在没有 anchors/sections 时已经返回"全片"，这里不要再补一段：
+    # 补了会在非小节对齐的片长上多出一个 0.x 秒的重复段（legacy 路径保留该历史行为）。
+    for s in _apply_pace(_merge_sections(anchors, sections, dur), pace):
+        sc.section(s["name"], s["start"], s["end"], s["energy"])
+    for t, db, d in (sucks or ()):
+        sc.suck(t, db, d)
+    plan = sc._build_plan()
+    secs = plan["sections"]
+    bar, beat = plan["bar_s"], plan["beat_s"]
+    n = max(int(plan["n"]), int(math.ceil(dur * sr - 1e-9)))
+    kval = sc.k
+    seed_eff = _styled_seed(sc.seed, fingerprint, style, mood)
+    bank = _Bank(seed_eff, beat, bar, sr)
+
+    m = _MOOD[mood]
+    mood_bright = float(m["bright"])
+    span = float(pack["level_span_db"])
+    ph = int(pack["phrase_bars"])
+    swing = float(pack["swing"])
+    space = pack["space"]
+
+    # ---- 1) 段落规划：tier / 层 / 和弦 / 电平目标 ----
+    # v0.7：指纹变奏计数（chord_swaps / motif_shifts / drum_ghosts）进 report["variation"]。
+    # 无指纹时三处变奏全关、计数恒 0，和弦仍走 v0.5 那条"只按能量档取进行"的分支。
+    chord_swaps = 0
+    motif_shifts = 0
+    drum_ghosts = 0
+    for si, sec in enumerate(secs):
+        e = sec["energy"]
+        tier = _styled_tier(e)
+        sec["tier"] = tier
+        sec["layers"] = _styled_layers(pack, e, mood)
+        prog = _styled_progression(pack, tier, mood, fingerprint)
+        sec["chords"], n_swap = _styled_chords(sec, si, secs, prog, pack, mood,
+                                               fingerprint, mode)
+        chord_swaps += n_swap
+        sec["target_db"] = round(_styled_target_db(e, span), 2)
+        sec["target_lufs"] = round(BASE_LUFS + sec["target_db"], 1)
+        sec["breath"] = {"calm": 2, "body": 1, "drive": 0, "climax": 0}[tier]
+    present = {name: [name in s["layers"] for s in secs] for name in LAYER_ORDER}
+    last_si = len(secs) - 1
+
+    master = np.zeros((n, 2), np.float32)
+
+    # ---- 2) 鼓：按 style["drums"][tier] 的 kick 落点 / hat 步长 / clap ----
+    hits: list = []
+    drums = _Bus(n, sr)
+    drum_pres = [bool(s["layers"].count("kick") + s["layers"].count("hat")) for s in secs]
+    for si, sec in enumerate(secs):
+        e = sec["energy"]
+        tier = sec["tier"]
+        cfg = pack["drums"][tier]
+        has_kick = "kick" in sec["layers"]
+        has_hat = "hat" in sec["layers"]
+        if not has_kick and not has_hat:
+            continue
+        nb = len(sec["bars"])
+        bm = sec["breath"]
+        kick_db = -12.0 + 7.5 * e + (1.0 if tier == "climax" else 0.0)
+        hat_db = -20.0 + 8.0 * e - float(m["drum"]) * 4.0
+        for j, bi in enumerate(sec["bars"]):
+            t0 = bi * bar
+            phrase_end = (j % ph == ph - 1) and nb >= ph
+            fill_bar = (j == nb - 1) and (si < len(secs) - 1)
+            breath = phrase_end and not fill_bar and bm > 0
+            if has_kick:
+                for kb in cfg.get("kick", ()):
+                    if (fill_bar and kb >= 3.0) or (breath and kb >= 3.0):
+                        continue
+                    accent = 1.5 if abs(kb) < 1e-9 else 0.0
+                    var = bank.kicks[(bi * 4 + int(round(kb))) % len(bank.kicks)]
+                    drums.add(var, t0 + kb * beat, kick_db + accent)
+                    hits.append((t0 + kb * beat, 0.28 + 0.22 * e))
+                # v0.7：指纹再塞一记 ghost kick（0.5 拍网格、不与现有落点重复；见 _styled_kick_ghost）
+                if fp_s:
+                    ghost_pos = _styled_kick_ghost(cfg, fp_s, si, j, fill_bar, breath)
+                    if ghost_pos is not None:
+                        gidx = (bi * 4 + int(round(ghost_pos * 2)) + 2) % len(bank.kicks)
+                        drums.add(bank.kicks[gidx], t0 + ghost_pos * beat, kick_db - 5.5)
+                        hits.append((t0 + ghost_pos * beat, 0.12 + 0.12 * e))
+                        drum_ghosts += 1
+            if has_hat and cfg.get("hat"):
+                step = float(cfg["hat"])
+                total = int(round(BEATS_PER_BAR / step))
+                for k in range(total):
+                    base_pos = k * step
+                    pos = base_pos + _styled_swing_shift(swing, step, k)
+                    if fill_bar and pos >= 3.0 - 1e-9:
+                        continue
+                    if breath and pos >= (3.0 if bm >= 2 else 3.5) - 1e-9:
+                        continue
+                    on_beat = abs(base_pos - round(base_pos)) < 1e-9
+                    ghost = 0.0 if on_beat else -2.5
+                    pan = 0.3 if k % 2 == 0 else -0.3
+                    var = bank.hats[(bi * 7 + k) % len(bank.hats)]
+                    drums.add(var, t0 + pos * beat, hat_db + ghost, pan)
+            if has_hat and e >= 0.50 and cfg.get("clap"):
+                for cidx, cb in enumerate(cfg.get("clap", ())):
+                    if phrase_end and cb >= 3.0:
+                        continue
+                    pos = float(cb)
+                    if fp_s:
+                        shift = _styled_clap_shift(fp_s, si, j, cidx)
+                        if shift and 0.0 <= pos + shift < float(BEATS_PER_BAR):
+                            pos += shift
+                            drum_ghosts += 1
+                    drums.add(bank.claps[(bi * 2 + int(round(pos))) % len(bank.claps)],
+                              t0 + pos * beat, -16.0 + 4.0 * e - 1.5 * float(m["drum"]), 0.08)
+            if tier == "climax" and has_hat:
+                for pos in (0.5, 1.5, 2.5, 3.5):
+                    if phrase_end and pos >= 3.5:
+                        continue
+                    drums.add(bank.hats_open[(bi + int(pos)) % len(bank.hats_open)],
+                              t0 + pos * beat, -21.0 + 3.0 * e, -0.2)
+        if si > 0 and tier in ("drive", "climax") and has_kick:
+            drums.add(bank.crashes[si % len(bank.crashes)], sec["start"],
+                      -10.0 + 2.0 * (1.0 - e))
+            drums.add(bank.kick_big, sec["start"], -9.0)
+            hits.append((sec["start"], 0.5))
+        if tier == "climax":
+            for j, bi in enumerate(sec["bars"]):
+                if j > 0 and j % 8 == 0:
+                    drums.add(bank.crashes[(si + j) % len(bank.crashes)], bi * bar, -17.0)
+    drums.buf *= _styled_gate_env(n, secs, drum_pres, bar, sr)[:, None]
+    master += drums.buf
+    drums.clear()
+
+    # ---- 3) 贝斯：型（whole/half/off8/16/dub）+ 风格音色 + 侧链避让 ----
+    bass = _Bus(n, sr)
+    bass_voice = _check_voice("bass", pack["voices"]["bass"])
+    for si, sec in enumerate(secs):
+        if not present["bass"][si]:
+            continue
+        e = sec["energy"]
+        cfg = pack["drums"][sec["tier"]]
+        pat = cfg.get("bass", "none")
+        if pat == "none":
+            continue
+        bdb = -14.0 + 5.0 * e
+        bright = _clip01(0.2 + 0.65 * e + 0.5 * mood_bright)
+        nb = len(sec["bars"])
+        bm = sec["breath"]
+        k = 0
+        for j, bi in enumerate(sec["bars"]):
+            t0 = bi * bar
+            chord = kval["chords"][sec["chords"][j]]
+            root = chord["root"]
+            phrase_end = (j % ph == ph - 1) and nb >= ph
+            breath = phrase_end and bm >= 2
+            if pat == "whole":
+                bass.add(_bass_texture(bank, bass_voice, root, bar * 0.92, bright), t0, bdb)
+            elif pat == "half":
+                for pos, dd in ((0.0, 1.8), (2.0, 1.8)):
+                    if breath and pos >= 3.0:
+                        continue
+                    bass.add(_bass_texture(bank, bass_voice, root, dd * beat, bright),
+                             t0 + pos * beat, bdb)
+            elif pat == "off8":
+                for pos in (0.5, 1.5, 2.5, 3.5):
+                    if breath and pos >= 3.0:
+                        continue
+                    nt = _up(root, 1) if (k % 7 == 3) else root
+                    bass.add(_bass_texture(bank, bass_voice, nt, 0.42 * beat, bright),
+                             t0 + pos * beat, bdb)
+                    k += 1
+            elif pat == "dub":
+                bass.add(_bass_texture(bank, bass_voice, root, bar * 0.55, bright), t0, bdb - 1.0)
+                if not breath:
+                    bass.add(_bass_texture(bank, bass_voice, _up(root, 1), bar * 0.30, bright),
+                             t0 + 2.5 * beat, bdb - 3.0)
+            else:                                  # "16"：十六分切分
+                for b in range(BEATS_PER_BAR):
+                    for off in (0.25, 0.5, 0.75):
+                        pos = b + off
+                        if breath and pos >= 3.0:
+                            continue
+                        nt = _up(root, 1) if (k % 11 == 7) else root
+                        bass.add(_bass_texture(bank, bass_voice, nt, 0.2 * beat, bright),
+                                 t0 + pos * beat, bdb)
+                        k += 1
+    bass.buf *= sc._duck_env(n, hits, depth=float(pack["duck"]["bass"]), tau=0.15)[:, None]
+    bass.buf *= _styled_gate_env(n, secs, present["bass"], bar, sr)[:, None]
+    master += bass.buf
+    bass.clear()
+
+    # ---- 4) 铺底 pad / strings（受底鼓轻压；段落首小节慢起音；shine 叠高八度） ----
+    pads = _Bus(n, sr)
+    pad_voice = _check_voice("pad", pack["voices"]["pad"])
+    attack_first = {"calm": 1.2, "body": 0.5, "drive": 0.24, "climax": 0.14}
+    attack_next = {"calm": 0.42, "body": 0.14, "drive": 0.07, "climax": 0.05}
+    for si, sec in enumerate(secs):
+        if not present["pad"][si]:
+            continue
+        e = sec["energy"]
+        tier = sec["tier"]
+        pdb = -20.0 + 7.0 * e + 0.8 * mood_bright
+        bright = _clip01(0.15 + 0.75 * e + mood_bright)
+        for j, bi in enumerate(sec["bars"]):
+            chord = kval["chords"][sec["chords"][j]]
+            attack = attack_first[tier] if j == 0 else attack_next[tier]
+            if pad_voice == "strings":
+                tex = bank.strings(chord, bright, attack)
+            else:
+                tex = bank.pad(chord, bright, attack)
+            pads.add(tex, bi * bar, pdb)
+            if present["shine"][si]:
+                pads.add(bank.pad(chord, _clip01(bright - 0.1), attack, octave=1),
+                         bi * bar, pdb - 6.0)
+    pads.buf *= sc._duck_env(n, hits, depth=float(pack["duck"]["pad"]), tau=0.18)[:, None]
+    pads.buf *= _styled_gate_env(n, secs, present["pad"], bar, sr)[:, None]
+    master += pads.buf
+    pads.clear()
+
+    # ---- 5) 琶音：步长来自 drums[arp]，音色来自 voices[arp]，带摇摆 ----
+    keys = _Bus(n, sr)
+    arp_voice = _check_voice("arp", pack["voices"]["arp"])
+    for si, sec in enumerate(secs):
+        if not present["arp"][si]:
+            continue
+        cfg = pack["drums"][sec["tier"]]
+        step = cfg.get("arp")
+        if not step:
+            continue
+        step = float(step)
+        e = sec["energy"]
+        adb = -25.0 + 8.0 * e + 0.5 * mood_bright
+        bright = _clip01(0.25 + 0.6 * e + mood_bright)
+        nb = len(sec["bars"])
+        bm = sec["breath"]
+        for j, bi in enumerate(sec["bars"]):
+            t0 = bi * bar
+            chord = kval["chords"][sec["chords"][j]]
+            seq = [_up(nt, 2) for nt in chord["notes"]]
+            seq = seq + seq[1:3][::-1]
+            total = int(round(BEATS_PER_BAR / step))
+            phrase_end = (j % ph == ph - 1) and nb >= ph
+            breath = phrase_end and bm > 0
+            for k in range(total):
+                pos = k * step + _styled_swing_shift(swing, step, k)
+                if breath and pos >= 3.0 - 1e-9:
+                    continue
+                nt = seq[k % len(seq)]
+                pan = 0.35 * math.sin(0.7 * k + 0.3 * j)
+                keys.add(_arp_texture(bank, arp_voice, nt, bright, 0.3),
+                         t0 + pos * beat, adb, pan)
+    keys.buf *= _styled_gate_env(n, secs, present["arp"], bar, sr)[:, None]
+    master += keys.buf
+    sc._add_delayed(master, keys.buf, float(space["delay_beats"]) * beat,
+                    float(space["delay_db"]), taps=int(space["taps"]), sr=sr)
+    keys.clear()
+
+    # ---- 6) 主奏：motif + lead_cycle 每乐句轮换；片尾用 end 动机 ----
+    lead = _Bus(n, sr)
+    cycle = tuple(pack["lead_cycle"])
+    phrase_i = 0
+    lead_pres = list(present["melody"])
+    if last_si >= 0 and secs[last_si]["energy"] >= 0.22:
+        lead_pres[last_si] = True
+    for si, sec in enumerate(secs):
+        e = sec["energy"]
+        nb = len(sec["bars"])
+        if nb < 2:
+            continue
+        bright = _clip01(0.4 + 0.5 * e + mood_bright)
+        if present["melody"][si]:
+            mel_db = -17.0 + 4.0 * e + float(m["lead_db"])
+            for pi, first in enumerate(range(0, nb, ph)):
+                is_last_phrase = (si == last_si and pi == (nb - 1) // ph)
+                if is_last_phrase:
+                    kind, motif = "end", pack["motif"]["end"]
+                elif phrase_i % 2 == 0:
+                    kind, motif = "q", pack["motif"]["q"]
+                else:
+                    kind, motif = "a", pack["motif"]["a"]
+                voice = cycle[phrase_i % len(cycle)]
+                t0 = sec["bars"][first] * bar
+                motif_shifts += _emit_styled_motif(
+                    lead, bank, motif, kval, voice, t0, beat, mel_db, bright,
+                    fingerprint=fingerprint, style=style, kind=kind, mode=mode)
+                phrase_i += 1
+        elif si == last_si and e >= 0.22:
+            # 片尾安静段：用第一个主奏音色把结局动机答完
+            t_last = sec["bars"][0] * bar + max(0.0, (nb - 2) * bar)
+            motif_shifts += _emit_styled_motif(
+                lead, bank, pack["motif"]["end"], kval, cycle[0],
+                t_last, beat, -19.0 + float(m["lead_db"]), bright,
+                fingerprint=fingerprint, style=style, kind="end", mode=mode)
+    lead.buf *= _styled_gate_env(n, secs, lead_pres, bar, sr)[:, None]
+    master += lead.buf
+    sc._add_delayed(master, lead.buf, float(space["delay_beats"]) * beat * 0.85,
+                    float(space["delay_db"]) - 3.0,
+                    taps=max(1, int(space["taps"]) - 1), sr=sr)
+    lead.clear()
+
+    # ---- 7) shine：高音闪光（只在最亮的段出现） ----
+    shine = _Bus(n, sr)
+    for si, sec in enumerate(secs):
+        if not present["shine"][si]:
+            continue
+        e = sec["energy"]
+        sdb = -30.0 + 6.0 * e + 0.6 * mood_bright
+        for j, bi in enumerate(sec["bars"]):
+            chord = kval["chords"][sec["chords"][j]]
+            hi = [_up(nt, 2) for nt in chord["notes"][1:3]]
+            for q, pos in enumerate((0.5, 2.75)):
+                shine.add(bank.glock(hi[(bi + q) % len(hi)], 0.9), bi * bar + pos * beat,
+                          sdb, 0.4 if q == 0 else -0.4)
+    shine.buf *= _styled_gate_env(n, secs, present["shine"], bar, sr)[:, None]
+    master += shine.buf
+    shine.clear()
+
+    # ---- 8) 过门与效果（每个内部交界一小节） ----
+    fx = _Bus(n, sr)
+    for ti, tr in enumerate(plan["transitions"]):
+        fill_start = tr["t"] - bar
+        nxt_e = secs[ti + 1]["energy"]
+        prev_e = secs[ti]["energy"]
+        sixteenth = 0.25 * beat
+        for k in range(int(round(bar / sixteenth))):
+            p = k / max(1.0, (bar / sixteenth) - 1.0)
+            tom = bank.toms[min(3, int(p * 4))]
+            fx.add(tom, fill_start + k * sixteenth,
+                   -18.0 + 6.0 * p + (1.5 if k % 2 == 0 else 0.0), -0.35 + 0.7 * p)
+            if p >= 0.6:
+                fx.add(bank.snares[k % len(bank.snares)], fill_start + k * sixteenth,
+                       -20.0 + 5.0 * p, 0.1)
+        fx.add(bank.swell(bar, ti, "styled"), fill_start, -15.0 + 2.0 * nxt_e)
+        if nxt_e > prev_e + 0.10:
+            fx.add(bank.riser(bar * 0.92, ti, "styled"), fill_start + bar * 0.08,
+                   -14.0 + 2.0 * nxt_e)
+        if nxt_e >= 0.72:
+            fx.add(bank.sub_boom(2.2, 55.0, 30.0), tr["t"], -9.0 - 2.0 * (1.0 - nxt_e))
+            fx.add(bank.crashes[ti % len(bank.crashes)], tr["t"], -11.0)
+        if nxt_e < prev_e - 0.15:
+            fx.add(bank.crashes[(ti + 1) % len(bank.crashes)], tr["t"], -20.0)
+    master += fx.buf
+    fx.clear()
+
+    # ---- 9) 自动电平（段落间能量 -> dB 曲线）/ 吸气 / 去直流 / 淡入淡出 / 峰值 ----
+    levels = sc._level_match(master, plan)
+    sc._apply_sucks(master, plan["sucks"], sr)
+    sc._de_dc(master)
+    sc._apply_fades(master)
+    peak = float(np.max(np.abs(master))) if n else 0.0
+    if peak > 1e-9:
+        master *= np.float32(_db_amp(TARGET_PEAK_DB) / peak)
+    peak_db = float(20.0 * math.log10(max(float(np.max(np.abs(master))), 1e-12)))
+    lufs = _approx_lufs(master, sr)
+    dc = float(np.max(np.abs(master.mean(axis=0)))) if n else 0.0
+    centroid = spectral_centroid(master, sr)
+
+    # ---- 10) 报告（version 2；字段与 legacy report 兼容，CLI 复用同一个格式化函数） ----
+    rep = {
+        "version": 2,
+        "generator": "scorekit",
+        "style": style,
+        "style_label": str(pack.get("label", style)),
+        "mood": mood,
+        "bpm": round(float(bpm), 4),
+        "bpm_hint": list(pack["bpm_hint"]),
+        "key": key,
+        "key_name": kval["name"],
+        "key_in_style_pool": key in tuple(pack["keys"]),
+        "sr": sr,
+        "duration": round(dur, 3),
+        "seed": int(sc.seed),
+        "seed_effective": int(seed_eff),
+        "fingerprint": "" if fingerprint is None else str(fingerprint),
+        # v0.7：指纹变奏的实际发生数（审计用；无指纹时三项目全 0）
+        "variation": {"chord_swaps": int(chord_swaps),
+                      "motif_shifts": int(motif_shifts),
+                      "drum_ghosts": int(drum_ghosts)},
+        "bar_s": round(bar, 4),
+        "beat_s": round(beat, 4),
+        "phrase_bars": ph,
+        "since": "v0.5",
+        "sections": [
+            {"name": s["name"], "start": round(s["start"], 3), "end": round(s["end"], 3),
+             "energy": round(s["energy"], 3), "tier": s["tier"], "bars": len(s["bars"]),
+             "target_db": round(s["target_db"], 2), "target_lufs": round(s["target_lufs"], 1),
+             "layers": list(s["layers"]), "chords": list(s["chords"])}
+            for s in secs
+        ],
+        "transitions": [dict(t) for t in plan["transitions"]],
+        "sucks": [dict(d) for d in plan["sucks"]],
+        "beats": list(plan["beats"]),
+        "peak_dbfs": round(peak_db, 2),
+        "lufs_approx": round(lufs, 1),
+        "dc_max": round(dc, 9),
+        "spectral_centroid_hz": round(centroid, 1),
+        "render_s": round(time.perf_counter() - t_start, 3),
+        "measured_sections": [
+            {"name": s["name"], "start": round(s["start"], 3), "end": round(s["end"], 3),
+             "energy": round(s["energy"], 3), "gain_db": round(lv["gain"], 2),
+             "measured_db": round(lv["after"], 2)}
+            for s, lv in zip(secs, levels)
+        ],
+    }
+    return master, rep
+
+
+def spectral_centroid(x, sr: int = SR) -> float:
+    """频谱质心（Hz）：粗略量"亮度"，用于验证不同风格不是同一首曲子。
+
+    单声道下混 -> 去均值 -> 分块 rFFT -> 幅度加权平均频率。确定性、无随机、无三方依赖。
+    """
+    a = np.asarray(x)
+    if a.ndim == 2:
+        mono = a.astype(np.float64).mean(axis=1)
+    else:
+        mono = a.astype(np.float64).ravel()
+    if len(mono) < 1024:
+        return 0.0
+    blk = 16384 if len(mono) >= 16384 else 1024
+    hop = max(1, blk // 2)
+    win = np.hanning(blk)
+    freqs = np.fft.rfftfreq(blk, 1.0 / float(sr))
+    acc_m = 0.0
+    acc_p = 0.0
+    for s in range(0, len(mono) - blk + 1, hop):
+        seg = mono[s:s + blk]
+        seg = seg - float(seg.mean())
+        mag = np.abs(np.fft.rfft(seg * win))
+        acc_m += float(np.dot(freqs, mag))
+        acc_p += float(mag.sum())
+    if acc_p <= 1e-12:
+        return 0.0
+    return float(acc_m / acc_p)
+
+
+def _music_style_lint() -> list:
+    """风格表体检：返回问题列表（空 = 过）。selftest 第 17 条调用。"""
+    bad: list = []
+    need = ("bpm_hint", "keys", "progressions", "motif", "layers", "voices",
+            "lead_cycle", "drums", "space", "phrase_bars", "duck",
+            "level_span_db", "swing")
+    for sid, pack in MUSIC_STYLES.items():
+        missing = [fld for fld in need if fld not in pack]
+        if missing:
+            bad.append(f"{sid}: 缺字段 {'/'.join(missing)}")
+            continue
+        if not pack["bpm_hint"]:
+            bad.append(f"{sid}: bpm_hint 为空")
+        for kk in pack["keys"]:
+            if kk not in KEYS_ALL:
+                bad.append(f"{sid}: 调 {kk} 不在 KEYS_ALL")
+        for tier in ("calm", "body", "drive"):
+            if tier not in pack["progressions"]:
+                bad.append(f"{sid}: progressions 缺 {tier}")
+                continue
+            for deg in pack["progressions"][tier]:
+                if deg not in _DEGREE_BY_NAME:
+                    bad.append(f"{sid}.{tier}: 级数 {deg} 不存在")
+        for mt in ("q", "a", "end"):
+            if mt not in pack["motif"]:
+                bad.append(f"{sid}: motif 缺 {mt}")
+                continue
+            for idx, ev in enumerate(pack["motif"][mt]):
+                if len(ev) != 3:
+                    bad.append(f"{sid}.{mt}[{idx}]: 必须是 (拍, 级数, 时值拍)")
+                    continue
+                if str(ev[1]) not in _DEGREE_BY_NAME:
+                    bad.append(f"{sid}.{mt}[{idx}]: 级数 {ev[1]} 不存在")
+                if float(ev[2]) <= 0.0:
+                    bad.append(f"{sid}.{mt}[{idx}]: 时值必须 > 0")
+        for slot in ("pad", "bass", "arp", "lead"):
+            if pack["voices"].get(slot) not in _STYLE_VOICES[slot]:
+                bad.append(f"{sid}.voices.{slot}={pack['voices'].get(slot)!r} 未知")
+        for voice in pack["lead_cycle"]:
+            if voice not in _STYLE_VOICES["lead"]:
+                bad.append(f"{sid}.lead_cycle: 音色 {voice!r} 未知")
+        for tier in ("calm", "body", "drive", "climax"):
+            cfg = pack["drums"].get(tier) or {}
+            if not cfg:
+                bad.append(f"{sid}.drums: 缺 {tier}")
+                continue
+            for kb in cfg.get("kick", ()):
+                if not (0.0 <= float(kb) < BEATS_PER_BAR):
+                    bad.append(f"{sid}.drums.{tier}: kick {kb} 越界")
+            for cb in cfg.get("clap", ()):
+                if not (0.0 <= float(cb) < BEATS_PER_BAR):
+                    bad.append(f"{sid}.drums.{tier}: clap {cb} 越界")
+            hs = cfg.get("hat", None)
+            if hs is not None and not (0.20 <= float(hs) <= 2.0):
+                bad.append(f"{sid}.drums.{tier}: hat {hs} 不合理")
+            if cfg.get("bass", "none") not in ("none", "whole", "half", "off8", "16", "dub"):
+                bad.append(f"{sid}.drums.{tier}: bass 型 {cfg.get('bass')!r} 未知")
+            asp = cfg.get("arp", None)
+            if asp is not None and not (0.2 <= float(asp) <= 2.0):
+                bad.append(f"{sid}.drums.{tier}: arp {asp} 不合理")
+        if int(pack["phrase_bars"]) not in (4, 8):
+            bad.append(f"{sid}: phrase_bars 只能是 4/8")
+        if not (float(pack["level_span_db"]) > 0.0):
+            bad.append(f"{sid}: level_span_db 必须 > 0")
+        if not (0.0 <= float(pack["swing"]) <= 0.2):
+            bad.append(f"{sid}: swing 必须 0~0.2")
+        for fld in ("bass", "pad"):
+            d = float(pack["duck"].get(fld, 0.0))
+            if not (0.0 <= d < 0.9):
+                bad.append(f"{sid}: duck.{fld}={d} 不合理")
+        if float(pack["layers"].get("pad", 1.0)) > 1e-9:
+            bad.append(f"{sid}: layers.pad 必须是 0.0")
+        for nm in LAYER_ORDER:
+            if nm not in pack["layers"]:
+                bad.append(f"{sid}: layers 缺 {nm}")
+        sp = pack["space"]
+        if not (0.0 < float(sp.get("delay_beats", 0.0)) <= 4.0):
+            bad.append(f"{sid}: space.delay_beats 必须 0~4 拍")
+        if int(sp.get("taps", 0)) < 1:
+            bad.append(f"{sid}: space.taps 必须 >= 1")
+    return bad
+
+
+def _stylekit_crosscheck() -> list:
+    """同目录有 stylekit.py 时交叉核对风格 id 与调池；没有就静默跳过（不算失败）。"""
+    try:
+        import stylekit as ST                     # noqa: F401
+    except Exception:                             # noqa: BLE001
+        return []
+    bad: list = []
+    for sid in MUSIC_STYLE_IDS:
+        if sid == LEGACY_MUSIC_STYLE:
+            continue
+        if sid not in ST.STYLES:
+            bad.append(f"stylekit 缺风格 {sid}")
+            continue
+        want = tuple(ST.STYLES[sid]["music"]["keys"])
+        got = tuple(MUSIC_STYLES[sid]["keys"])
+        if want != got:
+            bad.append(f"{sid}: 调池不一致 {got} != {want}")
+    return bad
+
+
+def _stylekit_available() -> bool:
+    """同目录是否有可导入的 stylekit（没有就跳过交叉核对，不判失败）。"""
+    try:
+        import stylekit  # noqa: F401
+        return True
+    except Exception:                             # noqa: BLE001
+        return False
+
 # ============================================================================
 # 模块级便捷函数
 # ============================================================================
@@ -1431,12 +3103,23 @@ def _merge_sections(anchors, sections, duration: float) -> list:
 
 
 def render(duration, bpm: float = 120.0, key: str = "Dm", anchors=None, sections=None,
-           seed: int = 7) -> tuple:
+           seed: int = 7, style=None, mood: str = "steady", fingerprint=None,
+           music_plan=None, pace=None) -> tuple:
     """一次性接口：合成整片配乐，返回 (samples, report)。
 
     anchors：timeline.json 的 [{id,kind,start,end}]（自动按 kind 映射能量分段）；
     sections：显式段落（绝对时间或 at 引用），在 anchors 之后追加/覆盖空隙。
+
+    v0.5：style=None / "legacy" 走 v0.4 原路径（逐样本与旧版一致；style/mood/fingerprint/
+    music_plan/pace 全部忽略）；其余 style（MUSIC_STYLE_IDS 里的 8 个）走 render_styled()。
+    music_plan / pace 的语义见 render_styled：music_plan 非 None 时覆盖 bpm/key/mood/seed。
     """
+    sid = _normalize_style_id(style)
+    if sid is not None:
+        return render_styled(duration, style=sid, bpm=bpm, key=key, mood=mood,
+                             anchors=anchors, sections=sections, seed=seed,
+                             fingerprint=fingerprint, music_plan=music_plan, pace=pace)
+    # ---- 以下与 v0.4 一字不差：legacy 逐字节兼容是硬契约，别在这段里改任何东西 ----
     sc = Score(duration, bpm=bpm, key=key, seed=seed)
     for s in _merge_sections(anchors, sections, float(duration)):
         sc.section(s["name"], s["start"], s["end"], s["energy"])
@@ -1449,6 +3132,12 @@ def save(path, x, sr: int = SR) -> Path:
     """把配乐写成 24-bit PCM WAV（通道数自适应；峰值由 render 保证 ≤ -1 dBFS）。"""
     path = Path(path)
     arr = np.asarray(x)
+    if arr.size and not np.all(np.isfinite(arr)):
+        # NaN 经 np.rint(...).astype(np.int32) 会落到 INT_MIN（不是 0），24-bit 写出后是
+        # 满幅负样本 —— 成片里一声爆响，且没有任何报错。与 filmkit.wav_write 同口径：报错。
+        bad = int(arr.size - np.count_nonzero(np.isfinite(arr)))
+        raise ValueError("scorekit.save: 采样里有 %d 个 NaN/Inf（%s）——配乐渲染有数值错误，"
+                         "拒绝写出损坏的 WAV" % (bad, path))
     if arr.ndim == 1:
         arr = np.stack([arr, arr], axis=1)
     _require(arr.ndim == 2 and arr.shape[1] in (1, 2), f"只支持单/双声道，收到 shape={arr.shape}")
@@ -1756,6 +3445,125 @@ def selftest() -> int:
     check("16. 集成形态：anchors+sections 同起点覆盖 / 无 end 自动补到片尾", ok_it,
           " | ".join(f"{b['name']}:{b['start']}-{b['end']}:e{b['energy']}" for b in merged))
 
+    # 17) v0.5 配乐风格表完整性（9 风格；级数存在；调池在 KEYS_ALL；与 stylekit 交叉核对）
+    lint_bad = _music_style_lint()
+    cross_bad = _stylekit_crosscheck()
+    check("17. 配乐风格表完整（9 风格 / 级数存在 / 调池在 KEYS_ALL）",
+          not (lint_bad or cross_bad),
+          "; ".join((lint_bad + cross_bad)[:3]) if (lint_bad or cross_bad)
+          else f"{len(MUSIC_STYLES)} 风格，{len(_DEGREE_BY_NAME)} 个级数"
+               + ("；stylekit 调池一致" if _stylekit_available() else "；无 stylekit 可交叉核对"))
+
+    # 18) v0.5 大调 & 七和弦表（KEYS 仍是 v0.4 的 4 个小调）
+    bad_major = []
+    for kname, kv in KEYS_MAJOR.items():
+        for deg in ("I", "ii", "iii", "IV", "V", "vi", "vii", "sus4",
+                    "Imaj7", "ii7", "iii7", "IVmaj7", "V7", "vi7", "i7"):
+            if deg not in kv["chords"]:
+                bad_major.append(f"{kname}.{deg} 缺失")
+        for chord in kv["chords"].values():
+            for nt in chord["notes"] + [chord["root"]]:
+                if not _NOTE_RE.match(nt) or S.hz(nt) <= 0:
+                    bad_major.append(f"{kname}: 非法音名 {nt!r}")
+    ok_major = ((not bad_major) and set(KEYS) == {"Dm", "Am", "Cm", "Em"}
+                and len(KEYS_ALL) == len(KEYS) + len(KEYS_MAJOR) == 10)
+    check("18. 大调 6 个 & 七和弦级数（KEYS 仍是 4 个小调）", ok_major,
+          "; ".join(bad_major[:3]) if bad_major
+          else f"{len(KEYS_ALL)} 个调，{len(KEYS_ALL['C']['chords'])} 个级数/调")
+
+    # 19) v0.5 逐风格 6 s 渲染：时长精确 / 有限值 / 峰值 / 同 seed 一致 / 风格间 PCM 不全等
+    t_styled = time.perf_counter()
+    style_ids = [sid for sid in MUSIC_STYLE_IDS if sid != LEGACY_MUSIC_STYLE]
+    pcm = {}
+    peaks = {}
+    bad_style = []
+    for sid in style_ids:
+        pk = MUSIC_STYLES[sid]
+        hint = pk["bpm_hint"]
+        bpm_s = float(hint[len(hint) // 2])
+        key_s = str(pk["keys"][0])
+        try:
+            x1, r1 = render_styled(6.0, style=sid, bpm=bpm_s, key=key_s, seed=7)
+            x2, _r2 = render_styled(6.0, style=sid, bpm=bpm_s, key=key_s, seed=7)
+        except Exception as exc:                  # 自测里也要报原因，不吞异常
+            bad_style.append(f"{sid}: {type(exc).__name__}: {exc}")
+            continue
+        want_n = int(math.ceil(6.0 * SR - 1e-9))
+        if x1.shape != (want_n, 2) or not bool(np.all(np.isfinite(x1))):
+            bad_style.append(f"{sid}: shape={x1.shape} 或含非有限值")
+        if not np.array_equal(x1, x2):
+            bad_style.append(f"{sid}: 同 seed 两次不一致")
+        peaks[sid] = 20.0 * math.log10(max(float(np.max(np.abs(x1))), 1e-12))
+        if not (-3.5 <= peaks[sid] <= -1.0):
+            bad_style.append(f"{sid}: 峰值 {peaks[sid]:.2f} dBFS 越界")
+        if r1.get("version") != 2 or r1.get("style") != sid or "sections" not in r1:
+            bad_style.append(f"{sid}: report 结构不对")
+        pcm[sid] = x1
+    same_pairs = []
+    ids_ok = list(pcm)
+    for i in range(len(ids_ok)):
+        for j in range(i + 1, len(ids_ok)):
+            if np.array_equal(pcm[ids_ok[i]], pcm[ids_ok[j]]):
+                same_pairs.append(f"{ids_ok[i]}=={ids_ok[j]}")
+    cen = {sid: spectral_centroid(x, SR) for sid, x in pcm.items()}
+    spread = (max(cen.values()) - min(cen.values())) if cen else 0.0
+
+    # 19b) stylekit 的 music_plan 优先级：plan 里的 bpm/key/mood/seed 必须盖过显式参数
+    plan_used = {"bpm": 123.0, "key": "A", "mood": "uplifting", "seed": 42,
+                 "seed_effective": 424242}
+    try:
+        _xp, rp = render_styled(4.0, style="vivid", bpm=90.0, key="D", mood="calm", seed=1,
+                                music_plan={"music": plan_used})
+        ok_plan = (rp.get("bpm") == 123.0 and rp.get("key") == "A"
+                   and rp.get("mood") == "uplifting" and rp.get("seed_effective") == 424242)
+        plan_detail = (f"plan -> {rp.get('bpm')}/{rp.get('key')}/{rp.get('mood')}/"
+                       f"seed {rp.get('seed_effective')}")
+    except Exception as exc:                      # 自测里也要报原因
+        ok_plan = False
+        plan_detail = f"{type(exc).__name__}: {exc}"
+
+    # 19c) pace：min_dur+hold 只合并过碎段落，不改片长 / 时间轴
+    stale_blocks = [
+        {"name": "碎1", "start": 0.0, "end": 2.0, "energy": 0.3},
+        {"name": "碎2", "start": 2.0, "end": 4.0, "energy": 0.6},
+        {"name": "长", "start": 4.0, "end": 12.0, "energy": 0.5},
+    ]
+    paced = _apply_pace(stale_blocks, {"min_dur": 3.2, "hold": 0.2})
+    ok_pace = (len(paced) == 2 and abs(paced[0]["end"] - 4.0) < 1e-9
+               and abs(paced[0]["energy"] - 0.6) < 1e-9
+               and abs(paced[-1]["start"] - 4.0) < 1e-9
+               and abs(paced[-1]["end"] - 12.0) < 1e-9)
+    try:
+        xpace, rpace = render_styled(
+            6.0, style="vivid", bpm=126, key="D", seed=7,
+            anchors=[{"id": "p%d" % i, "kind": "body", "start": i * 0.75,
+                      "end": (i + 1) * 0.75} for i in range(8)],
+            pace={"min_dur": 3.0, "hold": 0.30})
+        ok_pace = ok_pace and xpace.shape == (int(math.ceil(6.0 * SR - 1e-9)), 2)
+        pace_detail = f"索引 {len(paced)} 段；6 s 片仍 {xpace.shape[0]} 采样，{len(rpace['sections'])} 段"
+    except Exception as exc:
+        ok_pace = False
+        pace_detail = f"{type(exc).__name__}: {exc}"
+
+    ok_styled = ((not bad_style) and (not same_pairs) and len(pcm) == len(style_ids)
+                 and spread >= 100.0 and ok_plan and ok_pace)
+    check("19. 8 风格各渲 6 s：时长/有限值/峰值/确定性/两两 PCM 不全等", ok_styled,
+          ("; ".join((bad_style + same_pairs)[:3]) if (bad_style or same_pairs)
+           else f"{len(pcm)} 风格，{time.perf_counter() - t_styled:.1f} s；"
+                f"频谱质心 {min(cen.values()):.0f}~{max(cen.values()):.0f} Hz（跨度 {spread:.0f}）；"
+                f"{plan_detail}；{pace_detail}"))
+
+    # 20) v0.5 legacy 兼容：style=None / "legacy" / 任意 mood 都走 v0.4 原路径，逐样本一致
+    xn, rn = render(6.0, bpm=120, key="Dm", seed=7)
+    xl, rl = render(6.0, bpm=120, key="Dm", seed=7, style="legacy")
+    xm, _rm = render(6.0, bpm=120, key="Dm", seed=7, style=None, mood="driving",
+                     fingerprint="whatever")
+    rn_c = {k: v for k, v in rn.items() if k != "render_s"}
+    rl_c = {k: v for k, v in rl.items() if k != "render_s"}
+    ok_legacy = (np.array_equal(xn, xl) and np.array_equal(xn, xm) and rn_c == rl_c
+                 and rn.get("version") == 1)
+    check("20. legacy 兼容：style=None / 'legacy' / 任意 mood+fingerprint 逐样本一致", ok_legacy,
+          f"shape={xn.shape}，version={rn.get('version')}")
     total = time.perf_counter() - t_all
     passed = sum(1 for _, ok, _ in rows if ok)
     failed = len(rows) - passed
@@ -1810,12 +3618,36 @@ def _parse_suck_list(items) -> list:
     return out
 
 
+def _format_style_list() -> str:
+    """CLI --list-styles：列可用配乐风格（bpm_hint / 调池 / 主奏音色 / 乐句长度）。"""
+    lines = ["可用配乐风格（--style；缺省 legacy = v0.4 逐样本兼容）："]
+    for sid, pack in MUSIC_STYLES.items():
+        lines.append("  %-10s %-8s bpm_hint %-16s 调池 %-20s 主奏 %-14s 乐句 %d 小节" % (
+            sid, str(pack.get("label", "")),
+            "/".join(str(b) for b in pack["bpm_hint"]),
+            "/".join(str(k) for k in pack["keys"]),
+            "/".join(str(v) for v in pack["lead_cycle"]),
+            int(pack["phrase_bars"]),
+        ))
+    lines.append("  情绪 --mood：" + "/".join(MOOD_IDS))
+    return "\n".join(lines)
+
+
 def _format_report(rep: dict, wav_path: Path | None, report_path: Path | None) -> str:
     """CLI 中文摘要。"""
     lines = []
     lines.append(f"[scorekit] {rep['duration']:g} s / {rep['bpm']:g} BPM / {rep['key']}（{rep['key_name']}）"
                  f" / 小节 {rep['bar_s']:g} s / seed {rep['seed']}")
+    if rep.get("style"):
+        lines.append(f"  配乐风格 {rep['style']}（{rep.get('style_label', '')}）"
+                     f" / 情绪 {rep.get('mood', 'steady')} / 有效 seed {rep.get('seed_effective', rep['seed'])}"
+                     f" / 频谱质心 {rep.get('spectral_centroid_hz', 0):.0f} Hz")
     lines.append(f"  段落 {len(rep['sections'])} 个，交界 {len(rep['transitions'])} 处，吸气 {len(rep['sucks'])} 处")
+    var = rep.get("variation") or {}
+    if any(int(var.get(k, 0) or 0) for k in ("chord_swaps", "motif_shifts", "drum_ghosts")):
+        lines.append("  指纹变奏：和弦替换 %d 处 / 动机偏移 %d 音 / 鼓型 ghost %d 处"
+                     % (int(var.get("chord_swaps", 0)), int(var.get("motif_shifts", 0)),
+                        int(var.get("drum_ghosts", 0))))
     for s in rep["sections"]:
         lines.append(f"    {s['name']:<8} {s['start']:7.2f} – {s['end']:7.2f} s"
                      f"  energy {s['energy']:.2f}  目标 {s['target_lufs']:.1f} LUFS"
@@ -1839,9 +3671,17 @@ def main(argv=None) -> int:
         description="scorekit — 程序化配乐（numpy + sfxkit，无采样、确定性）",
     )
     ap.add_argument("--selftest", action="store_true", help="跑自测（不联网，逐条 PASS/FAIL）")
+    ap.add_argument("--list-styles", action="store_true", help="列出可用配乐风格后退出")
     ap.add_argument("--duration", type=float, default=60.0, help="片长（秒），默认 60")
-    ap.add_argument("--bpm", type=float, default=120.0, help="BPM，默认 120")
-    ap.add_argument("--key", default="Dm", help=f"调性，可选 {'/'.join(KEYS)}，默认 Dm")
+    ap.add_argument("--style", default=None,
+                    help="配乐风格：" + "/".join(MUSIC_STYLE_IDS) + "（缺省 = legacy，与 v0.4 逐样本一致）")
+    ap.add_argument("--mood", default="steady", help="情绪修饰：" + "/".join(MOOD_IDS))
+    ap.add_argument("--fingerprint", default=None,
+                    help="内容指纹（v0.7：参与和声/动机/鼓型变奏；只影响 style 路径，legacy 忽略）")
+    ap.add_argument("--bpm", type=float, default=None,
+                    help="BPM（缺省：legacy 120；风格路径取该风格 bpm_hint 的中位）")
+    ap.add_argument("--key", default=None,
+                    help="调性，可选 " + "/".join(KEYS_ALL) + "（缺省：legacy Dm；风格路径取调池首个）")
     ap.add_argument("--seed", type=int, default=7, help="随机种子，默认 7")
     ap.add_argument("--energy", type=float, default=0.55, help="无 anchors/sections 时的单段能量，默认 0.55")
     ap.add_argument("--anchors", default=None, help="timeline.json 或锚点列表文件（[{id,kind,start,end}]）")
@@ -1853,27 +3693,47 @@ def main(argv=None) -> int:
 
     if args.selftest:
         return selftest()
-
-    _require(args.key in KEYS, f"未知调性 {args.key!r}；可选：{'/'.join(KEYS)}")
+    if args.list_styles:
+        print(_format_style_list())
+        return 0
+
+    sid = _normalize_style_id(args.style)
+    if sid is None:
+        bpm = float(args.bpm) if args.bpm is not None else 120.0
+        key = str(args.key) if args.key else "Dm"
+    else:
+        hint = MUSIC_STYLES[sid]["bpm_hint"]
+        bpm = float(args.bpm) if args.bpm is not None else float(hint[len(hint) // 2])
+        key = str(args.key) if args.key else str(MUSIC_STYLES[sid]["keys"][0])
+    _require(key in KEYS_ALL, f"未知调性 {key!r}；可选：{'/'.join(KEYS_ALL)}")
     anchors = _parse_anchors_file(args.anchors) if args.anchors else None
     sections = _parse_sections_file(args.sections) if args.sections else None
-    if anchors or sections:
-        merged = _merge_sections(anchors, sections, float(args.duration))
-    else:
-        merged = [{"name": "全片", "start": 0.0, "end": float(args.duration), "energy": args.energy}]
-    sc = Score(args.duration, bpm=args.bpm, key=args.key, seed=args.seed)
-    for s in merged:
-        sc.section(s["name"], s["start"], s["end"], s["energy"])
-    if anchors:
-        sc._anchors = [{"id": a.get("id", ""), "kind": a.get("kind", ""),
-                        "start": float(a["start"]), "end": float(a["end"])} for a in anchors]
-    for t, db, dur in _parse_suck_list(args.suck):
-        sc.suck(t, db, dur)
+    sucks = _parse_suck_list(args.suck)
 
     t0 = time.perf_counter()
-    wav = sc.render()
+    if sid is None:
+        # legacy：与 v0.4 完全同一段代码（逐字节兼容是硬契约，不要并进 styled 路径）
+        if anchors or sections:
+            merged = _merge_sections(anchors, sections, float(args.duration))
+        else:
+            merged = [{"name": "全片", "start": 0.0, "end": float(args.duration),
+                       "energy": args.energy}]
+        sc = Score(args.duration, bpm=bpm, key=key, seed=args.seed)
+        for s in merged:
+            sc.section(s["name"], s["start"], s["end"], s["energy"])
+        if anchors:
+            sc._anchors = [{"id": a.get("id", ""), "kind": a.get("kind", ""),
+                            "start": float(a["start"]), "end": float(a["end"])} for a in anchors]
+        for t, db, dur in sucks:
+            sc.suck(t, db, dur)
+        wav = sc.render()
+        rep = sc.report()
+    else:
+        wav, rep = render_styled(args.duration, style=sid, bpm=bpm, key=key, mood=args.mood,
+                                 anchors=anchors, sections=sections, seed=args.seed,
+                                 fingerprint=args.fingerprint,
+                                 sucks=[(t, db, d) for t, db, d in sucks])
     dt = time.perf_counter() - t0
-    rep = sc.report()
     rep["render_s"] = round(dt, 3)
     wav_path = Path(args.out) if args.out else None
     report_path = Path(args.report) if args.report else None