@faapi/faapi 6.7.0 → 6.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AppRegistries, R as RouteManifest, F as FaapiContext, C as CorsOptions, T as TaskClient, H as HelmetOptions, L as LoggerOptions, a as FaapiMiddleware, 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, W as WsRouteManifest } from './routeTypes-CsL7xtqu.js';
-export { k as AgentHandleFactory, l as AgentHandleStore, m as AgentPathMeta, n as AgentRegistry, o as AgentToolDescriptor, p as FaapiContextConfig, q as FaapiTaskMeta, r as FailOptions, s as Injector, t as RouteInfo, u as RouteInputSchema, v as RouteOutputSchema, w as RouteParamSchema, S as SkillRegistry, x as SseEvent, y as SseWriter, z as TaskContext, B as TaskDriverJob, D as TaskDriverProcess, E as TaskDriverRecord, G as TaskFailedInfo, J as TaskJob, K as TaskJobStatus, M as TaskMetadata, N as TaskModule, O as TaskRegistriesSnapshot, P as TaskRegistriesView, Q as ToolCore, U as ToolPathMeta, V as ToolRegistry, X as cors, Y as createAppRegistries, Z as createTaskRegistriesView, _ as createTaskRegistry, $ as helmet, a0 as logger } from './routeTypes-CsL7xtqu.js';
+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-J5pPbjwR.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-J5pPbjwR.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -552,6 +552,26 @@ interface FaapiConfig {
     bodyLimit?: number;
     /** 日志中间件配置 */
     logger?: LoggerOptions | boolean;
+    /**
+     * 业务日志器全局配置（与 `logger` 请求日志中间件是两条独立管道，详见 logger/logger.md）
+     *
+     * - `false`：完全静默（含 error，测试降噪）
+     * - `true` / 缺省：默认级别（显式 level > LOG_LEVEL env > 'info'）+ console 文本输出
+     * - `LogConfig`：精细配置 level 与 sink（sink 可整体接管接 pino/winston/文件）
+     *
+     * 生效范围：`ctx.log` / 参数注入 `log` / `createLogger` / `taskCtx.log`。
+     * 日志全局配置是进程级资源，多 app 同进程时后启动覆盖先启动。
+     *
+     * ```ts
+     * export default {
+     *   log: {
+     *     level: 'debug',
+     *     sink: (entry) => pinoLogger[entry.level]({ scope: entry.scope, ...entry.fields }, entry.message),
+     *   },
+     * } satisfies FaapiConfig;
+     * ```
+     */
+    log?: LogConfig | boolean;
     /** HTTP/2 配置，false 禁用（默认 http/1.1） */
     http2?: Http2Options | boolean;
     /**
@@ -1466,6 +1486,26 @@ declare function loadConfig(rootDir: string, dist: string): Promise<Partial<Faap
  */
 declare function loadEnv(rootDir: string): void;
 
+/**
+ * 设置全局日志配置（进程级，`createAppBase` 启动时以 `config.log` 调用）
+ *
+ * - `false`：完全静默（含 error，测试降噪场景）
+ * - `true` / `{}`：默认级别（显式 level > LOG_LEVEL env > 'info'）+ 默认 console sink
+ * - `{ level, sink }`：精细配置；非法 level 抛错（启动期 fail fast）
+ * - `undefined`：重置为默认（编程式多 app 切换全局配置用）
+ *
+ * LOG_LEVEL env 仅在本函数读取——app 启动路径必经此处（env 非法在启动期报错）；
+ * 纯编程式不调本函数时 env 不生效（默认 info）。
+ */
+declare function configureLogging(config?: LogConfig | boolean | undefined): void;
+/**
+ * 创建日志器
+ *
+ * @param scope 分类标签（如 'db'、'http'），默认无分类
+ * @param options 实例级覆盖（level/sink/构造 fields）
+ */
+declare function createLogger(scope?: string, options?: CreateLoggerOptions): Logger;
+
 declare const VALIDATION_ERROR = "VALIDATION_ERROR";
 declare const ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND";
 declare const METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED";
@@ -1666,4 +1706,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, 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, 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, createProdApp as createApp, createCronScheduler, createDevApp, 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, 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 };

package/dist/index.js

@@ -1122,8 +1122,10 @@ var init_resolveInjection = __esm({
       // Phase 2.3
       agents: "agents",
       // Phase 2.3
-      tasks: "tasks"
+      tasks: "tasks",
       // 任务子系统：TaskClient（入队/查询）
+      log: "log"
+      // 请求级日志器（ctx.log 同一实例：scope http，自动带 requestId 等字段）
     };
     injectionCache = /* @__PURE__ */ new WeakMap();
   }
@@ -2066,6 +2068,36 @@ function serializeError(err) {
   return { name: 'Error', message: String(err), stack: undefined, props: {} };
 }
 `;
+var BUILD_LOGGER_SOURCE = `
+var LOG_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+function createTaskLogger(level, scope, fields) {
+  function make(suffix) {
+    function write(lvl, message, callFields) {
+      if (LOG_RANK[lvl] < LOG_RANK[level]) return;
+      var entry = { level: lvl, message: message, time: new Date().toISOString() };
+      var fullScope = suffix === undefined ? scope : scope === undefined ? suffix : scope + ':' + suffix;
+      if (fullScope !== undefined) entry.scope = fullScope;
+      if (fields !== undefined || callFields !== undefined) {
+        entry.fields = Object.assign({}, fields, callFields);
+      }
+      try {
+        parentPort.postMessage({ type: 'log', entry: entry });
+      } catch (_) {
+        entry.fields = { warning: 'log fields not cloneable across worker boundary, dropped' };
+        parentPort.postMessage({ type: 'log', entry: entry });
+      }
+    }
+    return {
+      debug: function (m, f) { write('debug', m, f); },
+      info: function (m, f) { write('info', m, f); },
+      warn: function (m, f) { write('warn', m, f); },
+      error: function (m, f) { write('error', m, f); },
+      child: function (cs) { return make(suffix === undefined ? cs : suffix + ':' + cs); },
+    };
+  }
+  return make(undefined);
+}
+`;
 function buildWrapperSource(moduleUrl) {
   return `
 import { parentPort } from 'node:worker_threads';
@@ -2075,6 +2107,8 @@ ${BUILD_VIEW_SOURCE}
 
 ${SERIALIZE_ERROR_SOURCE}
 
+${BUILD_LOGGER_SOURCE}
+
 const run = mod.run;
 if (typeof run !== 'function') {
   parentPort.postMessage({
@@ -2094,7 +2128,8 @@ if (typeof run !== 'function') {
     try {
       const registries = buildRegistriesView(msg.registries);
       const progress = (value) => parentPort.postMessage({ type: 'progress', value });
-      const result = await run(payload, { ...taskCtx, signal: controller.signal, registries, progress });
+      const taskLog = msg.log ? createTaskLogger(msg.log.level, msg.log.scope, msg.log.fields) : undefined;
+      const result = await run(payload, { ...taskCtx, signal: controller.signal, registries, progress, log: taskLog });
       parentPort.postMessage({ type: 'done', result });
     } catch (err) {
       const serialized = serializeError(err);
@@ -2202,6 +2237,8 @@ async function runTaskInWorker(options) {
           finish(() => reject(reviveError(msg.error)));
         } else if (msg?.type === "progress") {
           options.onProgress?.(msg.value);
+        } else if (msg?.type === "log") {
+          options.onLog?.(msg.entry);
         }
       }
     );
@@ -2225,7 +2262,8 @@ async function runTaskInWorker(options) {
         type: "run",
         payload,
         taskCtx: { config: safeConfig(taskCtx.config), job: taskCtx.job },
-        registries: options.registries
+        registries: options.registries,
+        log: options.log
       });
     } catch (err) {
       finish(
@@ -2237,6 +2275,118 @@ async function runTaskInWorker(options) {
   });
 }
 
+// src/logger/logger.ts
+var LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+var VALID_LEVELS = ["debug", "info", "warn", "error"];
+function assertLogLevel(value, source) {
+  if (typeof value !== "string" || !VALID_LEVELS.includes(value)) {
+    throw new Error(
+      `[faapi] Invalid log level from ${source}: ${String(value)}. Expected one of: ${VALID_LEVELS.join(", ")}.`
+    );
+  }
+}
+var globalState = {
+  level: null,
+  sink: null,
+  disabled: false
+};
+function configureLogging(config) {
+  if (config === void 0) {
+    globalState.level = null;
+    globalState.sink = null;
+    globalState.disabled = false;
+    return;
+  }
+  const objectConfig = typeof config === "object" ? config : {};
+  globalState.disabled = config === false;
+  globalState.sink = objectConfig.sink ?? null;
+  if (objectConfig.level !== void 0) {
+    assertLogLevel(objectConfig.level, "config.log.level");
+    globalState.level = objectConfig.level;
+  } else if (process.env.LOG_LEVEL !== void 0) {
+    assertLogLevel(process.env.LOG_LEVEL, "LOG_LEVEL env");
+    globalState.level = process.env.LOG_LEVEL;
+  } else {
+    globalState.level = null;
+  }
+}
+function globalThreshold() {
+  return globalState.level ?? "info";
+}
+function getEffectiveLogLevel() {
+  return globalThreshold();
+}
+function serializeFieldValue(value) {
+  if (value instanceof Error) {
+    return { name: value.name, message: value.message, stack: value.stack };
+  }
+  return value;
+}
+function formatEntry(entry) {
+  let line = `[${entry.time}] ${entry.level.toUpperCase()} `;
+  if (entry.scope) line += `[${entry.scope}] `;
+  line += entry.message;
+  if (entry.fields !== void 0) {
+    const plain = Object.fromEntries(
+      Object.entries(entry.fields).map(([k, v]) => [k, serializeFieldValue(v)])
+    );
+    try {
+      line += ` ${JSON.stringify(plain)}`;
+    } catch (err) {
+      line += ` [unserializable fields: ${err instanceof Error ? err.message : String(err)}]`;
+    }
+  }
+  return line;
+}
+var CONSOLE_METHOD = {
+  debug: "debug",
+  info: "info",
+  warn: "warn",
+  error: "error"
+};
+var consoleSink = (entry) => {
+  console[CONSOLE_METHOD[entry.level]](formatEntry(entry));
+};
+function globalDispatch(entry) {
+  if (globalState.disabled) return;
+  (globalState.sink ?? consoleSink)(entry);
+}
+function writeLogEntry(entry) {
+  if (LEVEL_RANK[entry.level] < LEVEL_RANK[globalThreshold()]) return;
+  globalDispatch(entry);
+}
+function createLogger(scope, options) {
+  const baseScope = scope;
+  const baseFields = options?.fields;
+  const write = (level, message, callFields, scopeSuffix) => {
+    const threshold = options?.level ?? globalThreshold();
+    if (LEVEL_RANK[level] < LEVEL_RANK[threshold]) return;
+    const entry = {
+      level,
+      message,
+      time: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const fullScope = scopeSuffix === void 0 ? baseScope : baseScope === void 0 ? scopeSuffix : `${baseScope}:${scopeSuffix}`;
+    if (fullScope !== void 0) entry.scope = fullScope;
+    if (baseFields !== void 0 || callFields !== void 0) {
+      entry.fields = { ...baseFields, ...callFields };
+    }
+    if (options?.sink) {
+      options.sink(entry);
+    } else {
+      globalDispatch(entry);
+    }
+  };
+  const makeLogger = (scopeSuffix) => ({
+    debug: (message, fields) => write("debug", message, fields, scopeSuffix),
+    info: (message, fields) => write("info", message, fields, scopeSuffix),
+    warn: (message, fields) => write("warn", message, fields, scopeSuffix),
+    error: (message, fields) => write("error", message, fields, scopeSuffix),
+    child: (childScope) => makeLogger(scopeSuffix === void 0 ? childScope : `${scopeSuffix}:${childScope}`)
+  });
+  return makeLogger(void 0);
+}
+
 // src/task/taskQueue.ts
 var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["done", "failed", "cancelled"]);
 var MAX_FINISHED_RECORDS = 1e3;
@@ -2340,12 +2490,20 @@ function createTaskQueue(deps) {
             job: { id: job.id, name: job.name, attempt: job.attempt }
           },
           registries: snapshotRegistries(),
+          // 日志配置随 workerData 下发（纯数据），worker 内联重建 taskCtx.log，
+          // 条目回传宿主走统一管道（scope/fields 与进程内路径一致）
+          log: {
+            level: getEffectiveLogLevel(),
+            scope: `task:${job.name}`,
+            fields: { jobId: job.id, task: job.name, attempt: job.attempt }
+          },
           timeoutMs: meta.timeoutMs,
           graceMs: meta.graceMs,
           externalSignal: job.signal,
           onProgress: (value) => {
             if (record.status === "running") record.progress = value;
-          }
+          },
+          onLog: writeLogEntry
         });
       } else {
         let mod = moduleCache2.get(job.name);
@@ -2361,6 +2519,9 @@ function createTaskQueue(deps) {
           config: deps.config,
           job: { id: job.id, name: job.name, attempt: job.attempt },
           registries: registriesView,
+          log: createLogger(`task:${job.name}`, {
+            fields: { jobId: job.id, task: job.name, attempt: job.attempt }
+          }),
           progress: (value) => {
             if (record.status === "running") record.progress = value;
           }
@@ -3772,6 +3933,7 @@ function logger(options = {}) {
       const response = await next();
       const duration = Date.now() - start;
       const entry = {
+        requestId: ctx.requestId,
         method: ctx.method,
         path: ctx.path,
         status: response.status,
@@ -3784,6 +3946,7 @@ function logger(options = {}) {
       const message = err instanceof Error ? err.message : String(err);
       const status = err?.statusCode ?? 500;
       const entry = {
+        requestId: ctx.requestId,
         method: ctx.method,
         path: ctx.path,
         status,
@@ -4406,6 +4569,12 @@ function formatErrorResponse(error, config) {
 }
 
 // src/runtime/createContext.ts
+function resolveRequestId(request) {
+  const header = request.headers.get("x-request-id");
+  const first = header?.split(",")[0]?.trim();
+  if (first) return first;
+  return crypto.randomUUID();
+}
 function parseCookies(cookieHeader) {
   const cookies = /* @__PURE__ */ new Map();
   if (!cookieHeader) return cookies;
@@ -4439,7 +4608,13 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
   for (const [key, val] of parsedCookies) {
     cookiesObj[key] = val;
   }
+  const requestId = resolveRequestId(request);
+  const log = createLogger("http", {
+    fields: { requestId, method: request.method, path: url.pathname }
+  });
   const ctx = {
+    requestId,
+    log,
     request,
     params,
     query: url.searchParams,
@@ -4824,6 +4999,9 @@ function getBuiltinInjectionValue(type, ctx, body) {
     // 任务子系统：注入 TaskClient（入队/查询）；未注册工厂（无 app 编排）时 undefined
     case "tasks":
       return ctx.registries ? ctx.registries.taskHandle.get(ctx) : void 0;
+    // 请求级日志器：与 ctx.log 同一实例（scope http，自动带 requestId/method/path 字段）
+    case "log":
+      return ctx.log;
     default:
       return void 0;
   }
@@ -6659,6 +6837,7 @@ var FAAPI_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "etag",
   "bodyLimit",
   "logger",
+  "log",
   "http2",
   "trustedProxy",
   "response",
@@ -6677,6 +6856,7 @@ async function createAppBase(options) {
     );
   }
   const config = await loadConfig(rootDir, dist);
+  configureLogging(config?.log);
   const serialized = await importWithCacheBust(routesPath);
   const hydrated = await hydrateRoutes(serialized);
   let sorted = sortRoutes(hydrated.routes);
@@ -7375,11 +7555,13 @@ export {
   ValidationError,
   clearAgentHandleFactory,
   collectRouteSchemaSources,
+  configureLogging,
   cors,
   createProdApp as createApp,
   createAppRegistries,
   createCronScheduler,
   createDevApp,
+  createLogger,
   createProdApp,
   createProgram,
   createPrograms,