@oh-story/dsh 0.1.10 → 0.1.11

package/lib/video-recap/skills/video-recap/references/creative-editing-playbook.md

@@ -1,225 +0,0 @@
-# 创作剪辑工作法
-
-本参考只规定 Agent 的创作判断，不增加渲染模块。进入剪辑或写稿前，先完成这里的决策，再写 `clip_plan.json` 或 `narration.json`。
-
-## 先判断创作控制模式
-
-- **CREATE**：没有既定成片方向，可以比较故事/剪辑假设并选择。
-- **DIRECTED**：用户已经指定结构、镜头、台词或表达，目标是准确落实而不是展示替代创意。
-- **REVISION**：基于已有版本看片修改。最新反馈覆盖旧决定；本轮未点名内容默认冻结。
-
-REVISION 先列本轮修改项与冻结项。表达、节奏、字幕意见写回 `style_card.json`，镜头与声音意见写回 `visual_audio_board.json`；只有故事主线改变才更新 `recap_story_plan.json`。删除内容时也删除过期的计划描述。完成后分别验证“该变的确实变了”和“不该变的没有漂移”。
-
-## 决策优先级
-
-硬约束先于审美：
-
-1. **证据真实**：人物、关系、因果和结果必须由画面、对白、可靠背景或用户上下文支撑。
-2. **声音可懂**：关键原声不能被截成半句，旁白不能把必须听见的对白完全盖住。
-
-硬约束满足后，发生冲突时按以下顺序取舍：
-
-1. 情绪与人物；
-2. 故事推进；
-3. 节奏；
-4. 视线与画面连续；
-5. 技术上的“绝对工整”。
-
-不要为了连续而牺牲人物反应，也不要为了快而删掉真正改变观众感受的瞬间。
-
-## 五次专业判断
-
-### 1. 导演：先决定观众经历什么
-
-先回答，而不是先写开场文案：
-
-- 观众承诺：看完具体会理解、担心或感受到什么？
-- POV：这条内容主要跟随谁的经历？谁不是主视角？
-- 戏剧问题：观众一直想知道的那个问题是什么？
-- 情绪路径：开头的情绪如何变成结尾的情绪？
-- 隐瞒与揭示：什么信息暂时不说，何时揭示才最有力量？
-- 结尾余味：答案落地后，观众最后应留下什么感受？
-
-CREATE 至少提出两个可成立的剪辑假设，再选一个。比较的是叙事效果，不是措辞：例如“按主角认知逐步揭示”与“先展示后果再追问原因”。DIRECTED / REVISION 沿用用户指定或已确认的主线，不为满足模板重新发散。只记录当前选择与理由，不输出冗长思维过程。
-
-### 2. 故事编辑：把素材组织成变化
-
-beat 不是固定秒数、场景名或一句旁白；beat 是一次可感知的变化。每个保留 beat 至少改变一项：
-
-- 观众知道了什么；
-- 人物想要什么；
-- 谁占上风；
-- 关系如何移动；
-- 情绪如何转向；
-- 风险或代价如何升级。
-
-如果移除一个 beat 后，因果、人物或情绪都没有损失，它通常不值得占用成片时间。钩子必须提出这条故事真正会兑现的问题，不能制造正文不回答的夸张承诺。
-
-### 3. 画面剪辑：选择时刻，而不只选择事件
-
-对每个 beat 做以下判断：
-
-- **入点**：能否晚一点进入，跳过已经能推断的铺垫？
-- **出点**：信息或情绪落地后，能否早一点离开？
-- **表演**：说话者与倾听者谁更能承载此刻？动作与反应谁更重要？
-- **不可替代瞬间**：停顿、迟疑、失误、眼神、动作声音中，哪一个让人物变得真实？
-- **节奏**：这一拍需要冲过去，还是需要多停半秒让含义落地？
-- **边界**：优先完整动作、完整台词和自然声音边界；不要机械地把每个片段切成同一长度。
-
-进入 `clip_plan.json` 的不是“发生过的所有重要事件”，而是最能让观众经历这条主线的具体时刻。
-
-目标不是绝对最短，而是**最短但完整**：晚进不能丢掉理解动作所需的前提，早出不能吃掉表演的回报。建立空间和事实的镜头通常可以短；关键对视、亲吻、受伤反应、决定落地或沉默可以多停一点，让观众先感受到再离开。
-
-场景之间的 IN / OUT 也要有任务：
-
-- 新人物、地点或情绪场景，先给画面一个可感知的建立时刻，再让旁白进入；旁白不必与画面同帧起跑。
-- OUT 优先落在动作完成、反应落地、台词句末、沉默结束或干净硬切前。
-- 不要在原片叠化、闪白或其他转场的中间再切一次。转场至少由画面变化、动作延续、声音接力或叙事跨越中的一项驱动。
-
-scene-change score、逐帧亮度和接点 contact sheet 只用于诊断：检查每个接点前后约 0.5–1 秒，定位硬切、白闪或曝光叠化候选。修复优先收进稳定镜头、保留原片完整转场的一侧、扩展源素材，或用相邻有效镜头补足时长；不能为了视觉干净切断台词。最终必须真实播放接点，不能把检测分数当成观看结论。
-
-对短时间频繁切镜头的段落，先用 ffmpeg scene filter 输出候选时间，例如：
-
-```bash
-ffmpeg -i input.mp4 -vf "select='gt(scene,0.35)',showinfo" -an -f null -
-```
-
-阈值只用于召回候选，闪白、叠化和大幅运动都可能误报。把候选映射回 source 区间和成片拼接边界后再分类处理：
-
-- **原片切点**：无关的短镜头按完整 source shot 删除；相关但停留过短、看起来像闪一下的镜头，向前/后扩展到完整动作、反应、台词或下一个干净切点。这里的“拉长”是多保留真实源素材，不默认用定格或慢放制造不存在的表演。
-- **本次剪辑制造的切点**：优先移动 IN / OUT、恢复同一源镜头的连续运动、合并相邻片段，或换成有叙事任务的连接镜头；能消除就不保留。溶解、闪白和包装不能用来遮掩坏接点。
-- **有意的原片蒙太奇**：只有当每个短镜头都提供新信息、动作或节奏回报，且正常播放仍清楚可读时才保留；否则按无关或过短镜头处理。
-
-密集度不是单一固定秒数门槛。先找同一短窗内的连续候选，再以正常速度播放判断观众感受到的是有效节奏还是闪烁。
-
-### 4. 声音与旁白：先分工，再写字
-
-每个 beat 先指定一个主要 `audio_owner`：
-
-- `original_dialogue`：原对白本身就是事件或表演；
-- `action_sound`：动作声音承担冲击、因果或空间感；
-- `ambience` / `music`：环境或音乐承担情绪；
-- `silence`：沉默、停顿或呼吸是内容；
-- `narration`：画面和原声无法独自交代必要的上下文、因果或预期。
-
-只有当旁白有明确工作时才写。`narration_job` 只能从以下任务中选择：
-
-- `context`：补充看不见但必要的背景；
-- `causal_link`：连接被压缩掉的因果；
-- `foreshadow`：建立稍后会兑现的预期；
-- `interpretation`：基于证据指出人物选择、关系或代价；
-- `transition`：跨越时间、地点或素材来源；
-- `none`：画面、原声或沉默已经足够。
-
-`7:3` 只可作为没有更好判断时的粗略首稿参考，不是质量目标或覆盖配额。强对白可以让一个 beat 完全没有旁白；信息密集的压缩段也可以由旁白主导。
-
-旁白拥有一个 beat 时，先写成一个连续思路，常见推进是“前提 → 触发动作 → 变化/意义”。句子数量不是目标；一个完整长句或少量相连句都可以，关键是一次 TTS 能自然说完而不是一句一停。字幕可以为阅读拆成多个 cue，但不能反过来把朗读稿切成碎 utterance。
-
-“不是 A，而是 B”只在素材确实需要纠正一个可能的旧判断时有价值。不要先虚构错误判断，再用肯定句制造洞察；能直接写动作、因果和后果时就直接写。
-
-### 5. 观众复核：从第一次观看出发
-
-完成草案后做三次反事实检查：
-
-1. **静音旁白**：只看画面和原声，人物、变化和关键情绪是否仍可感知？
-2. **只听声音**：旁白是否形成一条可听懂的主线，而不是字幕腔或画面复述？
-3. **第一次观看**：开头承诺了什么、每一拍又打开了什么问题、结尾是否真正回答？
-
-再逐 beat 追问：
-
-- 删除它，什么会坏？什么都不坏就删。
-- 换成反应镜头，情绪是否更强？
-- 旁白改成原声或沉默，含义是否更好？
-- 提前揭示或延后揭示，哪一个更符合 POV？
-- 能否晚进、早出，而不损失理解？
-
-只优先处理 1–3 个最高回报修改，避免用大量低价值润色掩盖结构问题。
-
-准备交付时，把抽象的“第一次观看”落实成动作：正常速度完整播放实际最终文件；逐个播放接点前后；完整只听声音；再单独复看开头、核心情绪点和结尾。脚本、样帧与自动 QC 只能辅助定位，不能替代完整观看。
-
-## Agent 创作产物
-
-这些是简洁的决策记录，不是公开的完整思维过程。CLI 可以忽略它们，但后续 Agent 与建议型评审会使用它们保持创作一致。
-
-### `recap_story_plan.json`
-
-```json
-{
-  "schema_version": 1,
-  "director_intent": {
-    "viewer_promise": "观众最终得到的具体体验",
-    "pov": "主要跟随谁，以及为什么",
-    "dramatic_question": "贯穿全片的问题",
-    "emotional_start": "起始情绪",
-    "emotional_end": "结束情绪",
-    "ending_aftertaste": "最后余味",
-    "withhold_reveal": "保留什么，何时揭示"
-  },
-  "hypotheses": [
-    {"id": "h1", "spine": "方案一主线", "opening": "如何进入", "ending": "如何落地", "risk": "主要风险"},
-    {"id": "h2", "spine": "方案二主线", "opening": "如何进入", "ending": "如何落地", "risk": "主要风险"}
-  ],
-  "chosen_hypothesis": "h1",
-  "choice_reason": "为什么它更符合素材中的人物、故事和情绪",
-  "beats": [
-    {
-      "beat_id": "b01",
-      "source_id": "可选，多视频时填写",
-      "source_start": 12.0,
-      "source_end": 20.0,
-      "function": "hook|setup|turn|escalation|payoff",
-      "event": "可观察到的事件",
-      "change": "knowledge|power|emotion|goal: before -> after",
-      "audience_question_in": "进入前观众想知道什么",
-      "audience_question_out": "离开时答案或新问题是什么",
-      "character_focus": "此拍由谁承载",
-      "must_keep_moment": "不可替代的动作/表情/台词/声音",
-      "evidence": ["visual", "asr"]
-    }
-  ]
-}
-```
-
-上例是 CREATE 形态。DIRECTED / REVISION 可以只保留用户指定或当前采用的假设；不要复制一个虚假备选来凑数量。
-
-### `visual_audio_board.json`
-
-```json
-{
-  "schema_version": 1,
-  "items": [
-    {
-      "beat_id": "b01",
-      "source_id": "可选，多视频时填写",
-      "source_start": 12.0,
-      "source_end": 20.0,
-      "output_start": null,
-      "output_end": null,
-      "picture_job": "orientation|evidence|performance|reaction|action|contrast",
-      "preferred_moment": "具体要保留的画面时刻",
-      "entry_reason": "为什么从这里进入",
-      "exit_reason": "为什么在这里离开",
-      "audio_owner": "original_dialogue|action_sound|ambience|music|silence|narration",
-      "original_audio_anchor": "要完整保留的对白/动作声/停顿",
-      "narration_job": "none|context|causal_link|foreshadow|interpretation|transition",
-      "handoff": "前后画面、原声与旁白如何接力"
-    }
-  ]
-}
-```
-
-cut 第一阶段先用原片时间写；`edited_source.mp4` 产生后，在第二阶段补上输出时间并重新确认 `audio_owner` / `narration_job`。
-
-## 内容质量基线
-
-进入 TTS 前，以下问题都必须能用具体 beat 回答；否则先改计划或脚本：
-
-1. **承诺**：开头提出的真实问题，结尾是否兑现？
-2. **主线**：是否有一个明确 POV 和一条主导因果/关系线？
-3. **变化**：每个 beat 是否改变知识、权力、目标、关系、情绪或风险？
-4. **人物**：是否保留了至少一个不能由剧情概述替代的表演/反应瞬间？
-5. **视听分工**：每个 beat 是否明确由画面、原声、沉默或旁白中的谁主导？
-6. **必要性**：旁白是否都在增加信息或期待，而不是复述像素？
-7. **完整观看**：实际最终文件是否完整看过、逐接点看过并只听声音检查过？
-
-这套基线与抖音、YouTube 或任何平台数据无关。先让内容本身成立，再讨论标题、封面、时长档位和发布优化。

package/lib/video-recap/skills/video-recap/references/research-guide.md

@@ -1,74 +0,0 @@
-# 背景调研指南（可选）
-
-Agent 在开始视频理解**之前**先做背景调研，确认作品名、角色关系、剧情背景或科普概念，写入 `work_dir/background_research.json`。理解阶段会把它并入 VLM 的画面分析上下文，让场景描述能直接叫出人物名字、带着剧情读画面，而不是把人都标成「黑衣男子」。**调研不是必需步骤**；没有浏览器工具、网络不可用或用户未提供明确片名时，直接跳过，不阻塞视频生成。
-
-## 工具选择
-
-使用当前环境里可用的任意检索方式即可，例如：
-
-- Codex / Claude 自带的联网搜索或网页浏览工具
-- 用户已经配置好的浏览器自动化或页面读取工具
-- 普通浏览器手动查找后把结果整理进 JSON
-- 已知资料、用户给的剧情背景或项目内已有文档
-
-## 通用流程
-
-1. 从 `--context`、文件名或用户描述里提取可搜索关键词。
-2. 搜索 1-3 个高价值问题，不要过度调研。
-3. 只记录对解说有帮助的事实：人物关系、剧情前提、世界观、当前集上下文、术语解释。
-4. 写入 `work_dir/background_research.json`。
-5. 如果查不到可靠信息，跳过调研并继续视频理解；不要在理解索引生成前提前写 `narration.json`。
-
-## 按视频类型搜索策略
-
-### 短剧 / 电视剧
-
-| 搜索关键词 | 目标字段 |
-|-----------|---------|
-| `{作品名} 剧情 介绍 人物` | synopsis, characters |
-| `{作品名} 人物 关系` | characters |
-| `{作品名} 第{N}集 剧情` | episode_context |
-
-### 电影
-
-| 搜索关键词 | 目标字段 |
-|-----------|---------|
-| `{电影名} 剧情 简介` | synopsis |
-| `{电影名} 影评 解读` | cultural_notes |
-
-### 纪录片 / 科普视频
-
-| 搜索关键词 | 目标字段 |
-|-----------|---------|
-| `{主题} 背景 知识` | worldbuilding |
-| `{核心概念} 解释` | synopsis |
-| `{主题} 最新 进展` | cultural_notes |
-
-## 写入格式
-
-写入 `work_dir/background_research.json`，只填搜到的字段，未搜到的字段省略，不要写 `null` 或空字符串。
-
-```json
-{
-  "synopsis": "...",
-  "characters": {
-    "角色名": "简介或关系"
-  },
-  "worldbuilding": "...",
-  "episode_context": "...",
-  "cultural_notes": [
-    {"item": "...", "explanation": "..."}
-  ]
-}
-```
-
-## 错误处理
-
-| 场景 | 处理 |
-|------|------|
-| 没有浏览器 / 搜索工具 | 跳过调研，继续视频理解 |
-| 搜索无结果 | 换一组关键词重试一次，仍无结果则继续视频理解 |
-| 结果互相矛盾 | 只使用用户提供的上下文或画面/ASR 可验证的信息 |
-| 信息可能剧透后续 | 只用于理解人物关系，不在解说里剧透用户没要求的后续剧情 |
-
-**原则**：背景资料只能补上下文，不能替代 `vlm_analysis.json` / `asr_result.json` 里的画面和对白证据。

package/lib/video-recap/skills/video-recap/references/timeline-and-jianying.md

@@ -1,250 +0,0 @@
-# Multi-track timeline (`timeline.json`) + optional 剪映 export
-
-`video-assemble` always emits `timeline.json`: a backend-neutral description of
-the finished recap. ffmpeg remains the canonical renderer; the optional 剪映
-exporter consumes the same timeline to make an editable sidecar draft. Timeline
-times are seconds and volumes are gains, so this file has no 剪映-only units.
-
-## `timeline.json` schema v2
-
-```jsonc
-{
-  "schema_version": 2,
-  "canvas": {"width": 1280, "height": 720, "fps": 25},
-  "duration": 315.0,
-  "tracks": [
-    {"kind": "video", "name": "video", "clips": [
-      {"source_path": "/orig.mp4",
-       "source_start": 243.0, "source_end": 268.0,
-       "timeline_start": 0.0, "timeline_end": 25.0,
-       "audio": {"role": "original", "base_gain": 0.85,
-                 "volume_keyframes": [{"t": 0.0, "gain": 0.85},
-                                       {"t": 2.19, "gain": 0.2}]}}
-    ]},
-    {"kind": "audio", "name": "narration", "role": "narration", "segments": [
-      {"source_path": "/_placed_0000.wav", "timeline_start": 2.19,
-       "timeline_end": 5.9, "gain": 1.0, "text": "…",
-       "overlaps_speech": true,
-       "source_duck_end": 6.1, "source_restore_at": 6.35,
-       "source_handoff_status": "sentence_boundary"}
-    ]},
-    {"kind": "audio", "name": "bgm", "role": "bgm", "loop": true,
-     "segments": [{"source_path": "/bgm.mp3", "timeline_start": 0.0,
-                    "timeline_end": 315.0, "gain": 0.18,
-                    "volume_keyframes": []}]},
-    {"kind": "text", "name": "subtitle", "segments": [
-      {"text": "…", "timeline_start": 2.19, "timeline_end": 5.9}
-    ]},
-    {"kind": "image", "name": "image", "segments": [
-      {"source_path": "/card.png", "timeline_start": 3.0,
-       "timeline_end": 7.0, "opacity": 0.8, "rotation_degrees": 0,
-       "scale": {"x": 0.5, "y": 0.5},
-       "position": {"x": 0.25, "y": -0.2},
-       "flip": {"horizontal": false, "vertical": false}}
-    ]}
-  ]
-}
-```
-
-- **video** — source clips plus editable original-audio volume automation. In
-  cut mode, explicit `--source-video` keeps references on the real source ranges.
-- **narration** — placed TTS segments. `source_path` points to the exact complete
-  per-segment PCM used by the canonical mix (`_placed_*.wav`), never a longer
-  pre-fit file that an editor would trim at `timeline_end`.
-- **bgm** — optional looped music with its own volume automation.
-- **subtitle** — display-ready narration subtitles.
-- **image** — optional local photo overlays. Transforms use normalized
-  canvas-center coordinates with positive Y upward. `build_timeline(...,
-  image_segments=[...])` is currently the programmatic entrypoint; recap does
-  not invent image overlays automatically.
-- `volume_keyframes` are timeline-absolute `{t, gain}` points with linear ramps.
-  Original-audio handoff keyframes stay low through the final source phoneme
-  (`source_duck_end`) and release only inside the measured sentence pause, reaching
-  idle at `source_restore_at`; ffmpeg and the editable timeline share this shape.
-
-Schema v2 also has additive JianYing authoring fields. Existing v1 timelines
-are copied and migrated to v2 at the exporter boundary; an unknown future
-schema version is rejected instead of being guessed:
-
-- video clips may add `speed`, `reverse`, `reverse_path`, `opacity`,
-  `rotation_degrees`, `scale`, `position`, `flip`, `transition`, `mask`, `lut`,
-  `compound`, `chroma`, and `green_background`;
-- audio/image segments may add constant `speed`; image segments may also add
-  `transition`, `mask`, and `lut`;
-- text segments may add `style`, `style_id`, `words`, and the same visual
-  transforms. `words[].index` / `length` are UTF-16 code-unit ranges, matching
-  JianYing and Java rather than Python code-point indexes;
-- top-level `style_presets` is a name-to-style object;
-- top-level `resource_packages` is a name-to-offline-package object;
-- `build_timeline(..., extra_tracks=[...])` appends explicit `sound`, `sticker`,
-  `text_template`, `video_effect`, or `face_effect` tracks without making the
-  normal recap pipeline invent proprietary effects.
-
-For a video clip with constant speed, the authored ranges must satisfy
-`source_end - source_start == (timeline_end - timeline_start) * speed`; an
-inconsistent clip is rejected. Image and resource segments derive that source
-duration automatically. This keeps source selection unambiguous.
-
-## Optional 剪映 / JianYing export
-
-`--export-jianying` / `EXPORT_JIANYING=1` maps the timeline into a folder with
-`draft_content.json`, `draft_info.json`, and `draft_meta_info.json`. The current
-adapter aligns its local-draft contract with
-[`duoec/duo-video`](https://github.com/duoec/duo-video) commit
-`ef4eb46c823910553f901649f2f13fd7575e748f`:
-
-- root schema profile `version: 360000`, `new_version: 111.0.0`, and template
-  `app_version: 5.9.5-beta1`, including `common_mask` in the material skeleton;
-- all segment times converted to integer microseconds at one boundary;
-- narration interval ends are rounded outward before that conversion, and export
-  probes bundled PCM duration; this prevents timestamp rounding from shaving even
-  a few samples from the final word;
-- narration and BGM as audio tracks, video/photo as video tracks, subtitles as
-  text tracks; regular segments use the schema `render_index` /
-  `track_render_index` value `2`;
-- subtitle materials use `type: subtitle`, with a zero-based full
-  `source_timerange` and timeline placement in `target_timerange`;
-- native `KFTypeVolume` keyframes and split BGM loops remain editable;
-- true half-open interval allocation: adjacent segments reuse a track, while
-  overlapping image/video/text material is moved to a numbered sibling track;
-- same-type first tracks use `flag: 0`; additional tracks use `flag: 2`.
-
-The upstream README's “verified with 剪映 v10.1.0” is an application smoke-test
-claim. The embedded `5.9.5-beta1` value is the upstream JSON template profile;
-it is **not** a claim that this project installs or emulates 剪映 5.9.5. We keep
-those two facts separate and do not promise compatibility with every desktop
-release without a real-app smoke test.
-
-### Portable media bundle
-
-Bundling is on by default because a clone or moved project must open without the
-original machine's absolute paths. The writer copies and de-duplicates media to:
-
-```text
-Resources/local/video/
-Resources/local/audio/
-Resources/local/image/
-```
-
-Material paths in `draft_content.json` use 剪映's
-`##_draftpath_placeholder_…_##/Resources/local/...` form. Type-0 entries in
-`draft_meta_info.json` index each copied file with `file_Path`, `metetype`
-(`video` / `music` / `photo`), ID, MD5, duration, dimensions, import timestamps,
-and rough-cut/sub ranges. Filename collisions are resolved within each resource
-kind. Missing media is reported and left as an honest external reference rather
-than being recorded as successfully bundled.
-
-`--jianying-no-bundle-media` is only for environments where 剪映 can reach the
-original paths. It trades portability for avoiding a copy and is not the
-recommended clone-ready workflow. Non-empty draft folders are never overwritten;
-a numbered sibling such as `recap_demo_2` is created. The entire folder is staged
-and atomically renamed, so a copy/write exception does not publish a half-draft.
-
-### Duo-video capability alignment
-
-The adapter is pinned to `duo-video@ef4eb46`; it deep-copies the upstream MIT
-JSON templates before replacing authored values. Core categories use status
-`supported`; proprietary-resource categories use
-`supported_offline_payload`. The latter means a pre-adapted material/segment
-protocol can be emitted from caller data. It does **not** mean this project
-ships JianYing's proprietary resource catalog or reconstructs it from an ID.
-
-| Capability | Timeline authoring | Output |
-| --- | --- | --- |
-| Video / local photo / audio | normal `video`, `image`, `audio` tracks | `materials.videos` / `audios`; photos use `type: photo` |
-| Text / subtitle / style | `text` track plus `style`, `style_id`, `words`, `style_presets` | UTF-16 rich-text styles, font/stroke/shadow/background/effect-style payloads |
-| Constant speed | `speed > 0` on video/audio/image/resource segments | segment speed plus referenced `materials.speeds`; curve speed is not claimed |
-| Reverse | `reverse: true`, optionally `reverse_path` | export generates a local reversed file with ffmpeg when needed, then bundles it; direct `build_draft()` requires `reverse_path` |
-| Transform | opacity, rotation, scale, normalized position, flip | editable segment `clip` transform |
-| Sound / sticker / video effect / face effect | explicit resource track with one offline material source | `audios`, `stickers`, or `video_effects` plus the matching track |
-| Text template | explicit resource track with pre-adapted template/text/effect payloads | `text_templates` plus caller-supplied subordinate `texts` / `effects` |
-| Transition / mask / LUT | object or package name on a video/photo segment | referenced `transitions`; legacy + `common_mask`; LUT/skin-tone `effects` |
-| Green screen / compound | video clip with `compound`, local `green_background`, and `chroma` | nested `materials.drafts` with recursively bundled foreground/background |
-
-Resource-backed segments must define exactly one of:
-
-```jsonc
-{"material": {"type": "sticker", "resource_id": "...", "path": "/local/file"}}
-{"resource_config": {
-  "resource_id": "...",
-  "main_config": {"type": "sticker", "path": "/local/file"},
-  "resources": [
-    {"source_path": "/local/file"},
-    {"source_path": "/local/package-dir", "target_path": "package-dir"}
-  ],
-  "cover_img": "/local/cover.png",
-  "texts": [],
-  "effects": []
-}}
-{"resource_package": "named-package"}
-```
-
-`resource_package` resolves a top-level `resource_packages` entry with the same
-canonical snake_case object shape as `resource_config`. `main_config` must be an
-object; callers adapt any external Jackson `JyResource` or JSON-file input before
-passing it to this skill.
-
-`resources` is an explicit local-file contract, never a filesystem guess. A
-descriptor must contain `source_path` and may additionally set `resource_kind`
-and a safe package-relative `target_path`. ZIP input is
-validated against path traversal, extracted under
-`Resources/local/<kind>/<archive-stem>`, and keeps its internal layout. Exact
-declared path values in material JSON, including rich-text JSON strings, are
-rewritten to draft placeholders. Missing declared resources, unsafe targets,
-unknown package names, and malformed payloads fail explicitly; semantic strings
-that happen to match local filenames are never copied. No network lookup,
-embedded demo credential, or silent resource-ID fallback is used.
-
-LUT skin-tone correction additionally requires an offline effect
-`main_config` with `lumi_hub_path`; the adapter emits the upstream `version: v3`
-skin-tone effect rather than deriving an effect directory from the `.cube`
-file's parent.
-
-Text-template **protocol emission** accepts the output of an offline template
-adapter in `main_config` / `texts` / `effects`. This repository does not bundle
-or download duo-video's separate `jy_text_template_adapter`, so it does not
-claim that an arbitrary official resource ID plus replacement strings can be
-adapted locally. The same boundary applies to official stickers/effects: callers
-must legally supply complete offline package data.
-
-## Isolation and failure behavior
-
-- Export modules are lazy-imported only after `--export-jianying`; the ffmpeg
-  render path does not import or depend on them.
-- The adapter is Python stdlib + ffprobe only; no vendored package is required.
-- Export failure is logged and never invalidates an already-rendered ffmpeg MP4.
-- The source clip is un-burned, so hardcoded source subtitles remain visible in
-  the editable draft. ffmpeg remains the authoritative final mix.
-
-## Verification boundary and manual smoke checklist
-
-Automated golden tests compare root, video, audio, text, rich-text, and
-base-segment templates against the pinned upstream revision. Structural tests
-cover compound/meta output and exercise every row in the matrix. On macOS,
-JianYing Pro `10.8.7-beta1` detected and registered a generated bundled smoke
-draft (`copy_draft_external`, `errno: 0`). Manual verification then opened it,
-confirmed online video/narration/BGM/subtitle/photo tracks and a valid preview,
-saved it, closed it, and reopened it with the same editable timeline. This does
-not prove that every caller-supplied official resource package renders correctly.
-
-AutoJY is a separate desktop-automation/export pipeline in the duo-video
-ecosystem, not part of the draft JSON protocol. This repository does not ship or
-claim AutoJY UI automation, rendered-file upload, task-status callbacks, or an
-automated final-video export smoke test.
-
-With a desktop 剪映 install, generate a bundled draft and verify:
-
-1. it appears in the draft list;
-2. video, narration, BGM, subtitles, and photo overlays are online/editable;
-3. subtitle semantics, track order/flags, and overlap lanes survive reopening;
-4. volume automation is visible/audible;
-5. no absolute-path/offline-media warning appears.
-
-## Acknowledgements
-
-The draft schema also follows
-[pyJianYingDraft](https://github.com/GuanYixuan/pyJianYingDraft) and
-[capcut-mate](https://github.com/Hommy-master/capcut-mate) (Apache-2.0). The
-duo-video alignment independently implements the builders and vendors only the
-pinned JSON protocol templates under duo-video's MIT license; no upstream
-executable code, resource package, adapter binary, or credential is vendored.