AppKit Inspector

AppKit Inspector — это мост только для отладки, позволяющий просматривать живой нативный интерфейс AppKit в macOS из Codex. Он захватывает представление содержимого приложения в процессе, сопоставляет кликнутую точку с соответствующим NSView, показывает иерархию и геометрию и подготавливает точную визуальную обратную связь для задачи кодирования.

Публичная предварительная версия: API, упаковка плагинов и поведение представления могут измениться до версии 1.0. Codex Browser — поддерживаемая поверхность по умолчанию. Полноэкранный режим остаётся экспериментальным и отключён по умолчанию.

Возможности

• Просматривайте реальное окно AppKit без разрешения на специальные возможности или запись экрана.

• Кликните по захваченному интерфейсу и определите самый глубокий нативный NSView.

• Просматривайте имена классов, фреймы, метаданные специальных возможностей и пути предков.

• Скопируйте пакет обратной связи, содержащий выбранное представление, геометрию, заметку и приватные локальные артефакты.

• Обеспечьте аутентификацию обнаружения и транспорта на 127.0.0.1.

• Исключите зонд из активного поведения Release с помощью #if DEBUG.

Related MCP server: computer-use

Требования

• macOS 14 или новее;

• Xcode 26 или новее со Swift 6.2;

• Node.js 22 или новее;

• актуальная установка Codex desktop для рабочего процесса плагинов.

Быстрый старт

Клонируйте и проверьте проект:

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

Установите клонированный репозиторий как локальный маркетплейс Codex и включите плагин:

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

Запустите включённое демо AppKit:

make demo

Начните новую задачу Codex, чтобы она загрузила недавно установленные инструменты MCP, затем спросите:

Use AppKit Inspector to connect to the running demo and open it in Codex Browser. The workflow
explicitly presents the right Browser panel after navigation. In the Inspector, use **Fit**, **−**,
and **+** to resize the snapshot; trackpad pinch and Command-modified scrolling also zoom.

Инструмент по умолчанию open_appkit_inspector создаёт 60-секундный одноразовый URL loopback для правой панели Browser текущей задачи. Он никогда не запрашивает полноэкранный режим и не вызывает системный браузер автоматически. Внешнее окно браузера — явный запасной вариант.

Добавьте зонд в проект AppKit

Добавьте пакет в Xcode с помощью:

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

Или объявите его в Package.swift:

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

Добавьте AppKitInspectorProbe только в цель Debug или конфигурацию Debug, затем запустите его после запуска приложения:

#if DEBUG
import AppKitInspectorProbe

_ = try? AppKitInspectorProbe.start()
#endif

Никогда не добавляйте и не запускайте зонд в сборках Release, archive, TestFlight или App Store.

Режимы представления

• Codex Browser: по умолчанию и поддерживается.

• Внешнее локальное окно: явный запасной вариант, открываемый в системном браузере по умолчанию.

• Полноэкранный режим MCP App: экспериментальный, отключён по умолчанию и доступен только при запуске MCP-сервера с APPKIT_INSPECTOR_EXPERIMENTAL_FULLSCREEN=1.

Никакой сбой представления не открывает автоматически другое окно.

Структура репозитория

• native/ — переиспользуемый Swift-зонд, демонстрационное приложение и нативные тесты.

• packages/mcp/ — локальный MCP-сервер, обнаружение и аутентифицированный транспорт.

• packages/app/ — интерфейс браузера Inspector и локальный клиент.

• plugins/appkit-inspector/ — устанавливаемый плагин Codex, сгенерированное распространение и навык.

• TODO.md — отложенные работы и приёмка экспериментального полноэкранного режима.

Разработка

npm ci
npm run check
swift build -c release

Для проверки живого моста запустите make demo в одном терминале и npm run test:live в другом. После изменения packages/app/ или packages/mcp/ выполните npm run build и включите соответствующие сгенерированные файлы в plugins/appkit-inspector/dist/.

Безопасность и конфиденциальность

Зонд и серверы Inspector привязываются только к loopback, требуют случайные учётные данные и записывают пользовательские приватные данные обнаружения. Ссылки запуска Codex Browser одноразовые и становятся сессиями HttpOnly, same-site. Проект использует публичные API AppKit и Foundation и не использует инъекции, автоматизацию специальных возможностей, приватные фреймворки или запись экрана.

Захваченные скриншоты, данные иерархии, заметки и артефакты проверки являются чувствительными. При использовании через Codex они могут стать частью задачи Codex под контролем данных продукта и рабочего пространства пользователя. Прочтите SECURITY.md перед интеграцией зонда и используйте приватные уведомления о безопасности для сообщений об уязвимостях.

Вклад

См. CONTRIBUTING.md. Вклады, намеренно отправленные в проект, лицензируются по Apache License 2.0.

Лицензия

Авторское право 2026 Jamin Zhou.

Лицензировано по Apache License, Version 2.0. Атрибуции встроенных зависимостей задокументированы в THIRD_PARTY_NOTICES.md.