scenario-asset-analysis

シナリオアセット分析

概要

4 つのツールが、既存のアセットからキャプション、スタイルの説明、分析、コントロールマップを抽出します。用途が固定されたものが 3 つ、自由形式のものが 1 つです。デフォルトのツールセットに含まれる search と併用すると、バッチを取り込んだ後に生じる質問に答えられます。実際の作業の大半がここにあります。依頼内容に沿っているか、どのような見た目か、何が描かれているか、次のモデルの条件付けに何を使えるか、先週承認されたバージョンはどこにあるか、といった質問です。

いずれもデフォルトのツールセットには含まれていません。scenario_tools_search でスキーマを取得し、返された permission に対応するエグゼキューターで実行してください。read には scenario_tool_execute_read を、write には scenario_tool_execute_write を使います。見積もりと実行の両方で、ライブの結果を使ってください。入力アセットが変わっていないからといって、実行レーンを推測しないでください。name にツール名を、parameters に入力を指定します。または ?toolsets=full を付けて再接続してください。接続とスコープについては、このリポジトリの scenario スキルを参照してください。ここで名前が挙がっている兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で作業を続ける場合は、ツールスキーマをもとに進め、不足していることを明記してください。

クイックリファレンス

必要なもの	ツール	形式
1 枚の画像のキャプション	asset_caption	details_level：action または action+style
1 枚の画像から再利用可能なルックを作成	asset_describe	詳細な説明と、プロンプトに使える合成結果を返します
その他の用途を自分の言葉で指定	asset_analyze	instruction、最大 10 個の images と 10 個の text_inputs
別のモデル用の条件付けマップ	asset_detect	10 種類のうち 1 つの modality。canny、depth、pose、segmentation など

4 つのツールはいずれもクレジットを消費し、見積もりを先に取得する場合は parameters 内で dry_run: true を指定します。OAuth では、見積もりと実行の両方に、ユーザーが選択した team_id と project_id を渡してください。同じ処理を再実行すると、課金対象のジョブがもう一度作成されることがあります。エグゼキューターのレーンを使っても無料にはなりません。

計画を変える 4 つの事実

• asset_analyze はバッチ処理に対応しています。 1 回の呼び出しで、1 つの instruction に対して最大 10 枚の画像を処理するため、200 個のアセットを確認する場合、呼び出しは 200 回ではなく 20 回です。num_outputs（1～5）はこれとは別の設定です。同じ指示に対する複数の異なる回答を返すもので、画像ごとに 1 つずつ回答するわけではありません。回答を解析しやすい状態に保つため、instruction では画像ごとの出力形式を固定して指定してください。
• asset_detect はデフォルトで背景を除去します。 remove_background のデフォルト値は true なので、depth マップや pose マップにはフレームの背景がすでに含まれていません。マップを画像全体に適用する必要がある場合は、false に設定してください。
• ファイルではなく、レンダリング結果を読み取ります。 ベクター形式やレイヤー付きのソースでは、ファイルの内容を確認したり、正確な値を報告したりできません。16 個のパスを持つ SVG をラスター画像と判定し、#101614 の塗りつぶしを #131A18 に置き換え、パレット外のパスを見落とした例があります。色や構造を正確に把握するにはファイルを解析してください。このツールが判定するのは、レンダリング結果に何が表示されているかです。
• 適合する場合は、固定用途のツールが柔軟なツールに勝ります。 asset_caption と asset_describe は用途に特化しており、同じ作業を LLM に指示するより高速です。分類、抽出、比較、翻訳、または依頼内容に対する判定には asset_analyze を使ってください。例外が 1 つあります。設定済みのブランドブリーフに対する pass／warn／fail 形式の判定を構造化して行う場合、Quality Gate アドオンを利用しているチームには、判定を保存して無料で再読み込みできる専用ツールがあります（scenario-quality-gate を参照）。アドオンがない場合や、ブリーフが文章としてしか存在しない場合は、引き続き asset_analyze を使ってください。

asset_analyze と asset_detect は最大 180 秒待機してから job_id を返します。他の場合と同様に、jobs_wait で処理を続けてください。

アセットを再び見つける

検索には target="assets" を指定した search を使います。また、query、filters、filter、 image、images のいずれかを必ず設定してください。何も指定しない呼び出しは、すべてのアセットを返すのではなく、400 エラーになります。

• テキストで検索する。 デフォルトでは query はキーワードで照合します。query_semantic_ratio を設定すると、意味による照合の比率を上げられます（「暗い中世の雰囲気」のようなムードのクエリには 0.5〜0.8 が適しており、1 は完全なセマンティック検索です）。この比率が 0 より大きい場合、sort_by（例：["createdAt:desc"]）は無視されるため、新しい順に並べるにはキーワードモードが必要です。
• 類似性で検索する。 image には 1 つのアセット ID または画像 URL を指定し、類似画像を取得します。images には {"like": [...], "unlike": [...]} を指定して、肯定例と否定例で検索を調整します（この 2 つのフィールドは同時に指定できません）。類似性の基準は image_semantic_ratio で決まります。デフォルトの 1 は被写体とムードを照合し、0 は画像の特徴を照合します。重複に近い画像やクロップ画像を探す場合は 0 に設定します。「これらに似ているが、もっとスタイライズされたもの」のように探すには、併せて query を指定してください。
• 構造で絞り込む。 filters では kind、tags、model_id、collection_ids、created_after／created_before で絞り込みます。これらは上記すべての条件と AND で結合されます。

実例：ブリーフに照らして一括レビューする

1. 実行結果からアセット ID を収集します（jobs_wait が返します）。
2. 最初のチャンクで dry_run: true を指定して asset_analyze を実行し、処理の料金を確認します。
3. images に 10 個の ID を指定し、ブリーフと出力形式を明記した instruction を設定して asset_analyze を実行します。「画像を順に確認し、それぞれ <index>: pass|fail, <reason in under 12 words> の形式で回答してください。すべての行に理由を記載し、pass の場合も省略しないでください。中央に配置されていないもの、無地の背景でないもの、またはテキストが含まれるものはすべて fail にしてください。」と指定します。チャンクごとに繰り返します。回答はテキストアセット（1 つ、または画像ごとに 1 つ）として保存されるため、判定結果を読むにはそれらを asset_download します。
4. 最も評価の高い pass に対して asset_describe を実行します。プロンプトに利用できる統合結果を次のバッチのプロンプトにそのまま使うと、トレーニングを実行せずに見た目の一貫性を保てます（scenario-consistency を参照）。統合結果が短いタイトルにすぎない場合は、代わりに説明文をプロンプトに使ってください。
5. 結果を整理します。collection_create の後、すべての ID を指定して collection_add_assets を 1 回呼び出します（内部で 49 件を超える場合は分割し、すでに追加済みの ID はスキップします）。asset_add_tags はタグを追加する処理なので、タグセットを作り直すのではなく、失敗したアセットにタグを付けます。後で search の filters={"collection_ids": [...]} を使ってこのセットを取得でき、images={"like": [...]} を使えば類似画像も検索できます。

よくある間違い

• 1 回の呼び出しに 10 件入るのに、アセットごとに asset_analyze を呼び出す。
• num_outputs を images に対するバッチサイズとして扱う。
• 元のフレームと一致させる必要がある asset_detect のマップで、remove_background をデフォルトのままにする。
• 以前に記憶した実行レーンを再利用する。dry_run の場合も含め、最新の scenario_tools_search の結果にある permission を使います。レーンで拒否された場合は、同じ呼び出しを再試行せず、検出を更新してその実行レーンを使ってください。
• asset_analyze に画像の生成を求める。これはテキストを返します。制御マップは asset_detect から、最終レンダリングは model_run から取得します。