DeskTopControl für Windows

Desktop-Steuerung für Windows

Übersicht

Nutzen Sie diese Fähigkeit, um sichtbare Windows-Benutzeroberflächen wie ein schneller Mensch zu bedienen: Screenshot machen, aus Pixeln schlussfolgern, das Zielfenster aktivieren und dann über die gebündelten Skripte Tastatur-/Mausaktionen ausführen. Der aktive Workflow ist ausschließlich lokale Python-Automatisierung.

Diese Fähigkeit hat zwei Rollen:

• Koordinator: Jeder Agent auf beliebiger Tiefe, der nicht bereits der UI-Worker ist, entscheidet, ob eine sichtbare UI-Steuerung erforderlich ist, delegiert eine begrenzte UI-Aufgabe an einen Worker, wenn Delegation verfügbar ist, und meldet eine Tool-/Richtliniensperre nur, wenn Delegation wirklich nicht möglich ist.
• UI-Worker: Der bereits delegierte Agent, der Screenshots macht, Pixel inspiziert und scripts/ui_control.py direkt ausführt.

Obligatorische Delegations-Gate: Entscheiden Sie für jede Live-Windows-UI-Steuerungsaufgabe zunächst anhand der erhaltenen Aufforderung, welche Rolle Sie haben. Wenn Sie nicht explizit als UI-Worker/Screen-Control-Worker für diese UI-Aufgabe gestartet wurden, sind Sie der Koordinator – selbst wenn Sie bereits ein Unteragent einer größeren Aufgabe sind. Machen Sie keine Screenshots, zeigen Sie keine Screenshots an, rufen Sie scripts/ui_control.py nicht auf und inspizieren Sie keine Live-Bildschirmbilder selbst. Delegieren Sie genau einen dedizierten UI-Worker. Wenn spawn_agent oder ein gleichwertiges Delegationstool verfügbar ist, ist die aktive Nutzung dieser Fähigkeit die Autorisierung zum Erstellen des Workers; fragen Sie den Benutzer nicht nach einem magischen Wort, Passwort oder einer zusätzlichen Bestätigung. Überspringen Sie die Delegation nur, wenn Sie bereits der UI-Worker sind oder wenn Sie diese Fähigkeit selbst debuggen/bearbeiten.

Keine rekursive UI-Worker-Delegation: Normale Aufgabenagenten können zwei oder drei Ebenen tief verschachtelt sein und dennoch einen dedizierten UI-Worker für ihre eigene sichtbare UI-Phase erstellen. Der Blatt-UI-Worker selbst darf keinen weiteren Agenten erstellen, delegieren, Nachrichten senden oder auf ihn warten. Führen Sie die UI-Arbeit lokal mit dem gebündelten Skript aus und geben Sie einen prägnanten Textbericht zurück.

Globaler UI-Lock: Alle Live-UI-Worker teilen sich eine Sperrdatei über scripts/ui_control.py. Ein UI-Worker muss den Lock zu Beginn seiner UI-Phase erwerben, das zurückgegebene --lock-token an jeden Screenshot-/Fenster-/Maus-/Tastatur-/Zwischenablage-Befehl übergeben und den Lock vor der Rückgabe freigeben. Wenn ein anderer Worker den Lock bereits hält, warten Sie darauf oder geben Sie partial mit den Details der Sperre zurück. Dies verhindert, dass parallele Agenten um Maus, Tastatur, Vordergrundfenster oder Zwischenablage kämpfen.

Gebietsschema-sensitive Texteingabe: Bevor Sie ein benanntes UI-Ziel wie den WeChat-Dateiübertragungs-Assistenten suchen, inspizieren Sie bei gehaltenem UI-Lock die App-Sprache/sichtbaren Beschriftungen. Wenn die UI Chinesisch ist, übergeben Sie die chinesische Beschriftung als ASCII-Unicode-Escapes an type ... --decode-unicode-escapes --method paste oder clipboard set ... --decode-unicode-escapes, z. B. \u6587\u4ef6\u4f20\u8f93\u52a9\u624b; geben Sie kein rohes Chinesisch über verschachtelte Aufforderungen, Shell-Argumente oder Befehlsdateien ein. Wenn die UI Englisch ist, verwenden Sie die englische Beschriftung oder einen ASCII-sicheren Alias wie filehelper. Wenn die Sprache nicht bestimmt werden kann, bevorzugen Sie Unicode-Escape-Eingabe über das Skript gegenüber rohem Nicht-ASCII-Text und überprüfen Sie das resultierende Ziel vor der Aktion.

Die Quelle wurde migriert von ClawHub breckengan/control v1.0.0 für lokale Desktop-Steuerungsmuster.

Migrationsumfang

Migrierte lokale Control-Fähigkeiten: absolute/relative Mausbewegung, flüssige Bewegung durch PyAutoGUI, Links-/Rechts-/Mittel-/Doppelklick, Maus gedrückt/losgelassen, langes Maushalten, Ziehen, vertikales/horizontales Scrollen, Mausposition, Texteingabe durch Tastaturanschläge oder Zwischenablage einfügen, Hotkeys, Taste gedrückt/losgelassen, Taste halten, Screenshots, Bereichsscreenshots, Pixelfarbe, Bildabgleich, Bildschirmgröße, Fensterliste/aktiv/aktivieren/Info/minimieren/maximieren/wiederherstellen/schließen, Zwischenablage setzen/holen, Failsafe, optionale Genehmigung, strenge Bereichsprüfungen, JSONL-Aktionsprotokollierung und Batch-Pläne.

Absichtlich nicht kopiert: die Upstream-Demo-Skripte und regelbasierten ai_agent.py-App-Demos. In Codex sollte die hochrangige Entscheidungsfindung in der aktiven Agentenschleife bleiben, wobei plan für deterministisches Batching verwendet wird.

Koordinator-Protokoll (Jeder Nicht-UI-Worker-Agent)

Für jede echte UI-Steuerungsaufgabe muss der Koordinator an einen einzigen UI-Worker delegieren, wenn die aktuelle Laufzeitrichtlinie Agentendelegation zulässt. Der Worker führt Screenshots, visuelle Inspektion und UI-Ausführung durch. Der Koordinator darf keine Screenshots machen, Screenshots anzeigen, scripts/ui_control.py ausführen oder Bildschirmbilder selbst inspizieren, es sei denn, er debuggt die Implementierung der Fähigkeit. Dadurch bleiben Bildschirmpixel, private Fensterinhalte und visuelle Schlussfolgerungen aus dem Hauptkonversationskontext fern.

Keine-Direktsteuerung-Ausweichregel: Wenn der Koordinator keinen UI-Worker erstellen oder ihm Nachrichten senden kann, weil die Laufzeitrichtlinie oder die Toolverfügbarkeit eine Delegation wirklich verhindert, muss er anhalten, bevor er die UI berührt, und diesen Blocker melden. Fragen Sie den Benutzer nicht nach einer rituellen Autorisierungsphrase; das schafft keine fehlenden Tools oder überschreibt die Laufzeitrichtlinie. Er darf nicht fortfahren, indem er lokale Screenshot-/Bildinspektions-/UI-Steuerungsarbeit in seinem eigenen Kontext durchführt.

Wenn Sie sich bereits in einem delegierten UI-Worker-Kontext befinden, überspringen Sie dieses Protokoll und folgen Sie dem UI-Worker-Protokoll unten. Rufen Sie nicht spawn_agent, send_input, wait_agent, close_agent, OpenSpace-Delegationstools oder gleichwertige verschachtelte Worker-Mechanismen auf.

Lesen Sie references/subagent-workflow.md, bevor Sie UI-Arbeit delegieren. Der Koordinator muss:

• Das Ziel intern klären und eine enge UI-Aufgabe für den Unteragenten definieren.
• Die genaue Ziel-App/das Fenster, das gewünschte Ergebnis, Sicherheitsgrenzen und ob irreversible Aktionen erlaubt sind, angeben.
• Im Worker-Prompt explizit angeben: „Du bist der UI-Worker. Erstelle oder delegiere keinen anderen Agenten.“
• Dem Unteragenten mitteilen, dass er den globalen UI-Lock erwerben muss, bevor er die UI berührt, --lock-token an jeden scripts/ui_control.py-Befehl übergeben muss und den Lock vor der Rückgabe freigeben muss.
• Dem Unteragenten mitteilen, dass er nur lokale scripts/ui_control.py verwenden darf; keine Remote-Visual-Modelle, Browsererweiterungen oder externen Dienste.
• Dem Unteragenten mitteilen, dass er die UI-Sprache inspizieren muss, bevor er Such-/Eingabetext auswählt; chinesische UI benötigt --decode-unicode-escapes, englische UI kann englische/ASCII-Aliase verwenden.
• Den Unteragenten bitten, einen prägnanten Textbericht mit verwendeten Befehlen, Endzustand, Screenshot-Dateipfaden und allen ungelösten Unsicherheiten zurückzugeben.
• Vermeiden Sie, rohe Screenshots in der endgültigen Antwort des Unteragenten anzufordern, es sei denn, der Benutzer benötigt sie speziell.

UI-Worker-Protokoll

Verwenden Sie diesen Abschnitt nur, wenn die Aufforderung explizit besagt, dass Sie der Bildschirm-Steuerungs-Worker, UI-Worker oder delegierte Worker für eine Windows-UI-Aufgabe sind, oder wenn Sie bereits in einem Agenten ausgeführt werden, der speziell für die Windows-UI-Steuerung erstellt wurde. Ein allgemeiner Unteragent einer größeren Aufgabe macht Sie nicht zum UI-Worker; in diesem Fall folgen Sie dem Koordinator-Protokoll, wenn eine Live-UI-Steuerung erforderlich ist.

Harte Regeln:

• Erstellen Sie keinen weiteren Agenten, delegieren Sie an keinen anderen Agenten und verwenden Sie kein OpenSpace, um einen verschachtelten Worker zu erstellen.
• Führen Sie das Koordinator-Protokoll nicht erneut aus.
• Verwenden Sie nur die scripts/ui_control.py dieser Fähigkeit und normale lokale Shell-Befehle, die zur Inspektion von Ausgaben erforderlich sind.
• Behalten Sie Screenshots in einem temporären Ordner wie $env:TEMP\codex-ui-subagent\.
• Inspizieren Sie Screenshots in Ihrem eigenen Kontext und geben Sie nur Text plus Screenshot-Pfade zurück.
• Wenn Sie die UI-Aufgabe nicht lokal abschließen können, melden Sie partial oder failed mit dem Blocker. Eskalieren Sie nicht, indem Sie einen anderen Agenten erstellen.

Worker-Schleife:

1. Erwerben Sie den globalen UI-Lock mit lock acquire --owner "<task label>" und behalten Sie das zurückgegebene Token privat in Ihrem Worker-Kontext.
2. Übergeben Sie --lock-token <token> an jeden nicht trockenen scripts/ui_control.py-Befehl bis zur Freigabe.
3. Führen Sie status --windows aus und machen Sie einen frischen Screenshot, während Sie den Lock halten.
4. Inspizieren Sie Screenshots lokal und wählen Sie die kleinste sichere Aktion.
5. Bevorzugen Sie Hotkeys und Einfügen aus der Zwischenablage gegenüber Mauskoordinaten, wenn sie zuverlässig sind.
6. Verwenden Sie --dry-run vor langen oder riskanten Plänen.
7. Führen Sie mit scripts/ui_control.py aus.
8. Überprüfen Sie mit einem weiteren Screenshot oder einem Nicht-Bild-Statusbefehl.
9. Geben Sie den Lock mit lock release --token <token> in der Bereinigung frei.
10. Geben Sie Ergebnis, zusammengefasste Aktionen, endgültigen beobachteten Zustand, Screenshot-Pfade und ungelöste Unsicherheit zurück.

Entscheidungsregeln

• Bevorzugen Sie normale APIs, CLI-Befehle, Browserautomatisierung oder anwendungsspezifische Tools, wenn sie existieren und zuverlässig sind.
• Für Live-Windows-UI-Steuerung wenden Sie die obligatorische Delegations-Gate an, bevor Sie Screenshots, Bildinspektionen oder scripts/ui_control.py-Aufrufe durchführen.
• Verwenden Sie scripts/ui_control.py für schnelle lokale Windows-Steuerung: Hotkeys, Texte einfügen/eintippen, Mausklick, Ziehen, Scrollen, Screenshots, Zwischenablage, Fensteraktivierung, Pixelprüfungen, Bildabgleich und Aktionspläne.
• Machen Sie einen Screenshot, bevor Sie handeln, es sei denn, die Zielkoordinaten/der Zustand sind bereits aus derselben Interaktionsschleife bekannt.
• Verwenden Sie Hotkeys und Einfügen aus der Zwischenablage vor der Mausnavigation, wenn es schneller und sicherer ist.
• Fassen Sie bekannte Aktionen mit plan zur Geschwindigkeit zusammen, aber halten Sie visuelle Entscheidungsschleifen schrittweise: Screenshot, inspizieren, handeln, überprüfen.
• Entscheiden Sie bei lokalisierten Apps wie WeChat, ob die sichtbare UI Chinesisch oder Englisch ist, bevor Sie suchen. Verwenden Sie --decode-unicode-escapes für chinesische Beschriftungen/Nachrichten in verschachtelten Worker-Kontexten; verlassen Sie sich niemals darauf, dass roher chinesischer Text Prompt-, CLI-, PowerShell- oder Log-Umleitungsebenen überlebt.

Lokale Steuerung

Dieser Abschnitt ist nur für UI-Worker und Skill-Debugging. Ein Koordinator darf diese Befehle nicht für eine Live-UI-Aufgabe ausführen; er muss zuerst an einen UI-Worker delegieren oder den Delegationsblocker melden, wenn Delegation nicht verfügbar ist.

Führen Sie vom Skill-Verzeichnis aus:

python scripts\ui_control.py lock acquire --owner "wechat-file-transfer"
python scripts\ui_control.py --lock-token <token> status --windows
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\screen.png"
python scripts\ui_control.py --lock-token <token> hotkey ctrl l
python scripts\ui_control.py --lock-token <token> type '\u6587\u4ef6\u4f20\u8f93\u52a9\u624b' --decode-unicode-escapes --method paste
python scripts\ui_control.py --lock-token <token> click --x 500 --y 300
python scripts\ui_control.py --lock-token <token> right-click --x 500 --y 300
python scripts\ui_control.py --lock-token <token> drag 100 100 700 450 --duration 0.5
python scripts\ui_control.py --lock-token <token> scroll -6 --x 900 --y 500
python scripts\ui_control.py --lock-token <token> hold-mouse --x 500 --y 300 --seconds 1.2
python scripts\ui_control.py lock release --token <token>

Alle Befehle geben JSON aus. Überprüfen Sie ok, error, Ausgabepfade, aktives Fenster und Koordinaten, bevor Sie fortfahren.

Lock-Verhalten: Befehle ohne --lock-token erwerben einen transienten Lock für diesen einzelnen Befehl. Ein Worker, der eine mehrschrittige sichtbare UI-Aufgabe ausführt, muss lock acquire verwenden und --lock-token über die gesamte Phase übergeben, damit andere Worker keine Aktionen zwischen seiner Screenshot-/Handeln-/Überprüfen-Schleife einfügen können. Globale Optionen wie --lock-token müssen vor dem Unterbefehl erscheinen, z. B. ui_control.py --lock-token <token> type ..., nicht danach. Verwenden Sie --lock-timeout <seconds> bei gewöhnlichen Befehlen, um zu steuern, wie lange auf einen anderen Worker gewartet werden soll; verwenden Sie lock status, um den aktuellen Inhaber zu überprüfen, ohne den Lock zu übernehmen. Abgelaufene Locks werden als veraltet behandelt und automatisch entfernt.

Unter Windows aktiviert scripts/ui_control.py die DPI-Awareness beim Start. Behandeln Sie Screenshots, Mauskoordinaten, Pixellesungen und Fensterrechtecke als dasselbe physikalische Pixel-Koordinatensystem. Wenn status eine Bildschirmgröße meldet, die nicht mit der aktiven Desktop-/Fenstergröße übereinstimmt, stoppen Sie und melden Sie die Abweichung, bevor Sie klicken.

Eine vollständige CLI-Syntax finden Sie in references/control-api.md.

Workflow

1. Globalen UI-Lock erwerben:

python scripts\ui_control.py lock acquire --owner "kurze Aufgabenbeschreibung"

Verwenden Sie das zurückgegebene Token als --lock-token <token> für jeden Befehl bis zur Freigabe.

2. Zustand inspizieren:

python scripts\ui_control.py --lock-token <token> status --windows
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\codex-ui.png"
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\codex-active.png" --active
python scripts\ui_control.py --lock-token <token> snapshot --out "$env:TEMP\codex-state.png" --windows --active

3. Das Zielfenster in den Vordergrund bringen:

python scripts\ui_control.py --lock-token <token> window activate "Notepad"

4. Die schnellste zuverlässige Grundaktion verwenden:

• Textfelder: type --method paste, mit --decode-unicode-escapes für chinesische Escape-Texte, dann press enter oder hotkey.
• Menüs und Tastenkombinationen: hotkey, press, key-hold.
• Schaltflächen und Leinwände: click, double-click, right-click, drag, scroll, hold-mouse.
• Bekannte App-/Fensterziele: Vor Vollbildaufnahme/-suche snapshot --active, screenshot --active, screenshot --window "<title>", find-image --active oder find-image --window "<title>" verwenden. snapshot --windows verwenden, wenn der Worker Fenstermetadaten und einen Screenshot im selben Schritt benötigt. Fensterziele werden auf den sichtbaren primären Bildschirm begrenzt, wenn Windows unsichtbare Randversätze meldet.
• Wiederholte deterministische Sequenzen: Eine JSON-Aktionsdatei schreiben und mit plan --file ausführen.
• Unbekanntes sichtbares Ziel: Der UI-Worker muss Screenshot machen und inspizieren, dann Koordinaten oder Bildabgleich verwenden.

5. Mit einem weiteren Screenshot oder Statusaufruf überprüfen.

Unter PowerShell bevorzugen Sie plan --file gegenüber plan --json für generiertes JSON. Komplexes JSON, das als natives Befehlsargument übergeben wird, kann von PowerShell vor dem Empfang durch Python neu zitiert werden.

Plan-Aktionen dürfen nur aktionsspezifische Felder setzen. Legen Sie keine globalen/Steuerungsfelder wie dry-run, require-approval, no-failsafe, strict-bounds, pause-after, log-file, lock-token, lock-timeout, lock-ttl, lock-owner, plan-file, plan-json, func oder stdin innerhalb einzelner Plan-Aktionen ab; der Controller lehnt sie ab, sodass Unteraktionen die Lock- und Sicherheitseinstellungen des Workers nicht umgehen können. Für Planeingabe von Text verwenden Sie einen text-Wert oder file. Von Plänen bereitgestellte Auswahlmöglichkeiten und boolesche Werte werden wie direkte CLI-Argumente validiert.

6. ...

[Text abgeschnitten für Übersetzung]