tt-help-cli-ycl 1.4.112 → 1.4.114

package/src/cli/refresh.js

@@ -71,7 +71,12 @@ export async function handleRefresh(options) {
     exploreProxy,
     exploreWebserver,
     exploreNoProduct,
+    exploreMini,
   } = options;
+  // --mini 模式：只采集视频列表及由视频推导的信息（EC视频、最新发布时间），
+  // 跳过用户信息、国家采样、关注/粉丝提取（最大耗时项）和商品详情抓取（由独立商品程序异步补抓），大幅提速。
+  const followEnabled = !exploreMini && exploreEnableFollow !== false;
+  const skipProduct = exploreMini || !!exploreNoProduct;
   const effectiveProxy = exploreProxy || configuredProxy;
   let resolvedProxy = effectiveProxy;
   if (
@@ -122,8 +127,11 @@ export async function handleRefresh(options) {
     console.error(`\n=== Refresh 模式（基于 explore） ===`);
     console.error(`服务器: ${serverUrl}`);
     console.error(`视频采集: ${exploreMaxVideos || 16}`);
+    if (exploreMini) {
+      console.error(`采集范围: mini（仅视频及视频相关信息）`);
+    }
     console.error(
-      `关注/粉丝: ${exploreEnableFollow ? "启用" : "禁用"} (${exploreMaxFollowing}/${exploreMaxFollowers})`,
+      `关注/粉丝: ${followEnabled ? "启用" : "禁用"} (${exploreMaxFollowing}/${exploreMaxFollowers})`,
     );
     console.error(`国家筛选: ${exploreLocation}`);
     if (exploreJobLocations) console.error(`任务国家: ${exploreJobLocations}`);
@@ -368,11 +376,11 @@ export async function handleRefresh(options) {
         await handleAccountSwitch(checkResult.reason);
       } else if (checkResult.info && processedCount % 10 === 0) {
         const followElapsed =
-          loggedIn && exploreEnableFollow
+          loggedIn && followEnabled
             ? Math.round((Date.now() - lastFollowSuccessTime) / 60000)
             : 0;
         const followStatus =
-          loggedIn && exploreEnableFollow
+          loggedIn && followEnabled
             ? ` | 关注/粉丝上次成功 ${followElapsed} 分钟前`
             : "";
         console.error(`\n[健康检查] ${checkResult.info}${followStatus}`);
@@ -446,8 +454,8 @@ export async function handleRefresh(options) {
         }
       }
 
-      // 关注/粉丝封禁检测
-      if (loggedIn && exploreEnableFollow) {
+      // 关注/粉丝封禁检测（mini 模式下不采集关注/粉丝，无需检测）
+      if (loggedIn && followEnabled) {
         const followElapsed = Date.now() - lastFollowSuccessTime;
         if (followElapsed > FOLLOW_BLOCK_THRESHOLD) {
           const minutes = Math.round(followElapsed / 60000);
@@ -481,7 +489,7 @@ export async function handleRefresh(options) {
         username,
         {
           maxVideos: exploreMaxVideos || 16,
-          enableFollow: exploreEnableFollow !== false,
+          enableFollow: followEnabled,
           loggedIn,
           maxFollowing: exploreMaxFollowing || 100,
           maxFollowers: exploreMaxFollowers || 100,
@@ -490,7 +498,8 @@ export async function handleRefresh(options) {
           browser,
           proxyServer: cdpOptions.proxyServer || null,
           webserverUrl: exploreWebserver || null,
-          noProduct: !!exploreNoProduct,
+          noProduct: skipProduct,
+          mini: !!exploreMini,
         },
         console.error,
       );
@@ -509,7 +518,7 @@ export async function handleRefresh(options) {
           username,
           {
             maxVideos: exploreMaxVideos || 16,
-            enableFollow: exploreEnableFollow !== false,
+            enableFollow: followEnabled,
             loggedIn,
             maxFollowing: exploreMaxFollowing || 100,
             maxFollowers: exploreMaxFollowers || 100,
@@ -518,7 +527,8 @@ export async function handleRefresh(options) {
             browser,
             proxyServer: cdpOptions.proxyServer || null,
             webserverUrl: exploreWebserver || null,
-            noProduct: !!exploreNoProduct,
+            noProduct: skipProduct,
+            mini: !!exploreMini,
           },
           console.error,
         );
@@ -559,7 +569,7 @@ export async function handleRefresh(options) {
             username,
             {
               maxVideos: exploreMaxVideos || 16,
-              enableFollow: exploreEnableFollow !== false,
+              enableFollow: followEnabled,
               loggedIn,
               maxFollowing: exploreMaxFollowing || 100,
               maxFollowers: exploreMaxFollowers || 100,
@@ -568,7 +578,8 @@ export async function handleRefresh(options) {
               browser,
               proxyServer: cdpOptions.proxyServer || null,
               webserverUrl: exploreWebserver || null,
-              noProduct: !!exploreNoProduct,
+              noProduct: skipProduct,
+              mini: !!exploreMini,
             },
             console.error,
           );
@@ -656,11 +667,16 @@ export async function handleRefresh(options) {
         result.confirmedLocation || result.locationCreated;
       const guessedLocation = refreshLocation || null;
 
-      // 把 confirmedLocation 合并到 userInfo 中（通过 commitRedoJob 写入 DB）
+      // 把 confirmedLocation / latestVideoTime 合并到 userInfo 中（通过 commitRedoJob 写入 DB）
+      // latestVideoTime 单独合并：mini 模式下 userInfo 为 null，但 latestVideoTime
+      // 是视频推导的零成本信息，仍需更新服务端 latest_video_time（影响任务排序与前端显示）
       const refreshUserInfo = { ...(result.userInfo || {}) };
       if (result.confirmedLocation) {
         refreshUserInfo.confirmedLocation = result.confirmedLocation;
       }
+      if (result.latestVideoTime) {
+        refreshUserInfo.latestVideoTime = result.latestVideoTime;
+      }
 
       const payload = {
         userInfo: refreshUserInfo,

package/src/cli/watchdog.js

@@ -22,10 +22,13 @@ export async function handleWatchdog(options) {
     watchdogNoDaemon,
   } = options;
 
-  // 服务端地址：--server 参数 > ~/.tt-help.json server > 默认值
+  // 服务端地址：--server 参数 > ~/.tt-help.json watchdogServer > server > 默认值
   const clientConfig = getClientConfig();
   const serverUrl =
-    watchdogServer || clientConfig.server || "http://127.0.0.1:3001";
+    watchdogServer ||
+    clientConfig.watchdogServer ||
+    clientConfig.server ||
+    "http://127.0.0.1:3001";
 
   // 客户端 ID：优先 --client-id，其次 userId@hostname，最后 hostname+pid
   const userId = clientConfig.userId || "";

package/src/lib/api-client.js

@@ -47,54 +47,69 @@ export function createApiClient(opts = {}) {
   const retryOpts = { maxRetries, backoff, log };
 
   async function apiGet(url) {
-    return withRetry(`GET ${url}`, async () => {
-      const res = await fetch(url, {
-        headers: buildHeaders({}, clientId, meta),
-      });
-      if (checkStatus && !res.ok) {
-        const errText = await res.text();
-        throw new Error(`HTTP ${res.status}: ${errText.substring(0, 200)}`);
-      }
-      return res.json();
-    }, retryOpts);
+    return withRetry(
+      `GET ${url}`,
+      async () => {
+        const res = await fetch(url, {
+          headers: buildHeaders({}, clientId, meta),
+          signal: AbortSignal.timeout(30000),
+        });
+        if (checkStatus && !res.ok) {
+          const errText = await res.text();
+          throw new Error(`HTTP ${res.status}: ${errText.substring(0, 200)}`);
+        }
+        return res.json();
+      },
+      retryOpts,
+    );
   }
 
   async function apiPost(url, body) {
-    return withRetry(`POST ${url}`, async () => {
-      const res = await fetch(url, {
-        method: "POST",
-        headers: buildHeaders(
-          { "Content-Type": "application/json" },
-          clientId,
-          meta,
-        ),
-        body: JSON.stringify(body),
-      });
-      if (checkStatus && !res.ok) {
-        const errText = await res.text();
-        throw new Error(`HTTP ${res.status}: ${errText.substring(0, 200)}`);
-      }
-      return res.json();
-    }, retryOpts);
+    return withRetry(
+      `POST ${url}`,
+      async () => {
+        const res = await fetch(url, {
+          method: "POST",
+          headers: buildHeaders(
+            { "Content-Type": "application/json" },
+            clientId,
+            meta,
+          ),
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(30000),
+        });
+        if (checkStatus && !res.ok) {
+          const errText = await res.text();
+          throw new Error(`HTTP ${res.status}: ${errText.substring(0, 200)}`);
+        }
+        return res.json();
+      },
+      retryOpts,
+    );
   }
 
   async function apiPut(url, body) {
-    return withRetry(`PUT ${url}`, async () => {
-      const res = await fetch(url, {
-        method: "PUT",
-        headers: buildHeaders(
-          { "Content-Type": "application/json" },
-          clientId,
-          meta,
-        ),
-        body: body ? JSON.stringify(body) : undefined,
-      });
-      if (checkStatus && !res.ok) {
-        const errText = await res.text();
-        throw new Error(`HTTP ${res.status}: ${errText.substring(0, 200)}`);
-      }
-      return res.json();
-    }, retryOpts);
+    return withRetry(
+      `PUT ${url}`,
+      async () => {
+        const res = await fetch(url, {
+          method: "PUT",
+          headers: buildHeaders(
+            { "Content-Type": "application/json" },
+            clientId,
+            meta,
+          ),
+          body: body ? JSON.stringify(body) : undefined,
+          signal: AbortSignal.timeout(30000),
+        });
+        if (checkStatus && !res.ok) {
+          const errText = await res.text();
+          throw new Error(`HTTP ${res.status}: ${errText.substring(0, 200)}`);
+        }
+        return res.json();
+      },
+      retryOpts,
+    );
   }
 
   return { apiGet, apiPost, apiPut };

package/src/lib/api-interceptor.js

@@ -142,24 +142,25 @@ async function processAPIResponse(
   return videoMap;
 }
 
-async function fetchUserVideosAPI(page, username, maxVideos, log) {
-  log(`  [API拦截] 获取 @${username} 视频 ...`);
+// 默认被封重试间隔：30/40/50 秒共 3 次，仍封才抛"被封"交给上层。
+// RM_BLOCKED_WAIT_MS 仅用于测试缩短所有等待
+const _rmBlockedWait = Number(process.env.RM_BLOCKED_WAIT_MS);
+const DEFAULT_BLOCKED_RETRY_WAITS =
+  _rmBlockedWait > 0
+    ? [_rmBlockedWait, _rmBlockedWait, _rmBlockedWait]
+    : [30_000, 40_000, 50_000];
 
-  // CDP 健康检查：确保 page 可用
-  try {
-    await page.evaluate(() => 1);
-  } catch (e) {
-    log(`  [API拦截] CDP 连接异常: ${e.message}`);
-    throw new Error(`CDP 连接异常: ${e.message}`);
-  }
-
-  let apiRequestUrl = null;
+/**
+ * 单次尝试：注册拦截 → goto 用户主页 → 等 item_list 响应 → 解析 JSON。
+ * apiRequestUrlRef 跨次复用（URL 相同，保留第一次捕获的即可）
+ */
+async function attemptItemListFetch(page, username, log, apiRequestUrlRef) {
   let sawApiRequest = false;
 
   const requestHandler = (request) => {
     if (request.url().includes("/api/post/item_list/")) {
       sawApiRequest = true;
-      if (!apiRequestUrl) apiRequestUrl = request.url();
+      if (!apiRequestUrlRef.value) apiRequestUrlRef.value = request.url();
     }
   };
 
@@ -168,18 +169,28 @@ async function fetchUserVideosAPI(page, username, maxVideos, log) {
   const t0 = Date.now();
   let data = null;
   let interceptionError = null;
+  let responsePromise = null;
+  let response = null;
+  let rawBodyBytes = -1; // -1 未知（未读取到 body）；0 = 服务端空响应（封禁判定依据）
 
   try {
+    // 响应监听必须在 goto 之前注册：domcontentloaded 返回时首个 item_list
+    // 响应可能已经到达，晚注册会错过它、被迫等下一个请求或超时
+    responsePromise = page.waitForResponse(
+      (res) => res.url().includes("/api/post/item_list/"),
+      { timeout: 30000 },
+    );
+    // 防 unhandledRejection：goto 卡住期间该 promise 可能先超时 reject，
+    // 未被 await 的 rejection 在 Node 默认配置下会直接崩进程
+    responsePromise.catch(() => {});
+
     await page.goto(`https://www.tiktok.com/@${username}`, {
       waitUntil: "domcontentloaded",
       timeout: 30000,
     });
     await assertPageUrl(page, `@${username}`);
 
-    const response = await page.waitForResponse(
-      (res) => res.url().includes("/api/post/item_list/"),
-      { timeout: 30000 },
-    );
+    response = await responsePromise;
 
     // 超时保护：response.json() 内部调用 CDP Network.getResponseBody，
     // 当页面刷新/验证码导致响应资源丢失时会挂起，需独立超时控制
@@ -194,50 +205,155 @@ async function fetchUserVideosAPI(page, username, maxVideos, log) {
     ]);
   } catch (e) {
     interceptionError = e.message;
+    // JSON 解析失败（如 "Unexpected end of JSON input"）时打印原始响应，
+    // 便于诊断空响应/截断响应/非 JSON 响应等异常形态
+    if (response) {
+      try {
+        // body 读取同样可能因页面异常而挂起，加独立超时保护
+        const raw = await Promise.race([
+          response.body(),
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error("body 读取超时（15s）")), 15000),
+          ),
+        ]);
+        const text = raw.toString("utf-8");
+        rawBodyBytes = raw.length;
+        // content-length 用于区分两种 0 字节形态：
+        // 声明长度 > 实际字节 = 传输被截断；声明缺失/为 0 = 服务端主动空响应
+        const declared = parseInt(
+          response.headers()["content-length"] || "0",
+          10,
+        );
+        const clNote =
+          raw.length === 0
+            ? declared > 0
+              ? `content-length 声明 ${declared}（传输截断）`
+              : "content-length 缺失/为 0（服务端主动空响应）"
+            : `content-length ${declared || "无"}`;
+        log(
+          `  [API拦截] item_list 响应异常: HTTP ${response.status()}, ${raw.length} 字节, ${clNote}, 内容: ${text.slice(0, 200).replace(/\s+/g, " ")}`,
+        );
+      } catch (e2) {
+        log(`  [API拦截] item_list 响应体读取失败: ${e2.message}`);
+      }
+    }
   } finally {
+    // goto 提前失败时丢弃未等待的响应 promise，避免 unhandledRejection
+    responsePromise?.catch(() => {});
     page.off("request", requestHandler);
   }
 
-  const elapsed = Date.now() - t0;
-
-  if (data && Array.isArray(data.itemList) && data.itemList.length > 0) {
-    log(`  [API拦截] 成功，耗时 ${elapsed}ms`);
-    return await processAPIResponse(
-      data,
-      username,
-      maxVideos,
-      [],
-      page,
-      apiRequestUrl,
-      log,
-    );
-  }
+  return {
+    data,
+    interceptionError,
+    rawBodyBytes,
+    elapsed: Date.now() - t0,
+  };
+}
 
-  let pageError = await detectPageError(page);
-  if (!pageError) {
-    pageError = await detectPageErrorWithWait(page, 5000);
-  }
+async function fetchUserVideosAPI(
+  page,
+  username,
+  maxVideos,
+  log,
+  options = {},
+) {
+  log(`  [API拦截] 获取 @${username} 视频 ...`);
 
-  if (pageError === "service_error") {
-    throw new Error(`被封: ${username}`);
-  }
+  // CDP 健康检查：带超时保护。页面主线程死锁时 evaluate 可能长时间无响应，
+  // 超时后自动刷新页面恢复（实测刷新页面即可解除死锁）
+  const evalWithTimeout = (label, ms) =>
+    Promise.race([
+      page.evaluate(() => 1),
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`${label} 超时（${ms / 1000}s）`)),
+          ms,
+        ),
+      ),
+    ]);
 
-  if (pageError === "cdn_blocked") {
-    throw new Error(`CDN限流: ${username}`);
+  try {
+    await evalWithTimeout("CDP 健康检查", 10000);
+  } catch (e) {
+    log(`  [API拦截] CDP 连接异常: ${e.message}，刷新页面恢复...`);
+    await page
+      .reload({ waitUntil: "domcontentloaded", timeout: 30000 })
+      .catch(() => {});
+    try {
+      await evalWithTimeout("刷新后重检", 10000);
+      log(`  [API拦截] 页面已恢复`);
+    } catch (e2) {
+      throw new Error(`CDP 连接异常（刷新后仍失败）: ${e2.message}`);
+    }
   }
 
-  if (pageError) {
-    log(`  [API拦截] 数据为空，识别到页面错误: ${pageError}`);
-    return new Map();
-  }
+  let apiRequestUrlRef = { value: null };
+  const { blockedRetryWaitsMs = DEFAULT_BLOCKED_RETRY_WAITS } = options;
+  const retryWaits = Array.isArray(blockedRetryWaitsMs)
+    ? blockedRetryWaitsMs
+    : DEFAULT_BLOCKED_RETRY_WAITS;
+  let attempt = 0;
+
+  while (true) {
+    attempt++;
+    const { data, interceptionError, rawBodyBytes, elapsed } =
+      await attemptItemListFetch(page, username, log, apiRequestUrlRef);
+
+    if (data && Array.isArray(data.itemList) && data.itemList.length > 0) {
+      log(`  [API拦截] 成功，耗时 ${elapsed}ms`);
+      return await processAPIResponse(
+        data,
+        username,
+        maxVideos,
+        [],
+        page,
+        apiRequestUrlRef.value,
+        log,
+      );
+    }
 
-  if (interceptionError) {
-    log(`  [API拦截] 超时/拦截失败: ${interceptionError}，耗时 ${elapsed}ms`);
-    throw new Error(`@${username} 页面异常（API拦截超时，未识别到错误类型）`);
-  }
+    // 0 字节空响应 = 被封（content-length 缺失/为 0 或截断，统一按封禁处理）。
+    // 不再依赖页面"出错了/很抱歉"文案判定，静默型封禁（页面正常渲染但 API 空响应）也能识别。
+    // 默认 30/40/50 秒等待重试 3 次，仍封才抛错交给上层（explore/refresh/refresh-mini 均受益）
+    if (rawBodyBytes === 0) {
+      const retryIndex = attempt - 1;
+      if (retryIndex < retryWaits.length) {
+        const waitMs = retryWaits[retryIndex];
+        log(
+          `  [API拦截] item_list 空响应（0 字节），判定为被封，${waitMs / 1000}s 后第 ${attempt}/${retryWaits.length} 次重试...`,
+        );
+        await new Promise((r) => setTimeout(r, waitMs));
+        continue;
+      }
+      log(
+        `  [API拦截] item_list 空响应（0 字节），重试 ${retryWaits.length} 次仍被封`,
+      );
+      throw new Error(`被封: ${username}`);
+    }
+
+    let pageError = await detectPageError(page);
+    if (!pageError) {
+      pageError = await detectPageErrorWithWait(page, 5000);
+    }
+
+    if (pageError === "cdn_blocked") {
+      throw new Error(`CDN限流: ${username}`);
+    }
 
-  log(`  [API拦截] 数据为空，未识别到错误类型，当作无视频处理`);
-  return new Map();
+    if (pageError) {
+      log(`  [API拦截] 数据为空，识别到页面错误: ${pageError}`);
+      return new Map();
+    }
+
+    if (interceptionError) {
+      log(`  [API拦截] 超时/拦截失败: ${interceptionError}，耗时 ${elapsed}ms`);
+      throw new Error(`@${username} 页面异常（API拦截超时，未识别到错误类型）`);
+    }
+
+    log(`  [API拦截] 数据为空，未识别到错误类型，当作无视频处理`);
+    return new Map();
+  }
 }
 
 export { fetchUserVideosAPI };

package/src/lib/args.js

@@ -515,11 +515,14 @@ function parseRefreshArgs(args) {
   let exploreJobLocations = null;
   let exploreWebserver = null;
   let exploreNoProduct = false;
+  let exploreMini = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--server") {
       serverUrl = args[++i];
+    } else if (arg === "--mini") {
+      exploreMini = true;
     } else if (arg === "--preset") {
       explorePreset = args[++i];
     } else if (arg === "-i" || arg === "--interval") {
@@ -581,6 +584,85 @@ function parseRefreshArgs(args) {
     exploreProxy,
     exploreWebserver,
     exploreNoProduct,
+    exploreMini,
+    serverUrl,
+    urls: [],
+    outputFormat: "json",
+    exploreCount: 0,
+    showConfig: false,
+    showHelp: false,
+    customProxy: null,
+    configAction: null,
+    configValue: null,
+    pipeMode: false,
+    filterStr: null,
+  };
+}
+
+function parseRefreshMiniArgs(args) {
+  let serverUrl = defaultServer;
+  let explorePreset = "normal";
+  let exploreInterval = 30;
+  let exploreLocation = DEFAULT_TARGET_LOCATIONS_CSV;
+  let exploreMaxUsers = 0;
+  let explorePort = 4222;
+  let exploreUserId = null;
+  let exploreMaxVideos = 16;
+  let exploreRedoMaxAge = 0;
+  let exploreProxy = null;
+  let exploreJobLocations = null;
+  let rotateMin = 10;
+  let captchaWaitMin = 10;
+  let ensureDaemon = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--server") {
+      serverUrl = args[++i];
+    } else if (arg === "--preset") {
+      explorePreset = args[++i];
+    } else if (arg === "-i" || arg === "--interval") {
+      exploreInterval = parseInt(args[++i], 10) || 30;
+    } else if (arg === "--port") {
+      explorePort = parseInt(args[++i]) || 4222;
+    } else if (arg === "--user-id") {
+      exploreUserId = args[++i];
+    } else if (arg === "--max-videos") {
+      exploreMaxVideos = parseInt(args[++i]) || 16;
+    } else if (arg === "--max-age") {
+      exploreRedoMaxAge = parseInt(args[++i]) || 0;
+    } else if (arg === "--proxy") {
+      exploreProxy = args[++i];
+    } else if (arg === "--location") {
+      exploreLocation = args[++i];
+    } else if (arg === "--job-locations") {
+      exploreJobLocations = args[++i];
+    } else if (arg === "--max-users") {
+      exploreMaxUsers = parseInt(args[++i]) || 0;
+    } else if (arg === "--rotate-min") {
+      rotateMin = parseInt(args[++i], 10) || 0;
+    } else if (arg === "--captcha-wait-min") {
+      captchaWaitMin = parseInt(args[++i], 10) || 10;
+    } else if (arg === "--ensure-daemon") {
+      ensureDaemon = true;
+    }
+  }
+
+  return {
+    subcommand: "refresh-mini",
+    explorePreset,
+    exploreInterval,
+    exploreLocation,
+    exploreJobLocations,
+    exploreMaxUsers,
+    explorePort,
+    exploreUserId,
+    exploreMaxVideos,
+    exploreRedoMaxAge,
+    exploreProxy,
+    rotateMin,
+    captchaWaitMin,
+    ensureDaemon,
     serverUrl,
     urls: [],
     outputFormat: "json",
@@ -766,6 +848,7 @@ function parseProductFillArgs(args) {
   let interval = 10;
   let serverUrl = defaultServer;
   let webserverUrl = null;
+  let proxyUrl = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -773,6 +856,8 @@ function parseProductFillArgs(args) {
       serverUrl = args[++i];
     } else if (arg === "-w" || arg === "--webserver") {
       webserverUrl = args[++i];
+    } else if (arg === "--proxy") {
+      proxyUrl = args[++i] || null;
     } else if (arg === "-i" || arg === "--interval") {
       interval = parseInt(args[++i], 10) || 10;
     } else if (arg === "-l" || arg === "--limit") {
@@ -786,6 +871,7 @@ function parseProductFillArgs(args) {
     productFillInterval: interval,
     serverUrl,
     productFillWebserver: webserverUrl,
+    productFillProxy: proxyUrl,
     urls: [],
     outputFormat: "json",
     exploreCount: 0,
@@ -1368,6 +1454,28 @@ export function parseArgs() {
   const args = process.argv.slice(2);
 
   if (args.includes("-h") || args.includes("--help")) {
+    // 子命令级帮助：product-fill -h 显示专属帮助，而非全局 HELP_TEXT
+    if (args[0] === "product-fill") {
+      return {
+        subcommand: "product-fill",
+        productFillLimit: 5,
+        productFillInterval: 10,
+        serverUrl: defaultServer,
+        productFillWebserver: null,
+        showHelp: true,
+        showVersion: false,
+        urls: [],
+        outputFile: null,
+        outputFormat: "json",
+        exploreCount: 0,
+        showConfig: false,
+        customProxy: null,
+        configAction: null,
+        configValue: null,
+        pipeMode: false,
+        filterStr: null,
+      };
+    }
     return {
       showHelp: true,
       showVersion: false,
@@ -1446,6 +1554,10 @@ export function parseArgs() {
     return parseRefreshArgs(args.slice(1));
   }
 
+  if (args.length > 0 && args[0] === "refresh-mini") {
+    return parseRefreshMiniArgs(args.slice(1));
+  }
+
   if (args.length > 0 && args[0] === "search") {
     return parseSearchArgs(args.slice(1));
   }