pi TUI Darwin 原生预编译构建指南：跨架构编译 macOS 修饰键检测模块

pi 项目的 TUI 包（packages/tui）内置了一个原生 C 扩展，用于在 macOS 上检测 Shift、Command、Control、Option 修饰键是否被按下——终端本身无法向应用传递这些按键状态。本篇技术指南基于 Darwin 预编译构建文档 展开，完整覆盖单条命令构建 arm64 与 x86_64 双架构预编译二进制的方法、部署目标的选择逻辑，以及在没有 macOS 主机的情况下使用交叉工具链（如 osxcross）构建的完整流程，并结合 构建脚本、C 源码 与 TypeScript 加载层 的源码实现，讲解这条构建链背后的设计取舍。读完后你可以独立完成双架构 .node 二进制的构建、理解交叉编译对 Apple SDK 的硬性依赖，以及知道为什么 Zig 无法作为替代方案。

为什么 TUI 需要一个 Darwin 原生模块

TUI 运行在终端里，而终端协议只传递键码与修饰键转义序列，应用层无法直接查询 macOS 键盘的修饰键状态。pi 的 TUI 需要这一能力来区分诸如 Shift+Enter 这类组合键。实现位于 darwin-modifiers.c，核心调用链如下：

1. 将键名映射为 CoreGraphics 事件标志位：shift → kCGEventFlagMaskShift、command → kCGEventFlagMaskCommand、control → kCGEventFlagMaskControl、option → kCGEventFlagMaskAlternate（见 modifier_mask_for_name 函数，darwin-modifiers.c 第 23–29 行）；
2. 通过 CGEventSourceFlagsState(kCGEventSourceStateCombinedSessionState) 查询当前会话的合成修饰键状态，与目标掩码做按位与；
3. 将布尔结果经 N-API 传回 JS 层。

该模块对外只暴露一个导出函数 isModifierPressed，在 napi_register_module_v1 中通过 napi_create_function 与 napi_set_named_property 注册。值得注意的是，它并不依赖 Node 头文件或 node_api.h，而是通过 dlsym(RTLD_DEFAULT, ...) 从宿主进程动态解析 N-API 符号（napi_get_cb_info、napi_get_value_string_utf8 等，第 19–21 行），这正是 Windows 侧构建文档 中所述"无需 Node 头文件"设计的同源做法，也解释了 build.sh 中 -undefined dynamic_lookup 链接标志的由来。

TS 侧的入口是 native-modifiers.ts：isNativeModifierPressed(key) 按 process.platform 与 process.arch 定位 native/darwin/prebuilds/darwin-<arch>/darwin-modifiers.node，逐候选路径 require，加载失败时静默降级为返回 false。其实际消费点在 terminal.ts 的 Shift+Enter 检测逻辑中。

从仓库根目录构建双架构预编译

构建入口是 package.json 中的脚本：

"build:native:darwin": "native/darwin/build.sh"

在仓库根目录执行：

npm --prefix packages/tui run build:native:darwin

该命令同时产出两种架构的预编译二进制，最终安装到：

• packages/tui/native/darwin/prebuilds/darwin-arm64/darwin-modifiers.node
• packages/tui/native/darwin/prebuilds/darwin-x64/darwin-modifiers.node

两个产物当前均已存在于仓库的 prebuilds 目录，并由 package.json 的 files 字段（"native/darwin/prebuilds/**/*.node" 等条目）随 npm 包一起发布，因此下游使用者无需本地编译。

部署目标

构建脚本固定了两种架构的最低系统版本：

• arm64：--target=arm64-apple-macos11.0（macOS 11.0，Apple Silicon 的起始版本）
• x86_64：--target=x86_64-apple-macos10.15（macOS 10.15，与 N-API 预编译二进制的常见兼容基线一致）

这一选择意味着 arm64 产物天然只面向 Apple Silicon，而 x86_64 产物覆盖较老的 Intel Mac；两个目标在 build.sh 末尾以 build arm64 arm64-apple-macos11.0 与 build x64 x86_64-apple-macos10.15 两行显式给出。

build.sh 的编译器与 SDK 解析流程

build.sh 的解析顺序值得注意，它决定了"任何一台 Intel 或 Apple Silicon 主机都能同时构建两种架构"：

1. 编译器选择：若设置了 CC 环境变量则直接使用 $CC；否则在 macOS 上通过 xcrun --find clang 定位 Apple clang；最后回退到 PATH 中的 clang（第 8–14 行）；
2. SDK 选择：若设置了 SDKROOT，先校验目录存在，再追加 -isysroot "$SDKROOT" 与 -F$SDKROOT/System/Library/Frameworks 两个标志；未设置且处于 Darwin 上时，通过 xcrun --sdk macosx --show-sdk-path 解析当前激活的 macOS SDK（第 21–31 行）；
3. 编译：统一使用 -std=c11 -Wall -Wextra -O2，以 -bundle -undefined dynamic_lookup -framework CoreGraphics 编译出 Mach-O bundle，先在 mktemp 临时目录中产出，再 install -m 755 到最终的 prebuilds 目录（第 43–57 行）。

-bundle 与 -undefined dynamic_lookup 的组合是该模块"无 Node 头文件"设计在链接侧的体现：所有 N-API 符号留待运行时从宿主 Node 进程解析，因此同一份二进制不需要针对 Node 大版本重新编译。

非 macOS 主机上的交叉构建

在 Linux 或 Windows 主机上构建，需要一套完整的 Darwin 交叉工具链，条件包括：macOS SDK 与 Mach-O 链接器。文档以 osxcross 为例，通过 CC 与 SDKROOT 两个环境变量注入工具链与 SDK：

CC=/path/to/osxcross/clang SDKROOT=/path/to/MacOSX.sdk \
  npm --prefix packages/tui run build:native:darwin

对照 build.sh 的逻辑可以看到这两个变量的确切消费点：CC 命中第 8 行的分支跳过 xcrun；SDKROOT 命中第 22 行分支，其目录存在性检查失败会直接以 SDKROOT does not exist 报错退出。由于脚本本身不依赖任何 macOS 专有工具，非 Darwin 主机只要提供上述变量即可走完整个流程。

为什么"Linux/Windows 上的普通 clang"不够

这里有一条硬性约束，必须单独强调：SDK 必须依照 Apple 的许可条款获取并使用；普通的 Linux 或 Windows clang 不足以完成构建。原因在于源码第 1 行 #include <CoreGraphics/CoreGraphics.h> 以及链接期的 -framework CoreGraphics——CoreGraphics 是 Apple 私有框架，其头文件与存根只随 macOS SDK 分发。任何通用工具链都不自带这些存根，因此交叉构建本质上离不开一份合法的 macOS SDK。

为什么不用 Zig

文档最后一段澄清了一个常见疑问：Zig 虽然自带跨平台 C 交叉编译能力，但它不捆绑 Apple SDK 或 CoreGraphics 框架存根，因而无法让该构建摆脱对 SDK 的依赖；并且其 clang 驱动目前也不能作为 Apple clang 的"即插即用"替换来处理这份 Mach-O bundle 配方（即 -bundle -undefined dynamic_lookup 组合）。结论是：选择 Apple clang + 显式 SDK 注入是功能性与许可约束共同决定的，而非单纯的工具偏好。

构建产物如何被 TUI 消费与校验

预编译二进制的加载与解析有一套独立的候选路径机制。native-module-path.test.ts 验证了两种场景：

• 当模块被打包进别的产物（例如捆绑后的 coding-agent）时，候选路径优先解析到已安装的 @earendil-works/pi-tui 包内的 native/darwin/prebuilds/...，再回退到捆绑模块相邻目录；
• 当 TUI 包不可解析时，回退到捆绑模块目录与可执行文件（execPath）旁的相对路径。

这解释了为什么 .node 文件既可以位于源码树的 prebuilds/ 目录、也可以位于 npm 包安装位置，且 native-modifiers.ts 的循环 try/catch 能逐个候选路径尝试加载。此外，files 字段将 native/darwin/src/**/*.c、build.sh 与 README.md 一并打包，意味着下游用户拿到 npm 包后既能直接使用预编译产物，也具备自行重编译的完整输入。

小结

关注点	结论
构建命令	npm --prefix packages/tui run build:native:darwin（仓库根目录执行）
产物	darwin-arm64（macOS 11.0 目标）与 darwin-x64（macOS 10.15 目标）两份 .node
macOS 主机	xcrun 自动定位 Apple clang 与激活 SDK，Intel/Apple Silicon 均可构建双架构
非 macOS 主机	需完整 Darwin 交叉工具链，CC + SDKROOT 注入 osxcross 编译器与 SDK
硬性依赖	合法来源的 macOS SDK + CoreGraphics 框架；普通 clang 不可行
替代方案排除	Zig 不提供 Apple SDK/框架存根，且其 clang 驱动不兼容本 Mach-O bundle 配方
运行形态	N-API 符号运行时 dlsym 解析，加载失败时 TS 层静默降级，功能自动关闭

这套构建方案的核心权衡是：用一份无 Node 头文件依赖、运行时解析 N-API 的 C 源码，换取跨 Node 版本稳定、双架构一次构建、且加载失败可优雅降级的修饰键检测能力；而其对 Apple SDK 的依赖则是 CoreGraphics 查询路径的固有代价。