scenario-quality-gate

シナリオ品質ゲート

概要

1 つのツール asset_quality_gate_run は、完成した画像アセットを採点し、0〜100 のスコアと、各評価軸の reasons および suggestions のリストを含む pass／warn／fail の判定を返します。チームまたはプロジェクトにブリーフが設定されている場合は、常に実施される AI 品質チェックに加えて、ブランドブリーフへの準拠も評価します。対象は画像アセットのみです。Quality Gate は Enterprise アドオンです。チームで有効になっていない場合、呼び出しは正常に失敗するため、それを検出して asset_analyze によるレビュー（scenario-asset-analysis を参照）に切り替え、その旨を伝えてください。再試行しても有効にはなりません。

このツールはカタログ専用の書き込みクラスです。スキーマは scenario_tools_search で取得し、{name: "asset_quality_gate_run", parameters: {...}} を指定して scenario_tool_execute_write 経由で実行してください。スコープ ID は parameters 内に指定します（読み取り用エグゼキューターはレーンの違いを理由に拒否し、適切な実行先を示します）。または、?toolsets=full を指定して再接続してください。接続とスコープについては scenario スキルを参照してください。ここで名前が挙げられている兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で処理を続ける場合は、ツールスキーマに基づいて進め、不足していることを明記してください。

クイックリファレンス：呼び出しにかかる費用

呼び出し	動作	費用
通常の呼び出し、利用可能な判定が保存済み	保存済みの判定を返します。source: "stored"	無料（レスポンスに creativeUnitsCost は含まれません）
通常の呼び出し、利用可能な判定なし	新たな分析を実行して判定を保存します。source: "new_analysis"	課金対象。レスポンスに creativeUnitsCost が含まれます（執筆時点では 1 CU）
rerun: true	新たな分析を実行し、保存済みの判定を置き換えます	課金対象
dry_run: true	何も実行せず、新たな分析の価格を creativeUnitsCost として返します	無料

利用可能な判定がすでに存在する場合に限り、通常の呼び出しは読み取り専用です。それ以外の場合、同じ呼び出しが暗黙のうちに課金対象の分析へ切り替わります。「利用可能な判定がない」には、未採点の場合と、保存済みの結果が error の場合の両方が含まれます。先に支出の承認が必要な場合は、dry_run: true または asset_get で無料の確認を行ってください。asset_get の qualityGate フィールドには、判定とスコアが保存されている場合にそれらが含まれます（サマリーのみ。保存済みの reasons と suggestions は引き続き無料でツールから取得できます）。sensitivity（low、medium、high。デフォルトはチームまたはプロジェクトの設定）は新しい分析にのみ影響し、保存済みの判定の読み取り時には無視されます。rerun: true はブリーフまたは感度を変更した後にのみ使用してください。それ以外の用途では使わないでください。再課金され、保存済みの判定が上書きされます。

判定の読み取り

レスポンスには source と quality_gate が含まれます。quality_gate には、verdict、overallScore、aiQualityScore、briefComplianceScore、sensitivity、appliedBriefIds、details が含まれます。ブリーフが設定されていない場合、準拠の評価軸は完全に省略されます（appliedBriefIds: []、overallScore は aiQualityScore と同じです）。ブリーフが設定されている場合は、details.briefCompliance が details.aiQuality と並んで含まれ、それぞれに score と reasons、suggestions のリストが含まれます。通常、各リストには複数の項目があります。

判定結果をより良い画像につなげる

判定結果だけでは、アセットを分類するにすぎません。フィードバックを次の試行に活かしてこそ、ゲートのコストに見合う価値が得られます。

• reasons には具体的な欠陥が記載されます（「左手の指の形状が細長すぎる」「背景のグラデーションがブリーフのパレットから外れている」など）。欠陥ごとに修正方法を選ぶために使います。他の部分は承認済みの画像に局所的な欠陥がある場合は、マスクを使ったインペインティング処理（scenario-image）を行います。全体的な欠陥の場合は再生成します。
• suggestions は編集指示として記述されており、多くの場合、手作業でのレタッチ向けの表現です。最初の提案だけでなく、適用できるものはすべて反映します。次の model_run のプロンプトやパラメーター、または編集指示に変換します。
• 再生成した画像は新しいアセットなので、通常の呼び出しでスコアが付けられます。rerun がループに含まれることはありません。無料で事前にスコアが付く場合もあります。自動検出が有効なチーム（teams_list の行で qualityGateAutoDetect: true）では、新しい生成画像が自動的に採点されます。
• 同じラウンドで、スコアが変わらないまま同じ種類の欠陥が繰り返される場合、言い換えても解決しません。モデルを切り替える（再度 recommend を実行する）か、次のラウンドに進む前にマスク編集で欠陥を修正します。
• 終了条件となる基準とラウンド上限は、あらかじめ決めておきます。デフォルトは verdict: "pass"、またはユーザーが指定したスコア目標（たとえば overallScore が90以上）です。指定された基準は、単なる pass より優先されます。また、特に指定がなければラウンドは3回とします。各ラウンドで生成と分析の費用が発生するためです。上限に達した場合、またはスコアが伸びなくなった場合は停止します。残っている欠陥を伝えたうえで最良のアセットを報告し、さらにラウンドを重ねる前に確認を求めます。確認を取らずに進める場合は、最良のアセットを納品し、基準未達であることを伝えます。

scenario-refine-loop は、ゲートを越えてループの規律を適用します。1ラウンドにつき変数を1つに限定し、承認済みのベースラインから再生成し、基準がブリーフの範囲を超えた場合は適切な修正方法に振り分けます。

判定結果で把握できないこと

ゲートはアーティファクトを検出します。実際のアセットで確認された、設計時に考慮すべき制限は3つあります。

• もっともらしさではなく、アーティファクトを検出します。 車の2つのホイールが別々の形状で、一方にだけホワイトウォールがあり、後輪の上にホイールアーチがなかったパネルは、sensitivity: "high" でスコア92、pass となり、欠陥だったクロームリムを reasons で称賛していました。見た目が悪いのではなく、物理的にありえないものについては、独自に構造チェックが必要です。数と接続関係（手、片手あたりの指、四肢、ホイールなどが、それぞれ1つの身体に接続されていること）、部分と全体の関係（ホイールはアーチの内側にある、ガードはそれ自体のブレードに取り付けられている、反射はそれを生じさせる物体の下にある）、そして何が重さを支えているかを確認します。
• 参照画像を見たことがありません。 briefCompliance には設定済みのブリーフが必要です。また、ブリーフはテキストなので、どの呼び出しでも、生成元となった画像と同じ車や衣装ではないことを判断できません。アセットを参照画像と項目ごとに自分で比較してください。
• 合成画像のスコアは、各パーツの平均になります。 12パネルのストーリーボードはスコア88、pass となりましたが、そのうち1つのパネルは物理的にありえないものでした。却下できる単位で採点してください。合成画像を model_scenario-image-slicer で分割して各パーツを採点し、失敗したものだけを修正してから、model_scenario-compose-image で再合成します。

スコアは、構造上の修正が反映されたかを示す弱いシグナルでもあります。壊れたパネルも、修正後の差し替えパネルもスコアは92で、変わったのは reasons だけでした。数値に注目するのではなく、欠陥リストをもう一度確認してください。

ヒーロー用小道具を合格するまで改善する例

1. scenario-image ごとに生成します：model_run、jobs_wait を実行し、アセット ID を取得します。
2. query="quality gate" を指定して scenario_tools_search を一度実行し、スキーマを確認します。その後、最初のアセットで dry_run: true を指定し、分析ごとの料金を確認します。
3. スコアを付けます：次の内容で scenario_tool_execute_write を実行します。 {name: "asset_quality_gate_run", parameters: {asset_id, team_id, project_id}}。source: "new_analysis" と、verdict: "warn"、briefComplianceScore: 58、およびロゴを左上に配置して背景をもっとフラットにするよう求める details.briefCompliance.suggestions を含む quality_gate が返されます。
4. 2 つの提案をプロンプトに反映して再生成し、新しいアセットを通常の呼び出し（rerun なし）で採点します。
5. verdict: "pass"：納品して、登録します（コレクションとタグについては scenario-asset-analysis を参照）。採点済みのアセットを後から読み取る場合、保存済みデータの読み取りは無料です。
6. 次のスプリントでブリーフが変わった場合に限り、再判定が必要なアセットに rerun: true を指定します。

よくある間違い

• 通常の呼び出しを無料の読み取りと見なす：利用可能な保存済みの判定がない場合、分析は通知なく実行され、料金が請求されます。費用が重要な場合は、まず dry_run または asset_get で確認してください。
• 習慣で rerun: true を渡す：無料で読み取れる判定に対して再度料金が請求されます。このオプションは、ブリーフまたは感度が変わった後に更新する場合にのみ使います。
• ブリーフが設定されていないのに briefComplianceScore が返ると期待する：appliedBriefIds が空でない場合に限り、quality_gate にこのスコアが含まれ、details.briefCompliance も返されます。
• 提案を 1 つずつ適用し、そのたびに再採点する：通常、提案のリストには複数の修正点が含まれており、1 回の再生成ですべて反映できます。
• scenario_tool_execute_read で実行する：書き込みクラスの操作であり、レーンによって拒否されます。
• 動画、3D、音声のアセットを採点する：対象は画像アセットのみです。
• 新しくアップロードしたファイルには判定がないと思い込む：アップロードはコンテンツで重複排除されるため、ファイル名にかかわらず、同一バイト列なら同じ長期間有効なアセット ID が返されます。また、チームが以前に採点したファイルを再アップロードすると、保存済みの判定が引き継がれます。
• 保存済みの判定が返る呼び出しで sensitivity を設定する：これは新しい分析にのみ適用されます。採点済みのアセットをより厳しく採点するには、rerun: true が必要です。
• エンタイトルメントのエラーを再試行する：Quality Gate は Enterprise アドオンです。scenario-asset-analysis の asset_analyze によるレビューに切り替え、その理由をユーザーに伝えてください。