tt-help-cli-ycl 1.4.33 → 1.4.35

package/package.json

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

package/src/cli/explore.js

@@ -25,6 +25,7 @@ import {
 import { showResourceUsage } from "../utils/index.js";
 import { HealthChecker } from "../lib/browser/health-checker.js";
 import { createApiClient } from "../lib/api-client.js";
+import { createCDNHandler } from "../lib/cdn-handler.js";
 import path from "path";
 import os from "os";
 
@@ -245,9 +246,30 @@ export async function handleExplore(options) {
       lastFollowSuccessTime = Date.now(); // 切换账户后重置
       captchaCount = 0; // 重置验证码计数
       blockedCount = 0; // 重置被封计数
+      cdn.reset();
       consecutiveNetworkErrors = 0; // 重置网络错误计数
     }
 
+    // CDN 限流处理器（共享逻辑）
+    const cdn = createCDNHandler({
+      submitJob: (result, username) =>
+        apiPost(`${serverUrl}/api/job/${username}`, {
+          error: result.error || "CDN限流",
+        }),
+      reportError: (result, username) =>
+        withRetry("report cdn-blocked", () =>
+          apiPost(`${serverUrl}/api/error-report`, {
+            userId,
+            username,
+            errorType: "cdn_blocked",
+            errorMessage: result.error || "CDN限流 (Access Denied)",
+            stage: "process",
+            errorStack: result.errorStack || "",
+          }),
+        ),
+      switchAccount: (reason) => handleAccountSwitch(reason),
+    });
+
     let processedCount = 0;
     let errorCount = 0;
     let consecutiveNetworkErrors = 0;
@@ -377,6 +399,7 @@ export async function handleExplore(options) {
             location: exploreLocation,
             proxyServer: cdpOptions.proxyServer || null,
             browser,
+            shopPage,
           },
           console.error,
         );
@@ -414,6 +437,7 @@ export async function handleExplore(options) {
 
         if (result.restricted) {
           consecutiveNetworkErrors = 0;
+          cdn.reset();
           await apiPost(`${serverUrl}/api/job/${username}`, {
             restricted: true,
             userInfo: result.userInfo || {},
@@ -425,6 +449,14 @@ export async function handleExplore(options) {
           continue;
         }
 
+        // CDN 限流检测：渐进退避，避免快速空转消耗任务
+        if (result.cdnBlocked) {
+          consecutiveNetworkErrors++;
+          errorCount++;
+          await cdn.handle(result, username);
+          continue;
+        }
+
         if (result.error) {
           consecutiveNetworkErrors++;
           errorCount++;
@@ -516,6 +548,7 @@ export async function handleExplore(options) {
         }
 
         consecutiveNetworkErrors = 0;
+        cdn.reset();
 
         // 更新关注/粉丝成功时间（仅登录状态下）
         if (result.hasFollowData && result.keepFollow) {

package/src/cli/precheck.js

@@ -0,0 +1,425 @@
+import { TikTokScraper } from "../lib/tiktok-scraper.mjs";
+import { CDNBlockedError } from "../lib/parse-ssr.mjs";
+import {
+  proxy as configuredProxy,
+  userId as configuredUserId,
+  saveUserId,
+} from "../lib/constants.js";
+import { getMacOrUuid } from "../lib/mac-or-uuid.js";
+import { createApiClient } from "../lib/api-client.js";
+import { DEFAULT_TARGET_LOCATIONS } from "../lib/target-locations.js";
+import v8 from "node:v8";
+
+const HEAP_RESTART_RATIO = 0.72;
+const MAX_TASK_BATCHES_BEFORE_RESTART = 200;
+
+function formatNow() {
+  return new Date().toLocaleString("zh-CN", {
+    hour12: false,
+  });
+}
+
+function precheckLog(message = "") {
+  console.error(`[${formatNow()}] ${message}`);
+}
+
+function isBrowserClosedError(err) {
+  if (!err) return false;
+  const msg = err.message || err.toString() || "";
+  return (
+    msg.includes("Target page, context or browser has been closed") ||
+    msg.includes("browser has been closed") ||
+    msg.includes("browserContext.newPage") ||
+    msg.includes("Protocol error")
+  );
+}
+
+function getHeapUsage() {
+  const heapUsed = process.memoryUsage().heapUsed;
+  const heapLimit = v8.getHeapStatistics().heap_size_limit;
+  return {
+    heapUsed,
+    heapLimit,
+    ratio: heapLimit > 0 ? heapUsed / heapLimit : 0,
+  };
+}
+
+async function recycleScraper(scraper, reason) {
+  precheckLog(`[Precheck] ${reason}，正在重启浏览器实例...`);
+  await scraper.restart();
+  precheckLog("[Precheck] 浏览器实例重启完成");
+}
+
+export async function handlePrecheck(options) {
+  const {
+    precheckInterval = 60,
+    precheckMaxAge = 86400,
+    precheckParallel = 20,
+    precheckSize = 5,
+    precheckCountries,
+    serverUrl,
+    customProxy,
+    showHelp,
+  } = options;
+  const effectiveProxy = customProxy || configuredProxy;
+
+  if (showHelp) {
+    precheckLog(
+      "用法: tt-help precheck [-s 服务端地址] [-i 轮询间隔] [--max-age 过期阈值] [-p 并行数] [-c 国家列表] [--proxy 代理] [--size 池大小]",
+    );
+    precheckLog("");
+    precheckLog("参数:");
+    precheckLog(
+      "  -s, --server <URL>    服务端地址（默认: http://127.0.0.1:3001）",
+    );
+    precheckLog("  -i, --interval <N>    空闲轮询间隔，单位秒（默认: 60）");
+    precheckLog(
+      "  --max-age <N>         用户过期阈值，单位秒（默认: 86400 = 24小时）",
+    );
+    precheckLog("  -p, --parallel <N>    每批检测用户数（默认: 20）");
+    precheckLog("  --size <N>            浏览器页面池大小（默认: 5）");
+    precheckLog(
+      "  -c, --countries <A,B>  目标国家列表（默认: 使用内置目标国家）",
+    );
+    precheckLog("  --proxy <代理地址>     HTTP 代理地址");
+    precheckLog("");
+    precheckLog("说明:");
+    precheckLog(
+      "  从服务端拉取 refresh_time 超过 --max-age 的商家用户，HTTP 获取 videoCount 对比。",
+    );
+    precheckLog("  有更新 → 标记 pending_refresh=1（等待 refresh 客户端处理）");
+    precheckLog("  无更新 → 更新 refresh_time（跳过本轮）");
+    precheckLog("  支持多实例并行，服务端统一管理 DB。");
+    precheckLog("");
+    precheckLog("示例:");
+    precheckLog("  tt-help precheck -s http://127.0.0.1:3001");
+    precheckLog("  tt-help precheck --max-age 43200 -p 30 --size 5");
+    precheckLog("  tt-help precheck -c DE,ES,FR --proxy http://127.0.0.1:7890");
+    return;
+  }
+
+  const locations =
+    precheckCountries && precheckCountries.length > 0
+      ? precheckCountries
+      : DEFAULT_TARGET_LOCATIONS;
+
+  precheckLog(`[Precheck] 服务端: ${serverUrl}`);
+  precheckLog(
+    `[Precheck] 过期阈值: ${precheckMaxAge}秒 (${Math.round(precheckMaxAge / 3600)}小时), 轮询间隔: ${precheckInterval}秒`,
+  );
+  precheckLog(
+    `[Precheck] 每批数量: ${precheckParallel}, 页面池: ${precheckSize}`,
+  );
+  precheckLog(`[Precheck] 目标国家: ${locations.join(", ")}`);
+  if (effectiveProxy) {
+    precheckLog(`[Precheck] 代理: ${effectiveProxy}`);
+  }
+
+  // ── 设备标识 ──
+  let userId = configuredUserId;
+  if (!userId) {
+    userId = await getMacOrUuid();
+    saveUserId(userId);
+    precheckLog(`[Precheck] 未检测到本地用户编号，已生成并使用: ${userId}`);
+  }
+  precheckLog(`[Precheck] 用户编号: ${userId}`);
+
+  let shuttingDown = false;
+  let forceExitTimer = null;
+
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    forceExitTimer = setTimeout(() => {
+      precheckLog("[Precheck] 关闭超时，强制退出");
+      process.exit(0);
+    }, 10000);
+    forceExitTimer.unref?.();
+    precheckLog(`\n[Precheck] 收到 ${signal}，等待当前批次完成后退出...`);
+  };
+
+  process.on("SIGINT", () => {
+    void shutdown("SIGINT");
+  });
+  process.on("SIGTERM", () => {
+    void shutdown("SIGTERM");
+  });
+
+  try {
+    const { apiGet, apiPost } = createApiClient({ log: false });
+
+    const scraper = new TikTokScraper({
+      poolSize: precheckSize,
+      proxyServer: effectiveProxy || null,
+    });
+    await scraper.init();
+    precheckLog("[Precheck] 浏览器初始化完成，开始循环预检...");
+
+    let loopCount = 0;
+    let browserRestartCount = 0;
+    let taskBatchCount = 0;
+
+    while (!shuttingDown) {
+      loopCount++;
+
+      // 检查浏览器是否存活
+      if (!scraper.isAlive()) {
+        precheckLog(
+          `[Precheck] 浏览器已关闭，正在重启 (${++browserRestartCount})...`,
+        );
+        await scraper.restart();
+        precheckLog("[Precheck] 浏览器重启完成");
+      }
+
+      // 收到退出信号，完成清理
+      if (shuttingDown) {
+        precheckLog("[Precheck] 正在关闭浏览器...");
+        await scraper.close().catch(() => {});
+        if (forceExitTimer) {
+          clearTimeout(forceExitTimer);
+          forceExitTimer = null;
+        }
+        precheckLog("[Precheck] 已退出");
+        process.exit(0);
+      }
+
+      // 从服务端获取候选用户
+      const locationsParam = encodeURIComponent(locations.join(","));
+      const { candidates } = await apiGet(
+        `${serverUrl}/api/precheck-candidates?limit=${precheckParallel}&maxAge=${precheckMaxAge}&locations=${locationsParam}`,
+      );
+
+      // 收到退出信号，不再处理新任务
+      if (shuttingDown) {
+        precheckLog("[Precheck] 已收到退出信号，跳过本轮...");
+        await scraper.close().catch(() => {});
+        if (forceExitTimer) {
+          clearTimeout(forceExitTimer);
+          forceExitTimer = null;
+        }
+        precheckLog("[Precheck] 已退出");
+        process.exit(0);
+      }
+
+      if (!candidates || candidates.length === 0) {
+        const heap = getHeapUsage();
+        if (heap.ratio >= HEAP_RESTART_RATIO) {
+          await recycleScraper(
+            scraper,
+            `空闲时堆占用 ${(heap.ratio * 100).toFixed(1)}%`,
+          );
+        }
+        if (loopCount === 1) {
+          precheckLog(
+            `[Precheck] 当前无到期用户，${precheckInterval}秒后重试...`,
+          );
+        }
+        await new Promise((r) => {
+          const timer = setTimeout(r, precheckInterval * 1000);
+          // 可中断的等待：收到退出信号立即返回
+          const check = setInterval(() => {
+            if (shuttingDown) {
+              clearTimeout(timer);
+              clearInterval(check);
+              r();
+            }
+          }, 500);
+        });
+        continue;
+      }
+
+      precheckLog(
+        `\n[Precheck] 第 ${loopCount} 轮，${candidates.length} 个候选用户...`,
+      );
+      taskBatchCount++;
+
+      // 收到退出信号但已有任务在跑，完成当前批次
+      if (shuttingDown) {
+        precheckLog("[Precheck] 正在处理当前批次，完成后退出...");
+      }
+
+      const results = await Promise.allSettled(
+        candidates.map(async (candidate) => {
+          const uniqueId = candidate.uniqueId;
+          try {
+            const info = await scraper.getUserInfo(uniqueId);
+            return {
+              uniqueId,
+              info,
+              error: null,
+              storedVideoCount: candidate.videoCount,
+            };
+          } catch (err) {
+            return {
+              uniqueId,
+              info: null,
+              error: err,
+              storedVideoCount: candidate.videoCount,
+            };
+          }
+        }),
+      );
+
+      // 批次完成后检查退出信号
+      if (shuttingDown) {
+        precheckLog("[Precheck] 正在关闭浏览器...");
+        await scraper.close().catch(() => {});
+        if (forceExitTimer) {
+          clearTimeout(forceExitTimer);
+          forceExitTimer = null;
+        }
+        precheckLog("[Precheck] 已退出");
+        process.exit(0);
+      }
+
+      let needRefreshCount = 0;
+      let skipCount = 0;
+      let failCount = 0;
+      let cdnBlockedCount = 0;
+      let needRestart = false;
+
+      // 收集预检结果，批量提交
+      const batchResults = [];
+
+      for (const result of results) {
+        if (result.status !== "fulfilled") {
+          failCount++;
+          precheckLog(
+            `  ✗ 任务执行异常: ${result.reason?.message || "未知错误"}`,
+          );
+          continue;
+        }
+
+        const { uniqueId, info, error, storedVideoCount } = result.value;
+
+        if (error) {
+          if (error instanceof CDNBlockedError) {
+            precheckLog(`  ⚠ @${uniqueId} CDN限流 (Access Denied)`);
+            cdnBlockedCount++;
+          } else if (isBrowserClosedError(error)) {
+            needRestart = true;
+            precheckLog(`  ✗ @${uniqueId} 浏览器断开: ${error.message}`);
+          } else {
+            precheckLog(
+              `  ✗ @${uniqueId} 获取失败: ${error.message || "未知错误"}`,
+            );
+          }
+          failCount++;
+          continue;
+        }
+
+        if (!info) {
+          precheckLog(`  ✗ @${uniqueId} 未获取到用户信息`);
+          failCount++;
+          continue;
+        }
+
+        // 私有账号或异常状态：跳过，更新 refresh_time
+        if (info.error || info.statusCode !== 0) {
+          batchResults.push({
+            uniqueId,
+            needRefresh: false,
+            videoCount: info.videoCount,
+          });
+          skipCount++;
+          const statusTag = info.statusCode
+            ? ` (statusCode=${info.statusCode})`
+            : "";
+          precheckLog(`  - @${uniqueId} 跳过${statusTag}`);
+          continue;
+        }
+
+        const currentVideoCount = info.videoCount || 0;
+
+        if (currentVideoCount > storedVideoCount) {
+          batchResults.push({
+            uniqueId,
+            needRefresh: true,
+            videoCount: currentVideoCount,
+          });
+          needRefreshCount++;
+          precheckLog(
+            `  ✓ @${uniqueId} 有更新 (${storedVideoCount} → ${currentVideoCount})`,
+          );
+        } else {
+          batchResults.push({
+            uniqueId,
+            needRefresh: false,
+            videoCount: currentVideoCount,
+          });
+          skipCount++;
+        }
+      }
+
+      // 批量提交预检结果到服务端
+      if (batchResults.length > 0) {
+        try {
+          const submitRet = await apiPost(`${serverUrl}/api/precheck-results`, {
+            results: batchResults,
+          });
+          precheckLog(
+            `  提交: ${submitRet.saved || batchResults.length}/${batchResults.length} 条`,
+          );
+        } catch (err) {
+          precheckLog(`  ✗ 提交预检结果失败: ${err.message}`);
+        }
+      }
+
+      precheckLog(
+        `  本轮结果: ${needRefreshCount} 需刷新, ${skipCount} 跳过, ${failCount} 失败`,
+      );
+
+      // CDN 限流比例超过 30% 时，冷却 + 重启浏览器
+      const cdnRatio =
+        candidates.length > 0 ? cdnBlockedCount / candidates.length : 0;
+      if (cdnRatio > 0.3) {
+        const coolDownSeconds = cdnRatio > 0.8 ? 120 : 60;
+        precheckLog(
+          `  [Precheck] CDN限流比例 ${(cdnRatio * 100).toFixed(0)}% (${cdnBlockedCount}/${candidates.length})，冷却 ${coolDownSeconds} 秒后重启浏览器...`,
+        );
+        await new Promise((r) => setTimeout(r, coolDownSeconds * 1000));
+        await recycleScraper(
+          scraper,
+          `CDN限流比例过高 (${cdnBlockedCount}/${candidates.length})`,
+        );
+        browserRestartCount++;
+        taskBatchCount = 0;
+      }
+
+      const heap = getHeapUsage();
+      if (heap.ratio >= HEAP_RESTART_RATIO) {
+        await recycleScraper(
+          scraper,
+          `本批后堆占用 ${(heap.ratio * 100).toFixed(1)}%`,
+        );
+        browserRestartCount++;
+        taskBatchCount = 0;
+      } else if (taskBatchCount >= MAX_TASK_BATCHES_BEFORE_RESTART) {
+        await recycleScraper(scraper, `已连续处理 ${taskBatchCount} 批任务`);
+        browserRestartCount++;
+        taskBatchCount = 0;
+      }
+
+      if (needRestart) {
+        precheckLog("[Precheck] 检测到浏览器异常，将在下一轮重启...");
+      }
+
+      // 批次间短暂休息
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  } catch (err) {
+    precheckLog(`[Precheck] 运行异常: ${err.message}`);
+    throw err;
+  } finally {
+    if (forceExitTimer) {
+      clearTimeout(forceExitTimer);
+      forceExitTimer = null;
+    }
+    process.removeListener("SIGINT", () => {
+      void shutdown("SIGINT");
+    });
+    process.removeListener("SIGTERM", () => {
+      void shutdown("SIGTERM");
+    });
+  }
+}

package/src/cli/refresh.js

@@ -24,6 +24,7 @@ import {
 } from "../lib/browser/cdp.js";
 import { HealthChecker } from "../lib/browser/health-checker.js";
 import { createApiClient } from "../lib/api-client.js";
+import { createCDNHandler } from "../lib/cdn-handler.js";
 import path from "path";
 import os from "os";
 
@@ -245,9 +246,30 @@ export async function handleRefresh(options) {
       lastFollowSuccessTime = Date.now();
       captchaCount = 0;
       blockedCount = 0;
+      cdn.reset();
       consecutiveNetworkErrors = 0;
     }
 
+    // CDN 限流处理器（共享逻辑）
+    const cdn = createCDNHandler({
+      submitJob: (result, username) =>
+        apiPost(`${serverUrl}/api/redo-job/${username}`, {
+          error: result.error || "CDN限流",
+        }),
+      reportError: (result, username) =>
+        withRetry("report cdn-blocked", () =>
+          apiPost(`${serverUrl}/api/error-report`, {
+            userId,
+            username,
+            errorType: "cdn_blocked",
+            errorMessage: result.error || "CDN限流 (Access Denied)",
+            stage: "process",
+            errorStack: result.errorStack || "",
+          }),
+        ),
+      switchAccount: (reason) => handleAccountSwitch(reason),
+    });
+
     let processedCount = 0;
     let errorCount = 0;
     let consecutiveNetworkErrors = 0;
@@ -426,6 +448,7 @@ export async function handleRefresh(options) {
 
       if (result.restricted) {
         consecutiveNetworkErrors = 0;
+        cdn.reset();
         await apiPost(`${serverUrl}/api/redo-job/${username}`, {
           restricted: true,
           userInfo: result.userInfo || {},
@@ -437,6 +460,14 @@ export async function handleRefresh(options) {
         continue;
       }
 
+      // CDN 限流检测：渐进退避，避免快速空转消耗任务
+      if (result.cdnBlocked) {
+        consecutiveNetworkErrors++;
+        errorCount++;
+        await cdn.handle(result, username);
+        continue;
+      }
+
       if (result.error) {
         consecutiveNetworkErrors++;
         errorCount++;
@@ -526,6 +557,7 @@ export async function handleRefresh(options) {
       }
 
       consecutiveNetworkErrors = 0;
+      cdn.reset();
 
       // 更新关注/粉丝成功时间
       if (result.hasFollowData && result.keepFollow) {

package/src/lib/api-interceptor.js

@@ -222,6 +222,10 @@ async function fetchUserVideosAPI(page, username, maxVideos, log) {
     throw new Error(`被封: ${username}`);
   }
 
+  if (pageError === "cdn_blocked") {
+    throw new Error(`CDN限流: ${username}`);
+  }
+
   if (pageError) {
     log(`  [API拦截] 数据为空，识别到页面错误: ${pageError}`);
     return new Map();

package/src/lib/args.js

@@ -690,6 +690,61 @@ function parseRecheckArgs(args) {
   };
 }
 
+function parsePrecheckArgs(args) {
+  let serverUrl = defaultServer;
+  let precheckInterval = 60;
+  let precheckMaxAge = 86400;
+  let precheckParallel = 20;
+  let precheckSize = 5;
+  let precheckCountries = null;
+  let customProxy = null;
+  let showHelp = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-s" || arg === "--server") {
+      serverUrl = args[++i];
+    } else if (arg === "-i" || arg === "--interval") {
+      precheckInterval = parseInt(args[++i], 10) || 60;
+    } else if (arg === "--max-age") {
+      precheckMaxAge = parseInt(args[++i], 10) || 86400;
+    } else if (arg === "-p" || arg === "--parallel") {
+      precheckParallel = parseInt(args[++i], 10) || 20;
+    } else if (arg === "--size") {
+      precheckSize = parseInt(args[++i], 10) || 5;
+    } else if (arg === "-c" || arg === "--countries") {
+      precheckCountries = args[++i]
+        .split(",")
+        .map((c) => c.trim().toUpperCase())
+        .filter(Boolean);
+    } else if (arg === "--proxy") {
+      customProxy = args[++i];
+    } else if (arg === "--help" || arg === "-h") {
+      showHelp = true;
+    }
+  }
+
+  return {
+    subcommand: "precheck",
+    serverUrl,
+    precheckInterval,
+    precheckMaxAge,
+    precheckParallel,
+    precheckSize,
+    precheckCountries,
+    customProxy,
+    showHelp,
+    urls: [],
+    outputFormat: "json",
+    exploreCount: 0,
+    showConfig: false,
+    configAction: null,
+    configValue: null,
+    pipeMode: false,
+    filterStr: null,
+  };
+}
+
 function parseOpenArgs(args) {
   let openPort = null;
   let openList = false;
@@ -1227,6 +1282,10 @@ export function parseArgs() {
     return parseRawSyncArgs(args.slice(1));
   }
 
+  if (args.length > 0 && args[0] === "precheck") {
+    return parsePrecheckArgs(args.slice(1));
+  }
+
   const urls = [];
   let inputFile = null;
   let outputFile = null;

package/src/lib/cdn-handler.js

@@ -0,0 +1,49 @@
+/**
+ * CDN 限流处理器（explore / refresh 共用）
+ *
+ * 用法：
+ *   const cdn = createCDNHandler({ submitJob, reportError, switchAccount });
+ *
+ *   // 重置（切换账户后 / 任务成功后）
+ *   cdn.reset();
+ *
+ *   // 处理 CDN 限流
+ *   if (result.cdnBlocked) {
+ *     await cdn.handle(result, username);
+ *     continue;
+ *   }
+ */
+
+const THRESHOLD = 3;
+
+export function createCDNHandler({
+  submitJob,
+  reportError,
+  switchAccount,
+  log = console.error,
+}) {
+  let count = 0;
+
+  return {
+    reset() {
+      count = 0;
+    },
+
+    async handle(result, username) {
+      count++;
+
+      const waitSec = count <= 1 ? 30 : count <= 2 ? 60 : 120;
+      log(`  [CDN限流] 第 ${count} 次，等待 ${waitSec}s...`);
+
+      await submitJob(result, username).catch(() => {});
+      await reportError(result, username).catch(() => {});
+
+      await new Promise((r) => setTimeout(r, waitSec * 1000));
+
+      if (count >= THRESHOLD) {
+        log(`  [CDN限流] 累计 ${count} 次，切换账户...`);
+        await switchAccount(`CDN限流累计 ${count} 次`);
+      }
+    },
+  };
+}

package/src/lib/constants.js

@@ -160,6 +160,22 @@ const HELP_TEXT = [
   "      --user-id <编号>          客户端编号（设备ID），默认自动生成",
   "--proxy <地址>            浏览器代理（如 socks5://127.0.0.1:1080），未指定时使用配置文件 proxy",
   "",
+  "  tt-help precheck [选项]",
+  "    对目标商家用户进行轻量预检，通过 HTTP 获取 videoCount 判断是否有新视频",
+  "    有更新 → 标记 pending_refresh=1（等待 refresh 客户端完整采集）",
+  "    无更新 → 更新 refresh_time（跳过本轮，24h 后重新检查）",
+  "    选项:",
+  "      -s, --server <URL>        服务端地址，默认 http://127.0.0.1:3001",
+  "      -i, --interval <秒数>     空闲轮询间隔，默认 60 秒",
+  "      --max-age <秒数>          用户过期阈值，默认 86400（24小时）",
+  "      -p, --parallel <数量>     每批检测用户数，默认 20",
+  "      --size <数量>             浏览器页面池大小，默认 5",
+  `      -c, --countries <国家>    目标国家列表，逗号分隔，默认 ${DEFAULT_TARGET_LOCATIONS_CSV}`,
+  "      --proxy <地址>            HTTP 代理（如 http://127.0.0.1:7890）",
+  "    示例: tt-help precheck -s http://127.0.0.1:3001",
+  "          tt-help precheck -i 60 --max-age 86400 -p 20 -c DE,ES,FR",
+  "          tt-help precheck --proxy http://127.0.0.1:7890",
+  "",
   "  tt-help info <URL> [URL2 ...] [--onlyvideo]",
   "    获取用户/视频信息，支持多个 URL",
   "    主页 URL      → 返回用户信息",

package/src/lib/page-error-detector.js

@@ -52,29 +52,31 @@ const PATTERNS = {
     "找不到此账号",
   ],
   service_error: ["出错了", "很抱歉"],
+  cdn_blocked: [
+    "Access Denied",
+    "Reference #",
+    "You don't have permission to access",
+  ],
 };
 
 export async function detectPageError(page, timeout = 10000) {
   try {
-    return await page.evaluate(
-      (patterns) => {
-        const body = document.body;
-        if (!body) return null;
-        const bodyText = body.innerText;
-        const lower = bodyText.toLowerCase();
+    return await page.evaluate((patterns) => {
+      const body = document.body;
+      if (!body) return null;
+      const bodyText = body.innerText;
+      const lower = bodyText.toLowerCase();
 
-        for (const [type, phrases] of Object.entries(patterns)) {
-          for (const phrase of phrases) {
-            if (lower.includes(phrase.toLowerCase())) {
-              return type;
-            }
+      for (const [type, phrases] of Object.entries(patterns)) {
+        for (const phrase of phrases) {
+          if (lower.includes(phrase.toLowerCase())) {
+            return type;
           }
         }
+      }
 
-        return null;
-      },
-      PATTERNS,
-    );
+      return null;
+    }, PATTERNS);
   } catch (e) {
     // CDP 断连或超时：返回 null 而非永久挂起
     if (

package/src/main.js

@@ -12,6 +12,7 @@ import { handleVideoStats } from "./cli/videostats.js";
 import { handleDbImport } from "./cli/db-import.js";
 import { handleWebserver } from "./cli/webserver.js";
 import { handleRefresh } from "./cli/refresh.js";
+import { handlePrecheck } from "./cli/precheck.js";
 import {
   handleTag,
   handleDiscover,
@@ -48,6 +49,8 @@ async function main() {
       return handleDbImport(parsed);
     case "refresh":
       return handleRefresh(parsed);
+    case "precheck":
+      return handlePrecheck(parsed);
     case "tag":
       return handleTag(parsed);
     case "raw-sync":

package/src/npm-main.js

@@ -8,6 +8,7 @@ import { handleConfig, showConfig, showUsage, version } from "./cli/config.js";
 import { handleOpen } from "./cli/open.js";
 import { handleComments } from "./cli/comments.js";
 import { handleRefresh } from "./cli/refresh.js";
+import { handlePrecheck } from "./cli/precheck.js";
 import {
   handleTag,
   handleDiscover,
@@ -48,6 +49,8 @@ async function main() {
       return handleComments(parsed);
     case "refresh":
       return handleRefresh(parsed);
+    case "precheck":
+      return handlePrecheck(parsed);
     case "tag":
       return handleTag(parsed);
     case "tag-discover":

package/src/scraper/explore-core.js

@@ -46,6 +46,7 @@ async function processExplore(page, username, options, log) {
     productDetail: null,
     noVideo: false,
     restricted: false,
+    cdnBlocked: false,
     error: null,
   };
 
@@ -129,15 +130,8 @@ async function processExplore(page, username, options, log) {
       };
 
       // 如果有商品链接，抓取商品详情页（评分、销量等）
-      if (topVideo.seoUrl && options.shopPage) {
+      if (topVideo.seoUrl && options.shopPage && !options.shopPage.isClosed()) {
         try {
-          // 检查 shopPage 是否被关闭（浏览器切换账号等），尝试恢复
-          if (options.shopPage.isClosed()) {
-            const ctx = page.context();
-            options.shopPage = await ctx.newPage();
-            log(`  [商品页] 已恢复 shopPage`);
-          }
-
           const { getProductInfoCDP } = await import("../lib/shop-scraper.mjs");
           const shopUrl = topVideo.seoUrl.replace(
             "www.tiktok.com/shop/pdp",
@@ -303,6 +297,13 @@ async function processExplore(page, username, options, log) {
       log(`  @${username} 认定为被封`);
     }
 
+    // CDN 限流（HTTP 路径: "CDN限流 (Access Denied...)"，CDP 路径: "CDN限流: username"）
+    if (e.message.startsWith("CDN限流")) {
+      result.processed = false;
+      result.cdnBlocked = true;
+      log(`  @${username} CDN限流`);
+    }
+
     // 临时性错误：超时、执行上下文销毁、网络异常 — 标记为可重试
     const retryablePatterns = [
       "Timeout",

package/src/videos/core.js

@@ -87,6 +87,10 @@ async function collectVideos(page, username, maxVideos, log) {
     if (e.message.startsWith("被封:")) {
       throw e; // 向上抛出，由 explore-core 处理
     }
+    // CDN 限流会抛出 "CDN限流..." 异常（HTTP 路径 CDNBlockedError / CDP 路径 api-interceptor）
+    if (e.message.startsWith("CDN限流")) {
+      throw e; // 向上抛出，由 explore-core 处理
+    }
     // 其他异常也向上抛出
     throw new Error(`API 拦截失败：@${username} ${e.message}`);
   }

package/src/watch/data-store.js

@@ -2162,9 +2162,10 @@ export function createStore(filePath, options = {}) {
           FROM jobs
           WHERE tt_seller = 1
             AND verified = 0
+            AND (pending_refresh IS NULL OR pending_refresh = 1)
             AND location_created IN (${placeholders})
-            AND COALESCE(refresh_time, ?) < ?
-          ORDER BY COALESCE(pinned, 0) DESC, COALESCE(refresh_time, ?) ASC
+            AND (pending_refresh = 1 OR COALESCE(refresh_time, ?) < ?)
+          ORDER BY COALESCE(pinned, 0) DESC, pending_refresh DESC, COALESCE(refresh_time, ?) ASC
           LIMIT 1
         `,
         )
@@ -2192,21 +2193,27 @@ export function createStore(filePath, options = {}) {
       (u) =>
         u.ttSeller &&
         u.verified === false &&
+        u.pendingRefresh !== false &&
         targetLocations.includes(u.locationCreated),
     );
     if (targetUsers.length === 0) return null;
 
     const recentEnough = targetUsers.filter((u) => {
+      // pendingRefresh=true（需刷新）的用户跳过时间窗口限制
+      if (u.pendingRefresh === true) return true;
       const rt = u.refreshTime || defaultTime;
       return rt < threshold;
     });
     if (recentEnough.length === 0) return null;
 
     recentEnough.sort((a, b) => {
-      // pinned 优先，其次按 refreshTime 升序
+      // pinned 优先，其次 pendingRefresh=true 优先，再按 refreshTime 升序
       if ((a.pinned ? 1 : 0) !== (b.pinned ? 1 : 0)) {
         return (b.pinned ? 1 : 0) - (a.pinned ? 1 : 0);
       }
+      if ((a.pendingRefresh ? 1 : 0) !== (b.pendingRefresh ? 1 : 0)) {
+        return (b.pendingRefresh ? 1 : 0) - (a.pendingRefresh ? 1 : 0);
+      }
       const ta = a.refreshTime || defaultTime;
       const tb = b.refreshTime || defaultTime;
       return ta - tb;
@@ -2227,6 +2234,7 @@ export function createStore(filePath, options = {}) {
       const user = getJob(uniqueId);
       if (!user) return { saved: false, error: "user not found" };
       user.refreshTime = Date.now();
+      user.pendingRefresh = false;
       if (result.userInfo) {
         const info = result.userInfo;
         for (const key of Object.keys(info)) {
@@ -2275,6 +2283,7 @@ export function createStore(filePath, options = {}) {
     if (!user) return { saved: false, error: "user not found" };
 
     user.refreshTime = Date.now();
+    user.pendingRefresh = false;
 
     if (result.userInfo) {
       const info = result.userInfo;
@@ -2314,6 +2323,83 @@ export function createStore(filePath, options = {}) {
     return { saved: true, newUsers };
   }
 
+  function getPrecheckCandidates({
+    limit = 50,
+    intervalSeconds = 86400,
+    locations = null,
+  }) {
+    if (!getDb()) return [];
+    const now = Date.now();
+    const threshold = now - intervalSeconds * 1000;
+    const defaultTime = new Date("2016-01-01T00:00:00Z").getTime();
+    const targetLocations = locations || DEFAULT_TARGET_LOCATIONS;
+    const placeholders = targetLocations.map(() => "?").join(",");
+
+    // 事务：SELECT + 立即 UPDATE refresh_time，防止多客户端重复领取
+    const rows = getDb().transaction(() => {
+      const selected = getDb()
+        .prepare(
+          `
+        SELECT unique_id, nickname, video_count, COALESCE(refresh_time, ?) AS refresh_time
+        FROM jobs
+        WHERE tt_seller = 1
+          AND verified = 0
+          AND (pending_refresh IS NULL OR pending_refresh = 0)
+          AND location_created IN (${placeholders})
+          AND COALESCE(refresh_time, ?) < ?
+        ORDER BY COALESCE(refresh_time, ?) ASC
+        LIMIT ?
+      `,
+        )
+        .all(
+          defaultTime,
+          ...targetLocations,
+          defaultTime,
+          threshold,
+          defaultTime,
+          limit,
+        );
+
+      if (selected.length > 0) {
+        const ids = selected.map((r) => r.unique_id);
+        const idPlaceholders = ids.map(() => "?").join(",");
+        getDb()
+          .prepare(
+            `UPDATE jobs SET refresh_time = ?, updated_at = ? WHERE unique_id IN (${idPlaceholders})`,
+          )
+          .run(now, now, ...ids);
+      }
+
+      return selected;
+    })();
+
+    return rows.map((r) => ({
+      uniqueId: r.unique_id,
+      nickname: r.nickname,
+      videoCount: r.video_count || 0,
+      refreshTime: r.refresh_time,
+    }));
+  }
+
+  function markPrecheckResult(uniqueId, { needRefresh, videoCount }) {
+    if (!getDb()) return { saved: false, error: "no db" };
+    const now = Date.now();
+    if (needRefresh) {
+      getDb()
+        .prepare(
+          "UPDATE jobs SET pending_refresh = 1, video_count = ?, refresh_time = ?, updated_at = ? WHERE unique_id = ?",
+        )
+        .run(videoCount ?? null, now, now, uniqueId);
+    } else {
+      getDb()
+        .prepare(
+          "UPDATE jobs SET pending_refresh = 0, video_count = ?, refresh_time = ?, updated_at = ? WHERE unique_id = ?",
+        )
+        .run(videoCount ?? null, now, now, uniqueId);
+    }
+    return { saved: true };
+  }
+
   function reportClientError(
     userId,
     errorType,
@@ -3297,6 +3383,8 @@ export function createStore(filePath, options = {}) {
     togglePin,
     getNextRedoJob,
     commitRedoJob,
+    getPrecheckCandidates,
+    markPrecheckResult,
     getPendingUserUpdateTasks,
     getRecheckJobs,
     batchUpdateRecheckJobs,

package/src/watch/db-columns.js

@@ -33,6 +33,7 @@ export const JOB_CORE_COLUMNS = [
   "refresh_time",
   "processed",
   "processed_at",
+  "pending_refresh",
   "created_at",
   "updated_at",
   "region",
@@ -100,6 +101,7 @@ export const WRITABLE_JOB_COLUMNS = new Set([
   "product_name",
   "user_create_time",
   "recent_ec_videos",
+  "pending_refresh",
 ]);
 
 // ===== Boolean 列（存储时 0/1，读取时转为 true/false/null） =====
@@ -110,6 +112,7 @@ export const JOB_BOOLEAN_COLUMNS = new Set([
   "processed",
   "tt_seller",
   "verified",
+  "pending_refresh",
   "error",
 ]);
 

package/src/watch/db-raw-jobs.js

@@ -44,7 +44,7 @@ export function moveJobsToRawByCountry(scope, country) {
   let scopeWhere = "";
 
   if (normalizedScope === "pending") {
-    sourceTable = "jobs";
+    sourceTable = "task_queue";
     scopeWhere = `status = 'pending'`;
   } else if (normalizedScope === "userUpdate") {
     sourceTable = "jobs_base";

package/src/watch/db-schema.js

@@ -111,6 +111,7 @@ export function initDb(filePath) {
       refresh_time INTEGER,
       processed INTEGER DEFAULT 0,
       processed_at INTEGER,
+      pending_refresh INTEGER DEFAULT 1,
       created_at INTEGER,
       updated_at INTEGER,
       region TEXT,
@@ -120,6 +121,7 @@ export function initDb(filePath) {
     )
   `);
   migrateColumns("jobs", {
+    pending_refresh: "INTEGER",
     status_code: "INTEGER",
     latest_video_time: "INTEGER",
     confirmed_location: "TEXT",
@@ -155,6 +157,7 @@ export function initDb(filePath) {
   }
   // 后续迁移也要给 task_queue 补列
   migrateColumns("task_queue", {
+    pending_refresh: "INTEGER",
     status_code: "INTEGER",
     latest_video_time: "INTEGER",
     confirmed_location: "TEXT",
@@ -202,6 +205,7 @@ export function initDb(filePath) {
       refresh_time INTEGER,
       processed INTEGER DEFAULT 0,
       processed_at INTEGER,
+      pending_refresh INTEGER DEFAULT 1,
       created_at INTEGER,
       updated_at INTEGER,
       region TEXT,
@@ -213,6 +217,7 @@ export function initDb(filePath) {
     )
   `);
   migrateColumns("jobs_base", {
+    pending_refresh: "INTEGER",
     status_code: "INTEGER",
     latest_video_time: "INTEGER",
     confirmed_location: "TEXT",

package/src/watch/public/app.js

@@ -286,6 +286,7 @@ function renderActiveClients(clients) {
   const types = [
     "explore",
     "refresh",
+    "precheck",
     "attach",
     "recheck",
     "comments",
@@ -296,6 +297,7 @@ function renderActiveClients(clients) {
   const labels = {
     explore: "Explore",
     refresh: "Refresh",
+    precheck: "Precheck",
     attach: "Attach",
     recheck: "Recheck",
     comments: "Comments",

package/src/watch/server.js

@@ -151,6 +151,7 @@ function sendCSV(res, columns, rows) {
 }
 
 function inferClientType(routePath) {
+  if (routePath.startsWith("/api/precheck")) return "precheck";
   if (routePath.startsWith("/api/redo-job")) return "refresh";
   if (routePath.startsWith("/api/user-update-tasks")) return "attach";
   if (routePath.startsWith("/api/recheck-jobs")) return "recheck";
@@ -843,6 +844,52 @@ export function startWatchServer(
         return;
       }
 
+      if (req.method === "GET" && routePath === "/api/precheck-candidates") {
+        const limit = parseInt(params.limit) || 50;
+        const maxAge = parseInt(params.maxAge) || 86400;
+        const locationsParam = params.locations || "";
+        const locations = locationsParam
+          ? locationsParam
+              .split(",")
+              .map((s) => s.trim().toUpperCase())
+              .filter(Boolean)
+          : null;
+        const candidates = store.getPrecheckCandidates({
+          limit,
+          intervalSeconds: maxAge,
+          locations,
+        });
+        const ts = new Date().toLocaleTimeString("zh-CN", { hour12: false });
+        console.error(
+          `[JOB ${ts}] PRECHECK-CANDIDATES: ${candidates.length} candidates (maxAge=${maxAge}s, limit=${limit})`,
+        );
+        sendJSON(res, 200, { candidates });
+        return;
+      }
+
+      if (req.method === "POST" && routePath === "/api/precheck-results") {
+        try {
+          const body = await readBody(req);
+          const results = body.results || [];
+          let saved = 0;
+          for (const r of results) {
+            const ret = store.markPrecheckResult(r.uniqueId, {
+              needRefresh: r.needRefresh,
+              videoCount: r.videoCount,
+            });
+            if (ret.saved) saved++;
+          }
+          const ts = new Date().toLocaleTimeString("zh-CN", { hour12: false });
+          console.error(
+            `[JOB ${ts}] PRECHECK-RESULTS: ${saved}/${results.length} saved`,
+          );
+          sendJSON(res, 200, { saved, total: results.length });
+        } catch (e) {
+          sendJSON(res, 400, { error: e.message });
+        }
+        return;
+      }
+
       if (req.method === "GET" && routePath === "/api/user-update-tasks") {
         const limit = params.limit;
         const countries = params.countries