tt-help-cli-ycl 1.4.13 → 1.4.14

package/package.json

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

package/src/cli/tag.js

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

package/src/lib/api-interceptor.js

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

package/src/lib/args.js

@@ -746,7 +746,9 @@ function parseTagArgs(args) {
   let isDiscover = false;
   let isScore = false;
   let isScoreAll = false;
+  let isRefresh = false;
   let scoreAllPort = 7222;
+  let refreshPort = 8222;
   let scoreProxy = null;
   let scoreTag = null;
   let scoreCountries = null;
@@ -794,6 +796,8 @@ function parseTagArgs(args) {
     } else if (arg === "--port") {
       if (isScoreAll) {
         scoreAllPort = parseInt(args[++i]) || 7222;
+      } else if (isRefresh) {
+        refreshPort = parseInt(args[++i]) || 8222;
       } else {
         scorePort = parseInt(args[++i]) || 9222;
       }
@@ -826,6 +830,8 @@ function parseTagArgs(args) {
         if (scoreCountries) i += scoreCountries.length;
       } else if (cleaned.toLowerCase() === "score-all") {
         isScoreAll = true;
+      } else if (cleaned.toLowerCase() === "refresh") {
+        isRefresh = true;
       } else {
         tags.push(cleaned.toLowerCase());
       }
@@ -899,6 +905,27 @@ function parseTagArgs(args) {
     };
   }
 
+  if (isRefresh) {
+    return {
+      subcommand: "tag-refresh",
+      tagRefresh: {
+        serverUrl,
+        port: refreshPort,
+        proxy: scoreProxy,
+      },
+      urls: [],
+      outputFormat: "json",
+      exploreCount: 0,
+      showConfig: false,
+      showHelp: false,
+      customProxy: null,
+      configAction: null,
+      configValue: null,
+      pipeMode: false,
+      filterStr: null,
+    };
+  }
+
   return {
     subcommand: "tag",
     tagTags: {

package/src/main.js

@@ -16,6 +16,7 @@ import {
   handleDiscover,
   handleScore,
   handleScoreAll,
+  handleTagRefresh,
 } from "./cli/tag.js";
 
 async function main() {
@@ -50,6 +51,8 @@ async function main() {
       return handleScore(parsed);
     case "tag-score-all":
       return handleScoreAll(parsed);
+    case "tag-refresh":
+      return handleTagRefresh(parsed);
   }
 
   const {

package/src/scraper/explore-core.js

@@ -105,6 +105,7 @@ async function processExplore(page, username, options, log) {
         href: topVideo.href,
         playCount: topVideo.playCount,
         createTime: topVideo.createTime,
+        isAd: topVideo.isAd,
       };
       log(
         `  7天内 EC视频最高播放: ${topVideo.playCount} 次播放 (${recentVideos.length} 个EC候选)`,

package/src/watch/data-store.js

@@ -50,6 +50,7 @@ import {
   getJobRow,
   getJobBaseRow,
   getJob,
+  getBulkAuthorLocations,
   getAllJobs,
   getVideoRow,
   getAllVideoRows,
@@ -96,6 +97,9 @@ import {
   rawQuery,
   normalizeTags,
   clearTags,
+  getProductiveRefreshTask,
+  claimRefreshTag,
+  reportRefreshResult,
 } from "./db-tags.js";
 
 // LLM 打分
@@ -391,6 +395,7 @@ function getTargetUsersByCountryFromDb(targetLocations = [], options = {}) {
         refresh_time,
         top_video_play_count,
         top_video_href,
+        top_video_is_ad,
         status,
         sources
       FROM jobs
@@ -490,6 +495,54 @@ function getTargetUsersByCountryFromDb(targetLocations = [], options = {}) {
   };
 }
 
+/**
+ * 查询已修改（modified_at IS NOT NULL）且 location_created 不在 targetLocations 中的目标商家，
+ * 按国家分组返回。
+ */
+function getModifiedTargetUsersOutsideLocations(targetLocations = []) {
+  if (!getDb()) return { countries: [], total: 0 };
+
+  const placeholders = targetLocations.map(() => "?").join(", ");
+  const rows = getDb()
+    .prepare(
+      `
+      SELECT unique_id, nickname, follower_count, video_count,
+             location_created, confirmed_location, modified_at, latest_video_time, refresh_time
+      FROM jobs
+      WHERE tt_seller = 1
+        AND verified = 0
+        AND modified_at IS NOT NULL
+        AND location_created IS NOT NULL
+        AND location_created NOT IN (${placeholders})
+      ORDER BY location_created ASC, COALESCE(latest_video_time, 0) DESC
+    `,
+    )
+    .all(...targetLocations)
+    .map(mapJobRow);
+
+  const countryMap = new Map();
+  for (const row of rows) {
+    const country = row.locationCreated || "未知";
+    if (!countryMap.has(country)) {
+      countryMap.set(country, { users: [], userCount: 0 });
+    }
+    const entry = countryMap.get(country);
+    entry.users.push(row);
+    entry.userCount++;
+  }
+
+  const countries = [];
+  for (const [country, entry] of countryMap) {
+    countries.push({
+      country,
+      count: entry.userCount,
+      users: entry.users,
+    });
+  }
+
+  return { total: rows.length, countries };
+}
+
 export function createStore(filePath, options = {}) {
   if (!filePath) {
     throw new Error("createStore requires an explicit .db path");
@@ -2292,6 +2345,7 @@ export function createStore(filePath, options = {}) {
       if (result.topRecentVideo && typeof result.topRecentVideo === "object") {
         user.topVideoPlayCount = result.topRecentVideo.playCount || null;
         user.topVideoHref = result.topRecentVideo.href || null;
+        user.topVideoIsAd = result.topRecentVideo.isAd ?? null;
       }
       user.sources = [...new Set([...(user.sources || []), "processed"])];
     }
@@ -2518,6 +2572,7 @@ export function createStore(filePath, options = {}) {
       if (result.topRecentVideo && typeof result.topRecentVideo === "object") {
         user.topVideoPlayCount = result.topRecentVideo.playCount || null;
         user.topVideoHref = result.topRecentVideo.href || null;
+        user.topVideoIsAd = result.topRecentVideo.isAd ?? null;
       }
       const newUsers = processDiscoveredUsers(result);
       const ret = updateJobInfo(uniqueId, user, false);
@@ -2543,6 +2598,7 @@ export function createStore(filePath, options = {}) {
     if (result.topRecentVideo && typeof result.topRecentVideo === "object") {
       user.topVideoPlayCount = result.topRecentVideo.playCount || null;
       user.topVideoHref = result.topRecentVideo.href || null;
+      user.topVideoIsAd = result.topRecentVideo.isAd ?? null;
     }
     const newUsers = processDiscoveredUsers(result);
     return { saved: true, newUsers };
@@ -3241,6 +3297,7 @@ export function createStore(filePath, options = {}) {
     getProcessedUsers,
     getAllUsers,
     getUserDbCount,
+    getBulkAuthorLocations,
     getJobsCount,
     getRawJobsCount,
     getPendingJobsCount,
@@ -3260,6 +3317,8 @@ export function createStore(filePath, options = {}) {
     getRawJobsPage: getRawJobsPageFromDb,
     getTargetUsers: getTargetUsersFromDb,
     getTargetUsersByCountry: getTargetUsersByCountryFromDb,
+    getModifiedTargetUsersOutsideLocations: (loc) =>
+      getModifiedTargetUsersOutsideLocations(loc),
     getStats,
     getStatusGroups,
     markGroupsDirty,
@@ -3310,6 +3369,9 @@ export function createStore(filePath, options = {}) {
     getTagStats,
     normalizeTags,
     clearTags,
+    getProductiveRefreshTask,
+    claimRefreshTag,
+    reportRefreshResult,
     data,
   };
 

package/src/watch/db-columns.js

@@ -48,6 +48,7 @@ export const JOB_EXT_COLUMNS = [
   "user_create_time",
   "top_video_play_count",
   "top_video_href",
+  "top_video_is_ad",
 ];
 
 // 完整的 jobs 列 = 核心列 + 扩展列
@@ -88,6 +89,7 @@ export const WRITABLE_JOB_COLUMNS = new Set([
   "latest_video_time",
   "top_video_play_count",
   "top_video_href",
+  "top_video_is_ad",
   "user_create_time",
 ]);
 

package/src/watch/db-crud.js

@@ -327,6 +327,34 @@ export function getJob(uniqueId) {
   return mapJobRow(getJobRow(uniqueId));
 }
 
+/**
+ * 批量查询作者的国家信息
+ * 从 jobs 和 jobs_base 表中查找已知的 location_created
+ * @param {string[]} uniqueIds
+ * @returns {Record<string, string>} { uniqueId: locationCreated }
+ */
+export function getBulkAuthorLocations(uniqueIds) {
+  const db = getDb();
+  if (!db || uniqueIds.length === 0) return {};
+  // SQLite 的 IN 子句不支持数组参数，动态构建占位符
+  const placeholders = uniqueIds.map(() => "?").join(",");
+  const sql = `
+    SELECT unique_id, location_created FROM jobs
+    WHERE unique_id IN (${placeholders}) AND location_created IS NOT NULL AND location_created != ''
+    UNION
+    SELECT unique_id, location_created FROM jobs_base
+    WHERE unique_id IN (${placeholders}) AND location_created IS NOT NULL AND location_created != ''
+  `;
+  const rows = db.prepare(sql).all(...uniqueIds, ...uniqueIds);
+  const result = {};
+  for (const r of rows) {
+    if (!result[r.unique_id]) {
+      result[r.unique_id] = r.location_created;
+    }
+  }
+  return result;
+}
+
 export function getAllJobs() {
   const db = getDb();
   if (!db) return [];

package/src/watch/db-schema.js

@@ -127,6 +127,7 @@ export function initDb(filePath) {
     bio_link: "TEXT",
     top_video_play_count: "INTEGER",
     top_video_href: "TEXT",
+    top_video_is_ad: "INTEGER",
     user_create_time: "INTEGER",
   });
 
@@ -280,6 +281,8 @@ export function initDb(filePath) {
     strategy: "TEXT",
     dead_reason: "TEXT",
     direction_id: "INTEGER",
+    refreshing: "INTEGER DEFAULT 0",
+    refreshed_at: "TEXT",
   });
 
   // ===== tag_directions 表（分层探索：通用词/分类/产品） =====

package/src/watch/db-tags.js

@@ -1234,3 +1234,98 @@ function getLang(country) {
   };
   return COUNTRY_LANG[country] || "en";
 }
+
+// ===== Tag 刷新 CRUD（productive 标签轮询重新抓取） =====
+
+/**
+ * 获取一个待刷新的 productive 标签（score > 70 且未被刷新锁定）
+ * 按 refreshed_at ASC 排序（最久未刷新的优先），NULL 排最前
+ */
+export function getProductiveRefreshTask() {
+  const db = getDb();
+  if (!db) return null;
+
+  // 先清理超时的 refreshing 锁（超过 30 分钟未释放）
+  db.prepare(
+    `UPDATE tags SET refreshing = 0 
+     WHERE refreshing = 1 AND refreshed_at IS NOT NULL 
+     AND refreshed_at < datetime('now', '-30 minutes')`,
+  ).run();
+
+  const row = db
+    .prepare(
+      `SELECT * FROM tags 
+       WHERE status = 'productive' AND score > 70 AND refreshing = 0 
+       ORDER BY refreshed_at IS NULL DESC, refreshed_at ASC 
+       LIMIT 1`,
+    )
+    .get();
+  return row ? parseTagRow(row) : null;
+}
+
+/**
+ * 锁定一个 productive 标签用于刷新（防并发冲突）
+ */
+export function claimRefreshTag(tag) {
+  const db = getDb();
+  if (!db) return { ok: false, error: "db not ready" };
+
+  const normalized = tag.replace(/^#+/, "").trim().toLowerCase();
+  if (!normalized || normalized.length < 2) {
+    return { ok: false, error: "invalid tag" };
+  }
+
+  // 同时尝试匹配带 # 和不带 # 的格式（兼容旧数据）
+  const result = db
+    .prepare(
+      `UPDATE tags SET refreshing = 1, refreshed_at = datetime('now') 
+       WHERE (tag = ? OR tag = ?) AND status = 'productive' AND score > 70 AND refreshing = 0`,
+    )
+    .run(normalized, `#${normalized}`);
+  if (result.changes === 0) {
+    const row = db
+      .prepare("SELECT status, refreshing FROM tags WHERE tag = ? OR tag = ?")
+      .get(normalized, `#${normalized}`);
+    if (!row) return { ok: false, error: "tag not found" };
+    if (row.refreshing) return { ok: false, error: "already being refreshed" };
+    return {
+      ok: false,
+      error: `tag status is ${row.status}, not eligible for refresh`,
+    };
+  }
+  return { ok: true, tag: normalized };
+}
+
+/**
+ * 报告刷新结果并解锁标签（不改变 score/status，只更新 refreshed_at 和 pushed_users）
+ */
+export function reportRefreshResult(tag, fields) {
+  const db = getDb();
+  if (!db) return { ok: false, error: "db not ready" };
+  const { pushedUsers, error } = fields;
+  const now = new Date().toISOString();
+  const normalized = tag.replace(/^#+/, "").trim().toLowerCase();
+
+  try {
+    const result = db
+      .prepare(
+        `UPDATE tags SET 
+          refreshing = 0, 
+          refreshed_at = ?,
+          pushed_users = COALESCE(pushed_users, 0) + COALESCE(?, 0),
+          last_error = COALESCE(?, last_error),
+          score_count = score_count + 1
+        WHERE tag = ? OR tag = ?`,
+      )
+      .run(
+        now,
+        pushedUsers ?? null,
+        error ?? null,
+        normalized,
+        `#${normalized}`,
+      );
+    return { ok: result.changes > 0, tag: normalized };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}

package/src/watch/public/app.js

@@ -735,6 +735,9 @@ async function selectLocation(uniqueId, location) {
       userInMem.locationCreated = location;
       userInMem.modifiedAt = Date.now();
     }
+
+    // 刷新"其他国家"区域（修改后可能需要更新统计）
+    fetchTargetOtherCountries();
   } catch (e) {
     showToast("更新失败: " + e.message, true);
   } finally {
@@ -1023,6 +1026,30 @@ document.getElementById("statTargetCard").addEventListener("click", () => {
 window.addEventListener("hashchange", handleRoute);
 window.addEventListener("DOMContentLoaded", handleRoute);
 
+// 回顶部按钮：仅在 targetPage 激活时监听滚动
+window.addEventListener(
+  "scroll",
+  function () {
+    const btn = document.getElementById("backToTop");
+    if (!btn) return;
+    const targetPage = document.getElementById("targetPage");
+    if (!targetPage || !targetPage.classList.contains("active")) {
+      btn.classList.remove("visible");
+      return;
+    }
+    if (window.scrollY > 400) {
+      btn.classList.add("visible");
+    } else {
+      btn.classList.remove("visible");
+    }
+  },
+  { passive: true },
+);
+
+function scrollToTop() {
+  window.scrollTo({ top: 0, behavior: "smooth" });
+}
+
 function handleRoute() {
   const hash = window.location.hash;
   if (hash === "#pending") {
@@ -1410,18 +1437,20 @@ function renderTagsTable() {
       const created = t.created_at || "-";
       const score = t.score != null ? t.score.toFixed(1) : "-";
       const authorCount = t.author_count ?? "-";
-      const totalPosts = t.total_posts ?? "-";
       const matchedAuthors = t.matched_authors ?? "-";
       const pushedUsers = t.pushed_users ?? "-";
+      const refreshedAt = t.refreshed_at
+        ? t.refreshed_at.slice(0, 16).replace("T", " ")
+        : "-";
 
       return `<tr>
       <td style="color:#9ca3af;font-size:12px;text-align:center">${i + 1}</td>
       <td style="font-weight:600;color:#e0e0e0">#${escapeHtml(t.tag)}</td>
-      <td style="color:${t.score >= 5 ? "#22c55e" : t.score >= 3 ? "#facc15" : "#888"}">${score}</td>
-      <td>${authorCount}</td>
-      <td>${totalPosts}</td>
-      <td>${matchedAuthors}</td>
-      <td>${pushedUsers}</td>
+      <td style="text-align:center;color:${t.score >= 5 ? "#22c55e" : t.score >= 3 ? "#facc15" : "#888"}">${score}</td>
+      <td style="text-align:center">${authorCount}</td>
+      <td style="text-align:center;font-size:11px;color:#9ca3af">${refreshedAt}</td>
+      <td style="text-align:center">${matchedAuthors}</td>
+      <td style="text-align:center">${pushedUsers}</td>
       <td style="font-size:11px">${countries}</td>
       <td>${statusTag}</td>
       <td style="font-size:11px;color:#888">${source}</td>
@@ -1517,6 +1546,7 @@ function showTargetPage() {
   document.getElementById("tagsPage").classList.remove("active");
   showLoading("正在加载目标商家数据...");
   fetchTargetByCountry();
+  fetchTargetOtherCountries();
   // 同步统计
   if (currentStats) {
     document.getElementById("targetPageStatTotal").textContent = formatStatNum(
@@ -1535,6 +1565,44 @@ let currentTargetSeq = 0;
 let currentTargetSort = { key: null, asc: true };
 const TARGET_PAGE_SIZE = 200;
 
+async function fetchTargetOtherCountries() {
+  try {
+    const res = await fetch("/api/target-users-other-countries");
+    const data = await res.json();
+    renderTargetOtherCountries(data.countries || []);
+  } catch (e) {
+    console.error("获取其他国家数据失败:", e);
+  }
+}
+
+function renderTargetOtherCountries(countries) {
+  const section = document.getElementById("targetOtherSection");
+  const grid = document.getElementById("targetOtherGrid");
+  if (!section || !grid) return;
+
+  if (!countries.length) {
+    section.style.display = "none";
+    return;
+  }
+  section.style.display = "block";
+  const total = countries.reduce((sum, c) => sum + (c.count || 0), 0);
+  grid.innerHTML = countries
+    .map((c) => {
+      const cnt = c.count || 0;
+      const pct = total > 0 ? ((cnt / total) * 100).toFixed(1) : "0.0";
+      const safeCountry = escapeJsString(c.country);
+      const sel = currentTargetLocation === c.country ? " selected" : "";
+      return `
+      <div class="pending-country-item other-country-item${sel}"
+           onclick="filterTargetByCountry('${safeCountry}')">
+        <div class="country-name">${c.country}</div>
+        <div class="country-count">${cnt}</div>
+        <div class="country-label">${pct}%</div>
+      </div>`;
+    })
+    .join("");
+}
+
 async function fetchTargetByCountry() {
   try {
     const res = await fetch("/api/target-users-by-country?summary=1");
@@ -1712,9 +1780,12 @@ function renderTargetTable() {
         u.topVideoPlayCount != null && u.topVideoPlayCount >= 1000
           ? formatNum(u.topVideoPlayCount)
           : "-";
+      const adTag = u.topVideoIsAd
+        ? ' <span style="color:red">(AD)</span>'
+        : "";
       const topPlayCountCell = u.topVideoHref
-        ? `<td data-label="最大播放量" style="font-size:11px;color:#888"><a href="${u.topVideoHref}" target="_blank" style="color:#3b82f6;text-decoration:none" title="点击查看视频">${topPlayCount}</a></td>`
-        : `<td data-label="最大播放量" style="font-size:11px;color:#888">${topPlayCount}</td>`;
+        ? `<td data-label="最大播放量" style="font-size:11px;color:#888"><a href="${u.topVideoHref}" target="_blank" style="color:#3b82f6;text-decoration:none" title="点击查看视频">${topPlayCount}${adTag}</a></td>`
+        : `<td data-label="最大播放量" style="font-size:11px;color:#888">${topPlayCount}${adTag}</td>`;
 
       const editIcon = ' <span style="font-size:10px;opacity:0.5">✏️</span>';
       const locationCell = u.modifiedAt
@@ -1782,13 +1853,9 @@ function filterTargetByCountry(country) {
 }
 
 function clearTargetFilters() {
-  currentTargetLocation = "";
+  // 只清空搜索关键词，保留当前选中的国家筛选
   const searchInput = document.getElementById("targetSearchInput");
-  const locationFilter = document.getElementById("targetLocationFilter");
   if (searchInput) searchInput.value = "";
-  if (locationFilter) locationFilter.value = "";
-  const btn = document.getElementById("targetReprocessBtn");
-  if (btn) btn.style.display = "none";
   if (currentTargetSummary) {
     renderTargetCountryGrid(currentTargetSummary.countries || []);
     loadTargetUsersPage();

package/src/watch/public/index.html

@@ -328,6 +328,11 @@
           <span style="color:#666;font-size:12px">加载中...</span>
         </div>
         <div class="muted-tip">点击国家卡片可筛选列表。</div>
+        <div class="target-other-section" id="targetOtherSection" style="display:none">
+          <h3 style="color:#f59e0b;margin-top:20px;margin-bottom:12px">🌍 其他国家 (已修改)</h3>
+          <div class="pending-country-grid" id="targetOtherGrid"></div>
+          <div class="muted-tip">这些商家已被手动修改到非目标国家。</div>
+        </div>
       </div>
       <div class="target-table-card">
         <h3>目标商家列表</h3>
@@ -361,6 +366,7 @@
         </div>
       </div>
     </div>
+    <div id="backToTop" title="回到顶部" onclick="scrollToTop()">↑</div>
   </div>
   <div id="tagsPage">
     <div class="stats" style="margin-bottom:16px">
@@ -415,7 +421,7 @@
                 <th style="min-width:120px">关键词</th>
                 <th class="sortable-tag" data-sort="score">评分 <span class="sort-icon">↕</span></th>
                 <th class="sortable-tag" data-sort="author_count">作者数 <span class="sort-icon">↕</span></th>
-                <th class="sortable-tag" data-sort="total_posts">帖子数 <span class="sort-icon">↕</span></th>
+                <th class="sortable-tag" data-sort="refreshed_at">最近刷新 <span class="sort-icon">↕</span></th>
                 <th class="sortable-tag" data-sort="matched_authors">匹配作者 <span class="sort-icon">↕</span></th>
                 <th class="sortable-tag" data-sort="pushed_users">推送用户 <span class="sort-icon">↕</span></th>
                 <th>国家</th>

package/src/watch/public/style.css

@@ -839,6 +839,36 @@ td.user-id:hover {
   display: block;
 }
 
+#backToTop {
+  position: fixed;
+  bottom: 32px;
+  right: 32px;
+  width: 44px;
+  height: 44px;
+  border-radius: 50%;
+  background: rgba(254, 44, 85, 0.85);
+  color: #fff;
+  font-size: 20px;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  z-index: 999;
+  box-shadow: 0 4px 16px rgba(254, 44, 85, 0.35);
+  transition: opacity 0.25s, transform 0.25s, background 0.2s;
+  user-select: none;
+}
+
+#backToTop:hover {
+  background: #e61944;
+  transform: translateY(-2px);
+  box-shadow: 0 6px 20px rgba(254, 44, 85, 0.5);
+}
+
+#backToTop.visible {
+  display: flex;
+}
+
 #mainPage.hidden {
   display: none;
 }
@@ -1004,6 +1034,19 @@ td.user-id:hover {
   color: #ddd6fe;
 }
 
+.other-country-item {
+  border-color: #f59e0b;
+}
+
+.other-country-item .country-name {
+  color: #f59e0b;
+}
+
+.other-country-item:hover {
+  border-color: #fbbf24;
+  background: #3a3520;
+}
+
 .back-btn {
   padding: 6px 14px;
   border: 1px solid #333;

package/src/watch/server.js

@@ -93,6 +93,7 @@ function inferClientType(routePath) {
   if (routePath.startsWith("/api/redo-job")) return "refresh";
   if (routePath.startsWith("/api/user-update-tasks")) return "attach";
   if (routePath.startsWith("/api/comment-task")) return "comments";
+  if (routePath.startsWith("/api/tags/refresh")) return "tag-refresh";
   if (routePath.startsWith("/api/tags")) return "scoring";
   if (
     routePath.startsWith("/api/job") ||
@@ -142,9 +143,12 @@ export function startWatchServer(
     let discoverRunning = false;
     let lastDiscoverTime = 0;
 
-    // 标签池充足阈值：new 标签总数超过此值时，定时触发直接跳过（不浪费 LLM token）
-    const DISCOVER_SUFFICIENT_TOTAL =
-      parseInt(process.env.TAG_DISCOVER_SUFFICIENT || "30", 10) || 30;
+    // 每国标签不足阈值：某国 new 标签低于此值时触发 discover
+    const DISCOVER_PER_COUNTRY_THRESHOLD = Math.max(
+      3,
+      parseInt(process.env.TAG_DISCOVER_PER_COUNTRY_THRESHOLD || "10", 10) ||
+        10,
+    );
 
     async function runAutoDiscover(trigger = "timer") {
       if (discoverRunning) return;
@@ -156,23 +160,14 @@ export function startWatchServer(
         );
         return;
       }
-      // 先看全局总量：标签池充足时直接跳过，不浪费 LLM token
-      const globalStats = store.getTagStats();
-      const totalNew = globalStats?.new || 0;
-      if (totalNew >= DISCOVER_SUFFICIENT_TOTAL) {
-        console.error(
-          `[discover] 标签池充足 (${totalNew} 个 new ≥ ${DISCOVER_SUFFICIENT_TOTAL})，跳过 [触发: ${trigger}]`,
-        );
-        return;
-      }
       discoverRunning = true;
       try {
-        // 只为 new 标签不足的国家发现
+        // 按国家维度判断：只为 new 标签不足的国家发现
         const countriesToDiscover = [];
         const { getTagsByStatus } = await import("./db-tags.js");
         for (const country of DEFAULT_TARGET_LOCATIONS) {
           const newTags = getTagsByStatus("new", 100, 0, country);
-          if (newTags.length < 10) {
+          if (newTags.length < DISCOVER_PER_COUNTRY_THRESHOLD) {
             countriesToDiscover.push(country);
           }
         }
@@ -860,12 +855,13 @@ export function startWatchServer(
               offset: parseInt(params.offset || "0", 10),
             },
           );
-          // 确保每个用户对象包含 topVideoPlayCount 和 topVideoHref
+          // 确保每个用户对象包含 topVideoPlayCount、topVideoHref 和 topVideoIsAd
           if (result.users && Array.isArray(result.users)) {
             result.users = result.users.map((u) => ({
               ...u,
               topVideoPlayCount: u.topVideoPlayCount || null,
               topVideoHref: u.topVideoHref || null,
+              topVideoIsAd: u.topVideoIsAd ?? null,
             }));
           }
           sendJSON(res, 200, result);
@@ -874,7 +870,7 @@ export function startWatchServer(
 
         // 默认：全量（兼容旧调用）
         const result = store.getTargetUsersByCountry(DEFAULT_TARGET_LOCATIONS);
-        // 确保每个用户对象包含 topVideoPlayCount 和 topVideoHref
+        // 确保每个用户对象包含 topVideoPlayCount、topVideoHref 和 topVideoIsAd
         if (result.countries && Array.isArray(result.countries)) {
           for (const country of result.countries) {
             if (country.users && Array.isArray(country.users)) {
@@ -882,6 +878,7 @@ export function startWatchServer(
                 ...u,
                 topVideoPlayCount: u.topVideoPlayCount || null,
                 topVideoHref: u.topVideoHref || null,
+                topVideoIsAd: u.topVideoIsAd ?? null,
               }));
             }
           }
@@ -890,6 +887,17 @@ export function startWatchServer(
         return;
       }
 
+      if (
+        req.method === "GET" &&
+        routePath === "/api/target-users-other-countries"
+      ) {
+        const result = store.getModifiedTargetUsersOutsideLocations(
+          DEFAULT_TARGET_LOCATIONS,
+        );
+        sendJSON(res, 200, result);
+        return;
+      }
+
       if (req.method === "GET" && routePath === "/api/client-errors") {
         sendJSON(res, 200, { clients: store.getClientErrors() });
         return;
@@ -1327,6 +1335,71 @@ export function startWatchServer(
         return;
       }
 
+      // POST /api/bulk-author-locations — 批量查询作者国家（用于 tag 客户端 enrich 前跳过已知数据）
+      if (req.method === "POST" && routePath === "/api/bulk-author-locations") {
+        try {
+          const body = await readBody(req);
+          const uniqueIds = Array.isArray(body.uniqueIds) ? body.uniqueIds : [];
+          const locations = store.getBulkAuthorLocations(uniqueIds);
+          sendJSON(res, 200, { locations });
+        } catch (e) {
+          sendJSON(res, 500, { error: e.message });
+        }
+        return;
+      }
+
+      // GET /api/tags/refresh-task — 领取一个 productive 标签用于刷新（score>70，未被锁定）
+      if (req.method === "GET" && routePath === "/api/tags/refresh-task") {
+        const task = store.getProductiveRefreshTask();
+        if (!task) {
+          sendJSON(res, 200, {
+            tag: null,
+            message: "no productive tags available for refresh",
+          });
+          return;
+        }
+        sendJSON(res, 200, {
+          tag: task.tag,
+          score: task.score,
+          refreshedAt: task.refreshed_at,
+        });
+        return;
+      }
+
+      // POST /api/tags/refresh-claim { tag } — 锁定 productive 标签用于刷新（防并发冲突）
+      if (req.method === "POST" && routePath === "/api/tags/refresh-claim") {
+        try {
+          const body = await readBody(req);
+          const tag = (body.tag || "").trim().toLowerCase();
+          if (!tag) {
+            sendJSON(res, 400, { error: "tag 不能为空" });
+            return;
+          }
+          const result = store.claimRefreshTag(tag);
+          sendJSON(res, result.ok ? 200 : 409, result);
+        } catch (e) {
+          sendJSON(res, 500, { error: e.message });
+        }
+        return;
+      }
+
+      // POST /api/tags/refresh-result { tag, pushedUsers, error } — 报告刷新结果并解锁
+      if (req.method === "POST" && routePath === "/api/tags/refresh-result") {
+        try {
+          const body = await readBody(req);
+          const tag = (body.tag || "").trim().toLowerCase();
+          if (!tag) {
+            sendJSON(res, 400, { error: "tag 不能为空" });
+            return;
+          }
+          const result = store.reportRefreshResult(tag, body);
+          sendJSON(res, result.ok ? 200 : 400, result);
+        } catch (e) {
+          sendJSON(res, 500, { error: e.message });
+        }
+        return;
+      }
+
       // GET /api/tags/recent-generated?country=ES&lookback=10 — 最近N轮生成的标签（去重）
       if (req.method === "GET" && routePath === "/api/tags/recent-generated") {
         try {
@@ -1915,7 +1988,7 @@ export function startWatchServer(
       );
       setTimeout(() => runAutoDiscover("startup"), 30000);
       console.error(
-        `[discover] 定时+按需发现已启动: 定时间隔 ${DISCOVER_INTERVAL_MS / 60000} 分钟, 每国 ${DISCOVER_COUNT_PER_COUNTRY} 个标签, 按需阈值 ${DISCOVER_LOW_THRESHOLD}, 冷却期 ${DISCOVER_COOLDOWN_MS / 1000}s`,
+        `[discover] 定时+按需发现已启动: 定时间隔 ${DISCOVER_INTERVAL_MS / 60000} 分钟, 每国 ${DISCOVER_COUNT_PER_COUNTRY} 个标签, 每国不足阈值 ${DISCOVER_PER_COUNTRY_THRESHOLD}, 按需触发阈值 ${DISCOVER_LOW_THRESHOLD}, 冷却期 ${DISCOVER_COOLDOWN_MS / 1000}s`,
       );
 
       _resolve({ server, port });