@oh-story/dsh 0.1.3 → 0.1.5

package/lib/types/workspace-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-route.d.ts","sourceRoot":"","sources":["../../src/workspace-route.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAgBnD,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAkOD,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAM7F"}
+{"version":3,"file":"workspace-route.d.ts","sourceRoot":"","sources":["../../src/workspace-route.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAmCnD,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAiHD,MAAM,WAAW,SAAS;IAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAE3E;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,IAAI,CAcpG;AAwGD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAW7E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAErE;AAoHD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ9C;AAmMD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiBnE;AAuJD,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAM7F"}

package/lib/video-recap/CHANGELOG.md

@@ -0,0 +1,282 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
+
+小节名统一使用 Keep a Changelog 的六个英文类别（`Added` / `Changed` / `Deprecated` /
+`Removed` / `Fixed` / `Security`），正文为中文。收紧到会拒绝旧输入的改动记入 `Changed`。
+
+## [Unreleased]
+
+## [0.4.0] - 2026-07-27
+
+汇总 `v0.3.3` 之后的全部工作：多源剪辑、QC、字幕与配音改进，可携带剪映草稿能力，内容驱动的创作流程，以及一轮深度审查带来的正确性、性能与配置面修复。
+
+### 新增
+
+- **贴合原片字幕带。** `tools/measure_subtitle.py` 用 stdlib + ffmpeg 抽帧、检测并输出红框预览；`--subtitle-y-top/--subtitle-y-bot` 把新字幕基线与字号适配到测得坐标，并显式启用该区域遮罩。
+- **半透明、解说时段遮罩。** 显式启用原字幕遮罩后，默认改为 `SUBTITLE_MASK_OPACITY=0.6`、`SOURCE_SUBTITLE_MASK_TIMING=narration`，原声留白不再常驻黑条；仍可设为 `1` / `all` 恢复全黑全时段效果。
+- **参考音色解说。** recap / voiceover 新增 `--voice-ref`，通过 `mimo-v2.5-tts-voiceclone` 给普通解说克隆音色；新生成时参考音频惰性转码一次、最长取 30 秒，内容与转码版本指纹参与 TTS 缓存校验。
+- **正式的建议性 MiMo QC。** `--mimo-qc pre-assemble|post-render|both` 在单源/多源流水线的组装前、成片后各最多发起一次 MiMo 请求，把语义/审美观察聚合进 `mimo_qc.json`；内容缓存、`--mimo-qc-refresh`、最多 6 张/768px 临时抽帧、密钥/base64 不落盘均有回归覆盖。缺 key、401/429、超时、畸形响应和本地异常全部 fail-open，只提示 Agent/用户，永远不生成 blocker。
+- **可携带剪映草稿。** video/audio/image 默认打包到 `Resources/local`；timeline v2 新增恒定变速、倒放、transform、富文本/逐字样式、转场/mask/LUT、绿幕复合和离线资源轨道。
+
+### 改进
+
+- **内容驱动的创作流程。** Agent 在剪辑或写稿前先比较剪辑假设，记录 POV、戏剧问题、change-based beats、具体画面/反应、`audio_owner` 与 `narration_job`；`recap_story_plan.json` / `visual_audio_board.json` 同时覆盖单视频与多视频 cut。旁白比例改为素材决定，`7:3` 只保留为粗略回退而非配额。
+- **阶段技能完全自包含。** 阶段说明与本地参考不再引用兄弟技能的路径或名称；写稿阶段拥有独立的补充调研指南与 `deslop_qc.py`，不会假装新调研已被既有 VLM 消费。
+- **多视频证据更可用。** 项目 brief 优先摘取逐来源的背景、索引、ASR 与场景证据，不再只截取通用写作说明。
+
+### 变更
+
+- **每个配置旋钮只声明在读它的技能里。** 六份 `lib.py` 中有五份此前携带所有技能配置的并集（各 155–173 个键，其中 95–132 个该技能从不读取）；`video-cut` 一直是反例（8 个键，全部使用）。现在各技能只声明自己读取的键，删除 583 条无效声明。保留集由运行时插桩实测得出（按调用栈把 parity 测试的读取与生产代码的读取区分开），而非静态匹配——这也是发现下列两处问题的方式。
+  - `zone_fade_seconds` 在五份副本中均有声明，但**全仓库无任何读取点**，此前仅靠「副本之间取值一致」的断言存活。
+  - `CLIP_PADDING` 在 `video-cut` 中依然无效：该技能的 `lib.py` 从未声明此键，查表始终落到内联默认值。
+- **音频策略一致性断言改为按实际声明范围校验。** 此前断言五份副本对约 30 个音频键取值一致，而多数技能并不读取它们——这种一致性是复制行为自身造成的循环要求。新增不变量：**任何技能不得声明自身从不读取的配置**，从结构上杜绝上述两类问题复现。
+
+### 修复
+
+- **画面锚点整体偏移 1/fps 秒。** ffmpeg 的 `fps` 滤镜首帧在源时间 0，而文件编号从 1 起，所以 `frame_00001.jpg` 是 `t=0`、第 n 帧是 `(n-1)/fps`；此前按 `n/fps` 计算，把 `frame_facts`、场景归属与 storyboard 标签整体推后 1/fps 秒（>5min 视频默认 fps=1，即整整 1 秒）。这些时间戳会写进 VLM prompt 并作为写稿 Agent 的权威画面锚点。换算规则收敛到 `extract.py` 独家定义，帧/VLM 缓存带约定版本号，旧产物强制重算。
+- **带封面图的素材渲染直接失败。** 组装映射 `0:v` 会匹配到 attached_pic 那一路视频流，而 `-vf` 只作用于第一路，ffmpeg 报 `Could not write header` 并留下损坏文件——发生在整条流程的最后一步。改为 `0:v:0`。
+- **`--clip-padding` 非零时相邻片段被误判为重复素材。** 重叠检测此前基于加过 padding 的区间，任意两个背靠背片段都会硬失败；现按 Agent 实际写入的入出点判断。
+- **`CLIP_PADDING` 环境变量此前完全无效。** 六份 CONFIG 都声明了该键并通过 `clip_padding_source` 汇报为生效，但唯一实现 padding 的 video-cut 只读 CLI 参数。
+- 多视频输出时间线的 speech 证据改为与 `audio_mix` / `sentence_boundaries` 一致优先读 `asr_clean.json`；`narration_coverage_max` 等三个只读不声明的 CONFIG 键补齐；`silencedetect` 超时改为与该函数其余失败路径一致地 fail-open；多源剪辑的句子截断阻断项不再挂在无关条件下。
+- 亮色画面不再把整片背景误并为字幕候选；测量结果按源隔离，失败时保留上一轮成功产物。
+- 校订版原声字幕使用逐窗口全不透明遮罩，避免与原片硬字幕重影；测量坐标拒绝不兼容的非底部 ASS 对齐。
+- voice reference 使用同一不可变快照完成转码和缓存标识，进程内重复调用不再继承上一次音色；CLI 与环境变量统一提前校验。
+- 长视频的遮罩滤镜超过安全命令长度时改用 ffmpeg filter script，避免 Windows `CreateProcess` 上限；measured band 统一为 `[top, bot)` 并成为视觉 QC 的真实安全区。
+- 测量产物提交失败会回滚整组旧产物；recap 通过显式 assemble 参数传递字幕坐标，不再污染进程环境。
+- 删除测试专用/生产不可达的 assemble、review、audio automation、QC rule-loader 兼容层；MiMo/其他 non-deterministic finding 不再有 allow-list 升级 blocker 的逃生口。每个 skill 的 `lib.py` / `brief.py` / `narration.py` 复制仍刻意保留，确保单独 clone/安装即可运行。
+
+### 性能
+
+- **不再重复哈希/解码/探测同一批字节。** `file_fingerprint` 按进程记忆化（内容寻址不变，仅用 dev/inode/size/mtime_ns 作记忆键）：一次理解流程原本要对源视频做 8–10 次全量 sha256、对整套抽帧做 2–3 遍，40 分钟视频约 2400 张全分辨率 JPEG。VLM 的逐帧 base64 缓存由无上界字典改为 LRU；续传缓存由每个场景整份重写改为按批落盘；TTS 响度归一从三遍纯 Python 遍历改为 `array('h')` 单遍（输出字节与元数据完全一致）；命中缓存的 TTS 段不再逐段 ffprobe；黑/白帧场景过滤按场景并行。
+
+### 构建
+
+- `pyproject.toml` 显式声明 ruff 规则集。CI 不固定 ruff 版本，而 0.16 起默认规则集被大幅扩展，会让无关 PR 的 lint 步骤失败。
+- `scripts/test.py` 将「未安装 pytest」与真实测试失败区分开。
+
+### 测试
+
+- 测试入口统一到跨平台 `scripts/test.py`；CI 中 frontmatter、manifest、prompt anchor 与隔离导入契约全部改为 pytest 行为/结构测试。
+- 合并重复测试并增加动态 skill 发现、精确重复测试体检测、测试组注册、自包含边界、创作 JSON 结构与 multi-source brief 回归覆盖。
+
+### 验证
+
+- 全套 `python3 scripts/test.py` 通过（801 tests）；`ruff`、`compileall`、修改模块 `mypy` clean；其中 assemble 275 tests 覆盖剪映草稿协议、timeline 迁移和便携资源写入。
+- 真实 ffmpeg 合成字幕样片验证：测量工具识别 `y=[613,637)`；遮罩像素在留白帧为 `128`、解说帧为 `51`。
+- 剪映专业版 `10.8.7-beta1` 实测：视频/解说/BGM/字幕/图片轨在线，预览、保存、关闭与重开正常。
+
+## [0.3.3] - 2026-06-28
+
+多源视频剪辑解说 + 文件系统素材库复用为主线，并合入跨 harness 支持、成片兼容性与竖屏字幕修复、解说评审硬闸等改进。
+
+### 新增
+
+- **多视频剪辑解说（cut 模式）。** 一次传入多个源视频，按 `source_id` 选取片段，剪成一个成片；项目级 `multi_source_manifest.json` 作为 recap / cut / assemble 的来源契约，`clip_plan.json` 每个片段带 `source_id`，重叠检测按源隔离。多视频 MVP 仅开放 `--edit-mode cut`。
+- **文件系统素材库复用。** `--material-library-dir` 搭配 `--save-materials` / `--use-materials`，把每个源视频的分析产物沉淀为 grep 友好的 `material.json` / `material.md` / 追加式 `materials_index.jsonl`，不复制原始媒体；按源指纹 + 设置指纹门控恢复，复用前清理旧 work dir 的残留产物。无 DB / embedding / 语义检索，纯文件系统 + `grep`。
+- **多源 provenance 透出。** `video-assemble` / `recap_inspect` 在时间线与剪映草稿中保留 `source_id` / `source_path`；个别源缺失时按片段降级并显式标记，保留其余在场源的来源，而非丢弃整条时间线。
+- **`video-understanding --brief-only`。** 从已恢复 / 缓存的分析产物重建 OUTPUT 时间轴 brief，不重跑抽帧 / ASR / VLM / 外部 API。
+- **跨 harness 支持 + Claude Code marketplace。** Codex 与 OpenClaw 直接读取 `.claude-plugin` 包，无需每 harness 文件；marketplace 命名为 `video-recap`。(#50)
+- **解说评审 scorecard + dub-lint 硬闸 + partial-TTS 可见性。** (#49)
+
+### 改进
+
+- **单视频 full / cut / dub 行为保持兼容。** 多视频仅在 cut 模式开放；单源剪辑滤镜图保持不变（字节级一致）。
+
+### 修复
+
+- **异源 concat 几何归一化。** 多源片段先归一到统一画布（scale / pad / setsar / fps / yuv420p）再 concat，分辨率 / SAR / 帧率不同的源视频不再让 ffmpeg 报错；不同分辨率的多视频可正常合成一个成片。
+- **多源音轨按源处理。** 个别无声源不再导致整段成片静音；每个片段都有音频（原声或合成静音）。
+- **密钥脱敏更精确。** 只脱敏凭证形态（`tp-` / `sk-` / `gh*_` / `AKIA` / JWT 与 `KEY=VALUE`）与凭证命名的 JSON key，不再误伤 transcript / summary 里的 `secret` / `token` 等普通词，也不再把多个 key 合并丢值。
+- **出片强制 `yuv420p` + faststart。** 微信 / 手机可播、边下边播。(#51)
+- **字幕样式按探测画布缩放。** 修复竖屏 (9:16) 字幕被拉伸。(#53)
+
+### 验证
+
+- 全套 `python3 scripts/test.py` 全部 skill groups passed（551 tests），`ruff` / `compileall` clean。
+- 新增真实 ffmpeg 多分辨率 + 混合音频渲染测试（验证异源 concat 与音轨归一化）；密钥脱敏保留正常词 / 不合并 key / 凭证形态测试；assemble 按片段降级（保留在场源 provenance）测试。
+
+## [0.3.2] - 2026-06-22
+
+让剪映草稿导出跟上新版工程结构，方便在剪映专业版里继续精修。
+
+### 新增
+
+- **新版剪映 schema-driven 草稿导出。** 剪映导出从单文件 JSON 拼装拆成 schema / model / builder / track / writer 分层，草稿基线升级到 `version: 360000`、`new_version: 111.0.0`、`app_version: 5.9.5-beta1`，并补齐包含 `common_mask` 在内的新版 `materials` skeleton。
+- **素材类型注册表与能力清单。** 明确区分已支持的 `video` / `audio` / `text` / `subtitle` / `speed`，以及预留但暂不写出的 image/sticker/effect/mask 等类别；未知或暂不支持类别会输出 note 并跳过，避免生成畸形草稿。
+
+### 改进
+
+- **剪映导出仍保持可选、懒加载、stdlib-only。** `export_jianying.py` 现在只是薄 facade，核心 ffmpeg 渲染路径不会导入任何 `jianying_*` 模块；`timeline.json` 仍是后端无关的 canonical input，ffmpeg 仍是最终成片判定标准。
+- **草稿写入更安全。** 写入器继续保留非空目录避让、媒体打包、路径重写、临时目录原子替换；并新增 `draft_name` 校验，拒绝空名、绝对路径、`..`、以及路径分隔符，防止错误名称逃逸草稿父目录。
+- **BGM 循环与音量自动化覆盖更完整。** 循环 BGM 会拆成多段铺满时间线，并把窗口内 `KFTypeVolume` 音量关键帧放到对应片段。
+
+### 验证
+
+- `ruff` / `py_compile` / `mypy --ignore-missing-imports` 覆盖剪映导出模块；相关 assemble/timeline 测试 84 passed，全项目 `scripts/test.py` 全部 skill groups passed。
+- 本机剪映专业版 `10.8.7` 实测：生成并打开 schema E2E 草稿；又把历史 `longvacation_2min_work/timeline.json` 转成 `recap_tmp_convert_longvacation_2min_20260623_003900`，剪映已登记并可打开。
+
+## [0.3.0] - 2026-06-20
+
+长视频更稳、跨语言更干净、剪辑更顺眼，并新增解说导航与成片压缩工具。
+
+### 新增
+
+- **VLM 场景分析可断点续传 + 限流自愈。** 长视频（数百场景）过去偶发 HTTP 429 会让整轮画面理解失败、再跑得从头重来。现在每个场景分析完即落盘（`vlm_scene_cache.json`，原子写），失败只重试缺失/失败的场景；遇到限流(429)的场景自动降到 ¼ 并发重试一次，持久性错误（空响应／解析失败）不重试。默认 8 并发不再拖垮长视频。
+- **跨语言解说降噪 `FOREIGN_SOURCE_AUDIO`。** 当原片语言与解说不同（如日剧配中文解说）时，解说下方被压低的原声本就听不懂、还会被当成「怪音」。该开关把解说下的原声压到近静音（0.05），而原声留白块仍保持满音量；显式 `SPEECH_DUCKING_VOLUME`／`ZONE_DUCKING_VOLUME` 仍可覆盖。
+- **剪辑边界吸附原片切镜头 `SCENE_CUT_SNAP`。** 片段边界若落在原片硬切点附近，会先闪一下相邻镜头再切，形成可见闪烁。新增一道吸附（在自然停顿吸附之后）：用 ffmpeg 在窄窗口里探测原片硬切并把边界移上去（每片段约 2 次轻量探测，复用现有缓存）；已对齐或附近无切点的边界不动，会把片段压到 ~0.5s 以下的吸附跳过。
+- **成片压缩参数 `OUTPUT_CRF` / `OUTPUT_PRESET` / `OUTPUT_MAX_HEIGHT`。** 最终混流过去硬编码 `-crf 18 -preset veryfast` 且从不缩放，成片体积偏大。现可调 CRF／preset／高度上限（缩放放在最后，遮挡与字幕先在原分辨率渲染再随帧缩小，更清晰）；默认仍是 18／veryfast／不缩放。demo：长假 2 分钟成片由 119MB 降到 16.9MB。
+- **解说导航工具（咨询性，不影响成片）。** 新增只读的 `inspect`（`state` 看流程进度／源视频指纹／下一处暂停；`clip-map` 在成片↔原片时间轴间精确换算，回答「成片 30–60s = 原片哪段」）与视频故事板（源时间轴 + 剪辑成片时间轴的缩略图总览，写作时扫一张图就能定位转场／反转，复用已抽帧不重抽）。任一缺失或异常都只降级提示、绝不阻断流程。
+
+### 变更
+
+- **手动评审自动按成片时间轴。** `review.py` 的 `--timeline` 默认改为 `auto`：检测到已验证的剪辑成片（`clip_plan_validated.json` + `edited_source.mp4`）就按成片时间轴评审，否则按原片。消除了 cut 模式下手动评审把原片时间当成成片、误报一堆「幻觉」的问题（demo 上 4 个假阳性 → 1 个真问题）。编排器显式传入的 `cut_output` 仍优先。
+- **ASR 默认分段 30→15s。** 时间戳最坏误差大致减半，并重新启用静音／ASR 交叉校验；代价是每个视频约 2× 顺序 ASR 调用（`ASR_SEGMENT_SECONDS` 可调）。
+- **自带字幕在不遮挡时也显示。** 原声留白字幕过去被绑在「遮挡原字幕(mask)」开关上，干净／外语片源（无烧录字幕、mask 关）会连同自带 `user_subtitles.*` 一起被丢掉。现解耦：有自带字幕文件即视为明确意图、在留白处照常显示（干净片源无重影风险）。与 `FOREIGN_SOURCE_AUDIO` 搭配适配「外语剧 + 自带中文字幕」。
+
+### 修复
+
+- **cut 模式 pass2 简报崩溃。** 被拆分的场景拿到字符串 id（如 `"5.0"`）、未拆分的仍是 int，`sorted(scene_ids)` 因 int／str 混排崩溃。改为类型安全排序键（int 在前、拆分串在后），并对字节孪生的 `brief.py`／`narration.py` 同步修改（md5 保持一致）。
+- **原声留白字幕滞后。** 粗粒度 ASR（按时钟分箱、按字符位置估时）会让某句晚显示约 6–8s。现「精确来源」与 ASR 兜底都改为按整句、从留白起点顺序排布，多句不再重叠或散到字符比例尾槽。
+- **成片压缩两处健壮性（发布前评审发现）。** 奇数 `OUTPUT_MAX_HEIGHT`（如 721）过去会产生奇数高度、被 libx264／yuv420p 拒绝 → 空成片 + 笼统报错；现强制宽高都为偶数。`OUTPUT_CRF=0`（无损，合法值）过去被当假值改成 18；现原样保留。
+- **inspect 测试接入 CI。** 新增的 inspect 测试组此前只写进 `scripts/test.sh`，而 CI 实际跑的是 `scripts/test.py`，导致这 22 个测试从未在 CI 运行；现已补进运行器。
+
+### 其他
+
+- demo 换成《悠长假日》第一集 2 分钟 cut 模式解说，集中展示本轮能力（无闪烁边界、跨语言降噪、自带中文字幕留白、CRF24/720p 压缩）；并更新 README 中的 demo 链接。
+
+## [0.2.3] - 2026-06-19
+
+一轮成片质量打磨：原声留白字幕更准（可自带字幕）、画面理解更密、解说去掉破折号、评审更稳。
+
+### 新增
+
+- **自带原声字幕（更准）。** 解说留白处的原声字幕，除了 Agent 校对、ASR 兜底之外，现在可以直接放一份准确的字幕文件作为**首选来源**：`work_dir/user_subtitles.json`（`[{start,end,text}]`，默认按成片时间轴；或写成 `{"timeline":"source","lines":[...]}` 用原片时间轴，按剪辑计划自动映射到成片）或 `user_subtitles.srt` / `.ass`（默认按原片时间轴映射）。优先级：自带字幕 › Agent 校对的 `original_subtitles.json` › ASR 兜底。
+- **逐帧采样随场景时长伸缩。** VLM 每个场景的取帧数过去硬上限 6 帧，长场景（合并后可达上百秒）只能 1 帧／约 20 秒，`frame_facts` 严重稀疏。现按场景时长伸缩（约每 `VLM_SECONDS_PER_FRAME`=4 秒一帧，下限 3、上限 `VLM_MAX_FRAMES`=16），长场景的画面理解不再被饿死；VLM `max_tokens` 800→1500（`VLM_MAX_TOKENS`）。
+- **MiMo 视频概览可作主理解来源。** 开启视频概览（`--mimo-video-overview` / `MIMO_VIDEO_OVERVIEW=1`）时，它会成为每个场景的**主要描述**（带动态、读得懂剧情），逐帧 `frame_facts` 仍保留作锚点与兜底；因为不动 `frame_facts`，substrate 评级不会因此回退。概览仍是可选项（默认关闭）。
+
+### 变更
+
+- **解说不再用破折号。** 破折号烧进字幕里很突兀：写作规则禁止在解说与 `original_subtitles.json` 里用破折号（——／—），渲染时再做一道归一化（替换为逗号）兜底；只改字幕显示，不动 TTS 朗读文本。
+- **解说评审更确定、只对硬伤拦。** 评委固定 `temperature=0`+种子，复跑结论一致；只有 `hallucination`／`incomplete`（事实类）能在严格模式拦截，文笔类意见（钩子弱、念画面、套话等）一律降为提示；评审规则承认 `background_research` 与画面、对白并列为有效依据，不再把有据可查的设定误判成幻觉。
+- **覆盖率指标按写作预算同速率计。** 解说覆盖率过去用 4.55 字／秒打分、却用 3.87 字／秒给 Agent 配额，比自己的预算还严约 18%，容易误报「讲得太少」。现统一用 3.87（含 `speech_safety_margin`）；并把几个覆盖率阈值提升为真正的 CONFIG 项。
+- **ASR 人名按背景资料纠错。** 转写后用 `background_research.json` 里的人名修正单字同音错误（如 叶青眉→叶轻眉），严格限定「恰好一字之差、且窗口本身不是已知人名」，避免误改。
+- **视频概览部分被审核拦截时降级。** 概览分片若部分被内容审核拦截，不再整体中止理解，而是用可用分片降级产出、未覆盖场景回退到逐帧描述；概览取帧帧率 `mimo_video_fps` 2→3。
+
+### 修复
+
+- **原声留白字幕与原声对不上。** 字幕时间过去依赖粗粒度 ASR（按块时间戳、中点估时），偶尔和原声对不上。现在「精确来源」（自带字幕／Agent 校对稿）按句**区间裁剪**精确落到所覆盖的留白：跨解说块的句子按时间比例切成各段、不再整句重复出现；过密的行截断显示而非直接丢成空白。
+
+## [0.2.2] - 2026-06-18
+
+让分块解说的成片更连贯、更好看：给原声留白补上**校对过**的字幕、解说与原声自然衔接、剪辑不再切断台词；并把会到最后才炸的失败提前暴露。
+
+### 新增
+
+- **原声留白也烧字幕了。** 解说块之间留给原声的留白，过去字幕是空的（解说字幕只写解说，原片自带字幕又被遮挡）。现在这些留白会烧上**原声台词字幕**，并用 `「」` 与解说区分开。优先采用 Agent 校对过的 `original_subtitles.json`（OUTPUT 时间轴 `[{start,end,text}]`：订正 ASR 错字与人名、只保留留白里真正出声的台词）；没有该文件时退回保守的 ASR 兜底——按句归到它所在的那一段留白、跳过太密读不完的行（`SUBTITLE_ORIGINAL_IN_GAPS`，默认开；cut 模式按剪辑计划把 ASR 从源时间映射到成片时间）。
+- **剪辑不再切断一句台词（cut 模式）。** `video-cut` 会把每个片段的结尾向后吸附到最近的自然停顿（依据 `silence_periods.json`，上限 `CLIP_SNAP_MAX_EXTEND`，默认 2 秒；`SNAP_CLIP_LINE_END` 可开关），让原声把话说完；选片 brief 也提示 Agent 在完整句尾收口。
+- **字幕烧录预检（快速失败）。** 烧字幕需要带 libass（`subtitles` 滤镜）的 ffmpeg。编排器在整条流程开跑前就检查，缺失即报错并给出处置（装一个带 libass 的 ffmpeg，或加 `--no-burn-subtitles`），不再跑完理解 / VLM / ASR / TTS、到最后渲染才失败；`video-assemble` 单独运行时同样有此预检。
+- **成片时直接给出解说评审入口。** 存在 `narration_review.md` 时，编排器收尾会打印它的结论与路径，把内容风险（钩子弱 / 没主线 / 节奏）摆到眼前——仍是建议性，硬门禁只有 `validate.py`。
+
+### 变更
+
+- **解说块与原声自然衔接。** brief、写作规则和评审一起教会 Agent：原声留白前的那一块要把原声**引出来**，留白后的那一块要**接住**原声刚呈现的内容，让解说和它包裹的原声读成一个连贯的 beat，而不是各说各的（评审新增 `disjoint_handoff` 类别）。
+
+### 修复
+
+- **原声字幕过度渲染 / 与解说混在一起。** 早先的实现会把一整段（多句）ASR 文本塞进一小段留白、还在多段留白里重复出现，渲染出根本没说出口的台词。现在按句归属到单段留白、跳过过密的行、并用 `「」` 与解说分隔；最佳效果由 Agent 校对的 `original_subtitles.json` 提供。
+- **文档：字幕烧录默认开启。** 两份 README 与 SKILL.md 原先把烧字幕写成需要 `--burn-subtitles` 才开，实际是默认开（用 `--no-burn-subtitles` 关闭）；已更正措辞。
+
+## [0.2.1] - 2026-06-17
+
+A delivery-quality release: narration now plays in blocks with the original audio breathing
+between them at full volume, and the burned-in subtitle band no longer compresses the picture.
+
+### Changed
+
+- **Narration is delivered in BLOCKS, ~7:3.** Each beat is a few sentences written as one
+  continuous thought and synthesized as a single fluent TTS utterance — fixing the choppy,
+  sentence-by-sentence delivery. Between blocks the recap leaves deliberate original-audio
+  blocks (~30% of the timeline) where the original scene plays at FULL volume.
+- **Original-audio blocks play at full volume.** `idle_orig_volume` now defaults to `1.0` and
+  `duck_bridge_seconds` to `1.5` (was `12`), so the original is ducked only under a narration
+  block and swells back to full in the gaps, instead of sitting under one permanent low bed.
+  This reverses the 0.2.0 "continuous bed" default. Tune with `IDLE_ORIG_VOLUME` /
+  `DUCK_BRIDGE_SECONDS`.
+- **Burned-in subtitles are split into short one-line chunks** timed karaoke-style across each
+  block, and the source-subtitle masking band is sized for ONE line (~14% of height) instead of
+  two (~23%) — the black band no longer compresses the picture.
+- **The brief and lint steer block authoring.** The agent is told to write blocks and leave
+  ~30% original-audio gaps; the per-sentence density lint is replaced by a block-coverage lint
+  (`no_original_blocks` / `under_narrated` / `no_original_breaks` / `fragmented_beats`), and the
+  block count is derived from coverage instead of beats-per-minute.
+
+### Fixed
+
+- **Blocks are no longer truncated by the speed-up.** `voiceover` sized a segment's text against
+  the raw TTS duration, ignoring the `narration_speed` (1.3×) atempo that assemble applies before
+  placement — so a correctly-budgeted block was clipped into a fragment. The truncation budget now
+  accounts for `narration_speed`.
+
+## [0.2.0] - 2026-06-16
+
+A quality-focused release that re-architects cut mode and the narration mix so the
+recap feels like a recap, not captions over a clip.
+
+### Changed
+
+- **Cut mode is now cut-first / narrate-second (two pauses).** The orchestrator renders
+  `edited_source.mp4` from `clip_plan.json` first, then asks the agent to write
+  `narration.json` against that real output timeline. Narration and picture stay in sync
+  by construction — the old source→output remap that could silently drop or clamp beats is
+  gone. Full mode is unchanged (single pause).
+- **Continuous original-audio bed.** The original is ducked into one continuous low bed
+  under the narration instead of swelling back up between sentences. Inter-beat gaps shorter
+  than `duck_bridge_seconds` (default 12s, just above the max narration gap) stay ducked;
+  only the lead-in and lead-out return to full volume. Tune with `DUCK_BRIDGE_SECONDS`.
+- **Narration density is a guide, not a quota.** The brief frames beats/min as a target to
+  aim for, explicitly telling the agent never to pad with filler or pixel-description to hit
+  a number — fewer "cold", caption-like recaps.
+- **`--consolidate` story index is on by default**, with a backward-compatible manifest shim
+  so existing `work_dir`s still resume. Use `--no-consolidate` to opt out.
+- **Research directive only fires when the substrate is thin/empty** (not on every titled
+  run), and the orchestrator surfaces a research hint in the pause banner.
+
+### Added
+
+- **Cut-desync floor:** narration is linted against the normalized clip plan, with a blocking
+  preflight that fails before TTS on heavy drop / too-sparse / long-gap output; `--allow-sparse-cut`
+  ships an intentional montage anyway.
+- **Phase ledger (`recap_phase.json`)** for deterministic cut-mode resume; a stale narration
+  from a changed `clip_plan` can no longer resume into TTS.
+- **`duck_bridge_seconds`** config knob (env `DUCK_BRIDGE_SECONDS`).
+
+### Fixed
+
+- **Long-video understanding rides out MiMo cluster rate limits.** A full episode fans out
+  into ~90 ASR + ~185 VLM calls; the MiMo endpoints now retry up to 10× with a 60s backoff
+  cap (plus a 10s floor when the server sends no `Retry-After`), and an optional
+  `ASR_THROTTLE_SECONDS` spaces sequential ASR — so a transient 429 no longer aborts the run.
+- **Resume cannot reuse stale artifacts.** Cached-artifact reuse now proves it matches the
+  current source bytes / settings and rejects stale provenance, so a changed input or config
+  can no longer silently resume on an out-of-date intermediate.
+
+## [0.1.0]
+
+- Initial release: turn any video into a Chinese-narration recap on `ffmpeg` + one Xiaomi
+  MiMo API key. Five independent skills (understanding, script, cut, voiceover, assemble)
+  plus a thin orchestrator; optional 剪映 draft export.
+
+[Unreleased]: https://github.com/zenstory-ai/video-recap-skills/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/zenstory-ai/video-recap-skills/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/zenstory-ai/video-recap-skills/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/zenstory-ai/video-recap-skills/compare/v0.3.1...v0.3.2
+[0.3.0]: https://github.com/zenstory-ai/video-recap-skills/compare/v0.2.3...v0.3.0
+[0.2.3]: https://github.com/zenstory-ai/video-recap-skills/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/zenstory-ai/video-recap-skills/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/zenstory-ai/video-recap-skills/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/zenstory-ai/video-recap-skills/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/zenstory-ai/video-recap-skills/releases/tag/v0.1.0

package/lib/video-recap/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PiteChen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/video-recap/README.en.md

@@ -0,0 +1,257 @@
+# video-recap-skills
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-purple)
+![Powered by Xiaomi MiMo](https://img.shields.io/badge/AI-Xiaomi%20MiMo-green)
+![Fish Audio TTS](https://img.shields.io/badge/TTS-Fish%20Audio-blue)
+
+[中文](README.md) · English
+
+**In Claude Code, Codex CLI, OpenCode, or OpenClaw, one natural-language request turns a video into a Chinese-narration recap.** It needs only Python, `ffmpeg`, and one Xiaomi MiMo API key locally; TTS can optionally use Fish Audio. No GPU or model downloads are required, and it runs on macOS / Linux / Windows.
+
+## Demo
+
+<video src="https://github.com/user-attachments/assets/f3c2df0c-6869-4f5b-8f4c-cce70b58b667" width="640" controls></video>
+
+[Explore the complete 60-second *Guohuo (这一秒过火)* Skill project, Remotion overlay source, and content audit](examples/guohuo-60s/)
+
+The case study covers the core cut, picture/audio lock, packaging exploration, viewing feedback, scoped conform/re-cut, and frozen-set verification. It also demonstrates multi-episode selects, source-audio/narration ownership, Fish Audio voiceover with TTS-aligned captions, and repairing distracting joins by restoring continuous source motion. No copyrighted episode footage, audio, or rendered video is stored in the repository.
+
+Beyond the rendered MP4, you can export a **剪映/JianYing draft** to keep editing by hand, with original clips, narration, BGM, and subtitles:
+
+<img alt="Exported 剪映 draft: original clips, narration, BGM, and subtitles" src="docs/jianying-export.png" width="100%">
+
+## What it is
+
+```mermaid
+flowchart LR
+    video(["Video"]) --> understand["① Understand<br/>scenes · ASR · VLM"]
+    research["Story research · optional"] -.-> understand
+    understand --> script["② Direct · Edit · Script<br/>agent"] --> voiceover["③ Voiceover<br/>MiMo / Fish Audio"] --> assemble["④ Assemble<br/>mux · subtitles"] --> output(["Recap"])
+    understand -. cut mode · cut first .-> cut["Cut<br/>render first"] -.-> script
+    classDef io fill:#4f86c6,stroke:#3a6298,color:#fff;
+    classDef stage fill:#eef6ff,stroke:#4f86c6,color:#1f2937;
+    classDef opt fill:#f3f4f6,stroke:#9ca3af,color:#475569;
+    class video,output io;
+    class understand,script,voiceover,assemble stage;
+    class research,cut opt;
+```
+
+## Why use it
+
+- **One key, runs anywhere.** ASR, VLM, and TTS all go through [Xiaomi MiMo](https://platform.xiaomimimo.com); the local runtime uses only Python's standard library and `ffmpeg`, with no `pip install`.
+- **Optional Fish Audio TTS.** Select `--tts-provider fish-audio` to use Fish Audio. Its current `s2.1-pro-free` model is useful for development, evaluation, and non-SLA workloads while the existing MiMo path remains the default.
+- **Research when it matters.** When the title/story context is known or the brief notes the material is thin, put character relationships and plot background in `background_research.json` so the VLM knows who's who.
+- **Make the editorial decision before allocating sound.** The agent first compares edit hypotheses and locks the POV, story spine, exact picture moments, and original-audio anchors. Narration is voiced as a block only when it has a defined job; strong dialogue, action sound, or silence may own an entire beat. A 7:3 split is only a rough fallback, never a quota.
+- **Cut first, frames aligned.** Cut mode renders the shortened video first, then writes narration against that output timeline, so picture and voice stay in sync.
+- **Multi-video cut, reusable analysis.** Feed several videos at once, pick ranges by `source_id`, and render one recap; each video's analysis is saved to a filesystem material library you can `grep` and reuse next time.
+- **Keep editing in 剪映.** Optionally export a schema-driven draft with editable original clips, narration, BGM, subtitles, and local image overlays. Video/audio/images are bundled under `Resources/local` with a material index, so a clone or moved draft stays usable. ffmpeg remains the canonical render.
+- **Optional MiMo adviser, never a gatekeeper.** On request, MiMo can review the project before assembly or after rendering. Missing keys, rate limits, timeouts, and malformed model output are warnings only, never blockers or automatic edits.
+
+## Installation
+
+### 1. Shared prerequisites
+
+- Python 3.10+
+- `ffmpeg` on `PATH`; subtitle burn-in is enabled by default and requires libass / the `subtitles` filter
+- One [Xiaomi MiMo](https://platform.xiaomimimo.com) API key for ASR, VLM, and the default TTS path
+
+```bash
+brew install ffmpeg                         # macOS
+sudo apt install ffmpeg                    # Debian / Ubuntu
+choco install ffmpeg                       # Windows; scoop or winget also work
+
+export MIMO_API_KEY=your-mimo-key          # macOS / Linux
+export MIMO_TOKEN_PLAN_CLUSTER=cn          # optional for tp-* keys: cn | sgp | ams
+```
+
+In Windows PowerShell, use `$env:MIMO_API_KEY="your-mimo-key"`. MiMo does not require a subscription: `sk-*` keys can use pay-as-you-go billing. In one complete-video run measured for this project, usage cost about CNY 1.3; actual cost varies with video length and request volume. Pay-as-you-go keys default to `https://api.xiaomimimo.com/v1`.
+
+To use the currently free Fish Audio TTS path:
+
+```bash
+export TTS_PROVIDER=fish-audio
+export FISH_API_KEY=your-fish-key
+export FISH_TTS_REFERENCE_ID=your-voice-model-id  # optional; overrides the built-in “娱乐扒妹” voice
+```
+
+The default Fish model is `s2.1-pro-free`, with the built-in “娱乐扒妹” narration voice (reference ID `5653cea4ac83480aaf2bf45406556185`). Set `FISH_TTS_REFERENCE_ID` to override it. [Fish Audio currently states](https://fish.audio/blog/s2-1-pro-free-api/?articleLocale=en) that free access runs through **2026-08-31**, subject to its Fair Use Policy and without an SLA; check its current policy after that date. See the [config playbook](skills/video-recap/references/config-playbook.md) for model, voice, loudness, subtitle, and per-capability settings.
+
+### 2. Choose an agent host
+
+#### Claude Code
+
+Run inside Claude Code:
+
+```text
+/plugin marketplace add zenstory-ai/video-recap-skills
+/plugin install video-recap-skills@video-recap
+```
+
+Or simply ask:
+
+```text
+Install this plugin: https://github.com/zenstory-ai/video-recap-skills
+```
+
+#### Codex CLI
+
+```bash
+codex plugin marketplace add zenstory-ai/video-recap-skills
+codex plugin add video-recap-skills@video-recap
+```
+
+For a local checkout, replace the marketplace source in the first command with its directory. This flow was smoke-tested with an isolated `CODEX_HOME` on Codex CLI `0.144.1`.
+
+#### OpenCode
+
+The official [OpenCode Agent Skills documentation](https://opencode.ai/docs/skills/) defines project skills under `.opencode/skills/<name>/SKILL.md`. Clone the repository and start OpenCode from that directory:
+
+```bash
+git clone https://github.com/zenstory-ai/video-recap-skills.git
+cd video-recap-skills
+mkdir -p .opencode
+ln -s ../skills .opencode/skills             # macOS / Linux
+opencode debug skill
+```
+
+On Windows, copy `skills\*` into `.opencode\skills\`. This PR was run-verified on OpenCode `1.14.32`: `opencode debug skill` discovered all 6 skills. Use `video-recap` for normal end-to-end production, `video-script` for planning or writing only, and the other four skills as tool stages.
+
+#### OpenClaw
+
+After cloning, import the Claude plugin bundle and check the discovered skills:
+
+```bash
+openclaw plugins install ./video-recap-skills
+openclaw skills list
+```
+
+Do not register the same checkout through multiple discovery paths; duplicate registration can cause name collisions or repeated triggers.
+
+After installation, ask the agent to check the environment:
+
+```text
+Check the video-recap environment and tell me whether Python, ffmpeg/libass, and MiMo are ready.
+```
+
+## Usage
+
+Give the agent the video paths, desired result, and any useful story context. Users do not need to run the repository's Python scripts directly.
+
+**Full-video recap:**
+
+```text
+Make a Chinese-narration recap of /path/to/video.mp4. It is episode 1 of 庆余年, the lead is 范闲, and subtitles should be burned in.
+```
+
+**Cut a long video into a shorter recap:**
+
+```text
+Turn /path/to/long.mp4 into a roughly ten-minute recap while preserving key original dialogue and character reactions.
+```
+
+**Build one story from multiple videos:**
+
+```text
+Use /path/to/ep1.mp4 and /path/to/ep2.mp4 to make one ten-minute recap with a shared story spine, not two separate summaries.
+```
+
+The agent handles understanding, story and audiovisual planning, editing, narration, voiceover, and assembly. In cut mode it first chooses footage, renders the shortened video, and only then writes narration on the output timeline; the agent also handles the internal pauses and resume steps.
+
+## Common advanced requests
+
+**Reuse previously analyzed material:**
+
+```text
+Analyze /path/to/ep1.mp4 and save reusable understanding artifacts under /path/to/.video-materials. Prefer that material library in later projects.
+```
+
+The library contains JSON, Markdown, and an index only. It does not copy raw media, create a database, or use embeddings; the agent searches it directly on the filesystem.
+
+**Add advisory quality review and export a JianYing draft:**
+
+```text
+Make a recap of /path/to/video.mp4, run MiMo quality review before assembly and after rendering, and export an editable JianYing draft.
+```
+
+MiMo review is always advisory: at most one request per selected stage, fail-open, and never an automatic edit or render blocker.
+
+**Align new subtitles with the source's burned-in subtitle band:**
+
+```text
+Detect the source subtitle band in /path/to/video.mp4 and let me confirm the preview before rendering recap subtitles in the same region.
+```
+
+The measurement preview is stored under `.subtitle_measure/`. It currently requires square-pixel video and bottom-aligned source subtitles. This capability is adapted from [ops120/video-recap-skills-plus](https://github.com/ops120/video-recap-skills-plus).
+
+**Clone an authorized reference voice:**
+
+```text
+Use the voice from /path/to/voice-ref.wav for the recap of /path/to/video.mp4. I have the voice owner's authorization.
+```
+
+The reference audio is sent to MiMo for synthesis and its content fingerprint participates in cache validation. Use voice cloning only with the voice owner's authorization.
+
+**Use the currently free Fish Audio voiceover path:**
+
+```text
+Use Fish Audio for the Chinese narration of /path/to/video.mp4 with the built-in “娱乐扒妹” voice.
+```
+
+The agent passes `--tts-provider fish-audio` to the orchestrator. `FISH_API_KEY` is required; the built-in “娱乐扒妹” voice is used unless `FISH_TTS_REFERENCE_ID` overrides it. Local `--voice-ref` cloning remains specific to MiMo.
+
+**Dub an English video into Chinese while preserving the voice:**
+
+```text
+Dub /path/to/english.mp4 into Chinese, keeping the original speaker's voice.
+```
+
+This replaces the original speech instead of overlaying commentary. The current version supports one speaker and full-track replacement without background-music separation.
+
+## Architecture
+
+| Skill | Does | In → Out (the `work_dir` contract) |
+|---|---|---|
+| **video-understanding** | scene detect · frame extract · ASR (`mimo-v2.5-asr`) · VLM (`mimo-v2.5`) · fuse timeline · build brief | `video` → `scenes / asr_result / vlm_analysis / silence_periods / timeline_fusion / agent_narration_brief.md` |
+| **video-script** | directing/story/picture/audio plan + narration + advisory review + lint/validate | `brief + index` → `recap_story_plan.json + visual_audio_board.json + [clip_plan.json] + narration.json` |
+| **video-cut** | clip plan → render the cut (cut-first/narrate-second; narration is written on the output timeline, no remap) | `clip_plan.json + video` → `edited_source.mp4` |
+| **video-voiceover** | synthesize narration audio (MiMo `mimo-v2.5-tts` / Fish Audio `s2.1-pro-free`) | `narration.json` → `tts_segments/ + tts_meta.json` |
+| **video-assemble** | mux · duck original audio · render subtitles · multi-track timeline (optional 剪映 export) | `video + tts_meta` → `recap_<name>.mp4 + subtitles.srt/.ass + timeline.json` |
+| **video-recap** | orchestration and environment diagnostics | `video` → `recap_<name>.mp4` |
+
+## Output
+
+- `recap_<name>.mp4`: the final recap, written to a stable name; subtitles are burned in by default and also written as `subtitles.srt` and `subtitles.ass`
+- `work_dir/narration.json`: the narration script (`narration_lint.json` timing diagnostics, `narration_review.md` review notes)
+- `work_dir/recap_story_plan.json` · `visual_audio_board.json`: agent-authored story, picture, and audio decisions for resume/advisory review; not a render gate
+- `work_dir/agent_narration_brief.md`: timing and scene brief for the agent
+- `work_dir/vlm_analysis.json` · `asr_result.json` · `silence_periods.json` · `timeline_fusion.json`: understanding artifacts
+- `work_dir/clip_plan.json` · `edited_source.mp4` · `recap_phase.json`: cut-mode artifacts (narration is written on the output timeline; `recap_phase.json` records cut/narrate progress for deterministic resume)
+- `work_dir/multi_source_manifest.json` · `work_dir/sources/<source_id>/`: multi-video cut source manifest and per-source analysis artifacts
+- `<material-library-dir>/materials/<material_id>/material.json|material.md` · `materials_index.jsonl`: optional grep-friendly material library for reusing analyzed sources
+- `work_dir/timeline.json` · `work_dir/assembly_manifest.json` · `tts_segments/` · `tts_meta.json`: multi-track timeline, slim render record, and TTS audio
+- `work_dir/mimo_qc.json`: optional aggregated pre-assemble/post-render MiMo advice; never a gate
+
+## Bring your own original-dialogue subtitles (optional, more accurate)
+
+During the original-audio gaps between narration blocks, the original dialogue is burned as a subtitle (wrapped in `「」` to set it apart from narration). By default that text is agent-proofread with an ASR fallback — but ASR timing is coarse and can drift from the audio. For accurate timing, drop a subtitle file into `work_dir`; it becomes the **preferred source**:
+
+- `work_dir/user_subtitles.json`: `[{"start": s, "end": s, "text": "line"}]` on the **output** timeline, used as-is; or wrap it as `{"timeline": "source", "lines": [...]}` to give **source**-timeline subs that are auto-mapped onto the cut via the clip plan.
+- `work_dir/user_subtitles.srt` / `.ass`: parsed as **source**-timeline by default and mapped onto the cut.
+
+Priority: **your file › the agent-proofread `original_subtitles.json` › ASR fallback**. When the source is accurate, each line is clipped precisely into its gap instead of being placed by a coarse midpoint estimate.
+
+## References
+
+- Per-skill contracts: each `skills/<skill>/SKILL.md` (the writing rules are in video-script's SKILL.md)
+- [Data schema](skills/video-recap/references/data-schema.md) · [Config playbook](skills/video-recap/references/config-playbook.md) · [Multi-track timeline / 剪映 export](skills/video-recap/references/timeline-and-jianying.md)
+- [Background research guide](skills/video-recap/references/research-guide.md) · [VLM prompt templates](skills/video-understanding/references/prompt-templates.md)
+
+## Acknowledgements
+
+- [linux.do](https://linux.do)
+- The 剪映 draft protocol references [pyJianYingDraft](https://github.com/GuanYixuan/pyJianYingDraft), [capcut-mate](https://github.com/Hommy-master/capcut-mate), and [duo-video](https://github.com/duoec/duo-video).
+
+## License
+
+MIT, see [LICENSE](LICENSE).