@maiyunnet/kebab 9.21.0 → 9.21.1

package/sys/monitor/watchdog.js

@@ -1,270 +1,339 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2026-02-08
- * Last: 2026-08-22
- * --- 看门狗 Worker 线程，独立事件循环监控主线程心跳 ---
- * --- 阻塞时通过 inspector.connectToMainThread() 远程抓取主线程 JS 调用栈和 CPU Profile ---
- * --- 看门狗必须最小依赖、最大自治，不引入项目库，确保主线程异常时仍能可靠运行 ---
+ * Last: 2026-10-05
+ * --- 独立线程监测主线程心跳，阻塞期间保存资源采样、请求、调用栈和 CPU Profile ---
+ * --- 只依赖 Node.js；主线程无法运行时，日志与 Inspector 超时仍可独立处理 ---
  */
 import * as workerThreads from 'worker_threads';
 import * as fs from 'fs';
 import * as path from 'path';
-import * as inspector from 'inspector';
+import * as os from 'os';
+import * as inspector from 'inspector/promises';
 const data = workerThreads.workerData;
-const view = new Uint32Array(data.buffer);
-/** --- 上次告警时间（秒级时间戳） --- */
+/** --- 0: 心跳 ms, 1: 调试, 2: Inspector 所有者（0-空闲,1-常规 Profile,2-阻塞 Profile）, 3: 同步诊断, 4: 已保存现场的心跳 --- */
+const view = new BigInt64Array(data.buffer);
+const activeRequests = new Map(data.requests);
+const recentRequests = [];
+const samples = [];
+let snapshot = null;
+let lastAlertHeartbeat = 0n;
 let lastAlertTime = 0;
-/** --- 是否正在诊断采集 --- */
 let capturing = false;
+let lastCpu = process.cpuUsage();
+let lastTime = Number(process.hrtime.bigint() / 1000000n);
+workerThreads.parentPort?.on('message', (message) => {
+    if (message.type === 'snapshot') {
+        snapshot = message.snapshot;
+        data.logFormat = message.logFormat;
+    }
+    else if (message.type === 'request') {
+        activeRequests.set(message.id, message.request);
+    }
+    else if (message.type === 'complete') {
+        activeRequests.delete(message.id);
+        recentRequests.push(message.request);
+        if (recentRequests.length > 100) {
+            recentRequests.shift();
+        }
+    }
+    else {
+        collectProfile(message.dir, message.ts).catch((error) => {
+            writeLog(`WATCHDOG: Unexpected profile failure: ${String(error)}`);
+        });
+    }
+});
 /**
- * --- 格式化时间戳为 YmdHis 字符串 ---
+ * --- 格式化本地时间，用于日志目录和文件名 ---
+ * @param date 要格式化的时间
+ * @returns YmdHis 字符串
  */
-function fmtTs() {
-    const d = new Date();
-    return String(d.getFullYear()) +
-        String(d.getMonth() + 1).padStart(2, '0') +
-        String(d.getDate()).padStart(2, '0') +
-        String(d.getHours()).padStart(2, '0') +
-        String(d.getMinutes()).padStart(2, '0') +
-        String(d.getSeconds()).padStart(2, '0');
+function fmtTs(date) {
+    return String(date.getFullYear()) + String(date.getMonth() + 1).padStart(2, '0') +
+        String(date.getDate()).padStart(2, '0') + String(date.getHours()).padStart(2, '0') +
+        String(date.getMinutes()).padStart(2, '0') + String(date.getSeconds()).padStart(2, '0');
 }
 /**
- * --- 格式化当前时间为 HH:mm:ss ---
+ * --- 独立写入看门狗日志，格式和字段与 Core.log 一致，失败时保留标准错误输出 ---
+ * --- 不向主线程转发，也不加载 Core 的控制器、网络等依赖 ---
+ * @param msg 日志内容
+ * @returns 无返回值
  */
-function fmtTime() {
-    const d = new Date();
-    return String(d.getHours()).padStart(2, '0') + ':' +
-        String(d.getMinutes()).padStart(2, '0') + ':' +
-        String(d.getSeconds()).padStart(2, '0');
+function writeLog(msg) {
+    const now = new Date();
+    const ts = fmtTs(now);
+    const dir = path.join(data.logDir, 'system-monitor', ts.slice(0, 4), ts.slice(4, 6), ts.slice(6, 8));
+    try {
+        fs.mkdirSync(dir, { 'recursive': true, 'mode': 0o700 });
+        const format = data.logFormat ?? 'jsonl';
+        const file = path.join(dir, `${ts.slice(8, 10)}.${format}`);
+        // --- Worker 没有单个请求上下文；内存使用 MB，保持日志字段可直接展示 ---
+        const entry = {
+            'time': `${ts.slice(8, 10)}:${ts.slice(10, 12)}:${ts.slice(12, 14)}`,
+            'unix': Math.floor(now.getTime() / 1000),
+            'url': '', 'cookie': {}, 'session': {}, 'userAgent': '',
+            'realIp': '', 'cfIp': '', 'xIp': '',
+            'osMem': `${Math.round((os.totalmem() - os.freemem()) / 1024 / 1024 * 100) / 100}MB`,
+            'procMem': `${Math.round(process.memoryUsage.rss() / 1024 / 1024 * 100) / 100}MB`,
+            'message': msg,
+        };
+        let content;
+        if (format === 'jsonl') {
+            content = JSON.stringify(entry) + '\n';
+        }
+        else {
+            if (!fs.existsSync(file)) {
+                fs.writeFileSync(file, 'TIME,UNIX,URL,COOKIE,SESSION,USER_AGENT,REALIP,CFIP,XIP,OS,PROCESS,MESSAGE\n', { 'mode': 0o600 });
+            }
+            const fields = [
+                entry.time, String(entry.unix), entry.url, '', '{}', 'No HTTP_USER_AGENT',
+                entry.realIp, entry.cfIp, entry.xIp, entry.osMem, entry.procMem, entry.message,
+            ];
+            content = fields.map(field => `"${field.replace(/"/g, '""')}"`).join(',') + '\n';
+        }
+        fs.appendFileSync(file, content, { 'mode': 0o600 });
+    }
+    catch (error) {
+        process.stderr.write(`[MONITOR] Watchdog log failed: ${String(error)}\n`);
+    }
 }
 /**
- * --- 写入日志到 CSV 文件 ---
- * @param msg 日志消息
+ * --- 写入权限受限的诊断文件 ---
+ * @param dir 诊断目录
+ * @param name 文件名
+ * @param content 文件内容
+ * @returns 是否保存成功
  */
-function writeLog(msg) {
-    const d = new Date();
-    const dir = path.join(data.logDir, 'system-monitor', String(d.getFullYear()), String(d.getMonth() + 1).padStart(2, '0'), String(d.getDate()).padStart(2, '0'));
+function writeFile(dir, name, content) {
     try {
-        fs.mkdirSync(dir, { 'recursive': true, 'mode': 0o777 });
-        const h = String(d.getHours()).padStart(2, '0');
-        const file = path.join(dir, h + '.csv');
-        if (!fs.existsSync(file)) {
-            fs.writeFileSync(file, 'TIME,UNIX,MESSAGE\n', { 'mode': 0o777 });
+        fs.writeFileSync(path.join(dir, name), content, { 'mode': 0o600 });
+        fs.chmodSync(path.join(dir, name), 0o600);
+        return true;
+    }
+    catch (error) {
+        process.stderr.write(`[MONITOR] Watchdog diagnostic write failed: ${String(error)}\n`);
+        return false;
+    }
+}
+/**
+ * --- 按主线程请求采集 Profile，开始、停止、超时和文件写入都不依赖主线程事件循环 ---
+ * @param dir 主线程已创建的诊断目录
+ * @param ts 唯一采集时间标识
+ * @returns 无返回值，独立保存结果并通知主线程
+ */
+async function collectProfile(dir, ts) {
+    const file = `cpu-${ts}.cpuprofile`;
+    const result = { 'file': file, 'saved': false, 'errors': [] };
+    if (Atomics.compareExchange(view, 2, 0n, 1n) !== 0n) {
+        result.errors.push('Inspector is already collecting a profile.');
+        const recorded = writeFile(dir, `profile-${ts}.json`, JSON.stringify(result, null, 2));
+        workerThreads.parentPort?.postMessage({ 'type': 'profile', ...result, recorded });
+        return;
+    }
+    const session = new inspector.Session();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        session.disconnect();
+    }, data.profileDuration + 10_000);
+    try {
+        session.connectToMainThread();
+        await session.post('Profiler.enable');
+        await session.post('Profiler.start');
+        await new Promise(resolve => setTimeout(resolve, data.profileDuration));
+        const { profile } = await session.post('Profiler.stop');
+        result.saved = writeFile(dir, file, JSON.stringify(profile));
+        if (!result.saved) {
+            result.errors.push('Failed to save CPU profile.');
         }
-        const now = Math.floor(Date.now() / 1000);
-        fs.appendFileSync(file, `"${fmtTime()}","${now}","${msg}"\n`);
     }
-    catch {
-        // --- 文件系统不可用时无法做更多处理 ---
+    catch (error) {
+        result.errors.push(timedOut ? 'Inspector profile collection timed out.' : String(error));
+    }
+    finally {
+        clearTimeout(timeout);
+        session.disconnect();
+        Atomics.compareExchange(view, 2, 1n, 0n);
+        const recorded = writeFile(dir, `profile-${ts}.json`, JSON.stringify(result, null, 2));
+        if (!recorded) {
+            writeLog('WATCHDOG: Failed to save CPU profile result.');
+        }
+        workerThreads.parentPort?.postMessage({ 'type': 'profile', ...result, recorded });
     }
 }
 /**
- * --- 通过 Inspector 远程抓取主线程调用栈和 CPU Profile ---
- * @param blockSec 阻塞秒数
+ * --- 保存阻塞现场；暂停后立即恢复，再写磁盘，整个会话有统一超时和释放出口 ---
+ * @param blockMs 心跳中断时间 ms
+ * @param heartbeat 这次阻塞前的心跳，用于区分连续阻塞和新事件
+ * @returns 无返回值，采集结果保留在 blocked-event.json
  */
-function captureDiag(blockSec) {
+async function captureDiag(blockMs, heartbeat) {
     if (capturing) {
         return;
     }
     capturing = true;
-    const ts = fmtTs();
-    const diagDir = path.join(data.logDir, 'monitor', ts.slice(0, 4), ts.slice(4, 6), ts.slice(6, 8), `${ts.slice(8)}-pid-${data.pid}`);
-    const session = new inspector.Session();
+    const now = new Date();
+    const ts = fmtTs(now);
+    const id = `${ts}-${now.getTime()}`;
+    const dir = path.join(data.logDir, 'monitor', ts.slice(0, 4), ts.slice(4, 6), ts.slice(6, 8), `${ts.slice(8)}-pid-${data.pid}-${now.getTime()}-blocked`);
+    const cpu = process.cpuUsage();
+    const rss = process.memoryUsage.rss();
+    const requests = [];
+    for (const req of activeRequests.values()) {
+        if (requests.length >= 100) {
+            break;
+        }
+        requests.push({
+            'url': req.url, 'method': req.method, 'duration': now.getTime() - req.start,
+            'cpuUser': cpu.user - req.startCpu.user, 'cpuSystem': cpu.system - req.startCpu.system,
+            'memDelta': rss - req.startMem,
+        });
+    }
+    const record = {
+        'pid': data.pid, 'time': now.getTime(), 'heartbeat': Number(heartbeat), 'blockMs': blockMs,
+        'samples': [...samples], 'lastMainSnapshot': snapshot, 'activeRequests': requests, 'activeCount': activeRequests.size,
+        'recentRequests': recentRequests.filter(req => now.getTime() - (req.completedAt ?? 0) <= 60_000),
+        'status': 'pending', 'files': [], 'errors': [],
+    };
     try {
-        session.connectToMainThread();
+        fs.mkdirSync(dir, { 'recursive': true, 'mode': 0o700 });
+        fs.chmodSync(dir, 0o700);
     }
-    catch {
+    catch (error) {
+        writeLog(`WATCHDOG: Failed to create diagnostic directory: ${String(error)}`);
         capturing = false;
         return;
     }
-    let didPause = false;
-    /** --- 10s 超时与 Debugger.enable 回调存在竞态，超时后 session 已断开，回调仍在断开的 session 上操作 --- */
-    let timedOut = false;
-    /** --- scriptId → URL 映射表 --- */
-    const scriptUrls = {};
-    const pauseTimeout = setTimeout(() => {
-        if (!didPause) {
-            timedOut = true;
-            try {
-                session.post('Debugger.resume');
-            }
-            catch {
-                // --- 忽略 ---
-            }
-            try {
-                session.post('Debugger.disable');
-            }
-            catch {
-                // --- 忽略 ---
-            }
-            try {
-                session.disconnect();
-            }
-            catch {
-                // --- 忽略 ---
-            }
-            capturing = false;
+    if (!writeFile(dir, 'blocked-event.json', JSON.stringify(record, null, 2))) {
+        capturing = false;
+        return;
+    }
+    writeLog(`WATCHDOG: Main thread heartbeat delayed ${blockMs}ms, PID:${data.pid}, EVENT:${dir}`);
+    if (Atomics.compareExchange(view, 2, 0n, 2n) !== 0n) {
+        record.status = 'skipped-busy';
+        lastAlertTime = Number(process.hrtime.bigint() / 1000000n) - data.cooldown * 1_000 + 5_000;
+        record.errors.push('Inspector is already collecting a profile.');
+        if (!writeFile(dir, 'blocked-event.json', JSON.stringify(record, null, 2))) {
+            writeLog('WATCHDOG: Failed to save Inspector busy result.');
         }
-    }, 10_000);
-    session.on('Debugger.scriptParsed', (msg) => {
-        scriptUrls[msg.params.scriptId] = msg.params.url ?? '';
+        capturing = false;
+        return;
+    }
+    const session = new inspector.Session();
+    const scriptUrls = {};
+    let timedOut = false;
+    let finishPause = null;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        finishPause?.(false);
+        // --- 断开会话会使挂起的 post 失败，并释放我们设置的暂停状态 ---
+        session.disconnect();
+    }, data.profileDuration + 10_000);
+    session.on('Debugger.scriptParsed', (message) => {
+        scriptUrls[message.params.scriptId] = message.params.url;
     });
-    session.on('Debugger.paused', (msg) => {
-        if (timedOut) {
-            return;
-        }
-        didPause = true;
-        clearTimeout(pauseTimeout);
-        let stackLines = [];
+    try {
+        session.connectToMainThread();
+        // --- 先启动 Profile，避免等待调用栈时错过仍在执行的热点 ---
+        await session.post('Profiler.enable');
+        await session.post('Profiler.start');
+        const profileStarted = Number(process.hrtime.bigint() / 1000000n);
         try {
-            const frames = msg.params.callFrames;
-            stackLines = frames.map((f, i) => {
-                const url = f.url
-                    || scriptUrls[f.location.scriptId]
-                    || '';
-                const line = f.location.lineNumber + 1;
-                const col = (f.location.columnNumber ?? 0) + 1;
-                const name = f.functionName || '(anonymous)';
-                return `#${i} ${name} (${url}:${line}:${col})`;
+            await session.post('Debugger.enable');
+            const frames = await new Promise((resolve) => {
+                finishPause = resolve;
+                session.once('Debugger.paused', (message) => { resolve(message.params.callFrames); });
+                void session.post('Debugger.pause').catch(() => { resolve(false); });
             });
-        }
-        catch {
-            // --- 忽略堆栈解析错误 ---
-        }
-        session.post('Debugger.resume', (resumeErr) => {
-            if (resumeErr) {
-                // --- resume 失败仍尝试 disable 并断开，防止主线程卡死 ---
-                try {
-                    session.post('Debugger.disable');
-                }
-                catch {
-                    // --- 忽略 ---
-                }
-                try {
-                    session.disconnect();
+            if (frames !== false && !timedOut) {
+                const lines = frames.map((frame, i) => {
+                    const url = frame.url || scriptUrls[frame.location.scriptId] || '';
+                    return `#${i} ${frame.functionName || '(anonymous)'} ` +
+                        `(${url}:${frame.location.lineNumber + 1}:${(frame.location.columnNumber ?? 0) + 1})`;
+                });
+                await session.post('Debugger.resume');
+                const name = `blocked-stack-${id}.txt`;
+                if (writeFile(dir, name, `Heartbeat delayed: ${blockMs}ms\nPID: ${data.pid}\nCaptured: ${now.toISOString()}\n\n${lines.join('\n')}\n`)) {
+                    record.files.push(name);
+                    Atomics.store(view, 4, heartbeat);
                 }
-                catch {
-                    // --- 忽略 ---
+                else {
+                    record.errors.push('Failed to save blocking stack.');
                 }
-                capturing = false;
-                return;
             }
-            session.post('Debugger.disable', () => {
-                // --- 写入堆栈文件 ---
-                try {
-                    fs.mkdirSync(diagDir, {
-                        'recursive': true, 'mode': 0o700,
-                    });
-                    fs.chmodSync(diagDir, 0o700);
-                    const content = `Event Loop Blocked: ${blockSec}s\n` +
-                        `Captured: ${new Date().toISOString()}\n` +
-                        `PID: ${data.pid}\n\n` +
-                        `Call Stack:\n${stackLines.join('\n')}\n`;
-                    fs.writeFileSync(path.join(diagDir, `blocked-stack-${ts}.txt`), content, { 'mode': 0o600 });
-                    fs.chmodSync(path.join(diagDir, `blocked-stack-${ts}.txt`), 0o600);
-                }
-                catch {
-                    // --- 忽略 ---
-                }
-                // --- 采集 CPU Profile ---
-                collectProfile(session, diagDir, ts);
-            });
-        });
-    });
-    session.post('Debugger.enable', (err) => {
-        if (err || timedOut) {
-            clearTimeout(pauseTimeout);
+            else {
+                record.errors.push('No blocking stack received before timeout.');
+            }
             if (!timedOut) {
-                session.disconnect();
-                capturing = false;
+                await session.post('Debugger.disable');
             }
-            return;
         }
-        try {
-            session.post('Debugger.pause', (err2) => {
-                if (err2 || timedOut) {
-                    clearTimeout(pauseTimeout);
-                    if (!timedOut) {
-                        try {
-                            session.post('Debugger.disable');
-                        }
-                        catch {
-                            // --- 忽略 ---
-                        }
-                        session.disconnect();
-                        capturing = false;
-                    }
-                }
-            });
-        }
-        catch {
-            clearTimeout(pauseTimeout);
-            try {
-                session.disconnect();
-            }
-            catch {
-                // --- 忽略 ---
+        catch (error) {
+            record.errors.push(`Stack: ${String(error)}`);
+            // --- 栈采集失败仍尝试恢复主线程，CPU Profile 可以独立完成 ---
+            if (!timedOut) {
+                await session.post('Debugger.resume').catch(() => undefined);
+                await session.post('Debugger.disable').catch(() => undefined);
             }
-            capturing = false;
         }
-    });
-}
-/**
- * --- 采集 CPU Profile ---
- * @param session Inspector 会话
- * @param diagDir 诊断输出目录
- * @param ts 时间戳字符串
- */
-function collectProfile(session, diagDir, ts) {
-    session.post('Profiler.enable', (err) => {
-        if (err) {
-            session.disconnect();
-            capturing = false;
-            return;
+        const remaining = data.profileDuration - (Number(process.hrtime.bigint() / 1000000n) - profileStarted);
+        if (remaining > 0) {
+            await new Promise(resolve => setTimeout(resolve, remaining));
         }
-        session.post('Profiler.start', (err2) => {
-            if (err2) {
-                session.post('Profiler.disable');
-                session.disconnect();
-                capturing = false;
-                return;
-            }
-            setTimeout(() => {
-                session.post('Profiler.stop', (err3, r) => {
-                    if (!err3 && r?.profile) {
-                        try {
-                            fs.writeFileSync(path.join(diagDir, `blocked-cpu-${ts}.cpuprofile`), JSON.stringify(r.profile), { 'mode': 0o600 });
-                            fs.chmodSync(path.join(diagDir, `blocked-cpu-${ts}.cpuprofile`), 0o600);
-                        }
-                        catch {
-                            // --- 忽略 ---
-                        }
-                    }
-                    session.post('Profiler.disable');
-                    session.disconnect();
-                    capturing = false;
-                });
-            }, data.profileDuration);
-        });
-    });
+        const { profile } = await session.post('Profiler.stop');
+        const name = `blocked-cpu-${id}.cpuprofile`;
+        if (writeFile(dir, name, JSON.stringify(profile))) {
+            record.files.push(name);
+            Atomics.store(view, 4, heartbeat);
+        }
+        else {
+            record.errors.push('Failed to save CPU profile.');
+        }
+        record.status = record.errors.length ? 'partial' : 'complete';
+    }
+    catch (error) {
+        record.status = record.files.length ? 'partial' : 'failed';
+        record.errors.push(timedOut ? 'Inspector collection timed out.' : String(error));
+    }
+    finally {
+        clearTimeout(timeout);
+        session.disconnect();
+        Atomics.compareExchange(view, 2, 2n, 0n);
+        capturing = false;
+        if (!writeFile(dir, 'blocked-event.json', JSON.stringify(record, null, 2))) {
+            record.errors.push('Failed to update event summary.');
+            record.status = 'partial';
+        }
+        writeLog(`WATCHDOG: Diagnostic ${record.status}, PID:${data.pid}, EVENT:${dir}`);
+        workerThreads.parentPort?.postMessage({ 'type': 'diagnostic', 'heartbeat': Number(heartbeat), dir,
+            'files': record.files.map(name => path.join(dir, name)), 'errors': record.errors, 'status': record.status });
+    }
 }
-// --- 主循环：检测心跳 ---
+// --- 每秒独立采样；新心跳代表新事件，不让上一事件的冷却吞掉下一次阻塞 ---
 setInterval(() => {
-    const lastHb = Atomics.load(view, 0);
-    const now = Math.floor(Date.now() / 1000);
-    if (lastHb <= 0 || now - lastHb < data.threshold) {
-        return;
+    const time = Number(process.hrtime.bigint() / 1000000n);
+    const cpu = process.cpuUsage();
+    const elapsed = time - lastTime;
+    const heartbeat = Atomics.load(view, 0);
+    const blockMs = time - Number(heartbeat);
+    const cpuPercent = elapsed > 0
+        ? (cpu.user - lastCpu.user + cpu.system - lastCpu.system) / (elapsed * 1_000) * 100 : 0;
+    lastCpu = cpu;
+    lastTime = time;
+    samples.push({ 'time': Date.now(), elapsed, 'cpu': Math.round(cpuPercent * 100) / 100,
+        'rss': process.memoryUsage.rss(), 'heartbeatLag': blockMs });
+    if (samples.length > 60) {
+        samples.shift();
     }
-    // --- 调试模式下跳过阻塞检测，避免干扰 IDE 调试器 ---
-    if (Atomics.load(view, 1) === 1) {
+    if (heartbeat <= 0n || blockMs < data.threshold || Atomics.load(view, 1) === 1n || Atomics.load(view, 3) === 1n) {
         return;
     }
-    if (now - lastAlertTime < data.cooldown) {
+    if (capturing || heartbeat === lastAlertHeartbeat && time - lastAlertTime < data.cooldown * 1_000) {
         return;
     }
-    lastAlertTime = now;
-    const blockSec = now - lastHb;
-    writeLog('WATCHDOG: Main thread event loop blocked for ' +
-        blockSec + 's, PID: ' + data.pid);
-    captureDiag(blockSec);
+    lastAlertHeartbeat = heartbeat;
+    lastAlertTime = time;
+    captureDiag(blockMs, heartbeat).catch((error) => {
+        writeLog(`WATCHDOG: Unexpected collection failure: ${String(error)}`);
+    });
 }, data.interval);

package/sys/monitor.d.ts

@@ -1,5 +1,16 @@
+/** --- 活跃请求的描述 --- */
+export interface IActiveRequest {
+    'url': string;
+    'method': string;
+    /** --- 请求开始的时间戳（ms） --- */
+    'start': number;
+    /** --- 请求开始时的 CPU 累计用量基准 --- */
+    'startCpu': NodeJS.CpuUsage;
+    /** --- 请求开始时的进程整体内存 RSS 基准（bytes） --- */
+    'startMem': number;
+}
 /** --- 单个请求快照 --- */
-interface ISnapshotRequest {
+export interface ISnapshotRequest {
     'url': string;
     'method': string;
     'duration': number;
@@ -9,6 +20,8 @@ interface ISnapshotRequest {
     'cpuSystem': number;
     /** --- 请求存续期间的进程整体 RSS 增量（bytes），不代表请求独占 --- */
     'memDelta': number;
+    /** --- 已完成请求的结束时间，活跃请求不含此字段 --- */
+    'completedAt'?: number;
 }
 /** --- 整体资源快照 --- */
 export interface ISnapshot {
@@ -35,14 +48,19 @@ export interface ISnapshot {
         'free': number;
     };
     'eloopLag': number;
+    /** --- 本采样窗口最大延迟，用于复盘单次卡顿；持续告警仍按 P99 判断 --- */
+    'eloopMax': number;
     /** --- 最早开始的活跃请求，最多 100 条 --- */
     'activeRequests': ISnapshotRequest[];
     /** --- 全部活跃请求数量，可能大于 activeRequests.length --- */
     'activeCount': number;
+    /** --- 最近一分钟完成的请求，最多 100 条；资源增量均为整个进程的增量 --- */
+    'recentRequests': ISnapshotRequest[];
 }
 /**
  * --- 启动性能监控 ---
  * @param opt 可选的阈值配置
+ * @returns 是否成功启动，配置无效时返回 false
  */
 export declare function start(opt?: {
     /** --- CPU 使用率阈值百分比，默认 80 --- */
@@ -53,24 +71,31 @@ export declare function start(opt?: {
     'eloop'?: number;
     /** --- 内存超阈值时是否采集堆快照，默认 false --- */
     'heapSnapshot'?: boolean;
-}): void;
+    /** --- 同一指标持续超阈值的确认时间 ms，默认 10000 --- */
+    'duration'?: number;
+    /** --- 主线程心跳中断的确认时间 ms，默认 5000，最小 1000 --- */
+    'blocked'?: number;
+}): boolean;
 /**
  * --- 停止性能监控 ---
+ * @returns 无返回值
  */
 export declare function stop(): void;
 /**
  * --- 注册一个活跃请求，返回追踪 ID ---
  * @param url 请求 URL
  * @param method 请求方法
+ * @returns 追踪 ID
  */
 export declare function track(url: string, method: string): string;
 /**
  * --- 移除已完成的请求追踪 ---
  * @param id 追踪 ID
+ * @returns 无返回值
  */
 export declare function untrack(id: string): void;
 /**
  * --- 获取当前资源快照 ---
+ * @returns 资源与请求快照
  */
 export declare function getSnapshot(): ISnapshot;
-export {};