@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-recap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: video-recap
 description: >
- 从输入视频端到端生成中文解说成片。用户提供 .mp4 / .mov / .mkv / .webm，并要求添加旁白、
+ 从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm，并要求剪辑、添加旁白、
  配音、总结、短剧/电视剧/电影/纪录片/科普解说时使用。负责编排 video-* 技能链：视频理解 →
  Agent 制定故事与视听方案 → 剪辑 → 配音 → 合成。触发词：视频解说、视频旁白、生成解说、
  视频 recap、video recap、voiceover、narration、auto-dub、recap。
@@ -15,34 +15,55 @@ description: >
 video-understanding ─▶ Agent 按 video-script 制定方案并写稿 ─▶ [video-cut] ─▶ video-voiceover ─▶ video-assemble
 ```
 
-流程支持断点续跑：写好 `narration.json` 后重复同一条命令即可继续。第二阶段会校验
-`recap_run_manifest.json`，拒绝复用来自其他源视频或其他运行参数的旧工作目录；视频理解产物也只在来源一致时复用。
+流程支持断点续跑：写好 `narration.json` 后重复同一条命令即可继续。第二阶段会比对
+`recap_run_manifest.json` 记录的源视频路径、文件大小/修改时间与运行参数，拒绝复用来自其他源视频或其他参数的旧工作目录；视频理解产物也只在来源一致时复用。
 
-## 2. 创作职责
+画面流程 `--edit-mode full|cut|dub` 与声音策略 `--audio-mode` 是两个独立开关；
+`narration` 保留上述解说流程，`source-mix` 不做配音，`adopted-packet-copy` 冻结当前输入的已采用 AAC 音轨。
+组合只有下面几条路径，其余组合在启动时直接报错：
+
+| 输入 | `--edit-mode` | `--audio-mode` | Agent 暂停点 | 流程 | 详见 |
+|---|---|---|---|---|---|
+| 单视频 | full | narration | 1：`narration.json` | 理解 → 写稿 → 校验 → 配音 → 合成 | §4 |
+| 单视频 | cut | narration | 2：`clip_plan.json`，再对着成片写 `narration.json` | 理解 → 剪辑 → 重建输出时间 brief → 写稿 → 配音 → 合成 | §4 |
+| 多视频 | cut | narration | 2：同上，clip 必须带 `source_id` | 逐源理解 → 剪辑 → 写稿 → 配音 → 合成 | §4.3 |
+| 单视频 | full | source-mix / adopted-packet-copy | 无 | 直接合成当前整段 | §4.7 |
+| 单 / 多视频 | cut | source-mix / adopted-packet-copy | 1：`clip_plan.json` | 理解 → 剪辑 → 合成，不写稿 | §4.7 |
+| 单视频 | dub | narration | 1：`dub_script.json` | 英文转写 → 译稿 → 克隆音色整轨替换 | §5 |
+| 已剪好的母版 | full | narration + 三个采用 JSON | 无 | 只做严格合成 | 下文 |
+
+所有 full/cut 路径共用同一段收尾：（有旁白时）评审 → TTS → 合成 → 成片 QC。使用原声模式时读
+`references/audio-routing.md`。
 
-这不是单纯的 JSON / 渲染流水线。Agent 是本次内容的创作负责人。先判断本轮的**创作控制模式**；它与 `--edit-mode full|cut|dub` 是两个维度：
+已有预制画面和本地采用的完整声音三件套时，可走严格 assembly-only 路径：
 
-- **CREATE**：从素材创作新成片。比较真正可行的故事/剪辑假设，再选择主线。
-- **DIRECTED**：用户已经指定结构、镜头、台词或包装方向。把这些决定当作基线落实，不为满足模板而另起方案。
-- **REVISION**：用户针对已有版本看片修改。最新反馈覆盖旧决定；本轮未点名的故事、镜头、声音和包装默认冻结，不重新发散创作。
+```bash
+python3 scripts/recap.py picture.mp4 --edit-mode full --work-dir NEW_WORK \
+  --output-dir DELIVERY \
+  --tts-meta tts_meta.json \
+  --narration-adoption narration_adoption.json \
+  --audio-mix-adoption audio_mix_adoption.json
+```
 
-REVISION 开始前先明确“本轮修改项”和“冻结项”。表达、节奏、字幕反馈写回 `style_card.json`，镜头、入出点和声音分工写回 `visual_audio_board.json`；只有观众承诺、POV、主线或故事 beat 改变时才更新 `recap_story_plan.json`。删除成片内容时同步删除计划中的旧描述，不能让工作产物继续指导已不存在的镜头。
+三个 JSON 参数必须同时出现。该入口只接受单视频、full、narration、音轨 0、新工作目录和未存在的
+交付文件；不运行理解、写稿、解说评审、TTS、cut、MiMo QC 或剪映导出。语义与媒体形状仍由
+video-assemble 严格验证，recap 只核对子技能绑定记录引用的是同一批采用文件与母版路径，不把调用方
+采用的声音或混音声明成自动创作或发布批准。详见 `references/audio-routing.md`。
 
-确定模式后，在进入昂贵的下游处理前完成五次判断：
+这里的单视频是**已经剪好的母版**。重剪后可以复用未改动的 WAV 与 `tts_meta.json`，但必须按新母版
+重新写混音采用文件里的落点与准备好的音床；衔接步骤见 `references/audio-routing.md` 的 “Keep adopted voice after a cut”。
 
-1. **导演判断**：确定观众承诺、POV、戏剧问题、情绪终点，以及哪些信息要保留到后面揭示。
-2. **故事编辑**：CREATE 比较至少两个可行的剪辑假设；DIRECTED / REVISION 继承用户指定或已确认的主线。beat 始终定义为“发生了什么变化”，而不是场景摘要。
-3. **画面剪辑**：选择真正值得保留的具体时刻、人物反应、入点与出点。
-4. **声音/旁白**：先分配画面、原声、沉默和旁白的任务，再写解说词。
-5. **观众复核**：分别检查无旁白、只听声音和第一次观看时的体验，优先修改回报最高的问题。
+## 2. 创作职责
 
-执行前阅读本技能的 `references/creative-editing-playbook.md`，并把简洁的创作决定写入：
+这不是单纯的 JSON / 渲染流水线。Agent 是本次内容的创作负责人。先判断本轮的**创作控制模式**（CREATE / DIRECTED / REVISION，与 `--edit-mode` 无关），再在进入昂贵的下游处理前完成五次判断：
 
-- `recap_story_plan.json`：导演意图、适用时的备选假设、选定主线和基于变化的 beat 图。
-- `visual_audio_board.json`：每拍的画面任务、表演/反应选择、原声锚点、`audio_owner` 与 `narration_job`。
-- `style_card.json`（有表达要求或表达反馈时）：当前声音、口语节奏、字幕阅读姿态与明确禁忌。
+1. **导演判断**：观众承诺、POV、戏剧问题、情绪终点与揭示节奏。
+2. **故事编辑**：beat 定义为“发生了什么变化”，不是场景摘要。
+3. **画面剪辑**：选择真正值得保留的具体时刻、反应、入点与出点。
+4. **声音/旁白**：先分配画面、原声、沉默和旁白的任务，再写解说词。
+5. **观众复核**：分别检查无旁白、只听声音和第一次观看的体验。
 
-这些文件只记录可审计的当前决定，不记录冗长思维过程；它们不会增加服务或渲染依赖。现有工具可以忽略它们，Agent 与建议型解说评审会用它们保持创作一致。建立这条内容基线不需要平台数据。
+三种控制模式的定义、REVISION 的修改/冻结规则、创作方法以及 `recap_story_plan.json` / `visual_audio_board.json` / `style_card.json` 的写法，全部按 `video-script` 执行；它会要求先读创作手册。这些文件只记录可审计的当前决定，不增加服务或渲染依赖。
 
 ## 3. 环境与脚本路径
 
@@ -57,7 +78,7 @@ export MIMO_API_KEY=***
 - VLM：`mimo-v2.5`
 - TTS：`mimo-v2.5-tts`
 
-TTS 可通过 `--tts-provider fish-audio` / `TTS_PROVIDER=fish-audio` 改用 Fish Audio；此时另需 `FISH_API_KEY`，默认模型为 `s2.1-pro-free`，默认使用“娱乐扒妹”音色（`5653cea4ac83480aaf2bf45406556185`），可用 `FISH_TTS_REFERENCE_ID` 覆盖。ASR/VLM 仍使用 MiMo。
+TTS 供应商由 `--tts-provider mimo-tts|fish-audio|index-tts`（或 `TTS_PROVIDER`）透传给配音技能；Fish Audio 与自托管 index-tts 各自的环境变量、默认音色和能力限制见该技能。ASR/VLM 始终使用 MiMo。`--doctor` 只做离线配置检查。
 
 `tp-*` Token Plan 密钥默认使用中国区集群，可用 `MIMO_TOKEN_PLAN_CLUSTER` 覆盖。
 
@@ -66,15 +87,15 @@ TTS 可通过 `--tts-provider fish-audio` / `TTS_PROVIDER=fish-audio` 改用 Fis
 - `--mimo-video-overview`：按场景块补充 MiMo 视频理解。
 - `--mimo-qc pre-assemble|post-render|both`：在合成前、成片后或两个阶段给出建议型复核。
 
-MiMo QC 默认关闭；每个选定阶段最多请求一次，写入 `mimo_qc.json`。任何凭证缺失、限流、超时、格式错误或采样失败都只记录状态，不阻断流程。详细可覆盖配置见 `references/config-playbook.md`。
+MiMo QC 默认关闭；每个选定阶段最多请求一次，写入 `mimo_qc.json`。任何凭证缺失、限流、超时、格式错误或采样失败都只记录状态，不阻断流程。可覆盖配置见 `references/config-playbook.md`，QC 报告的最小契约见 `references/shift-left-qc-schema.md`。
 
 下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本启动后会自行定位兄弟技能和资源。
 
-## 4. 标准解说流程
+## 4. 标准解说流程（audio-mode narration）
 
 ### 4.1 背景调研
 
-若能识别影片、剧集或主题，先按本技能的 `references/research-guide.md` 调研并写入
+若能识别影片、剧集或主题，先按 video-understanding 技能的调研指南 `research-guide.md` 调研并写入
 `work_dir/background_research.json`。视频理解会把人物名和剧情背景折入 VLM 上下文，避免只得到“黑衣男子”一类模糊描述。无法识别来源时可跳过。
 
 ### 4.2 分析并暂停创作
@@ -114,6 +135,10 @@ python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --material-library-dir
 
 素材检索只是对 JSON / MD / JSONL 做 grep，例如 `grep -R "keyword" .video-materials`。当前版本不复制原始媒体，也不提供数据库、向量或语义搜索。
 
+同一根目录还可以登记可复用的资源（BGM、音效、音色、字体、图片）、带版本与采用记录的模板（字幕样式、包装图层）和样片。
+格式与 `scripts/library.py check|list|show` 只读工具见 `references/resource-library.md`。用 `--project recap_project.json` 把已采用的字幕样式、音色与 BGM 绑定到这次运行；
+每次 full / cut 合成后 `work_dir/resource_lock.json` 记下实际用到的资源与授权状态。
+
 ### 4.4 继续生成成片
 
 写好所需产物后，重复同一条命令：
@@ -130,7 +155,9 @@ python3 scripts/recap.py <video> --work-dir <work_dir>  # 可追加 --edit-mode
 python3 scripts/recap.py <video> --work-dir <work_dir> --mimo-qc both
 ```
 
-合成前复核会读取脚本、计划和 TTS 元数据；成片后还会读取最多六张临时 JPEG。相同输入命中内容缓存，`--mimo-qc-refresh` 可强制刷新。帧的 base64 与凭证不会写入磁盘。
+合成前复核会读取脚本、计划和 TTS 元数据；成片后还会读取最多六张临时 JPEG。输入文件的大小/修改时间、模型与提示都未变时直接复用上次报告，`--mimo-qc-refresh` 可强制刷新。帧的 base64 与凭证不会写入磁盘。
+
+已有批准解说稿时加 `--preserve-approved-text`：校验与 TTS 原样保留批准稿（只更新 `overlaps_speech`），装不下时间窗即失败，不缩稿、不降级为部分成功。
 
 ### 4.5 字幕与克隆旁白
 
@@ -154,7 +181,27 @@ python3 tools/measure_subtitle.py <video>
 4. 单独复看开头、核心情绪/表演点和结尾，确认进入时机、回报停留和收束都成立。
 5. REVISION 分别验证本轮修改项已经改变、冻结项没有意外变化；然后再做解码、时长、音画规格等机械检查。
 
-scene score、亮度统计、contact sheet 与自动 QC 只负责定位候选问题；最终判断以真实播放为准。短时间内出现密集候选时，必须判断每个切点来自原片还是本次拼接：原片无关短镜头整段删，相关短镜头扩展到完整动作/反应；人工拼接点优先移动边界、恢复同源连续运动或合并片段，能消除就不保留。修复失败时回到剪点、声音或文案层，不用更多包装掩盖。
+scene score、亮度统计、contact sheet 与自动 QC 只负责定位候选问题；最终判断以真实播放为准。密集切点的来源判断与处理规则按剪辑技能执行。修复失败时回到剪点、声音或文案层，不用更多包装掩盖。
+
+full/cut 交付如需让确定性的最终检查影响命令退出状态，显式传
+`--require-final-qc`。只有 `final_qc.json` 与 `golden_eval.json` 的摘要均为
+`ok: true` 且整数 `blocker_count: 0` 才打印完成并返回成功；缺失、畸形或 blocker
+会保留报告和已渲染诊断媒体，但命令非零退出且不打印完成。默认仍是仅报告、不阻断。
+该参数不支持 `--edit-mode dub`；dub 未传该参数时的准备和渲染行为不变。
+
+### 4.7 不需要解说的片子
+
+```bash
+# 对当前整段输入直接合成；不隐式跑理解/ASR/TTS
+python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
+# 剪辑计划仍按 cut 流程产生，剪完不再暂停等待 narration.json
+python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix
+# 只换包装时冻结当前整片 AAC；不允许同时加 BGM/TTS
+python3 scripts/recap.py adopted.mp4 --work-dir packaging_work --audio-mode adopted-packet-copy
+```
+
+`source-mix` 仍会混音和重编码；`cut + adopted-packet-copy` 冻结的是剪后中间片的声音，不是原片的 AAC 包。
+当前严格字幕轨只支持 adopted 模式；其他字幕来源没有因此变成精确对齐。切换声音模式须新工作目录，不得把旧 TTS、QC 或自动生成的解说花字混入本轮原声生产。细节见 `references/audio-routing.md`。
 
 ## 5. 英译中原声复刻模式
 
@@ -178,12 +225,22 @@ python3 scripts/recap.py <video> --edit-mode dub --work-dir <work_dir>
 
 重复同一命令后输出 `dub_<name>.mp4`。每句单独克隆并贴回原时间线；只有即将覆盖下一句时才局部加速。当前版本只支持单说话者、整轨替换，不分离背景音乐。
 
-## 6. 自检命令
+## 6. 自检与只读 dashboard
 
 ```bash
 python3 scripts/recap.py --doctor
 ```
 
+### 6.1 只读 dashboard
+
+```bash
+python3 scripts/dashboard_server.py --root <目录> [--port 0] [--open]
+```
+
+前台运行并打印本机地址（只绑定 127.0.0.1，Agent 启动时放到后台）。它在 `--root` 下按 `library.json`、`recap_project.json`、
+`recap_run_manifest.json` 发现资源库、项目与运行，按阶段显示剪辑节奏、旁白、成片与时间线、QC 和 `resource_lock.json`。
+严格只读：只接受 GET / HEAD，不写任何文件；页面上的「复制给助手」只复制一句请求，改动回到对话里做。
+
 ## 7. 输出与参数
 
 主要输出：
@@ -194,23 +251,10 @@ python3 scripts/recap.py --doctor
 - `work_dir/recap_story_plan.json` / `visual_audio_board.json`：Agent 创作意图与剪辑决定。
 - `work_dir/mimo_qc.json`：可选的建议型复核，不作为发布门禁。
 
-可透传参数：
-
-`--context`、`--scene-threshold`、`--style`、`--edit-mode {full,cut,dub}`、`--target-duration`、
-`--skip-asr`、`--mimo-video-overview`、`--mimo-qc {off,pre-assemble,post-render,both}`、
-`--mimo-qc-refresh`、`--consolidate`、`--consolidate-asr`、`--tts-provider`、`--mimo-tts-voice`、`--voice-ref`、
-`--allow-partial-tts`、`--review-narration`、`--no-review-narration`、`--require-narration-review`、
-`--subtitle-y-top`、`--subtitle-y-bot`、`--no-burn-subtitles`、`--output-dir`、
-`--export-jianying`、`--jianying-bundle-media`、`--jianying-no-bundle-media`、
-`--material-library-dir`、`--use-materials`、`--save-materials`。
-
-`--style` 是原样传给 Agent 的自由文本指导，不是 preset、枚举、开关或有限风格分类。
+完整参数列表以 `python3 scripts/recap.py --help` 为准。`--style` 是原样传给 Agent 的自由文本指导，不是 preset、枚举、开关或有限风格分类。
 
 ## 8. 能力边界
 
-- 编排器不代替 Agent 写 `narration.json` / `clip_plan.json`；具体写作遵循创作 brief 与写作阶段契约。
 - 语义评审默认建议型、失败开放；只有调用方显式启用严格解说评审时，事实矛盾、残句或评审不可用才会在 TTS 前阻断。确定性校验阶段始终负责硬校验。
 - MiMo QC 不能阻断、自动修复或改变退出状态，只提供定位建议。
-- 建立内容质量基线不依赖平台分析、留存遥测或发布接入。
-- 本技能不是无人值守调度器，不会向任何平台发布内容。
-- 各阶段技能不共享代码，只通过 `work_dir` 产物通信。
+- 宣发标题、花字或外部文案回填见 `video-script` 的 references/promotional-copy.md。

package/lib/video-recap/skills/video-recap/references/audio-routing.md

@@ -0,0 +1,126 @@
+# Recap audio routing
+
+`--edit-mode` selects the picture workflow; `--audio-mode` independently
+selects the final audio workflow:
+
+| Audio mode | Narration validation/review | TTS | Assemble input |
+| --- | --- | --- | --- |
+| `narration` (default) | Runs as before | Runs as before | source or rendered cut |
+| `source-mix` | Not applicable | Not run | current source or rendered cut |
+| `adopted-packet-copy` | Not applicable | Not run | current source or rendered cut |
+
+`full` with either non-narration mode goes directly to assemble and does not
+implicitly run understanding. `cut` still requires the existing `clip_plan`:
+the first run analyzes and pauses for that plan, then later runs the established
+single- or multi-source cut renderer. It does not pause for `narration.json`.
+
+## Local adopted full-sound assembly
+
+The strict local-adoption route accepts one prebuilt picture in `full` mode and
+exactly this all-or-none bundle:
+
+```text
+--tts-meta PATH --narration-adoption PATH --audio-mix-adoption PATH
+```
+
+It requires narration mode, stream 0, a new explicit `--work-dir`, and a delivery path
+that does not already exist. `--output-dir` is optional; when omitted, delivery uses the
+new work directory's parent. The route calls only the video-assemble CLI; it does
+not run understanding, script validation, narration review, voiceover, MiMo QC, cut,
+continuation, editor export, or material-cache reuse. Ambient TTS provider and voice
+configuration are inert. Explicit TTS/voice/review/MiMo/editor flags are rejected rather
+than silently ignored.
+
+`recap_run_manifest.json` records the resolved path of all three local artifacts under
+`audio.local_adoption`, and the picture's path plus `{size, mtime_ns}` as
+`source_video_identity`. Analysis settings remain separate and unchanged. Recap validates
+routing and, after the child run, checks that the assembler's binding records reference
+the same adoption files and picture; video-assemble remains authoritative for the adoption
+schemas, PCM shapes, frame clock, mix, bindings, and final media transaction. This path
+executes caller-adopted assets and does not claim that recap authored or approved their
+story, voice, or mix.
+
+## Keep adopted voice after a cut
+
+The single input above is the **finished picture**, which may contain one or many source
+episodes. Use two existing stages rather than sending an old mix binding into a new cut:
+
+1. Finish the selected cut with `video-cut`: either run `recap.py ... --edit-mode cut`,
+   or call that skill's own `scripts/cut.py` from its installed directory, with an
+   existing clip plan and source manifest:
+
+   ```bash
+   python3 <video-cut>/scripts/cut.py ep1.mp4 --work-dir CUT_WORK \
+     --sources-manifest SOURCES_JSON
+   ```
+
+   A single-source cut omits `--sources-manifest`. For already locked frame decisions,
+   use the picture-plan path instead. Read `clip_plan_validated.json` (or the locked path's
+   `picture_map.json`) before placing sound.
+2. Keep the selected WAVs, `tts_meta.json`, and `narration_adoption.json` when the words,
+   WAV bytes, and selected voice are unchanged. Do not run voiceover just to move a line.
+   In this explicit mix, new `output_start_sample` values own placement; old generation
+   windows in `tts_meta.json` are not the revised output timeline.
+3. Match source dialogue, ambience and music to the new picture. Reuse the prepared bed
+   only if that sound and its complete sample clock remain appropriate; otherwise rebuild
+   it with the existing `video-assemble` source/score producer. Write a **new** mix adoption
+   with the prepared receipt path, total samples and complete WAV placements for the new
+   picture. Reordering shots can require moving dialogue too; a mix adoption written for
+   the old picture cannot simply be pointed at the new one.
+4. Run the local adopted `full` command in `SKILL.md` with `CUT_WORK/edited_source.mp4` and a new
+   assembly work/delivery directory. Inspect the emitted narration placements and subtitles
+   against that mixed output. Rebind any precise subtitle track to the new finished audio.
+
+The same steps handle a later revision: keep unchanged picture/voice assets, rebuild only
+the affected bed and placement decisions, then assemble into a new directory. The local
+assembly command still does not resume an old work directory or decide new placements.
+
+## Identity and resume
+
+`recap_run_manifest.json` binds `{mode, selected_stream_index}` separately from
+understanding/material settings. Changing audio mode or stream requires a new
+work directory; it never reuses narrated TTS accidentally. Legacy manifests
+without the audio field are interpreted as `narration`, stream 0, preserving
+old in-flight narration runs. Continuation commands retain the audio selection.
+
+An unbound work directory containing `narration.json` is ambiguous and cannot
+be adopted by a source mode. Existing run-local QC stages are reset after the
+work-directory policy is validated. Source runs record TTS, narration
+validation, and narration review as `not_applicable`; old `tts_meta.json` and
+narration review files are not read as evidence for the current run.
+
+## Fail-closed combinations
+
+- `dub` cannot be combined with a non-narration audio mode.
+- Explicit TTS/text-policy options are rejected in source modes rather than
+  ignored. Ambient TTS provider/voice configuration is inert because TTS does
+  not run, and continuation commands do not promote it into explicit flags.
+- Cut audio modes support selected stream 0 only. Full mode may pass
+  another stream to assemble, subject to assemble/export support.
+- Source modes do not support advisory MiMo QC; use `off`.
+- Local adopted full-sound assembly consumes a prebuilt picture in `full` mode; use the
+  two-stage workflow above for single- or multi-source cuts. That assembly invocation
+  does not resume an old work directory or export an editor draft.
+- `source-mix` rejects an explicit `subtitle_track.json` before analysis or cut,
+  because the precise-track contract only binds adopted packet audio.
+
+`--preserve-approved-text` remains opt-in and is forwarded unchanged to
+voiceover and continuation only in narration mode.
+
+Narration may explicitly select `--tts-provider index-tts`; `auto` does not
+select Index TTS. Index TTS cannot be combined with MiMo voice selection,
+`--voice-ref`, or `dub`. Its endpoint and voice remain backend configuration,
+not recap defaults.
+
+## Packaging and frozen-audio boundary
+
+Source modes never regenerate `visual_overlays.json`. A work directory already
+bound to narration is rejected, preventing narration-derived overlays from
+silently becoming source-mode author input. Otherwise existing overlays are
+treated as caller-authored packaging and preserved.
+
+`adopted-packet-copy` freezes only the selected audio stream on the actual file
+passed to assemble. In `full`, that is the input video. In `cut`, the cut stage
+has already rendered `edited_source.mp4`; packet-copy verification therefore
+applies to that file's audio, **not** to AAC packets from any original source.
+This routing does not prove listening quality or publication approval.

package/lib/video-recap/skills/video-recap/references/config-playbook.md

@@ -2,8 +2,10 @@
 
 The bundle runs **zero-config** with sensible defaults. To change behavior, set the
 environment variables below (or pass the noted CLI flags) — they **override** the defaults.
-Nothing here is required; this is documentation only. No tool reads a config file, and the
-bundle ships no root `CLAUDE.md` (so it never collides with your project/global instructions).
+Nothing here is required; this is documentation only. The only config file any tool reads is an
+optional `recap_project.json` passed with `--project` (see `resource-library.md`): it resolves to the same
+variables below, and a variable you set that disagrees with the project stops the run. The bundle ships no
+root `CLAUDE.md` (so it never collides with your project/global instructions).
 Defaults below are bundle-level defaults unless a note scopes them to a specific stage.
 
 | Concern | Env var / flag | Default | Notes |
@@ -14,18 +16,19 @@ Defaults below are bundle-level defaults unless a note scopes them to a specific
 | ASR model | `MIMO_ASR_MODEL` | `mimo-v2.5-asr` | speech-to-text |
 | ASR language | `MIMO_ASR_LANGUAGE` | `auto` | `auto` / `zh` / `en` |
 | ASR window | `ASR_SEGMENT_SECONDS` | `15` | smaller → finer dialogue timestamps (stays under MiMo's 10MB base64 cap) |
-| TTS provider | `TTS_PROVIDER` / `--tts-provider {auto,mimo-tts,fish-audio}` | `auto` | `auto` prefers configured MiMo, then Fish Audio; explicit selection is recommended for repeatable runs |
+| TTS provider | `TTS_PROVIDER` / `--tts-provider {auto,mimo-tts,fish-audio,index-tts}` | `auto` | `auto` prefers configured MiMo, then Fish Audio, and never picks index-tts; explicit selection is recommended for repeatable runs |
 | MiMo TTS model | `MIMO_TTS_MODEL` | `mimo-v2.5-tts` | MiMo provider only |
 | MiMo voice | `MIMO_TTS_VOICE` / `--mimo-tts-voice` | `冰糖` | |
 | Cloned narration voice | `VOICE_REF` / `--voice-ref` | off | MiMo full/cut only; lazily normalize once, then use `mimo-v2.5-tts-voiceclone`; mutually exclusive with `--mimo-tts-voice`; requires authorization and sends the reference to MiMo |
 | Fish Audio key | `FISH_API_KEY` | — | required when Fish Audio is selected; never written to artifacts or cache metadata |
-| Fish Audio model | `FISH_TTS_MODEL` | `s2.1-pro-free` | current free model; Fair Use/no SLA and free availability is currently announced through 2026-08-31 |
-| Fish Audio voice | `FISH_TTS_REFERENCE_ID` | `5653cea4ac83480aaf2bf45406556185`（娱乐扒妹） | optional override for the built-in narration voice; participates in segment cache identity |
+| Fish Audio model | `FISH_TTS_MODEL` | `s2.1-pro-free` | free model under Fair Use, no SLA; check Fish Audio's current policy |
+| Fish Audio voice | `FISH_TTS_REFERENCE_ID` | `5653cea4ac83480aaf2bf45406556185`（娱乐扒妹） | optional override for the built-in narration voice; part of the per-segment cache settings |
 | Fish Audio endpoint | `FISH_TTS_API_URL` | `https://api.fish.audio/v1/tts` | returns WAV directly to the existing voiceover pipeline |
-| TTS transport | `TTS_TIMEOUT` / `TTS_WORKERS` / `TTS_RETRIES` | `300` / `4` / `3` | request timeout, parallel segments, and per-segment retries for both providers |
+| Self-hosted TTS | `INDEX_TTS_ENDPOINT` / `INDEX_TTS_VOICE` | — | explicit `--tts-provider index-tts` only; the endpoint is never written to disk, and segment `emotion`/style is rejected |
+| TTS transport | `TTS_TIMEOUT` / `TTS_WORKERS` / `TTS_RETRIES` | `300` / `4` / `3` | request timeout, parallel segments, and per-segment retries for all providers |
 | Advisory MiMo QC | `MIMO_QC` / `--mimo-qc {off,pre-assemble,post-render,both}` | `off` | optional subjective review at the selected stage(s), one request per stage. Always fail-open: results only point the agent/user to `mimo_qc.json`, never block or auto-repair |
-| MiMo QC refresh/model | `MIMO_QC_REFRESH` / `--mimo-qc-refresh`; `MIMO_QC_MODEL` | cache on / VLM fallback | content-keyed cache excludes absolute paths. Post-render temporarily samples at most 6 JPEGs (≤768px); base64 is never persisted. The standalone adapter requires explicit `mimo_qc.py --live` for network access |
-| Narration block coverage | `NARRATION_COVERAGE_TARGET` / `NARRATION_BLOCK_SECONDS` | `0.7` / `9.0` | current block-recap density controls; old `TARGET_SEGMENTS_PER_MINUTE` applies only to legacy single-pass cut mapping reports |
+| MiMo QC refresh/model | `MIMO_QC_REFRESH` / `--mimo-qc-refresh`; `MIMO_QC_MODEL` | cache on / VLM fallback | the reuse check compares evidence file sizes/mtimes, model and prompt, never absolute paths. Post-render temporarily samples at most 6 JPEGs (≤768px); base64 is never persisted. The standalone adapter requires explicit `mimo_qc.py --live` for network access |
+| Narration block coverage | `NARRATION_COVERAGE_TARGET` / `NARRATION_BLOCK_SECONDS` | `0.7` / `9.0` | current block-recap density controls |
 | Narration speed | `NARRATION_SPEED` | `1.15` | global atempo on the voiceover; set `1.0` for long-form/documentary |
 | Narration authored start | `NARRATION_DELAY_SECONDS` | `0` | the renderer uses the Agent-authored `start` exactly. Set a non-zero value only for legacy drafts; hidden delay can move a validated sentence-boundary entry back into source speech |
 | Source sentence boundary detector | `SOURCE_BOUNDARY_NOISE_THRESHOLD` / `SOURCE_BOUNDARY_MIN_PAUSE` / `SOURCE_BOUNDARY_MAX_ALIGNMENT_ERROR` | `-18dB` / `0.12` / `2.1` | aligns ASR terminal punctuation to short acoustic pauses and writes `speech_boundary_anchors.json`; unsafe narration entries and cut in/out points are blocked. There is no intentional-interrupt override |
@@ -47,6 +50,7 @@ Defaults below are bundle-level defaults unless a note scopes them to a specific
 | Shot-change-aware cut | `SCENE_CUT_SNAP` / `SCENE_CUT_SNAP_MARGIN` / `SCENE_CUT_DETECT_THRESHOLD` | on / `0.5` / `0.4` | cut mode: nudge each clip boundary off the original footage's hard cuts so the edit point doesn't flash a sliver of the adjacent shot (闪烁). source_start moves forward onto / source_end back onto any shot-change within the margin; boundaries already on a cut, or that would shrink a clip below ~0.5s, are left as-is. Set `SCENE_CUT_SNAP=0` to disable |
 | VLM workers | `VLM_WORKERS` | `8` | lower to 1 if a proxy/WAF rate-limits |
 | Subtitle size | `SUBTITLE_FONT_SIZE` / `SUBTITLE_MARGIN_V` | `42` / `48` | look & placement |
+| Subtitle font | `SUBTITLE_FONT_NAME` / `SUBTITLE_FONT_FILE` | `Arial` / — | with a font file, burned ASS subtitles load fonts from its directory (`fontsdir`) and on-screen text overlays use it (`fontfile`); `SUBTITLE_FONT_NAME` must be that file's family name. A bound `subtitle_style` template sets both |
 | 整理 / index | `--no-consolidate` / `--consolidate-asr` | on | build the understanding index (and optionally clean ASR); use `--no-consolidate` to skip |
 | Advisory / strict narration review | `REVIEW_NARRATION` / `--review-narration` / `--no-review-narration`; strict: `REQUIRE_NARRATION_REVIEW` / `--require-narration-review` | advisory on, strict off | runs the narration review stage after validation and before TTS. Default advisory mode is fail-open; strict mode blocks TTS on review failure, parse error, or error-severity findings. In cut mode the reviewer uses `clip_plan_validated.json` to remap VLM/ASR grounding onto the output timeline |
 | 剪映 export (optional) | `--export-jianying` / `EXPORT_JIANYING` | off | after rendering, also write a 剪映/JianYing draft from `timeline.json`. Decoupled — the core render never needs it |

package/lib/video-recap/skills/video-recap/references/data-schema.md

@@ -106,14 +106,13 @@
 {
   "schema_version": 2,
   "timeline": "cut_output",
-  "clip_plan_fingerprint": "md5-of-canonical-clip-plan",
   "sentence_anchors": [{"time": 4.0, "pause_start": 3.8, "confidence": "high"}],
   "speech_spans": [{"start": 0.0, "end": 3.8}],
   "quiet_windows": [{"start": 3.8, "end": 4.1}]
 }
 ```
 
-`clip_plan_fingerprint` 必须与当前 `clip_plan_validated.json` 一致。缺失、过期或畸形的
+该文件必须不早于当前 `clip_plan_validated.json`（按修改时间判断）。缺失、过期或畸形的
 output 证据一律 fail closed，不能回退到原片时钟或信任 Agent 写入的
 `overlaps_speech=false`。多来源剪辑的每条映射记录还保留 `source_id` 和原片起止时间。
 
@@ -143,7 +142,7 @@ output 证据一律 fail closed，不能回退到原片时钟或信任 Agent 写
 
 ## narration.json
 
-Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated cut 模式（`video-recap --edit-mode cut`）下，第二次暂停时已经先剪出 `edited_source.mp4`，因此 `narration.json` 必须直接使用剪后成片的 OUTPUT 时间轴（0..成片总时长），不会再生成或消费 `narration_mapped.json`。只有 legacy direct `video-cut` 单 pass 路径才会把原视频时间的 narration remap 成 `narration_mapped.json`：
+Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated cut 模式（`video-recap --edit-mode cut`）下，第二次暂停时已经先剪出 `edited_source.mp4`，因此 `narration.json` 必须直接使用剪后成片的 OUTPUT 时间轴（0..成片总时长）；不存在原视频时间→输出时间的旁白映射产物：
 
 ```json
 [
@@ -181,7 +180,7 @@ Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated
 
 ## recap_story_plan.json / visual_audio_board.json（Agent 创作工作产物）
 
-这两个 JSON 是 skill 层的创作决策记录：前者保存导演意图、备选剪辑假设、POV/主线和 change-based beats；后者保存每拍的画面/表演选择、入点/出点、原声锚点、`audio_owner` 与 `narration_job`。完整字段与工作流见本技能的 `creative-editing-playbook.md`。
+这两个 JSON 是 skill 层的创作决策记录：前者保存导演意图、备选剪辑假设、POV/主线和 change-based beats；后者保存每拍的画面/表演选择、入点/出点、原声锚点、`audio_owner` 与 `narration_job`。完整字段与工作流见 video-script 技能的 `creative-editing-playbook.md`。
 
 CLI 不以它们作为渲染硬门禁，也不新增解析服务；建议型解说评审在文件存在时读取它们，Agent 则用它们保证 cut、旁白和声音选择没有偏离同一个创作意图。
 
@@ -264,19 +263,19 @@ CLI 不以它们作为渲染硬门禁，也不新增解析服务；建议型解
 
 ## multi_source_manifest.json（多视频 cut）
 
-多视频剪辑模式下，项目级 `work_dir/multi_source_manifest.json` 是编排、剪辑与合成阶段共用的来源契约。`source_id` 默认由源文件 SHA-256 派生为 `src_<fingerprint[:12]>`；同一项目里重复 fingerprint 的不同路径会追加短 path hash 后缀。
+多视频剪辑模式下，项目级 `work_dir/multi_source_manifest.json` 是编排、剪辑与合成阶段共用的来源契约。`source_id` 由源文件名主干与文件大小派生为 `src_<stem>_<size>`；同一项目里得到相同 id 的后续来源按输入顺序追加 `_2`、`_3` 后缀。`source_video_identity` 记录该文件的 `{size, mtime_ns}`，续跑时与当前输入逐项比对。
 
 ```json
 {
   "schema_version": 1,
   "sources": [
     {
-      "source_id": "src_0123456789ab",
+      "source_id": "src_episode1_734003200",
       "source_path": "/abs/episode1.mp4",
       "source_name": "episode1.mp4",
-      "source_video_fingerprint": "0123456789abcdef...",
-      "source_work_dir": "sources/src_0123456789ab",
-      "material_id": "episode1-0123456789ab"
+      "source_video_identity": {"size": 734003200, "mtime_ns": 1758326400000000000},
+      "source_work_dir": "sources/src_episode1_734003200",
+      "material_id": "episode1-734003200"
     }
   ]
 }
@@ -307,8 +306,8 @@ cut 模式下 Agent 选择要保留的原片片段，数组或 `{ "clips": [...]
 {
   "target_duration": "10m",
   "clips": [
-    {"source_id": "src_0123456789ab", "start": 12.0, "end": 38.0, "reason": "b01 | setup | knowledge: unknown→clue | POV=主角 | 保留迟疑反应 | 入点=线索出现 | 出点=疑问成立"},
-    {"source_id": "src_fedcba987654", "start": 4.0, "end": 22.0, "reason": "b02 | payoff | power: suspect→hero | POV=主角 | 保留最终选择 | 入点=证据落下 | 出点=代价显现"}
+    {"source_id": "src_episode1_734003200", "start": 12.0, "end": 38.0, "reason": "b01 | setup | knowledge: unknown→clue | POV=主角 | 保留迟疑反应 | 入点=线索出现 | 出点=疑问成立"},
+    {"source_id": "src_episode2_689110016", "start": 4.0, "end": 22.0, "reason": "b02 | payoff | power: suspect→hero | POV=主角 | 保留最终选择 | 入点=证据落下 | 出点=代价显现"}
   ]
 }
 ```
@@ -347,7 +346,7 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
   "clips": [
     {
       "clip_id": 0,
-      "source_id": "src_0123456789ab",
+      "source_id": "src_episode1_734003200",
       "source_path": "/abs/episode1.mp4",
       "source_start": 12.0,
       "source_end": 38.0,
@@ -362,7 +361,7 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
 
 ## material library（可选，grep 复用）
 
-`--material-library-dir <dir> --save-materials` 会把每个源视频的已分析小文件复制到 `<dir>/materials/<material_id>/`，不复制原始媒体。`--use-materials` 会在 fingerprint 和 settings fingerprint 匹配时把这些 JSON/MD 产物恢复到当前 per-source `work_dir`。
+`--material-library-dir <dir> --save-materials` 会把每个源视频的已分析小文件复制到 `<dir>/materials/<material_id>/`，不复制原始媒体。`--use-materials` 会在源文件路径、`source_video_identity`（`{size, mtime_ns}`）和分析 `settings` 都相等时把这些 JSON/MD 产物恢复到当前 per-source `work_dir`。
 
 ```text
 .video-materials/
@@ -377,27 +376,10 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
     artifacts/understanding_index.json
 ```
 
-`materials_index.jsonl` 每次保存追加一行，字段包括 `schema_version`, `event`, `material_id`, `source_name`, `source_path`, `source_video_fingerprint`, `settings_fingerprint`, `summary`, `tags`, `material_dir`, `updated_at`。当前权威状态始终以 `materials/<material_id>/material.json` 为准。MVP 只承诺 `grep -R "关键词" <library>` 这类文件检索；没有 DB、embedding 或语义搜索。
+`materials_index.jsonl` 每次保存追加一行，字段包括 `schema_version`, `event`, `material_id`, `source_name`, `source_path`, `source_video_identity`, `summary`, `tags`, `material_dir`, `updated_at`；`material.json` 另外记录分析 `settings` 字典与每个产物的 `bytes`。当前权威状态始终以 `materials/<material_id>/material.json` 为准。MVP 只承诺 `grep -R "关键词" <library>` 这类文件检索；没有 DB、embedding 或语义搜索。
 
 保存时会对凭证形态（`tp-`/`sk-`/`gh*_`/`AKIA`/JWT 与 `KEY=VALUE` 赋值）和凭证命名的 JSON key 做脱敏，但这只是**尽力而为**的兜底，不是保证：陌生格式的密钥仍可能漏过。请从源头避免把密钥写进分析产物——key 从环境变量/`.env` 读取，不需要落进 scenes/ASR/VLM/summary 等 JSON。
 
-## narration_mapped.json
-
-仅 legacy direct `video-cut` 单 pass 路径会生成。orchestrated cut 模式不使用它：Agent 在 pass2 直接按剪后成片 OUTPUT 时间轴写 `narration.json`。当 legacy 路径启用时，`start/end` 已变成短视频输出时间，`source_start/source_end` 保留原视频时间：
-
-```json
-[
-  {
-    "start": 2.0,
-    "end": 7.0,
-    "source_start": 14.0,
-    "source_end": 19.0,
-    "source_clip_id": 0,
-    "narration": "解说文本"
-  }
-]
-```
-
 ## original_subtitles.json / user_subtitles.{json,srt,ass}（可选，原声留白字幕）
 
 解说块之间的原声留白会把【原声台词】烧成字幕（assemble 阶段用 `「」` 包裹以区分解说）。来源优先级（高→低）：
@@ -484,6 +466,35 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
 
 > 正常（无失败）运行也会带 `"partial": false, "failures": []`。partial 成片只适合预览，不建议直接发布。
 
+`voice` 记录本次实际使用的音色：`{"provider": "mimo-tts", "model": "mimo-v2.5-tts", "voice_id": "冰糖", "reference": null}`。
+用参考音频克隆时 `voice_id` 为 `null`，`reference` 为 `{path, size, mtime_ns}`；Fish Audio 的 `voice_id` 是 reference id，
+index-tts 的是 `INDEX_TTS_VOICE`。旧 `tts_meta.json` 没有这个字段时按只知道 `engine` 处理。
+
+## resource_lock.json（本次运行用到的资源）
+
+full / cut 流程（含本地采用路径）合成完成后，video-recap 在 `work_dir` 写出 `resource_lock.json`，汇总运行清单、
+`tts_meta.json.voice` 与 `assembly_manifest.json`（BGM 路径、字幕字体）里已有的事实；配置了资源库时，按解析后的路径
+（音色按 provider + voice_id）把每项对上已登记的资源，带出授权与声音授权状态。dub 模式不写。
+
+```json
+{
+  "schema": "video-recap.resource-lock.v1",
+  "work_dir": "/abs/work_dir",
+  "library": "/abs/library",
+  "project": null,
+  "templates": [],
+  "resources": [
+    {"role": "bgm", "path": "/abs/library/resources/bgm/pulse-demo/pulse-demo.wav", "size": 8044, "mtime_ns": 1,
+     "detail": {}, "library": {"id": "pulse-demo", "kind": "bgm", "license": "owned", "consent": null}}
+  ],
+  "attention": [{"code": "license_unknown", "role": "voice", "message": "…"}]
+}
+```
+
+`role` ∈ `source_video` / `voice` / `bgm` / `subtitle_font`（项目绑定后还会有模板引入的资源）。`attention` 列出需要人确认的项：
+`license_unknown` / `license_restricted`、参考音频的 `consent_unknown` / `consent_denied`，以及配置了资源库但没有登记的
+`unregistered`。它只提示、不阻断；`final_qc.json` 只承载阻断项，不包含这些提示。
+
 组装后，`assembly_manifest.json.audio_segments[]` 另外记录 `fit_status`、`truncated`、
 `truncate_reason`、`placed_audio_duration`、`placed_audio_path`、`source_duck_end`、
 `source_restore_at` 与 `source_handoff_status`。组装阶段从不按时间裁旁白尾音：放不下时用
@@ -496,7 +507,7 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
 
 Dub 模式下，`dub_script.json` 在 voiceclone **之前**先经过 deterministic lint，把明显不可发布的脚本挡在昂贵的克隆 TTS 之前。空译文、相邻行重叠、时间越界、`room < 0.4s` 等 **error** 会 `verdict=FAIL` 并阻断 render；`fast_speech`、`trim_risk` 等是 warning，不阻断。
 
-每行 voiceclone 原始 WAV 会按模型、合成提示、中文台词和参考音频 SHA-256 写入相邻的 `*.wav.meta.json`。指纹完全匹配且 WAV 可读取时，dub render 直接复用并在 `dub_manifest.json.lines[].tts_cache` 记录 `hit`；台词、参考音频、模型或提示变化都会自动失效并重新合成。
+每行 voiceclone 原始 WAV 会把中文台词、模型/提示等合成设置和参考音频信息写入相邻的 `*.wav.meta.json`。台词与设置完全相等且 WAV 可读取时，dub render 直接复用并在 `dub_manifest.json.lines[].tts_cache` 记录 `hit`；台词、参考音频、模型或提示变化都会重新合成。
 
 ```json
 {
@@ -527,7 +538,7 @@ Dub 模式下，`dub_script.json` 在 voiceclone **之前**先经过 determinist
 
 `preflight_qc.json`、`final_qc.json`、`golden_eval.json`、`mimo_qc.json` 共用最小 QC 契约；stage 仅允许 `pre_cut` / `post_cut` / `pre_tts` / `post_tts` / `pre_assemble` / `post_render` / `golden`，其中 `mimo_qc.json` 是 artifact 而不是 stage。详见 `shift-left-qc-schema.md`。
 
-`recap.py` 可通过 `--mimo-qc pre-assemble|post-render|both`（默认 `off`）在组装前和/或成片后写 `mimo_qc.json`。每个 stage 最多一次 live request；相同素材/模型命中内容缓存，`--mimo-qc-refresh` 可刷新。`post_render` 最多临时抽取 6 张、最长边 768px 的 JPEG；base64 只进入请求，不写进 artifact。多 stage 报告聚合在 `metadata.stages`，状态为 `completed` / `cached` / `unavailable` / `failed`，任何状态都不阻断、也不自动修复。关闭功能会清理旧 `mimo_qc.json`，避免陈旧建议被误认为本轮结果。
+`recap.py` 可通过 `--mimo-qc pre-assemble|post-render|both`（默认 `off`）在组装前和/或成片后写 `mimo_qc.json`。每个 stage 最多一次 live request；报告的 `metadata.cache_input`（证据文件的 kind/bytes/mtime_ns、模型、提示与抽帧元数据）与本次完全相等时复用上次结果，`--mimo-qc-refresh` 可刷新。`post_render` 最多临时抽取 6 张、最长边 768px 的 JPEG；base64 只进入请求，不写进 artifact。多 stage 报告聚合在 `metadata.stages`，状态为 `completed` / `cached` / `unavailable` / `failed`，任何状态都不阻断、也不自动修复。关闭功能会清理旧 `mimo_qc.json`，避免陈旧建议被误认为本轮结果。
 
 QC 证据把 `source_asr` 与 `generated_subtitles` 分开：前者只用于源事实/原声时序，后者是本轮旁白派生字幕，不能反过来充当事实证据。多视频项目从 `multi_source_manifest.json` 指向的逐源 work dir 汇集 ASR；`cut_output` 解说评审同样按 `source_id` 映射逐源 VLM/ASR，避免项目根目录没有单一 ASR 文件时产生空证据。