befly 3.77.0 → 3.77.2

package/Befly.js

@@ -13,6 +13,7 @@ import { syncMenu } from "./sync/menu.js";
 import { calcPerfTime } from "./utils/calcPerfTime.js";
 import { createError } from "./utils/error.js";
 import { isPrimaryProcess } from "./utils/is.js";
+import { printErrorSummary } from "./utils/prettyError.js";
 import { waitFor } from "./utils/util.js";
 
 const SYNC_READY_KEY = "befly:syncReady";
@@ -162,6 +163,7 @@ export class Befly {
             process.once("SIGTERM", this.signalHandlers.SIGTERM);
             return this.server;
         } catch (error) {
+            printErrorSummary(error, { title: "项目启动失败" });
             Logger.error("项目启动失败", error);
             try {
                 await this.stop();

package/apis/admin/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "系统管理"
+}

package/apis/api/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "接口管理"
+}

package/apis/auth/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "认证登录"
+}

package/apis/dashboard/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "仪表盘"
+}

package/apis/dict/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "字典项"
+}

package/apis/dictType/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "字典类型"
+}

package/apis/email/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "邮件"
+}

package/apis/loginLog/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "登录日志"
+}

package/apis/menu/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "菜单"
+}

package/apis/operateLog/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "操作日志"
+}

package/apis/role/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "角色"
+}

package/apis/source/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "资源"
+}

package/apis/tongJi/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "数据统计"
+}

package/apis/tongJi/dailyReport.js

@@ -30,7 +30,7 @@ export default {
         const productCode = ctx.body?.productCode || "";
 
         if (!(await isRegisteredProductCode(befly, productCode))) {
-            return befly.tool.No("productCode 未注册");
+            return befly.tool.No("产品代号未注册");
         }
 
         let memberMeta;

package/apis/tongJi/errorReport.js

@@ -52,7 +52,7 @@ export default {
         const productCode = body.productCode || "";
 
         if (!(await isRegisteredProductCode(befly, productCode))) {
-            return befly.tool.No("productCode 未注册");
+            return befly.tool.No("产品代号未注册");
         }
         const rawMessage = body.message || "";
         const extractedMessage = extractErrorMessage(rawMessage);

package/apis/upload/_meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "上传"
+}

package/checks/table.js

@@ -26,7 +26,7 @@ function checkFieldDefinition(issues, tableName, fieldName, field) {
     if (typeof field.name !== "string" || !field.name || field.name !== field.name.trim() || field.name.includes("\n") || field.name.length > 20) addIssue(issues, [...path, "name"], "必须是 1..20 字符的简短名称，不允许首尾空白或换行");
     if (field.detail !== undefined && (typeof field.detail !== "string" || !field.detail || field.detail !== field.detail.trim())) addIssue(issues, [...path, "detail"], "必须是非空无首尾空白字符串");
     if (!fieldParamTypes[field.fieldType]) addIssue(issues, [...path, "fieldType"], "必须是 integer、number、varchar、text");
-    if (typeof field.fieldNullable !== "boolean") addIssue(issues, [...path, "fieldNullable"], "必须是 boolean");
+    if (typeof field.fieldNullable !== "boolean") addIssue(issues, [...path, "fieldNullable"], "必须是布尔值");
 
     let parseField;
     try {

package/configs/beflyConfig.json

@@ -19,7 +19,10 @@
     "excludeApisLog": ["/api/core/tongJi/*Report"],
     "logger": {
         "debug": true,
-        "excludeFields": ["password", "token", "secret"]
+        "excludeFields": ["password", "token", "secret"],
+        "truncateStringLength": 512,
+        "truncateArrayLength": 20,
+        "truncatePreviewLength": 200
     },
     "mysql": {
         "hostname": "127.0.0.1",

package/index.js

@@ -12,6 +12,7 @@ import beflyMenus from "./configs/beflyMenus.json";
 import { calcPerfTime } from "./utils/calcPerfTime.js";
 import { deepMerge } from "./utils/deepMerge.js";
 import { createError } from "./utils/error.js";
+import { printErrorSummary } from "./utils/prettyError.js";
 import { scanSources } from "./utils/scanSources.js";
 import { getRunMode } from "./utils/util.js";
 
@@ -38,7 +39,7 @@ export async function createBefly(config = {}, menus = []) {
         const mergedConfig = deepMerge(beflyConfig, config);
         const mergedMenus = deepMerge(prefixMenuPaths(beflyMenus, "core"), menus);
 
-        Logger.configure({ runtimeEnv: getRunMode(), ...mergedConfig.logger });
+        await Logger.configure({ runtimeEnv: getRunMode(), ...mergedConfig.logger });
         Logger.info(`启动 合并配置 耗时 ${calcPerfTime(mergeStartTime)}`);
 
         let stageStartTime = Bun.nanoseconds();
@@ -80,6 +81,7 @@ export async function createBefly(config = {}, menus = []) {
             corns: corns
         });
     } catch (error) {
+        printErrorSummary(error, { title: "启动失败" });
         Logger.error("启动失败", error);
         await Logger.shutdown();
         throw error;

package/libs/logger/logger.js

@@ -6,6 +6,10 @@ import { buildSensitiveKeyMatcher, isPlainObject, sanitizeLogRecord } from "./sa
 const builtinSensitiveKeys = ["*password*", "pass", "pwd", "*token*", "access_token", "refresh_token", "accessToken", "refreshToken", "authorization", "cookie", "set-cookie", "*secret*", "apiKey", "api_key", "privateKey", "private_key"];
 const textEncoder = new TextEncoder();
 
+// 单条日志与单次写入批次的字节上限（正常不触发，仅极端兜底）
+const MAX_LINE_LENGTH = 65536;
+const MAX_WRITE_BATCH_BYTES = 65536;
+
 let config;
 let sanitizeOptions;
 let mockInstance = null;
@@ -26,13 +30,20 @@ function formatTime(value, dateOnly = false) {
     const hour = String(date.getHours()).padStart(2, "0");
     const minute = String(date.getMinutes()).padStart(2, "0");
     const second = String(date.getSeconds()).padStart(2, "0");
-    return `${year}-${month}-${day} ${hour}:${minute}:${second}`;
+    const millisecond = String(date.getMilliseconds()).padStart(3, "0");
+    return `${year}-${month}-${day} ${hour}:${minute}:${second}.${millisecond}`;
 }
 
 function writeStderr(message) {
     Bun.stderr.write(`[befly-logger] ${message}\n`);
 }
 
+// 次日零点时间戳：日期滚动判断只做一次数值比较，避免每行格式化日期字符串
+function computeNextDayMs() {
+    const now = new Date();
+    return new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1).getTime();
+}
+
 class FileSink {
     constructor(prefix, sinkConfig) {
         this.prefix = prefix;
@@ -43,6 +54,11 @@ class FileSink {
         this.size = 0;
         this.pending = Promise.resolve();
         this.disabled = false;
+        this.queue = [];
+        this.flushScheduled = false;
+        this.droppedCount = 0;
+        this.maxQueueLines = normalizeInteger(sinkConfig.maxQueueLines, 10000, 1, 100000);
+        this.nextDayMs = 0;
     }
 
     getPath(date, index) {
@@ -59,6 +75,7 @@ class FileSink {
             this.disabled = true;
             writeStderr(`写入失败 (${this.prefix}): ${error.message || error}`);
         });
+        this.nextDayMs = computeNextDayMs();
     }
 
     close(resetPosition = true) {
@@ -76,17 +93,16 @@ class FileSink {
     }
 
     async prepare(bytes) {
-        const date = formatTime(Date.now(), true);
-        if (this.stream && this.date !== date) await this.close();
+        if (this.stream && Date.now() >= this.nextDayMs) await this.close();
 
         if (!this.stream) {
-            this.date = date;
+            this.date = formatTime(Date.now(), true);
             this.index = 0;
-            let path = this.getPath(date, this.index);
+            let path = this.getPath(this.date, this.index);
             this.size = Bun.file(path).size;
             while (this.prefix !== "dev" && this.size > 0 && this.size + bytes > this.config.maxBytes) {
                 this.index += 1;
-                path = this.getPath(date, this.index);
+                path = this.getPath(this.date, this.index);
                 this.size = Bun.file(path).size;
             }
             this.open(path);
@@ -95,30 +111,62 @@ class FileSink {
         if (this.prefix !== "dev" && this.size > 0 && this.size + bytes > this.config.maxBytes) {
             await this.close(false);
             this.index += 1;
-            this.size = Bun.file(this.getPath(date, this.index)).size;
-            this.open(this.getPath(date, this.index));
+            this.size = Bun.file(this.getPath(this.date, this.index)).size;
+            this.open(this.getPath(this.date, this.index));
         }
     }
 
+    // 写入入口：单次编码、超长截断、入队（有界）、按需调度冲刷
     write(line) {
         if (this.disabled) return;
-        const bytes = textEncoder.encode(line).byteLength;
+        const text = line.length > MAX_LINE_LENGTH ? `${line.slice(0, MAX_LINE_LENGTH)}[截断，原 ${line.length} 字符]\n` : line;
+        const buffer = textEncoder.encode(text);
+        this.queue.push({ buffer: buffer, bytes: buffer.byteLength });
+
+        // 日志风暴/磁盘卡顿时有界丢弃最旧行，恢复后补摘要标记
+        while (this.queue.length > this.maxQueueLines) {
+            this.queue.shift();
+            this.droppedCount += 1;
+        }
+
+        if (this.flushScheduled) return;
+        this.flushScheduled = true;
         // 链尾 catch 隔离单次写失败：保持 pending 永远 resolved，
         // 避免未处理 rejection 与后续日志全部静默丢失
         this.pending = this.pending
             .then(async () => {
-                await this.prepare(bytes);
-                if (!this.stream || this.disabled) return;
-                this.size += bytes;
-                await new Promise((resolveWrite) => {
-                    this.stream.write(line, resolveWrite);
-                });
+                await this.drain();
             })
             .catch((error) => {
                 writeStderr(`写入失败 (${this.prefix}): ${error?.message || error}`);
             });
     }
 
+    // 冲刷队列：积压行合并为批次（单次系统调用），串行保持顺序
+    async drain() {
+        this.flushScheduled = false;
+
+        if (this.droppedCount > 0) {
+            const marker = textEncoder.encode(`{"level":"warn","time":"${formatTime(Date.now())}","pid":${process.pid},"msg":"[日志拥塞，已丢弃 ${this.droppedCount} 行]"}\n`);
+            this.queue.unshift({ buffer: marker, bytes: marker.byteLength });
+            this.droppedCount = 0;
+        }
+
+        while (this.queue.length > 0) {
+            let batch = this.queue.shift();
+            while (this.queue.length > 0 && batch.bytes + this.queue[0].bytes <= MAX_WRITE_BATCH_BYTES) {
+                batch = mergeBatch(batch, this.queue.shift());
+            }
+
+            await this.prepare(batch.bytes);
+            if (!this.stream || this.disabled) return;
+            this.size += batch.bytes;
+            await new Promise((resolveWrite) => {
+                this.stream.write(batch.buffer, resolveWrite);
+            });
+        }
+    }
+
     async flush() {
         await this.pending;
     }
@@ -129,6 +177,13 @@ class FileSink {
     }
 }
 
+function mergeBatch(left, right) {
+    const merged = new Uint8Array(left.bytes + right.bytes);
+    merged.set(left.buffer, 0);
+    merged.set(right.buffer, left.bytes);
+    return { buffer: merged, bytes: merged.byteLength };
+}
+
 function resetConfig(options = {}) {
     const runtimeEnv = options.runtimeEnv === "development" ? "development" : "production";
     const dir = options.dir ? resolve(options.dir) : resolve(process.cwd(), "logs");
@@ -146,7 +201,10 @@ function resetConfig(options = {}) {
     sanitizeOptions = {
         sanitizeDepth: normalizeInteger(options.sanitizeDepth, 5, 1, 10),
         sanitizeNodes: normalizeInteger(options.sanitizeNodes, 5000, 50, 20000),
-        sanitizeObjectKeys: normalizeInteger(options.sanitizeObjectKeys, 500, 10, 5000),
+        sanitizeObjectKeys: normalizeInteger(options.sanitizeObjectKeys, 50, 5, 500),
+        truncateStringLength: normalizeInteger(options.truncateStringLength, 512, 32, 65536),
+        truncateArrayLength: normalizeInteger(options.truncateArrayLength, 20, 1, 1000),
+        truncatePreviewLength: normalizeInteger(options.truncatePreviewLength, 200, 32, 65536),
         sensitiveKeyMatcher: buildSensitiveKeyMatcher(builtinSensitiveKeys, options.excludeFields)
     };
 }
@@ -191,7 +249,7 @@ function toRecord(input) {
     try {
         return { msg: String(input) };
     } catch {
-        return { msg: "[Unserializable]" };
+        return { msg: "[无法序列化的日志记录]" };
     }
 }
 
@@ -208,7 +266,7 @@ function buildLine(level, record) {
     try {
         return `${JSON.stringify(output)}\n`;
     } catch {
-        return `${JSON.stringify({ level: level, time: output.time, pid: process.pid, msg: "[Unserializable log record]" })}\n`;
+        return `${JSON.stringify({ level: level, time: output.time, pid: process.pid, msg: "[无法序列化的日志记录]" })}\n`;
     }
 }
 
@@ -237,13 +295,14 @@ export const Logger = {
         write("error", isPlainObject(message) ? message : { msg: message, err: error, data: data });
     },
     debug: createMethod("debug"),
-    configure: function (options = {}) {
+    configure: async function (options = {}) {
         const sinks = [appSink, errorSink].filter(Boolean);
         appSink = null;
         errorSink = null;
-        for (const sink of sinks) sink.shutdown().catch((error) => writeStderr(`关闭失败: ${error.message || error}`));
+        // 配置即时生效（同步重置），旧 sink 关闭异步等待，避免新旧并发期间的配置错位
         resetConfig(options);
         prepareDirectory(config.clearDevelopmentLog);
+        await Promise.allSettled(sinks.map((sink) => sink.shutdown()));
     },
     setMock: function (mock) {
         mockInstance = mock;
@@ -262,3 +321,5 @@ export const Logger = {
         }
     }
 };
+
+export { FileSink };

package/libs/logger/sanitize.js

@@ -44,17 +44,23 @@ function isSensitiveKey(key, matcher) {
     return matcher.contains.some((part) => lower.includes(part));
 }
 
+// 长字符串截断：超过阈值保留前段并追加统一可 grep 的标记
+function truncateText(text, limit) {
+    if (text.length <= limit) return text;
+    return `${text.slice(0, limit)}[截断，原 ${text.length} 字符]`;
+}
+
 function sanitizeError(error, options, state, depth, visited) {
     if (visited.has(error)) return "[Circular]";
     visited.add(error);
 
     const output = {
         name: error.name || "Error",
-        message: error.message || "",
-        chain: errorChainSummary(error)
+        message: truncateText(error.message || "", options.truncateStringLength),
+        chain: truncateText(errorChainSummary(error), options.truncateStringLength)
     };
 
-    if (typeof error.stack === "string") output.stack = error.stack;
+    if (typeof error.stack === "string") output.stack = truncateText(error.stack, options.truncateStringLength);
     if (error.cause !== undefined) output.cause = sanitizeValue(error.cause, options, state, depth + 1, visited);
 
     for (const key of Object.keys(error)) {
@@ -65,10 +71,11 @@ function sanitizeError(error, options, state, depth, visited) {
     return output;
 }
 
+// 降级预览：整体转字符串并按预览长度截断（深度/节点数超限、非普通对象的统一出口）
 function stringifyPreview(value, options) {
     const seen = new WeakSet();
     try {
-        return JSON.stringify(value, (key, item) => {
+        const text = JSON.stringify(value, (key, item) => {
             if (key && isSensitiveKey(key, options.sensitiveKeyMatcher)) return "[MASKED]";
             if (typeof item === "bigint") return String(item);
             if (item && typeof item === "object") {
@@ -77,17 +84,41 @@ function stringifyPreview(value, options) {
             }
             return item;
         });
+        return truncateText(text, options.truncatePreviewLength);
     } catch {
         try {
-            return String(value);
+            return truncateText(String(value), options.truncatePreviewLength);
         } catch {
-            return "[Unserializable]";
+            return "[无法序列化]";
         }
     }
 }
 
+function sanitizeArray(value, options, state, depth, visited) {
+    const limit = options.truncateArrayLength;
+    const items = value.slice(0, limit).map((item) => sanitizeValue(item, options, state, depth + 1, visited));
+    if (value.length > limit) {
+        items.push(`[截断，显示 ${limit}/共 ${value.length} 项]`);
+    }
+    return items;
+}
+
+function sanitizeObject(value, options, state, depth, visited) {
+    const entries = Object.entries(value);
+    const shown = entries.slice(0, options.sanitizeObjectKeys);
+    const output = {};
+    for (const [key, item] of shown) {
+        output[key] = isSensitiveKey(key, options.sensitiveKeyMatcher) ? "[MASKED]" : sanitizeValue(item, options, state, depth + 1, visited);
+    }
+    if (entries.length > shown.length) {
+        output.__truncated__ = `已省略 ${entries.length - shown.length} 个键`;
+    }
+    return output;
+}
+
 function sanitizeValue(value, options, state, depth, visited) {
-    if (value === null || value === undefined || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+    if (value === null || value === undefined || typeof value === "number" || typeof value === "boolean") return value;
+    if (typeof value === "string") return truncateText(value, options.truncateStringLength);
     if (typeof value === "bigint") return String(value);
     if (value instanceof Error) return sanitizeError(value, options, state, depth, visited);
 
@@ -98,14 +129,8 @@ function sanitizeValue(value, options, state, depth, visited) {
     visited.add(value);
     state.nodes += 1;
 
-    if (Array.isArray(value)) return value.map((item) => sanitizeValue(item, options, state, depth + 1, visited));
-
-    const output = {};
-    const entries = Object.entries(value).slice(0, options.sanitizeObjectKeys);
-    for (const [key, item] of entries) {
-        output[key] = isSensitiveKey(key, options.sensitiveKeyMatcher) ? "[MASKED]" : sanitizeValue(item, options, state, depth + 1, visited);
-    }
-    return output;
+    if (Array.isArray(value)) return sanitizeArray(value, options, state, depth, visited);
+    return sanitizeObject(value, options, state, depth, visited);
 }
 
 export function sanitizeLogRecord(record, options) {

package/libs/validator/compiler.js

@@ -23,7 +23,7 @@ function schemaError(path, message) {
 }
 
 function assertBoolean(value, path) {
-    if (value !== undefined && typeof value !== "boolean") schemaError(path, "必须是 boolean");
+    if (value !== undefined && typeof value !== "boolean") schemaError(path, "必须是布尔值");
 }
 
 function assertLimit(value, path) {
@@ -212,7 +212,7 @@ export function compileNode(schema, path, parents) {
     if (schema.paramType === "object") {
         assertItemBounds(schema, path);
         if (schema.fields !== undefined && !isPlainObject(schema.fields)) schemaError([...path, "fields"], "必须是对象");
-        if (schema.extra !== undefined && typeof schema.extra !== "boolean" && !isPlainObject(schema.extra)) schemaError([...path, "extra"], "必须是 boolean 或 Schema");
+        if (schema.extra !== undefined && typeof schema.extra !== "boolean" && !isPlainObject(schema.extra)) schemaError([...path, "extra"], "必须是布尔值或 Schema 对象");
         node.minItem = schema.minItem;
         node.maxItem = schema.maxItem;
         node.fields = Object.entries(schema.fields || {}).map(([key, child]) => ({ key: key, node: compileNode(child, [...path, "fields", key], parents) }));

package/libs/validator/parser.js

@@ -5,7 +5,7 @@ function addIssue(issues, path, code, message) {
 }
 
 function typeMessage(kind) {
-    if (kind === "boolean") return "必须是 boolean";
+    if (kind === "boolean") return "必须是布尔值";
     if (kind === "integer") return "必须是安全整数";
     if (kind === "number") return "必须是有限数字";
     if (kind === "string") return "必须是字符串";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.77.0",
+    "version": "3.77.2",
     "gitHead": "49c39d36695036e85fc64083cc43c1652fff96cb",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 JavaScript API 接口框架核心引擎",

package/schemas/api.json

@@ -19,6 +19,12 @@
                 "paramType": "string",
                 "minValue": 1
             },
+            "parentTitle": {
+                "paramType": "string",
+                "minValue": 0,
+                "maxValue": 500,
+                "optional": true
+            },
             "apiPath": {
                 "paramType": "string",
                 "minValue": 1,

package/schemas/config.json

@@ -78,6 +78,24 @@
                     "items": {
                         "paramType": "string"
                     }
+                },
+                "truncateStringLength": {
+                    "paramType": "integer",
+                    "minValue": 32,
+                    "maxValue": 65536,
+                    "optional": true
+                },
+                "truncateArrayLength": {
+                    "paramType": "integer",
+                    "minValue": 1,
+                    "maxValue": 1000,
+                    "optional": true
+                },
+                "truncatePreviewLength": {
+                    "paramType": "integer",
+                    "minValue": 32,
+                    "maxValue": 65536,
+                    "optional": true
                 }
             }
         },

package/sync/api.js

@@ -26,7 +26,7 @@ const getApiParentPath = (apiPath) => {
 export async function syncApi(ctx, apis) {
     const allDbApis = await ctx.mysql.getAll({
         table: BEFLY_API_TABLE,
-        fields: ["id", "path", "parentPath", "name", "method", "auth", "category", "state"],
+        fields: ["id", "path", "parentPath", "parentTitle", "name", "method", "auth", "category", "state"],
         where: { state$gte: 0 }
     });
 
@@ -37,6 +37,7 @@ export async function syncApi(ctx, apis) {
             path: api.apiPath,
             method: api.method,
             parentPath: getApiParentPath(api.apiPath),
+            parentTitle: api.parentTitle || "",
             auth: serializeAuth(api.auth),
             category: api.category || "other"
         });
@@ -50,6 +51,7 @@ export async function syncApi(ctx, apis) {
             path: def.path,
             method: def.method,
             parentPath: def.parentPath,
+            parentTitle: def.parentTitle,
             auth: def.auth,
             category: def.category
         }),
@@ -58,6 +60,7 @@ export async function syncApi(ctx, apis) {
             path: def.path,
             method: def.method,
             parentPath: def.parentPath,
+            parentTitle: def.parentTitle,
             auth: def.auth,
             category: def.category
         })

package/tables/api.json

@@ -52,5 +52,14 @@
         "paramType": "string",
         "fieldType": "varchar",
         "fieldDefault": ""
+    },
+    "parentTitle": {
+        "name": "目录标题",
+        "detail": "目录标题路径：每级有 _meta.js 标题用标题，没有用目录名",
+        "minValue": 0,
+        "maxValue": 100,
+        "paramType": "string",
+        "fieldType": "varchar",
+        "fieldDefault": ""
     }
 }

package/utils/prettyError.js

@@ -0,0 +1,102 @@
+import { relative } from "node:path";
+
+// 摘要中每组错误最多列出的文件数，其余以计数收尾（完整清单在日志里）
+const MAX_FILES_PER_GROUP = 3;
+
+// 高频错误的修复提示（按内容模式匹配，只保留最有价值的少数几条）
+const HINT_RULES = [
+    {
+        match: (text) => text.includes("不允许出现"),
+        hint: "疑似新增字段未在对应 schema 中声明"
+    },
+    {
+        match: (text) => text.includes("必须是") || text.includes("必填"),
+        hint: "检查对应字段的类型与取值是否符合 schema 声明"
+    }
+];
+
+function shortPath(file) {
+    const text = String(file || "");
+    if (!text) return "(未知来源)";
+    const related = relative(process.cwd(), text);
+    return (related.length < text.length ? related : text).replaceAll("\\", "/");
+}
+
+// 兼容字符串化的错误项（经 sanitize 深度降级后会变成 JSON 字符串）
+function toErrorItems(errors) {
+    if (!Array.isArray(errors)) return [];
+    return errors.map((item) => {
+        if (item && typeof item === "object") return item;
+        if (typeof item === "string" && item.startsWith("{")) {
+            try {
+                return JSON.parse(item);
+            } catch {
+                return { expected: item };
+            }
+        }
+        return { expected: String(item) };
+    });
+}
+
+function collectHints(texts) {
+    const hints = [];
+    for (const rule of HINT_RULES) {
+        if (hints.length >= 2) break;
+        if (texts.some((text) => rule.match(text)) && !hints.includes(rule.hint)) {
+            hints.push(rule.hint);
+        }
+    }
+    return hints;
+}
+
+/**
+ * 将结构化错误（含 checkAll 的 errors 分组）格式化为人类可读的多行摘要。
+ * 用于启动失败等关键错误的终端输出；日志仍记录完整结构化信息。
+ */
+export function formatErrorSummary(error, options = {}) {
+    const title = options.title || "启动失败";
+    const lines = [`✗ ${title}：${error?.message || error}`];
+
+    const groups = Array.isArray(error?.errors) ? error.errors : [];
+    const allTexts = [];
+    for (const group of groups) {
+        const items = toErrorItems(group?.errors ?? group);
+        if (items.length === 0) continue;
+
+        // 按原因聚合：同因错误合并，文件清单截断展示
+        const byReason = new Map();
+        for (const item of items) {
+            const reason = item.expected || item.message || "(无原因)";
+            if (!byReason.has(reason)) byReason.set(reason, []);
+            byReason.get(reason).push(shortPath(item.file));
+        }
+        allTexts.push(...byReason.keys());
+
+        lines.push("");
+        lines.push(`[${group?.check || "错误"}] 共 ${items.length} 处：`);
+        for (const [reason, files] of byReason) {
+            lines.push(`  ${reason}`);
+            const shown = files.slice(0, MAX_FILES_PER_GROUP);
+            for (const file of shown) {
+                lines.push(`    ${file}`);
+            }
+            if (files.length > shown.length) {
+                lines.push(`    … 其余 ${files.length - shown.length} 个`);
+            }
+        }
+    }
+
+    const hints = collectHints(allTexts);
+    if (hints.length > 0) {
+        lines.push("");
+        for (const hint of hints) {
+            lines.push(`提示：${hint}`);
+        }
+    }
+
+    return lines.join("\n");
+}
+
+export function printErrorSummary(error, options = {}) {
+    Bun.stderr.write(`${formatErrorSummary(error, options)}\n`);
+}

package/utils/scanFiles.js

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { join, normalize, parse, relative } from "node:path";
 
 import { createError } from "./error.js";
@@ -12,6 +12,42 @@ const selectFields = {
     state: { name: "状态", paramType: "integer" }
 };
 
+/**
+ * 扫描接口目录下的 _meta.json 目录元数据（约定：_ 前缀文件不注册路由）。
+ * 返回 Map<目录 apiPath, 中文标题>，键与接口 apiPath 的目录部分对齐，供 scanSources 挂载 parentTitle。
+ */
+export async function scanApiMetaTitles(dir, source) {
+    const titles = new Map();
+    if (!existsSync(dir)) return titles;
+
+    const glob = new Bun.Glob("**/_meta.json");
+    const files = await Array.fromAsync(
+        glob.scan({
+            cwd: dir,
+            onlyFiles: true,
+            absolute: true,
+            followSymlinks: true
+        })
+    );
+
+    for (const file of files) {
+        const filePath = normalize(file);
+        const meta = await importDefault(filePath, {});
+        const record = isPlainObject(meta) ? meta : {};
+        const title = record.title;
+        if (typeof title !== "string" || title.trim().length === 0 || title.trim().length > 50) {
+            throw createError(`目录元数据无效：${filePath} 的 title 必须是 1-50 个字符`, { code: "policy", subsystem: "scan", operation: "scanApiMetaTitles" });
+        }
+
+        const parsedRelativePath = parse(relative(dir, filePath));
+        const relativeDir = parsedRelativePath.dir.replaceAll("\\", "/");
+        const dirApiPath = source === "core" ? `/api/core/${relativeDir}` : `/api/${relativeDir}`;
+        titles.set(dirApiPath, title.trim());
+    }
+
+    return titles;
+}
+
 /**
  * 扫描指定目录下的文件
  * @param dir 目录路径
@@ -83,3 +119,23 @@ export async function scanFiles(dir, source, type, pattern) {
         throw createError(`扫描失败: source=${source} type=${type} dir=${dir} pattern=${pattern}`, { cause: error, code: "runtime" });
     }
 }
+
+// 枚举接口目录下全部子目录（任意深度，跳过 _ 前缀段），返回目录 apiPath 集合，
+// 供启动校验"每个目录必须有 _meta.js"使用
+export function scanApiDirPaths(dir, source) {
+    const result = new Set();
+    if (!existsSync(dir)) return result;
+    const prefix = source === "core" ? "/api/core/" : "/api/";
+
+    function collect(current, relativeDir) {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (!entry.isDirectory() || entry.name.startsWith("_")) continue;
+            const childRelative = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+            result.add(`${prefix}${childRelative}`);
+            collect(join(current, entry.name), childRelative);
+        }
+    }
+
+    collect(dir, "");
+    return result;
+}

package/utils/scanSources.js

@@ -16,7 +16,24 @@ import {
     appCornDir
 } from "../paths.js";
 import { createError } from "./error.js";
-import { scanFiles } from "./scanFiles.js";
+import { scanApiDirPaths, scanApiMetaTitles, scanFiles } from "./scanFiles.js";
+
+// 逐级拼接目录显示标题：每级目录有 _meta.js 标题用标题，没有用目录名，以 / 连接
+// 例：/api/admin/product/insert + 标题映射 -> "后台管理/product"
+export function composeTitlePath(apiPath, metaTitles) {
+    const segments = apiPath.split("/").filter(Boolean);
+    const start = segments[1] === "core" ? 2 : 1;
+    const dirs = segments.slice(start, -1);
+    if (dirs.length === 0) return "";
+
+    const parts = [];
+    let current = `/${segments.slice(0, start).join("/")}`;
+    for (const dir of dirs) {
+        current = `${current}/${dir}`;
+        parts.push(metaTitles.get(current) || dir);
+    }
+    return parts.join("/");
+}
 
 function warnWhenAppSourcesMissing() {
     // 全部 app 源码目录都不存在时显式告警，避免"项目源码静默消失、以纯 core 形态运行"的配置事故
@@ -119,17 +136,42 @@ export const scanSources = async ({ beflyMode = "auto" } = {}) => {
         corns.push(item);
     }
 
-    // 处理接口
-    const allCoreApis = await scanFiles(coreApiDir, "core", "api", "**/*.js");
+    // 处理接口（读取目录 _meta.js 标题挂载 parentTitle）
+    const [allCoreApis, coreMetaTitles, coreDirPaths, allAppApis, appMetaTitles, appDirPaths] = await Promise.all([
+        scanFiles(coreApiDir, "core", "api", "**/*.js"),
+        scanApiMetaTitles(coreApiDir, "core"),
+        scanApiDirPaths(coreApiDir, "core"),
+        scanFiles(appApiDir, "app", "api", "**/*.js"),
+        scanApiMetaTitles(appApiDir, "app"),
+        scanApiDirPaths(appApiDir, "app")
+    ]);
+
     for (const item of allCoreApis) {
+        item.parentTitle = composeTitlePath(item.apiPath, coreMetaTitles);
         apis.push(item);
     }
-    const allAppApis = await scanFiles(appApiDir, "app", "api", "**/*.js");
     for (const item of allAppApis) {
         assertAppApiNamespace(item);
+        item.parentTitle = composeTitlePath(item.apiPath, appMetaTitles);
         apis.push(item);
     }
 
+    // 每个接口目录（含空目录，_ 前缀隔离目录除外）都必须有 _meta.js 中文标题
+    const missingTitleDirs = new Set();
+    for (const dirPath of coreDirPaths) {
+        if (!coreMetaTitles.has(dirPath)) missingTitleDirs.add(dirPath);
+    }
+    for (const dirPath of appDirPaths) {
+        if (!appMetaTitles.has(dirPath)) missingTitleDirs.add(dirPath);
+    }
+    if (missingTitleDirs.size > 0) {
+        throw createError(`以下接口目录缺少 _meta.json 中文标题：${Array.from(missingTitleDirs).toSorted().join("、")}`, {
+            code: "policy",
+            subsystem: "scan",
+            operation: "scanSources"
+        });
+    }
+
     assertUnique(plugins, "fileName", "Plugin 文件名");
     assertUnique(hooks, "fileName", "Hook 文件名");
     assertUnique(corns, "fileName", "Cron 文件名");