nodeJs.runtime — 轻量 Node.js 运行时

用于直接运行 Node.js CLI、npm-cli.js 或独立 JavaScript 脚本，不启动旧 nodeJs RPC 环境。

导入不创建进程、不下载，不分配端口，不修改父进程环境或第三方模块。
resolve(options) 只定位、运行校验现有 Node；ensure(options) 必要时准备固定版本便携 Node。
返回纯描述符：nodeExePath/npmCliJsPath/nodeDir/version/arch/source，可跨线程传值。
popen(runtime,cmdArgs,startInfo) 返回原生 process.popen，UTF-8；不隐式安装。

快速上手

import nodeJs.runtime;

var runtime,err,code = nodeJs.runtime.ensure();
if(!runtime) return null,err,code;

var pipe,err = nodeJs.runtime.popen(runtime,["-p","process.versions.node"]);
if(!pipe) return null,err;
var text,stderr,exitCode = pipe.readAll(); // readAll 默认负责 close
return {text=text;stderr=stderr;exitCode=exitCode};

resolve/ensure 校验会短暂运行候选 node.exe，不是纯 PE 元数据读取，也不是样本沙箱；不要把不可信程序冒充运行时传入。

定位与版本策略

默认依次检查 NODE_EXE、PATH、Windows 标准 Node 安装目录、受管便携目录。候选必须能运行，实际架构匹配，默认要求同目录下有 node_modules/npm/bin/npm-cli.js。

选项	含义
`nodeExePath`	显式路径；仅校验此候选，失败不回退或替换
`useSystem=false`	禁用环境变量、PATH 和系统目录复用，只用受管便携运行时
`version`	便携版的固定 `x.y.z`，默认 `24.22.2`；不接受 latest
`arch`	实际 Node 进程架构，默认 x64（32 位 Windows 为 ia32），也可指定 arm64；x86 作为 ia32 别名
`requireNpm=false`	接受独立 node.exe，描述符的 npmCliJsPath 可能为 null
`accept(runtime)`	调用者的版本兼容判断；返回假值拒绝此候选
`installRoot`	默认 `io.appData("aardio/std/nodeJs/runtime")`
`probeTimeout`	每个候选运行校验的超时，默认 5000ms，上限 60000ms
`stop()`	阶段间/接收过程中检查取消，返回真值取消

**version 只固定便携下载版本，不代表系统候选必须等于该版本。** 使用者根据实际工具要求提供 accept；本库不实现 npm semver 求解器，也不隐式升级系统 Node。

例如，只接受指定版本：

import nodeJs.runtime;
var runtime,err,code = nodeJs.runtime.ensure({
    version="24.22.2";
    accept=lambda(rt) rt.version=="24.22.2";
});
return runtime,err,code;

便携准备与完整性

ensure 先复用兼容候选，确有缺口才执行：

取得按目标路径隔离的安装锁并重新检查。
从 Node 官方 HTTPS SHASUMS256.txt 取得对应 ZIP 的 SHA256；也可传入已从可信来源冻结的 sha256。
归档下载到 installRoot/.cache/，校验后才解压到短暂存目录。
预检 Windows 路径长度，确认每个归档文件已解出，实际运行验证版本/架构及 npm 入口。
写入 .runtime.json 校验记录，再提交完整目录；失败不标 ready，不替换已有兼容目录。

可选 downloadUrl 只改变 ZIP 传输地址，必须同时指定可信 SHA256。onProgress(received,total) 接收累计字节数。取消会清除本次不完整归档和暂存目录；已校验归档保留，重复准备无需重新下载。坏 hash 返回 integrity，保留归档供诊断；确认原因后可删除对应 .cache/*.zip 再重试。

下载/解压/安装锁是同步操作，建议在工作线程执行。超时选项不是整个安装的统一 deadline。路径过长会明确失败，应改用更短的 installRoot，不会把部分 npm 当成成功。未完成校验提交的受管目录不会被 resolve 接受。

默认不要求管理员权限，不写系统 PATH、NODE_PATH、npm prefix 或 .npmrc，不修改其它 Node 安装。

启动参数、环境和 npm

cmdArgs/startInfo 遵循 process.popen：单字符串是命令行文本，数组/表是字面参数；不预加引号、不修改调用者数组。子环境和工作目录通过 STARTUPINFO 传递，不改父环境。

import nodeJs.runtime;
var rt,err = nodeJs.runtime.resolve();
if(!rt) return null,err;

// 不经过 npm.cmd/cmd.exe，不初始化 Node RPC。
var p,err = nodeJs.runtime.popen(rt,[rt.npmCliJsPath,"--version"],{
    workDir=io.fullpath("/");
    environment={NPM_CONFIG_PREFIX=io.appData("myApp/npm")};
});
if(!p) return null,err;
return p.readAll();

readAll 首返混合 stdout/stderr；JSON 协议或长任务需要分别、有界排空双管道。不要先把 stdout 读到 EOF 再读 stderr。运行校验清空其子进程的 NODE_OPTIONS/NODE_PATH；普通 popen 尊重调用者的子环境设置。

需要整树监管时

本库不为原生管道再包装一层生命周期对象。直接组合独立 Job：

import nodeJs.runtime;
import process.job.limitKill;
var rt,err = nodeJs.runtime.ensure();
if(!rt) return null,err;
var job,err = process.job.limitKill();
if(!job) return null,err;
var pipe,err,code,pending = job.popen(rt.nodeExePath,["-p","42"]);
if(!pipe){job.dispose();return null,err,code,pending;}
pipe.codepage=65001;
var text,stderr,exitCode = pipe.readAll();
var ok,err,code = job.dispose(2000);
if(!ok) return null,err,code,job;
return {text=text;stderr=stderr;exitCode=exitCode};

必须持有 job，完成后主动 dispose；只关闭 pipe 不保证后代进程退出。详见 Job 生命周期文档。

Markdown 格式