@faapi/faapi 6.7.0 → 6.9.0

package/dist/cli/index.js

@@ -649,9 +649,9 @@ var init_constants = __esm({
 });
 
 // src/utils/normalizePath.ts
-function normalizePath(path31) {
-  if (!path31) return "";
-  let result = path31.replace(/\\/g, "/");
+function normalizePath(path32) {
+  if (!path32) return "";
+  let result = path32.replace(/\\/g, "/");
   result = result.replace(/\/+/g, "/");
   result = result.replace(/\/+$/, "");
   if (result && !result.startsWith("/")) {
@@ -2260,8 +2260,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();
   }
@@ -4080,7 +4082,7 @@ var init_esm = __esm({
         this._directoryFilter = normalizeFilter(opts.directoryFilter);
         const statMethod = opts.lstat ? lstat : stat;
         if (wantBigintFsStats) {
-          this._stat = (path31) => statMethod(path31, { bigint: true });
+          this._stat = (path32) => statMethod(path32, { bigint: true });
         } else {
           this._stat = statMethod;
         }
@@ -4105,8 +4107,8 @@ var init_esm = __esm({
             const par = this.parent;
             const fil = par && par.files;
             if (fil && fil.length > 0) {
-              const { path: path31, depth } = par;
-              const slice = fil.splice(0, batch).map((dirent) => this._formatEntry(dirent, path31));
+              const { path: path32, depth } = par;
+              const slice = fil.splice(0, batch).map((dirent) => this._formatEntry(dirent, path32));
               const awaited = await Promise.all(slice);
               for (const entry of awaited) {
                 if (!entry)
@@ -4146,20 +4148,20 @@ var init_esm = __esm({
           this.reading = false;
         }
       }
-      async _exploreDir(path31, depth) {
+      async _exploreDir(path32, depth) {
         let files;
         try {
-          files = await readdir(path31, this._rdOptions);
+          files = await readdir(path32, this._rdOptions);
         } catch (error) {
           this._onError(error);
         }
-        return { files, depth, path: path31 };
+        return { files, depth, path: path32 };
       }
-      async _formatEntry(dirent, path31) {
+      async _formatEntry(dirent, path32) {
         let entry;
         const basename3 = this._isDirent ? dirent.name : dirent;
         try {
-          const fullPath = presolve(pjoin(path31, basename3));
+          const fullPath = presolve(pjoin(path32, basename3));
           entry = { path: prelative(this._root, fullPath), fullPath, basename: basename3 };
           entry[this._statsProp] = this._isDirent ? dirent : await this._stat(fullPath);
         } catch (err) {
@@ -4220,16 +4222,16 @@ import { watchFile, unwatchFile, watch as fs_watch } from "fs";
 import { open, stat as stat2, lstat as lstat2, realpath as fsrealpath } from "fs/promises";
 import * as sysPath from "path";
 import { type as osType } from "os";
-function createFsWatchInstance(path31, options, listener, errHandler, emitRaw) {
+function createFsWatchInstance(path32, options, listener, errHandler, emitRaw) {
   const handleEvent = (rawEvent, evPath) => {
-    listener(path31);
-    emitRaw(rawEvent, evPath, { watchedPath: path31 });
-    if (evPath && path31 !== evPath) {
-      fsWatchBroadcast(sysPath.resolve(path31, evPath), KEY_LISTENERS, sysPath.join(path31, evPath));
+    listener(path32);
+    emitRaw(rawEvent, evPath, { watchedPath: path32 });
+    if (evPath && path32 !== evPath) {
+      fsWatchBroadcast(sysPath.resolve(path32, evPath), KEY_LISTENERS, sysPath.join(path32, evPath));
     }
   };
   try {
-    return fs_watch(path31, {
+    return fs_watch(path32, {
       persistent: options.persistent
     }, handleEvent);
   } catch (error) {
@@ -4574,12 +4576,12 @@ var init_handler = __esm({
         listener(val1, val2, val3);
       });
     };
-    setFsWatchListener = (path31, fullPath, options, handlers) => {
+    setFsWatchListener = (path32, fullPath, options, handlers) => {
       const { listener, errHandler, rawEmitter } = handlers;
       let cont = FsWatchInstances.get(fullPath);
       let watcher;
       if (!options.persistent) {
-        watcher = createFsWatchInstance(path31, options, listener, errHandler, rawEmitter);
+        watcher = createFsWatchInstance(path32, options, listener, errHandler, rawEmitter);
         if (!watcher)
           return;
         return watcher.close.bind(watcher);
@@ -4590,7 +4592,7 @@ var init_handler = __esm({
         addAndConvert(cont, KEY_RAW, rawEmitter);
       } else {
         watcher = createFsWatchInstance(
-          path31,
+          path32,
           options,
           fsWatchBroadcast.bind(null, fullPath, KEY_LISTENERS),
           errHandler,
@@ -4605,7 +4607,7 @@ var init_handler = __esm({
             cont.watcherUnusable = true;
           if (isWindows && error.code === "EPERM") {
             try {
-              const fd = await open(path31, "r");
+              const fd = await open(path32, "r");
               await fd.close();
               broadcastErr(error);
             } catch (err) {
@@ -4636,7 +4638,7 @@ var init_handler = __esm({
       };
     };
     FsWatchFileInstances = /* @__PURE__ */ new Map();
-    setFsWatchFileListener = (path31, fullPath, options, handlers) => {
+    setFsWatchFileListener = (path32, fullPath, options, handlers) => {
       const { listener, rawEmitter } = handlers;
       let cont = FsWatchFileInstances.get(fullPath);
       const copts = cont && cont.options;
@@ -4658,7 +4660,7 @@ var init_handler = __esm({
             });
             const currmtime = curr.mtimeMs;
             if (curr.size !== prev.size || currmtime > prev.mtimeMs || currmtime === 0) {
-              foreach(cont.listeners, (listener2) => listener2(path31, curr));
+              foreach(cont.listeners, (listener2) => listener2(path32, curr));
             }
           })
         };
@@ -4686,13 +4688,13 @@ var init_handler = __esm({
        * @param listener on fs change
        * @returns closer for the watcher instance
        */
-      _watchWithNodeFs(path31, listener) {
+      _watchWithNodeFs(path32, listener) {
         const opts = this.fsw.options;
-        const directory = sysPath.dirname(path31);
-        const basename3 = sysPath.basename(path31);
+        const directory = sysPath.dirname(path32);
+        const basename3 = sysPath.basename(path32);
         const parent = this.fsw._getWatchedDir(directory);
         parent.add(basename3);
-        const absolutePath = sysPath.resolve(path31);
+        const absolutePath = sysPath.resolve(path32);
         const options = {
           persistent: opts.persistent
         };
@@ -4702,12 +4704,12 @@ var init_handler = __esm({
         if (opts.usePolling) {
           const enableBin = opts.interval !== opts.binaryInterval;
           options.interval = enableBin && isBinaryPath(basename3) ? opts.binaryInterval : opts.interval;
-          closer = setFsWatchFileListener(path31, absolutePath, options, {
+          closer = setFsWatchFileListener(path32, absolutePath, options, {
             listener,
             rawEmitter: this.fsw._emitRaw
           });
         } else {
-          closer = setFsWatchListener(path31, absolutePath, options, {
+          closer = setFsWatchListener(path32, absolutePath, options, {
             listener,
             errHandler: this._boundHandleError,
             rawEmitter: this.fsw._emitRaw
@@ -4729,7 +4731,7 @@ var init_handler = __esm({
         let prevStats = stats;
         if (parent.has(basename3))
           return;
-        const listener = async (path31, newStats) => {
+        const listener = async (path32, newStats) => {
           if (!this.fsw._throttle(THROTTLE_MODE_WATCH, file, 5))
             return;
           if (!newStats || newStats.mtimeMs === 0) {
@@ -4743,11 +4745,11 @@ var init_handler = __esm({
                 this.fsw._emit(EV.CHANGE, file, newStats2);
               }
               if ((isMacos || isLinux || isFreeBSD) && prevStats.ino !== newStats2.ino) {
-                this.fsw._closeFile(path31);
+                this.fsw._closeFile(path32);
                 prevStats = newStats2;
                 const closer2 = this._watchWithNodeFs(file, listener);
                 if (closer2)
-                  this.fsw._addPathCloser(path31, closer2);
+                  this.fsw._addPathCloser(path32, closer2);
               } else {
                 prevStats = newStats2;
               }
@@ -4779,7 +4781,7 @@ var init_handler = __esm({
        * @param item basename of this item
        * @returns true if no more processing is needed for this entry.
        */
-      async _handleSymlink(entry, directory, path31, item) {
+      async _handleSymlink(entry, directory, path32, item) {
         if (this.fsw.closed) {
           return;
         }
@@ -4789,7 +4791,7 @@ var init_handler = __esm({
           this.fsw._incrReadyCount();
           let linkPath;
           try {
-            linkPath = await fsrealpath(path31);
+            linkPath = await fsrealpath(path32);
           } catch (e) {
             this.fsw._emitReady();
             return true;
@@ -4799,12 +4801,12 @@ var init_handler = __esm({
           if (dir.has(item)) {
             if (this.fsw._symlinkPaths.get(full) !== linkPath) {
               this.fsw._symlinkPaths.set(full, linkPath);
-              this.fsw._emit(EV.CHANGE, path31, entry.stats);
+              this.fsw._emit(EV.CHANGE, path32, entry.stats);
             }
           } else {
             dir.add(item);
             this.fsw._symlinkPaths.set(full, linkPath);
-            this.fsw._emit(EV.ADD, path31, entry.stats);
+            this.fsw._emit(EV.ADD, path32, entry.stats);
           }
           this.fsw._emitReady();
           return true;
@@ -4833,9 +4835,9 @@ var init_handler = __esm({
             return;
           }
           const item = entry.path;
-          let path31 = sysPath.join(directory, item);
+          let path32 = sysPath.join(directory, item);
           current.add(item);
-          if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path31, item)) {
+          if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path32, item)) {
             return;
           }
           if (this.fsw.closed) {
@@ -4844,8 +4846,8 @@ var init_handler = __esm({
           }
           if (item === target || !target && !previous.has(item)) {
             this.fsw._incrReadyCount();
-            path31 = sysPath.join(dir, sysPath.relative(dir, path31));
-            this._addToNodeFs(path31, initialAdd, wh, depth + 1);
+            path32 = sysPath.join(dir, sysPath.relative(dir, path32));
+            this._addToNodeFs(path32, initialAdd, wh, depth + 1);
           }
         }).on(EV.ERROR, this._boundHandleError);
         return new Promise((resolve3, reject) => {
@@ -4914,13 +4916,13 @@ var init_handler = __esm({
        * @param depth Child path actually targeted for watch
        * @param target Child path actually targeted for watch
        */
-      async _addToNodeFs(path31, initialAdd, priorWh, depth, target) {
+      async _addToNodeFs(path32, initialAdd, priorWh, depth, target) {
         const ready = this.fsw._emitReady;
-        if (this.fsw._isIgnored(path31) || this.fsw.closed) {
+        if (this.fsw._isIgnored(path32) || this.fsw.closed) {
           ready();
           return false;
         }
-        const wh = this.fsw._getWatchHelpers(path31);
+        const wh = this.fsw._getWatchHelpers(path32);
         if (priorWh) {
           wh.filterPath = (entry) => priorWh.filterPath(entry);
           wh.filterDir = (entry) => priorWh.filterDir(entry);
@@ -4936,8 +4938,8 @@ var init_handler = __esm({
           const follow = this.fsw.options.followSymlinks;
           let closer;
           if (stats.isDirectory()) {
-            const absPath = sysPath.resolve(path31);
-            const targetPath = follow ? await fsrealpath(path31) : path31;
+            const absPath = sysPath.resolve(path32);
+            const targetPath = follow ? await fsrealpath(path32) : path32;
             if (this.fsw.closed)
               return;
             closer = await this._handleDir(wh.watchPath, stats, initialAdd, depth, target, wh, targetPath);
@@ -4947,29 +4949,29 @@ var init_handler = __esm({
               this.fsw._symlinkPaths.set(absPath, targetPath);
             }
           } else if (stats.isSymbolicLink()) {
-            const targetPath = follow ? await fsrealpath(path31) : path31;
+            const targetPath = follow ? await fsrealpath(path32) : path32;
             if (this.fsw.closed)
               return;
             const parent = sysPath.dirname(wh.watchPath);
             this.fsw._getWatchedDir(parent).add(wh.watchPath);
             this.fsw._emit(EV.ADD, wh.watchPath, stats);
-            closer = await this._handleDir(parent, stats, initialAdd, depth, path31, wh, targetPath);
+            closer = await this._handleDir(parent, stats, initialAdd, depth, path32, wh, targetPath);
             if (this.fsw.closed)
               return;
             if (targetPath !== void 0) {
-              this.fsw._symlinkPaths.set(sysPath.resolve(path31), targetPath);
+              this.fsw._symlinkPaths.set(sysPath.resolve(path32), targetPath);
             }
           } else {
             closer = this._handleFile(wh.watchPath, stats, initialAdd);
           }
           ready();
           if (closer)
-            this.fsw._addPathCloser(path31, closer);
+            this.fsw._addPathCloser(path32, closer);
           return false;
         } catch (error) {
           if (this.fsw._handleError(error)) {
             ready();
-            return path31;
+            return path32;
           }
         }
       }
@@ -5008,26 +5010,26 @@ function createPattern(matcher) {
   }
   return () => false;
 }
-function normalizePath2(path31) {
-  if (typeof path31 !== "string")
+function normalizePath2(path32) {
+  if (typeof path32 !== "string")
     throw new Error("string expected");
-  path31 = sysPath2.normalize(path31);
-  path31 = path31.replace(/\\/g, "/");
+  path32 = sysPath2.normalize(path32);
+  path32 = path32.replace(/\\/g, "/");
   let prepend = false;
-  if (path31.startsWith("//"))
+  if (path32.startsWith("//"))
     prepend = true;
   const DOUBLE_SLASH_RE2 = /\/\//;
-  while (path31.match(DOUBLE_SLASH_RE2))
-    path31 = path31.replace(DOUBLE_SLASH_RE2, "/");
+  while (path32.match(DOUBLE_SLASH_RE2))
+    path32 = path32.replace(DOUBLE_SLASH_RE2, "/");
   if (prepend)
-    path31 = "/" + path31;
-  return path31;
+    path32 = "/" + path32;
+  return path32;
 }
 function matchPatterns(patterns, testString, stats) {
-  const path31 = normalizePath2(testString);
+  const path32 = normalizePath2(testString);
   for (let index = 0; index < patterns.length; index++) {
     const pattern = patterns[index];
-    if (pattern(path31, stats)) {
+    if (pattern(path32, stats)) {
       return true;
     }
   }
@@ -5088,19 +5090,19 @@ var init_esm2 = __esm({
       }
       return str;
     };
-    normalizePathToUnix = (path31) => toUnix(sysPath2.normalize(toUnix(path31)));
-    normalizeIgnored = (cwd = "") => (path31) => {
-      if (typeof path31 === "string") {
-        return normalizePathToUnix(sysPath2.isAbsolute(path31) ? path31 : sysPath2.join(cwd, path31));
+    normalizePathToUnix = (path32) => toUnix(sysPath2.normalize(toUnix(path32)));
+    normalizeIgnored = (cwd = "") => (path32) => {
+      if (typeof path32 === "string") {
+        return normalizePathToUnix(sysPath2.isAbsolute(path32) ? path32 : sysPath2.join(cwd, path32));
       } else {
-        return path31;
+        return path32;
       }
     };
-    getAbsolutePath = (path31, cwd) => {
-      if (sysPath2.isAbsolute(path31)) {
-        return path31;
+    getAbsolutePath = (path32, cwd) => {
+      if (sysPath2.isAbsolute(path32)) {
+        return path32;
       }
-      return sysPath2.join(cwd, path31);
+      return sysPath2.join(cwd, path32);
     };
     EMPTY_SET = Object.freeze(/* @__PURE__ */ new Set());
     DirEntry = class {
@@ -5155,10 +5157,10 @@ var init_esm2 = __esm({
     STAT_METHOD_F = "stat";
     STAT_METHOD_L = "lstat";
     WatchHelper = class {
-      constructor(path31, follow, fsw) {
+      constructor(path32, follow, fsw) {
         this.fsw = fsw;
-        const watchPath = path31;
-        this.path = path31 = path31.replace(REPLACER_RE, "");
+        const watchPath = path32;
+        this.path = path32 = path32.replace(REPLACER_RE, "");
         this.watchPath = watchPath;
         this.fullWatchPath = sysPath2.resolve(watchPath);
         this.dirParts = [];
@@ -5280,20 +5282,20 @@ var init_esm2 = __esm({
         this._closePromise = void 0;
         let paths = unifyPaths(paths_);
         if (cwd) {
-          paths = paths.map((path31) => {
-            const absPath = getAbsolutePath(path31, cwd);
+          paths = paths.map((path32) => {
+            const absPath = getAbsolutePath(path32, cwd);
             return absPath;
           });
         }
-        paths.forEach((path31) => {
-          this._removeIgnoredPath(path31);
+        paths.forEach((path32) => {
+          this._removeIgnoredPath(path32);
         });
         this._userIgnored = void 0;
         if (!this._readyCount)
           this._readyCount = 0;
         this._readyCount += paths.length;
-        Promise.all(paths.map(async (path31) => {
-          const res = await this._nodeFsHandler._addToNodeFs(path31, !_internal, void 0, 0, _origAdd);
+        Promise.all(paths.map(async (path32) => {
+          const res = await this._nodeFsHandler._addToNodeFs(path32, !_internal, void 0, 0, _origAdd);
           if (res)
             this._emitReady();
           return res;
@@ -5315,17 +5317,17 @@ var init_esm2 = __esm({
           return this;
         const paths = unifyPaths(paths_);
         const { cwd } = this.options;
-        paths.forEach((path31) => {
-          if (!sysPath2.isAbsolute(path31) && !this._closers.has(path31)) {
+        paths.forEach((path32) => {
+          if (!sysPath2.isAbsolute(path32) && !this._closers.has(path32)) {
             if (cwd)
-              path31 = sysPath2.join(cwd, path31);
-            path31 = sysPath2.resolve(path31);
+              path32 = sysPath2.join(cwd, path32);
+            path32 = sysPath2.resolve(path32);
           }
-          this._closePath(path31);
-          this._addIgnoredPath(path31);
-          if (this._watched.has(path31)) {
+          this._closePath(path32);
+          this._addIgnoredPath(path32);
+          if (this._watched.has(path32)) {
             this._addIgnoredPath({
-              path: path31,
+              path: path32,
               recursive: true
             });
           }
@@ -5389,38 +5391,38 @@ var init_esm2 = __esm({
        * @param stats arguments to be passed with event
        * @returns the error if defined, otherwise the value of the FSWatcher instance's `closed` flag
        */
-      async _emit(event, path31, stats) {
+      async _emit(event, path32, stats) {
         if (this.closed)
           return;
         const opts = this.options;
         if (isWindows)
-          path31 = sysPath2.normalize(path31);
+          path32 = sysPath2.normalize(path32);
         if (opts.cwd)
-          path31 = sysPath2.relative(opts.cwd, path31);
-        const args = [path31];
+          path32 = sysPath2.relative(opts.cwd, path32);
+        const args = [path32];
         if (stats != null)
           args.push(stats);
         const awf = opts.awaitWriteFinish;
         let pw;
-        if (awf && (pw = this._pendingWrites.get(path31))) {
+        if (awf && (pw = this._pendingWrites.get(path32))) {
           pw.lastChange = /* @__PURE__ */ new Date();
           return this;
         }
         if (opts.atomic) {
           if (event === EVENTS.UNLINK) {
-            this._pendingUnlinks.set(path31, [event, ...args]);
+            this._pendingUnlinks.set(path32, [event, ...args]);
             setTimeout(() => {
-              this._pendingUnlinks.forEach((entry, path32) => {
+              this._pendingUnlinks.forEach((entry, path33) => {
                 this.emit(...entry);
                 this.emit(EVENTS.ALL, ...entry);
-                this._pendingUnlinks.delete(path32);
+                this._pendingUnlinks.delete(path33);
               });
             }, typeof opts.atomic === "number" ? opts.atomic : 100);
             return this;
           }
-          if (event === EVENTS.ADD && this._pendingUnlinks.has(path31)) {
+          if (event === EVENTS.ADD && this._pendingUnlinks.has(path32)) {
             event = EVENTS.CHANGE;
-            this._pendingUnlinks.delete(path31);
+            this._pendingUnlinks.delete(path32);
           }
         }
         if (awf && (event === EVENTS.ADD || event === EVENTS.CHANGE) && this._readyEmitted) {
@@ -5438,16 +5440,16 @@ var init_esm2 = __esm({
               this.emitWithAll(event, args);
             }
           };
-          this._awaitWriteFinish(path31, awf.stabilityThreshold, event, awfEmit);
+          this._awaitWriteFinish(path32, awf.stabilityThreshold, event, awfEmit);
           return this;
         }
         if (event === EVENTS.CHANGE) {
-          const isThrottled = !this._throttle(EVENTS.CHANGE, path31, 50);
+          const isThrottled = !this._throttle(EVENTS.CHANGE, path32, 50);
           if (isThrottled)
             return this;
         }
         if (opts.alwaysStat && stats === void 0 && (event === EVENTS.ADD || event === EVENTS.ADD_DIR || event === EVENTS.CHANGE)) {
-          const fullPath = opts.cwd ? sysPath2.join(opts.cwd, path31) : path31;
+          const fullPath = opts.cwd ? sysPath2.join(opts.cwd, path32) : path32;
           let stats2;
           try {
             stats2 = await stat3(fullPath);
@@ -5478,23 +5480,23 @@ var init_esm2 = __esm({
        * @param timeout duration of time to suppress duplicate actions
        * @returns tracking object or false if action should be suppressed
        */
-      _throttle(actionType, path31, timeout) {
+      _throttle(actionType, path32, timeout) {
         if (!this._throttled.has(actionType)) {
           this._throttled.set(actionType, /* @__PURE__ */ new Map());
         }
         const action = this._throttled.get(actionType);
         if (!action)
           throw new Error("invalid throttle");
-        const actionPath = action.get(path31);
+        const actionPath = action.get(path32);
         if (actionPath) {
           actionPath.count++;
           return false;
         }
         let timeoutObject;
         const clear = () => {
-          const item = action.get(path31);
+          const item = action.get(path32);
           const count = item ? item.count : 0;
-          action.delete(path31);
+          action.delete(path32);
           clearTimeout(timeoutObject);
           if (item)
             clearTimeout(item.timeoutObject);
@@ -5502,7 +5504,7 @@ var init_esm2 = __esm({
         };
         timeoutObject = setTimeout(clear, timeout);
         const thr = { timeoutObject, clear, count: 0 };
-        action.set(path31, thr);
+        action.set(path32, thr);
         return thr;
       }
       _incrReadyCount() {
@@ -5516,44 +5518,44 @@ var init_esm2 = __esm({
        * @param event
        * @param awfEmit Callback to be called when ready for event to be emitted.
        */
-      _awaitWriteFinish(path31, threshold, event, awfEmit) {
+      _awaitWriteFinish(path32, threshold, event, awfEmit) {
         const awf = this.options.awaitWriteFinish;
         if (typeof awf !== "object")
           return;
         const pollInterval = awf.pollInterval;
         let timeoutHandler;
-        let fullPath = path31;
-        if (this.options.cwd && !sysPath2.isAbsolute(path31)) {
-          fullPath = sysPath2.join(this.options.cwd, path31);
+        let fullPath = path32;
+        if (this.options.cwd && !sysPath2.isAbsolute(path32)) {
+          fullPath = sysPath2.join(this.options.cwd, path32);
         }
         const now = /* @__PURE__ */ new Date();
         const writes = this._pendingWrites;
         function awaitWriteFinishFn(prevStat) {
           statcb(fullPath, (err, curStat) => {
-            if (err || !writes.has(path31)) {
+            if (err || !writes.has(path32)) {
               if (err && err.code !== "ENOENT")
                 awfEmit(err);
               return;
             }
             const now2 = Number(/* @__PURE__ */ new Date());
             if (prevStat && curStat.size !== prevStat.size) {
-              writes.get(path31).lastChange = now2;
+              writes.get(path32).lastChange = now2;
             }
-            const pw = writes.get(path31);
+            const pw = writes.get(path32);
             const df = now2 - pw.lastChange;
             if (df >= threshold) {
-              writes.delete(path31);
+              writes.delete(path32);
               awfEmit(void 0, curStat);
             } else {
               timeoutHandler = setTimeout(awaitWriteFinishFn, pollInterval, curStat);
             }
           });
         }
-        if (!writes.has(path31)) {
-          writes.set(path31, {
+        if (!writes.has(path32)) {
+          writes.set(path32, {
             lastChange: now,
             cancelWait: () => {
-              writes.delete(path31);
+              writes.delete(path32);
               clearTimeout(timeoutHandler);
               return event;
             }
@@ -5564,8 +5566,8 @@ var init_esm2 = __esm({
       /**
        * Determines whether user has asked to ignore this path.
        */
-      _isIgnored(path31, stats) {
-        if (this.options.atomic && DOT_RE.test(path31))
+      _isIgnored(path32, stats) {
+        if (this.options.atomic && DOT_RE.test(path32))
           return true;
         if (!this._userIgnored) {
           const { cwd } = this.options;
@@ -5575,17 +5577,17 @@ var init_esm2 = __esm({
           const list = [...ignoredPaths.map(normalizeIgnored(cwd)), ...ignored];
           this._userIgnored = anymatch(list, void 0);
         }
-        return this._userIgnored(path31, stats);
+        return this._userIgnored(path32, stats);
       }
-      _isntIgnored(path31, stat4) {
-        return !this._isIgnored(path31, stat4);
+      _isntIgnored(path32, stat4) {
+        return !this._isIgnored(path32, stat4);
       }
       /**
        * Provides a set of common helpers and properties relating to symlink handling.
        * @param path file or directory pattern being watched
        */
-      _getWatchHelpers(path31) {
-        return new WatchHelper(path31, this.options.followSymlinks, this);
+      _getWatchHelpers(path32) {
+        return new WatchHelper(path32, this.options.followSymlinks, this);
       }
       // Directory helpers
       // -----------------
@@ -5617,63 +5619,63 @@ var init_esm2 = __esm({
        * @param item      base path of item/directory
        */
       _remove(directory, item, isDirectory) {
-        const path31 = sysPath2.join(directory, item);
-        const fullPath = sysPath2.resolve(path31);
-        isDirectory = isDirectory != null ? isDirectory : this._watched.has(path31) || this._watched.has(fullPath);
-        if (!this._throttle("remove", path31, 100))
+        const path32 = sysPath2.join(directory, item);
+        const fullPath = sysPath2.resolve(path32);
+        isDirectory = isDirectory != null ? isDirectory : this._watched.has(path32) || this._watched.has(fullPath);
+        if (!this._throttle("remove", path32, 100))
           return;
         if (!isDirectory && this._watched.size === 1) {
           this.add(directory, item, true);
         }
-        const wp = this._getWatchedDir(path31);
+        const wp = this._getWatchedDir(path32);
         const nestedDirectoryChildren = wp.getChildren();
-        nestedDirectoryChildren.forEach((nested) => this._remove(path31, nested));
+        nestedDirectoryChildren.forEach((nested) => this._remove(path32, nested));
         const parent = this._getWatchedDir(directory);
         const wasTracked = parent.has(item);
         parent.remove(item);
         if (this._symlinkPaths.has(fullPath)) {
           this._symlinkPaths.delete(fullPath);
         }
-        let relPath = path31;
+        let relPath = path32;
         if (this.options.cwd)
-          relPath = sysPath2.relative(this.options.cwd, path31);
+          relPath = sysPath2.relative(this.options.cwd, path32);
         if (this.options.awaitWriteFinish && this._pendingWrites.has(relPath)) {
           const event = this._pendingWrites.get(relPath).cancelWait();
           if (event === EVENTS.ADD)
             return;
         }
-        this._watched.delete(path31);
+        this._watched.delete(path32);
         this._watched.delete(fullPath);
         const eventName = isDirectory ? EVENTS.UNLINK_DIR : EVENTS.UNLINK;
-        if (wasTracked && !this._isIgnored(path31))
-          this._emit(eventName, path31);
-        this._closePath(path31);
+        if (wasTracked && !this._isIgnored(path32))
+          this._emit(eventName, path32);
+        this._closePath(path32);
       }
       /**
        * Closes all watchers for a path
        */
-      _closePath(path31) {
-        this._closeFile(path31);
-        const dir = sysPath2.dirname(path31);
-        this._getWatchedDir(dir).remove(sysPath2.basename(path31));
+      _closePath(path32) {
+        this._closeFile(path32);
+        const dir = sysPath2.dirname(path32);
+        this._getWatchedDir(dir).remove(sysPath2.basename(path32));
       }
       /**
        * Closes only file-specific watchers
        */
-      _closeFile(path31) {
-        const closers = this._closers.get(path31);
+      _closeFile(path32) {
+        const closers = this._closers.get(path32);
         if (!closers)
           return;
         closers.forEach((closer) => closer());
-        this._closers.delete(path31);
+        this._closers.delete(path32);
       }
-      _addPathCloser(path31, closer) {
+      _addPathCloser(path32, closer) {
         if (!closer)
           return;
-        let list = this._closers.get(path31);
+        let list = this._closers.get(path32);
         if (!list) {
           list = [];
-          this._closers.set(path31, list);
+          this._closers.set(path32, list);
         }
         list.push(closer);
       }
@@ -5918,18 +5920,18 @@ function getWsIndex(routes) {
   wsIndexCache.set(routes, index);
   return index;
 }
-function matchRoute(routes, method, path31) {
+function matchRoute(routes, method, path32) {
   const index = getHttpIndex(routes);
   const upper = method.toUpperCase();
-  const hit = matchByMethod(index, upper, path31);
+  const hit = matchByMethod(index, upper, path32);
   if (hit) return hit;
   if (upper === "HEAD") {
-    return matchByMethod(index, "GET", path31);
+    return matchByMethod(index, "GET", path32);
   }
   return null;
 }
-function matchByMethod(index, method, path31) {
-  const staticHit = index.static.get(`${method}|${path31}`);
+function matchByMethod(index, method, path32) {
+  const staticHit = index.static.get(`${method}|${path32}`);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
@@ -5938,31 +5940,31 @@ function matchByMethod(index, method, path31) {
     if (route.method !== method) {
       continue;
     }
-    const params = matchSegments(entry.segments, path31, route.paramNames, route.isCatchAll);
+    const params = matchSegments(entry.segments, path32, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function matchWsRoute(wsRoutes, path31) {
+function matchWsRoute(wsRoutes, path32) {
   const index = getWsIndex(wsRoutes);
-  const staticHit = index.static.get(path31);
+  const staticHit = index.static.get(path32);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
   for (const route of index.dynamics) {
-    const params = matchDynamicPath(route.urlPath, path31, route.paramNames, route.isCatchAll);
+    const params = matchDynamicPath(route.urlPath, path32, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function findAllowedMethods(routes, path31) {
+function findAllowedMethods(routes, path32) {
   const index = getHttpIndex(routes);
   const methods = /* @__PURE__ */ new Set();
-  const staticMethods = index.methodsByStaticPath.get(path31);
+  const staticMethods = index.methodsByStaticPath.get(path32);
   if (staticMethods) {
     for (const method of staticMethods) {
       methods.add(method);
@@ -5971,7 +5973,7 @@ function findAllowedMethods(routes, path31) {
   for (const entry of index.dynamics) {
     const params = matchSegments(
       entry.segments,
-      path31,
+      path32,
       entry.route.paramNames,
       entry.route.isCatchAll
     );
@@ -5984,11 +5986,11 @@ function findAllowedMethods(routes, path31) {
   }
   return Array.from(methods);
 }
-function matchDynamicPath(pattern, path31, paramNames, isCatchAll) {
-  return matchSegments(pattern.split("/").filter(Boolean), path31, paramNames, isCatchAll);
+function matchDynamicPath(pattern, path32, paramNames, isCatchAll) {
+  return matchSegments(pattern.split("/").filter(Boolean), path32, paramNames, isCatchAll);
 }
-function matchSegments(patternSegments, path31, paramNames, isCatchAll) {
-  const pathSegments = path31.split("/").filter(Boolean);
+function matchSegments(patternSegments, path32, paramNames, isCatchAll) {
+  const pathSegments = path32.split("/").filter(Boolean);
   if (isCatchAll) {
     const nonCatchAllCount = patternSegments.length - 1;
     if (pathSegments.length <= nonCatchAllCount) {
@@ -6261,14 +6263,14 @@ var init_httpErrors = __esm({
       issues;
     };
     RouteNotFoundError = class extends FaapiError {
-      constructor(path31) {
-        super("ROUTE_NOT_FOUND", `Route not found: ${path31}`, 404);
+      constructor(path32) {
+        super("ROUTE_NOT_FOUND", `Route not found: ${path32}`, 404);
         this.name = "RouteNotFoundError";
       }
     };
     MethodNotAllowedError = class extends FaapiError {
-      constructor(method, path31, allowedMethods) {
-        super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path31}`, 405);
+      constructor(method, path32, allowedMethods) {
+        super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path32}`, 405);
         this.allowedMethods = allowedMethods;
         this.name = "MethodNotAllowedError";
       }
@@ -6386,7 +6388,228 @@ var init_responseFormatter = __esm({
   }
 });
 
+// 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;
+}
+var init_formatEntry = __esm({
+  "src/logger/formatEntry.ts"() {
+    "use strict";
+  }
+});
+
+// src/logger/fileSink.ts
+import fs17 from "fs";
+import path23 from "path";
+function createFileLogSink(options) {
+  fs17.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 = fs17.createWriteStream(path23.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((resolve3) => {
+    if (pendingCount === 0) {
+      resolve3();
+      return;
+    }
+    drainWaiters.push(resolve3);
+  });
+  const close = () => Promise.all(
+    [...streams.values()].map(
+      (stream) => new Promise((resolve3) => {
+        stream.end(() => resolve3());
+      })
+    )
+  ).then(() => {
+    streams.clear();
+  });
+  return { write, flush, close };
+}
+var LEVEL_FILES;
+var init_fileSink = __esm({
+  "src/logger/fileSink.ts"() {
+    "use strict";
+    init_formatEntry();
+    LEVEL_FILES = ["debug", "info", "warn", "error"];
+  }
+});
+
+// src/logger/logger.ts
+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(", ")}.`
+    );
+  }
+}
+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();
+}
+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);
+}
+var LEVEL_RANK, VALID_LEVELS, globalState, consoleSink, CONSOLE_METHOD;
+var init_logger = __esm({
+  "src/logger/logger.ts"() {
+    "use strict";
+    init_formatEntry();
+    init_fileSink();
+    LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+    VALID_LEVELS = ["debug", "info", "warn", "error"];
+    globalState = { level: null, sink: null, fileSink: null, stdout: true, accessLog: false, disabled: false };
+    consoleSink = (entry) => {
+      console[CONSOLE_METHOD[entry.level]](formatEntry(entry));
+    };
+    CONSOLE_METHOD = {
+      debug: "debug",
+      info: "info",
+      warn: "warn",
+      error: "error"
+    };
+  }
+});
+
 // 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;
@@ -6420,7 +6643,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,
@@ -6525,6 +6754,7 @@ var init_createContext = __esm({
     "use strict";
     init_sse();
     init_responseFormatter();
+    init_logger();
   }
 });
 
@@ -7092,6 +7322,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;
   }
@@ -7308,9 +7541,9 @@ async function validateInput(schemaPath, method, inputType, input) {
 function mapZodIssues(error) {
   return error.issues.map((issue) => {
     const code = mapZodCode(issue);
-    const path31 = issue.path.map(String).join(".") || "";
+    const path32 = issue.path.map(String).join(".") || "";
     return {
-      path: path31,
+      path: path32,
       code,
       expected: issue.expected ?? mapExpectedFromMessage(issue.message),
       received: issue.received ?? mapReceivedFromMessage(issue.message),
@@ -7708,14 +7941,34 @@ var init_etag = __esm({
 });
 
 // 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,
@@ -7728,6 +7981,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,
@@ -7739,9 +7993,10 @@ function logger(options = {}) {
     }
   };
 }
-var init_logger = __esm({
+var init_logger2 = __esm({
   "src/middleware/logger.ts"() {
     "use strict";
+    init_logger();
   }
 });
 
@@ -7808,9 +8063,9 @@ var init_wsHandler = __esm({
 });
 
 // src/server/handleWsUpgrade.ts
-import fs17 from "fs";
+import fs18 from "fs";
 import { WebSocketServer, WebSocket } from "ws";
-import path23 from "path";
+import path24 from "path";
 function getPathname(req) {
   const url = req.url ?? "/";
   const idx = url.indexOf("?");
@@ -7821,7 +8076,7 @@ async function loadWsHandler(filePath, ctx, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs17.existsSync(sourcePath)) {
+      if (sourcePath && fs18.existsSync(sourcePath)) {
         await ensureCompiled(sourcePath, rootDir, dist);
       }
     }
@@ -7935,7 +8190,7 @@ function attachWebSocket(options) {
     const finalHandler = async () => {
       let handlers;
       try {
-        const absoluteFilePath = path23.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path24.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx, rootDir);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -8011,7 +8266,7 @@ import {
 import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable3 } from "stream";
-import path24 from "path";
+import path25 from "path";
 function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT, requestSignal) {
   const forwardedProto = req.headers["x-forwarded-proto"];
   const protocol = Array.isArray(forwardedProto) ? forwardedProto[0]?.split(",")[0]?.trim() ?? "http" : forwardedProto?.split(",")[0]?.trim() ?? "http";
@@ -8207,7 +8462,7 @@ function getRoutePaths(route, rootDir, dist) {
   let cached = routePathCache.get(route);
   if (!cached) {
     cached = {
-      absFilePath: path24.resolve(rootDir, route.filePath),
+      absFilePath: path25.resolve(rootDir, route.filePath),
       schemaPath: getRuntimeSchemaPath(route.filePath, dist, rootDir)
     };
     routePathCache.set(route, cached);
@@ -8317,7 +8572,7 @@ var init_createServer = __esm({
     init_helmet();
     init_compression();
     init_etag();
-    init_logger();
+    init_logger2();
     init_handleWsUpgrade();
     init_serverUtils();
     init_generateSchemaFiles();
@@ -8386,6 +8641,8 @@ ${BUILD_VIEW_SOURCE}
 
 ${SERIALIZE_ERROR_SOURCE}
 
+${BUILD_LOGGER_SOURCE}
+
 const run = mod.run;
 if (typeof run !== 'function') {
   parentPort.postMessage({
@@ -8405,7 +8662,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);
@@ -8513,6 +8771,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);
         }
       }
     );
@@ -8536,7 +8796,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(
@@ -8547,7 +8808,7 @@ async function runTaskInWorker(options) {
     }
   });
 }
-var KILL_GRACE_MS, TaskCancelledError, BUILD_VIEW_SOURCE, SERIALIZE_ERROR_SOURCE;
+var KILL_GRACE_MS, TaskCancelledError, BUILD_VIEW_SOURCE, SERIALIZE_ERROR_SOURCE, BUILD_LOGGER_SOURCE;
 var init_taskWorker = __esm({
   "src/task/taskWorker.ts"() {
     "use strict";
@@ -8625,12 +8886,42 @@ function serializeError(err) {
   }
   return { name: 'Error', message: String(err), stack: undefined, props: {} };
 }
+`;
+    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);
+}
 `;
   }
 });
 
 // src/task/taskQueue.ts
-import path25 from "path";
+import path26 from "path";
 function createTaskQueue(deps) {
   const { registry, rootDir, driver } = deps;
   const registriesView = deps.registries ?? createEmptyTaskRegistriesView();
@@ -8660,7 +8951,7 @@ function createTaskQueue(deps) {
   }
   const loadTaskModule = deps.loadTaskModule ?? (async (filePath) => await import(filePath));
   const loadPayloadSchema = deps.loadPayloadSchema ?? (async (filePath) => {
-    const zodPath = path25.join(path25.dirname(filePath), "zod.js");
+    const zodPath = path26.join(path26.dirname(filePath), "zod.js");
     try {
       const mod = await import(zodPath);
       const schemaKey = Object.keys(mod).find((k) => k.endsWith("Schema"));
@@ -8688,7 +8979,7 @@ function createTaskQueue(deps) {
       const meta = registry.get(name);
       schemaCache.set(
         name,
-        await loadPayloadSchema(path25.resolve(rootDir, meta.filePath)).catch(() => void 0)
+        await loadPayloadSchema(path26.resolve(rootDir, meta.filePath)).catch(() => void 0)
       );
     }
     const schema = schemaCache.get(name);
@@ -8724,24 +9015,32 @@ function createTaskQueue(deps) {
       let result;
       if (meta.timeoutMs !== void 0 && meta.timeoutMs > 0) {
         result = await (deps.runIsolated ?? runTaskInWorker)({
-          taskModulePath: path25.resolve(rootDir, meta.filePath),
+          taskModulePath: path26.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(path25.resolve(rootDir, meta.filePath));
+          mod = await loadTaskModule(path26.resolve(rootDir, meta.filePath));
           moduleCache2.set(job.name, mod);
         }
         if (typeof mod.run !== "function") {
@@ -8752,6 +9051,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;
           }
@@ -8906,6 +9208,7 @@ var init_taskQueue = __esm({
     init_httpErrors();
     init_taskWorker();
     init_registries();
+    init_logger();
     TERMINAL_STATUSES = /* @__PURE__ */ new Set(["done", "failed", "cancelled"]);
     MAX_FINISHED_RECORDS = 1e3;
   }
@@ -9019,8 +9322,8 @@ var init_cronScheduler = __esm({
 });
 
 // src/cli/loadPlugins.ts
-import path26 from "path";
-import fs18 from "fs";
+import path27 from "path";
+import fs19 from "fs";
 import { pathToFileURL as pathToFileURL3 } from "url";
 async function loadPlugins(declarations, ctx, rootDir, dist) {
   const handlerWrappers = [];
@@ -9083,37 +9386,37 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
   return { handlerWrappers, upgradeWrappers, failures };
 }
 function resolveLocalPluginSource(specifier, baseDir) {
-  const base = path26.isAbsolute(specifier) ? specifier : path26.resolve(baseDir, specifier);
-  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs18.existsSync(base)) return base;
+  const base = path27.isAbsolute(specifier) ? specifier : path27.resolve(baseDir, specifier);
+  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs19.existsSync(base)) return base;
   for (const ext of [".ts", ".js"]) {
-    if (fs18.existsSync(base + ext)) return base + ext;
+    if (fs19.existsSync(base + ext)) return base + ext;
   }
   for (const indexExt of ["/index.ts", "/index.js"]) {
-    if (fs18.existsSync(base + indexExt)) return base + indexExt;
+    if (fs19.existsSync(base + indexExt)) return base + indexExt;
   }
   return null;
 }
 function mirrorProductPath(sourcePath, baseDir, distDir) {
-  let rel = path26.relative(baseDir, sourcePath).replace(/\\/g, "/");
+  let rel = path27.relative(baseDir, sourcePath).replace(/\\/g, "/");
   if (rel.startsWith("src/")) rel = rel.slice(4);
-  return path26.resolve(distDir, rel.replace(TS_EXTS, ".js"));
+  return path27.resolve(distDir, rel.replace(TS_EXTS, ".js"));
 }
 function isSourceNewer(sourcePath, productPath) {
   try {
-    return fs18.statSync(sourcePath).mtimeMs > fs18.statSync(productPath).mtimeMs;
+    return fs19.statSync(sourcePath).mtimeMs > fs19.statSync(productPath).mtimeMs;
   } catch {
     return true;
   }
 }
 async function importPluginModule(specifier, baseDir, dist) {
   const isRelative = specifier.startsWith("./") || specifier.startsWith("../");
-  if (!isRelative && !path26.isAbsolute(specifier)) {
+  if (!isRelative && !path27.isAbsolute(specifier)) {
     return import(specifier);
   }
-  const distDir = dist ? path26.resolve(baseDir, dist) : null;
+  const distDir = dist ? path27.resolve(baseDir, dist) : null;
   const sourcePath = resolveLocalPluginSource(specifier, baseDir);
   const productPath = sourcePath && distDir ? mirrorProductPath(sourcePath, baseDir, distDir) : null;
-  if (productPath !== null && fs18.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
+  if (productPath !== null && fs19.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
     return import(pathToFileURL3(productPath).href);
   }
   if (sourcePath && TS_EXTS.test(sourcePath)) {
@@ -9122,13 +9425,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 = path26.relative(baseDir, sourcePath).replace(/\\/g, "/");
+    const relFromRoot = path27.relative(baseDir, sourcePath).replace(/\\/g, "/");
     if (relFromRoot.startsWith("src/")) {
       await ensureCompiled(sourcePath, baseDir, dist);
     } else {
       await compileProjectModules([sourcePath], baseDir, dist);
     }
-    if (productPath && fs18.existsSync(productPath)) {
+    if (productPath && fs19.existsSync(productPath)) {
       return import(pathToFileURL3(productPath).href);
     }
   }
@@ -9140,7 +9443,7 @@ async function importPluginModule(specifier, baseDir, dist) {
     `${specifier}/index.ts`,
     `${specifier}.js`,
     `${specifier}/index.js`
-  ].map((c) => path26.isAbsolute(c) ? c : path26.join(baseDir, c));
+  ].map((c) => path27.isAbsolute(c) ? c : path27.join(baseDir, c));
   throw new Error(
     `Cannot find local plugin "${specifier}" (resolved from ${baseDir}). Expected one of:
   ${candidates.join("\n  ")}
@@ -9175,12 +9478,12 @@ var init_loadPlugins = __esm({
 });
 
 // src/cli/createAppCore.ts
-import fs19 from "fs";
-import path27 from "path";
+import fs20 from "fs";
+import path28 from "path";
 import { PassThrough, Readable as Readable4 } from "stream";
 async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries) {
-  const toolsPath = path27.resolve(rootDir, dist, TOOLS_FILE2);
-  if (!fs19.existsSync(toolsPath)) {
+  const toolsPath = path28.resolve(rootDir, dist, TOOLS_FILE2);
+  if (!fs20.existsSync(toolsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(toolsPath);
@@ -9189,8 +9492,8 @@ async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries
   return hydrated;
 }
 async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistries) {
-  const agentsPath = path27.resolve(rootDir, dist, AGENTS_FILE2);
-  if (!fs19.existsSync(agentsPath)) {
+  const agentsPath = path28.resolve(rootDir, dist, AGENTS_FILE2);
+  if (!fs20.existsSync(agentsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(agentsPath);
@@ -9205,8 +9508,8 @@ function getTaskDriverOptions(config) {
   return void 0;
 }
 async function loadAndHydrateTasks(rootDir, dist, registries = defaultRegistries) {
-  const tasksPath = path27.resolve(rootDir, dist, TASKS_FILE);
-  if (!fs19.existsSync(tasksPath)) {
+  const tasksPath = path28.resolve(rootDir, dist, TASKS_FILE);
+  if (!fs20.existsSync(tasksPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(tasksPath);
@@ -9246,13 +9549,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 = path27.resolve(rootDir, dist, ROUTES_FILE);
-  if (!fs19.existsSync(routesPath)) {
+  const routesPath = path28.resolve(rootDir, dist, ROUTES_FILE);
+  if (!fs20.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);
@@ -9589,6 +9893,7 @@ var init_createAppCore = __esm({
     init_loadTaskDriver();
     init_idleTaskDriver();
     init_cronScheduler();
+    init_logger();
     init_loadPlugins();
     init_importWithCacheBust();
     init_registries();
@@ -9612,6 +9917,7 @@ var init_createAppCore = __esm({
       "etag",
       "bodyLimit",
       "logger",
+      "log",
       "http2",
       "trustedProxy",
       "response",
@@ -9621,7 +9927,7 @@ var init_createAppCore = __esm({
 });
 
 // src/cli/createDevApp.ts
-import path28 from "path";
+import path29 from "path";
 async function createDevApp(options) {
   const { app, ctx } = await createAppBase(options);
   const devApp = app;
@@ -9671,7 +9977,7 @@ async function createDevApp(options) {
     invalidateProgramCache();
     const tasks = await scanTasks(ctx.rootDir, TASK_PATTERNS);
     for (const task of tasks) {
-      await ensureCompiled(path28.resolve(ctx.rootDir, task.filePath), ctx.rootDir, ctx.dist);
+      await ensureCompiled(path29.resolve(ctx.rootDir, task.filePath), ctx.rootDir, ctx.dist);
     }
     await generateTaskArtifacts(tasks, ctx.rootDir, ctx.dist);
     ctx.taskQueue.invalidateModules();
@@ -9713,7 +10019,7 @@ __export(devCommand_exports, {
   generateTaskArtifactsForDev: () => generateTaskArtifactsForDev,
   generateToolArtifactsForDev: () => generateToolArtifactsForDev
 });
-import path29 from "path";
+import path30 from "path";
 async function devCommand(options) {
   const rootDir = process.cwd();
   if (!process.env.NODE_ENV) process.env.NODE_ENV = "development";
@@ -9742,7 +10048,7 @@ async function devCommand(options) {
 async function generateRouteArtifacts(rootDir, patterns, dist) {
   const { routes, wsRoutes } = await scanRoutes(rootDir, patterns, dist);
   const sorted = sortRoutes(routes);
-  const routesPath = path29.resolve(rootDir, dist, ROUTES_FILE2);
+  const routesPath = path30.resolve(rootDir, dist, ROUTES_FILE2);
   const serialized = serializeRoutes(sorted, wsRoutes, rootDir, dist);
   await writeRoutesModule(serialized, routesPath);
 }
@@ -9757,7 +10063,7 @@ async function generateAgentArtifactsForDev(rootDir, dist) {
 async function generateTaskArtifactsForDev(rootDir, dist) {
   const tasks = await scanTasks(rootDir, TASK_PATTERNS);
   for (const task of tasks) {
-    await ensureCompiled(path29.resolve(rootDir, task.filePath), rootDir, dist);
+    await ensureCompiled(path30.resolve(rootDir, task.filePath), rootDir, dist);
   }
   await generateTaskArtifacts(tasks, rootDir, dist);
 }
@@ -9805,15 +10111,15 @@ var buildCommand_exports = {};
 __export(buildCommand_exports, {
   buildCommand: () => buildCommand
 });
-import path30 from "path";
-import fs20 from "fs";
+import path31 from "path";
+import fs21 from "fs";
 async function buildCommand(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const outdir = options?.dist ?? DEFAULT_DIST2;
-  const absOut = path30.resolve(rootDir, outdir);
-  const realRoot = toRealPath(path30.resolve(rootDir));
+  const absOut = path31.resolve(rootDir, outdir);
+  const realRoot = toRealPath(path31.resolve(rootDir));
   if (isInsideDir(toRealPath(absOut), realRoot)) {
-    fs20.rmSync(absOut, { recursive: true, force: true });
+    fs21.rmSync(absOut, { recursive: true, force: true });
   } else {
     console.warn(
       `! Output directory "${outdir}" is outside the project root, skipping clean (stale artifacts may remain)`
@@ -9821,10 +10127,10 @@ async function buildCommand(options) {
   }
   await compileConfig({ rootDir, dist: outdir });
   const _config = await loadConfig(rootDir, outdir);
-  const pkgPath = path30.resolve(rootDir, "package.json");
-  if (fs20.existsSync(pkgPath)) {
+  const pkgPath = path31.resolve(rootDir, "package.json");
+  if (fs21.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs20.readFileSync(pkgPath, "utf-8"));
+      const pkg = JSON.parse(fs21.readFileSync(pkgPath, "utf-8"));
       if (pkg.type !== "module") {
         console.warn(
           '! package.json is missing "type": "module" \u2014 build output is ESM and `node dist/main` will fail without it'
@@ -9852,7 +10158,7 @@ async function buildCommand(options) {
   if (localPluginSources.length > 0) {
     console.log("\n[2.5/8] Compiling local plugins...");
     const outside = localPluginSources.filter((p) => {
-      const rel = path30.relative(rootDir, p).replace(/\\/g, "/");
+      const rel = path31.relative(rootDir, p).replace(/\\/g, "/");
       return !rel.startsWith("src/");
     });
     if (outside.length > 0) {
@@ -9876,9 +10182,9 @@ async function buildCommand(options) {
   }
   console.log("\n[4/8] Generating schema...");
   await generateSchemaFiles(sorted, rootDir, outdir);
-  console.log(`  Schema: zod.js files under ${path30.resolve(rootDir, outdir)}`);
+  console.log(`  Schema: zod.js files under ${path31.resolve(rootDir, outdir)}`);
   console.log("\n[5/8] Generating routes manifest...");
-  const routesPath = path30.resolve(rootDir, outdir, "faapi-routes.js");
+  const routesPath = path31.resolve(rootDir, outdir, "faapi-routes.js");
   const serialized = serializeRoutes(sorted, wsRoutes, rootDir, outdir);
   await writeRoutesModule(serialized, routesPath);
   console.log(`  Written to ${routesPath}`);
@@ -9886,19 +10192,19 @@ async function buildCommand(options) {
   const tools = await scanTools(rootDir, TOOL_PATTERNS);
   const toolMeta = await generateToolArtifacts(tools, rootDir, outdir);
   console.log(`  Found ${toolMeta.length} tool(s)`);
-  console.log(`  Tool manifest: ${path30.resolve(rootDir, outdir, "faapi-tools.js")}`);
+  console.log(`  Tool manifest: ${path31.resolve(rootDir, outdir, "faapi-tools.js")}`);
   console.log("\n[7/8] Generating agent manifest...");
   const agents = await scanAgents(rootDir, DEFAULT_AGENT_PATTERNS);
   const agentMeta = await generateAgentArtifacts(agents, rootDir, outdir);
   console.log(`  Found ${agentMeta.length} agent(s)`);
-  console.log(`  Agent manifest: ${path30.resolve(rootDir, outdir, "faapi-agents.js")}`);
+  console.log(`  Agent manifest: ${path31.resolve(rootDir, outdir, "faapi-agents.js")}`);
   console.log("\n[7.5/8] Generating task manifest and schema...");
   const tasks = await scanTasks(rootDir, TASK_PATTERNS);
   const taskMeta = await generateTaskArtifacts(tasks, rootDir, outdir);
   console.log(`  Found ${taskMeta.length} task(s)`);
-  console.log(`  Task manifest: ${path30.resolve(rootDir, outdir, "faapi-tasks.js")}`);
+  console.log(`  Task manifest: ${path31.resolve(rootDir, outdir, "faapi-tasks.js")}`);
   console.log("\n[8/8] Generating entry file...");
-  const mainPath = path30.resolve(rootDir, outdir, "main.js");
+  const mainPath = path31.resolve(rootDir, outdir, "main.js");
   const createProdAppArgs = options?.dist && options.dist !== DEFAULT_DIST2 ? `{ dist: ${JSON.stringify(outdir)} }` : "";
   const mainContent = `// \u7531 faapi build \u81EA\u52A8\u751F\u6210\uFF0C\u8BF7\u52FF\u624B\u52A8\u7F16\u8F91
 import { createProdApp, loadEnv } from '@faapi/faapi';
@@ -9910,7 +10216,7 @@ loadEnv(process.cwd());
 const app = await createProdApp(${createProdAppArgs});
 await app.listen();
 `;
-  await fs20.promises.writeFile(mainPath, mainContent, "utf-8");
+  await fs21.promises.writeFile(mainPath, mainContent, "utf-8");
   console.log(`  Written to ${mainPath}`);
   console.log("\nfaapi build completed");
 }
@@ -9924,7 +10230,7 @@ function extractLocalPluginSources(declarations, rootDir) {
     else if (Array.isArray(decl)) specifier = decl[0];
     else if ("path" in decl) specifier = decl.path;
     if (!specifier) continue;
-    if (!specifier.startsWith("./") && !specifier.startsWith("../") && !path30.isAbsolute(specifier)) {
+    if (!specifier.startsWith("./") && !specifier.startsWith("../") && !path31.isAbsolute(specifier)) {
       continue;
     }
     const source = resolveLocalPluginSource(specifier, rootDir);