oh-my-pi Natives Addon Loader Runtime 深度解析ESM 入口与已校验.node原生模块之间的运行时【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本篇技术指南围绕 oh-my-piomp仓库中的 docs/natives-addon-loader-runtime.md 展开聚焦oh-my-pi/pi-natives包的原生模块加载运行时。该运行时负责完成Node/Bun 导入 ESM 入口到加载并校验正确的pi_natives.platform-arch*.node插件之间的全部工作平台与 CPU 变体检测、候选路径解析、Windows 更新安全暂存、Bun 独立可执行文件的内嵌解压、版本哨兵校验以及可诊断的失败聚合。读完本文你将完整掌握该加载器的上下文构成、候选排序策略、AVX2 变体选择逻辑、内嵌清单解压的安全校验以及PI_DEBUG_STARTUP、PI_NATIVE_VARIANT等关键环境变量的实战用法。一、加载器在包结构中的位置oh-my-pi/pi-natives是一个通过 N-APInapi-rs暴露 Rust 能力的原生绑定包其package.json中的exports定义了三个实际为四个入口子路径.→./native/index.js完整 API 面模块求值时就加载原生插件./desktop→./native/desktop.js桌面会话按需加载./clipboard→./native/clipboard.js剪贴板按需加载./vcs→./native/vcs.js版本控制相关绑定见 packages/natives/package.json。其中真正承载加载逻辑的文件是 packages/natives/native/loader-state.js。它的文件头注释明确了职责边界Node importsnative/index.js 与 正确的pi_natives.platform-arch*.node被 require、校验并返回 之间的每一步都归属于这个模块——平台/变体检测、候选路径解析、Windows 暂存、内嵌解压、版本哨兵校验与聚合错误面。而index.js本身被刻意缩减为一次loadNative()调用加上MARKER_START/MARKER_END之间的生成式导出由 packages/natives/scripts/gen-enums.ts 在napi build后重写其文件头注释说明了这样拆分的动机把纯函数助手留在loader-state.js让它们可以不经副作用不触发 AVX2 检测、不探测文件系统就能被单元测试覆盖。二、入口与加载时机eager 与 lazy 两种模式加载器支持两种加载时机二者共用同一个loadNative()实现Eager 加载根入口。native/index.js在模块求值时直接执行const nativeBindings loadNative();见 packages/natives/native/index.js随后从返回的 bindings 中导出全部类与函数——AudioCapture、DesktopSession、DiffStream、EditStore、PtySession、Shell、VcsGitRepo以及countTokens、grep、highlightCode、pdfToMarkdown、executeShell等上百个函数和若干枚举。任何业务代码一旦 import 这个根入口原生插件就会立即被加载。Lazy 加载子入口。native/desktop.js与native/clipboard.js同样 import 了加载器但只在各自的公开包装函数内部调用loadNative()// desktop.js export function createDesktopSession(options) { DesktopSession ?? adaptDesktopSession(loadNative().DesktopSession); return new DesktopSession(options); }// clipboard.js export function copyToClipboard(text) { return loadNative().copyToClipboard(text); } export function readImageFromClipboard() { return loadNative().readImageFromClipboard(); }createDesktopSession的注释点明了设计意图在 computer worker 收到初始化消息之前不加载原生插件从而把桌面会话这类重功能从启动路径上剥离。两个文件都是首次调用时才真正 dlopen。不记忆化no memoization。文档明确一次成功的加载并不会被 JS 层记忆化。重复调用依赖 Node/Bun 运行时require(...)的原生模块缓存——同一路径二次 require 会命中缓存不会重复 dlopen而加载后的附加设置Tokio 运行时安装、旧版本缓存清理被设计为幂等或 best-effort可安全重复执行。三、加载上下文Loader Context的构成initLoaderContext()见 packages/natives/native/loader-state.js一次性完成所有路径、策略与变体决策使后续加载循环保持纯粹的 require/validate 流水线。其核心产出如下平台标签与版本哨兵platformTag${platform}-${process.arch}例如linux-x64、darwin-arm64versionSentinelExport由package.json#version推导的哨兵导出名__piNativesVversion其中非字母数字统一映射为下划线。当前仓库版本为18.1.14对应哨兵名__piNativesV18_1_14——该名字与 Rust 侧#[napi(js_name __piNativesV18_1_14)]的常量函数严格对应见 crates/pi-natives/src/lib.rs。仓库测试 packages/natives/test/windows-staging.test.ts 专门断言 Rust 的js_name与package.json版本始终同步防止发布脚本回归。目录解析nativeDir包本地native/目录即.node的常规安放处execDirprocess.execPath所在目录nativesDir默认~/.omp/natives仅当$XDG_DATA_HOME/omp目录存在时才改用$XDG_DATA_HOME/omp/natives见 loader-state.js 的getNativesDir()versionedDirnativesDir/packageVersion即每个包版本一个独立缓存目录userDataDir遗留编译产物目录Windows 上为%LOCALAPPDATA%/omp或~/AppData/Local/omp其他平台为~/.local/bin外加workspace/install/compiled 三种模式判定、可选的 leaf 目录、Windows 暂存策略、CPU 变体、文件名列表与有序候选路径。编译模式判定Compiled Binary。detectCompiledBinary()的判定顺序是存在非空的embeddedAddon清单 →PI_COMPILED环境变量被设置 →import.meta.url包含 Bun 内嵌标记$bunfs、~BUN或%7EBUN。loader-state.js 的头部注释解释了背景issue #823bun build --compile --define PI_COMPILEDtrue会替换裸标识符PI_COMPILED而非process.env.PI_COMPILED因此运行时读环境变量恒为undefined同时 ESM 的import.meta.url会被重写为 bunfs URL所以 URL 标记是可靠的编译模式信号之一。仓库中 packages/natives/test/issue-823-repro.test.ts 对这一行为做了回归覆盖。workspace 判定。非编译模式下若nativeDir不在node_modules路径段内则判定为 workspace 加载即从packages/natives/native/本地开发树运行。Windows 上的路径匹配大小写不敏感nativeDir.toLowerCase()后再匹配其他平台大小写敏感windows-staging.test.ts 用C:\Users\...与/tmp/NODE_MODULES/...等样例验证了这套分类逻辑。四、平台支持与 CPU 变体AVX2选择受支持的发布标签共 6 个平台标签说明linux-x64Linux / x86-64linux-arm64Linux / ARM64darwin-x64macOS / Inteldarwin-arm64macOS / Apple Siliconwin32-x64Windows / x86-64win32-arm64Windows / ARM64不支持的标签不会在加载一开始就报错而是先走完候选探测流程最后才抛出Unsupported platform错误详见失败诊断一节。x64 的 CPU 变体分为modern启用 AVX2与baseline通用指令集。选择优先级如下对应selectCpuVariant()见 loader-state.jsPI_NATIVE_VARIANTmodern|baseline环境变量覆盖永远优先非法值被忽略例如garbage会被当作未设置继续走后续检测私有继承环境变量__PI_NATIVE_VARIANT_CACHE当值合法modern/baseline时直接采用。该缓存由第一个完成检测的上下文主线程写入process.envBun worker 与子进程在 spawn 时继承process.env从而跳过重复检测——这是 issue #3238 的修复核心运行时 AVX2 检测最慢路径每个进程至多执行一次结果回写到缓存环境变量供后续 worker/子进程继承。检测失败或检测不到 AVX2则回落为baseline。非 x64 架构完全不参与变体逻辑selectCpuVariant返回{ variant: null, source: non-x64 }既不读取也不回写缓存。各平台检测手段detectAvx2Support()loader-state.jsLinux直接读取/proc/cpuinfo正则匹配\bavx2\bmacOS依次尝试绝对路径/usr/sbin/sysctl与裸sysctlPATH 可能不含/usr/sbin见 issue #3238查询machdep.cpu.leaf7_features与machdep.cpu.features两个键Windows在 Bun 运行时优先通过bun:ffi调用kernel32.dll的IsProcessorFeaturePresent(40)PF_AVX2_INSTRUCTIONS_AVAILABLE约 0.5ms相对 PowerShell 子进程约 270msNode 内嵌无bun:ffi时回退到 PowerShell——依次尝试pwsh.exePowerShell 7 / .NET Core能正确回答[System.Runtime.Intrinsics.X86.Avx2]::IsSupported与powershell.exeWindows PowerShell 5.1 / .NET Framework会抛 TypeNotFound从而把主机钉在 baseline 插件。子进程执行统一封装在runCommand()中优先Bun.spawnSync因为 Bun 的child_process.spawnSyncshim 在 macOS worker 线程中曾返回非零/null这正是 issue #3238 的失败模式再回退node:child_process。文件名列表由getAddonFilenames()生成运行时选择有序文件名modern x64pi_natives.tag-modern.nodepi_natives.tag-baseline.nodepi_natives.tag.nodebaseline x64pi_natives.tag-baseline.nodepi_natives.tag.node非 x64 / 无变体pi_natives.tag.node其中tag即platformTag。issue #3238 的教训正是worker 里检测失败导致文件名列表只剩[baseline, default]而磁盘上只有 modern 产物修复后由主线程缓存变体结论worker 继承modern文件名列表重新包含 modern 文件见 packages/natives/test/issue-3238-repro.test.ts。测试还断言PI_NATIVE_VARIANT覆盖路径不会污染缓存——用户可能按调用切换覆盖值子进程应自行重新评估该环境变量。五、候选路径排序Candidate OrderingresolveLoaderCandidates()loader-state.js对候选路径去重new Set(...)保留首次出现顺序并按运行模式生成不同顺序。5.1 已安装、非编译包顺序为leaf 包oh-my-pi/pi-natives-tag中每个选中文件名通过createRequire(import.meta.url).resolve(.../package.json)定位见resolveLeafPackageDir()每个文件名依次在包本地nativeDir、可执行文件目录execDir中探测。平台 leaf 包优先于可能过期的核心包产物workspace 加载则刻意跳过 leaf 解析。5.2 Windowsnode_modules暂存staging当满足平台为 Windows 非编译运行时 nativeDir含node_modules路径段三个条件时shouldStageNodeModulesAddon()loader-state.js候选顺序变为versionedDir中的每个文件名暂存目标leaf 包候选包本地与可执行目录候选。暂存动作由maybeStageNodeModulesAddon()执行把leafPackageDir ?? nativeDir下每个可用文件名拷贝到versionedDir的缺失缓存目标已存在的缓存文件保留不动。目录/拷贝失败被记录在错误列表正常探测继续。这一机制是 Windows 下bun install -g更新安全网issue #4812见 packages/natives/test/issue-4812-repro.test.ts当旧omp进程仍在运行时bun 无法覆盖node_modules/oh-my-pi/pi-natives/native/中被锁定的.node会留下旧二进制 新 ESM 包装的错位组合下次启动表现为工具深处的sym is not a function崩溃。暂存到版本固定的缓存目录后每个包版本拥有独立路径并发 omp 进程不会碰撞同一文件运行进程持有的是缓存副本的句柄bun 得以在后续更新中自由覆盖node_modules副本后续更新不会触发文件锁竞争。该策略在非 Windowsbun 原子改名无锁问题、workspace 开发否则bun --cwdpackages/natives run build的重建会被陈旧缓存副本遮蔽以及编译二进制由内嵌解压器负责填充versionedDir下被禁用。测试 windows-staging.test.ts 对上述门控规则与暂存路径必须排在 node_modules 路径之前的排序约束做了完整断言同时验证暂存路径中不会混入编译模式专用的 user-data 目录。5.3 编译运行时顺序为每个文件名在versionedDir、遗留 user-data 目录中探测每个文件名在包本地nativeDir、可执行文件目录中探测。若内嵌解压成功选中一个候选该路径会被前置到候选列表最前面编译模式下 Windows 暂存被禁用。六、内嵌清单与解压Embedded Manifest Extraction清单生成。native/embedded-addon.js在普通源码/发布核心状态下被重置为embeddedAddon null见 packages/natives/native/embedded-addon.js。构建流水线运行 packages/natives/scripts/embed-native.ts 后会生成真实清单其结构为platformTag与包versionarchivegzip 压缩 tar 归档引用format: tar.gz、filename、filePath文件名形如embedded-addons.tag.tar.gz位于native/目录files[]每个条目含variantmodern/baseline/default、仅 basename 的filename与size。脚本逻辑embed-native.ts按TARGET_PLATFORM/TARGET_ARCH默认取宿主确定平台标签x64 收集 modernbaseline 两个候选非 x64 收集 default 单候选available.length 0时报错并列出期望文件名随后用Bun.Archive以 gzip level 9 打包并把import archivePath from ../native/...tar.gz with { type: file }注入生成文件使编译后的独立可执行文件能内嵌该归档。--reset参数会把embedded-addon.js重置回null桩并清理归档用于发布前还原。解压条件。maybeExtractEmbeddedAddon()仅在编译模式 清单platformTag与当前平台一致 清单version与包版本一致 存在可选择的文件四者同时满足时执行。文件选择逻辑selectEmbeddedAddonFile()非 x64default其次清单首个文件modern x64modern其次baselinebaseline x64仅baseline。解压过程extractEmbeddedAddonArchive()loader-state.js创建versionedDirprepareNativeVersionDir还会utimes刷新目录时间戳防止并发清理误删进行中的缓存见NATIVE_CACHE_CLEANUP_GRACE_MS 10 * 60_000的 10 分钟宽限期若每个需要解压的清单文件都已是声明大小一致的常规文件直接复用跳过解压否则zlib.gunzipSync解压并手工解析 tar 头512 字节块、八进制长度字段、prefix/name拼接只接受清单允许列表中的 basename-only 常规文件条目拒绝路径穿越path.basename(filename) filename且不含/、\、拒绝非常规条目类型typeflag ! 0、校验文件大小、通过临时文件 rename原子写盘writeEmbeddedAddonFile临时名含 pid 与时间戳缺失条目、截断归档、不安全文件名、错误类型、尺寸不符都会抛出明确错误较旧的清单若没有 archive 字段仍可提供每个文件的独立filePath元数据走直接拷贝路径。解压错误被累积到错误列表加载器继续尝试普通候选路径——内嵌解压失败不会立即终止启动。七、候选校验与加载后配置对每个候选路径加载循环loadNative()loader-state.js执行启用时输出启动标记startupMarkerrequire(candidate)除非是 workspace 开发require 期望的包版本哨兵函数若插件提供__ompInstallTokioRuntime()则调用它best-effort 清理比当前版本更旧的语义化版本缓存目录返回 bindings。哨兵校验版本一致性证明。validateLoadedBindings()通过js_name编码版本的做法把一个物理上不可能的约束变成强校验不同发布的.node无法暴露当前加载器查找的哨兵符号从而把 Windows 锁文件更新导致的无声sym is not a function崩溃转化为加载期可操作错误。workspace 开发路径跳过校验是因为本地.node只有在bun --cwdpackages/natives run build重建后才获得重命名的哨兵——跳过校验让拉取后未重建的开发树也能启动。哨兵缺失时的错误诊断区分为两种模式这也是该模块最精妙的设计之一磁盘过期stale disk磁盘上的.node早于当前加载器构建但进程内没有旧模块驻留——错误提示重新安装reinstall以重新同步文件进程驻留过期resident old原地升级已把新发布写入磁盘而当前进程仍持有旧代插件驻留在动态加载器的原生模块缓存中require返回的仍是旧导出携带旧哨兵——此时磁盘其实已一致重装是无效操作错误信息明确指示重启进程restart。判据是读候选文件字节若其中包含当前哨兵字符串diskHasExpectedSentinel且 bindings 携带旧哨兵则为进程驻留过期 → 重启否则为磁盘过期 → 重装。此外还兼容一个前哨兵时代pre-sentinel的稳定核心 ABI当磁盘文件无当前哨兵、bindings 不含任何__piNativesV...键、且满足countTokens/executeShell/visibleWidth/DesktopSession(capture/execute/close) 等签名时isCompatiblePreSentinelNativeAddon允许旧发布桥接版本升级。加载器不校验全部公开导出。Tokio/Rayon 运行时安装。Rust 侧#[module_init]crates/pi-natives/src/lib.rs只安装崩溃诊断crash_handler::install()刻意不在动态加载器锁内派生运行时线程——在锁内急切地构建多线程运行时会在某些宿主上死锁新 worker 阻塞在加载器锁上而 init 线程仍持有该锁。可选的加载后钩子omp_install_tokio_runtime()js_name __ompInstallTokioRuntimelib.rs由 JS 加载器在dlopen返回后、任何异步原生调用之前恰好调用一次Windows 上先通过probe_spawnable_workers预探测可派生线程数std::thread::Builder::spawn返回io::Result不会像多线程 runtime 构建那样在提交限制下以 panic 中止进程再据此构建有界 Tokio 多线程运行时兜底 current-thread 运行时与有界 Rayon 全局线程池探测不到任何 worker 时打补丁的 Rayon 调用点保持串行。该钩子是 best-effort 的旧插件未提供该导出、或钩子失败时回退到 napi-rs 默认行为每个 CPU 一线程的默认 runtime。安装由AtomicBool保证进程内最多执行一次幂等。旧版本缓存清理。cleanupStaleNativeVersions()忽略读/删失败启动已成功绝不能被清理打断只删除解析为语义化版本且严格早于当前包版本的目录并受 10 分钟 mtime 宽限期保护当前/未来版本、预发布或非 semver 名称如not-a-version、普通文件全部保留。测试用临时目录构造了 stale、fresh、当前、未来版本与普通文件混合场景断言只有过期目录被移除windows-staging.test.ts。启动标记。设置PI_DEBUG_STARTUP后加载器会向 stderr 同步输出[startup] ...标记含native:loadNative:start、native:extractEmbeddedAddon:start、native:require:basename、native:tokioRuntime:installed/failed、native:loadNative:done。同步写 stderr 是刻意为之解压或 dlopen 挂起时:start标记也必须留下便于定位卡点。加载器无法依赖 pi-utils因此实现了一份本地副本。八、失败诊断当所有候选都失败时loadNative()区分两种错误面不支持的平台抛出Unsupported platform: tag附受支持列表与开 issue 指引If you need support for this platform, please open an issue.受支持平台加载失败抛出Failed to load pi_natives native addon for tagx64 时含变体如tag (modern)随后逐条列出每个候选/准备阶段的错误Tried:\n- candidate: error最后附加模式专属帮助。模式专属帮助buildHelpMessage()内容差异编译二进制列出期望的缓存路径versionedDir下的每个文件名建议删除该版本目录后重跑并打印 release 下载用的curl -fsSL ... -o ...命令模板已安装包建议重装oh-my-pi/pi-natives、本地宿主构建bun --cwdpackages/natives run build、以及显式目标构建bun scripts/bazel-natives.ts target --dest packages/natives/native后者对应仓库 scripts/bazel-natives.ts。九、完整生命周期文档以如下伪代码概括加载全流程entrypoint evaluates or lazy wrapper is invoked - initialize loader context - extract matching embedded archive, if any - otherwise stage Windows node_modules addon, if applicable - require candidates in deterministic order - validate sentinel outside workspace development - install optional post-load runtime - best-effort clean older version caches - return bindings - no success: throw unsupported-platform or aggregated load error值得强调的两个设计要点其一上下文初始化只发生一次loadNative()调用initLoaderContext()纯助手导入不会触发 AVX2 检测或文件系统探测测试零成本其二成功加载不做 JS 层记忆化重复调用依赖运行时require缓存而加载后设置均幂等或 best-effort天然适合 lazy 包装器的首次调用即加载语义。十、测试与回归保障加载器的正确性由多个针对性回归测试钉住可作阅读源码的入口packages/natives/test/windows-staging.test.tsWindows 暂存门控规则、候选排序、大小写不敏感路径分类、过期缓存清理、Rust 哨兵与包版本同步断言packages/natives/test/issue-3238-repro.test.ts跨 worker 上下文的变体解析、PI_NATIVE_VARIANT覆盖优先于缓存、垃圾值忽略、非 x64 不污染缓存、modern 文件名列表回归packages/natives/test/issue-823-repro.test.ts编译模式下PI_COMPILED/bunfs URL 标记的检测回归packages/natives/test/issue-4812-repro.test.tsWindows 锁文件更新的暂存修复回归packages/natives/test/legacy-desktop-sentinel.test.ts前哨兵时代兼容 ABI 的校验。整体来看oh-my-pi/pi-natives的加载运行时把原生模块分发这件事拆成了可独立验证的纯函数变体选择、候选解析、暂存判定、解压、清理与一个副作用受限的主循环用环境变量PI_NATIVE_VARIANT、__PI_NATIVE_VARIANT_CACHE、PI_DEBUG_STARTUP、PI_COMPILED、XDG_DATA_HOME与版本哨兵把跨平台分发、更新安全与失败诊断统一到一个可测试的链路里。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
oh-my-pi Natives Addon Loader Runtime 深度解析：ESM 入口与已校验 `.node` 原生模块之间的运行时
oh-my-pi Natives Addon Loader Runtime 深度解析ESM 入口与已校验.node原生模块之间的运行时【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本篇技术指南围绕 oh-my-piomp仓库中的 docs/natives-addon-loader-runtime.md 展开聚焦oh-my-pi/pi-natives包的原生模块加载运行时。该运行时负责完成Node/Bun 导入 ESM 入口到加载并校验正确的pi_natives.platform-arch*.node插件之间的全部工作平台与 CPU 变体检测、候选路径解析、Windows 更新安全暂存、Bun 独立可执行文件的内嵌解压、版本哨兵校验以及可诊断的失败聚合。读完本文你将完整掌握该加载器的上下文构成、候选排序策略、AVX2 变体选择逻辑、内嵌清单解压的安全校验以及PI_DEBUG_STARTUP、PI_NATIVE_VARIANT等关键环境变量的实战用法。一、加载器在包结构中的位置oh-my-pi/pi-natives是一个通过 N-APInapi-rs暴露 Rust 能力的原生绑定包其package.json中的exports定义了三个实际为四个入口子路径.→./native/index.js完整 API 面模块求值时就加载原生插件./desktop→./native/desktop.js桌面会话按需加载./clipboard→./native/clipboard.js剪贴板按需加载./vcs→./native/vcs.js版本控制相关绑定见 packages/natives/package.json。其中真正承载加载逻辑的文件是 packages/natives/native/loader-state.js。它的文件头注释明确了职责边界Node importsnative/index.js 与 正确的pi_natives.platform-arch*.node被 require、校验并返回 之间的每一步都归属于这个模块——平台/变体检测、候选路径解析、Windows 暂存、内嵌解压、版本哨兵校验与聚合错误面。而index.js本身被刻意缩减为一次loadNative()调用加上MARKER_START/MARKER_END之间的生成式导出由 packages/natives/scripts/gen-enums.ts 在napi build后重写其文件头注释说明了这样拆分的动机把纯函数助手留在loader-state.js让它们可以不经副作用不触发 AVX2 检测、不探测文件系统就能被单元测试覆盖。二、入口与加载时机eager 与 lazy 两种模式加载器支持两种加载时机二者共用同一个loadNative()实现Eager 加载根入口。native/index.js在模块求值时直接执行const nativeBindings loadNative();见 packages/natives/native/index.js随后从返回的 bindings 中导出全部类与函数——AudioCapture、DesktopSession、DiffStream、EditStore、PtySession、Shell、VcsGitRepo以及countTokens、grep、highlightCode、pdfToMarkdown、executeShell等上百个函数和若干枚举。任何业务代码一旦 import 这个根入口原生插件就会立即被加载。Lazy 加载子入口。native/desktop.js与native/clipboard.js同样 import 了加载器但只在各自的公开包装函数内部调用loadNative()// desktop.js export function createDesktopSession(options) { DesktopSession ?? adaptDesktopSession(loadNative().DesktopSession); return new DesktopSession(options); }// clipboard.js export function copyToClipboard(text) { return loadNative().copyToClipboard(text); } export function readImageFromClipboard() { return loadNative().readImageFromClipboard(); }createDesktopSession的注释点明了设计意图在 computer worker 收到初始化消息之前不加载原生插件从而把桌面会话这类重功能从启动路径上剥离。两个文件都是首次调用时才真正 dlopen。不记忆化no memoization。文档明确一次成功的加载并不会被 JS 层记忆化。重复调用依赖 Node/Bun 运行时require(...)的原生模块缓存——同一路径二次 require 会命中缓存不会重复 dlopen而加载后的附加设置Tokio 运行时安装、旧版本缓存清理被设计为幂等或 best-effort可安全重复执行。三、加载上下文Loader Context的构成initLoaderContext()见 packages/natives/native/loader-state.js一次性完成所有路径、策略与变体决策使后续加载循环保持纯粹的 require/validate 流水线。其核心产出如下平台标签与版本哨兵platformTag${platform}-${process.arch}例如linux-x64、darwin-arm64versionSentinelExport由package.json#version推导的哨兵导出名__piNativesVversion其中非字母数字统一映射为下划线。当前仓库版本为18.1.14对应哨兵名__piNativesV18_1_14——该名字与 Rust 侧#[napi(js_name __piNativesV18_1_14)]的常量函数严格对应见 crates/pi-natives/src/lib.rs。仓库测试 packages/natives/test/windows-staging.test.ts 专门断言 Rust 的js_name与package.json版本始终同步防止发布脚本回归。目录解析nativeDir包本地native/目录即.node的常规安放处execDirprocess.execPath所在目录nativesDir默认~/.omp/natives仅当$XDG_DATA_HOME/omp目录存在时才改用$XDG_DATA_HOME/omp/natives见 loader-state.js 的getNativesDir()versionedDirnativesDir/packageVersion即每个包版本一个独立缓存目录userDataDir遗留编译产物目录Windows 上为%LOCALAPPDATA%/omp或~/AppData/Local/omp其他平台为~/.local/bin外加workspace/install/compiled 三种模式判定、可选的 leaf 目录、Windows 暂存策略、CPU 变体、文件名列表与有序候选路径。编译模式判定Compiled Binary。detectCompiledBinary()的判定顺序是存在非空的embeddedAddon清单 →PI_COMPILED环境变量被设置 →import.meta.url包含 Bun 内嵌标记$bunfs、~BUN或%7EBUN。loader-state.js 的头部注释解释了背景issue #823bun build --compile --define PI_COMPILEDtrue会替换裸标识符PI_COMPILED而非process.env.PI_COMPILED因此运行时读环境变量恒为undefined同时 ESM 的import.meta.url会被重写为 bunfs URL所以 URL 标记是可靠的编译模式信号之一。仓库中 packages/natives/test/issue-823-repro.test.ts 对这一行为做了回归覆盖。workspace 判定。非编译模式下若nativeDir不在node_modules路径段内则判定为 workspace 加载即从packages/natives/native/本地开发树运行。Windows 上的路径匹配大小写不敏感nativeDir.toLowerCase()后再匹配其他平台大小写敏感windows-staging.test.ts 用C:\Users\...与/tmp/NODE_MODULES/...等样例验证了这套分类逻辑。四、平台支持与 CPU 变体AVX2选择受支持的发布标签共 6 个平台标签说明linux-x64Linux / x86-64linux-arm64Linux / ARM64darwin-x64macOS / Inteldarwin-arm64macOS / Apple Siliconwin32-x64Windows / x86-64win32-arm64Windows / ARM64不支持的标签不会在加载一开始就报错而是先走完候选探测流程最后才抛出Unsupported platform错误详见失败诊断一节。x64 的 CPU 变体分为modern启用 AVX2与baseline通用指令集。选择优先级如下对应selectCpuVariant()见 loader-state.jsPI_NATIVE_VARIANTmodern|baseline环境变量覆盖永远优先非法值被忽略例如garbage会被当作未设置继续走后续检测私有继承环境变量__PI_NATIVE_VARIANT_CACHE当值合法modern/baseline时直接采用。该缓存由第一个完成检测的上下文主线程写入process.envBun worker 与子进程在 spawn 时继承process.env从而跳过重复检测——这是 issue #3238 的修复核心运行时 AVX2 检测最慢路径每个进程至多执行一次结果回写到缓存环境变量供后续 worker/子进程继承。检测失败或检测不到 AVX2则回落为baseline。非 x64 架构完全不参与变体逻辑selectCpuVariant返回{ variant: null, source: non-x64 }既不读取也不回写缓存。各平台检测手段detectAvx2Support()loader-state.jsLinux直接读取/proc/cpuinfo正则匹配\bavx2\bmacOS依次尝试绝对路径/usr/sbin/sysctl与裸sysctlPATH 可能不含/usr/sbin见 issue #3238查询machdep.cpu.leaf7_features与machdep.cpu.features两个键Windows在 Bun 运行时优先通过bun:ffi调用kernel32.dll的IsProcessorFeaturePresent(40)PF_AVX2_INSTRUCTIONS_AVAILABLE约 0.5ms相对 PowerShell 子进程约 270msNode 内嵌无bun:ffi时回退到 PowerShell——依次尝试pwsh.exePowerShell 7 / .NET Core能正确回答[System.Runtime.Intrinsics.X86.Avx2]::IsSupported与powershell.exeWindows PowerShell 5.1 / .NET Framework会抛 TypeNotFound从而把主机钉在 baseline 插件。子进程执行统一封装在runCommand()中优先Bun.spawnSync因为 Bun 的child_process.spawnSyncshim 在 macOS worker 线程中曾返回非零/null这正是 issue #3238 的失败模式再回退node:child_process。文件名列表由getAddonFilenames()生成运行时选择有序文件名modern x64pi_natives.tag-modern.nodepi_natives.tag-baseline.nodepi_natives.tag.nodebaseline x64pi_natives.tag-baseline.nodepi_natives.tag.node非 x64 / 无变体pi_natives.tag.node其中tag即platformTag。issue #3238 的教训正是worker 里检测失败导致文件名列表只剩[baseline, default]而磁盘上只有 modern 产物修复后由主线程缓存变体结论worker 继承modern文件名列表重新包含 modern 文件见 packages/natives/test/issue-3238-repro.test.ts。测试还断言PI_NATIVE_VARIANT覆盖路径不会污染缓存——用户可能按调用切换覆盖值子进程应自行重新评估该环境变量。五、候选路径排序Candidate OrderingresolveLoaderCandidates()loader-state.js对候选路径去重new Set(...)保留首次出现顺序并按运行模式生成不同顺序。5.1 已安装、非编译包顺序为leaf 包oh-my-pi/pi-natives-tag中每个选中文件名通过createRequire(import.meta.url).resolve(.../package.json)定位见resolveLeafPackageDir()每个文件名依次在包本地nativeDir、可执行文件目录execDir中探测。平台 leaf 包优先于可能过期的核心包产物workspace 加载则刻意跳过 leaf 解析。5.2 Windowsnode_modules暂存staging当满足平台为 Windows 非编译运行时 nativeDir含node_modules路径段三个条件时shouldStageNodeModulesAddon()loader-state.js候选顺序变为versionedDir中的每个文件名暂存目标leaf 包候选包本地与可执行目录候选。暂存动作由maybeStageNodeModulesAddon()执行把leafPackageDir ?? nativeDir下每个可用文件名拷贝到versionedDir的缺失缓存目标已存在的缓存文件保留不动。目录/拷贝失败被记录在错误列表正常探测继续。这一机制是 Windows 下bun install -g更新安全网issue #4812见 packages/natives/test/issue-4812-repro.test.ts当旧omp进程仍在运行时bun 无法覆盖node_modules/oh-my-pi/pi-natives/native/中被锁定的.node会留下旧二进制 新 ESM 包装的错位组合下次启动表现为工具深处的sym is not a function崩溃。暂存到版本固定的缓存目录后每个包版本拥有独立路径并发 omp 进程不会碰撞同一文件运行进程持有的是缓存副本的句柄bun 得以在后续更新中自由覆盖node_modules副本后续更新不会触发文件锁竞争。该策略在非 Windowsbun 原子改名无锁问题、workspace 开发否则bun --cwdpackages/natives run build的重建会被陈旧缓存副本遮蔽以及编译二进制由内嵌解压器负责填充versionedDir下被禁用。测试 windows-staging.test.ts 对上述门控规则与暂存路径必须排在 node_modules 路径之前的排序约束做了完整断言同时验证暂存路径中不会混入编译模式专用的 user-data 目录。5.3 编译运行时顺序为每个文件名在versionedDir、遗留 user-data 目录中探测每个文件名在包本地nativeDir、可执行文件目录中探测。若内嵌解压成功选中一个候选该路径会被前置到候选列表最前面编译模式下 Windows 暂存被禁用。六、内嵌清单与解压Embedded Manifest Extraction清单生成。native/embedded-addon.js在普通源码/发布核心状态下被重置为embeddedAddon null见 packages/natives/native/embedded-addon.js。构建流水线运行 packages/natives/scripts/embed-native.ts 后会生成真实清单其结构为platformTag与包versionarchivegzip 压缩 tar 归档引用format: tar.gz、filename、filePath文件名形如embedded-addons.tag.tar.gz位于native/目录files[]每个条目含variantmodern/baseline/default、仅 basename 的filename与size。脚本逻辑embed-native.ts按TARGET_PLATFORM/TARGET_ARCH默认取宿主确定平台标签x64 收集 modernbaseline 两个候选非 x64 收集 default 单候选available.length 0时报错并列出期望文件名随后用Bun.Archive以 gzip level 9 打包并把import archivePath from ../native/...tar.gz with { type: file }注入生成文件使编译后的独立可执行文件能内嵌该归档。--reset参数会把embedded-addon.js重置回null桩并清理归档用于发布前还原。解压条件。maybeExtractEmbeddedAddon()仅在编译模式 清单platformTag与当前平台一致 清单version与包版本一致 存在可选择的文件四者同时满足时执行。文件选择逻辑selectEmbeddedAddonFile()非 x64default其次清单首个文件modern x64modern其次baselinebaseline x64仅baseline。解压过程extractEmbeddedAddonArchive()loader-state.js创建versionedDirprepareNativeVersionDir还会utimes刷新目录时间戳防止并发清理误删进行中的缓存见NATIVE_CACHE_CLEANUP_GRACE_MS 10 * 60_000的 10 分钟宽限期若每个需要解压的清单文件都已是声明大小一致的常规文件直接复用跳过解压否则zlib.gunzipSync解压并手工解析 tar 头512 字节块、八进制长度字段、prefix/name拼接只接受清单允许列表中的 basename-only 常规文件条目拒绝路径穿越path.basename(filename) filename且不含/、\、拒绝非常规条目类型typeflag ! 0、校验文件大小、通过临时文件 rename原子写盘writeEmbeddedAddonFile临时名含 pid 与时间戳缺失条目、截断归档、不安全文件名、错误类型、尺寸不符都会抛出明确错误较旧的清单若没有 archive 字段仍可提供每个文件的独立filePath元数据走直接拷贝路径。解压错误被累积到错误列表加载器继续尝试普通候选路径——内嵌解压失败不会立即终止启动。七、候选校验与加载后配置对每个候选路径加载循环loadNative()loader-state.js执行启用时输出启动标记startupMarkerrequire(candidate)除非是 workspace 开发require 期望的包版本哨兵函数若插件提供__ompInstallTokioRuntime()则调用它best-effort 清理比当前版本更旧的语义化版本缓存目录返回 bindings。哨兵校验版本一致性证明。validateLoadedBindings()通过js_name编码版本的做法把一个物理上不可能的约束变成强校验不同发布的.node无法暴露当前加载器查找的哨兵符号从而把 Windows 锁文件更新导致的无声sym is not a function崩溃转化为加载期可操作错误。workspace 开发路径跳过校验是因为本地.node只有在bun --cwdpackages/natives run build重建后才获得重命名的哨兵——跳过校验让拉取后未重建的开发树也能启动。哨兵缺失时的错误诊断区分为两种模式这也是该模块最精妙的设计之一磁盘过期stale disk磁盘上的.node早于当前加载器构建但进程内没有旧模块驻留——错误提示重新安装reinstall以重新同步文件进程驻留过期resident old原地升级已把新发布写入磁盘而当前进程仍持有旧代插件驻留在动态加载器的原生模块缓存中require返回的仍是旧导出携带旧哨兵——此时磁盘其实已一致重装是无效操作错误信息明确指示重启进程restart。判据是读候选文件字节若其中包含当前哨兵字符串diskHasExpectedSentinel且 bindings 携带旧哨兵则为进程驻留过期 → 重启否则为磁盘过期 → 重装。此外还兼容一个前哨兵时代pre-sentinel的稳定核心 ABI当磁盘文件无当前哨兵、bindings 不含任何__piNativesV...键、且满足countTokens/executeShell/visibleWidth/DesktopSession(capture/execute/close) 等签名时isCompatiblePreSentinelNativeAddon允许旧发布桥接版本升级。加载器不校验全部公开导出。Tokio/Rayon 运行时安装。Rust 侧#[module_init]crates/pi-natives/src/lib.rs只安装崩溃诊断crash_handler::install()刻意不在动态加载器锁内派生运行时线程——在锁内急切地构建多线程运行时会在某些宿主上死锁新 worker 阻塞在加载器锁上而 init 线程仍持有该锁。可选的加载后钩子omp_install_tokio_runtime()js_name __ompInstallTokioRuntimelib.rs由 JS 加载器在dlopen返回后、任何异步原生调用之前恰好调用一次Windows 上先通过probe_spawnable_workers预探测可派生线程数std::thread::Builder::spawn返回io::Result不会像多线程 runtime 构建那样在提交限制下以 panic 中止进程再据此构建有界 Tokio 多线程运行时兜底 current-thread 运行时与有界 Rayon 全局线程池探测不到任何 worker 时打补丁的 Rayon 调用点保持串行。该钩子是 best-effort 的旧插件未提供该导出、或钩子失败时回退到 napi-rs 默认行为每个 CPU 一线程的默认 runtime。安装由AtomicBool保证进程内最多执行一次幂等。旧版本缓存清理。cleanupStaleNativeVersions()忽略读/删失败启动已成功绝不能被清理打断只删除解析为语义化版本且严格早于当前包版本的目录并受 10 分钟 mtime 宽限期保护当前/未来版本、预发布或非 semver 名称如not-a-version、普通文件全部保留。测试用临时目录构造了 stale、fresh、当前、未来版本与普通文件混合场景断言只有过期目录被移除windows-staging.test.ts。启动标记。设置PI_DEBUG_STARTUP后加载器会向 stderr 同步输出[startup] ...标记含native:loadNative:start、native:extractEmbeddedAddon:start、native:require:basename、native:tokioRuntime:installed/failed、native:loadNative:done。同步写 stderr 是刻意为之解压或 dlopen 挂起时:start标记也必须留下便于定位卡点。加载器无法依赖 pi-utils因此实现了一份本地副本。八、失败诊断当所有候选都失败时loadNative()区分两种错误面不支持的平台抛出Unsupported platform: tag附受支持列表与开 issue 指引If you need support for this platform, please open an issue.受支持平台加载失败抛出Failed to load pi_natives native addon for tagx64 时含变体如tag (modern)随后逐条列出每个候选/准备阶段的错误Tried:\n- candidate: error最后附加模式专属帮助。模式专属帮助buildHelpMessage()内容差异编译二进制列出期望的缓存路径versionedDir下的每个文件名建议删除该版本目录后重跑并打印 release 下载用的curl -fsSL ... -o ...命令模板已安装包建议重装oh-my-pi/pi-natives、本地宿主构建bun --cwdpackages/natives run build、以及显式目标构建bun scripts/bazel-natives.ts target --dest packages/natives/native后者对应仓库 scripts/bazel-natives.ts。九、完整生命周期文档以如下伪代码概括加载全流程entrypoint evaluates or lazy wrapper is invoked - initialize loader context - extract matching embedded archive, if any - otherwise stage Windows node_modules addon, if applicable - require candidates in deterministic order - validate sentinel outside workspace development - install optional post-load runtime - best-effort clean older version caches - return bindings - no success: throw unsupported-platform or aggregated load error值得强调的两个设计要点其一上下文初始化只发生一次loadNative()调用initLoaderContext()纯助手导入不会触发 AVX2 检测或文件系统探测测试零成本其二成功加载不做 JS 层记忆化重复调用依赖运行时require缓存而加载后设置均幂等或 best-effort天然适合 lazy 包装器的首次调用即加载语义。十、测试与回归保障加载器的正确性由多个针对性回归测试钉住可作阅读源码的入口packages/natives/test/windows-staging.test.tsWindows 暂存门控规则、候选排序、大小写不敏感路径分类、过期缓存清理、Rust 哨兵与包版本同步断言packages/natives/test/issue-3238-repro.test.ts跨 worker 上下文的变体解析、PI_NATIVE_VARIANT覆盖优先于缓存、垃圾值忽略、非 x64 不污染缓存、modern 文件名列表回归packages/natives/test/issue-823-repro.test.ts编译模式下PI_COMPILED/bunfs URL 标记的检测回归packages/natives/test/issue-4812-repro.test.tsWindows 锁文件更新的暂存修复回归packages/natives/test/legacy-desktop-sentinel.test.ts前哨兵时代兼容 ABI 的校验。整体来看oh-my-pi/pi-natives的加载运行时把原生模块分发这件事拆成了可独立验证的纯函数变体选择、候选解析、暂存判定、解压、清理与一个副作用受限的主循环用环境变量PI_NATIVE_VARIANT、__PI_NATIVE_VARIANT_CACHE、PI_DEBUG_STARTUP、PI_COMPILED、XDG_DATA_HOME与版本哨兵把跨平台分发、更新安全与失败诊断统一到一个可测试的链路里。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
