Desktop Takeover

Présentation

Orchestration unifiée du processus complet par lequel l'agent prend le contrôle du bureau pour effectuer des opérations GUI : d'abord router pour trouver la meilleure voie, puis s'assurer que les autorisations computer use sont prêtes, et enfin distribuer la tâche et la valider. Attention : computer use est une voie de secours, pas la voie par défaut – elle n'est utilisée que lorsque la tâche doit absolument être réalisée via une interface graphique.

Arbre de décision du workflow

Lors d'une demande d'opération sur le bureau, suivre cet ordre pour déterminer la voie, s'arrêter dès qu'une correspondance est trouvée :

1. Connecteur/MCP accessible directement ?
   L'application cible dispose d'un connecteur installé (GitHub, WPS Knowledge Base, WeCom, etc.)
   → Utiliser le connecteur, ne pas toucher à la GUI
   Exemple : Vérifier une PR GitHub → connecteur gh ; Lire un document WPS → wps-knowledgebase

2. Operation purement navigateur ?
   La tâche se déroule dans une page web (remplir un formulaire, cliquer sur un élément, comparer des captures d'écran)
   → Utiliser la skill browser-use, ne pas toucher à la GUI système
   Exemple : Se connecter à un site pour modifier des paramètres → browser-use

3. Lecture/écriture de fichiers Office/WPS ?
   La cible est un fichier doc/docx/xls/xlsx/ppt/pptx
   → Utiliser la famille de skills Office (workbuddy-docx / sheetagent / local-office-edit)
   Exemple : Modifier un tableau dans Word → local-office-edit

4. Accès par ligne de commande/script ?
   La tâche est fondamentalement une opération de fichier, un traitement de données, une configuration système, et il existe une voie CLI ou script
   → Utiliser directement Bash/script
   Exemple : Renommer en masse → script ; Consulter les infos système → commande

5. Aucune des voies ci-dessus n'est possible → Prise en contrôle du bureau par computer use
   La tâche nécessite de manipuler des éléments d'interface d'une application GUI (boutons, menus, fenêtres non-web)
   Exemple : Modifier un paramètre uniquement accessible par GUI dans un logiciel chinois

Principe de décision : À chaque niveau inférieur, la fiabilité et la rapidité diminuent, l'incertitude augmente. Les opérations GUI impliquent de multiples incertitudes : localisation des éléments, focus des fenêtres, langue de l'interface. C'est le dernier recours.

Remarque : La dépendance à la visibilité de niveau 5 (énumération des fenêtres + capture d'écran) est une faiblesse structurelle lorsque Stage Manager est activé (voir Pré-vol, point 2 et le « Piège des fenêtres invisibles »). Les outils AX (arbre d'accessibilité) lisent les coordonnées logiques, insensibles aux déplacements et réductions de Stage Manager. Ils constituent une voie alternative/de secours. 27.0.1 a partiellement confirmé (voir la découverte 5 dans la section Piège) : condition limite – les fenêtres nouvellement lancées qui ne sont jamais montées sur la scène sont également invisibles dans l'arbre AX. L'outil de secours AX intégré à cette skill : tools/axctl (utilisation décrite dans le chapitre « Couche de secours AX »).

En cas de doute sur l'existence d'un connecteur pour l'application cible, vérifier d'abord list_installed_plugins, ne pas se fier à la mémoire.

Pré-vol : Double vérification des autorisations et de l'environnement

Avant d'utiliser computer use, deux vérifications préalables sont obligatoires, aucune ne peut être sautée :

1. Vérification des autorisations

Appeler gui_permission_status :

all_granted: true → Passer à la deuxième vérification
Autorisations manquantes → Suivre le processus du fichier references/authorization-macos.md pour guider l'utilisateur (macOS)
Windows → La version actuelle ne prend en charge que macOS. En informer clairement l'utilisateur.

2. Pré-vérification de Stage Manager (obligatoire – Stage Manager est souvent activé)

Exécuter defaults read com.apple.WindowManager GloballyEnabled :

Retourne 1 (activé) → Avant de distribuer la tâche, il faut d'abord open -a <nom_app> pour activer l'application cible et la ramener sur la scène actuelle (cela volera brièvement le focus ; en informer l'utilisateur au préalable). Ensuite, appeler gui_list_windows pour confirmer que la fenêtre cible est visible, puis enfin create_task. Si la fenêtre n'est toujours pas dans la liste après l'activation, passer directement à la séquence de dépannage « Piège des fenêtres invisibles » ci-dessous – ne pas réessayer create_task, ne pas conclure que l'application est défaillante.
Retourne 0 (désactivé) → Suivre le processus de distribution normal.

Cette pré-vérification fait passer le piège de Stage Manager d'un « diagnostic a posteriori » à un « contournement a priori ». Stage Manager est assez courant chez les utilisateurs de macOS 15+. Pour ceux qui l'ont activé, cette vérification est le chemin par défaut à chaque distribution, pas une exception. Le mécanisme d'activation et de matérialisation a été re-vérifié sur macOS 27.0.1 le même jour, mais avec deux nouveaux détails : « la première activation ne colle pas » et « rétrécissement après matérialisation ». Voir le sous-chapitre « Re-vérification sur 27 » dans la section « Piège des fenêtres invisibles ».

Distribution des tâches

Une fois les autorisations prêtes, suivre le workflow standard de la skill computer use intégrée :

gui_list_windows pour localiser la fenêtre de l'application cible ; si rien ne correspond, open_app pour la lancer.
Vérifier la visibilité après le lancement : après open_app, rappeler gui_list_windows pour confirmer que la fenêtre apparaît bien dans la liste. Si elle n'apparaît pas, ne pas conclure hâtivement que « l'application est cassée ». Consulter d'abord le « Piège des fenêtres invisibles » ci-dessous.
Si Stage Manager est activé (confirmé par la pré-vérification) : activer d'abord l'application cible avec open -a avant de distribuer la tâche – voir Pré-vol, point 2 ; ne pas répéter la vérification ici.
create_task(window_id, task) pour distribuer la tâche.

Piège des fenêtres invisibles (scénario Stage Manager)

Périmètre des conclusions : Établi pour la première fois par des expériences contrôlées sur macOS 15. Re-vérifié et re-testé sur macOS 27.0.1 (sondes double-canal Swift + test binaire natif via AX API ; mécanisme confirmé avec de nouveaux détails, voir ci-dessous). Les conclusions sur la couche AX ont été confirmées par des tests réels sur 27.0.1 après autorisation (canal AXError=0), sans recourir à des déductions.

Conditions de déclenchement : Stage Manager activé, indépendant du lancement en arrière-plan. Lorsqu'il est activé, les fenêtres d'applications qui ne sont pas sur la scène actuelle existent réellement mais ne peuvent pas être correctement capturées par l'énumération des fenêtres et les captures d'écran – le processus est vivant, la fenêtre a été créée (par exemple, Cmd+N a fonctionné), mais gui_list_windows ne voit pas de fenêtre normale. Dès que l'application est activée (la fenêtre revient sur la scène actuelle), la fenêtre devient immédiatement visible.

Nouvelles découvertes lors de la re-vérification sur macOS 27.0.1 :

Visualisation du mécanisme des miniatures latérales : La fenêtre d'une application mise en arrière-plan est réduite en une petite miniature latérale (test réel : la fenêtre principale de la Calculatrice a été réduite à 39×100 pt, collée au bord gauche ; 4 autres fenêtres de scène en pleine largeur de 34 pt ont été générées). Si gui_list_windows filtre par « fenêtre de taille normale », ces miniatures peuvent être manquées ou mal interprétées.
L'activation rend la fenêtre visible, mais il y a un phénomène de « première activation qui ne colle pas » : Test réel : après un premier open -a, la fenêtre principale est toujours en miniature (l'avant-plan est occupé par une autre application). Ce n'est qu'après un deuxième open -a qu'elle s'agrandit à sa taille réelle (405, 517, 230×408). Traitement : Après activation, vérifier immédiatement par gui_list_windows. Si la fenêtre n'est pas matérialisée, refaire open -a (maximum 2 fois). Si elle n'est toujours pas matérialisée, passer à la séquence de dépannage.
Rétrécissement possible après matérialisation : Si l'avant-plan est repris par une autre application, la fenêtre peut se réduire à nouveau en miniature en environ 5 secondes (test réel reproduit). Conséquence : La validation par capture d'écran a une fenêtre de temps – si l'avant-plan est volé pendant l'exécution de create_task, la tâche elle-même n'est pas affectée, mais si gui_screenshot est prise après le rétrécissement, la fenêtre cible ne sera pas dans l'image. Traitement : Avant de prendre une capture, si un changement d'avant-plan vient de se produire, faire d'abord open -a avant de capturer.
Le canal CGWindowList n'est pas affecté : optionOnScreenOnly et la liste complète peuvent tous deux énumérer les fenêtres (seuls les titres nécessitent l'autorisation d'enregistrement d'écran) – mais attention : la liste onScreenOnly contient les miniatures, pas la fenêtre principale. Les outils qui utilisent les coordonnées des fenêtres pour cliquer risquent de cliquer au mauvais endroit (sur la miniature au lieu du vrai bouton).
L'arbre AX lit les coordonnées logiques et est insensible au déplacement des miniatures, mais a une zone d'ombre (testé sur 27.0.1 après autorisation) : Les frames des fenêtres retournées par AX sont en coordonnées logiques pleine taille (ex : (405,517,230×408)), alors qu'au même moment, l'état de rendu CGWindowList est une miniature de 39×100 pt – le déplacement géométrique de Stage Manager ne trompe pas AX. Mais zone d'ombre : Pour une fenêtre nouvellement lancée qui n'est jamais montée sur la scène, AX indique windows=0 ; après être montée sur la scène puis mise en arrière-plan, AX continue de la voir. Conséquence : La perception AX n'est pas non plus inconditionnellement immunisée ; les applications lancées pour la première fois doivent d'abord être activées sur la scène. De plus, envoyer des événements de souris synthétiques basés sur les coordonnées logiques AX cliquera sur la mauvaise application (position logique ≠ position de rendu actuelle) – les outils AX doivent utiliser l'API d'actions d'accessibilité comme AXPress (ex : axctl), et non des clics par coordonnées.

Ordre de diagnostic (lorsque l'application cible n'est pas dans la liste des fenêtres) :

Vérifier d'abord si le processus est en vie (pgrep) : en vie → très probablement un problème de visibilité, pas une défaillance de l'application.
Confirmer si l'utilisateur a activé Stage Manager (macOS 15+, defaults read com.apple.WindowManager GloballyEnabled, 1 = activé) : activé → passer à l'étape 3 ; désactivé → peut-être que la fenêtre n'existe plus ou une autre raison.
Activer l'application pour rendre la fenêtre visible : open -a <nom_app> (cela volera brièvement le focus ; en informer l'utilisateur au préalable). Sur 27, la première activation peut ne pas coller ; vérifier immédiatement après activation, et si la fenêtre n'est pas matérialisée, réactiver (limite : 2 fois).
Rappeler gui_list_windows ; normalement, le window_id sera obtenu.

Signal supplémentaire : Lorsque Stage Manager est activé, open_app ne retourne généralement pas de window_id (il retourne un hint demandant une deuxième énumération). Lorsqu'il est désactivé, open_app retourne normalement le window_id.

Conséquences importantes :

Une erreur « aucune fenêtre visible » ne signifie pas que la fenêtre n'existe pas, et encore moins que l'opération précédente a échoué. Une tâche précédente « échouée » a peut-être en réalité réussi (la fenêtre a été créée, mais elle est simplement invisible).
Les fenêtres de type dialogue (comme la boîte de dialogue « Ouvrir » un fichier) deviennent invalides après avoir été fermées par la tâche elle-même ; les captures d'écran ultérieures échoueront – c'est normal ; il suffit de ré-énumérer pour obtenir un nouvel ID.
Certaines applications (comme TextEdit) n'ont pas de fenêtre lors d'un lancement sans document – c'est normal ; il faut lancer avec un fichier.

Description de tâche en trois parties (clé du succès)

Le paramètre task doit contenir trois parties :

Objectif : décrire étape par étape ce qui doit être accompli.
Limites : préciser clairement ce qu'il ne faut pas toucher, par exemple : « Ne cliquez sur aucun élément de la liste de l'historique ».
Gestion des échecs : si une opération ne répond pas, enregistrer précisément ce qui s'est passé et passer à l'étape suivante ; ne pas réessayer ni changer de méthode.

La règle de gestion des échecs ne doit pas être omise – sans elle, un échec unique déclenchera des tentatives répétées, épuisant le quota d'étapes de l'ensemble du cycle.

La description ne doit pas contenir de coordonnées de pixels ou de positions numériques ; utiliser le texte visible de l'interface et les noms des contrôles pour désigner les cibles.

Exemple

Demande de l'utilisateur : « Aide-moi à ouvrir l'application XX et à changer le format d'exportation en CSV »

Objectif : 1. Trouver et cliquer sur l'entrée « Paramètres » ou « Preferences » dans la barre de menus ou la barre d'outils.
2. Dans le panneau des paramètres, trouver l'option « Format d'exportation » ou « Export Format ».
3. Changer sa valeur en CSV.
4. Enregistrer les paramètres et fermer le panneau.
Limites : Ne modifier aucun autre paramètre ; ne pas cliquer sur le bouton « Réinitialiser ».
Gestion des échecs : Si le contrôle ci-dessus est introuvable, enregistrer le nom réel du contrôle vu et terminer la tâche ; ne pas cliquer par supposition.

Couche de secours AX (`axctl`)

Lorsque le computer use intégré n'est pas disponible (non activé, outils gui_* manquants, tâche trop petite pour justifier une distribution), ou qu'une opération sémantique au niveau des éléments est nécessaire, utiliser l'outil de secours AX intégré à cette skill : tools/axctl. Implémenté purement via l'API Accessibility, ne touche pas la souris, ne vole pas le focus, n'est pas limité par le bac à sable AppleEvents (le bac à sable de WorkBuddy interdit l'envoi d'événements de contrôle aux System Events ; la route osascript est dépréciée et ne doit plus être tentée).

Emplacement et installation : Le binaire tools/axctl, le code source tools/axctl.swift (fichier Swift unique), tous deux distribués avec la skill. Avant la première utilisation, exécuter sh tools/install.sh : si swiftc est détecté, il compile à la volée (recommandé – code source auditable, adapté à l'architecture de la machine) ; sinon, il utilise le binaire pré-compilé inclus (Apple Silicon uniquement). Pour recompiler après avoir modifié le code source, exécuter swiftc -O -o axctl axctl.swift dans le répertoire tools.

Précondition : L'hôte doit avoir l'autorisation TCC « Accessibilité » (dans Réglages système → Confidentialité et sécurité → Accessibilité, cocher l'hôte, puis redémarrer l'hôte pour que l'effet soit pris en compte). L'indicateur de disponibilité est un retour AXError=0 lors d'un appel AX.

Sous-commandes

axctl list <bundle-id|pid>        Lister les fenêtres : titre + frame géométrique logique
axctl tree <cible> [profondeur]    Lire l'arbre UI : rôle/titre/description/valeur/frame (profondeur par défaut : 2)
axctl actions <cible> <titre>     Lister les actions disponibles pour un élément correspondant
axctl press <cible> <titre>       Appuyer sur AXPress (clic sémantique, au niveau élément, sans coordonnées)
axctl activate <cible>            Activer l'application (NSRunningApplication.activate)

<cible> prend en charge le bundle id (recommandé, ex : com.apple.calculator), un PID numérique, ou le nom localisé de l'application (correspondance en minuscules – sur un système chinois, ce sera « 计算器 » et non « Calculator » ; la correspondance par nom est sujette aux erreurs, privilégier le bundle id).

Règles d'utilisation

Recherche d'éléments : D'abord tree, ou bien actions avec le titre d'un bouton connu pour confirmer la présence de AXPress, puis press. press ne fonctionne que sur les éléments qui ont une action AXPress. Les éléments de menu utilisent AXPick, à évaluer au cas par cas.
Vérification de l'action : Après que press a retourné PRESSED, utiliser tree pour lire la nouvelle valeur de l'élément cible ou de la zone d'affichage associée comme preuve (référence : test concret avec la Calculatrice : après avoir pressé « 3 », la valeur de StaticText est devenue 3) – même principe que la validation par capture d'écran avec computer use : l'auto-déclaration textuelle ne compte pas.
Scénario Stage Manager : L'arbre AX lit les coordonnées logiques ; les fenêtres en miniature peuvent être lues et manipulées (testé en pratique). Mais : les fenêtres nouvellement lancées qui ne sont jamais montées sur la scène ont un arbre AX vide – il faut d'abord faire axctl activate ou open -a pour les monter sur la scène avant d'interagir.
Limites d'application : axctl est adapté aux opérations au niveau des éléments (boutons, menus, champs de texte) ; pour les clics dans la barre de menus inter-applications, la simulation de souris/clavier au niveau système, ou les flux GUI complexes en plusieurs étapes, il faut recourir à la distribution via le computer use intégré.
Limites connues : Pas de surveillance des changements d'interface (capacité observe_changes d'axmcp, à réévaluer après adaptation à Swift 6.4 en amont) ; opérations élément par élément, pas de transaction par lot.

Résultats de test réels (macOS 27.0.1, Stage Manager activé)

axctl press com.apple.calculator "3" → PRESSED path=w/0/0/0/1/0/15 → tree a lu une valeur AXStaticText de 3 – les quatre étapes (lecture de l'arbre, localisation, clic sémantique, validation de l'effet) ont toutes fonctionné.

Validation des résultats

Le texte auto-rapporté par un agent GUI ne suffit pas comme preuve de réussite – un état d'interface résiduel peut être interprété à tort comme un succès. Il faut :

Une fois la tâche retournée done=true, appeler gui_screenshot(window_id) pour prendre une capture d'écran finale.
Utiliser le contenu de la capture pour juger si l'objectif est atteint.
Lors du rapport à l'utilisateur, préciser que la conclusion est basée sur la capture d'écran.

Ne pas prendre de capture d'écran par défaut entre chaque tour (la valeur de retour de continue_task contient déjà l'historique d'exécution). Ne prendre une capture supplémentaire que si reasoning/action_desc n'a pas changé pendant plusieurs tours consécutifs, pour vérifier si l'agent est bloqué.

Référence rapide de dépannage

Symptôme	Traitement
`permission_denied`	Voir `references/authorization-macos.md`
Plusieurs tours consécutifs bloqués sur la même étape	`continue_task` avec paramètre `hint` pour donner le texte visible exact du contrôle
Aucun changement d'interface mais signalement de réussite	Utiliser `gui_screenshot` ; vérifier que le `window_id` est correct
`conflict`	Une tâche existe déjà sur cette fenêtre ; d'abord `delete_task`
`window_not_found`	La fenêtre a été fermée ou l'ID a expiré ; refaire `gui_list_windows`
« Aucune fenêtre visible » (processus en vie)	Activation de Stage Manager rend la fenêtre non capturable : `open -a` (activation) → énumérer immédiatement ; si non matérialisée, réactiver une fois (sur 27, la première activation peut ne pas coller, limite : 2 fois). Voir « Piège des fenêtres invisibles » (confirmé expérimentalement sur 15 et 27.0.1)
La capture d'écran montre une fenêtre anormalement petite / collée au bord de l'écran	La fenêtre cible est en miniature Stage Manager (découverte sur 27) : d'abord `open -a` pour activer et restaurer sa taille réelle, puis capturer. Voir les points 1 et 3 du sous-chapitre « Re-vérification sur 27 » de la section « Piège des fenêtres invisibles »
Statut `call_user`	Intervention humaine nécessaire ; transmettre le `reasoning` à l'utilisateur, ne pas appeler `continue_task`

Support de plateforme

macOS : Support complet. Le processus d'autorisation est détaillé dans references/authorization-macos.md.
Windows : Non vérifié pour l'instant ; la version actuelle ne garantit pas le support. En environnement Windows, informer honnêtement l'utilisateur de cette limitation, ne pas essayer d'appliquer le modèle d'autorisation de macOS.

Ressources

references/authorization-macos.md – Processus complet d'autorisation macOS, avec les pièges réels rencontrés (non-prise en compte après coche, boîte de dialogue Quit & Reopen, etc.).
tools/axctl – Outil de secours AX (code source tools/axctl.swift dans le même répertoire ; avant la première utilisation, exécuter sh tools/install.sh). Utilisation décrite dans le chapitre « Couche de secours AX ».

GreenWich-art/agent-skills

Qu'est-ce que agent-skills ?

Demander à votre IA préférée

Documentation