tt-help-cli-ycl 1.4.151 → 1.4.153

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tt-help-cli-ycl",
-  "version": "1.4.151",
+  "version": "1.4.153",
   "description": "TikTok user & video data scraper - extract ttSeller, verified, locationCreated from HTML source",
   "type": "module",
   "bin": {

package/scripts/test-api-interceptor-captcha.mjs

@@ -0,0 +1,134 @@
+// 临时验证：被判重试期间弹出验证码 → fetchUserVideosAPI 立即抛 "验证码:"，不再空转重试
+// 运行：RM_BLOCKED_WAIT_MS=1 node scripts/test-api-interceptor-captcha.mjs
+import { fetchUserVideosAPI } from "../src/lib/api-interceptor.js";
+
+let pass = 0;
+let fail = 0;
+
+function check(name, ok, detail = "") {
+  if (ok) {
+    pass++;
+    console.log(`✓ ${name}${detail ? `: ${detail}` : ""}`);
+  } else {
+    fail++;
+    console.error(`✗ ${name}${detail ? `: ${detail}` : ""}`);
+  }
+}
+
+// 429 + 页面有验证码容器
+function make429CaptchaPage(username) {
+  let gotoCount = 0;
+  const page = {
+    _handlers: {},
+    on(event, fn) {
+      (page._handlers[event] ||= []).push(fn);
+      return page;
+    },
+    off(event) {
+      delete page._handlers[event];
+      return page;
+    },
+    url: () => `https://www.tiktok.com/@${username}`,
+    goto: async () => {
+      gotoCount++;
+    },
+    // checkCdpHealth 用 () => document.readyState（fn.length===0）→ "complete"
+    // detectCaptcha 用 () => {...}（fn.length===0，通过 captchaVisible 开关控制返回值）
+    _captchaVisible: true,
+    evaluate: async (fn) => {
+      if (
+        page._captchaVisible &&
+        fn.toString().includes("captcha-verify-container")
+      ) {
+        return {
+          exists: true,
+          visible: true,
+          rect: { x: 0, y: 0, w: 100, h: 100 },
+        };
+      }
+      // detectPageError（fn.length===1）→ null
+      if (fn.length === 1) return null;
+      return "complete";
+    },
+    reload: async () => {},
+    waitForFunction: async () => null,
+    waitForResponse: async (pred) => {
+      const resp = {
+        url: () => "https://www.tiktok.com/api/post/item_list/?...",
+        status: () => 429,
+        headers: () => ({ "content-length": "19" }),
+        json: async () => {
+          throw new Error("Unexpected token 'r'...");
+        },
+        body: async () => Buffer.from("ratelimit triggered"),
+      };
+      if (!pred(resp)) throw new Error("response 不匹配 item_list");
+      return resp;
+    },
+    get gotoCount() {
+      return gotoCount;
+    },
+  };
+  return page;
+}
+
+// 用例1：429 + 验证码可见 → 立即抛 "验证码:"，只 goto 1 次（无重试）
+{
+  const page = make429CaptchaPage("fumolbbf08o");
+  try {
+    await fetchUserVideosAPI(page, "fumolbbf08o", 5, () => {});
+    check("429+验证码 立即转验证码", false, "未抛错");
+  } catch (e) {
+    check(
+      "429+验证码 立即转验证码",
+      e.message === "验证码: fumolbbf08o",
+      `抛错 "${e.message}"`,
+    );
+  }
+  check(
+    "429+验证码 不再重试（仅 1 次 goto）",
+    page.gotoCount === 1,
+    `goto 次数 = ${page.gotoCount}`,
+  );
+}
+
+// 用例2：429 + 验证码不可见 → 仍走正常被封重试，最终抛 "被封:"
+{
+  const page = make429CaptchaPage("fumolbbf08o");
+  page._captchaVisible = false;
+  try {
+    await fetchUserVideosAPI(page, "fumolbbf08o", 5, () => {});
+    check("429无验证码 仍按被封重试", false, "未抛错");
+  } catch (e) {
+    check(
+      "429无验证码 仍按被封重试",
+      e.message === "被封: fumolbbf08o",
+      `抛错 "${e.message}"，goto ${page.gotoCount} 次`,
+    );
+  }
+}
+
+// 用例3：429 + detectCaptcha 本身抛异常（页面上下文销毁）→ 忽略，按被封重试
+{
+  const page = make429CaptchaPage("fumolbbf08o");
+  page.evaluate = async (fn) => {
+    if (fn.toString().includes("captcha-verify-container")) {
+      throw new Error("Execution context was destroyed");
+    }
+    if (fn.length === 1) return null;
+    return "complete";
+  };
+  try {
+    await fetchUserVideosAPI(page, "fumolbbf08o", 5, () => {});
+    check("检测异常时忽略按被封重试", false, "未抛错");
+  } catch (e) {
+    check(
+      "检测异常时忽略按被封重试",
+      e.message === "被封: fumolbbf08o",
+      `抛错 "${e.message}"`,
+    );
+  }
+}
+
+console.error(`\n结果: ${pass} 通过, ${fail} 失败`);
+process.exit(fail > 0 ? 1 : 0);

package/scripts/test-sample-all-fail.mjs

@@ -0,0 +1,142 @@
+// 验证：国家采样全失败（通道故障）→ 任务按 error 回流，不再静默 done
+// 运行：node scripts/test-sample-all-fail.mjs
+let pass = 0;
+let fail = 0;
+function check(name, ok, detail = "") {
+  if (ok) {
+    pass++;
+    console.log(`✓ ${name}${detail ? `: ${detail}` : ""}`);
+  } else {
+    fail++;
+    console.error(`✗ ${name}${detail ? `: ${detail}` : ""}`);
+  }
+}
+
+// [1] 全失败判定（等价于实现中 Promise.all + sampleFailCount 计数）
+{
+  const sampleUrls = ["u1", "u2", "u3", "u4", "u5"];
+  // 模拟通道故障：每个 fetch 都抛错 → catch 内计数 +1，返回 null
+  let sampleFailCount = 0;
+  const locations = await Promise.all(
+    sampleUrls.map(async () => {
+      try {
+        throw new Error("fetch failed");
+      } catch {
+        sampleFailCount++;
+        return null;
+      }
+    }),
+  );
+  const allFailed =
+    sampleUrls.length > 0 && sampleFailCount === sampleUrls.length;
+  check(
+    "全失败判定：5/5 fetch 抛错 → allFailed=true",
+    allFailed === true && locations.every((l) => l === null),
+  );
+}
+
+// [2] 部分失败判定：2/5 失败 → allFailed=false（保持众数逻辑）
+{
+  const sampleUrls = ["u1", "u2", "u3", "u4", "u5"];
+  let sampleFailCount = 0;
+  const locations = await Promise.all(
+    sampleUrls.map(async (u) => {
+      try {
+        if (u === "u1" || u === "u2") throw new Error("timeout");
+        return "TH";
+      } catch {
+        sampleFailCount++;
+        return null;
+      }
+    }),
+  );
+  const allFailed =
+    sampleUrls.length > 0 && sampleFailCount === sampleUrls.length;
+  check(
+    "部分失败判定：2/5 失败 → allFailed=false（走众数）",
+    allFailed === false && locations.filter(Boolean).length === 3,
+  );
+}
+
+// [3] 全成功但无数据判定：sampleFailCount=0 → 不转 error（保持 done 无国家回炉机制）
+{
+  const sampleUrls = ["u1", "u2", "u3"];
+  let sampleFailCount = 0;
+  const locations = await Promise.all(
+    sampleUrls.map(async () => {
+      const data = { locationCreated: null }; // 成功响应但无字段
+      return data?.locationCreated || null;
+    }),
+  );
+  const allFailed =
+    sampleUrls.length > 0 && sampleFailCount === sampleUrls.length;
+  check(
+    "全成功无数据：failCount=0 → 不转 error（done 无国家，2h 回炉兜底）",
+    allFailed === false && locations.every((l) => l === null),
+  );
+}
+
+// [4] 不可达 webserver → fetch 必抛错（通道故障可稳定复现）
+{
+  let fetchThrows = false;
+  try {
+    await fetch("http://127.0.0.1:1/api/tiktok/video", {
+      method: "POST",
+      signal: AbortSignal.timeout(2000),
+    });
+  } catch {
+    fetchThrows = true;
+  }
+  check(
+    "不可达 webserver → fetch 抛错（通道故障可复现）",
+    fetchThrows === true,
+  );
+}
+
+// [5] 真实 processExplore：page mock 让 collectVideos 走不通（API 拦截失败抛错）
+//     无论命中哪条错误路径，都不应出现"processed=true 且无 error 且无国家"的静默 done
+{
+  const fakePage = {
+    async evaluate() {
+      return {};
+    },
+    async goto() {},
+    on() {
+      return this;
+    },
+    off() {
+      return this;
+    },
+    url: () => "https://www.tiktok.com/@test",
+    waitForResponse() {
+      return Promise.reject(new Error("timeout"));
+    },
+  };
+  const { processExplore } = await import("../src/scraper/explore-core.js");
+  const result = await processExplore(
+    fakePage,
+    "testuser",
+    {
+      maxVideos: 1,
+      enableFollow: false,
+      loggedIn: false,
+      mini: false,
+      webserverUrl: "http://127.0.0.1:1",
+      location: "TH",
+    },
+    () => {},
+  );
+  const silentDone =
+    result.processed === true &&
+    !result.error &&
+    !result.noVideo &&
+    !result.locationCreated;
+  check(
+    "通道故障下不出现静默 done",
+    silentDone === false,
+    `error=${result.error ? `"${result.error.slice(0, 40)}"` : "无"}`,
+  );
+}
+
+console.error(`\n结果: ${pass} 通过, ${fail} 失败`);
+process.exit(fail > 0 ? 1 : 0);

package/src/cli/explore.js

@@ -73,6 +73,8 @@ export async function handleExplore(options) {
     exploreProxy,
     exploreWebserver,
     exploreNoProduct,
+    exploreSwitchDelay,
+    exploreCommentDelay,
   } = options;
 
   let userId = exploreUserId || configuredUserId;
@@ -111,6 +113,17 @@ export async function handleExplore(options) {
     }
 
     setDelayConfig(explorePreset);
+    // 自定义延迟：数值参数优先于预设（仅覆盖给出的项）
+    if (exploreSwitchDelay != null || exploreCommentDelay != null) {
+      const overrides = {};
+      if (exploreSwitchDelay != null) overrides.switchMax = exploreSwitchDelay;
+      if (exploreCommentDelay != null)
+        overrides.commentMax = exploreCommentDelay;
+      setDelayConfig(overrides);
+      console.error(
+        `自定义延迟: 切换 ${overrides.switchMax ?? "预设值"}ms, 评论 ${overrides.commentMax ?? "预设值"}ms`,
+      );
+    }
 
     console.error(`\n国家筛选: ${exploreLocation}`);
     if (exploreJobLocations) console.error(`任务国家: ${exploreJobLocations}`);
@@ -562,14 +575,21 @@ export async function handleExplore(options) {
           // 可能在验证码延迟渲染前已执行，或已识别到( captchaDetected=true )但后续流程又抛了异常出现 error。
           // 这里在把错误上报为 network/other 前对当前页面再检测一次，识别到则转走验证码分支。
           if (result.error) {
+            // 先记住原错误类型：兜底转验证码时带上，服务端可同时看到"被判+验证码"
+            const wasBlocked = result.error.startsWith("被封:");
             try {
               const lateCaptcha = await detectCaptcha(page);
               if (lateCaptcha && lateCaptcha.visible) {
-                console.error(`  [验证码] 兜底识别到验证码 @${username}`);
+                console.error(
+                  `  [验证码] 兜底识别到验证码 @${username}${wasBlocked ? "（被判后弹出）" : ""}`,
+                );
                 result.captchaDetected = true;
                 result.captchaStage = result.captchaStage || "process";
                 result.captchaMessage =
-                  result.captchaMessage || "上报错误前识别到验证码";
+                  result.captchaMessage ||
+                  (wasBlocked
+                    ? `被判后弹出验证码（原错误: ${result.error}）`
+                    : "上报错误前识别到验证码");
                 result.error = null;
                 result.errorStack = "";
                 result.retryable = false;

package/src/cli/refresh-mini.js

@@ -150,6 +150,8 @@ export async function handleRefreshMini(options) {
     rotateMin,
     captchaWaitMin,
     ensureDaemon,
+    exploreSwitchDelay,
+    exploreCommentDelay,
   } = options;
 
   // 配置了什么代理就用什么代理（--proxy > ~/.tt-help.json 的 proxy）；
@@ -191,6 +193,17 @@ export async function handleRefreshMini(options) {
     }
 
     setDelayConfig(explorePreset);
+    // 自定义延迟：数值参数优先于预设（仅覆盖给出的项）
+    if (exploreSwitchDelay != null || exploreCommentDelay != null) {
+      const overrides = {};
+      if (exploreSwitchDelay != null) overrides.switchMax = exploreSwitchDelay;
+      if (exploreCommentDelay != null)
+        overrides.commentMax = exploreCommentDelay;
+      setDelayConfig(overrides);
+      console.error(
+        `自定义延迟: 切换 ${overrides.switchMax ?? "预设值"}ms, 评论 ${overrides.commentMax ?? "预设值"}ms`,
+      );
+    }
 
     console.error(`\n=== refresh-mini 模式（视频信息更新） ===`);
     console.error(`服务器: ${serverUrl}`);

package/src/cli/refresh.js

@@ -72,6 +72,8 @@ export async function handleRefresh(options) {
     exploreWebserver,
     exploreNoProduct,
     exploreMini,
+    exploreSwitchDelay,
+    exploreCommentDelay,
   } = options;
   // --mini 模式：只采集视频列表及由视频推导的信息（EC视频、最新发布时间），
   // 跳过用户信息、国家采样、关注/粉丝提取（最大耗时项）和商品详情抓取（由独立商品程序异步补抓），大幅提速。
@@ -119,6 +121,17 @@ export async function handleRefresh(options) {
     }
 
     setDelayConfig(explorePreset);
+    // 自定义延迟：数值参数优先于预设（仅覆盖给出的项）
+    if (exploreSwitchDelay != null || exploreCommentDelay != null) {
+      const overrides = {};
+      if (exploreSwitchDelay != null) overrides.switchMax = exploreSwitchDelay;
+      if (exploreCommentDelay != null)
+        overrides.commentMax = exploreCommentDelay;
+      setDelayConfig(overrides);
+      console.error(
+        `自定义延迟: 切换 ${overrides.switchMax ?? "预设值"}ms, 评论 ${overrides.commentMax ?? "预设值"}ms`,
+      );
+    }
 
     console.error(`\n=== Refresh 模式（基于 explore） ===`);
     console.error(`服务器: ${serverUrl}`);

package/src/lib/api-interceptor.js

@@ -1,5 +1,6 @@
 import { delay } from "./delay.js";
 import { assertPageUrl } from "./browser/page.js";
+import { detectCaptcha } from "../scraper/modules/captcha-handler.js";
 import {
   detectPageError,
   detectPageErrorWithWait,
@@ -390,6 +391,20 @@ async function fetchUserVideosAPI(
         rawBodyBytes === 0
           ? "空响应（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}`);
+        }
+      } catch (e) {
+        if (e.message && e.message.startsWith("验证码:")) throw e;
+        // 检测本身失败（页面导航中/上下文销毁等）：忽略，继续按被封重试
+      }
       const retryIndex = attempt - 1;
       if (retryIndex < retryWaits.length) {
         const waitMs = retryWaits[retryIndex];

package/src/lib/args.js

@@ -185,6 +185,8 @@ function parseExploreArgs(args) {
   let exploreProxy = null;
   let exploreWebserver = null;
   let exploreNoProduct = false;
+  let exploreSwitchDelay = null;
+  let exploreCommentDelay = null;
 
   const positional = [];
   const PRESETS = ["fast", "normal", "slow", "stealth"];
@@ -229,6 +231,12 @@ function parseExploreArgs(args) {
       exploreWebserver = args[++i];
     } else if (arg === "--no-product") {
       exploreNoProduct = true;
+    } else if (arg === "--preset") {
+      explorePreset = args[++i];
+    } else if (arg === "--switch-delay") {
+      exploreSwitchDelay = parseInt(args[++i], 10) || null;
+    } else if (arg === "--comment-delay") {
+      exploreCommentDelay = parseInt(args[++i], 10) || null;
     } else {
       positional.push(arg);
     }
@@ -254,6 +262,8 @@ function parseExploreArgs(args) {
     subcommand: "explore",
     exploreUsernames: usernames,
     explorePreset,
+    exploreSwitchDelay,
+    exploreCommentDelay,
     exploreInterval,
     exploreMaxComments,
     exploreMaxGuess,
@@ -542,6 +552,8 @@ function parseRefreshArgs(args) {
   let exploreWebserver = null;
   let exploreNoProduct = false;
   let exploreMini = false;
+  let exploreSwitchDelay = null;
+  let exploreCommentDelay = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -551,6 +563,10 @@ function parseRefreshArgs(args) {
       exploreMini = true;
     } else if (arg === "--preset") {
       explorePreset = args[++i];
+    } else if (arg === "--switch-delay") {
+      exploreSwitchDelay = parseInt(args[++i], 10) || null;
+    } else if (arg === "--comment-delay") {
+      exploreCommentDelay = parseInt(args[++i], 10) || null;
     } else if (arg === "-i" || arg === "--interval") {
       exploreInterval = parseInt(args[++i], 10) || 30;
     } else if (arg === "--port") {
@@ -593,6 +609,8 @@ function parseRefreshArgs(args) {
   return {
     subcommand: "refresh",
     explorePreset,
+    exploreSwitchDelay,
+    exploreCommentDelay,
     exploreInterval,
     exploreEnableFollow,
     exploreMaxFollowing,
@@ -640,6 +658,8 @@ function parseRefreshMiniArgs(args) {
   let rotateMin = 10;
   let captchaWaitMin = 10;
   let ensureDaemon = false;
+  let exploreSwitchDelay = null;
+  let exploreCommentDelay = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -647,6 +667,10 @@ function parseRefreshMiniArgs(args) {
       serverUrl = args[++i];
     } else if (arg === "--preset") {
       explorePreset = args[++i];
+    } else if (arg === "--switch-delay") {
+      exploreSwitchDelay = parseInt(args[++i], 10) || null;
+    } else if (arg === "--comment-delay") {
+      exploreCommentDelay = parseInt(args[++i], 10) || null;
     } else if (arg === "-i" || arg === "--interval") {
       exploreInterval = parseInt(args[++i], 10) || 30;
     } else if (arg === "--port") {
@@ -677,6 +701,8 @@ function parseRefreshMiniArgs(args) {
   return {
     subcommand: "refresh-mini",
     explorePreset,
+    exploreSwitchDelay,
+    exploreCommentDelay,
     exploreInterval,
     exploreLocation,
     exploreJobLocations,

package/src/lib/constants.js

@@ -124,6 +124,9 @@ const HELP_TEXT = [
   "    预设: fast, normal（默认）, slow, stealth",
   "    选项:",
   "      --server <URL>            服务端地址，默认 http://127.0.0.1:3001",
+  "      --preset <预设>           延迟预设 fast/normal/slow/stealth，默认 normal",
+  "      --switch-delay <毫秒>     任务切换延迟上限，覆盖预设值（实际等待随机 delay(switchMax, switchMax*3)）",
+  "      --comment-delay <毫秒>    评论滚动延迟上限，覆盖预设值",
   `      --location <国家代码>     国家筛选，逗号分隔，默认 ${DEFAULT_TARGET_LOCATIONS_CSV}`,
   "      --job-locations <国家>    任务国家筛选，逗号分隔（仅筛选服务端任务）",
   "      --max-comments <数量>     每视频最大评论数，默认 10",
@@ -139,8 +142,11 @@ const HELP_TEXT = [
   "      --base-port <端口号>      起始端口，默认 9222",
   "      --port-count <数量>       端口数量（账户数），默认 10",
   "      --user-id <编号>          客户端编号（设备ID），默认自动生成",
-  "--proxy <地址>            浏览器代理（如 socks5://127.0.0.1:1080），未指定时使用配置文件 proxy",
-  "--webserver <URL>         集中式视频国家查询服务（如 http://127.0.0.1:3000），省去本地 Playwright 浏览器",
+  "      --preset <预设>           延迟预设 fast/normal/slow/stealth，默认 normal",
+  "      --switch-delay <毫秒>     任务切换延迟上限，覆盖预设值",
+  "      --comment-delay <毫秒>    评论滚动延迟上限，覆盖预设值",
+  "      --proxy <地址>            浏览器代理（如 socks5://127.0.0.1:1080），未指定时使用配置文件 proxy",
+  "      --webserver <URL>         集中式视频国家查询服务（如 http://127.0.0.1:3000），省去本地 Playwright 浏览器",
   "",
   "  tt-help refresh [选项]",
   "    对目标商家用户进行轮回刷新，重新采集视频 + 关注 + 粉丝",
@@ -162,6 +168,9 @@ const HELP_TEXT = [
   "      --base-port <端口号>      起始端口，默认 9222",
   "      --port-count <数量>       端口数量（账户数），默认 10",
   "      --user-id <编号>          客户端编号（设备ID），默认自动生成",
+  "      --preset <预设>           延迟预设 fast/normal/slow/stealth，默认 normal",
+  "      --switch-delay <毫秒>     任务切换延迟上限，覆盖预设值",
+  "      --comment-delay <毫秒>    评论滚动延迟上限，覆盖预设值",
   "--proxy <地址>            浏览器代理（如 socks5://127.0.0.1:1080），未指定时使用配置文件 proxy",
   "--webserver <URL>         集中式视频国家查询服务（如 http://127.0.0.1:3000），省去本地 Playwright 浏览器",
   "",
@@ -184,6 +193,8 @@ const HELP_TEXT = [
   "      --captcha-wait-min <分钟> 验证码等待人工解决上限，默认 10",
   "      --ensure-daemon           启动时检查 clash-daemon 是否存活，未存活则自动拉起（默认不检测）",
   "      --preset <预设>           延迟预设 fast/normal/slow/stealth，默认 normal",
+  "      --switch-delay <毫秒>     任务切换延迟上限，覆盖预设值",
+  "      --comment-delay <毫秒>    评论滚动延迟上限，覆盖预设值",
   "      --proxy <地址>            浏览器代理（默认走 Clash 本地端口，切换节点才有效）",
   "",
   "  tt-help precheck [选项]",

package/src/scraper/auto-core.js

@@ -9,24 +9,25 @@ import {
   detectPageError,
   isLoggedIn,
   assertPageUrl,
-} from './modules/page-helpers.js';
-import { detectCaptcha } from './modules/captcha-handler.js';
+} from "./modules/page-helpers.js";
+import { detectCaptcha } from "./modules/captcha-handler.js";
 export { ensureBrowserReady };
-import {
-  getUserInfo,
-  collectVideos,
-} from '../videos/core.js';
-import { runScrape } from './core.js';
-import { extractFollowAndFollowers } from './modules/follow-extractor.js';
+import { getUserInfo, collectVideos } from "../videos/core.js";
+import { runScrape } from "./core.js";
+import { extractFollowAndFollowers } from "./modules/follow-extractor.js";
 
 function mergeUserInfo(existing, incoming, source) {
   const merged = { ...existing };
   for (const [key, value] of Object.entries(incoming)) {
-    if (key === '_sources') continue;
-    if (value === undefined || value === null || value === '') continue;
-    if (typeof value === 'number' && typeof merged[key] === 'number') {
+    if (key === "_sources") continue;
+    if (value === undefined || value === null || value === "") continue;
+    if (typeof value === "number" && typeof merged[key] === "number") {
       merged[key] = Math.max(merged[key], value);
-    } else if (merged[key] === undefined || merged[key] === null || merged[key] === '') {
+    } else if (
+      merged[key] === undefined ||
+      merged[key] === null ||
+      merged[key] === ""
+    ) {
       merged[key] = value;
     }
   }
@@ -43,7 +44,7 @@ async function processUser(page, username, options, log) {
     scrapeDepth = 50,
     maxComments = 200,
     maxGuess = 10,
-    preset = 'fast',
+    preset = "fast",
     switchMax = null,
     commentMax = null,
     enableFollow = false,
@@ -65,34 +66,43 @@ async function processUser(page, username, options, log) {
 
   try {
     log(`\n[processUser] 访问 @${username}...`);
-    await retryWithBackoff(async () => {
-      await page.goto(`https://www.tiktok.com/@${username}`, {
-        waitUntil: 'load', timeout: 30000,
-      });
-      assertPageUrl(page, `@${username}`);
-    }, { log });
-    await page.waitForSelector('[class*="DivVideoList"]', { timeout: 10000 }).catch(() => {});
+    await retryWithBackoff(
+      async () => {
+        await page.goto(`https://www.tiktok.com/@${username}`, {
+          waitUntil: "load",
+          timeout: 30000,
+        });
+        assertPageUrl(page, `@${username}`);
+      },
+      { log },
+    );
+    await page
+      .waitForSelector('[class*="DivVideoList"]', { timeout: 10000 })
+      .catch(() => {});
     await delay(1000, 2000);
 
     const info = await getUserInfo(page);
     result.userInfo = info;
     if (!info.uniqueId) info.uniqueId = username;
-    log(`  昵称: ${info.nickname || '-'} | 粉丝: ${info.followerCount || 0}`);
+    log(`  昵称: ${info.nickname || "-"} | 粉丝: ${info.followerCount || 0}`);
 
     if (options.enableFollow) {
       const loggedIn = await isLoggedIn(page);
       if (!loggedIn) {
-        log('  [跳过] 提取关注/粉丝：未登录，请先登录 TikTok');
+        log("  [跳过] 提取关注/粉丝：未登录，请先登录 TikTok");
         result.discoveredFollowing = [];
         result.discoveredFollowers = [];
       } else {
         try {
-          log('  提取关注/粉丝列表...');
-          const { following, followers } = await extractFollowAndFollowers(page, {
-            maxFollowing: options.maxFollowing || 200,
-            maxFollowers: options.maxFollowers || 200,
-            log,
-          });
+          log("  提取关注/粉丝列表...");
+          const { following, followers } = await extractFollowAndFollowers(
+            page,
+            {
+              maxFollowing: options.maxFollowing || 200,
+              maxFollowers: options.maxFollowers || 200,
+              log,
+            },
+          );
           result.discoveredFollowing = following;
           result.discoveredFollowers = followers;
           log(`  关注: ${following.length} | 粉丝: ${followers.length}`);
@@ -108,13 +118,13 @@ async function processUser(page, username, options, log) {
     if (captcha && captcha.visible) {
       log(`[验证码] @${username} 页面出现验证码`);
       result.captchaDetected = true;
-      result.captchaStage = result.captchaStage || 'video-page';
-      result.captchaMessage = result.captchaMessage || '视频页出现验证码';
+      result.captchaStage = result.captchaStage || "video-page";
+      result.captchaMessage = result.captchaMessage || "视频页出现验证码";
     }
 
     const videos = await collectVideos(page, username, collectMax, log);
     const videoList = Array.from(videos.values()).slice(0, collectMax);
-    result.collectedVideos = videoList.map(v => ({
+    result.collectedVideos = videoList.map((v) => ({
       videoId: v.id,
       videoUrl: v.href,
     }));
@@ -126,10 +136,12 @@ async function processUser(page, username, options, log) {
 
       for (let i = 0; i < videoList.length; i++) {
         const video = videoList[i];
-        const videoUrl = video.href.startsWith('http')
+        const videoUrl = video.href.startsWith("http")
           ? video.href
           : `https://www.tiktok.com${video.href}`;
-        log(`  [${i + 1}/${videoList.length}] 开始 scrape: ${videoUrl} (深度 ${scrapeDepth})`);
+        log(
+          `  [${i + 1}/${videoList.length}] 开始 scrape: ${videoUrl} (深度 ${scrapeDepth})`,
+        );
 
         const scrapeResult = await runScrape({
           videoUrl,
@@ -146,8 +158,9 @@ async function processUser(page, username, options, log) {
 
         if (scrapeResult.captchaDetected) {
           result.captchaDetected = true;
-          result.captchaStage = scrapeResult.captchaStage || 'scrape';
-          result.captchaMessage = scrapeResult.captchaMessage || 'scrape阶段出现验证码';
+          result.captchaStage = scrapeResult.captchaStage || "scrape";
+          result.captchaMessage =
+            scrapeResult.captchaMessage || "scrape阶段出现验证码";
         }
 
         const scrapeOutput = scrapeResult.output;
@@ -181,7 +194,9 @@ async function processUser(page, username, options, log) {
       result.discoveredCommentAuthors = [...allCommentAuthors];
       result.discoveredGuessAuthors = [...allGuessAuthors];
 
-      log(`  发现: ${result.discoveredVideoAuthors.length} 个视频作者, ${result.discoveredCommentAuthors.length} 个评论作者, ${result.discoveredGuessAuthors.length} 个猜你喜欢作者`);
+      log(
+        `  发现: ${result.discoveredVideoAuthors.length} 个视频作者, ${result.discoveredCommentAuthors.length} 个评论作者, ${result.discoveredGuessAuthors.length} 个猜你喜欢作者`,
+      );
     } else {
       const pageError = await detectPageError(page);
       result.restricted = !!pageError;
@@ -192,8 +207,17 @@ async function processUser(page, username, options, log) {
       }
     }
   } catch (e) {
+    // 被判重试期间弹出验证码（api-interceptor 抛出 "验证码: username"）:
+    // 转验证码标记，由外层 captchaDetected 计数处理
+    if (e.message.startsWith("验证码:")) {
+      result.captchaDetected = true;
+      result.captchaStage = result.captchaStage || "video-page";
+      result.captchaMessage = result.captchaMessage || "被判重试期间弹出验证码";
+      log(`  @${username} 被判期间弹出验证码，转验证码处理`);
+      return result;
+    }
     result.error = e.message;
-    result.errorStack = e.stack || '';
+    result.errorStack = e.stack || "";
     log(`  [错误] ${e.message}`);
   }
 

package/src/scraper/explore-core.js

@@ -200,6 +200,7 @@ async function processExplore(page, username, options, log) {
         `  国家采样(${sampleUrls.length}个, 已排除图文${videoArray.length - videoArray.filter((v) => !v.isPhoto).length}条): 开始查询`,
       );
       let locations;
+      let sampleFailCount = 0; // 查询本身失败（网络/超时/CDN）计数，与"查成功但无数据"区分
       if (webserverUrl) {
         // 走集中式 webserver，不再启动本地 TikTokScraper
         locations = await Promise.all(
@@ -214,6 +215,7 @@ async function processExplore(page, username, options, log) {
               const data = await res.json();
               return data?.locationCreated || null;
             } catch (e) {
+              sampleFailCount++;
               log(`  [webserver] 视频查询失败: ${e.message}`);
               return null;
             }
@@ -221,12 +223,32 @@ async function processExplore(page, username, options, log) {
         );
       } else {
         locations = await Promise.all(
-          sampleUrls.map((url) => extractVideoLocation(url)),
+          sampleUrls.map(async (url) => {
+            try {
+              return await extractVideoLocation(url);
+            } catch (e) {
+              sampleFailCount++;
+              log(`  [采样] 视频查询失败: ${e.message}`);
+              return null;
+            }
+          }),
         );
       }
       log(
-        `  国家采样(${locations.length}个): [${locations.filter(Boolean).join(", ") || "无数据"}]`,
+        `  国家采样(${locations.length}个${sampleFailCount > 0 ? `, 查询失败${sampleFailCount}` : ""}): [${locations.filter(Boolean).join(", ") || "无数据"}]`,
       );
+
+      // 全部查询失败 ≠ 全部无数据：
+      // 通道故障（webserver 挂掉/超时、本地 Scraper 被封）时若按 done 无国家入库，
+      // 会陷入"无国家 → 2h 回炉 → 又全失败 → 又 done"的空转循环；
+      // 按 error 上报让任务回流重做，且面板可见
+      if (sampleUrls.length > 0 && sampleFailCount === sampleUrls.length) {
+        result.error = `国家采样全失败（${webserverUrl ? "webserver" : "本地Scraper"}通道 ${sampleFailCount}/${sampleUrls.length} 全失败）`;
+        result.errorStack = "";
+        result.processed = false;
+        log(`  [错误] ${result.error}，任务按错误回流`);
+        return result;
+      }
       // 直接标准化，不去重（保留重复值用于频率统计）
       const normalizedLocations = locations
         .map((loc) => normalizeLocation(loc))
@@ -353,6 +375,19 @@ async function processExplore(page, username, options, log) {
       log(`  @${username} CDN限流`);
     }
 
+    // 被判重试期间弹出验证码（api-interceptor 抛出 "验证码: username"）:
+    // 清掉 error 转验证码分支，让外层 CLI 走 captchaDetected 上报/等待人工解决流程
+    if (e.message.startsWith("验证码:")) {
+      result.error = null;
+      result.errorStack = "";
+      result.processed = false;
+      result.captchaDetected = true;
+      result.captchaStage = result.captchaStage || "video-page";
+      result.captchaMessage = result.captchaMessage || "被判重试期间弹出验证码";
+      log(`  @${username} 被判期间弹出验证码，转验证码处理`);
+      return result;
+    }
+
     // 临时性错误：超时、执行上下文销毁、网络异常 — 标记为可重试
     const retryablePatterns = [
       "Timeout",

package/src/videos/core.js

@@ -87,6 +87,11 @@ async function collectVideos(page, username, maxVideos, log) {
     if (e.message.startsWith("被封:")) {
       throw e; // 向上抛出，由 explore-core 处理
     }
+    // 被判重试期间弹出验证码会抛出 "验证码: username"，同样原样上抛
+    // （不能被包装成 "API 拦截失败"，否则上层识别不到前缀）
+    if (e.message.startsWith("验证码:")) {
+      throw e; // 向上抛出，由 explore-core 处理
+    }
     // CDN 限流会抛出 "CDN限流..." 异常（HTTP 路径 CDNBlockedError / CDP 路径 api-interceptor）
     if (e.message.startsWith("CDN限流")) {
       throw e; // 向上抛出，由 explore-core 处理