Desktop-Übernahme (Desktop Takeover)

Übersicht

Vereinheitlicht den gesamten Ablauf, wenn ein Agent den Desktop übernehmen muss, um GUI-Operationen durchzuführen: Zuerst Routing zur optimalen Route, dann Sicherstellung der Computer-Use-Berechtigungen, schließlich Aufgabenverteilung und Verifikation. Computer Use ist die letzte, nicht die erste Wahl – nur wenn die Aufgabe zwingend über die GUI erledigt werden muss.

Entscheidungsbaum für den Workflow

Bei einer Desktop-Operationsanfrage wird die Route in der folgenden Reihenfolge geprüft, Stopp bei erstem Treffer:

1. Konnektor/MCP direkt verfügbar?
   Die Zielanwendung hat einen verbundenen Konnektor (GitHub, WPS-Wissensdatenbank, WeCom etc.)
   → Konnektor verwenden, GUI nicht anfassen
   Beispiel: GitHub PR prüfen → gh-Konnektor; WPS-Dokument lesen → wps-knowledgebase

2. Reine Browser-Operation?
   Aufgabe geschieht in einer Webseite (Formular ausfüllen, Web-Klick, Screenshot-Vergleich)
   → `browser-use`-Skill verwenden, System-GUI nicht berühren
   Beispiel: Auf einer Website einloggen und Einstellungen ändern → browser-use

3. Office/WPS-Datei-Lesen/Schreiben?
   Ziel sind doc/docx/xls/xlsx/ppt/pptx-Dateiinhalte
   → Office-Skill-Familie (workbuddy-docx / sheetagent / local-office-edit)
   Beispiel: Tabelle in Word ändern → local-office-edit

4. Über Kommandozeile/Script erreichbar?
   Aufgabe ist im Kern Dateioperation, Datenverarbeitung oder Systemkonfiguration mit CLI/Script-Pfad
   → Direkt Bash/Script verwenden
   Beispiel: Stapelumbenennung → Script; Systeminfo abfragen → Befehl

5. Keins der obigen → Computer Use Desktop-Übernahme
   Die Aufgabe muss UI-Elemente einer GUI-Anwendung bedienen (Schaltflächen, Menüs, Nicht-Web-Fenster)
   Beispiel: Eine Einstellung in einer proprietären Software ändern, die nur einen GUI-Zugang hat

Entscheidungsprinzip: Mit jeder Stufe sinken Zuverlässigkeit und Geschwindigkeit, die Unsicherheit steigt. GUI-Operationen beinhalten Elementpositionierung, Fensterfokus, Sprachbarrieren – sie sind das letzte Mittel.

Hinweis: Die Sichtbarkeit der Stufe 5 (Fensteraufzählung + Screenshot) ist bei aktiviertem Stage Manager eine strukturelle Schwäche (siehe Pre-Flight Punkt 2 und „Unsichtbares-Fenster-Falle“). AX-Werkzeuge (Barrierefreiheitsbaum) lesen logische Geometrien, die nicht durch Stage-Minimierung getäuscht werden – sie sind Ersatz-/Ergänzungspfade – bestätigt durch erneute Prüfung unter 27.0.1 (siehe Erkenntnisse in der Fallen-Sektion). Dieser Skill enthält das AX-Rückfallwerkzeug: tools/axctl (Verwendung siehe Kapitel „AX-Rückfallebene“).

Wenn Sie unsicher sind, ob die Zielanwendung einen Konnektor hat, prüfen Sie zuerst list_installed_plugins – verlassen Sie sich nicht auf Ihr Gedächtnis.

Pre-Flight: Berechtigungs- und Umgebungs-Doppelprüfung

Vor der Computer-Use-Nutzung müssen beide Prüfungen durchgeführt werden, keine darf übersprungen werden:

1. Berechtigungsprüfung

gui_permission_status aufrufen:

all_granted: true → zur zweiten Prüfung übergehen
Fehlende Berechtigung → Benutzer gemäß references/authorization-macos.md zur Autorisierung führen (macOS)
Windows → Aktuelle Version unterstützt nur macOS, Benutzer explizit informieren

2. Stage Manager-Prüfung (obligatorisch, da Benutzer ihn oft eingeschaltet lassen)

defaults read com.apple.WindowManager GloballyEnabled ausführen:

Liefert 1 (eingeschaltet) → Vor der Aufgabenverteilung muss open -a <App-Name> die Zielanwendung aktivieren, um sie in die aktuelle Bühne zu holen (kurzer Fokuswechsel; Benutzer vorher informieren). Dann gui_list_windows aufrufen, um zu bestätigen, dass das Zielfenster sichtbar ist – erst dann create_task. Wenn das Fenster nach der Aktivierung immer noch nicht in der Liste erscheint, direkt zur Sequenz „Unsichtbares-Fenster-Falle“ unten übergehen – nicht create_task wiederholen, nicht auf App-Fehler schließen
Liefert 0 (ausgeschaltet) → normaler Aufgabenverteilungsprozess

Diese Prüfung macht die Stage-Manager-Falle von einer „Nachsorge“ zu einem „vorbeugenden Umgehen“. Stage Manager ist unter macOS 15+ Benutzern nicht selten; bei eingeschaltetem Modus ist dieser Schritt der Standardpfad bei jeder Aufgabenverteilung, keine Ausnahme. Der Aktivierungs-Sichtbarmachungs-Mechanismus wurde am selben Tag unter macOS 27.0.1 erneut bestätigt, jedoch mit zwei neuen Details: „Erste Aktivierung haftet nicht“ und „Rückzug nach dem Sichtbarwerden“ – siehe Abschnitt „Unsichtbares-Fenster-Falle“.

Aufgabenverteilung

Nach Bereitschaft der Berechtigungen wird der Standard-Workflow des integrierten Computer-Use-Skills ausgeführt:

gui_list_windows – Zielfenster der Anwendung lokalisieren; bei keinem Treffer open_app zum Starten
Sichtbarkeit nach Start prüfen: Nach open_app muss erneut gui_list_windows ausgeführt werden, um zu bestätigen, dass das Fenster wirklich in der Liste erscheint. Wenn nicht, nicht vorschnell auf „App defekt“ schließen – zuerst den Abschnitt „Unsichtbares-Fenster-Falle“ prüfen
Bei aktiviertem Stage Manager (bereits in Pre-Flight bestätigt): Zuerst open -a zur Aktivierung, dann Aufgabe verteilen – siehe Pre-Flight Punkt 2, hier nicht wiederholen
create_task(window_id, task) – Aufgabe verteilen

Unsichtbares-Fenster-Falle (Stage Manager Szenario)

Gültigkeit der Schlussfolgerungen: Erstmalig durch kontrolliertes Experiment unter macOS 15 etabliert; unter macOS 27.0.1 erneut überprüft und bestätigt (Swift Dual-Channel-Sonde + AX API natives Binary, Mechanismus bestätigt; neue Details entdeckt, siehe unten). Die AX-Schicht-Schlussfolgerungen sind durch autorisierte Messung unter 27.0.1 bestätigt (AXError=0 Pfad), nicht mehr abhängig von Rückschlüssen.

Auslösebedingungen: Stage Manager aktiv; unabhängig vom Hintergrundstart. Wenn aktiviert, existieren Fenster von nicht in der aktuellen Bühne befindlichen Anwendungen real, können aber von Fensteraufzählung und Screenshot nicht normal erfasst werden – der Prozess lebt, das Fenster wurde erstellt (z. B. Cmd+N funktioniert), aber gui_list_windows zeigt keine normalen Fenster. Sobald die Anwendung aktiviert wird (Fenster zurück in die aktuelle Bühne), wird das Fenster sofort sichtbar.

Neue Erkenntnisse unter macOS 27.0.1:

Mechanismus der Miniaturleiste: Fenster von Anwendungen in der „Ablage“ werden zu seitlichen Miniaturfenstern verkleinert (im Test wurde das Hauptfenster des Taschenrechners auf 39×100pt an den linken Rand gesetzt, zusätzlich 4 vollbreite 34pt Bühnenplatzhalterfenster). Wenn gui_list_windows nach „normalen Größen“ filtert, können diese Miniaturen übersehen oder falsch interpretiert werden
Aktivierung & Sichtbarkeit gilt weiterhin, aber mit „erste Aktivierung haftet nicht“: Beim ersten open -a blieb das Hauptfenster in der Miniatur (weil der Vordergrund durch eine andere App belegt war), erst das zweite open -a erweiterte es auf Vollgröße (405, 517, 230×408). Maßnahme: Nach Aktivierung sofort gui_list_windows zur Verifikation aufrufen; bei fehlender Sichtbarkeit erneut open -a (max. 2 Mal); erst dann Fehlersuchsequenz starten
Sichtbarkeitsrückzug: Nach etwa 5 Sekunden, wenn der Vordergrund von einer anderen App zurückerobert wird, kann das Fenster wieder zur Miniatur schrumpfen (Reproduktion im Test). Schlussfolgerung: Screenshot-Verifikation hat ein Zeitfenster – wenn der Vordergrund während der Ausführung von create_task wechselt, bleibt die Aufgabe selbst unbeeinträchtigt, aber gui_screenshot zeigt nach dem Rückzug das Zielfenster nicht mehr im Bild. Maßnahme: Wenn kurz vor dem Screenshot ein Vordergrundwechsel stattfand, zuerst open -a und dann aufnehmen
CGWindowList-Pfad bleibt unbeeinflusst: optionOnScreenOnly und die vollständige Liste können Fenster aufzählen (nur Titel benötigt Bildschirmaufnahme-Berechtigung) – aber beachten: In der onScreenOnly-Liste erscheinen Miniaturen, nicht das Hauptfenster. Werkzeuge, die auf Fensterkoordinaten für Klick-Positionierung angewiesen sind, klicken an die falsche Stelle (auf die Miniatur, nicht auf den echten Button)
AX-Baum liest logische Geometrie, immun gegen Miniaturverschiebung, aber mit blinden Flecken (27.0.1 Messung nach Berechtigung): AX gibt den Window-Frame in voller logischer Größe zurück (z. B. (405,517,230×408)), während zur gleichen Zeit der CGWindowList-Render-Status ein 39×100 Miniaturfenster zeigt – die geometrische Verschiebung durch Stage Manager täuscht AX nicht. Aber blinder Fleck: Fenster, die neu gestartet und noch nie auf der Bühne waren, meldet AX Tree als windows=0; nachdem sie einmal auf der Bühne waren und dann im Hintergrund neu gestartet werden, bleibt AX sichtbar. Schlussfolgerung: Die AX-Wahrnehmung ist nicht bedingungslos immun; Apps, die zum ersten Mal gestartet werden, müssen zuerst auf die Bühne aktiviert werden. Außerdem: Durch Senden von synthetischen Mausereignissen basierend auf AX-logischen Koordinaten an den Bildschirm wird die falsche Anwendung getroffen (logische Position ≠ aktuelle Render-Position) – AX-Werkzeuge müssen Aktionen über die AX-Barrierefreiheits-API (z. B. AXPress, wie axctl) und nicht über Koordinaten-Klicks ausführen

Prüfreihenfolge (wenn das Zielfenster nicht in der Fensterliste erscheint):

Prüfen, ob der Prozess noch lebt (pgrep): Lebt → wahrscheinlich ein Sichtbarkeitsproblem, kein App-Fehler
Prüfen, ob der Benutzer Stage Manager aktiviert hat (macOS 15+, defaults read com.apple.WindowManager GloballyEnabled, 1=ein): Ein → Schritt 3; Aus → möglicherweise Fenster plötzlich verschwunden oder andere Ursache
Anwendung aktivieren, um es sichtbar zu machen: open -a <App-Name> (kurzer Fokuswechsel; Benutzer vorher informieren); Unter 27 kann die erste Aktivierung nicht haften – sofort nach Aktivierung verifizieren, bei fehlender Sichtbarkeit erneut aktivieren (max. 2 Mal)
gui_list_windows erneut aufrufen – normalerweise erhält man nun die window_id

Zusätzliches Signal: Bei aktiviertem Stage Manager liefert open_app in der Regel keine window_id (es wird ein Hinweis zur erneuten Aufzählung zurückgegeben); bei deaktiviertem Modus wird normal eine window_id zurückgegeben.

Wichtige Schlussfolgerungen:

Die Meldung Keine sichtbaren Fenster bedeutet nicht, dass das Fenster nicht existiert, und erst recht nicht, dass die vorherige Operation fehlgeschlagen ist – eine zuvor als „fehlgeschlagen“ gemeldete Aufgabe könnte tatsächlich erfolgreich gewesen sein (das Fenster existiert, ist nur nicht sichtbar)
Dialogfenster (z. B. „Öffnen“-Dateidialog) werden, nachdem sie von der Aufgabe selbst geschlossen wurden, ungültig – nachfolgende Screenshots schlagen dann fehl. Dies ist normales Verhalten; einfache Neuaufzählung ergibt eine neue ID
Manche Anwendungen (z. B. TextEdit) haben ohne geöffnetes Dokument standardmäßig überhaupt kein Fenster – dies ist normales Verhalten; die Datei muss mitgeöffnet werden

Drei-Teile-Aufgabenbeschreibung (erfolgsentscheidend)

Der task-Parameter muss drei Teile enthalten:

Ziel: Schrittweise beschreiben, was erreicht werden soll
Grenzen: Klar definieren, was nicht berührt werden darf, z. B. „Kein Eintrag in der Verlaufsliste anklicken“
Fehlerbehandlung: Wenn eine Operation keine Reaktion zeigt, genau dokumentieren, was passiert ist, und zum nächsten Schritt übergehen – nicht wiederholen oder Methode wechseln

Fehlerbehandlungsregel darf nicht fehlen – sonst führt ein einzelner Fehler zu endlosen Wiederholungen, die das gesamte Schrittkontingent aufbrauchen.

Die Beschreibung sollte keine Pixelkoordinaten oder Zahlenpositionen enthalten – verwenden Sie sichtbare Texte und Steuerelementnamen, um Ziele zu identifizieren.

Beispiel

Benutzeranfrage: „Bitte öffnen Sie die App XX und ändern Sie das Exportformat auf CSV“

Ziel: 1. Finden und klicken Sie den Eintrag „Einstellungen“ oder „Preferences“ in der Menüleiste oder Symbolleiste
2. Finden Sie im Einstellungsfenster die Option „Exportformat“ oder „Export Format“
3. Ändern Sie den Wert auf CSV
4. Speichern Sie die Einstellungen und schließen Sie das Fenster
Grenzen: Keine anderen Einstellungen ändern; nicht auf die „Zurücksetzen“-Schaltfläche klicken
Fehlerbehandlung: Wenn die genannten Steuerelemente nicht gefunden werden, notieren Sie die tatsächlich gesehenen Steuerelementnamen und beenden Sie die Aufgabe – nicht ratend klicken

AX-Rückfallebene (axctl)

Wenn das integrierte Computer Use nicht verfügbar ist (nicht aktiviert, gui_*-Werkzeuge fehlen, Aufgabe zu klein für eine eigene Verteiler-Aufgabe), oder wenn semantische Element-Operationen erforderlich sind, verwenden Sie das in diesem Skill integrierte AX-Rückfallwerkzeug tools/axctl. Reine Accessibility-API-Implementierung, berührt keine Maus, raubt keinen Fokus, ist nicht durch AppleEvents-Sandbox eingeschränkt (WorkBuddy-Sandbox verbietet das Senden von Steuerungsereignissen an System Events; der osascript-Pfad ist veraltet und sollte nicht mehr verwendet werden).

Ort und Installation: Binär tools/axctl, Quellcode tools/axctl.swift (Swift-Einzelfeld), beide werden mit dem Skill verteilt. Vor der ersten Verwendung sh tools/install.sh ausführen: Wenn swiftc erkannt wird, wird der Quellcode lokal kompiliert (empfohlen – Code ist prüfbar, an die lokale Architektur angepasst), sonst wird die mitgelieferte vorkompilierte Binärdatei verwendet (nur Apple Silicon). Nach Änderungen am Quellcode im tools-Verzeichnis swiftc -O -o axctl axctl.swift ausführen, um neu zu kompilieren.

Voraussetzung: Der Host muss über die TCC-Berechtigung „Bedienungshilfen“ verfügen (in den Systemeinstellungen → Datenschutz & Sicherheit → Bedienungshilfen den Host aktivieren und dann Host neu starten; als Bereitschaftsindikator gilt, dass ein AX-Aufruf AXError=0 zurückgibt).

Unterbefehle

axctl list <bundle-id|pid>        Fenster auflisten: Titel + logischer Geometrie-Frame
axctl tree <target> [depth]       UI-Baum lesen: Rolle/Titel/Beschreibung/Wert/Frame (Standard Tiefe=2)
axctl actions <target> <title>    Verfügbare Aktionen eines passenden Elements auflisten
axctl press <target> <title>      AXPress ausführen (semantischer Klick, Elementebene, keine Koordinaten)
axctl activate <target>           Anwendung aktivieren (NSRunningApplication.activate)

<target> unterstützt Bundle-ID (empfohlen, z. B. com.apple.calculator), numerische PID oder lokalisierte App-Namen (Kleinschreibung-Matching – in deutschen Systemen ist es „Taschenrechner“ nicht „Calculator“; Namensmatching ist fehleranfällig, Bundle-ID bevorzugen).

Verwendungsregeln

Elementsuche: Zuerst tree oder nach bekanntem Button-Titel direkt actions, um die Existenz von AXPress zu bestätigen, dann press. press funktioniert nur für Elemente mit der Aktion AXPress; Menüelemente haben AXPick – pro Elementtyp prüfen
Aktionsverifikation: Nachdem press PRESSED zurückgibt, mit tree den neuen Wert des Zielelements oder des zugehörigen Anzeigebereichs auslesen (wie beim Taschenrechner-Test: Nach press "3" zeigt der StaticText-Wert 3) – analog zur Screenshot-Verifikation bei Computer Use; bloße Textausgabe zählt nicht
Stage Manager Szenario: Der AX-Baum liest logische Geometrie – minimierte Fenster sind les- und bedienbar (im Test bestätigt); aber für neu gestartete, noch nie auf der Bühne gewesene Apps ist der AX-Baum leer – zuerst axctl activate oder open -a, um sie auf die Bühne zu bringen, dann bedienen
Anwendungsgrenzen: axctl eignet sich für Element-Lese-/Schreiboperationen (Buttons/Menüs/Textfelder); bei notwendigen app-übergreifenden Menüleisten-Klicks, systemweiten Maus-/Tastatursimulationen oder komplexen mehrstufigen GUI-Abläufen bleibt die integrierte Computer-Use-Verteilung der richtige Weg
Bekannte Einschränkungen: Kein UI-Änderungs-Listener (die observe_changes-Fähigkeit von axmcp wird nach der Anpassung des Upstreams an Swift 6.4 neu bewertet); Einzel-Element-Operationen, keine Batch-Transaktionen

Testergebnis (macOS 27.0.1, Stage Manager aktiv)

axctl press com.apple.calculator "3" → PRESSED path=w/0/0/0/1/0/15 → tree liest AXStaticText-Wert=3 – Lesen des Baums, Positionierung, semantischer Klick, Effektverifikation – alle vier Schritte funktionieren.

Ergebnisverifikation

Textausgaben des GUI-Agents reichen nicht als Erfolgsnachweis aus – ein zurückgebliebener alter UI-Zustand könnte fälschlich als Erfolg gewertet werden. Erforderlich:

Nachdem die Aufgabe done=true zurückgibt, gui_screenshot(window_id) aufrufen, um den endgültigen Screenshot zu nehmen
Anhand des Screenshot-Inhalts beurteilen, ob das Ziel erreicht wurde
Dem Benutzer bei der Berichterstattung die Grundlage der Schlussfolgerung mitteilen (Screenshot)

Zwischen den Runden sollte standardmäßig kein Screenshot gemacht werden (continue_task-Rückgabewert enthält bereits den Ausführungsverlauf); nur wenn reasoning/action_desc des Agents über mehrere Runden hinweg unverändert bleibt, wird ein zusätzlicher Screenshot aufgenommen, um zu prüfen, ob der Agent feststeckt.

Schnell-Fehlerbehebung

Symptom	Behandlung
`permission_denied`	Siehe references/authorization-macos.md
Mehrere Runden bleiben auf demselben Schritt hängen	`continue_task` mit `hint`-Parameter, der den genauen sichtbaren Text des Steuerelements angibt
Keine UI-Änderung, aber Erfolgsmeldung	Auf `gui_screenshot` angewiesen; window_id überprüfen
`conflict`	Dieses Fenster hat bereits eine Aufgabe; zuerst `delete_task` aufrufen
`window_not_found`	Fenster wurde geschlossen oder ID abgelaufen; `gui_list_windows` erneut aufrufen
`Keine sichtbaren Fenster` (Prozess lebt)	Stage Manager aktiviert, Fenster kann nicht erfasst werden: `open -a` zum Aktivieren → sofort neu aufzählen; bei fehlender Sichtbarkeit erneut aktivieren (erste Aktivierung unter 27 haftet möglicherweise nicht; max. 2 Mal), siehe „Unsichtbares-Fenster-Falle“ (experimentell bestätigt auf 15 und 27.0.1)
Der Screenshot zeigt ein ungewöhnlich kleines / am Bildschirmrand klebendes Fenster	Das Zielfenster befindet sich im Stage-Minimierungszustand (27-Erkenntnis): Zuerst `open -a` zum Aktivieren, um es auf Vollgröße zu bringen, dann fotografieren – siehe Erkenntnisse 1 und 3 im Abschnitt „Unsichtbares-Fenster-Falle“ unter 27
Status `call_user`	Menschliches Eingreifen erforderlich; `reasoning` an Benutzer weiterleiten, nicht `continue_task` aufrufen

Plattformunterstützung

macOS: Vollständig unterstützt. Autorisierungsprozess siehe references/authorization-macos.md
Windows: Derzeit nicht getestet; aktuelle Version garantiert keine Unterstützung. Bei Windows-Umgebungen den Benutzer über diese Einschränkung informieren – nicht versuchen, das macOS-Berechtigungsmodell anzuwenden

Ressourcen

references/authorization-macos.md – Vollständiger macOS-Autorisierungsprozess, einschließlich Fallstricke aus der Praxis (Aktivierung wirkt nicht, Quit & Reopen Dialog etc.)
tools/axctl – AX-Rückfallwerkzeug (Quellcode tools/axctl.swift im selben Verzeichnis; vor der ersten Verwendung sh tools/install.sh ausführen), Verwendung siehe Kapitel „AX-Rückfallebene“

GreenWich-art/agent-skills

Was ist agent-skills?

In Ihrer bevorzugten KI fragen

Dokumentation