cawcut-ad-video

CawCut Ad Video

5 段階の AD Video ウィザード（Product → Config → Idea → Storyboard → Video）を使って、商品広告動画を作成します。各段階は、開発者向け API に対する cawcut ad-video コマンドに対応しています。コマンドフラグの一覧は references/api.md、各段階の説明と無効化マトリクスは references/stages.md、スクリプト編集の作成方法は references/script-editing.md、エラーからの復旧方法は references/troubleshooting.md に記載されています。スキル本文の先頭に表示されているベースディレクトリを使い、<base_dir>/references/<file>.md からこれらを Read してください。これらのファイルを find／grep で探さないでください。

返信言語。 そのターンのユーザーの言語に合わせて、すべての返信（文章、状況の更新、AskUserQuestion／AskQuestion の質問と選択肢のラベル）を行ってください。言語は、そのターンにおけるユーザーの実際のチャットメッセージの内容から判断します。Skill ツールの呼び出しに args パラメーターが含まれていたかどうかは判断材料になりません。これは無関係な任意のパススルーフィールドです。暗黙のトリガーも対象です。ユーザーのメッセージが /cawcut-ad-video という文字列そのものではなく、「广告视频」「商品广告」「make an ad for …」などのトリガーフレーズに一致したためにスキルが呼び出された場合、そのトリガーフレーズがそのターンのユーザーのチャットメッセージの内容となります。商品 URL が不足している場合に質問するときも含め、最初の返信からその言語を使ってください。呼び出しに言語を示す情報がまったく含まれていない場合（例：他に何も付けず、文字どおり /cawcut-ad-video のみの場合）に限り、英語を既定の言語としてください。ユーザーが別の言語で具体的な依頼を加えたら、その後のセッションではその言語を使ってください。返信言語にかかわらず、CLI コマンド／フラグ、JSON キー、URL、生のエラーコードは元の形式のまま維持してください。また、英語の CLI 出力をそのままユーザー向けの回答に貼り付けず、返信言語で要約してください。

ステップ 0 — 初期設定

実行環境に応じてログインモードを選択する

コマンドを実際に実行する場所に応じて選択します。ユーザー自身のコンピューターで実行する場合は、cawcut auth login --browser --json を実行します。CLI がブラウザーを開き、承認を待ちます。ユーザーのブラウザーにアクセスできないリモート環境、VM、またはコンテナーでは、cawcut auth login --device-auth --json を実行し、ユーザーに authorization_url を送って、ユーザー自身のコンピューターで開いて承認してもらいます。どちらのモードでも JSON に対応しています。構造化された出力が必要であることは、デバイス認証を選ぶ理由にはなりません。エージェント名、非 TTY シェル、localhost URL だけでは、コマンドの実行場所は判断できません。把握している実行コンテキストを使い、明示的なモードフラグで CLI の自動判定を上書きしてください。

デバイスログインでは、続けて cawcut auth login --complete --wait --timeout 60 --json を実行します。ツールの実行タイムアウトが短い場合は、next_poll_after_seconds に従って、--complete --json を単独で呼び出してください。デバイスログインが中断された場合、または wait_timeout が返された場合は、新しいリンクを作成せず、保存された現在のリクエストを再開してください。ブラウザーログインでは従来のループバックコールバックを使います。中断された場合は、--complete を使わずに cawcut auth login --browser --json を再実行してください。status=pending は認証成功を意味しません。status=authenticated になってから、元の操作を再試行してください。拒否または期限切れになった場合、このリクエストは終了です。承認リンクを際限なく作成しないでください。パスワード、トークン、またはウェブページからコピーしたコードをユーザーに尋ねないでください。

ブートストラップは、ユーザー向けの段階ではなく、目立たない安全策として実行してください。

1. AI セッションごとに最大 1 回です。 この AI セッションですでに cawcut コマンドが 1 つでも成功している場合は、ブートストラップの確認をすべてスキップして続行してください。
2. 明示的な確認コマンドは 1 つだけ使用します。 cawcut upgrade check --json。
   • "update_available": true の場合は、ホストシェルで自分で cawcut upgrade を実行してください（ユーザーに入力を求めないでください）。成功したら、ステップ 1 からこのスキルを続行してください。
   • "ahead_of_registry": true の場合は、アップグレードせずに続行してください。
   • cawcut が見つからない場合は、ユーザーに npm install -g @ubnt/cawcut のインストールを依頼してください。その後、ブートストラップを続行してください。
   • その他の確認エラーはそのまま続行し、後続の CLI コマンドが失敗した場合に限り、警告について言及してください。
3. 「bootstrap checks passed」と表示しないでください。 ステップ 1 に直接進んでください。
4. 最初の実コマンドで認証を検証してください。トークン／認証エラー（Token expired を含む）が発生した場合は、上記のログイン手順に従ってください。実行環境に適したモードを使用し、status=authenticated の後に限り、失敗したコマンドを 1 回だけ再試行してください。CLI コマンドは自分で実行し、ユーザーにはブラウザーでの承認のみを依頼してください。
5. 構造化されたユーザー確認ツール（セッションごとに確認）。 Claude Code では選択肢が列挙される質問すべてに AskUserQuestion を使用し、Cursor では AskQuestion を使用してください。どちらかを利用できる場合、このスキル内の列挙式の選択（プラットフォーム、解像度、時間、動画タイプ、ストーリーボードのスタイル、言語、アイデア候補、クレジットの確認など）では、すべて必ず使用してください。候補リストがポップアップに収まらない場合も同様です。 長いリストでもツールを開き、先頭の項目を選択肢として表示し、後の項目を入力して選べるよう、完全な番号付きリストをその横に示してください（「インタラクティブな選択」を参照）。

ウィザードの概要

① Product    create → analyze run → poll → review/confirm analysis
② Config     options → pick settings → config set
③ Idea       idea run → poll → pick candidate (or custom) → idea select
④ Storyboard storyboard run → poll → (optional edit / regenerate) → image quote → confirm → image run (×2 if hand-drawn)
⑤ Video      video quote → confirm → video run → poll → download

1 つのプロジェクトにつき、video_ad_id は 1 つです。各長時間ステージは --wait なしで起動し、同梱スクリプトでポーリングしてください（「ポーリング」を参照）。唯一のポーリングポイントは cawcut ad-video detail <id> --json です。 outputs マップを返すのはこのコマンドだけです。

バンドルスクリプトランナー

プロジェクト操作や詳細の確認には、cawcut CLI コマンドを直接使用します。ホストプラットフォームに対応するバンドルヘルパーを選択してください。Windows のヘルパーには PowerShell とインストール済みの cawcut CLI が必要です。Python、jq、bash、外部の curl は必要ありません。このスキルのために、Windows ユーザーにこれらのツールのインストールを求めないでください。macOS/Linux の .sh ヘルパーには jq が必要です。どちらのプラットフォームでも Python は使用しません。

• macOS/Linux：bash <base_dir>/scripts/<name>.sh …
• Windows PowerShell：powershell -ExecutionPolicy Bypass -File "<base_dir>\scripts\<name>.ps1" …

4 つのヘルパー（poll、script_plan、storyboard_review、download_media）には、同等の .sh と .ps1 の実装があります。1 回の実行では、対応する拡張子とプラットフォーム固有のフラグを一貫して使用してください。たとえば、bash の --kind video は PowerShell では -Kind video です。

Stage ① — Product

1. 商品の URL を取得します（Amazon／Shopify／公式ページのいずれでも構いません）。ユーザーが URL を提示していない場合は、自由回答形式でプレーンテキストで尋ねてください。プロジェクト名は尋ねないでください。分析／エクスポート後に、バックエンドが商品情報からプロジェクト名を自動設定します。
2. cawcut ad-video create --url "<url>" --json を実行し、id を取得します。作成時の --url は省略可能です（空のドラフトも作成できます）が、ユーザーが URL を提示している場合は必ず渡してください。後で analyze run を実行する際には、いずれにせよ URL が必要です。--category は省略可能です。省略すると、分析後にバックエンドが自動検出します。ユーザーが特定のタイトルを明示的に指定した場合に限り、--name を渡してください。
3. cawcut ad-video analyze run <id> --url "<the product URL from step 1>" --json を実行します（--wait は指定しないでください。API では本文に url が必要です）。その後、プラットフォームに応じたランナーでポーリングします。macOS／Linux では poll.sh <id> '.status' stage_completed 600 15、Windows では poll.ps1 <id> '.status' stage_completed 600 15 を実行してください。
4. detail <id> --json の結果を読み取り、分析結果を提示します。
   • 商品情報をそのまま提示 — 値が設定されているすべての product_info フィールドを含めます。対象は name、description、selling_points[]（各項目を省略せず番号付きで提示）、target_audience、brand_style、promotional_info、source_platform、category です。商品コンテンツ自体は要約、短縮、翻訳しないでください。これはユーザーのマーケティングコピーであり、返されたとおりに提示する必要があります。周囲のラベルと文章のみ、reply_language に従ってください。
   • 商品画像 — まず、プラットフォームに応じた download_media ヘルパーを使って画像をダウンロードします。<id> --kind product を指定してください。その後、カテゴリごとに提示します（ラベルは reply_language に従います）。
     • ロゴ（logo_images）とメイン画像（primary_images）：ダウンロードしたローカルパス（例：~/Downloads/ad-video-<name>/product/logo-1.jpg、primary-1.jpg）を使い、ホストのファイル送信ツール（例：Claude の SendUserFile）で各画像をインライン表示します。Markdown リンクではクリック可能な行として表示されるだけで、画像は表示されません。
     • 追加の商品画像（images[]）：インラインプレビューに対応している場合は、1 枚ずつ列挙し、それぞれに Product Image #n のラベルを付けてインライン送信します。表示は最大 9 枚までとし、それ以上ある場合は、…and N–9 more のように残りの枚数を伝え、残りは <dest>/product/ フォルダーにあることをユーザーに知らせます。インラインプレビューに対応していない場合は、ローカルパスを表にして提示します（# とパスの列）。同じフォルダーも案内してください。
     • どちらの形式でも asset_id 列は含めません。ローカルパスはプレビュー用の参照にすぎません。これらのファイルはユーザーが画像を確認できるように用意されているものです。CLI に渡さないでください。 その後、AskUserQuestion を使って、内容の確認または修正をユーザーに求めます。
   • ✅ Looks good → Stage ② に進みます。
   • ✏️ Edit product info → 変更内容を確認し、そのフィールドだけを cawcut ad-video product set <id> … に渡します。このコマンドはまずプロジェクトを読み込み、渡されなかったフィールドをすべて引き継ぎます（API は product_info 全体を置き換えるため、たとえば --product-name だけを指定すると、説明、画像、セールスポイントが消えてしまいます）。
     • 画像リストは、渡すと置き換えられます。 --logo／--primary-image／--asset には、保持する項目の完全なリストを指定してください。画像を削除する場合も同様です。置き換えられたリストはその選択内容を失い、バックエンドはデフォルトに戻します（--asset ではすべての候補、ロゴ／メイン画像では最初の候補）。ダウンロードしたファイルを再送しないでください。保存済みの参照はすでに asset_ids として返されます。
     • プロジェクト外からユーザーが提供した画像に限り、ローカルパスを渡してください。CLI が新しいアセットとしてアップロードします（有効期間 7 日）。
     • --description "" は説明を消去し、--clear-selling-points はセールスポイントを空にします。空のリストは実際の状態であり、「未設定」ではありません。
5. ユーザーが実行中の分析を中止したい場合は、cawcut ad-video analyze cancel <id> を実行します。 素材の権利（ユーザーが独自の画像を提供する場合に、一度だけ伝えてください）。 CLI からアップロードされた画像は、素材のコンプライアンスチェックを受けず、そのまま受け入れられます。ウェブポータルとは異なり、権利を確認する手順はありません。このチェックは、第三者のロゴや有名人の肖像を検出するためのものです。この方法では、素材の権利を保有する責任はユーザーにあります。ツールが確認済みだと思われないよう、アップロードの前にこの点を一文ではっきり伝えてください。これは、ユーザーが提供する新しいファイルにのみ適用されます。プロジェクト内にすでにある画像（クローラーが抽出した商品画像）は、もともとこのチェックの対象ではありません。

Stage ② — 設定（すべてのオプションは実行時に取得し、ハードコードしません）

1. cawcut ad-video options --video-ad-id <id> --json → video_settings（publish_to、languages、aspect_ratios、resolutions、duration_ranges、video_types、storyboard_styles、video_models、defaults）を読み取ります。

2. 次の順番で項目を確認します。字幕がそもそも選択肢になるかどうかと、使用可能なモデル／解像度の組み合わせの両方を決めるため、最初に動画タイプを確認します。

   • 動画タイプ — video_types の各エントリーを1つずつ選択肢として提示します。
   • 動画モデル — **video_models が空でない場合のみ。**候補は video_models[].value、デフォルトは defaults.video_model です。一覧を載せる表には、# に加えて3つの列を含めます。モデル、その supported_resolutions、defaults.video_model を示すデフォルトマークです。モデルを選ぶと次の項目で選択可能な解像度が決まるため、解像度も表に含めます。候補がちょうど1つの場合は、文章で伝えて先に進みます（選択肢が1つなら選択ではありません）。候補がない場合は、この項目を省略します。
   • 解像度 — デフォルトは defaults.resolution とし、選択したモデルの supported_resolutions に合わせて制限します（サーバーが検証に使用するものと同じリストです）。モデルがサポートしていない解像度は提示しません。config set で拒否されるためです。モデルを選択していない場合は、resolutions の全リストを提示します。
   • 自動字幕 — **product_with_voiceover と talking_video の場合のみ。**字幕はナレーション／会話の音声トラックから焼き込まれるため、product_showcase には字幕を付けるものがありません。質問せず、--auto-captions false を明示的に渡します（このタイプでは値を強制的にオフにするウェブポータルと同じ動作です）。
   • プラットフォーム — 各選択肢の説明に default_aspect_ratio を表示します（例：TikTok — 9:16）。言語、長さ、ストーリーボードのスタイルも確認します（説明：手描きでは、フォトリアリスティックなパネルの前にスケッチ工程が追加されます）。
   • **アスペクト比は質問しません。**プラットフォームに紐づいています（比率の選択項目がないウェブポータルと同じ動作です）。選択した publish_to オプションの default_aspect_ratio を自動的に使用します。比率を個別に尋ねてはいけません。ユーザーが明示的に上書きを指定した場合に限り、プラットフォームのデフォルトを変更します。

   各項目は 1回の AskUserQuestion 呼び出しにまとめます。1回の呼び出しにつき質問は各項目につき1つ、最大4つまでです。項目数の多い軸（プラットフォーム、言語、動画モデル）では、Interactive selection のオーバーフロー形式に従います。メッセージ本文に全リストを番号付きの表で示し、# に加えて、その項目に必要な情報を記載します。プラットフォームならラベルと default_aspect_ratio、言語ならラベル、モデルならラベルと supported_resolutions およびデフォルトマークです。質問自体は短い一文にし、ポップアップには先頭の項目を番号付きの選択肢として表示します。それ以降の項目は、自由入力欄に番号または名前で回答してもらいます。各項目にはそれぞれ独立した表と番号を使用します。回答はその項目専用のフィールドに入力するため、2つの番号を同時に尋ねてはいけません（1 + 10）。

3. cawcut ad-video config set <id> --publish-to … --language … --aspect-ratio <the platform's default_aspect_ratio> --resolution … --duration-seconds … --video-type … --video-model … --storyboard-style … --auto-captions … --json

video_model は実際にコストを左右する項目です。提示する際は、より安価なモデルが利用できる場合があることを伝えます。ただし、エンドポイントから返されていないモデルは提示してはいけません。

ステージ ③ — アイデア

1. cawcut ad-video idea run <id> --json を実行し、outputs.generated_marketing_messages.status === "succeeded" になるまでポーリングします。
2. 最大8件まで表示し、それ以上は表示しません。 1回の実行で最大16件の候補が生成されますが、detail で返されるのは一度に1ページ（4件）だけなので、新たに読み込むと最初の4件のみが表示されます。outputs.generated_marketing_messages を読み込み、8件が表示されるか has_more === false になるまで、cawcut ad-video idea load-more <id> --json を呼び出します（呼び出すたびに detail を再読み込みします）。いずれか早い方で終了します。
   • load-more では、すでに生成された候補を表示するだけです。LLM の呼び出しやクレジットの消費はありません。
   • 8件は上限であり、目標件数ではありません。 プロジェクトに8件未満しかない場合は、その件数のみを表示します。8件が表示されたら、has_more が true のままでも、それ以上は表示しません。このフローに「もう1バッチ」進む手順はありません。
   • 表示件数を明示し、プロジェクトにある候補をすべて表示していない場合に、すべて表示したかのように伝えてはいけません。
3. 候補は全文をそのまま表にして表示します。候補ごとに1行とし、列は #、タイトル、内容です。要約、言い換え、省略、翻訳はしません。これはユーザー自身のマーケティング文案であり、ユーザーは候補全体を比較して選びます。件数を最初に示します（例：「8件の候補を表示しています：」）。# 列はポップアップ内の番号です。この表は、ポップアップに表示しきれなかった番号を入力する際の基準になります。
4. 選択は1回、質問も1つだけです。 選択肢は AskUserQuestion を1回だけ提示します。候補について質問した後、その回答に対する次の操作を尋ねる2つ目の質問をしてはいけません。選択肢は次の順に4つ提示します。
   • 1. <タイトル>、2. <タイトル>、3. <タイトル> — 最初の3件を、それぞれ番号付きで提示します。
   • ✏️ Write my own → ユーザーまたはエージェントが作成したアイデアのテキストを、idea select <id> --custom "<text>" で送信します（60～10000文字。ウェブ版のカスタムアイデアの制限に合わせます）。これはポータルのカスタムパスに従います。CLI はこのテキストを custom_content として is_custom: true とともに送信します。生成済み候補の選択として扱ったり、タイトルで囲んだりしてはいけません。
   • 4件目から8件目までの候補は、自由入力欄に番号またはタイトルを入力して選択します。ユーザーが提示された選択肢の中から回答できるよう、この方法を質問文自体に reply_language で明記し、推測させてはいけません。
5. 選択された場合：cawcut ad-video idea select <id> --message-id <mm-N> --title "<title>" --content "<content>" --json を実行します。送信前にタイトルや内容を軽く編集できることを案内します。
6. 新しいバッチを生成するのは、ユーザーが明示的に希望した場合だけです。 idea regenerate は選択肢に含めません。ユーザーが「换一批」や「regenerate」のように自分の言葉で新しいバッチを求めた場合は、まず現在の選択がクリアされることを警告してから、cawcut ad-video idea regenerate <id> --json を実行し、ポーリングします。その後、再度表示し（手順2）、選択を尋ねます（手順4）。

ステージ ④ — ストーリーボード

順序はウェブポータルに準じます：エンティティ → 料金 → キャラクター → ロケーション → スクリプト → 画像（ビジュアルディレクションは画像のステップ内）。 最初の編集の前に <base_dir>/references/storyboard-stage.md を読みます。エンティティコマンドは <base_dir>/references/character-scene.md、スクリプトの編集は <base_dir>/references/script-editing.md にあります。キャラクター／シーン機能のない旧プロジェクトでは、ステップ 1～4 とビジュアルディレクションの質問をスキップし、元のフローを維持します。

1. どのエンティティがありますか？ アイデアが確定した後、character estimate <id> --wait --json を実行します。スクリプトにキャラクター、シーン、両方、またはどちらも必要ないかをユーザーに伝えます（character.needed / location.needed）。どちらも不要な場合 → キューに入るのはスクリプトだけです。

2. 料金の確認（必須）。 estimated_credits（0 = 無料）を表示し、AskUserQuestion で確認します：✅ Confirm & generate / ⏸ Not now。回答を得てから初めて storyboard run <id> --confirmation-token <token> --json を実行します。これによりキャラクター／シーンの画像生成が開始され、クレジットが消費されます。回答前に決して実行してはいけません。

3. レビューキュー — CLI に対象を選ばせます。 storyboard_review スクリプト（wait → images → script table）を実行し、その後 cawcut ad-video review next <id> --json を実行して、CLI が指定した項目だけを1ターンにつき1つ表示します：character → location → script。wait → ポーリングを続けます。done → ステップ 4 へ進みます。ユーザーが項目を承認したら review approve <id> --item <item> を実行し、続けて review next を実行します。承認は表示した内容に紐づいています。スクリプトや画像を再生成した場合（新しいアイデア、新しいプロンプト、編集）は再びレビュー対象になり、review next が done を返すまで image quote/run は拒否されます。

   • character / location： 名前、画像、画像プロンプト（entities[].names / prompts）、ステータスを表示します。✅ This character works / 📝 Regenerate from a new prompt と尋ねます（シーンの場合：✅ This scene works）。新しいプロンプトを使う場合は references/storyboard-stage.md の手順を実行し、新しい画像を表示して再度確認します。自分の画像のアップロードと音声の選択はまだ利用できません。決して提案してはいけません。
   • script： portal_url の文字列そのもの（ad-video url <id> --json）とともに script_table を表示します（shot_prompt / video_prompt は表示しません）。✅ Looks good / ✏️ Work on the script / 🔁 Regenerate the script と尋ねます。編集と再生成は references/script-editing.md に従います。再生成するとすべての編集が破棄されるため、必ず事前に警告してください。

4. 画像 — CLI に次の作業を指定させます。 cawcut ad-video image next <id> --json を実行し、その next_step の指示どおりに進めます。各工程または回答の後に再実行します。

   • sketch → image quote --generation-type hand_drawn → クレジットを確認 → image run（見積もりのタイミング）を実行し、ポーリングしてスケッチをプレビューします。その後 ✅ Continue / ✏️ Edit script と尋ねます。
   • visual_direction → カスタムプロンプトについて質問します（下記参照）。回答を得るまで image quote/run --generation-type photo_realistic はCLI に拒否されます。
   • photo → image quote --generation-type photo_realistic → 確認 → image run を実行し、3600 の期限でポーリングして、download_media <id> --kind storyboard でプレビューします。
   • done → ステージ ⑤ へ進みます。

   ビジュアルディレクションの質問（カスタムプロンプト1つで、写実的なストーリーボードと最終動画のスタイルを指定します。1回だけ、写実的な工程の直前に質問します。スケッチがある場合はその後、ない場合はスクリプトの直後です）。保存済みのテキスト（instruction）を表示して、次のいずれかを尋ねます：✅ No extra direction → instruction confirm <id> を実行／🎨 Add or change visual direction → instruction set を実行（references/storyboard-stage.md を参照）。画像または動画がすでにある場合、保存するとそれらは古い状態（need_regenerate）になります。事前に警告し、同意を得てください。

未回答の質問も実行中のポーリングもない状態でターンを終えてはいけません — 生成が完了したら、上記の順序で次の項目を表示して質問します。エンティティの失敗（next_step: fix_failed）は表示し、スキップしてはいけません。再試行するのは同意を得てからに限ります。

Stage ⑤ — 動画

1. cawcut ad-video video quote <id> --json → AskUserQuestion でクレジットを確認 → 直ちに cawcut ad-video video run <id> --confirmation-token <token> --json を実行します（変更のない結果をユーザーが明示的に再レンダリングする場合に限り、--force を追加します）。
2. final_video / voiceover_final_video / talking_video のいずれかが succeeded になるまでポーリングします。ポーリングテーブルに記載された期限は 3600 です。
3. 成功したら、cawcut ad-video video deliver <id> --json で動画をプロジェクトフォルダーにダウンロードし、report（ローカルパスと、すぐ使える Markdown リンク形式の Portal リンク）、local_path、portal_url を取得します。
4. まず引き継ぎメッセージを送信してください。ファイルだけを送ってもレポートにはなりません。 report で始まるテキストメッセージを 1 通送り、Markdown リンクは単独の行に置き、ラベルは reply_language にします。同じメッセージに URL を含めずに Portal について言及してはいけません。結果の URL は不要です。送信後に限り、local_path を指定して 必ず cawcut-vn に引き継いでください。VN メニューを表示したり、独自に cawcut vn コマンドを実行したりしてはいけません（判断は一度だけです。VN の判断は引き継ぎ先のスキルが担い、再確認はしません）。

メディアのプレビューとダウンロード

API が返すすべてのメディア URL（商品画像、ストーリーボードのスケッチ／グリッド、最終動画）は事前署名済みです。追加の署名手順は不要で、そのまま curl でダウンロードできます。403 エラーが発生した場合は、detail を読み直し、新しい URL で再試行してください（商品画像の URL は detail を呼び出すたびに再署名されます）。

プレビューの優先順位（商品ロゴ／メイン画像、ストーリーボードのスケッチ／グリッド）：

1. ホストにファイルをユーザーへ送信するツール（例：Claude の SendUserFile）がある場合は、まずファイルをダウンロードしてから送信し、チャット内でユーザーがそのままプレビューできるようにします。
2. それ以外の場合は、ダウンロードしたファイルを open（macOS）で開くか、ローカルパスを報告するだけにします。

手作業で curl／jq のパイプラインを組まず、必ず同梱のダウンローダー（キャラクター／シーン画像：cawcut ad-video entities download <id>。storyboard_review によってダウンロード済み）を使用してください。また、シェル変数に status という名前を付けてはいけません（zsh では読み取り専用です）。

# macOS/Linux
bash <base_dir>/scripts/download_media.sh <id> [--kind product|entities|storyboard|video|all] [dest_dir]

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File "<base_dir>\scripts\download_media.ps1" <id> [-Kind product|entities|storyboard|video|all] [-Destination <dir>]

デフォルトの保存先：~/Downloads/ad-video-<product-name>（プロジェクト名が付く前は ad-video-<id> にフォールバック）。構成：product/（ロゴ＋メイン画像＋追加画像）、entities/（character-N／location-N）、storyboard/（スケッチ＋パネルグリッド）、最終動画はフォルダーのルートに保存されます。保存したパスがすべて表示されるので、それらを reply_language でユーザーに伝えてください。

無効化の意味（必須 — Web ポータルに準拠）

変更操作（product set、config set、idea select、storyboard set）の後は毎回、次の手順を実行してください。

1. 直ちに cawcut ad-video detail <id> --json を実行します。まず、クリアされた成果物と、保持されているが古くなった成果物を区別してください。どちらもプロジェクト履歴から推測してはいけません。
   • クリエイティブ設定のいずれかのフィールド（--duration-seconds、--language、--video-type、--storyboard-style、--publish-to）を変更すると、下流のコンテンツがクリアされます。outputs.generated_marketing_messages に使用可能な成功済みの value / selection がなくなった場合、以前のアイデアは現在のプロジェクト状態には存在しません。そのアイデアを再利用するか、保持するか、引き続き使用するかを尋ねてはいけません。また、選択肢として提示してはいけません。 Stage ③ に進み、cawcut ad-video idea run <id> を実行して成功するまでポーリングし、新しいアイデアを選択してから新しいストーリーボードを生成します。
   • status: "succeeded" で need_regenerate === true のまま存在している出力のみが、保持されているが古くなった出力であり、再生成するか後回しにするかの判断対象です。クリアされた出力は古くなったものでも再利用可能なものでもありません。
2. need_regenerate === true のまま保持されている outputs.<key> をすべて集めます。該当するものがある場合は、影響を受ける成果物をユーザーに1つのメッセージで列挙してから、AskUserQuestion を1回だけ行います。
   • 🔄 Regenerate affected → パイプラインの順序に従って、影響を受けるステージを再実行します（storyboard run → image quote/run → video quote/run）。生成ステージごとに、クレジットを再度見積もり、確認を取ります。
   • ⏸ Later → 再生成せずに続行し、古くなった成果物を伝えます。
3. 編集中に再生成してはいけません。 ユーザーの編集をすべてまとめてから、再生成を1回だけ行います。スクリプトを保存したときは、影響を受ける出力が再生成を必要とする状態として表示するだけにしてください。画像または動画の見積もり／実行を開始してはいけません。image run / video run は、そのステージの新しい見積もりをユーザーが明示的に確認した後にのみ実行します。また、上流の出力に need_regenerate=true がある間は実行が拒否されます（VIDEO_AD_NEEDS_REGENERATION）。

見積もりのタイミング（必須）

confirmation_token は見積もりから5分後に期限切れになります。必ず、見積もり → AskUserQuestion で確認 → 実行の順に、間にユーザーとのやり取りを挟まず続けて行ってください。run がトークン／確認エラー（期限切れまたは無効化）で失敗した場合は、見積もりを取り直し、再度確認を求めてから、もう一度実行してください。試行ごとに1回だけ行い、無言で再試行してはいけません。

支出の確認を求める前に、残高を確認してください（必須）。 image quote / video quote は、estimated_credits とともに credits_balance、credits_shortfall、credits_sufficient も報告します。確認を求める前に、これらを確認してください。

• credits_sufficient === false → 数値を明確に伝えます（「これにはXクレジット必要ですが、残高はYクレジットで、Zクレジット不足しています」）。Web ポータルでクレジットを追加するよう案内してください。確認メニューでは通常の確認と実行ではなく、💳 Top up credits / ⏸ Not now を提示します。支払いできないユーザーを課金に誘導してはいけません。
• credits_sufficient === true、または残高を取得できない場合（credits_balance_error — 残高の照会はベストエフォートであり、決して処理を妨げてはいけません）は、通常どおり確認を求めます。
• 残高不足を、事後に一般的な失敗として伝えてはいけません。実行前に伝えることが重要です。
• クレジットの追加にはトークンの有効期限である5分を超える時間がかかります。ユーザーが戻ったら、見積もりを取り直し → 再度確認を求め → 実行してください。期限切れのトークンを再利用してはいけません。

ポーリング（同梱スクリプト — 必須）

--wait を付けずにトリガーし、プラットフォーム固有の同梱スクリプトでポーリングします。ポーリングループを独自に作成しないでください。場当たり的な echo "$var" | jq ループは、zsh では（echo が \n エスケープを解釈するため）JSON を破損させ、終端状態に一致しないまま無限に動き続けます。

bash <base_dir>/scripts/poll.sh <id> '<json_path>' <success_value> <timeout_s> [interval_s=30]

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File "<base_dir>\scripts\poll.ps1" <id> '<json_path>' <success_value> <timeout_s> [interval_s=30]

Stage	json_path	success_value	timeout_s
① 分析	.status	stage_completed	600
③ アイデア	.outputs.generated_marketing_messages.status	succeeded	600
④ プラン	.outputs.storyboard_plan.status	succeeded	3600
④ プロンプト	.outputs.storyboard_plan.prompt_status	succeeded	600
④ スケッチ	.outputs.storyboard_sketch.status	succeeded	3600
④ パネル	.outputs.storyboard_image.status	succeeded	3600
⑤ 動画	.outputs.final_video.status // .outputs.voiceover_final_video.status // .outputs.talking_video.status	succeeded	3600

Windows ヘルパーは、これらのドット区切りパスと // によるフォールバックを内部で解析します。Windows では json_path に jq は必要ありません。

終了コード：0 成功 · 2 失敗（detail --json の出力にある error を報告してください。references/troubleshooting.md を参照） · 3 タイムアウト → AskUserQuestion ⏳ Continue waiting（スクリプトを再実行）／❌ Stop（プロジェクトは保持されます。後で cawcut ad-video detail <id> で再開してください） · 4 出力を解析できない → ポーリングを停止し、cawcut ad-video detail <id> --json を一度実行して内容を確認します（認証／CLI の問題）。

スクリプトは通知しません。通知するのはホストのツールです。 poll.sh は終了コードを返して終了し、それ以外は行いません。シェルから OS 通知を送信しないでください（osascript、notify-send、BurntToast）。スクリプトに通知機能を追加しないでください。また、ユーザーのマシンで通知権限を独自に登録しないでください。シェルコマンドから表示されるトースト通知はアプリ独自の通知とは別の経路であり、ユーザーが求めたものではありません。

所要時間をユーザーに伝える

生成時間を独自に見積もらないでください。また、期限を所要時間として伝えないでください。 実行時間はサーバーが計算し、ステージの実行中は detail に estimated_running_ms（ミリ秒）として含まれます。poll.sh は最初の確認時にこの値を読み取り、estimated: about Nm の行を一度だけ出力します。値があれば、その時間を伝え、それ以上は付け加えないでください。値を直接確認する必要がある場合は、detail --json の読み取り結果に含まれています。

API から値が得られない場合（フィールドがないかゼロの場合。検索はベストエフォートのため、見つからないことがあります）は、期限ではなく桁の目安を伝えてください。これらのステージは数分程度かかります（これらのステージを担当するノードの見積もりは、数秒から数分程度です）。そのため、「数分ほどです」と伝え、完了したらすぐに知らせることを付け加えてください。所要時間は不明だと言わず、長めに見積もらないでください。

timeout_s 列は待機を打ち切る期限であり、実行時間ではありません。 行に 3600 とあるからといって「最長で約 1 時間」と伝えるのは、時間の範囲をでっち上げるのと同じ誤りです。これはスクリプトが待機を停止する時点であり、通常、実際の実行時間より桁違いに長く設定されています。期限は、たとえ「最大で」などとぼかしても、返信に含めてはいけません。

時間がかかるステージ — その間、ユーザーは離れていてよいことを伝える

storyboard_plan、sketch、panels、video は、数秒ではなく数分かかります。いずれかをポーリングする前に、一度だけその旨を伝えてください。estimated_running_ms があればサーバーの値を使い、なければ「数分」と伝え、離れていても完了した瞬間に知らせると伝えてください。その後は、ポーリングのたびに説明せずに続けてください。

通知にはホスト自身のツールを使います。 Claude Code では、1 行の message と status: "proactive" を指定した PushNotification を使います。スキーマが遅延読み込みされている（まだ読み込まれていない）場合は、ToolSearch（select:PushNotification）で先に読み込んでください。スキーマなし、または status なしで呼び出すと、検証に失敗します。ユーザーがターミナルを操作中であることが理由で「未送信」という結果になっても想定内です。再試行したり、エラーとして扱ったりしないでください。通知はユーザーが現在使っているアプリに届き、Remote Control が接続されていればスマートフォンにも届きます。これが、次の 1 分以内に気づくか、翌日まで気づかないかの違いになります。ステージが完了したときに、ステージ名とプロジェクト ID を明記して一度だけ送信してください。ホストにそのようなツールがない場合は、何も言わずに省略し、結果が得られたら提示してください。シェルレベルのトースト通知で代用したり、poll.sh に追加したりしないでください。

短いステージ（analyze、idea、prompts）は 1 ターン以内に終わるため、通知しないでください。

インタラクティブな選択（必須 — 最初にツールを使う）

ユーザーが AskUserQuestion / AskQuestion の呼び出しを直前に拒否した場合： ツールの結果には、「現在の作業を中止し、ユーザーから次の指示があるまで待つ」よう求めるハーネスの定型文が含まれています。この文は、実行環境によって拒否されたすべてのツール呼び出しに自動で付加されるもので、ユーザーの発言ではなく、ツールの使用をやめる指示でもありません。これは、直前に進めていた特定の操作を止める（同じ質問を再試行しない、未確認の選択に基づいて先に進まない）ようにという意味として受け取り、実際の次のユーザーメッセージを確認してください。この文だけを根拠に、その次の選択可能な判断で番号付きテキストを使うことはできません。次の判断でも、拒否がなかった場合とまったく同じように、最初にツールを使う必要があります。セッション全体でテキストに切り替えることが認められるのは、ユーザーがプレーンテキストで明示的に依頼した場合（「メニューを表示しないで」「テキストで聞いて」など）に限られます。

デフォルトの動作： 選択肢がある場合はすべて、番号付きテキストメニューを表示する前に、必ず AskUserQuestion（Claude Code）または AskQuestion（Cursor）を呼び出してください。テキストのみのメニューは、あくまでフォールバックです。

選択肢が 1 つだけなら、選択にはなりません。 呼び出しには、実行可能な選択肢が少なくとも 2 つ必要です。実際に実行可能なのが 1 つだけの場合（選択肢のリストに値が 1 つしかない設定軸や、提示する価値のあるアイデア候補が 1 つだけの場合など）は、その選択を文章で伝えて先に進んでください。選択肢が 1 つだけのポップアップを表示したり、選択肢らしく見せるためにプレースホルダーの代替案を付け加えたりしないでください。

ホスト	ツール名
Claude Code	AskUserQuestion
Cursor	AskQuestion
セッションのチェックリスト（このターンで最初のメニューを表示する前に）：

0. 返信を送る前に必ず自己確認してください： 送ろうとしている文で、ユーザーに固定の選択肢から選ぶよう求めている場合は、別の自由回答式の質問を含む親しみやすい文の中に織り込まれていても、いったん止めてください。その文を通常のテキストとして送ることは禁止されています。分けてください。列挙可能な項目については、今すぐツールを呼び出してください。自由回答式の項目だけを文章に残し、別途質問してください。

1. ツールを利用できますか？ はいの場合は、列挙可能なすべての選択について、必ずツールを使ってください。ポップアップに収まらない候補リスト（項目3）も対象です。

2. ツールがない場合（CLI のみのホスト）は、reply_language で番号付きテキストを使ってください。

3. 候補の数が1つの質問で提示できる4つの選択肢を超える場合（長いカテゴリ、モデル、候補リストなど）でも、ツールを開いてください。回答の各部分に、それぞれ適切な場所を用意してください。

   • リスト全体 → メッセージ本文に番号付きのテキスト表を記載します。各項目を1行にまとめ、# と、その項目に含まれる列を記載してください。たとえば、プラットフォームの default_aspect_ratio、言語のラベル、モデルの supported_resolutions とデフォルトのマーク、候補のタイトルと内容などです。リストを質問文にそのまま含めないでください。22個のモデル一覧を質問の見出しに貼り付けると読みづらく、質問が埋もれてしまいます。表とツール呼び出しは同時に送ります。
   • 質問文 → 選択内容を示す短い文を1つと、ポップアップに収まらない項目を示す案内を記載します（例：「項目4～22は、番号または名前を以下に入力できます」を reply_language で記載）。
   • ポップアップ → 番号を付けた先頭の項目を、必須のアクション（自由入力など）をクリック可能な状態で残せる範囲で、できるだけ多く選択肢として提示します。
   • 自由入力欄 → ポップアップに収まらなかった項目を、番号または名前で入力できるようにします。

   番号は、表とポップアップを結び付けるためのルールです。ポップアップに収まる項目はすべてクリック可能な状態にし、テキスト入力はポップアップに収まらない項目にのみ使います。選択は1つの質問で完結させてください。1つ目の質問への回答をどう扱うか、2つ目の質問で尋ねることは禁止です。

ツールを利用できる場合は禁止されること： ツール呼び出しの代わりに番号付きテキストのメニューを提示すること、ポップアップなしで「番号または名前で返信してください」と伝えること、ユーザーに列挙値を記憶から入力するよう求めること。長いリストの番号付きテーブルはテキストメニューではありません。ツール呼び出しの索引であり、単独で送ることはありません。

選択肢の値をハードコードしないでください。 プラットフォーム、解像度、長さ、動画の種類、動画モデル、ストーリーボードのスタイル、言語、スタイル ID は、このドキュメントやトレーニングデータではなく、このセッションで cawcut ad-video options --json を実行した結果から取得してください。

UX ルール

1. 簡潔にします。デフォルトの出力は結果 URL とローカルパスです。デバッグ時を除き、生の JSON ダンプは出力しません（--json はポーリングスクリプト用です）。
2. 返信言語：ファイル冒頭のルールを参照してください。最初の返信や AskUserQuestion の質問／ラベルも含め、すべての返信でユーザーの言語に従い、CLI の出力は生の英語を貼り付けず、reply_language で要約します。
3. curl で CawCut HTTP API を呼び出さないでください。認証とトークンは CLI が処理します。
4. 選択肢を先に提示 — 設定項目、アイデア候補、クレジット確認、再生成確認など、選択可能な判断はすべて Interactive selection に従い、AskUserQuestion／AskQuestion を通じて行います。
5. 1 回のリクエストにつき 1 プロジェクト。ユーザーが複数の広告動画を求めた場合は、次を始める前に 1 つのウィザードを完了させます。
6. クライアントのバージョンではなく、プロジェクトの機能に基づいて判断します。レガシーと v2 の両方のプロジェクトに対応します。古いプロジェクトにエンティティを強制的に適用したり、不足しているキーを待ったり、W3 を移行したりしないでください。storyboard status を使って、存在しない／未対応の状態と実行中／失敗の状態を区別します。
7. クレジット：image run／video run の前に、必ず見積もりを提示して確認を取ります。このセッションでユーザーから明示的な確認を得る前に、クレジットを消費してはいけません。また、確認を求める前に、見積もりの残高数値を確認してください。残高不足の場合は、実行の失敗で判明するのではなく、確認を求める前に伝えます（Quote timing を参照）。
8. 時間のかかる段階（storyboard_plan、sketch、panels、video）には数分かかり、数秒では終わりません。その旨は一度だけ伝えます。サーバーの estimated_running_ms を提示するか、値がない場合は「数分」と伝えます（Polling を参照）。期限は伝えず、ユーザーはその場を離れてもよく、通知が届いたら戻ればよいことを伝えます。ポーリングのたびに状況を説明しないでください。

CLI クイックリファレンス

cawcut ad-video create [--url <u>] [--name <n>] [--category <c>] [--json]
cawcut ad-video detail <id> [--json]
cawcut ad-video options [--video-ad-id <id>] [--language <l>] [--json]
cawcut ad-video product set <id> [--product-name …] [--description …] [--selling-point …] [--clear-selling-points] [--logo <ref>] [--primary-image <ref>] [--asset <ref>…] [--target-audience …] [--promo-*] [--json]   # only the fields passed change
cawcut ad-video config set <id> [--publish-to …] [--language …] [--aspect-ratio …] [--resolution …] [--duration-seconds …] [--video-type …] [--video-model …] [--storyboard-style …] [--auto-captions …] [--json]
cawcut ad-video analyze run <id> --url <u> [--wait] [--json]   ·   analyze cancel <id>
cawcut ad-video idea run <id> [--wait] [--json]   ·   idea select <id> (--message-id <m> | --custom <text>)   ·   idea regenerate <id>   ·   idea load-more <id>
cawcut ad-video storyboard run <id> [--style-id <s>] [--force] [--wait] [--json]   ·   storyboard set <id> --base-revision <n> (--plan <json> | --plan-file <path>) [--update-prompts --prompt-target <shot_id>:<fields>…]   # run --force rewrites the script, discarding saved edits
cawcut ad-video image quote <id> --generation-type <hand_drawn|photo_realistic>   ·   image run <id> [--confirmation-token <t>] [--generation-type <t>] [--force] [--wait] [--download]
cawcut ad-video video quote <id>   ·   video run <id> [--confirmation-token <t>] [--force] [--wait] [--download]   ·   video deliver <id> [--dest <dir>]

エラー

症状	対処
Token expired	Step 0 のログイン手順に従い、status=authenticated になった後、失敗したコマンドを 1 回再試行します
VIDEO_AD_NEEDS_REGENERATION / 308000414	上流の出力が古くなっています。まず、該当する段階を再実行します（Invalidation semantics を参照）
確認トークンの期限切れ／無効	見積もりを取り直し、ユーザーに再確認してから再実行します（Quote timing を参照）
storyboard set の 409	リビジョンが一致しません。detail を読み直し、新しい value.revision を使って再試行します
同時実行による 409	別の段階が実行中です。detail をポーリングして完了を確認してから再試行します
config set の 400	無効な列挙値、段階の前提条件未達、または選択した video_model が対応していない解像度です。ad-video options を読み直します
見積もりでクレジット不足が判明	credits_sufficient: false — 不足分を伝えてチャージを案内し、ユーザーが戻ったら見積もりを取り直します（Quote timing を参照）
CLI が見つからない	npm install -g @ubnt/cawcut を実行します（Step 0）

復旧手順の全体については、references/troubleshooting.md を参照してください。