用途
godot-agent-vision 为构建 Godot 项目的编码智能体提供宿主侧“视觉之眼”：捕获画面 → 编码为受预算约束的 WebP → 进行带评分的视觉评审。它不是游戏内的 Autoload，也不是可导出的截图 API。
主要能力
跨平台截图 CLI
capture.py 是主命令行工具，提供 doctor、list-windows、screen、region、window、asset、editor 等子命令，输出 wrote=、bytes=、budget=short-edge:N|long-edge:N 等信息。
WebP 编码与预算
webp_encode.py 默认按短边 512 适配；--detail / --max-edge 切换为长边上限（1568）。从不放大图像；若超过 1MB 会进行软重编码。
素材图集
asset_sheet.py 支持单个素材或不超过 2×2 的带标签联系表，res:// 路径基于 --project-root 解析。
编辑器视口桥接（临时）
stage_editor_bridge.py 会暂存临时 addon、可选通过 --godot 启动、等待握手、编码 WebP、拆除并清理 project.godot 中的插件条目。桥接模板包括 plugin.cfg / plugin.gd（@tool EditorPlugin 轮询 request → raw/*.png → done）以及 capture_viewport.gd（Control 裁剪辅助，get_global_rect → Image.get_region）。
结构化视觉评审
Taste Receptor Atlas v2 包含约 237 个微受体，分属 13 个族（HIER、CTRST、TYPE×41、AFF、SPACE、COLOR、ICON、COMP、LIGHT、MOT、SLOP、ORIG、ID），每个按 0/1/2 打分，按适用项百分比评级并设硬性门槛。V1–V8 /120 仅作汇总。
使用方式
安装（智能体宿主）：
pip install -r skills/godot-agent-vision/requirements-vision.txt
# optional macOS window titles:
# pip install pyobjc-framework-Quartz
需要显示会话，并使用仓库/项目 venv 的 Python。
典型命令：
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。
捕获后：读取 WebP → 按 Taste Receptor Atlas 打分（而非凭感觉）→ 输出零分清单与按受体 ID 排序的修复建议。若在 512 短边下出现 TYPE-* / 微接缝 ≤1 的不可读情况，需用 --detail 或文字裁剪重新捕获后再锁定。
适用场景
- 素材文件/图集：使用
asset模式，配合 capture-modes、webp-budgets、rubric V6–V8 与 originality-sight。 - 桌面矩形区域：使用
region模式。 - Godot/编辑器/游戏窗口：使用
window --title。 - 整屏：使用
screen（最后手段）。 - 编辑器 2D/3D 像素：使用
editor模式，配合 editor-bridge-lifecycle。
限制与注意事项
- 不要为单个任务加载全部参考文件；只加载当前模式的必读文件与正在评分的评分轴。
- 绝不将编辑器桥接作为 Autoload 发布，也不要提交
addons/_gdskills_agent_vision/；应暂存、捕获、拆除。 - 调试后绝不保留
--keep-bridge。 - 绝不把未压缩 PNG 大量塞入模型上下文；仅用 WebP，默认短边 512。
- 绝不用二元 PASS/FAIL 或主观感觉替代评分。
- 不要承诺在 Wayland 上按标题静默抓窗；应使用 region、grim、X11 或编辑器桥接。
- 不要信任黑屏的全屏 BitBlt/mss 帧（独占全屏/某些 GPU 路径会返回空）。
- 不要提交
.gdskills/vision/**，先确保.gdskills/已加入 gitignore。 - 平台细节（Windows DPI、macOS 屏幕录制归属、Linux Wayland 等）与 WebP 预算、编辑器桥接生命周期等均有必读参考文件。
参考
官方文档涉及 EditorPlugin、EditorInterface、Using Viewports、Image、SubViewport、RenderingServer 等；相关技能包括 godot-project-foundations、godot-ui-containers、godot-ui-theming、godot-ui-rich-text、godot-auditor、godot-debugging-profiling、godot-builder、godot-master 等。