AppKit Inspector

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

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

Возможности

• Инспектируйте реальное окно AppKit без разрешения Accessibility или Screen Recording.

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

• Просматривайте имена классов, фреймы, метаданные Accessibility и цепочки предков.

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

• Поддерживайте аутентифицированное обнаружение и транспорт на 127.0.0.1.

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

Требования

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

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

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

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

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

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

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.

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

Добавление зонда в проект 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 fullscreen: экспериментальный, отключён по умолчанию и доступен только когда сервер 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 и не использует инъекции, автоматизацию Accessibility, приватные фреймворки или Screen Recording.

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

Участие в разработке

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

Лицензия

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

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