godot-agent-vision

Godot Agent Vision

Godot プロジェクトを構築するコーディングエージェント向けの、ホスト側の目です。キャプチャ → 予算内の WebP → スコア付きのビジュアルレビューを行います。ゲームの Autoload ではなく、エクスポート可能なスクリーンショット API でもありません。

すべてのリファレンスを読み込まないでください。現在のモードで必須のファイルを読み込んでから、スコアを付ける評価軸だけを読み込んでください。

絶対にしないこと

• エディターブリッジを Autoload として組み込んだり、addons/_gdskills_agent_vision/ をコミットしたりしないでください。ステージング、キャプチャ、後片付けを行ってください。
• デバッグ後も --keep-bridge を有効にしたままにしないでください。後片付けがスキップされ、利用側のプロジェクトが汚れます。
• 圧縮されていない PNG の大きな画像をモデルのコンテキストに読み込まないでください。WebP のみを使用し、デフォルトは短辺 512です。ピクセルを確認できない場合（特に文字）は --detail のみを使用してください。
• スコア付きの審美的評価を、単純な PASS/FAIL や感覚的な判断に置き換えないでください。taste-receptors.md の該当する行にスコアを付けてください（Atlas v2、237 個の受容体 × 0～2）。vision-review-rubric.md の V1～V8 /120 は集計専用です。
• 該当するピクセルがあるのに、ファミリー別の詳細なリファレンスを読み込まずに審美的評価をでっち上げないでください：TYPE → typography-sight.md；HIER/CTRST → hier-contrast-receptors.md；SPACE/AFF → space-affordance-receptors.md；COLOR/ICON → color-icon-receptors.md；COMP/LIGHT/MOT → composition-fx-receptors.md；さらに anti-slop-sight.md / ui-taste-sight.md。
• 紫のグラデーション、光彩付きカード、クリーム色の背景にセリフ体という AI の定番を、「優れた UI」として扱わないでください。ただし、キャプチャが、読みやすい重要情報と適切なタイポグラフィを備えた独自のアイデンティティを示している場合は除きます（SLOP-STACK / TYPE-DISPLAY-HUD-SPLIT）。
• 弾薬数、HP、タイマーに装飾的なディスプレイ書体を使わないでください。TYPE-DISPLAY-HUD-SPLIT は出荷ブロッカーです。データ表示は意図的に目立たなくするものです。
• Wayland でタイトル指定によるウィンドウキャプチャが確実に動作すると約束しないでください。リージョン、grim、X11、またはエディターブリッジを使用してください。
• 全画面表示の黒い BitBlt/mss フレームを信用しないでください。排他全画面表示や一部の GPU 経路では空のフレームが返されます。ウィンドウ表示、リージョン、妥当な理由がある場合のみ DXGI、またはエディターブリッジを使用してください。
• .gdskills/vision/** をコミットしないでください。まず .gdskills/ が gitignore に追加されていることを確認してください。

使用する場面

必要なもの	モード	必須の読み込み
アセットファイル / シート	asset	capture-modes.md、webp-budgets.md、ルーブリック V6～V8 + originality-sight.md
デスクトップの矩形領域	region	capture-modes + budgets + フレーム内のルーブリック評価軸
Godot / エディター / ゲームのウィンドウ	window --title	capture-modes（OS の制限に注意！）
モニター全体	screen	最終手段（機密情報が映る可能性あり）
エディターの 2D/3D ピクセル	editor	editor-bridge-lifecycle.md

キャプチャ後：WebP を読み込み → Taste Receptor Atlas でスコアを付ける（感覚的な判断ではなく）→ 受容体 ID に対応した、該当項目なしの一覧と優先順位付きの修正案を作成します。判読不能なために TYPE-* / マイクロシームのいずれかが 512 の短辺で 1 以下になった場合は、確定前に --detail またはテキスト部分のクロップで再キャプチャしてください。

セットアップ（エージェントホスト）

pip install -r skills/godot-agent-vision/requirements-vision.txt
# optional macOS window titles:
# pip install pyobjc-framework-Quartz

ディスプレイセッションが必要です。リポジトリまたはプロジェクトの venv Python を使用してください。

利用可能なスクリプト

すべてのスクリプトを読み込まないでください。モードに必要なものだけを呼び出してください。

capture.py

メイン CLI：doctor、list-windows、screen、region、window、asset、editor。wrote=、bytes=、budget=short-edge:N|long-edge:N を出力します。

webp_encode.py

デフォルトは短辺を 512 に合わせる設定です。--detail / --max-edge を指定すると、長辺の上限（1568）に切り替わります。拡大はしません。1MB を超える場合は、画質を抑えて再エンコードします。

asset_sheet.py

単一アセット、またはラベル付きの 2×2 以下のコンタクトシートを作成します。res:// は --project-root を基準に解決します。

ensure_gitignore.py

.gdskills/ を追記し、Vision の一時ファイルがステージングされないようにします。

stage_editor_bridge.py

TEMP アドオンをステージングし、任意で --godot を起動してハンドシェイクを待機し、WebP にエンコードした後、ティアダウンと project.godot のプラグイン除去を行います。

エディターブリッジのテンプレート

• plugin.cfg / plugin.gd — @tool の EditorPlugin が request → raw/*.png → done をポーリングします
• capture_viewport.gd — Control のクロップヘルパー（get_global_rect → Image.get_region）

キャプチャ CLI（推奨手順）

python skills/godot-agent-vision/scripts/capture.py doctor
python skills/godot-agent-vision/scripts/capture.py window --project-root . --title Godot
python skills/godot-agent-vision/scripts/capture.py asset --project-root . --paths res://ui/icons --sheet
python skills/godot-agent-vision/scripts/capture.py editor --project-root . --editor-mode 3d --godot "%GODOT_PATH%"
# typography / OCR / dense layout only:
python skills/godot-agent-vision/scripts/capture.py window --project-root . --title Godot --detail

デフォルトの出力先：{project}/.gdskills/vision/YYYYMMDD-HHMMSS-<mode>[-label].webp

プラットフォーム固有の落とし穴については、必ず capture-modes.md を参照してください。予算については、必ず webp-budgets.md を参照してください。

エディターブリッジ（TEMP）

テンプレートをステージング → addons/_gdskills_agent_vision/ → .gdskills/vision/{request,raw,done} → WebP → アドオンを削除し、enabled= を復元します。

必須： editor-bridge-lifecycle.md。EditorScript よりも EditorPlugin を優先してください（RefCounted をまたぐ await は安全ではありません）。

構造化レビュー（Taste Receptor Atlas → 任意の /120 評価）

必須の基本資料： taste-receptors.md — 13 ファミリーにわたる 237 個のマイクロ受容器（HIER、CTRST、TYPE×41、AFF、SPACE、COLOR、ICON、COMP、LIGHT、MOT、SLOP、ORIG、ID）。各受容器を 0/1/2 で評価し、該当項目に対する割合とハードゲートに基づいて採点します。ルーティングと V-rollup については、vision-review-rubric.md を参照してください。

評価時の条件…	読み込む資料
すべてのレビュー	必須 taste-receptors.md
TYPE-* / HUD の数字 / メニュー	必須 typography-sight.md
HIER-* / CTRST-*	hier-contrast-receptors.md
SPACE-* / AFF-*	space-affordance-receptors.md
COLOR-* / ICON-*	color-icon-receptors.md
COMP-* / LIGHT-* / MOT-*	composition-fx-receptors.md
SLOP-* / UI のクロスチェック	anti-slop-sight.md、ui-taste-sight.md
ORIG-*	originality-sight.md
ID-*	identity-sight.md

専門知識の差分

キャプチャ / OS

• Windows：ジオメトリを取得する前に Per-Monitor DPI V2 を設定し、DPI を変更するインポートより前に mss をインポートします。monitors[0] は原点が負になる場合のある仮想ディスプレイ全体を示します。Godot のパスがタイトルに含まれるウィンドウでは、最も長く一致するタイトルを選びます。
• Windows の黒いフレーム：最小化、排他的フルスクリーン、GPU 保護コンテンツが原因です。「空の UI」ではありません。ウィンドウ表示＋リージョン指定、またはエディターブリッジを優先してください。DXGI は任意の依存要素であり、デフォルトではありません。
• macOS：画面収録の許可は 責任を持つバイナリ に付与されます。壁紙だけが表示される場合は明確な失敗です。エージェントでは screencapture CLI の帰属が機能しなくなるため、プロセス内の Quartz/mss を優先してください。
• macOS Retina：自動化には 論理ポイント、OCR には バックピクセル を選び、スケールメタデータなしに両者を混在させないでください。
• Linux：Wayland では mss をスキップし、wlroots では grim を使用します。タイトルからのキャプチャを黙って行わないでください。ポータル経由の操作は対話式です。
• アセットの res:// は --project-root を基準に解決します。パスが存在しない場合は明確にエラーにしてください。ファイルを捏造してはいけません。

WebP / コンテキスト

• ビジョントークンは ピクセル面積 に応じて変化し、リクエストサイズはコーデックに応じて変化します。ID、概要、アンチスロップにはデフォルトで 短辺 512 を使用し、グリフ、継ぎ目、密度の高い全体レイアウトの場合に限り、長辺を 1568 まで引き上げてください。
• コンタクトシートはガター付きで 最大 2×2 にしてください。3×3 以上では、モデルによる縮小後にパネル内のテキストがサブピクセルになります。
• 小さなアイコンを 512/1568 いっぱいに拡大しないでください。情報が増えないままトークンを浪費します。

エディターブリッジ

• EditorPlugin（Node）では await RenderingServer.frame_post_draw を安全に使用できます。EditorScript は RefCounted であり、await 中に解放されることがあります。
• キャプチャ：EditorInterface.get_editor_viewport_2d/3d → get_texture().get_image()。1～2 フレーム以上待ってから取得してください。先にメイン画面を 2D／3D に設定しないと、テクスチャが古いか空になります。
• get_image() が空 ⇒ await が不足しているか、メイン画面が間違っています。GPU に問題がない証拠ではありません。
• ハンドシェイク：raw/ に PNG を書き込んでから、done フラグを設定します。Python はサイズが安定した PNG を待ちます。
• ティアダウンでは、[editor_plugins] enabled= から res://addons/_gdskills_agent_vision/plugin.cfg を取り除き、アドオンを削除する必要があります。アンダースコア付きの名前は非公開／一時的であることを示します。
• コントロールのクロップ：エディター全体の画像と get_global_rect を使い、境界内に収めて Image.get_region を適用します。

視覚／センス（アトラスが重い理由）

• 印象ではなく受容体を採点します。階層は複合的な サイズ×コントラスト×動き×彩度 です（HIER-WEIGHT-MATH）。周辺 HUD は形として認識できる必要があります（HIER-PERIPH-READ）。プレート上のコントラストは最悪ケースで評価します（CTRST-GRAD-WORST、CTRST-BODY-45）。
• エージェントは AI UI の典型（紫の色かぶり、ネオングローのカード、クリーム色＋セリフ体、Lucide の寄せ集め）をデフォルトで選びます。所有する根拠なしに T≥3 となる場合、SLOP-STACK=0／総合評価 F です。
• タイポグラフィはリリースを阻む要因です（TYPE 受容体は41個）： TYPE-DISPLAY-HUD-SPLIT、TYPE-OPSZ-MATCH、TYPE-NUM-TABULAR／TIMER-STABLE、TYPE-GLYPH-INTEGRITY、TYPE-FACE-CAP — HUD サイズでのディスプレイ書体の破綻やタブラー数字の揺れは、スタイルの問題ではなくゼロ点です。
• 色／アイコン：意味的な役割は4～6個、アクセントの使用量は約5～15％にします。アイコンセットのシルエットテストを行い、CVD では形状を代替手がかりにします（COLOR-ONLY／ICON-SIL）。
• 構図／FX／動き：パワーポイントと HUD の競合に注意します（COMP-POWER-CONFLICT）。ブルームやパーティクルで階層を置き換えたり、UI を覆ったりしてはいけません。静止画にはシェイク／トゥイーンのアーティファクトが残ります（MOT-*）。ピークが曖昧な場合はシーケンスでキャプチャします。
• 独自性：まず「よくあるお決まりの表現」を除外します。フランチャイズのシルエットやマークとの一致、構成要素の積み重ねから出自が分かる表現は不合格です。
• アイデンティティ：パレットの役割＋エッジの文法＋モチーフの反復（2～4回）＋書体の組み合わせ＋アイコングリッド＋HUD↔メニュー↔キービジュアルの一貫性 — グラデーションだけではブランドになりません。

判断ツリー

1. ディスク上にファイルがある？ → asset（± シート）→ 読み取り → COLOR／ICON／ORIG／ID／SLOP を採点（ラベルがある場合は TYPE も）→ 修正。
2. 既知のウィンドウ？ → window（それ以外は region）→ 読み取り → 該当するアトラスファミリーをすべて採点 → 修正。
3. エディタービューポートの忠実度が必要？ → editor → ティアダウン → 採点 → 修正。
4. それ以外は screen（最終手段）。
5. 512 で TYPE／CTRST が判読できない？ → --detail またはテキストのクロップを使用 → 該当する受容体を再採点。
6. MOT／ヒットピークが曖昧？ → 2～8フレームのシーケンスを取得 → MOT／LIGHT のヒット受容体を再採点。

リファレンス

段階的開示：特定の API を使う場合にのみ公式ドキュメントを開き、同じ階層の別ドメインに振り分ける場合にのみ関連スキルを読み込みます。階層全体を事前に読み込まないでください。

公式ドキュメント

• EditorPlugin — 一時的なブリッジホスト。有効化／無効化のライフサイクル。
• EditorInterface — get_editor_viewport_2d/3d、キャプチャ前のメイン画面切り替え。
• ビューポートの使用 — Image キャプチャに渡すビューポートテクスチャ。
• Image — save_png、Control のクロップに使う get_region。
• SubViewport — エディター／ゲームのネストされた表示サーフェス。
• RenderingServer — テクスチャ読み戻し前の frame_post_draw 待機。
• 移行手順：migration-notes.md

関連スキル

前提条件

• godot-project-foundations — ビジョン用のスクラッチ作業の前に、プロジェクトルートと .gitignore を適切に管理します。
• godot-ui-containers — ビジョンの問題を Theme のせいにする前に、レイアウトが適切であることを確認します。

補完

• godot-ui-theming — V3/V8 でクロームやタイポグラフィの課題が見つかった後に、Theme/StyleBox/フォント API を扱います。
• godot-ui-rich-text — HUD のタイポグラフィ上の役割との一貫性を保つ必要がある BBCode/フォントを扱います。
• godot-auditor — アーキテクチャ面でのアンチスロップという共通点があります。
• godot-debugging-profiling — ピクセル表示にとどまらない、ランタイムや孤立ノードの問題を扱います。
• godot-builder — ブリッジ用のキャプチャでエディターを起動する際の CLI/GODOT_PATH パターンを扱います。

下流／利用側

• 画面を実装するジャンルおよび UI スキル — エージェントが結果を推測するのではなく、目で確認する必要がある場合に利用します。

マスター

• godot-master — 決定マトリックスの項目 エージェントの視点／ビジュアル QA。