befly 3.16.1 → 3.16.4

package/dist/index.js

@@ -195,21 +195,6 @@ export class Befly {
                     noLog = true;
                 }
             }
-            const writePlainLinesToConsole = (prefix, errName, message) => {
-                const text = String(message || "");
-                const parts = text.split("\n");
-                const firstLine = parts.length > 0 ? String(parts[0] || "") : "";
-                const head = `[${prefix}] 启动失败: ${errName}: ${firstLine}`;
-                try {
-                    process.stderr.write(`${head}\n`);
-                    for (let i = 1; i < parts.length; i = i + 1) {
-                        process.stderr.write(`${parts[i]}\n`);
-                    }
-                }
-                catch {
-                    // ignore
-                }
-            };
             // 注意：测试要求 start() 失败时必须 Logger.error 一次，所以这里始终调用 error。
             // 但如果下层已经记录过详细堆栈，则入口只输出摘要，避免重复。
             if (!alreadyLogged && multiline) {
@@ -221,7 +206,17 @@ export class Befly {
                     errorKind: kind,
                     errorMessage: errMessage
                 }, { truncate: false, console: false });
-                writePlainLinesToConsole(appName, errName, errMessage);
+                {
+                    const text = String(errMessage || "");
+                    const parts = text.split("\n");
+                    const firstLine = parts.length > 0 ? String(parts[0] || "") : "";
+                    const lines = [];
+                    lines.push(`[${appName}] 启动失败: ${errName}: ${firstLine}`);
+                    for (let i = 1; i < parts.length; i = i + 1) {
+                        lines.push(String(parts[i] || ""));
+                    }
+                    Logger.printPlainLines(lines, { stream: "stderr" });
+                }
             }
             else if (alreadyLogged) {
                 Logger.error({

package/dist/lib/dbHelper.js

@@ -4,7 +4,6 @@
  */
 import { CoreError } from "../types/coreError";
 import { convertBigIntFields } from "../utils/convertBigIntFields";
-import { fieldClear } from "../utils/fieldClear";
 import { toNumberFromSql, toSqlParams } from "../utils/sqlUtil";
 import { arrayKeysToCamel, isPlainObject, keysToCamel, snakeCase } from "../utils/util";
 import { DbUtils } from "./dbUtils";
@@ -91,7 +90,7 @@ export class DbHelper {
      * 统一的查询参数预处理方法
      */
     async prepareQueryOptions(options) {
-        const cleanWhere = fieldClear(options.where || {}, { excludeValues: [null, undefined] });
+        const cleanWhere = DbUtils.clearDeep(options.where || {});
         const hasJoins = options.joins && options.joins.length > 0;
         // 联查时使用特殊处理逻辑
         if (hasJoins) {
@@ -723,8 +722,8 @@ export class DbHelper {
      */
     async updData(options) {
         const { table, data, where } = options;
-        // 清理条件（排除 null 和 undefined）
-        const cleanWhere = fieldClear(where, { excludeValues: [null, undefined] });
+        // 清理条件（排除 null 和 undefined，递归）
+        const cleanWhere = DbUtils.clearDeep(where);
         // 转换表名：小驼峰 → 下划线
         const snakeTable = snakeCase(table);
         const snakeWhere = DbUtils.whereKeysToSnake(cleanWhere);
@@ -761,8 +760,8 @@ export class DbHelper {
         const { table, where } = options;
         // 转换表名：小驼峰 → 下划线
         const snakeTable = snakeCase(table);
-        // 清理条件字段
-        const cleanWhere = fieldClear(where, { excludeValues: [null, undefined] });
+        // 清理条件字段（排除 null 和 undefined，递归）
+        const cleanWhere = DbUtils.clearDeep(where);
         const snakeWhere = DbUtils.whereKeysToSnake(cleanWhere);
         // 物理删除
         const builder = this.createSqlBuilder().where(snakeWhere);
@@ -850,7 +849,7 @@ export class DbHelper {
             throw new Error(`exists 不支持 schema.table 写法（table: ${rawTable}）`);
         }
         const snakeTable = snakeCase(rawTable);
-        const cleanWhere = fieldClear(options.where || {}, { excludeValues: [null, undefined] });
+        const cleanWhere = DbUtils.clearDeep(options.where || {});
         const snakeWhere = DbUtils.whereKeysToSnake(cleanWhere);
         const whereFiltered = DbUtils.addDefaultStateFilter(snakeWhere, snakeTable, false);
         // 使用 COUNT(1) 实现：语义清晰、适配现有返回结构
@@ -955,8 +954,8 @@ export class DbHelper {
         if (typeof value !== "number" || isNaN(value)) {
             throw new Error(`自增值必须是有效的数字 (table: ${table}, field: ${field}, value: ${value})`);
         }
-        // 清理 where 条件（排除 null 和 undefined）
-        const cleanWhere = fieldClear(where, { excludeValues: [null, undefined] });
+        // 清理 where 条件（排除 null 和 undefined，递归）
+        const cleanWhere = DbUtils.clearDeep(where);
         // 转换 where 条件字段名：小驼峰 → 下划线
         const snakeWhere = DbUtils.whereKeysToSnake(cleanWhere);
         // 使用 SqlBuilder 构建安全的 WHERE 条件

package/dist/lib/dbUtils.d.ts

@@ -10,6 +10,22 @@ type BuildInsertRowOptions = {
     now: number;
 };
 export declare class DbUtils {
+    /**
+     * 深度剔除 null/undefined（通用工具）。
+     *
+     * 说明：
+     * - 仅处理 object 结构；数组默认原样返回（避免误处理 $in/$between 这类“值数组”）。
+     * - 你可以通过 options.arrayObjectKeys 指定“哪些 key 的数组是对象列表，需要递归清理”。
+     *   典型场景：where 的 $or/$and。
+     * - 通过 options.depth 控制清理深度：
+     *   - 0（默认）：递归处理（无限深度）
+     *   - N（正整数）：最多处理 N 层（1 表示只处理当前这一层）
+     *   - 注意：数组本身不计入 depth（例如 where 的 $or/$and 是数组；遍历数组元素不会额外消耗层级）
+     */
+    static clearDeep(value: any, options?: {
+        arrayObjectKeys?: string[];
+        depth?: number;
+    }): any;
     static parseTableRef(tableRef: string): {
         schema: string | null;
         table: string;

package/dist/lib/dbUtils.js

@@ -2,6 +2,86 @@ import { fieldClear } from "../utils/fieldClear";
 import { keysToSnake, snakeCase } from "../utils/util";
 import { SqlCheck } from "./sqlCheck";
 export class DbUtils {
+    /**
+     * 深度剔除 null/undefined（通用工具）。
+     *
+     * 说明：
+     * - 仅处理 object 结构；数组默认原样返回（避免误处理 $in/$between 这类“值数组”）。
+     * - 你可以通过 options.arrayObjectKeys 指定“哪些 key 的数组是对象列表，需要递归清理”。
+     *   典型场景：where 的 $or/$and。
+     * - 通过 options.depth 控制清理深度：
+     *   - 0（默认）：递归处理（无限深度）
+     *   - N（正整数）：最多处理 N 层（1 表示只处理当前这一层）
+     *   - 注意：数组本身不计入 depth（例如 where 的 $or/$and 是数组；遍历数组元素不会额外消耗层级）
+     */
+    static clearDeep(value, options) {
+        const arrayObjectKeys = Array.isArray(options?.arrayObjectKeys) ? options.arrayObjectKeys : ["$or", "$and"];
+        const arrayObjectKeySet = new Set();
+        for (const key of arrayObjectKeys) {
+            arrayObjectKeySet.add(key);
+        }
+        const depthRaw = typeof options?.depth === "number" && Number.isFinite(options.depth) ? Math.floor(options.depth) : 0;
+        const depth = depthRaw < 0 ? 0 : depthRaw;
+        const clearInternal = (input, remainingDepth) => {
+            if (!input || typeof input !== "object") {
+                return input;
+            }
+            if (Array.isArray(input)) {
+                return input;
+            }
+            const canRecurse = remainingDepth === 0 || remainingDepth > 1;
+            const childDepth = remainingDepth === 0 ? 0 : remainingDepth - 1;
+            const result = {};
+            for (const [key, item] of Object.entries(input)) {
+                if (item === undefined || item === null) {
+                    continue;
+                }
+                if (arrayObjectKeySet.has(key)) {
+                    if (!Array.isArray(item)) {
+                        continue;
+                    }
+                    // 数组不计入 depth：递归进入数组元素时不消耗 remainingDepth
+                    const arrayChildDepth = remainingDepth;
+                    const outList = [];
+                    for (const child of item) {
+                        if (!child || typeof child !== "object" || Array.isArray(child)) {
+                            continue;
+                        }
+                        const cleaned = clearInternal(child, arrayChildDepth);
+                        if (!cleaned || typeof cleaned !== "object" || Array.isArray(cleaned)) {
+                            continue;
+                        }
+                        if (Object.keys(cleaned).length === 0) {
+                            continue;
+                        }
+                        outList.push(cleaned);
+                    }
+                    if (outList.length > 0) {
+                        result[key] = outList;
+                    }
+                    continue;
+                }
+                if (typeof item === "object" && !Array.isArray(item)) {
+                    if (!canRecurse) {
+                        result[key] = item;
+                        continue;
+                    }
+                    const cleanedObj = clearInternal(item, childDepth);
+                    if (!cleanedObj || typeof cleanedObj !== "object" || Array.isArray(cleanedObj)) {
+                        continue;
+                    }
+                    if (Object.keys(cleanedObj).length === 0) {
+                        continue;
+                    }
+                    result[key] = cleanedObj;
+                    continue;
+                }
+                result[key] = item;
+            }
+            return result;
+        };
+        return clearInternal(value, depth);
+    }
     static parseTableRef(tableRef) {
         if (typeof tableRef !== "string") {
             throw new Error(`tableRef 必须是字符串 (tableRef: ${String(tableRef)})`);

package/dist/lib/logger.d.ts

@@ -1,12 +1,8 @@
 /**
  * 日志系统 - Bun 环境自定义实现（替换 pino / pino-roll）
  */
-import type { LoggerConfig, LoggerSink } from "../types/logger";
+import type { LoggerConfig, LoggerSink, LoggerWriteOptions } from "../types/logger";
 type SinkLogger = LoggerSink;
-type LoggerWriteOptions = {
-    truncate?: boolean;
-    console?: boolean;
-};
 export declare function flush(): Promise<void>;
 export declare function shutdown(): Promise<void>;
 /**
@@ -23,11 +19,21 @@ export declare function setMockLogger(mock: SinkLogger | null): void;
  */
 export declare function getLogger(): SinkLogger;
 declare class LoggerFacade {
-    private maybeSanitizeForMock;
+    private write;
     info(input: unknown, options?: LoggerWriteOptions): void;
     warn(input: unknown, options?: LoggerWriteOptions): void;
     error(input: unknown, options?: LoggerWriteOptions): void;
     debug(input: unknown, options?: LoggerWriteOptions): void;
+    /**
+     * 打印多行纯文本到控制台（stdout/stderr）。
+     *
+     * 说明：
+     * - 该方法不写入 JSONL 文件、不做清洗/脱敏/截断；仅用于“人类可读”的多行输出。
+     * - 若需要落盘/采集：请先调用 Logger.info/warn/error/debug 写入 JSONL（可选 console:false），再调用本方法输出多行。
+     */
+    printPlainLines(input: string | string[], options?: {
+        stream?: "stdout" | "stderr";
+    }): void;
     flush(): Promise<void>;
     configure(cfg: LoggerConfig): void;
     setMock(mock: SinkLogger | null): void;

package/dist/lib/logger.js

@@ -21,11 +21,8 @@ let sanitizeOptions = {
     sanitizeObjectKeys: 500,
     sensitiveKeyMatcher: buildSensitiveKeyMatcher({ builtinPatterns: BUILTIN_SENSITIVE_KEYS, userPatterns: [] })
 };
-const recordWriteOptions = new WeakMap();
-function buildSanitizeOptionsForWrite(writeOptions) {
-    if (!writeOptions)
-        return sanitizeOptions;
-    if (writeOptions.truncate !== false)
+function buildSanitizeOptionsForWriteOptions(writeOptions) {
+    if (!writeOptions || writeOptions.truncate !== false)
         return sanitizeOptions;
     // 仅关闭“截断”，仍保留敏感字段掩码与结构化清洗（避免泄露敏感信息）。
     return {
@@ -45,8 +42,6 @@ const HOSTNAME = (() => {
         return "unknown";
     }
 })();
-let instance = null;
-let errorInstance = null;
 let mockInstance = null;
 let appFileSink = null;
 let errorFileSink = null;
@@ -369,8 +364,6 @@ export async function shutdown() {
         return;
     // 重要：shutdown 可能与后续 Logger.getLogger() 并发。
     // 因此这里捕获“当前的旧 sink/instance 快照”，只关闭这些快照，避免把新创建的 sink 一并清掉。
-    const currentInstance = instance;
-    const currentErrorInstance = errorInstance;
     const currentAppFileSink = appFileSink;
     const currentErrorFileSink = errorFileSink;
     const currentAppConsoleSink = appConsoleSink;
@@ -398,12 +391,6 @@ export async function shutdown() {
     if (appConsoleSink === currentAppConsoleSink) {
         appConsoleSink = null;
     }
-    if (instance === currentInstance) {
-        instance = null;
-    }
-    if (errorInstance === currentErrorInstance) {
-        errorInstance = null;
-    }
     // shutdown 后允许下一次重新初始化时再次校验/创建目录（测试会清理目录，避免 ENOENT）
     // 无需缓存状态：确保目录存在是幂等的。
 }
@@ -450,8 +437,6 @@ export function configure(cfg) {
             mb = 100;
         config.maxSize = mb;
     }
-    instance = null;
-    errorInstance = null;
     appFileSink = null;
     errorFileSink = null;
     appConsoleSink = null;
@@ -476,32 +461,20 @@ function getSink(kind) {
     // 优先返回 mock 实例（用于测试）
     if (mockInstance)
         return mockInstance;
-    if (kind === "app") {
-        if (instance)
-            return instance;
-    }
-    else {
-        if (errorInstance)
-            return errorInstance;
-    }
-    ensureLogDirExists();
-    const maxSizeMb = typeof config.maxSize === "number" ? config.maxSize : 20;
-    const maxFileBytes = Math.floor(maxSizeMb * 1024 * 1024);
-    if (kind === "app") {
-        if (!appFileSink) {
-            appFileSink = new LogFileSink({ prefix: "app", maxFileBytes: maxFileBytes });
-        }
-        if (config.console === 1 && !appConsoleSink) {
-            appConsoleSink = createStreamSink("stdout");
+    return {
+        info(record) {
+            writeJsonl(kind, "info", record, undefined);
+        },
+        warn(record) {
+            writeJsonl(kind, "warn", record, undefined);
+        },
+        error(record) {
+            writeJsonl(kind, "error", record, undefined);
+        },
+        debug(record) {
+            writeJsonl(kind, "debug", record, undefined);
         }
-        instance = createSinkLogger({ fileSink: appFileSink, consoleSink: config.console === 1 ? appConsoleSink : null });
-        return instance;
-    }
-    if (!errorFileSink) {
-        errorFileSink = new LogFileSink({ prefix: "error", maxFileBytes: maxFileBytes });
-    }
-    errorInstance = createSinkLogger({ fileSink: errorFileSink, consoleSink: null });
-    return errorInstance;
+    };
 }
 /**
  * 获取 Logger 实例（延迟初始化）
@@ -570,46 +543,39 @@ function safeJsonStringify(obj) {
         }
     }
 }
-function createSinkLogger(options) {
-    const fileSink = options.fileSink;
-    const consoleSink = options.consoleSink;
-    const write = (level, record) => {
-        if (level === "debug" && config.debug !== 1)
-            return;
-        const time = Date.now();
-        const base = buildBaseFields(level, time);
-        const input = isPlainObject(record) ? record : { value: record };
-        let writeOptions = null;
-        if (input && typeof input === "object") {
-            writeOptions = recordWriteOptions.get(input) ?? null;
-            if (writeOptions) {
-                recordWriteOptions.delete(input);
-            }
+function ensureSinksReady(kind) {
+    ensureLogDirExists();
+    const maxSizeMb = typeof config.maxSize === "number" ? config.maxSize : 20;
+    const maxFileBytes = Math.floor(maxSizeMb * 1024 * 1024);
+    if (kind === "app") {
+        if (!appFileSink) {
+            appFileSink = new LogFileSink({ prefix: "app", maxFileBytes: maxFileBytes });
         }
-        const effectiveSanitizeOptions = buildSanitizeOptionsForWrite(writeOptions);
-        const sanitizedRecord = sanitizeLogObject(input, effectiveSanitizeOptions);
-        const fileLine = buildLogLineWithBase(base, sanitizedRecord);
-        fileSink.enqueue(fileLine);
-        if (consoleSink) {
-            if (!writeOptions || writeOptions.console !== false) {
-                consoleSink.enqueue(fileLine);
-            }
+        if (config.console === 1 && !appConsoleSink) {
+            appConsoleSink = createStreamSink("stdout");
         }
-    };
-    return {
-        info(record) {
-            write("info", record);
-        },
-        warn(record) {
-            write("warn", record);
-        },
-        error(record) {
-            write("error", record);
-        },
-        debug(record) {
-            write("debug", record);
+        return { fileSink: appFileSink, consoleSink: config.console === 1 ? appConsoleSink : null };
+    }
+    if (!errorFileSink) {
+        errorFileSink = new LogFileSink({ prefix: "error", maxFileBytes: maxFileBytes });
+    }
+    return { fileSink: errorFileSink, consoleSink: null };
+}
+function writeJsonl(kind, level, record, options) {
+    if (level === "debug" && config.debug !== 1)
+        return;
+    const sinks = ensureSinksReady(kind);
+    const time = Date.now();
+    const base = buildBaseFields(level, time);
+    const effectiveSanitizeOptions = buildSanitizeOptionsForWriteOptions(options);
+    const sanitizedRecord = sanitizeLogObject(record, effectiveSanitizeOptions);
+    const fileLine = buildLogLineWithBase(base, sanitizedRecord);
+    sinks.fileSink.enqueue(fileLine);
+    if (sinks.consoleSink) {
+        if (!options || options.console !== false) {
+            sinks.consoleSink.enqueue(fileLine);
         }
-    };
+    }
 }
 // 对象清洗/脱敏/截断逻辑已下沉到 utils/loggerUtils.ts（减少 logger.ts 复杂度）。
 function metaToObject() {
@@ -679,51 +645,72 @@ function withRequestMetaRecord(record) {
     return mergeMetaIntoObject(record, meta);
 }
 class LoggerFacade {
-    maybeSanitizeForMock(record, options) {
-        if (!mockInstance)
-            return record;
-        const effective = buildSanitizeOptionsForWrite(options ? options : null);
-        return sanitizeLogObject(record, effective);
-    }
-    info(input, options) {
+    write(level, input, options) {
+        // debug!=1 则完全不记录 debug 日志（包括文件与控制台）
+        if (level === "debug" && config.debug !== 1)
+            return;
         const record0 = withRequestMetaRecord(toRecord(input));
-        if (!mockInstance && options && isPlainObject(record0)) {
-            recordWriteOptions.set(record0, options);
+        // 测试场景：mock logger 走同步写入，并在 facade 层进行清洗/脱敏/截断控制
+        if (mockInstance) {
+            const effective = buildSanitizeOptionsForWriteOptions(options);
+            const sanitized = sanitizeLogObject(record0, effective);
+            if (level === "info") {
+                mockInstance.info(sanitized);
+            }
+            else if (level === "warn") {
+                mockInstance.warn(sanitized);
+            }
+            else if (level === "error") {
+                mockInstance.error(sanitized);
+            }
+            else {
+                mockInstance.debug(sanitized);
+            }
+            return;
+        }
+        writeJsonl("app", level, record0, options);
+        if (level === "error") {
+            // error 专属文件：始终镜像一份
+            writeJsonl("error", "error", record0, options);
         }
-        const record = this.maybeSanitizeForMock(record0, options);
-        getSink("app").info(record);
+    }
+    info(input, options) {
+        this.write("info", input, options);
     }
     warn(input, options) {
-        const record0 = withRequestMetaRecord(toRecord(input));
-        if (!mockInstance && options && isPlainObject(record0)) {
-            recordWriteOptions.set(record0, options);
-        }
-        const record = this.maybeSanitizeForMock(record0, options);
-        getSink("app").warn(record);
+        this.write("warn", input, options);
     }
     error(input, options) {
-        const record0 = withRequestMetaRecord(toRecord(input));
-        if (!mockInstance && options && isPlainObject(record0)) {
-            recordWriteOptions.set(record0, options);
-        }
-        const record = this.maybeSanitizeForMock(record0, options);
-        getSink("app").error(record);
-        // 测试场景：启用 mock 时不做镜像，避免调用次数翻倍
-        if (mockInstance)
-            return;
-        // error 专属文件：始终镜像一份
-        getSink("error").error(record);
+        this.write("error", input, options);
     }
     debug(input, options) {
-        // debug!=1 则完全不记录 debug 日志（包括文件与控制台）
-        if (config.debug !== 1)
-            return;
-        const record0 = withRequestMetaRecord(toRecord(input));
-        if (!mockInstance && options && isPlainObject(record0)) {
-            recordWriteOptions.set(record0, options);
+        this.write("debug", input, options);
+    }
+    /**
+     * 打印多行纯文本到控制台（stdout/stderr）。
+     *
+     * 说明：
+     * - 该方法不写入 JSONL 文件、不做清洗/脱敏/截断；仅用于“人类可读”的多行输出。
+     * - 若需要落盘/采集：请先调用 Logger.info/warn/error/debug 写入 JSONL（可选 console:false），再调用本方法输出多行。
+     */
+    printPlainLines(input, options) {
+        const kind = options && options.stream === "stderr" ? "stderr" : "stdout";
+        const stream = kind === "stderr" ? process.stderr : process.stdout;
+        try {
+            if (Array.isArray(input)) {
+                for (const line of input) {
+                    stream.write(`${String(line)}\n`);
+                }
+                return;
+            }
+            const parts = String(input).split("\n");
+            for (let i = 0; i < parts.length; i = i + 1) {
+                stream.write(`${parts[i]}\n`);
+            }
+        }
+        catch {
+            // ignore
         }
-        const record = this.maybeSanitizeForMock(record0, options);
-        getSink("app").debug(record);
     }
     async flush() {
         await flush();

package/dist/sync/syncTable.js

@@ -188,6 +188,7 @@ export class SyncTable {
             // plan 阶段补充的兼容性检查：保证“遇到第一条 throw”不会中止汇总。
             SyncTable.throwIfIncompatibleTypeChanges(incompatibleTypeChanges);
             // 预检通过后，再执行实际同步（DDL）。
+            const createdTables = [];
             for (const task of tableTasks) {
                 const item = task.item;
                 const tableName = task.tableName;
@@ -229,6 +230,7 @@ export class SyncTable {
                     }
                     else {
                         await SyncTable.createTable(this.db, tableName, tableFields);
+                        createdTables.push(tableName);
                     }
                 }
                 catch (error) {
@@ -257,6 +259,20 @@ export class SyncTable {
                     throw error;
                 }
             }
+            // 创建表汇总日志：单条输出（避免“一个表一行”刷屏）。
+            if (createdTables.length > 0) {
+                const lines = [];
+                lines.push(`创建表列表（共${createdTables.length}张）:`);
+                for (const tableName of createdTables) {
+                    lines.push(`- ${tableName}`);
+                }
+                const text = lines.join("\n");
+                // 说明：
+                // - 参考 start() 对 CoreError.multiline 的处理：文件仍写 JSONL，控制台改为原样多行文本。
+                // - 这样既不破坏 JSONL（文件/采集端仍可解析），也避免“每个表一条 JSON”刷屏。
+                Logger.debug(text, { truncate: false, console: false });
+                Logger.printPlainLines(text, { stream: "stdout" });
+            }
         }
         catch (error) {
             // 若已在表级 catch 打印过更详细上下文，则这里避免重复打印。
@@ -1063,7 +1079,6 @@ export class SyncTable {
         const { ENGINE, CHARSET, COLLATE } = SyncTable.MYSQL_TABLE_CONFIG;
         const createSQL = `CREATE TABLE ${tableQuoted} (\n            ${cols}\n        ) ENGINE=${ENGINE} DEFAULT CHARSET=${CHARSET} COLLATE=${COLLATE}`;
         await db.unsafe(createSQL);
-        Logger.debug(`[表 ${tableName}] + 创建表（系统字段 + 业务字段）`);
         const indexClauses = [];
         for (const sysField of systemIndexFields) {
             const indexName = `idx_${sysField}`;

package/dist/utils/loadMenuConfigs.js

@@ -14,7 +14,9 @@ export function normalizeViewDirMeta(input) {
         return null;
     }
     const orderRaw = record["order"];
-    const order = typeof orderRaw === "number" && Number.isFinite(orderRaw) && Number.isInteger(orderRaw) && orderRaw >= 0 ? orderRaw : undefined;
+    // 注意：菜单校验（checkMenu）要求 sort 最小值为 1。
+    // 因此 meta.json 的 order 若提供，也必须是整数且 >= 1。
+    const order = typeof orderRaw === "number" && Number.isFinite(orderRaw) && Number.isInteger(orderRaw) && orderRaw >= 1 ? orderRaw : undefined;
     if (order === undefined) {
         return {
             title: title

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "befly",
-    "version": "3.16.1",
-    "gitHead": "effac3f749af5f1395048a1ed528eac7e55eaed5",
+    "version": "3.16.4",
+    "gitHead": "9823cc29996ba9950dd08bfd72856e3b65815039",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "keywords": [