tt-help-cli-ycl 1.4.153 → 1.4.154

package/package.json

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

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

@@ -16,8 +16,13 @@ function check(name, ok, detail = "") {
 }
 
 // 429 + 页面有验证码容器
-function make429CaptchaPage(username) {
+// captchaPhase 控制验证码何时出现：
+//   "instant"  → 首次检测时已渲染（进分支 5s 检测命中）
+//   "delayed"  → 首次检测时未渲染，进入重试等待后才出现（sleep 醒来后 3s 检测命中）
+//   "never"    → 不出现（走正常被封重试）
+function make429CaptchaPage(username, captchaPhase = "instant") {
   let gotoCount = 0;
+  let captchaDelayElapsed = false;
   const page = {
     _handlers: {},
     on(event, fn) {
@@ -33,12 +38,16 @@ function make429CaptchaPage(username) {
       gotoCount++;
     },
     // checkCdpHealth 用 () => document.readyState（fn.length===0）→ "complete"
-    // detectCaptcha 用 () => {...}（fn.length===0，通过 captchaVisible 开关控制返回值）
-    _captchaVisible: true,
+    // detectCaptcha/detectCaptchaWithWait 通过 captchaDelayElapsed 开关控制
+    _captchaVisible() {
+      if (captchaPhase === "never") return false;
+      if (captchaPhase === "instant") return true;
+      return captchaDelayElapsed; // delayed：等待后才可见
+    },
     evaluate: async (fn) => {
       if (
-        page._captchaVisible &&
-        fn.toString().includes("captcha-verify-container")
+        fn.toString().includes("captcha-verify-container") &&
+        page._captchaVisible()
       ) {
         return {
           exists: true,
@@ -50,8 +59,18 @@ function make429CaptchaPage(username) {
       if (fn.length === 1) return null;
       return "complete";
     },
+    waitForFunction: async (fn, opts) => {
+      // 带等待检测：轮询语义——可见即返回 handle，否则等满 timeout 返回 null
+      const deadline = Date.now() + (opts?.timeout || 5000);
+      while (Date.now() < deadline) {
+        if (page._captchaVisible()) {
+          return { jsonValue: async () => true };
+        }
+        await new Promise((r) => setTimeout(r, 5));
+      }
+      return null;
+    },
     reload: async () => {},
-    waitForFunction: async () => null,
     waitForResponse: async (pred) => {
       const resp = {
         url: () => "https://www.tiktok.com/api/post/item_list/?...",
@@ -68,34 +87,61 @@ function make429CaptchaPage(username) {
     get gotoCount() {
       return gotoCount;
     },
+    // 测试钩子：标记 delayed 验证码已出现
+    _markCaptchaDelayed() {
+      captchaDelayElapsed = true;
+    },
   };
   return page;
 }
 
-// 用例1：429 + 验证码可见 → 立即抛 "验证码:"，只 goto 1 次（无重试）
+// 用例1：429 + 验证码立即可见 → 首次检测命中，只 goto 1 次（无重试）
 {
-  const page = make429CaptchaPage("fumolbbf08o");
+  const page = make429CaptchaPage("fumolbbf08o", "instant");
   try {
     await fetchUserVideosAPI(page, "fumolbbf08o", 5, () => {});
-    check("429+验证码 立即转验证码", false, "未抛错");
+    check("429+验证码(即时) 立即转验证码", false, "未抛错");
   } catch (e) {
     check(
-      "429+验证码 立即转验证码",
+      "429+验证码(即时) 立即转验证码",
       e.message === "验证码: fumolbbf08o",
       `抛错 "${e.message}"`,
     );
   }
   check(
-    "429+验证码 不再重试（仅 1 次 goto）",
+    "429+验证码(即时) 不再重试（仅 1 次 goto）",
     page.gotoCount === 1,
     `goto 次数 = ${page.gotoCount}`,
   );
 }
 
-// 用例2：429 + 验证码不可见 → 仍走正常被封重试，最终抛 "被封:"
+// 用例2（核心场景）：429 首检时验证码未渲染 → 重试等待期间弹出
+// → sleep 醒来后的检测必须抓住它（下次 goto 冲掉前），抛 "验证码:"
+{
+  const page = make429CaptchaPage("fumolbbf08o", "delayed");
+  // 在 waitForFunction 轮询到 captchaDelayElapsed=false 一轮后标记出现，
+  // 模拟"等待期渲染"：用 setTimeout 在重试 sleep 期间触发
+  setTimeout(() => page._markCaptchaDelayed(), 50);
+  try {
+    await fetchUserVideosAPI(page, "fumolbbf08o", 5, () => {});
+    check("等待期间弹出的验证码 被醒来检测抓住", false, "未抛错");
+  } catch (e) {
+    check(
+      "等待期间弹出的验证码 被醒来检测抓住",
+      e.message === "验证码: fumolbbf08o",
+      `抛错 "${e.message}"，goto ${page.gotoCount} 次`,
+    );
+  }
+  check(
+    "醒来检测抓住时未再发起下一轮 goto（goto ≤ 2）",
+    page.gotoCount <= 2,
+    `goto 次数 = ${page.gotoCount}`,
+  );
+}
+
+// 用例3：429 + 验证码始终不出现 → 走正常被封重试，最终抛 "被封:"
 {
-  const page = make429CaptchaPage("fumolbbf08o");
-  page._captchaVisible = false;
+  const page = make429CaptchaPage("fumolbbf08o", "never");
   try {
     await fetchUserVideosAPI(page, "fumolbbf08o", 5, () => {});
     check("429无验证码 仍按被封重试", false, "未抛错");
@@ -108,15 +154,11 @@ function make429CaptchaPage(username) {
   }
 }
 
-// 用例3：429 + detectCaptcha 本身抛异常（页面上下文销毁）→ 忽略，按被封重试
+// 用例4：429 + waitForFunction/检测本身抛异常（上下文销毁）→ 忽略，按被封重试
 {
-  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";
+  const page = make429CaptchaPage("fumolbbf08o", "never");
+  page.waitForFunction = async () => {
+    throw new Error("Execution context was destroyed");
   };
   try {
     await fetchUserVideosAPI(page, "fumolbbf08o", 5, () => {});

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 {
@@ -578,7 +579,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 ? "（被判后弹出）" : ""}`,

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/scraper/modules/captcha-handler.js

@@ -17,6 +17,29 @@ 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');