@oh-story/dsh 0.1.14 → 0.1.16

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

@@ -1,5 +1,3 @@
-<!-- Last synced with README.md: 2026-09-20 -->
-
 <p align="center">
   <img src="https://zenstory.ai/brand/zenstory-ai-mark.svg" alt="" width="76" height="76">
 </p>
@@ -23,7 +21,7 @@
 <p align="center">
   <a href="https://github.com/zenstory-ai/video-recap-skills/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/zenstory-ai/video-recap-skills?style=flat-square&color=22D3EE&logo=github&logoColor=white&label=Stars"></a>
   <a href="https://github.com/zenstory-ai/video-recap-skills/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/zenstory-ai/video-recap-skills?style=flat-square&color=081431&label=Release"></a>
-  <img alt="Skills 6" src="https://img.shields.io/badge/Skills-6-081431?style=flat-square">
+  <img alt="Skills 7" src="https://img.shields.io/badge/Skills-7-081431?style=flat-square">
   <a href="https://www.python.org/"><img alt="Python 3.10%2B" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white"></a>
   <a href="https://github.com/zenstory-ai/video-recap-skills/actions/workflows/skill-validate.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/zenstory-ai/video-recap-skills/skill-validate.yml?style=flat-square&label=CI"></a>
   <a href="https://platform.xiaomimimo.com"><img alt="AI Xiaomi%20MiMo" src="https://img.shields.io/badge/AI-Xiaomi%20MiMo-34A853?style=flat-square"></a>
@@ -43,16 +41,16 @@ The 59-second landscape recap above, *Guohuo (这一秒过火)*, is the final de
 Seven skills (six for production plus one on-demand reference skill) install into Claude Code, Codex CLI, OpenCode, or OpenClaw. You give the video paths and the recap you want in plain language; the agent understands picture and dialogue, decides the story and audiovisual plan, cuts, writes, voices, mixes, and subtitles. Supported inputs: `.mp4 / .mov / .mkv / .webm`.
 
 - **One key, ffmpeg locally.** ASR, VLM, and TTS all go through [Xiaomi MiMo](https://platform.xiaomimimo.com); the local runtime is Python's standard library plus `ffmpeg`, with no GPU, no `pip install`, and no model downloads. Voiceover can switch to Fish Audio, which replaces only that stage.
-- **The editorial decision comes before the sound allocation.** The agent compares edit hypotheses first, writes the viewer promise, POV, dramatic question, and change-based beats into `recap_story_plan.json`, then assigns each beat a picture job and an audio owner: narration is voiced as a block only when it has a defined job, and strong dialogue, action sound, or silence may own an entire beat.
-- **Cut first, narrate second, so the timeline is aligned by construction.** Cut mode renders the shortened video first and writes narration against that output timeline; feed several videos at once and pick ranges by `source_id` to cut one story spine; each video's analysis is saved to a filesystem material library for reuse.
+- **The editorial decision comes before the sound allocation.** For a new concept, the agent compares viable edit directions; for a directed task or viewing feedback, it follows the current decisions. It records the viewer promise, POV, dramatic question, and change-based beats in `recap_story_plan.json`, then assigns each beat a picture job and an audio owner: narration is voiced as a block only when it has a defined job, and strong dialogue, action sound, or silence may own an entire beat.
+- **Cut first, narrate second, so the timeline is aligned by construction.** Cut mode renders the shortened video first and writes narration against that output timeline; feed several videos at once and pick ranges by `source_id` to cut one story spine; analysis can be saved to a filesystem material library and reused when the source and settings match.
 - **Keep editing after the render.** The multi-track `timeline.json` exports to a JianYing draft with editable source clips, narration, BGM, subtitles, and image overlays; drop in an accurate subtitle file and it becomes the preferred source for original-dialogue captions.
-- **Every step leaves a record you can check.** Narration lint, assembly QC, delivery QC, and the revision log are machine-readable files.
+- **Every step leaves a record you can check.** Narration lint, assembly QC, and final QC produce machine-readable reports. Viewing revisions can separately record changes, frozen items, and verification.
 
 ## Install
 
 ### ClawHub
 
-ClawHub distribution is governed by the repository's [explicit publish inventory](.clawhub/publish.json), with discovery through [ClawHub](https://clawhub.ai/). A skill-specific link is added here only after its publisher, version, and anonymous accessibility are verified, so this README never presents a nonexistent listing as live.
+ClawHub entries and dependencies are governed by the [explicit publish inventory](.clawhub/publish.json). The `video-recap` orchestrator remains `blocked` pending verification of companion installation under one skills root. For the complete workflow, install the plugin bundle or source checkout below.
 
 
 Prerequisites: Python 3.10 or newer, `ffmpeg` on `PATH`, and one [Xiaomi MiMo](https://platform.xiaomimimo.com) API key. Subtitles are burned in by default, which needs an ffmpeg with libass. Homebrew's stock `ffmpeg` has no libass: the default run then skips the burn, ships a same-name `.srt` sidecar next to the recap, and records a warning in `final_qc.json` (an explicit `--burn-subtitles` stops before the run starts instead). Narration that adds on-screen text overlays (`visual_overlays`) also needs an ffmpeg with drawtext, and stops before voiceover without it. To burn subtitles on macOS, use `brew install ffmpeg-full` (keg-only: put its `bin` first on `PATH`).
@@ -329,7 +327,7 @@ Use /path/to/ep1.mp4 and /path/to/ep2.mp4 to make one ten-minute recap with a sh
 
 > I have permission to use 〈local video〉 and am supplying checked picture and dialogue records for it. Propose only the sound handoff for this material: which full dialogue line, action sound or pause to preserve, where narration is needed, and which record supports each choice. List missing evidence rather than inventing motives or unseen events. Return beat notes and necessary narration drafts without calling TTS or rendering.
 
-The agent handles understanding, story and audiovisual planning, cutting, scripting, voiceover, and assembly. In cut mode it first chooses the footage, renders the shortened video, and only then writes narration on the output timeline; the internal pauses and resumes are the agent's job too.
+For a complete production request, the agent handles understanding, story and audiovisual planning, cutting, scripting, voiceover, and assembly. A text-only handoff stops at the requested scope. In cut mode it first chooses the footage, renders the shortened video, and only then writes narration on the output timeline; the internal pauses and resumes are the agent's job too.
 
 ## Workflow and the seven skills
 
@@ -408,7 +406,7 @@ Use /path/to/library as the resource library: register this BGM, this font and t
 template for 1080x1920 for me to adopt, then render this series with /path/to/series/recap_project.json binding them.
 ```
 
-Resources, templates and sample films are JSON records in your own directory; licence and "adopted" status are only ever set by you. A binding that conflicts with an explicit setting, or a template whose canvas differs from the output, stops the run before voicing. Each render gets a `resource_lock.json` listing what it actually used and whether the licences are clear. Format: [resource library, templates and samples](skills/video-recap/references/resource-library.md).
+Resources, templates and sample films are JSON records in your own directory; licence and "adopted" status are only ever set by you. A binding that conflicts with an explicit setting, or a template whose canvas differs from the output, stops the run before voicing. Each run writes `work_dir/resource_lock.json`, listing what it actually used and whether the licences are clear. Format: [resource library, templates and samples](skills/video-recap/references/resource-library.md).
 
 **Browse projects, runs and the library in a local page (read-only):**
 
@@ -432,7 +430,7 @@ Yes. Understanding relies on the VLM reading the picture and does not require ex
 
 ### A long video hit a 429 or was interrupted halfway. Do I start over?
 
-No. VLM scene analysis resumes from where it stopped and recovers from rate limits; once `narration.json` is written, repeating the same command continues, cut mode records in `recap_phase.json` which clip plan the narration was written for (changing the plan asks for a new narration), and a resume only continues a work directory for the same source video and parameters.
+VLM analysis saves completed scenes and retries suspected rate limits once with lower concurrency. Persistent failures remain visible. After addressing the cause, repeat the same command to reuse matching scene caches and continue. Use the original command after writing `narration.json` too. In cut mode, `recap_phase.json` binds narration to its clip plan; a changed plan requires checking or rewriting the narration. Resuming requires the same source video and parameters.
 
 ### The VLM can't tell who is who and the narration is all "a man in black"?
 

package/lib/video-recap/README.md

@@ -21,7 +21,7 @@
 <p align="center">
   <a href="https://github.com/zenstory-ai/video-recap-skills/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/zenstory-ai/video-recap-skills?style=flat-square&color=22D3EE&logo=github&logoColor=white&label=Stars"></a>
   <a href="https://github.com/zenstory-ai/video-recap-skills/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/zenstory-ai/video-recap-skills?style=flat-square&color=081431&label=Release"></a>
-  <img alt="Skills 6" src="https://img.shields.io/badge/Skills-6-081431?style=flat-square">
+  <img alt="Skills 7" src="https://img.shields.io/badge/Skills-7-081431?style=flat-square">
   <a href="https://www.python.org/"><img alt="Python 3.10%2B" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white"></a>
   <a href="https://github.com/zenstory-ai/video-recap-skills/actions/workflows/skill-validate.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/zenstory-ai/video-recap-skills/skill-validate.yml?style=flat-square&label=CI"></a>
   <a href="https://platform.xiaomimimo.com"><img alt="AI Xiaomi%20MiMo" src="https://img.shields.io/badge/AI-Xiaomi%20MiMo-34A853?style=flat-square"></a>
@@ -44,16 +44,16 @@
 决定故事与视听方案、剪辑、写稿、配音、混音和字幕。支持 `.mp4 / .mov / .mkv / .webm`。
 
 - **一个 key，本地只要 ffmpeg。** ASR、VLM、TTS 都走[小米 MiMo](https://platform.xiaomimimo.com)，本地只用 Python 标准库和 `ffmpeg`，不需要 GPU，不需要 `pip install`，也不下载模型。配音可以换成 Fish Audio，只替换配音这一段。
-- **先做创作决定，再分配声音。** Agent 先比较剪辑假设，把观众承诺、POV、戏剧问题和"发生了什么变化"的 beat 写进 `recap_story_plan.json`，再给每一拍指定画面任务和声音归属：旁白只在有明确任务时整块配音，强对白、动作声或沉默可以完整主导一拍。
-- **先剪后配，时间轴天然对齐。** 剪辑模式先把长视频剪成成片，再对着成片写解说；一次可以传多个视频，按 `source_id` 选段剪成一条主线；每个视频的分析沉淀成文件系统素材库，下次直接复用。
+- **先做创作决定，再分配声音。** 首次策划时，Agent 比较可行的剪辑方向；已有指定结构或看片反馈时，按当前决定修订。观众承诺、POV、戏剧问题和每拍变化写进 `recap_story_plan.json`，再给每一拍指定画面任务和声音归属：旁白只在有明确任务时整块配音，强对白、动作声或沉默可以完整主导一拍。
+- **先剪后配，时间轴天然对齐。** 剪辑模式先把长视频剪成成片，再对着成片写解说；一次可以传多个视频，按 `source_id` 选段剪成一条主线；视频分析可按需保存到文件系统素材库，后续在来源和设置匹配时复用。
 - **成片之外还能继续改。** 多轨时间线 `timeline.json` 可一键导出剪映草稿，原片、解说、BGM、字幕、图片叠层都可编辑；自带一份准确字幕文件就会被当作原声字幕的首选来源。
-- **每一步都留下可核对的记录。** 旁白 lint、组装 QC、交付 QC 和看片修改日志都是机器可读文件。
+- **每一步都留下可核对的记录。** 旁白 lint、组装 QC 与最终 QC 会生成机器可读报告；看片修改可另记录本轮改动、冻结项与验证结果。
 
 ## 安装
 
 ### ClawHub
 
-ClawHub 分发由仓库中的 [显式发布清单](.clawhub/publish.json) 管理，并通过 [ClawHub](https://clawhub.ai/) 提供发现入口。具体 skill 链接只有在发布者、版本和匿名访问均验证后才会写入本文档，避免把尚不存在的条目当成已上架。
+ClawHub 条目与依赖由 [显式发布清单](.clawhub/publish.json) 管理。编排器 `video-recap` 当前仍因同根安装验证未完成而标为 `blocked`；使用完整流程请按下方方式安装整套插件或源码。
 
 
 前提：Python 3.10 或更新版本，`PATH` 上有 `ffmpeg`，以及一个[小米 MiMo](https://platform.xiaomimimo.com) API Key。默认把字幕烧录进画面，这需要带 libass 的 ffmpeg；Homebrew 自带的 `ffmpeg` 没有 libass，这时默认运行不烧录，在成片旁输出同名 `.srt` 外挂字幕并在 `final_qc.json` 里记一条警告（显式传 `--burn-subtitles` 则在开跑前报错）。旁白里写了画面文字叠加（`visual_overlays`）时还需要带 drawtext 的 ffmpeg，缺了会在配音前报错。要在 macOS 上烧录字幕，可用 `brew install ffmpeg-full`（keg-only，需把它的 `bin` 放到 `PATH` 前面）。
@@ -318,7 +318,7 @@ Agent 在剪任何一刀之前先写 [`recap_story_plan.json`](examples/guohuo-6
 
 > 我有权使用〈本地视频〉，并提供了对应的已核对画面与对白记录。先只给这段素材的声音分工建议：哪句对白、哪个动作声或停顿应完整保留，哪里确需旁白，依据是哪条记录。缺证据就列待核对项，不补人物动机或没出现的事件。交付分拍说明和必要的旁白草案，不调用配音或渲染。
 
-Agent 会自动完成理解、故事与视听规划、剪辑、写稿、配音和合成。剪辑模式内部会先确定保留片段、生成剪后成片，再按输出时间轴写旁白；这些暂停和续跑也由 Agent 处理。
+完整制作请求由 Agent 完成理解、故事与视听规划、剪辑、写稿、配音和合成；只做文字交接的请求按指定范围停止。剪辑模式内部会先确定保留片段、生成剪后成片，再按输出时间轴写旁白；这些暂停和续跑也由 Agent 处理。
 
 ## 流程与七个技能
 
@@ -398,7 +398,7 @@ flowchart LR
 ```
 
 资源、模板和样片是你自己目录里的 JSON 记录，授权与"已采用"状态只由你确认；绑定与显式设置冲突、模板画布与成片不符时，会在配音之前停下。
-每条成片旁边的 `resource_lock.json` 记下这次实际用了哪些资源、授权是否清楚。格式见 [资源库、模板与样片](skills/video-recap/references/resource-library.md)。
+每次运行的 `work_dir/resource_lock.json` 记下这次实际用了哪些资源、授权是否清楚。格式见 [资源库、模板与样片](skills/video-recap/references/resource-library.md)。
 
 **在浏览器里看项目、运行和资源库（只读）：**
 
@@ -422,7 +422,7 @@ flowchart LR
 
 ### 长视频跑到一半报 429 或中断了，要从头再来吗？
 
-不用。VLM 场景分析可断点续传，限流会自愈；写好 `narration.json` 后重复同一条命令即可继续，剪辑模式在 `recap_phase.json` 记下解说对应的剪辑计划（改了计划会要求重写解说），续跑只会接同一个源视频、同一组参数的工作目录。
+VLM 会保存已完成的场景；遇到疑似限流会降低并发重试一轮，仍失败时保留错误供处理。解决原因后重复同一条命令，可以复用匹配的场景缓存并继续。写好 `narration.json` 后也用原命令续跑；剪辑模式用 `recap_phase.json` 绑定写稿时的计划，改了计划需重新核对或重写解说。续跑只接受同一源视频、同一组参数的工作目录。
 
 ### VLM 认不出谁是谁，解说里全是"黑衣男子"？
 

package/lib/video-recap/manifest.json

@@ -2,10 +2,10 @@
   "schemaVersion": 1,
   "upstream": {
     "repository": "https://github.com/zenstory-ai/video-recap-skills.git",
-    "commit": "539168622918e058bd250c793b82f043eced31e0",
+    "commit": "5785c33d8b5172cfa2837a8a0d57eb4b87837475",
     "releaseVersion": "0.6.2"
   },
-  "generatedAt": "2026-10-08T11:36:39.521Z",
+  "generatedAt": "2026-10-15T09:51:04.161Z",
   "skills": [
     "video-assemble",
     "video-cut",
@@ -18,8 +18,8 @@
   "files": [
     {
       "path": "CHANGELOG.md",
-      "sha256": "043143b851ca8357b371bb782c838a5e6593b6018b911edacab58fa862213786",
-      "bytes": 107052
+      "sha256": "3557aac67f3d50d1f08045e648d40c5cf5fd6a9b7af8e88f9b8fb8443b400580",
+      "bytes": 108052
     },
     {
       "path": "LICENSE",
@@ -28,23 +28,23 @@
     },
     {
       "path": "README.en.md",
-      "sha256": "61ca8e1d4d2ff312fb15444a6dfe1044de77ce83f47063b16db3a245a2a41d02",
-      "bytes": 30977
+      "sha256": "0404dc0dee26a81ecf1595a662a3b74ea7a9edc5df90362518bb0ce4a314a950",
+      "bytes": 31281
     },
     {
       "path": "README.md",
-      "sha256": "e431bb4c4fb45c21e8d9a9e4523bcaceb14cb5be545c55fbc7af3f379252f253",
-      "bytes": 26828
+      "sha256": "a159253fc336a3cea2c6ae7716fd726940a7925c617a1485897fd6de07808f43",
+      "bytes": 27093
     },
     {
       "path": "skills/video-assemble/SKILL.md",
-      "sha256": "db9ba594e52b0e7a8a3daf9a439b6e079621e5bb0bec68818969664b8cff0b1f",
-      "bytes": 12210
+      "sha256": "88ab7ae6de32321e1bdb1858a132e7968b3f5f20a8b549378f727dfe0d3db2ce",
+      "bytes": 12364
     },
     {
       "path": "skills/video-assemble/references/audio-modes.md",
-      "sha256": "39a6544ba0918db7de0a113f6d40a3af3c4e96d6158464e698681cbcef451bac",
-      "bytes": 3537
+      "sha256": "e6d93e29367a3cae24da1bd1b5719810b3d9d3b587062031887b0eb1150f001c",
+      "bytes": 3509
     },
     {
       "path": "skills/video-assemble/references/explicit-audio-mix.md",
@@ -58,8 +58,8 @@
     },
     {
       "path": "skills/video-assemble/references/jianying/SOURCE.md",
-      "sha256": "726b1e12cbde535571cf0c37bd0a4b5dfe6da951bf2918e2210abcbd11e84c79",
-      "bytes": 781
+      "sha256": "43dd440f97b8b07153aeeb66fda3722096b059b297dde356fd6d4f5ef2d1fc00",
+      "bytes": 703
     },
     {
       "path": "skills/video-assemble/references/jianying/empty_draft_meta_info.json",
@@ -108,13 +108,13 @@
     },
     {
       "path": "skills/video-assemble/references/packaging.md",
-      "sha256": "f4f8a1e3bec7775d14a976954e5173794e6109ac375fb3e466d8e08b95e55dd5",
-      "bytes": 2856
+      "sha256": "b9d294ea26c7a359d3dae969fe824c9d9904ec51ad92dd502c1a7a9bc7f3fb53",
+      "bytes": 2801
     },
     {
       "path": "skills/video-assemble/references/source-score.md",
-      "sha256": "cbed800c93e32ddc00987ae4cb5fa77e7e4cc5bbc677a134e61d6adb925c7208",
-      "bytes": 6864
+      "sha256": "7d33561851dd9a39fb9c60e91979faa95f54321301acf9a6d4d4a12444556437",
+      "bytes": 6869
     },
     {
       "path": "skills/video-assemble/references/subtitle-track.md",
@@ -328,13 +328,13 @@
     },
     {
       "path": "skills/video-cut/SKILL.md",
-      "sha256": "d4068e941c98bd773c6000cbafe1f593ada4ac7914ada378b1db5a301879c6b4",
-      "bytes": 11756
+      "sha256": "063eef0a661dd72cdcd987dbf7b59785094a32a69f0fbfded6e5675f01947dea",
+      "bytes": 11734
     },
     {
       "path": "skills/video-cut/references/shot-review.md",
-      "sha256": "3be8547c064a44f2d03d8cf83b1edcc6cf7c72c0916e794a942bb8476accb790",
-      "bytes": 5537
+      "sha256": "12dd50bcdb2ecb15cbd961f017d94cdca1f73bb042581cb73770f913ab0957f7",
+      "bytes": 5570
     },
     {
       "path": "skills/video-cut/scripts/cut.py",
@@ -398,28 +398,28 @@
     },
     {
       "path": "skills/video-recap/SKILL.md",
-      "sha256": "dcee225f8a0e2f797ef03640bf5462c91b28efb34f4e9378ed7fcad373d5df2c",
-      "bytes": 17027
+      "sha256": "e321596c52db87ef347f66d6782d2548c2516b8415f1aa89e4bc460d58f18240",
+      "bytes": 17221
     },
     {
       "path": "skills/video-recap/references/audio-routing.md",
-      "sha256": "31d245880c19b86f795ee8a6265cb681198938cf95e5d5876443a21810b6ceee",
-      "bytes": 7361
+      "sha256": "b13bddf5212d9a576b9dc518e09ae9da827dc48f791b9813c7fa48147190b991",
+      "bytes": 7245
     },
     {
       "path": "skills/video-recap/references/config-playbook.md",
-      "sha256": "0cfc3cf66d39a9faa56d1b61e1b1fba3fefb81a825a3352174a2d0f286cbd821",
-      "bytes": 13265
+      "sha256": "7e6d02f53564238799cb34d9909fd250007042ca86625a3722469b35475c8f60",
+      "bytes": 13079
     },
     {
       "path": "skills/video-recap/references/data-schema.md",
-      "sha256": "d9992b03e036d8c53f73c24232eac7249b3ebc1931ca012286adf085d7746a91",
-      "bytes": 36030
+      "sha256": "6741b2abbce4c6e38baebc4f97f863dbc632d759dd63eb9111134309f1f1b78e",
+      "bytes": 36172
     },
     {
       "path": "skills/video-recap/references/resource-library.md",
-      "sha256": "ae7b2646415d3d9eee1d492d3f21eccb736b44ba32e4384761e76735a0d91bcf",
-      "bytes": 10117
+      "sha256": "86cbdcb95d2381f573513906ce2250713c6ae34df2909918f9487d164491e80b",
+      "bytes": 10146
     },
     {
       "path": "skills/video-recap/scripts/doctor.py",
@@ -508,13 +508,13 @@
     },
     {
       "path": "skills/video-reference/SKILL.md",
-      "sha256": "88940900b89b705883aca00598719e89516b5941a4623f0f9de5eb21d0fb3cb9",
-      "bytes": 9699
+      "sha256": "eba7399c9021d3ad218a4f4f5cfd4e1f02538c0d31c3670a6a5531487aa927e9",
+      "bytes": 9672
     },
     {
       "path": "skills/video-reference/references/reference-schema.md",
-      "sha256": "844be9370c1e03d90da51719e9e9375ddc72cec0b3906668c10682404757486f",
-      "bytes": 9279
+      "sha256": "1a0315d268fd449460fe0ff9e89040b873bca88e6ae890683678e8108d620724",
+      "bytes": 9258
     },
     {
       "path": "skills/video-reference/scripts/lib.py",
@@ -548,13 +548,13 @@
     },
     {
       "path": "skills/video-script/SKILL.md",
-      "sha256": "7ae12d12f77e300829650789452caf867f1cab6bd4f8e002fcb3fc4394b54369",
-      "bytes": 18296
+      "sha256": "02f231df44d60985f23b6cd2ee1c731ca234f5a6cfe1233418535f44919ea405",
+      "bytes": 18362
     },
     {
       "path": "skills/video-script/references/creative-editing-playbook.md",
-      "sha256": "c20ee6bd4f6923a1009b451408416e6db91f70a683f072ffd4e89b3fbb1fe436",
-      "bytes": 13959
+      "sha256": "26269189312abf42f83e275de960866c3b21e7c2d26f00e65d61165b324dde3d",
+      "bytes": 13952
     },
     {
       "path": "skills/video-script/references/promotional-copy.md",
@@ -633,13 +633,13 @@
     },
     {
       "path": "skills/video-understanding/SKILL.md",
-      "sha256": "e62600a4194f720a80075dcdb13e65fe7afcbbefba39e8f018de840e871d3ef6",
-      "bytes": 7191
+      "sha256": "e0a9612667bf2fdff0b50252daa18d3546c1a88cb53bca61544317dea86736b5",
+      "bytes": 8117
     },
     {
       "path": "skills/video-understanding/references/data-schema.md",
-      "sha256": "6f0ac8486933a1bab344dd230830971fe5ab6ed3e1f5711068554f28825c3b1a",
-      "bytes": 6212
+      "sha256": "997beda5d80510520a50e84c332f0f25b03216eff5f4b2a480be8e438b410ece",
+      "bytes": 6218
     },
     {
       "path": "skills/video-understanding/references/prompt-templates.md",
@@ -758,13 +758,13 @@
     },
     {
       "path": "skills/video-voiceover/SKILL.md",
-      "sha256": "2ba0c0c0ded5d561f89ed80d42b7075edc469fb820224a547e97d122ff50fdf9",
-      "bytes": 11407
+      "sha256": "80f1ecf4c26ca9fd93f121fcfd68886d7bbeaccd7a8783b998fc1a42f851a354",
+      "bytes": 11341
     },
     {
       "path": "skills/video-voiceover/references/index-tts.md",
-      "sha256": "fb3972271efd389da432310d69787fcab93460ac32485ca4f2cd11a49865642c",
-      "bytes": 1623
+      "sha256": "485ac7c63c244b60b3b11b9d3b9a8e0158d8dccc057a7e982ab71d570b23f4ea",
+      "bytes": 1553
     },
     {
       "path": "skills/video-voiceover/scripts/approved_text_policy.py",

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

@@ -1,10 +1,7 @@
 ---
 name: video-assemble
 user-invocable: false
-description: >
- 合成视频解说最终成片：把旁白音频铺到源视频上，按旁白窗口压低原声，生成 SRT / ASS 字幕并可烧录，
- 最后做响度标准化。作为最终合成阶段使用。输入源视频、tts_meta.json 与旁白位置；
- 输出 recap 成片和字幕。触发词：视频合成、混音、字幕、压字幕、assemble video、mux、ducking、subtitles、成片。
+description: 合成视频解说最终成片：把旁白音频铺到源视频上，按旁白窗口压低原声，生成 SRT / ASS 字幕并可烧录， 最后做响度标准化。作为最终合成阶段使用。输入源视频、tts_meta.json 与旁白位置； 输出 recap 成片和字幕。触发词：视频合成、混音、字幕、压字幕、assemble video、mux、ducking、subtitles、成片。
 ---
 
 ## 1. 定位
@@ -27,7 +24,7 @@ description: >
 - `silence`
 - `narration`
 
-因此，旁白间隙是主动选择，不是必须填满的空白。不要为了“更满”而加入通用 BGM、压住必须听见的台词或消除有意义的沉默。
+旁白间隙按已选声音分工保留。只在确有任务时加入 BGM，并保住必须听见的台词与有意义的沉默。
 
 当前渲染器不解析 `visual_audio_board.json`；Agent 通过旁白时间、`overlaps_speech`、原声留白与现有混音参数落实这些决定。
 
@@ -73,7 +70,7 @@ python3 scripts/assemble.py <video> --work-dir <work_dir> \
 - 段落首块（与上一块作者留白超过 1.6 秒）从写的 `start` 放置，但不早于上一块实际结尾加它的 `pause_after_ms`，上一块超时会把它往后推；段落内后续块紧接上一块的实际结尾（间隔 0.35 秒），最多比写的 `start` 提前 1.2 秒。这一提前发生在旁白校验之后，所以提前的那一段不能进入原声对白：有对白时最多提前到最后一段对白结束处。真的提前了的块在 `source_entry_status` 记 `paragraph_tightened`，并在 `written_start` 记写的 `start`。
 - 旁白不做任何容差裁尾；温和加速后仍放不下即 `no_safe_fit`。每段 `_placed_*.wav`
   必须与序列化后的时间线区间等长或更短，否则 `timeline_audio_mismatch` 阻断。
-- 已采用配音的 v1 合同只支持原速、禁止段内适速；不能让环境默认 1.15 倍速或旧缓存覆盖它。放不下就修订安排，不裁尾。严格运行使用新工作目录与新输出路径；输入/实际混音来源变动或 QC 失败时，不发布候选成片。没有采用文件的旧入口仍是兼容模式，不自动获得同等证据。
+- 已采用配音按其 `tempo_policy` 执行：保守默认是原速且禁止段内适速，也可显式采用符合范围要求的其他速度策略；环境默认 1.15 倍速不能覆盖采用决定。显式完整声音混音分支固定原速，不做自动适配。放不下就修订安排，不裁尾。严格运行使用新工作目录与新输出路径；输入/实际混音来源变动或 QC 失败时，不发布候选成片。没有采用文件时仍可按默认旁白路径合成，但消费记录为 `UNADOPTED`。
 - 原声在旁白结束后最多再压低 3 秒，等这段时间内的下一个句末锚点：压到它的 `pause_start`，只在实测停顿内渐强，
   于 `source_restore_at` 回满（锚点为 `unverified` 时状态记 `sentence_boundary_unverified`）。3 秒内没有锚点时，
   离时间线末端不足 3 秒就压到末端（`held_to_timeline_end`），否则在旁白结束处直接回满（`bounded_release`），
@@ -84,7 +81,7 @@ python3 scripts/assemble.py <video> --work-dir <work_dir> \
 - 导出只接受 `schema_version: 2` 的 `timeline.json`，只映射视频、音频、字幕和图片叠层（`scale` / `position`）；变速、转场、蒙版、富文本、特效轨等手写扩展字段会被明确拒绝。
 - 剪映草稿引用未烧录的源视频，因此原片硬字幕仍会保留，必要时在剪映内另行遮罩。
 - 字幕外观可用 `SUBTITLE_FONT_SIZE`、`SUBTITLE_MARGIN_V`、`SUBTITLE_MAX_CHARS` 等控制。
-- `SUBTITLE_Y_TOP/BOT` 把 ASS 基线放到测得的原片字幕区域，坐标为显示画布上的半开 `[top, bot)`，只接受方形或近方形像素（SAR 与 1:1 相差不超过 2%，未标注的 `0:1` 按方形）；显式遮罩策略下默认 `SUBTITLE_MASK_OPACITY=0.6`，`SOURCE_SUBTITLE_MASK_TIMING=narration`。
+- `SUBTITLE_Y_TOP/BOT` 把 ASS 基线放到测得的原片字幕区域，坐标为显示画布上的半开 `[top, bot)`，只接受方形或近方形像素（SAR 与 1:1 相差不超过 2%，未标注的 `0:1` 按方形）；比例遮罩默认 `SUBTITLE_MASK_OPACITY=0.6`；显式指定实测字幕带时默认不透明，除非另设该变量。`SOURCE_SUBTITLE_MASK_TIMING` 默认是 `narration`。
 - 原声在旁白间隙回到 `IDLE_ORIG_VOLUME`，旁白下压到 `SPEECH_DUCKING_VOLUME`；`DUCK_FADE_SECONDS` 控制过渡。还可配置 `DUCK_BRIDGE_SECONDS`、`ZONE_DUCKING_VOLUME`、`FINAL_LOUDNORM`、`TARGET_LUFS` 与 `LOUDNESS_LIMITER_MAX_DB`。
 - 可通过 `BGM_PATH` 指定 BGM；它会循环到成片长度，并按 `BGM_VOLUME` / `BGM_DUCKING_VOLUME` 混音。不要在没有创作依据时设置通用 BGM。
 - 烧录字幕需要带 `subtitles` / libass 的 ffmpeg，合成阶段在渲染前预检。显式要求烧录（`--burn-subtitles` 或环境变量 `BURN_SUBTITLES`）时缺 libass 直接失败；只是默认开启时降级：不烧录，交付外挂 `.srt`（留白里的 `「」` 原声对白仅在有 `user_subtitles.*` 时照常写进去；原本由遮罩触发的对白随遮罩一起关闭，原片硬字幕可见），`visual_qc.json` 的 `warnings` 与 `assembly_manifest.json` 的 `warnings` 记一条 `subtitle_burn_degraded`，`subtitles.burn_degraded_reason` 写原因。降级后遮罩照旧关闭（`mask.trigger` 为 `burn_subtitles_degraded`）。
@@ -92,7 +89,7 @@ python3 scripts/assemble.py <video> --work-dir <work_dir> \
 - 成片画面一律是 H.264 8-bit 4:2:0 并带 `+faststart`：不需要滤镜、且源画面已是 H.264 8-bit 4:2:0（`yuv420p`，或全范围的 `yuvj420p`）、宽高为偶数时才流复制，原样交付；否则重编码为 `yuv420p`。色彩标记：源未标记或已是 BT.709 时标为 BT.709（`-colorspace/-color_primaries/-color_trc bt709`），其它已声明的色彩空间原样保留；全范围（`pc`）源保留 `pc`，其余标 `tv`。YUV 源只改标记，不转换像素；RGB 源（ffprobe 报 `gbr`，如 PNG/QuickTime RLE 封装的 MOV）没有 YUV 矩阵可保留，按 BT.709 limited 转换。结果记在 `assembly_qc.json` 的 `delivery_qc.color_tags`（RGB 源多一个 `from_rgb: true`）。
 - 原声留白中的对白字幕优先读取 Agent 校对的 `original_subtitles.json`；否则保守映射 ASR。只有遮罩覆盖留白或用户字幕明确要求替换时才烧录原声对白，并用 `「」` 与旁白区分。
 
-### 按原片区间准备声音，而不是整体压低旧成片
+### 按原片区间准备声音底轨
 
 已有多段原声取舍和独立 BGM 决定时，先用 `references/source-score.md` 的独立
 `source_score.py` 从原片声音流按精确帧区间重建原声轨、音乐轨及两者之和；它只输出

package/lib/video-recap/skills/video-assemble/references/audio-modes.md

@@ -6,7 +6,7 @@ zero-based audio ordinal used by FFmpeg's `0:a:N` selector.
 
 ## `narration`
 
-- Requires non-empty `tts_meta.json` segments, as before.
+- Requires non-empty `tts_meta.json` segments.
 - Builds/places narration WAV, performs source ducking and optional BGM mix,
   then applies the configured final loudness/limiter stage and AAC encoding.
 - Missing source audio may use the existing synthetic-silence fallback.
@@ -21,8 +21,8 @@ zero-based audio ordinal used by FFmpeg's `0:a:N` selector.
 - Uses the selected input audio stream, applies `IDLE_ORIG_VOLUME`, mixes a
   declared `BGM_PATH` when present, and runs the configured final
   loudness/limiter stage before AAC encoding.
-- A declared but missing `BGM_PATH` is an error in this new mode (the legacy
-  narration-mode warn-and-skip behavior remains unchanged).
+- A declared but missing `BGM_PATH` is an error in source-mix mode. Narration
+  mode warns and skips the missing music.
 - This is a processed mix, not frozen audio. `assembly_qc.json` reports the
   operations that actually ran.
 

package/lib/video-recap/skills/video-assemble/references/jianying/SOURCE.md

@@ -5,8 +5,7 @@ These JSON protocol templates are pinned to
 `ef4eb46c823910553f901649f2f13fd7575e748f`, under its MIT license. They are
 data/schema baselines, not executable upstream code. Runtime builders deep-copy
 the templates and replace authored values such as IDs, paths, timings, and canvas
-dimensions. Only the templates the exporter builds from are kept; the nested
-compound-draft templates were dropped together with green-screen export.
+dimensions. The directory contains only templates used by the exporter.
 
 The required copyright and permission notice is preserved in
 `LICENSE.duo-video` in this directory.

package/lib/video-recap/skills/video-assemble/references/packaging.md

@@ -13,8 +13,7 @@
 4. 渲染完整透明字幕层，再 overlay 到锁定母版；合成后确认音轨未被意外改写。
 5. 完整播放实际最终文件，并复查字幕遮脸、跳字、断行、首尾帧和边界处残影。
 
-已有项目级渲染器能输出精确包装时，由该项目自己把它生成的透明层合成到锁定母版，而不是用通用白字黑框
-近似品牌样式；本技能不提供逐帧前景合成命令。合成时音轨按流复制，合成后核对帧率、时长与音轨未被改写，
+已有项目级渲染器时，由该项目把透明层合成到锁定母版，以保留已确认的包装样式；本技能不提供逐帧前景合成命令。合成时音轨按流复制，合成后核对帧率、时长与音轨未被改写，
 再写入新文件。片名卡有渐显或动画时须渲染完整序列，不能冻结最后一张图代替。
 
 ## 静态包装图层 `packaging_layers.json`

package/lib/video-recap/skills/video-assemble/references/source-score.md

@@ -73,8 +73,9 @@ Each unique selected source stream is decoded from its actual PTS clock to canon
 48 kHz stereo exactly once. All authored intervals are then cut from that canonical
 sample array—never independently decoded or `-ss`-seeked per edit.
 
-The source segment duration is `(source_end_frame-source_start_frame)*48000/fps`.
-Its output end is derived, not declared. Source segments and explicit silence ranges
+The source segment length is the difference between the rounded start and end
+sample positions described above. Its output end is derived from that integer
+length, not declared or rounded from the duration again. Source segments and explicit silence ranges
 must form an exact, nonoverlapping partition of `[0,total_samples)`. There are no
 implicit gaps. Supported roles are `protected_original` and
 `mixed_original_under_narration`; their gains and labels are retained unchanged.
@@ -131,9 +132,7 @@ directory cannot publish final-named beds or a receipt.
 Diagnostic command/log/intermediate files may remain in the unique failed directory.
 
 To consume a completed receipt with explicitly adopted narration, use the strict
-`--audio-mix-adoption` path in `explicit-audio-mix.md`. To deliver an already complete
-prepared bed without narration, a dedicated prepared-audio renderer will follow in a
-later release. Do not feed `prepared_bed.wav` through legacy source ducking or
+`--audio-mix-adoption` path in `explicit-audio-mix.md`. This path does not render a final video from a prepared bed alone. Do not feed `prepared_bed.wav` through legacy source ducking or
 ambient BGM/loudness settings.
 
 ## 与旧入口的关系（中文摘要）
@@ -143,5 +142,5 @@ ambient BGM/loudness settings.
 完整音乐决定且不再叠加配乐，使用严格的 `score:{"kind":"none"}`；它生成真实全零 score，
 并保持 prepared 与 source 逐字节相同，不伪造静音音乐资产。
 
-这一步仅输出声音底轨和来源回执，不是最终视频。旧入口保留兼容行为；调用方须区分
+这一步输出声音底轨和来源回执，后续合成负责最终视频。调用方须区分
 “底轨已验证”“配音已验证”和“完整混音已验证”三种状态，不能相互冒充。

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

@@ -1,11 +1,7 @@
 ---
 name: video-cut
 user-invocable: false
-description: >
- 把长视频按 Agent 选择的原片区间剪成短片。作为两阶段创作流程中的剪辑环节，读取 clip_plan.json 与源视频，
- 输出 edited_source.mp4；随后 Agent 按输出时间线写 narration.json。支持单视频与多视频（sources manifest）拼剪，
- 本工具不读取、不映射旁白。
- 触发词：视频剪辑、剪辑式解说、video cut、clip plan、拼剪。
+description: 把长视频按 Agent 选择的原片区间剪成短片。作为两阶段创作流程中的剪辑环节，读取 clip_plan.json 与源视频， 输出 edited_source.mp4；随后 Agent 按输出时间线写 narration.json。支持单视频与多视频（sources manifest）拼剪， 本工具不读取、不映射旁白。 触发词：视频剪辑、剪辑式解说、video cut、clip plan、拼剪。
 ---
 
 ## 1. 定位
@@ -18,7 +14,7 @@ description: >
 4. 拼接选定区间，输出恒定帧率的 `edited_source.mp4`，帧数与 `clip_plan_validated.json` 记录的一致。
 5. 到此停止，由 Agent 按真实输出时间线写 `narration.json`；本工具不读取旁白，也不做原片→输出映射。
 
-相同输入会得到相同输出。`edited_source.mp4.meta.json` 记录标准化 clips、渲染设置和每个源文件的 `size`/`mtime_ns`；三者与当前一致且 `edited_source.mp4` 存在非空才复用，任一不同即重渲染。只有 sidecar 而没有媒体文件不复用。
+渲染缓存按输入与设置复用。`edited_source.mp4.meta.json` 记录标准化 clips、渲染设置和每个源文件的 `size`/`mtime_ns`；三者与当前一致且 `edited_source.mp4` 存在非空才复用，任一不同即重渲染。只有 sidecar 而没有媒体文件不复用。
 
 ## 2. 输入契约
 
@@ -43,7 +39,7 @@ description: >
 
 ## 3. 剪辑意图契约
 
-工具不会替 Agent 做创作选择。写片段前先完成本节的剪辑意图检查，并让每个区间映射到 `recap_story_plan.json` 的一个 beat。
+Agent 写片段前先确认剪辑意图，并让每个区间映射到 `recap_story_plan.json` 的一个 beat；工具负责执行与校验。
 
 使用现有自由文本 `reason` 保存简洁决定：
 

package/lib/video-recap/skills/video-cut/references/shot-review.md

@@ -40,7 +40,7 @@ python3 scripts/cut.py source.mp4 --work-dir work --review-shots
 
 对每个候选看前后 0.5–1 秒，核对角色表演、完整动作、对白与原片切镜；未实际播放就保留 `NEEDS_DYNAMIC_REVIEW`。
 先对照源画面和取景参数：同一原生镜头中途换 crop/画窗，或曝光闪光，都可能产生切点分数；两个候选间的帧数不一定是一段真实短镜头。
-修复后用同样参数重跑对照：候选消失才算真的修掉；仍被保留的短镜逐个判断，不因“短”就判错。
+修复后用同样参数重跑，核对候选变化，再以正常速度播放确认修复是否成立；仍被保留的短镜逐个判断，不因“短”就判错。
 判断无关残镜后，在作者计划里删除整个无关镜头或恢复同源连续画面；相关反应可回原片扩完整，不能用定格补长、转场掩盖或只修导出文件。
 
 ## 修短残镜时的取景复核

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

@@ -1,10 +1,6 @@
 ---
 name: video-recap
-description: >
- 从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm，并要求剪辑、添加旁白、
- 配音、总结、短剧/电视剧/电影/纪录片/科普解说时使用。负责编排 video-* 技能链：视频理解 →
- Agent 制定故事与视听方案 → 剪辑 → 配音 → 合成。触发词：视频解说、视频旁白、生成解说、
- 视频 recap、video recap、voiceover、narration、auto-dub、recap。
+description: 从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm，并要求剪辑、添加旁白、 配音、总结、短剧/电视剧/电影/纪录片/科普解说时使用。负责编排 video-* 技能链：视频理解 → Agent 制定故事与视听方案 → 剪辑 → 配音 → 合成。触发词：视频解说、视频旁白、生成解说、 视频 recap、video recap、voiceover、narration、auto-dub、recap。
 ---
 
 ## 1. 定位与流程
@@ -60,7 +56,7 @@ video-assemble 严格验证，recap 只核对子技能绑定记录引用的是
 
 ## 2. 创作职责
 
-这不是单纯的 JSON / 渲染流水线。Agent 是本次内容的创作负责人。先判断本轮的**创作控制模式**（CREATE / DIRECTED / REVISION，与 `--edit-mode` 无关），再在进入昂贵的下游处理前完成五次判断：
+Agent 负责本次创作。先判断本轮的**创作控制模式**（CREATE / DIRECTED / REVISION，与 `--edit-mode` 分别选择），再在配音和渲染前完成五次判断：
 
 1. **导演判断**：观众承诺、POV、戏剧问题、情绪终点与揭示节奏。
 2. **故事编辑**：beat 定义为“发生了什么变化”，不是场景摘要。
@@ -93,7 +89,7 @@ TTS 供应商由 `--tts-provider mimo-tts|fish-audio|index-tts`（或 `TTS_PROVI
 
 可覆盖配置见 `references/config-playbook.md`，`final_qc.json` 的字段见 `references/data-schema.md`。
 
-下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本启动后会自行定位兄弟技能和资源。
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。编排脚本从同一技能根目录定位所需阶段；安装时需让五个阶段技能与本技能位于同一层。
 
 ## 4. 标准解说流程（audio-mode narration）
 
@@ -161,13 +157,13 @@ python3 scripts/recap.py <video> --work-dir <work_dir>  # 可追加 --edit-mode
 
 ### 4.5 字幕与克隆旁白
 
-若要把旁白字幕固定在原片字幕区域，先在仓库根目录运行：
+若要把旁白字幕固定在原片字幕区域，先测量位置。完整源码安装可在仓库根目录运行以下工具；单独安装技能时，由 Agent 查看视频帧测出同一显示画布上的上下边界：
 
 ```bash
 python3 tools/measure_subtitle.py <video>
 ```
 
-再传入测得的 `--subtitle-y-top/--subtitle-y-bot`。坐标基于 ffmpeg 自动旋转后的显示画布，区间为半开 `[top, bot)`，并要求底对齐 ASS 样式；显式设置后，该区域默认使用 60% 透明度的旁白窗口遮罩。
+再传入测得的 `--subtitle-y-top/--subtitle-y-bot`。坐标基于 ffmpeg 自动旋转后的显示画布，区间为半开 `[top, bot)`，并要求底对齐 ASS 样式；显式设置后，该区域默认使用不透明的旁白窗口遮罩；可用 `SUBTITLE_MASK_OPACITY` 调整。
 
 解说模式如需克隆参考声音，使用 `--voice-ref <audio>`；它与 dub 模式不同。
 
@@ -190,7 +186,7 @@ full/cut 交付如需让确定性的最终检查影响命令退出状态，显
 该参数不支持 `--edit-mode dub`；dub 未传该参数时的准备和渲染行为不变。
 
 交付时读 `final_qc.json` 的 `metadata.warnings`，有内容就原样告诉用户，不能只报“完成”。`subtitle_burn_degraded`
-表示 ffmpeg 缺 libass、默认烧录被降级：成片里没有字幕，字幕在成片旁的同名 `.srt`。用户要烧录字幕，就请他装带 libass 的
+表示 ffmpeg 缺 libass、默认烧录被降级：新字幕保存在成片旁的同名 `.srt`，原片已有硬字幕仍保留。用户要烧录字幕，就请他装带 libass 的
 ffmpeg 后重跑；显式传 `--burn-subtitles` 时缺 libass 会在开跑前报错。旁白里写了 `visual_overlays` 而 ffmpeg 缺
 drawtext 时，流程在配音前停下，按报错删掉叠加或换 ffmpeg 后续跑。
 
@@ -256,4 +252,4 @@ python3 scripts/dashboard_server.py --root <目录> [--port 0] [--open]
 ## 8. 能力边界
 
 - 语义评审默认建议型、失败开放；只有调用方显式启用严格解说评审时，事实矛盾、残句或评审不可用才会在 TTS 前阻断。确定性校验阶段始终负责硬校验。
-- 宣发标题、花字或外部文案回填见 `video-script` 的 references/promotional-copy.md。
+- 宣发标题、花字或外部文案回填交给 `video-script`，由它读取自己的宣发参考。

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

@@ -57,8 +57,7 @@ episodes. Use two existing stages rather than sending an old mix binding into a
    `SOURCES_JSON` must be `{"sources": [{"source_id": ..., "source_path": ...}]}`
    (optional per-source `duration` and `source_work_dir`); recap's
    `multi_source_manifest.json` already has this shape. 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.
+   `--sources-manifest`. Read `clip_plan_validated.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