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 は選択肢を提示するためのものです。そのため、呼び出すたびに実行可能な選択肢を 2 つ以上用意してください。選択肢が 1 つだけなら質問ではありません。文章でその内容を伝えて続行し、仮の選択肢で水増ししないでください。ユーザーまたは上流のスキルによってすでに回答が決まっている場合は呼び出しを省略し、ツールが利用できない場合、または選択肢が上限を超える場合に限り、番号付きのテキストメニューを使用してください。

初期設定

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が使用可能な場合は、次の3つの選択肢を提示します。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. 実現可能な編集スタイルを提案する

スタイル

素材の内容と用途に基づいて、適したスタイルを提案します。おすすめの選択肢を最初に示し、意味のある代替案は最大2つまで提示してください。

• クリーンなナラティブ — 時系列または意味上の順序で構成し、読みやすい長めのショットを使用して、控えめな dissolve トランジションを使います。色を経由するトランジションを意図する場合にのみ、fade-black または fade-white を使用します。解説映像や製品紹介映像に適しています。
• リズムモンタージュ — 使用可能な動画範囲を短めにし、対応している強めのトランジションを使って、音楽や効果音のキューを計画します。変化に富んだ映像素材が十分にある場合にのみ提案してください。ビート検出と自動ビート同期には対応していません。
• フォトストーリー — 静止画像をテンポよく配置し、dissolve トランジションを使います。画像中心の素材に適しています。

これらのスタイルをそのまま当てはめるのではなく、素材に合わせて調整してください。すべての提案は機能リファレンスの範囲内に収めてください。手動でのクロップやリフレーム、オーバーレイ、速度ランプ、装飾的なタイポグラフィ、オーディオフェード、その他の未対応操作は提案しないでください。

先に進む前に、ユーザーがすでにスタイルを指定または明確に説明している場合を除き、AskUserQuestion を使って編集スタイルを選んでもらってください。おすすめのスタイルを最初に示し、おすすめと明記してください。素材からスタイルを黙って決めたり、最終プランの承認まで選択を先送りしたりしないでください。ただし、素材で実際に対応できるスタイルだけを提示し、適したスタイルが1つだけの場合は、選択肢が1つだけの質問をするのではなく、文章でその旨を伝えてください（ユーザーへの質問を参照）。

キャンバスのフィルモードとトランジション

--scale-mode とトランジションの命名については references/capabilities.md に従い、ここでは理由を説明し直さず、そのとおりに適用してください。デフォルトは fill とし、ユーザーがソースのフレーム全体を表示したいと明示した場合にのみ fit に切り替えてください（編集プランでは、結果として生じるレターボックスやピラーボックスの余白を明記してください）。ソースとプロジェクトの比率が似ているというだけで fit と判断してはいけません。実際のピクセル比率を確認してください。トランジションは常に正確な正式名称で指定し、非推奨の fade エイリアスは記述も実行もしてはいけません。

トランジションが適用されるのはクリップではなく境界です（capabilities.md → Transition model を参照）。「クリップ X にトランジションを設定して」という指定は X → X+1 と解釈し、必ずその形式で記述してください。add-clip --transition は使用しないでください。先にすべてのクリップを追加し、その後 set-transition --index N で各境界を設定してください。

4. 音楽と効果音を決める

BGMと効果音は別々に決めてください。

• BGMも効果音も提供されておらず、ユーザーが無音を希望していない場合は、ローカルBGM、ローカル効果音、両方、どちらもなしのいずれを希望するか尋ねてください。
• どちらか一方が提供されている場合、選択したスタイルを大きく向上させるときに限り、提供されていないほうについてのみ尋ねてください。
• ユーザーが音声を希望する場合は、正確なローカルパスが提示されるまで待ってください。このスキル単体では、音声の検索、ダウンロード、生成は行いません。
• 音声のタイミングを計画するのは、映像の構成とおおよその長さが決まってからにしてください。ビートへの自動同期を行うとは説明しないでください。
• 音声ソースが配置予定の長さより長い場合は、--trim-start / --trim-end を使ってソース範囲を選択し、プランに記載してください（トリミングと --duration の正確な仕様については references/capabilities.md を参照）。
• 追加した音声が、ソースクリップにもともと含まれる音声を置き換えることはありません。提供された動画にサウンドトラックがあり、ユーザーがそれをBGMで置き換えるつもりでいる場合は、その部分については対応できないと伝えてください（VNでは対応できない要求への対応を参照）。プランには、両方のトラックが同時に再生されることを明記してください。

5. テキストを決める

提供された .srt は別の手順で扱います。 ユーザーから .srt ファイルが1つ以上提供された場合、以下の質問はしないでください。キューにはすでにテキストとタイミングが設定されています。確認するのは、--at でブロック全体を移動するかどうかだけです。編集プランにはキュー数と適用後の時間範囲を示し、add-srt で読み込みます。キューを入力し直したり、タイミングを変更したり、文言を書き換えたりしないでください。また、ファイルを個別の add-text 呼び出しに分割しないでください。

この編集にテキストを入れるか、ユーザーに確認してください。これは単純なオプトインの質問で、フェーズ4で音楽と効果音について尋ねたのと同じ流れに含めます。映像の順序とスタイルが決まったら、AskUserQuestion を使って テキストを追加 ／ テキストなし を尋ねます。ユーザーがすでにテキストを希望している場合や、会話の前半ですでにテキスト内容を提供している場合に限り、この質問を省略します。

テキストを希望しない場合は、再度尋ねず、テキストなしでフェーズ6に進みます。

テキストを希望した場合（またはすでに希望している場合）は、実装に必要な内容、タイミング、種類（タイトル／字幕／キャプション）だけを確認します。ユーザーが提供または承認していない文言、タイミング、種類を勝手に決めないでください。テキストを入れるか尋ねることは、表示する文言の提案とは異なります。

テキストはオーバーレイであり、メイントラックやプロジェクトの尺を延長することはありません。ユーザーの表現から意図する配置を判断し、デフォルトでエンドカードのクリップを追加しないでください。

• 「最後のN秒間に」「動画の残りN秒間に」など同等の表現は、既存の最後の映像クリップにテキストを重ねることを意味します。
• 「すべてのショットの後にN秒間」「独立したエンドカードを追加」など、明示的に順次配置する表現は、独立したN秒の映像クリップを追加し、そのクリップにテキストを重ねることを意味します。
• どちらの意味にも取れる表現の場合は、編集プランを提示する前に、タイミングについて焦点を絞った質問を1つしてください。黙ってどちらかを選ばないでください。

追加のメイントラッククリップが許可されるのは2つ目の場合だけです。「すべてのショットの後」という明示的な要望に対し、直前のショットを短くしたり、覆ったりして対応してはいけません。CLIでは単色クリップを作成できないため、独立したクリップが求められた場合は、エンドカード用の画像を提供してもらうか、その生成を別途依頼してください。

フォントの選択

テキストの各種類にはデフォルトのフォントとポイントサイズがあります（references/capabilities.md を参照）。ただし、テキストが決まったらフォントについても確認してください。確認せずに進めてはいけません。ユーザーがすでにフォントを指定または説明している場合は、そのままフォントの決定に進みます。それ以外の場合は AskUserQuestion を使い、次の選択肢を提示します。

1. デフォルトを使用（推奨） — その種類のデフォルトのフォントとポイントサイズを使用します。--font／--font-file／--font-size は指定しません。
2. おすすめを表示 — cawcut vn fonts --json を実行し、候補を最大4つ提示します（ラベルはファミリー名＋スタイルとし、選択した編集スタイルに近いものから順に並べ、最も近い候補に （推奨） を付けます）。
3. フォントを指定する — フォント名、またはツールの自由入力「その他」オプションを使ったローカルファイルパス（--font-file に渡します）。

ユーザーのポイントサイズは変更せず、そのまま渡してください。これはキャンバスに対する相対値ではなく、VNの Font Size ボックスに表示される数値です。フォントフラグの動作と移植性については references/capabilities.md を参照してください。編集プランにテキストを含める場合は、フォントとポイントサイズも記載します（フェーズ7）。

6. カバーを確認する

新しいプロジェクトでは、ユーザーがすでに指定していない限り、編集プランを提示する前にカバーをどうするか明示的に確認してください。

• set-cover で明示的な写真カバーとして使用する、提供済みのPNG。
• ユーザーが提供する別のローカルPNG。
• VNが自動設定する最初のフレームのカバー。

この選択には AskUserQuestion を使ってください。プロジェクトを明確に表している提供済み画像があれば、それを推奨します。該当する画像がなければ、最初のフレームの自動設定を推奨してください。タイムラインの冒頭のショットと、VNで明示的に設定するカバーを混同しないでください。

7. 編集計画を提示し、承認を待つ

init、add-clip、add-audio、add-sound-effect、add-text、 add-srt、または set-transition を実行する前に、次の内容を含む具体的な計画を提示してください。

• プロジェクトのタイトル、アスペクト比、選択したスタイル、カバーの選択、推定合計時間。
• 順序どおりのショットと、各ショットのソースパスおよび画像の表示時間または動画のトリミング範囲。
• 各トランジションを明示的な境界 N → N+1: <種類> (<秒数>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-text で再度追加するのではなく、add-srt でインポートします。
4. show --json を実行し、結果を承認済みの計画と照合して、CLI で安全に修正できる差異があれば修正します。トランジションの差異は、set-transition（解除する場合は --type none）で必ずその場で修正できます。トランジションを修正するためにドラフトを作り直してはいけません。クリップの削除、タイミング変更、置き換え、並べ替えが必要な場合は、承認済みの計画に基づいて新しいドラフトを作成します。
5. validate を実行します。検証に合格するまで、完了を報告してはいけません。失敗したアセットを黙って除外したり、サポートされていない効果で代替したりしてはいけません。

9. VN を開くか確認する

show がプランと一致し、validate に合格した後に限り、cawcut vn status をもう一度実行します。ユーザーがその後 VN をインストールまたはアップグレードしている可能性があるため、フェーズ 0 の結果を再利用しないでください（また、ユーザーがそのまま編集に進んだため、フェーズ 0 で VN を確認していない場合もあります）。

• VN を使用可能： ラフカットが完成したことをユーザーに伝え、今すぐ VN で開くかどうかを尋ねます。
  • はい： cawcut vn project pack --open --project <dir> を実行します。開く処理に失敗した場合、CLI が理由とそのプラットフォームで動作する方法を示します。同じコマンドを再試行せず、その内容を伝えてください。
  • いいえ： アプリを起動せずに .vn の納品物を準備できるよう、cawcut vn project pack --project <dir> を実行します。
• VN を使用できない： 提示できる選択肢がないため、質問は省略します。cawcut vn project pack --project <dir> を直接実行し、任意の補足として VN のダウンロード／アップグレード用リンクに言及します。

ドラフトのディレクトリ、.vn のパス、長さ、クリップ／音声／テキストの数、意図的に簡略化した点を報告します。この最終確認の前に VN を開かないでください。

引き継ぎの境界

• メディアの受け渡し方法は 2 通りあります。ユーザーが自分のローカルファイルを直接提供する方法（例外的なケースではなく、通常のケースとして扱います）と、上流のスキルが生成した出力を引き渡す方法です。後者の場合は、有効なパスをそのまま信頼し、すでに決まっているアスペクト比、意図、音声に関する判断を再利用します。また、事前に決定された操作（プレビューか編集か）を信頼し、フェーズ 0 の確認を繰り返さないでください。どちらの場合も、タイムラインを変更する前に編集プランを提示します。
• ラフカットを作成せず、数個のファイルだけをプレビューしたいという依頼は、フェーズ 0 のプレビューとインポートの分岐に該当します。このワークフロー内で完結し、別の場所への引き継ぎは行いません。
• コマンド、フラグ、パスは英語のままにし、reply_language で会話します。