tt-help-cli-ycl 1.4.183 → 1.4.185

package/package.json

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

package/scripts/test-candidate-retry.mjs

@@ -0,0 +1,496 @@
+/**
+ * 候选注入失败「原号重试」改造（客户端 explore.js/search.js）单测：
+ *
+ * 背景：f11 节点 48h 实测 8208 条注入验证失败，~17% 为瞬态环境失败
+ * （page.goto 超时 / AbortError / net::ERR_* / Execution context destroyed / 无账号数据），
+ * 0 条会话过期。改造前对非崩溃失败一律立即弃号换下一个候选，网络劣化窗口
+ * 会连续烧掉 5 个候选且全死于同一环境。
+ *
+ * 覆盖：
+ * A. isDeterministicAccountFailure（确定性号死：会话过期/身份不符）
+ * B. isRetryableInjectFailure（瞬态/环境失败白名单谓词）
+ * C. decideCandidateInjectAction（三路分流决策：崩溃优先熔断 > 瞬态重试 > 其余弃号）
+ * D. retryRestoreOnNavFailure 驱动 + onRetry 钩子（注入式，纯逻辑）
+ *    D1. 瞬态失败重试 2 次后成功（共 3 次尝试）
+ *    D2. 3 次全败（attempts=3 后停止）
+ *    D3/D4. 会话过期 / 身份不符零重试
+ *    D5. 崩溃签名不进重试（驱动层兜底；熔断分流由 C 节保证）
+ *    D6. shouldAbort 中断
+ * E. 候选循环小模型（与 switchPoolAccount 同构）：验证租约保持在手 / 弃号时机 /
+ *    崩溃中止循环 / acquire 次数不虚增
+ *
+ * 运行：node scripts/test-candidate-retry.mjs
+ */
+import {
+  CANDIDATE_INJECT_MAX_RETRIES,
+  CANDIDATE_INJECT_DELAY_MS,
+  isDeterministicAccountFailure,
+  isRetryableInjectFailure,
+  decideCandidateInjectAction,
+  retryRestoreOnNavFailure,
+} from "../src/lib/login-pool-client.js";
+import { isBrowserClosedError } from "../src/lib/browser/page.js";
+
+let pass = 0;
+let fail = 0;
+
+function assert(cond, label) {
+  if (cond) {
+    pass++;
+    console.error(`  ✓ ${label}`);
+  } else {
+    fail++;
+    console.error(`  ✗ ${label}`);
+  }
+}
+
+const TRANSIENT_TIMEOUT = "page.goto: Timeout 30000ms exceeded.";
+const TRANSIENT_NET = "page.goto: net::ERR_TIMED_OUT at https://www.tiktok.com";
+
+// ── A. isDeterministicAccountFailure ──
+{
+  console.error("\n[A] isDeterministicAccountFailure 确定性号死");
+  assert(isDeterministicAccountFailure("会话过期") === true, "「会话过期」命中");
+  assert(
+    isDeterministicAccountFailure("身份不符（期望 @a，实际 @b）") === true,
+    "「身份不符（…）」命中（含前后缀文案）",
+  );
+  assert(
+    isDeterministicAccountFailure(TRANSIENT_TIMEOUT) === false,
+    "超时不算号死",
+  );
+  assert(isDeterministicAccountFailure("") === false, "空串不命中");
+  assert(isDeterministicAccountFailure(null) === false, "null 不命中");
+}
+
+// ── B. isRetryableInjectFailure 瞬态/环境失败白名单 ──
+{
+  console.error("\n[B] isRetryableInjectFailure 瞬态白名单");
+  assert(isRetryableInjectFailure(TRANSIENT_TIMEOUT) === true, "超时 → 可重试");
+  assert(isRetryableInjectFailure(TRANSIENT_NET) === true, "net::ERR_TIMED_OUT → 可重试");
+  assert(
+    isRetryableInjectFailure("page.goto: net::ERR_HTTP_RESPONSE_CODE_FAILURE") === true,
+    "net::ERR_HTTP_RESPONSE_CODE_FAILURE → 可重试",
+  );
+  assert(isRetryableInjectFailure("AbortError") === true, "AbortError → 可重试");
+  assert(
+    isRetryableInjectFailure(
+      "Execution context was destroyed, most likely because of a navigation",
+    ) === true,
+    "Execution context destroyed → 可重试",
+  );
+  assert(isRetryableInjectFailure("无账号数据") === true, "无账号数据 → 可重试");
+  assert(
+    isRetryableInjectFailure("导航失败: page.goto: net::ERR_ABORTED") === true,
+    "导航失败前缀 → 可重试",
+  );
+  // 不可重试侧
+  assert(isRetryableInjectFailure("会话过期") === false, "会话过期 → 不可重试（号死）");
+  assert(
+    isRetryableInjectFailure("身份不符（期望 @x，实际 @y）") === false,
+    "身份不符 → 不可重试（号死）",
+  );
+  assert(isRetryableInjectFailure("Page crashed") === false, "Page crashed → 不可重试（走熔断）");
+  assert(isRetryableInjectFailure("Target crashed") === false, "Target crashed → 不可重试（走熔断）");
+  assert(
+    isRetryableInjectFailure("账号 cookies 为空") === false,
+    "未知失败 → 不可重试（保守兜底，维持现状弃号）",
+  );
+  assert(isRetryableInjectFailure("") === false, "空串 → false");
+  assert(isRetryableInjectFailure(null) === false, "null → false");
+}
+
+// ── C. decideCandidateInjectAction 三路分流（真实 isBrowserClosedError 注入）──
+{
+  console.error("\n[C] decideCandidateInjectAction 决策");
+  const d = (reason) => decideCandidateInjectAction(reason, isBrowserClosedError);
+  assert(d("Page crashed") === "circuit-break", "Page crashed → circuit-break");
+  assert(d("Target crashed") === "circuit-break", "Target crashed → circuit-break");
+  assert(
+    d("Target page, context or browser has been closed") === "circuit-break",
+    "浏览器关闭签名 → circuit-break",
+  );
+  assert(
+    d("page.goto: net::ERR_CONNECTION_RESET") === "circuit-break",
+    "net::ERR_CONNECTION_* 命中崩溃签名（BROWSER_CLOSED_PATTERNS）→ 优先熔断（现状语义保持）",
+  );
+  assert(d(TRANSIENT_TIMEOUT) === "retry", "超时 → retry");
+  assert(d(TRANSIENT_NET) === "retry", "net::ERR_TIMED_OUT → retry");
+  assert(d("AbortError") === "retry", "AbortError → retry");
+  assert(d("无账号数据") === "retry", "无账号数据 → retry");
+  assert(d("会话过期") === "discard", "会话过期 → discard（立即弃号换候选）");
+  assert(
+    d("身份不符（期望 @a，实际 @b）") === "discard",
+    "身份不符 → discard",
+  );
+  assert(d("账号 cookies 为空") === "discard", "未知失败 → discard（现状兜底）");
+  assert(
+    decideCandidateInjectAction("Page crashed") === "discard",
+    "防御：未注入崩溃谓词时不误判熔断（调用方恒传谓词，此处仅验证缺省安全）",
+  );
+}
+
+// ── D. retryRestoreOnNavFailure 驱动 + onRetry 钩子 ──
+// 注：驱动语义「首次尝试已发生」——firstFailure 即首败结果，
+// attemptResults 只含重试轮序列（第2/3次尝试）
+async function drive({ attemptResults, firstFailure, shouldAbort, onInject }) {
+  const calls = { sleepMs: 0, onRetry: [], attempts: 0, inject: 0 };
+  const seq = [...attemptResults];
+  const r = await retryRestoreOnNavFailure(
+    () => {
+      calls.inject++;
+      if (typeof onInject === "function") onInject(calls.inject);
+      const item = seq.shift();
+      return Promise.resolve(item ?? { ok: true });
+    },
+    firstFailure,
+    {
+      isRetryable: isRetryableInjectFailure,
+      maxRetries: CANDIDATE_INJECT_MAX_RETRIES,
+      delayMs: CANDIDATE_INJECT_DELAY_MS,
+      sleep: async (ms) => {
+        calls.sleepMs += ms;
+      },
+      shouldAbort: shouldAbort || (() => false),
+      onRetry: (n, delayMs, why) => calls.onRetry.push({ n, delayMs, why }),
+    },
+  );
+  return { r, calls };
+}
+
+{
+  console.error("\n[D] retryRestoreOnNavFailure 驱动（注入式）");
+  // D1. 瞬态失败重试 2 次后成功（首败 net::ERR_ABORTED + 重试轮：失败→成功）
+  {
+    const { r, calls } = await drive({
+      attemptResults: [
+        { ok: false, reason: TRANSIENT_TIMEOUT },
+        { ok: true, username: "t1" },
+      ],
+      firstFailure: "page.goto: net::ERR_ABORTED",
+    });
+    assert(r.ok === true, "D1 第 3 次尝试成功 → ok");
+    assert(r.attempts === 3, "D1 attempts=3（共 3 次尝试）");
+    assert(r.username === "t1", "D1 成功结果字段透传");
+    assert(calls.inject === 2, "D1 重试轮注入 2 次（首败已发生，不重复计入）");
+    assert(
+      calls.sleepMs === 2 * CANDIDATE_INJECT_DELAY_MS,
+      "D1 重试间隔 2 次 × 15s",
+    );
+    assert(
+      calls.onRetry.length === 2 &&
+        calls.onRetry[0].n === 1 &&
+        calls.onRetry[1].n === 2,
+      "D1 onRetry 回调 2 次（第1/2次失败后各一次）",
+    );
+    assert(
+      calls.onRetry[0].delayMs === CANDIDATE_INJECT_DELAY_MS,
+      "D1 onRetry 携带间隔时长（供日志「15s 后原号重试」）",
+    );
+  }
+  // D2. 3 次全败
+  {
+    const { r, calls } = await drive({
+      attemptResults: [
+        { ok: false, reason: TRANSIENT_TIMEOUT },
+        { ok: false, reason: "无账号数据" },
+      ],
+      firstFailure: TRANSIENT_TIMEOUT,
+    });
+    assert(r.ok === false, "D2 3 次全败 → ok=false");
+    assert(r.attempts === 3, "D2 attempts=3 后停止");
+    assert(calls.inject === 2, "D2 重试轮恰好 2 次（不无限重试）");
+    assert(calls.onRetry.length === 2, "D2 onRetry 仅 2 次（第 3 次失败后不再回调）");
+  }
+  // D3/D4. 确定性号死零重试
+  for (const [label, reason] of [
+    ["D3 会话过期", "会话过期"],
+    ["D4 身份不符", "身份不符（期望 @pool，实际 @other）"],
+  ]) {
+    const { r, calls } = await drive({
+      attemptResults: [],
+      firstFailure: reason,
+    });
+    assert(r.ok === false && r.attempts === 1, `${label} 零重试（attempts=1）`);
+    assert(calls.inject === 0 && calls.sleepMs === 0, `${label} 不再注入不等待`);
+    assert(calls.onRetry.length === 0, `${label} 无 onRetry 回调`);
+  }
+  // D5. 崩溃签名不进重试（驱动层兜底；分流到熔断由 C 节决策保证）
+  {
+    const { r, calls } = await drive({
+      attemptResults: [],
+      firstFailure: "Page crashed",
+    });
+    assert(r.ok === false && r.attempts === 1, "D5 崩溃签名零重试");
+    assert(calls.sleepMs === 0, "D5 不消耗重试等待");
+  }
+  // D6. shouldAbort 中断（中断点：sleep 之后、下一次尝试之前）
+  {
+    const { r, calls } = await drive({
+      attemptResults: [],
+      firstFailure: TRANSIENT_TIMEOUT,
+      shouldAbort: () => true,
+    });
+    assert(
+      r.aborted === true && r.ok === false,
+      "D6 shouldAbort 命中 → aborted 返回",
+    );
+    assert(r.attempts === 1, "D6 中断时 attempts 不虚增");
+    assert(calls.inject === 0, "D6 中断后不再尝试注入");
+    // 第二轮重试等待后才中断：attempts 停在 2，重试轮注入恰好 1 次
+    let abortAfterOne = false;
+    const { r: r2, calls: c2 } = await drive({
+      attemptResults: [{ ok: false, reason: TRANSIENT_TIMEOUT }],
+      firstFailure: TRANSIENT_TIMEOUT,
+      shouldAbort: () => abortAfterOne,
+      onInject: () => {
+        abortAfterOne = true;
+      },
+    });
+    assert(
+      r2.aborted === true && r2.attempts === 2,
+      "D6 第二轮等待后中断 → attempts=2",
+    );
+    assert(c2.inject === 1, "D6 中断前完成的重试轮注入恰好 1 次");
+  }
+  // D7. 重试中途失败升级为崩溃签名 → 驱动立即停止（不再消耗第 3 次尝试），
+  // 最终 reason 透传给调用方重判（熔断分流在 E8 小模型验证）
+  {
+    const { r, calls } = await drive({
+      attemptResults: [{ ok: false, reason: "Page crashed" }],
+      firstFailure: TRANSIENT_TIMEOUT,
+    });
+    assert(
+      r.ok === false && r.attempts === 2 && r.reason === "Page crashed",
+      "D7 中途崩溃 → attempts=2 停止，最终 reason=Page crashed",
+    );
+    assert(calls.inject === 1, "D7 不再进行第 3 次尝试");
+    assert(
+      decideCandidateInjectAction(r.reason, isBrowserClosedError) === "circuit-break",
+      "D7 最终 reason 重判命中熔断（调用方重判依据）",
+    );
+  }
+}
+
+// ── E. 候选循环小模型（与 switchPoolAccount 同构，验证租约保持在手/弃号时机）──
+/**
+ * 复刻 explore.js/search.js 候选循环的注入失败分流骨架（单候选）：
+ * acquire → inject → decideCandidateInjectAction →
+ *   circuit-break: 熔断标记 + release 候选 + 中止（返回）
+ *   retry: retryRestoreOnNavFailure（sleep/shouldAbort 注入）→ 成功 fall-through / 失败弃号
+ *   discard: 直接弃号
+ * 返回观测记录 {action, acquire, release, injectCalls, sleepMs, retries, switched}
+ */
+async function runCandidateOnce({ injectSeq, shouldAbort }) {
+  const obs = {
+    acquire: 0,
+    release: 0,
+    injectCalls: 0,
+    sleepMs: 0,
+    retryLogs: [],
+    switched: false,
+    circuitBreak: false,
+  };
+  obs.acquire++; // 取候选号
+  let r = await Promise.resolve(injectSeq.shift() ?? { ok: true });
+  obs.injectCalls++;
+  if (!r.ok) {
+    let action = decideCandidateInjectAction(r.reason, isBrowserClosedError);
+    if (action === "circuit-break") {
+      obs.circuitBreak = true;
+      obs.release++; // 既有行为：已取候选照常 release，中止候选循环
+      return obs;
+    }
+    if (action === "retry") {
+      r = await retryRestoreOnNavFailure(
+        () => {
+          obs.injectCalls++;
+          return Promise.resolve(injectSeq.shift() ?? { ok: true });
+        },
+        r.reason,
+        {
+          isRetryable: isRetryableInjectFailure,
+          maxRetries: CANDIDATE_INJECT_MAX_RETRIES,
+          delayMs: CANDIDATE_INJECT_DELAY_MS,
+          sleep: async (ms) => {
+            obs.sleepMs += ms;
+          },
+          shouldAbort: shouldAbort || (() => false),
+          onRetry: (n, delayMs, why) =>
+            obs.retryLogs.push(
+              `[换号] @t 第${n}次注入失败（瞬态，${why}），${Math.round(delayMs / 1000)}s 后原号重试`,
+            ),
+        },
+      );
+      if (r.aborted) {
+        obs.release++; // shuttingDown：释放候选退出
+        obs.aborted = true;
+        return obs;
+      }
+      if (!r.ok) {
+        // 补丁：重试中途失败签名可能升级（崩溃/号死），对最终原因重判——
+        // 与 switchPoolAccount 补丁后同构：命中熔断走熔断，否则弃号
+        action = decideCandidateInjectAction(r.reason, isBrowserClosedError);
+        if (action === "circuit-break") {
+          obs.circuitBreak = true;
+          obs.release++;
+          return obs;
+        }
+      }
+    }
+    if (!r.ok) {
+      obs.release++; // 3 次全败（或确定性号死/未知失败）才弃号
+      obs.finalReason = r.reason;
+      obs.finalAttempts = r.attempts;
+      return obs;
+    }
+    if (r.attempts > 1) obs.retrySuccessAt = r.attempts;
+  }
+  obs.switched = true; // 注入验证通过（含重试成功），不 release 新号（租约保持在手）
+  return obs;
+}
+
+{
+  console.error("\n[E] 候选循环小模型（租约保持在手 / 弃号时机）");
+  // E1. 瞬态失败重试 2 次后成功：不弃号、不还池、不重新取号
+  {
+    const obs = await runCandidateOnce({
+      injectSeq: [
+        { ok: false, reason: TRANSIENT_TIMEOUT },
+        { ok: false, reason: TRANSIENT_NET },
+        { ok: true },
+      ],
+    });
+    assert(obs.switched === true && obs.release === 0, "E1 重试成功 → 候选保持在手（release=0）");
+    assert(obs.acquire === 1, "E1 不重新取号（acquire=1）");
+    assert(obs.injectCalls === 3, "E1 共 3 次尝试");
+    assert(obs.retryLogs.length === 2, "E1 每次瞬态失败后打重试日志");
+    assert(
+      /第1次注入失败（瞬态.*）.*15s 后原号重试/.test(obs.retryLogs[0]),
+      "E1 日志格式含「第N次注入失败（瞬态）…15s 后原号重试」",
+    );
+  }
+  // E2. 3 次全败 → 弃号一次（release=1）
+  {
+    const obs = await runCandidateOnce({
+      injectSeq: [
+        { ok: false, reason: TRANSIENT_TIMEOUT },
+        { ok: false, reason: TRANSIENT_TIMEOUT },
+        { ok: false, reason: "无账号数据" },
+      ],
+    });
+    assert(
+      obs.switched === false && obs.release === 1,
+      "E2 3 次全败 → 恰好弃号一次",
+    );
+    assert(obs.finalAttempts === 3, "E2 弃号发生在共 3 次尝试之后");
+    assert(obs.injectCalls === 3, "E2 共 3 次尝试（不提前弃号）");
+    assert(obs.sleepMs === 2 * CANDIDATE_INJECT_DELAY_MS, "E2 重试等待 2 × 15s");
+  }
+  // E3. 会话过期 → 零重试直接弃号
+  {
+    const obs = await runCandidateOnce({
+      injectSeq: [{ ok: false, reason: "会话过期" }],
+    });
+    assert(
+      obs.switched === false && obs.release === 1 && obs.injectCalls === 1,
+      "E3 会话过期 → 零重试立即弃号",
+    );
+    assert(obs.retryLogs.length === 0 && obs.sleepMs === 0, "E3 无重试无等待");
+  }
+  // E4. 身份不符 → 零重试直接弃号
+  {
+    const obs = await runCandidateOnce({
+      injectSeq: [{ ok: false, reason: "身份不符（期望 @t，实际 @x）" }],
+    });
+    assert(
+      obs.switched === false && obs.release === 1 && obs.injectCalls === 1,
+      "E4 身份不符 → 零重试立即弃号",
+    );
+  }
+  // E5. 崩溃 → 走熔断（不进重试），候选照常 release（既有行为）
+  {
+    const obs = await runCandidateOnce({
+      injectSeq: [{ ok: false, reason: "Page crashed" }],
+    });
+    assert(obs.circuitBreak === true, "E5 崩溃 → circuit-break 分流");
+    assert(obs.release === 1 && obs.injectCalls === 1, "E5 候选照常 release，不重试");
+    assert(obs.switched === false && obs.sleepMs === 0, "E5 不重试不等待");
+  }
+  // E6. net::ERR_CONNECTION_* → 崩溃签名优先熔断（现状语义，不进重试）
+  {
+    const obs = await runCandidateOnce({
+      injectSeq: [{ ok: false, reason: "page.goto: net::ERR_CONNECTION_RESET" }],
+    });
+    assert(
+      obs.circuitBreak === true && obs.retryLogs.length === 0,
+      "E6 net::ERR_CONNECTION_* → 熔断优先于重试（现状语义保持）",
+    );
+  }
+  // E7. shuttingDown 中断 → 释放候选退出
+  {
+    const obs = await runCandidateOnce({
+      injectSeq: [{ ok: false, reason: TRANSIENT_TIMEOUT }],
+      shouldAbort: () => true,
+    });
+    assert(
+      obs.aborted === true && obs.release === 1 && obs.switched === false,
+      "E7 关闭信号中断 → 释放候选退出",
+    );
+    assert(obs.injectCalls === 1, "E7 中断后不再尝试注入");
+  }
+  // E8. 首败 timeout 进重试、第 2 次尝试失败=Page crashed → 重判走熔断（补验收缺口）：
+  // 不弃号给下一候选（坏浏览器再吃一个号），crashStreak/退避由熔断分支接管
+  {
+    const obs = await runCandidateOnce({
+      injectSeq: [
+        { ok: false, reason: TRANSIENT_TIMEOUT },
+        { ok: false, reason: "Page crashed" },
+      ],
+    });
+    assert(
+      obs.circuitBreak === true,
+      "E8 重试中途升级崩溃 → 熔断分流（不落弃号分支）",
+    );
+    assert(
+      obs.switched === false && obs.release === 1,
+      "E8 候选照常 release，不切换不进入下一候选",
+    );
+    assert(
+      obs.finalAttempts === undefined,
+      "E8 不进弃号分支（无弃号 attempts 痕迹）",
+    );
+    assert(obs.injectCalls === 2, "E8 共 2 次尝试后停止（不再第 3 次）");
+  }
+  // E9. 首败 timeout 进重试、第 2 次尝试=会话过期 → 弃号换候选（不误入熔断）
+  {
+    const obs = await runCandidateOnce({
+      injectSeq: [
+        { ok: false, reason: TRANSIENT_TIMEOUT },
+        { ok: false, reason: "会话过期" },
+      ],
+    });
+    assert(
+      obs.circuitBreak === false,
+      "E9 重试中途号死 → 不误入熔断",
+    );
+    assert(
+      obs.switched === false && obs.release === 1,
+      "E9 弃号换下一个候选（恰好 release 一次）",
+    );
+    assert(
+      obs.finalReason === "会话过期" && obs.finalAttempts === 2,
+      "E9 弃号发生在共 2 次尝试之后（中途号死停止重试）",
+    );
+  }
+}
+
+// ── 常量契约 ──
+{
+  console.error("\n[F] 常量契约");
+  assert(CANDIDATE_INJECT_MAX_RETRIES === 2, "原号重试上限 = 2（共 3 次尝试）");
+  assert(CANDIDATE_INJECT_DELAY_MS === 15 * 1000, "重试间隔 = 15s");
+}
+
+console.error(`\n结果: ${pass} 通过, ${fail} 失败`);
+process.exit(fail > 0 ? 1 : 0);