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

package/README.md

@@ -1,6 +1,6 @@
 # @dsh-gis/dsh-video-studio-skill
 
-![version](https://img.shields.io/badge/version-0.4.0-blue) ![license](https://img.shields.io/badge/license-MIT-green)
+![version](https://img.shields.io/badge/version-0.7.2-blue) ![license](https://img.shields.io/badge/license-MIT-green)
 
 **DeepSeek Harness 技能插件：用代码从零生成中文视频。**
 
@@ -16,7 +16,26 @@ ffmpeg 编码 → 采样级混音 → **四层质检**（容器 / 信号 / 时
 > **v0.4.0**：修掉 4 处"门禁看着干净、其实没在查"的静默问题（`--resume` 复用旧分块、
 > `music.mode=off` 仍混入旧配乐、PIL 路线音画同步恒空、亮度静止判据误报 4 段），
 > 补上仓库级体检（`tools/ci_check.py`）、CI、`requirements.txt`，并修掉管道中文乱码。
-> 详见 [CHANGELOG.md](CHANGELOG.md) 与 SKILL.md §13。
+> **v0.5.0（风格包）**：解决"每部片都长一个样"。一个 `style` id 同时决定画风（8 套主题 ×
+> 3 种版式）、配乐（8 套风格：调池/BPM 梯度/进行/动机/配器/鼓型）、旁白（9 个声线 × 6 档语气）
+> 与节奏；`"style": "auto"` 按内容自动选，三级内容指纹保证"改错别字不换整首曲子"。
+> 不写 `style` 字段 = v0.4 行为（配乐 PCM 逐样本一致，selfcheck 有断言）。
+> **v0.6.0（交付可信化）**：解决"**质检结论只活在控制台里**"。新增门禁账本与机读交付报告
+> `out/QC-REPORT.md`（gate matrix 分 **pass / fail / skipped 三档**——"没执行"不再冒充"通过"）、
+> 人工签核 `--stage accept`（绑内容指纹，改了剧本旧签核自动失效）、阶段新鲜度 `--stage explain`
+> （改上游后哪些产物还是旧的、最小重跑什么）、开渲前成本预演 `tools/estimate.py`、
+> `film.json` 契约校验 `filmcheck.py`（改成 `holds` 这种拼写错误不再静默失效）。
+> 顺手修掉一个**已发布版本里的真 bug**：`--jobs >1` 并行渲染因主题色元组被 JSON 变成 list 而直接崩溃
+> ——也就是 README 下面教的"长片分块并行"此前根本跑不通。
+> 详见 [CHANGELOG.md](CHANGELOG.md)、SKILL.md §7.0 与 references/change-impact.md。
+> **v0.7.0（声音也不再一片一样）**：内容指纹从 seed 推进到**结构层**——和弦替换、进行档位、动机偏移、
+> 鼓型 ghost 都随内容变化；音效 seed 改内容派生并跟随配乐调性（`in_key`）；段落边界前 2.2 s 的
+> whoosh/riser 自动 -3 dB，避免与配乐过门撞车；duck 按风格加深到 3.0–5.5 dB。legacy 路径逐样本不变。
+> **v0.7.1（旁白优先）**：配乐基线从 -1.5 降到 **-12 dB**，有人声处再按包络压配乐 6 dB / 音效 3 dB，
+> 混音后按台词活跃区实测旁白/背景差，**不足 12 dB 自动补压背景**（`guard_snr_db`，最多 30 dB）。
+> 实测（真实素材）：旧混音 -4.2 dB → 新混音 12.0 dB，`audio_similarity --strict` D 组 12.9 dB；
+> selfcheck 34 → 38 条，其中第 35–38 条专盯这条链路。
+> 详见 [CHANGELOG.md](CHANGELOG.md) 与 SKILL.md §5.6 / §5.7、references/audio-variation.md。
 
 ## 安装
 
@@ -49,10 +68,38 @@ mv ~/.dsh/skills/video-studio ~/.dsh/backup/video-studio.bak-$(date +%Y%m%d)
 <p align="center"><img src="docs/demo-pil-sheet.png" width="100%" alt="默认模板片联系表：开场 / 正文卡片 / 正文卡片 / 收尾"></p>
 
 上面四帧是用仓库自带的 `assets/film.json` + `assets/scenes.py` 从零跑一遍 `python render.py` 的
-`work/qa/sheet.png`，未经任何修图。配套实测（同一台机器）：
+`work/qa/sheet.png`，未经任何修图。配套实测（**作者机器** Windows 11 / OSGeo4W Python 3.12，
+v0.6 时期口径；TTS 实测时长与 AAC 编码会让这些数字在小范围内浮动，换机请按 SKILL.md §14 重测）：
 **时长 30.10 s / 1920×1080 / 30 fps / h264+aac 48 kHz / -16.0 LUFS / 真峰 -1.2 dBTP / 黑帧 0 /
 帧级深检：闪烁 0、空窗 0、画面静止 0**（音画同步在 PIL 路线上需要写 `visual_at` 才会真的查，见 SKILL.md §7）。
 
+怎么复现：按 [SKILL.md §1](skills/video-studio/SKILL.md) 的五步上手，把自带模板拷到**空目录**里跑一遍即可
+（`cp assets/film.json assets/scenes.py` + 拷 `scripts/*.py` → `python render.py`）。数字每次都会差一点：
+TTS 实测时长、AAC 编码都会让真峰/响度/锐度浮动，**别 chasing 小数点**。本机（另一台）复测同模板得到的是
+29.00 s / -16.5 LUFS / -1.4 dBTP / 锐度比 1.01（2026-11-10 另一台 Windows 机器复测）——
+**不同机器、不同 TTS 结果，两组都对，别混着引用**。
+
+## 效果：同一个模板，八种气质（v0.5）
+
+同一份文字，只改 `"style"`（画风 / 配乐 / 旁白 / 节奏一起变）：
+
+<p align="center"><img src="docs/styles/sheet-8-styles.png" width="100%" alt="8 套风格对比：科技深蓝 / 杂志暖白 / 手绘纸感 / 活力撞色 / 极简黑白 / 电影青橙 / 暖灰薄荷 / 深黑鎏金"></p>
+
+三份**不同题材**的短片（全流程真跑：TTS → 排轴 → 配乐 → 音效 → 混音 → 逐帧 → 编码 → 质检；数据见
+`docs/styles/demo-results.json`，是 v0.5 时期的实测快照，片源脚本未随仓库分发，**不可直接复现**；
+**别把这张表当成"现在跑出来就是这样"**——BPM/调性由内容指纹从风格梯度里选（v0.7 起指纹还参与配乐结构），
+同一题材换一版正文就可能落到别的 BPM/调性，当前风格解析结果请以 `--stage style` 的打印为准）：
+
+| 题材 | 自动选中的风格 | 配乐 | 旁白声线 | 质检 |
+|---|---|---|---|---|
+| AI 大模型的三年 | tech-deep 科技深蓝 | 小调 116BPM / Em | 青年开场 → 男声正文 → 女声引用 | PASS（17.3s，-16.0 LUFS） |
+| 手工木作的一天 | paper 手绘纸感 | 大调 88BPM / G | 女声 + 软糯女声正文 | PASS（19.9s） |
+| 深夜学习指南 | lo-fi 暖灰薄荷 | 大调 84BPM / F | 温柔女声 + 女声开场 | PASS（20.1s） |
+
+<p align="center"><img src="docs/styles/sheet-ai.png" width="32%" alt="AI 题材"><img src="docs/styles/sheet-craft.png" width="32%" alt="手作题材"><img src="docs/styles/sheet-night.png" width="32%" alt="深夜题材"></p>
+
+三片的联系表（左→右为时间顺序）肉眼可见不是同一套风格：深蓝科技 / 牛皮纸手作 / 冷灰薄荷深夜。
+
 ## 用法
 
 触发词：做一个视频 / 生成宣传片 / 把报告变成视频 / 做动画 / 配音配字幕 / 出成片 /
@@ -62,14 +109,18 @@ mv ~/.dsh/skills/video-studio ~/.dsh/backup/video-studio.bak-$(date +%Y%m%d)
 
 ```bash
 mkdir -p myfilm && cd myfilm
-cp <SKILL_DIR>/assets/film.json .                       # 剧本模板
+cp <SKILL_DIR>/assets/film.json .                       # 剧本模板（"style": "auto"）
 cp <SKILL_DIR>/assets/scenes.py .                       # 场景模板
-cp <SKILL_DIR>/scripts/*.py .                           # filmkit/render/selfcheck + sfxkit/scorekit/qa_frames/webengine
+cp <SKILL_DIR>/scripts/*.py .                           # filmkit/stylekit/voicekit/render/selfcheck + sfxkit/scorekit/qa_frames/webengine
 cp -r <SKILL_DIR>/assets/web ./web                       # 只在走浏览器引擎时需要
 
-python selfcheck.py                                     # 24 条环境/回归断言（20 秒，不联网）
+python selfcheck.py                                     # 43 条环境/回归断言（20 秒内，不联网）
+python <REPO>/tools/estimate.py --script film.json       # v0.6：开渲前先算耗时/磁盘/分块（仓库/包里的工具，
+                                                         #     不在 skills/video-studio/ 内，quickstart 拷出来的目录没有它）
 python render.py --stage stills --stills "l01:3,l02:5"  # 母版预览（缺 tts/layout 会自动补跑）
 python render.py --script film.json --scenes scenes.py --out out/film.mp4 --work work
+cat out/QC-REPORT.md                                    # v0.6：机器可读交付结论（pass/fail/skipped）
+python render.py --stage accept --gate release          # v0.6：人工签核（绑内容指纹）
 ```
 
 分阶段（每步落盘、可单独重跑）：
@@ -90,12 +141,21 @@ tts → layout → cues → score → sfx → audio → frames → mux → qa
 
 | 想要 | 怎么做 |
 |---|---|
-| 让 PIL 路线的音画同步门禁真的生效 | cue 加 `"visual_at": 绝对秒`；CI 里再加 `QA_REQUIRE_SYNC=1` 把"没查"变成失败 |
+| 让 PIL 路线的音画同步门禁真的生效 | cue 加 `"visual_at": 绝对秒`；再把 `QA_REQUIRE_SYNC=1` 加进你自己的交付流水线（本仓库的 workflow 没设它） |
 | 浏览器渲染要跨会话字节级可复现 | `--deterministic`（或 `WEBENGINE_DETERMINISTIC=1`），代价约 +22%/帧 |
 
-`<SKILL_DIR>` 是 `skill` 工具加载时回报的 resourceBase 目录（`.../skills/video-studio/`）。
+`<SKILL_DIR>` 是 `skill` 工具加载时回报的 resourceBase 目录（`.../skills/video-studio/`）；
+`<REPO>` 是包根（仓库根，或装好后 profile 里的 `node_modules/@dsh-gis/dsh-video-studio-skill/`），即 `<SKILL_DIR>` 往上两级——`tools/`、`schemas/` 都在 `<REPO>` 下，`cp` 到 `myfilm/` 后那里**没有** `tools/`。
+
+分阶段（v0.2 起**每个 stage 只做自己的事**）：`--stage style | tts | layout | cues | score | sfx | audio | frames | mux | qa | stills | accept | explain`。
 
-分阶段（v0.2 起**每个 stage 只做自己的事**；完整 10 个 stage 见上）：`--stage tts | layout | cues | score | sfx | audio | frames | mux | qa | stills`。
+**v0.6 的三个新开关**（都是"让结论可追责"，不是新玩具）：
+
+| 想要 | 怎么做 |
+|---|---|
+| 交付前把"没执行"也算失败 | `--stage qa --strict-gates`（对齐 `QA_REQUIRE_SYNC` 语义） |
+| 改完东西不知道要重跑什么 | `--stage explain`（机器判断过时阶段 + 给最小重跑命令），表见 [references/change-impact.md](skills/video-studio/references/change-impact.md) |
+| 规整 `film.json` 避免静默失效 | `python skills/video-studio/scripts/filmcheck.py film.json`（`holds`→提示写成 `hold`） |
 
 长片：`--stage frames --jobs 4`（按绝对帧号分块并行）+ `--resume`（中断只补缺块）。
 
@@ -111,6 +171,10 @@ tts → layout → cues → score → sfx → audio → frames → mux → qa
 | **声音和画面对不上（v0.3）** | **提示点系统**：画面登记 cue → 音效按 cue 合成，改节奏不用重新对时间 |
 | **声音单薄、只有"叮叮咚咚"（v0.3）** | `sfxkit` 物理建模音效 + `scorekit` 一张和弦表贯穿全片 |
 | **一帧白闪/两秒空窗没人发现（v0.3）** | `qa_frames` 帧级深检：单帧闪烁、画面空窗、音画同步 |
+| **"我查过了"无法复现（v0.6）** | `out/QC-REPORT.md` + `work/gates.json`：三档 gate matrix，"没执行"独立成 `skipped` |
+| **"我签过了"变成空头支票（v0.6）** | 签核绑内容指纹：改剧本 / `scenes.py` / 引擎，旧签核自动失效 |
+| **改一句台词不知道要重跑什么（v0.6）** | `work/manifest.json` 记每阶段输入/输出指纹，`--stage explain` 直接给最小重跑命令 |
+| **`holds` 写成拼写错误却静默失效（v0.6）** | `schemas/film.schema.json` + `filmcheck.py`，并接进 `ci_check` 第 12 项 |
 
 ## 文件结构
 
@@ -120,25 +184,33 @@ cordis.patch.yml             组合包 patch（insert: video-studio）
 icon.svg / locale/*.json     插件页展示元数据
 skills/video-studio/
   SKILL.md                   主线：上手 / 八阶段 / 引擎选型 / 画质 / 声音 / 提示点 / 停留窗口 / 质检 / 故障速查
-  references/                pipeline · scene-authoring · audio · sfx-design · web-engine · frame-qa
-                             quality-gates · pitfalls
+  references/                pipeline · scene-authoring · audio · audio-variation · sfx-design · web-engine
+                             frame-qa · quality-gates · change-impact · style-packs · pitfalls
   scripts/filmkit.py         生产内核（字体/排版/字幕/音频总线/CueBus/TTS/时间轴/编码/质检）
-  scripts/render.py          编排器（10 个独立 stage、pil|web 双引擎、分块并行、断点续跑、母版预览）
-  scripts/selfcheck.py       回归自检（24 条"曾真的坏过"的断言）
+  scripts/gates.py           v0.6 门禁账本 / QC 报告渲染 / 人工签核（绑内容指纹）
+  scripts/stagewatch.py      v0.6 阶段新鲜度（work/manifest.json + --stage explain）
+  scripts/filmcheck.py       v0.6 film.json 契约校验（未知键/枚举/跨字段）
+  scripts/render.py          编排器（13 个 stage、pil|web 双引擎、分块并行、断点续跑、母版预览、门禁账本）
+  scripts/selfcheck.py       回归自检（43 条"曾真的坏过"的断言）
   scripts/sfxkit.py          物理建模音效库（24 配方，scipy 可选）
   scripts/scorekit.py        程序化配乐（和弦表 / 分段能量 / 吸气）
   scripts/webengine.py       浏览器逐帧渲染（CDP 截图、分块并行、崩溃重开、cue 导出、文字质检）
   scripts/qa_frames.py       帧级深检（单帧闪烁 / 画面空窗 / 画面静止 / 音画同步 / 亮度响度曲线）
   requirements.txt           Python 依赖（必需 / 强烈建议 / 可选三档，带注释）
-  assets/film.json           剧本模板（含 hold / bpm / music / sfx.cues）
+  assets/film.json           剧本模板（含 bpm / music / sfx.cues / 逐句 hold；顶层 hold 可选，缺省用风格 pacing）
   assets/scenes.py           场景模板（开场 / 正文卡片 / 收尾 + cues() 钩子）
   assets/web/                浏览器页面模板（原生 Canvas2D 确定性时间轴）
-tools/ci_check.py            仓库级体检（语法/JSON/依赖白名单/打包卫生/文档引用，不需 ffmpeg）
+tools/ci_check.py            仓库级体检（12 项；语法/JSON/依赖白名单/打包卫生/文档引用/film 契约，不需 ffmpeg）
+tools/estimate.py            开渲前成本预演（帧数/耗时/磁盘/分块建议，--json 可机读）
+tools/audio_similarity.py    音频差异/相似度验收（--strict 阈值判定，改音频代码后必跑）
+tools/selftest_noscipy.py    无 scipy 兜底路径自检（CI 用；屏蔽 scipy 后跑 sfxkit/scorekit 自检）
+schemas/film.schema.json     film.json 的契约（draft-07 子集）
 .github/workflows/ci.yml     CI：repo 体检（ubuntu+windows）+ 技能自检（ubuntu）
 ```
 
 ## 环境前提
 
+**插件运行**：Node.js ≥ 20（`package.json` 的 `engines`；这是 DSH 加载插件用的运行时，不必另装）。
 **必需**：ffmpeg + Python 的 numpy / Pillow / edge-tts。
 **可选**：cv2（编码锐度比）、scipy（音效滤波加速，缺了走 FFT 卷积）、
 playwright + Chromium/Edge（只在 `--engine web` 时需要）。
@@ -170,9 +242,12 @@ peer 范围 `@deepseek-ai/dsh-skill-filesystem >=0.1.0-rc.6 <0.3.0-0`，覆盖 D
 ## 仓库自检（给贡献者与 CI 用，不是给用户用的）
 
 ```bash
-python tools/ci_check.py -v     # 11 项：py 语法 / node --check / JSON / 技能清单 / 依赖白名单 /
-                                #         npm pack 打包卫生 / 文档路径引用 / Python 3.9 语法 /
-                                #         Markdown 围栏平衡 / CI workflow 语法 / 单文件体积
+python tools/ci_check.py -v     # 12 项：py 语法（含 tools/，SyntaxWarning 记失败）/ node --check /
+                                #         JSON + 版本号一致性（package.json vs README 徽章）/ 技能清单 /
+                                #         依赖白名单 / npm pack 打包卫生 / 文档路径 + 正文相对链接 /
+                                #         Python 3.9 语法 / Markdown 围栏（状态机）/ CI workflow
+                                #         （裸冒号 + run 里的 python 脚本是否存在）/ 单文件体积 /
+                                #         film.json 契约（调 filmcheck.py，规则只留一份）
 ```
 
 它**不需要 ffmpeg、字体或网络**，任何机器都能跑；它检查的是"这个仓库作为可分发包是否完整"。

package/docs/styles/demo-results.json

@@ -0,0 +1,76 @@
+{
+ "generated": "2026-11-09",
+ "demos": [
+  {
+   "demo": "ai",
+   "title": "科技深蓝",
+   "style": "tech-deep",
+   "bpm": 116,
+   "key": "Em",
+   "mood": "steady",
+   "duration": 17.26,
+   "personas": [
+    "young_male",
+    "narrator_male",
+    "narrator_female"
+   ],
+   "tones": [
+    "emphasis",
+    "body",
+    "quote",
+    "outro"
+   ],
+   "layouts": [
+    "left-stack",
+    "split-right"
+   ],
+   "spectral_centroid_hz": 5784
+  },
+  {
+   "demo": "craft",
+   "title": "手绘纸感",
+   "style": "paper",
+   "bpm": 88,
+   "key": "G",
+   "mood": "hopeful",
+   "duration": 19.855,
+   "personas": [
+    "narrator_female",
+    "warm_female"
+   ],
+   "tones": [
+    "hook",
+    "body",
+    "outro"
+   ],
+   "layouts": [
+    "left-stack",
+    "center-stack"
+   ],
+   "spectral_centroid_hz": 4899.4
+  },
+  {
+   "demo": "night",
+   "title": "暖灰薄荷",
+   "style": "lo-fi",
+   "bpm": 84,
+   "key": "F",
+   "mood": "calm",
+   "duration": 20.108,
+   "personas": [
+    "warm_female",
+    "narrator_female"
+   ],
+   "tones": [
+    "hook",
+    "body",
+    "outro"
+   ],
+   "layouts": [
+    "left-stack",
+    "split-right"
+   ],
+   "spectral_centroid_hz": 5573.8
+  }
+ ]
+}

package/index.js

@@ -31,11 +31,12 @@ export const inject = ["skills"];
 /**
  * 注册 bundled 技能根。
  *
- * 三件事任何一件不成立都只打日志、不抛错——插件本身没有"必须成功"的业务，
+ * 四件事任何一件不成立都只打日志、不抛错——插件本身没有"必须成功"的业务，
  * 挂不上技能是降级，不是崩溃：
  *   1. 找不到包内 SKILL.md（打包漏了文件 / 被裁剪）
  *   2. 运行时没有 ctx.skills（profile 没装技能注册表）
  *   3. 可选 peer 没装（只装了本插件）
+ *   4. provider 自己抛错（版本不匹配 / 目录无权限 / 注册表已占用）
  *
  * @param ctx - 携带 skills 服务的 Cordis 上下文。
  */
@@ -63,12 +64,24 @@ export async function apply(ctx) {
     return;
   }
 
-  applyFilesystemProvider(ctx, {
-    providerName: "video-studio",
-    includeDefaultRoots: false,
-    bundledSkillDir,
-    watch: false,
-  });
+  // 第 4 件可能失败的事：provider 自己抛错（版本不匹配、目录无权限、注册表已占用……）。
+  // 这里必须兜住：插件行的加载失败会让整行从 profile 里消失，而"挂不上技能"本来只是个降级。
+  // （v0.7.1 之前没兜：provider 一抛错 apply 就 reject，而且一行日志都没有——stub 实测复现过。）
+  try {
+    applyFilesystemProvider(ctx, {
+      providerName: "video-studio",
+      includeDefaultRoots: false,
+      bundledSkillDir,
+      watch: false,
+    });
+  } catch (error) {
+    warn(
+      ctx,
+      `挂载 bundled 技能根失败（本次只是空行，不影响 profile 里其它插件）：` +
+        `${error?.code ?? error?.message ?? error}` +
+        `；检查 ${PROVIDER_PKG} 的版本是否满足 peer 范围，以及 ${bundledSkillDir} 是否可读`
+    );
+  }
 }
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dsh-gis/dsh-video-studio-skill",
-  "version": "0.4.0",
-  "description": "Video Studio skill plugin for DeepSeek Harness: code-generated Chinese videos with measured TTS timeline, deterministic PIL/browser frame rendering, programmatic SFX and score, cue-driven sound sync, ffmpeg encoding, sample-level mixing and multi-layer QA gates.",
+  "version": "0.7.2",
+  "description": "Video Studio skill plugin for DeepSeek Harness: style-pack driven code-generated Chinese videos — one style id decides palette/typography/music style/voice persona/pacing, measured TTS timeline, deterministic PIL/browser rendering, programmatic SFX and score, cue-driven sound sync, ffmpeg encoding, sample-level mixing and multi-layer QA gates.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -26,7 +26,17 @@
     "THIRD_PARTY_NOTICES.md",
     "skills",
     "!skills/**/__pycache__",
-    "!skills/**/*.pyc"
+    "!skills/**/*.pyc",
+    "docs/styles/sheet-8-styles.png",
+    "docs/styles/sheet-ai.png",
+    "docs/styles/sheet-craft.png",
+    "docs/styles/sheet-night.png",
+    "docs/styles/demo-results.json",
+    "schemas",
+    "tools/estimate.py",
+    "tools/ci_check.py",
+    "tools/audio_similarity.py",
+    "tools/selftest_noscipy.py"
   ],
   "publishConfig": {
     "access": "public"