@oh-story/dsh 0.1.15 → 0.1.17

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/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "description": "Bundled upstream Skills; no module type so scripts resolve as in an upstream install."
+}

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

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

@@ -1,11 +1,9 @@
 # Config playbook (override-only)
 
-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. 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).
+Use the defaults after configuring the required credentials and local tools. The environment
+variables and CLI flags below override those defaults. An optional `recap_project.json` passed
+with `--project` binds resources and templates to the same settings (see `resource-library.md`).
+A conflict between a project binding and an explicit setting stops the run.
 Defaults below are bundle-level defaults unless a note scopes them to a specific stage.
 
 | Concern | Env var / flag | Default | Notes |
@@ -31,7 +29,7 @@ Defaults below are bundle-level defaults unless a note scopes them to a specific
 | 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 |
 | Cut sentence snapping | `SNAP_CLIP_LINE_END` / `CLIP_START_SNAP_MAX_PREPEND` / `CLIP_START_SNAP_MAX_TRIM` / `CLIP_SNAP_MAX_EXTEND` | on / `1.8` / `0.35` / `2.0` | scene-cut cleanup runs first, then reliable sentence/quiet snapping, then a sub-frame frame-grid alignment that keeps the edge in its pause. An ASR-owned edge still inside speech produces `unsafe_clip_sentence_boundary` instead of a half sentence, with `nearest_safe` before/after times within 5 s, already on the source frame grid |
 | Mask source subs | `MASK_SOURCE_SUBTITLES` / `SOURCE_SUBTITLE_MASK_POLICY` / `SOURCE_SUBTITLE_MASK_RATIO` | off / `off` / `0.14` | masking requires an explicit policy (`opt_in`, `safe`, or `forced`) and burned recap subtitles. Passing measured `--subtitle-y-top/--subtitle-y-bot` opts in automatically. With `--no-burn-subtitles`, or when a default burn degrades because ffmpeg lacks libass, the MP4 stays unmasked |
-| Measured subtitle band | `SUBTITLE_Y_TOP` / `SUBTITLE_Y_BOT`; `--subtitle-y-top/--subtitle-y-bot` | off | half-open `[top, bot)` rows of the auto-rotated display canvas (the stored width is scaled by the SAR; a rotated non-square stream's rows are scaled by it too, and the mask converts them back to decoded-frame rows); square or near-square pixels (SAR within 2% of 1:1; unspecified `0:1` counts as square) and bottom ASS alignment (1/2/3) only; use `tools/measure_subtitle.py` to generate source-identified previews and suggestions |
+| Measured subtitle band | `SUBTITLE_Y_TOP` / `SUBTITLE_Y_BOT`; `--subtitle-y-top/--subtitle-y-bot` | off | half-open `[top, bot)` rows of the auto-rotated display canvas (the stored width is scaled by the SAR; a rotated non-square stream's rows are scaled by it too, and the mask converts them back to decoded-frame rows); square or near-square pixels (SAR within 2% of 1:1; unspecified `0:1` counts as square) and bottom ASS alignment (1/2/3) only; a full source checkout includes `tools/measure_subtitle.py` for source-identified previews and suggestions |
 | Subtitle mask look | `SUBTITLE_MASK_OPACITY` / `SOURCE_SUBTITLE_MASK_TIMING` / `SUBTITLE_MASK_PADDING` | `0.6` / `narration` / `4` | generic ratio masks stay translucent by default; an explicitly measured `--subtitle-y-top/--subtitle-y-bot` band defaults to opaque so source glyphs cannot show through. Set `SUBTITLE_MASK_OPACITY` to override; timing `all` restores full-time masking |
 | Original ducking | `IDLE_ORIG_VOLUME` / `SPEECH_DUCKING_VOLUME` | `1.0` / `0.2` | the original returns to full-volume `IDLE` in deliberate gaps/original blocks, and ducks to `SPEECH` under narration. Inter-beat gaps shorter than `DUCK_BRIDGE_SECONDS` stay ducked so a single narration block does not swell between sentences. A fixed `0.3` is only the fallback when beats carry no placement info |
 | Foreign source audio | `FOREIGN_SOURCE_AUDIO` | off | set when the original audio is in a language the narration is **not** (e.g. a Japanese drama recapped in Chinese). The under-narration original (`SPEECH_DUCKING_VOLUME` / `ZONE_DUCKING_VOLUME`) drops from `0.2`/`0.12` to `0.05` so the foreign speech doesn't bleed under the narration as 怪音; original-audio gap blocks still play full-volume (`IDLE_ORIG_VOLUME`). Explicit `SPEECH_DUCKING_VOLUME`/`ZONE_DUCKING_VOLUME` still override. Pairs with bring-your-own `user_subtitles.*` for the foreign dialogue |

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

@@ -1,6 +1,6 @@
 # 数据格式（中间 JSON）
 
-所有中间文件均在 pipeline 工作目录（work_dir/）下。
+中间产物保存在本次运行的工作目录 `work_dir/` 下。
 
 ## vlm_analysis.json
 
@@ -165,7 +165,7 @@ cut 第二轮（已有 `edited_source.mp4`）时本文件与 `asr_writing_chunks
 
 ## narration.json
 
-Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated cut 模式（`video-recap --edit-mode cut`）下，第二次暂停时已经先剪出 `edited_source.mp4`，因此 `narration.json` 必须直接使用剪后成片的 OUTPUT 时间轴（0..成片总时长）；不存在原视频时间→输出时间的旁白映射产物：
+Agent 撰写的解说词。full 模式下使用原视频时间；**编排 cut 模式（`video-recap --edit-mode cut`）下**，第二次暂停时已经先剪出 `edited_source.mp4`，因此 `narration.json` 必须直接使用剪后成片的 OUTPUT 时间轴（0..成片总时长）；不存在原视频时间→输出时间的旁白映射产物：
 
 ```json
 [
@@ -180,7 +180,7 @@ Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated
 ```json
 {
   "ok": false,
-  "error_count": 1,
+  "error_count": 2,
   "warning_count": 1,
   "metrics": {
     "segment_count": 12,
@@ -245,7 +245,7 @@ CLI 不以它们作为渲染硬门禁，也不新增解析服务；建议型解
 
 ## narration_lint.json 的 deslop_qc（CLI 生成，报告型 QC）
 
-`narration_lint.json` 的 `deslop_qc` 字段由本地 deterministic scanner 生成，Agent 不手写；不再单独写 `deslop_qc.json`。它只是 report-only QC：不是 AIGC detector，不判断文本是不是 AI 写的，不会自动改写。修改仍由 Agent/人工根据报告回到 `narration.json`、`style_card.json` 或字幕源里处理。
+`narration_lint.json` 的 `deslop_qc` 字段由本地 deterministic scanner 生成，Agent 不手写；不再单独写 `deslop_qc.json`。它输出可读性报告，区分下面两类结果；不判断文本是否由 AI 生成，也不自动改写。修改仍由 Agent/人工根据报告回到 `narration.json`、`style_card.json` 或字幕源里处理。
 
 报告分两层：
 
@@ -417,14 +417,14 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
 
 ## original_subtitles.json / user_subtitles.{json,srt,ass}（可选，原声留白字幕）
 
-解说块之间的原声留白会把【原声台词】烧成字幕（assemble 阶段用 `「」` 包裹以区分解说）。来源优先级（高→低）：
+遮罩覆盖原声留白或用户字幕明确要求替换时，assemble 才为留白生成原声对白字幕，并用 `「」` 与旁白区分。来源优先级（高→低）：
 
-1. **`work_dir/user_subtitles.json`**（用户自带，最准）— 数组 `[{start,end,text}]` 默认按**成片 OUTPUT** 时间轴直接使用；也可写成 `{"timeline": "source"|"output", "lines": [...]}`，`source` 表示按**原片**时间轴给出，由 assemble 依 `clip_plan_validated.json` 映射到成片。
+1. **`work_dir/user_subtitles.json`**（用户自带，优先使用）— 数组 `[{start,end,text}]` 默认按**成片 OUTPUT** 时间轴直接使用；也可写成 `{"timeline": "source"|"output", "lines": [...]}`，`source` 表示按**原片**时间轴给出，由 assemble 依 `clip_plan_validated.json` 映射到成片。
 2. **`work_dir/user_subtitles.srt` / `.ass`**（用户自带）— 默认按**原片**时间轴解析后映射到成片。
 3. **`work_dir/original_subtitles.json`**（Agent 校对，cut pass2 写）— OUTPUT 时间轴 `[{start,end,text}]`，订正 ASR 错字/人名、只写留白里真正出声的句子。
 4. **ASR 兜底** — 无上述文件时，用 `asr_result.json` 按留白粗略映射（中点估时，可能偏多偏乱）。
 
-来源 1–3 为「精确来源」：每条按句**区间裁剪**落到所覆盖的留白边界（跨边界会拆分），不走 ASR 兜底的中点估时；over-dense 行截断显示而非丢弃。
+来源 1–3 直接采用声明的时间区间：每条按句**区间裁剪**落到所覆盖的留白边界（跨边界会拆分），不走 ASR 兜底的中点估时；过密行截断显示而非丢弃。时间声明仍需对照实际声音核准，不能仅凭文件来源认定已精确对齐。
 
 ```json
 [
@@ -599,4 +599,4 @@ Dub 模式下，`dub_script.json` 在 voiceclone **之前**先经过 determinist
  "mask_dropped": false, "message": "…", "next_action": "…"}
 ```
 
-这时成片里没有字幕，字幕在成片旁的同名 `.srt`（路径见 `assembly_manifest.json` 的 `subtitle_sidecar`）；`mask_dropped` 为 `true` 表示原本会画的原字幕遮罩也一并关掉了。`final_qc.py` 打印的摘要 `final_qc.warnings` 列出这些 code，`recap.py` 完成时打印一行警告和外挂字幕路径。
+这时新字幕保存在成片旁的同名 `.srt`，路径见 `assembly_manifest.json` 的 `subtitle_sidecar`；原片已有硬字幕仍保留。`mask_dropped` 为 `true` 表示原本会画的原字幕遮罩也一并关掉了。`final_qc.py` 打印的摘要 `final_qc.warnings` 列出这些 code，`recap.py` 完成时打印一行警告和外挂字幕路径。

package/lib/video-recap/skills/video-recap/references/resource-library.md

@@ -22,7 +22,7 @@ python3 scripts/library.py --library-dir <library> show <id|id@vN>
 
 浏览资源、模板与样片（含图片、音频与样片预览）可用只读 dashboard：`python3 scripts/dashboard_server.py --root <library 或其上层目录>`。
 
-工具从不写库。新增或修改记录时直接编辑 JSON，再跑 `check`。**错误**表示该条目不能用；**警告**表示能用但需要人看一眼
+这三个查询命令不写库。新增或修改记录时直接编辑 JSON，再跑 `check`。**错误**表示该条目不能用；**警告**表示能用但需要人看一眼
 （授权未确认、声音授权未确认、样片不在本机、模板采用后资源文件已变化）。
 
 ## 通用规则
@@ -114,7 +114,7 @@ python3 scripts/library.py --library-dir <library> show <id|id@vN>
    任何层级出现 `source_facts`、`labels`、`evidence`、`entities`、`statement`、`from`、`path` 键都报错（与参考技能导出时的复扫同一组键）。
 5. 用户确认后把 `status` 改为 `adopted` 并用用户原话写 `adoption`。之后要改内容就出 `v2`，不改已采纳的版本。
 
-库仍然只读，登记与采纳都是手工编辑。
+上述库查询命令只读，登记与采纳由操作者编辑 JSON。
 
 ## 样片 `sample.json`
 

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

@@ -1,16 +1,12 @@
 ---
 name: video-reference
 user-invocable: true
-description: >
- 按需把一部成片拆成可复用的制作参考：测镜头节奏与响度，标注段落与音轨分工，把原片事实与可迁移方法分开，
- 导出不含原片人名台词的 production_reference.json 供下次制作参考。不在默认生产路径上。
- 触发词：拆片、拆解成片、制作参考、参考模板、production reference。
+description: 按需把一部成片拆成可复用的制作参考：测镜头节奏与响度，标注段落与音轨分工，把原片事实与可迁移方法分开， 导出不含原片人名台词的 production_reference.json 供下次制作参考。不在默认生产路径上。 触发词：拆片、拆解成片、制作参考、参考模板、production reference。
 ---
 
 ## 1. 定位
 
-本技能把一部**已完成的成片**拆成下一次制作能直接参考的方法与数值。它是按需的参考分析，不是生产阶段，也不是质检：
-不调用 MiMo，不改其他产物，不给任何运行打分或拦截。
+本技能把一部**已完成的成片**拆成下一次制作可参考的方法与数值，按需在本地运行。它只写自己的测量、标注与导出物，不调用 MiMo，也不对生产流程评分或拦截。
 
 Agent 的角色是**拆片编辑**：先如实记录"这部片子怎么做的"（事实），再提炼"换一部素材还能怎么用"（方法）。
 两者必须分开：事实只留在本地工作目录，导出物只含方法和测得的数值。
@@ -24,7 +20,7 @@ Agent 的角色是**拆片编辑**：先如实记录"这部片子怎么做的"
   标注时 Agent 还应看故事板 / contact sheet 与 `vlm_analysis.json`。
 
 没有理解产物也能跑，但旁白语速为空，泄漏扫描只剩 Agent 自己写的 `entities`，check 会给出警告；
-看画面改用 `frames --span 0,<时长> --step 2` 的接触表。
+看画面可用 `frames --span 0,<时长> --step 2` 生成的抽帧拼图。
 
 下面的 `scripts/...` 均相对于本技能目录。
 
@@ -94,7 +90,7 @@ R6 只能拦住字面泄漏，拦不住改写过的剧情；写方法时要写"
 
 使用方式：把它复制进下一次制作的 `work_dir`。写稿阶段只在文件存在时阅读它，
 并可在 `recap_story_plan.json` 的可选字段 `reference_methods` 记录每条方法的 adopt / adapt / skip。
-它是参考，不是配额：与新素材的证据冲突时以素材为准。没有任何脚本读取它，也不会因为它的存在改变任何阶段的通过与否。
+采用时以新素材证据为准，不把参考数值当作配额。没有任何脚本读取它，也不会因为它的存在改变任何阶段的通过与否。
 
 `U/` 里的 breakdown 与 `reference_frames/` 含原片事实和画面，只留在本地，不要复制或提交。
 

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

@@ -1,6 +1,6 @@
 # 制作参考：字段、枚举与示例
 
-本文件只列字段与枚举；剧作与剪辑手法的具体规则以后续写稿阶段自己的手册为准，这里不复述。
+按本文件填写测量标注、事实与可迁移方法。后续写稿阶段自行决定是否采用方法。
 
 ## 标注词表