AirCodex

AirCodex 是一个原生 macOS GUI App，把 NuPhy Air75 V3 的六个可配置键位和旋钮映射到 Codex Desktop。当前产品边界只支持键盘的 Bluetooth LE 无线模式，不要求在 NuPhyIO 中预设宏，也不写入键盘固件。

本仓库已把原设计中的 Phase 0～5 合并为一个完整基线：BLE HID 学习、事件抑制、Codex 快捷键与 Direct Bridge 控制、深色 GUI、配置持久化、权限引导、诊断、开机启动、Sparkle 2 更新接入以及 Developer ID 发布脚本均在同一个 App 中。

使用

环境要求：macOS 14 或更高版本、Xcode 26 或兼容的 Swift 6.2+ 工具链、Codex Desktop，以及通过 Bluetooth LE 连接的 Air75 V3。

swift test -j 1
./scripts/build-app.sh release
open build/AirCodex.app

安装到本机与日常迭代

使用以下命令把经过签名验证的构建安装到 /Applications/AirCodex.app：

./scripts/install-local.sh release

日常开发时可使用更快的本机架构 Debug 构建：

./scripts/install-local.sh debug

安装脚本不会直接在 /Applications 中编译。它会先生成并验证 build/AirCodex.app，在应用程序目录中暂存完整副本，退出旧实例后再替换正式 App，最后刷新 Launch Services 并从正式路径重新启动。后续本机迭代重复执行同一命令即可；稳定的 Bundle ID 与代码签名可降低 macOS 在更新后重新请求输入监控和辅助功能权限的概率。

首次运行：

1. 在“权限与启动”中授予输入监控和辅助功能权限，然后点“重新检测”。
2. 在“权限与启动”中可开启“Automatic Codex Takeover”；之后 AirCodex 会在 Codex 新启动且缺少 Direct Bridge 时自动以本机参数重新打开。对于 AirCodex 启动前已经运行的 Codex，仍需在控制台点“启用直接控制”并确认重启。
3. 保持 Air75 V3 使用 Bluetooth LE 连接，进入“设备诊断”。
4. 若要保留 F10～F12 的系统媒体功能，先在 NuPhyIO 将旋钮三种手势映射为三个未占用的 F13～F24 扩展功能键（例如 F21～F23）；再在 Phase 0 门禁中点“开始九项顺序学习”。Air75 的 F14/F15 与亮度层冲突，仍应避开。
5. 回到控制台，点击键盘上的热点，为六个槽位选择 Codex 动作、作用域和事件消费策略。
6. 在配置弹窗中点“测试动作”，确认 Direct Bridge 返回模型或推理强度状态。

诊断页的 Phase 0 门禁不会根据“动作已发送”推断成功。只有九项签名完整且唯一、真实映射事件被 Event Tap 丢弃、Direct Bridge 能控制当前任务或新任务编辑器，以及模型和推理动作均由完成响应与渲染状态共同确认后，状态才会从 NO-GO 变为 GO。该证据也会进入用户主动导出的脱敏诊断包。

F13～F18 是 App 内部的六个逻辑槽位名，不要求键盘已经发送对应的标准 F 键。学习成功后，槽位使用 BLE HID 签名识别真实物理控制；热点文案会切换为所选 Codex 功能图标。

原则与边界

• 仅以非独占、只读方式使用 IOHIDManager，不安装内核扩展、DriverKit 扩展或后台 Helper。
• 不调用 NuPhy 私有协议，不发送 Feature/Output Report，因此与 NuPhyIO 同时运行时不会争抢设备写权限。
• 快捷键用于 Codex 已公开的动作；模型仍按任务状态选择 app-server 或新任务 setter，旋钮则直接调用当前活跃编辑器的推理强度语义控制器并做短回验。主对话与侧边对话同时显示时，焦点或最近一次点击所在的编辑器成为控制目标。它不打开选择器或推理 popover，也不会等待 thread/settings/update 的长超时。
• “切换速度模式”直接调用编辑器的 service-tier 控制器，并在渲染状态确认 priority/普通模式后才报告成功，不打开模型菜单。
• “切换目标模式”调用 Codex 独立的 onOpenGoalEditor / onClearGoal 控制器；它与 Plan Mode 分离。未开启时进入目标模式，已开启时再次触发会清除并关闭目标；若当前处于 Plan Mode，会先遵循 Codex 原生行为回到默认协作模式。
• 不锁定 Codex 版本。每次连接都探测渲染层消息桥、当前本地任务或新任务编辑器、model/list、目标模型目录、对应设置函数以及写入后的只读回验能力；不兼容时只在 AirCodex 内提示并停止直接动作，不回退到 UI 点击。
• 自动接管是显式开启的本机偏好，只处理 AirCodex 已运行期间新创建的 Codex PID。CDP 的动态发现、flattened session 和跨进程重启租约由 CodexCDPKit 提供；它先复用任意兼容 App 已启用的端口，只在确认缺失并取得全局租约后优雅重启，因此多个集成不会抢占 Codex 的重启入口。
• App 仅在设置调用完成、且动作开始时锁定的同一编辑器达到目标值后标记为“已确认”，不会把“动作已发送”或另一个对话的状态误当成成功。新任务页的选择会成为首次发送任务时继承的模型与推理强度。
• 事件拦截仅对已学习且已映射的事件生效；可全局暂停，Event Tap 超时会自动恢复。
• 当前不承诺 USB 和 2.4G 接收器模式。

工程入口

• Sources/AirCodexCore：纯数据模型、匹配、抑制判定和 JSON 仓库。
• Sources/AirCodexApp：AppKit 生命周期、SwiftUI GUI、BLE HID、Event Tap、基于 CodexCDPKit 的 Codex Direct Bridge、权限和更新服务。
• Config/Info.plist：应用身份、系统版本和 TCC 用途说明。
• Vendor/Sparkle.xcframework：固定版本的 Sparkle 2 二进制依赖。
• scripts/build-app.sh：Debug 构建本机架构，Release 构建 Universal 2 .app，并执行 Hardened Runtime 临时签名。
• scripts/install-local.sh：构建、验证并安全替换本机 /Applications/AirCodex.app，用于日常开发迭代。
• scripts/package-dmg.sh：生成本地测试用 DMG。
• scripts/sign-and-notarize.sh：Developer ID 签名、公证与票据装订。

架构细节见 docs/architecture.md，实机验收见 docs/acceptance-checklist.md，发布配置见 docs/release.md。

隐私

配置保存在 ~/Library/Application Support/AirCodex/Profiles/air75-v3-ble.json。App 只保存设备元数据、HID 元素签名、映射和最近的内存诊断记录；不读取按键输入文本，不上传数据。导出的诊断包不包含键盘输入内容。