tt-help-cli-ycl 1.3.63 → 1.3.65

package/package.json

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

package/scripts/run-explore.bat

@@ -131,4 +131,4 @@ ECHO   Max following: 5
 ECHO   Max followers: 5
 ECHO   Speed: stealth (slowest)
 ECHO ========================================
-CALL tt-help explore stealth --user-id %%USER_ID%% --base-port %%BASE_PORT%% --port-count %%PORT_COUNT%% --max-following 5 --max-followers 5 %%JOB_LOC_ARGS%%
+CALL tt-help explore stealth --user-id %%USER_ID%% --base-port %%BASE_PORT%% --port-count %%PORT_COUNT%% --max-following 100 --max-followers 100 %%JOB_LOC_ARGS%%

package/src/cli/attach.js

@@ -1,4 +1,5 @@
 import { TikTokScraper } from "../lib/tiktok-scraper.mjs";
+import { proxy as configuredProxy } from "../lib/constants.js";
 import v8 from "node:v8";
 
 const MAX_RETRY_WAIT = 5 * 60 * 1000;
@@ -81,8 +82,14 @@ export async function handleAttach(options) {
     attachInterval,
     serverUrl,
     attachCountries,
+    customProxy,
     showHelp,
   } = options;
+  const effectiveProxy = customProxy || configuredProxy;
+
+  if (effectiveProxy) {
+    attachLog(`[Attach] 使用代理: ${effectiveProxy}`);
+  }
   let shuttingDown = false;
   let forceExitTimer = null;
 
@@ -100,6 +107,9 @@ export async function handleAttach(options) {
     attachLog(
       "  -c, --countries <A,B,C>  猜测国家列表（逗号分隔，如 PL,DE,FR），服务端优先返回这些国家的任务",
     );
+    attachLog(
+      "  --proxy <代理地址>    HTTP 代理地址（如 http://127.0.0.1:7890），不配置则从 ~/.tt-help.json 读取",
+    );
     attachLog("");
     attachLog("说明:");
     attachLog(
@@ -124,7 +134,7 @@ export async function handleAttach(options) {
     `[Attach] 并行数: ${attachParallel}, 空闲间隔: ${attachInterval}秒, 服务端: ${serverUrl}${countryStr}`,
   );
 
-  const scraper = new TikTokScraper();
+  const scraper = new TikTokScraper(effectiveProxy || null);
   const shutdown = async (signal) => {
     if (shuttingDown) return;
     shuttingDown = true;

package/src/cli/config.js

@@ -33,7 +33,29 @@ function showUsage(helpText = HELP_TEXT) {
   process.exit(0);
 }
 
+const CONFIG_KEYS = [
+  "proxy",
+  "server",
+  "browser",
+  "userId",
+  "maxFollowing",
+  "maxFollowers",
+  "maxVideos",
+  "maxComments",
+];
+
 function handleConfig(action, key, value) {
+  // 简写语法兼容：tt-help config proxy "值" → tt-help config set proxy "值"
+  if (CONFIG_KEYS.includes(action) && key !== undefined && key !== null) {
+    // action 是 key 名（如 "proxy"），key 是值（如 "http://..."）
+    // 转换为 set 模式
+    const realKey = action;
+    const realValue = key;
+    action = "set";
+    key = realKey;
+    value = realValue;
+  }
+
   switch (action) {
     case "show": {
       const configLines = getConfigText();
@@ -52,13 +74,13 @@ function handleConfig(action, key, value) {
 
       switch (key) {
         case "proxy":
-          if (!value) {
+          if (value === undefined || value === null) {
             console.error("请提供 proxy 的值");
             console.error("用法: tt-help config set proxy <代理地址>");
             return;
           }
           saveProxy(value);
-          console.error(`代理已更新: ${value}`);
+          console.error(`代理已更新: ${value || "(空，不使用代理)"}`);
           break;
 
         case "server":
@@ -135,6 +157,27 @@ function handleConfig(action, key, value) {
       break;
     }
 
+    case "unset": {
+      if (!key) {
+        console.error("用法: tt-help config unset <key>");
+        console.error(
+          "  可用 key: proxy, server, browser, userId, maxFollowing, maxFollowers, maxVideos, maxComments",
+        );
+        break;
+      }
+      const cfg = existsSync(configPath)
+        ? JSON.parse(readFileSync(configPath, "utf-8"))
+        : {};
+      if (cfg[key] !== undefined) {
+        delete cfg[key];
+        writeFileSync(configPath, JSON.stringify(cfg, null, 2), "utf-8");
+        console.error(`已删除配置: ${key}`);
+      } else {
+        console.error(`配置项 ${key} 不存在`);
+      }
+      break;
+    }
+
     case "reset": {
       if (existsSync(configPath)) {
         writeFileSync(configPath, "{}", "utf-8");
@@ -147,7 +190,7 @@ function handleConfig(action, key, value) {
 
     default:
       console.error(`未知配置命令: ${action}`);
-      console.error("用法: tt-help config [show|set|reset]");
+      console.error("用法: tt-help config [show|set|unset|reset]");
   }
 }
 

package/src/cli/explore.js

@@ -12,7 +12,11 @@ import {
   detectCaptcha,
   closeCaptcha,
 } from "../scraper/modules/captcha-handler.js";
-import { userId as configuredUserId, saveUserId } from "../lib/constants.js";
+import {
+  userId as configuredUserId,
+  saveUserId,
+  proxy as configuredProxy,
+} from "../lib/constants.js";
 import { getMacOrUuid } from "../lib/mac-or-uuid.js";
 import {
   ensureBrowserReady as ensureBrowserReadyCDP,
@@ -151,8 +155,14 @@ export async function handleExplore(options) {
       cdpOptions.userDataDir = currentAccount.userDataDir;
     }
 
-    if (exploreProxy) {
-      cdpOptions.proxyServer = exploreProxy;
+    const effectiveProxy = exploreProxy || configuredProxy;
+    if (effectiveProxy) {
+      cdpOptions.proxyServer = effectiveProxy;
+      console.error(
+        `代理: ${effectiveProxy}${exploreProxy ? " (命令行指定)" : " (配置文件)"}`,
+      );
+    } else {
+      console.error(`代理: 未配置`);
     }
 
     console.error(`CDP 端口: ${cdpOptions.port}, 用户编号: ${userId}`);
@@ -166,7 +176,7 @@ export async function handleExplore(options) {
 
     browser = await ensureBrowserReadyCDP(cdpOptions);
     const { processExplore } = await import("../scraper/explore-core.js");
-    const { isLoggedIn } = await import("../lib/browser/page.js");
+    const { safeCheckLogin } = await import("../lib/browser/page.js");
 
     const page = await getOrCreatePage(browser);
 
@@ -176,8 +186,7 @@ export async function handleExplore(options) {
     });
 
     // 检测登录状态（启动时只检测一次）
-    let loggedIn = await isLoggedIn(page);
-    console.error(`登录状态: ${loggedIn ? "已登录" : "未登录"}`);
+    let loggedIn = await safeCheckLogin(page);
 
     // 全局拦截图片资源，减少内存占用和加载时间
     await page.route("**/*", (route) => {
@@ -208,9 +217,11 @@ export async function handleExplore(options) {
       const oldAccount = currentAccount;
       const nextAccount = healthChecker.getNextAccount();
       currentAccount = nextAccount;
+      const effectiveProxy = cdpOptions.proxyServer;
       const newBrowser = await switchAccount(
         { port: oldAccount.port, userDataDir: oldAccount.userDataDir },
         { port: nextAccount.port, userDataDir: nextAccount.userDataDir },
+        effectiveProxy,
       );
       browser = newBrowser;
       const newPage = await setupNewPage(browser);
@@ -218,13 +229,16 @@ export async function handleExplore(options) {
       Object.assign(cdpOptions, {
         port: nextAccount.port,
         userDataDir: nextAccount.userDataDir,
+        ...(effectiveProxy ? { proxyServer: effectiveProxy } : {}),
       });
-      console.error(`[健康检查] 已切换到端口 ${nextAccount.port}`);
+      console.error(
+        `[健康检查] 已切换到端口 ${nextAccount.port}${effectiveProxy ? ", 代理: " + effectiveProxy : ""}`,
+      );
       // 切换账户后先导航到 TikTok 页面，再重新检测登录状态
       await page.goto(STARTUP_TIKTOK_URL, {
         waitUntil: "domcontentloaded",
       });
-      loggedIn = await isLoggedIn(page);
+      loggedIn = await safeCheckLogin(page);
       console.error(
         `[健康检查] 新账户登录状态: ${loggedIn ? "已登录" : "未登录"}`,
       );
@@ -358,6 +372,7 @@ export async function handleExplore(options) {
           maxFollowing: exploreMaxFollowing,
           maxFollowers: exploreMaxFollowers,
           location: exploreLocation,
+          proxyServer: cdpOptions.proxyServer || null,
           browser,
         },
         console.error,
@@ -383,6 +398,7 @@ export async function handleExplore(options) {
             maxFollowing: exploreMaxFollowing,
             maxFollowers: exploreMaxFollowers,
             location: exploreLocation,
+            proxyServer: cdpOptions.proxyServer || null,
             browser,
           },
           console.error,
@@ -420,6 +436,7 @@ export async function handleExplore(options) {
               maxFollowing: exploreMaxFollowing,
               maxFollowers: exploreMaxFollowers,
               location: exploreLocation,
+              proxyServer: cdpOptions.proxyServer || null,
               browser,
             },
             console.error,

package/src/cli/refresh.js

@@ -12,7 +12,11 @@ import {
   detectCaptcha,
   closeCaptcha,
 } from "../scraper/modules/captcha-handler.js";
-import { userId as configuredUserId, saveUserId } from "../lib/constants.js";
+import {
+  userId as configuredUserId,
+  proxy as configuredProxy,
+  saveUserId,
+} from "../lib/constants.js";
 import { getMacOrUuid } from "../lib/mac-or-uuid.js";
 import {
   ensureBrowserReady as ensureBrowserReadyCDP,
@@ -77,6 +81,7 @@ export async function handleRefresh(options) {
     exploreRedoMaxAge,
     exploreProxy,
   } = options;
+  const effectiveProxy = exploreProxy || configuredProxy;
 
   let userId = exploreUserId || configuredUserId;
   let browser = null;
@@ -116,9 +121,16 @@ export async function handleRefresh(options) {
     console.error(`\n=== Refresh 模式（基于 explore） ===`);
     console.error(`服务器: ${serverUrl}`);
     console.error(`视频采集: ${exploreMaxVideos || 16}`);
-    console.error(`关注/粉丝: ${exploreEnableFollow ? "启用" : "禁用"} (${exploreMaxFollowing}/${exploreMaxFollowers})`);
+    console.error(
+      `关注/粉丝: ${exploreEnableFollow ? "启用" : "禁用"} (${exploreMaxFollowing}/${exploreMaxFollowers})`,
+    );
     console.error(`国家筛选: ${exploreLocation}`);
     console.error(`空闲间隔: ${exploreInterval || 30} 秒`);
+    if (effectiveProxy) {
+      console.error(
+        `代理: ${effectiveProxy}${exploreProxy ? " (命令行指定)" : " (配置文件)"}`,
+      );
+    }
     if (exploreMaxUsers > 0) console.error(`上限: ${exploreMaxUsers} 个用户`);
 
     const healthChecker = new HealthChecker({
@@ -149,8 +161,8 @@ export async function handleRefresh(options) {
       cdpOptions.userDataDir = currentAccount.userDataDir;
     }
 
-    if (exploreProxy) {
-      cdpOptions.proxyServer = exploreProxy;
+    if (effectiveProxy) {
+      cdpOptions.proxyServer = effectiveProxy;
     }
 
     console.error(`CDP 端口: ${cdpOptions.port}, 用户编号: ${userId}`);
@@ -217,6 +229,9 @@ export async function handleRefresh(options) {
         port: nextAccount.port,
         userDataDir: nextAccount.userDataDir,
       });
+      if (effectiveProxy) {
+        cdpOptions.proxyServer = effectiveProxy;
+      }
       console.error(`[健康检查] 已切换到端口 ${nextAccount.port}`);
       await page.goto(STARTUP_TIKTOK_URL, {
         waitUntil: "domcontentloaded",
@@ -249,9 +264,10 @@ export async function handleRefresh(options) {
       if (checkResult.shouldSwitch) {
         await handleAccountSwitch(checkResult.reason);
       } else if (checkResult.info && processedCount % 10 === 0) {
-        const followElapsed = loggedIn && exploreEnableFollow
-          ? Math.round((Date.now() - lastFollowSuccessTime) / 60000)
-          : 0;
+        const followElapsed =
+          loggedIn && exploreEnableFollow
+            ? Math.round((Date.now() - lastFollowSuccessTime) / 60000)
+            : 0;
         const followStatus =
           loggedIn && exploreEnableFollow
             ? ` | 关注/粉丝上次成功 ${followElapsed} 分钟前`
@@ -270,14 +286,16 @@ export async function handleRefresh(options) {
       } catch (e) {
         consecutiveNetworkErrors++;
         console.error(
-          `  [网络] 获取任务失败 (${consecutiveNetworkErrors}): ${e.message}`
+          `  [网络] 获取任务失败 (${consecutiveNetworkErrors}): ${e.message}`,
         );
         await new Promise((r) => setTimeout(r, 10000));
         continue;
       }
 
       if (!job.hasJob) {
-        console.error(`\n[空闲] 暂无 redo 任务，${exploreInterval || 30}s 后重试...`);
+        console.error(
+          `\n[空闲] 暂无 redo 任务，${exploreInterval || 30}s 后重试...`,
+        );
         await new Promise((r) => setTimeout(r, (exploreInterval || 30) * 1000));
         consecutiveNetworkErrors = 0;
         continue;
@@ -363,6 +381,7 @@ export async function handleRefresh(options) {
           maxFollowers: exploreMaxFollowers || 100,
           location: exploreLocation,
           browser,
+          proxyServer: cdpOptions.proxyServer || null,
         },
         console.error,
       );
@@ -387,6 +406,7 @@ export async function handleRefresh(options) {
             maxFollowers: exploreMaxFollowers || 100,
             location: exploreLocation,
             browser,
+            proxyServer: cdpOptions.proxyServer || null,
           },
           console.error,
         );
@@ -424,6 +444,7 @@ export async function handleRefresh(options) {
               maxFollowers: exploreMaxFollowers || 100,
               location: exploreLocation,
               browser,
+              proxyServer: cdpOptions.proxyServer || null,
             },
             console.error,
           );

package/src/lib/args.js

@@ -533,6 +533,7 @@ function parseAttachArgs(args) {
   let interval = 10;
   let serverUrl = defaultServer;
   let countries = [];
+  let customProxy = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -547,6 +548,8 @@ function parseAttachArgs(args) {
         .split(",")
         .map((c) => c.trim().toUpperCase())
         .filter(Boolean);
+    } else if (arg === "--proxy") {
+      customProxy = args[++i];
     }
   }
 
@@ -556,12 +559,12 @@ function parseAttachArgs(args) {
     attachInterval: interval,
     serverUrl,
     attachCountries: countries,
+    customProxy,
     urls: [],
     outputFormat: "json",
     exploreCount: 0,
     showConfig: false,
     showHelp: false,
-    customProxy: null,
     configAction: null,
     configValue: null,
     pipeMode: false,
@@ -806,8 +809,14 @@ export function parseArgs() {
         configKey = args[i + 2];
         configValue = args[i + 3];
         i += 3;
+      } else if (configAction === "unset" || configAction === "reset") {
+        configKey = args[i + 2];
+        i += 2;
       } else {
-        i++;
+        // 简写语法：tt-help config proxy "值" → 当作 set 处理
+        // args.js 层只负责把参数传过去，在 handleConfig 中转换
+        configKey = args[i + 2];
+        i += 2;
       }
     } else if (arg === "--pipe") {
       pipeMode = true;

package/src/lib/browser/cdp.js

@@ -164,7 +164,7 @@ function launchEdgeWithCDP(port, userDataDir, proxyServer) {
       "--disable-sync",
     ];
     if (proxyServer) {
-      extraArgs.push(`--proxy-server="${proxyServer}"`);
+      extraArgs.push(`--proxy-server=${proxyServer}`);
     }
 
     const argsStr = extraArgs.join(" ");
@@ -177,6 +177,8 @@ function launchEdgeWithCDP(port, userDataDir, proxyServer) {
       command = `msedge ${argsStr} &`;
     }
 
+    console.error(`[浏览器] 启动命令: ${command}`);
+
     exec(command, (err) => {
       if (err) reject(new Error(`启动 Edge 浏览器失败: ${err.message}`));
       else resolve();
@@ -219,7 +221,9 @@ export async function ensureBrowserReady(options = {}) {
 
   if (needLaunch) {
     if (isCustom) {
-      console.error(`CDP 端口 ${port} 未就绪，正在启动 Edge 浏览器...`);
+      console.error(
+        `CDP 端口 ${port} 未就绪，正在启动 Edge 浏览器...${proxyServer ? " (代理: " + proxyServer + ")" : ""}`,
+      );
     } else {
       const edgeRunning = await isEdgeRunning();
       if (edgeRunning) {
@@ -230,7 +234,7 @@ export async function ensureBrowserReady(options = {}) {
         console.error(`CDP 端口 ${port} 未就绪，正在启动 Edge 浏览器...`);
       }
     }
-    await launchEdgeWithCDP(port, userDataDir);
+    await launchEdgeWithCDP(port, userDataDir, proxyServer);
 
     console.error("等待浏览器启动...");
     const launched = await waitForCDP(port);
@@ -247,7 +251,7 @@ export async function ensureBrowserReady(options = {}) {
   return browser;
 }
 
-export async function switchAccount(oldAccount, newAccount) {
+export async function switchAccount(oldAccount, newAccount, proxyServer) {
   console.error(`\n[账户切换] 从端口 ${oldAccount.port} -> ${newAccount.port}`);
   console.error(`  [账户切换] 等待 30 秒，请完成当前操作后自动切换...`);
   await new Promise((r) => setTimeout(r, 30000));
@@ -258,6 +262,10 @@ export async function switchAccount(oldAccount, newAccount) {
   const newCdpOptions = {};
   newCdpOptions.port = newAccount.port;
   newCdpOptions.userDataDir = newAccount.userDataDir;
+  if (proxyServer) {
+    newCdpOptions.proxyServer = proxyServer;
+    console.error(`  [账户切换] 代理: ${proxyServer}`);
+  }
 
   const browser = await ensureBrowserReady(newCdpOptions);
 

package/src/lib/browser/page.js

@@ -68,6 +68,8 @@ export async function withBrowserRecovery(fn, browser, page, cdpOptions, port) {
 
 const DOM_CHECK_TIMEOUT = 20000; // 单次 DOM 检测超时 20 秒
 const DOM_CHECK_RETRIES = 3; // DOM 检测最大重试次数
+const SAFE_CHECK_ROUNDS = 2; // 安全登录检测轮数（首次检测 + 额外1轮确认）
+const SAFE_CHECK_INTERVAL = 5000; // 安全登录检测每轮间隔 5 秒
 
 /**
  * 判断登录状态：Cookie 为主，DOM 验真为辅。
@@ -102,6 +104,45 @@ export async function isLoggedIn(page) {
   return true;
 }
 
+/**
+ * 安全登录检测：发现未登录时多检测几轮，避免因 TikTok 页面渲染延迟导致误判。
+ * - 首次检测为已登录 → 直接返回 true
+ * - 首次检测为未登录 → 等待后重新导航并检测，连续 SAFE_CHECK_ROUNDS 轮都为未登录才确认
+ * - 任何一轮检测为已登录 → 立即返回 true
+ */
+export async function safeCheckLogin(page) {
+  // 第一轮检测
+  let loggedIn = await isLoggedIn(page);
+  if (loggedIn) {
+    console.error(`[安全登录检测] 第 1 轮: 已登录 ✓`);
+    return true;
+  }
+  console.error(
+    `[安全登录检测] 第 1 轮: 未登录 ✗，等待 ${SAFE_CHECK_INTERVAL / 1000}s 后重检...`,
+  );
+
+  // 后续轮次：等待后重新导航到 TikTok 页面再检测
+  for (let round = 2; round <= SAFE_CHECK_ROUNDS; round++) {
+    await new Promise((r) => setTimeout(r, SAFE_CHECK_INTERVAL));
+    // 重新导航到 TikTok 页面，确保页面状态刷新
+    await page.goto("https://www.tiktok.com", {
+      waitUntil: "domcontentloaded",
+    });
+    loggedIn = await isLoggedIn(page);
+    if (loggedIn) {
+      console.error(`[安全登录检测] 第 ${round} 轮: 已登录 ✓`);
+      return true;
+    }
+    console.error(`[安全登录检测] 第 ${round} 轮: 未登录 ✗`);
+  }
+
+  // 连续 SAFE_CHECK_ROUNDS 轮都为未登录
+  console.error(
+    `[安全登录检测] 连续 ${SAFE_CHECK_ROUNDS} 轮均为未登录，确认为未登录`,
+  );
+  return false;
+}
+
 /**
  * 通过 DOM 元素判断登录状态（验真方案）
  * 使用 locator API + state: 'attached' 来避免 CDP 连接下 waitForSelector 的可见性问题

package/src/lib/constants.js

@@ -8,7 +8,7 @@ const __dirname = dirname(__filename);
 const homeDir = process.env.HOME || process.env.USERPROFILE || "";
 const configPath = join(homeDir, ".tt-help.json");
 
-const DEFAULT_PROXY = "http://127.0.0.1:7897";
+const DEFAULT_PROXY = null;
 const DEFAULT_OUTPUT = "tiktok_data.json";
 
 let proxy = DEFAULT_PROXY;
@@ -24,8 +24,8 @@ let maxComments = 10;
 try {
   if (existsSync(configPath)) {
     const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
-    if (cfg.proxy) {
-      proxy = cfg.proxy;
+    if (cfg.proxy !== undefined) {
+      proxy = cfg.proxy || null;
     }
     if (cfg.server) {
       server = cfg.server;
@@ -131,33 +131,33 @@ const HELP_TEXT = [
   "      --disable-follow          禁用关注/粉丝提取",
   "      --max-following <数量>    最大获取关注数，默认 50",
   "      --max-followers <数量>    最大获取粉丝数，默认 50",
-      "      --max-users <数量>        最大处理用户数，默认无限制",
-      "      -i, --interval <秒数>     无任务时轮询间隔，默认 10 秒",
-      "      --port <端口号>           固定 CDP 端口（调试用，关闭自动轮换）",
-      "      --base-port <端口号>      起始端口，默认 9222",
-      "      --port-count <数量>       端口数量（账户数），默认 10",
-      "      --user-id <编号>          客户端编号（设备ID），默认自动生成",
-      "      --proxy <地址>            浏览器代理（如 socks5://127.0.0.1:1080）",
-      "",
-      "  tt-help refresh [选项]",
-      "    对目标商家用户进行轮回刷新，重新采集视频 + 关注 + 粉丝",
-      "    筛选条件: tt_seller=1, verified=0, 目标国家",
-      "    选项:",
-      "      --server <URL>            服务端地址，默认 http://127.0.0.1:3001",
-      `      --location <国家代码>     国家筛选，逗号分隔，默认 ${DEFAULT_TARGET_LOCATIONS_CSV}`,
-      "      --max-videos <数量>       每用户最大视频数，默认 16",
-      "      --enable-follow           启用关注/粉丝提取（默认启用）",
-      "      --disable-follow          禁用关注/粉丝提取",
-      "      --max-following <数量>    最大获取关注数，默认 100",
-      "      --max-followers <数量>    最大获取粉丝数，默认 100",
-      "      --max-users <数量>        最大处理用户数，默认无限制",
-      "      -i, --interval <秒数>     无任务时轮询间隔，默认 30 秒",
-      "      --max-age <秒数>          最小刷新间隔，默认 43200（12小时）",
-      "      --port <端口号>           固定 CDP 端口（调试用，关闭自动轮换）",
-      "      --base-port <端口号>      起始端口，默认 9222",
-      "      --port-count <数量>       端口数量（账户数），默认 10",
-      "      --user-id <编号>          客户端编号（设备ID），默认自动生成",
-      "      --proxy <地址>            浏览器代理（如 socks5://127.0.0.1:1080）",
+  "      --max-users <数量>        最大处理用户数，默认无限制",
+  "      -i, --interval <秒数>     无任务时轮询间隔，默认 10 秒",
+  "      --port <端口号>           固定 CDP 端口（调试用，关闭自动轮换）",
+  "      --base-port <端口号>      起始端口，默认 9222",
+  "      --port-count <数量>       端口数量（账户数），默认 10",
+  "      --user-id <编号>          客户端编号（设备ID），默认自动生成",
+  "--proxy <地址>            浏览器代理（如 socks5://127.0.0.1:1080），未指定时使用配置文件 proxy",
+  "",
+  "  tt-help refresh [选项]",
+  "    对目标商家用户进行轮回刷新，重新采集视频 + 关注 + 粉丝",
+  "    筛选条件: tt_seller=1, verified=0, 目标国家",
+  "    选项:",
+  "      --server <URL>            服务端地址，默认 http://127.0.0.1:3001",
+  `      --location <国家代码>     国家筛选，逗号分隔，默认 ${DEFAULT_TARGET_LOCATIONS_CSV}`,
+  "      --max-videos <数量>       每用户最大视频数，默认 16",
+  "      --enable-follow           启用关注/粉丝提取（默认启用）",
+  "      --disable-follow          禁用关注/粉丝提取",
+  "      --max-following <数量>    最大获取关注数，默认 100",
+  "      --max-followers <数量>    最大获取粉丝数，默认 100",
+  "      --max-users <数量>        最大处理用户数，默认无限制",
+  "      -i, --interval <秒数>     无任务时轮询间隔，默认 30 秒",
+  "      --max-age <秒数>          最小刷新间隔，默认 43200（12小时）",
+  "      --port <端口号>           固定 CDP 端口（调试用，关闭自动轮换）",
+  "      --base-port <端口号>      起始端口，默认 9222",
+  "      --port-count <数量>       端口数量（账户数），默认 10",
+  "      --user-id <编号>          客户端编号（设备ID），默认自动生成",
+  "--proxy <地址>            浏览器代理（如 socks5://127.0.0.1:1080），未指定时使用配置文件 proxy",
   "",
   "  tt-help info <URL> [URL2 ...] [--onlyvideo]",
   "    获取用户/视频信息，支持多个 URL",
@@ -208,19 +208,20 @@ const HELP_TEXT = [
   "      POST /api/tiktok/lookup 同时获取视频和作者信息 { videoUrl: string }",
   "    示例: tt-help webserver -p 3000",
   "",
-  "  config  [show|set|reset]",
+  "  config  [show|set|unset|reset]",
   "    config                    查看当前配置",
   "    config set <key> <value>  设置配置（key: proxy, server, browser, userId, maxFollowing, maxFollowers, maxVideos, maxComments）",
+  "    config unset <key>        删除某项配置",
   "    config reset              重置所有配置为默认",
   "",
   "  全局选项:",
   "    -h, --help                显示帮助",
   "    --version                 显示版本号",
   "",
-      "  示例: tt-help info https://www.tiktok.com/@nike https://www.tiktok.com/@adidas",
-      "        tt-help explore qiqi23280 fast --location ES --max-comments 50",
-      "        tt-help refresh --server http://127.0.0.1:3001 --port 9222",
-      "        tt-help config set server http://127.0.0.1:3001",
+  "  示例: tt-help info https://www.tiktok.com/@nike https://www.tiktok.com/@adidas",
+  "        tt-help explore qiqi23280 fast --location ES --max-comments 50",
+  "        tt-help refresh --server http://127.0.0.1:3001 --port 9222",
+  "        tt-help config set server http://127.0.0.1:3001",
   "        tt-help attach -p 5 -i 10",
   "        tt-help watch -o data/result.db",
   "        tt-help videostats data/result.db -p 3",
@@ -282,7 +283,7 @@ function getConfigText() {
     "tt-help v1.0.1",
     "",
     "配置:",
-    `  代理: ${proxy}`,
+    `  代理: ${proxy || "未配置"}`,
     `  服务端: ${server}`,
     `  浏览器: ${browser || "未配置（将自动探测或回退）"}`,
     `  用户号: ${currentUserId || "未设置（首次运行 auto 自动创建）"}`,

package/src/lib/scrape.js

@@ -1,15 +1,31 @@
-import { TikTokScraper } from './tiktok-scraper.mjs';
-import { isProfileUrl, isVideoUrl, extractUniqueId, normalizeUsername } from './url.js';
+import { TikTokScraper } from "./tiktok-scraper.mjs";
+import {
+  isProfileUrl,
+  isVideoUrl,
+  extractUniqueId,
+  normalizeUsername,
+} from "./url.js";
 
 // Lazy singleton for TikTokScraper
 let scraperInstance = null;
 let scraperInitPromise = null;
+let scraperProxyServer = null;
+
+export function setScraperProxy(proxyServer) {
+  // 只在代理变化时才关闭重建
+  if (scraperProxyServer === proxyServer) return;
+  scraperProxyServer = proxyServer;
+  if (scraperInstance) {
+    scraperInstance.close().catch(() => {});
+    scraperInstance = null;
+  }
+}
 
 async function getScraper() {
   if (scraperInstance) return scraperInstance;
   if (scraperInitPromise) return scraperInitPromise;
   scraperInitPromise = (async () => {
-    const scraper = new TikTokScraper();
+    const scraper = new TikTokScraper({ proxyServer: scraperProxyServer });
     await scraper.init();
     scraperInstance = scraper;
     scraperInitPromise = null;
@@ -57,7 +73,7 @@ export async function extractUserData(url) {
   const uniqueId = extractUniqueId(url);
   if (!uniqueId) throw new Error(`无法从URL提取用户名: ${url}`);
   const user = await scraper.getUserInfo(normalizeUsername(uniqueId));
-  if (!user) throw new Error('无法解析用户信息');
+  if (!user) throw new Error("无法解析用户信息");
   return mapUserInfo(user);
 }