shortcut-clips

shortcut-clips 是做什么的？

本地流水线负责所有机械性工作（转录、寻找候选窗口、画面重构图、字幕、渲染）。你的工作是判断环节：阅读候选时刻的文本，挑选最佳片段，并写入 clips.json。你永远不需要查看视频帧。

0. 输入

• 视频：本地文件路径。如果用户提供的是 URL，请解释 shortcut-clips 只能处理用户提供的文件（用户拥有或有权使用的文件），并要求提供文件。不要自己下载任何内容。
• 片段数量：使用用户指定的数量；如果未指定，则默认为 3。
• 选项（仅在用户提出时）：--language hi|kn|en|…，--min-len/--max-len（默认 20-60 秒），样式 bold-pop（默认）、minimal 或 karaoke-highlight。

1. 准备（转录 + 候选片段）

shortcut-clips prepare "<视频文件路径>"

• 命令会先打印输出文件夹路径，然后每个分块文件打印一行。请注意两者。
• 首次运行会下载语音模型。播放时长为 1 小时的视频，CPU 上大约需要 15-25 分钟，GPU 上需要 5-10 分钟。对于时长超过约 10 分钟的视频，请在后台运行命令并等待其完成。告知用户正在处理。重新运行是安全的：已完成的阶段会被缓存。
• 如果失败，请向用户显示错误信息中附带的修复建议。shortcut-clips doctor 命令可以检查安装是否正常。

2. 挑选精彩时刻

1. 读取 <输出文件夹>/work/candidates.txt 文件，然后依次读取其中列出的每个分块文件。每个分块列出了句子（s0012 [68.3] text）和候选片段（c004 s0012-s0021 68.2-108.6 (40s)），每个候选片段对应这些句子的一个范围。不要读取 transcript.json 或 candidates.json：分块文件包含了你所需的一切信息，且 Token 数量少得多。
2. 根据 reference/rubric.md 为每个候选片段打分。在此过程中，维护一个大约为请求数量 3 倍的候选列表：包含候选 ID、五项标准的得分以及一行备注。其余候选片段则放弃。
3. 优化优胜者。你可以将片段的边缘移动到其他句子的边界，例如，从最吸引人的句子开始，或者正好在精彩部分结束时结束：
   • start = 所选第一句子的时间。
   • end = 你保留的最后一句子的下一个句子的时间；如果你保留了该候选片段的最后一句，则使用该候选片段的结果时间。
   • 确保时长在规定的范围内。验证器会将边缘对齐到完整的单词。
4. 选择最终的一组：总体得分最高，任意两个片段之间没有太多重叠（超过几秒），并且尽量涵盖不同的话题。

3. 写入 clips.json

根据 reference/clips-format.md 写入 <输出文件夹>/clips.json。使用转录文本的语言和文字来填写 hook_text、title 和 caption，除非用户另有要求。将最佳片段排在第一位。然后运行：

shortcut-clips validate "<输出文件夹>/clips.json" --write

修复所有 error 并重新运行，直到显示 ✓。在简单的情况下修复 warning。info 行报告了自动调整（例如，对齐边缘），无需任何操作。

4. 渲染

shortcut-clips render "<输出文件夹>/clips.json"

然后向用户报告：每个片段的编号、标题、时长、得分和视频路径，以及画廊文件 <输出文件夹>/index.html。对排名第一的片段，用一句话解释其为何有效。告知用户可以随时要求修改。

编辑与重新运行

• “把片段 2 剪短点”、“换个新标题”、“使用卡拉 OK 风格”：编辑 clips.json（每个片段可以覆盖 defaults 中的 style/layout 设置），使用 --write 验证，然后重新渲染。未更改的片段会从缓存中复用。
• “找找其他精彩瞬间”：回到步骤 2，使用相同的分块文件。不要重新运行 prepare。
• 检测到的语言不正确：使用 --language <代码> 重新运行 prepare。只有转录及后续阶段会重做。
• No candidate windows：视频太短或几乎没有语音内容。使用更小的 --min-len（例如 10）重新运行 prepare。