multi-tasks 3.3.0 → 3.4.1

package/utils/progressView.js

@@ -1,102 +1,110 @@
-//终端进度条渲染器(零依赖): 两行进度区——上行 bar+百分比固定 36 列(约 18 个中文字符宽, 不随终端宽度变), 下行实时计数(动态宽, 封顶 cols-1)。
-//bar 行短则拖动窗口时几乎不触发终端折行重排(reflow), ESC[1A 数行更可信(占满整行方案在 conpty 重排下
-//反复错位, 用户拍板改短行)。首帧直接写两行(无光标控制); 后续帧 \r 回行首 + 清行 + ESC[1A 上移一行 + 清行 + 重写两行。
-//resize 重锚定(reanchor)是抹除式: 终端重排(reflow)后旧帧占用行数不再固定为 2, 按记录的上帧
-//两行可见长度 ÷ 当前列宽算出实际占用行数, 上移回旧帧首行 + ESC[0J 清到屏尾, 下一帧从锚点重写——
-//不做换行定格: 定格会把重排碎片留在滚动区, 连续拖动即满屏碎片(用户否掉的旧方案)。
-//已知取舍: 两帧之间若有外部写入共享终端, ESC[1A 数行会被挤偏, 旧帧可能滞留残留(用户确认接受)。
-const ESC = '\x1B';
-const fs = require('fs');
-const RED = '\x1B[31m';
-const GREEN = '\x1B[32m';
-const YELLOW = '\x1B[33m';
-const RESET_FG = '\x1B[39m';
-
-const BAR_OVERHEAD = 10;//'[' + '] ' + 6 位百分比 + '%'
-const BAR_COLS = 36;//bar 行固定 36 列(约 18 个中文字符宽, 用户拍板, 不随终端宽度变): 行短则拖动窗口时几乎不触发折行重排; info 行保持动态宽(计数器全显)
-
-//仅渲染帧上色(writeLine/run.log 永远无色): bar 完成段绿 / done 数绿 / succ 数绿 / running 数黄 / failed 整词红 / succ-but-save-failed 数黄,
-//为 0 不着色减少噪音。必须在按列宽截断之后调用: 颜色码不占可见宽度, 也不会被截断拆开
-const colorizeFrame = (line) => {
-  return line
-    .replace(/\[([█]+)/, (m, blocks) => `[${GREEN}${blocks}${RESET_FG}`)
-    .replace(/(\d+) failed/, (m, n) => (n === '0' ? m : `${RED}${n} failed${RESET_FG}`))
-    .replace(/(\d+) succ-but-save-failed/, (m, n) => (n === '0' ? m : `${YELLOW}${n}${RESET_FG} succ-but-save-failed`))
-    .replace(/(\d+) running/, (m, n) => (n === '0' ? m : `${YELLOW}${n}${RESET_FG} running`))
-    .replace(/(\d+) succ(?=,|$)/, (m, n) => (n === '0' ? m : `${GREEN}${n}${RESET_FG} succ`))//(?=,|$) 防误配 succ-but-save-failed 的词头
-    .replace(/(\d+)\/(\d+) done/, (m, done, total) => (done === '0' ? m : `${GREEN}${done}${RESET_FG}/${total} done`));
-};
-
-const create = ({ stream }) => {
-  if (!stream) { throw new Error('progressView needs a stream'); };
-  let frameCount = 0;
-  let ended = false;
-  let lastBarLen = 0;//上帧两行可见长度(截断后、上色前): resize 重排后算旧帧实际占用行数用
-  let lastInfoLen = 0;
-
-  //TTY 现场排查开关: MULTI_TASKS_PROGRESS_DEBUG=文件路径 时, 每帧字节流+当时列宽记成 JSON 行,
-  //供 test/terminalSim.js 回放比对真实终端行为(仅排查用, 平时为空不写盘)
-  const debugPath = process.env.MULTI_TASKS_PROGRESS_DEBUG;
-  const write = (s) => {
-    if (debugPath) {
-      fs.appendFileSync(debugPath, `${JSON.stringify({ at: Date.now(), cols: stream.columns || 80, data: s })}\n`);
-    };
-    stream.write(s);
-  };
-
-  const buildLines = ({ done, succ, running, remaining, failed, succButSaveFailed }) => {
-    //行比终端列宽还长会折行、光标定位错乱: 每行封顶 cols-1(截断后才上色);
-    //留 1 空列: 写满整列会触发终端满列换行(deferred wrap), resize 重排时 ESC[1A 数行失准;
-    //bar 行固定 BAR_COLS 列(窄终端整行截断, 行尾百分比会被截掉): 行短则拖动窗口时几乎不触发折行重排
-    const cols = stream.columns || 80;
-    const maxLineLen = Math.max(1, cols - 1);
-    const truncate = (line) => (line.length > maxLineLen ? line.slice(0, maxLineLen) : line);
-    let total = done + running + remaining;
-    let width = BAR_COLS - BAR_OVERHEAD;//固定 26 格, 不随终端宽度变
-    let filled = total > 0 ? Math.floor(width * done / total) : width;
-    let bar = '█'.repeat(filled) + '░'.repeat(width - filled);
-    let pct = (total > 0 ? 100 * done / total : 100).toFixed(2).padStart(6);//两位小数, 定宽防行长抖动
-    //下行实时计数器(done/succ/running/failed/succ-but-save-failed), 与收尾计数器行同源(都出自 getFinalStats)
-    let barLine = `[${bar}] ${pct}%`;
-    let infoLine = `${done}/${total} done, ${succ || 0} succ, ${running} running, ${failed || 0} failed, ${succButSaveFailed || 0} succ-but-save-failed`;
-    return [truncate(barLine), truncate(infoLine)];
-  };
-
-  const render = (data) => {
-    let [barLine, infoLine] = buildLines(data);
-    lastBarLen = barLine.length;
-    lastInfoLen = infoLine.length;
-    let frame = `${colorizeFrame(barLine)}\n${colorizeFrame(infoLine)}`;
-    if (frameCount === 0) {
-      write(frame);
-    } else {
-      write(`\r${ESC}[2K${ESC}[1A${ESC}[2K${frame}`);
-    };
-    frameCount++;
-  };
-
-  const end = () => {//收尾换行: 进度区定格, 后续输出(shell 提示符等)落在下一行
-    ended = true;
-    write('\n');
-  };
-
-  const reanchor = () => {//终端 resize 重排后旧帧行数不可信: 按上帧行长 ÷ 当前列宽算出实际占用行数,
-    //上移回旧帧首行并 ESC[0J 清到屏尾(抹除旧帧, 不留定格碎片), 下一帧从该锚点按首帧重写
-    if (ended || frameCount === 0) {
-      return;
-    };
-    const cols = stream.columns || 80;
-    const wrapRows = (len) => Math.max(1, Math.ceil(len / cols));
-    const rowsAbove = wrapRows(lastBarLen) + wrapRows(lastInfoLen) - 1;
-    write(`\r${ESC}[${rowsAbove}A${ESC}[0J`);
-    frameCount = 0;
-  };
-
-  const writeLine = (text) => {//定格后整行输出(计数器行等): 纯文本一行, 不进 run.log(ASCII 契约之外的字符只走 render)
-    write(`${text}\n`);
-  };
-
-  return { render, end, reanchor, writeLine };
-};
-
-module.exports = { create };
+//终端进度条渲染器(零依赖): N 行帧——首行 bar+百分比固定 36 列(约 18 个中文字符宽, 不随终端宽度变), 末行实时计数(动态宽, 封顶 cols-1),
+//中间可接 extraLines 附加行(如 worker 状态行, 同样封顶 cols-1); 帧行数帧间必须恒定(由调用方保证), 是原地重绘的前提。
+//bar 行短则拖动窗口时几乎不触发终端折行重排(reflow), ESC[nA 数行更可信(占满整行方案在 conpty 重排下
+//反复错位, 用户拍板改短行)。首帧直接写整帧(无光标控制); 后续帧 \r 回行首 + 清行 + 逐行 ESC[1A 上移清行(N-1 次) + 重写整帧。
+//resize 重锚定(reanchor)是抹除式: 终端重排(reflow)后旧帧占用行数不可信, 按记录的上帧
+//各行可见长度 ÷ 当前列宽算出实际占用行数, 上移回旧帧首行 + ESC[0J 清到屏尾, 下一帧从锚点重写——
+//不做换行定格: 定格会把重排碎片留在滚动区, 连续拖动即满屏碎片(用户否掉的旧方案)。
+//已知取舍: 两帧之间若有外部写入共享终端, ESC[nA 数行会被挤偏, 旧帧可能滞留残留(用户确认接受)。
+const ESC = '\x1B';
+const fs = require('fs');
+const RED = '\x1B[31m';
+const GREEN = '\x1B[32m';
+const YELLOW = '\x1B[33m';
+const RESET_FG = '\x1B[39m';
+
+const BAR_OVERHEAD = 10;//'[' + '] ' + 6 位百分比 + '%'
+const BAR_COLS = 36;//bar 行固定 36 列(约 18 个中文字符宽, 用户拍板, 不随终端宽度变): 行短则拖动窗口时几乎不触发折行重排; info 行保持动态宽(计数器全显)
+
+//仅渲染帧上色(writeLine/run.log 永远无色): bar 完成段绿 / done 数绿 / succ 数绿 / running 数黄 / failed 整词红 / succ-but-save-failed 数黄,
+//为 0 不着色减少噪音。必须在按列宽截断之后调用: 颜色码不占可见宽度, 也不会被截断拆开
+const colorizeFrame = (line) => {
+  return line
+    .replace(/\[([█]+)/, (m, blocks) => `[${GREEN}${blocks}${RESET_FG}`)
+    .replace(/(\d+) failed/, (m, n) => (n === '0' ? m : `${RED}${n} failed${RESET_FG}`))
+    .replace(/(\d+) succ-but-save-failed/, (m, n) => (n === '0' ? m : `${YELLOW}${n}${RESET_FG} succ-but-save-failed`))
+    .replace(/(\d+) running/, (m, n) => (n === '0' ? m : `${YELLOW}${n}${RESET_FG} running`))
+    .replace(/(\d+) succ(?=,|$)/, (m, n) => (n === '0' ? m : `${GREEN}${n}${RESET_FG} succ`))//(?=,|$) 防误配 succ-but-save-failed 的词头
+    .replace(/(\d+)\/(\d+) done/, (m, done, total) => (done === '0' ? m : `${GREEN}${done}${RESET_FG}/${total} done`));
+};
+
+const create = ({ stream }) => {
+  if (!stream) { throw new Error('progressView needs a stream'); };
+  let frameCount = 0;
+  let ended = false;
+  let lastLineLens = [];//上帧各行可见长度(截断后、上色前): resize 重排后算旧帧实际占用行数用
+
+  //TTY 现场排查开关: MULTI_TASKS_PROGRESS_DEBUG=文件路径 时, 每帧字节流+当时列宽记成 JSON 行,
+  //供 test/terminalSim.js 回放比对真实终端行为(仅排查用, 平时为空不写盘)
+  const debugPath = process.env.MULTI_TASKS_PROGRESS_DEBUG;
+  const write = (s) => {
+    if (debugPath) {
+      fs.appendFileSync(debugPath, `${JSON.stringify({ at: Date.now(), cols: stream.columns || 80, data: s })}\n`);
+    };
+    stream.write(s);
+  };
+
+  const buildLines = ({ done, succ, running, remaining, failed, succButSaveFailed, extraLines }) => {
+    //行比终端列宽还长会折行、光标定位错乱: 每行封顶 cols-1(截断后才上色);
+    //留 1 空列: 写满整列会触发终端满列换行(deferred wrap), resize 重排时 ESC[1A 数行失准;
+    //bar 行固定 BAR_COLS 列(窄终端整行截断, 行尾百分比会被截掉): 行短则拖动窗口时几乎不触发折行重排
+    const cols = stream.columns || 80;
+    const maxLineLen = Math.max(1, cols - 1);
+    const truncate = (line) => (line.length > maxLineLen ? line.slice(0, maxLineLen) : line);
+    let total = done + running + remaining;
+    let width = BAR_COLS - BAR_OVERHEAD;//固定 26 格, 不随终端宽度变
+    let filled = total > 0 ? Math.floor(width * done / total) : width;
+    let bar = '█'.repeat(filled) + '░'.repeat(width - filled);
+    let pct = (total > 0 ? 100 * done / total : 100).toFixed(2).padStart(6);//两位小数, 定宽防行长抖动
+    //末行实时计数器(done/succ/running/failed/succ-but-save-failed), 与收尾计数器行同源(都出自 getFinalStats)
+    let barLine = `[${bar}] ${pct}%`;
+    let infoLine = `${done}/${total} done, ${succ || 0} succ, ${running} running, ${failed || 0} failed, ${succButSaveFailed || 0} succ-but-save-failed`;
+    //extraLines(状态行等)插在 bar 行与计数器行之间(计数器行固定帧尾——用户拍板):
+    //帧行数必须帧间恒定(ESC[nA 上移数按新帧行数算, 变行数会错位), 由调用方(progressCtl)保证开启期间每帧都带
+    let lines = [barLine];
+    if (extraLines) {
+      lines = lines.concat(extraLines);
+    };
+    lines.push(infoLine);
+    return lines.map(truncate);
+  };
+
+  const render = (data) => {
+    let lines = buildLines(data);
+    lastLineLens = lines.map((line) => line.length);
+    let frame = lines.map(colorizeFrame).join('\n');
+    if (frameCount === 0) {
+      write(frame);
+    } else {
+      //N 行帧同构推广: \r 回行首清当前行(帧末行) + 逐行上移清行(N-1 次) + 重写整帧
+      let prefix = `\r${ESC}[2K` + `${ESC}[1A${ESC}[2K`.repeat(lines.length - 1);
+      write(`${prefix}${frame}`);
+    };
+    frameCount++;
+  };
+
+  const end = () => {//收尾换行: 进度区定格, 后续输出(shell 提示符等)落在下一行
+    ended = true;
+    write('\n');
+  };
+
+  const reanchor = () => {//终端 resize 重排后旧帧行数不可信: 按上帧各行行长 ÷ 当前列宽算出实际占用行数,
+    //上移回旧帧首行并 ESC[0J 清到屏尾(抹除旧帧, 不留定格碎片), 下一帧从该锚点按首帧重写
+    if (ended || frameCount === 0) {
+      return;
+    };
+    const cols = stream.columns || 80;
+    const wrapRows = (len) => Math.max(1, Math.ceil(len / cols));
+    const rowsAbove = lastLineLens.reduce((sum, len) => sum + wrapRows(len), 0) - 1;
+    write(`\r${ESC}[${rowsAbove}A${ESC}[0J`);
+    frameCount = 0;
+  };
+
+  const writeLine = (text) => {//定格后整行输出(计数器行等): 纯文本一行, 不进 run.log(ASCII 契约之外的字符只走 render)
+    write(`${text}\n`);
+  };
+
+  return { render, end, reanchor, writeLine };
+};
+
+module.exports = { create };

package/utils/randoms.js

@@ -1,10 +1,11 @@
 
+const crypto = require('crypto');
 const fmtDigit = (n)=>{
     return n > 9 ? "" + n: "0" + n;
-}
+};
 const getDateTimeTxt = ()=>{
     let d=new Date();
-    let YYYY=d.getFullYear()
+    let YYYY=d.getFullYear();
     let MM=fmtDigit(d.getMonth()+1);
     let DD=fmtDigit(d.getDate());
     let HH=fmtDigit(d.getHours());
@@ -13,9 +14,11 @@ const getDateTimeTxt = ()=>{
     return `${YYYY}-${MM}-${DD}_${HH}-${mm}-${ss}`;
 };
 const get36Id = ()=>{
-    let num1 = (Math.random().toString().match(/\d/g).join('')*1).toString(36);  
+    //时间戳前缀(保排序可读) + crypto 随机后缀(hex 是 base36 字符集子集):
+    //Math.random 拼数字会丢前导零且同毫秒时钟不变, 批量建任务熵不足(勿回退)
     let num2 = Date.now().toString(36);
-    let str = num2+num1;
+    let rand = crypto.randomBytes(8).toString('hex');
+    let str = num2+rand;
     return str;
 };
 module.exports = {getDateTimeTxt, get36Id};

package/utils/resolveWorkers.js

@@ -6,7 +6,7 @@ const PERCENT_PATTERN = /^(\d+(?:\.\d+)?)%$/;
 
 // 解析 numberOfWorkers 配置:
 // - undefined -> 默认 "50%", 按核数四舍五入折算, 最小为 1;
-// - number -> 原样返回(现状行为不变);
+// - number -> 必须是 >=1 的整数(0 会静默起不来 worker、小数/负数行为隐晦, fail-fast);
 // - string -> 必须是 "数字%" 形式且百分比在 1-100 之间, 按核数四舍五入折算, 最小为 1;
 // - 其余 -> 抛 Error。
 const percentToWorkers = (percent) => {
@@ -18,7 +18,9 @@ const resolveNumberOfWorkers = (value) => {
     return percentToWorkers(50);
   };
   if (typeof value === 'number') {
-    return value;
+    if (Number.isInteger(value) && value >= 1) {
+      return value;
+    };
   };
   if (typeof value === 'string') {
     const match = value.trim().match(PERCENT_PATTERN);

package/utils/startupBanner.js

@@ -7,7 +7,7 @@ const runLog = require('./runLog');
 
 const VERSION = require('../package.json').version;
 
-const KEY_WIDTH = 17;//键列宽: 需容纳最长键 'monitor start cmd', 改动时同步调
+const KEY_WIDTH = 19;//键列宽: 需容纳最长键 'monitor install cmd', 改动时同步调
 
 const renderTitleBox = (mode) => {
   const left = `multi-tasks v${VERSION}`;
@@ -27,6 +27,7 @@ const renderFieldLines = (info) => {
     ['new tasks', `${info.newTasks}`],
     ['run.log', info.sysLogFile || '(not available)'],
     ['started at', info.startedAt],
+    ['monitor install cmd', 'npm install multi-tasks-monitor'],
     ['monitor start cmd', `npx multi-tasks-monitor --task-dir "${info.taskFolder}" --port 3777`],
   ];
   return rows.map(([key, value]) => `${key.padEnd(KEY_WIDTH)} : ${value}`);

package/utils/workerStatusProbe.js

@@ -0,0 +1,38 @@
+//worker 端状态探针(零依赖, perf_hooks 为 Node 内置): unref 定时器按间隔自采——
+//两个增量指标: ELU(eventLoopUtilization 快照差值的 utilization, 0~1, JS 线程打没打满的直接答案)与
+//CPU%(process.cpuUsage 增量/墙钟增量, 单核占比, 用户开 worker_threads 时可 >100, 原样上报);
+//两个内存快照: rss(进程物理内存)与 heapUsed(V8 堆), 原始字节上报, 格式化在 master。
+//通过 send 回调发给 master。只在 worker 进程内运行; interval <= 0 不启动(特性关闭)。
+//unref: 不阻碍进程退出, 不干扰 autoClose; 采样/上报异常只 runLog.warn, 绝不影响任务执行。
+const { performance } = require('perf_hooks');
+
+const runLog = require('./runLog');
+
+const start = (intervalMs, send) => {
+  if (!(intervalMs > 0)) {
+    return null;
+  };
+  let lastElu = performance.eventLoopUtilization();
+  let lastCpu = process.cpuUsage();
+  const timer = setInterval(() => {
+    try {
+      const wallMs = intervalMs;//定时器间隔即墙钟窗口: fake timers/真实运行一致, 漂移纳入分子分母可忽略
+      const curElu = performance.eventLoopUtilization();
+      const elu = performance.eventLoopUtilization(curElu, lastElu).utilization;
+      const cpuDelta = process.cpuUsage(lastCpu);
+      const cpu = ((cpuDelta.user + cpuDelta.system) / (wallMs * 1000)) * 100;
+      const mem = process.memoryUsage();//~0.6µs/次, 每帧一次可忽略
+      lastElu = curElu;
+      lastCpu = process.cpuUsage();
+      send({ elu, cpu, rss: mem.rss, heapUsed: mem.heapUsed });
+    } catch (e) {
+      runLog.warn('[Worker]: status probe failed, skip this frame', e);
+    };
+  }, intervalMs);
+  timer.unref();
+  return {
+    stop: () => { clearInterval(timer); },
+  };
+};
+
+module.exports = { start };