tt-help-cli-ycl 1.4.153 → 1.4.155

package/src/clash/daemon.js

@@ -47,6 +47,8 @@ export class ClashDaemon {
     this.disconnectSampleMs =
       opts.disconnectSampleMs > 0 ? opts.disconnectSampleMs : 1000;
     this.dryRun = !!opts.dryRun;
+    // 白名单守卫（默认开启）：当前节点必须 ∈ 候选集（咱们节点列表），不在的不允许，强制切回
+    this.whitelistGuard = opts.whitelistGuard !== false;
     // 控制端发现参数（CLI 显式值优先，内部再合并 ~/.tt-help.json）
     this._discoverOpts = {
       apiPort: opts.apiPort,
@@ -168,6 +170,32 @@ export class ClashDaemon {
     });
   }
 
+  /**
+   * 逐个尝试候选节点并内容验证（巡检/failover/白名单守卫共用切换循环）
+   * @returns {{target: string|null, h2: object|null}} 第一个满足（健康或壳页）的候选；全部失败返回 {target:null}
+   */
+  async _tryRotateCandidates(c, ordered, currentNode, reason = "") {
+    const tag = reason ? ` [原因: ${reason}]` : "";
+    let target = null;
+    let h2 = null;
+    for (const cand of ordered) {
+      if (cand === currentNode) continue;
+      this._log(`↺ [${c.proxyPort}] 尝试候选: ${cand}${tag}`);
+      if (!(await checker.switchToNode(cand))) {
+        this._log(`  ↺ ${cand} 切换失败，下一个`);
+        continue;
+      }
+      this._markSwitch(c, cand);
+      h2 = checker.checkNodeHealth();
+      if (h2.healthy || this._isShellPage(h2)) {
+        target = cand;
+        break;
+      }
+      this._log(`  ↺ ${cand} 内容验证未通过，下一个`);
+    }
+    return { target, h2 };
+  }
+
   /** 将全局 api/checker 上下文指向指定控制器 */
   _useController(c) {
     api.configure({ port: c.port, secret: c.secret });
@@ -402,6 +430,8 @@ export class ClashDaemon {
           this._log(
             `✓ [${c.proxyPort}] ${h.timeTotal.toFixed(1)}s ${(h.sizeDownload / 1024).toFixed(0)}KB`,
           );
+        // 白名单守卫：节点健康但不在咱们节点列表内（如人工在 Clash Verge 界面手动切换）→ 强制切回
+        await this._enforceWhitelist(c, node);
         return;
       }
 
@@ -412,6 +442,8 @@ export class ClashDaemon {
         this._log(
           `~ [${c.proxyPort}] 空壳页（降级响应，链路正常），不切换 (${(h.sizeDownload / 1024).toFixed(0)}KB ${h.timeTotal.toFixed(1)}s)`,
         );
+        // 白名单守卫与主分支同口径：壳页=链路正常，但列表外节点仍不允许
+        if (await this._enforceWhitelist(c, node)) return;
         return this._writeHealth(c, {
           node,
           healthy: true,
@@ -432,6 +464,8 @@ export class ClashDaemon {
         this._log(
           `~ [${c.proxyPort}] 复测恢复（首次异常: ${firstReason}），不切换`,
         );
+        // 白名单守卫：复测恢复同样守口径（列表外节点不允许）
+        if (await this._enforceWhitelist(c, node)) return;
         return this._writeHealth(c, {
           node,
           healthy: true,
@@ -476,23 +510,12 @@ export class ClashDaemon {
       // 逐个切换候选 + 内容验证，第一个满足即采用
       // 排序：切过的节点按切换时间沉底（后进后出），优先尝试"最久没被切过"的节点
       const ordered = this._sortCandidates(nodes, c);
-      let target = null;
-      let h2 = null;
-      for (const cand of ordered) {
-        if (cand === node) continue;
-        this._log(`↺ [${c.proxyPort}] 尝试候选: ${cand} [原因: ${reason}]`);
-        if (!(await checker.switchToNode(cand))) {
-          this._log(`  ↺ ${cand} 切换失败，下一个`);
-          continue;
-        }
-        this._markSwitch(c, cand);
-        h2 = checker.checkNodeHealth();
-        if (h2.healthy || this._isShellPage(h2)) {
-          target = cand;
-          break;
-        }
-        this._log(`  ↺ ${cand} 内容验证未通过，下一个`);
-      }
+      const { target, h2 } = await this._tryRotateCandidates(
+        c,
+        ordered,
+        node,
+        reason,
+      );
 
       if (!target) {
         // 全部候选不可用，恢复原节点
@@ -564,6 +587,75 @@ export class ClashDaemon {
     }
   }
 
+  /**
+   * 白名单守卫：当前 Clash Verge 正在使用的节点必须 ∈ 候选集（咱们节点列表）
+   *
+   * 场景：人工在 Clash Verge 界面手动切到列表外节点、其它程序乱切等。
+   * 每轮巡检执行（健康分支）：发现越界 → 立即切回候选集
+   *（按轮换排序逐个切换+内容验证，第一个满足即采用，同巡检切换口径）。
+   *
+   * 不受 failover 冷却期约束（越界纠正而非故障切换）；候选集为空时无法判定，
+   * 放行（由 delay 初测逻辑自动补齐，下一轮巡检再守卫）。
+   *
+   * @returns {Promise<boolean>} true=已强制切回候选集（调用方可据此跳过自身的 health 写入）
+   */
+  async _enforceWhitelist(c, node) {
+    if (!this.whitelistGuard) return false;
+    if (!node || node === "?") return false;
+    const { nodes } = checker.loadHealthyList();
+    if (!nodes.length || nodes.includes(node)) return false;
+    if (this.dryRun) {
+      this._log(
+        `[DRY-RUN] [${c.proxyPort}] 白名单守卫: 当前节点 ${node} 不在候选集(${nodes.length}个)内，应切回`,
+      );
+      return false;
+    }
+    this._log(
+      `⛔ [${c.proxyPort}] 白名单守卫: 当前节点 ${node} 不在咱们节点列表(${nodes.length}个)内，切回`,
+    );
+    const ordered = this._sortCandidates(nodes, c);
+    const { target, h2 } = await this._tryRotateCandidates(
+      c,
+      ordered,
+      node,
+      "白名单守卫",
+    );
+    if (!target) {
+      // 与 failover/巡检切换口径一致：候选全部不可用时恢复原节点
+      //（_tryRotateCandidates 逐个试切后，当前实际已停在最后尝试的候选上）
+      await checker.switchToNode(node).catch(() => {});
+      this._markSwitch(c, node);
+      this._markSwitchTime(c);
+      await this._disconnect(c);
+      this._log(
+        `✗ [${c.proxyPort}] 白名单守卫: 候选全部不可用，恢复原节点 ${node}`,
+      );
+      this._writeHealth(c, {
+        node,
+        healthy: false,
+        error: "白名单守卫 — 候选全部不可用",
+        lastSwitch: `白名单守卫: 候选全部不可用，恢复原节点 ${node}`,
+      });
+      return false;
+    }
+    this._log(
+      `⚠ [${c.proxyPort}] 节点切换 [白名单守卫]: ${node} → ${target} (${h2.timeTotal.toFixed(1)}s ${(h2.sizeDownload / 1024).toFixed(0)}KB)`,
+    );
+    // 切换后优雅断连：回收空闲连接，活跃放行（同巡检切换）
+    await this._disconnect(c);
+    this._markSwitchTime(c);
+    this._writeHealth(c, {
+      node: target,
+      healthy: h2.healthy,
+      httpCode: h2.httpCode,
+      timeTotal: h2.timeTotal,
+      sizeDownload: h2.sizeDownload,
+      title: h2.title,
+      lastSwitch: `白名单守卫: ${node} → ${target}`,
+    });
+    return true;
+  }
+
   // ── 候选集 delay 初测（每个控制端独立，零切换） ──
 
   _runDelayProbeAll() {
@@ -753,23 +845,12 @@ export class ClashDaemon {
       // 逐个切换候选 + 内容验证，第一个满足即采用（跳过当前节点）
       // 排序：切过的节点按切换时间沉底（后进后出），优先尝试"最久没被切过"的节点
       const ordered = this._sortCandidates(nodes, c);
-      let target = null;
-      let h2 = null;
-      for (const cand of ordered) {
-        if (cand === node) continue;
-        this._log(`↺ 尝试候选: ${cand}`);
-        if (!(await checker.switchToNode(cand))) {
-          this._log(`  ↺ ${cand} 切换失败，下一个`);
-          continue;
-        }
-        this._markSwitch(c, cand);
-        h2 = checker.checkNodeHealth();
-        if (h2.healthy || this._isShellPage(h2)) {
-          target = cand;
-          break;
-        }
-        this._log(`  ↺ ${cand} 内容验证未通过，下一个`);
-      }
+      const { target, h2 } = await this._tryRotateCandidates(
+        c,
+        ordered,
+        node,
+        reason,
+      );
       // 本次 failover 已尽力处置（成功切换或恢复原节点）：更新锚点，给新节点干净观察期
       this._markSwitchTime(c);
 
@@ -839,7 +920,7 @@ export class ClashDaemon {
       `  检测: ${checker.CONFIG.testUrl}  |  巡检: ${this.intervalMs / 1000}s  |  候选刷新: ${this.benchmarkMs / 60000}min${filterTag}`,
     );
     console.error(
-      `  模式: ${this.dryRun ? "DRY-RUN（只检测不切换）" : "正常运行"}`,
+      `  模式: ${this.dryRun ? "DRY-RUN（只检测不切换）" : "正常运行"}  |  白名单守卫: ${this.whitelistGuard ? "开启（列表外节点强制切回）" : "关闭"}`,
     );
     console.error("═".repeat(50));
   }
@@ -882,6 +963,14 @@ function _buildCmdHandlers(daemon) {
         daemon._log(`📋 检测URL: → ${cmd.url}`);
       }
     },
+    setWhitelistGuard(cmd) {
+      const prev = daemon.whitelistGuard;
+      const next = cmd.enabled !== false && cmd.enabled !== "false";
+      daemon.whitelistGuard = next;
+      daemon._log(
+        `📋 白名单守卫: ${prev ? "开启" : "关闭"} → ${next ? "开启" : "关闭"}`,
+      );
+    },
     runBenchmark() {
       daemon._log("📋 收到手动刷新候选集命令");
       daemon._runDelayProbeAll();
@@ -911,6 +1000,7 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
     benchmarkMin: parseInt(getArg("--benchmark")) || undefined,
     country: getArg("--country") || undefined,
     dryRun: args.includes("--dry-run"),
+    whitelistGuard: !args.includes("--no-whitelist-guard"),
     apiPort: parseInt(getArg("--api-port")) || undefined,
     secret: getArg("--secret") || undefined,
     selection: getArg("--selection") || undefined,

package/src/cli/clash-daemon.js

@@ -16,6 +16,7 @@ export async function handleClashDaemon(options) {
       options["dry-run"] === "" ||
       options["dry-run"] === true ||
       process.argv.includes("--dry-run"),
+    whitelistGuard: !options["no-whitelist-guard"],
     apiPort: parseInt(options["api-port"]) || undefined,
     secret: options.secret || undefined,
     selection: options.selection || undefined,

package/src/cli/explore.js

@@ -10,6 +10,7 @@ import {
 } from "../scraper/modules/page-helpers.js";
 import {
   detectCaptcha,
+  detectCaptchaWithWait,
   closeCaptcha,
 } from "../scraper/modules/captcha-handler.js";
 import {
@@ -75,6 +76,7 @@ export async function handleExplore(options) {
     exploreNoProduct,
     exploreSwitchDelay,
     exploreCommentDelay,
+    captchaWaitMin,
   } = options;
 
   let userId = exploreUserId || configuredUserId;
@@ -351,6 +353,44 @@ export async function handleExplore(options) {
       switchAccount: (reason) => handleAccountSwitch(reason),
     });
 
+    /** 等待人工在浏览器中解决验证码：轮询检测，解决即继续；超时返回 false */
+    async function waitForCaptchaResolved() {
+      const waitMin = captchaWaitMin || 3;
+      const deadline = Date.now() + waitMin * 60000;
+      console.error(
+        `  [验证码] 等待人工解决（上限 ${waitMin} 分钟，每15秒检测一次，解决即继续）...`,
+      );
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 15000));
+        let visible = true;
+        try {
+          const r = await detectCaptcha(page);
+          visible = !!(r && r.visible);
+        } catch {
+          visible = false; // 检测异常（页面导航中/重建中）按已解决处理，避免卡死
+        }
+        if (!visible) {
+          console.error("  [验证码] 已解决，继续处理");
+          return true;
+        }
+      }
+      console.error(`  [验证码] 等待 ${waitMin} 分钟未解决，尝试关闭...`);
+      // 超时后尝试关闭验证码弹窗，关不掉由调用方计数切账户
+      await closeCaptcha(page).catch(() => {});
+      await new Promise((r) => setTimeout(r, 2000));
+      try {
+        const r = await detectCaptcha(page);
+        if (!(r && r.visible)) {
+          console.error("  [验证码] 超时后关闭成功，继续处理");
+          return true;
+        }
+      } catch {
+        /* 忽略 */
+      }
+      console.error("  [验证码] 超时且关闭失败");
+      return false;
+    }
+
     let processedCount = 0;
     let errorCount = 0;
     let consecutiveNetworkErrors = 0;
@@ -402,20 +442,13 @@ export async function handleExplore(options) {
         // 切换任务前检测验证码
         const switchCaptcha = await detectCaptcha(page);
         if (switchCaptcha && switchCaptcha.visible) {
-          console.error(`\n[验证码] 切换任务前检测到验证码，等待3分钟...`);
+          console.error(`\n[验证码] 切换任务前检测到验证码`);
           captchaCount++;
           console.error(`  [验证码] 累计 ${captchaCount} 次`);
 
-          // 等待3分钟
-          await new Promise((r) => setTimeout(r, 3 * 60 * 1000));
-
-          // 尝试关闭
-          const closeResult = await closeCaptcha(page);
-          if (closeResult.success) {
-            console.error(`  [验证码] 已关闭`);
-          } else {
-            console.error(`  [验证码] 关闭失败: ${closeResult.reason}`);
-          }
+          // 轮询等待人工解决（解决即继续，超时尝试关闭）；
+          // 不再盲等 3 分钟——同一个验证码若未解决会在下一轮重复计数凑满切账户阈值
+          const resolved = await waitForCaptchaResolved();
 
           // 上报
           await withRetry("report captcha", () =>
@@ -423,16 +456,24 @@ export async function handleExplore(options) {
               userId,
               username: "unknown",
               errorType: "captcha",
-              errorMessage: "切换任务前检测到验证码",
+              errorMessage: resolved
+                ? "切换任务前检测到验证码（已解决）"
+                : "切换任务前检测到验证码（超时未解决）",
               stage: "between-tasks",
               errorStack: "",
             }),
           ).catch(() => {});
 
-          // 累计2次切换账户
-          if (captchaCount >= 2) {
-            await handleAccountSwitch(`验证码累计 ${captchaCount} 次`);
-            captchaCount = 0;
+          // 超时未解决才累计切账户；已解决的不计入（人工处理完了不应消耗账户）
+          if (!resolved) {
+            if (captchaCount >= 3) {
+              await handleAccountSwitch(
+                `验证码累计 ${captchaCount} 次（超时未解决）`,
+              );
+              captchaCount = 0;
+            }
+          } else {
+            captchaCount--; // 解决了就不算一次独立事件
           }
         }
 
@@ -578,7 +619,8 @@ export async function handleExplore(options) {
             // 先记住原错误类型：兜底转验证码时带上，服务端可同时看到"被判+验证码"
             const wasBlocked = result.error.startsWith("被封:");
             try {
-              const lateCaptcha = await detectCaptcha(page);
+              // 带等待检测：验证码容器晚于页面加载渲染，瞬时检测常漏（尤其被判场景）
+              const lateCaptcha = await detectCaptchaWithWait(page, 5000);
               if (lateCaptcha && lateCaptcha.visible) {
                 console.error(
                   `  [验证码] 兜底识别到验证码 @${username}${wasBlocked ? "（被判后弹出）" : ""}`,
@@ -655,9 +697,17 @@ export async function handleExplore(options) {
             }),
           ).catch(() => {});
 
-          // 累计2次验证码，切换账户
-          if (captchaCount >= 2) {
-            await handleAccountSwitch(`验证码累计 ${captchaCount} 次`);
+          // 轮询等待人工解决（解决即继续）：
+          // 不等待会导致同一个验证码在下一轮"切换任务前检测"重复计数，白白凑满阈值切账户
+          const resolved = await waitForCaptchaResolved();
+
+          if (resolved) {
+            captchaCount--; // 人工解决了，不算独立事件
+          } else if (captchaCount >= 3) {
+            // 累计3次验证码（均超时未解决），切换账户
+            await handleAccountSwitch(
+              `验证码累计 ${captchaCount} 次（超时未解决）`,
+            );
             captchaCount = 0;
           }
         }

package/src/lib/api-interceptor.js

@@ -1,6 +1,9 @@
 import { delay } from "./delay.js";
 import { assertPageUrl } from "./browser/page.js";
-import { detectCaptcha } from "../scraper/modules/captcha-handler.js";
+import {
+  detectCaptcha,
+  detectCaptchaWithWait,
+} from "../scraper/modules/captcha-handler.js";
 import {
   detectPageError,
   detectPageErrorWithWait,
@@ -392,19 +395,25 @@ async function fetchUserVideosAPI(
           ? "空响应（0 字节）"
           : `限流（HTTP ${httpStatus}, ${bodyText.slice(0, 60)}）`;
       // 被封形态（尤其 429/ratelimit）常伴随页面弹出验证码：此时继续重试无意义，
-      // 人工解决验证码才是正解。检测到立即抛 "验证码:"，跳过剩余 30/40/50s 空转重试
-      try {
-        const captcha = await detectCaptcha(page);
-        if (captcha && captcha.visible) {
-          log(
-            `  [API拦截] item_list ${reason}，页面已弹出验证码，转验证码处理（不再重试）`,
-          );
-          throw new Error(`验证码: ${username}`);
+      // 人工解决验证码才是正解。检测到立即抛 "验证码:"，跳过剩余 30/40/50s 空转重试。
+      // 验证码容器晚于 domcontentloaded 渲染，瞬时检测常因"太早"漏检 → 用带等待检测；
+      // 等待期（30/40/50s）内弹出的验证码会被下一轮 goto 冲掉，
+      // 所以每轮 sleep 醒来后、下次 goto 前还要再检一次
+      const captchaHit = async (waitMs, when) => {
+        try {
+          const captcha = await detectCaptchaWithWait(page, waitMs);
+          if (captcha && captcha.visible) {
+            log(
+              `  [API拦截] item_list ${reason}，${when}弹出验证码，转验证码处理（不再重试）`,
+            );
+            throw new Error(`验证码: ${username}`);
+          }
+        } catch (e) {
+          if (e.message && e.message.startsWith("验证码:")) throw e;
+          // 检测本身失败（页面导航中/上下文销毁等）：忽略，继续按被封重试
         }
-      } catch (e) {
-        if (e.message && e.message.startsWith("验证码:")) throw e;
-        // 检测本身失败（页面导航中/上下文销毁等）：忽略，继续按被封重试
-      }
+      };
+      await captchaHit(5000, "页面已");
       const retryIndex = attempt - 1;
       if (retryIndex < retryWaits.length) {
         const waitMs = retryWaits[retryIndex];
@@ -412,8 +421,12 @@ async function fetchUserVideosAPI(
           `  [API拦截] item_list ${reason}，判定为被封，${waitMs / 1000}s 后第 ${attempt}/${retryWaits.length} 次重试...`,
         );
         await new Promise((r) => setTimeout(r, waitMs));
+        // 关键时机：等待期间验证码才会真正渲染出来（被 ban 后前端延迟弹窗），
+        // 下次 goto 会把它冲掉 —— sleep 醒来后立即检测，抓住它
+        await captchaHit(3000, "等待期间");
         continue;
       }
+      await captchaHit(5000, "重试耗尽后");
       log(
         `  [API拦截] item_list ${reason}，重试 ${retryWaits.length} 次仍被封`,
       );

package/src/lib/args.js

@@ -187,6 +187,7 @@ function parseExploreArgs(args) {
   let exploreNoProduct = false;
   let exploreSwitchDelay = null;
   let exploreCommentDelay = null;
+  let captchaWaitMin = 3;
 
   const positional = [];
   const PRESETS = ["fast", "normal", "slow", "stealth"];
@@ -237,6 +238,8 @@ function parseExploreArgs(args) {
       exploreSwitchDelay = parseInt(args[++i], 10) || null;
     } else if (arg === "--comment-delay") {
       exploreCommentDelay = parseInt(args[++i], 10) || null;
+    } else if (arg === "--captcha-wait-min") {
+      captchaWaitMin = parseInt(args[++i], 10) || 3;
     } else {
       positional.push(arg);
     }
@@ -264,6 +267,7 @@ function parseExploreArgs(args) {
     explorePreset,
     exploreSwitchDelay,
     exploreCommentDelay,
+    captchaWaitMin,
     exploreInterval,
     exploreMaxComments,
     exploreMaxGuess,
@@ -813,6 +817,7 @@ function parseClashDaemonArgs(args) {
   let interval = 120;
   let benchmark = 10;
   let dryRun = false;
+  let noWhitelistGuard = false;
   let country = null;
   let apiPort = null;
   let secret = null;
@@ -829,6 +834,8 @@ function parseClashDaemonArgs(args) {
       country = args[++i] || null;
     } else if (arg === "--dry-run") {
       dryRun = true;
+    } else if (arg === "--no-whitelist-guard") {
+      noWhitelistGuard = true;
     } else if (arg === "--api-port") {
       apiPort = parseInt(args[++i]) || 0;
     } else if (arg === "--secret") {
@@ -847,6 +854,7 @@ function parseClashDaemonArgs(args) {
     benchmark,
     country,
     "dry-run": dryRun,
+    "no-whitelist-guard": noWhitelistGuard,
     "api-port": apiPort,
     secret,
     selection,

package/src/lib/constants.js

@@ -127,6 +127,7 @@ const HELP_TEXT = [
   "      --preset <预设>           延迟预设 fast/normal/slow/stealth，默认 normal",
   "      --switch-delay <毫秒>     任务切换延迟上限，覆盖预设值（实际等待随机 delay(switchMax, switchMax*3)）",
   "      --comment-delay <毫秒>    评论滚动延迟上限，覆盖预设值",
+  "      --captcha-wait-min <分钟> 验证码等待人工解决上限（轮询检测，解决即继续），默认 3",
   `      --location <国家代码>     国家筛选，逗号分隔，默认 ${DEFAULT_TARGET_LOCATIONS_CSV}`,
   "      --job-locations <国家>    任务国家筛选，逗号分隔（仅筛选服务端任务）",
   "      --max-comments <数量>     每视频最大评论数，默认 10",
@@ -460,6 +461,7 @@ const HELP_TEXT = [
   "      --country <国家代码>     只保留指定国家节点，默认不过滤",
   "                               支持: US, GB, DE, FR, JP, KR, SG, HK, TW, RU 等",
   "      --dry-run                只检测不切换（调试用）",
+  "      --no-whitelist-guard     关闭白名单守卫（默认开启：当前节点不在候选集内时强制切回）",
   "      --api-port <端口>        控制 API 端口（默认自动发现；显式指定验证失败时报错）",
   "      --secret <secret>        控制 API 密钥（默认自动获取）",
   "      --selection <策略>       多控制端选择策略: system-proxy / preference / first-alive",
@@ -469,6 +471,7 @@ const HELP_TEXT = [
   '      {"action":"switchNode","node":"节点名"}         一次性切换到指定节点（不干扰自检）',
   '      {"action":"setCountryFilter","country":"US"}   切换国家过滤',
   '      {"action":"setCountryFilter","country":null}    取消过滤',
+  '      {"action":"setWhitelistGuard","enabled":false}  关闭白名单守卫（enabled:true 开启）',
   '      {"action":"runBenchmark"}                      手动刷新候选集（delay 初测）',
   '      {"action":"setInterval","seconds":60}         修改巡检间隔',
   "    示例: tt-help clash-daemon",

package/src/scraper/modules/captcha-handler.js

@@ -1,6 +1,6 @@
 export async function detectCaptcha(page) {
   return page.evaluate(() => {
-    const container = document.querySelector('.captcha-verify-container');
+    const container = document.querySelector(".captcha-verify-container");
     if (!container) return null;
 
     const r = container.getBoundingClientRect();
@@ -17,14 +17,44 @@ export async function detectCaptcha(page) {
   });
 }
 
+/**
+ * 带等待的验证码检测：轮询等待 .captcha-verify-container 出现且可见。
+ * 验证码容器由前端 JS 延迟渲染（晚于 domcontentloaded / item_list 响应），
+ * 瞬时 detectCaptcha 常因"检测太早"漏检；超时未出现返回 null。
+ */
+export async function detectCaptchaWithWait(page, timeoutMs = 5000) {
+  try {
+    const handle = await page.waitForFunction(
+      () => {
+        const c = document.querySelector(".captcha-verify-container");
+        return !!(c && c.offsetParent !== null);
+      },
+      { timeout: timeoutMs },
+    );
+    const appeared = handle
+      ? await handle.jsonValue().catch(() => false)
+      : false;
+    if (!appeared) return null;
+    // 出现后用原函数拿完整信息（rect 等）；异常按未出现处理
+    return (
+      (await detectCaptcha(page).catch(() => null)) || {
+        exists: true,
+        visible: true,
+      }
+    );
+  } catch {
+    return null; // 超时或页面异常：未出现
+  }
+}
+
 export async function closeCaptcha(page) {
   return page.evaluate(() => {
-    const closeBtn = document.getElementById('captcha_close_button');
-    if (!closeBtn) return { success: false, reason: 'close button not found' };
+    const closeBtn = document.getElementById("captcha_close_button");
+    if (!closeBtn) return { success: false, reason: "close button not found" };
 
-    closeBtn.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
-    closeBtn.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
-    closeBtn.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    closeBtn.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
+    closeBtn.dispatchEvent(new MouseEvent("mouseup", { bubbles: true }));
+    closeBtn.dispatchEvent(new MouseEvent("click", { bubbles: true }));
 
     return { success: true };
   });
@@ -36,12 +66,13 @@ export async function handleCaptcha(page, options = {}) {
   const captcha = await detectCaptcha(page);
   if (!captcha) return { detected: false, closed: false };
 
-  await new Promise(r => setTimeout(r, waitMs));
+  await new Promise((r) => setTimeout(r, waitMs));
 
   const result = await closeCaptcha(page);
-  if (!result.success) return { detected: true, closed: false, reason: result.reason };
+  if (!result.success)
+    return { detected: true, closed: false, reason: result.reason };
 
-  await new Promise(r => setTimeout(r, 1000));
+  await new Promise((r) => setTimeout(r, 1000));
 
   const stillThere = await detectCaptcha(page);
   return { detected: true, closed: !stillThere };
@@ -51,8 +82,8 @@ export async function getIncognitoPage(browser, url, options = {}) {
   const { waitMs = 3000 } = options;
   const context = await browser.newContext();
   const page = await context.newPage();
-  await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
-  await new Promise(r => setTimeout(r, waitMs));
+  await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30000 });
+  await new Promise((r) => setTimeout(r, waitMs));
   return { page, context };
 }
 
@@ -62,13 +93,13 @@ export async function waitAndGetCaptcha(page, options = {}) {
   const captcha = await detectCaptcha(page);
   if (!captcha) return { detected: false, resolved: false, waited: 0 };
 
-  if (log) log('  检测到验证码，等待用户手动输入...');
+  if (log) log("  检测到验证码，等待用户手动输入...");
 
   const startTime = Date.now();
   const deadline = startTime + waitMs;
 
   while (Date.now() < deadline) {
-    await new Promise(r => setTimeout(r, pollInterval));
+    await new Promise((r) => setTimeout(r, pollInterval));
     const remaining = await detectCaptcha(page);
     if (!remaining) {
       const waited = Math.round((Date.now() - startTime) / 1000);
@@ -82,7 +113,7 @@ export async function waitAndGetCaptcha(page, options = {}) {
 
   // 超时后尝试关闭验证码弹窗
   await closeCaptcha(page);
-  await new Promise(r => setTimeout(r, 1000));
+  await new Promise((r) => setTimeout(r, 1000));
 
   return { detected: true, resolved: false, waited };
 }
@@ -92,22 +123,30 @@ export async function safeClickComment(page, options = {}) {
 
   // 点击评论
   await page.evaluate(() => {
-    const all = document.querySelectorAll('button');
+    const all = document.querySelectorAll("button");
     for (const el of all) {
-      if (/^评论$/.test(el.textContent?.trim()) && el.offsetParent !== null && el.getBoundingClientRect().width > 0) {
+      if (
+        /^评论$/.test(el.textContent?.trim()) &&
+        el.offsetParent !== null &&
+        el.getBoundingClientRect().width > 0
+      ) {
         el.click();
         break;
       }
     }
   });
 
-  await new Promise(r => setTimeout(r, waitMs));
+  await new Promise((r) => setTimeout(r, waitMs));
 
   // 检测并关闭验证码
   const captcha = await detectCaptcha(page);
   if (captcha) {
     const result = await handleCaptcha(page);
-    return { clicked: true, captchaDetected: true, captchaClosed: result.closed };
+    return {
+      clicked: true,
+      captchaDetected: true,
+      captchaClosed: result.closed,
+    };
   }
 
   return { clicked: true, captchaDetected: false, captchaClosed: false };