@faapi/faapi 6.7.0 → 6.9.0

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();
   }
@@ -1233,13 +1235,13 @@ var init_collectRouteSchemaSources = __esm({
 });
 
 // src/utils/atomicWrite.ts
-import path9 from "path";
-import fs7 from "fs";
+import path10 from "path";
+import fs8 from "fs";
 async function atomicWriteFile(outputPath, content) {
-  await fs7.promises.mkdir(path9.dirname(outputPath), { recursive: true });
+  await fs8.promises.mkdir(path10.dirname(outputPath), { recursive: true });
   const tmp = `${outputPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-  await fs7.promises.writeFile(tmp, content, "utf-8");
-  await fs7.promises.rename(tmp, outputPath);
+  await fs8.promises.writeFile(tmp, content, "utf-8");
+  await fs8.promises.rename(tmp, outputPath);
 }
 var init_atomicWrite = __esm({
   "src/utils/atomicWrite.ts"() {
@@ -1586,7 +1588,7 @@ __export(generateSchemaFiles_exports, {
   getRuntimeSchemaPath: () => getRuntimeSchemaPath,
   getSchemaOutputPath: () => getSchemaOutputPath
 });
-import path10 from "path";
+import path11 from "path";
 function getSchemaOutputPath(sourceFile, dist, rootDir) {
   let rel = sourceFile.replace(/\\/g, "/");
   if (rel.startsWith("src/")) {
@@ -1594,7 +1596,7 @@ function getSchemaOutputPath(sourceFile, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path10.resolve(rootDir, dist, relDir, "zod.js");
+  return path11.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getRuntimeSchemaPath(filePath, dist, rootDir) {
   let rel = filePath.replace(/\\/g, "/");
@@ -1605,7 +1607,7 @@ function getRuntimeSchemaPath(filePath, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path10.resolve(rootDir, dist, relDir, "zod.js");
+  return path11.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getHelpersImportPath(relDir) {
   if (!relDir) return `./${HELPERS_FILENAME}`;
@@ -1664,7 +1666,7 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   }
   const fileEntries = [];
   for (const [filePath, fileSources] of sourcesByFile) {
-    const relFile = path10.relative(rootDir, filePath).replace(/\\/g, "/");
+    const relFile = path11.relative(rootDir, filePath).replace(/\\/g, "/");
     const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
     let relForDir = relFile;
     if (relForDir.startsWith("src/")) {
@@ -1683,7 +1685,7 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   }
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
   if (usesCoerceHelpers(allSourceCode)) {
-    const helpersPath = path10.resolve(rootDir, dist, HELPERS_FILENAME);
+    const helpersPath = path11.resolve(rootDir, dist, HELPERS_FILENAME);
     await writeSchemaFile(helpersPath, generateHelpersFileSource());
   }
   await Promise.all(
@@ -1915,7 +1917,7 @@ function createAppRegistries() {
 var defaultRegistries = createAppRegistries();
 
 // src/task/taskQueue.ts
-import path3 from "path";
+import path4 from "path";
 
 // src/errors/FaapiError.ts
 var FaapiError = class extends Error {
@@ -1943,14 +1945,14 @@ var ValidationError = class extends FaapiError {
   issues;
 };
 var RouteNotFoundError = class extends FaapiError {
-  constructor(path28) {
-    super("ROUTE_NOT_FOUND", `Route not found: ${path28}`, 404);
+  constructor(path29) {
+    super("ROUTE_NOT_FOUND", `Route not found: ${path29}`, 404);
     this.name = "RouteNotFoundError";
   }
 };
 var MethodNotAllowedError = class extends FaapiError {
-  constructor(method, path28, allowedMethods) {
-    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path28}`, 405);
+  constructor(method, path29, allowedMethods) {
+    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path29}`, 405);
     this.allowedMethods = allowedMethods;
     this.name = "MethodNotAllowedError";
   }
@@ -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 (level !== undefined && 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,201 @@ async function runTaskInWorker(options) {
   });
 }
 
+// src/logger/formatEntry.ts
+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;
+}
+
+// src/logger/fileSink.ts
+import fs2 from "fs";
+import path3 from "path";
+var LEVEL_FILES = ["debug", "info", "warn", "error"];
+function createFileLogSink(options) {
+  fs2.mkdirSync(options.dir, { recursive: true });
+  const streams = /* @__PURE__ */ new Map();
+  const getStream = (name) => {
+    if (streams.has(name)) return streams.get(name);
+    return void 0;
+  };
+  const openStream = (name) => {
+    const stream = fs2.createWriteStream(path3.join(options.dir, `${name}.log`), { flags: "a" });
+    stream.on("error", () => {
+    });
+    streams.set(name, stream);
+  };
+  const fileNames = options.splitByLevel ? [...LEVEL_FILES] : ["app", "error"];
+  for (const name of fileNames) openStream(name);
+  let pendingCount = 0;
+  let drainWaiters = [];
+  const onWriteDone = () => {
+    pendingCount--;
+    if (pendingCount === 0 && drainWaiters.length > 0) {
+      const waiters = drainWaiters;
+      drainWaiters = [];
+      for (const waiter of waiters) waiter();
+    }
+  };
+  const write = (entry) => {
+    const line = `${formatEntry(entry)}
+`;
+    const target = options.splitByLevel ? entry.level : "app";
+    const main = getStream(target);
+    if (main) {
+      pendingCount++;
+      main.write(line, onWriteDone);
+    }
+    if (!options.splitByLevel && entry.level === "error") {
+      const dup = getStream("error");
+      if (dup) {
+        pendingCount++;
+        dup.write(line, onWriteDone);
+      }
+    }
+  };
+  const flush = () => new Promise((resolve) => {
+    if (pendingCount === 0) {
+      resolve();
+      return;
+    }
+    drainWaiters.push(resolve);
+  });
+  const close = () => Promise.all(
+    [...streams.values()].map(
+      (stream) => new Promise((resolve) => {
+        stream.end(() => resolve());
+      })
+    )
+  ).then(() => {
+    streams.clear();
+  });
+  return { write, flush, close };
+}
+
+// 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, fileSink: null, stdout: true, accessLog: false, disabled: false };
+function configureLogging(config) {
+  const objectConfig = typeof config === "object" ? config : {};
+  if (objectConfig.sink && objectConfig.dir) {
+    throw new Error(
+      "[faapi] config.log.sink and config.log.dir are mutually exclusive: pick one output pipeline (custom sink OR built-in file logs)."
+    );
+  }
+  void globalState.fileSink?.close();
+  globalState.disabled = config === false;
+  globalState.sink = objectConfig.sink ?? null;
+  globalState.accessLog = objectConfig.accessLog ?? objectConfig.dir !== void 0;
+  globalState.stdout = objectConfig.stdout ?? true;
+  globalState.fileSink = objectConfig.dir ? createFileLogSink({ dir: objectConfig.dir, splitByLevel: objectConfig.splitByLevel }) : 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() {
+  if (globalState.level) return globalState.level;
+  if (globalState.fileSink) return void 0;
+  return "info";
+}
+function belowThreshold(level, threshold) {
+  return threshold !== void 0 && LEVEL_RANK[level] < LEVEL_RANK[threshold];
+}
+function getEffectiveLogLevel() {
+  return globalThreshold();
+}
+var consoleSink = (entry) => {
+  console[CONSOLE_METHOD[entry.level]](formatEntry(entry));
+};
+var CONSOLE_METHOD = {
+  debug: "debug",
+  info: "info",
+  warn: "warn",
+  error: "error"
+};
+function globalDispatch(entry) {
+  if (globalState.disabled) return;
+  if (globalState.sink) {
+    globalState.sink(entry);
+    return;
+  }
+  if (globalState.fileSink) {
+    globalState.fileSink.write(entry);
+    if (globalState.stdout) consoleSink(entry);
+    return;
+  }
+  consoleSink(entry);
+}
+function writeLogEntry(entry) {
+  if (belowThreshold(entry.level, globalThreshold())) return;
+  globalDispatch(entry);
+}
+function isAccessLogPiped() {
+  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;
+    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;
@@ -2269,7 +2502,7 @@ function createTaskQueue(deps) {
   }
   const loadTaskModule = deps.loadTaskModule ?? (async (filePath) => await import(filePath));
   const loadPayloadSchema = deps.loadPayloadSchema ?? (async (filePath) => {
-    const zodPath = path3.join(path3.dirname(filePath), "zod.js");
+    const zodPath = path4.join(path4.dirname(filePath), "zod.js");
     try {
       const mod = await import(zodPath);
       const schemaKey = Object.keys(mod).find((k) => k.endsWith("Schema"));
@@ -2297,7 +2530,7 @@ function createTaskQueue(deps) {
       const meta = registry.get(name);
       schemaCache.set(
         name,
-        await loadPayloadSchema(path3.resolve(rootDir, meta.filePath)).catch(() => void 0)
+        await loadPayloadSchema(path4.resolve(rootDir, meta.filePath)).catch(() => void 0)
       );
     }
     const schema = schemaCache.get(name);
@@ -2333,24 +2566,32 @@ function createTaskQueue(deps) {
       let result;
       if (meta.timeoutMs !== void 0 && meta.timeoutMs > 0) {
         result = await (deps.runIsolated ?? runTaskInWorker)({
-          taskModulePath: path3.resolve(rootDir, meta.filePath),
+          taskModulePath: path4.resolve(rootDir, meta.filePath),
           payload: job.payload,
           taskCtx: {
             config: deps.config,
             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);
         if (!mod) {
-          mod = await loadTaskModule(path3.resolve(rootDir, meta.filePath));
+          mod = await loadTaskModule(path4.resolve(rootDir, meta.filePath));
           moduleCache2.set(job.name, mod);
         }
         if (typeof mod.run !== "function") {
@@ -2361,6 +2602,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;
           }
@@ -2584,8 +2828,8 @@ function createCronScheduler(registry, enqueue) {
 
 // src/task/scanTasks.ts
 import fg from "fast-glob";
-import path4 from "path";
-import fs2 from "fs";
+import path5 from "path";
+import fs3 from "fs";
 var TASK_PATTERNS = ["src/tasks/**/task.ts"];
 var TASK_FILENAME = "task.ts";
 var CRON_RE = /(?:^|\n)\s*cron:\s*['"`]([^'"`\n]+)['"`]/;
@@ -2616,12 +2860,12 @@ async function scanTasks(rootDir, patterns) {
   const seen = /* @__PURE__ */ new Map();
   for (const file of files) {
     const normalizedFile = file.replace(/\\/g, "/");
-    const fileName = path4.posix.basename(normalizedFile);
+    const fileName = path5.posix.basename(normalizedFile);
     if (fileName !== TASK_FILENAME) {
       continue;
     }
-    const absPath = path4.resolve(rootDir, normalizedFile);
-    const source = await fs2.promises.readFile(absPath, "utf8").catch(() => "");
+    const absPath = path5.resolve(rootDir, normalizedFile);
+    const source = await fs3.promises.readFile(absPath, "utf8").catch(() => "");
     const name = filePathToTaskName(normalizedFile);
     const prevFile = seen.get(name);
     if (prevFile) {
@@ -2694,7 +2938,7 @@ function listSkills() {
 }
 
 // src/loader/loadAgentModule.ts
-import fs10 from "fs";
+import fs11 from "fs";
 
 // src/loader/resolveExports.ts
 function resolveExport(module, exportName) {
@@ -2740,18 +2984,18 @@ async function importWithCacheBust(filePath, bustViteCache = false) {
 }
 
 // src/cli/compileOnDemand.ts
-import path12 from "path";
-import fs9 from "fs";
+import path13 from "path";
+import fs10 from "fs";
 
 // src/cli/compileSourceFiles.ts
-import path8 from "path";
-import fs6 from "fs";
+import path9 from "path";
+import fs7 from "fs";
 import fg2 from "fast-glob";
 
 // src/cli/aliasPlugin.ts
 import ts7 from "typescript";
-import path7 from "path";
-import fs5 from "fs";
+import path8 from "path";
+import fs6 from "fs";
 
 // src/utils/resolveAlias.ts
 function resolveAlias(specifier, config) {
@@ -2777,8 +3021,8 @@ function resolveAlias(specifier, config) {
 }
 
 // src/utils/prodPaths.ts
-import path5 from "path";
-import fs3 from "fs";
+import path6 from "path";
+import fs4 from "fs";
 var APP_DIR = "src";
 var ROUTE_PATTERNS = ["src/api/**/*.ts"];
 function toProdFilePath(filePath, dist) {
@@ -2797,27 +3041,27 @@ function toProdExtension(filePath) {
 }
 function toRealPath(p) {
   try {
-    return fs3.realpathSync(p);
+    return fs4.realpathSync(p);
   } catch {
     return p;
   }
 }
 function isInsideDir(filePath, dir) {
-  const rel = path5.relative(dir, filePath);
-  return rel !== "" && !rel.startsWith("..") && !path5.isAbsolute(rel);
+  const rel = path6.relative(dir, filePath);
+  return rel !== "" && !rel.startsWith("..") && !path6.isAbsolute(rel);
 }
 
 // src/utils/readTsconfig.ts
 import ts6 from "typescript";
-import path6 from "path";
-import fs4 from "fs";
+import path7 from "path";
+import fs5 from "fs";
 var tsconfigCache = /* @__PURE__ */ new Map();
 function readTsconfig(rootDir) {
-  const tsconfigPath = path6.resolve(rootDir, "tsconfig.json");
-  if (!fs4.existsSync(tsconfigPath)) return null;
+  const tsconfigPath = path7.resolve(rootDir, "tsconfig.json");
+  if (!fs5.existsSync(tsconfigPath)) return null;
   let mtimeMs;
   try {
-    mtimeMs = fs4.statSync(tsconfigPath).mtimeMs;
+    mtimeMs = fs5.statSync(tsconfigPath).mtimeMs;
   } catch {
     return null;
   }
@@ -2833,7 +3077,7 @@ function readTsconfig(rootDir) {
   const config = rawPaths ? (() => {
     const paths = {};
     for (const [pattern, targets] of Object.entries(rawPaths)) {
-      paths[pattern] = targets.map((t) => path6.resolve(baseUrl, t));
+      paths[pattern] = targets.map((t) => path7.resolve(baseUrl, t));
     }
     return { baseUrl, paths };
   })() : null;
@@ -2843,26 +3087,26 @@ function readTsconfig(rootDir) {
 
 // src/cli/aliasPlugin.ts
 function toProdImportPath(sourceFile, importer) {
-  const importerDir = path7.dirname(importer);
-  let rel = path7.relative(importerDir, sourceFile);
-  rel = rel.split(path7.sep).join("/");
+  const importerDir = path8.dirname(importer);
+  let rel = path8.relative(importerDir, sourceFile);
+  rel = rel.split(path8.sep).join("/");
   if (!rel.startsWith(".")) rel = "./" + rel;
   return toProdExtension(rel);
 }
 function toStrippedProdImportPath(sourceFile, rootDir) {
-  const appDirAbs = toRealPath(path7.resolve(rootDir, APP_DIR));
+  const appDirAbs = toRealPath(path8.resolve(rootDir, APP_DIR));
   const sourceReal = toRealPath(sourceFile);
-  let rel = path7.relative(appDirAbs, sourceReal);
-  rel = rel.split(path7.sep).join("/");
+  let rel = path8.relative(appDirAbs, sourceReal);
+  rel = rel.split(path8.sep).join("/");
   if (!rel.startsWith(".")) rel = "./" + rel;
   return toProdExtension(rel);
 }
 function toProdImportFromImporter(importer, rootDir, relFromDist) {
-  const importerRel = path7.relative(toRealPath(path7.resolve(rootDir)), toRealPath(importer)).split(path7.sep).join("/");
-  const importerProdDir = path7.posix.dirname(toProdExtension(importerRel));
+  const importerRel = path8.relative(toRealPath(path8.resolve(rootDir)), toRealPath(importer)).split(path8.sep).join("/");
+  const importerProdDir = path8.posix.dirname(toProdExtension(importerRel));
   if (importerProdDir === ".") return relFromDist;
   const target = relFromDist.replace(/^\.\//, "");
-  let rel = path7.posix.relative(importerProdDir, target);
+  let rel = path8.posix.relative(importerProdDir, target);
   if (!rel.startsWith(".")) rel = "./" + rel;
   return rel;
 }
@@ -2877,41 +3121,41 @@ var INDEX_EXTS = [
   "/index.cjs"
 ];
 function resolveRelativeSpecifier(importer, specifier) {
-  const importerDir = path7.dirname(importer);
-  const base = path7.resolve(importerDir, specifier);
+  const importerDir = path8.dirname(importer);
+  const base = path8.resolve(importerDir, specifier);
   if (PROD_EXTS.some((ext) => specifier.endsWith(ext))) {
-    if (fs5.existsSync(base)) return base;
+    if (fs6.existsSync(base)) return base;
     if (base.endsWith(".js")) {
       for (const ext of [".ts", ".tsx", ".jsx"]) {
         const file = base.slice(0, -3) + ext;
-        if (fs5.existsSync(file)) return file;
+        if (fs6.existsSync(file)) return file;
       }
     }
     return null;
   }
   if (/\.(ts|tsx|jsx)$/.test(specifier)) {
-    return fs5.existsSync(base) ? base : null;
+    return fs6.existsSync(base) ? base : null;
   }
   for (const ext of SOURCE_EXTS) {
     const file = base + ext;
-    if (fs5.existsSync(file)) return file;
+    if (fs6.existsSync(file)) return file;
   }
   for (const indexExt of INDEX_EXTS) {
     const file = base + indexExt;
-    if (fs5.existsSync(file)) return file;
+    if (fs6.existsSync(file)) return file;
   }
   return null;
 }
 function createAliasPlugin(config, options) {
-  const appDirAbs = options?.rootDir ? toRealPath(path7.resolve(options.rootDir, APP_DIR)) : null;
+  const appDirAbs = options?.rootDir ? toRealPath(path8.resolve(options.rootDir, APP_DIR)) : null;
   const probeCandidateFile = (candidate) => {
     for (const ext of SOURCE_EXTS) {
       const file = candidate + ext;
-      if (fs5.existsSync(file)) return file;
+      if (fs6.existsSync(file)) return file;
     }
     for (const indexExt of INDEX_EXTS) {
       const file = candidate + indexExt;
-      if (fs5.existsSync(file)) return file;
+      if (fs6.existsSync(file)) return file;
     }
     return null;
   };
@@ -2921,7 +3165,7 @@ function createAliasPlugin(config, options) {
       build.onLoad({ filter: /\.(ts|tsx|js|jsx|mjs|cjs)$/ }, (args) => {
         let source;
         try {
-          source = fs5.readFileSync(args.path, "utf8");
+          source = fs6.readFileSync(args.path, "utf8");
         } catch {
           return void 0;
         }
@@ -3046,11 +3290,11 @@ async function compileSourceFiles(options) {
   if (entryPoints.length === 0) {
     return { compiledFiles: [] };
   }
-  const absDist = path8.resolve(rootDir, dist);
-  await fs6.promises.mkdir(absDist, { recursive: true });
+  const absDist = path9.resolve(rootDir, dist);
+  await fs7.promises.mkdir(absDist, { recursive: true });
   const plugins = buildAliasPlugins(rootDir);
   const esbuild = await import("esbuild");
-  const outbase = path8.resolve(rootDir, APP_DIR);
+  const outbase = path9.resolve(rootDir, APP_DIR);
   const result = await esbuild.build({
     entryPoints,
     outdir: absDist,
@@ -3070,10 +3314,10 @@ async function compileSourceFiles(options) {
   if (atomicWrite && result.outputFiles) {
     await Promise.all(
       result.outputFiles.map(async (file) => {
-        await fs6.promises.mkdir(path8.dirname(file.path), { recursive: true });
+        await fs7.promises.mkdir(path9.dirname(file.path), { recursive: true });
         const tmp = `${file.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-        await fs6.promises.writeFile(tmp, file.contents);
-        await fs6.promises.rename(tmp, file.path);
+        await fs7.promises.writeFile(tmp, file.contents);
+        await fs7.promises.rename(tmp, file.path);
       })
     );
   }
@@ -3090,8 +3334,8 @@ init_generateSchemaFiles();
 init_generateSchemaFiles();
 
 // src/cli/collectImports.ts
-import path11 from "path";
-import fs8 from "fs";
+import path12 from "path";
+import fs9 from "fs";
 var SPEC_RE = /(\bfrom\s*|import\s*\(\s*)(['"])([^'"]+)\2/g;
 function extractImportSpecifiers(source) {
   const specifiers = [];
@@ -3103,10 +3347,10 @@ function extractImportSpecifiers(source) {
   return specifiers;
 }
 function resolveSpecifierFromDir(dir, specifier) {
-  return resolveRelativeSpecifier(path11.join(dir, "__faapi_probe__.ts"), specifier);
+  return resolveRelativeSpecifier(path12.join(dir, "__faapi_probe__.ts"), specifier);
 }
 async function collectRelativeImports(entryFiles, rootDir) {
-  const appDirAbs = toRealPath(path11.resolve(rootDir, "src"));
+  const appDirAbs = toRealPath(path12.resolve(rootDir, "src"));
   const tsconfig = readTsconfig(rootDir);
   const visited = /* @__PURE__ */ new Set();
   const insideFiles = /* @__PURE__ */ new Set();
@@ -3116,7 +3360,7 @@ async function collectRelativeImports(entryFiles, rootDir) {
     visited.add(filePath);
     let source;
     try {
-      source = await fs8.promises.readFile(filePath, "utf8");
+      source = await fs9.promises.readFile(filePath, "utf8");
     } catch {
       return;
     }
@@ -3138,7 +3382,7 @@ async function collectRelativeImports(entryFiles, rootDir) {
         resolved = null;
       }
       if (!resolved) continue;
-      if (!isInsideDir(toRealPath(resolved), toRealPath(path11.resolve(rootDir)))) continue;
+      if (!isInsideDir(toRealPath(resolved), toRealPath(path12.resolve(rootDir)))) continue;
       if (isInsideDir(toRealPath(resolved), appDirAbs)) {
         insideFiles.add(resolved);
       } else {
@@ -3159,8 +3403,8 @@ async function collectRelativeImports(entryFiles, rootDir) {
 // src/cli/compileOnDemand.ts
 function isProductFresh(sourceAbsPath, productAbsPath) {
   try {
-    const srcStat = fs9.statSync(sourceAbsPath);
-    const prodStat = fs9.statSync(productAbsPath);
+    const srcStat = fs10.statSync(sourceAbsPath);
+    const prodStat = fs10.statSync(productAbsPath);
     return prodStat.mtimeMs >= srcStat.mtimeMs;
   } catch {
     return false;
@@ -3192,7 +3436,7 @@ async function ensureCompiled(sourceAbsPath, rootDir, dist) {
   if (state.compiledFiles.has(sourceAbsPath)) {
     return false;
   }
-  if (!fs9.existsSync(sourceAbsPath)) {
+  if (!fs10.existsSync(sourceAbsPath)) {
     return false;
   }
   const productPath = prodSourcePathToProductPath(sourceAbsPath, rootDir, dist);
@@ -3242,11 +3486,11 @@ async function ensureMiddlewaresCompiled(middlewarePaths, rootDir) {
   }
 }
 function prodSourcePathToProductPath(sourceAbsPath, rootDir, dist) {
-  const rel = path12.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  const rel = path13.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
   if (!rel.startsWith("src/")) return null;
   const relWithoutSrc = rel.slice(4);
   const jsRel = relWithoutSrc.replace(/\.ts$/, ".js");
-  return path12.resolve(rootDir, dist, jsRel);
+  return path13.resolve(rootDir, dist, jsRel);
 }
 function clearGeneratedSchemas() {
   state.generatedSchemas.clear();
@@ -3262,9 +3506,9 @@ async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir,
   if (state.generatedSchemas.has(schemaPath)) {
     return false;
   }
-  const prodAbsPath = path12.resolve(rootDir, routeFilePath);
+  const prodAbsPath = path13.resolve(rootDir, routeFilePath);
   const sourceAbsPath = prodPathToSourcePath(prodAbsPath, rootDir, dist);
-  if (!fs9.existsSync(sourceAbsPath)) {
+  if (!fs10.existsSync(sourceAbsPath)) {
     return false;
   }
   if (isProductFresh(sourceAbsPath, schemaPath)) {
@@ -3275,7 +3519,7 @@ async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir,
   if (fileRoutes.length === 0) {
     return false;
   }
-  const sourceRelPath = path12.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  const sourceRelPath = path13.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
   const sourceRoutes = fileRoutes.map((r) => ({ ...r, filePath: sourceRelPath }));
   const generatePromise = (async () => {
     await generateSchemaFiles(sourceRoutes, rootDir, dist);
@@ -3296,7 +3540,7 @@ async function deleteSchemaFiles(routes, rootDir, dist) {
     if (deleted.has(schemaPath)) continue;
     deleted.add(schemaPath);
     try {
-      await fs9.promises.unlink(schemaPath);
+      await fs10.promises.unlink(schemaPath);
     } catch {
     }
   }
@@ -3305,19 +3549,19 @@ var sourcePathCache = /* @__PURE__ */ new Map();
 function prodPathToSourcePath(prodAbsPath, rootDir, dist) {
   const cached = sourcePathCache.get(prodAbsPath);
   if (cached) return cached;
-  const rel = path12.relative(rootDir, prodAbsPath).replace(/\\/g, "/");
+  const rel = path13.relative(rootDir, prodAbsPath).replace(/\\/g, "/");
   let relWithoutDist = rel;
   if (relWithoutDist.startsWith(`${dist}/`)) {
     relWithoutDist = relWithoutDist.slice(dist.length + 1);
   }
   const srcRel = `src/${relWithoutDist}`;
   const tsRel = srcRel.replace(/\.js$/, ".ts");
-  const tsAbs = path12.resolve(rootDir, tsRel);
+  const tsAbs = path13.resolve(rootDir, tsRel);
   let result;
-  if (fs9.existsSync(tsAbs)) {
+  if (fs10.existsSync(tsAbs)) {
     result = tsAbs;
   } else {
-    result = path12.resolve(rootDir, srcRel);
+    result = path13.resolve(rootDir, srcRel);
   }
   sourcePathCache.set(prodAbsPath, result);
   return result;
@@ -3335,7 +3579,7 @@ async function loadAgentModule(filePath, hasRun, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs10.existsSync(sourcePath)) {
+      if (sourcePath && fs11.existsSync(sourcePath)) {
         try {
           await ensureCompiled(sourcePath, rootDir, dist);
         } catch (compileErr) {
@@ -3368,13 +3612,13 @@ async function loadAgentModule(filePath, hasRun, rootDir) {
 }
 
 // src/loader/loadToolModule.ts
-import fs11 from "fs";
+import fs12 from "fs";
 async function loadToolModule(filePath, functionName, rootDir) {
   if (isDevOnDemandEnabled() && rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs11.existsSync(sourcePath)) {
+      if (sourcePath && fs12.existsSync(sourcePath)) {
         try {
           await ensureCompiled(sourcePath, rootDir, dist);
         } catch (compileErr) {
@@ -3406,7 +3650,7 @@ async function loadToolModule(filePath, functionName, rootDir) {
 import { existsSync as existsSync2 } from "fs";
 
 // src/cli/generateToolArtifacts.ts
-import path13 from "path";
+import path14 from "path";
 import { existsSync } from "fs";
 
 // src/ast/extractToolMetadata.ts
@@ -3530,7 +3774,7 @@ function collectToolSchemaSources(tools, rootDir) {
   const toolsByFile = /* @__PURE__ */ new Map();
   for (const tool of tools) {
     if (!tool.inputTypeName) continue;
-    const absPath = path13.resolve(rootDir, tool.filePath);
+    const absPath = path14.resolve(rootDir, tool.filePath);
     let list = toolsByFile.get(absPath);
     if (!list) {
       list = [];
@@ -3590,15 +3834,15 @@ function generateToolSchemaFileSource(sources, resolveType, helpersImportPath) {
 }
 async function maybeGenerateHelpers(allSourceCode, distDir) {
   if (!usesCoerceHelpers(allSourceCode)) return;
-  const helpersPath = path13.resolve(distDir, HELPERS_FILENAME);
+  const helpersPath = path14.resolve(distDir, HELPERS_FILENAME);
   if (existsSync(helpersPath)) return;
   await atomicWriteFile(helpersPath, generateHelpersFileSource());
 }
 async function generateToolArtifacts(tools, rootDir, dist, options) {
   const metadata = [];
-  const programByFile = createPrograms(tools.map((m) => path13.resolve(rootDir, m.filePath)));
+  const programByFile = createPrograms(tools.map((m) => path14.resolve(rootDir, m.filePath)));
   for (const manifest of tools) {
-    const absPath = path13.resolve(rootDir, manifest.filePath);
+    const absPath = path14.resolve(rootDir, manifest.filePath);
     const program = programByFile.get(absPath);
     const result = extractToolMetadata(program, absPath, manifest.functionName, {
       name: manifest.name,
@@ -3609,7 +3853,7 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
     }
   }
   const serialized = serializeTools(metadata, dist);
-  const toolsPath = path13.resolve(rootDir, dist, TOOLS_FILE);
+  const toolsPath = path14.resolve(rootDir, dist, TOOLS_FILE);
   await writeToolsModule(serialized, toolsPath);
   if (options?.skipSchema) {
     return metadata;
@@ -3632,7 +3876,7 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
   }
   const fileEntries = [];
   for (const [filePath, fileSources] of sourcesByFile) {
-    const relFile = path13.relative(rootDir, filePath).replace(/\\/g, "/");
+    const relFile = path14.relative(rootDir, filePath).replace(/\\/g, "/");
     const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
     const resolver = resolversByFile.get(filePath);
     let relForDir = relFile;
@@ -3650,7 +3894,7 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
     fileEntries.push({ outputPath, source });
   }
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
-  const distDir = path13.resolve(rootDir, dist);
+  const distDir = path14.resolve(rootDir, dist);
   await maybeGenerateHelpers(allSourceCode, distDir);
   await Promise.all(
     fileEntries.map(({ outputPath, source }) => writeToolSchemaFile(outputPath, source))
@@ -3764,14 +4008,34 @@ function cors(options = {}) {
 }
 
 // src/middleware/logger.ts
+function levelForStatus(status) {
+  if (status >= 500) return "error";
+  if (status >= 400) return "warn";
+  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);
+}
 function logger(options = {}) {
   return async (ctx, next) => {
-    const log = options.log ?? console.log;
+    const log = options.log ?? defaultLog;
     const start = Date.now();
     try {
       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 +4048,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,
@@ -3859,16 +4124,16 @@ function helmet(options = {}) {
 }
 
 // src/config/loadConfig.ts
-import path14 from "path";
-import fs12 from "fs";
+import path15 from "path";
+import fs13 from "fs";
 var CONFIG_PRODUCT_FILE = "faapi-config.js";
 async function loadConfig(rootDir, dist) {
-  const configProductPath = path14.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
-  if (fs12.existsSync(configProductPath)) {
+  const configProductPath = path15.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
+  if (fs13.existsSync(configProductPath)) {
     const module = await importWithCacheBust(configProductPath);
     return module.default ?? {};
   }
-  const hasSourceConfig = fs12.existsSync(path14.join(rootDir, "faapi.config.ts")) || fs12.existsSync(path14.join(rootDir, "faapi.config.js"));
+  const hasSourceConfig = fs13.existsSync(path15.join(rootDir, "faapi.config.ts")) || fs13.existsSync(path15.join(rootDir, "faapi.config.js"));
   if (hasSourceConfig) {
     throw new Error(
       `[faapi] ${dist}/${CONFIG_PRODUCT_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
@@ -3878,8 +4143,8 @@ async function loadConfig(rootDir, dist) {
 }
 
 // src/cli/loadEnv.ts
-import fs13 from "fs";
-import path15 from "path";
+import fs14 from "fs";
+import path16 from "path";
 function resolveEnv() {
   return process.env.NODE_ENV || "development";
 }
@@ -3946,9 +4211,9 @@ function loadEnv(rootDir) {
   const files = getEnvFiles(env);
   const merged = {};
   for (const file of files) {
-    const filePath = path15.join(rootDir, file);
-    if (!fs13.existsSync(filePath)) continue;
-    const content = fs13.readFileSync(filePath, "utf-8");
+    const filePath = path16.join(rootDir, file);
+    if (!fs14.existsSync(filePath)) continue;
+    const content = fs14.readFileSync(filePath, "utf-8");
     const parsed = parseEnvFile(content, merged);
     Object.assign(merged, parsed);
   }
@@ -3960,8 +4225,8 @@ function loadEnv(rootDir) {
 }
 
 // src/cli/createAppCore.ts
-import fs18 from "fs";
-import path23 from "path";
+import fs19 from "fs";
+import path24 from "path";
 import { PassThrough, Readable as Readable3 } from "stream";
 
 // src/router/sortRoutes.ts
@@ -4014,7 +4279,7 @@ import {
 import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable2 } from "stream";
-import path17 from "path";
+import path18 from "path";
 
 // src/router/matchRoute.ts
 var httpIndexCache = /* @__PURE__ */ new WeakMap();
@@ -4056,18 +4321,18 @@ function getWsIndex(routes) {
   wsIndexCache.set(routes, index);
   return index;
 }
-function matchRoute(routes, method, path28) {
+function matchRoute(routes, method, path29) {
   const index = getHttpIndex(routes);
   const upper = method.toUpperCase();
-  const hit = matchByMethod(index, upper, path28);
+  const hit = matchByMethod(index, upper, path29);
   if (hit) return hit;
   if (upper === "HEAD") {
-    return matchByMethod(index, "GET", path28);
+    return matchByMethod(index, "GET", path29);
   }
   return null;
 }
-function matchByMethod(index, method, path28) {
-  const staticHit = index.static.get(`${method}|${path28}`);
+function matchByMethod(index, method, path29) {
+  const staticHit = index.static.get(`${method}|${path29}`);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
@@ -4076,31 +4341,31 @@ function matchByMethod(index, method, path28) {
     if (route.method !== method) {
       continue;
     }
-    const params = matchSegments(entry.segments, path28, route.paramNames, route.isCatchAll);
+    const params = matchSegments(entry.segments, path29, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function matchWsRoute(wsRoutes, path28) {
+function matchWsRoute(wsRoutes, path29) {
   const index = getWsIndex(wsRoutes);
-  const staticHit = index.static.get(path28);
+  const staticHit = index.static.get(path29);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
   for (const route of index.dynamics) {
-    const params = matchDynamicPath(route.urlPath, path28, route.paramNames, route.isCatchAll);
+    const params = matchDynamicPath(route.urlPath, path29, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function findAllowedMethods(routes, path28) {
+function findAllowedMethods(routes, path29) {
   const index = getHttpIndex(routes);
   const methods = /* @__PURE__ */ new Set();
-  const staticMethods = index.methodsByStaticPath.get(path28);
+  const staticMethods = index.methodsByStaticPath.get(path29);
   if (staticMethods) {
     for (const method of staticMethods) {
       methods.add(method);
@@ -4109,7 +4374,7 @@ function findAllowedMethods(routes, path28) {
   for (const entry of index.dynamics) {
     const params = matchSegments(
       entry.segments,
-      path28,
+      path29,
       entry.route.paramNames,
       entry.route.isCatchAll
     );
@@ -4122,11 +4387,11 @@ function findAllowedMethods(routes, path28) {
   }
   return Array.from(methods);
 }
-function matchDynamicPath(pattern, path28, paramNames, isCatchAll) {
-  return matchSegments(pattern.split("/").filter(Boolean), path28, paramNames, isCatchAll);
+function matchDynamicPath(pattern, path29, paramNames, isCatchAll) {
+  return matchSegments(pattern.split("/").filter(Boolean), path29, paramNames, isCatchAll);
 }
-function matchSegments(patternSegments, path28, paramNames, isCatchAll) {
-  const pathSegments = path28.split("/").filter(Boolean);
+function matchSegments(patternSegments, path29, paramNames, isCatchAll) {
+  const pathSegments = path29.split("/").filter(Boolean);
   if (isCatchAll) {
     const nonCatchAllCount = patternSegments.length - 1;
     if (pathSegments.length <= nonCatchAllCount) {
@@ -4406,6 +4671,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 +4710,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 +5101,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;
   }
@@ -5018,9 +5298,9 @@ async function validateInput(schemaPath, method, inputType, input) {
 function mapZodIssues(error) {
   return error.issues.map((issue) => {
     const code = mapZodCode(issue);
-    const path28 = issue.path.map(String).join(".") || "";
+    const path29 = issue.path.map(String).join(".") || "";
     return {
-      path: path28,
+      path: path29,
       code,
       expected: issue.expected ?? mapExpectedFromMessage(issue.message),
       received: issue.received ?? mapReceivedFromMessage(issue.message),
@@ -5252,9 +5532,9 @@ function etag(options = {}) {
 }
 
 // src/server/handleWsUpgrade.ts
-import fs14 from "fs";
+import fs15 from "fs";
 import { WebSocketServer, WebSocket } from "ws";
-import path16 from "path";
+import path17 from "path";
 
 // src/server/serverUtils.ts
 function nodeHttpToWebHeaders(req) {
@@ -5389,7 +5669,7 @@ async function loadWsHandler(filePath, ctx, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs14.existsSync(sourcePath)) {
+      if (sourcePath && fs15.existsSync(sourcePath)) {
         await ensureCompiled(sourcePath, rootDir, dist);
       }
     }
@@ -5503,7 +5783,7 @@ function attachWebSocket(options) {
     const finalHandler = async () => {
       let handlers;
       try {
-        const absoluteFilePath = path16.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path17.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx, rootDir);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -5756,7 +6036,7 @@ function getRoutePaths(route, rootDir, dist) {
   let cached = routePathCache.get(route);
   if (!cached) {
     cached = {
-      absFilePath: path17.resolve(rootDir, route.filePath),
+      absFilePath: path18.resolve(rootDir, route.filePath),
       schemaPath: getRuntimeSchemaPath(route.filePath, dist, rootDir)
     };
     routePathCache.set(route, cached);
@@ -5878,8 +6158,8 @@ function applyPluginWrappers(server, handlerWrappers, upgradeWrappers) {
 }
 
 // src/cli/generateRoutes.ts
-import fs15 from "fs";
-import path18 from "path";
+import fs16 from "fs";
+import path19 from "path";
 async function hydrateRoutes(manifest) {
   const hydrateRoute = (serialized) => ({
     method: serialized.method,
@@ -5904,7 +6184,7 @@ async function hydrateRoutes(manifest) {
 }
 
 // src/cli/generateAgentArtifacts.ts
-import path19 from "path";
+import path20 from "path";
 
 // src/ast/extractAgentMetadata.ts
 import ts10 from "typescript";
@@ -6177,9 +6457,9 @@ function validateAgentList(metadata) {
 }
 async function generateAgentArtifacts(agents, rootDir, dist) {
   const metadata = [];
-  const programByFile = createPrograms(agents.map((m) => path19.resolve(rootDir, m.filePath)));
+  const programByFile = createPrograms(agents.map((m) => path20.resolve(rootDir, m.filePath)));
   for (const manifest of agents) {
-    const absPath = path19.resolve(rootDir, manifest.filePath);
+    const absPath = path20.resolve(rootDir, manifest.filePath);
     const program = programByFile.get(absPath);
     const result = extractAgentMetadata(program, absPath, {
       name: manifest.name,
@@ -6195,13 +6475,13 @@ async function generateAgentArtifacts(agents, rootDir, dist) {
   }
   validateAgentList(metadata);
   const serialized = serializeAgents(metadata, dist);
-  const agentsPath = path19.resolve(rootDir, dist, AGENTS_FILE);
+  const agentsPath = path20.resolve(rootDir, dist, AGENTS_FILE);
   await writeAgentsModule(serialized, agentsPath);
   return metadata;
 }
 
 // src/cli/generateTaskArtifacts.ts
-import path20 from "path";
+import path21 from "path";
 init_createProgram();
 init_atomicWrite();
 init_generateSchemaFiles();
@@ -6240,7 +6520,7 @@ function collectTaskSchemaSources(tasks, rootDir) {
   const tasksByFile = /* @__PURE__ */ new Map();
   for (const task of tasks) {
     if (!task.inputTypeName) continue;
-    const absPath = path20.resolve(rootDir, task.filePath);
+    const absPath = path21.resolve(rootDir, task.filePath);
     let list = tasksByFile.get(absPath);
     if (!list) {
       list = [];
@@ -6297,9 +6577,9 @@ function generateTaskSchemaFileSource(sources, resolveType, helpersImportPath) {
 async function generateTaskArtifacts(manifests, rootDir, dist) {
   const metadata = [];
   if (manifests.length > 0) {
-    const programByFile = createPrograms(manifests.map((m) => path20.resolve(rootDir, m.filePath)));
+    const programByFile = createPrograms(manifests.map((m) => path21.resolve(rootDir, m.filePath)));
     for (const manifest of manifests) {
-      const absPath = path20.resolve(rootDir, manifest.filePath);
+      const absPath = path21.resolve(rootDir, manifest.filePath);
       const result = extractToolMetadata(programByFile.get(absPath), absPath, "run", {
         name: manifest.name,
         filePath: manifest.filePath
@@ -6310,7 +6590,7 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
     }
   }
   const serialized = serializeTasks(manifests, dist);
-  const tasksPath = path20.resolve(rootDir, dist, TASKS_FILE);
+  const tasksPath = path21.resolve(rootDir, dist, TASKS_FILE);
   await writeTasksModule(serialized, tasksPath);
   if (metadata.length === 0) {
     return hydrateTasks(serialized);
@@ -6330,7 +6610,7 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
   }
   const fileEntries = [];
   for (const [filePath, fileSources] of sourcesByFile) {
-    const relFile = path20.relative(rootDir, filePath).replace(/\\/g, "/");
+    const relFile = path21.relative(rootDir, filePath).replace(/\\/g, "/");
     const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
     const resolver = resolversByFile.get(filePath);
     let relForDir = relFile;
@@ -6349,7 +6629,7 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
   }
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
   if (usesCoerceHelpers(allSourceCode)) {
-    const helpersPath = path20.resolve(rootDir, dist, HELPERS_FILENAME);
+    const helpersPath = path21.resolve(rootDir, dist, HELPERS_FILENAME);
     const { existsSync: existsSync3 } = await import("fs");
     if (!existsSync3(helpersPath)) {
       await atomicWriteFile(helpersPath, generateHelpersFileSource());
@@ -6381,18 +6661,18 @@ function createIdleTaskDriver() {
 }
 
 // src/cli/loadPlugins.ts
-import path22 from "path";
-import fs17 from "fs";
+import path23 from "path";
+import fs18 from "fs";
 import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/cli/compileConfig.ts
-import path21 from "path";
-import fs16 from "fs";
+import path22 from "path";
+import fs17 from "fs";
 async function compileProjectModules(entryPoints, rootDir, dist) {
   const { insideFiles, outsideFiles } = await collectRelativeImports(entryPoints, rootDir);
   const esbuild = await import("esbuild");
   const aliasPlugins = buildAliasPlugins(rootDir);
-  const absDist = path21.resolve(rootDir, dist);
+  const absDist = path22.resolve(rootDir, dist);
   await esbuild.build({
     entryPoints: [...entryPoints, ...outsideFiles],
     outdir: absDist,
@@ -6406,7 +6686,7 @@ async function compileProjectModules(entryPoints, rootDir, dist) {
     logLevel: "silent"
   });
   if (insideFiles.length > 0) {
-    const appOutbase = path21.resolve(rootDir, "src");
+    const appOutbase = path22.resolve(rootDir, "src");
     await esbuild.build({
       entryPoints: insideFiles,
       outdir: absDist,
@@ -6487,37 +6767,37 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
 var TS_EXTS = /\.(ts|tsx|mts|cts)$/;
 var JS_EXTS = /\.(js|mjs|cjs|jsx)$/;
 function resolveLocalPluginSource(specifier, baseDir) {
-  const base = path22.isAbsolute(specifier) ? specifier : path22.resolve(baseDir, specifier);
-  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs17.existsSync(base)) return base;
+  const base = path23.isAbsolute(specifier) ? specifier : path23.resolve(baseDir, specifier);
+  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs18.existsSync(base)) return base;
   for (const ext of [".ts", ".js"]) {
-    if (fs17.existsSync(base + ext)) return base + ext;
+    if (fs18.existsSync(base + ext)) return base + ext;
   }
   for (const indexExt of ["/index.ts", "/index.js"]) {
-    if (fs17.existsSync(base + indexExt)) return base + indexExt;
+    if (fs18.existsSync(base + indexExt)) return base + indexExt;
   }
   return null;
 }
 function mirrorProductPath(sourcePath, baseDir, distDir) {
-  let rel = path22.relative(baseDir, sourcePath).replace(/\\/g, "/");
+  let rel = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
   if (rel.startsWith("src/")) rel = rel.slice(4);
-  return path22.resolve(distDir, rel.replace(TS_EXTS, ".js"));
+  return path23.resolve(distDir, rel.replace(TS_EXTS, ".js"));
 }
 function isSourceNewer(sourcePath, productPath) {
   try {
-    return fs17.statSync(sourcePath).mtimeMs > fs17.statSync(productPath).mtimeMs;
+    return fs18.statSync(sourcePath).mtimeMs > fs18.statSync(productPath).mtimeMs;
   } catch {
     return true;
   }
 }
 async function importPluginModule(specifier, baseDir, dist) {
   const isRelative = specifier.startsWith("./") || specifier.startsWith("../");
-  if (!isRelative && !path22.isAbsolute(specifier)) {
+  if (!isRelative && !path23.isAbsolute(specifier)) {
     return import(specifier);
   }
-  const distDir = dist ? path22.resolve(baseDir, dist) : null;
+  const distDir = dist ? path23.resolve(baseDir, dist) : null;
   const sourcePath = resolveLocalPluginSource(specifier, baseDir);
   const productPath = sourcePath && distDir ? mirrorProductPath(sourcePath, baseDir, distDir) : null;
-  if (productPath !== null && fs17.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
+  if (productPath !== null && fs18.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
     return import(pathToFileURL3(productPath).href);
   }
   if (sourcePath && TS_EXTS.test(sourcePath)) {
@@ -6526,13 +6806,13 @@ async function importPluginModule(specifier, baseDir, dist) {
         `Local plugin "${specifier}" has no up-to-date build artifact (dist is stale or missing). Run "faapi build" first, or use "faapi dev" for on-demand compilation.`
       );
     }
-    const relFromRoot = path22.relative(baseDir, sourcePath).replace(/\\/g, "/");
+    const relFromRoot = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
     if (relFromRoot.startsWith("src/")) {
       await ensureCompiled(sourcePath, baseDir, dist);
     } else {
       await compileProjectModules([sourcePath], baseDir, dist);
     }
-    if (productPath && fs17.existsSync(productPath)) {
+    if (productPath && fs18.existsSync(productPath)) {
       return import(pathToFileURL3(productPath).href);
     }
   }
@@ -6544,7 +6824,7 @@ async function importPluginModule(specifier, baseDir, dist) {
     `${specifier}/index.ts`,
     `${specifier}.js`,
     `${specifier}/index.js`
-  ].map((c) => path22.isAbsolute(c) ? c : path22.join(baseDir, c));
+  ].map((c) => path23.isAbsolute(c) ? c : path23.join(baseDir, c));
   throw new Error(
     `Cannot find local plugin "${specifier}" (resolved from ${baseDir}). Expected one of:
   ${candidates.join("\n  ")}
@@ -6575,8 +6855,8 @@ var ROUTES_FILE = "faapi-routes.js";
 var TOOLS_FILE2 = "faapi-tools.js";
 var AGENTS_FILE2 = "faapi-agents.js";
 async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries) {
-  const toolsPath = path23.resolve(rootDir, dist, TOOLS_FILE2);
-  if (!fs18.existsSync(toolsPath)) {
+  const toolsPath = path24.resolve(rootDir, dist, TOOLS_FILE2);
+  if (!fs19.existsSync(toolsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(toolsPath);
@@ -6585,8 +6865,8 @@ async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries
   return hydrated;
 }
 async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistries) {
-  const agentsPath = path23.resolve(rootDir, dist, AGENTS_FILE2);
-  if (!fs18.existsSync(agentsPath)) {
+  const agentsPath = path24.resolve(rootDir, dist, AGENTS_FILE2);
+  if (!fs19.existsSync(agentsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(agentsPath);
@@ -6601,8 +6881,8 @@ function getTaskDriverOptions(config) {
   return void 0;
 }
 async function loadAndHydrateTasks(rootDir, dist, registries = defaultRegistries) {
-  const tasksPath = path23.resolve(rootDir, dist, TASKS_FILE);
-  if (!fs18.existsSync(tasksPath)) {
+  const tasksPath = path24.resolve(rootDir, dist, TASKS_FILE);
+  if (!fs19.existsSync(tasksPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(tasksPath);
@@ -6659,6 +6939,7 @@ var FAAPI_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "etag",
   "bodyLimit",
   "logger",
+  "log",
   "http2",
   "trustedProxy",
   "response",
@@ -6670,13 +6951,14 @@ function isFaapiConfigKey(key) {
 async function createAppBase(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const dist = options?.dist ?? process.env.FAAPI_DIST ?? DEFAULT_DIST;
-  const routesPath = path23.resolve(rootDir, dist, ROUTES_FILE);
-  if (!fs18.existsSync(routesPath)) {
+  const routesPath = path24.resolve(rootDir, dist, ROUTES_FILE);
+  if (!fs19.existsSync(routesPath)) {
     throw new Error(
       `[faapi] ${dist}/${ROUTES_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
     );
   }
   const config = await loadConfig(rootDir, dist);
+  configureLogging(config?.log);
   const serialized = await importWithCacheBust(routesPath);
   const hydrated = await hydrateRoutes(serialized);
   let sorted = sortRoutes(hydrated.routes);
@@ -6998,21 +7280,21 @@ async function createAppBase(options) {
 }
 
 // src/cli/createDevApp.ts
-import path27 from "path";
+import path28 from "path";
 
 // src/router/scanRoutes.ts
 import fg3 from "fast-glob";
-import path24 from "path";
-import fs19 from "fs";
+import path25 from "path";
+import fs20 from "fs";
 
 // src/router/constants.ts
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 var HTTP_METHOD_SET = new Set(HTTP_METHODS);
 
 // src/utils/normalizePath.ts
-function normalizePath(path28) {
-  if (!path28) return "";
-  let result = path28.replace(/\\/g, "/");
+function normalizePath(path29) {
+  if (!path29) return "";
+  let result = path29.replace(/\\/g, "/");
   result = result.replace(/\/+/g, "/");
   result = result.replace(/\/+$/, "");
   if (result && !result.startsWith("/")) {
@@ -7073,34 +7355,34 @@ function extractExportsFromSource(source) {
   return names;
 }
 function collectMiddlewarePaths(routeFilePath, rootDir, dist) {
-  const routeDir = path24.dirname(routeFilePath);
-  const resolvedRoot = path24.resolve(rootDir);
+  const routeDir = path25.dirname(routeFilePath);
+  const resolvedRoot = path25.resolve(rootDir);
   const paths = [];
-  let currentDir = path24.resolve(rootDir, routeDir);
+  let currentDir = path25.resolve(rootDir, routeDir);
   while (true) {
     if (dist) {
-      const mwTsPath = path24.join(currentDir, "middlewares.ts");
-      const mwJsPath = path24.join(currentDir, "middlewares.js");
-      const absTsPath = path24.resolve(rootDir, mwTsPath);
-      const absJsPath = path24.resolve(rootDir, mwJsPath);
-      const absMwPath = fs19.existsSync(absTsPath) ? absTsPath : fs19.existsSync(absJsPath) ? absJsPath : null;
+      const mwTsPath = path25.join(currentDir, "middlewares.ts");
+      const mwJsPath = path25.join(currentDir, "middlewares.js");
+      const absTsPath = path25.resolve(rootDir, mwTsPath);
+      const absJsPath = path25.resolve(rootDir, mwJsPath);
+      const absMwPath = fs20.existsSync(absTsPath) ? absTsPath : fs20.existsSync(absJsPath) ? absJsPath : null;
       if (absMwPath) {
-        const relMwPath = path24.relative(rootDir, absMwPath);
-        const prodAbsPath = path24.resolve(rootDir, toProdFilePath(relMwPath, dist));
+        const relMwPath = path25.relative(rootDir, absMwPath);
+        const prodAbsPath = path25.resolve(rootDir, toProdFilePath(relMwPath, dist));
         paths.push(prodAbsPath);
       }
     } else {
       for (const ext of [".ts", ".js"]) {
-        const mwPath = path24.join(currentDir, `middlewares${ext}`);
-        const absMwPath = path24.resolve(rootDir, mwPath);
-        if (fs19.existsSync(absMwPath)) {
+        const mwPath = path25.join(currentDir, `middlewares${ext}`);
+        const absMwPath = path25.resolve(rootDir, mwPath);
+        if (fs20.existsSync(absMwPath)) {
           paths.push(absMwPath);
           break;
         }
       }
     }
     if (currentDir === resolvedRoot) break;
-    const parentDir = path24.dirname(currentDir);
+    const parentDir = path25.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
@@ -7119,7 +7401,7 @@ async function scanRoutes(rootDir, patterns, dist) {
     const normalizedFile = file.replace(/\\/g, "/");
     const fileName = normalizedFile.split("/").pop();
     if (fileName === "handler.ts" || fileName === "handler.js") {
-      const absPath = path24.resolve(rootDir, normalizedFile);
+      const absPath = path25.resolve(rootDir, normalizedFile);
       const urlPath = filePathToUrlPath(normalizedFile);
       const paramNames = extractParamNames(urlPath);
       const isDynamic = paramNames.length > 0;
@@ -7132,7 +7414,7 @@ async function scanRoutes(rootDir, patterns, dist) {
         const mwPaths = collectMiddlewarePaths(normalizedFile, rootDir);
         middlewareBundle = await loadMergedMiddlewares(mwPaths);
       }
-      const source = await fs19.promises.readFile(absPath, "utf8").catch(() => "");
+      const source = await fs20.promises.readFile(absPath, "utf8").catch(() => "");
       const exportNames = extractExportsFromSource(source);
       const methods = HTTP_METHODS.filter((m) => exportNames.has(m));
       for (const method of methods) {
@@ -7168,8 +7450,8 @@ async function scanRoutes(rootDir, patterns, dist) {
 
 // src/tools/scanTools.ts
 import fg4 from "fast-glob";
-import path25 from "path";
-import fs20 from "fs";
+import path26 from "path";
+import fs21 from "fs";
 var TOOL_PATTERNS = ["src/tools/**/*.ts"];
 var TOOL_EXPORT_RE = new RegExp(
   String.raw`export\s+(?:async\s+)?(?:function\s+|const\s+)([A-Za-z_$][\w$]*)\s*(?:\(|=)`,
@@ -7219,8 +7501,8 @@ async function scanTools(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path25.resolve(rootDir, normalizedFile);
-    const source = await fs20.promises.readFile(absPath, "utf8").catch(() => "");
+    const absPath = path26.resolve(rootDir, normalizedFile);
+    const source = await fs21.promises.readFile(absPath, "utf8").catch(() => "");
     const exportNames = extractToolExportsFromSource(source);
     const namespace = filePathToToolNamespace(normalizedFile);
     for (const fnName of exportNames) {
@@ -7244,8 +7526,8 @@ async function scanTools(rootDir, patterns) {
 
 // src/agents/scanAgents.ts
 import fg5 from "fast-glob";
-import path26 from "path";
-import fs21 from "fs";
+import path27 from "path";
+import fs22 from "fs";
 var DEFAULT_AGENT_PATTERNS = ["src/agents/**/handler.ts"];
 var RUN_EXPORT_RE = /export\s+(?:async\s+)?(?:function\s+|const\s+)run\b/;
 function extractAgentNameFromPath(filePath) {
@@ -7277,8 +7559,8 @@ async function scanAgents(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path26.resolve(rootDir, normalizedFile);
-    const source = await fs21.promises.readFile(absPath, "utf8").catch(() => "");
+    const absPath = path27.resolve(rootDir, normalizedFile);
+    const source = await fs22.promises.readFile(absPath, "utf8").catch(() => "");
     const { hasRun } = detectAgentExports(source);
     const name = extractAgentNameFromPath(normalizedFile);
     const prevFile = seen.get(name);
@@ -7348,7 +7630,7 @@ async function createDevApp(options) {
     invalidateProgramCache();
     const tasks = await scanTasks(ctx.rootDir, TASK_PATTERNS);
     for (const task of tasks) {
-      await ensureCompiled(path27.resolve(ctx.rootDir, task.filePath), ctx.rootDir, ctx.dist);
+      await ensureCompiled(path28.resolve(ctx.rootDir, task.filePath), ctx.rootDir, ctx.dist);
     }
     await generateTaskArtifacts(tasks, ctx.rootDir, ctx.dist);
     ctx.taskQueue.invalidateModules();
@@ -7375,11 +7657,13 @@ export {
   ValidationError,
   clearAgentHandleFactory,
   collectRouteSchemaSources,
+  configureLogging,
   cors,
   createProdApp as createApp,
   createAppRegistries,
   createCronScheduler,
   createDevApp,
+  createLogger,
   createProdApp,
   createProgram,
   createPrograms,