AppKit Inspector

AppKit Inspector ist eine reine Debug-Brücke zum Inspizieren einer laufenden nativen macOS-AppKit-Oberfläche aus Codex. Sie erfasst die Content-View der Anwendung im eigenen Prozess, ordnet einen geklickten Punkt der entsprechenden NSView zu, zeigt Hierarchie und Geometrie und bereitet präzises visuelles Feedback für eine Codierungsaufgabe vor.

Public Preview: APIs, Plugin-Verpackung und Präsentationsverhalten können sich vor 1.0 ändern. Codex Browser ist die unterstützte Standardoberfläche. Vollbild bleibt experimentell und ist standardmäßig deaktiviert.

Features

• Ein echtes AppKit-Fenster ohne Accessibility- oder Bildschirmaufnahme-Berechtigung inspizieren.

• Die erfasste Oberfläche anklicken und die tiefste native NSView identifizieren.

• Klassennamen, Frames, Accessibility-Metadaten und Vorgängerpfade einsehen.

• Ein Feedback-Paket kopieren, das die ausgewählte Ansicht, Geometrie, Notiz und private lokale Artefakte enthält.

• Discovery und Transport auf 127.0.0.1 authentifiziert halten.

• Die Sonde mit #if DEBUG aus aktivem Release-Verhalten herausheditieren.

Anforderungen

• macOS 14 oder neuer;

• Xcode 26 oder neuer mit Swift 6.2;

• Node.js 22 oder neuer;

• eine aktuelle Codex-Desktopinstallation für den Plugin-Workflow.

Schnellstart

Klonen Sie das Projekt und verifizieren Sie es:

git clone https://github.com/JaminZhou/AppKitInspector.git
cd AppKitInspector
npm ci
npm run check

Installieren Sie das geklonte Repository als lokalen Codex-Marketplace und aktivieren Sie das Plugin:

codex plugin marketplace add "$PWD"
codex plugin add appkit-inspector@appkit-inspector-dev

Starten Sie die enthaltene AppKit-Demo:

make demo

Starten Sie eine neue Codex-Aufgabe, damit sie die neu installierten MCP-Tools lädt, und fragen Sie dann:

Use AppKit Inspector to connect to the running demo and open it in Codex Browser.

Das Standardwerkzeug open_appkit_inspector erstellt eine einmalige Loopback-URL mit 60 Sekunden Gültigkeit und richtet sich an das rechte Browser-Panel der aktuellen Aufgabe. Es fordert niemals Vollbild an und öffnet nie automatisch den Systembrowser. Das externe Browserfenster ist ein expliziter Fallback.

Sonde zu einem AppKit-Projekt hinzufügen

Fügen Sie das Paket in Xcode hinzu mit:

https://github.com/JaminZhou/AppKitInspector.git

Oder deklarieren Sie es in Package.swift:

.package(
    url: "https://github.com/JaminZhou/AppKitInspector.git",
    from: "0.1.1"
)

Fügen Sie AppKitInspectorProbe nur zu einem Debug-Ziel oder einer Debug-Konfiguration hinzu und starten Sie es, nachdem die Anwendung gestartet wurde:

#if DEBUG
import AppKitInspectorProbe

_ = try? AppKitInspectorProbe.start()
#endif

Fügen Sie die Sonde niemals in Release-, Archiv-, TestFlight- oder App-Store-Builds hinzu oder starten Sie sie dort.

Darstellungsmodi

• Codex Browser: Standard und unterstützt.

• Externes lokales Fenster: expliziter Fallback, der im System-Standardbrowser geöffnet wird.

• MCP-App-Vollbild: experimentell, standardmäßig deaktiviert und nur verfügbar, wenn der MCP-Server mit APPKIT_INSPECTOR_EXPERIMENTAL_FULLSCREEN=1 gestartet wird.

Kein Darstellungsfehler öffnet automatisch ein anderes Fenster.

Repository-Struktur

• native/ – Swift-Probe, Demo-Anwendung und native Tests.

• packages/mcp/ – lokaler MCP-Server, Discovery und authentifizierter Transport.

• packages/app/ – Anpassbare Browser-Oberfläche und lokaler Client.

• plugins/appkit-inspector/ – installierbares Codex-Plugin, generierte Distribution und Skill.

• TODO.md – verschobene Arbeiten und experimentelle Vollbild-Abnahme.

Entwicklung

npm ci
npm run check
swift build -c release

Für eine Live-Bridge-Prüfung führen Sie make demo in einem Terminal und npm run test:live in einem anderen aus. Nach Änderungen an packages/app/ oder packages/mcp/ führen Sie npm run build aus und übernehmen die passenden generierten Dateien unter plugins/appkit-inspector/dist/.

Sicherheit und Datenschutz

Die Sonde und die Inspector-Server binden nur an Loopback, erfordern zufällige Zugangsdaten und schreiben benutzerprivate Discovery-Daten. Startlinks der Codex-Browser sind einmalig verwendbar und werden zu HttpOnly- und Same-Site-Sessions. Das Projekt verwendet öffentliche AppKit- und Foundation-APIs und nutzt weder Injection, noch Accessibility-Automatisierung, private Frameworks oder Screen Recording.

Aufgenommene Screenshots, Hierarchiedaten, Notizen und Prüfarterm are vertraulich. Bei Verknüpfung mit Codex unterliegen sie möglicherweise den Datenkontrollen des Benutzerkontos und des Workspace in der Codex-Aufgabe. Lesen Sie SECURITY.md, bevor Sie die Sonde integrieren, und nutzen Sie {big private Advisory-Plattform für Schwachstellenmeldungen.

Mitwirken

Siehe CONTRIBUTING.md. Beiträge, die absichtlich dem Projekt schnell eingereicht werden, lizenziert unter der Apache License 2.0.

Lizenz

Copyright 2026 Jamin Zhou.

Lizenziert unter der Apache License, Version 2.0. Die Zuschreibungen der gebundenen Abhängigkeiten sind in THIRD_PARTY_NOTICES.md dokumentiert.