agent-desktop

Que fait agent-desktop ?

agent-desktop est un CLI qui permet à un agent IA d'observer et de manipuler des applications de bureau via l'arbre d'accessibilité du système d'exploitation. C'est un outil, pas un agent. Chaque commande imprime une enveloppe JSON (ok, data ou error). La boucle observer, agir et vérifier est à votre charge.

Syntaxe shell

Les exemples utilisent un shell POSIX. Dans PowerShell, mettez chaque référence entre guillemets ('@s8f3k2p9:e1'), car un @token nu est l'opérateur splatting. Utilisez $env:NOM = 'valeur' au lieu de export, et | ConvertFrom-Json au lieu de $(...) et jq. La compétence Windows contient les formes PowerShell.

Prévol

Exécutez ceci avant la première commande d'une tâche. C'est le seul endroit où l'outil est installé.

1. Lancez agent-desktop version. Le code de sortie 0 signifie que le CLI est présent : allez à l'étape 4.

2. S'il est manquant, installez-le avec npm. npm est le seul chemin supporté :

   npm install -g agent-desktop

   N'essayez pas Homebrew, Scoop, une archive téléchargée ou une version antérieure. Cette compétence est écrite pour la version que npm résout. Si npm n'est pas dans le PATH, exécutez node -v et where npm (Windows) ou which npm (macOS, Linux) et signalez ce que vous avez trouvé. Ne devinez pas un autre gestionnaire de paquets.

3. Relancez agent-desktop version. Si cela échoue encore, arrêtez-vous et dites à l'utilisateur : les 20 dernières lignes de la sortie d'installation, si agent-desktop --help fonctionne, et le système d'exploitation que vous utilisez. Ne recourez pas par vous-même aux captures d'écran ou à l'automatisation de la souris.

4. Exécutez agent-desktop status. Il indique la plateforme, les autorisations et supported_surfaces. Sur macOS, une autorisation d'accessibilité manquante apparaît ici ; dites à l'utilisateur d'exécuter agent-desktop permissions --guide au lieu d'essayer de l'accorder vous-même.

5. Exécutez agent-desktop skills get platform. Il charge la compétence pour le système d'exploitation sur lequel le binaire tourne (macOS, Windows ou Linux), et elle prévaut partout où elle est en désaccord avec ce fichier.

6. Pour les options et la syntaxe, exécutez agent-desktop <commande> --help. Cette compétence ne répète jamais les listes d'options, donc --help correspond toujours à la version installée.

Si agent-desktop skills get desktop affiche des règles différentes de ce fichier, le binaire a raison : ce fichier est une copie, le binaire est ce que vous pilotez réellement.

La boucle

Utilisez find lorsque vous connaissez le rôle ou le nom exact. Sinon, cartographiez d'abord l'application puis plongez dans une région.

agent-desktop snapshot --skeleton --app "Notes" -i --compact   # vue superficielle, children_count sur les branches coupées
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # plonger dans une région
agent-desktop click @s8f3k2p9:e12                              # agir sur une référence qualifiée
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # vérifier : relire la même région

• Une petite application n'a pas besoin de squelette. Prenez un snapshot -i complet.
• -i ne conserve que les nœuds interactifs, donc l'étiquette de texte statique d'une ligne est ignorée. Pour savoir à quelle ligne appartient un bouton répété, plongez dans le conteneur de cette ligne avec --root et omettez -i. Sous Windows et Linux, cela lit la ligne mais ne rend pas son bouton actionnable : un bouton répété dans d'autres lignes est un jumeau dans la fenêtre et sa référence est refusée (voir Références).
• Une plongée --root ajoute ses références au même identifiant d'instantané. Les références en dehors du sous-arbre exploré, ainsi que la racine explorée elle-même, restent valides ; les références qui étaient déjà à l'intérieur sont remplacées, donc une ancienne référence y renvoie STALE_REF.
• Ne faites jamais de squelette d'une surface (--surface menu, sheet, alert). Une surface est déjà ciblée.
• Une action qui ouvre un menu, une feuille ou une alerte les liste dans data.surfaces. Ciblez cette superposition ensuite.
• Après une étape asynchrone, utilisez wait (voir references/commands-system.md). Un sommeil fixe est une situation de compétition.

Références

• Les références en sortie sont qualifiées : @<snapshot_id>:e<N>, par exemple @s8f3k2p9:e1. Passez-les telles quelles aux commandes suivantes.
• Les références sont valables pour un seul instantané. Après tout changement d'interface, replongez dans la région affectée ou prenez un nouvel instantané.
• Seuls les éléments adressables reçoivent des références. Le texte statique et les conteneurs inertes n'en reçoivent pas.
• Une commande ré-identifie l'élément avant d'agir. Sur macOS, la référence porte l'adresse propre de l'élément, donc les jumeaux identiques conservent chacun leur référence. Sous Windows et Linux, une référence n'est résolue que lorsqu'elle était le seul élément de la fenêtre que son instantané a capturé avec son rôle, son identifiant natif, son nom et sa description, compté même en dessous d'un squelette ou d'une coupe en profondeur, et qu'exactement un élément vivant correspond encore. Les jumeaux identiques n'ont donc pas de chemin de référence : seul --headed mouse-click --xy X,Y peut en choisir un, il passe au premier plan, et une session Linux Wayland le refuse.
• STALE_REF : l'élément a disparu ou ne correspond plus. details.kind est saved_ref_absent, ou retained_object_stale sur macOS. Prenez un nouvel instantané et utilisez la nouvelle référence.
• AMBIGUOUS_TARGET : un élément identique est apparu (saved_ref_ambiguous), ou la référence n'a pas été prouvée unique lors de la capture (identity_not_unique). Répéter la référence ou re-photographier les jumeaux identiques donne le même refus ; agissez sur un contrôle unique dans la fenêtre. identity_not_unique suit également un instantané qui n'a pas pu lire toute la fenêtre à temps : reprenez-le avec un --timeout-ms plus grand.
• TIMEOUT avec details.kind: resolution_identity_unknown : une lecture en direct n'a pas répondu, donc l'identité n'est pas prouvée. Rien n'a été envoyé ; réessayez.
• SNAPSHOT_NOT_FOUND : l'identifiant de l'instantané a expiré. Prenez un nouvel instantané.

Délivrance et nouvelle tentative

Les résultats d'action contiennent data.disposition et les erreurs contiennent error.disposition, chacun avec delivery et retry. Les commandes d'observation telles que snapshot n'en ont pas en cas de succès ; leurs erreurs, ainsi que tout refus INVALID_ARGS, portent not_delivered et retry: safe.

• Ne réessayez ou ne substituez une action que lorsque disposition.retry est safe. Seul not_delivered est sûr.
• Toute autre valeur de délivrance signifie que l'action a peut-être été effectuée. Une répétition peut cliquer, taper ou soumettre deux fois, et toggle peut s'annuler.
• Sur un résultat qui n'est pas sûr, lisez l'état en direct (get, is, ou un nouvel instantané) et décidez en fonction. details.post_state aide lorsqu'il est présent.
• Ramiflez sur error.code et error.disposition. Le message et le texte de suggestion peuvent changer.
• details.retryable: false signifie qu'attendre ne peut pas changer le résultat. Essayez une approche différente.

Headless et avec tête

Les actions par référence sont headless par défaut. Elles utilisent des appels d'accessibilité sémantiques et ne prennent pas le focus, ne déplacent pas le curseur, ne synthétisent pas de touches et n'utilisent pas le presse-papiers. Si aucun chemin sémantique n'existe, l'action échoue fermement. Utilisez le drapeau global --headed uniquement lorsque l'utilisateur autorise explicitement une entrée physique, comme un double-clic, un survol, un glisser-déposer ou la prise de focus. Ne passez jamais en mode avec tête pour vous remettre d'un échec headless. Les coordonnées brutes (--xy) n'impliquent jamais le focus. Les actions qui nécessitent --headed diffèrent par système d'exploitation : lisez la compétence de la plateforme.

Références

Chargez-en une seulement lorsque vous en avez besoin : agent-desktop skills get desktop <reference>.

Référence	Ouvrez-la quand
commands-observation	Vous avez besoin de la sémantique de snapshot, find, get, is, screenshot, list-surfaces, des arbres partiels ou des règles --root
commands-interaction	Vous choisissez entre les commandes click, type, set-value, select, toggle, scroll, press et mouse, ou vous déboguez une erreur d'action
commands-system	Vous lancez ou fermez des applications, gérez les fenêtres, utilisez le presse-papiers, wait, batch, les sessions, les curseurs multi-agents, le traçage, ou chargez des compétences
workflows	Vous voulez des modèles éprouvés (formulaires, menus, boîtes de dialogue, attente d'une nouvelle fenêtre, scroll-recherche, glisser-déposer) et la liste des anti-patrons