@faapi/faapi 6.9.0 → 6.10.0

package/dist/index.d.ts

@@ -1,10 +1,38 @@
-import { A as AppRegistries, R as RouteManifest, F as FaapiContext, C as CorsOptions, T as TaskClient, H as HelmetOptions, L as LoggerOptions, a as LogConfig, b as FaapiMiddleware, I as InjectorMap, c as TaskFailedHandler, d as TaskQueueDeps, e as TaskQueue, f as TaskDriver, g as TaskRegistry, h as TaskManifest, i as ToolMetadata, j as AgentCore, k as AgentMetadata, l as CreateLoggerOptions, m as Logger, W as WsRouteManifest } from './routeTypes-CuGMDCGB.js';
-export { n as AgentHandleFactory, o as AgentHandleStore, p as AgentPathMeta, q as AgentRegistry, r as AgentToolDescriptor, s as FaapiContextConfig, t as FaapiTaskMeta, u as FailOptions, v as Injector, w as LogEntry, x as LogLevel, y as LogSink, z as RouteInfo, B as RouteInputSchema, D as RouteOutputSchema, E as RouteParamSchema, S as SkillRegistry, G as SseEvent, J as SseWriter, K as TaskContext, M as TaskDriverJob, N as TaskDriverProcess, O as TaskDriverRecord, P as TaskFailedInfo, Q as TaskJob, U as TaskJobStatus, V as TaskMetadata, X as TaskModule, Y as TaskRegistriesSnapshot, Z as TaskRegistriesView, _ as ToolCore, $ as ToolPathMeta, a0 as ToolRegistry, a1 as cors, a2 as createAppRegistries, a3 as createTaskRegistriesView, a4 as createTaskRegistry, a5 as helmet, a6 as logger } from './routeTypes-CuGMDCGB.js';
+import { F as FaapiMiddleware, A as AppRegistries, R as RouteManifest, a as FaapiContext, C as CorsOptions, T as TaskClient, H as HelmetOptions, L as LogConfig, I as InjectorMap, b as TaskFailedHandler, c as TaskQueueDeps, d as TaskQueue, e as TaskDriver, f as TaskRegistry, g as TaskManifest, h as ToolMetadata, i as AgentCore, j as AgentMetadata, k as CreateLoggerOptions, l as Logger, W as WsRouteManifest } from './routeTypes-m9wZHWyo.js';
+export { m as AgentHandleFactory, n as AgentHandleStore, o as AgentPathMeta, p as AgentRegistry, q as AgentToolDescriptor, r as FaapiContextConfig, s as FaapiTaskMeta, t as FailOptions, u as Injector, v as LogEntry, w as LogLevel, x as LogSink, y as RouteInfo, z as RouteInputSchema, B as RouteOutputSchema, D as RouteParamSchema, S as SkillRegistry, E as SseEvent, G as SseWriter, J as TaskContext, K as TaskDriverJob, M as TaskDriverProcess, N as TaskDriverRecord, O as TaskFailedInfo, P as TaskJob, Q as TaskJobStatus, U as TaskMetadata, V as TaskModule, X as TaskRegistriesSnapshot, Y as TaskRegistriesView, Z as ToolCore, _ as ToolPathMeta, $ as ToolRegistry, a0 as cors, a1 as createAppRegistries, a2 as createTaskRegistriesView, a3 as createTaskRegistry, a4 as helmet } from './routeTypes-m9wZHWyo.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
 import ts from 'typescript';
 
+type LoggerFn = (messageOrObj: string | Record<string, unknown>, message?: string) => void;
+interface LoggerOptions {
+    /**
+     * 自定义日志函数（完全接管输出，不再走统一管道——高级用法，一般无需配置）
+     *
+     * - 传入 `console.log`：纯文本格式 `GET /api/users 200 12ms`
+     * - 传入 pino logger：结构化日志 `logger.info({ method, path, status, durationMs }, 'request completed')`
+     */
+    log?: LoggerFn;
+}
+/**
+ * 创建请求日志中间件（洋葱模型）
+ *
+ * 默认并入统一日志管道（egg 模型：访问日志与业务日志同管道，一份 config.log
+ * 管全部输出），`config.log.accessLog: false` 关闭。
+ *
+ * 日志格式（文本 message）：GET /api/users 200 12ms
+ * 错误格式：POST /api/users 400 45ms - Error: ...
+ *
+ * before/after 一体，闭包变量共享开始时间，无需污染 ctx。
+ * 错误用 try/catch 捕获，记录后重新抛出（让上层处理）。
+ * 成功时从 next() 返回的 Response 读取状态码。
+ *
+ * log 函数每次请求时读取（options.log ?? defaultLog），运行时切换全局日志配置
+ * 同样生效。编程式自定义输出：`middlewares: [logger({ log: myFn })]`。
+ */
+declare function logger(options?: LoggerOptions): FaapiMiddleware;
+
 /** HTTP 请求 handler 类型 */
 type RequestHandler = (req: IncomingMessage, res: ServerResponse) => void;
 /** WebSocket 升级 handler 类型 */
@@ -550,21 +578,19 @@ interface FaapiConfig {
     etag?: EtagOptions | boolean;
     /** 请求体大小限制（字节），默认 10MB（10 * 1024 * 1024） */
     bodyLimit?: number;
-    /** 日志中间件配置 */
-    logger?: LoggerOptions | boolean;
     /**
-     * 业务日志器全局配置（详见 logger/logger.md）
+     * 日志全局配置——唯一日志配置入口，业务日志与请求日志同管道（egg 模型，
+     * 详见 logger/logger.md；`config.logger` 独立配置已废除）
      *
-     * - `false`：完全静默（含 error，测试降噪；不影响请求日志，关闭用 `logger: false`）
-     * - `true` / 缺省：默认级别（显式 level > LOG_LEVEL env > 'info'）+ console 文本输出
-     * - `LogConfig`：精细配置——`sink` 自定义管道（接 pino/winston）或 `dir` egg 风格
-     *   文件输出（app.log 全量 + error.log 仅 error，splitByLevel 按级别四文件），
-     *   两者互斥；`dir` 模式请求日志自动并入（`accessLog` 缺省 true），未显式配置
-     *   level 时不过滤（全量落盘）
+     * - `false`：全部静默（含 error 与请求日志，测试降噪）
+     * - `true` / 缺省：console 输出（consoleLevel 默认 'info'），管道不过滤
+     * - `LogConfig`：`dir` egg 风格文件输出（app.log 全量 + error.log 仅 error，
+     *   splitByLevel 按级别四文件）或 `sink` 自定义管道接管（接 pino/winston），
+     *   两者互斥；`level` 管道阈值（不配不过滤）、`consoleLevel` console 出口阈值
+     *   （不配 'info'，false 关 console）；请求日志无条件并入（`accessLog: false` 关闭）
      *
-     * 生效范围：`ctx.log` / 参数注入 `log` / `createLogger` / `taskCtx.log`，
-     * `dir`/`accessLog` 模式下含请求日志中间件。
-     * 日志全局配置是进程级资源，多 app 同进程时后启动覆盖先启动。
+     * 生效范围：`ctx.log` / 参数注入 `log` / `createLogger` / `taskCtx.log` /
+     * 请求日志中间件。日志全局配置是进程级资源，多 app 同进程时后启动覆盖先启动。
      *
      * ```ts
      * export default {
@@ -1495,16 +1521,23 @@ declare function loadEnv(rootDir: string): void;
 /**
  * 设置全局日志配置（进程级，`createAppBase` 启动时以 `config.log` 调用）
  *
- * - `false`：完全静默（含 error，测试降噪场景）
- * - `true` / `{}`：默认级别（显式 level > LOG_LEVEL env > 模式默认）+ 默认 console sink
- * - `{ level, sink }`：自定义管道接管（与 dir 互斥，同时配置抛错）
- * - `{ dir, splitByLevel?, stdout?, accessLog? }`：egg 风格文件输出（fileSink.md）
+ * - `false`：全部静默（含 error 与请求日志，测试降噪场景）
+ * - `true` / `{}`：console 出口默认 info，管道出口不过滤，无文件输出
+ * - `{ level, consoleLevel, sink, dir, stdout, accessLog }`：egg 模型精细配置
+ *   （level 管管道出口、consoleLevel 管 console 出口；sink 与 dir 互斥）
  * - `undefined`：重置为默认（编程式多 app 切换全局配置用）
  *
- * LOG_LEVEL env 仅在本函数读取——app 启动路径必经此处（env 非法在启动期报错）；
- * 纯编程式不调本函数时 env 不生效。
+ * LOG_LEVEL env 仅作为管道 level 的环境来源（consoleLevel 无 env）——本函数是
+ * env 读取点，非法值启动期报错（fail fast）。
  */
 declare function configureLogging(config?: LogConfig | boolean | undefined): void;
+/**
+ * 刷盘文件日志缓冲（不结束流，flush 后可继续写）
+ *
+ * 优雅停机场景在 `lifecycle.onClose` 调用，确保缓冲中的条目落盘后再退出进程；
+ * 测试场景断言文件内容前调用。无文件管道（未配置 `config.log.dir`）时为 no-op。
+ */
+declare function flushLogging(): Promise<void>;
 /**
  * 创建日志器
  *
@@ -1713,4 +1746,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type AgentConfig, AgentCore, AgentMetadata, type AgentModule, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, CreateLoggerOptions, type CronScheduler, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LlmConfig, type LlmModelConfig, LogConfig, Logger, LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, TASK_PATTERNS, type TaskBullMqOptions, TaskClient, type TaskConfig, TaskDriver, TaskFailedHandler, TaskManifest, type TaskPgBossOptions, TaskQueue, TaskRegistry, ToolMetadata, type ToolModule, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, configureLogging, createProdApp as createApp, createCronScheduler, createDevApp, createLogger, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };
+export { type AgentConfig, AgentCore, AgentMetadata, type AgentModule, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, CreateLoggerOptions, type CronScheduler, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LlmConfig, type LlmModelConfig, LogConfig, Logger, type LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, TASK_PATTERNS, type TaskBullMqOptions, TaskClient, type TaskConfig, TaskDriver, TaskFailedHandler, TaskManifest, type TaskPgBossOptions, TaskQueue, TaskRegistry, ToolMetadata, type ToolModule, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, configureLogging, createProdApp as createApp, createCronScheduler, createDevApp, createLogger, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, flushLogging, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, logger, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };

package/dist/index.js

@@ -2374,7 +2374,15 @@ function assertLogLevel(value, source) {
     );
   }
 }
-var globalState = { level: null, sink: null, fileSink: null, stdout: true, accessLog: false, disabled: false };
+var globalState = {
+  level: null,
+  consoleLevel: null,
+  sink: null,
+  fileSink: null,
+  stdout: true,
+  accessLog: true,
+  disabled: false
+};
 function configureLogging(config) {
   const objectConfig = typeof config === "object" ? config : {};
   if (objectConfig.sink && objectConfig.dir) {
@@ -2385,9 +2393,17 @@ function configureLogging(config) {
   void globalState.fileSink?.close();
   globalState.disabled = config === false;
   globalState.sink = objectConfig.sink ?? null;
-  globalState.accessLog = objectConfig.accessLog ?? objectConfig.dir !== void 0;
+  globalState.accessLog = objectConfig.accessLog ?? true;
   globalState.stdout = objectConfig.stdout ?? true;
   globalState.fileSink = objectConfig.dir ? createFileLogSink({ dir: objectConfig.dir, splitByLevel: objectConfig.splitByLevel }) : null;
+  if (objectConfig.consoleLevel !== void 0) {
+    if (objectConfig.consoleLevel !== false) {
+      assertLogLevel(objectConfig.consoleLevel, "config.log.consoleLevel");
+    }
+    globalState.consoleLevel = objectConfig.consoleLevel;
+  } else {
+    globalState.consoleLevel = null;
+  }
   if (objectConfig.level !== void 0) {
     assertLogLevel(objectConfig.level, "config.log.level");
     globalState.level = objectConfig.level;
@@ -2398,52 +2414,57 @@ function configureLogging(config) {
     globalState.level = null;
   }
 }
-function globalThreshold() {
-  if (globalState.level) return globalState.level;
-  if (globalState.fileSink) return void 0;
-  return "info";
+function pipelineThreshold() {
+  return globalState.level ?? void 0;
+}
+function consoleThreshold() {
+  return globalState.consoleLevel ?? "info";
 }
 function belowThreshold(level, threshold) {
   return threshold !== void 0 && LEVEL_RANK[level] < LEVEL_RANK[threshold];
 }
 function getEffectiveLogLevel() {
-  return globalThreshold();
+  return pipelineThreshold();
 }
-var consoleSink = (entry) => {
-  console[CONSOLE_METHOD[entry.level]](formatEntry(entry));
-};
 var CONSOLE_METHOD = {
   debug: "debug",
   info: "info",
   warn: "warn",
   error: "error"
 };
+function consoleDispatch(entry) {
+  const threshold = consoleThreshold();
+  if (threshold === false || belowThreshold(entry.level, threshold)) return;
+  console[CONSOLE_METHOD[entry.level]](formatEntry(entry));
+}
 function globalDispatch(entry) {
   if (globalState.disabled) return;
+  const pipeThreshold = pipelineThreshold();
   if (globalState.sink) {
-    globalState.sink(entry);
+    if (!belowThreshold(entry.level, pipeThreshold)) globalState.sink(entry);
     return;
   }
   if (globalState.fileSink) {
-    globalState.fileSink.write(entry);
-    if (globalState.stdout) consoleSink(entry);
+    if (!belowThreshold(entry.level, pipeThreshold)) globalState.fileSink.write(entry);
+    if (globalState.stdout) consoleDispatch(entry);
     return;
   }
-  consoleSink(entry);
+  consoleDispatch(entry);
 }
 function writeLogEntry(entry) {
-  if (belowThreshold(entry.level, globalThreshold())) return;
   globalDispatch(entry);
 }
-function isAccessLogPiped() {
+function flushLogging() {
+  return globalState.fileSink ? globalState.fileSink.flush() : Promise.resolve();
+}
+function isAccessLogEnabled() {
   return !globalState.disabled && globalState.accessLog;
 }
 function createLogger(scope, options) {
   const baseScope = scope;
   const baseFields = options?.fields;
   const write = (level, message, callFields, scopeSuffix) => {
-    const threshold = options?.level ?? globalThreshold();
-    if (belowThreshold(level, threshold)) return;
+    if (belowThreshold(level, options?.level)) return;
     const entry = {
       level,
       message,
@@ -4014,18 +4035,14 @@ function levelForStatus(status) {
   return "info";
 }
 function defaultLog(entry, text) {
-  if (isAccessLogPiped()) {
-    const logEntry = {
-      level: levelForStatus(entry.status),
-      message: text,
-      time: (/* @__PURE__ */ new Date()).toISOString(),
-      scope: "access",
-      fields: entry
-    };
-    writeLogEntry(logEntry);
-    return;
-  }
-  console.log(entry);
+  if (!isAccessLogEnabled()) return;
+  writeLogEntry({
+    level: levelForStatus(entry.status),
+    message: text,
+    time: (/* @__PURE__ */ new Date()).toISOString(),
+    scope: "access",
+    fields: entry
+  });
 }
 function logger(options = {}) {
   return async (ctx, next) => {
@@ -5938,7 +5955,6 @@ function createServer(options) {
     compression: compressionOption,
     etag: etagOption,
     registries,
-    logger: loggerOption,
     bodyLimit = DEFAULT_BODY_LIMIT,
     http2: http2Option,
     trustedProxy = false
@@ -5955,8 +5971,7 @@ function createServer(options) {
     const helmOpts = typeof helmetOption === "object" ? helmetOption : {};
     configMiddlewares.push(helmet(helmOpts));
   }
-  const loggerMiddlewareInst = loggerOption === false ? null : loggerOption === true || loggerOption === void 0 ? logger() : logger(loggerOption);
-  if (loggerMiddlewareInst) configMiddlewares.push(loggerMiddlewareInst);
+  configMiddlewares.push(logger());
   if (etagOption) {
     const etagOpts = typeof etagOption === "object" ? etagOption : {};
     configMiddlewares.push(etag(etagOpts));
@@ -6938,7 +6953,6 @@ var FAAPI_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "compression",
   "etag",
   "bodyLimit",
-  "logger",
   "log",
   "http2",
   "trustedProxy",
@@ -7013,7 +7027,6 @@ async function createAppBase(options) {
     helmet: config?.helmet,
     compression: config?.compression,
     etag: config?.etag,
-    logger: config?.logger,
     bodyLimit: config?.bodyLimit,
     http2: config?.http2,
     trustedProxy: config?.trustedProxy,
@@ -7671,6 +7684,7 @@ export {
   createTaskRegistriesView,
   createTaskRegistry,
   extractTypeInfo,
+  flushLogging,
   getAgent,
   getAgentEntry,
   getApp,