agent-desktop

Was macht agent-desktop?

agent-desktop ist ein CLI, mit dem ein KI-Agent Desktop-Apps durch den OS-Barrierefreiheitsbaum beobachten und bedienen kann. Es ist ein Werkzeug, kein Agent. Jeder Befehl gibt einen JSON-Envelope aus (ok, data oder error). Der Beobachten-Handeln-Überprüfen-Zyklus liegt bei Ihnen.

Shell-Syntax

Die Beispiele verwenden eine POSIX-Shell. Verwenden Sie in PowerShell jede Referenz in Anführungszeichen ('@s8f3k2p9:e1'), da ein nacktes @token der Splatting-Operator ist. Verwenden Sie $env:NAME = 'value' statt export und | ConvertFrom-Json statt $(...) und jq. Die Windows-Skill-Datei enthält die PowerShell-Formen.

Vorbereitung

Führen Sie dies vor dem ersten Befehl einer Aufgabe aus. Nur hier wird das Tool installiert.

1. Führen Sie agent-desktop version aus. Exit-Code 0 bedeutet, dass das CLI vorhanden ist: Fahren Sie mit Schritt 4 fort.

2. Falls es fehlt, installieren Sie es mit npm. npm ist der einzige unterstützte Pfad:

   npm install -g agent-desktop

   Versuchen Sie nicht Homebrew, Scoop, ein heruntergeladenes Archiv oder eine ältere Version. Diese Skill-Datei ist für die Version geschrieben, die npm auflöst. Wenn npm nicht im PATH ist, führen Sie node -v und where npm (Windows) oder which npm (macOS, Linux) aus und melden Sie, was Sie gefunden haben. Raten Sie nicht bei einem anderen Paketmanager.

3. Führen Sie erneut agent-desktop version aus. Wenn es immer noch fehlschlägt, stoppen Sie und teilen Sie dem Benutzer Folgendes mit: die letzten 20 Zeilen der Installationsausgabe, ob agent-desktop --help überhaupt läuft, und Ihr Betriebssystem. Fallen Sie nicht von sich aus auf Screenshots oder Mausautomatisierung zurück.

4. Führen Sie agent-desktop status aus. Es meldet die Plattform, Berechtigungen und supported_surfaces. Unter macOS wird hier eine fehlende Barrierefreiheitsberechtigung angezeigt; weisen Sie den Benutzer an, agent-desktop permissions --guide auszuführen, anstatt zu versuchen, sie selbst zu erteilen.

5. Führen Sie agent-desktop skills get platform aus. Es lädt die Skill-Datei für das Betriebssystem, auf dem die Binärdatei läuft (macOS, Windows oder Linux), und sie hat Vorrang, wenn sie von dieser Datei abweicht.

6. Für Flags und Syntax führen Sie agent-desktop <command> --help aus. Diese Skill-Datei wiederholt nie Flag-Listen, daher stimmt --help immer mit der installierten Version überein.

Wenn agent-desktop skills get desktop Regeln ausgibt, die von dieser Datei abweichen, hat die Binärdatei recht: Diese Datei ist eine Kopie, die Binärdatei ist das, was Sie tatsächlich steuern.

Der Zyklus

Verwenden Sie find, wenn Sie die Rolle oder den genauen Namen kennen. Karten Sie andernfalls zuerst die App ab und bohren Sie sich in eine Region.

agent-desktop snapshot --skeleton --app "Notes" -i --compact   # flache Karte, children_count an abgeschnittenen Ästen
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # in eine Region bohren
agent-desktop click @s8f3k2p9:e12                              # auf eine qualifizierte Referenz einwirken
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # überprüfen: dieselbe Region erneut lesen

• Eine kleine App benötigt kein Skelett. Machen Sie einen vollständigen snapshot -i.
• -i behält nur interaktive Knoten, daher wird die statische Textbeschriftung einer Zeile weggelassen. Um herauszufinden, zu welcher Zeile eine wiederholte Schaltfläche gehört, bohren Sie mit --root in den Container dieser Zeile und lassen Sie -i weg. Unter Windows und Linux liest das die Zeile, macht ihre Schaltfläche aber nicht ausführbar: Eine in anderen Zeilen wiederholte Schaltfläche ist ein Zwilling im Fenster, und ihre Referenz wird abgelehnt (siehe Referenzen).
• Ein --root-Bohren fügt seine Referenzen zur selben Snapshot-ID hinzu. Referenzen außerhalb des gebohrten Teilbaums und die gebohrte Wurzel selbst bleiben gültig; Referenzen, die bereits darin waren, werden ersetzt, sodass eine alte Referenz dort STALE_REF zurückgibt.
• Verknoten Sie niemals eine Oberfläche (--surface menu, sheet, alert). Eine Oberfläche ist bereits fokussiert.
• Eine Aktion, die ein Menü, Sheet oder Alert öffnet, listet es in data.surfaces auf. Zielen Sie als nächstes auf diesen Overlay.
• Verwenden Sie nach einem asynchronen Schritt wait (siehe references/commands-system.md). Ein festes Sleep ist ein Wettlauf.

Referenzen

• Ausgabereferenzen sind qualifiziert: @<snapshot_id>:e<N>, zum Beispiel @s8f3k2p9:e1. Übergeben Sie sie unverändert an spätere Befehle.
• Referenzen sind für einen Snapshot gültig. Nach jeder UI-Änderung bohren Sie den betroffenen Bereich erneut an oder machen einen neuen Snapshot.
• Nur adressierbare Elemente erhalten Referenzen. Statischer Text und inaktive Container nicht.
• Ein Befehl identifiziert das Element neu, bevor er handelt. Unter macOS trägt die Referenz die eigene Adresse des Elements, sodass identische Zwillinge jeweils ihre Referenz behalten. Unter Windows und Linux löst eine Referenz nur auf, wenn sie das einzige Element im Fenster war, das sein Snapshot mit seiner Rolle, nativen ID, Name und Beschreibung erfasst hat, gezählt auch unter einem Skelett- oder Tiefenschnitt, und genau ein Live-Element noch übereinstimmt. Identische Zwillinge haben dort keinen Referenzpfad: Nur --headed mouse-click --xy X,Y kann eines auswählen, es nimmt den Vordergrund, und eine Linux-Wayland-Sitzung lehnt es ab.
• STALE_REF: Das Element ist verschwunden oder stimmt nicht mehr überein. details.kind ist saved_ref_absent oder unter macOS retained_object_stale. Machen Sie einen neuen Snapshot und verwenden Sie die neue Referenz.
• AMBIGUOUS_TARGET: Ein identisches Element ist aufgetaucht (saved_ref_ambiguous), oder die Referenz wurde bei der Erfassung nicht als eindeutig nachgewiesen (identity_not_unique). Das Wiederholen der Referenz oder ein erneuter Snapshot identischer Zwillinge führt zur gleichen Ablehnung; handeln Sie auf einem Steuerelement, das im Fenster eindeutig ist. identity_not_unique folgt auch auf einen Snapshot, der das gesamte Fenster nicht rechtzeitig lesen konnte: Wiederholen Sie ihn mit einem größeren --timeout-ms.
• TIMEOUT mit details.kind: resolution_identity_unknown: Eine Live-Lesung hat nicht geantwortet, daher ist die Identität nicht nachgewiesen. Es wurde nichts gesendet; versuchen Sie es erneut.
• SNAPSHOT_NOT_FOUND: Die Snapshot-ID ist abgelaufen. Machen Sie erneut einen Snapshot.

Zustellung und Wiederholung

Aktionsergebnisse enthalten data.disposition und Fehler enthalten error.disposition, jeweils mit delivery und retry. Beobachtungsbefehle wie snapshot haben bei Erfolg keine; ihre Fehler und jede INVALID_ARGS-Ablehnung enthalten not_delivered und retry: safe.

• Wiederholen oder ersetzen Sie eine Aktion nur, wenn disposition.retry safe ist. Nur not_delivered ist sicher.
• Jeder andere Zustellungswert bedeutet, dass die Aktion möglicherweise ausgeführt wurde. Eine Wiederholung kann zweimal klicken, tippen oder absenden, und toggle kann sich selbst rückgängig machen.
• Bei einem Ergebnis, das nicht sicher ist, lesen Sie den Live-Status (get, is oder ein neuer Snapshot) und entscheiden Sie daraus. details.post_state hilft, wenn vorhanden.
• Verzweigen Sie nach error.code und error.disposition. Nachricht und Vorschlagstext können sich ändern.
• details.retryable: false bedeutet, dass Warten das Ergebnis nicht ändern kann. Versuchen Sie einen anderen Ansatz.

Headless und Headed

Ref-Aktionen sind standardmäßig headless. Sie verwenden semantische Barrierefreiheitsaufrufe und nehmen keinen Fokus, bewegen den Cursor nicht, synthetisieren keine Tasten und verwenden nicht die Zwischenablage. Wenn kein semantischer Pfad existiert, schlägt die Aktion geschlossen fehl. Verwenden Sie das globale --headed-Flag nur, wenn der Benutzer explizit physische Eingaben erlaubt, wie Doppelklick, Hover, Ziehen oder Fokus. Wechseln Sie niemals in den Headed-Modus, um sich von einem Headless-Fehler zu erholen. Rohe Koordinaten (--xy) implizieren nie Fokus. Welche Aktionen --headed benötigen, unterscheidet sich je nach Betriebssystem: Lesen Sie die plattformspezifische Skill-Datei.

Referenzen

Laden Sie eine nur, wenn Sie sie benötigen: agent-desktop skills get desktop <reference>.

Referenz	Öffnen Sie sie, wenn ...
commands-observation	Sie Semantiken von snapshot, find, get, is, screenshot, list-surfaces, partielle Bäume oder die --root-Regeln benötigen
commands-interaction	Sie zwischen click, type, set-value, select, toggle, scroll, press und mouse-Befehlen wählen oder einen Aktionsfehler debuggen
commands-system	Sie Apps starten oder schließen, Fenster verwalten, die Zwischenablage verwenden, wait, batch, Sitzungen, Multi-Agent-Cursor, Tracing oder Skill-Dateien laden
workflows	Sie erprobte Muster (Formulare, Menüs, Dialoge, Warten auf ein neues Fenster, Scroll-Finden, Ziehen) und die Anti-Patterns-Liste wünschen