tt-help-cli-ycl 1.2.0 → 1.3.1

package/src/lib/args.js

@@ -74,9 +74,7 @@ function parseAutoArgs(args) {
   let autoPreset = 'fast';
   let autoSwitchDelay = null;
   let autoCommentDelay = null;
-  let outputFile = null;
-  let autoWatch = false;
-  let autoWatchPort = 3000;
+  let serverUrl = 'http://127.0.0.1:3000';
   let autoEnableFollow = false;
   let autoMaxFollowing = 200;
   let autoMaxFollowers = 200;
@@ -86,20 +84,12 @@ function parseAutoArgs(args) {
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg === '-o' || arg === '--output') {
-      outputFile = args[++i];
-    } else if (arg === '--switch-delay') {
+    if (arg === '--server') {
+      serverUrl = args[++i];
+    } else if (arg === '--switch-delay') {
       autoSwitchDelay = parseInt(args[++i]) || null;
     } else if (arg === '--comment-delay') {
       autoCommentDelay = parseInt(args[++i]) || null;
-    } else if (arg === '--watch') {
-      autoWatch = true;
-      if (args[i + 1] === '-p') {
-        autoWatchPort = parseInt(args[i + 2]) || 3000;
-        i += 2;
-      }
-    } else if (arg === '-p' && autoWatch) {
-      autoWatchPort = parseInt(args[++i]) || 3000;
     } else if (arg === '--enable-follow') {
       autoEnableFollow = true;
     } else if (arg === '--max-following') {
@@ -144,9 +134,7 @@ function parseAutoArgs(args) {
     autoPreset,
     autoSwitchDelay,
     autoCommentDelay,
-    outputFile,
-    autoWatch,
-    autoWatchPort,
+    serverUrl,
     autoEnableFollow,
     autoMaxFollowing,
     autoMaxFollowers,
@@ -164,16 +152,14 @@ function parseAutoArgs(args) {
 }
 
 function parseExploreArgs(args) {
-  let outputFile = null;
+  let serverUrl = 'http://127.0.0.1:3000';
   let explorePreset = 'normal';
-  let exploreMaxComments = 100;
+  let exploreMaxComments = 10;
   let exploreMaxGuess = 0;
   let exploreEnableFollow = true;
-  let exploreMaxFollowing = 200;
-  let exploreMaxFollowers = 200;
+  let exploreMaxFollowing = 5;
+  let exploreMaxFollowers = 5;
   let exploreLocation = 'ES';
-  let exploreWatch = false;
-  let exploreWatchPort = 3000;
   let exploreMaxUsers = 0;
 
   const positional = [];
@@ -181,8 +167,8 @@ function parseExploreArgs(args) {
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg === '-o' || arg === '--output') {
-      outputFile = args[++i];
+    if (arg === '--server') {
+      serverUrl = args[++i];
     } else if (arg === '--max-comments') {
       exploreMaxComments = parseInt(args[++i]) || 0;
     } else if (arg === '--max-guess') {
@@ -194,17 +180,11 @@ function parseExploreArgs(args) {
     } else if (arg === '--disable-follow') {
       exploreEnableFollow = false;
     } else if (arg === '--max-following') {
-      exploreMaxFollowing = parseInt(args[++i]) || 200;
+      exploreMaxFollowing = parseInt(args[++i]) || 5;
     } else if (arg === '--max-followers') {
-      exploreMaxFollowers = parseInt(args[++i]) || 200;
+      exploreMaxFollowers = parseInt(args[++i]) || 5;
     } else if (arg === '--max-users') {
       exploreMaxUsers = parseInt(args[++i]) || 0;
-    } else if (arg === '--watch') {
-      exploreWatch = true;
-      if (args[i + 1] === '-p') {
-        exploreWatchPort = parseInt(args[i + 2]) || 3000;
-        i += 2;
-      }
     } else {
       positional.push(arg);
     }
@@ -232,10 +212,8 @@ function parseExploreArgs(args) {
     exploreMaxFollowing,
     exploreMaxFollowers,
     exploreLocation,
-    exploreWatch,
-    exploreWatchPort,
+    serverUrl,
     exploreMaxUsers,
-    outputFile,
     urls: [],
     outputFormat: 'json',
     exploreCount: 0,
@@ -287,7 +265,7 @@ function parseVideosArgs(args) {
 }
 
 function parseWatchArgs(args) {
-  let outputFile = null;
+  let outputFile = './result.json';
   let watchPort = 3000;
 
   for (let i = 0; i < args.length; i++) {
@@ -346,6 +324,7 @@ export function parseArgs() {
   let exploreCount = 0;
   let showConfig = false;
   let showHelp = false;
+  let showVersion = false;
   let customProxy = null;
   let configAction = null;
   let configValue = null;
@@ -383,6 +362,8 @@ export function parseArgs() {
       showConfig = true;
     } else if (arg === '-h' || arg === '--help') {
       showHelp = true;
+    } else if (arg === '--version') {
+      showVersion = true;
     } else if (arg.startsWith('http')) {
       urls.push(arg);
     }
@@ -394,5 +375,5 @@ export function parseArgs() {
     urls.push(...lines);
   }
 
-  return { urls, outputFile, outputFormat, exploreCount, showConfig, showHelp, customProxy, configAction, configValue, pipeMode, filterStr };
+  return { urls, outputFile, outputFormat, exploreCount, showConfig, showHelp, showVersion, customProxy, configAction, configValue, pipeMode, filterStr };
 }

package/src/lib/auto-browser.mjs

@@ -1,13 +1,6 @@
-import { createRequire } from 'module';
+import { processUser } from '../auto-core.mjs';
+import { processExplore } from '../explore-core.mjs';
+import { ensureBrowserReady } from '../scraper/modules/page-helpers.mjs';
+import { ensureTikTokPage, closeCommentPanel } from '../scraper/modules/page-helpers.mjs';
 
-const require = createRequire(import.meta.url);
-const core = require('../auto-core.cjs');
-const exploreCore = require('../explore-core.cjs');
-const helpers = require('../scraper/modules/page-helpers.cjs');
-
-export const runAuto = core.runAuto;
-export const processUser = core.processUser;
-export const processExplore = exploreCore.processExplore;
-export const ensureBrowserReady = helpers.ensureBrowserReady;
-export const ensureTikTokPage = helpers.ensureTikTokPage;
-export const closeCommentPanel = helpers.closeCommentPanel;
+export { processUser, processExplore, ensureBrowserReady, ensureTikTokPage, closeCommentPanel };

package/src/lib/browser/anti-detect.js

@@ -0,0 +1,23 @@
+export function getAntiDetectScript() {
+  return () => {
+    Object.defineProperty(navigator, 'webdriver', { get: () => false });
+
+    if (!window.chrome) {
+      window.chrome = { runtime: {} };
+    }
+
+    const originalQuery = window.navigator.permissions.query;
+    window.navigator.permissions.query = (params) =>
+      params.name === 'notifications'
+        ? Promise.resolve({ state: Notification.permission })
+        : originalQuery(params);
+
+    Object.defineProperty(navigator, 'languages', {
+      get: () => ['en-US', 'en'],
+    });
+
+    Object.defineProperty(navigator, 'plugins', {
+      get: () => [1, 2, 3, 4, 5],
+    });
+  };
+}

package/src/lib/browser/cdp.js

@@ -0,0 +1,142 @@
+import { exec } from 'child_process';
+import http from 'http';
+import os from 'os';
+import path from 'path';
+import { chromium } from 'playwright';
+
+export const CDP_PORT = 9222;
+
+function getEdgePath() {
+  const platform = os.platform();
+  if (platform === 'darwin') return '"Microsoft Edge"';
+  if (platform === 'win32') return 'msedge.exe';
+  return 'msedge';
+}
+
+function isEdgeRunning() {
+  return new Promise(resolve => {
+    const platform = os.platform();
+    let command;
+    if (platform === 'darwin') {
+      command = 'ps aux | grep -q "[M]icrosoft Edge.app/Contents/MacOS/Microsoft Edge" 2>/dev/null';
+    } else if (platform === 'win32') {
+      command = 'tasklist /FI "IMAGENAME eq msedge.exe" 2>nul | findstr /I msedge';
+    } else {
+      command = 'pgrep -f msedge > /dev/null 2>&1';
+    }
+    exec(command, (err) => resolve(!err));
+  });
+}
+
+function checkCDPPort() {
+  return new Promise(resolve => {
+    const req = http.get(`http://127.0.0.1:${CDP_PORT}/json`, res => {
+      res.on('data', () => {});
+      res.on('end', () => resolve(res.statusCode === 200));
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(3000, () => { resolve(false); req.destroy(); });
+  });
+}
+
+function checkEdgeArgs() {
+  return new Promise(resolve => {
+    const platform = os.platform();
+    let command;
+    if (platform === 'darwin') {
+      command = 'ps aux | grep "[M]icrosoft Edge" | grep -v "Helper\\|crashpad" | grep "user-data-dir"';
+    } else if (platform === 'win32') {
+      command = 'wmic process where "name like \\"%msedge%\\"" get commandline | findstr "user-data-dir"';
+    } else {
+      command = 'ps aux | grep "[m]sedge" | grep -v "Helper\\|crashpad" | grep "user-data-dir"';
+    }
+    exec(command, (err, stdout) => resolve(!err && stdout.trim().length > 0));
+  });
+}
+
+function killEdgeProcesses() {
+  return new Promise(resolve => {
+    const platform = os.platform();
+    let command;
+    if (platform === 'darwin') {
+      command = 'killall -9 "Microsoft Edge" 2>/dev/null; rm -f ~/Library/Caches/Microsoft\\ Edge/Singleton*; true';
+    } else if (platform === 'win32') {
+      command = 'taskkill /F /IM msedge.exe 2>nul || exit 0';
+    } else {
+      command = 'pkill -9 -f msedge 2>/dev/null; true';
+    }
+    exec(command, () => resolve());
+  });
+}
+
+function launchEdgeWithCDP() {
+  return new Promise((resolve, reject) => {
+    const platform = os.platform();
+    const edgePath = getEdgePath();
+    const userDataDir = path.join(os.homedir(), 'Library', 'Application Support', 'Microsoft Edge For Testing');
+    let command;
+
+    if (platform === 'darwin') {
+      command = `open -a ${edgePath} --args --remote-debugging-port=${CDP_PORT} --user-data-dir="${userDataDir}"`;
+    } else if (platform === 'win32') {
+      command = `start msedge --remote-debugging-port=${CDP_PORT} --user-data-dir="${userDataDir}"`;
+    } else {
+      command = `msedge --remote-debugging-port=${CDP_PORT} --user-data-dir="${userDataDir}" &`;
+    }
+
+    exec(command, (err) => {
+      if (err) reject(new Error(`启动 Edge 浏览器失败: ${err.message}`));
+      else resolve();
+    });
+  });
+}
+
+async function waitForCDP(timeout = 30000, interval = 1000) {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    const ready = await checkCDPPort();
+    if (ready) return true;
+    await new Promise(r => setTimeout(r, interval));
+  }
+  return false;
+}
+
+export async function ensureBrowserReady() {
+  const isReady = await checkCDPPort();
+  let needLaunch = !isReady;
+
+  if (!needLaunch) {
+    const edgeArgsValid = await checkEdgeArgs();
+    if (!edgeArgsValid) {
+      console.error('Edge 已运行但启动参数不完整，正在重启...');
+      await killEdgeProcesses();
+      await new Promise(r => setTimeout(r, 3000));
+      needLaunch = true;
+    }
+  }
+
+  if (needLaunch) {
+    const edgeRunning = await isEdgeRunning();
+    if (edgeRunning) {
+      console.error(`Edge 已运行但 CDP 端口 ${CDP_PORT} 未启用，正在重启...`);
+      await killEdgeProcesses();
+      await new Promise(r => setTimeout(r, 3000));
+    } else {
+      console.error(`CDP 端口 ${CDP_PORT} 未就绪，正在启动 Edge 浏览器...`);
+    }
+    await launchEdgeWithCDP();
+
+    console.error('等待浏览器启动...');
+    const launched = await waitForCDP();
+    if (!launched) {
+      throw new Error(
+        `等待 CDP 端口 ${CDP_PORT} 超时。请确认 Edge 浏览器已安装，\n` +
+        '或手动启动: Microsoft Edge --remote-debugging-port=9222'
+      );
+    }
+    console.error('浏览器启动成功');
+  }
+
+  const browser = await chromium.connectOverCDP(`http://127.0.0.1:${CDP_PORT}`);
+  return browser;
+}

package/src/lib/browser/launch.js

@@ -0,0 +1,43 @@
+import { accessSync } from 'fs';
+
+export function detectBrowser() {
+  const isMac = process.platform === 'darwin';
+  const isWin = process.platform === 'win32';
+  const isLinux = process.platform === 'linux';
+
+  const paths = [];
+
+  if (isMac) {
+    paths.push(
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+      '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+      '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    );
+  } else if (isWin) {
+    const localAppData = process.env.LOCALAPPDATA || '';
+    const programFiles = process.env.PROGRAMFILES || '';
+    const programFilesX86 = process.env['PROGRAMFILES(X86)'] || '';
+    paths.push(
+      `${programFiles}\\Google\\Chrome\\Application\\chrome.exe`,
+      `${programFilesX86}\\Google\\Chrome\\Application\\chrome.exe`,
+      `${localAppData}\\Google\\Chrome\\Application\\chrome.exe`,
+      `${programFiles}\\Microsoft\\Edge\\Application\\msedge.exe`,
+      `${programFilesX86}\\Microsoft\\Edge\\Application\\msedge.exe`,
+    );
+  } else if (isLinux) {
+    paths.push(
+      '/usr/bin/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/chromium-browser',
+      '/usr/bin/chromium',
+      '/snap/bin/chromium',
+      '/usr/bin/microsoft-edge',
+    );
+  }
+
+  for (const p of paths) {
+    try { accessSync(p); return p; } catch { /* not found */ }
+  }
+  return null;
+}

package/src/lib/browser/page.js

@@ -0,0 +1,62 @@
+import { delay } from '../delay.js';
+import { retryWithBackoff } from '../retry.js';
+import { getDelayConfig } from '../delay.js';
+
+export async function closeCommentPanel(page) {
+  await page.evaluate(() => {
+    const rightPanel = document.querySelector('[class*="RightPanelContainer"]');
+    if (rightPanel) {
+      const tabContainer = rightPanel.querySelector('[class*="TabContainer"]');
+      if (tabContainer) {
+        const closeOverlay = tabContainer.querySelector('div:last-child');
+        if (closeOverlay) closeOverlay.click();
+      }
+    }
+  });
+}
+
+export async function ensureTikTokPage(browser, url) {
+  const contexts = browser.contexts();
+  let page = null;
+
+  for (const ctx of contexts) {
+    for (const p of ctx.pages()) {
+      if (p.url().includes('tiktok.com')) {
+        page = p;
+        break;
+      }
+    }
+    if (page) break;
+  }
+
+  if (!page) {
+    console.error('未找到 TikTok 页面，正在打开...');
+    const defaultCtx = browser.contexts()[0];
+    page = await defaultCtx.newPage();
+    await retryWithBackoff(() => page.goto(url, { waitUntil: 'load', timeout: 30000 }));
+    const config = getDelayConfig();
+    await delay(Math.round(config.switchMax * 0.5), config.switchMax);
+    console.error('TikTok 页面已打开');
+  }
+
+  return page;
+}
+
+export async function findTikTokPage(browser) {
+  const contexts = browser.contexts();
+  for (const ctx of contexts) {
+    for (const p of ctx.pages()) {
+      if (p.url().includes('tiktok.com')) return p;
+    }
+  }
+  return null;
+}
+
+export async function getOrCreatePage(browser) {
+  let page = await findTikTokPage(browser);
+  if (!page) {
+    const defaultCtx = browser.contexts()[0] || await browser.newContext();
+    page = await defaultCtx.newPage();
+  }
+  return page;
+}

package/src/lib/constants.js

@@ -1,6 +1,7 @@
 import { join, dirname } from 'path';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { fileURLToPath } from 'url';
+import { USER_SECTION_SIZE } from './parser.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -9,7 +10,6 @@ const configPath = join(homeDir, '.tt-help.json');
 
 const DEFAULT_PROXY = 'http://127.0.0.1:7897';
 const DEFAULT_OUTPUT = 'tiktok_data.json';
-const USER_SECTION_SIZE = 12000;
 
 let proxy = DEFAULT_PROXY;
 let configFile = null;
@@ -39,109 +39,27 @@ function saveBrowser(path) {
 }
 
 const HELP_TEXT = [
-  '用法: tt-help [选项]',
-  '       tt-help scrape <URL> [预设] [选项]',
-  '       tt-help videos <用户名> [最大视频数] [选项]',
-  '       tt-help auto <用户名> [preset] [收集数] [切换数] [每视频评论数] [选项]',
+  '用法: tt-help explore <用户名> [preset] [选项]',
   '',
-  '参数:',
-  '  explore <用户名> [preset] [选项]    用户探索模式',
-  '  --explore [count]      从 Explore 页面获取视频列表（默认: 100）',
-  '  --pipe                 将 Explore 结果自动传给 URL 爬取',
-  '',
-  '用户探索模式 (explore):',
-  '  tt-help explore <用户名> [preset] [选项]',
-  '  支持多个用户名: tt-help explore @user1 @user2 -o data.json',
+  '  支持多个用户名: tt-help explore @user1 @user2 --server http://127.0.0.1:3000',
   '  预设: fast, normal（默认）, slow, stealth',
   '  选项:',
+  '    --server <URL>            服务端地址，默认 http://127.0.0.1:3000',
   '    --location <国家代码>     国家筛选，默认 ES',
-  '    --max-comments <数量>     每视频最大评论数，默认 100',
+  '    --max-comments <数量>     每视频最大评论数，默认 10',
   '    --max-guess <数量>        每视频最大猜你喜欢数，默认 0',
   '    --enable-follow           启用关注/粉丝提取（默认启用）',
   '    --disable-follow          禁用关注/粉丝提取',
-  '    --max-following <数量>    最大获取关注数，默认 200',
-  '    --max-followers <数量>    最大获取粉丝数，默认 200',
+  '    --max-following <数量>    最大获取关注数，默认 5',
+  '    --max-followers <数量>    最大获取粉丝数，默认 5',
   '    --max-users <数量>        最大处理用户数，默认无限制',
-  '    --watch [-p 端口]         启动 Web 监控页面',
-  '  示例: tt-help explore qiqi23280 fast --location ES --max-comments 50 -o results.json',
-  '  --proxy <地址>          临时指定代理地址',
-  '  --filter <条件>         过滤结果（格式: key=value&key2=value2）',
-  '  -i, --input <file>     从文件读取 URL 列表（每行一个）',
-  '  -o, --output <file>    指定输出文件（默认: tiktok_data.json）',
-  '  -f, --format <fmt>     输出格式: json（默认）, table, raw',
-  '  -c, --config           显示当前配置',
-  '  -h, --help             显示帮助',
-  '',
-  '浏览器抓取模式 (scrape):',
-  '  tt-help scrape <URL> [preset] [最大视频数] [最大评论数] [-o 输出路径]',
-  '  tt-help scrape <URL> [最大视频数] [最大评论数] [--switch-delay ms] [--comment-delay ms]',
-  '  预设: fast(600ms/400ms), normal(1.5s/800ms), slow(3s/2s), stealth(5s/3.5s)',
-  '  不指定 -o 则输出到 stdout（可 pipe）',
-  '',
-  '用户视频模式 (videos):',
-  '  tt-help videos <用户名> [最大视频数] [-o 输出路径]',
-  '  获取用户信息和视频列表（浏览器模式）',
-  '  不指定 -o 则输出到 stdout（可 pipe）',
-  '',
-  '自动探索模式 (auto):',
-  '  tt-help auto [用户名...] [preset] [收集数] [切换数] [每视频评论数] [选项]',
-  '  支持多个用户名: tt-help auto @user1 @user2 -o data.json',
-  '  不指定用户名: 从 -o 数据源中读取未处理的用户继续探索',
-  '  收集数: 从种子用户收集的种子视频数（默认 1）',
-  '  切换数: 每个种子作者主页下切换视频的次数（默认 50）',
-  '  每视频评论数: 每个视频抓取评论数（默认 200）',
-  '  预设: fast（默认）, normal, slow, stealth',
-  '  选项: -o <路径>             数据源文件（不指定则输出到 stdout）',
-  '        --switch-delay <ms>   视频切换延迟（毫秒）',
-  '        --comment-delay <ms>  评论滚动延迟（毫秒）',
-  '        --watch [-p 3000]     启动 Web 监控页面实时查看数据',
-  '        --enable-follow       启用关注/粉丝列表提取（需已登录）',
-  '        --max-following <n>   关注列表最大提取数（默认 200）',
-  '        --max-followers <n>   粉丝列表最大提取数（默认 200）',
-  '  返回: 纯用户数组，按 uniqueId 去重',
-  '  示例: tt-help auto username -o result.json',
-  '        tt-help auto @a @b fast 1 30 100 -o data.json',
-  '        tt-help auto -o data.json                  # 续跑',
-  '        tt-help auto username --watch -o data.json  # 带监控页面',
-  '',
-  '实时监控模式 (watch):',
-  '  tt-help watch -o <数据文件> [-p 端口]',
-  '  启动 Web 监控页面，实时查看采集数据',
-  '  支持在 auto 模式中通过 --watch 参数同时启动',
-  '  示例: tt-help watch -o data.json',
-  '        tt-help watch -o data.json -p 8080',
+  '    --proxy <地址>            临时指定代理地址',
+  '    -o, --output <file>       指定输出文件（默认: tiktok_data.json）',
+  '    -h, --help                显示帮助',
+  '    --version                 显示版本号',
   '',
-  '过滤示例:',
-  '  --filter "ttSeller=true&verified=false"           过滤卖家且未认证',
-  '  --filter "locationCreated=DE,ES"                  过滤指定地区',
-  '  --filter "ttSeller=true&locationCreated=US"       组合条件',
-  '',
-  '配置代理:',
-  '  tt-help config set http://127.0.0.1:7890  设置代理',
-  '  tt-help config show                        查看配置',
-  '  tt-help config reset                       恢复默认',
-  '',
-  '配置浏览器:',
-  '  tt-help config set-browser /path/to/chrome  手动指定浏览器路径',
-  '  tt-help config set-browser auto             自动探测浏览器',
-  '',
-  '示例:',
-  '  tt-help --explore 200                    # 先预览 Explore 结果',
-  '  tt-help --explore 50 --pipe -o result.json  # 自动抓取用户数据',
-  '  tt-help --explore -f raw                 # 仅输出 URL 列表',
-  '  tt-help --explore -f raw -o urls.txt     # 保存 URL 到文件',
-  '  tt-help -i urls.txt -o result.json       # 再爬取这些 URL',
-  '  tt-help scrape <URL> fast 50 999        # 浏览器抓取（快速预设）',
-  '  tt-help scrape <URL> slow -o out.json    # 慢速预设，输出到文件',
-  '  tt-help scrape <URL> 20 999 | jq .       # 输出到 stdout 可 pipe',
-  '  tt-help videos username 100              # 获取用户 100 个视频',
-  '  tt-help videos username 50 -o out.json   # 输出到文件',
-  '  tt-help auto username -o out.json  # 自动探索（默认 fast/1/50/200）',
-  '  tt-help auto username slow 1 30 100 -o out.json  # 慢速探索',
-  '  tt-help config set http://127.0.0.1:7890',
-  '  tt-help https://www.tiktok.com/@username',
-  '  tt-help https://... --filter "ttSeller=true&locationCreated=DE"',
-];
+  '  示例: tt-help explore qiqi23280 fast --location ES --max-comments 50',
+];
 
 const CONFIG_TEXT = [
   'tt-help v1.0.1',

package/src/lib/delay.js

@@ -0,0 +1,54 @@
+export const DELAY_PRESETS = {
+  fast:    { switchMax: 300, commentMax: 200, fast: true },
+  normal:  { switchMax: 1500, commentMax: 800 },
+  slow:    { switchMax: 3000, commentMax: 2000 },
+  stealth: { switchMax: 5000, commentMax: 3500 },
+};
+
+const delayConfig = {
+  switchMax: 2500,
+  commentMax: 1500,
+  fast: false,
+};
+
+export function setDelayConfig(config) {
+  if (typeof config === 'string') {
+    const preset = DELAY_PRESETS[config.toLowerCase()];
+    if (!preset) {
+      throw new Error(
+        `未知的延迟预设: ${config}\n可用预设: ${Object.keys(DELAY_PRESETS).join(', ')}`
+      );
+    }
+    delayConfig.switchMax = preset.switchMax;
+    delayConfig.commentMax = preset.commentMax;
+    delayConfig.fast = preset.fast || false;
+  } else if (typeof config === 'object') {
+    if (config.switchMax) delayConfig.switchMax = config.switchMax;
+    if (config.commentMax) delayConfig.commentMax = config.commentMax;
+    delayConfig.fast = config.fast || false;
+  }
+}
+
+export function getDelayConfig() {
+  return { ...delayConfig };
+}
+
+export function listDelayPresets() {
+  return DELAY_PRESETS;
+}
+
+export function delay(min, max) {
+  const lo = Math.min(min, max);
+  const hi = Math.max(min, max);
+  let ms;
+  if (delayConfig.fast) {
+    ms = 0;
+  } else {
+    ms = Math.floor(Math.random() * (hi - lo + 1)) + lo;
+  }
+  return new Promise(r => setTimeout(r, ms));
+}
+
+export function randomDelay(min = 200, max = 600) {
+  return delay(min, max);
+}