tt-help-cli-ycl 1.4.142 → 1.4.144

package/package.json

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

package/scripts/sync-raw-jobs.mjs

@@ -15,13 +15,16 @@ import Database from "better-sqlite3";
 import { initDb, getDb } from "../src/watch/db-schema.js";
 import { loadLlmConfig, reloadLlmConfig } from "../src/watch/llm-config.js";
 import { scoreJobsBatch } from "../src/watch/llm-scoring.js";
-import { DEFAULT_TARGET_LOCATIONS } from "../src/lib/target-locations.js";
+import { getTargetLocations, reloadConfig } from "../src/lib/app-config.js";
 
 // ═══════════════════════════════════════════════════════════════════
 // 常量
 // ═══════════════════════════════════════════════════════════════════
 
-const LOCATIONS = DEFAULT_TARGET_LOCATIONS;
+// 目标国家：每轮 tick 前 reloadConfig() 重读配置文件，捕捉服务端(设置页)修改
+function currentLocations() {
+  return getTargetLocations();
+}
 
 const FILTER = "video_count>6 AND follower_count>0 AND following_count>0";
 
@@ -161,7 +164,7 @@ const vals = (row, cols) => cols.map((c) => row[c] ?? null);
 const ph = (n) => Array(n).fill("?").join(", ");
 
 /** 构建 WHERE 子句（含国家过滤）。strict=true 时仅匹配明确国家，不含 NULL/空 */
-function buildWhere(locations = LOCATIONS, strict = false) {
+function buildWhere(locations = currentLocations(), strict = false) {
   const locs = [
     ...new Set(
       locations.map((l) => String(l).trim().toUpperCase()).filter(Boolean),
@@ -268,14 +271,14 @@ function countPendingByCountry() {
   const map = {};
   for (const r of rows) map[r.loc] = r.c;
   // 确保所有目标国家都有值
-  for (const loc of LOCATIONS) {
+  for (const loc of currentLocations()) {
     if (!(loc in map)) map[loc] = 0;
   }
   return map;
 }
 
 function findNeedyCountries(byCountry, threshold) {
-  return LOCATIONS.filter((loc) => (byCountry[loc] || 0) < threshold);
+  return currentLocations().filter((loc) => (byCountry[loc] || 0) < threshold);
 }
 
 // ═══════════════════════════════════════════════════════════════════
@@ -335,7 +338,7 @@ async function refillLLM(archiveDb, needyLocations) {
 
     // 2. LLM 打分
     const ts = Date.now();
-    const scores = await scoreJobsBatch(samples, LOCATIONS);
+    const scores = await scoreJobsBatch(samples, currentLocations());
     log("  ", `${loc} 打分${scores.length}条 ${Date.now() - ts}ms`);
 
     if (
@@ -406,6 +409,7 @@ async function tick(archiveDb, opts) {
   const t0 = Date.now();
 
   archiveNewUsers(archiveDb);
+  reloadConfig(); // 每轮重读目标国家配置，支持服务端(设置页)修改
   if (opts.llm) reloadLlmConfig(); // 每轮重载，支持热切换模型
 
   const byCountry = countPendingByCountry();
@@ -414,7 +418,9 @@ async function tick(archiveDb, opts) {
   if (!needy.length) {
     log(
       "--",
-      `轮${tickN} 全部充足 | ${LOCATIONS.map((l) => `${l}:${byCountry[l]}`).join(" ")}`,
+      `轮${tickN} 全部充足 | ${currentLocations()
+        .map((l) => `${l}:${byCountry[l]}`)
+        .join(" ")}`,
     );
     return;
   }

package/scripts/test-api-interceptor-429.mjs

@@ -0,0 +1,122 @@
+// 临时验证：fetchUserVideosAPI 对 HTTP 429 / ratelimit triggered 判定为"被封"
+// 运行：RM_BLOCKED_WAIT_MS=1 node scripts/test-api-interceptor-429.mjs
+import { fetchUserVideosAPI } from "../src/lib/api-interceptor.js";
+
+// 构造一个可被 waitForResponse 返回的 429 响应
+function make429Response() {
+  return {
+    url: () => "https://www.tiktok.com/api/post/item_list/?...",
+    status: () => 429,
+    headers: () => ({ "content-length": "19" }),
+    json: async () => {
+      throw new Error("Unexpected token 'r'...");
+    },
+    body: async () => Buffer.from("ratelimit triggered"),
+  };
+}
+
+// 构造一个正常响应（itemList 非空）
+function make200Response(username) {
+  const itemList = [
+    { id: "111", stats: { playCount: 1 }, isECVideo: 0, isAd: 0 },
+  ];
+  return {
+    url: () => "https://www.tiktok.com/api/post/item_list/?...",
+    status: () => 200,
+    headers: () => ({}),
+    json: async () => ({ itemList, cursor: 0, hasMore: false }),
+    body: async () => Buffer.from(JSON.stringify({ itemList })),
+    username,
+  };
+}
+
+// 构造 mock page：封禁场景时 waitForResponse 返回 429 响应
+function makePage(username, respFactory) {
+  const page = {
+    _handlers: {},
+    on(event, fn) {
+      (page._handlers[event] ||= []).push(fn);
+      return page;
+    },
+    off(event) {
+      delete page._handlers[event];
+      return page;
+    },
+    url: () => `https://www.tiktok.com/@${username}`,
+    goto: async () => {},
+    // checkCdpHealth 用 () => document.readyState（fn.length===0）→ 返回 "complete"；
+    // detectPageError 用 (patterns)=>...（fn.length===1）→ 返回 null（页面无错误文案）
+    evaluate: async (fn) => (fn.length === 1 ? null : "complete"),
+    reload: async () => {},
+    waitForFunction: async () => null,
+    waitForResponse: async (pred, opts) => {
+      const resp = respFactory();
+      if (!pred(resp)) throw new Error("response 不匹配 item_list");
+      return resp;
+    },
+  };
+  return page;
+}
+
+let pass = 0;
+let fail = 0;
+
+async function expectReject(name, fn, expectedMsg) {
+  try {
+    await fn();
+    fail++;
+    console.error(`✗ ${name}: 未抛错（期望 "${expectedMsg}"）`);
+  } catch (e) {
+    if (e.message === expectedMsg || e.message.includes(expectedMsg)) {
+      pass++;
+      console.log(`✓ ${name}: 抛错 "${e.message}"`);
+    } else {
+      fail++;
+      console.error(
+        `✗ ${name}: 抛错 "${e.message}"（期望含 "${expectedMsg}"）`,
+      );
+    }
+  }
+}
+
+async function expectResolve(name, fn) {
+  try {
+    const r = await fn();
+    if (r instanceof Map && r.size === 1) {
+      pass++;
+      console.log(`✓ ${name}: 正常返回 ${r.size} 个视频`);
+    } else {
+      fail++;
+      console.error(`✗ ${name}: 返回异常 ${JSON.stringify(r)}`);
+    }
+  } catch (e) {
+    fail++;
+    console.error(`✗ ${name}: 抛错 ${e.message}`);
+  }
+}
+
+// 用例1：429 + ratelimit triggered → 判定为"被封"
+await expectReject(
+  "HTTP 429 ratelimit triggered 判为被封",
+  () =>
+    fetchUserVideosAPI(
+      makePage("fumolbbf08o", make429Response),
+      "fumolbbf08o",
+      5,
+      () => {},
+    ),
+  "被封: fumolbbf08o",
+);
+
+// 用例2：正常 200 itemList → 不误判，正常返回视频
+await expectResolve("HTTP 200 正常 itemList 不被误伤", () =>
+  fetchUserVideosAPI(
+    makePage("fumolbbf08o", make200Response),
+    "fumolbbf08o",
+    5,
+    () => {},
+  ),
+);
+
+console.log(`\n结果: ${pass} 通过, ${fail} 失败`);
+process.exit(fail > 0 ? 1 : 0);

package/src/cli/comments.js

@@ -23,10 +23,10 @@ import {
   saveUserId,
 } from "../lib/constants.js";
 import {
-  DEFAULT_TARGET_LOCATIONS,
   isLocationInList,
   normalizeLocation,
 } from "../lib/target-locations.js";
+import { getTargetLocations } from "../lib/app-config.js";
 import { createApiClient } from "../lib/api-client.js";
 import { ensureBrowserReady, killEdgeProcesses } from "../lib/browser/cdp.js";
 import { delay } from "../lib/delay.js";
@@ -562,7 +562,7 @@ async function runAutoMode(options) {
   console.error(`\n╔══════════════════════════════════════════╗`);
   console.error(`║     自动评论采集模式（CDP 连接已登录浏览器）`);
   console.error(
-    `║  目标国家: ${jobLocations || DEFAULT_TARGET_LOCATIONS.slice(0, 6).join(",") + "..."}`,
+    `║  目标国家: ${jobLocations || getTargetLocations().slice(0, 6).join(",") + "..."}`,
   );
   if (jobLocations) console.error(`║  任务过滤: ${jobLocations}`);
   console.error(`║  服务端:   ${serverUrl}`);
@@ -636,7 +636,7 @@ async function runAutoMode(options) {
             const taskNum = totalTasks() + 1;
 
             // 非目标国家 → 跳过
-            if (loc && !isLocationInList(loc, DEFAULT_TARGET_LOCATIONS)) {
+            if (loc && !isLocationInList(loc, getTargetLocations())) {
               await apiPut(`${serverUrl}/api/comment-task/${id}`);
               skippedCount++;
               console.error(
@@ -960,10 +960,10 @@ async function runManualMode(url, options) {
       // ── --save: 去重保存到服务端 ──
       if (
         guessedLocation &&
-        !isLocationInList(guessedLocation, DEFAULT_TARGET_LOCATIONS)
+        !isLocationInList(guessedLocation, getTargetLocations())
       ) {
         console.error(`\n猜测国家: ${guessedLocation}，非目标国家，跳过保存`);
-        console.error(`目标国家: ${DEFAULT_TARGET_LOCATIONS.join(", ")}`);
+        console.error(`目标国家: ${getTargetLocations().join(", ")}`);
       } else {
         console.error(`\n正在提交 ${authors.length} 个评论作者到服务端...`);
         console.error(`服务端: ${serverUrl}`);

package/src/cli/precheck.js

@@ -8,7 +8,7 @@ import {
 } from "../lib/constants.js";
 import { getMacOrUuid } from "../lib/mac-or-uuid.js";
 import { createApiClient } from "../lib/api-client.js";
-import { DEFAULT_TARGET_LOCATIONS } from "../lib/target-locations.js";
+import { getTargetLocations } from "../lib/app-config.js";
 import v8 from "node:v8";
 
 const HEAP_RESTART_RATIO = 0.72;
@@ -104,7 +104,7 @@ export async function handlePrecheck(options) {
   const locations =
     precheckCountries && precheckCountries.length > 0
       ? precheckCountries
-      : DEFAULT_TARGET_LOCATIONS;
+      : getTargetLocations();
 
   precheckLog(`[Precheck] 服务端: ${serverUrl}`);
   precheckLog(

package/src/cli/refresh-mini.js

@@ -8,7 +8,7 @@
  *   需要切换时向 clash-daemon 发 failover 命令（fire-and-forget），
  *   选节点、内容验证、失败回滚均由 daemon 完成
  *   触发条件：定时轮换（--rotate-min）/ 验证码超时 / 连续错误 ≥ 3 / CDN ≥ 3
- *   被封（0 字节空响应，api-interceptor 内部按 30/40/50s 重试 3 次）→ 仍封才触发切换
+ *   被封（0 字节空响应 / HTTP 429 限流，api-interceptor 内部按 30/40/50s 重试 3 次）→ 仍封才触发切换
  * - --ensure-daemon：启动时检查 daemon 是否存活，未存活则自动拉起（默认关闭）
  */
 

package/src/cli/tag.js

@@ -15,10 +15,8 @@ import { fetchTagData, enrichVideosWithLocation } from "../lib/tag-fetcher.js";
 import { killEdgeProcesses, ensureBrowserReady } from "../lib/browser/cdp.js";
 import { getOrCreatePage, isBrowserClosedError } from "../lib/browser/page.js";
 import { TikTokScraper } from "../lib/tiktok-scraper.mjs";
-import {
-  DEFAULT_TARGET_LOCATIONS,
-  isLocationInList,
-} from "../lib/target-locations.js";
+import { isLocationInList } from "../lib/target-locations.js";
+import { getTargetLocations } from "../lib/app-config.js";
 import { delay as randomDelay } from "../lib/delay.js";
 import { discoverTags } from "../lib/tag-discover.js";
 import {
@@ -33,26 +31,10 @@ import {
   closeCaptcha,
 } from "../scraper/modules/captcha-handler.js";
 
-const ALL_COUNTRIES = DEFAULT_TARGET_LOCATIONS;
 const DEFAULT_SERVER = cfgServer || "http://127.0.0.1:3000";
-const DEFAULT_SCORE_COUNTRIES = [
-  "ES",
-  "FR",
-  "DE",
-  "PT",
-  "IT",
-  "NL",
-  "BE",
-  "AT",
-  "IE",
-  "PL",
-  "CZ",
-  "GR",
-  "HU",
-];
 
 function resolveTargetCountries(countries) {
-  return countries || DEFAULT_SCORE_COUNTRIES;
+  return countries || getTargetLocations();
 }
 
 /**
@@ -465,7 +447,7 @@ export async function handleDiscover(parsed) {
     countries.length === 1 &&
     countries[0].toUpperCase() === "ALL"
   ) {
-    countries = ALL_COUNTRIES;
+    countries = getTargetLocations();
   }
 
   if (!countries || countries.length === 0) {
@@ -1649,7 +1631,7 @@ export async function handleTag(parsed) {
         .split(",")
         .map((s) => s.trim().toUpperCase())
         .filter(Boolean)
-    : DEFAULT_TARGET_LOCATIONS;
+    : getTargetLocations();
 
   const autoEnrich = enrich || !!discover;
 
@@ -2129,7 +2111,7 @@ export async function handleTagRefresh(parsed) {
         }
 
         // 过滤目标国家的视频和作者
-        const targetLocations = DEFAULT_TARGET_LOCATIONS;
+        const targetLocations = getTargetLocations();
         const filteredVideos = videos.filter((v) =>
           isLocationInList(v.locationCreated, targetLocations),
         );

package/src/lib/api-interceptor.js

@@ -172,6 +172,8 @@ async function attemptItemListFetch(page, username, log, apiRequestUrlRef) {
   let responsePromise = null;
   let response = null;
   let rawBodyBytes = -1; // -1 未知（未读取到 body）；0 = 服务端空响应（封禁判定依据）
+  let httpStatus = null; // 响应 HTTP 状态码
+  let bodyText = ""; // 响应体文本（识别 ratelimit triggered 等限流文案）
 
   try {
     // 响应监听必须在 goto 之前注册：domcontentloaded 返回时首个 item_list
@@ -208,6 +210,7 @@ async function attemptItemListFetch(page, username, log, apiRequestUrlRef) {
     // JSON 解析失败（如 "Unexpected end of JSON input"）时打印原始响应，
     // 便于诊断空响应/截断响应/非 JSON 响应等异常形态
     if (response) {
+      httpStatus = response.status();
       try {
         // body 读取同样可能因页面异常而挂起，加独立超时保护
         const raw = await Promise.race([
@@ -218,6 +221,7 @@ async function attemptItemListFetch(page, username, log, apiRequestUrlRef) {
         ]);
         const text = raw.toString("utf-8");
         rawBodyBytes = raw.length;
+        bodyText = text;
         // content-length 用于区分两种 0 字节形态：
         // 声明长度 > 实际字节 = 传输被截断；声明缺失/为 0 = 服务端主动空响应
         const declared = parseInt(
@@ -247,6 +251,8 @@ async function attemptItemListFetch(page, username, log, apiRequestUrlRef) {
     data,
     interceptionError,
     rawBodyBytes,
+    httpStatus,
+    bodyText,
     elapsed: Date.now() - t0,
   };
 }
@@ -343,8 +349,14 @@ async function fetchUserVideosAPI(
 
   while (true) {
     attempt++;
-    const { data, interceptionError, rawBodyBytes, elapsed } =
-      await attemptItemListFetch(page, username, log, apiRequestUrlRef);
+    const {
+      data,
+      interceptionError,
+      rawBodyBytes,
+      httpStatus,
+      bodyText,
+      elapsed,
+    } = await attemptItemListFetch(page, username, log, apiRequestUrlRef);
 
     if (data && Array.isArray(data.itemList) && data.itemList.length > 0) {
       log(`  [API拦截] 成功，耗时 ${elapsed}ms`);
@@ -359,21 +371,27 @@ async function fetchUserVideosAPI(
       );
     }
 
-    // 0 字节空响应 = 被封（content-length 缺失/为 0 或截断，统一按封禁处理）。
-    // 不再依赖页面"出错了/很抱歉"文案判定，静默型封禁（页面正常渲染但 API 空响应）也能识别。
-    // 默认 30/40/50 秒等待重试 3 次，仍封才抛错交给上层（explore/refresh/refresh-mini 均受益）
-    if (rawBodyBytes === 0) {
+    // 判定为被封的两种形态，统一按封禁处理（默认 30/40/50 秒重试 3 次，仍封才抛错交给上层）：
+    // 1. 0 字节空响应（content-length 缺失/为 0 或截断）—— 静默型封禁（页面正常渲染但 API 空响应）
+    // 2. HTTP 429 或 body 含 ratelimit —— 服务端主动限流（ratelimit triggered）
+    // 两种都不再依赖页面"出错了/很抱歉"文案判定，explore/refresh/refresh-mini 均受益
+    const rateLimited = httpStatus === 429 || /ratelimit/i.test(bodyText || "");
+    if (rawBodyBytes === 0 || rateLimited) {
+      const reason =
+        rawBodyBytes === 0
+          ? "空响应（0 字节）"
+          : `限流（HTTP ${httpStatus}, ${bodyText.slice(0, 60)}）`;
       const retryIndex = attempt - 1;
       if (retryIndex < retryWaits.length) {
         const waitMs = retryWaits[retryIndex];
         log(
-          `  [API拦截] item_list 空响应（0 字节），判定为被封，${waitMs / 1000}s 后第 ${attempt}/${retryWaits.length} 次重试...`,
+          `  [API拦截] item_list ${reason}，判定为被封，${waitMs / 1000}s 后第 ${attempt}/${retryWaits.length} 次重试...`,
         );
         await new Promise((r) => setTimeout(r, waitMs));
         continue;
       }
       log(
-        `  [API拦截] item_list 空响应（0 字节），重试 ${retryWaits.length} 次仍被封`,
+        `  [API拦截] item_list ${reason}，重试 ${retryWaits.length} 次仍被封`,
       );
       throw new Error(`被封: ${username}`);
     }

package/src/lib/app-config.js

@@ -0,0 +1,119 @@
+/**
+ * 通用应用配置模块（key-value，落盘到 ~/.tt-help-config.json）
+ *
+ * 设计为通用命名：任意配置项以 `key` 形式存放，后续可加入其他配置。
+ * 例如当前使用 `targetLocations`，未来可扩展 `xxx` 等。
+ *
+ * 读取规则：文件存在则用文件内容，否则回退内置默认值。
+ * 写入规则：整份 JSON 落盘（原子性不强，但配置变更频率低，可接受）。
+ */
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { DEFAULT_TARGET_LOCATIONS } from "./target-locations.js";
+
+// 通用配置文件路径（与 ~/.tt-help.json 隔离，避免与看门狗 clientConfig 写入冲突）
+const CONFIG_FILE = join(homedir(), ".tt-help-config.json");
+
+let _cache = null;
+
+export function getConfigFilePath() {
+  return CONFIG_FILE;
+}
+
+function readConfig() {
+  if (_cache) return _cache;
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      const parsed = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+      _cache = parsed && typeof parsed === "object" ? parsed : {};
+    } else {
+      _cache = {};
+    }
+  } catch {
+    _cache = {};
+  }
+  return _cache;
+}
+
+/**
+ * 通用读取：getConfig() 返回整份配置；getConfig(key) 返回指定项。
+ * @param {string|null} key
+ * @param {*} fallback
+ */
+export function getConfig(key = null, fallback = null) {
+  const cfg = readConfig();
+  if (key == null) return { ...cfg };
+  return cfg[key] !== undefined ? cfg[key] : fallback;
+}
+
+/**
+ * 通用写入：设置指定 key 并落盘，返回更新后的整份配置。
+ * @param {string} key
+ * @param {*} value
+ */
+export function setConfig(key, value) {
+  const cfg = readConfig();
+  cfg[key] = value;
+  _cache = cfg;
+  try {
+    writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), "utf-8");
+  } catch {
+    // 写失败不抛出，保证调用方不至于崩溃；仅保留内存值
+  }
+  return { ...cfg };
+}
+
+/**
+ * 通用删除：移除指定 key 并落盘，返回更新后的整份配置。
+ * @param {string} key
+ */
+export function removeConfig(key) {
+  const cfg = readConfig();
+  if (key in cfg) {
+    delete cfg[key];
+    _cache = cfg;
+    try {
+      writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), "utf-8");
+    } catch {
+      // 写失败忽略，仅保留内存值
+    }
+  }
+  return { ...cfg };
+}
+
+function normalizeLocations(locations) {
+  if (!Array.isArray(locations)) return [];
+  return [
+    ...new Set(
+      locations.map((l) => String(l).trim().toUpperCase()).filter(Boolean),
+    ),
+  ];
+}
+
+/** 读取当前目标国家，未配置则回退 DEFAULT_TARGET_LOCATIONS */
+export function getTargetLocations() {
+  const raw = getConfig("targetLocations", []);
+  const normalized = normalizeLocations(raw);
+  return normalized.length > 0 ? normalized : [...DEFAULT_TARGET_LOCATIONS];
+}
+
+/**
+ * 保存目标国家（自动去重、大写）。
+ * 传入空数组/非法值 = 移除配置项，回退到内置默认列表。
+ * 始终返回"生效后的列表"（getTargetLocations()），保证响应与读取一致。
+ */
+export function setTargetLocations(locations) {
+  const normalized = normalizeLocations(locations);
+  if (normalized.length === 0) {
+    removeConfig("targetLocations");
+  } else {
+    setConfig("targetLocations", normalized);
+  }
+  return getTargetLocations();
+}
+
+/** 清除内存缓存，强制下次读盘（配置被外部修改时调用） */
+export function reloadConfig() {
+  _cache = null;
+}

package/src/lib/args.js

@@ -1,6 +1,8 @@
 import { readFileSync } from "fs";
 import { server as defaultServer } from "./constants.js";
-import { DEFAULT_TARGET_LOCATIONS_CSV } from "./target-locations.js";
+import { getTargetLocations } from "./app-config.js";
+
+const DEFAULT_TARGET_LOCATIONS_CSV = getTargetLocations().join(",");
 
 const PRESETS = ["fast", "normal", "slow", "stealth"];
 

package/src/lib/constants.js

@@ -1,7 +1,9 @@
 import { join, dirname } from "path";
 import { readFileSync, writeFileSync, existsSync } from "fs";
 import { fileURLToPath } from "url";
-import { DEFAULT_TARGET_LOCATIONS_CSV } from "./target-locations.js";
+import { getTargetLocations } from "./app-config.js";
+
+const DEFAULT_TARGET_LOCATIONS_CSV = getTargetLocations().join(",");
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);

package/src/lib/target-locations.js

@@ -12,6 +12,7 @@ const DEFAULT_TARGET_LOCATIONS = [
   "IT",
   "IE",
   "AT",
+  "TH",
   "US",
 ];
 

package/src/scraper/core.js

@@ -11,17 +11,17 @@ import {
 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";
+import { getTargetLocations } from "../lib/app-config.js";
 
 async function scrapeSingleVideo(
   page,
   maxComments,
   maxGuess,
   log,
-  location = DEFAULT_TARGET_LOCATIONS_CSV,
+  location = getTargetLocations().join(","),
 ) {
   const config = getDelayConfig();
 

package/src/scraper/explore-core.js

@@ -5,12 +5,12 @@ import { getUserInfo, collectVideos } from "../videos/core.js";
 import { extractFollowAndFollowers } from "./modules/follow-extractor.js";
 import { extractVideoLocation, setScraperProxy } from "../lib/scrape.js";
 import {
-  DEFAULT_TARGET_LOCATIONS_CSV,
   findBestMatchingLocation,
   isLocationInList,
   normalizeLocation,
   normalizeLocationList,
 } from "../lib/target-locations.js";
+import { getTargetLocations } from "../lib/app-config.js";
 import {
   maxFollowing as globalMaxFollowing,
   maxFollowers as globalMaxFollowers,
@@ -23,7 +23,7 @@ async function processExplore(page, username, options, log) {
     loggedIn = false, // 由外部传入登录状态，避免每次调用 isLoggedIn(page)
     maxFollowing = 50,
     maxFollowers = 50,
-    location = DEFAULT_TARGET_LOCATIONS_CSV,
+    location = getTargetLocations().join(","),
     locationMode = "explore", // "explore" | "refresh"
     proxyServer = null,
     webserverUrl = null,

package/src/watch/data-store.js

@@ -19,10 +19,8 @@
 import fs from "fs";
 import path from "path";
 import Database from "better-sqlite3";
-import {
-  isLocationInList,
-  DEFAULT_TARGET_LOCATIONS,
-} from "../lib/target-locations.js";
+import { isLocationInList } from "../lib/target-locations.js";
+import { getTargetLocations } from "../lib/app-config.js";
 
 // Schema 与连接管理
 import {
@@ -665,7 +663,7 @@ function getModifiedTargetUsersOutsideLocations(targetLocations = []) {
 function getTargetRefreshStats(hours = 24) {
   if (!getDb()) return { countries: [], total: 0, refreshed: 0 };
 
-  const targetLocations = DEFAULT_TARGET_LOCATIONS;
+  const targetLocations = getTargetLocations();
   const placeholders = targetLocations.map(() => "?").join(", ");
 
   // 按国家统计总数
@@ -2226,7 +2224,7 @@ export function createStore(filePath, options = {}) {
       const now = Date.now();
       const threshold = now - maxAgeSeconds * 1000;
       const defaultTime = new Date("2016-01-01T00:00:00Z").getTime();
-      const targetLocations = locations || DEFAULT_TARGET_LOCATIONS;
+      const targetLocations = locations || getTargetLocations();
       const placeholders = targetLocations.map(() => "?").join(",");
       const row = getDb()
         .prepare(
@@ -2261,7 +2259,7 @@ export function createStore(filePath, options = {}) {
     const defaultTime = new Date("2016-01-01T00:00:00Z").getTime();
 
     // 筛选目标国家用户，按 refreshTime 升序取最远的（没有则默认 2016-01-01）
-    const targetLocations = locations || DEFAULT_TARGET_LOCATIONS;
+    const targetLocations = locations || getTargetLocations();
     const targetUsers = data.filter(
       (u) =>
         u.ttSeller &&
@@ -2405,7 +2403,7 @@ export function createStore(filePath, options = {}) {
     const now = Date.now();
     const threshold = now - intervalSeconds * 1000;
     const defaultTime = new Date("2016-01-01T00:00:00Z").getTime();
-    const targetLocations = locations || DEFAULT_TARGET_LOCATIONS;
+    const targetLocations = locations || getTargetLocations();
     const placeholders = targetLocations.map(() => "?").join(",");
 
     // SELECT 候选用户

package/src/watch/public/app.js

@@ -683,7 +683,7 @@ function closeAddModal() {
 
 // ========== 国家修改模态框 ==========
 
-const TARGET_LOCATIONS = [
+const DEFAULT_LOCATION_OPTIONS = [
   "AT",
   "BE",
   "CZ",
@@ -697,19 +697,35 @@ const TARGET_LOCATIONS = [
   "NL",
   "PL",
   "PT",
+  "TH",
+  "US",
 ];
+let locationOptions = [...DEFAULT_LOCATION_OPTIONS];
 
-function openLocationModal(uniqueId, currentLocation) {
+async function openLocationModal(uniqueId, currentLocation) {
   let overlay = document.getElementById("locationModalOverlay");
   if (overlay) return;
+  // 优先使用服务端配置的目标国家作为候选，失败则回退默认
+  try {
+    const res = await fetch("/api/settings/target-locations");
+    const data = await res.json();
+    const locs = (data.locations || []).filter(Boolean);
+    if (locs.length) {
+      locationOptions = [...new Set([...locs, ...DEFAULT_LOCATION_OPTIONS])];
+    }
+  } catch {
+    locationOptions = [...DEFAULT_LOCATION_OPTIONS];
+  }
   overlay = document.createElement("div");
   overlay.id = "locationModalOverlay";
   overlay.className = "modal-overlay";
   const safeId = escapeJsString(uniqueId);
-  const options = TARGET_LOCATIONS.map(
-    (loc) =>
-      `<button class="loc-option ${loc === currentLocation ? "active" : ""}" onclick="selectLocation('${safeId}','${loc}')">${loc}</button>`,
-  ).join("");
+  const options = locationOptions
+    .map(
+      (loc) =>
+        `<button class="loc-option ${loc === currentLocation ? "active" : ""}" onclick="selectLocation('${safeId}','${loc}')">${loc}</button>`,
+    )
+    .join("");
   overlay.innerHTML = `
     <div class="modal" style="max-width:420px">
       <h3>修改用户国家</h3>
@@ -1392,6 +1408,157 @@ function showSettingsPage() {
   hideAllPages();
   document.getElementById("settingsPage").classList.add("active");
   fetchLlmConfig();
+  loadTargetLocations();
+}
+
+// ========== 目标国家配置（通用 app-config，落盘 ~/.tt-help-config.json） ==========
+
+const AVAILABLE_COUNTRIES = [
+  "AT",
+  "BE",
+  "CZ",
+  "DE",
+  "ES",
+  "FR",
+  "GR",
+  "HU",
+  "IE",
+  "IT",
+  "NL",
+  "PL",
+  "PT",
+  "TH",
+  "US",
+  "GB",
+  "SE",
+  "NO",
+  "FI",
+  "DK",
+  "RO",
+  "BG",
+  "CH",
+  "SK",
+  "SI",
+  "HR",
+  "RS",
+  "UA",
+  "TR",
+  "MX",
+  "BR",
+  "AR",
+  "CL",
+  "CO",
+];
+
+function normalizeCountryInput(str) {
+  return [
+    ...new Set(
+      String(str || "")
+        .split(",")
+        .map((s) => s.trim().toUpperCase())
+        .filter(Boolean),
+    ),
+  ];
+}
+
+async function loadTargetLocations() {
+  const input = document.getElementById("targetLocationsInput");
+  const status = document.getElementById("targetLocationsStatus");
+  if (!input) return;
+  try {
+    const res = await fetch("/api/settings/target-locations");
+    const data = await res.json();
+    const locations = data.locations || [];
+    input.value = locations.join(",");
+    renderTargetCountryGrid(locations);
+    if (status) {
+      status.textContent = `当前 ${locations.length} 个国家: ${locations.join(", ")}`;
+      status.className = "settings-status ok";
+    }
+  } catch (e) {
+    console.error("loadTargetLocations error:", e);
+    if (status) {
+      status.textContent = "读取目标国家失败";
+      status.className = "settings-status warn";
+    }
+  }
+}
+
+function renderTargetCountryGrid(selected) {
+  const grid = document.getElementById("targetCountryGrid");
+  if (!grid) return;
+  const selectedSet = new Set(selected || []);
+  grid.innerHTML = AVAILABLE_COUNTRIES.map(
+    (loc) =>
+      `<button type="button" class="loc-option ${selectedSet.has(loc) ? "active" : ""}" onclick="toggleTargetCountry('${loc}')">${loc}</button>`,
+  ).join("");
+}
+
+function toggleTargetCountry(loc) {
+  const input = document.getElementById("targetLocationsInput");
+  if (!input) return;
+  let current = normalizeCountryInput(input.value);
+  if (current.includes(loc)) {
+    current = current.filter((l) => l !== loc);
+  } else {
+    current.push(loc);
+  }
+  input.value = current.join(",");
+  renderTargetCountryGrid(current);
+}
+
+async function saveTargetLocations() {
+  const input = document.getElementById("targetLocationsInput");
+  const status = document.getElementById("targetLocationsStatus");
+  if (!input) return;
+  const locations = normalizeCountryInput(input.value);
+  status.textContent = "保存中...";
+  status.className = "settings-status loading";
+  try {
+    const res = await fetch("/api/settings/target-locations", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ locations }),
+    });
+    const data = await res.json();
+    input.value = (data.locations || []).join(",");
+    renderTargetCountryGrid(data.locations || []);
+    status.textContent = `已保存 ${(data.locations || []).length} 个国家`;
+    status.className = "settings-status ok";
+  } catch (e) {
+    console.error("saveTargetLocations error:", e);
+    status.textContent = "保存失败";
+    status.className = "settings-status warn";
+  }
+}
+
+async function resetTargetLocations() {
+  const status = document.getElementById("targetLocationsStatus");
+  if (status) {
+    status.textContent = "保存中...";
+    status.className = "settings-status loading";
+  }
+  try {
+    const res = await fetch("/api/settings/target-locations", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ locations: [] }),
+    });
+    const data = await res.json();
+    const input = document.getElementById("targetLocationsInput");
+    if (input) input.value = (data.locations || []).join(",");
+    renderTargetCountryGrid(data.locations || []);
+    if (status) {
+      status.textContent = `已恢复默认 ${(data.locations || []).length} 个国家`;
+      status.className = "settings-status ok";
+    }
+  } catch (e) {
+    console.error("resetTargetLocations error:", e);
+    if (status) {
+      status.textContent = "恢复默认失败";
+      status.className = "settings-status warn";
+    }
+  }
 }
 
 let _llmProvidersCache = null;
@@ -1596,27 +1763,14 @@ function openAddTagModal() {
     if (e.target === overlay) closeAddTagModal();
   });
 
-  // 渲染国家复选框
+  // 渲染国家复选框（使用动态目标国家列表，含 TH/US，失败回退默认）
   const countryGrid = document.getElementById("addTagCountryCheckboxes");
-  const TARGET_LOCATIONS = [
-    "AT",
-    "BE",
-    "CZ",
-    "DE",
-    "ES",
-    "FR",
-    "GR",
-    "HU",
-    "IE",
-    "IT",
-    "NL",
-    "PL",
-    "PT",
-  ];
-  countryGrid.innerHTML = TARGET_LOCATIONS.map(
-    (c) =>
-      `<label class="checkbox-label"><input type="checkbox" value="${c}" checked> ${c}</label>`,
-  ).join("");
+  countryGrid.innerHTML = locationOptions
+    .map(
+      (c) =>
+        `<label class="checkbox-label"><input type="checkbox" value="${c}" checked> ${c}</label>`,
+    )
+    .join("");
 
   const ta = document.getElementById("addTagModalInput");
   ta.focus();

package/src/watch/public/index.html

@@ -20,7 +20,7 @@
         <input type="checkbox" id="fireworkToggle" checked onchange="toggleFireworks()">
         <span>🎆</span>
       </label>
-      <a class="script-link" onclick="navigateToSettings()" style="cursor:pointer">⚙️ LLM</a>
+      <a class="script-link" onclick="navigateToSettings()" style="cursor:pointer">⚙️ 配置</a>
       <a class="script-link" onclick="navigateToWatchdog()" style="cursor:pointer">🐕 看门狗</a>
       <span class="status" id="lastUpdate">--</span>
     </div>
@@ -488,6 +488,26 @@
         </div>
       </div>
     </div>
+    <div class="settings-card">
+      <h3>🎯 目标国家</h3>
+      <p class="settings-hint">设置采集的目标国家列表，保存后写入通用配置文件（~/.tt-help-config.json）。当前仅保存配置，后续接入采集流程后生效。</p>
+      <div class="settings-form">
+        <div class="settings-field">
+          <label>目标国家（英文国家代码，逗号分隔，如 CZ,GR,TH）</label>
+          <input type="text" id="targetLocationsInput" placeholder="CZ,GR,HU,PT,ES,PL,NL,BE,DE,FR,IT,IE,AT,TH,US">
+          <span class="settings-note">可手动输入，或点击下方国家快速选择。</span>
+        </div>
+        <div class="settings-field">
+          <label>快速选择</label>
+          <div class="loc-grid" id="targetCountryGrid"></div>
+        </div>
+        <div class="settings-status" id="targetLocationsStatus"></div>
+        <div class="btn-row">
+          <button class="btn-submit" onclick="saveTargetLocations()">保存目标国家</button>
+          <button class="btn-cancel" onclick="resetTargetLocations()">恢复默认</button>
+        </div>
+      </div>
+    </div>
   </div>
   <div id="watchdogPage">
     <div class="stats" style="margin-bottom:16px">

package/src/watch/public/style.css

@@ -1834,6 +1834,22 @@ td.user-id:hover {
   background: #e61944;
 }
 
+.settings-form .btn-cancel {
+  padding: 10px 20px;
+  border: 1px solid #333;
+  border-radius: 8px;
+  background: #2a2a3a;
+  color: #ccc;
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.2s;
+}
+
+.settings-form .btn-cancel:hover {
+  background: #333;
+}
+
 /* ── 看门狗页面 ── */
 
 #watchdogPage {

package/src/watch/server.js

@@ -8,7 +8,7 @@ import { fileURLToPath } from "url";
 import { spawn } from "child_process";
 import { createStore } from "./data-store.js";
 import { getTagDb } from "./db-schema.js";
-import { DEFAULT_TARGET_LOCATIONS } from "../lib/target-locations.js";
+import { getTargetLocations } from "../lib/app-config.js";
 import { tryHandleWatchdogRoute } from "./watchdog-server.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -44,11 +44,17 @@ const SLOW_STATS_TTL = 300000; // 5 分钟
 const usersCache = new Map(); // key -> { result, time }
 const USERS_CACHE_TTL = 3000; // 3 秒
 
-// 目标国家占位符（jobs 表聚合需要 location_created IN (...)）
-const TARGET_PLACEHOLDERS = DEFAULT_TARGET_LOCATIONS.map(() => "?").join(", ");
-const TARGET_IN_SQL = DEFAULT_TARGET_LOCATIONS.length
-  ? `location_created IN (${TARGET_PLACEHOLDERS})`
-  : "1 = 0";
+// 目标国家占位符（jobs 表聚合需要 location_created IN (...)，运行时按 getTargetLocations() 动态生成）
+function targetPlaceholders() {
+  const locs = getTargetLocations();
+  return locs.map(() => "?").join(", ");
+}
+function targetInSql() {
+  const locs = getTargetLocations();
+  return locs.length
+    ? `location_created IN (${targetPlaceholders()})`
+    : "1 = 0";
+}
 
 // 统计分组定义：每组包含若干 SQL（分片执行）与一个聚合函数
 // sqls 项：{ key, sql, mode: 'one'|'all', params: 数组或返回数组的函数 }
@@ -80,8 +86,8 @@ const STAT_GROUPS = {
       {
         key: "jobsAgg",
         mode: "one",
-        params: DEFAULT_TARGET_LOCATIONS,
-        sql: `SELECT
+        params: () => getTargetLocations(),
+        sql: () => `SELECT
           SUM(jobsTotal) as jobsTotal,
           SUM(done) as done,
           SUM(error) as error,
@@ -94,7 +100,7 @@ const STAT_GROUPS = {
             SUM(CASE WHEN status = 'done' THEN 1 ELSE 0 END) as done,
             SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error,
             SUM(CASE WHEN status = 'restricted' THEN 1 ELSE 0 END) as restricted,
-            SUM(CASE WHEN tt_seller = 1 AND verified = 0 AND ${TARGET_IN_SQL} THEN 1 ELSE 0 END) as targetUsers,
+            SUM(CASE WHEN tt_seller = 1 AND verified = 0 AND ${targetInSql()} THEN 1 ELSE 0 END) as targetUsers,
             SUM(CASE WHEN no_video = 1 THEN 1 ELSE 0 END) as noVideo
           FROM jobs
           UNION ALL
@@ -177,10 +183,10 @@ const STAT_GROUPS = {
       {
         key: "targetCountryStats",
         mode: "all",
-        params: DEFAULT_TARGET_LOCATIONS,
-        sql: `SELECT location_created as country, COUNT(*) as count
+        params: () => getTargetLocations(),
+        sql: () => `SELECT location_created as country, COUNT(*) as count
         FROM jobs
-        WHERE tt_seller = 1 AND verified = 0 AND ${TARGET_IN_SQL}
+        WHERE tt_seller = 1 AND verified = 0 AND ${targetInSql()}
         GROUP BY location_created
         ORDER BY count DESC`,
       },
@@ -284,9 +290,10 @@ function refreshGroupInShards(st, name) {
     if (idx < spec.sqls.length) {
       const s = spec.sqls[idx++];
       try {
+        const sql = typeof s.sql === "function" ? s.sql() : s.sql;
         const params =
           typeof s.params === "function" ? s.params() : s.params || [];
-        const r = st.rawQuery(s.sql, params);
+        const r = st.rawQuery(sql, params);
         if (r?.error) {
           console.error(`[stats] ${name}.${s.key} 查询失败: ${r.error}`);
           results[s.key] = null;
@@ -334,9 +341,10 @@ function computeGroupStats(st, name) {
     try {
       const results = {};
       for (const s of STAT_GROUPS[name].sqls) {
+        const sql = typeof s.sql === "function" ? s.sql() : s.sql;
         const params =
           typeof s.params === "function" ? s.params() : s.params || [];
-        const r = st.rawQuery(s.sql, params);
+        const r = st.rawQuery(sql, params);
         results[s.key] =
           s.mode === "all" ? r?.rows || [] : r?.rows?.[0] || null;
       }
@@ -641,7 +649,7 @@ export function startWatchServer(
         // 按国家维度判断：只为 new 标签不足的国家发现
         const countriesToDiscover = [];
         const { getTagsByStatus } = await import("./db-tags.js");
-        for (const country of DEFAULT_TARGET_LOCATIONS) {
+        for (const country of getTargetLocations()) {
           const newTags = getTagsByStatus("new", 100, 0, country, null, "llm");
           if (newTags.length < DISCOVER_PER_COUNTRY_THRESHOLD) {
             countriesToDiscover.push(country);
@@ -1137,7 +1145,7 @@ export function startWatchServer(
 
       if (req.method === "GET" && routePath === "/api/stats") {
         const stats = computeStatsIncremental(store);
-        stats.targetLocations = DEFAULT_TARGET_LOCATIONS;
+        stats.targetLocations = getTargetLocations();
         stats.clientLoginStatus = store.getClientLoginStatus();
         stats.activeClients = store.getActiveClients();
         sendJSON(res, 200, stats);
@@ -1494,7 +1502,7 @@ export function startWatchServer(
       }
 
       if (req.method === "GET" && routePath === "/api/target-users") {
-        const targetResult = store.getTargetUsers(DEFAULT_TARGET_LOCATIONS);
+        const targetResult = store.getTargetUsers(getTargetLocations());
         const targets = targetResult.users;
         if (req.headers["accept"]?.includes("text/csv")) {
           const columns = [
@@ -1549,19 +1557,16 @@ export function startWatchServer(
       ) {
         // 摘要模式：只返回各国统计数
         if (params.summary === "1") {
-          const result = store.getTargetUsersByCountry(
-            DEFAULT_TARGET_LOCATIONS,
-            { summaryOnly: true },
-          );
+          const result = store.getTargetUsersByCountry(getTargetLocations(), {
+            summaryOnly: true,
+          });
           sendJSON(res, 200, result);
           return;
         }
 
         // CSV 导出：全量数据
         if (req.headers["accept"]?.includes("text/csv")) {
-          const result = store.getTargetUsersByCountry(
-            DEFAULT_TARGET_LOCATIONS,
-          );
+          const result = store.getTargetUsersByCountry(getTargetLocations());
           const columns = [
             "uniqueId",
             "nickname",
@@ -1615,17 +1620,14 @@ export function startWatchServer(
 
         // 分页模式：按国家+搜索+分页查询用户
         if (params.limit) {
-          const result = store.getTargetUsersByCountry(
-            DEFAULT_TARGET_LOCATIONS,
-            {
-              country: params.country || undefined,
-              search: params.search || undefined,
-              limit: parseInt(params.limit, 10),
-              offset: parseInt(params.offset || "0", 10),
-              sort: params.sort || undefined,
-              sortOrder: params.sortOrder || "desc",
-            },
-          );
+          const result = store.getTargetUsersByCountry(getTargetLocations(), {
+            country: params.country || undefined,
+            search: params.search || undefined,
+            limit: parseInt(params.limit, 10),
+            offset: parseInt(params.offset || "0", 10),
+            sort: params.sort || undefined,
+            sortOrder: params.sortOrder || "desc",
+          });
           // 确保每个用户对象包含 topVideoPlayCount、topVideoHref 和 topVideoIsAd
           if (result.users && Array.isArray(result.users)) {
             result.users = result.users.map((u) => ({
@@ -1640,7 +1642,7 @@ export function startWatchServer(
         }
 
         // 默认：全量（兼容旧调用）
-        const result = store.getTargetUsersByCountry(DEFAULT_TARGET_LOCATIONS);
+        const result = store.getTargetUsersByCountry(getTargetLocations());
         // 确保每个用户对象包含 topVideoPlayCount、topVideoHref 和 topVideoIsAd
         if (result.countries && Array.isArray(result.countries)) {
           for (const country of result.countries) {
@@ -1662,9 +1664,8 @@ export function startWatchServer(
         req.method === "GET" &&
         routePath === "/api/target-users-other-countries"
       ) {
-        const result = store.getModifiedTargetUsersOutsideLocations(
-          DEFAULT_TARGET_LOCATIONS,
-        );
+        const result =
+          store.getModifiedTargetUsersOutsideLocations(getTargetLocations());
         sendJSON(res, 200, result);
         return;
       }
@@ -1842,6 +1843,49 @@ export function startWatchServer(
         return;
       }
 
+      // ====== 目标国家配置（通用 app-config 落盘） ======
+
+      // GET /api/settings/target-locations — 读取当前目标国家
+      if (
+        req.method === "GET" &&
+        routePath === "/api/settings/target-locations"
+      ) {
+        try {
+          const { getTargetLocations } = await import("../lib/app-config.js");
+          sendJSON(res, 200, { locations: getTargetLocations() });
+        } catch (e) {
+          sendJSON(res, 500, { error: e.message });
+        }
+        return;
+      }
+
+      // POST /api/settings/target-locations — 保存目标国家（body: { locations: ["CZ","GR",...] }）
+      if (
+        req.method === "POST" &&
+        routePath === "/api/settings/target-locations"
+      ) {
+        try {
+          const body = await readBody(req);
+          const { setTargetLocations } = await import("../lib/app-config.js");
+          const saved = setTargetLocations(body.locations);
+          sendJSON(res, 200, { locations: saved });
+        } catch (e) {
+          sendJSON(res, 400, { error: e.message });
+        }
+        return;
+      }
+
+      // GET /api/settings/config — 读取整份通用配置（便于后续扩展其他配置）
+      if (req.method === "GET" && routePath === "/api/settings/config") {
+        try {
+          const { getConfig } = await import("../lib/app-config.js");
+          sendJSON(res, 200, { config: getConfig() });
+        } catch (e) {
+          sendJSON(res, 500, { error: e.message });
+        }
+        return;
+      }
+
       // GET /api/llm-test — 直接测试 LLM API 连通性
       if (req.method === "GET" && routePath === "/api/llm-test") {
         try {
@@ -1939,7 +1983,7 @@ export function startWatchServer(
             targetLocation: params.targetLocation,
             limit: params.limit,
             offset: params.offset,
-            targetLocations: DEFAULT_TARGET_LOCATIONS,
+            targetLocations: getTargetLocations(),
           });
           usersCache.set(cacheKey, { result, time: Date.now() });
         }