tt-help-cli-ycl 1.4.150 → 1.4.152

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/scripts/test-seller-any-country.mjs

@@ -0,0 +1,167 @@
+/**
+ * 商家任务国家放开领取测试（claimNextJob 分支顺序）
+ *
+ * 验证（临时 SQLite 库）：
+ *   1. 传了国家子集：先领对应国家的 ttseller，领完再领任意国家 ttseller
+ *   2. 未传国家：领商家（任意国家均可）
+ *   3. 其他来源级顺序不变：seed 仍排商家前，非商家任务仍按国家分层
+ *   4. 未登录客户端不领商家任务（保持原逻辑）
+ *
+ * 运行: TMPDIR=$(mktemp -d) node scripts/test-seller-any-country.mjs
+ */
+import { createStore } from "../src/watch/data-store.js";
+import { getDb } from "../src/watch/db-schema.js";
+import { join } from "node:path";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+const tmp = mkdtempSync(join(tmpdir(), "seller-any-"));
+const store = createStore(join(tmp, "test.db"));
+const db = getDb();
+if (!db) {
+  console.error("❌ db 未初始化");
+  process.exit(1);
+}
+
+let passed = 0;
+function check(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ✅ ${name}`);
+  } catch (e) {
+    console.error(`  ❌ ${name}\n     ${e.message}`);
+    process.exitCode = 1;
+  }
+}
+function assert(cond, msg = "断言失败") {
+  if (!cond) throw new Error(msg);
+}
+
+const now = Date.now();
+// 直接插 task_queue（refill 后形态）
+const insert = (id, loc, seller, sources, opts = {}) =>
+  db
+    .prepare(
+      `INSERT INTO task_queue (unique_id, status, pinned, guessed_location, tt_seller, verified, sources, video_count, follower_count, created_at, updated_at)
+       VALUES (?, 'pending', 0, ?, ?, 0, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      id,
+      loc,
+      seller,
+      JSON.stringify(sources),
+      opts.videoCount ?? 3,
+      opts.followers ?? 100,
+      now,
+      now,
+    );
+
+console.log("===== 商家任务国家放开领取测试 =====");
+
+// ── 场景 1：传 US，队列里有 US 商家 + DE 商家 ──
+console.log("\n[1] 传国家子集 US：US 商家优先于 DE 商家");
+insert("seller_de", "DE", 1, ["following"]);
+insert("seller_us", "US", 1, ["following"]);
+{
+  const job = await store.claimNextJob("t1", 5 * 60 * 1000, ["US"], true);
+  check("先领到 US 商家", () =>
+    assert(job?.uniqueId === "seller_us", `实际: ${job?.uniqueId}`),
+  );
+}
+
+// ── 场景 2：US 商家已不在（被领走），传 US → 兜任意国家 DE 商家 ──
+console.log("\n[2] 无 US 商家可领时：兜到任意国家商家（DE）");
+{
+  // seller_us 已被 t1 领走（processing），队列只剩 DE 商家 pending
+  const job = await store.claimNextJob("t2", 5 * 60 * 1000, ["US"], true);
+  check("兜到 DE 商家", () =>
+    assert(job?.uniqueId === "seller_de", `实际: ${job?.uniqueId}`),
+  );
+}
+
+// ── 场景 3：传 US 但队列只有 FR 商家 → 领 FR ──
+console.log("\n[3] 传 US 但无 US 商家 → 领 FR 商家（任意国家兜底）");
+db.prepare(`DELETE FROM task_queue`).run();
+insert("seller_fr", "FR", 1, ["following"]);
+{
+  const job = await store.claimNextJob("t3", 5 * 60 * 1000, ["US"], true);
+  check("领到 FR 商家", () =>
+    assert(job?.uniqueId === "seller_fr", `实际: ${job?.uniqueId}`),
+  );
+}
+
+// ── 场景 4：空位置商家（guessed_location=''）→ 任意国家分支领到 ──
+console.log("\n[4] 空位置商家可被任意国家分支领到");
+db.prepare(`DELETE FROM task_queue`).run();
+insert("seller_noloc", "", 1, ["following"]);
+{
+  const job = await store.claimNextJob("t4", 5 * 60 * 1000, ["US"], true);
+  check("领到空位置商家", () =>
+    assert(job?.uniqueId === "seller_noloc", `实际: ${job?.uniqueId}`),
+  );
+}
+
+// ── 场景 5：未传国家，队列只有配置外国商家 → 直接领到 ──
+console.log("\n[5] 未传国家：配置外国商家（FR）也能领到");
+db.prepare(`DELETE FROM task_queue`).run();
+insert("seller_fr2", "FR", 1, ["following"]);
+{
+  const job = await store.claimNextJob("t5", 5 * 60 * 1000, null, true);
+  check("领到 FR 商家（未传国家不再被挡）", () =>
+    assert(job?.uniqueId === "seller_fr2", `实际: ${job?.uniqueId}`),
+  );
+}
+
+// ── 场景 6：seed 仍优先于商家（顺序不变）──
+console.log("\n[6] seed 优先级仍高于商家");
+db.prepare(`DELETE FROM task_queue`).run();
+insert("seed_pl", "PL", 0, ["seed"]);
+insert("seller_xx", "XX", 1, ["following"]);
+{
+  const job = await store.claimNextJob("t6", 5 * 60 * 1000, null, true);
+  check("先领 seed", () =>
+    assert(job?.uniqueId === "seed_pl", `实际: ${job?.uniqueId}`),
+  );
+}
+
+// ── 场景 7：非商家任务仍按国家分层（PL 配置内优先于 ZZ 配置外）──
+console.log("\n[7] 商家清空后：非商家按国家顺序领取");
+db.prepare(`DELETE FROM task_queue`).run();
+insert("other_pl", "PL", 0, ["search"]);
+insert("other_zz", "ZZ", 0, ["search"]);
+{
+  const job = await store.claimNextJob("t7", 5 * 60 * 1000, null, true);
+  check("PL 非商家先于 ZZ（配置内优先）", () =>
+    assert(job?.uniqueId === "other_pl", `实际: ${job?.uniqueId}`),
+  );
+}
+
+// ── 场景 8：未登录客户端不领商家（原逻辑不变）──
+console.log("\n[8] 未登录不领商家任务");
+db.prepare(`DELETE FROM task_queue`).run();
+insert("seller_only", "US", 1, ["following"]);
+insert("other_task", "PL", 0, ["search"]);
+{
+  const job = await store.claimNextJob("t8", 5 * 60 * 1000, null, false);
+  check("未登录跳过商家领普通任务", () =>
+    assert(job?.uniqueId === "other_task", `实际: ${job?.uniqueId}`),
+  );
+}
+
+// ── 场景 9：非商家任务不享受任意国家兜底（配置内先于配置外）──
+console.log("\n[9] 非商家配置外国家不越级");
+db.prepare(`DELETE FROM task_queue`).run();
+insert("plain_de", "DE", 0, ["search"]); // DE 在默认配置内
+insert("plain_zz", "ZZ", 0, ["search"]); // ZZ 不在配置
+{
+  const job = await store.claimNextJob("t9", 5 * 60 * 1000, null, true);
+  check("DE（配置内）先于 ZZ（配置外）", () =>
+    assert(job?.uniqueId === "plain_de", `实际: ${job?.uniqueId}`),
+  );
+}
+
+store.stopBackup?.();
+console.log(
+  `\n结果: ${passed} 通过${process.exitCode ? ", 有失败" : ", 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/product-fill.js

@@ -540,9 +540,21 @@ export async function handleProductFill(options) {
             batchSuccess++;
             totalSuccess++;
             failCount.delete(uniqueId);
+            const skus = detail.skus;
+            const skuInfo = skus
+              ? ` | SKU ${skus.length}个 总库存 ${skus.reduce((sum, s) => sum + (s.stock || 0), 0)}`
+              : "";
             log(
-              `  ✓ @${uniqueId} 商品已补全 (评分${detail.rating ?? "-"} | 销量${detail.soldCount ?? "-"} | 评论${detail.reviewCount ?? "-"})`,
+              `  ✓ @${uniqueId} 商品已补全 (评分${detail.rating ?? "-"} | 销量${detail.soldCount ?? "-"} | 评论${detail.reviewCount ?? "-"}${skuInfo})`,
             );
+            if (skus) {
+              // SKU 明细日志：规格 | 库存 | 状态（先观察数据质量，暂不入库）
+              for (const s of skus) {
+                log(
+                  `    · ${s.skuId} | ${s.specs || "(无规格名)"} | 库存${s.stock ?? "?"} | 状态${s.stockStatus ?? "?"}`,
+                );
+              }
+            }
           } else {
             batchFailed++;
             totalFailed++;

package/src/cli/refresh-mini.js

@@ -191,6 +191,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

@@ -119,6 +119,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,
@@ -46,9 +47,17 @@ function extractProductInfo(item) {
 
 /**
  * 构建统一的视频对象
+ *
+ * 图文帖（photo post）与视频混在 item_list 响应里，用 imagePost 字段区分
+ * （实测 @zoecole.fr：图文 item 有 imagePost={cover,images,...}，
+ *   video.duration=0 且无 PlayAddrStruct/codecType；视频 duration>0）。
+ * - isPhoto 标记贯穿全链路：EC 筛选/入库照常保留图文，仅国家采样排除
+ * - href 按真实路径生成：图文 /photo/{id}，视频 /video/{id}
  */
 function buildVideoObject(item, username) {
-  const href = `https://www.tiktok.com/@${username}/video/${item.id}`;
+  // 双保险：优先官方 imagePost 字段，duration=0 兜底（防字段偶发缺失）
+  const isPhoto = item.imagePost !== undefined || item.video?.duration === 0;
+  const href = `https://www.tiktok.com/@${username}/${isPhoto ? "photo" : "video"}/${item.id}`;
   const productInfo = extractProductInfo(item);
   return {
     id: item.id,
@@ -57,6 +66,7 @@ function buildVideoObject(item, username) {
     playCount: item.stats?.playCount || 0,
     isECVideo: item.isECVideo ? 1 : 0,
     isAd: item.isAd ? 1 : 0,
+    isPhoto: isPhoto ? 1 : 0,
     productId: productInfo?.productId || null,
     productTitle: productInfo?.productTitle || null,
     seoUrl: productInfo?.seoUrl || null,
@@ -381,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 [选项]",