video-to-shorts

视频转短视频

依赖项

/video-understand 是前置条件。请先运行它，以便短视频使用经过验证的 源转录文本和规范时间线。 开始前，请确认已安装该依赖项。如果未安装，请告知用户缺少此 前置条件，并在处理媒体前停止。

要求 ffmpeg/ffprobe 位于 PATH 中，并安装带有 Pillow 的 Python。请在处理媒体前检查这些依赖。

范围

此技能分为两个项目阶段：

1. 渲染前规划： 将理解后的转录文本映射到节目时间，编写并 审批候选片段，然后写入 work/shorts/shorts-plan.json。此阶段不会写入 最终视频。
2. 渲染后定稿： 审批所有选定的主序列剪辑并验证共享的主交付内容后，重新运行 plan.py，将相同的已审批 范围绑定到该交付内容，然后提取横屏和可选的竖屏输出。

此技能负责短视频候选判断、确定性筛选、横屏提取、 相对于短视频的转录文本，以及可选的确定性竖屏交付。它不会在项目模式下转录、修改主序列、添加字幕/图形、 调色、发布或执行连续主体跟踪。

交付的短视频是 final/final-video.mp4 的衍生内容，但候选规划会在该文件生成前进行。 请在项目 DAG 中记录此操作，但绝不要将其添加到 sequences.main.operations；主交付内容及其原始版本与最终版本的比较 必须保持不变。

项目输入

• work/project.json
• project.source.path 记录的项目源文件
• 源时间轴中的 work/understand/transcript.json
• work/timeline.json
• 每个阶段的活动主操作修订版本

规划不要求存在 final/final-video.mp4。定稿和提取要求 该项目的确切渲染结果满足 render.status: verified。

prepare_transcript.py --timeline 会调用共享的 projectlib.map_transcript_to_timeline。因此，候选片段/提取时间是实际最终视频中的节目秒数。主剪辑删除的单词 无法用于短视频。每个保留的单词都会保留其 source_range、 program_range 和 clip_id。

项目转录元数据通过绝对路径、大小、修改时间和 SHA-256 绑定项目源文件、源转录文本和时间线。候选片段审核帧会将其节目时间戳映射回 timeline.json 中的源视频。候选片段 验证会拒绝已变更的绑定关系。

输出布局

work/shorts/
|-- transcript.json
|-- transcript_metadata.json
|-- candidates.json
|-- shorts-plan.json
|-- review/
|   |-- candidate_review.json
|   `-- approved_candidates.json
`-- short-001/
    |-- transcript.json
    |-- extraction-report.json
    `-- vertical-agent/
        |-- agent_vertical_plan.json
        |-- vertical_plan.json
        `-- review/vertical_review.json

work/cache/shorts/                 # disposable frames/sheets/intermediate media

review/06-shorts/
|-- candidates-<review-id>.html              # immutable authoritative page
|-- candidates-<review-id>-question.md
|-- assets/candidates-<review-id>/            # immutable start/middle/end frames
|-- candidates.html                           # non-authoritative latest alias
|-- candidates-summary.md
|-- short-001-horizontal.jpg
|-- short-001-vertical-preview.mp4
|-- short-001-vertical-contact-sheet.jpg
|-- short-001-vertical-preview-summary.json
|-- short-001-vertical-preview-probe.json
|-- <short-id>-vertical-review-<review-id>.html # immutable authoritative page
|-- <short-id>-vertical-review-<review-id>-question.md
|-- <short-id>-vertical-review.html             # non-authoritative latest alias
|-- <short-id>-vertical-review-assets/
|   `-- <review-id>/                             # immutable authoritative evidence
|       |-- preview.mp4                          # absent for REVIEW_REQUIRED
|       |-- contact-sheet.jpg                    # absent for REVIEW_REQUIRED
|       |-- preview-summary.json
|       `-- media-probe.json
`-- shorts-summary.md

final/shorts/
|-- short-001-horizontal.mp4
`-- short-001-vertical.mp4          # only when selected and approved

节目转录文本

从仓库根目录运行：

$RepoRoot = (Resolve-Path ".").Path
$SkillRoot = Join-Path $RepoRoot "skills\video-to-shorts"
$ProjectRoot = (Resolve-Path "<project-root>").Path
$Work = Join-Path $ProjectRoot "work"
$ShortsWork = Join-Path $Work "shorts"
$ProjectSource = (Resolve-Path "<project-source-from-work/project.json>").Path
$FinalVideo = Join-Path $ProjectRoot "final\final-video.mp4"
$ShortsReview = Join-Path $ProjectRoot "review\06-shorts"
New-Item -ItemType Directory -Force $ShortsWork,$ShortsReview | Out-Null

python "$SkillRoot\scripts\prepare_transcript.py" $ProjectSource `
  --transcript "$Work\understand\transcript.json" `
  --timeline "$Work\timeline.json" `
  --out $ShortsWork

项目时间线模式要求使用提供的规范转录文本。独立模式 可以省略 --timeline；它会保留相对于输入的时间，并可使用临时的 video-understand/scripts/transcribe.py 回退方案。不会自动发现转录文本。

候选项编写

将长视频的视觉上下文生成为缓存，检查决策所需的每张画面表，并手动编写候选项 JSON。确定性代码负责验证编辑判断，不会凭空生成候选项或分数。

python "$SkillRoot\scripts\prepare_visual_context.py" $ProjectSource `
  --timeline "$Work\timeline.json" `
  --out "$Work\cache\shorts\candidate-visual" --interval 15

为保持兼容，候选项输入仍使用 shorts-candidates.v2。将 selection.evidence_mode 和每个候选项的 evidence_mode 设为 text_visual。 每个候选项都必须包含：

• 稳定的 candidate_id、标题和场景类型；
• 完整的节目时间 start_time/end_time；
• transcript_excerpt 必须与重叠的逐字稿词语完全一致，而不是包含整个重叠片段；
• 六项评分及非空理由；
• 非空的 metadata.editorial_reason；
• 可选的、经审核的 filler_drop_spans 和视觉证据字段。

请勿提供总分 score；验证器会将六个维度相加：

维度	最高分
hook	20
completeness	20
audience_value	20
emotion_tension	15
quotability	15
pace_editability	10

优先选择完整且能独立理解的想法，而不是较短的片段。如有必要，应保留依赖于上下文的采访者提问、前提、论点佐证、反转或结尾。边界必须落在完整的词语和想法处。

验证编写的文件：

$CandidateDir = Join-Path $ShortsWork "preview\text_visual"
python "$SkillRoot\scripts\candidates.py" `
  --out $CandidateDir `
  --candidates "$CandidateDir\candidate-input.json" `
  --transcript "$ShortsWork\transcript.json" `
  --project-root $ProjectRoot

此操作会写入兼容性预览文件、持久化的 work/shorts/candidates.json，以及 review/06-shorts/candidates.{html,summary.md}。

审核模式

候选项选择和交付模式构成一道由哈希绑定的关卡。交付模式只能是 horizontal_only 或 horizontal_and_vertical。

以人工模式打开绑定的交互页面：

python "$SkillRoot\scripts\interaction.py" candidate-open --out $ShortsWork --review-out $ShortsReview

该命令会输出一个权威的、限定于审核 ID 的页面。回执会通过 SHA-256 将该页面、候选项 JSON、逐字稿、源媒体、固定问题和每一帧提取的画面绑定起来。candidates.html 只是指向最新页面的非权威便捷别名。使用当前操作系统的原生命令打开输出的权威路径：

# Windows PowerShell
Start-Process (Resolve-Path -LiteralPath "<printed-authoritative-page>")
# macOS
open "<printed-authoritative-page>"
# Linux
xdg-open "<printed-authoritative-page>"
# Agent: Present the authoritative page and STOP.

如果打开失败，请重试原生命令；如果仍无法打开，请报告失败。展示页面后请勿继续操作。页面初始状态下，所有候选项复选框和两种交付选项均未选中。用户必须选择 1-5 个候选项和一种交付模式。绑定页面绝不会暗中选择候选项。

要批准，请将页面生成的以下结构化摘要原样复制到 candidate-answer：

Shorts candidate review
Review: <review-id>
Candidates: text_visual/cand-001, text_visual/cand-002
Delivery: horizontal_and_vertical

要进行修改，请将页面生成的以下结构化摘要原样复制：

Shorts candidate review
Review: <review-id>
Decision: revise
Changes: <non-empty requested changes>

记录后续回复，不要改写：

python "$SkillRoot\scripts\interaction.py" candidate-answer `
  --out $ShortsWork --response-file "<verbatim-summary-file>"

当用户明确委托决策时：

python "$SkillRoot\scripts\interaction.py" candidate-open `
  --out $ShortsWork --review-out $ShortsReview --decision-mode agent `
  --delegation-note "User delegated shorts selection and vertical approval."

python "$SkillRoot\scripts\interaction.py" candidate-agent-approve `
  --out $ShortsWork `
  --candidates "text_visual/cand-001" `
  --delivery horizontal_and_vertical `
  --rationale "The selected range has a self-contained hook, explanation, and payoff."

Agent 会打开并检查同一个权威页面，使用明确的候选项引用、明确的交付模式和非空的理由。它绝不会伪造人工回复或 user_response。人工模式和 Agent 模式互斥；在 Agent 模式下，人工回答命令会失败；在人工模式下，Agent 批准命令会失败。回执验证会重新检查审核、页面和媒体的哈希。重新生成源文件、候选项、逐字稿、页面、问题、画面或已批准候选项工件都会使批准失效。

规范计划

python "$SkillRoot\scripts\plan.py" `
  --out $ShortsWork --project-root $ProjectRoot

work/shorts/shorts-plan.json 使用整数 schema_version: 1。其中记录：

• target: derived、timebase: program 和 timeline_id；
• 规划期间的 delivery_status: awaiting_main_render；
• 用于候选审核的项目源和时间线绑定；
• 活动主序列中精确的 depends_on / based_on 修订版本；
• 选择模式、理由、交付模式和审核 ID；
• 稳定的短片 ID；
• 明确的 program_range 和映射后的 source_ranges；
• 评分／编辑证据、已批准的填充词删除，以及节目时间保留片段；
• 工作转录稿／报告路径和 ../final/shorts/*.mp4 交付路径。

首次运行即为规划阶段的结束。请在此处停止，并按规范顺序继续处理所请求的字幕、内容卡片、动态图形和其他剩余的主序列操作。不要运行 extract_shorts.py，也不要通过此技能创建 final.mp4。

共享渲染器验证 final/final-video.mp4 后，重新运行相同的 plan.py 命令。它会重新验证已批准的项目源和时间线，刷新全部活动操作的修订版本，添加已验证主渲染的指纹，并将 delivery_status 设为 ready。时间线发生变化时，必须重新生成候选项并重新审批；内容卡片和字幕等仅影响像素的操作则不需要。

资格判定保持确定性：得分至少为 70，完整度至少为 15，预计输出时长为 20-90 秒，片段必须准确有效，不得与排名更高的短片重叠超过 50%，并且除非另行配置，最多输出五条。

只有边界安全、语义上无实际内容的独立犹豫词才可获准作为填充词删除。已拒绝或不安全的片段会连同原因保留在计划中。总删除量不得超过 15%，任何保留片段不得短于 0.15 秒。

横向提取

python "$SkillRoot\scripts\extract_shorts.py" `
  --video $FinalVideo --out $ShortsWork `
  --project-root $ProjectRoot

提取前，脚本会重新检查主渲染指纹、项目渲染状态、当前完整的主操作列表及其修订版本、候选回执、已批准候选项的哈希值和源视频。awaiting_main_render 计划会被拒绝。每个保留范围都会成为一个独立的、经过定位的 -ss/-t/-i 输入；ffmpeg 会拼接这些输入并执行一次 H.264/AAC 编码。它不会针对每个保留范围各解码一次完整主视频。

所选最终转录词语的边界与媒体剪切终点是分开的。提取会在所选内容之后至少保留 0.25 秒的尾音，并以 0.30 秒为目标。--no-refine-boundaries 只会禁用语义短语边界贴合；它绝不会禁用强制保留的尾音余量。如果源视频在结束前无法保留所需的余量，提取就会失败，而不会将短片标记为已验证。

短片相对转录稿会排除已删除的词语，将后续词语移至连续的零起始时间轴上，并保留输入节目／源素材证据。横向媒体会直接写入 final/shorts；工作目录中仅包含其转录稿和报告。

纵向规划

纵向交付从已批准的横向输出开始。每隔 1 秒生成密集的视觉证据；若运动情况需要，则每隔 0.5 秒生成。检查每张图集，并编写以下其中一种方案：

• STATIC_CROP：一个稳定、固定的 9:16 裁剪。
• SCENE_CROP：按场景界定的固定裁剪；仅对需要完整横向信息的场景使用 LETTERBOX。
• LETTERBOX：保留完整清晰前景，并叠加模糊或变暗的填充背景。
• REVIEW_REQUIRED：证据不足以支持确定性的固定裁剪；禁止正式渲染。

演讲者场景应保持头部和躯干稳定且占画面较大。幻灯片、产品、群体和图表必须保留关键信息。不要声称支持连续跟踪。裁剪变化应在场景边界处进行。

每个方案片段都必须完整覆盖短片时间线，包含策略、内容类型、非空理由，并在适用时包含有效的边界内裁剪。必需的内容类型为 PRESENTER、WIDE_INFORMATION、PRODUCT、MULTI_SUBJECT 和 OTHER。

$ShortId = "short-001"
$Horizontal = Join-Path $ProjectRoot "final\shorts\$ShortId-horizontal.mp4"
$VerticalWork = Join-Path $ShortsWork "$ShortId\vertical-agent"
$ExtractionReport = Join-Path $ShortsWork "$ShortId\extraction-report.json"

python "$SkillRoot\scripts\prepare_visual_context.py" $Horizontal `
  --out "$Work\cache\shorts\$ShortId-vertical-visual" --interval 1

python "$SkillRoot\scripts\vertical_plan.py" `
  --video $Horizontal `
  --input "$VerticalWork\agent_vertical_plan.json" `
  --out $VerticalWork `
  --source-video $FinalVideo `
  --extraction-report $ExtractionReport

vertical_plan.json 以 {num, den} 的形式保留精确 FPS，并确定性地验证几何信息、覆盖范围、策略时长和警告。直接渲染绑定会对已验证的主交付文件和精确的提取报告进行哈希。预览审查仍使用已批准的横向短片时间线；正式渲染则通过记录的 keep_spans 映射该时间线，并直接读取已验证主交付文件中的像素。

将较小尺寸的预览渲染到面向用户的审查目录：

python "$SkillRoot\scripts\render_vertical.py" `
  --video $Horizontal --plan "$VerticalWork\vertical_plan.json" `
  --out $VerticalWork --review-out $ShortsReview --mode preview

该命令首先写入扁平的最新便捷输出，文件名为 <short-id>-vertical-preview.mp4、<short-id>-vertical-contact-sheet.jpg、<short-id>-vertical-preview-summary.json 和 <short-id>-vertical-preview-probe.json。随后打印权威的 <short-id>-vertical-review-<review-id>.html 页面。最新的 <short-id>-vertical-review.html 别名仅供方便使用，不具权威性。

权威页面和回执会绑定 <short-id>-vertical-review-assets/<review-id>/ 下不可变且按审查 ID 分类的副本：preview.mp4、contact-sheet.jpg、preview-summary.json 和 media-probe.json。之后生成的预览可以替换扁平便捷输出，但不会更改先前的回执。REVIEW_REQUIRED 仅在其分类目录中保存 preview-summary.json 和 media-probe.json，因为不会渲染预览视频或联系表。

使用当前操作系统的原生命令打开打印出的权威路径：

# Windows PowerShell
Start-Process (Resolve-Path -LiteralPath "<printed-authoritative-page>")
# macOS
open "<printed-authoritative-page>"
# Linux
xdg-open "<printed-authoritative-page>"
# Agent: Present the authoritative page and STOP.

如果打开失败，请重试原生命令；如果仍无法打开，请报告失败。报告后不要继续。检查完整预览、联系表、所有片段及裁剪/适配决策、媒体探测结果和每一条警告。回执会对页面、方案、源文件、预览、联系表、预览摘要、探测结果和固定问题进行哈希。

人工审查时，将页面中精确的结构化摘要原样复制到 vertical-answer。可能的三种摘要如下：

Shorts vertical review
Short: <short-id>
Review: <review-id>
Decision: approve

Shorts vertical review
Short: <short-id>
Review: <review-id>
Decision: revise
Changes: <non-empty requested changes>

Shorts vertical review
Short: <short-id>
Review: <review-id>
Decision: skip

python "$SkillRoot\scripts\interaction.py" vertical-answer `
  --out $VerticalWork --response-file "<verbatim-summary-file>"

委派模式使用相同的页面，并记录诚实的 Agent 决策及非空理由：

python "$SkillRoot\scripts\interaction.py" vertical-agent-approve `
  --out $VerticalWork `
  --rationale "All sampled scenes preserve the subject and essential information."

REVIEW_REQUIRED 仅提供 revise 或 skip；禁止 Agent 批准。更新的候选审查会使较早的纵向回执失效。只有在获得批准后，才允许进行最终纵向渲染。只有通过批准且哈希匹配的审查媒体和方案才能进入最终渲染；修改和跳过都不会生成最终纵向文件。

正式渲染会重新验证每项已批准的制品：

python "$SkillRoot\scripts\render_vertical.py" `
  --video $Horizontal --plan "$VerticalWork\vertical_plan.json" `
  --out $VerticalWork --review-out $ShortsReview --mode final

正式渲染器使用有理数 num/den，从已验证的主交付文件生成一个 H.264/yuv420p 版本，采用 libx264 -preset slow -crf 16，并编码连续音频。为加快审查，预览渲染仍使用 medium / CRF 20。渲染器会检查尺寸、时长、FPS、音频是否存在、源文件/报告哈希以及保留区间映射。

项目操作

在 work/project.json 中添加一个派生操作，但不要将其加入主序列：

{
  "id": "shorts",
  "skill": "video-to-shorts",
  "revision": 1,
  "depends_on": ["understanding"],
  "based_on": {"understanding": 1},
  "status": "approved",
  "plan": "shorts/shorts-plan.json",
  "outputs": [],
  "target": {"sequence": "main", "scope": "derivatives"},
  "effects": {
    "changes_timeline": true,
    "changes_geometry": true,
    "changes_video_pixels": true,
    "changes_audio": true,
    "adds_track": null
  },
  "check": {"status": "pending", "report": "../review/06-shorts/shorts-summary.md"}
}

这是预渲染状态。使用计划中存储的实际依赖项列表和修订版本。共享主渲染完成后，重新运行 plan.py，根据刷新后的依赖项更新操作，提取并验证输出，然后将操作/检查状态设为 verified/pass，并列出已交付的文件。项目验证会检查 DAG 和文件；短片仍不属于主渲染计划。

兼容性

不使用 --project-root 时，候选项和 shorts-plan.v2 仍沿用既定的独立路径和相对于输入的时间。提取器接受这两种计划格式。旧版 short_XX/source.mp4 竖屏工作流和人工审阅命令仍然有效。只有旧版未绑定的文本审阅可以使用默认的前 5 个候选项；已绑定的交互页面始终要求明确选择。独立回退转录使用规范的 video-understand 转录器和项目本地模型缓存。

自检

运行：

python "$SkillRoot\scripts\check_project_protocol.py"
python "$RepoRoot\skills\video-understand\scripts\validate.py" project `
  "$Work\project.json" $ProjectRoot

对每个已交付的短片，验证：

• 候选片段与重叠的节目词句一致，且表达完整；
• 源/节目范围和依赖项修订版本均可解析；
• 横屏时长约等于保留片段时长之和；
• 短片转录从 0 开始，在媒体时长范围内结束，不包含已移除的词句或仅在释放把手内听到的词句，并报告 tail_release_verified: true；
• 横屏输出具有预期的 FPS、H.264 视频、同步音频和审阅静帧；
• 竖屏输出为 9:16，使用精确的有理数 FPS，保证所需内容位于安全区域内，音频同步，与已批准的预览/计划哈希匹配，并记录 direct_render: true，且以已验证的主交付内容作为 render_source；
• 所有面向用户的媒体均位于 review/ 或 final/ 下，可丢弃的材料位于 work/cache/ 下；
• shorts-summary.md 记录输出、决定、警告和检查结果。

仅生成页面或验证 JSON 并不代表成功。请观看横屏和竖屏输出，并检查其审阅图像/联系表。