Utilisation sur desktop

Un seul contrôleur opère une cible GUI exacte, observe chaque effet, et s'arrête quand la postcondition de l'utilisateur est prouvée.

Agir

Objectif	Commande / outil
Découvrir	`cua-driver list_apps` ; utiliser `launch_app` quand un lancement est demandé, puis sélectionner la fenêtre prévue dans sa réponse ou utiliser `list_windows`
Observer	`get_window_state` avec le `pid` observé, le `window_id`, et la `session` du run ; utiliser `query`, `max_elements`, ou `max_depth` pour limiter les grands arbres
Agir	`click` / `type_text` avec une `target` exacte et un `element_token` frais ; utiliser `x,y` uniquement depuis une capture d'écran de cible valide
Menu / géométrie	Préférer `invoke_menu` avec un chemin de menu observé, ou `set_window_frame` ; vérifier l'état de la fenêtre résultant
Vérifier	`get_window_state` / `get_desktop_state` frais, ou `verify_state` pour une postcondition de fenêtre exacte et exprimable
Terminer	Finalisez tout enregistrement détenu, puis `end_session` ; laissez les applications personnelles et services partagés en cours d'exécution sauf si une fermeture a été demandée

Utilisez le CLI par défaut ou une connexion MCP existante. Remplacez les identifiants d'exemple, les tokens, les coordonnées, et RUN_ID par les observations actuelles et une étiquette de run unique :

cua-driver get_window_state '{"pid":844,"window_id":10725,"session":"RUN_ID"}'
cua-driver click '{"target":{"kind":"window","pid":844,"window_id":10725},"element_token":"s0000002a:14","session":"RUN_ID"}'
# Observez à nouveau et vérifiez l'effet demandé avant une autre action.

Détection et configuration

command -v cua-driver
cua-driver --version
cua-driver status
cua-driver doctor
cua-driver describe click

Aucune installation séparée de la skill Cua n'est requise. Préservez les wrappers exécutables et la propriété des services existants. Si le binaire est manquant, obtenez l'approbation avant d'utiliser l'installateur macOS/Linux ou l'installateur Windows officiel. Inspectez les schémas en direct non familiers ; une version cliente ne détermine pas un daemon déjà en cours d'exécution.

Hôte	Configuration requise
macOS	L'app/hôte responsable a besoin d'autorisations Accessibilité et Enregistrement d'écran ; laissez l'utilisateur exécuter `cua-driver permissions grant` et approuver les invites
Windows	L'exécution doit se faire dans la session interactive du bureau, pas Session 0 ; l'utilisateur/hôte gère l'installation et les invites de sécurité
Linux	Exécutez comme utilisateur graphique sur son bus d'affichage/session ; Wayland natif peut nécessiter `CUA_DRIVER_RS_ENABLE_WAYLAND=1` dans l'environnement du service. Le support de capture/saisie/vidéo du compositeur varie

Règles

Ne substituez jamais les méthodes. Cua-only/native-input exclut CDP, DOM, les APIs applicatives, et les raccourcis shell/média, y compris pour Electron.
Ne partagez jamais le contrôle du bureau. Gardez l'observation interactive, l'entrée, les attentes de permission, et le nettoyage dans le parent. Réutilisez une étiquette de run et un répertoire d'artefacts ; répétez session sur chaque appel CLI supporté. Les étiquettes n'isolent pas le focus, l'état app, ou les caches de snapshot.
Ne réutilisez jamais les cibles obsolètes ou ambiguës. Un nouveau snapshot invalide les anciens handles. Ne combinez pas target avec des champs de ciblage à plat ; l'observation et les outils sémantiques uniquement conservent leurs propres schémas. Ré-résolvez les lancements à froid ou fenêtres disparues avec découverte limitée, pas les lancements répétés.
Ne déduisez jamais les pixels d'une absence de preuve. Lisez l'image réelle et ses dimensions ; tenez compte des aperçus/crops redimensionnés. La capture arborescente uniquement ne peut pas fonder l'entrée en pixels. capture_mode ne répare pas les échecs de capture.
N'escaladez jamais implicitement. L'entrée du fond de fenêtre est le défaut. La livraison en avant-plan, l'activation de menu temporaire, la capture/saisie du bureau, les changements de service, et les approbations OS nécessitent l'autorisation appropriée de l'utilisateur/hôte.
N'équivalez jamais livraison et complétion. Réobservez après une saisie incertaine, partielle, ou interrompue avant de réessayer. Vérifiez la postcondition de la tâche : la sélection n'est pas la lecture ; une frame inchangée n'est pas la preuve d'un gel ; une fenêtre fermée n'est pas la preuve de la sortie du processus.

Carte des défaillances

Symptôme	Action suivante
Binaire manquant, permission, ou capacité	Rapportez l'étape `BLOCKED` (vérifiez le vocabulaire) et résolvez la configuration avec l'utilisateur plutôt que d'installer, redémarrer, ou changer silencieusement les paramètres de sécurité
Installation ou mise à jour `cua-driver` interrompue	Avant de réessayer, inspectez ce qui existe : `cua-driver --version`, `cua-driver status`, et tout service ou wrapper en cours ; avec approbation, réessayez uniquement l'étape qui n'a pas été complétée
Arbre clairsemé	Inspectez `degraded_reason` ; réessayez une fois pour l'initialisation lazy. Utilisez les pixels uniquement si une image valide existe
Image manquante / `surface_identity_unproven`	Utilisez la sémantique retournée si suffisante ; sinon, demandez un scope desktop ou rapportez l'étape `BLOCKED`. Ne reclassifiez pas un crop comme capture de fenêtre vérifiée
Timeout ou échec opaque de capture/saisie	Recherchez une boîte de dialogue de permission en attente : lisez l'état du bureau autorisé, ou demandez à l'utilisateur ce qui est apparu. Laissez-les approuver ou refuser ; après approbation, ré-acquérez un état frais plutôt que de rejouer l'action expirée
`background_unavailable`	Réobservez ; réessayez uniquement l'action nécessaire avec `delivery_mode:"foreground"` si le contrôle visible est autorisé

Pour une boucle de bureau autorisée, utilisez get_desktop_state → saisie avec target:{"kind":"desktop","display_id":"primary"} → état de bureau frais. L'entrée clavier suit le focus visible : arrêtez si l'utilisateur ou un autre contrôleur le change.

Enregistrement

Uniquement si demandé. Vérifiez la connexion d'abord : les outils d'enregistrement sont accessibles via cua-driver call aussi bien que MCP, mais start_recording indique que la vidéo dure pour la connexion client qui l'a démarrée, donc l'enregistrement s'exécute sur une connexion MCP persistante. Si aucun outil MCP get_recording_state n'est callable dans cette session, l'étape d'enregistrement est BLOCKED : remettez à l'utilisateur la ligne droid mcp add … affichée par cua-driver mcp-config --client droid, n'ajoutez pas le serveur ou ne démarrez pas les services vous-même, et reprenez une fois reconnectés.

Sur cette connexion : get_recording_state({}) → start_recording({"output_dir":"/absolute/unused/run-dir","record_video":true}) → actions autorisées → stop_recording({}).

Ces outils d'enregistrement n'ont pas de paramètre session public. La vidéo est désactivée par défaut ; vérifiez video_active et last_error. L'enregistreur est partagé au sein de son runtime, et l'arrêt manuel est inconditionnel : coordonnez-vous avec un propriétaire existant plutôt que de prendre le relais. Finalisez avant de déconnecter ; inspectez last_video_path, décodez la vidéo, et vérifiez son scope/dimensions/durée. Un PNG qui fonctionne ne prouve pas le support vidéo Wayland.

Transmission des preuves

Rapportez les résultats ordinaires de la tâche directement. Chargez capture pour les preuves enregistrées ou multi-étapes, verify pour la preuve formelle/QA, et compose uniquement pour un artefact produit. Incluez le driver/hôte, la cible/route d'entrée exacte, la postcondition observée, les chemins des preuves brutes, et toute limitation. Préservez les enregistrements partiels comme preuves incomplètes ; passez en revue le contenu privé avant de le partager.

desktop-use