@dsh-gis/dsh-video-studio-skill 0.9.1 → 1.0.2

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

@@ -1,59 +1,57 @@
 # -*- coding: utf-8 -*-
-"""voicekit.py — 旁白声线（Voice Personas）：让每部片的"谁在说话"也不一样。
+"""voicekit.py — 旁白声线：直接给 edge voice id + 语气档 + 响度补偿表。
 
 v0.5.0 新增。v0.4 的 render.py 把 script.voice / rate / pitch 三个单值一路传给
 filmkit.tts_batch，结果是所有片、所有段落都由同一个人用同一种语气念完 ——
 用户的原话是「旁白声音都差不多、整体画风也差不多，希望随内容变化」。
 
-本模块只做「策展 + 计划」：给出每句该用哪个声线、什么语气、语速/音高/音量抖多少、
+D3（v1.0）删掉了 persona 身份层
+-------------------------------
+以前有 9 个 persona（narrator_male 之类）当「谁在说话」的身份表。问题不在名字，
+而在多了一层映射：design/style/line 里写 narrator_male，真正下发给 edge-tts 的却是
+zh-CN-YunyangNeural。任何一层没对齐，表现都是「配了却没生效」，而且要等听成片才发现。
+现在声线一律是 edge voice id（zh-CN-YunxiNeural），映射只发生一次、就在设计里。
+
+被删掉的：PERSONA_IDS / VOICE_PERSONAS / _pick_persona / _govern / legacy 分支，
+以及「文本里有引号就偷偷换人」那套规则 —— 身份是数据，不该由一个正则决定。
+
+但 persona 表里有一件**不能丢**的东西：每把音色的实测响度补偿。删表不补补偿，
+换音色就要人肉重新对电平，正是本次改造要根除的「改了不生效 / 要人调」。
+所以补偿独立成一张按 voice id 的数据表 VOICE_LOUDNESS（没有任何身份含义）。
+
+本模块只做「策展 + 计划」：给出每句用哪个音色、什么语气、语速/音高/音量抖多少、
 前后留白多少。真正的合成仍在 filmkit.tts（Lead 负责接线），因此本模块
 **不 import filmkit**（render.py 会同时 import 两者，互相 import 会成环），
 只依赖 stylekit + 标准库。
 
 三层结构
 --------
-  VOICE_PERSONAS  9 个声线角色（谁在说话）：voice id + 基础语速/音高/音量 + 响度补偿
+  VOICE_LOUDNESS  响度补偿（数据）：每把音色实测的 level 补偿
   VOICE_TONES     6 档语气（怎么说）：相对 deltas + 前后留白 lead/tail
   _rules()        文本规则（说什么）：引号/数字/问叹/长短句/转折词 → 语气与微调
 
-计划优先级（高到低）
+声线从哪来（高到低）
 --------------------
-  lines[].persona / lines[].voice / lines[].tone（显式）
-  > style_plan["voice"]["map"][kind]（风格包）
-  > 文本规则（引号/数字 → 语气）
-  > kind 规则（hook/body/quote/outro 各自的缺省声线）
-  > 默认 persona
+  lines[].voice（显式 edge id）
+  > script.voice.map / design.audio.voice.map 的 kind 映射（D3 设计）
+  > style_plan["voice"]["map"][kind]（风格包 / designkit.design_to_plan）
+  > script.voice.id / design.audio.voice.id / style_plan["voice"]["default"]（主声线）
+没有任何来源就报错（并给出迁移路径）——D3 的设计必须明确「谁在说话」。
+
+声线一旦确定就**不再治理**：以前 _govern 会在段边界偷偷换人、用 max_distinct 限预算，
+那层逻辑只对 persona 有意义（为了「别让一部片出现太多人」）。现在 map 怎么写就怎么念，
+声线策略里的 max_distinct 随之退休 —— 想少换人就少写几个 kind，不需要中间层猜意图。
 
 确定性
 ------
-所有抖动都来自 sha1(title|id|persona)，禁 random / time / hash()（str hash 带盐）。
+所有抖动都来自 sha1(title|id|voice)，禁 random / time / hash()（str hash 带盐）。
 同一份 film.json 两次 voice_plan() 完全相等；jitter=0 时与「无抖动」逐字段相等。
 
-legacy 兼容
------------
-style_plan["legacy"] 为 True（film.json 没有 style 字段）时不换人、不加抖动、不叠语气：
-全部用 script 的 voice/rate/pitch 单值 + script 的 lead/tail，与 v0.4 逐字段一致。
-这是硬契约：legacy 路径的任何变化都会让老项目音频变样、缓存全失效。
-
-校准（实测定稿，换 voice id 必须重测）
---------------------------------------
-2026-11-09 在本机用 edge-tts 7.3.1 合成同一句校准文本
-「这是一句用来校准的中文样本，长度大约二十个字。」（20 个汉字），
-用 ffmpeg 解成 24k 单声道后测门限 RMS（20ms 帧，低于 -45 dBFS 的静音帧不计）。
-目标响度取 9 个 persona 的中位数 -20.97 dBFS；gain_db = 目标 - 实测，夹在 ±3 dB：
-    narrator_male      Yunyang     4.56s 4.61cps -24.39dBFS -> +3.00
-    narrator_female    Xiaoxiao    4.63s 4.53cps -18.28dBFS -> -2.69
-    warm_female        HsiaoChen   5.33s 3.94cps -17.51dBFS -> -3.00（原始 -3.46，夹到 -3）
-    bright_female      Xiaoyi      4.73s 4.44cps -20.40dBFS -> -0.57
-    authority_male     Yunjian     5.21s 4.03cps -21.98dBFS -> +1.01
-    young_male         Yunxi       4.80s 4.38cps -22.91dBFS -> +1.94
-    teen_male          Yunxia      4.85s 4.33cps -21.27dBFS -> +0.30
-    dialect_ne_female  Xiaobei     5.47s 3.84cps -20.97dBFS ->  0.00
-    dialect_sx_female  Xiaoni      5.09s 4.13cps -20.63dBFS -> -0.34
-edge-tts 免费端点只提供上面 8 个 zh-CN 音色（另有 zh-TW/zh-HK，可用但带腔），
-故 9 个 persona 复用 8 个 voice id：warm_female 用 zh-TW-HsiaoChenNeural
-（微软标注 "Warm, considerate"，实测基频 194Hz 低于 Xiaoxiao 的 238Hz，确实更暖；
-若目标观众只要大陆标准音，把它换成 zh-CN-XiaoxiaoNeural 并降速即可，其余字段不用改）。
+迁移（老结构）
+--------------
+v0.4 的「顶层 voice 单值」和「没有 design 的 legacy 计划」不再支持：voice_plan 直接抛
+ValueError，消息里给三条可照抄的迁移路径（design.audio.voice / lines[].voice / voice.map）。
+不静默回落是刻意的：静默回落 = 配音变了却没人知道，比报错难查得多。
 
 用法
 ----
@@ -61,14 +59,17 @@ edge-tts 免费端点只提供上面 8 个 zh-CN 音色（另有 zh-TW/zh-HK，
     plan = VK.voice_plan(script, ST.resolve_script_style(script))
     VK.describe(plan)
     VK.spec_key(dict(plan[0], text=script["lines"][0]["text"]))   # v2 缓存键
+    VK.calibrate_voice("zh-CN-YunxiNeural")   # 联网实测；离线 measured=False，不抛
 
-    python voicekit.py --list                  # 声线/语气表
+    python voicekit.py --list                 # 音色响度表 + 语气档
     python voicekit.py --plan film.json       # 某份剧本的声线计划（可读表格）
-    python voicekit.py --calibrate            # 联网实测 dur/RMS/cps，打印建议 gain_db（失败 SKIP 返回 0）
+    python voicekit.py --calibrate --only zh-CN-YunxiNeural   # 联网实测，打印该抄回的数
 """
 from __future__ import annotations
 
 import argparse
+import array
+import asyncio
 import hashlib
 import json
 import math
@@ -81,97 +82,75 @@ import tempfile
 import wave
 
 # ============================================================================
-# 一、声线（谁在说话）
+# 一、响度补偿（数据，不是身份）：换音色不用手调电平
 # ============================================================================
 #
-# 字段口径：
-#   voice     edge-tts 的 voice id（"-" 分隔且以 Neural 结尾）
-#   rate/pitch/volume  字符串，直接透传给 edge_tts.Communicate（只接受整数）
-#   gain_db  mix 侧给该句加的分贝（正 = 该音色偏轻，需要补），已按校准文本实测
-#   desc     人话说明（打印 / --list 用）
-#   narrate  能否被"自动"选来念长段叙述（方言/少年音只适合引用与点缀，设 False）
-#   home     该声线的"主场"段落类型（hook/body/quote/outro），给 governor 与文档用
-
-PERSONA_IDS = (
-    "narrator_male", "narrator_female", "warm_female", "bright_female",
-    "authority_male", "young_male", "teen_male",
-    "dialect_ne_female", "dialect_sx_female",
-)
-
-VOICE_PERSONAS = {
-    "narrator_male": {
-        "voice": "zh-CN-YunyangNeural", "rate": "+2%", "pitch": "+0Hz", "volume": "+0%",
-        "gain_db": 3.0, "narrate": True, "home": "body",
-        "desc": "新闻/纪录片男声，稳、清楚，默认叙述（实测最轻，+3dB 补偿）",
-    },
-    "narrator_female": {
-        "voice": "zh-CN-XiaoxiaoNeural", "rate": "+5%", "pitch": "+0Hz", "volume": "+0%",
-        "gain_db": -2.7, "narrate": True, "home": "body",
-        "desc": "标准女声叙述，清澈不甜，报告/复盘/知识片（实测最响，-2.7dB）",
-    },
-    "warm_female": {
-        "voice": "zh-TW-HsiaoChenNeural", "rate": "-2%", "pitch": "-1Hz", "volume": "+2%",
-        "gain_db": -3.0, "narrate": True, "home": "outro",
-        "desc": "软糯女声（台湾腔），低基频 194Hz，适合纸感/人文/深夜",
-    },
-    "bright_female": {
-        "voice": "zh-CN-XiaoyiNeural", "rate": "+6%", "pitch": "+2Hz", "volume": "+3%",
-        "gain_db": -0.6, "narrate": True, "home": "hook",
-        "desc": "活泼女声，高基频 289Hz，适合活力/营销/上新",
-    },
-    "authority_male": {
-        "voice": "zh-CN-YunjianNeural", "rate": "+2%", "pitch": "-2Hz", "volume": "+2%",
-        "gain_db": 1.0, "narrate": True, "home": "hook",
-        "desc": "有力男声，慢而沉，适合开场/观点/史诗（实测 3.96cps 最慢）",
-    },
-    "young_male": {
-        "voice": "zh-CN-YunxiNeural", "rate": "+5%", "pitch": "+1Hz", "volume": "+1%",
-        "gain_db": 1.9, "narrate": True, "home": "quote",
-        "desc": "青年男声（v0.4 的缺省音色），适合引用、对话、年轻向内容",
-    },
-    "teen_male": {
-        "voice": "zh-CN-YunxiaNeural", "rate": "+7%", "pitch": "+1Hz", "volume": "+2%",
-        "gain_db": 0.3, "narrate": False, "home": "quote",
-        "desc": "少年音，基频 282Hz，只适合引用/角色台词，别整片念",
-    },
-    "dialect_ne_female": {
-        "voice": "zh-CN-liaoning-XiaobeiNeural", "rate": "+4%", "pitch": "+0Hz", "volume": "+0%",
-        "gain_db": 0.0, "narrate": False, "home": "quote",
-        "desc": "东北女声，自带喜感，适合引用/段子/接地气内容",
-    },
-    "dialect_sx_female": {
-        "voice": "zh-CN-shaanxi-XiaoniNeural", "rate": "+3%", "pitch": "+0Hz", "volume": "+0%",
-        "gain_db": -0.3, "narrate": False, "home": "quote",
-        "desc": "陕西女声，质地厚，适合引用/方言故事/纪录片片段",
-    },
+# 为什么这张表不能跟着 persona 一起删：
+#   9 个 persona 的实测响度跨度 6.0 dB（-3.0 ~ +3.0）。差别来自音色本身（基频、气声、
+#   端点侧的归一化），跟台词、语气、机器负载都无关，但**换一把音色就会整体偏几 dB**。
+#   删表不补补偿，每次换音色都要试听、手调 gain —— 那正是「改了不生效 / 要人调」。
+#
+# 口径：gain_db = 目标响度 - 实测 rms_db，夹在 ±3 dB（正 = 该音色偏轻，mix 侧补回来）。
+#   - 实测：2026-11-09 在本机用 edge-tts 7.3.1 合成同一句校准文本（CALIB_TEXT，21 个
+#     汉字），ffmpeg 解成 24k 单声道，测 20ms 帧门限 RMS（低于 -45 dBFS 的静音帧不计）；
+#   - 目标：CALIBRATION_LOG 里 9 条实测 rms_db 的中位数（-20.97 dBFS），由下方
+#     CALIB_TARGET_DB 现算，不另写第二个魔数。
+#
+# **换机 / 换 edge-tts 版本 / 换 voice id 都要重测**：同一把音色在不同机器、不同版本上
+# 差 1~2 dB 很常见，把上次的数字跨机照抄会一句响一句轻。重测入口：
+#   python voicekit.py --calibrate（结果记 work/voice_calib.json，并打印该抄回的数）
+VOICE_LOUDNESS = {
+    "zh-CN-YunyangNeural": 3.0,           # 新闻/纪录片男声，实测最轻
+    "zh-CN-XiaoxiaoNeural": -2.7,         # 标准女声，实测最响
+    "zh-TW-HsiaoChenNeural": -3.0,        # 软糯女声（台湾腔），原始 -3.46，夹到 -3
+    "zh-CN-XiaoyiNeural": -0.6,           # 活泼女声
+    "zh-CN-YunjianNeural": 1.0,           # 有力男声
+    "zh-CN-YunxiNeural": 1.9,             # 青年男声（v0.4 的缺省音色）
+    "zh-CN-YunxiaNeural": 0.3,            # 少年音
+    "zh-CN-liaoning-XiaobeiNeural": 0.0,  # 东北女声（本次校准的基准，补偿 0）
+    "zh-CN-shaanxi-XiaoniNeural": -0.3,   # 陕西女声
 }
 
-# 校准日志：--calibrate 会用实测值对比这里，换 voice id 后重跑一次再改表
+# 表里没有的音色按 0 dB 处理（不猜），voice_plan 的 reason 会标 unmeasured_voice：
+# 让人一眼看出「这句没补过」，而不是以为补过了。
 CALIBRATED_ON = "2026-11-09"
 CALIB_TEXT = "这是一句用来校准的中文样本，长度大约二十个字。"
 CALIBRATION_LOG = {
-    "narrator_male": {"dur": 4.56, "cps": 4.61, "rms_db": -24.39},
-    "narrator_female": {"dur": 4.63, "cps": 4.53, "rms_db": -18.28},
-    "warm_female": {"dur": 5.33, "cps": 3.94, "rms_db": -17.51},
-    "bright_female": {"dur": 4.73, "cps": 4.44, "rms_db": -20.40},
-    "authority_male": {"dur": 5.21, "cps": 4.03, "rms_db": -21.98},
-    "young_male": {"dur": 4.80, "cps": 4.38, "rms_db": -22.91},
-    "teen_male": {"dur": 4.85, "cps": 4.33, "rms_db": -21.27},
-    "dialect_ne_female": {"dur": 5.47, "cps": 3.84, "rms_db": -20.97},
-    "dialect_sx_female": {"dur": 5.09, "cps": 4.13, "rms_db": -20.63},
+    "zh-CN-YunyangNeural": {"dur": 4.56, "cps": 4.61, "rms_db": -24.39},
+    "zh-CN-XiaoxiaoNeural": {"dur": 4.63, "cps": 4.53, "rms_db": -18.28},
+    "zh-TW-HsiaoChenNeural": {"dur": 5.33, "cps": 3.94, "rms_db": -17.51},
+    "zh-CN-XiaoyiNeural": {"dur": 4.73, "cps": 4.44, "rms_db": -20.40},
+    "zh-CN-YunjianNeural": {"dur": 5.21, "cps": 4.03, "rms_db": -21.98},
+    "zh-CN-YunxiNeural": {"dur": 4.80, "cps": 4.38, "rms_db": -22.91},
+    "zh-CN-YunxiaNeural": {"dur": 4.85, "cps": 4.33, "rms_db": -21.27},
+    "zh-CN-liaoning-XiaobeiNeural": {"dur": 5.47, "cps": 3.84, "rms_db": -20.97},
+    "zh-CN-shaanxi-XiaoniNeural": {"dur": 5.09, "cps": 4.13, "rms_db": -20.63},
 }
 
+
+def _median(values):
+    """中位数（偶数个取上中位）：定目标响度，不为了一个数去 import statistics。"""
+    xs = sorted(float(v) for v in values)
+    return xs[len(xs) // 2] if xs else 0.0
+
+
+CALIB_TARGET_DB = round(_median(r["rms_db"] for r in CALIBRATION_LOG.values()), 2)
+
 # ============================================================================
-# 二、语气（怎么说）：deltas 叠在 persona 上；lead/tail 是 v0.4 基准附近的偏移量
+# 二、语气（怎么说）：deltas 叠在「裸 voice id」上；lead/tail 是基准行的偏移
 # ============================================================================
-# body 必须等于 v0.4 现状：lead 0.62 / tail 0.92 / 所有 delta = 0，legacy 才可能逐字段一致。
+# body 是基准行：所有 delta = 0，lead/tail 就是 BODY_LEAD / BODY_TAIL。
+# voice_plan 只在这个基准上加减，所以「某一句听起来不对」时先看 reason 里是 tone:xxx
+# 还是 rule:xxx，改一处就够，不用同时去翻音色表和文本规则。
 BODY_LEAD = 0.62
 BODY_TAIL = 0.92
 TONE_IDS = ("body", "hook", "quote", "outro", "emphasis", "calm")
 
+# gain_db 是**语气自己的**电平增量（强调句要更响），与 VOICE_LOUDNESS 的「音色补偿」
+# 是两回事：前者是表演，后者是设备；voice_plan 里两者相加，各自都能单独解释。
 VOICE_TONES = {
     "body": {"rate_delta": 0, "pitch_delta": 0, "volume_delta": 0, "gain_db": 0.0,
-             "lead": 0.62, "tail": 0.92, "desc": "正文，平稳（v0.4 基准）"},
+             "lead": 0.62, "tail": 0.92, "desc": "正文，平稳（基准行）"},
     "hook": {"rate_delta": 3, "pitch_delta": 1, "volume_delta": 2, "gain_db": 0.6,
              "lead": 0.48, "tail": 0.78, "desc": "开场，提一点速压一点留白，抓人"},
     "quote": {"rate_delta": -2, "pitch_delta": -1, "volume_delta": 1, "gain_db": 0.4,
@@ -184,13 +163,6 @@ VOICE_TONES = {
              "lead": 0.88, "tail": 1.25, "desc": "沉静，长留白，适合思辨/深夜"},
 }
 
-# kind 规则：风格包没给映射时的缺省声线（风格包优先）
-KIND_DEFAULT = {
-    "hook": "authority_male", "body": "narrator_male",
-    "quote": "narrator_female", "outro": "warm_female",
-}
-
-LEGACY_VOICE = "zh-CN-YunxiNeural"       # 与 render.py 的 script.get("voice", ...) 缺省一致
 _RATE_LIMIT = (-15, 12)                  # 与 stylekit policy 的缺省一致
 _PITCH_LIMIT = (-8, 8)
 _VOL_LIMIT = (-10, 10)
@@ -200,7 +172,7 @@ _GAIN_LIMIT = 3.0
 
 try:
     import stylekit as _ST
-except Exception:                        # noqa: BLE001 — stylekit 缺失时走兜底解析
+except Exception:                        # noqa: BLE001 — stylekit 缺失时只少了风格包这一层
     _ST = None
 
 
@@ -209,8 +181,8 @@ except Exception:                        # noqa: BLE001 — stylekit 缺失时
 # ============================================================================
 # 允许小数（"+4.5%"）：edge-tts 只收整数百分比，所以解析后按 _round_half_away 取整。
 # 以前正则只认整数，"+4.5%" 解析失败 → 静默回落 0 —— 而 0 与 "+0%" 在 spec_key 里
-# 是**同一个 TTS 缓存键**，于是"把语速从 0 调到 4.5%"完全没生效，还复用了旧音频。
-# 这是配置写对了却不生效里最难查的一类：没有报错、没有日志、听起来就是"没反应"。
+# 是**同一个 TTS 缓存键**，于是「把语速从 0 调到 4.5%」完全没生效，还复用了旧音频。
+# 这是配置写对了却不生效里最难查的一类：没有报错、没有日志、听起来就是「没反应」。
 _PCT_RE = re.compile(r"^\s*([+-]?)(\d+(?:\.\d+)?)\s*%\s*$")
 _HZ_RE = re.compile(r"^\s*([+-]?)(\d+(?:\.\d+)?)\s*Hz\s*$")
 
@@ -262,7 +234,7 @@ def hanzi_count(text):
 
 
 def is_edge_voice(name):
-    """形如 zh-CN-YunxiNeural 的原始 voice id（不是 persona 名）。"""
+    """形如 zh-CN-YunxiNeural 的原始 voice id（不是 persona 名 / 不是路径）。"""
     n = str(name or "").strip()
     return ("-" in n) and n.endswith("Neural")
 
@@ -280,7 +252,7 @@ def _clamp(v, lo, hi):
 
 
 def _jitter(title, lid, who):
-    """sha1(title|id|persona) 派生确定性抖动：rate/pitch/lead/tail + 两个量化阈值。
+    """sha1(title|id|voice) 派生确定性抖动：rate/pitch/lead/tail + 两个量化阈值。
 
     rate/pitch 是浮点目标值（±1.5% / ±1Hz 再乘 policy.jitter），但 edge-tts 只收整数；
     若直接四舍五入，jitter=0.35 时 ±0.5 的小数会被吃光、抖动形同不存在。
@@ -297,7 +269,7 @@ def _jitter(title, lid, who):
 
 
 def _quantize(v, u):
-    """确定性随机进位：`floor(v)+1` 的概率 = v 的小数部分，期望值仍是 v。
+    """确定性随机进位：floor(v)+1 的概率 = v 的小数部分，期望值仍是 v。
 
     u 来自 sha1（同一句永远同一结果），用来把浮点抖动量化成 edge-tts 能收的整数。
     v 本身是整数时（jitter=0）绝不进位，保证与「无抖动」逐字段相等。
@@ -310,10 +282,9 @@ def _quantize(v, u):
 # ============================================================================
 # 四、文本规则（说什么）：全部确定性，命中即返回理由
 # ============================================================================
-# 引语起始符。**不含书名号 《（《）**：正文里出现"《设计模式》"是书名，不是引用某人在说话。
-# 实测踩过：把 《 算进引语后，"今天我们聊《设计模式》"这句的 tone 被判成 quote，
-# 进而触发 rule:quote:persona，把 persona 从 narrator_male 换成 narrator_female ——
-# 旁白中途换人，听感像换了主播（而这句根本没有人引语）。
+# 引语起始符。**不含书名号《》**：正文里出现「《设计模式》」是书名，不是引用某人在说话。
+# 实测踩过：把 《 算进引语后，「今天我们聊《设计模式》」这句被判成 quote 语气 ——
+# 整句降速、留白加长，听感像突然换了频道（而这句根本没有人引语）。
 _QUOTE_OPEN = ('"', "\u201c", "\u300c", "\u300e")
 _QUOTE_WORDS = ("他说", "她说", "有人问", "所谓", "据称")
 _NUM_UNITS = ("%", "万", "亿", "年", "倍")
@@ -356,85 +327,120 @@ def _rules(text):
 # 五、计划：每句用谁、什么语气、多快多响多长留白
 # ============================================================================
 def _resolve(script, style_plan):
-    """拿 stylekit 的计划；没有就调 stylekit 算；stylekit 也没有就兜底。"""
+    """拿风格计划：显式参数 > script["_style"]（render 已解析过）> stylekit 现算 > {}。
+
+    返回 {} 不是故障：D3 的声线来源是 design.audio.voice，本模块自己就能读；
+    stylekit 只负责风格包/节奏这一层，缺了它照样能出 voice 计划。
+    """
     if isinstance(style_plan, dict) and style_plan:
         return style_plan
+    cached = script.get("_style")
+    if isinstance(cached, dict) and cached:
+        return cached
     if _ST is not None:
         try:
             return _ST.resolve_script_style(script)
-        except Exception:                # noqa: BLE001 — 坏剧本交给 filmkit 报错
+        except Exception:                # noqa: BLE001 — 坏剧本交给 filmcheck 报错
             pass
-    vis = script.get("visual") if isinstance(script.get("visual"), dict) else {}
-    voce = script.get("voice") if isinstance(script.get("voice"), dict) else {}
-    legacy = ("style" not in script) and not vis.get("theme")
-    return {
-        "legacy": bool(legacy),
-        "voice": {"map": {}, "default": voce.get("default"), "policy": {
-            "auto": not legacy, "jitter": 0.0 if legacy else 0.35,
-            "max_distinct": 2 if legacy else 3,
-            "rate_range": list(_RATE_LIMIT), "pitch_range": list(_PITCH_LIMIT)}},
-        "pacing": {"lead": float(script.get("lead", 0.55)),
-                   "tail": float(script.get("tail", 0.85))},
-    }
+    return {}
 
 
-def _fmt_num(v):
-    """计划里的 lead/tail 统一保留 3 位（避免 0.6200000000001 这种浮点尾巴）。"""
-    return round(float(v) + 0.0, 3)
+def _design_voice(script):
+    """读 D3 设计的声线：返回 (主声线, {kind: id}, 策略 {auto, jitter})。
 
+    为什么直接读 script["design"] 而不只依赖 style_plan：D3 的单测/验收会直接
+    voice_plan(script)，此时没有 render.py 解析过的 _style；而 stylekit 对「没有
+    design」的剧本已经直接报错，_resolve 只能返回 {}。design.audio.voice 是声线的
+    唯一事实来源，能读就读，别要求调用方先跑一遍 render。
 
-def _legacy_plan(script, lines, pace):
-    """v0.4 路径：单值 voice/rate/pitch + script 的 lead/tail，无抖动无语气。"""
-    voice = str(script.get("voice") or LEGACY_VOICE)
-    rate = script.get("rate")
-    pitch = script.get("pitch")
-    rate_s = fmt_pct(parse_pct(rate)) if isinstance(rate, (int, float)) else str(rate or "+0%")
-    pitch_s = fmt_hz(parse_hz(pitch)) if isinstance(pitch, (int, float)) else str(pitch or "+0Hz")
-    lead = float(script.get("lead", pace.get("lead", 0.55)))
-    tail = float(script.get("tail", pace.get("tail", 0.85)))
-    rows = []
-    for i, ln in enumerate(lines):
-        ln = ln if isinstance(ln, dict) else {}
-        rows.append({
-            "id": str(ln.get("id") or ("l%02d" % (i + 1))),
-            "kind": str(ln.get("kind") or "body"),
-            "persona": None, "tone": "body", "voice": voice,
-            "rate": rate_s, "pitch": pitch_s, "volume": "+0%", "gain_db": 0.0,
-            "lead": _fmt_num(lead), "tail": _fmt_num(tail), "reason": "legacy",
-        })
-    return rows
+    策略跟着设计走（与 designkit.design_to_plan 对齐）：裸 id = 单声线、不抖动、
+    不加文本规则；dict = 设计采样出来的多声线方案，auto=True、jitter 取设计值。
+    本模块不 import designkit（那会多一层依赖），所以这三项在这里读一遍。
+    """
+    des = script.get("design") if isinstance(script.get("design"), dict) else {}
+    au = des.get("audio") if isinstance(des.get("audio"), dict) else {}
+    vo = au.get("voice")
+    if isinstance(vo, str):
+        return (vo.strip() or None), {}, {"auto": False, "jitter": 0.0}
+    if not isinstance(vo, dict):
+        return None, {}, {}
+    mode = str(vo.get("mode") or "").strip()
+    if mode == "wav":
+        raise ValueError(
+            "design.audio.voice.mode='wav'：voicekit 只出 edge-tts 的声线计划，"
+            "wav 音色（录音/克隆）请直接交给混音侧，别从这里过。")
+    vid = str(vo.get("id") or "").strip() or None
+    raw = vo.get("map") if isinstance(vo.get("map"), dict) else {}
+    vmap = {}
+    for kind, v in raw.items():
+        if isinstance(v, dict):
+            v = v.get("id")
+        if v not in (None, ""):
+            vmap[str(kind)] = str(v).strip()
+    try:
+        jitter = max(0.0, float(vo.get("jitter", 0.0)))
+    except (TypeError, ValueError):
+        jitter = 0.0
+    return vid, vmap, {"auto": True, "jitter": jitter}
 
 
-def _pick_persona(line, kind, vmap, default, reasons):
-    """返回 (persona 或 None, 是否显式, 原始 voice id 或 None)。"""
-    for field in ("persona", "voice"):
-        raw = line.get(field)
-        if raw in (None, ""):
-            continue
-        name = str(raw).strip()
-        if name in VOICE_PERSONAS:
-            reasons.append("explicit:%s" % field)
-            return name, True, None
-        if is_edge_voice(name):
-            reasons.append("explicit:%s" % field)
-            return None, True, name
-        reasons.append("unknown_persona:%s" % name)
-    mapped = vmap.get(kind, vmap.get("*"))
-    if mapped:
-        name = str(mapped).strip()
-        if name in VOICE_PERSONAS:
-            reasons.append("map:%s" % kind)
-            return name, False, None
-        if is_edge_voice(name):
-            reasons.append("map:%s" % kind)
-            return None, False, name
-        reasons.append("unknown_map:%s" % name)
-    if default:
-        reasons.append("default")
-        return default, False, None
-    name = KIND_DEFAULT.get(kind, "narrator_male")
-    reasons.append("kind:%s" % kind)
-    return name, False, None
+def _script_voice(script):
+    """v0.5 形状的 script.voice（dict）：返回 (主声线, {kind: id})。"""
+    vo = script.get("voice")
+    if not isinstance(vo, dict):
+        return None, {}
+    vid = str(vo.get("id") or vo.get("default") or "").strip() or None
+    raw = vo.get("map") if isinstance(vo.get("map"), dict) else {}
+    vmap = {str(k): str(v).strip() for k, v in raw.items() if v not in (None, "")}
+    return vid, vmap
+
+
+def _style_voice(sp):
+    """style_plan["voice"]：返回 ({kind: id}, 主声线)。"""
+    vsec = sp.get("voice") if isinstance(sp.get("voice"), dict) else {}
+    raw = vsec.get("map") if isinstance(vsec.get("map"), dict) else {}
+    vmap = {str(k): str(v).strip() for k, v in raw.items() if v not in (None, "")}
+    default = str(vsec.get("default") or "").strip() or None
+    return vmap, default
+
+
+# 迁移说明只写一份：三处报错（persona / 老结构 / map 值）都指向它，避免各处各写一套。
+_MIGRATE = (
+    "声线现在一律写 edge voice id（形如 zh-CN-YunxiNeural）。迁移任选一条：\n"
+    "  1) design.json：audio.voice = {\"mode\": \"edge_id\", \"id\": \"zh-CN-YunxiNeural\"}；"
+    "要分段换声线再加 map: {\"hook\": \"zh-CN-YunjianNeural\"}；\n"
+    "  2) film.json：lines[].voice 逐句写 id；\n"
+    "  3) 风格包 / voice.map：值改成 edge voice id。\n"
+    "可用音色与实测响度补偿：python voicekit.py --list"
+)
+
+
+def _bad_voice(field, value):
+    return ValueError("%s = %r 不是 edge voice id，而 voicekit 从 D3 起已删掉 persona 身份表。\n%s"
+                      % (field, value, _MIGRATE))
+
+
+def _old_structure(script, sp, scalar=None):
+    """老结构（v0.4 单值 voice / 没有 design 的 legacy）不再支持：直说怎么迁移。"""
+    bits = []
+    if scalar:
+        bits.append("顶层 voice = %r，v0.4 的单值声线" % scalar)
+    if sp.get("legacy"):
+        bits.append("风格计划判定为 legacy（film.json 里没有 design/style）")
+    return ValueError(
+        "这份剧本还是老结构（%s），而 voicekit 从 D3 起已删掉 legacy / persona 路径。\n%s"
+        % ("；".join(bits) or "没有 design.audio.voice，也没有 lines[].voice / voice.map", _MIGRATE))
+
+
+def _validate_voice_map(field, vmap):
+    for kind, vid in vmap.items():
+        if not is_edge_voice(vid):
+            raise _bad_voice("%s[%r]" % (field, kind), vid)
+
+
+def _fmt_num(v):
+    """计划里的 lead/tail 统一保留 3 位（避免 0.6200000000001 这种浮点尾巴）。"""
+    return round(float(v) + 0.0, 3)
 
 
 def _pick_tone(line, kind, rules, use_rules, reasons):
@@ -454,74 +460,75 @@ def _pick_tone(line, kind, rules, use_rules, reasons):
     return "body"
 
 
-def _govern(cand, prev, kind, prev_kind, used, max_distinct, explicit, fallback=None,
-            quote_rule=False):
-    """换人治理：同段落不换人；换段可换，但要过 max_distinct 预算。
-
-    返回 (最终 persona, 附加 reason)。相邻两句不换人是防"广播剧"的关键：
-    同一 kind 的连续句子必须由同一把声音念；只有显式指定、或到了 hook/body/quote/outro
-    的段落边界（body->quote 是 spec 明说的允许点），才会换。
-    预算用尽时优先回到"正文声线"（fallback），避免收尾句被引用声线一路念到底。
-    quote_rule=True 表示"这句文本有引号、该由 quote 声线念"：这是 body->quote 的
-    spec 允许点，不受同 kind 限制、也不占 max_distinct 预算（reason 记 governor:quote）。
-    """
-    if explicit or cand is None or prev is None:
-        # 显式指定 / 风格包直接写了原始 voice id：一律放行，不参与换人治理
-        return cand, ""
-    if cand == prev:
-        return cand, ""
-    if quote_rule:
-        return cand, "governor:quote"
-    if kind == prev_kind:
-        return prev, "governor:glue"
-    if cand not in used and len(used) >= max_distinct:
-        # 预算用尽：只有"正文声线已经在用"时才能回落，否则会偷偷多出第 max_distinct+1 个人
-        if fallback and fallback in used and fallback != cand:
-            return fallback, "governor:cap"
-        return prev, "governor:cap"
-    return cand, "governor:switch"
-
-
 def voice_plan(script, style_plan=None):
     """把剧本拆成逐句的旁白计划（纯函数、确定性，两次调用结果完全相等）。
 
     参数
     ----
     script      film.json 解析后的 dict（只读，不修改）
-    style_plan  stylekit.resolve_script_style(script) 的返回值；None 时本模块自己算
+    style_plan  stylekit.resolve_script_style() 或 designkit.design_to_plan() 的返回；
+                None 时本模块自己解析（design.audio.voice 优先，其次 stylekit）
 
     返回
     ----
     list[dict]，每行：id / kind / persona / tone / voice / rate / pitch / volume /
     gain_db / lead / tail / reason。rate/pitch/volume 是可直接透传 edge-tts 的字符串。
+    persona 字段**保留但恒为 None**（老下游可能读它）；voice 恒为 edge voice id。
     """
     script = script if isinstance(script, dict) else {}
     sp = _resolve(script, style_plan)
     lines = [ln for ln in (script.get("lines") or [])]
+    if not lines:
+        return []                        # 空剧本给空计划；缺 lines 由 filmcheck 报
     vsec = sp.get("voice") if isinstance(sp.get("voice"), dict) else {}
     policy = vsec.get("policy") if isinstance(vsec.get("policy"), dict) else {}
     pace = sp.get("pacing") if isinstance(sp.get("pacing"), dict) else {}
 
-    if sp.get("legacy"):
-        return _legacy_plan(script, lines, pace)
-
-    jitter = max(0.0, float(policy.get("jitter", 0.35)))
+    # ---- 声线来源：显式覆盖 > 设计 > 风格包（合并时后者先铺、前者覆盖）----
+    s_vid, s_map = _script_voice(script)
+    d_vid, d_map, d_pol = _design_voice(script)
+    p_map, p_default = _style_voice(sp)
+    vmap = {}
+    vmap.update(p_map)
+    vmap.update(d_map)
+    vmap.update(s_map)
+    default = s_vid or d_vid or p_default
+    for field, m in (("script.voice.map", s_map), ("design.audio.voice.map", d_map),
+                     ("style_plan.voice.map", p_map)):
+        _validate_voice_map(field, m)
+    for field, vid in (("script.voice.id", s_vid), ("design.audio.voice.id", d_vid),
+                       ("style_plan.voice.default", p_default)):
+        if vid and not is_edge_voice(vid):
+            raise _bad_voice(field, vid)
+
+    scalar = script.get("voice")
+    has_line_voice = any(isinstance(ln, dict) and ln.get("voice") for ln in lines)
+    if isinstance(scalar, str) and scalar.strip():
+        # v0.4 的单值声线。D3 之后声线事实来源只有 design.audio.voice（或逐句 voice），
+        # 再读它会和 design 打架，而「谁生效」取决于调用顺序 —— 最难查的一类。
+        raise _old_structure(script, sp, scalar.strip())
+    if not (default or vmap or has_line_voice):
+        # 没有任何来源时**不猜**：以前会静默套 kind 缺省，整片悄悄换声线。
+        # 宁可报错一次，让人把 design.audio.voice 补上。
+        if isinstance(script.get("design"), dict):
+            raise ValueError(
+                "design.audio.voice 没有给出声线（id 与 map 都为空）：D3 起设计必须明确"
+                "「谁在说话」。\n" + _MIGRATE)
+        raise _old_structure(script, sp)
+
+    # 策略：显式 style_plan 优先；没有（例如直接 voice_plan(script)）就用设计里的策略。
+    # jitter 缺省 0.0 —— 抖动必须是设计采样出来的，不能由计划层凭空加。
+    if not policy and d_pol:
+        policy = d_pol
+    jitter = max(0.0, float(policy.get("jitter", 0.0)))
     use_rules = _as_bool(policy.get("auto"), True)
-    max_distinct = max(1, int(policy.get("max_distinct", 3)))
     rate_lim = tuple(policy.get("rate_range") or _RATE_LIMIT)
     pitch_lim = tuple(policy.get("pitch_range") or _PITCH_LIMIT)
-    vmap = vsec.get("map") if isinstance(vsec.get("map"), dict) else {}
-    default = str(vsec.get("default") or "").strip()
-    default = default if default in VOICE_PERSONAS else ""
     base_lead = float(pace.get("lead", 0.55))
     base_tail = float(pace.get("tail", 0.85))
     title = str(script.get("title") or "")
-    # 正文声线锚点：预算用尽时回落用它，让"旁白"始终是正文那把声音
-    body_persona = vmap.get("body") if vmap.get("body") in VOICE_PERSONAS else None
-    body_persona = body_persona or default or KIND_DEFAULT.get("body", "narrator_male")
 
-    rows, used = [], []
-    prev_persona, prev_kind = None, None
+    rows = []
     for i, ln in enumerate(lines):
         ln = ln if isinstance(ln, dict) else {}
         lid = str(ln.get("id") or ("l%02d" % (i + 1)))
@@ -530,43 +537,42 @@ def voice_plan(script, style_plan=None):
         rules = _rules(ln.get("text")) if use_rules else {
             "tone": "", "rate": 0, "volume": 0, "tail": 0.0, "reasons": []}
 
-        cand, explicit, raw_voice = _pick_persona(ln, kind, vmap, default, reasons)
-        # 文本规则也要能换人：kind 仍标 body 的「他说：『…』」不能还是正文那条嗓子，
-        # 否则语气换了、声音没换，听感依旧是同一个人在念。显式 voice/tone 优先级更高。
-        quote_rule = False
-        if not explicit and rules["tone"] == "quote" and cand is not None and cand == body_persona:
-            quote_p = vmap.get("quote") if vmap.get("quote") in VOICE_PERSONAS else None
-            quote_p = quote_p or KIND_DEFAULT.get("quote", "narrator_female")
-            if quote_p != cand:
-                cand = quote_p
-                quote_rule = True
-                reasons.append("rule:quote:persona")
-        final, gov = _govern(cand, prev_persona, kind, prev_kind, used, max_distinct,
-                             explicit, body_persona, quote_rule)
-        if gov:
-            reasons.append(gov)
-        if final is not None and final not in used:
-            used.append(final)
+        # 身份只有一个来源，写错就报错，不再「悄悄回落到某个缺省声线」：
+        # 以前拼错 persona 名会静默换人（听感变了但没有任何提示），是本项目最忌讳的坑。
+        raw_p = ln.get("persona")
+        if raw_p not in (None, ""):
+            raise _bad_voice("lines[%d].persona" % i, raw_p)
+        raw_v = ln.get("voice")
+        if raw_v not in (None, ""):
+            voice = str(raw_v).strip()
+            if not is_edge_voice(voice):
+                raise _bad_voice("lines[%d].voice" % i, raw_v)
+            reasons.append("explicit:voice")
+        else:
+            mapped = vmap.get(kind, vmap.get("*"))
+            if mapped:
+                voice = mapped
+                reasons.append("map:%s" % kind)
+            elif default:
+                voice = default
+                reasons.append("default")
+            else:
+                raise ValueError(
+                    "声线映射没覆盖 lines[%d].kind=%r，也没有全片主声线：不知道这句该谁念。\n"
+                    "补 design.audio.voice.id（全片主声线）或 map[%r]。\n%s"
+                    % (i, kind, kind, _MIGRATE))
 
         tone_name = _pick_tone(ln, kind, rules, use_rules, reasons)
         tone = VOICE_TONES[tone_name]
 
-        if final is not None:
-            p = VOICE_PERSONAS[final]
-            voice = p["voice"]
-            rate_v = parse_pct(p["rate"]) + tone["rate_delta"]
-            pitch_v = parse_hz(p["pitch"]) + tone["pitch_delta"]
-            vol_v = parse_pct(p["volume"]) + tone["volume_delta"]
-            gain = float(p["gain_db"]) + float(tone["gain_db"])
-        else:                            # 显式原始 voice id：没有 persona 底子，只叠语气
-            voice = raw_voice or LEGACY_VOICE
-            rate_v = tone["rate_delta"]
-            pitch_v = tone["pitch_delta"]
-            vol_v = tone["volume_delta"]
-            gain = float(tone["gain_db"])
-
-        rate_v += rules["rate"]
-        vol_v += rules["volume"]
+        # 音色补偿（设备）+ 语气补偿（表演）；表里没有的音色按 0 dB 并把事实写进 reason。
+        gain = float(VOICE_LOUDNESS.get(voice, 0.0)) + float(tone["gain_db"])
+        if voice not in VOICE_LOUDNESS:
+            reasons.append("unmeasured_voice")
+
+        rate_v = tone["rate_delta"] + rules["rate"]
+        pitch_v = tone["pitch_delta"]
+        vol_v = tone["volume_delta"] + rules["volume"]
         if use_rules:
             reasons.extend(rules["reasons"])
 
@@ -575,7 +581,7 @@ def voice_plan(script, style_plan=None):
 
         u_rate, u_pitch = 0.0, 0.0
         if jitter > 0:
-            jr, jp, jl, jt, u_rate, u_pitch = _jitter(title, lid, final or voice)
+            jr, jp, jl, jt, u_rate, u_pitch = _jitter(title, lid, voice)
             rate_v += jr * jitter
             pitch_v += jp * jitter
             lead += jl * jitter
@@ -593,7 +599,7 @@ def voice_plan(script, style_plan=None):
             reasons.append("clamp:volume")
 
         # edge-tts 只收整数：jitter>0 时用确定性随机进位（长期期望=浮点目标），
-        # jitter=0 时退化为纯四舍五入，保证与无抖动逐字段相等。
+        # jitter=0 时退化为纯四舍五入，保证与「无抖动」逐字段相等。
         if jitter > 0:
             rate_s = "%+d%%" % _quantize(rate_c, u_rate)
             pitch_s = "%+dHz" % _quantize(pitch_c, u_pitch)
@@ -602,17 +608,13 @@ def voice_plan(script, style_plan=None):
             pitch_s = fmt_hz(pitch_c)
 
         rows.append({
-            "id": lid, "kind": kind, "persona": final, "tone": tone_name,
+            "id": lid, "kind": kind, "persona": None, "tone": tone_name,
             "voice": voice, "rate": rate_s, "pitch": pitch_s,
             "volume": fmt_pct(vol_c), "gain_db": round(gain, 2),
             "lead": _fmt_num(_clamp(lead, _LEAD_LIMIT[0], _LEAD_LIMIT[1])),
             "tail": _fmt_num(_clamp(tail, _TAIL_LIMIT[0], _TAIL_LIMIT[1])),
             "reason": ";".join(reasons),
         })
-        prev_persona = final if final is not None else prev_persona
-        # 生效类型：引号句虽然 kind 标 body，但已经按 quote 声线念了，
-        # 下一句普通正文才算"换段"，否则会被同 kind 粘连规则永远锁在引用声线上。
-        prev_kind = "quote" if quote_rule else kind
     return rows
 
 
@@ -652,56 +654,53 @@ def spec_key(spec):
 
 
 def plan_stats(plan):
-    """计划摘要：用了几个 persona / 哪些语气 / 是否 legacy（测试与日志用）。"""
+    """计划摘要：用了几把声音 / 哪些语气（测试与日志用）。"""
     rows = [r for r in (plan or []) if isinstance(r, dict)]
-    personas = []
-    tones = []
+    voices, tones = [], []
     for r in rows:
-        p, t = r.get("persona"), r.get("tone")
-        if p and p not in personas:
-            personas.append(p)
+        v, t = r.get("voice"), r.get("tone")
+        if v and v not in voices:
+            voices.append(v)
         if t and t not in tones:
             tones.append(t)
-    return {"lines": len(rows), "personas": personas, "tones": tones,
-            "distinct": len(personas),
-            "legacy": bool(rows) and all(r.get("reason") == "legacy" for r in rows)}
+    return {"lines": len(rows), "voices": voices, "tones": tones, "distinct": len(voices)}
 
 
 # ============================================================================
 # 七、人读输出
 # ============================================================================
 def describe(plan):
-    """把计划表打成人可读的多行文本（id/kind/persona/tone/voice/rate/lead/tail）。"""
+    """把计划表打成人可读的多行文本（id/kind/voice/tone/rate/pitch/vol/gain/lead/tail）。"""
     rows = [r for r in (plan or []) if isinstance(r, dict)]
-    head = "%-8s %-7s %-18s %-9s %-28s %-6s %-6s %-6s" % (
-        "id", "kind", "persona", "tone", "voice", "rate", "lead", "tail")
+    head = "%-8s %-7s %-28s %-9s %-6s %-6s %-6s %-6s %-6s %-6s" % (
+        "id", "kind", "voice", "tone", "rate", "pitch", "vol", "gain", "lead", "tail")
     out = [head, "-" * len(head)]
     for r in rows:
-        out.append("%-8s %-7s %-18s %-9s %-28s %-6s %-6.2f %-6.2f" % (
-            str(r.get("id", "")), str(r.get("kind", "")),
-            str(r.get("persona") or "-"), str(r.get("tone", "")),
-            str(r.get("voice", "")), str(r.get("rate", "")),
+        out.append("%-8s %-7s %-28s %-9s %-6s %-6s %-6s %+6.2f %-6.2f %-6.2f" % (
+            str(r.get("id", "")), str(r.get("kind", "")), str(r.get("voice", "")),
+            str(r.get("tone", "")), str(r.get("rate", "")), str(r.get("pitch", "")),
+            str(r.get("volume", "")), float(r.get("gain_db", 0.0)),
             float(r.get("lead", 0.0)), float(r.get("tail", 0.0))))
     return "\n".join(out)
 
 
 # ============================================================================
-# 八、校准：真合成、真实测，失败优雅降级（返回 0，不阻塞主链）
+# 八、校准：真合成、真实测；离线优雅降级（不抛异常，不阻塞主链）
 # ============================================================================
-def _measure_wav(path):
-    """读 24k 单声道 wav，返回 dur/cps/rms_db/peak_db（纯标准库，不用 numpy）。"""
+def _measure_wav(path, text=CALIB_TEXT):
+    """读 24k 单声道 16-bit wav，返回 dur/cps/rms_db（纯标准库，不用 numpy）。"""
     with wave.open(path, "rb") as w:
         sr = w.getframerate()
         n = w.getnframes()
+        if w.getsampwidth() != 2:
+            raise ValueError("只接受 16-bit PCM wav（ffmpeg 要带 -sample_fmt s16）")
         raw = w.readframes(n)
-    import array
     data = array.array("h")
     data.frombytes(raw)
     if sys.byteorder == "big":
         data.byteswap()
     total = len(data)
     dur = total / float(sr) if sr else 0.0
-    peak = max((abs(v) for v in data), default=0) / 32768.0
     fl = max(1, int(0.02 * sr))
     hop = max(1, int(0.01 * sr))
     frames = []
@@ -715,73 +714,182 @@ def _measure_wav(path):
         frames.append(math.sqrt(acc / float(len(seg))) / 32768.0)
     gated = [x for x in frames if x > 10 ** (-45.0 / 20.0)]
     rms = math.sqrt(sum(x * x for x in gated) / len(gated)) if gated else 1e-6
-    return {"dur": dur, "cps": hanzi_count(CALIB_TEXT) / dur if dur else 0.0,
-            "rms_db": 20.0 * math.log10(rms + 1e-12),
-            "peak_db": 20.0 * math.log10(peak + 1e-12)}
+    return {"dur": dur, "cps": hanzi_count(text) / dur if dur else 0.0,
+            "rms_db": 20.0 * math.log10(rms + 1e-12)}
+
+
+def _gain_for(rms_db):
+    """实测 RMS -> 建议补偿（目标响度 - 实测，夹在 ±3 dB，保留 2 位）。"""
+    return round(_clamp(CALIB_TARGET_DB - float(rms_db), -_GAIN_LIMIT, _GAIN_LIMIT), 2)
+
+
+_CALIB_TIMEOUT = 30.0                    # 单条合成上限：没网时不能让主链挂死
+_CALIB_CACHE = os.path.join("work", "voice_calib.json")
+_CALIB_SCHEMA = 1
+
+
+def _calib_path(cache_path=None):
+    return str(cache_path or _CALIB_CACHE)
+
+
+def _load_calib(cache_path):
+    """读缓存 -> (校准文本, {voice: {rms_db, cps, dur}})；读不了/结构不对 -> (None, {})。"""
+    try:
+        with open(cache_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return None, {}
+    if not isinstance(data, dict) or data.get("schema") != _CALIB_SCHEMA:
+        return None, {}
+    voices = data.get("voices")
+    return str(data.get("text") or ""), (voices if isinstance(voices, dict) else {})
+
+
+def _store_calib(cache_path, text, row):
+    """只缓存**成功测量**：失败也写会把一次断网固化成「测过」，之后永远读到假数据。"""
+    _, voices = _load_calib(cache_path)
+    voices = dict(voices)
+    voices[row["voice"]] = {"rms_db": row["rms_db"], "cps": row["cps"], "dur": row["dur"]}
+    # target_db 记下来只为审计（换机后一眼看出上次按多少 dBFS 补的）；
+    # 读缓存时 gain 仍然用**当前** CALIB_TARGET_DB 现算，改目标不用清缓存。
+    data = {"schema": _CALIB_SCHEMA, "text": text, "target_db": CALIB_TARGET_DB,
+            "voices": voices}
+    try:
+        d = os.path.dirname(os.path.abspath(cache_path))
+        os.makedirs(d, exist_ok=True)
+        with open(cache_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=1)
+    except OSError as e:                 # 缓存写不进去不影响本次结果，但要说出来
+        return "%s: %s" % (type(e).__name__, e)
+    return ""
+
+
+async def _synthesize(edge_tts, text, voice, out_mp3):
+    """合成一句校准文本；wait_for 是防「没网时挂死」的硬上限。"""
+    await asyncio.wait_for(
+        edge_tts.Communicate(text, voice).save(out_mp3), timeout=_CALIB_TIMEOUT)
 
 
-def calibrate(personas=None, log=None):
-    """逐个 persona 合成校准句，实测 dur/cps/门限 RMS，打印建议 gain_db。
+def calibrate_voice(voice_id, cache_path=None, text=None):
+    """实测一把音色的响度补偿；能联网才真测，其余情况优雅降级（绝不抛异常）。
 
-    只在这里 import edge_tts（其余函数纯标准库，方便无网环境单测）。
-    没装 edge_tts / 没 ffmpeg / 没网：打印 SKIP 并返回 0，绝不让主链失败。
+    参数
+    ----
+    voice_id    edge voice id（zh-CN-YunxiNeural）
+    cache_path  结果缓存，默认 work/voice_calib.json；同一把音色下次直接读
+    text        校准文本，默认 CALIB_TEXT（改文本会让旧缓存失效并重测）
+
+    返回 dict：
+      测得  {'voice', 'rms_db', 'cps', 'dur', 'gain_db', 'measured': True[, 'cached': True]}
+      降级  {'voice', 'rms_db': None, 'cps': None, 'gain_db': 表里的值,
+             'measured': False, 'reason': '为什么没测成'}
+    gain_db 沿用口径：CALIB_TARGET_DB - 实测 rms_db，夹在 ±3 dB。
+
+    为什么要缓存：edge-tts 是免费端点，校准句要真联网合成；每句计划都去测一遍既慢
+    也不稳定。但**只缓存成功测量**——失败也写缓存的话，一次断网就会把「没测」固化成
+    「测过」，下一台机器照抄一个假增益，比没补还糟。
     """
-    log = log or (lambda s: None)
+    vid = str(voice_id or "").strip()
+    text = str(text or CALIB_TEXT)
+    cache = _calib_path(cache_path)
+    base = {"voice": vid, "rms_db": None, "cps": None, "dur": None,
+            "gain_db": float(VOICE_LOUDNESS.get(vid, 0.0)), "measured": False}
+
+    if not is_edge_voice(vid):
+        base["reason"] = ("不是 edge voice id：%r（persona 名已删除；写 zh-CN-XxxNeural）"
+                          % vid)
+        return base
+
+    cached_text, voices = _load_calib(cache)
+    hit = voices.get(vid) if cached_text == text else None
+    try:
+        rms = float(hit["rms_db"]) if isinstance(hit, dict) else None
+    except (KeyError, TypeError, ValueError):
+        rms = None
+    if rms is not None:
+        try:
+            cps = float(hit.get("cps") or 0.0)
+            dur = float(hit.get("dur") or 0.0)
+        except (TypeError, ValueError):
+            cps, dur = 0.0, 0.0
+        base.update(rms_db=round(rms, 2), cps=round(cps, 2), dur=round(dur, 2),
+                    gain_db=_gain_for(rms), measured=True, cached=True)
+        return base
+
     try:
         import edge_tts
-    except Exception as e:              # noqa: BLE001
-        log("[SKIP] 没装 edge_tts（%s: %s），跳过校准" % (type(e).__name__, e))
-        return 0
+    except Exception as e:               # noqa: BLE001 — 没装就降级，不拖垮主链
+        base["reason"] = "没装 edge_tts（%s: %s）" % (type(e).__name__, e)
+        return base
     ffmpeg = shutil.which("ffmpeg")
     if not ffmpeg:
-        log("[SKIP] 没找到 ffmpeg，无法把 mp3 解成 PCM 测 RMS，跳过校准")
-        return 0
-    ids = [p for p in (personas or PERSONA_IDS) if p in VOICE_PERSONAS]
+        base["reason"] = "没找到 ffmpeg，没法把 mp3 解成 PCM 测 RMS"
+        return base
+
     tmp = tempfile.mkdtemp(prefix="voicekit_cal_")
-    rows = {}
     try:
-        import asyncio
-        for pid in ids:
-            p = VOICE_PERSONAS[pid]
-            mp3 = os.path.join(tmp, pid + ".mp3")
-            wav = os.path.join(tmp, pid + ".wav")
-
-            async def _go(_p=p, _mp3=mp3):
-                await edge_tts.Communicate(CALIB_TEXT, _p["voice"], rate=_p["rate"],
-                                           pitch=_p["pitch"], volume=_p["volume"]).save(_mp3)
-
-            try:
-                asyncio.run(_go())
-                r = subprocess.run([ffmpeg, "-y", "-v", "error", "-i", mp3,
-                                    "-ac", "1", "-ar", "24000", "-sample_fmt", "s16", wav],
-                                   capture_output=True, text=True)
-                if r.returncode != 0:
-                    raise RuntimeError((r.stderr or "")[-200:])
-                m = _measure_wav(wav)
-                rows[pid] = m
-                log("  OK   %-18s %-28s dur %.2fs  cps %.2f  rms %.2f dBFS"
-                    % (pid, p["voice"], m["dur"], m["cps"], m["rms_db"]))
-            except Exception as e:      # noqa: BLE001 — 单条失败不该中断整表
-                log("  SKIP %-18s %s: %s" % (pid, type(e).__name__, str(e)[:110]))
+        mp3 = os.path.join(tmp, "cal.mp3")
+        wav = os.path.join(tmp, "cal.wav")
+        coro = _synthesize(edge_tts, text, vid, mp3)
+        try:
+            asyncio.run(coro)
+        except Exception as e:          # noqa: BLE001 — 没网/端点不可用都走这里
+            # 事件循环有时根本起不来（asyncio.run 在 await 之前就抛），协程没人接；
+            # 不关掉的话「never awaited」警告会盖住真正的原因，误导排查方向。
+            coro.close()
+            base["reason"] = ("合成失败（多半是没网或 edge 端点临时不可用）：%s: %s"
+                              % (type(e).__name__, str(e)[:160]))
+            return base
+        try:
+            r = subprocess.run([ffmpeg, "-y", "-v", "error", "-i", mp3,
+                                "-ac", "1", "-ar", "24000", "-sample_fmt", "s16", wav],
+                               capture_output=True, text=True)
+            if r.returncode != 0:
+                raise RuntimeError((r.stderr or "")[-200:])
+            m = _measure_wav(wav, text)
+        except Exception as e:          # noqa: BLE001 — 解码/测量失败同样降级
+            base["reason"] = "ffmpeg 解码或测量失败：%s" % str(e)[:160]
+            return base
+        got = {"voice": vid, "rms_db": round(m["rms_db"], 2), "cps": round(m["cps"], 2),
+               "dur": round(m["dur"], 2), "gain_db": _gain_for(m["rms_db"]),
+               "measured": True}
+        err = _store_calib(cache, text, got)
+        if err:
+            got["cache_error"] = err
+        return got
     finally:
         shutil.rmtree(tmp, ignore_errors=True)
-    if not rows:
-        log("[SKIP] 所有音色都合成失败（多半是没网或 edge 端点临时不可用），未产生校准值")
-        return 0
-    target = sorted(r["rms_db"] for r in rows.values())[len(rows) // 2]
+
+
+def calibrate(voices=None, log=None):
+    """逐把音色实测，打印「实测 vs 表里」，并给出该抄回 VOICE_LOUDNESS 的数。
+
+    edge_tts 只在真测时 import（其余函数纯标准库，方便无网环境单测）。
+    没装 edge_tts / 没 ffmpeg / 没网：逐条 SKIP，返回 0，绝不让主链失败。
+    """
+    log = log or (lambda s: None)
+    ids = [str(v).strip() for v in (voices or list(VOICE_LOUDNESS)) if str(v).strip()]
+    log("校准文本：%s（%d 个汉字）" % (CALIB_TEXT, hanzi_count(CALIB_TEXT)))
+    log("目标响度：%.2f dBFS（CALIBRATION_LOG 实测中位数）；gain 夹在 ±%.1f dB"
+        % (CALIB_TARGET_DB, _GAIN_LIMIT))
     log("")
-    log("目标响度（%d 个 persona 门限 RMS 中位数）= %.2f dBFS" % (len(rows), target))
-    log("%-18s %-28s %6s %6s %8s %8s %8s" % (
-        "persona", "voice", "dur", "cps", "rms", "建议gain", "当前gain"))
-    for pid in rows:
-        m = rows[pid]
-        want = _clamp(target - m["rms_db"], -_GAIN_LIMIT, _GAIN_LIMIT)
-        cur = float(VOICE_PERSONAS[pid]["gain_db"])
-        log("%-18s %-28s %6.2f %6.2f %8.2f %+8.2f %+8.2f%s" % (
-            pid, VOICE_PERSONAS[pid]["voice"], m["dur"], m["cps"], m["rms_db"],
-            want, cur, "" if abs(want - cur) < 0.35 else "  <-- 建议改表"))
+    ok = 0
+    for vid in ids:
+        r = calibrate_voice(vid)
+        if r["measured"]:
+            ok += 1
+            cur = float(VOICE_LOUDNESS.get(vid, 0.0))
+            log("  OK   %-30s rms %7.2f dBFS  cps %.2f  gain %+6.2f  表 %+6.2f%s"
+                % (vid, r["rms_db"], r["cps"], r["gain_db"], cur,
+                   "（缓存）" if r.get("cached") else ""))
+        else:
+            log("  SKIP %-30s %s" % (vid, r.get("reason")))
     log("")
-    log("把上面「建议gain」抄回 VOICE_PERSONAS[pid]['gain_db']，并把 CALIBRATED_ON 改成今天；")
+    if not ok:
+        log("[SKIP] 没测到任何音色（多半是没网 / 没装 edge_tts / 没 ffmpeg）；"
+            "VOICE_LOUDNESS 保持原样，主链不受影响")
+        return 0
+    log("把上面「gain」抄回 VOICE_LOUDNESS[voice]，并把 CALIBRATED_ON 改成今天；")
     log("换 voice id 必须重跑本命令 —— 不同音色的响度差 3-7 dB，凭感觉调会一句响一句轻。")
     return 0
 
@@ -799,18 +907,24 @@ def _setup_stdio():
 
 
 def _cli_list():
-    print("voicekit 声线表（v0.5.0；校准于 %s，edge-tts 免费端点只有 8 个 zh-CN 音色）"
+    print("voicekit 音色表（校准于 %s；edge-tts 免费端点只有 8 个 zh-CN 音色 + zh-TW/zh-HK）"
           % CALIBRATED_ON)
-    print("%-18s %-28s %6s %7s %7s %8s %-8s %-8s %s" % (
-        "persona", "voice", "rate", "pitch", "volume", "gain_db", "narrate", "home", "desc"))
-    print("-" * 150)
-    for pid in PERSONA_IDS:
-        p = VOICE_PERSONAS[pid]
-        print("%-18s %-28s %6s %7s %7s %+8.2f %-8s %-8s %s" % (
-            pid, p["voice"], p["rate"], p["pitch"], p["volume"], p["gain_db"],
-            "yes" if p["narrate"] else "no", p["home"], p["desc"]))
+    print("gain_db = 目标 %.2f dBFS - 实测 RMS，夹在 ±%.1f dB（正 = 该音色偏轻，mix 侧补回来）"
+          % (CALIB_TARGET_DB, _GAIN_LIMIT))
+    print("%-30s %8s %9s %7s %7s" % ("voice", "gain_db", "实测RMS", "dur", "cps"))
+    print("-" * 70)
+    for vid, gain in VOICE_LOUDNESS.items():
+        m = CALIBRATION_LOG.get(vid) or {}
+        print("%-30s %+8.2f %9s %7s %7s" % (
+            vid, gain,
+            ("%.2f" % m["rms_db"]) if m else "-",
+            ("%.2f" % m["dur"]) if m else "-",
+            ("%.2f" % m["cps"]) if m else "-"))
+    print("")
+    print("表里没有的音色按 0 dB 处理（不猜），voice_plan 的 reason 会标 unmeasured_voice。")
+    print("换机 / 换 edge-tts 版本 / 换 voice id 都要重测：python voicekit.py --calibrate")
     print("")
-    print("语气档（body 必须等于 v0.4 基准：lead 0.62 / tail 0.92 / 所有 delta=0）")
+    print("语气档（body 是基准行：所有 delta = 0；lead/tail 相对它偏移）")
     print("%-10s %8s %9s %9s %8s %6s %6s  %s" % (
         "tone", "rate", "pitch", "volume", "gain_db", "lead", "tail", "desc"))
     print("-" * 120)
@@ -820,8 +934,8 @@ def _cli_list():
             tid, t["rate_delta"], t["pitch_delta"], t["volume_delta"], t["gain_db"],
             t["lead"], t["tail"], t["desc"]))
     print("")
-    print("注：warm_female 用 zh-TW-HsiaoChenNeural（台湾腔软糯女声）；要大陆标准音就换成")
-    print("    zh-CN-XiaoxiaoNeural 并把 rate 改成 '-3%'，其余字段不用动。")
+    print("注：zh-TW-HsiaoChenNeural 是台湾腔软糯女声（微软标注 Warm）；要大陆标准音就换")
+    print("    zh-CN-XiaoxiaoNeural，响度补偿按上表 -2.7 dB，其余字段不用动。")
     return 0
 
 
@@ -836,46 +950,54 @@ def _cli_plan(path):
         print("[剧本格式错误] %s 顶层必须是对象且含非空 lines" % path)
         return 2
     sp = _resolve(script, None)
-    plan = voice_plan(script, sp)
+    try:
+        plan = voice_plan(script, sp)
+    except ValueError as e:              # 配置错误要能照抄着改，不要 traceback
+        print("[声线配置错误] %s" % e)
+        return 2
+    voce = sp.get("voice") if isinstance(sp.get("voice"), dict) else {}
     print("剧本：%s（%d 句）" % (path, len(plan)))
-    print("风格：%s  legacy=%s  voice.map=%s"
-          % (sp.get("style", "?"), bool(sp.get("legacy")),
-             json.dumps(sp.get("voice", {}).get("map", {}), ensure_ascii=False)))
+    print("风格：%s  voice.map=%s" % (sp.get("style") or "-",
+                                      json.dumps(voce.get("map") or {}, ensure_ascii=False)))
     print("")
     print(describe(plan))
     print("")
-    for r, ln in zip(plan, script["lines"]):
-        print("  %-8s rate=%-5s pitch=%-6s vol=%-5s gain=%+5.2f lead=%-5.2f tail=%-5.2f %s"
-              % (r["id"], r["rate"], r["pitch"], r["volume"], r["gain_db"],
+    for r in plan:
+        print("  %-8s voice=%-28s rate=%-5s pitch=%-6s vol=%-5s gain=%+5.2f"
+              " lead=%-5.2f tail=%-5.2f %s"
+              % (r["id"], r["voice"], r["rate"], r["pitch"], r["volume"], r["gain_db"],
                  r["lead"], r["tail"], r["reason"]))
     st = plan_stats(plan)
     print("")
-    print("声线 %d 种：%s" % (st["distinct"], ", ".join(st["personas"]) or "-"))
+    print("声线 %d 种：%s" % (st["distinct"], ", ".join(st["voices"]) or "-"))
     print("语气 %d 档：%s" % (len(st["tones"]), ", ".join(st["tones"]) or "-"))
-    print("提示：同一份剧本两次 voice_plan() 结果完全相同；legacy 剧本走 v0.4 单值路径。")
+    print("提示：同一份剧本两次 voice_plan() 结果完全相同；persona 字段恒为 None"
+          "（只为兼容下游而保留）。")
     return 0
 
 
 def main(argv=None):
     _setup_stdio()
     ap = argparse.ArgumentParser(
-        prog="voicekit.py", description="v0.5 旁白声线/语气计划（不合成，只出计划）")
-    ap.add_argument("--list", action="store_true", help="列出声线表与语气档")
+        prog="voicekit.py", description="v1.0 旁白声线/语气计划（不合成，只出计划）")
+    ap.add_argument("--list", action="store_true", help="列出音色响度表与语气档")
     ap.add_argument("--plan", metavar="FILM_JSON", help="打印某份 film.json 的声线计划")
-    ap.add_argument("--calibrate", action="store_true", help="联网实测各 persona 的 dur/RMS，打印建议 gain_db")
-    ap.add_argument("--only", metavar="PERSONA", help="--calibrate 时只测这些 persona（逗号分隔）")
+    ap.add_argument("--calibrate", action="store_true",
+                    help="联网实测各音色的 dur/RMS，打印建议 gain_db（失败 SKIP 返回 0）")
+    ap.add_argument("--only", metavar="VOICE_ID",
+                    help="--calibrate 时只测这些 edge voice id（逗号分隔）")
     a = ap.parse_args(argv)
     if a.list:
         return _cli_list()
     if a.calibrate:
         only = [x.strip() for x in (a.only or "").split(",") if x.strip()] or None
         if only:
-            unknown = [x for x in only if x not in VOICE_PERSONAS]
+            unknown = [x for x in only if not is_edge_voice(x)]
             if unknown:
-                # 以前拼错 persona 会静默变成空集合 -> 打出"所有音色都合成失败（多半是没网）"，
+                # 以前拼错名字会静默变成空集合 -> 打出「所有音色都合成失败（多半没网）」，
                 # 把配置错误伪装成网络错误。这里先点名校验，给人话可照抄的可用清单。
-                print("[未知 persona] %s；可用：%s"
-                      % ("、".join(unknown), " / ".join(PERSONA_IDS)), file=sys.stderr)
+                print("[未知音色] %s；可用：%s"
+                      % ("、".join(unknown), " / ".join(VOICE_LOUDNESS)), file=sys.stderr)
                 return 2
         return calibrate(only, log=print)
     if a.plan: