将 JS/TS 热路径移植到 pi-nativesoh-my-pi 的 N-API 原生化贡献指南【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi在 oh-my-pi⌥ Coding agent with the IDE wired in中crates/pi-natives是承载 PDF 转换、音频、grep、剪贴板、图像处理、语法高亮、PTY 与 shell 操作的 Rust 原生绑定层通过 N-API 向oh-my-pi/pi-natives包暴露能力。本文基于仓库中的贡献者指南 docs/porting-to-natives.md完整梳理把被测量确认的 JS/TS 热路径移植为 Rust 原生实现的全过程从是否值得移植的判断标准、包结构与构建分工到 N-API 边界设计、任务调度与取消机制、六步端到端检查清单、常见失败模式与完成标准。读完本文你将掌握在 oh-my-pi 中新增一个原生导出项并安全发布它的完整实战方法。移植决策什么时候该用 Rust什么时候该留在 JS移植不是为了快而快。仓库指南给出的判断标准非常明确当原生代码能够消除已被实测证明的 CPU 开销、阻塞型 I/O、分配开销或平台集成开销且边界可以保持面向数据data-oriented时才值得移植。反之当工作高度依赖以下条件时应保留 JS 实现JS 对象身份object identity动态 import回调进应用状态callbacks into application state原生转换开销会抵消收益native conversion cost erases the gain。指南特别强调必须从行为兼容的 JS 基线baseline和代表性输入开始。一个存在但更慢、或行为有差异的原生导出不能算成功的移植——存在但不合格比没有更糟因为它会悄悄改变调用方语义。当前包结构与构建分工oh-my-pi/pi-natives的入口设计在 packages/natives/package.json 的exports字段中完整呈现。需要明确该包没有packages/natives/src/module这类包装层其入口点是入口文件说明eager 根入口native/index.js 生成的native/index.d.ts加载 addon 并显式导出所有符号lazy desktop 包装native/desktop.js/desktop.d.ts延迟加载lazy clipboard 包装native/clipboard.js/clipboard.d.ts延迟加载lazy vcs 包装native/vcs.js/vcs.d.tsoh-my-pi/pi-natives/vcs延迟加载其中 vcs 子路径暴露的是后端无关的Vcs*仓库 API18.0.9 引入VcsGitRepo.mergeBase()随后在 18.0.10 加入通过git()/repo()/require()/requireGit()返回VcsGitRepo/VcsRepo/VcsJjWorkspace句柄覆盖 refs 与 status、diff、暂存、提交、分支、worktree、patch 应用、stash、cherry-pick以及 CLI 支撑的 push/fetch/clone全部支持取消此外还有 JS 侧的isVcsError错误助手以及基于VcsRepo.watchTarget()的watch(repo, onChange)head 变更监视器。可在 packages/natives/native/vcs.js 中看到这些包装的真实实现例如isVcsError通过error.name VcsError识别原生构造的错误对象跨语言构造的错误无法使用instanceof身份判断只能依赖 name。两条构建命令用途截然不同务必区分# 1) 为宿主host运行 napi-rs安装本地变体 addon 与生成的声明 # 并重新生成显式 ESM/enum 导出。当 Rust 公共类型表面发生变化时用它。 bun --cwdpackages/natives run build:bindings # 2) 调用 scripts/bazel-natives.ts host --dest native。 # host 目标默认走本地 cargo/napi-rs 后端构建 # 设置 OMP_NATIVE_BUILD_BACKENDbazel 才切换到 bazel但不再重新生成声明。 bun --cwdpackages/natives run buildbuild:bindings的完整实现位于 packages/natives/scripts/build-bindings.ts它通过 napi-rs CLI 构建crates/pi-natives--dts index.d.ts、--no-js把产物 addon 归一化安装到native/目录Windows 上被占用的 DLL 走先删后改名的原子替换策略再调用gen-enums.ts生成显式导出。脚本还处理了平台细节Windows 上自动通过 vswhere 定位 VS 的 CMake/Ninjax64 按变体固定-C target-cpumodern 对应 x86-64-v3、baseline 对应 x86-64-v2Windows 上额外追加-C target-featurecrt-static静态链接 MSVC CRT。发布构建Release则走 Bazel 目标在各平台叶子包leaf packages中发布.node文件核心发布重写逻辑会移除 addon 并注入由gen-npm-packages.ts中的LEAF_TARGETS生成的同步lockstep可选依赖。设计 N-API 边界五个要点边界设计直接决定移植的成败仓库指南给出如下顺序化建议实现放归属 crate实现放crates/pi-natives/src/module.rs新模块在crates/pi-natives/src/lib.rs注册pub mod module;。当前 lib.rs 已注册 appearance、ast、audio、clipboard、diff、edit、fd、glob、grep、highlight、html、pdf、sixel、snapcompact、svg、utok、vcs、pty、shell、task 等模块。保持纯函数核心只要可行把计算放在普通 Rust 函数中再暴露一层薄的#[napi]边界。偏好拥有的 N-API 兼容值String、向量、类型化数组以及#[napi(object)]的 option/result 结构体。避免借用型公共输入——其生命周期无法跨 N-API 工作边界。命名遵循默认转换让 napi-rs 应用默认的 snake_case→camelCase 名称转换除非确实需要公共名称时才用js_name。保持 JS 契约不变null/undefined 区分、顺序、error 与 result 语义、回调时机、同步 vs Promise 行为都必须原样保留。任务调度与取消Work scheduling and cancellation这是移植中最容易踩坑的部分crates/pi-natives/src/task.rs 给出了完整的实现依据CPU 密集或阻塞工作用task::blocking(tag, cancel_token, work)。它返回AsyncTaskJS 侧表现为PromiseT会对工作做性能剖析profile_region并在 panic 跨过 async-work FFI 边界之前捕获它——Blocking::compute在catch_unwind内执行工作闭包任何 panic 都会被映射为带native task \{tag} panicked: {message}消息的GenericFailure绝不会让 unwind 逃逸进 napi 的extern C 帧导致宿主进程强制中止。task.rs 的测试覆盖了字符串 panic、格式化 panic、非字符串 panic payload、甚至Drop 时自身会 panic 的 payloadDropBomb这类病态场景。Tokio 异步 I/O用task::future(env, tag, future)通过Env::spawn_future返回PromiseRaw。超时与中止当公共 options 暴露timeoutMs或AbortSignal时构建task::CancelToken::new(timeout_ms, signal)并在阻塞循环的有意义的间隔处调用heartbeat()。取消是协作式的——一个从不被检查的 token 不会停止任何工作。CancelToken::new内部会用signal.on_abort注册 abort tokenheartbeat()返回Result()被取消时返回错误。禁止在模块初始化时创建 runtime 或 worker 池。JS 加载器会在动态加载器锁释放后的可选 post-load 步骤__ompInstallTokioRuntime中完成安装该导出可见于 packages/natives/native/index.js 的函数导出块。此外调度/错误形状应该与某个既有导出保持一致而不是引入第二套约定。端到端检查清单六步第 1 步实现并暴露添加 Rust 逻辑必要时为纯不变量补充聚焦的 Rust 测试添加#[napi]项及 object/enum 类型在crates/pi-natives/src/lib.rs注册新模块若移植用到其他 first-party crate把依赖加入crates/pi-natives/Cargo.toml以及原生构建所需的 build-system 输入。当前 Cargo.toml 已依赖 pi-vcs、pi-ast、pi-diff、pi-edit、pi-iso、pi-shell、pi-voice、pi-walker 等多个内部 crate平台相关依赖Linux 的 x11rb/zbus/pipewire、macOS 的 objc2 系列、Windows 的 windows-sys/clipboard-win/uiautomation均按 target 条件组织。第 2 步重新生成并检查绑定bun --cwdpackages/natives run build:bindings然后逐项验证native/index.d.ts包含预期的 JS 名称、精确的输入/结果类型、回调形状、同步/Promise 返回native/index.js中标记的生成块// --- generated native exports (do not edit) ---与// --- end generated native exports ---之间包含该 class/function 的导出变更的枚举同时具备声明与字面量运行时对象。gen-enums.ts通过读取index.d.ts顶层的export declare class、export declare function与 enum 声明来派生导出见 packages/natives/scripts/gen-enums.ts。一个未出现在声明中的项不会成为具名根 ESM 导出。注意 napi-rs 的#[napi(string_enum)]在 .d.ts 中只生成 TS-only 的const enum没有 JS 运行时值——这正是gen-enums.ts存在的原因它在 index.js 中为每个 enum 生成字面量运行时对象例如GrepOutputMode { Content: content, ... }并把 .d.ts 中的const enum改写为export declare enum以便字符串字面量可赋值。第 3 步仅在确有理由时添加懒加载入口根入口会 eager 加载 addon。如果某个 worker 必须在不付出该启动成本的情况下 import就照抄 desktop/clipboard 模式一个小的 JS 包装在导出的函数内部调用loadNative()参见 packages/natives/native/desktop.jscreateDesktopSession直到真正构造时才执行loadNative().DesktopSession配套的.d.tsimport/reexport 根类型package.json#exports同时提供types与import路径。不要仅仅为了给生成的根导出改名而添加包装层。第 4 步干净地迁移消费者从oh-my-pi/pi-natives导入生成的根符号或有意设计的懒加载子路径在边界用例上把结果与错误和 JS 基线对比在同一个变更中切换所有目标调用方并删除过时实现不允许新旧并存当原生原语不拥有用户可见策略与渲染逻辑时把策略与渲染保留在消费者侧。第 5 步对代表性工作做基准测试把可复现的基准放在所属包中packages/natives/bench、packages/tui/bench、packages/coding-agent/bench或其他既有包的 bench 目录在同一进程内用完全相同的预处理输入分别运行 JS 与原生实现。当调用方可以复用 setup 时把 setup/转换与计时操作分开。仓库指南给出的模板如下const ITERATIONS 2_000; function bench(name: string, fn: () void): number { const start Bun.nanoseconds(); for (let i 0; i ITERATIONS; i) fn(); const elapsedMs (Bun.nanoseconds() - start) / 1e6; console.log( ${name}: ${elapsedMs.toFixed(2)}ms (${(elapsedMs / ITERATIONS).toFixed(6)}ms/op), ); return elapsedMs; } bench(feature/js, () jsImpl(sample)); bench(feature/native, () nativeImpl(sample));对于返回 Promise 的操作使用 async 基准循环并await每一次调用不要只对 Promise 创建本身计时那测的是调度开销而非真实工作。仓库现有基准示例可参考 packages/natives/bench/grep.ts 与 packages/natives/bench/text.ts。第 6 步验证实际加载的产物针对刚构建的 addon 运行窄场景。诊断候选不匹配时检查加载器上报的候选路径bun -e import { createRequire } from node:module; const require createRequire(import.meta.url); const mod require(process.argv[1]); console.log(Object.keys(mod).sort()) -- /path/to/pi_natives.tag[-variant].node确认导出与包版本哨兵sentinel如__piNativesV18_1_17都存在。不要为必需的导出添加可选的消费者检查来掩盖产物不匹配——那是把问题埋起来而不是修掉它。常见失败模式与排查过时变体或缓存胜出Stale variant or cache winsx64 候选顺序为modern 主机按 modern → baseline → 无后缀baseline 主机按 baseline → 无后缀。此外编译后暂存的 Windows 加载也可能在包路径之前命中getNativesDir()/version。只删除加载器诊断指出的过时本地产物/缓存后重建。加载器在成功加载后会尽力删除旧版本合法发布的缓存目录但故意保留当前版本目录——所以当前版本的陈旧二进制只能手动清理。声明变了但发布的 addon 没变build:bindings负责声明生成build负责 Bazel host 产物CI/发布目标负责跨平台产物。三者各管一段既要检查生成的两个源码控制产物index.d.ts / index.js也要检查场景实际用到的二进制。同版本但不完整的 addon哨兵只能证明发布版本不能证明完整导出集。本地产生的同版本二进制可能通过加载却缺少新生成的成员。对实际候选执行Object.keys检查并重建它不要削弱调用方。运行时枚举缺失Runtime enum missingnapi-rs 的 enum 声明本身不提供根的运行时字面量对象。运行build:bindings并检查生成块。若gen-enums.ts无法解析声明形状修复生成器本身而不是手工编辑它拥有的标记块。错误的同步/异步假设以native/index.d.ts为权威。例如renderSnapcompactPng返回Promisestring而snapcompactSupportedChars是同步的。改变调用风格的移植必须是有意的消费者迁移不能悄悄发生。完成标准一次移植只有满足以下全部条件才算完成生成的声明与 ESM 导出和 Rust API 一致目标消费者确实在使用它过时的 JS 代码已被删除针对刚构建的 addon 的一次真实调用成功代表性对比显示行为与性能均可接受。这套标准的闭环价值在于行为与性能双验证 产物级验证它把移植成功从能跑提升到可发布、可维护、可回退的可信状态。对 oh-my-pi 这样同时依赖 Bazel 发布流水线、napi-rs 声明生成与多平台叶子包的工程而言按本文的决策、边界设计、六步清单与失败排查路径走一遍是让每个pi-natives新导出项安全落地的可复用方法论。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
将 JS/TS 热路径移植到 pi-natives：oh-my-pi 的 N-API 原生化贡献指南
将 JS/TS 热路径移植到 pi-nativesoh-my-pi 的 N-API 原生化贡献指南【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi在 oh-my-pi⌥ Coding agent with the IDE wired in中crates/pi-natives是承载 PDF 转换、音频、grep、剪贴板、图像处理、语法高亮、PTY 与 shell 操作的 Rust 原生绑定层通过 N-API 向oh-my-pi/pi-natives包暴露能力。本文基于仓库中的贡献者指南 docs/porting-to-natives.md完整梳理把被测量确认的 JS/TS 热路径移植为 Rust 原生实现的全过程从是否值得移植的判断标准、包结构与构建分工到 N-API 边界设计、任务调度与取消机制、六步端到端检查清单、常见失败模式与完成标准。读完本文你将掌握在 oh-my-pi 中新增一个原生导出项并安全发布它的完整实战方法。移植决策什么时候该用 Rust什么时候该留在 JS移植不是为了快而快。仓库指南给出的判断标准非常明确当原生代码能够消除已被实测证明的 CPU 开销、阻塞型 I/O、分配开销或平台集成开销且边界可以保持面向数据data-oriented时才值得移植。反之当工作高度依赖以下条件时应保留 JS 实现JS 对象身份object identity动态 import回调进应用状态callbacks into application state原生转换开销会抵消收益native conversion cost erases the gain。指南特别强调必须从行为兼容的 JS 基线baseline和代表性输入开始。一个存在但更慢、或行为有差异的原生导出不能算成功的移植——存在但不合格比没有更糟因为它会悄悄改变调用方语义。当前包结构与构建分工oh-my-pi/pi-natives的入口设计在 packages/natives/package.json 的exports字段中完整呈现。需要明确该包没有packages/natives/src/module这类包装层其入口点是入口文件说明eager 根入口native/index.js 生成的native/index.d.ts加载 addon 并显式导出所有符号lazy desktop 包装native/desktop.js/desktop.d.ts延迟加载lazy clipboard 包装native/clipboard.js/clipboard.d.ts延迟加载lazy vcs 包装native/vcs.js/vcs.d.tsoh-my-pi/pi-natives/vcs延迟加载其中 vcs 子路径暴露的是后端无关的Vcs*仓库 API18.0.9 引入VcsGitRepo.mergeBase()随后在 18.0.10 加入通过git()/repo()/require()/requireGit()返回VcsGitRepo/VcsRepo/VcsJjWorkspace句柄覆盖 refs 与 status、diff、暂存、提交、分支、worktree、patch 应用、stash、cherry-pick以及 CLI 支撑的 push/fetch/clone全部支持取消此外还有 JS 侧的isVcsError错误助手以及基于VcsRepo.watchTarget()的watch(repo, onChange)head 变更监视器。可在 packages/natives/native/vcs.js 中看到这些包装的真实实现例如isVcsError通过error.name VcsError识别原生构造的错误对象跨语言构造的错误无法使用instanceof身份判断只能依赖 name。两条构建命令用途截然不同务必区分# 1) 为宿主host运行 napi-rs安装本地变体 addon 与生成的声明 # 并重新生成显式 ESM/enum 导出。当 Rust 公共类型表面发生变化时用它。 bun --cwdpackages/natives run build:bindings # 2) 调用 scripts/bazel-natives.ts host --dest native。 # host 目标默认走本地 cargo/napi-rs 后端构建 # 设置 OMP_NATIVE_BUILD_BACKENDbazel 才切换到 bazel但不再重新生成声明。 bun --cwdpackages/natives run buildbuild:bindings的完整实现位于 packages/natives/scripts/build-bindings.ts它通过 napi-rs CLI 构建crates/pi-natives--dts index.d.ts、--no-js把产物 addon 归一化安装到native/目录Windows 上被占用的 DLL 走先删后改名的原子替换策略再调用gen-enums.ts生成显式导出。脚本还处理了平台细节Windows 上自动通过 vswhere 定位 VS 的 CMake/Ninjax64 按变体固定-C target-cpumodern 对应 x86-64-v3、baseline 对应 x86-64-v2Windows 上额外追加-C target-featurecrt-static静态链接 MSVC CRT。发布构建Release则走 Bazel 目标在各平台叶子包leaf packages中发布.node文件核心发布重写逻辑会移除 addon 并注入由gen-npm-packages.ts中的LEAF_TARGETS生成的同步lockstep可选依赖。设计 N-API 边界五个要点边界设计直接决定移植的成败仓库指南给出如下顺序化建议实现放归属 crate实现放crates/pi-natives/src/module.rs新模块在crates/pi-natives/src/lib.rs注册pub mod module;。当前 lib.rs 已注册 appearance、ast、audio、clipboard、diff、edit、fd、glob、grep、highlight、html、pdf、sixel、snapcompact、svg、utok、vcs、pty、shell、task 等模块。保持纯函数核心只要可行把计算放在普通 Rust 函数中再暴露一层薄的#[napi]边界。偏好拥有的 N-API 兼容值String、向量、类型化数组以及#[napi(object)]的 option/result 结构体。避免借用型公共输入——其生命周期无法跨 N-API 工作边界。命名遵循默认转换让 napi-rs 应用默认的 snake_case→camelCase 名称转换除非确实需要公共名称时才用js_name。保持 JS 契约不变null/undefined 区分、顺序、error 与 result 语义、回调时机、同步 vs Promise 行为都必须原样保留。任务调度与取消Work scheduling and cancellation这是移植中最容易踩坑的部分crates/pi-natives/src/task.rs 给出了完整的实现依据CPU 密集或阻塞工作用task::blocking(tag, cancel_token, work)。它返回AsyncTaskJS 侧表现为PromiseT会对工作做性能剖析profile_region并在 panic 跨过 async-work FFI 边界之前捕获它——Blocking::compute在catch_unwind内执行工作闭包任何 panic 都会被映射为带native task \{tag} panicked: {message}消息的GenericFailure绝不会让 unwind 逃逸进 napi 的extern C 帧导致宿主进程强制中止。task.rs 的测试覆盖了字符串 panic、格式化 panic、非字符串 panic payload、甚至Drop 时自身会 panic 的 payloadDropBomb这类病态场景。Tokio 异步 I/O用task::future(env, tag, future)通过Env::spawn_future返回PromiseRaw。超时与中止当公共 options 暴露timeoutMs或AbortSignal时构建task::CancelToken::new(timeout_ms, signal)并在阻塞循环的有意义的间隔处调用heartbeat()。取消是协作式的——一个从不被检查的 token 不会停止任何工作。CancelToken::new内部会用signal.on_abort注册 abort tokenheartbeat()返回Result()被取消时返回错误。禁止在模块初始化时创建 runtime 或 worker 池。JS 加载器会在动态加载器锁释放后的可选 post-load 步骤__ompInstallTokioRuntime中完成安装该导出可见于 packages/natives/native/index.js 的函数导出块。此外调度/错误形状应该与某个既有导出保持一致而不是引入第二套约定。端到端检查清单六步第 1 步实现并暴露添加 Rust 逻辑必要时为纯不变量补充聚焦的 Rust 测试添加#[napi]项及 object/enum 类型在crates/pi-natives/src/lib.rs注册新模块若移植用到其他 first-party crate把依赖加入crates/pi-natives/Cargo.toml以及原生构建所需的 build-system 输入。当前 Cargo.toml 已依赖 pi-vcs、pi-ast、pi-diff、pi-edit、pi-iso、pi-shell、pi-voice、pi-walker 等多个内部 crate平台相关依赖Linux 的 x11rb/zbus/pipewire、macOS 的 objc2 系列、Windows 的 windows-sys/clipboard-win/uiautomation均按 target 条件组织。第 2 步重新生成并检查绑定bun --cwdpackages/natives run build:bindings然后逐项验证native/index.d.ts包含预期的 JS 名称、精确的输入/结果类型、回调形状、同步/Promise 返回native/index.js中标记的生成块// --- generated native exports (do not edit) ---与// --- end generated native exports ---之间包含该 class/function 的导出变更的枚举同时具备声明与字面量运行时对象。gen-enums.ts通过读取index.d.ts顶层的export declare class、export declare function与 enum 声明来派生导出见 packages/natives/scripts/gen-enums.ts。一个未出现在声明中的项不会成为具名根 ESM 导出。注意 napi-rs 的#[napi(string_enum)]在 .d.ts 中只生成 TS-only 的const enum没有 JS 运行时值——这正是gen-enums.ts存在的原因它在 index.js 中为每个 enum 生成字面量运行时对象例如GrepOutputMode { Content: content, ... }并把 .d.ts 中的const enum改写为export declare enum以便字符串字面量可赋值。第 3 步仅在确有理由时添加懒加载入口根入口会 eager 加载 addon。如果某个 worker 必须在不付出该启动成本的情况下 import就照抄 desktop/clipboard 模式一个小的 JS 包装在导出的函数内部调用loadNative()参见 packages/natives/native/desktop.jscreateDesktopSession直到真正构造时才执行loadNative().DesktopSession配套的.d.tsimport/reexport 根类型package.json#exports同时提供types与import路径。不要仅仅为了给生成的根导出改名而添加包装层。第 4 步干净地迁移消费者从oh-my-pi/pi-natives导入生成的根符号或有意设计的懒加载子路径在边界用例上把结果与错误和 JS 基线对比在同一个变更中切换所有目标调用方并删除过时实现不允许新旧并存当原生原语不拥有用户可见策略与渲染逻辑时把策略与渲染保留在消费者侧。第 5 步对代表性工作做基准测试把可复现的基准放在所属包中packages/natives/bench、packages/tui/bench、packages/coding-agent/bench或其他既有包的 bench 目录在同一进程内用完全相同的预处理输入分别运行 JS 与原生实现。当调用方可以复用 setup 时把 setup/转换与计时操作分开。仓库指南给出的模板如下const ITERATIONS 2_000; function bench(name: string, fn: () void): number { const start Bun.nanoseconds(); for (let i 0; i ITERATIONS; i) fn(); const elapsedMs (Bun.nanoseconds() - start) / 1e6; console.log( ${name}: ${elapsedMs.toFixed(2)}ms (${(elapsedMs / ITERATIONS).toFixed(6)}ms/op), ); return elapsedMs; } bench(feature/js, () jsImpl(sample)); bench(feature/native, () nativeImpl(sample));对于返回 Promise 的操作使用 async 基准循环并await每一次调用不要只对 Promise 创建本身计时那测的是调度开销而非真实工作。仓库现有基准示例可参考 packages/natives/bench/grep.ts 与 packages/natives/bench/text.ts。第 6 步验证实际加载的产物针对刚构建的 addon 运行窄场景。诊断候选不匹配时检查加载器上报的候选路径bun -e import { createRequire } from node:module; const require createRequire(import.meta.url); const mod require(process.argv[1]); console.log(Object.keys(mod).sort()) -- /path/to/pi_natives.tag[-variant].node确认导出与包版本哨兵sentinel如__piNativesV18_1_17都存在。不要为必需的导出添加可选的消费者检查来掩盖产物不匹配——那是把问题埋起来而不是修掉它。常见失败模式与排查过时变体或缓存胜出Stale variant or cache winsx64 候选顺序为modern 主机按 modern → baseline → 无后缀baseline 主机按 baseline → 无后缀。此外编译后暂存的 Windows 加载也可能在包路径之前命中getNativesDir()/version。只删除加载器诊断指出的过时本地产物/缓存后重建。加载器在成功加载后会尽力删除旧版本合法发布的缓存目录但故意保留当前版本目录——所以当前版本的陈旧二进制只能手动清理。声明变了但发布的 addon 没变build:bindings负责声明生成build负责 Bazel host 产物CI/发布目标负责跨平台产物。三者各管一段既要检查生成的两个源码控制产物index.d.ts / index.js也要检查场景实际用到的二进制。同版本但不完整的 addon哨兵只能证明发布版本不能证明完整导出集。本地产生的同版本二进制可能通过加载却缺少新生成的成员。对实际候选执行Object.keys检查并重建它不要削弱调用方。运行时枚举缺失Runtime enum missingnapi-rs 的 enum 声明本身不提供根的运行时字面量对象。运行build:bindings并检查生成块。若gen-enums.ts无法解析声明形状修复生成器本身而不是手工编辑它拥有的标记块。错误的同步/异步假设以native/index.d.ts为权威。例如renderSnapcompactPng返回Promisestring而snapcompactSupportedChars是同步的。改变调用风格的移植必须是有意的消费者迁移不能悄悄发生。完成标准一次移植只有满足以下全部条件才算完成生成的声明与 ESM 导出和 Rust API 一致目标消费者确实在使用它过时的 JS 代码已被删除针对刚构建的 addon 的一次真实调用成功代表性对比显示行为与性能均可接受。这套标准的闭环价值在于行为与性能双验证 产物级验证它把移植成功从能跑提升到可发布、可维护、可回退的可信状态。对 oh-my-pi 这样同时依赖 Bazel 发布流水线、napi-rs 声明生成与多平台叶子包的工程而言按本文的决策、边界设计、六步清单与失败排查路径走一遍是让每个pi-natives新导出项安全落地的可复用方法论。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考