AppKit Inspector

AppKit Inspector 是一个仅用于调试的桥接工具，用于从 Codex 检查正在运行的本地 macOS AppKit 界面。它在进程内捕获应用程序的内容视图，将点击的点映射到其 NSView，显示层次结构和几何信息，并为编码任务准备精确的视觉反馈。

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

功能

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

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

• 查看类名、框架、辅助功能元数据和祖先路径。

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

• 在 127.0.0.1 上进行身份验证的发现和传输。

• 使用 #if DEBUG 将探针从活跃的 Release 行为中编译出来。

Related MCP server: computer-use

要求

• 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. 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 工具会为当前任务的右侧 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 目标或 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，并使用私有安全公告报告漏洞。

贡献

请参阅 CONTRIBUTING.md。有意提交给项目的贡献根据 Apache License 2.0 许可。

许可证

版权所有 2026 Jamin Zhou。

根据 Apache License, Version 2.0 许可。 捆绑的依赖项归属在 THIRD_PARTY_NOTICES.md 中记录。