tt-help-cli-ycl 1.4.12 → 1.4.14

package/package.json

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

package/src/cli/comments.js

@@ -528,6 +528,7 @@ async function runAutoMode(options) {
     maxComments,
     basePort,
     proxy: proxyOption,
+    locations,
   } = options;
 
   const actualParallel = Math.max(1, parallel || CFG.parallel);
@@ -535,6 +536,7 @@ async function runAutoMode(options) {
   const actualMaxComments = maxComments || CFG.maxComments;
   const effectiveProxy = proxyOption || configuredProxy;
   const portPoolStart = basePort || CFG.portPoolStart;
+  const jobLocations = locations || null;
 
   loadEnvConfig();
 
@@ -597,8 +599,9 @@ async function runAutoMode(options) {
   console.error(`\n╔══════════════════════════════════════════╗`);
   console.error(`║     自动评论采集模式（CDP 连接已登录浏览器）`);
   console.error(
-    `║  目标国家: ${DEFAULT_TARGET_LOCATIONS.slice(0, 6).join(",")}...`,
+    `║  目标国家: ${jobLocations || DEFAULT_TARGET_LOCATIONS.slice(0, 6).join(",") + "..."}`,
   );
+  if (jobLocations) console.error(`║  任务过滤: ${jobLocations}`);
   console.error(`║  服务端:   ${serverUrl}`);
   console.error(
     `║  CDP 端口池: ${portPoolStart}-${portPoolStart + CFG.portPoolSize - 1}（当前: ${session.port}）`,
@@ -635,9 +638,10 @@ async function runAutoMode(options) {
         // ── 领取任务 ──
         let tasks;
         try {
-          const resp = await apiGet(
-            `${serverUrl}/api/comment-tasks?limit=${actualParallel}`,
-          );
+          const apiUrl = jobLocations
+            ? `${serverUrl}/api/comment-tasks?limit=${actualParallel}&locations=${encodeURIComponent(jobLocations)}`
+            : `${serverUrl}/api/comment-tasks?limit=${actualParallel}`;
+          const resp = await apiGet(apiUrl);
           tasks = resp.tasks || [];
         } catch (err) {
           console.error(`  × 获取任务失败: ${err.message}`);
@@ -1031,6 +1035,7 @@ export async function handleComments(options) {
     commentsServer,
     commentsBasePort,
     commentsProxy,
+    commentsLocations,
   } = options;
 
   // 自动模式：无 URL
@@ -1042,6 +1047,7 @@ export async function handleComments(options) {
       maxComments: commentsMax,
       basePort: commentsBasePort,
       proxy: commentsProxy,
+      locations: commentsLocations,
     });
   }
 

package/src/cli/tag.js

@@ -171,6 +171,82 @@ async function pushToServer(
   return data;
 }
 
+/**
+ * 带服务端缓存的批量 enrich：先从服务端查询已有国家信息，只对未知的做 HTTP enrich
+ * @returns {{ videos: Array, cdnBlockedCount: number }}
+ */
+async function enrichWithServerCache(
+  videos,
+  baseUrl,
+  enrichScraper,
+  options = {},
+) {
+  const { clientId, clientMeta, effectiveProxy, log } = options;
+  const logFn = log || (() => {});
+
+  // Step 1: 收集所有唯一作者 ID
+  const uniqueAuthors = [
+    ...new Set(videos.map((v) => v.authorUniqueId).filter(Boolean)),
+  ];
+
+  // Step 2: 批量查询服务端已知国家
+  let knownLocations = {};
+  if (uniqueAuthors.length > 0 && baseUrl) {
+    try {
+      const res = await fetch(`${baseUrl}/api/bulk-author-locations`, {
+        method: "POST",
+        headers: buildClientHeaders(clientId || "", clientMeta || {}, {
+          "Content-Type": "application/json",
+        }),
+        body: JSON.stringify({ uniqueIds: uniqueAuthors }),
+      });
+      const data = await res.json();
+      knownLocations = data.locations || {};
+      const knownCount = Object.keys(knownLocations).length;
+      if (knownCount > 0) {
+        logFn(
+          `  📋 服务端已知 ${knownCount}/${uniqueAuthors.length} 个作者的国家`,
+        );
+      }
+    } catch {
+      // 查询失败则全部走 enrich，不影响主流程
+    }
+  }
+
+  // Step 3: 给已知国家的视频赋值，收集未知视频
+  const unknownVideos = [];
+  for (const v of videos) {
+    const loc = knownLocations[v.authorUniqueId];
+    if (loc) {
+      v.locationCreated = loc;
+    } else {
+      unknownVideos.push(v);
+    }
+  }
+
+  // Step 4: 只对未知视频做 HTTP enrich
+  let cdnBlockedCount = 0;
+  if (unknownVideos.length > 0) {
+    const enrichOpts = {
+      mode: "videos",
+      existingScraper: enrichScraper,
+      onProgress: ({ done, total, current, locationCreated }) => {
+        if (done % 10 === 0 || done === total) {
+          process.stderr.write(
+            `\r    [${done}/${total}] ${current.split("/").pop().slice(0, 20)} → ${locationCreated || "-"}\x1b[K`,
+          );
+        }
+      },
+    };
+    if (effectiveProxy) enrichOpts.proxyServer = effectiveProxy;
+    const enriched = await enrichVideosWithLocation(unknownVideos, enrichOpts);
+    // 将 enrich 结果写回原数组（v 是引用，已经被 enrichVideosWithLocation 修改）
+    cdnBlockedCount = enriched.cdnBlockedCount || 0;
+  }
+
+  return { videos, cdnBlockedCount };
+}
+
 // 共享算分逻辑（handleScore / handleScoreAll 共用）
 function calcScore(authorCount, matchedAuthors, filteredVideoCount) {
   const densityScore =
@@ -1002,20 +1078,18 @@ export async function handleScoreAll(parsed) {
           continue;
         }
 
-        // enrich: 逐个视频查 view-source 获取国家
-        const enrichOpts = {
-          mode: "videos",
-          existingScraper: enrichScraper,
-          onProgress: ({ done, total, current, locationCreated }) => {
-            if (done % 10 === 0 || done === total) {
-              process.stderr.write(
-                `\r    [${done}/${total}] ${current.split("/").pop().slice(0, 20)} → ${locationCreated || "-"}\x1b[K`,
-              );
-            }
+        // enrich: 先查服务端缓存，只对未知视频发 HTTP 请求
+        const enriched = await enrichWithServerCache(
+          videos,
+          baseUrl,
+          enrichScraper,
+          {
+            clientId,
+            clientMeta,
+            effectiveProxy,
+            log,
           },
-        };
-        if (effectiveProxy) enrichOpts.proxyServer = effectiveProxy;
-        const enriched = await enrichVideosWithLocation(videos, enrichOpts);
+        );
         videos = enriched.videos;
 
         // CDN 限流检测：有拦截则冷却 + 重启 scraper
@@ -1324,3 +1398,429 @@ export async function handleTag(parsed) {
     console.log(json);
   }
 }
+
+// ====== Productive 标签刷新（重新抓取，不打分） ======
+
+export async function handleTagRefresh(parsed) {
+  const { tagRefresh } = parsed;
+  const { serverUrl, port, proxy: cliProxy } = tagRefresh || {};
+
+  const baseUrl = serverUrl || DEFAULT_SERVER;
+  const defaultRefreshPort =
+    parseInt(process.env.TAG_REFRESH_PORT_POOL_START || "8222", 10) || 8222;
+  let cdpPort = port || defaultRefreshPort;
+  const effectiveProxy = cliProxy || configuredProxy;
+
+  const log = (...args) => process.stderr.write(args.join(" ") + "\n");
+
+  log("");
+  log("╔══════════════════════════════════════════╗");
+  log("║     Productive 标签刷新模式（重新抓取）");
+  log("║     服务端:   " + baseUrl);
+  log(
+    "║     CDP 端口: " +
+      cdpPort +
+      (effectiveProxy ? "  代理: " + effectiveProxy : ""),
+  );
+  log("║     只抓取不重新打分，score>70 的标签");
+  log("╚══════════════════════════════════════════╝");
+  log("");
+
+  log(`📊 启动内存: ${formatMemoryWithBrowser(cdpPort)}`);
+  log("");
+
+  // ── 设备标识 ──
+  let userId = configuredUserId;
+  if (!userId) {
+    userId = await getMacOrUuid();
+    saveUserId(userId);
+  }
+
+  // 连接 CDP 浏览器
+  const cdpOpts = { port: cdpPort };
+  if (effectiveProxy) cdpOpts.proxyServer = effectiveProxy;
+  let browser = await ensureBrowserReady(cdpOpts);
+  let page = await getOrCreatePage(browser);
+  const blockedRoutePages = new WeakSet();
+
+  async function setupPageRequestBlocking(targetPage) {
+    if (!targetPage || blockedRoutePages.has(targetPage)) return;
+    await targetPage.route("**/*", (route) => {
+      const resourceType = route.request().resourceType();
+      if (resourceType === "image" || resourceType === "stylesheet") {
+        route.abort();
+      } else {
+        route.continue();
+      }
+    });
+    blockedRoutePages.add(targetPage);
+  }
+
+  await setupPageRequestBlocking(page);
+
+  // 端口池
+  const portPoolStart = cdpPort;
+  const portPoolSize = Math.max(
+    2,
+    parseInt(process.env.TAG_REFRESH_PORT_POOL_SIZE || "10", 10) || 10,
+  );
+
+  function pickNextPort(currentPort) {
+    const candidates = [];
+    for (let i = 0; i < portPoolSize; i++) {
+      const p = portPoolStart + i;
+      if (p !== currentPort) candidates.push(p);
+    }
+    if (candidates.length === 0) return currentPort;
+    return candidates[Math.floor(Math.random() * candidates.length)];
+  }
+
+  // ── 内存回收配置 ──
+  const RECYCLE_CONFIG = {
+    nodeRssMb: Math.max(
+      256,
+      parseInt(process.env.TAG_REFRESH_RECYCLE_RSS_MB || "2000", 10) || 2000,
+    ),
+    nodeHeapMb: Math.max(
+      128,
+      parseInt(process.env.TAG_REFRESH_RECYCLE_HEAP_MB || "2000", 10) || 2000,
+    ),
+    edgeMb: Math.max(
+      500,
+      parseInt(process.env.TAG_REFRESH_RECYCLE_EDGE_MB || "2000", 10) || 2000,
+    ),
+    cooldownMs: Math.max(
+      0,
+      parseInt(process.env.TAG_REFRESH_RECYCLE_COOLDOWN_MS || "180000", 10) ||
+        180000,
+    ),
+    periodicEvery: Math.max(
+      0,
+      parseInt(process.env.TAG_REFRESH_PERIODIC_RECYCLE_EVERY || "0", 10) || 0,
+    ),
+    switchPortOnRecycle:
+      String(process.env.TAG_REFRESH_SWITCH_PORT_ON_RECYCLE || "1") !== "0",
+  };
+  let lastRecycleAt = 0;
+
+  // ── 轻量回收 ──
+  async function recyclePage() {
+    if (!page || page.isClosed()) {
+      page = await getOrCreatePage(browser);
+      await setupPageRequestBlocking(page);
+      return;
+    }
+    try {
+      await page.goto("about:blank", {
+        waitUntil: "domcontentloaded",
+        timeout: 5000,
+      });
+    } catch {
+      await page.close().catch(() => {});
+      page = await getOrCreatePage(browser);
+      await setupPageRequestBlocking(page);
+    }
+  }
+
+  // ── 深度回收 ──
+  async function recycleCdpSession(reason, { switchPort = true } = {}) {
+    const oldPort = cdpPort;
+    const shouldSwitch = switchPort && RECYCLE_CONFIG.switchPortOnRecycle;
+    if (shouldSwitch) {
+      cdpPort = pickNextPort(cdpPort);
+      cdpOpts.port = cdpPort;
+      clientMeta.port = cdpPort;
+    }
+    const portHint =
+      oldPort === cdpPort ? `port=${cdpPort}` : `port ${oldPort}→${cdpPort}`;
+    log(`  ♻️ 重建 CDP 会话 (${reason}; ${portHint})...`);
+    if (page) {
+      await page.close().catch(() => {});
+      page = null;
+    }
+    await browser.close().catch(() => {});
+    if (oldPort !== cdpPort) {
+      await killEdgeProcesses(null, oldPort).catch(() => {});
+    }
+    browser = await ensureBrowserReady(cdpOpts);
+    page = await getOrCreatePage(browser);
+    await setupPageRequestBlocking(page);
+    lastRecycleAt = Date.now();
+  }
+
+  async function maybeRecycleForMemory() {
+    const mem = process.memoryUsage();
+    const rssMB = mem.rss / 1024 / 1024;
+    const heapMB = mem.heapUsed / 1024 / 1024;
+    const edgeMB = getBrowserMemory(cdpPort);
+
+    const nodeOver =
+      rssMB >= RECYCLE_CONFIG.nodeRssMb || heapMB >= RECYCLE_CONFIG.nodeHeapMb;
+    const edgeOver = edgeMB !== null && edgeMB >= RECYCLE_CONFIG.edgeMb;
+
+    if (nodeOver || edgeOver) {
+      if (
+        RECYCLE_CONFIG.cooldownMs > 0 &&
+        Date.now() - lastRecycleAt < RECYCLE_CONFIG.cooldownMs
+      )
+        return;
+
+      const parts = [];
+      if (rssMB >= RECYCLE_CONFIG.nodeRssMb)
+        parts.push(`rss=${rssMB.toFixed(0)}≥${RECYCLE_CONFIG.nodeRssMb}`);
+      if (heapMB >= RECYCLE_CONFIG.nodeHeapMb)
+        parts.push(`heap=${heapMB.toFixed(0)}≥${RECYCLE_CONFIG.nodeHeapMb}`);
+      if (edgeOver)
+        parts.push(`edge:${cdpPort}=${edgeMB}≥${RECYCLE_CONFIG.edgeMb}`);
+
+      await recycleCdpSession(`mem ${parts.join("+")}`, {
+        switchPort: edgeOver,
+      });
+      return;
+    }
+
+    if (
+      RECYCLE_CONFIG.periodicEvery > 0 &&
+      totalRefreshed > 0 &&
+      totalRefreshed % RECYCLE_CONFIG.periodicEvery === 0
+    ) {
+      await recycleCdpSession(`periodic #${totalRefreshed}`, {
+        switchPort: false,
+      });
+    }
+  }
+
+  let totalRefreshed = 0;
+  let emptyRounds = 0;
+  let consecutiveCaptcha = 0;
+  const MAX_CONSECUTIVE_CAPTCHA = 3;
+
+  const clientId = randomUUID();
+  const clientMeta = { type: "tag-refresh", port: cdpPort };
+
+  // 复用 TikTokScraper
+  const enrichScraper = new TikTokScraper({
+    poolSize: 3,
+    proxyServer: effectiveProxy || undefined,
+  });
+  await enrichScraper.init();
+  log("✅ TikTokScraper 已就绪 (enrich 复用)");
+  log(`  客户端 ID: ${clientId.substring(0, 8)}...`);
+  log("");
+
+  const cleanup = () => {
+    log("\n正在清理资源...");
+    enrichScraper.close().catch(() => {});
+    killEdgeProcesses(null, cdpPort);
+    process.exit(0);
+  };
+  process.on("SIGINT", cleanup);
+
+  try {
+    while (true) {
+      try {
+        // 从服务端获取下一个 productive 标签
+        const taskRes = await fetch(`${baseUrl}/api/tags/refresh-task`, {
+          headers: buildClientHeaders(clientId, clientMeta),
+        });
+        const taskData = await taskRes.json();
+
+        if (!taskData.tag) {
+          emptyRounds++;
+
+          if (emptyRounds >= 5) {
+            log(
+              `⏳ 连续 ${emptyRounds} 轮无 productive 标签可刷新（30 秒后重试）...`,
+            );
+            await new Promise((r) => setTimeout(r, 30000));
+            emptyRounds = 0;
+            continue;
+          }
+          log(
+            `⏳ 暂无 productive 标签可刷新（连续 ${emptyRounds} 轮），10 秒后重试...`,
+          );
+          await new Promise((r) => setTimeout(r, 10000));
+          continue;
+        }
+
+        emptyRounds = 0;
+
+        const tag = taskData.tag.replace(/^#+/, "").trim().toLowerCase();
+        const startTime = Date.now();
+
+        log(
+          `[${totalRefreshed + 1}] 正在刷新 #${tag} (score: ${taskData.score})...`,
+        );
+
+        const result = {
+          tag,
+          pushedUsers: 0,
+          error: null,
+        };
+
+        // 锁定标签
+        const claimRes = await fetch(`${baseUrl}/api/tags/refresh-claim`, {
+          method: "POST",
+          headers: buildClientHeaders(clientId, clientMeta, {
+            "Content-Type": "application/json",
+          }),
+          body: JSON.stringify({ tag }),
+        });
+        const claimData = await claimRes.json();
+        if (!claimData.ok) {
+          if (
+            claimData.error &&
+            claimData.error.includes("already being refreshed")
+          ) {
+            log(`  ⏭️ 已被其他客户端锁定，跳过`);
+            await recyclePage();
+            continue;
+          }
+          log(`  ⚠️ 无法锁定 (${claimData.error})，重试下一个`);
+          await recyclePage();
+          continue;
+        }
+
+        // 抓取视频
+        const fetchStart = Date.now();
+        log(`  抓取 TikTok 标签页...`);
+        const tagResult = await fetchTagData(tag, {
+          page,
+          onProgress: ({ videos, authors }) => {
+            process.stderr.write(
+              `\r  抓取中: ${videos} 视频, ${authors} 作者\x1b[K`,
+            );
+          },
+        });
+        const fetchSec = ((Date.now() - fetchStart) / 1000).toFixed(1);
+        log(
+          `\r  完成: ${tagResult.videoCount} 视频, ${tagResult.uniqueAuthorCount} 作者 (${fetchSec}s)\x1b[K`,
+        );
+
+        let videos = tagResult.videos;
+
+        if (!videos || videos.length === 0) {
+          const deadSec = ((Date.now() - fetchStart) / 1000).toFixed(1);
+          log(`  ⚠️ 无视频 (${deadSec}s)，保留 productive 状态，等待下次刷新`);
+          result.error = "no videos found";
+          await fetch(`${baseUrl}/api/tags/refresh-result`, {
+            method: "POST",
+            headers: buildClientHeaders(clientId, clientMeta, {
+              "Content-Type": "application/json",
+            }),
+            body: JSON.stringify({ tag, pushedUsers: 0, error: result.error }),
+          }).catch(() => {});
+          totalRefreshed++;
+          await randomDelay(0, 5000);
+          await recyclePage();
+          await maybeRecycleForMemory();
+          continue;
+        }
+
+        // enrich: 先查服务端缓存，只对未知视频发 HTTP 请求
+        const enriched = await enrichWithServerCache(
+          videos,
+          baseUrl,
+          enrichScraper,
+          {
+            clientId,
+            clientMeta,
+            effectiveProxy,
+            log,
+          },
+        );
+        videos = enriched.videos;
+
+        // CDN 限流检测
+        const cdnBlocked = enriched.cdnBlockedCount || 0;
+        if (cdnBlocked > 0) {
+          const cdnRatio = cdnBlocked / (videos.length || 1);
+          const coolSec = cdnRatio > 0.3 ? 120 : 60;
+          log(
+            `  ⚠️ CDN 限流: ${cdnBlocked}/${videos.length} (${(cdnRatio * 100).toFixed(0)}%)，冷却 ${coolSec} 秒后重启 scraper`,
+          );
+          await new Promise((r) => setTimeout(r, coolSec * 1000));
+          log(`  正在重启 TikTokScraper...`);
+          await enrichScraper.restart();
+          log(`  ✅ TikTokScraper 已重启`);
+        }
+
+        // 过滤目标国家的视频和作者
+        const targetLocations = DEFAULT_TARGET_LOCATIONS;
+        const filteredVideos = videos.filter((v) =>
+          isLocationInList(v.locationCreated, targetLocations),
+        );
+        const filteredAuthors = [
+          ...new Set(
+            filteredVideos.map((v) => v.authorUniqueId).filter(Boolean),
+          ),
+        ];
+        const filteredCount = videos.length - filteredVideos.length;
+        if (filteredCount > 0) {
+          log(`  过滤非目标国家: ${filteredCount}/${videos.length} 视频被排除`);
+        }
+
+        // 推送过滤后的作者到服务端
+        if (filteredAuthors.length > 0) {
+          const pushResult = await pushToServer(
+            baseUrl,
+            filteredAuthors,
+            filteredVideos,
+            clientId,
+            clientMeta,
+          );
+          result.pushedUsers = pushResult.added || 0;
+        }
+
+        // 上报刷新结果（只更新 pushed_users，不改变 score/status）
+        await fetch(`${baseUrl}/api/tags/refresh-result`, {
+          method: "POST",
+          headers: buildClientHeaders(clientId, clientMeta, {
+            "Content-Type": "application/json",
+          }),
+          body: JSON.stringify({
+            tag,
+            pushedUsers: result.pushedUsers,
+            error: result.error,
+          }),
+        }).catch(() => {});
+
+        totalRefreshed++;
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+        const memStr = ` mem=${formatMemoryWithBrowser(cdpPort)}`;
+        log(
+          `  🔄 #${tag} 完成 (${elapsed}s) — ${videos.length} 视频(${filteredVideos.length} 匹配), ${filteredAuthors.length} 作者, 推送 ${result.pushedUsers} 用户${memStr}`,
+        );
+        log("");
+
+        if (totalRefreshed % 10 === 0) {
+          log(
+            `📊 [${totalRefreshed}] 内存汇总: ${formatMemoryWithBrowser(cdpPort)}`,
+          );
+        }
+        await recyclePage();
+        await maybeRecycleForMemory();
+        await randomDelay(3000, 7000);
+      } catch (e) {
+        const isNetworkError =
+          e.code === "ECONNREFUSED" ||
+          e.code === "ENOTFOUND" ||
+          e.code === "ECONNRESET" ||
+          (e.message &&
+            (e.message.includes("ECONNREFUSED") ||
+              e.message.includes("fetch failed") ||
+              e.message.includes("network")));
+        if (isNetworkError) {
+          log(`  ⚠️ 服务端连接失败 (${e.message})，15 秒后重试...`);
+          await new Promise((r) => setTimeout(r, 15000));
+          continue;
+        }
+        log(`  ⚠️ 处理出错 (${e.message})，10 秒后重试...`);
+        await new Promise((r) => setTimeout(r, 10000));
+        await recyclePage().catch(() => {});
+      }
+    }
+  } finally {
+    cleanup();
+  }
+}

package/src/lib/api-interceptor.js

@@ -24,6 +24,7 @@ async function processAPIResponse(
       createTime: item.createTime || null,
       playCount: item.stats?.playCount || 0,
       isECVideo: item.isECVideo ? 1 : 0,
+      isAd: item.isAd ? 1 : 0,
     });
   }
 
@@ -74,6 +75,7 @@ async function processAPIResponse(
             createTime: item.createTime || null,
             playCount: item.stats?.playCount || 0,
             isECVideo: item.isECVideo ? 1 : 0,
+            isAd: item.isAd ? 1 : 0,
           });
         }
       }

package/src/lib/args.js

@@ -670,6 +670,7 @@ function parseCommentsArgs(args) {
   let commentsServer = defaultServer;
   let commentsBasePort = 6222;
   let commentsProxy = null;
+  let commentsLocations = null;
 
   const positional = [];
 
@@ -689,6 +690,12 @@ function parseCommentsArgs(args) {
       commentsBasePort = parseInt(args[++i]) || 6222;
     } else if (arg === "--proxy") {
       commentsProxy = args[++i];
+    } else if (
+      arg === "-l" ||
+      arg === "--location" ||
+      arg === "--job-locations"
+    ) {
+      commentsLocations = args[++i];
     } else {
       positional.push(arg);
     }
@@ -709,6 +716,7 @@ function parseCommentsArgs(args) {
     commentsServer,
     commentsBasePort,
     commentsProxy,
+    commentsLocations,
     urls: [],
     outputFormat: "json",
     exploreCount: 0,
@@ -738,7 +746,9 @@ function parseTagArgs(args) {
   let isDiscover = false;
   let isScore = false;
   let isScoreAll = false;
+  let isRefresh = false;
   let scoreAllPort = 7222;
+  let refreshPort = 8222;
   let scoreProxy = null;
   let scoreTag = null;
   let scoreCountries = null;
@@ -786,6 +796,8 @@ function parseTagArgs(args) {
     } else if (arg === "--port") {
       if (isScoreAll) {
         scoreAllPort = parseInt(args[++i]) || 7222;
+      } else if (isRefresh) {
+        refreshPort = parseInt(args[++i]) || 8222;
       } else {
         scorePort = parseInt(args[++i]) || 9222;
       }
@@ -818,6 +830,8 @@ function parseTagArgs(args) {
         if (scoreCountries) i += scoreCountries.length;
       } else if (cleaned.toLowerCase() === "score-all") {
         isScoreAll = true;
+      } else if (cleaned.toLowerCase() === "refresh") {
+        isRefresh = true;
       } else {
         tags.push(cleaned.toLowerCase());
       }
@@ -891,6 +905,27 @@ function parseTagArgs(args) {
     };
   }
 
+  if (isRefresh) {
+    return {
+      subcommand: "tag-refresh",
+      tagRefresh: {
+        serverUrl,
+        port: refreshPort,
+        proxy: scoreProxy,
+      },
+      urls: [],
+      outputFormat: "json",
+      exploreCount: 0,
+      showConfig: false,
+      showHelp: false,
+      customProxy: null,
+      configAction: null,
+      configValue: null,
+      pipeMode: false,
+      filterStr: null,
+    };
+  }
+
   return {
     subcommand: "tag",
     tagTags: {