Orca：协调编码代理，同时保留清楚的工作记录
阅读 Orca 原生运行时检查器，定位终端启动错误
跟踪 Node 与 Electron 检查、条件重建和新进程复核，理解 ensure-native-runtime.mjs 的真实副作用。
你将学会
- 先选对运行时
- 普通检查可能重建依赖
- 使用新进程再次确认
开始前需要
- 基本命令行与配置阅读能力
- 能够在独立且获准的环境中试验
记录主机、工作树和验收证据，不自动合并分支，也不删除尚未审阅的工作。
先看结论
- 普通 ensure 可能修改依赖。
- Node 和 Electron 分开检查。
- 原生加载失败后新进程很重要。
先选对运行时
readRuntimeArg 接受行内或分开的 --runtime=node、--runtime=electron，不支持的选择以状态 2 退出。package 的测试命令在 Vitest 前先对 Node 运行检查。
检查列表包含 node-pty，在 Windows 增加特定原生模块。其他位置的 JavaScript 导入成功，并不能证明这些二进制依赖与当前运行时、平台和架构匹配。
普通检查可能重建依赖
ensureNodeRuntime 先检查加载和修补版 node-pty 的重建条件，两者均满足才直接返回；否则选择模块重建后再验证。Electron 分支需要时调用原生依赖重建脚本。
所以普通 ensure 命令不能称为只读诊断，它可能改变安装依赖。子进程 --check-only 分支只收集失败并退出，但本章没有完整审计它调用的每个辅助函数。
使用新进程再次确认
runNodeCheck 启动新 Node 进程，因为失败的原生模块加载可能污染当前进程；runElectronCheck 则以 ELECTRON_RUN_AS_NODE=1 启动安装的 Electron，重建后再次检查。
源码还比较 Electron 包版本与安装二进制版本，并检查可执行路径。应先看这些诊断，再把终端错误归因于模型。本次仅阅读控制流，没有执行重建或上游测试。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
确认错误属于 Node 还是 Electron。
- 2
重建前阅读原生模块诊断。
- 3
获准重建后在正确运行时重新验证。
可复制示例
运行时参数 → Node / Electron
首次加载与补丁条件
必要时重建原生依赖
新进程复核 → 成功或 exit 1常见问题
检查器只是诊断吗？
普通路径可能重建依赖，需理解并授权其影响。
Node 检查成功证明桌面兼容吗？
不能，Electron 有单独执行与二进制检查。
资料来源
- Orca / config/scripts/ensure-native-runtime.mjs来源核查 2026-09-18
- Orca / package.json来源核查 2026-09-18