godot-agent-vision

Godot Agent Vision

面向构建 Godot 项目的编码 Agent 的主机端视觉能力：捕获 → 按预算压缩为 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。
• 除非捕获内容以清晰易读的关键信息和严谨的字体设计确立了自身风格（SLOP-STACK / TYPE-DISPLAY-HUD-SPLIT），否则绝对不要把紫色渐变、发光卡片或奶油色衬线字体等 AI 默认风格当作“优秀 UI”。
• 绝对不要在弹药量、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（注意操作系统限制！）
整个显示器	screen	最后手段（会包含机密信息）
编辑器 2D/3D 像素	editor	editor-bridge-lifecycle.md

捕获后：读取 WebP 图像 → 对照审美感受器图谱评分（不要凭感觉）→ 列出所有问题，并按感受器 ID 排序给出修复项。如果任何 TYPE-* / 微小接缝因 512 短边而无法辨认，评分 ≤1，就重新捕获并使用 --detail 或文字裁剪图，再定稿。

设置（Agent 主机）

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 联系表；基于 --project-root 解析 res://。

ensure_gitignore.py

追加 .gdskills/，避免视觉临时文件被暂存。

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。优先使用 EditorPlugin，而不是 EditorScript（跨 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 汇总：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：屏幕录制权限关联到实际负责的二进制文件；只捕获到墙纸 = 硬性失败；在 Agent 环境下，screencapture CLI 的归属会出问题——优先使用进程内 Quartz/mss。
• macOS Retina：选择逻辑点（自动化）或后备像素（OCR），没有比例元数据时不要混用。
• Linux：Wayland → 跳过 mss；wlroots 上使用 grim；不得静默捕获标题栏；门户路径需要交互操作。
• 资源 res:// 相对于 --project-root 解析；缺失路径必须明确报错——绝不可虚构文件。

WebP / 上下文

• 视觉 token 数量取决于像素面积；请求大小取决于编解码器。身份识别 / 总览 / anti-slop 默认使用短边 512；只有字形、接缝或密集的完整布局才将长边提高到 1568。
• 联系表限制为 ≤2×2，并留出间隔——3×3 或更大时，模型缩小图像后面板文字会小于一个像素。
• 绝不要将微小图标放大到 512/1568 填满画面——这会浪费 token，却不增加信息。

编辑器桥接

• 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，并删除该插件；下划线名称表示私有/临时。
• Control 裁剪：完整编辑器图像 + get_global_rect → Image.get_region，并将范围限制在边界内。

观感 / 品味（图谱为何如此庞大）

• 评估感受器，而非感觉：层级由复合指标尺寸×对比度×运动×饱和度构成（HIER-WEIGHT-MATH）；外围 HUD 必须能以形状辨认（HIER-PERIPH-READ）；面板上的对比度按最差情况评估（CTRST-GRAD-WORST、CTRST-BODY-45）。
• Agent 默认采用 AI UI 的视觉风格（紫色调、霓虹光效卡片、奶油色 + 衬线字体、Lucide 图标大杂烩）。T≥3 且没有明确归属 ⇒ SLOP-STACK=0 / 总评 F。
• 字体排版会阻止发布（41 个 TYPE 感受器）： 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）。
• 构图/特效/运动：力量点与 HUD 冲突（COMP-POWER-CONFLICT）；泛光/粒子不能取代层级或遮挡 UI；定格画面会暴露震动/补间瑕疵（MOT-*）——峰值不明确时按序列捕获。
• 原创性：先排除常见套路；若与知名作品的轮廓/标记相似，或暴露出堆叠拼凑的痕迹，则判失败。
• 品牌识别：调色板角色 + 边缘风格 + 母题重复（2–4 次）+ 字体搭配 + 图标网格 + HUD↔菜单↔主视觉的统一基因 — 只有渐变不算品牌。

决策树

1. 磁盘上有文件？→ asset（± sheet）→ 读取 → 评估 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 — 确保 BBCode/字体与 HUD 字体角色保持一致。
• godot-auditor — 架构反劣化方面的相关技能。
• godot-debugging-profiling — 处理像素问题之外的运行时 / 孤立对象问题。
• godot-builder — 启动编辑器进行桥接捕获时使用 CLI/GODOT_PATH 模式。

下游 / 使用方

• 用于交付界面的类型和 UI 技能 — 当 Agent 必须查看结果而非猜测时，转到这里。

主技能

• godot-master — 决策矩阵中的 Agent Eyes / Visual QA 行。