@maiyunnet/kebab 9.15.6 → 9.16.0

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.15.6";
+export declare const VER = "9.16.0";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.15.6';
+export const VER = '9.16.0';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/core.d.ts

@@ -352,12 +352,31 @@ export declare function debug(message?: any, ...optionalParams: any[]): void;
  */
 export declare function display(message?: any, ...optionalParams: any[]): void;
 /**
- * --- 让 res 发送头部（前提是头部没有被发送才能调用本方法 ---
+ * --- 提交 HTTP 响应状态和头部，兼容 HTTP/1.1 与 HTTP/2 ---
+ *
+ * `setHeader()` 只暂存或修改单个头部，不会发送响应头，也不能提交状态码；在响应头提交前可反复调用。
+ * 本方法会立即提交状态码和此前设置的全部头部，必须在所有 `setHeader()` 调用之后、首次
+ * `write()`、`end()` 或 `pipe()` 之前调用。提交后再调用 `setHeader()` 会抛出 `ERR_HTTP_HEADERS_SENT`。
+ *
+ * 普通控制器应设置 `_httpCode`、调用 `_res.setHeader()` 并直接返回内容，由路由层统一提交响应头。
+ * 仅框架内部或手动接管响应（错误、重定向、代理、流式输出等）时才应直接调用本方法。
+ *
  * @param res 响应对象
- * @param statusCode 状态码
- * @param headers 头部
+ * @param statusCode HTTP 状态码
+ * @param headers 随本次提交附加的头部；通常优先在提交前使用 `setHeader()`
+ * @returns 无返回值
  */
 export declare function writeHead(res: http2.Http2ServerResponse | http.ServerResponse, statusCode: number, headers?: http.OutgoingHttpHeaders): void;
+/**
+ * --- 提交服务器发送事件（SSE）响应头 ---
+ *
+ * 在发送第一条事件前调用一次，固定提交状态码 200、事件流内容类型和禁止缓存头部。
+ * SSE 的内容长度和结束时间未知，因此不设置 `content-length`；调用后响应头已经提交，
+ * 不能再调用 `setHeader()`，后续应使用 `write()` 持续发送事件，并由调用方在结束时关闭响应。
+ *
+ * @param res 响应对象
+ * @returns 无返回值
+ */
 export declare function writeEventStreamHead(res: http2.Http2ServerResponse | http.ServerResponse): void;
 /**
  * --- 向 res 发送数据 ---

package/lib/core.js

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2019-5-3 23:54
- * Last: 2020-4-11 22:34:58, 2022-10-2 14:13:06, 2022-12-28 20:33:24, 2023-12-15 11:49:02, 2024-7-2 15:23:35, 2025-6-13 19:45:53, 2026-05-20 09:50:00
+ * Last: 2020-4-11 22:34:58, 2022-10-2 14:13:06, 2022-12-28 20:33:24, 2023-12-15 11:49:02, 2024-7-2 15:23:35, 2025-6-13 19:45:53, 2026-05-20 09:50:00, 2026-8-22
  */
 import * as cp from 'child_process';
 import * as http2 from 'http2';
@@ -1221,10 +1221,19 @@ export function display(message, ...optionalParams) {
     console.log(`KE-DISPLAY ${lTime.format(null, 'Y-m-d H:i:s')}`, message, ...optionalParams);
 }
 /**
- * --- 让 res 发送头部（前提是头部没有被发送才能调用本方法 ---
+ * --- 提交 HTTP 响应状态和头部，兼容 HTTP/1.1 与 HTTP/2 ---
+ *
+ * `setHeader()` 只暂存或修改单个头部，不会发送响应头，也不能提交状态码；在响应头提交前可反复调用。
+ * 本方法会立即提交状态码和此前设置的全部头部，必须在所有 `setHeader()` 调用之后、首次
+ * `write()`、`end()` 或 `pipe()` 之前调用。提交后再调用 `setHeader()` 会抛出 `ERR_HTTP_HEADERS_SENT`。
+ *
+ * 普通控制器应设置 `_httpCode`、调用 `_res.setHeader()` 并直接返回内容，由路由层统一提交响应头。
+ * 仅框架内部或手动接管响应（错误、重定向、代理、流式输出等）时才应直接调用本方法。
+ *
  * @param res 响应对象
- * @param statusCode 状态码
- * @param headers 头部
+ * @param statusCode HTTP 状态码
+ * @param headers 随本次提交附加的头部；通常优先在提交前使用 `setHeader()`
+ * @returns 无返回值
  */
 export function writeHead(res, statusCode, headers) {
     if (res instanceof http2.Http2ServerResponse) {
@@ -1234,6 +1243,16 @@ export function writeHead(res, statusCode, headers) {
         res.writeHead(statusCode, headers);
     }
 }
+/**
+ * --- 提交服务器发送事件（SSE）响应头 ---
+ *
+ * 在发送第一条事件前调用一次，固定提交状态码 200、事件流内容类型和禁止缓存头部。
+ * SSE 的内容长度和结束时间未知，因此不设置 `content-length`；调用后响应头已经提交，
+ * 不能再调用 `setHeader()`，后续应使用 `write()` 持续发送事件，并由调用方在结束时关闭响应。
+ *
+ * @param res 响应对象
+ * @returns 无返回值
+ */
 export function writeEventStreamHead(res) {
     writeHead(res, 200, {
         'content-type': 'text/event-stream; charset=utf-8',

package/lib/text.d.ts

@@ -170,6 +170,12 @@ export declare function parseJson<T>(str: string): T | false;
  * @param space 美化方式
  */
 export declare function stringifyJson(obj: kebab.Json, space?: string | number): string;
+/**
+ * --- 将未知异常转换为适合单行日志的文本，Error 优先返回完整堆栈 ---
+ * @param error 异常对象
+ * @returns 已转义的单行错误文本
+ */
+export declare function stringifyError(error: unknown): string;
 /**
  * --- 输出文本格式的 buffer ---
  * @param buf 原始 buffer

package/lib/text.js

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2019-5-15 16:49:39
- * Last: 2020-04-06 20:51:06, 2022-9-29 15:18:16, 2022-12-29 00:01:30, 2024-3-6 17:53:14, 2024-5-31 17:29:52, 2025-6-13 15:47:02, 2025-9-23 12:51:49
+ * Last: 2020-04-06 20:51:06, 2022-9-29 15:18:16, 2022-12-29 00:01:30, 2024-3-6 17:53:14, 2024-5-31 17:29:52, 2025-6-13 15:47:02, 2025-9-23 12:51:49, 2026-8-22
  */
 import * as net from 'net';
 import * as kebab from '#kebab/index.js';
@@ -624,6 +624,29 @@ export function stringifyJson(obj, space) {
         return v;
     }, space).replace(/"-mybigint-([-+0-9]+?)"/g, '$1');
 }
+/**
+ * --- 将未知异常转换为适合单行日志的文本，Error 优先返回完整堆栈 ---
+ * @param error 异常对象
+ * @returns 已转义的单行错误文本
+ */
+export function stringifyError(error) {
+    let message;
+    if (error instanceof Error) {
+        message = error.stack ?? error.message;
+    }
+    else if (typeof error === 'string') {
+        message = error;
+    }
+    else {
+        try {
+            message = stringifyJson(error);
+        }
+        catch {
+            message = String(error);
+        }
+    }
+    return stringifyJson(message).slice(1, -1);
+}
 /**
  * --- 输出文本格式的 buffer ---
  * @param buf 原始 buffer

package/lib/undici/request.d.ts

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2020-4-9 20:02:39
- * Last: 2020-4-9 20:47:58, 2022-09-10 01:35:34, 2025-9-23 12:41:58
+ * Last: 2020-4-9 20:47:58, 2022-09-10 01:35:34, 2025-9-23 12:41:58, 2026-8-22
  */
 import * as stream from 'stream';
 import * as lCookie from '#kebab/lib/cookie.js';
@@ -47,6 +47,11 @@ export declare class Request {
      * @param timeout 秒
      */
     timeout(timeout: number): this;
+    /**
+     * --- 设置网络异常后的重试次数 ---
+     * @param retry 重试次数，默认为 1；非幂等请求需由调用方保证安全
+     */
+    retry(retry?: number): this;
     /**
      * --- 设置是否跟随请求方的 location，留空为跟随，不设置为不跟随 ---
      * @param follow

package/lib/undici/request.js

@@ -59,6 +59,14 @@ export class Request {
         this._opt['timeout'] = timeout;
         return this;
     }
+    /**
+     * --- 设置网络异常后的重试次数 ---
+     * @param retry 重试次数，默认为 1；非幂等请求需由调用方保证安全
+     */
+    retry(retry = 1) {
+        this._opt['retry'] = retry;
+        return this;
+    }
     /**
      * --- 设置是否跟随请求方的 location，留空为跟随，不设置为不跟随 ---
      * @param follow

package/lib/undici/response.d.ts

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2020-4-9 15:33:06
- * Last: 2020-4-12 11:12:03, 2022-09-10 12:43:23, 2022-12-25 15:12:57, 2023-9-26 14:20:41
+ * Last: 2020-4-12 11:12:03, 2022-09-10 12:43:23, 2022-12-25 15:12:57, 2023-9-26 14:20:41, 2026-8-22
  */
 import * as undici from 'undici';
 import * as zlib from 'zlib';

package/lib/undici/response.js

@@ -28,7 +28,8 @@ export class Response {
             return this._req ? await lBuffer.getFull(stream) : null;
         }
         catch (e) {
-            lCore.log({}, '[Undici][Response][getContent] ' + e.message, '-error');
+            this.error = e instanceof Error ? e : new Error(String(e));
+            lCore.log({}, '[Undici][Response][getContent] ' + lText.stringifyError(e), '-error');
             return null;
         }
     }

package/lib/undici.d.ts

@@ -41,7 +41,7 @@ export declare function postJson(u: string, data: kebab.Json[] | Record<string,
  * @param data 数据
  * @param opt 选项
  */
-export declare function postJsonResponseJson(u: string, data: kebab.Json[] | Record<string, kebab.Json>, opt?: IRequestOptions): Promise<kebab.Json | null>;
+export declare function postJsonResponseJson(u: string, data: kebab.Json[] | Record<string, kebab.Json>, opt?: IRequestOptions): Promise<kebab.Json | null | false>;
 /**
  * --- 发起 POST 请求并解析 JSON 响应 ---
  * @param u 网址
@@ -49,14 +49,14 @@ export declare function postJsonResponseJson(u: string, data: kebab.Json[] | Rec
  * @param opt 选项
  * @returns JSON 数据，失败时返回 null
  */
-export declare function postResponseJson(u: string, data: Record<string, kebab.Json>, opt?: IRequestOptions): Promise<kebab.Json | null>;
+export declare function postResponseJson(u: string, data: Record<string, kebab.Json>, opt?: IRequestOptions): Promise<kebab.Json | null | false>;
 /**
  * --- 发起 GET 请求并解析 JSON 响应 ---
  * @param u 网址
  * @param opt 选项
  * @returns JSON 数据，失败时返回 null
  */
-export declare function getResponseJson(u: string, opt?: IRequestOptions): Promise<kebab.Json | null>;
+export declare function getResponseJson(u: string, opt?: IRequestOptions): Promise<kebab.Json | null | false>;
 /**
  * --- 发起一个完全兼容 fetch 的请求 ---
  * @param input 请求的 URL 或 Request 对象
@@ -71,6 +71,8 @@ export declare function fetch(input: string | URL | Request, init?: RequestInit
     };
     /** --- 自定义 host 映射，如 {'www.maiyun.net': '127.0.0.1'}，或全部映射到一个 host --- */
     'hosts'?: Record<string, string> | string;
+    /** --- 网络异常后的重试次数，默认 0；流式请求体不可重试，非幂等请求需由调用方保证安全 --- */
+    'retry'?: number;
 }): Promise<Response>;
 /**
  * --- 发起一个请求 ---
@@ -126,6 +128,8 @@ export interface IRequestOptions {
     'type'?: 'form' | 'json';
     /** --- 秒数，默认 300 秒 --- */
     'timeout'?: number;
+    /** --- 网络异常后的重试次数，默认 0；流式请求体不可重试，非幂等请求需由调用方保证安全 --- */
+    'retry'?: number;
     /** --- 追踪 location 次数，0 为不追踪，默认为 0 --- */
     'follow'?: number;
     /** --- 自定义 host 映射，如 {'www.maiyun.net': '127.0.0.1'}，或全部映射到一个 host --- */

package/lib/undici.js

@@ -26,6 +26,12 @@ function getMproxyUrl(u, mproxy) {
 }
 /** --- 复用的 undici.agent 对象列表 --- */
 const agents = new Map();
+/** --- 可重试的网络异常代码 --- */
+const retryErrorCodes = [
+    'ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'ENETDOWN', 'ENETUNREACH',
+    'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'ETIMEDOUT', 'UND_ERR_SOCKET',
+    'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT'
+];
 /** --- 获取或创建 undici.agent 对象 --- */
 function getAgent(opt = {}) {
     let k = opt.reuse ?? 'default';
@@ -59,6 +65,27 @@ function getAgent(opt = {}) {
     }
     return agents.get(k);
 }
+/**
+ * --- 获取请求使用的 dispatcher ---
+ * @param opt 请求选项
+ * @param method 请求方法
+ * @param data 请求数据
+ * @returns 普通或带网络异常重试能力的 dispatcher
+ */
+function getDispatcher(opt, method, data) {
+    const agent = getAgent(opt);
+    const retry = (typeof opt.retry === 'number') && Number.isFinite(opt.retry) ?
+        Math.max(0, Math.floor(opt.retry)) : 0;
+    if ((retry === 0) || (data instanceof stream.Readable)) {
+        return agent;
+    }
+    return new undici.RetryAgent(agent, {
+        'maxRetries': retry,
+        'methods': [method],
+        'statusCodes': [],
+        'errorCodes': retryErrorCodes,
+    });
+}
 /**
  * --- 创建一个请求对象 ---
  * @param u
@@ -109,9 +136,13 @@ export async function postJsonResponseJson(u, data, opt = {}) {
     if (!rtn) {
         return null;
     }
-    const json = lText.parseJson(rtn.toString());
+    const rtnStr = rtn.toString();
+    const json = lText.parseJson(rtnStr);
     if (!json) {
-        return null;
+        if (opt.log === undefined || opt.log) {
+            lCore.log({}, `[UNDICI][POSTJSONRESPONSEJSON] parse json failed, url: ${u}, data: ${lText.stringifyJson(data)}, content: ${rtnStr}`, '-neterror');
+        }
+        return false;
     }
     return json;
 }
@@ -129,9 +160,13 @@ export async function postResponseJson(u, data, opt = {}) {
     if (!rtn) {
         return null;
     }
-    const json = lText.parseJson(rtn.toString());
+    const rtnStr = rtn.toString();
+    const json = lText.parseJson(rtnStr);
     if (!json) {
-        return null;
+        if (opt.log === undefined || opt.log) {
+            lCore.log({}, `[UNDICI][POSTRESPONSEJSON] parse json failed, url: ${u}, data: ${lText.stringifyJson(data)}, content: ${rtnStr}`, '-neterror');
+        }
+        return false;
     }
     return json;
 }
@@ -147,9 +182,13 @@ export async function getResponseJson(u, opt = {}) {
     if (!rtn) {
         return null;
     }
-    const json = lText.parseJson(rtn.toString());
+    const rtnStr = rtn.toString();
+    const json = lText.parseJson(rtnStr);
     if (!json) {
-        return null;
+        if (opt.log === undefined || opt.log) {
+            lCore.log({}, `[UNDICI][GETRESPONSEJSON] parse json failed, url: ${u}, content: ${rtnStr}`, '-neterror');
+        }
+        return false;
     }
     return json;
 }
@@ -244,6 +283,7 @@ export async function fetch(input, init = {}) {
         'headers': headers,
         'hosts': init.hosts,
         'mproxy': init.mproxy,
+        'retry': init.retry,
         'signal': init.signal ?? undefined,
         'follow': init.redirect === 'follow' ? 10 : 0,
     };
@@ -387,7 +427,7 @@ export async function request(u, data, opt = {}) {
             }
             return res;
         }
-        const agent = getAgent(opt);
+        const dispatcher = getDispatcher(opt, method, data);
         req = await undici.request(opt.mproxy ? getMproxyUrl(u, opt.mproxy) : u, {
             'method': method,
             'body': data,
@@ -395,7 +435,7 @@ export async function request(u, data, opt = {}) {
             'headersTimeout': timeout * 1_000,
             'bodyTimeout': timeout * 1_000,
             'signal': opt.signal,
-            'dispatcher': agent,
+            'dispatcher': dispatcher,
         });
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.15.6",
+  "version": "9.16.0",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [

package/sys/child.js

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2019-5-3 23:54
- * Last: 2020-3-31 15:01:07, 2020-4-9 22:28:50, 2022-07-22 14:19:46, 2022-9-29 22:11:07, 2023-5-1 18:26:57, 2024-1-12 13:32:00, 2024-3-4 16:49:19, 2026-3-8 16:21:40
+ * Last: 2020-3-31 15:01:07, 2020-4-9 22:28:50, 2022-07-22 14:19:46, 2022-9-29 22:11:07, 2023-5-1 18:26:57, 2024-1-12 13:32:00, 2024-3-4 16:49:19, 2026-3-8 16:21:40, 2026-8-22
  */
 import * as http2 from 'http2';
 import * as tls from 'tls';
@@ -57,15 +57,18 @@ const http2Sessions = new Set();
  * @param method 请求方法
  */
 function wrapWithLinkCount(key, handler, errorPrefix, method = 'GET') {
-    linkCount[key] = (linkCount[key] ?? 0) + 1;
-    const trackId = sMonitor.track(key, method);
-    handler().catch((e) => {
-        lCore.log({}, `${errorPrefix} ${lText.stringifyJson(e.stack).slice(1, -1)}`, '-error');
+    const queryIndex = key.search(/[?#]/u);
+    /** --- 查询参数可能含敏感信息，请求计数与诊断仅保留路径 --- */
+    const requestKey = queryIndex === -1 ? key : key.slice(0, queryIndex);
+    linkCount[requestKey] = (linkCount[requestKey] ?? 0) + 1;
+    const trackId = sMonitor.track(requestKey, method);
+    Promise.resolve().then(handler).catch((e) => {
+        lCore.log({}, `${errorPrefix} ${lText.stringifyError(e)}`, '-error');
     }).finally(() => {
         sMonitor.untrack(trackId);
-        --linkCount[key];
-        if (!linkCount[key]) {
-            delete linkCount[key];
+        --linkCount[requestKey];
+        if (!linkCount[requestKey]) {
+            delete linkCount[requestKey];
         }
     });
 }
@@ -295,8 +298,8 @@ async function requestHandler(req, res, https) {
                             'req': req,
                             'get': uri.query ? lText.queryParse(uri.query) : {},
                             'cookie': {},
-                            'headers': {}
-                        }, '[CHILD][requestHandler][E0]' + lText.stringifyJson(e.stack).slice(1, -1), '-error');
+                            'headers': {},
+                        }, '[CHILD][requestHandler][E0]' + lText.stringifyError(e), '-error');
                         const content = '<h1>500 Server Error</h1><hr>Kebab';
                         if (!res.headersSent) {
                             res.setHeader('content-type', 'text/html; charset=utf-8');
@@ -339,7 +342,7 @@ async function requestHandler(req, res, https) {
                     }
                 }
                 catch (e) {
-                    lCore.log({}, '[CHILD][requestHandler][E1]' + lText.stringifyJson(e.stack).slice(1, -1), '-error');
+                    lCore.log({}, '[CHILD][requestHandler][E1]' + lText.stringifyError(e), '-error');
                     const content = '<h1>500 Server Error</h1><hr>Kebab';
                     if (!res.headersSent) {
                         res.setHeader('content-type', 'text/html; charset=utf-8');
@@ -618,7 +621,7 @@ process.on('message', function (msg) {
             }
         }
     })().catch(function (e) {
-        lCore.log({}, '[CHILD][process][message] ' + lText.stringifyJson(e.stack).slice(1, -1), '-error');
+        lCore.log({}, '[CHILD][process][message] ' + lText.stringifyError(e), '-error');
     });
 });
 /**

package/sys/ctr.js

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2020-3-14 17:24:38
- * Last: 2020-3-30 15:31:40, 2022-07-22 16:59:00, 2022-09-12 23:51:56, 2022-09-23 15:53:58, 2022-12-29 01:18:08, 2023-2-28 20:07:57, 2023-12-27 18:39:35, 2024-3-1 19:38:53, 2024-4-9 16:03:58, 2025-2-12 18:55:44, 2025-6-12 16:56:08
+ * Last: 2020-3-30 15:31:40, 2022-07-22 16:59:00, 2022-09-12 23:51:56, 2022-09-23 15:53:58, 2022-12-29 01:18:08, 2023-2-28 20:07:57, 2023-12-27 18:39:35, 2024-3-1 19:38:53, 2024-4-9 16:03:58, 2025-2-12 18:55:44, 2025-6-12 16:56:08, 2026-8-22
  */
 import ejs from 'ejs';
 import * as lCore from '#kebab/lib/core.js';
@@ -128,7 +128,7 @@ export class Ctr {
                 }
             })().catch(e => {
                 lCore.display('[ERROR][CTR][ASYNCTASK]', e);
-                lCore.log(this, '[CTR][_asyncTask] ' + lText.stringifyJson(e.stack).slice(1, -1), '-error');
+                lCore.log(this, '[CTR][_asyncTask] ' + lText.stringifyError(e), '-error');
                 --this._waitInfo.asyncTask.count;
                 if (!this._waitInfo.asyncTask.count) {
                     this._waitInfo.asyncTask.resolve();
@@ -367,7 +367,7 @@ export class Ctr {
         }
         catch (e) {
             lCore.debug(`[CTR][_loadReactPage] ${e.message ?? ''}`);
-            lCore.log(this, '[CTR][_loadReactPage] ' + lText.stringifyJson(e.stack).slice(1, -1), '-error');
+            lCore.log(this, '[CTR][_loadReactPage] ' + lText.stringifyError(e), '-error');
             return '';
         }
     }

package/sys/monitor/watchdog.js

@@ -1,6 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2026-02-08
+ * Last: 2026-08-22
  * --- 看门狗 Worker 线程，独立事件循环监控主线程心跳 ---
  * --- 阻塞时通过 inspector.connectToMainThread() 远程抓取主线程 JS 调用栈和 CPU Profile ---
  * --- 看门狗必须最小依赖、最大自治，不引入项目库，确保主线程异常时仍能可靠运行 ---
@@ -10,7 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as inspector from 'inspector';
 const data = workerThreads.workerData;
-const view = new Int32Array(data.buffer);
+const view = new Uint32Array(data.buffer);
 /** --- 上次告警时间（秒级时间戳） --- */
 let lastAlertTime = 0;
 /** --- 是否正在诊断采集 --- */
@@ -66,8 +67,8 @@ function captureDiag(blockSec) {
         return;
     }
     capturing = true;
-    const diagDir = path.join(data.logDir, 'monitor', String(data.pid));
     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();
     try {
         session.connectToMainThread();
@@ -152,13 +153,15 @@ function captureDiag(blockSec) {
                 // --- 写入堆栈文件 ---
                 try {
                     fs.mkdirSync(diagDir, {
-                        'recursive': true, 'mode': 0o777,
+                        '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': 0o777 });
+                    fs.writeFileSync(path.join(diagDir, `blocked-stack-${ts}.txt`), content, { 'mode': 0o600 });
+                    fs.chmodSync(path.join(diagDir, `blocked-stack-${ts}.txt`), 0o600);
                 }
                 catch {
                     // --- 忽略 ---
@@ -230,7 +233,8 @@ function collectProfile(session, diagDir, ts) {
                 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': 0o777 });
+                            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 {
                             // --- 忽略 ---

package/sys/monitor.d.ts

@@ -3,15 +3,18 @@ interface ISnapshotRequest {
     'url': string;
     'method': string;
     'duration': number;
+    /** --- 请求存续期间的进程整体用户态 CPU 增量（微秒），不代表请求独占 --- */
     'cpuUser': number;
+    /** --- 请求存续期间的进程整体系统态 CPU 增量（微秒），不代表请求独占 --- */
     'cpuSystem': number;
+    /** --- 请求存续期间的进程整体 RSS 增量（bytes），不代表请求独占 --- */
     'memDelta': number;
 }
 /** --- 整体资源快照 --- */
 export interface ISnapshot {
     'pid': number;
     'time': number;
-    /** --- 本进程 CPU 占用（单核基准，0-100） --- */
+    /** --- 本进程 CPU 占用，100 代表占满一个逻辑核心，多线程时可超过 100 --- */
     'cpuProcess': number;
     /** --- 系统总 CPU 占用（所有核心合计，0-100，与任务管理器一致） --- */
     'cpuOs': number;
@@ -32,7 +35,9 @@ export interface ISnapshot {
         'free': number;
     };
     'eloopLag': number;
+    /** --- 最早开始的活跃请求，最多 100 条 --- */
     'activeRequests': ISnapshotRequest[];
+    /** --- 全部活跃请求数量，可能大于 activeRequests.length --- */
     'activeCount': number;
 }
 /**
@@ -46,6 +51,8 @@ export declare function start(opt?: {
     'mem'?: number;
     /** --- 事件循环延迟阈值 ms，默认 500 --- */
     'eloop'?: number;
+    /** --- 内存超阈值时是否采集堆快照，默认 false --- */
+    'heapSnapshot'?: boolean;
 }): void;
 /**
  * --- 停止性能监控 ---