cawcut-vn

CawCut VN

所有本地 VN 操作的统一入口。该技能负责 VN 对话和操作顺序——决定是打开轻量预览还是制作粗剪；cawcut vn CLI 则负责生成草稿文件并启动应用。

技能文件仅使用英文。 在实时回复中通过 reply_language 匹配用户的语言，但此文件及其引用内容必须保持英文。

参考资料

• 提出编辑方案前，先阅读 references/capabilities.md。该文件是 cawcut vn 支持的操作、标志和编辑限制的权威说明。切勿承诺其中未列出的效果。
• 仅在打包、打开、安装或排查交付到 VN 应用的问题时，阅读 references/install.md。

切勿手动编辑 VN JSON。只能使用有文档说明的 cawcut vn 命令。

拒绝 VN 不支持的操作

references/capabilities.md 中的 Not supported 列表和 Common refusals 表格划定了能力边界。提出风格或方案前，先对照用户的请求进行检查；如需拒绝，应立即用用户的语言明确说明，绝不能默默将其纳入最终草稿。

• 明确指出缺少的能力（“cawcut vn 无法移除或静音源视频自带的音频——没有任何标志可以做到这一点”），不要含糊其辞。
• 绝不能让拒绝看起来像是已经完成：不得报告 CLI 从未应用的效果已成功完成，不得描述源媒体时假装它已被修改，也不得手动编辑 JSON 来伪造效果。
• 提供最接近的受支持行为，或说明必须在此技能之外处理媒体，并将其作为本地文件重新提供。如果没有相近的受支持行为，就直接拒绝，而不是替换成其他效果，并在编辑计划（阶段 7）中列出所有未实现的内容。

询问用户

AskUserQuestion 用于让用户做出选择，因此每次调用都必须提供至少两个可行选项。只有一个选项就不算问题——用文字直接说明并继续，绝不要用占位选项凑数。如果用户或上游技能已经确定答案，就跳过调用；仅当该工具不可用或选项超过其上限时，才使用带编号的文本菜单。

初始化

在 AI 会话中首次执行 cawcut 操作前，静默运行以下步骤：

1. 如果本会话中已经有 cawcut 命令成功运行，则跳过初始化。
2. 否则只运行 cawcut upgrade check --json。如果有可用更新，则运行 cawcut upgrade。如果找不到该命令，请让用户通过 npm install -g @ubnt/cawcut 安装。
3. 切勿运行 cawcut auth login；VN 操作均在本地进行。

工作流

按顺序执行各阶段。重用用户或上游技能已经确定的信息；不要重复询问同一个问题。

0. 选择 VN 操作

无论媒体来源如何，只有此技能会决定如何处理 VN：

• 用户直接调用此技能（/cawcut-vn 或等效请求），并提供自己的本地图像、视频或音频文件进行编辑。这是主要使用路径，不是备用方案——不要等待或要求上游技能先输出结果。
• 上游技能（cawcut-workflow、cawcut-app-run、cawcut-avatar-video、cawcut-ad-video）交付生成的媒体后会无条件移交给此技能——它们不会预先筛选，也不会显示自己的 VN 选项菜单。

1. 运行 cawcut vn status——关于何种状态算作“可用”，详见 references/capabilities.md。
2. 如果上游技能或用户已经说明了操作（仅预览或进行编辑），则跳过下方问题，直接进入相应分支——这与其他所有移交流程使用的是同一个只决定一次的保护机制。
3. 否则，使用 AskUserQuestion，并根据 reply_language 本地化：
   • VN 可用时，提供三个选项：打开 VN 预览并立即导入（推荐快速查看）、进入编辑流程（制作粗剪）、不需要。
   • VN 不可用时（未安装或版本低于 VN_MIN_VERSION），省略预览选项——只提供进入编辑流程和不需要。不要提供无法成功的选项。

分支：

• 预览并导入（仅在 VN 可用时可选）：运行 cawcut vn import <path_1> <path_2> ... --title "<name>" --open，并包含所有提供的本地路径。复用对话中已确定的名称（用户为项目命名，或上游技能交付了带标题的结果）；否则根据文件内容自行命名。名称保持简短，使用几个词即可——这是 VN 在项目列表中显示的标签，而不是描述。告知用户项目 URL 和素材数量。然后停止——不要继续下方的编辑阶段。
• 不需要：结束，不运行任何 cawcut vn 命令。
• 进入编辑流程：继续至阶段 1。此分支不要求安装 VN——起草并验证粗剪完全可在本地完成，不会启动应用。

1. 清点提供的媒体

创建或修改项目之前：

• 解析每个提供的路径，并将其归类为图像、视频、音乐或音效。记录已知的视频和音频时长，以及对话、上游生成结果（如有）、文件名或可用的本地检查工具提供的有意义内容和顺序线索。绝不要编造未见过的内容。
• 立即识别缺失、无法读取、重复或不受支持的文件。注明哪些视频带有自己的音轨，并趁清点信息还清晰时检查用户的请求是否属于拒绝清单——不支持的请求必须现在就拒绝，而不是等到制作时才发现。
• 如果可用素材清单会影响编辑，请向用户概述。
• 不要生成替代媒体。如果需要生成媒体，请移交给 cawcut-workflow 或 cawcut-app-run，之后使用它们输出的路径继续。

2. 确认项目形式

对于新项目，明确询问用户选择 9:16、16:9 或 1:1。根据用户说明的发布平台推荐一种，但在用户选择之前不要创建项目。如果标题、预期平台／用途和目标时长尚未确定，也要一并确认。

对于现有草稿的副本，保留其宽高比，除非用户要求创建新项目；CLI 无法直接更改现有草稿的宽高比。

3. 推荐可行的编辑风格

风格

根据素材清单和预期用途推荐一种风格。先提供推荐选项，最多再提供两个有意义的备选项：

• 叙事风格 — 按时间顺序或语义顺序编排，使用较长、易于观看的镜头，并采用克制的 dissolve 转场。只有在确实需要通过颜色过渡时，才使用 fade-black 或 fade-white。适用于说明性内容或产品视频。
• 节奏蒙太奇 — 使用较短的可用视频片段、更多受支持的转场，并规划音乐／音效提示。只有在素材足够丰富多样时才提供；不支持节拍检测和自动节拍同步。
• 照片故事 — 以适当节奏展示静态图片，并使用 dissolve 转场。适用于图片较多的素材集。

根据实际情况调整这些风格，不要生搬硬套。所有方案都必须符合功能参考：不支持手动裁剪／重新构图、叠加内容、变速、样式化排版、音频淡入淡出或其他不受支持的操作。

继续之前，使用 AskUserQuestion 让用户选择剪辑风格，除非用户已经明确说出或清楚描述了风格。将推荐风格放在第一位，并标明为推荐。不要根据素材清单擅自选择风格，也不要把这项选择推迟到最终方案审批时再确定；但只提供该素材清单实际支持的风格。如果只有一种风格适用，请在文字中说明，而不是提出只有一个选项的问题（参见询问用户）。

画布填充模式和转场

遵循 references/capabilities.md 对 --scale-mode 和转场命名的说明——直接应用，不要在此重复说明理由：默认使用 fill；只有用户明确要求完整显示源画面时才切换为 fit（在剪辑方案中说明由此产生的上下或左右黑边）。不要仅因源素材与项目的宽高比看起来相似，就推断应使用 fit——请检查它们的实际像素比例。始终使用准确的规范转场类型名称；绝不要使用或调用已弃用的 fade 别名。

转场属于片段之间的边界，而不是某个片段（参见 capabilities.md → Transition model）。将“在片段 X 上添加转场”理解为 X → X+1，并始终按这种方式描述。绝不要使用 add-clip --transition；先添加所有片段，再使用 set-transition --index N 设置每个边界的转场。

4. 确定音乐和音效

将背景音乐和音效作为两项独立内容来决定。

• 如果用户没有提供任何一种，且未要求静音，请询问他们是否要提供本地背景音乐、本地音效、两者都提供，或两者都不提供。
• 如果用户已提供一种，只有在另一种能显著提升所选风格时，才询问缺少的那一种。
• 如果用户需要音频，请等待其提供准确的本地路径。此技能本身不会查找、下载或生成音频。
• 只有在视觉顺序和大致时长确定后，才规划音频时间安排。不要声称可以自动对齐节拍。
• 如果音频源比预期使用时长更长，请使用 --trim-start / --trim-end 选择并展示源素材范围（准确的裁剪方式和 --duration 语义见 references/capabilities.md）。
• 添加的音频不会替换源片段自带的音频。如果任何提供的视频自带音轨，而用户希望用背景音乐替换它，请在此拒绝这一部分（参见拒绝 VN 无法实现的需求），并在方案中说明两条音轨会同时播放。

5. 确认文本

用户提供的 .srt 文件需要单独处理。 用户提供一个或多个 .srt 文件时，不要提出下文的问题——这些字幕条目已有自己的文案和时间。只确认是否要通过 --at 平移整个字幕块，在编辑计划中显示字幕条目数和最终时间范围，然后使用 add-srt 导入。绝不要重新输入、调整时间或改写字幕条目，也绝不要将文件拆分成多个 add-text 调用。

询问用户是否要在本次编辑中添加文本——这是一个简单的选择题，应像第 4 阶段询问音乐和音效那样纳入流程。视觉序列和风格确定后，使用 AskUserQuestion：添加文本 / 不添加文本。只有用户已提出添加文本的要求，或在对话前文中提供了文本内容时，才跳过此问题。

如果用户拒绝，就不要再问——不添加文本，进入第 6 阶段。

如果用户同意添加文本（或已经提出此要求），只收集实现所需的信息：内容、时间和类型（标题／副标题／说明文字）。不要擅自编写文案、设定时间或确定用户未提供或认可的类型——询问用户是否要添加文本，不等于提议文本内容。

文本是叠加内容，不会延长主轨或项目时长。根据用户的措辞推断预期位置；不要默认追加片尾卡片：

• “最后 N 秒期间”、“视频最后 N 秒”或类似表述，表示将文本叠加在现有的最后一个视觉片段上；
• “所有镜头结束后再显示 N 秒”、“追加独立片尾卡片”或类似明确表示顺序关系的表述，表示追加一个单独的 N 秒视觉片段，然后将文本叠加在该片段上；
• 如果措辞可能有两种含义，应在展示编辑计划前提出一个聚焦于时间安排的问题，而不是擅自选择。

只有第二种情况允许额外添加主轨片段。绝不要通过缩短或遮挡前一个镜头来满足明确提出的“所有镜头结束后”要求。由于 CLI 无法创建纯色片段，如果需要单独的片尾片段，用户必须提供片尾卡片图像，或由你交接图像生成任务。

字体选择

每种文本类型都有默认字体和字号（见 references/capabilities.md），但确认添加文本后，还要询问字体——不要默默略过。用户已指定或描述字体时，直接确定字体；否则使用 AskUserQuestion，提供以下选项：

1. 使用默认字体（推荐）——使用该类型对应的默认字体和字号；不设置 --font/--font-file/--font-size。
2. 为我推荐一些字体——运行 cawcut vn fonts --json，最多提供 4 个候选项（标签格式为：字体系列 + 样式；优先列出最符合所选编辑风格的候选项，并标记为 （推荐））。
3. 我提供自己的字体——提供字体名称，或通过工具的自由文本“其他”选项提供本地文件路径（传入 --font-file）。

原样传递用户提供的字号——它指的是 VN“字体大小”框中显示的数值，不是相对于画布的比例。字体标志的含义和可移植性见 references/capabilities.md。编辑计划中包含文本时，必须列出字体和字号（第 7 阶段）。

6. 确认封面

对于新项目，展示编辑计划前，必须明确确认封面选择，除非用户已指定：

• 使用用户提供的 PNG，通过 set-cover 将其设为明确的照片封面；
• 使用用户之后提供的另一张本地 PNG；或
• 使用 VN 自动生成的首帧封面。

使用 AskUserQuestion 询问封面选择。如果用户提供的图片明显能代表该项目，就推荐使用该图片；否则推荐自动生成的首帧。不要将时间线中的开场镜头与明确设置的 VN 封面混为一谈。

7. 展示剪辑计划并等待批准

运行 init、add-clip、add-audio、add-sound-effect、add-text、 add-srt 或 set-transition 之前，请先展示一份具体计划，其中包含：

• 项目标题、宽高比、选定的风格、封面选择和预计总时长；
• 按顺序排列的镜头，包含素材路径以及图片时长或视频剪辑范围；
• 每个转场都必须明确标注为边界 N → N+1: <type> (<duration>s)， 绝不能附加到单个片段上；
• 仅当用户明确请求文字时：标题／副标题／字幕内容，以及开始时间、时长、字体和字号（与 VN 文字面板中 Font Size 框显示的数字相同）；
• 对于提供的 .srt：文件名、字幕条数、解析器将跳过的字幕条目、生成的时间跨度，以及任何 --at 时间偏移；
• BGM 和 SFX 路径，以及时间线开始时间、素材剪辑范围、时长和音量；
• 计划中未实现的每项请求，都必须列为明确的拒绝或简化方案——包括此前对话中已拒绝的请求。绝不能让未实现的效果看起来像是已包含在计划中。

多镜头剪辑时，建议使用精简的时间线表格。展示完整计划后，始终使用 AskUserQuestion 确认是否生成；不能只用文字询问是否批准。提供以下选项，并根据用户的语言本地化：

1. 按此计划创建（推荐） — 批准所展示的计划并开始生成草稿。
2. 修改计划 — 收集所需修改，更新完整计划，然后再次调用 AskUserQuestion。
3. 取消 — 停止，不创建或修改草稿。

只有选择第一项才授权进入第 8 阶段。不要将沉默、无关回复，或此前笼统提出的“制作一段视频”视为批准。此确认环节很重要，因为 CLI 会追加片段，且不支持删除、重新排序或原地编辑片段。

8. 构建并验证粗剪

获得批准后：

1. 初始化草稿，或使用 init --from 复制现有草稿。
2. 按批准的顺序添加片段，并使用计划中的视频素材剪辑范围。
3. 如已选择明确封面，则应用该封面。按照批准的时间线开始时间和素材剪辑范围添加 BGM 和 SFX，然后使用 set-transition --index N 设置每个已批准的转场（绝不要使用 add-clip --transition）。只有在文字已被明确请求并包含在批准的计划中时才添加文字；对于已批准的 .srt，请使用 add-srt 导入，而不是通过 add-text 逐条重放字幕。
4. 运行 show --json，将结果与批准的计划进行比较，并安全地修正 CLI 能够表达的任何差异。转场差异始终可以通过 set-transition 原地修正（使用 --type none 清除）——绝不要为了转场而重建草稿。如果修正需要删除、调整时间、替换或重新排序片段，则根据批准的计划创建一个新草稿。
5. 运行 validate。验证通过前，不要报告已完成。绝不要悄悄丢弃失败的素材或替换为不受支持的效果。

9. 询问是否在 VN 中打开

只有在 show 与计划相符且 validate 通过后，才再次运行 cawcut vn status——不要重复使用第 0 阶段的结果，因为用户可能在此期间安装或升级了 VN（也可能是因为用户直接开始编辑，第 0 阶段根本没有检查 VN）。

• VN 可用： 告知用户粗剪已完成，并询问现在是否要在 VN 中打开。
  • 是： 运行 cawcut vn project pack --open --project <dir>。如果打开失败，CLI 会说明原因，并提供适用于该平台的可行方案——转告用户这个方案，不要重试同一条命令。
  • 否： 运行 cawcut vn project pack --project <dir>，这样即使不启动应用，.vn 成品也已准备就绪。
• VN 不可用： 跳过询问——没有可供选择的可行方案。直接运行 cawcut vn project pack --project <dir>，并酌情附上 VN 下载／升级链接。

报告草稿目录、.vn 路径、时长、片段／音频／文本数量，以及任何有意简化之处。最终做出选择之前，不要打开 VN。

交接边界

• 媒体有两种来源：用户直接提供自己的本地文件（应视为常见情况，而非特殊情况），或由上游技能移交其生成的输出。若属于后一种情况，应信任其有效路径，沿用已确定的画面比例、意图或音频决策，并信任预先决定的操作（预览还是编辑），不要重新询问第 0 阶段的问题。无论哪种情况，在修改时间线之前仍须先展示编辑计划。
• 如果用户只要求预览几个文件，不做粗剪，这属于第 0 阶段的预览并导入分支——仍在此工作流内，不应移交给其他流程。
• 命令、标志和路径均使用英文；对话使用 reply_language。