Toma de control del escritorio

Resumen

Orquestación unificada de "que el agente tome el control del escritorio para realizar operaciones GUI": primero decide la ruta óptima, luego asegura que los permisos de computer use estén listos, y finalmente despacha la tarea y la verifica. Computer use es la ruta de respaldo, no la ruta preferida; solo se usa cuando la tarea debe realizarse a través de la GUI.

Árbol de decisión del flujo de trabajo

Al recibir una solicitud de operación de escritorio, evalúa las rutas en el siguiente orden, deteniéndose en la primera que coincida:

1. ¿El conector/MCP puede llegar directamente?
   La aplicación destino tiene un conector conectado (GitHub, WPS Knowledge Base, WeChat Work, etc.)
   → Usa el conector, no toques la GUI
   Ej: Consultar PR en GitHub → conector gh; Leer documento de WPS → wps-knowledgebase

2. ¿Es una operación puramente de navegador?
   La tarea ocurre en una página web (llenar formularios, hacer clic en elementos web, comparar capturas)
   → Usa el skill browser-use, no toques la GUI del sistema
   Ej: Iniciar sesión en un sitio web y cambiar configuración → browser-use

3. ¿Es lectura/escritura de archivos Office/WPS?
   El objetivo es contenido de archivos doc/docx/xls/xlsx/ppt/pptx
   → Usa la familia de skills Office (workbuddy-docx / sheetagent / local-office-edit)
   Ej: Modificar una tabla en Word → local-office-edit

4. ¿Se puede alcanzar con línea de comandos/scripts?
   La tarea es esencialmente manipulación de archivos, procesamiento de datos o configuración del sistema, y existe una ruta CLI o de script
   → Usa Bash/scripts directamente
   Ej: Renombrar archivos por lote → script; Consultar información del sistema → comando

5. Si ninguna de las anteriores funciona → computer use: toma de control del escritorio
   La tarea debe manipular elementos de interfaz de una aplicación GUI (botones, menús, ventanas no web)
   Ej: Cambiar una opción de configuración que solo tiene entrada GUI en un software propietario

Principio de evaluación: Cada nivel inferior que se baja, la confiabilidad y la velocidad disminuyen, y la incertidumbre aumenta. Las operaciones GUI implican múltiples incertidumbres (localización de elementos, foco de ventana, idioma de la interfaz) y son el último recurso.

Nota: La dependencia de la visibilidad en el nivel 5 (enumeración de ventanas + captura de pantalla) es una debilidad estructural cuando Stage Manager está activado (consulta el elemento 2 de Pre-flight y la "Trampa de ventana invisible"). Las herramientas del sistema AX (percepción del árbol de accesibilidad) leen geometría lógica y no se dejan engañar por la compresión visual de Stage Manager, por lo que son una ruta alternativa/complementaria — la re-verificación en 27.0.1 ha confirmado parcialmente esto (consulta el descubrimiento 5 en la subsección de trampas), con la condición limitante de que las ventanas iniciadas por primera vez y que nunca han estado en el escenario también son invisibles para el árbol AX. La herramienta de respaldo AX incorporada en este skill: tools/axctl (uso en el capítulo "Capa de respaldo AX").

Al enrutar, si no estás seguro de si la aplicación destino tiene un conector, primero consulta list_installed_plugins, no asumas de memoria.

Pre-flight: verificación dual de permisos y entorno

Antes de usar computer use, se deben completar dos verificaciones previas, ninguna puede omitirse:

1. Verificación de permisos

Llama a gui_permission_status:

all_granted: true → pasa a la segunda verificación
Permisos faltantes → sigue el flujo en references/authorization-macos.md para guiar al usuario a otorgar permisos (macOS)
Windows → la versión actual solo admite macOS, informa claramente al usuario

2. Verificación de Stage Manager (obligatorio, los usuarios suelen tenerlo activado)

Ejecuta defaults read com.apple.WindowManager GloballyEnabled:

Devuelve 1 (activado) → antes de despachar, primero open -a <nombre_app> para activar la aplicación destino y traerla al escenario actual (robará el foco brevemente, informa al usuario primero), luego gui_list_windows para confirmar que la ventana destino es visible, y finalmente create_task. Si después de la activación la ventana aún no aparece en la lista, entra directamente en la secuencia de diagnóstico de la "Trampa de ventana invisible" a continuación — no reintentes create_task, no asumas que la aplicación está fallando
Devuelve 0 (desactivado) → procede directamente con el flujo de despacho normal

Esta verificación previa eleva la trampa de Stage Manager de "diagnóstico posterior" a "prevención anticipada". Stage Manager no es poco común entre usuarios de macOS 15+, y para aquellos que lo tienen activado, esta ruta es la ruta predeterminada en cada despacho, no una excepción. El mecanismo de activación-visualización se ha re-verificado en macOS 27.0.1 el mismo día, pero existen dos nuevos detalles: "la primera activación no se mantiene" y "retroceso después de visualizarse"; consulta la subsección de re-verificación en 27 en la "Trampa de ventana invisible".

Despacho de tareas

Una vez que los permisos están listos, sigue el flujo de trabajo estándar del skill de computer use incorporado:

gui_list_windows localiza la ventana de la aplicación destino; si no acierta, open_app para iniciarla
Verifica la visibilidad después de iniciar: después de open_app, debes llamar a gui_list_windows nuevamente para confirmar que la ventana realmente aparece en la lista. Si no aparece, no te apresures a concluir "la aplicación está rota"; primero consulta la "Trampa de ventana invisible" a continuación
Si Stage Manager está activado (confirmado en Pre-flight): primero open -a para activar la aplicación destino antes de despachar — consulta el elemento 2 de Pre-flight, no repitas la evaluación aquí
create_task(window_id, task) despacha la tarea

Trampa de ventana invisible (escenario con Stage Manager)

Ámbito de aplicación de las conclusiones: experimento controlado en macOS 15 establecido por primera vez; verificado y re-verificado en macOS 27.0.1 (sonda de doble canal Swift + medición real con API AX nativa en binario, mecanismo confirmado y se descubrieron nuevos detalles, ver más abajo). La conclusión sobre la capa AX ha sido confirmada por medición real posterior a la autorización en 27.0.1 (ruta AXError=0), ya no se basa en inferencias.

Condiciones de activación: Stage Manager activado, independientemente de si la aplicación se inició en segundo plano. Cuando está activado, las ventanas de aplicaciones que no están en el escenario actual existen realmente pero no pueden ser capturadas correctamente por la enumeración de ventanas ni las capturas de pantalla — el proceso está vivo, la ventana se ha creado (por ejemplo, Cmd+N funcionó), pero gui_list_windows no puede ver la ventana normal. Una vez que la aplicación se activa (la ventana regresa al escenario actual), la ventana se vuelve visible inmediatamente.

Nuevos descubrimientos de la re-verificación en macOS 27.0.1:

Mecanismo de barra de miniaturas visualizado: las ventanas de aplicaciones fuera del escenario se comprimen en miniaturas laterales (medido: la ventana principal de Calculator se comprimió a 39×100pt pegada al borde izquierdo, además se generaron 4 ventanas de marcador de escenario de ancho completo de 34pt). Si gui_list_windows filtra por "ventanas de tamaño normal", estas miniaturas podrían pasar desapercibidas o ser malinterpretadas
La activación y visualización siguen siendo válidas, pero existe el fenómeno de "la primera activación no se mantiene": en la prueba real, después del primer open -a, la ventana principal aún estaba en miniatura (cuando el frente estaba ocupado por otra aplicación), y solo con el segundo open -a se expandió al tamaño completo (405, 517, 230×408). Manejo: después de la activación, verifica inmediatamente con gui_list_windows; si no se visualiza, vuelve a ejecutar open -a (máximo 2 veces); solo si aún no se visualiza, entra en la secuencia de diagnóstico
Posible retroceso después de la visualización: cuando otra aplicación recupera el frente, la ventana puede volver a comprimirse a miniatura en unos 5 segundos (reproducido en la prueba). Corolario: existe una ventana de tiempo para la verificación con captura de pantalla — si el frente es arrebatado durante la ejecución de create_task, la tarea en sí no se ve afectada, pero gui_screenshot tomada después del retroceso no mostrará la ventana destino. Manejo: si acaba de ocurrir un cambio de frente antes de la captura, primero ejecuta open -a y luego toma la captura
El canal CGWindowList no se ve afectado: tanto optionOnScreenOnly como la lista completa pueden enumerar la ventana (solo el título requiere permiso de grabación de pantalla) — pero ten en cuenta que en la lista onScreenOnly aparecen las miniaturas, no la ventana principal. Las herramientas que dependen de las coordenadas de la ventana para hacer clics apuntarán al lugar equivocado (al clic en la miniatura, no al botón real)
El árbol AX lee geometría lógica, es inmune al desplazamiento de miniaturas, pero tiene una zona ciega (medido en 27.0.1 después de la autorización): el frame de la ventana devuelto por AX son coordenadas lógicas de tamaño completo (ej. (405,517,230×408)), mientras que al mismo tiempo el estado renderizado de CGWindowList muestra una miniatura de 39×100pt — el desplazamiento geométrico de Stage Manager no engaña a AX. Pero la zona ciega: para ventanas iniciadas por primera vez que nunca han estado en el escenario, el árbol AX reporta windows=0; después de haber estado en el escenario y luego iniciarse en segundo plano, AX permanece visible. Corolario: la percepción de AX tampoco es incondicionalmente inmune; las aplicaciones iniciadas por primera vez aún necesitan activarse en el escenario. Además: hacer clic con eventos de ratón sintéticos en la pantalla utilizando las coordenadas lógicas de AX hará clic en la aplicación equivocada (posición lógica ≠ posición renderizada actual) — las herramientas del sistema AX para acciones deben usar la API de acciones de accesibilidad como AXPress (ej. axctl), no clics por coordenadas

Orden de diagnóstico (cuando la aplicación destino no aparece en la lista de ventanas):

Primero verifica si el proceso está vivo (pgrep): vivo → probablemente sea un problema de visibilidad, no un fallo de la aplicación
Confirma si el usuario tiene Stage Manager activado (macOS 15+, defaults read com.apple.WindowManager GloballyEnabled, 1=activado): activado → ve al paso 3; no activado → posible que la ventana haya desaparecido repentinamente u otra razón
Activa la aplicación para hacerla visible: open -a <nombre_app> (robará el foco brevemente, informa al usuario primero); en 27, la primera activación puede no mantenerse, verifica inmediatamente después de activar; si no se visualiza, activa nuevamente (máximo 2 veces)
Vuelve a ejecutar gui_list_windows, normalmente obtendrás el window_id

Señal adicional: cuando Stage Manager está activado, open_app generalmente no obtiene un window_id (devuelve un hint para una segunda enumeración); cuando está desactivado, devuelve window_id normalmente.

Corolarios importantes:

Reportar sin ventana visible ≠ la ventana no existe, y mucho menos que la operación anterior falló — la tarea "fallida" anterior podría haber tenido éxito (la ventana se creó, solo que no se ve)
Las ventanas de tipo diálogo (ej. diálogo "Abrir" archivo) que la tarea cierra por sí misma invalidan su window_id, y las capturas posteriores fallarán — esto es normal; simplemente enumera de nuevo para obtener un nuevo ID
Algunas aplicaciones (ej. TextEdit) no tienen ventanas al iniciarse sin un documento, esto es comportamiento normal; necesitas abrir un archivo con ellas

Formato de tres partes de la descripción de la tarea (clave para el éxito o fracaso)

El parámetro task debe contener tres partes:

Objetivo: describe paso a paso lo que se debe lograr
Límites: especifica claramente lo que no se debe tocar, ej. "No hacer clic en ningún elemento del historial"
Manejo de errores: si una operación no responde, registra exactamente lo que ocurrió y pasa al siguiente paso; no reintentes ni uses otro método

La regla de manejo de errores no es opcional — si falta, un solo fallo desencadenará reintentos repetidos que agotarán toda la cuota de pasos.

En la descripción no uses coordenadas de píxel ni posiciones numéricas; usa el texto visible y los nombres de los controles de la interfaz para referirte a los objetivos.

Ejemplo

Solicitud del usuario: "Ayúdame a abrir la aplicación XX y cambiar el formato de exportación a CSV"

Objetivo: 1. Encontrar y hacer clic en la entrada "Configuración" o "Preferences" en la barra de menú o barra de herramientas
2. En el panel de configuración, encontrar la opción "Formato de exportación" o "Export Format"
3. Cambiar su valor a CSV
4. Guardar la configuración y cerrar el panel
Límites: No modificar ninguna otra opción de configuración; no hacer clic en el botón "Restablecer"
Manejo de errores: Si no se encuentra el control mencionado, registrar los nombres de los controles realmente vistos y finalizar la tarea; no hacer clics especulativos

Capa de respaldo AX (axctl)

Cuando el computer use incorporado no está disponible (no habilitado, faltan herramientas gui_*, la tarea es demasiado pequeña para merecer un despacho) o se necesita una operación de elementos a nivel semántico, usa la herramienta de respaldo AX de este skill: tools/axctl. Implementación pura de Accessibility API, no toca el mouse, no roba el foco, no está restringida por el sandbox de AppleEvents (el sandbox de WorkBuddy prohíbe enviar eventos de control a System Events; la ruta de osascript está obsoleta, no intentes más).

Ubicación e instalación: binario tools/axctl, código fuente tools/axctl.swift (archivo único Swift), ambos distribuidos con el skill. Antes del primer uso, ejecuta sh tools/install.sh: si detecta swiftc, compila en el momento (recomendado, código auditado, adaptado a la arquitectura local); de lo contrario, usa el binario precompilado incluido (solo Apple Silicon). Después de modificar el código fuente, ejecuta swiftc -O -o axctl axctl.swift en el directorio tools para recompilar.

Requisito previo: el host debe tener el permiso TCC de "Accesibilidad" (en Configuración del Sistema → Privacidad y Seguridad → Accesibilidad, marca el host y reinicia el host para que surta efecto; la señal de preparación es que una llamada AX devuelva AXError=0).

Subcomandos

axctl list <bundle-id|pid>        Lista ventanas: título + frame de geometría lógica
axctl tree <target> [depth]       Lee el árbol UI: rol/título/descripción/valor/frame (profundidad predeterminada=2)
axctl actions <target> <título>    Verifica la lista de acciones disponibles para elementos coincidentes
axctl press <target> <título>     Ejecuta AXPress (clic semántico, a nivel de elemento, sin necesidad de coordenadas)
axctl activate <target>           Activa la aplicación (NSRunningApplication.activate)

<target> admite bundle id (recomendado, ej. com.apple.calculator), PID numérico, o nombre de aplicación localizado (coincidencia en minúsculas — en un sistema en chino es "计算器", no "Calculator"; la coincidencia por nombre es propensa a errores, se prefiere bundle id).

Reglas de uso

Búsqueda de elementos: primero tree o, si conoces el título del botón, directamente actions para confirmar que existe AXPress, luego press. press solo funciona en elementos que tienen la acción AXPress; los elementos de menú tienen AXPick; evalúa por tipo
Verificación de acciones: después de que press devuelva PRESSED, usa tree para leer el nuevo valor del elemento destino o del área de visualización asociada como evidencia (consulta la prueba real con Calculator: después de press "3", el valor del StaticText cambió a 3) — al igual que la verificación con captura de pantalla de computer use, la autodescripción textual no cuenta
Escenario con Stage Manager: el árbol AX lee geometría lógica; las ventanas en estado de miniatura se pueden leer y operar (probado en la realidad); pero para aplicaciones iniciadas por primera vez que nunca han estado en el escenario, el árbol AX está vacío — primero ejecuta axctl activate o open -a para que aparezcan en el escenario antes de operar
Límites de aplicabilidad: axctl es adecuado para lectura/escritura a nivel de elementos (botones/menús/campos de texto); para clics en la barra de menú entre aplicaciones, simulación de teclado/ratón a nivel del sistema, o flujos GUI complejos de múltiples pasos, sigue usando el despacho de computer use incorporado
Limitaciones conocidas: no tiene monitoreo de cambios en la IU (capacidad observe_changes de axmcp, se evaluará después de que el upstream se adapte a Swift 6.4); operación de un solo elemento a la vez, sin transacciones por lotes

Registro de pruebas reales (macOS 27.0.1, Stage Manager activado)

axctl press com.apple.calculator "3" → PRESSED path=w/0/0/0/1/0/15 → tree leyó el valor de AXStaticText como 3 — lectura del árbol, localización, clic semántico y verificación del efecto, todos los cuatro pasos funcionaron.

Verificación de resultados

La autodescripción textual del agente GUI no es suficiente como evidencia de finalización — el estado residual de la interfaz anterior podría ser malinterpretado como éxito. Es necesario:

Después de que la tarea devuelva done=true, llama a gui_screenshot(window_id) para obtener la captura final
Usa el contenido de la captura para determinar si se ha alcanzado el objetivo
Al informar al usuario, especifica que la conclusión se basa en la captura de pantalla

Entre rondas, no tomes capturas de pantalla por defecto (el valor de retorno de continue_task ya incluye el historial de ejecución); solo toma una captura adicional si el reasoning/action_desc del agente no cambia durante varias rondas consecutivas para determinar si se ha quedado atascado.

Referencia rápida de solución de problemas

Síntoma	Manejo
`permission_denied`	Consulta `references/authorization-macos.md`
Múltiples rondas consecutivas estancadas en el mismo paso	`continue_task` con el parámetro `hint` para dar el texto visible exacto del control
La interfaz no cambia pero reporta éxito	Confía en `gui_screenshot`; verifica que el `window_id` sea correcto
`conflict`	Esa ventana ya tiene una tarea, primero `delete_task`
`window_not_found`	La ventana se ha cerrado o el ID ha expirado, vuelve a ejecutar `gui_list_windows`
`sin ventana visible` (con el proceso vivo)	Stage Manager activado hace que la ventana sea incapturable: `open -a` para activar → enumera inmediatamente; si no se visualiza, activa nuevamente (en 27 la primera activación puede no mantenerse, máximo 2 veces). Consulta la "Trampa de ventana invisible" (confirmado experimentalmente en 15 y 27.0.1)
La captura muestra la ventana anormalmente pequeña/pegada al borde de la pantalla	La ventana destino está en miniatura de Stage Manager (descubrimiento en la re-verificación en 27): primero `open -a` para activarla y restaurar el tamaño completo antes de tomar la captura. Consulta los elementos 1 y 3 de la subsección de re-verificación en 27 de la "Trampa de ventana invisible"
Estado `call_user`	Se necesita intervención humana; transmite el `reasoning` al usuario; no llames a `continue_task`

Soporte de plataforma

macOS: soporte completo. El flujo de autorización se encuentra en references/authorization-macos.md
Windows: no verificado, la versión actual no promete soporte. Cuando te encuentres con un entorno Windows, informa honestamente al usuario de esta limitación; no intentes aplicar el modelo de permisos de macOS

Recursos

references/authorization-macos.md — flujo completo de autorización en macOS, incluyendo problemas comunes encontrados en pruebas reales (no funciona después de marcar, ventana emergente "Quit & Reopen", etc.)
tools/axctl — herramienta de respaldo AX (código fuente tools/axctl.swift en el mismo directorio; antes del primer uso ejecuta sh tools/install.sh), uso en el capítulo "Capa de respaldo AX"

GreenWich-art/agent-skills

¿Qué es agent-skills?

Preguntar en tu IA favorita

Documentación