xrk-node-runtime

文档

• 权威清单：docs/node-26-runtime.md
• 写法与性能（非 Node 专项）：docs/coding-style.md · skill xrk-coding-style
• 工具模块：docs/底层架构设计.md §1 工具表

版本

• 要求：Node ≥ 26.0（推荐 / 实测 26.7.x，至少 ≥ 26.5.1）；package.json engines 与 app.js 启动校验一致。
• 勿用：Node 24 特性检测回退、polyfill、未在文档列出的实验 API（如 node:ffi，除非用户明确要求）。

Core / 业务代码（core/**/*.js）必用

基础设施（src/**/*.js）

• 同上；唯一允许 util.promisify(exec) 的位置：src/utils/exec-async.js。
• 错误：errorHandler + normalizeError；日志：Error.isError 分支（见 log.js）。

代码示例（Core HTTP handler）

import { HttpResponse } from '#utils/http-utils.js';
import { normalizeError } from '#utils/normalize-error.js';

export default {
  routes: [{
    method: 'GET',
    path: '/api/example/ping',
    handler: HttpResponse.asyncHandler(async (req, res) => {
      const resp = await fetch('https://example.com', {
        signal: AbortSignal.timeout(5000)
      });
      if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
      return HttpResponse.success(res, await resp.text());
    }, 'example')
  }]
};

代码示例（Core 工作流 / 插件 catch）

} catch (err) {
  const error = normalizeError(err);
  RuntimeUtil.makeLog('error', error.message, 'MyStream');
}

代码示例（Shell / 热重载）

import { exec } from '#utils/exec-async.js';

const { stdout, stderr } = await exec('node --version');
// 至 26.7 仍无 node:child_process/promises — 勿在各文件 promisify(exec)

代码示例（二进制 / 设备路径）

const fileId = Buffer.from(filePath, 'utf8').toBase64({ alphabet: 'base64url' });
const path = Buffer.from(Uint8Array.fromBase64(fileId, { alphabet: 'base64url' })).toString('utf8');

审查清单（改 Core 前自检）

• 无 node-fetch、https-proxy-agent
• 无 import ... child_process/promises
• 无文件内 promisify(exec)（应用 exec-async.js）
• 无 AbortController + setTimeout(abort)
• 无 instanceof Error 作判错（展示类型名除外）
• 无 URLPattern / Error.isError 存在性检测
• 无 toString('base64'|'hex') / Buffer.from(s,'base64') 新代码
• Core 改底层需求：提 issue/说明，不直接改 src/infrastructure/、src/utils/（见 xrk-core-code.mdc）