tt-help-cli-ycl 1.3.43 → 1.3.45

package/package.json

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

package/src/cli/attach.js

@@ -76,12 +76,12 @@ async function recycleScraper(scraper, reason) {
 }
 
 export async function handleAttach(options) {
-  const { attachParallel, attachInterval, serverUrl, showHelp } = options;
+  const { attachParallel, attachInterval, serverUrl, attachCountries, showHelp } = options;
   let shuttingDown = false;
   let forceExitTimer = null;
 
   if (showHelp) {
-    attachLog("用法: tt-help attach [-p 并行数] [-i 间隔秒数] [-s 服务端地址]");
+    attachLog("用法: tt-help attach [-p 并行数] [-i 间隔秒数] [-s 服务端地址] [-c 国家列表]");
     attachLog("");
     attachLog("参数:");
     attachLog("  -p, --parallel <N>     并行抓取数（默认: 1）");
@@ -89,6 +89,9 @@ export async function handleAttach(options) {
     attachLog(
       "  -s, --server <URL>     服务端地址（默认: http://127.0.0.1:3001）",
     );
+    attachLog(
+      "  -c, --countries <A,B,C>  猜测国家列表（逗号分隔，如 PL,DE,FR），服务端优先返回这些国家的任务",
+    );
     attachLog("");
     attachLog("说明:");
     attachLog(
@@ -101,11 +104,16 @@ export async function handleAttach(options) {
     attachLog("  tt-help attach");
     attachLog("  tt-help attach -p 5 -i 10");
     attachLog("  tt-help attach -p 3 -i 5 -s http://127.0.0.1:3001");
+    attachLog("  tt-help attach -c PL,DE,FR -p 5");
     return;
   }
 
+  const countryStr =
+    attachCountries && attachCountries.length > 0
+      ? `, 猜测国家: ${attachCountries.join(", ")}`
+      : "";
   attachLog(
-    `[Attach] 并行数: ${attachParallel}, 空闲间隔: ${attachInterval}秒, 服务端: ${serverUrl}`,
+    `[Attach] 并行数: ${attachParallel}, 空闲间隔: ${attachInterval}秒, 服务端: ${serverUrl}${countryStr}`,
   );
 
   const scraper = new TikTokScraper();
@@ -162,8 +170,12 @@ export async function handleAttach(options) {
         process.exit(0);
       }
 
+      const countryParam =
+        attachCountries && attachCountries.length > 0
+          ? `&countries=${encodeURIComponent(attachCountries.join(","))}`
+          : "";
       const { total, tasks } = await apiGet(
-        `${serverUrl}/api/user-update-tasks?limit=${attachParallel}`,
+        `${serverUrl}/api/user-update-tasks?limit=${attachParallel}${countryParam}`,
       );
 
       if (!tasks || tasks.length === 0) {

package/src/cli/comments.js

@@ -2,22 +2,11 @@ import { chromium } from "playwright";
 import { fetchUserCommentsAPI } from "../lib/api-interceptor-comment.js";
 import { closeCommentPanel } from "../lib/browser/page.js";
 import { server as defaultServer } from "../lib/constants.js";
-
-const TARGET_LOCATIONS = [
-  "CZ",
-  "GR",
-  "HU",
-  "PT",
-  "ES",
-  "PL",
-  "NL",
-  "BE",
-  "DE",
-  "FR",
-  "IT",
-  "IE",
-  "AT",
-];
+import {
+  DEFAULT_TARGET_LOCATIONS,
+  isLocationInList,
+  normalizeLocation,
+} from "../lib/target-locations.js";
 
 async function waitForPageReady(page, timeout = 30000) {
   const startTime = Date.now();
@@ -130,7 +119,7 @@ async function runAutoMode(options) {
     `\n[Comments Auto] 并行: ${actualParallel}, 间隔: ${actualInterval}s, 评论数: ${actualMaxComments}`,
   );
   console.error(`服务器: ${serverUrl}`);
-  console.error(`目标国家: ${TARGET_LOCATIONS.join(", ")}`);
+  console.error(`目标国家: ${DEFAULT_TARGET_LOCATIONS.join(", ")}`);
   console.error(`开始循环接收任务...\n`);
 
   let browser;
@@ -228,10 +217,10 @@ async function runAutoMode(options) {
         for (const task of tasks) {
           try {
             const { id, href, locationCreated, ttSeller } = task;
-            const loc = (locationCreated || "").toUpperCase();
+            const loc = normalizeLocation(locationCreated);
 
             // 检查目标国家
-            if (loc && !TARGET_LOCATIONS.includes(loc)) {
+            if (loc && !isLocationInList(loc, DEFAULT_TARGET_LOCATIONS)) {
               // 非目标国家，直接 commit 跳过
               await apiPut(`${serverUrl}/api/comment-task/${id}`);
               skippedCount++;
@@ -487,12 +476,15 @@ export async function handleComments(options) {
         ),
       ];
 
-      const guessedLocation = (videoInfo?.locationCreated || "").toUpperCase();
+      const guessedLocation = normalizeLocation(videoInfo?.locationCreated);
       const serverUrl = commentsServer || defaultServer;
 
-      if (guessedLocation && !TARGET_LOCATIONS.includes(guessedLocation)) {
+      if (
+        guessedLocation &&
+        !isLocationInList(guessedLocation, DEFAULT_TARGET_LOCATIONS)
+      ) {
         console.error(`\n猜测国家: ${guessedLocation}，非目标国家，跳过保存`);
-        console.error(`目标国家: ${TARGET_LOCATIONS.join(", ")}`);
+        console.error(`目标国家: ${DEFAULT_TARGET_LOCATIONS.join(", ")}`);
       } else {
         console.error(`\n正在提交 ${authors.length} 个评论作者到服务端...`);
         console.error(`服务端: ${serverUrl}`);

package/src/lib/args.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "fs";
 import { server as defaultServer } from "./constants.js";
+import { DEFAULT_TARGET_LOCATIONS_CSV } from "./target-locations.js";
 
 const PRESETS = ["fast", "normal", "slow", "stealth"];
 
@@ -171,7 +172,7 @@ function parseExploreArgs(args) {
   let exploreEnableFollow = true;
   let exploreMaxFollowing = 50;
   let exploreMaxFollowers = 50;
-  let exploreLocation = "CZ,GR,HU,PT,PL,NL,BE,DE,FR,IT,ES,IE,AT";
+  let exploreLocation = DEFAULT_TARGET_LOCATIONS_CSV;
   let exploreJobLocations = null;
   let exploreMaxUsers = 0;
   let explorePort = null;
@@ -462,6 +463,7 @@ function parseAttachArgs(args) {
   let parallel = 1;
   let interval = 10;
   let serverUrl = defaultServer;
+  let countries = [];
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -471,6 +473,11 @@ function parseAttachArgs(args) {
       interval = parseInt(args[++i], 10) || 10;
     } else if (arg === "-s" || arg === "--server") {
       serverUrl = args[++i];
+    } else if (arg === "-c" || arg === "--countries") {
+      countries = args[++i]
+        .split(",")
+        .map((c) => c.trim().toUpperCase())
+        .filter(Boolean);
     }
   }
 
@@ -479,6 +486,7 @@ function parseAttachArgs(args) {
     attachParallel: parallel,
     attachInterval: interval,
     serverUrl,
+    attachCountries: countries,
     urls: [],
     outputFormat: "json",
     exploreCount: 0,

package/src/lib/browser/page.js

@@ -67,19 +67,20 @@ export async function withBrowserRecovery(fn, browser, page, cdpOptions, port) {
 }
 
 /**
- * 通过 Cookie 判断登录状态（推荐，最可靠）
- * 已登录：存在 sessionid Cookie
- * 未登录：不存在 sessionid Cookie
+ * 稳定判断登录状态：先检查 sessionid Cookie，再用页面 DOM 做验真。
+ * 仅有 sessionid 不足以说明会话仍然有效，因此需要二次确认。
  */
 export async function isLoggedIn(page) {
   const cookies = await page.context().cookies("https://www.tiktok.com");
-  return cookies.some((c) => c.name === "sessionid");
+  const hasSessionId = cookies.some((c) => c.name === "sessionid");
+  if (!hasSessionId) return false;
+
+  return await isLoggedInByDom(page);
 }
 
 /**
- * 通过 DOM 元素判断登录状态（备用方案）
- * 依赖页面渲染完成，可能存在误判
- * @deprecated 推荐使用 isLoggedIn（基于 Cookie）
+ * 通过 DOM 元素判断登录状态（验真方案）
+ * 依赖页面渲染完成，因此不单独作为主判断，而是和 Cookie 组合使用。
  */
 export async function isLoggedInByDom(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 { DEFAULT_TARGET_LOCATIONS_CSV } from "./target-locations.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -121,7 +122,7 @@ const HELP_TEXT = [
   "    预设: fast, normal（默认）, slow, stealth",
   "    选项:",
   "      --server <URL>            服务端地址，默认 http://127.0.0.1:3001",
-  "      --location <国家代码>     国家筛选，逗号分隔，默认 CZ,GR,HU,PT,PL,NL,BE,DE,FR,IT,ES,IE,AT",
+  `      --location <国家代码>     国家筛选，逗号分隔，默认 ${DEFAULT_TARGET_LOCATIONS_CSV}`,
   "      --job-locations <国家>    任务国家筛选，逗号分隔（仅筛选服务端任务）",
   "      --max-comments <数量>     每视频最大评论数，默认 10",
   "      --max-guess <数量>        每视频最大猜你喜欢数，默认 0",
@@ -145,12 +146,14 @@ const HELP_TEXT = [
   "    示例: tt-help info https://www.tiktok.com/@nike",
   "          tt-help info https://www.tiktok.com/@nike/video/7234567890 --onlyvideo",
   "",
-  "  tt-help attach [-p 并行数] [-i 间隔秒数] [-s 服务端地址]",
+  "  tt-help attach [-p 并行数] [-i 间隔秒数] [-s 服务端地址] [-c 国家列表]",
   "    后台轮询服务端任务接口，自动抓取 TikTok 用户信息",
   "    -p, --parallel <N>     并行抓取数（默认: 1）",
   "    -i, --interval <N>     无任务时轮询间隔，单位秒（默认: 10）",
   "    -s, --server <URL>     服务端地址（默认: http://127.0.0.1:3001）",
+  "    -c, --countries <A,B>  猜测国家列表（逗号分隔，如 PL,DE,FR）",
   "    示例: tt-help attach -p 5 -i 10",
+  "          tt-help attach -c PL,DE,FR -p 5",
   "",
   "  tt-help watch -o <db路径> [-p 端口]",
   "    启动监控服务；运行期主数据仅来自 SQLite",

package/src/lib/target-locations.js

@@ -0,0 +1,61 @@
+const DEFAULT_TARGET_LOCATIONS = [
+  "CZ",
+  "GR",
+  "HU",
+  "PT",
+  "ES",
+  "PL",
+  "NL",
+  "BE",
+  "DE",
+  "FR",
+  "IT",
+  "IE",
+  "AT",
+];
+
+const DEFAULT_TARGET_LOCATIONS_CSV = DEFAULT_TARGET_LOCATIONS.join(",");
+
+function normalizeLocation(location) {
+  if (location == null) return null;
+  const normalized = String(location).trim().toUpperCase();
+  return normalized || null;
+}
+
+function normalizeLocationList(locations, fallback = DEFAULT_TARGET_LOCATIONS) {
+  const source = Array.isArray(locations)
+    ? locations
+    : String(locations == null ? "" : locations).split(",");
+  const normalized = source
+    .map((location) => normalizeLocation(location))
+    .filter(Boolean);
+  return normalized.length > 0 ? [...new Set(normalized)] : [...fallback];
+}
+
+function isLocationInList(location, locations) {
+  const normalizedLocation = normalizeLocation(location);
+  if (!normalizedLocation) return false;
+  return normalizeLocationList(locations).includes(normalizedLocation);
+}
+
+function findFirstMatchingLocation(
+  locations,
+  targetLocations = DEFAULT_TARGET_LOCATIONS,
+) {
+  const normalizedTargetLocations = normalizeLocationList(targetLocations);
+  const normalizedLocations = normalizeLocationList(locations, []);
+  return (
+    normalizedLocations.find((location) =>
+      normalizedTargetLocations.includes(location),
+    ) || null
+  );
+}
+
+export {
+  DEFAULT_TARGET_LOCATIONS,
+  DEFAULT_TARGET_LOCATIONS_CSV,
+  findFirstMatchingLocation,
+  isLocationInList,
+  normalizeLocation,
+  normalizeLocationList,
+};

package/src/scraper/core.js

@@ -10,13 +10,18 @@ import {
 } from "./modules/page-helpers.js";
 import { extractCommentAuthors } from "./modules/comment-extractor.js";
 import { extractGuessVideos } from "./modules/guess-extractor.js";
+import {
+  DEFAULT_TARGET_LOCATIONS_CSV,
+  isLocationInList,
+  normalizeLocationList,
+} from "../lib/target-locations.js";
 
 async function scrapeSingleVideo(
   page,
   maxComments,
   maxGuess,
   log,
-  location = "CZ,GR,HU,PT,PL,NL,BE,DE,FR,IT,ES,IE",
+  location = DEFAULT_TARGET_LOCATIONS_CSV,
 ) {
   const config = getDelayConfig();
 
@@ -52,14 +57,8 @@ async function scrapeSingleVideo(
   let captchaStage = "";
   let captchaMessage = "";
 
-  const locationList = (location || "ES")
-    .split(",")
-    .map((s) => s.trim().toUpperCase());
-  if (
-    locationList.includes(
-      userData.locationCreated?.toUpperCase?.() || userData.locationCreated,
-    )
-  ) {
+  const locationList = normalizeLocationList(location);
+  if (isLocationInList(userData.locationCreated, locationList)) {
     if (maxGuess > 0) {
       guessVideos = await extractGuessVideos(page, maxGuess);
     }

package/src/scraper/explore-core.js

@@ -4,6 +4,12 @@ export { ensureBrowserReady };
 import { getUserInfo, collectVideos } from "../videos/core.js";
 import { extractFollowAndFollowers } from "./modules/follow-extractor.js";
 import { extractVideoLocation } from "../lib/scrape.js";
+import {
+  DEFAULT_TARGET_LOCATIONS_CSV,
+  findFirstMatchingLocation,
+  isLocationInList,
+  normalizeLocationList,
+} from "../lib/target-locations.js";
 import {
   maxFollowing as globalMaxFollowing,
   maxFollowers as globalMaxFollowers,
@@ -16,7 +22,7 @@ async function processExplore(page, username, options, log) {
     loggedIn = false, // 由外部传入登录状态，避免每次调用 isLoggedIn(page)
     maxFollowing = 50,
     maxFollowers = 50,
-    location = "CZ,GR,HU,PT,PL,NL,BE,DE,FR,IT,ES,IE",
+    location = DEFAULT_TARGET_LOCATIONS_CSV,
   } = options;
 
   const result = {
@@ -35,6 +41,8 @@ async function processExplore(page, username, options, log) {
     error: null,
   };
 
+  const locationList = normalizeLocationList(location);
+
   try {
     log(`  访问 @${username} 主页...`);
     const videoList = await collectVideos(page, username, maxVideos, log);
@@ -66,9 +74,11 @@ async function processExplore(page, username, options, log) {
       return result;
     }
 
-    // 从最多 5 个视频并发获取 locationCreated，取众数
+    // 从最多 5 个视频并发获取 locationCreated。
+    // 新规则：采样列表里只要有任一国家命中目标列表，就直接采用该国家；否则回退到众数。
     const SAMPLE_SIZE = 5;
     let locationCreated = null;
+    let locationDecision = null;
     const sampleVideos = videoArray.slice(0, SAMPLE_SIZE);
     if (sampleVideos.length > 0) {
       const sampleUrls = sampleVideos.map((v) =>
@@ -80,26 +90,34 @@ async function processExplore(page, username, options, log) {
       log(
         `  国家采样(${locations.length}个): [${locations.filter(Boolean).join(", ") || "无数据"}]`,
       );
+      const normalizedLocations = normalizeLocationList(locations, []);
+      const matchedTargetLocation = findFirstMatchingLocation(
+        normalizedLocations,
+        locationList,
+      );
       const freq = {};
-      for (const loc of locations) {
-        if (loc) {
-          const key = loc.toUpperCase();
-          freq[key] = (freq[key] || 0) + 1;
-        }
+      for (const key of normalizedLocations) {
+        freq[key] = (freq[key] || 0) + 1;
       }
       const entries = Object.entries(freq).sort((a, b) => b[1] - a[1]);
-      locationCreated = entries.length > 0 ? entries[0][0] : null;
+      if (matchedTargetLocation) {
+        locationCreated = matchedTargetLocation;
+        locationDecision = "命中目标国家";
+      } else if (entries.length > 0) {
+        locationCreated = entries[0][0];
+        locationDecision = "回退众数";
+      }
     }
 
     result.locationCreated = locationCreated || null;
-    log(`  国家: ${result.locationCreated || "未知"} (众数)`);
+    log(
+      `  国家: ${result.locationCreated || "未知"}${locationDecision ? ` (${locationDecision})` : ""}`,
+    );
 
     // 国家筛选
-    const locationList = (location || "ES")
-      .split(",")
-      .map((s) => s.trim().toUpperCase());
-    const isTargetLocation = locationList.includes(
-      result.locationCreated?.toUpperCase?.() || result.locationCreated,
+    const isTargetLocation = isLocationInList(
+      result.locationCreated,
+      locationList,
     );
 
     if (isTargetLocation) {

package/src/scraper/modules/follow-extractor.js

@@ -1,5 +1,6 @@
 import { delay, getDelayConfig } from "./page-helpers.js";
 import { scrollAndCollect } from "./scroll-collector.js";
+import { extractUniqueId, toProfileUrl } from "../../lib/url.js";
 
 const FILTER_WORDS = ["主页", "已关注", "粉丝", "推荐"];
 
@@ -48,7 +49,14 @@ async function waitForListContent(page, minChildren = 1, timeout = 15000) {
     .catch(() => {});
 }
 
-async function openFollowModal(page) {
+function getProfileUrlForRetry(page) {
+  const currentUrl = page.url();
+  const uniqueId = extractUniqueId(currentUrl);
+  if (uniqueId) return toProfileUrl(uniqueId);
+  return currentUrl;
+}
+
+async function openFollowModal(page, log = () => {}) {
   const tryOpen = async () =>
     page.evaluate((selectors) => {
       const clickTarget = (node) => {
@@ -83,7 +91,16 @@ async function openFollowModal(page) {
   for (let attempt = 1; attempt <= 3; attempt++) {
     await waitForFollowTrigger(page, attempt === 1 ? 15000 : 8000);
     opened = await tryOpen();
-    if (opened) break;
+    if (opened) {
+      if (attempt >= 2) {
+        log(`  [关注弹窗] 第 ${attempt} 次已点击关注入口: ${opened}`);
+      }
+      break;
+    }
+
+    if (attempt >= 2) {
+      log(`  [关注弹窗] 第 ${attempt} 次仍未找到可点击的关注入口`);
+    }
 
     await page
       .evaluate(() => {
@@ -94,6 +111,7 @@ async function openFollowModal(page) {
   }
 
   if (!opened) {
+    log("  [关注弹窗] 重试后仍未找到关注入口");
     throw new Error(
       "未找到关注入口元素，请确认当前页面为用户主页或页面结构已变化",
     );
@@ -107,20 +125,31 @@ async function openFollowModal(page) {
         timeout: 30000,
       });
       containerReady = true;
+      if (attempt >= 2) {
+        log(`  [关注弹窗] 第 ${attempt} 次等待后，关注列表容器已出现`);
+      }
       break;
     } catch (e) {
       if (attempt === 1) {
-        // 第一次超时，刷新页面重试
-        await page.reload({ waitUntil: "domcontentloaded" });
+        // 第一次超时，重新 goto 用户主页后重试
+        const retryUrl = getProfileUrlForRetry(page);
+        log(
+          `  [关注弹窗] 第 1 次等待列表超时，准备 goto 主页重试: ${retryUrl} | ${e.message}`,
+        );
+        await page.goto(retryUrl, { waitUntil: "domcontentloaded" });
         await delay(2000, 3000);
+        log("  [关注弹窗] 主页跳转完成，重新点击关注入口");
         // 重新点击 follow 入口
         opened = await tryOpen();
         if (!opened) {
+          log("  [关注弹窗] goto 主页后仍未找到关注入口");
           throw new Error(
-            "刷新后仍未找到关注入口元素，请确认当前页面为用户主页",
+            "goto 主页后仍未找到关注入口元素，请确认当前页面为用户主页",
           );
         }
+        log(`  [关注弹窗] goto 主页后已重新点击关注入口: ${opened}`);
       } else {
+        log(`  [关注弹窗] 第 2 次等待列表仍超时，结束本次提取: ${e.message}`);
         throw e;
       }
     }
@@ -200,7 +229,7 @@ async function extractUsersFromModal(page, maxUsers) {
 async function extractFollowAndFollowers(page, options = {}) {
   const { maxFollowing = 999, maxFollowers = 999, log = () => {} } = options;
 
-  await openFollowModal(page);
+  await openFollowModal(page, log);
 
   const following = await extractUsersFromModal(page, maxFollowing);
   log(`  已关注: ${following.length}`);

package/src/scraper/refresh-core.js

@@ -8,6 +8,7 @@ import { detectCaptcha } from "./modules/captcha-handler.js";
 import { getUserInfo, collectVideos } from "../videos/core.js";
 import { extractFollowAndFollowers } from "./modules/follow-extractor.js";
 import { processExplore } from "./explore-core.js";
+import { DEFAULT_TARGET_LOCATIONS_CSV } from "../lib/target-locations.js";
 
 export async function processRefresh(page, username, serverUrl, options, log) {
   const { maxFollowing = 100, maxFollowers = 100, maxVideos = 100 } = options;
@@ -131,7 +132,7 @@ export async function processRefresh(page, username, serverUrl, options, log) {
           enableFollow: true,
           maxFollowing: 5,
           maxFollowers: 5,
-          location: "CZ,GR,HU,PT,PL,NL,BE,DE,FR,IT,ES,IE",
+          location: DEFAULT_TARGET_LOCATIONS_CSV,
         },
         log,
       );

package/src/watch/data-store.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import Database from "better-sqlite3";
+import { isLocationInList } from "../lib/target-locations.js";
 
 // SQLite 用户表（用于判重）
 let db = null;
@@ -989,6 +990,117 @@ function restoreRawJobsByCountry(country) {
   return { restored: count, country: normalizedCountry };
 }
 
+function restoreRawJobById(uniqueId) {
+  if (!db) {
+    return { restored: 0, uniqueId, error: "db not ready" };
+  }
+
+  const safeId = String(uniqueId).trim();
+  if (!safeId) {
+    return { restored: 0, uniqueId: safeId, error: "uniqueId is required" };
+  }
+
+  const exists =
+    db
+      .prepare("SELECT COUNT(*) as c FROM raw_jobs WHERE unique_id = ?")
+      .get(safeId)?.c || 0;
+
+  if (!exists) {
+    return { restored: 0, uniqueId: safeId };
+  }
+
+  const restoreTxn = db.transaction(() => {
+    db.prepare(
+      `
+      INSERT OR REPLACE INTO jobs (
+        unique_id, nickname, status, sources, claimed_by, claimed_at, error,
+        pinned, no_video, restricted, user_update_count, tt_seller, verified,
+        video_count, comment_count, guessed_location, location_created,
+        follower_count, following_count, heart_count, refresh_time,
+        processed, processed_at, created_at, updated_at, region, signature, sec_uid
+      )
+      SELECT
+        unique_id, nickname, status, sources, claimed_by, claimed_at, error,
+        pinned, no_video, restricted, user_update_count, tt_seller, verified,
+        video_count, comment_count, guessed_location, location_created,
+        follower_count, following_count, heart_count, refresh_time,
+        processed, processed_at, created_at, updated_at, region, signature, sec_uid
+      FROM raw_jobs WHERE unique_id = ?
+    `,
+    ).run(safeId);
+
+    db.prepare("DELETE FROM raw_jobs WHERE unique_id = ?").run(safeId);
+  });
+
+  restoreTxn();
+  return { restored: 1, uniqueId: safeId };
+}
+
+function restoreRawJobsByFilter({ search, location }) {
+  if (!db) {
+    return { restored: 0, error: "db not ready" };
+  }
+
+  const where = [];
+  const args = [];
+
+  if (search) {
+    where.push(
+      "(LOWER(unique_id) LIKE ? OR LOWER(COALESCE(nickname, '')) LIKE ?)",
+    );
+    const likeVal = `%${search.toLowerCase()}%`;
+    args.push(likeVal, likeVal);
+  }
+
+  if (location) {
+    where.push("COALESCE(guessed_location, '未知') = ?");
+    args.push(location);
+  }
+
+  if (where.length === 0) {
+    return { restored: 0, error: "at least one filter is required" };
+  }
+
+  const whereSql = where.join(" AND ");
+
+  const count =
+    db
+      .prepare(
+        `SELECT COUNT(*) as c FROM raw_jobs WHERE ${whereSql}`,
+      )
+      .get(...args)?.c || 0;
+
+  if (!count) {
+    return { restored: 0 };
+  }
+
+  const restoreTxn = db.transaction(() => {
+    db.prepare(
+      `
+      INSERT OR REPLACE INTO jobs (
+        unique_id, nickname, status, sources, claimed_by, claimed_at, error,
+        pinned, no_video, restricted, user_update_count, tt_seller, verified,
+        video_count, comment_count, guessed_location, location_created,
+        follower_count, following_count, heart_count, refresh_time,
+        processed, processed_at, created_at, updated_at, region, signature, sec_uid
+      )
+      SELECT
+        unique_id, nickname, status, sources, claimed_by, claimed_at, error,
+        pinned, no_video, restricted, user_update_count, tt_seller, verified,
+        video_count, comment_count, guessed_location, location_created,
+        follower_count, following_count, heart_count, refresh_time,
+        processed, processed_at, created_at, updated_at, region, signature, sec_uid
+      FROM raw_jobs WHERE ${whereSql}
+    `,
+    ).run(...args);
+
+    db.prepare(`DELETE FROM raw_jobs WHERE ${whereSql}`).run(...args);
+  });
+
+  restoreTxn();
+  return { restored: count };
+}
+
 function getRawJobsPageFromDb({ search, location, limit, offset }) {
   if (!db) return null;
 
@@ -1911,8 +2023,7 @@ export function createStore(filePath) {
     // 国家过滤：如果指定了 locations，只保留 guessedLocation 在列表中的用户
     function locationFilter(u) {
       if (!locations || locations.length === 0) return true;
-      const loc = (u.guessedLocation || "").toUpperCase();
-      return locations.includes(loc);
+      return isLocationInList(u.guessedLocation, locations);
     }
 
     // 从候选列表中按优先级取第一个：pinned > 超时回收 > seed > ttSeller(仅登录) > follow > other
@@ -2474,21 +2585,33 @@ export function createStore(filePath) {
     return Array.from(clientErrors.values());
   }
 
-  function getPendingUserUpdateTasks(limit) {
+  function getPendingUserUpdateTasks(limit, countries) {
+    const targetCountries = countries
+      ? countries.map((c) => String(c).trim().toUpperCase())
+      : [];
+    const hasCountryFilter = targetCountries.length > 0;
+
     if (db) {
       const l = Math.max(1, parseInt(limit) || 5);
-      const rows = db
-        .prepare(
-          `
-          SELECT *
-          FROM jobs
-          WHERE COALESCE(tt_seller, '') = ''
-            AND COALESCE(user_update_count, 0) <= 0
-          ORDER BY created_at ASC, unique_id ASC
-          LIMIT ?
-        `,
-        )
-        .all(l);
+
+      let sql = `
+        SELECT *
+        FROM jobs
+        WHERE COALESCE(tt_seller, '') = ''
+          AND COALESCE(user_update_count, 0) <= 0
+      `;
+      const sqlParams = [];
+
+      if (hasCountryFilter) {
+        const placeholders = targetCountries.map(() => "?").join(", ");
+        sql += ` AND UPPER(COALESCE(guessed_location, '')) IN (${placeholders})`;
+        sqlParams.push(...targetCountries);
+      }
+
+      sql += ` ORDER BY created_at ASC, unique_id ASC LIMIT ?`;
+      sqlParams.push(l);
+
+      const rows = db.prepare(sql).all(...sqlParams);
       if (rows.length === 0) return [];
       const now = Date.now();
       const bumpStmt = db.prepare(
@@ -2520,9 +2643,16 @@ export function createStore(filePath) {
         const ttSellerEmpty =
           u.ttSeller === null || u.ttSeller === undefined || u.ttSeller === "";
         if (!ttSellerEmpty) return false;
-        return (
+        if (
           updateCount === null || updateCount === undefined || updateCount <= 0
-        );
+        ) {
+          if (hasCountryFilter) {
+            const loc = (u.guessedLocation || "").toUpperCase();
+            return targetCountries.includes(loc);
+          }
+          return true;
+        }
+        return false;
       })
       .slice(0, l);
     // 接受任务时 userUpdateCount + 1
@@ -2814,6 +2944,8 @@ export function createStore(filePath) {
     moveJobsToRawByCountry,
     restoreAttachStuckByCountry,
     restoreRawJobsByCountry,
+    restoreRawJobById,
+    restoreRawJobsByFilter,
     getUsersPage: getUsersPageFromDb,
     getRawJobsPage: getRawJobsPageFromDb,
     getTargetUsers: getTargetUsersFromDb,

package/src/watch/public/index.html

@@ -1265,6 +1265,7 @@
             <option value="">全部国家</option>
           </select>
           <button onclick="clearRawFilters()">清空筛选</button>
+          <button onclick="restoreFilteredRawJobs()" style="background:#22c55e;color:#fff;border:none;padding:6px 12px;border-radius:6px;cursor:pointer;font-size:12px;">恢复当前筛选到 jobs</button>
         </div>
         <div class="table-scroll">
           <table>
@@ -1279,6 +1280,7 @@
                 <th>来源</th>
                 <th>状态</th>
                 <th>创建时间</th>
+                <th>操作</th>
               </tr>
             </thead>
             <tbody id="rawTable"></tbody>
@@ -2181,7 +2183,7 @@
     function renderRawJobsTable(users) {
       const el = document.getElementById('rawTable');
       if (!users.length) {
-        el.innerHTML = '<tr><td colspan="9" style="color:#666;text-align:center;padding:24px">暂无毛料库任务</td></tr>';
+        el.innerHTML = '<tr><td colspan="10" style="color:#666;text-align:center;padding:24px">暂无毛料库任务</td></tr>';
         return;
       }
       el.innerHTML = users.map(u => {
@@ -2203,6 +2205,7 @@
           <td data-label="来源">${sources || '-'}</td>
           <td data-label="状态">${statusTag}</td>
           <td data-label="创建时间" style="font-size:11px;color:#888">${created}</td>
+          <td data-label="操作" style="text-align:center"><button onclick="restoreRawJob('${u.uniqueId}')" style="background:#22c55e;color:#fff;border:none;padding:4px 10px;border-radius:4px;cursor:pointer;font-size:11px;">恢复</button></td>
         </tr>`;
       }).join('');
     }
@@ -2237,6 +2240,63 @@
       fetchRawJobs();
     }
 
+    async function restoreRawJob(uniqueId) {
+      if (!window.confirm(`确认将 @${uniqueId} 从毛料库恢复到 jobs 队列吗？`)) {
+        return;
+      }
+      try {
+        const res = await fetch('/api/raw-jobs/restore', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ uniqueId })
+        });
+        const data = await res.json();
+        if (!res.ok || data.error) {
+          showToast(data.error || '恢复失败', true);
+          return;
+        }
+        showToast(`@${uniqueId} 已恢复到队列`);
+        await fetchStats();
+        await fetchRawByCountry();
+        await fetchRawJobs();
+      } catch (e) {
+        showToast('恢复失败: ' + e.message, true);
+      }
+    }
+
+    async function restoreFilteredRawJobs() {
+      const search = document.getElementById('rawSearchInput').value.trim();
+      const location = currentRawLocation;
+      let desc = '当前筛选条件';
+      if (search && location) desc = `搜索="${search}" + 国家=${location}`;
+      else if (search) desc = `搜索="${search}"`;
+      else if (location) desc = `国家=${location}`;
+      if (!window.confirm(`确认将毛料库中符合【${desc}】的任务恢复到 jobs 队列吗？`)) {
+        return;
+      }
+      try {
+        const body = {};
+        if (search) body.search = search;
+        if (location) body.location = location;
+        const res = await fetch('/api/raw-jobs/restore', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(body)
+        });
+        const data = await res.json();
+        if (!res.ok || data.error) {
+          showToast(data.error || '恢复失败', true);
+          return;
+        }
+        showToast(`已恢复 ${data.restored} 条任务到队列`);
+        await fetchStats();
+        await fetchRawByCountry();
+        await fetchRawJobs();
+      } catch (e) {
+        showToast('恢复失败: ' + e.message, true);
+      }
+    }
+
     async function restoreRawJobsByCountry(country, count) {
       const countText = count != null ? `将恢复 ${formatStatNum(count)} 条。` : '';
       if (!window.confirm(`确认将 ${country} 从毛料库恢复到 jobs 队列吗？${countText}`)) {

package/src/watch/server.js

@@ -6,22 +6,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { spawn } from "child_process";
 import { createStore } from "./data-store.js";
-
-const TARGET_LOCATIONS = [
-  "CZ",
-  "GR",
-  "HU",
-  "PT",
-  "ES",
-  "PL",
-  "NL",
-  "BE",
-  "DE",
-  "FR",
-  "IT",
-  "IE",
-  "AT",
-];
+import { DEFAULT_TARGET_LOCATIONS } from "../lib/target-locations.js";
 
 const __filename = fileURLToPath(import.meta.url);
 
@@ -40,7 +25,7 @@ const __dirname = dirname(__filename);
 const publicDir = join(__dirname, "public");
 
 function computeStatsIncremental(st) {
-  return st.getDashboardStats(TARGET_LOCATIONS);
+  return st.getDashboardStats(DEFAULT_TARGET_LOCATIONS);
 }
 
 function readBody(req) {
@@ -328,7 +313,7 @@ export function startWatchServer(dataAnchor, port = 3000, existingStore) {
 
       if (req.method === "GET" && routePath === "/api/stats") {
         const stats = computeStatsIncremental(store);
-        stats.targetLocations = TARGET_LOCATIONS;
+        stats.targetLocations = DEFAULT_TARGET_LOCATIONS;
         sendJSON(res, 200, stats);
         return;
       }
@@ -348,9 +333,12 @@ export function startWatchServer(dataAnchor, port = 3000, existingStore) {
 
       if (req.method === "GET" && routePath === "/api/user-update-tasks") {
         const limit = params.limit;
-        const tasks = store.getPendingUserUpdateTasks(limit);
+        const countries = params.countries
+          ? params.countries.split(",").map((c) => c.trim().toUpperCase()).filter(Boolean)
+          : [];
+        const tasks = store.getPendingUserUpdateTasks(limit, countries);
         const ts = new Date().toISOString().slice(11, 19);
-        console.error(`[JOB ${ts}] USER-UPDATE-TASKS: ${tasks.length} tasks`);
+        console.error(`[JOB ${ts}] USER-UPDATE-TASKS: ${tasks.length} tasks${countries.length ? ` (countries: ${countries.join(",")})` : ""}`);
         sendJSON(res, 200, { total: tasks.length, tasks });
         return;
       }
@@ -459,7 +447,7 @@ export function startWatchServer(dataAnchor, port = 3000, existingStore) {
       }
 
       if (req.method === "GET" && routePath === "/api/target-users") {
-        const targetResult = store.getTargetUsers(TARGET_LOCATIONS);
+        const targetResult = store.getTargetUsers(DEFAULT_TARGET_LOCATIONS);
         const targets = targetResult.users;
         if (req.headers["accept"]?.includes("text/csv")) {
           const columns = [
@@ -555,7 +543,20 @@ export function startWatchServer(dataAnchor, port = 3000, existingStore) {
       if (req.method === "POST" && routePath === "/api/raw-jobs/restore") {
         try {
           const body = await readBody(req);
-          const result = store.restoreRawJobsByCountry(body.country);
+          let result;
+          if (body.uniqueId) {
+            result = store.restoreRawJobById(body.uniqueId);
+          } else if (body.search || body.location) {
+            result = store.restoreRawJobsByFilter({
+              search: body.search || "",
+              location: body.location || "",
+            });
+          } else if (body.country) {
+            result = store.restoreRawJobsByCountry(body.country);
+          } else {
+            sendJSON(res, 400, { error: "missing filter: uniqueId, country, or search/location" });
+            return;
+          }
           if (result.error) {
             sendJSON(res, 400, result);
             return;
@@ -623,7 +624,7 @@ export function startWatchServer(dataAnchor, port = 3000, existingStore) {
           targetLocation: params.targetLocation,
           limit: params.limit,
           offset: params.offset,
-          targetLocations: TARGET_LOCATIONS,
+          targetLocations: DEFAULT_TARGET_LOCATIONS,
         });
 
         if (params.view === "light") {