@maiyunnet/kebab 2.0.7 → 2.0.8

package/lib/core.d.ts

@@ -4,6 +4,7 @@ import * as stream from 'stream';
 import * as lResponse from '../lib/net/response';
 import * as sCtr from '../sys/ctr';
 import * as types from '../types';
+/** --- 全局参数 --- */
 export declare const globalConfig: types.IConfig & {
     'httpPort': number;
     'httpsPort': number;
@@ -12,6 +13,7 @@ export declare const globalConfig: types.IConfig & {
     'debug': boolean;
     'max': number;
 };
+/** --- Cookie 设置的选项 --- */
 export interface ICookieOptions {
     'ttl'?: number;
     'path'?: string;
@@ -20,7 +22,20 @@ export interface ICookieOptions {
     'httponly'?: boolean;
     'samesite'?: 'None' | 'Lax' | 'Strict';
 }
+/**
+ * --- 设置 cookie ---
+ * @param ctr ctr 实例
+ * @param name 名
+ * @param value 值
+ * @param opt 选项，ttl, 默认和 undefined 为关闭浏览器失效
+ */
 export declare function setCookie(ctr: sCtr.Ctr, name: string, value: string, opt?: ICookieOptions): void;
+/**
+ * --- 生成基础的范围随机数 ---
+ * @param min >= 最小值
+ * @param max <= 最大值
+ * @param prec 保留几位小数
+ */
 export declare function rand(min: number, max: number, prec?: number): number;
 export declare const RANDOM_N = "0123456789";
 export declare const RANDOM_U = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
@@ -31,12 +46,41 @@ export declare const RANDOM_LU: string;
 export declare const RANDOM_LUN: string;
 export declare const RANDOM_V = "ACEFGHJKLMNPRSTWXY34567";
 export declare const RANDOM_LUNS: string;
+/**
+ * --- 生成随机字符串 ---
+ * @param length 长度
+ * @param source 采样值
+ * @param block 排除的字符
+ */
 export declare function random(length?: number, source?: string, block?: string): string;
 export declare const CONVERT62_CHAR = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+/**
+ * --- 将 10 进制转换为 62 进制 ---
+ * @param n 10 进制数字最大 9223372036854775807n
+ */
 export declare function convert62(n: bigint | number | string): string;
+/**
+ * --- 将 62 进制转换为 10 进制 ---
+ * @param n 62 进制数字最大 aZl8N0y58M7
+ */
 export declare function unconvert62(n: string): bigint;
+/**
+ * --- 去除 html 的空白符、换行以及注释 ---
+ * @param text 要纯净的字符串
+ */
 export declare function purify(text: string): string;
+/**
+ * --- 判断一个对象是否符合示例组，返回空字符串代表校验通过，返回：应该的类型:位置:传入的类型 ---
+ * @param val 对象
+ * @param type 示例组
+ * @param tree 当前树，无需传入
+ */
 export declare function checkType(val: any, type: any, tree?: string): string;
+/**
+ * --- 获取 MUID ---
+ * @param ctr Ctr 对象
+ * @param opt len: 8 - 32, 默认 8; bin: 是否含有大小写, 默认 true; key: 多样性混合, 默认空; insert: 插入指定字符, 最好不超过 2 字符，默认空，num: 是否含有数字，默认 true
+ */
 export declare function muid(ctr: sCtr.Ctr, opt?: {
     'len'?: number;
     'bin'?: boolean;
@@ -44,24 +88,84 @@ export declare function muid(ctr: sCtr.Ctr, opt?: {
     'insert'?: string;
     'num'?: boolean;
 }): string;
+/**
+ * --- 获取 IP（非安全 IP）---
+ * @param ctr
+ */
 export declare function ip(ctr: sCtr.Ctr | http.IncomingHttpHeaders, req?: http2.Http2ServerRequest | http.IncomingMessage): string;
 export declare const REAL_IP_X = "x-forwarded-for";
 export declare const REAL_IP_CF = "cf-connecting-ip";
+/**
+ * --- 获取直连 IP（安全 IP） ---
+ * @param ctr
+ * @param name 输入安全的 header
+ */
 export declare function realIP(ctr: sCtr.Ctr, name?: string): string;
+/**
+ * --- 间隔一段时间 ---
+ * @param ms 间隔毫秒
+ */
 export declare function sleep(ms: number): Promise<void>;
+/**
+ * --- 将对象进行升序排列 ---
+ * @param o 要重排的对象
+ */
 export declare function objectSort<T extends Record<string, any>>(o: T): T;
+/**
+ * --- 将对象的所有属性清除包括键，不会破坏引用关系，对象变量依然保证是引用状态 ---
+ * @param obj 要清除的对象
+ * @patam deep 也将子项都清空，如果子项有独立引用的话也要清空的话则要设置为 true
+ */
 export declare function emptyObject(obj: Record<string, types.Json>, deep?: boolean): void;
+/**
+ * --- 调用前自行创建 passThrough，并且调用 pipe 绑定到应该绑定的对象，然后再调用本函数 ---
+ * @param passThrough passThrough 对象
+ * @param data 数组
+ * @param end 是否关闭写入，默认是，关闭后 passThrough 不能被写入，但仍然可读
+ */
 export declare function passThroughAppend(passThrough: stream.PassThrough, data: Array<stream.Readable | lResponse.Response | string | Buffer>, end?: boolean): Promise<void>;
+/**
+ * --- 执行命令行 ---
+ * @param command 命令字符串
+ */
 export declare function exec(command: string): Promise<string | false>;
+/**
+ * --- 向主进程（或局域网同代码机子）发送广播将进行 reload 操作，等待回传 ---
+ * --- 主要作用除代码热更新以外的其他情况 ---
+ */
 export declare function sendReload(hosts?: string[]): Promise<string[]>;
+/**
+ * --- 向主进程（或局域网同代码机子）发送广播将进行 restart 操作，停止监听并启动新进程，老进程在连接全部断开后自行销毁 ---
+ * --- 主要用作不间断的代码热更新 ---
+ */
 export declare function sendRestart(hosts?: string[]): Promise<string[]>;
+/** --- 跨进程全局变量 --- */
 export declare const global: Record<string, any>;
+/**
+ * --- 设置跨线程的全局变量 ---
+ * @param key 变量名
+ * @param data 变量值
+ * @param hosts 局域网列表
+ */
 export declare function setGlobal(key: string, data: types.Json, hosts?: string[]): Promise<string[]>;
+/**
+ * --- 移除某个跨线程全局变量 ---
+ * @param key 变量名
+ * @param hosts 局域网列表
+ */
 export declare function removeGlobal(key: string, hosts?: string[]): Promise<string[]>;
+/**
+ * --- 上传并覆盖代码文件，config.json、kebab.json、.js.map、.ts, .gitignore 不会被覆盖和新建 ---
+ * @param sourcePath zip 文件
+ * @param path 要覆盖到的路径，无所谓是否 / 开头 / 结尾，是对方 kebab 的根据路开始算起
+ * @param hosts 局域网多机部署，不设置默认本机部署
+ * @param config 是否自动更新 config 的 set.staticVer 为最新，默认更新
+ */
 export declare function updateCode(sourcePath: string, path: string, hosts?: string[], config?: boolean): Promise<Record<string, {
     'result': boolean;
     'return': string;
 }>>;
+/** --- log 设置的选项 --- */
 export interface ILogOptions {
     'path': string;
     'urlFull': string;
@@ -71,15 +175,45 @@ export interface ILogOptions {
     'cookie': Record<string, string>;
     'headers': http.IncomingHttpHeaders;
 }
+/**
+ * --- 写入文件日志 ---
+ * @param msg 自定义内容
+ * @param fend 文件名追加
+ * @param opt 选项
+ */
 export declare function log(opt: sCtr.Ctr | ILogOptions, msg: string, fend?: string): Promise<void>;
+/**
+ * --- 获取日志内容为一个数组 ---
+ * @param opt 参数
+ */
 export declare function getLog(opt: {
+    /** --- 如 127.0.0.1 --- */
     'host': string;
+    /** --- 如 2024/08/01/22 --- */
     'path': string;
+    /** --- 如 -error --- */
     'fend'?: string;
+    /** --- 仅显示被搜索到的行 --- */
     'search'?: string;
+    /** --- 跳过条数 --- */
     'offset'?: number;
+    /** --- 最大限制，默认 100 --- */
     'limit'?: number;
 }): Promise<string[][] | null | false>;
+/**
+ * --- 完整的克隆一份数组/对象，Kebab: yes, Mutton: no ---
+ * @param obj 要克隆的对象
+ */
 export declare function clone(obj: Record<string, any> | any[]): any[] | any;
+/**
+ * --- 打印调试信息，线上环境不会打印 ---
+ * @param message 参数
+ * @param optionalParams 参数
+ */
 export declare function debug(message?: any, ...optionalParams: any[]): void;
+/**
+ * --- 向控制台直接显示内容，一般情况下禁止使用 ---
+ * @param message 参数
+ * @param optionalParams 参数
+ */
 export declare function display(message?: any, ...optionalParams: any[]): void;

package/lib/core.js

@@ -59,6 +59,11 @@ exports.getLog = getLog;
 exports.clone = clone;
 exports.debug = debug;
 exports.display = display;
+/**
+ * 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
+ */
 const cp = __importStar(require("child_process"));
 const stream = __importStar(require("stream"));
 const lTime = __importStar(require("../lib/time"));
@@ -69,12 +74,25 @@ const lCrypto = __importStar(require("../lib/crypto"));
 const lResponse = __importStar(require("../lib/net/response"));
 const sCtr = __importStar(require("../sys/ctr"));
 const kebab = __importStar(require("../index"));
+/** --- 全局参数 --- */
 exports.globalConfig = {};
+/**
+ * --- 设置 cookie ---
+ * @param ctr ctr 实例
+ * @param name 名
+ * @param value 值
+ * @param opt 选项，ttl, 默认和 undefined 为关闭浏览器失效
+ */
 function setCookie(ctr, name, value, opt = {}) {
     const res = ctr.getPrototype('_res');
     if (!res) {
         return;
     }
+    /*
+    const expires =  lTime.get(ctr, {
+        'data': lTime.stamp() + ttl
+    }).toUTCString();
+    */
     const maxAge = opt.ttl === undefined ? '' : `; Max-Age=${opt.ttl}`;
     const path = `; path=${opt.path ?? '/'}`;
     const domain = opt.domain ? `; domain=${opt.domain}` : '';
@@ -82,9 +100,16 @@ function setCookie(ctr, name, value, opt = {}) {
     const httpOnly = opt.httponly ? '; HttpOnly' : '';
     const sameSite = opt.samesite ? '; SameSite=' + opt.samesite : '';
     const cookies = res.getHeader('set-cookie') ?? [];
+    // cookies.push(`${name}=${encodeURIComponent(value)}; expires=${expires}; Max-Age=${ttl}${path}${domain}${secure}${httpOnly}`);
     cookies.push(`${name}=${encodeURIComponent(value)}${maxAge}${path}${domain}${secure}${httpOnly}${sameSite}`);
     res.setHeader('set-cookie', cookies);
 }
+/**
+ * --- 生成基础的范围随机数 ---
+ * @param min >= 最小值
+ * @param max <= 最大值
+ * @param prec 保留几位小数
+ */
 function rand(min, max, prec = 0) {
     if (prec < 0) {
         prec = 0;
@@ -94,6 +119,7 @@ function rand(min, max, prec = 0) {
     max = max * p;
     return Math.round(Math.random() * (max - min) + min) / p;
 }
+// --- 随机 ---
 exports.RANDOM_N = '0123456789';
 exports.RANDOM_U = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
 exports.RANDOM_L = 'abcdefghijklmnopqrstuvwxyz';
@@ -103,7 +129,14 @@ exports.RANDOM_LU = exports.RANDOM_L + exports.RANDOM_U;
 exports.RANDOM_LUN = exports.RANDOM_L + exports.RANDOM_U + exports.RANDOM_N;
 exports.RANDOM_V = 'ACEFGHJKLMNPRSTWXY34567';
 exports.RANDOM_LUNS = exports.RANDOM_LUN + '()`~!@#$%^&*-+=_|{}[]:;"<>,.?/]"';
+/**
+ * --- 生成随机字符串 ---
+ * @param length 长度
+ * @param source 采样值
+ * @param block 排除的字符
+ */
 function random(length = 8, source = exports.RANDOM_LN, block = '') {
+    // --- 剔除 block 字符 ---
     let len = block.length;
     if (len > 0) {
         for (let i = 0; i < len; ++i) {
@@ -121,6 +154,10 @@ function random(length = 8, source = exports.RANDOM_LN, block = '') {
     return temp;
 }
 exports.CONVERT62_CHAR = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+/**
+ * --- 将 10 进制转换为 62 进制 ---
+ * @param n 10 进制数字最大 9223372036854775807n
+ */
 function convert62(n) {
     if (typeof n !== 'bigint') {
         n = BigInt(n);
@@ -132,6 +169,10 @@ function convert62(n) {
     }
     return res;
 }
+/**
+ * --- 将 62 进制转换为 10 进制 ---
+ * @param n 62 进制数字最大 aZl8N0y58M7
+ */
 function unconvert62(n) {
     let res = 0n;
     const nl = n.length;
@@ -140,6 +181,10 @@ function unconvert62(n) {
     }
     return res;
 }
+/**
+ * --- 去除 html 的空白符、换行以及注释 ---
+ * @param text 要纯净的字符串
+ */
 function purify(text) {
     text = '>' + text + '<';
     const keepScripts = [];
@@ -163,9 +208,17 @@ function purify(text) {
     });
     return text.slice(1, -1);
 }
+/**
+ * --- 判断一个对象是否符合示例组，返回空字符串代表校验通过，返回：应该的类型:位置:传入的类型 ---
+ * @param val 对象
+ * @param type 示例组
+ * @param tree 当前树，无需传入
+ */
 function checkType(val, type, tree = 'root') {
+    /** --- 要校验的对象 --- */
     const vtype = typeof val;
     if (Array.isArray(type)) {
+        // --- 数组的话 ---
         if (!Array.isArray(val)) {
             return 'array:' + tree + ':' + vtype;
         }
@@ -177,8 +230,10 @@ function checkType(val, type, tree = 'root') {
         }
         return '';
     }
+    /** --- 要符合的类型 --- */
     const ttype = typeof type;
     if (type instanceof RegExp) {
+        // --- 正则 ---
         if (vtype !== 'string') {
             return 'regexp:' + tree + ':' + vtype;
         }
@@ -188,6 +243,7 @@ function checkType(val, type, tree = 'root') {
         if (vtype !== 'string' && val !== undefined && val !== null) {
             return 'string:' + tree + ':' + vtype;
         }
+        // --- 是字符串、undefined、null ---
         if (type) {
             return val ? '' : 'require:' + tree + ':' + vtype;
         }
@@ -206,12 +262,14 @@ function checkType(val, type, tree = 'root') {
         if (!Object.keys(type).length) {
             return '';
         }
+        // --- 先判断每个值是否相等 ---
         for (const key in type) {
             const res = checkType(val[key], type[key], tree + '.' + key);
             if (res) {
                 return res;
             }
         }
+        // --- 再判断是否传了类型限定中没有的值 ---
         for (const key in val) {
             if (type[key] !== undefined) {
                 continue;
@@ -222,6 +280,11 @@ function checkType(val, type, tree = 'root') {
     }
     return vtype === ttype ? '' : ttype + ':' + tree + ':' + vtype;
 }
+/**
+ * --- 获取 MUID ---
+ * @param ctr Ctr 对象
+ * @param opt len: 8 - 32, 默认 8; bin: 是否含有大小写, 默认 true; key: 多样性混合, 默认空; insert: 插入指定字符, 最好不超过 2 字符，默认空，num: 是否含有数字，默认 true
+ */
 function muid(ctr, opt = {}) {
     const len = opt.len ?? 8;
     const bin = opt.bin ?? true;
@@ -240,9 +303,14 @@ function muid(ctr, opt = {}) {
     if (!char) {
         return '';
     }
+    // --- 生成随机数 ---
     const over = random(len - 1 - ilen, bin ? (num ? exports.RANDOM_LUN : exports.RANDOM_LU) : (num ? exports.RANDOM_LN : exports.RANDOM_L)) + char[20];
     return over[0] + insert + over.slice(1);
 }
+/**
+ * --- 获取 IP（非安全 IP）---
+ * @param ctr
+ */
 function ip(ctr, req) {
     const headers = ctr instanceof sCtr.Ctr ? ctr.getPrototype('_headers') : ctr;
     if (typeof headers['cf-connecting-ip'] === 'string') {
@@ -265,6 +333,11 @@ function ip(ctr, req) {
 }
 exports.REAL_IP_X = 'x-forwarded-for';
 exports.REAL_IP_CF = 'cf-connecting-ip';
+/**
+ * --- 获取直连 IP（安全 IP） ---
+ * @param ctr
+ * @param name 输入安全的 header
+ */
 function realIP(ctr, name = '') {
     const headers = ctr.getPrototype('_headers');
     if (name !== '') {
@@ -276,6 +349,11 @@ function realIP(ctr, name = '') {
     const req = ctr.getPrototype('_req');
     return req.socket.remoteAddress ?? '';
 }
+// --- 以下 Mutton 没有 ---
+/**
+ * --- 间隔一段时间 ---
+ * @param ms 间隔毫秒
+ */
 function sleep(ms) {
     return new Promise(function (resolve) {
         setTimeout(function () {
@@ -283,6 +361,10 @@ function sleep(ms) {
         }, ms);
     });
 }
+/**
+ * --- 将对象进行升序排列 ---
+ * @param o 要重排的对象
+ */
 function objectSort(o) {
     const ordered = {};
     const list = Object.keys(o).sort();
@@ -296,6 +378,11 @@ function objectSort(o) {
     }
     return ordered;
 }
+/**
+ * --- 将对象的所有属性清除包括键，不会破坏引用关系，对象变量依然保证是引用状态 ---
+ * @param obj 要清除的对象
+ * @patam deep 也将子项都清空，如果子项有独立引用的话也要清空的话则要设置为 true
+ */
 function emptyObject(obj, deep = false) {
     const keys = Object.keys(obj);
     for (const key of keys) {
@@ -308,10 +395,17 @@ function emptyObject(obj, deep = false) {
         delete obj[key];
     }
 }
+/**
+ * --- 调用前自行创建 passThrough，并且调用 pipe 绑定到应该绑定的对象，然后再调用本函数 ---
+ * @param passThrough passThrough 对象
+ * @param data 数组
+ * @param end 是否关闭写入，默认是，关闭后 passThrough 不能被写入，但仍然可读
+ */
 async function passThroughAppend(passThrough, data, end = true) {
     for (const item of data) {
         if (item instanceof stream.Readable || item instanceof lResponse.Response) {
             const stm = item instanceof stream.Readable ? item : item.getStream();
+            // --- 读取流、Net 库 Response 对象 ---
             stm.pipe(passThrough, {
                 'end': false
             });
@@ -322,6 +416,7 @@ async function passThroughAppend(passThrough, data, end = true) {
             });
         }
         else {
+            // --- 字符串、Buffer ---
             await new Promise((resolve) => {
                 passThrough.write(item, () => {
                     resolve();
@@ -333,6 +428,10 @@ async function passThroughAppend(passThrough, data, end = true) {
         passThrough.end();
     }
 }
+/**
+ * --- 执行命令行 ---
+ * @param command 命令字符串
+ */
 function exec(command) {
     return new Promise(function (resolve) {
         cp.exec(command, function (err, stdout) {
@@ -344,15 +443,23 @@ function exec(command) {
         });
     });
 }
+/**
+ * --- 向主进程（或局域网同代码机子）发送广播将进行 reload 操作，等待回传 ---
+ * --- 主要作用除代码热更新以外的其他情况 ---
+ */
 async function sendReload(hosts) {
     if (!hosts) {
+        // --- 本地模式 ---
+        // eslint-disable-next-line no-console
         console.log('[ Child] Sending reload request...');
         process.send({
             'action': 'reload'
         });
         return [];
     }
+    // --- 局域网模式 ---
     const time = lTime.stamp();
+    /** --- 返回成功的 host --- */
     const rtn = [];
     for (const host of hosts) {
         const res = await lNet.get('http://' + host + ':' + exports.globalConfig.rpcPort.toString() + '/' + lCrypto.aesEncrypt(lText.stringifyJson({
@@ -372,15 +479,23 @@ async function sendReload(hosts) {
     }
     return rtn;
 }
+/**
+ * --- 向主进程（或局域网同代码机子）发送广播将进行 restart 操作，停止监听并启动新进程，老进程在连接全部断开后自行销毁 ---
+ * --- 主要用作不间断的代码热更新 ---
+ */
 async function sendRestart(hosts) {
     if (!hosts) {
+        // --- 本地模式 ---
+        // eslint-disable-next-line no-console
         console.log('[ Child] Sending restart request...');
         process.send({
             'action': 'restart'
         });
         return [];
     }
+    // --- 局域网模式 ---
     const time = lTime.stamp();
+    /** --- 返回成功的 host --- */
     const rtn = [];
     for (const host of hosts) {
         const res = await lNet.get('http://' + host + ':' + exports.globalConfig.rpcPort.toString() + '/' + lCrypto.aesEncrypt(lText.stringifyJson({
@@ -400,9 +515,17 @@ async function sendRestart(hosts) {
     }
     return rtn;
 }
+/** --- 跨进程全局变量 --- */
 exports.global = {};
+/**
+ * --- 设置跨线程的全局变量 ---
+ * @param key 变量名
+ * @param data 变量值
+ * @param hosts 局域网列表
+ */
 async function setGlobal(key, data, hosts) {
     if (!hosts) {
+        // --- 本地模式 ---
         process.send({
             'action': 'global',
             'key': key,
@@ -410,7 +533,9 @@ async function setGlobal(key, data, hosts) {
         });
         return [];
     }
+    // --- 局域网模式 ---
     const time = lTime.stamp();
+    /** --- 返回成功的 host --- */
     const rtn = [];
     for (const host of hosts) {
         const res = await lNet.get('http://' + host + ':' + exports.globalConfig.rpcPort.toString() + '/' + lCrypto.aesEncrypt(lText.stringifyJson({
@@ -430,11 +555,24 @@ async function setGlobal(key, data, hosts) {
     }
     return rtn;
 }
+/**
+ * --- 移除某个跨线程全局变量 ---
+ * @param key 变量名
+ * @param hosts 局域网列表
+ */
 async function removeGlobal(key, hosts) {
     return setGlobal(key, null, hosts);
 }
+/**
+ * --- 上传并覆盖代码文件，config.json、kebab.json、.js.map、.ts, .gitignore 不会被覆盖和新建 ---
+ * @param sourcePath zip 文件
+ * @param path 要覆盖到的路径，无所谓是否 / 开头 / 结尾，是对方 kebab 的根据路开始算起
+ * @param hosts 局域网多机部署，不设置默认本机部署
+ * @param config 是否自动更新 config 的 set.staticVer 为最新，默认更新
+ */
 async function updateCode(sourcePath, path, hosts, config = true) {
     hosts ??= ['127.0.0.1'];
+    /** --- 返回成功的 host --- */
     const rtn = {};
     for (const host of hosts) {
         const fd = lNet.getFormData();
@@ -465,6 +603,12 @@ async function updateCode(sourcePath, path, hosts, config = true) {
     }
     return rtn;
 }
+/**
+ * --- 写入文件日志 ---
+ * @param msg 自定义内容
+ * @param fend 文件名追加
+ * @param opt 选项
+ */
 async function log(opt, msg, fend = '') {
     let req;
     let headers;
@@ -526,16 +670,24 @@ async function log(opt, msg, fend = '') {
         'flag': 'a'
     });
 }
+/**
+ * --- 获取日志内容为一个数组 ---
+ * @param opt 参数
+ */
 async function getLog(opt) {
     const path = kebab.LOG_CWD + opt.host + (opt.fend ?? '') + '/' + opt.path + '.csv';
     if (!await lFs.isFile(path)) {
         return null;
     }
+    /** --- 剩余 limit --- */
     let limit = opt.limit ?? 100;
+    /** --- 剩余 offset --- */
     let offset = opt.offset ?? 0;
     return new Promise((resolve) => {
         const list = [];
+        /** --- 当前行号 --- */
         let line = 0;
+        /** --- 当前行数据 --- */
         let packet = '';
         lFs.createReadStream(path, {
             'encoding': 'utf8'
@@ -544,17 +696,21 @@ async function getLog(opt) {
                 return;
             }
             while (true) {
+                // --- 分包 ---
                 const index = buf.indexOf('\n');
                 if (index === -1) {
+                    // --- 本次包还没有结束 ---
                     packet += buf;
                     break;
                 }
+                // --- 本次行结束了 ---
                 if (limit === 0) {
                     break;
                 }
                 packet += buf.slice(0, index);
                 buf = buf.slice(index + 1);
                 ++line;
+                // --- 先执行下本次完成的 ---
                 if (line > 1) {
                     if (offset === 0) {
                         if (!opt.search || packet.includes(opt.search)) {
@@ -589,10 +745,14 @@ async function getLog(opt) {
                         --offset;
                     }
                 }
+                // --- 处理结束 ---
                 packet = '';
+                // --- 看看还有没有后面的粘连包 ---
                 if (!buf.length) {
+                    // --- 没粘连包 ---
                     break;
                 }
+                // --- 有粘连包 ---
             }
         }).on('end', () => {
             resolve(list);
@@ -601,6 +761,10 @@ async function getLog(opt) {
         });
     });
 }
+/**
+ * --- 完整的克隆一份数组/对象，Kebab: yes, Mutton: no ---
+ * @param obj 要克隆的对象
+ */
 function clone(obj) {
     let newObj = {};
     if (obj instanceof Array) {
@@ -652,12 +816,24 @@ function clone(obj) {
     }
     return newObj;
 }
+/**
+ * --- 打印调试信息，线上环境不会打印 ---
+ * @param message 参数
+ * @param optionalParams 参数
+ */
 function debug(message, ...optionalParams) {
     if (!exports.globalConfig.debug) {
         return;
     }
+    // eslint-disable-next-line no-console
     console.debug(message, ...optionalParams);
 }
+/**
+ * --- 向控制台直接显示内容，一般情况下禁止使用 ---
+ * @param message 参数
+ * @param optionalParams 参数
+ */
 function display(message, ...optionalParams) {
+    // eslint-disable-next-line no-console
     console.log(message, ...optionalParams);
 }