screenshot-debug
Debug errores visibles en pantalla tomando un screenshot completo y analizándolo con un modelo de visión (Qwen3.6-Plus via OpenCode Go).
- License 许可
- MIT
- 所属仓库
- iberi22/skills
- 最近更新
- 2026-10-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- screenshot-debug
- tags
- [ "debug", "screenshot", "vision", "grim", "hyprland", "wayland", "opencode-go" ]
- author
- Hermes Agent
- version
- 1.0.0
- description
- Debug errores visibles en pantalla tomando un screenshot completo y analizándolo con un modelo de visión (Qwen3.6-Plus via OpenCode Go).
02 资源文件 2
- 参考文档references/hyprland-version-migration.md3.4 KB
- 参考文档references/programmatic-analysis.md2.6 KB
03 SKILL.md 正文
Screenshot Debug — Depuración Visual con OpenCode Go
Usa este skill cuando el usuario reporte errores visibles en pantalla — overlays de Hyprland, ventanas de error, notificaciones, waybar con errores, etc. Toma un screenshot completo y analízalo con el modelo Qwen3.6-Plus (visión) a través de OpenCode Go.
Requisitos
griminstalado (para capturar pantalla en Wayland)slurpinstalado (para seleccionar región, opcional)- WAYLAND_DISPLAY accesible (usar
WAYLAND_DISPLAY=wayland-1si no está en PATH)
Paso 0: Verificar disponibilidad de modelo con visión
ANTES de tomar screenshot, verifica si el modelo activo soporta imágenes. El modelo se lista en el primer mensaje del turno (Model: <name>). Si NO soporta visión:
delegate_taskcontoolsets=["vision"]puede funcionar si existe otro modelo con visión configurado- Si delegate_task también falla (ej. HTTP 404 desde OpenCode Go), NO hay modelo de visión disponible
- SALTA inmediatamente al análisis programático (Paso 3 → Opción C) en lugar de intentar ver el screenshot
Procedimiento
Paso 1: Tomar Screenshot
Siempre con las variables de entorno correctas para Wayland (el agente NO tiene $WAYLAND_DISPLAY por defecto):
WAYLAND_DISPLAY=wayland-1 XDG_RUNTIME_DIR=/run/user/1000 grim /tmp/screenshot_debug.png
Verifica que el archivo se creó y su tamaño (generalmente 300-900KB):
ls -la /tmp/screenshot_debug.png
Si el terminal tiene PATH corrupto, usa execute_code con subprocess en vez de terminal.
Paso 2: Analizar con Visión
Usa vision_analyze para examinar la imagen. Enfócate en la parte superior de la pantalla — ahí aparecen los overlays de Hyprland:
vision_analyze(
image_url="/tmp/screenshot_debug.png",
question="Describe TODOS los errores, warnings y notificaciones visibles en la pantalla. Enfócate en la PARTE SUPERIOR (overlays de Hyprland, notificaciones, waybar). ¿Qué mensajes de error específicos ves? ¿Hay una barra roja indicadora? ¿Cuántos errores se muestran?"
)
Paso 3: Si vision_analyze falla porque el modelo activo no soporta imágenes
Opción A ✅ RECOMENDADA: Usar delegate_task con herramientas de visión
Esto funciona porque el subagente puede usar vision_analyze con su propio modelo:
delegate_task(
goal="Analiza el screenshot en /tmp/screenshot_debug.png y describe todos los errores visibles en la pantalla. Enfócate en la PARTE SUPERIOR (overlays de Hyprland, notificaciones, errores de barra). Describe coordenadas, texto exacto, colores.",
context="El screenshot está en /tmp/screenshot_debug.png (ruta absoluta). Tiene aprox 600KB. El sistema es NixOS con Hyprland. Busca específicamente errores de configuración de Hyprland, ventanas de error, notificaciones.",
toolsets=["vision","file","terminal"]
)
Nota: El subagente con toolsets=["vision"] puede usar vision_analyze internamente para examinar la imagen.
Opción B: Cambiar modelo temporalmente (requiere modificar ~/.hermes/config.yaml)
No intentes cambiar ~/.hermes/config.yaml durante la sesión — es frágil y puedes perder la conexión.
Opción C ⚠️ Análisis programático sin visión (cuando A y B fallan)
Cuando NO hay ningún modelo de visión disponible (tanto vision_analyze como delegate_task con toolsets vision fallan):
-
Determinar geometría de la ventana via IPC (Hyprland):
# Para ventanas regulares (xdg-shell) hyprctl clients -j | python3 -c "import json,sys; [print(f'Class:{c.get(\"class\")} Size:{c.get(\"size\")} At:{c.get(\"at\")}') for c in json.load(sys.stdin) if 'eww' in c.get('class','').lower() or 'dashboard' in c.get('title','').lower()]" # Para ventanas layer-shell (EWW dock mode), NO aparecen en hyprctl clients # Usar eww directamente: eww list-windows eww state | grep -E "width|height|geometry" -
Verificar ancho/constraints desde el código fuente:
# Buscar width constraints en window geometry grep -n "geometry\|:width\|:height" ~/.config/eww/eww.yuck # Buscar min-width, max-width, width en styles grep -n "min-width\|max-width\|width" ~/.config/eww/eww.yuck # Verificar SCSS por propiedades de overflow grep -n "max-width\|max-height\|overflow" ~/.config/eww/eww.scss -
Verificar dimensiones del screenshot (solo validación básica de archivo):
# Leer dimensiones PNG sin PIL (Python stdlib) python3 -c "import struct; f=open('/tmp/ss.png','rb'); f.seek(16); w=struct.unpack('>I',f.read(4))[0]; h=struct.unpack('>I',f.read(4))[0]; print(f'{w}x{h}')" -
Usar
eww debugpara inspeccionar la jerarquía de widgets:eww debug | grep -E "VarName|width|min_width|max_width" | head -30 -
Reportar al usuario que no se pudo obtener análisis visual y pedir confirmación textual:
- Describe exactamente qué cambios hiciste
- Pregunta si el problema persiste
- Adjunta la ruta del screenshot para que el usuario lo vea manualmente
Paso 4: Debuggear según lo que se vea
Overlay de Hyprland (más común)
El overlay cuenta TODOS los errores de parseo. Acción inmediata:
# 1. Encontrar la instancia de Hyprland
HYPRLAND_INSTANCE_SIGNATURE=$(ls /run/user/1000/hypr/)
# 2. Buscar errores de config
grep -i "no such option\|does not exist\|Invalid dispatcher" /run/user/1000/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log
# 3. Contar errores reales vs ruido de inicio
echo "ERR (config): $(grep -c 'ERR \]:' /run/user/1000/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log)"
echo "ERR (aquamarine/DRM): $(grep -c 'ERR from aquamarine' /run/user/1000/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log)"
echo "WARN: $(grep -c 'WARN' /run/user/1000/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log)"
Validar cada opción del config contra Hyprland en ejecución
for opt in "general:cursor_inactive_timeout" "decoration:drop_shadow" "decoration:shadow_range" "decoration:col.shadow" "misc:vfr" "misc:render_ahead_of_time" "misc:no_direct_scanout"; do
echo -n "$opt: "
hyprctl getoption $opt 2>&1 | head -1
done
"no such option"= removida — buscar reemplazo o eliminar- Devuelve un valor = válida
Notificaciones de Dunst
cat ~/.config/dunst/dunstrc 2>/dev/null
dunstctl history 2>/dev/null | head -20
EWW Dashboard (SWAL)
# Reiniciar daemon EWW (si se mató)
pkill -9 eww 2>/dev/null; rm -f /run/user/1000/eww-server_*
WAYLAND_DISPLAY=wayland-1 eww daemon; sleep 1; eww open dashboard
# Verificar estado
eww list-windows
eww state | grep -E "EWW_CPU|cal_widget|time " | head -3
Overflow fix: window 360px + scroll :hscroll false + :width 360 + inner box style="width:340px;min-width:340px;". NO max-width en GTK3 CSS. margin:0 6px removido de cards. cal_widget usa Pango markup con #00FF88. deflisten media_info para Now Playing.
Waybar con errores
journalctl --user -u waybar --no-pager -n 50
Error de compilación NixOS
nixos-rebuild dry-build --flake /path/to/flake#hostname 2>&1 | grep -iE "error|fail|trace"
Para errores de opciones deprecadas de Hyprland 0.55.x, ver references/hyprland-version-migration.md (incluye tabla completa de opciones antiguas → reemplazos, comandos de diagnóstico, y ejemplo before/after).
Paso 5: Verificar y cerrar el ciclo
- Aplicar fixes en el source (swal-desktop/hypr/hyprland.conf)
- Rebuild:
nixos-rebuild switch --flake ... - Recargar Hyprland:
hyprctl reload - Verificar que no hayan nuevos errores:
grep -c "ERR \]:" /run/user/1000/hypr/$SIGNATURE/hyprland.log # Debe ser 0 para el período post-reload - Captura post-fix para confirmar visualmente:
WAYLAND_DISPLAY=wayland-1 XDG_RUNTIME_DIR=/run/user/1000 grim /tmp/screenshot_after_fix.png
Paso 6: Si el overlay persiste después del reload
El Error Overlay de Hyprland se crea al inicio de la sesión y NO siempre se destruye con hyprctl reload. Si el overlay sigue visible aunque el log esté limpio:
- Decirle al usuario que cierre sesión (
SUPER SHIFT + Q→ logout, ohyprctl dispatch exit) - O agregar
disable_error_popups = trueenmisc {}para prevenirlo en el futuro
Pitfalls
- SIEMPRE verificar visualmente antes de reportar un fix. Si no hay modelo de visión disponible, NO digas "el problema está resuelto" — en su lugar: (a) ejecuta el Paso 3 → Opción C (análisis programático), (b) espera confirmación textual del usuario. Reportar "✅ arreglado" sin verificación visual causa frustración.
grimfalla con "failed to create display" → NecesitasWAYLAND_DISPLAY=wayland-1yXDG_RUNTIME_DIR=/run/user/1000slurppara screenshot de región puede fallar si no hay monitor conectadovision_analyzecon modelos text-only va a fallar → Usardelegate_taskcon subagente que tenga modelo de visión- La API de OpenCode Go requiere API key para acceso directo → Siempre usar las herramientas de Hermes (vision_analyze, delegate_task) en lugar de curl directo
- El screenshot puede ser grande (>500KB) → Reducir resolución o convertir a JPEG si es necesario:
magick /tmp/screenshot_debug.png -resize 50% /tmp/screenshot_small.jpg
Modelos con Visión en OpenCode Go
| Modelo | Tipo | Bueno para |
|---|---|---|
qwen3.6-plus |
Visión general | Debug de UI, texto en pantalla |
mimo-v2-omni |
Multimodal completo | Análisis general |
glm-5.1 |
Visión | Texto chino/español en pantalla |
04 同仓库更多 Skills
web-design-guidelines
暂无简介
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall. Recovers the page via archives and provenance-checked fallbacks.
studio-coach
暂无简介
src-generator
暂无简介
sqlite-pro
暂无简介
rigor-evaluator
Use when you need a quick heuristic rigor score (10 criteria, 0-2 each) for the features in a .gitcore/features.json file, to decide which features are ready to ship.