素材首次入库、同商品资料复用或剪辑前查找背景音乐时，按需读取相邻 reusable-material-library/SKILL.md 及其类型说明。先复用已有理解，再补实际缺口；采用结果交原消费者并回读实际产物。

任务方案与交付

当前运行 Agent 在本阶段前读取相邻 ecommerce-operations/references/task-execution.md，沿用本任务最新有效方案和适用偏好，按真实结果交付并记录成功操作。已在同一任务读取时直接复用；不反向重启总控或重复业务动作。Agent 主导顺序、分支与恢复，本 Skill 返回实际结果和正式恢复线索。该参考暂不可读时说明缺口并继续当前可执行工作，不新增文档或格式硬门槛。

Video Editor Runner

Use this skill only as the deterministic execution layer between reviewed segments and final-render review. Do not choose selling points, rewrite copy, reorder the story, decide what footage to remove, or publish the result.

creation_mode=product_asset_remix_v2 使用 plan_driven_remix_render.py。Runner 只执行 reviewed remix-execution-plan-v1 的 operation graph：先按删除区间生成无卡顿主轨，再按方案插入/覆盖 B-roll，逐片段执行 keep/mute/duck/replace 音频决定，最后烧录已冻结字幕。源文件始终只读；可恢复的方案投影、时间线或配置差异返回诊断，Agent 通过原登记/编译入口恢复；实际媒体变化须登记新 revision。manual 方案消费原 review sidecar，不改写方案正文；无 B-roll 和静音主轨均可执行。该路径不生成卖点、不选择 recipe、不调用 TTS/AI 审核 Provider，成功输出绑定方案 lineage 的 video-edit-manifest-v3。

plan_driven_autonomous_v1 的 canonical edit request 可明确表达 narration.mode=none + source_audio.mode=mute。此时 timeline 不要求伪造 narration beat/voiceover，TTS 返回 not_applicable，最终 manifest 写入 audio.narration_mode=none / tts_status=not_applicable；全静音音轨不执行 loudnorm。有口播路径必须使用任务主档投影的 task-operation-authorization-v1；TTS executor 为每次实际网络提交创建独立 operation，主档统一裁决预算和防重，TTS submit ledger 只记录执行证据。历史 central-action-authorization-v1 只读兼容。

商品原创剪辑

商品原创视频剪辑时，读取 product-original-workflow.md。同一任务兼有多个分支时读取对应分支；其中的原有条件、顺序和例外继续适用。

Workflow

1. Read references/input-output-contract.md before preparing or executing a request.
2. Confirm edit_request.json has schema_version=edit-request-v1/v2/v3/v4/v5, source paths and hashes, and an output path different from every source. V1–V3 require concrete keep_ranges; V4 requires one atomic integer-PTS source_range per item plus rational playback rate, semantic shots, narration beats, evidence ref and exact output range. creation_mode=video_replication / womenswear_template_video_v1 还必须携带 hash 绑定的 generation_closeout。Runner 会回读 exact required output set、binding、Provider success observation、verified-video-download-manifest-v2、完整解码证据、媒体 SHA 和 recovery ledger；任一缺失、伪造或漂移都在 FFmpeg 前返回 dreamina_required_segment_unresolved。 视频复刻新请求还必须提供 hash 绑定的 source_review_lineage[]；任一源审核为 regenerate_required / blocked、持续商品身份错配或血缘漂移时拒绝执行。裁剪、放大、overlay 或遮挡不能作为持续商品错配的修复方式，成功 manifest 必须原样保留该血缘供 final review 回读。 V2 BGM must be an active douyin-music-library asset whose account_scope equals target_account_id; never download music in this skill or reuse another account's asset. 普通多账号 V3 剪辑使用其账号配置；V4/V5 按各自已有模式合同消费。 Resolve the target account through resolve_edit_profile.py; require an active, hash-locked account-video-edit-profile-v1 whose account_scope equals target_account_id, plus hash-verified runtime font assets. Never fall back to another account or the legacy global style. precision_trim additionally requires one hash-locked auto-trim-plan-v1 with semantic_preservation=passed, 正整数 auto_trim_attempt, matching account/product/source video, and exact keep_ranges. Never infer or alter the trim ranges here. V5 仅按既有 creation_mode=product_asset_remix_v1 消费多源原子时间线，读取 输入输出合同 的 V5 段；V2 客户方案渲染沿已有 plan-driven 入口，不把 V5 作为所有模式的默认请求。
3. Reject unresolved values such as from_storyboard_shots; require concrete subtitle and voiceover cues or verified audio assets. Default replication segments that already contain generated audio and burned-in captions may instead use explicit preserve_source_audio / preserve_burned_in policies. These policies never synthesize new content, require an existing source audio stream, and remain subject to final review. For audio_first_seedance_experimental_v1, first run prepare_spoken_audio.py; after generated segments are downloaded, run verify_seedance_audio.py, then use audio_first_edit_adapter.py to materialize and execute a standard edit-request-v1 through the existing runner. For guide_voice_then_tts_experimental_v1, first run build_guide_voice_windows.py to derive deterministic sentence-target-windows-v2 from the reviewed Storyboard, fidelity mapping and locked timeline; no guide-audio transcription is performed. Resolve the account TTS profile, then run guide_voice_tts_adapter.py --prepare only after reference fidelity passes. tts_decision=no_tts returns tts_not_required; only use_tts can create a Provider request. New executions require task-bound authorization and run the fixed-input FFmpeg media preflight before reading the Speech API Key. Fixture decode failure, empty PCM, runtime drift during the same authorization, locked-video drift and window overflow remain objective failures; a valid non-empty decode whose PCM hash differs across FFmpeg builds is recorded as fixture_pcm_hash_drift / diagnostic_disposition=continue and does not consume another plan revision. Provider semantics and timestamps come only from submitted source text plus hash-bound Provider subtitle evidence. 对 plan-driven V4，只要批准方案为完整口播并使用 TTS，pre_tts_edit_request.json 就只用于冻结并本地渲染无声锁片，不能直接交付。guide_voice_tts_adapter.py --materialize 必须回读 visual-lock-manifest-v2、锁片、账号 edit profile、唯一 TTS manifest 和 Provider 时间戳，验证 atomic timeline 未漂移后清除 pending 状态。若方案不显示口播字幕，只挂载一次连续配音，正式请求保持 subtitle_materialization=not_required、空字幕轨和 omit_by_execution_plan；否则按 Provider 时间戳物化字幕。锁片后本地失败只允许零 Provider 修复。 After Provider audio is stored, run continuous_tts_audio_integrity.py: undecodable, empty, silent or invalid audio is an objective failure; repeat windows, abnormal word gaps and clipping are diagnostics with owner-only listenable slices and an explicit Codex disposition. No transcript similarity, homophone comparison or independent ASR participates in correction or blocking. A successful new asset is continuous-tts-manifest-v4 and binds tts-audio-validation-v1, Provider subtitle evidence, media preflight and the exact audio. Offline revision and recovery never access Provider and must rerun the same audio-integrity and subtitle-layout checks before producing V4. Recovery accepts a terminal source receipt authorized by current task-operation-authorization-v1 / video_generation_task_record only when its task root, task authorization, plan revision, execution identity and single-call limits are complete; it reuses the already returned audio and never consumes another Provider call. A leading semantic word with a Provider-confirmed zero-length interval may be repaired from the next positive start, or by deterministically splitting the next positive interval when both words share the same start; every other non-positive semantic interval still fails closed. A reviewed audio-integrity continue decision may be carried into a fresh immutable recovery only when regenerated audio SHA, PCM facts, media probe, thresholds, diagnostic signature, semantic source, subtitle evidence SHA and listenable slices all match; the new receipt records the decision source. When Provider punctuation groups multiple business sentences into one subtitle sentence, a local timing revision must retime the original V4 sentences[] through the same piecewise mapping instead of replacing their segmentation with Provider groups. Materialization accepts current task-record authorization only after rereading the same run/account scope, succeeded TTS operation, Provider request ID, revision/execution identity, consumed budget and empty unresolved set. Historical V2/V3 manifests, tts_asr, guide_asr and acoustic-review receipts remain read-only compatible only; they cannot start or resume a Provider call and never become inputs to new semantic decisions. Plan-driven task-level narration uses hash-bound narration_revision + creative_execution_plan; materialization preserves every V4 atomic source/output range and source-review lineage, splits verified Provider subtitle cues at atom boundaries, and attaches the continuous TTS asset exactly once. Both strong replication modes may consume prepare 阶段正式生成的 storyboard_actual_shot_locked_timeline，但必须回读 hash-bound sentence_window_source + storyboard + creative_execution_plan，且 V2 窗口、锁片、业务句和 plan revision 完全一致；shot-content 当前窗口还必须回读 passed reference-fidelity report，并逐项重验 target-to-actual shot 映射。物化器与渲染器必须在 final_timeline 中消费同一证据集合，不得补造空 guide_asr。closing silence 是实际音画事实，由执行模型判断；不改变已确认口播文案。 With replication_mode=shot_content_faithful_v1, derive sentence windows from the fidelity report's hash-bound approved-target to actual-shot mapping and actual shot timecodes. Skip only Storyboard mappings explicitly approved as decision=omit with empty target shots and an omission reason; every non-omit target still requires actual-shot evidence. When placement needs recovery, the existing optimizer may expand into contiguous adjacent approved planned shots, including after real Provider timing is known; 85% is a placement preference, not a materialization gate; record the original/effective overlap and borrowed target/actual shot ids. Materialization must verify the V4 recovery receipt, revalidate every expansion against the immutable adjacent windows, and use the effective window for final subtitle/speech alignment. Record both target_shot_ids[] and actual_shot_ids[]. Require per-sentence semantic_match=passed, then materialize and revalidate hash-bound final_timeline.json. This timeline is the single source for locked-video duration, continuous TTS timestamps, subtitles and BGM. Tail silence and overlap remain in the timeline for model review, without mode-specific hard thresholds. With replication_mode=persuasion_structure_faithful_v1, require the passed generation review and frozen visual lock before TTS. Use the task-bound TTS profile and actual local tempo/tail timing, and bind locked video, continuous TTS, beats/shots, subtitles and applicable account-scoped BGM to one final_timeline.json. Materialization must also expose the same replication_mode at the final edit-request top level so the V2 edit manifest and final reviewer consume an explicit identical mode. Owner-requested no-BGM delivery is valid only when the base edit omits background_music, explicitly lists background_music in forbidden_operations, and the final timeline records mode=none/applied=false; an unmarked missing music asset remains invalid. If timing failure requires shorter copy, accept only a hash-bound voiceover-timing-revision-v1 that preserves every sentence's selling point, Beat, shot and source references; the final TTS manifest must bind the revision ID and exact revised source text. When narration_generation_route=direct_reference_narration_v1, the registered direct narration overrides that historical timing-revision exception: Storyboard, sentence windows, TTS source text, subtitles and final timeline must match exactly, and any timing revision is rejected as direct_narration_text_drift. When reviewed Seedance material is longer than its final target window in this mode, preserve the full reviewed keep_ranges and use the compiler-provided playback_rate to retime the picture and guide audio into that window. Do not truncate a required action result merely to match the target duration.
4. Execute:

python3 scripts/run_video_edit.py \
  --request /abs/path/edit_request.json

5. For V3 covers, run select_cover_frame.py to extract 12 frames and perform deterministic exposure/detail/duplicate prefiltering. Visually review the contact sheet and provide cover-frame-vision-ranking-v1; do not replace visual ranking with a random or purely graphical choice. Run prepare_cover.py with the selected original frame, locked account profile and runtime profile. It may crop/scale proportionally and add the confirmed title/secondary label, but must not distort the model or manufacture blank space. Small overlap with hair/shoulders is allowed only by profile; face, neckline and product key details remain protected. image_gen is only an explicitly enabled no-eligible-frame fallback.
6. Continue only when render_result.json.status=success, edit_manifest.json.status=success, source_files_unchanged=true, and the output passes audio/video, duration, dimensions, hashes, account scope, and optional attached_pic stream-copy validation.
7. Run content-reviewer on the final video and edit_manifest.json. For automatic precision trim, also require semantic-preservation-report-v1.decision=passed and exact source-to-output mapping. Do not hand the output to publishing unless both gates pass.
8. When editable Jianying delivery is requested, read references/jianying-handoff.md and verify jianying_handoff.json. Deliver 剪辑源文件/ for manual import: pre-trimmed silent video clips, independent audio tracks, UTF-8 SRT, style intent, and Chinese instructions. Never import final_preview.mp4 as a substitute for an editable timeline or claim that the package is a private Jianying project file.

run_video_edit.py writes an active workbench report after request validation and updates it on success, verified reuse, or failure. Edit success remains final_content_review pending and never marks publish-ready by itself.

Rendering Rules

• Preserve timeline order and support hard cuts only in V1.
• Treat every keep_ranges value as source time; record the resulting output-time mapping.
• playback_rate 必须为有限正数；现有 FFmpeg 执行画面与保留音轨的对应变速。静音模式直接走现有静音分支；工具不支持的变换返回真实错误，模型选择已有本地能力恢复。
• For precision_trim, write the bound trim plan record, issue IDs, required semantic unit IDs, and exact source-to-output mapping into edit_manifest.json; return the actual missing/drifted/semantically unapproved input for model recovery; do not cap local trim revisions.
• Generate UTF-8 ASS and SRT assets. Prefer FFmpeg ass; when the installed FFmpeg lacks libass, render deterministic transparent subtitle images with Pillow and burn them using FFmpeg overlay.
• 账号字幕 profile 显式冻结 subtitles.background=false；历史缺失值按透明背景兼容，true 直接阻断。ASS 固定 BorderStyle=1，Pillow 背景 alpha 固定为 0。
• V3 must first write assets/subtitle_layout.json. Both ASS and Pillow consume its wrapping, font size and explicit center anchor. Closing punctuation must stay with at least one preceding character and may not wrap onto a line by itself. Wrapping width must use the smaller horizontal distance from the center anchor to either safe-area edge, doubled, so asymmetric account safe areas cannot produce a centered bbox outside the right or left edge. Use the task/account subtitle safe area inside the actual frame; platform UI and readability are visually reviewed, not decided by universal coordinates. Shrink only to the account profile's min_font_size, then fail with subtitle_safe_area_overflow.
• Use an explicit audio file or macOS say with an available named voice. Do not silently replace a missing voice.
• Audio-first experiments synthesize one master TTS only. Preserve Seedance output audio only when every required segment passes verification; otherwise use input TTS for every segment. Never mix the two sources within one final video.
• Guide-voice experiments preserve the Seedance audio as evidence but mute it in the final mix. Require the authorized model/voice and one continuous TTS asset; retain actual sentence overlap for review. New jobs must bind tts-profile-snapshot-v2 with api_family=audio_generation_http / model=seed-audio-1.0 and auth.mode=speech_api_key; reject inactive/cross-account/drifted profiles, plaintext secrets, incomplete voice overrides, provider-policy changes, text over 3000 Unicode code points, target/output duration over 120 seconds, more than one successful paid call, or missing per-run approval evidence before materialization. An account speech_speed is immutable after snapshot and maps only at the Provider boundary to official integer audio_config.speech_rate=(speech_speed-1)*100; tasks may not inject that field. Never use Volc SSO/STS for a new Speech provider call. Legacy timing defaults are review hints; shot_content_faithful_v1 preserves semantic match, verified Provider timestamps and the shared final-timeline-v1, without fixed boundary/tail vetoes. Never pad an over-short narration to disguise drift.
• Mix source audio, voiceover, and optional BGM without modifying source files. V2 may explicitly mute source audio. Loop/trim the external BGM to the timeline, apply configured fades, duck the audio bed while voiceover is active, then perform final loudness normalization.
• A cover must carry cover-asset-manifest-v1, matching hashes, profile identity, selected timestamp/candidate evidence, and product_consistency_status=passed. Embed it as MP4 attached_pic; never insert it as a first frame or alter the primary video/audio streams.
• Keep commands, tool versions, input/output probes, hashes, assets, validation, and the pending final-review gate in edit_manifest.json.
• 定向换画面只消费 video-repair-recipe-v1 编译出的 V4 原子时间轴。替换素材源音轨必须静音，最终音轨从基线媒体 stream-copy；只有统一解码后的 PCM SHA256 相等才继承音频完整性事实，不相等则完整重跑音频完整性检查。两种情况都必须重跑全片普通审核和参考保真。
• edit-request-v5 仅用于 creation_mode=product_asset_remix_v1。它接受完整匹配的 V1 或 V2 outline/selection/rough-cut family，禁止跨版本混绑；必须逐 atom 验证实际采用的 Seedance 源。每个源二选一绑定 canonical closeout/evidence ref，或绑定 source_admissions[].historical-use-admission-receipt-v1。历史 receipt 必须回读成功旧成片、旧合格审核 lineage、本地/既有分镜证据、源媒体 hash 和精确允许区间，禁止伪造 closeout/V2/material-entry。所有 atom 继续校验 review lineage、虚拟分镜 ID、整数 PTS、源区间与输出区间；源音轨静音、BGM 禁用。成功输出 video-edit-manifest-v3 并保留完整多源 lineage，V1–V4 语义不变。
• scripts/remix_tts_adapter.py prepare 必须同时接收已渲染的 --locked-video，把该媒体 SHA/粗剪实际时长和逐 clip 输出预算写入 locked_video + post-download-duration-budget-v1，再编译现有 continuous-tts-request-v2；一句口播可覆盖同 beat 的连续多个 atom。只有 TTS profile、逐 run 付费授权、Provider 字幕证据、preflight、声学审核和句级真实时间与内容绑定全部有效，才生成最终字幕与时间线；adapter 不自行调用 TTS Provider。

Failure Boundaries

本次渲染未成功不等于整条任务不可恢复。plan-driven/混剪按现有入口返回 needs_model_action；旧路径可能仍返回 failed，由模型读取真实 reason/detail 并沿原编译器或 renderer 修复。恢复后重新核验实际媒体并完成终审，不改写旧失败、receipt 或来源 hash，不把局部诊断当成交付；未授权费用、身份/账号/权利冲突、submitted/unknown 与客观不可执行事实仍暂停受影响分支。

Report an unsuccessful render on invalid schema, unresolved/drifted generation closeout, missing/cross-account/inactive/drifted edit profile, missing or changed fonts, subtitle safe-area overflow, unavailable visual cover ranking, protected-subject title overlap, missing media, hash mismatch, cross-account/paused/unreviewed music, invalid time ranges, unsupported operations, unavailable TTS/filter, Provider subtitle evidence write failure, ineligible terminal TTS recovery, recovery tempo/mapping/hash drift, failed objective audio integrity, failed FFmpeg/ffprobe, inconsistent cover, changed primary streams, output collision, invalid output, or incomplete Jianying assets. 对 plan-driven 终编，可恢复问题写 needs_model_action 诊断并保持未交付，由模型零 Provider 修复后重试；pre_tts_visual_lock 被直接送入最终渲染时固定返回物化建议，不生成成片或 success manifest。

On failure, write render_result.json and logs/render.jsonl; do not write a success manifest. Do not overwrite an existing output or source file.

Resources

• Input/output contract: references/input-output-contract.md
• BGM asset boundary: references/bgm-acquisition.md
• Jianying manual-import contract: references/jianying-handoff.md
• Runtime profile: templates/video-edit-profile.json
• Account V3 profile: templates/account-video-edit-profile.yaml
• Shared TTS provider profile: templates/tts-provider-profile.yaml
• Account TTS profile: templates/account-tts-profile.yaml
• TTS profile resolver: scripts/resolve_tts_profile.py
• Continuous TTS executor: scripts/execute_continuous_tts.py
• Terminal continuous TTS recovery: scripts/recover_continuous_tts_alignment.py
• Localized continuous TTS revision: scripts/revise_continuous_tts.py
• Account profile resolver: scripts/resolve_edit_profile.py
• Hybrid cover-frame selector: scripts/select_cover_frame.py
• Deterministic runner: scripts/run_video_edit.py
• Guide voice/TTS adapter: scripts/guide_voice_tts_adapter.py
• Product remix/TTS adapter: scripts/remix_tts_adapter.py
• Deterministic guide-window builder: scripts/build_guide_voice_windows.py
• Continuous TTS audio integrity: scripts/continuous_tts_audio_integrity.py
• Deterministic cover compositor: scripts/prepare_cover.py

通用屏显文字轨道

使用通用屏显文字轨道时，读取 overlay-workflow.md。同一任务兼有多个分支时读取对应分支；其中的原有条件、顺序和例外继续适用。

原生剪辑交接与旧输入兼容

新 edit request 由原编译器直接产出，实际渲染回读请求和输出，不要求中央回执或安装中央适配器。输入明确携带历史兼容记录时才调用 creative-runner/scripts/legacy_contract_receipts.py 只读验真；不签新回执、不加载旧写入引擎。付费调用、subtitle evidence、PCM、账号、授权和 FFmpeg 输出仍按原事实处理；历史 ASR 只读，已付费但对齐失败不能映射为成功。

旧连续 TTS 恢复中的逐句/全文 ASR 相似度只作为 reference_defaults / advisories，不再因 0.95 / 0.90 / 0.85 等默认值拒绝本地恢复。恢复仍须验证原音频、Provider 字幕证据、提交文本、时间映射、hash、授权与防重，且 provider_call_count=0；客观音频或绑定冲突按真实边界停止。

混剪配置与交付恢复

混剪配置、剪映交付或混剪恢复时，读取 remix-recovery-workflow.md。同一任务兼有多个分支时读取对应分支；其中的原有条件、顺序和例外继续适用。

固定 API 凭据默认放在用户维护的 ~/.config/loopilot/credentials.json（目录 0700、文件 0600），Profile 保存展开后的绝对路径及 json_pointer：Ark /volcengine/ark/api_key、Speech /volcengine/speech/api_key、飞书 /feishu/app_secret。共享 ecommerce-operations/scripts/file_auth.py 按字段读取，拒绝符号链接、非当前用户、宽权限、缺字段或空值；不把整份 JSON 发给 Provider，不回退钥匙串。旧单值文件无指针仍可用；Keychain 只供显式旧配置。密钥文件不进发布包、run、日志或 Git。飞书 App Secret 不替代 lark-cli 的 OAuth/主密钥，即梦 CLI 的原有认证域保持独立。