AppKit Inspector

AppKit Inspector 是一个仅用于 Debug 的桥接器，用于从 Codex 检查实时运行的 macOS 原生 AppKit 界面。它在进程内捕获应用的内容视图，将点击的坐标点映射到对应的 NSView，展示视图层级和几何信息，并为编码任务准备精确的视觉反馈。

公开预览： 在 1.0 之前，API、插件打包方式以及呈现行为可能会发生变化。 Codex Browser 是受支持的默认呈现载体。全屏仍处于实验阶段，且默认禁用。

功能

• 无需辅助功能或屏幕录制权限，即可检查真实的 AppKit 窗口。

• 点击捕获的界面，并识别最深层的原生 NSView。

• 查看类名、frame、辅助功能元数据以及祖先路径。

• 复制反馈包，其中包含所选视图、几何信息、备注和私有本地工件。

• 在 127.0.0.1 上保持发现与传输的认证。

• 通过 #if DEBUG 将探针从实际的 Release 构建行为中排除。

环境要求

• macOS 14 或更高版本；

• 带 Swift 6.2 的 Xcode 26 或更高版本；

• Node.js 22 或更高版本；

• 安装了最新版 Codex 桌面客户端，以支持插件工作流。

快速开始

克隆并验证项目：

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

将克隆的仓库作为本地 Codex marketplace 安装并启用插件：

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 工具会为当前任务右侧的 Browser 面板创建一个 60 秒有效、一次性使用的回环 URL。它不会请求全屏，也不会自动调用系统浏览器。外部浏览器窗口是显式的回退方案。

将探针添加到 AppKit 项目中

在 Xcode 中添加该包：

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

或者在 Package.swift 中声明它：

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

仅将 AppKitInspectorProbe 添加到 Debug target 或 Debug 配置中，然后在应用启动完成后启动它：

#if DEBUG
import AppKitInspectorProbe

_ = try? AppKitInspectorProbe.start()
#endif

切勿在 Release、归档、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 服务器只绑定到本机回环，索要随机凭据，并写入多用户私有密钥文件。Codex Browser 启动链接为一次性使用，并且会变成 HttpOnly 同站会话。项目使用公开的 AppKit 和 Foundation API，不涉及注入、辅助功能自动化、私有框架或屏幕录制。

捕获的截图、层级数据、备注和审阅产物均为敏感信息。通过 Codex 使用时，它们可能成为 Codex 任务的一部分，并受到用户的产品和工作区资料管理控制。在集成探针前，请先阅读 SECURITY.md；漏洞报告请使用私有安全公告。

许可

Copyright 2026 Jamin Zhou.

根据 Apache License, Version 2.0 使用。 随附依赖项的归属说明请参见 THIRD_PARTY_NOTICES.md。