Pilote Desktop-Control

L'orchestrateur vous a routé ici. Utilisez ces mécaniques pour exécuter votre plan.

Pilotez les applications GUI de bureau natives via le cua-driver upstream trycua/cua : énumérez les applications et fenêtres, capturez les arbres d'accessibilité, cliquez/tapez/scrollez par element_index ou coordonnées pixel, et vérifiez par re-snapshot -- tout cela sans mettre la cible en avant-plan.

Quand l'utiliser

Automatiser une application de bureau native (Finder, Notepad, Paramètres système, éditeurs natifs)
Piloter les dialogues natifs et les feuilles de sécurité/permissions que ni le DOM ni PTY ne peuvent atteindre
QA visuelle d'UI native : captures par fenêtre, assertions sur l'arbre d'accessibilité

Si la cible est un TUI terminal, utilisez tuistory ou true-input. Si c'est une page web ou une application Electron, utilisez agent-browser -- CDP est supérieur aux arbres d'accessibilité pour tout ce qui est basé sur Chromium.

Support des plateformes

Plateforme	Tier upstream	Lire
macOS	Production	platforms/macos.md
Windows	Production	platforms/windows.md
Linux	Pre-release (vrais caveats)	platforms/linux.md

Lisez le fichier de plateforme pour votre OS cible. Chacun contient les permissions, le lancement du daemon, et les motifs et modes de défaillance spécifiques à la plateforme.

Prérequis

# installation unique : par utilisateur, pas de sudo/admin
curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash
# Windows (PowerShell) :
#   irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.ps1 | iex

cua-driver doctor           # sondes de plateforme : permissions, daemon, tuyauterie d'accessibilité
cua-driver skills install   # récupère le pack de skills upstream vers ~/.cua-driver/skills/cua-driver

Le pack upstream (~/.cua-driver/skills/cua-driver/SKILL.md + la doc de votre plateforme) est la référence approfondie -- surface d'outils complète, matrice de comportement d'état de fenêtre, listes de commandes interdites -- et il se met à jour avec le binaire. Lisez-le avant tout workflow non trivial. Cet atome possède l'intégration du contrôle droid : routage, isolation d'exécution, délégation, transmission de preuves.

Cycle de vie du daemon

Les workflows element_index requièrent le daemon. Sans lui, chaque invocation CLI est un processus frais et le cache d'éléments par (pid, window_id) meurt entre les appels.

cua-driver serve            # démarrer le daemon (macOS nécessite la forme LaunchServices -- voir platforms/macos.md)
cua-driver status           # santé du daemon et du socket
cua-driver stop

Les permissions sont vérifiées et accordées via le driver, pas en éditant manuellement les paramètres système (gate macOS uniquement ; surface sans effet sur Windows/Linux) :

cua-driver permissions status   # lecture seule ; répond via le daemon en cours d'exécution
cua-driver permissions grant    # flux de prompt attribué -- la bonne façon d'accorder

Boucle centrale

Les noms d'outils sont en snake_case et invoqués directement : cua-driver <tool> '<json>'. (cua-driver call <tool> est legacy ; ne l'utilisez pas.) cua-driver list-tools pour l'inventaire, cua-driver describe <tool> pour tout schéma.

Chaque workflow est Découvrir -> Observer -> Agir -> Vérifier contre un (pid, window_id) explicite :

cua-driver launch_app '{"name":"TextEdit"}'
#  -> {pid: 844, windows: [{window_id: 10725, ...}]}   # list_windows utile seulement pour les pids longs
cua-driver get_window_state '{"pid":844,"window_id":10725}' --screenshot-out-file "${RUN_DIR}/before.png"
cua-driver click '{"pid":844,"window_id":10725,"element_index":14,"session":"'"${RUN_ID}"'-desktop"}'
cua-driver get_window_state '{"pid":844,"window_id":10725}' --screenshot-out-file "${RUN_DIR}/after.png"

Capturez avant ET après chaque action. Le get_window_state pré-action résout le element_index que vous allez utiliser -- les indices sont par snapshot, par (pid, window_id), et les indices obsolètes échouent avec No cached AX state. Le snapshot post-action est la preuve que l'action a eu lieu ; sans lui une no-op silencieuse ressemble à un succès.

Préférence de mode d'adressage :

element_index (par défaut) -- sémantique, fonctionne sur les fenêtres cachées et en arrière-plan, pas de changement d'avant-plan.
Pixel click '{"pid":N,"window_id":W,"x":X,"y":Y}' -- pour les surfaces que l'arbre n'atteint pas (canvas, contrôles dessinés personnalisés). Les coordonnées sont les pixels de screenshot locaux à la fenêtre, origine en haut à gauche.
Clavier (press_key, hotkey) et fallbacks de plateforme -- dernier recours ; voir les fichiers de plateforme.

Isolation d'exécution (règle fondamentale 5 -> sessions cua)

Les sessions cua sont l'équivalent desktop des préfixes de session tctl : une session possède son curseur d'agent, ses remplacements de config, et son scope d'enregistrement. Déclarez-en une par run, dérivée du RUN_ID du workflow, et passez-la sur chaque action :

cua-driver start_session '{"session":"'"${RUN_ID}"'-desktop"}'
# ... chaque action porte "session":"${RUN_ID}-desktop" ...
cua-driver end_session '{"session":"'"${RUN_ID}"'-desktop"}'

Les workers parallèles déclarent chacun leur propre session et passent creates_new_application_instance: true à launch_app pour que chacun obtienne sa propre fenêtre. Le cache d'éléments est clé sur (pid, window_id) et le curseur sur session, donc les workers isolés ne peuvent pas entrer en collision.

Délégation

cua-driver est sur PATH -- les workers n'ont besoin d'aucune résolution ${DROID_PLUGIN_ROOT}. Comme pour les autres drivers, donnez aux capture workers des commandes exactes avec le scope de run du parent intégré :

Prompt de tâche pour un capture worker desktop :
  "Exécutez ces commandes dans l'ordre. Signalez les chemins de captures et toute erreur.
   1. cua-driver start_session '{"session":"1712345678-42-notepad"}'
   2. cua-driver launch_app '{"name":"Notepad","creates_new_application_instance":true}'
      -> notez le pid et window_id retournés
   3. cua-driver get_window_state '{"pid":<pid>,"window_id":<wid>}' --screenshot-out-file /tmp/droid-run-1712345678-42-xxxx/before.png
   4. cua-driver type_text '{"pid":<pid>,"window_id":<wid>,"element_index":<text-area>,"text":"hello","session":"1712345678-42-notepad"}'
   5. cua-driver get_window_state '{"pid":<pid>,"window_id":<wid>}' --screenshot-out-file /tmp/droid-run-1712345678-42-xxxx/after.png
   6. cua-driver end_session '{"session":"1712345678-42-notepad"}'"

Transmission de preuves

Type de preuve	Comment capturer
État de fenêtre	`get_window_state ... --screenshot-out-file ${RUN_DIR}/proof-N.png` (garde aussi le PNG hors de la réponse d'outil)
Affichage complet	`cua-driver screenshot '{"out_file":"'"${RUN_DIR}"'/screen.png"}'`
Assertions sémantiques	`tree_markdown` depuis `get_window_state` (filtrer avec `"query":"..."`)
Vidéo	`cua-driver recording start` / `recording stop` -> `recording.mp4` scoped à la session

Passez les chemins PNG/mp4 à compose / verify comme toute autre sortie de driver. Conservez la sortie d'outil brut à côté des captures chaque fois que le comportement GUI est la chose testée.

Règles critiques

Ne changez jamais l'application frontmost de l'utilisateur. Si une commande dit activer, mettre en avant-plan, élever, ou rendre clé -- arrêtez ; les chemins d'événements par-pid existent précisément pour que vous n'en ayez pas besoin. Les listes interdites de plateforme vivent dans le pack upstream.
Re-capturez après chaque action et signalez ce que vous avez observé, pas ce que vous aviez l'intention de faire. Un arbre inchangé après une action est une trouvaille, pas une formalité.
Les actions destructives ont besoin d'une intention utilisateur explicite. Ne supprimez pas de fichiers, n'envoyez pas de messages, ne soumettez pas de formulaires à moins que le workflow n'ait demandé exactement cela.

desktop-control