tt-help-cli-ycl 1.4.89 → 1.4.91

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tt-help-cli-ycl",
-  "version": "1.4.89",
+  "version": "1.4.91",
   "description": "TikTok user & video data scraper - extract ttSeller, verified, locationCreated from HTML source",
   "type": "module",
   "bin": {
@@ -48,4 +48,4 @@
   "devDependencies": {
     "better-sqlite3": "^12.10.0"
   }
-}
+}

package/scripts/test-country-fix.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * 回归测试：节点国家配置收敛修复（2026-08-12）
+ *
+ * 背景：daemon 启动硬编码 --country US，且服务端幂等基准是"是否下发过"，
+ * 导致 daemon 重启（崩溃自愈/升级/机器重启）回退 US 后服务端不补发 → 一直用美国节点。
+ *
+ * 运行方式（务必用隔离 TMPDIR，避免污染真实 clash-*.json / 服务端配置）：
+ *   TMPDIR=$(mktemp -d) node scripts/test-country-fix.mjs
+ *
+ * 覆盖：
+ *   A. 服务端幂等基准 = 客户端实际生效国家（核心修复）
+ *      - daemon 重启回退 US 后，服务端补发 JP
+ *      - daemon 已生效 JP 时，幂等不重复下发
+ *      - daemon 未上报时，下发
+ *      - 多国配置且已生效时，幂等不重复下发
+ *   B. daemon 逗号分隔多国 --country 参数解析
+ *   C. checker normalizeCountries / filterNodesByCountry 回归
+ *   D. 客户端 daemon 启动兜底：读 clash-health.json 上次生效国家 → join(",")
+ */
+
+import { mkdtempSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+let passed = 0;
+let failed = 0;
+function ok(cond, name, extra = "") {
+  if (cond) {
+    passed++;
+    console.log(`  ✅ ${name}`);
+  } else {
+    failed++;
+    console.log(`  ❌ ${name}  ${extra}`);
+  }
+}
+
+// ── 隔离 HOME：避免读写真实服务端配置 ~/.tt-help-watchdog.json ──
+const fakeHome = mkdtempSync(join(tmpdir(), "tt-wd-home-"));
+process.env.HOME = fakeHome;
+process.env.USERPROFILE = fakeHome;
+
+function fakeRes() {
+  return {
+    status: 0,
+    body: null,
+    writeHead(code) {
+      this.status = code;
+    },
+    end(b) {
+      this.body = b;
+    },
+  };
+}
+async function wdCall(mod, path, method, params, body) {
+  const res = fakeRes();
+  await mod.tryHandleWatchdogRoute(path, method, params, body, res);
+  return { status: res.status, data: res.body ? JSON.parse(res.body) : null };
+}
+
+console.log("\n═══ A. 服务端幂等基准 = 客户端实际生效国家 ═══");
+const wd = await import("../src/watch/watchdog-server.js");
+
+// A1 配置 T1 → JP
+let r = await wdCall(
+  wd,
+  "/api/watchdog/set-country-filter",
+  "POST",
+  {},
+  {
+    userId: "T1",
+    countries: ["JP"],
+  },
+);
+ok(
+  r.status === 200 && JSON.stringify(r.data.countries) === '["JP"]',
+  "A1 配置 T1 → JP",
+  JSON.stringify(r.data),
+);
+
+// A2 心跳：daemon 回退 US（重启后）→ 服务端应补发 JP（核心修复点，旧逻辑因 lastSent 幂等不会下发）
+r = await wdCall(
+  wd,
+  "/api/watchdog/heartbeat",
+  "POST",
+  { clientId: "c1" },
+  {
+    config: { userId: "T1" },
+    clashHealth: { meta: { countryFilter: ["US"] } },
+  },
+);
+let cmds = (r.data && r.data.clashCommands) || [];
+ok(
+  cmds.some(
+    (c) =>
+      c.action === "setCountryFilter" &&
+      JSON.stringify(c.countries) === '["JP"]',
+  ),
+  "A2 daemon 生效 US(重启回退) → 补发 setCountryFilter JP",
+  JSON.stringify(cmds),
+);
+
+// A3 心跳：daemon 已生效 JP → 幂等不重复下发
+r = await wdCall(
+  wd,
+  "/api/watchdog/heartbeat",
+  "POST",
+  { clientId: "c1" },
+  {
+    config: { userId: "T1" },
+    clashHealth: { meta: { countryFilter: ["JP"] } },
+  },
+);
+cmds = (r.data && r.data.clashCommands) || [];
+ok(
+  !cmds.some((c) => c.action === "setCountryFilter"),
+  "A3 daemon 生效 JP → 幂等不下发",
+  JSON.stringify(cmds),
+);
+
+// A4 心跳：daemon 未上报 clashHealth → 下发
+r = await wdCall(
+  wd,
+  "/api/watchdog/heartbeat",
+  "POST",
+  { clientId: "c1" },
+  {
+    config: { userId: "T1" },
+    clashHealth: null,
+  },
+);
+cmds = (r.data && r.data.clashCommands) || [];
+ok(
+  cmds.some(
+    (c) =>
+      c.action === "setCountryFilter" &&
+      JSON.stringify(c.countries) === '["JP"]',
+  ),
+  "A4 daemon 未上报 → 下发 setCountryFilter JP",
+  JSON.stringify(cmds),
+);
+
+// A5 多国配置 US+JP 且 daemon 已生效 US+JP → 幂等不下发
+// 注：配置动作本身会立即入队一次下发（配置后本该生效一次），首轮心跳取走后再验证幂等
+await wdCall(
+  wd,
+  "/api/watchdog/set-country-filter",
+  "POST",
+  {},
+  {
+    userId: "T2",
+    countries: ["US", "JP"],
+  },
+);
+r = await wdCall(
+  wd,
+  "/api/watchdog/heartbeat",
+  "POST",
+  { clientId: "c2" },
+  {
+    config: { userId: "T2" },
+    clashHealth: { meta: { countryFilter: ["US", "JP"] } },
+  },
+);
+cmds = (r.data && r.data.clashCommands) || [];
+ok(
+  cmds.some(
+    (c) =>
+      c.action === "setCountryFilter" &&
+      JSON.stringify(c.countries) === '["US","JP"]',
+  ),
+  "A5a 配置后首次心跳取走命令",
+  JSON.stringify(cmds),
+);
+r = await wdCall(
+  wd,
+  "/api/watchdog/heartbeat",
+  "POST",
+  { clientId: "c2" },
+  {
+    config: { userId: "T2" },
+    clashHealth: { meta: { countryFilter: ["US", "JP"] } },
+  },
+);
+cmds = (r.data && r.data.clashCommands) || [];
+ok(
+  !cmds.some((c) => c.action === "setCountryFilter"),
+  "A5 多国且已生效 → 幂等不下发",
+  JSON.stringify(cmds),
+);
+
+console.log("\n═══ B. daemon 逗号分隔多国 --country 解析 ═══");
+const { ClashDaemon } = await import("../src/clash/daemon.js");
+const checker = await import("../src/clash/checker.js");
+
+const cases = [
+  ["US,JP", ["US", "JP"], "US,JP 逗号分隔 → 多国并集"],
+  ["JP", ["JP"], "JP 单国"],
+  ["us, jp", ["US", "JP"], "小写+空格归一"],
+  [undefined, null, "未传 country → 不过滤"],
+];
+for (const [input, expect, name] of cases) {
+  checker.CONFIG.nodeCountryFilter = null;
+  new ClashDaemon({ country: input });
+  const got = checker.CONFIG.nodeCountryFilter;
+  ok(JSON.stringify(got) === JSON.stringify(expect), name, JSON.stringify(got));
+}
+checker.CONFIG.nodeCountryFilter = null;
+
+console.log("\n═══ C. checker 国家过滤回归 ═══");
+ok(
+  JSON.stringify(checker.normalizeCountries(["us", " JP", "US"])) ===
+    '["US","JP"]',
+  "C1 数组去重大写",
+);
+ok(
+  JSON.stringify(checker.normalizeCountries("jp")) === '["JP"]',
+  "C2 字符串大写",
+);
+ok(checker.normalizeCountries(null).length === 0, "C3 null → 空");
+ok(checker.normalizeCountries("").length === 0, "C4 空串 → 空");
+// 注意：checker.normalizeCountries 不拆分逗号（拆分在 daemon constructor），单字符串"US,JP"保持为一个元素
+ok(
+  JSON.stringify(checker.normalizeCountries("US,JP")) === '["US,JP"]',
+  "C5 单字符串逗号不拆分（保持向后兼容）",
+);
+const nodes = ["🇺🇸美国A", "🇯🇵日本A", "🇩🇪德国A", "无旗帜节点"];
+let fr = checker.filterNodesByCountry(nodes, ["US", "JP"]);
+ok(
+  fr.filtered.length === 2 && fr.excluded === 2,
+  "C6 多国并集过滤（US+JP 命中 2）",
+  JSON.stringify(fr),
+);
+fr = checker.filterNodesByCountry(nodes, ["ZZ"]);
+ok(
+  fr.filtered.length === 4 && fr.excluded === 0,
+  "C7 未知国家向后兼容返回全部",
+);
+fr = checker.filterNodesByCountry(nodes, null);
+ok(fr.filtered.length === 4 && fr.excluded === 0, "C8 null 不过滤");
+
+console.log("\n═══ D. 客户端 daemon 启动兜底（读上次生效国家）═══");
+const { getClashHealth } = await import("../src/watchdog/reporter.js");
+const healthPath = join(tmpdir(), "clash-health.json");
+
+writeFileSync(
+  healthPath,
+  JSON.stringify({
+    meta: { countryFilter: ["JP"] },
+    lastCheck: new Date().toISOString(),
+  }),
+);
+let prev = getClashHealth()?.meta?.countryFilter;
+ok(
+  Array.isArray(prev) && JSON.stringify(prev) === '["JP"]',
+  "D1 读到上次生效国家 JP",
+  JSON.stringify(prev),
+);
+let countryArg = Array.isArray(prev) && prev.length ? prev.join(",") : "US";
+ok(countryArg === "JP", "D2 单国 join → 'JP'", countryArg);
+
+writeFileSync(
+  healthPath,
+  JSON.stringify({
+    meta: { countryFilter: ["US", "JP"] },
+    lastCheck: new Date().toISOString(),
+  }),
+);
+prev = getClashHealth()?.meta?.countryFilter;
+countryArg = Array.isArray(prev) && prev.length ? prev.join(",") : "US";
+ok(countryArg === "US,JP", "D3 多国 join → 'US,JP'", countryArg);
+
+// 无上次生效记录（clashHealth 缺失）→ 兜底 US
+const nonePrev = null?.meta?.countryFilter;
+const noneArg =
+  Array.isArray(nonePrev) && nonePrev.length ? nonePrev.join(",") : "US";
+ok(noneArg === "US", "D4 无记录 → 兜底 US");
+
+console.log(`\n结果: ${passed} 通过, ${failed} 失败`);
+process.exit(failed ? 1 : 0);

package/src/clash/daemon.js

@@ -25,14 +25,22 @@ function fmtCountries(v) {
 export class ClashDaemon {
   constructor(opts = {}) {
     this.intervalMs = (opts.intervalSec || 120) * 1000;
-    this.benchmarkMs = (opts.benchmarkMin || 40) * 60 * 1000;
+    this.benchmarkMs = (opts.benchmarkMin || 10) * 60 * 1000; // 候选集刷新默认 10 分钟
     this.dryRun = !!opts.dryRun;
     this._running = false;
     this._timers = [];
     this._waitTimer = null; // 等待 Clash 就绪的重试定时器
     this._startedOnce = false; // 首次启动标记（banner/信号只打印注册一次）
     this._benchmarkRunning = false;
-    const initCountries = normalizeCountries(opts.country);
+    // 支持逗号分隔字符串（如 "US,JP"），便于 watchdog 以 --country 透传上次生效的多国配置
+    let initCountriesRaw = opts.country;
+    if (
+      typeof initCountriesRaw === "string" &&
+      initCountriesRaw.includes(",")
+    ) {
+      initCountriesRaw = initCountriesRaw.split(",");
+    }
+    const initCountries = normalizeCountries(initCountriesRaw);
     if (initCountries.length) checker.CONFIG.nodeCountryFilter = initCountries;
     this._meta = {
       groupName: checker.CONFIG.groupName,
@@ -171,21 +179,24 @@ export class ClashDaemon {
         h.error || `HTTP ${h.httpCode} ${(h.sizeDownload / 1024).toFixed(0)}KB`;
       const { nodes } = checker.loadHealthyList();
       if (!nodes.length) {
-        this._log(`✗ ${reason} — 候选集为空，触发 delay 初测`);
+        this._log(`✗ 巡检异常 [${reason}] — 候选集为空，触发 delay 初测`);
         await this._runDelayProbe();
         return;
       }
       if (this.dryRun) {
-        this._log(`[DRY-RUN] 当前节点异常，候选: ${nodes.length} 个`);
+        this._log(
+          `[DRY-RUN] 当前节点 ${node} 异常 [${reason}]，候选: ${nodes.length} 个`,
+        );
         return;
       }
 
+      this._log(`✗ 巡检异常 [${reason}]，开始从候选集切换 (当前 ${node})`);
       // 逐个切换候选 + 内容验证，第一个满足即采用
       let target = null;
       let h2 = null;
       for (const cand of nodes) {
         if (cand === node) continue;
-        this._log(`↺ 尝试候选: ${cand}`);
+        this._log(`↺ 尝试候选: ${cand} [原因: ${reason}]`);
         if (!(await checker.switchToNode(cand))) {
           this._log(`  ↺ ${cand} 切换失败，下一个`);
           continue;
@@ -201,19 +212,19 @@ export class ClashDaemon {
       if (!target) {
         // 全部候选不可用，恢复原节点
         await checker.switchToNode(node).catch(() => {});
-        this._log(`✗ ${reason} — 候选全部不可用，恢复原节点`);
+        this._log(`✗ 恢复原节点 ${node}（原因: ${reason} — 候选全部不可用）`);
         ipc.writeHealth({
           node,
           healthy: false,
           error: `${reason} — 候选全部不可用`,
-          lastSwitch: "failover: 候选全部不可用",
+          lastSwitch: `巡检恢复(${reason}): → ${node}`,
           meta: this._buildMeta(),
         });
         return;
       }
 
       this._log(
-        `⚠ ${node} → ${target} (${h2.timeTotal.toFixed(1)}s ${(h2.sizeDownload / 1024).toFixed(0)}KB)`,
+        `⚠ 节点切换 [巡检异常: ${reason}]: ${node} → ${target} (${h2.timeTotal.toFixed(1)}s ${(h2.sizeDownload / 1024).toFixed(0)}KB)`,
       );
       ipc.writeHealth({
         node: target,
@@ -222,7 +233,7 @@ export class ClashDaemon {
         timeTotal: h2.timeTotal,
         sizeDownload: h2.sizeDownload,
         title: h2.title,
-        lastSwitch: `${node} → ${target}`,
+        lastSwitch: `巡检异常(${reason}): ${node} → ${target}`,
         meta: this._buildMeta(),
       });
     } catch (e) {
@@ -323,12 +334,13 @@ export class ClashDaemon {
    * 看门狗指令: 主动故障切换（不依赖巡检发现，强制从候选集切下一个可用节点）
    * 用于业务进程连续报错（CDN限流/网络异常/封 IP 等）时换出口节点
    */
-  async _handleFailover() {
+  async _handleFailover(cmd) {
     try {
+      const reason = (cmd && cmd.reason) || "看门狗主动故障切换";
       const node = await api
         .getCurrentNode(checker.CONFIG.groupName)
         .catch(() => "?");
-      this._log(`🔄 看门狗指令: 触发故障切换 (当前: ${node})`);
+      this._log(`🔄 看门狗指令: 触发故障切换 [${reason}] (当前: ${node})`);
       const { nodes } = checker.loadHealthyList();
       if (!nodes.length) {
         this._log("🔄 候选集为空，触发 delay 初测");
@@ -354,16 +366,18 @@ export class ClashDaemon {
       }
       if (!target) {
         await checker.switchToNode(node).catch(() => {});
-        this._log(`✗ failover: 候选全部不可用，恢复原节点`);
+        this._log(
+          `✗ failover [${reason}] — 候选全部不可用，恢复原节点 ${node}`,
+        );
         return ipc.writeHealth({
           node,
           healthy: false,
-          error: "failover: 候选全部不可用",
-          lastSwitch: "failover: 候选全部不可用",
+          error: `failover(${reason}): 候选全部不可用`,
+          lastSwitch: `failover恢复(${reason}): → ${node}`,
           meta: this._buildMeta(),
         });
       }
-      this._log(`⚠ failover: ${node} → ${target}`);
+      this._log(`⚠ 节点切换 [${reason}]: ${node} → ${target}`);
       ipc.writeHealth({
         node: target,
         healthy: h2.healthy,
@@ -371,7 +385,7 @@ export class ClashDaemon {
         timeTotal: h2.timeTotal,
         sizeDownload: h2.sizeDownload,
         title: h2.title,
-        lastSwitch: `failover: ${node} → ${target}`,
+        lastSwitch: `${reason}: ${node} → ${target}`,
         meta: this._buildMeta(),
       });
     } catch (e) {
@@ -464,7 +478,7 @@ function _buildCmdHandlers(daemon) {
       }
     },
     switchNode: (cmd) => daemon._handleSwitchNode(cmd),
-    failover: () => daemon._handleFailover(),
+    failover: (cmd) => daemon._handleFailover(cmd),
   };
 }
 

package/src/cli/clash-daemon.js

@@ -1,7 +1,7 @@
 /**
  * clash-daemon CLI 命令入口
  *
- * 用法: tt-help clash-daemon [--interval 120] [--benchmark 40] [--country US] [--dry-run]
+ * 用法: tt-help clash-daemon [--interval 120] [--benchmark 10] [--country US] [--dry-run]
  */
 import { ClashDaemon } from "../clash/daemon.js";
 

package/src/cli/tag.js

@@ -6,7 +6,7 @@ import path from "path";
 import readline from "readline";
 import { fetchTagData, enrichVideosWithLocation } from "../lib/tag-fetcher.js";
 import { killEdgeProcesses, ensureBrowserReady } from "../lib/browser/cdp.js";
-import { getOrCreatePage } from "../lib/browser/page.js";
+import { getOrCreatePage, isBrowserClosedError } from "../lib/browser/page.js";
 import { TikTokScraper } from "../lib/tiktok-scraper.mjs";
 import {
   DEFAULT_TARGET_LOCATIONS,
@@ -48,6 +48,24 @@ function resolveTargetCountries(countries) {
   return countries || DEFAULT_SCORE_COUNTRIES;
 }
 
+/**
+ * 判断浏览器是否已断开（用户手动关窗口 / CDP 断开）。
+ * 用于让采集循环（score-all / refresh）在浏览器被关闭后自动退出，避免无限重试。
+ */
+function isBrowserDisconnected(browser, e) {
+  if (e && isBrowserClosedError(e)) return true;
+  try {
+    if (
+      browser &&
+      typeof browser.isConnected === "function" &&
+      !browser.isConnected()
+    ) {
+      return true;
+    }
+  } catch {}
+  return false;
+}
+
 function formatMemoryUsage(mem = process.memoryUsage()) {
   return `rss:${(mem.rss / 1024 / 1024).toFixed(0)}MB heap:${(mem.heapUsed / 1024 / 1024).toFixed(0)}MB ext:${(mem.external / 1024 / 1024).toFixed(0)}MB ab:${(mem.arrayBuffers / 1024 / 1024).toFixed(0)}MB`;
 }
@@ -1082,6 +1100,12 @@ export async function handleScoreAll(parsed) {
 
   try {
     while (true) {
+      // 检测浏览器窗口是否被手动关闭（CDP 断开）→ 自动退出
+      if (isBrowserDisconnected(browser)) {
+        log("🚪 检测到浏览器窗口已关闭，score-all 自动退出");
+        cleanup();
+        return;
+      }
       try {
         // 从服务端取下一个 new 标签（同时查剩余数量）
         const tagsRes = await fetch(
@@ -1300,6 +1324,12 @@ export async function handleScoreAll(parsed) {
         await maybeRecycleForMemory();
         await randomDelay(3000, 7000);
       } catch (e) {
+        // 浏览器窗口被手动关闭（CDP 断开）→ 自动退出，避免无限重试循环
+        if (isBrowserDisconnected(browser, e)) {
+          log(`🚪 浏览器窗口已关闭 (${e?.message || ""})，score-all 自动退出`);
+          cleanup();
+          return;
+        }
         // 区分网络错误和业务错误
         const isNetworkError =
           e.code === "ECONNREFUSED" ||
@@ -1767,6 +1797,12 @@ export async function handleTagRefresh(parsed) {
 
   try {
     while (true) {
+      // 检测浏览器窗口是否被手动关闭（CDP 断开）→ 自动退出
+      if (isBrowserDisconnected(browser)) {
+        log("🚪 检测到浏览器窗口已关闭，refresh 自动退出");
+        cleanup();
+        return;
+      }
       try {
         // 从服务端获取下一个 productive 标签
         const taskRes = await fetch(
@@ -1987,6 +2023,12 @@ export async function handleTagRefresh(parsed) {
         await maybeRecycleForMemory();
         await randomDelay(3000, 7000);
       } catch (e) {
+        // 浏览器窗口被手动关闭（CDP 断开）→ 自动退出，避免无限重试循环
+        if (isBrowserDisconnected(browser, e)) {
+          log(`🚪 浏览器窗口已关闭 (${e?.message || ""})，refresh 自动退出`);
+          cleanup();
+          return;
+        }
         const isNetworkError =
           e.code === "ECONNREFUSED" ||
           e.code === "ENOTFOUND" ||

package/src/lib/args.js

@@ -665,7 +665,7 @@ function parseWatchdogArgs(args) {
 
 function parseClashDaemonArgs(args) {
   let interval = 120;
-  let benchmark = 40;
+  let benchmark = 10;
   let dryRun = false;
   let country = null;
 
@@ -674,7 +674,7 @@ function parseClashDaemonArgs(args) {
     if (arg === "--interval") {
       interval = parseInt(args[++i]) || 120;
     } else if (arg === "--benchmark") {
-      benchmark = parseInt(args[++i]) || 40;
+      benchmark = parseInt(args[++i]) || 10;
     } else if (arg === "--country") {
       country = args[++i] || null;
     } else if (arg === "--dry-run") {

package/src/lib/constants.js

@@ -393,7 +393,7 @@ const HELP_TEXT = [
   "    看门狗启动时会自动拉起此守护进程",
   "    选项:",
   "      --interval <秒>          巡检间隔，默认 120 秒（2分钟）",
-  "      --benchmark <分钟>       候选集 delay 初测间隔，默认 40 分钟",
+  "      --benchmark <分钟>       候选集 delay 初测间隔，默认 10 分钟",
   "      --country <国家代码>     只保留指定国家节点，默认不过滤",
   "                               支持: US, GB, DE, FR, JP, KR, SG, HK, TW, RU 等",
   "      --dry-run                只检测不切换（调试用）",

package/src/watch/watchdog-server.js

@@ -330,11 +330,17 @@ async function handleHeartbeat(params, body, res) {
   const userId = (body.config && body.config.userId) || "";
   const commands = getClientCommands(userId);
 
-  // 幂等下发节点国家配置（默认 US；配置变化时才入队，daemon 端相同则忽略）
+  // 幂等下发节点国家配置（默认 US）
+  // 幂等基准 = 客户端 daemon 实际生效国家（body.clashHealth.meta.countryFilter），而非"是否下发过"。
+  // 否则 daemon 重启（崩溃自愈/升级/机器重启）回退到 --country US 后，服务端会因"配置没变"而不补发，
+  // 导致实际一直用美国节点（生效与配置不一致）。
   const countries = getClientCountries(userId);
   const countryKey = JSON.stringify(countries);
+  const activeKey = JSON.stringify(
+    body.clashHealth?.meta?.countryFilter || null,
+  );
   const pending = clashCmdQueue.get(userId) || [];
-  if (countryKey !== lastSentCountries.get(userId)) {
+  if (countryKey !== activeKey) {
     pending.push({ action: "setCountryFilter", countries });
     lastSentCountries.set(userId, countryKey);
   }

package/src/watchdog/agent.js

@@ -16,14 +16,14 @@ import {
 import { ProcessManager } from "./process-manager.js";
 import {
   getVersion,
-  performUpgrade,
+  spawnUpgraderAndWait,
   isGlobalInstall,
   startUpgradeChecker,
 } from "./upgrader.js";
-import { writeFileSync, existsSync, readFileSync, openSync } from "fs";
+import { writeFileSync, existsSync, readFileSync } from "fs";
 import { spawn } from "child_process";
 import { join, dirname } from "path";
-import { homedir, tmpdir } from "os";
+import { homedir } from "os";
 import { fileURLToPath } from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -195,6 +195,7 @@ export class WatchdogAgent {
     this._errorTriggerCount = ERROR_TRIGGER_COUNT;
     this._errorTriggerMinMs = ERROR_MIN_MS;
     this._errorTriggerBreakMs = ERROR_BREAK_MS;
+    this._lastErrorTriggerKey = null; // 上次配置指纹（幂等打印用）
   }
 
   /**
@@ -303,6 +304,10 @@ export class WatchdogAgent {
       this._errorTriggerMinMs = cfg.minMinutes * 60 * 1000;
     if (cfg?.breakSeconds > 0)
       this._errorTriggerBreakMs = cfg.breakSeconds * 1000;
+    // 幂等打印：参数没变化就不刷屏（心跳每次都会带 errorTrigger，此前会每次心跳都打一条）
+    const key = `${this._errorTriggerEnabled}|${this._errorTriggerCount}|${this._errorTriggerMinMs}|${this._errorTriggerBreakMs}`;
+    if (key === this._lastErrorTriggerKey) return;
+    this._lastErrorTriggerKey = key;
     console.error(
       `[watchdog] 错误触发切换: ${this._errorTriggerEnabled ? "已启用" : "已禁用"} (连续${this._errorTriggerCount}次 / 持续${this._errorTriggerMinMs / 60000}min / 中断${this._errorTriggerBreakMs / 1000}s)`,
     );
@@ -323,6 +328,7 @@ export class WatchdogAgent {
         firstErrorAt: 0,
         lastErrorAt: 0,
       };
+      const hadNew = newErrors.length > 0;
       for (const line of newErrors) {
         // 错误间隔超阈值 → 连续中断，重新计数
         if (
@@ -349,6 +355,15 @@ export class WatchdogAgent {
         }
       }
       this._errorStates.set(cmdId, st);
+      // 动态进度：仅本轮扫描到新增错误时打印（扫描间隔 30s，天然低频不刷屏）
+      if (hadNew && st.consecutive > 0 && st.firstErrorAt) {
+        const durMs = now - st.firstErrorAt;
+        const durMin = Math.floor(durMs / 60000);
+        const durSec = Math.floor((durMs % 60000) / 1000);
+        console.error(
+          `[watchdog] 错误累计: ${cmdId} 连续 ${st.consecutive} 次 / 已持续 ${durMin}min${durSec}s (阈值: 连续${this._errorTriggerCount}次/持续${this._errorTriggerMinMs / 60000}min)`,
+        );
+      }
     }
     // 无新错误的进程：长时间无错误则重置连续计数
     for (const [cmdId, st] of this._errorStates) {
@@ -367,7 +382,10 @@ export class WatchdogAgent {
   async _triggerFailover(cmdId) {
     try {
       const ipc = await import("../clash/ipc.js");
-      ipc.writeCommand({ action: "failover" });
+      ipc.writeCommand({
+        action: "failover",
+        reason: `业务进程${cmdId ? ` ${cmdId}` : ""} 连续错误触发`,
+      });
       console.error(`[watchdog] 已下发 failover 命令 (触发源: ${cmdId})`);
     } catch (e) {
       console.error(`[watchdog] 下发 failover 失败: ${e.message}`);
@@ -556,32 +574,39 @@ export class WatchdogAgent {
 
     this.upgradeChecker = startUpgradeChecker({
       onUpdateAvailable: async ({ current, latest }) => {
-        console.error(`[upgrade] ${current} → ${latest}`);
-        // 升级流程：先标记 daemon 主动关闭（避免 kill 后被崩溃自愈重新拉起旧版），再停业务与 daemon
-        this._daemonStopping = true;
-        this.processManager.stopAll();
-        this._killClashDaemon();
-
-        const result = await performUpgrade();
-        if (result.success) {
-          this.ttHelpVersion = latest;
+        // 简化升级：spawn 独立升级器下载，下载期间业务/心跳完全不受影响；
+        // 下载成功后才停业务并退出，由新版接管（避免"边停边起"与二次 taskkill 竞态）
+        console.error(
+          `[upgrade] ${current} → ${latest}，启动升级程序（下载期间业务不受影响）`,
+        );
+        const outcome = await spawnUpgraderAndWait(this._buildRestartParams());
+        if (outcome !== "ok") {
           console.error(
-            `[upgrade] 升级成功 (${latest})，重启 watchdog 使新版 clash daemon 生效`,
+            `[upgrade] 升级未完成（${outcome === "fail" ? "下载失败" : "升级程序无响应"}），保持当前版本运行`,
           );
-          // 重启自身进程加载新代码（内部 daemon 路径优先），新进程会拉起新版 daemon
-          this._restartSelf();
           return;
         }
-        // 升级失败：恢复 daemon 与业务，保持当前进程运行
         console.error(
-          `[upgrade] 失败: ${result.output.substring(0, 200)}，恢复运行`,
+          `[upgrade] 新版本已下载，停止业务与 daemon 后退出，新版将接管`,
         );
-        this._recoverAfterFailedUpgrade();
-        await this._sendHeartbeat();
+        await this.stop();
+        process.exit(0);
       },
     });
   }
 
+  /** 构建新版 watchdog 重启所需参数（透传给独立升级器） */
+  _buildRestartParams() {
+    return {
+      serverUrl: this.serverUrl,
+      clientId: this.clientId,
+      intervalSec: Math.max(5, Math.round(this.intervalMs / 1000)),
+      spawnDaemon: this.spawnDaemon,
+      interactive: !!process.stdout.isTTY,
+      oldPid: process.pid,
+    };
+  }
+
   /**
    * 启动 clash daemon 子进程
    * daemon 负责代理节点健康巡检和故障切换，watchdog 不阻塞等待
@@ -597,12 +622,23 @@ export class WatchdogAgent {
     }
 
     console.error(`[watchdog] 启动代理守护: ${daemonPath}`);
+    // 上次生效的国家优先（从 daemon 写入的 clash-health.json 读取），避免重启回退到硬编码 US
+    // 服务端心跳会按"实际生效 vs 配置"收敛，这里作为下发前窗口/服务端不可达时的兜底
+    let countryArg = "US";
     try {
-      const child = spawn(process.execPath, [daemonPath, "--country", "US"], {
-        stdio: ["ignore", "pipe", "pipe"],
-        detached: false,
-        windowsHide: true, // Windows 隐藏控制台窗口
-      });
+      const prev = getClashHealth()?.meta?.countryFilter;
+      if (Array.isArray(prev) && prev.length) countryArg = prev.join(",");
+    } catch {}
+    try {
+      const child = spawn(
+        process.execPath,
+        [daemonPath, "--country", countryArg],
+        {
+          stdio: ["ignore", "pipe", "pipe"],
+          detached: false,
+          windowsHide: true, // Windows 隐藏控制台窗口
+        },
+      );
 
       child.stdout?.on("data", (d) => {
         // daemon 日志通过 stderr 输出，stdout 静默
@@ -695,110 +731,6 @@ export class WatchdogAgent {
     this.clashDaemon = null;
   }
 
-  /**
-   * 升级后重启自身进程（加载新代码）
-   * 用 cli.js watchdog 子进程替换当前进程，保证新版本内部 daemon 路径逻辑生效。
-   * 带存活确认与兜底：新进程确认存活后才退出旧进程；启动失败则回退保持旧进程运行。
-   */
-  _restartSelf() {
-    const cliPath = join(__dirname, "..", "..", "cli.js");
-    const args = ["watchdog"];
-    if (this.serverUrl) args.push("--server", this.serverUrl);
-    if (this.clientId) args.push("--client-id", this.clientId);
-    if (!this.spawnDaemon) args.push("--no-daemon");
-    args.push(
-      "--interval",
-      String(Math.max(5, Math.round(this.intervalMs / 1000))),
-    );
-
-    // 交互式终端（用户在 cmd 窗口里手动跑 tt-help watchdog）：
-    // 升级重启后接管原控制台窗口继续显示（stdio inherit + 不 detached），窗口不消失
-    const interactive = !!process.stdout.isTTY;
-
-    // 非交互（计划任务/脚本/无人值守）时，新进程日志重定向到文件，崩溃有据可查
-    let logFd = undefined;
-    try {
-      const logPath = join(
-        tmpdir(),
-        `tt-help-watchdog-restart-${Date.now()}.log`,
-      );
-      logFd = openSync(logPath, "a");
-      console.error(`[upgrade] 新进程日志: ${logPath}`);
-    } catch {}
-    const out = logFd ?? "ignore";
-
-    let child;
-    try {
-      child = spawn(process.execPath, [cliPath, ...args], {
-        // 交互式：继承原 cmd 窗口一直显示；非交互：后台运行 + 日志文件
-        detached: !interactive,
-        stdio: interactive ? "inherit" : ["ignore", out, out],
-        windowsHide: !interactive, // 交互时不隐藏，保留可见窗口
-      });
-    } catch (e) {
-      console.error(`[upgrade] 重启自身失败: ${e.message}，保持旧进程运行`);
-      this._recoverAfterFailedUpgrade();
-      return;
-    }
-    // 非交互后台进程独立存活（父进程退出不影响）；交互式继承窗口无需 unref
-    if (!interactive) child.unref();
-
-    // 存活确认：轮询新进程是否正常存活，确认后才退出旧进程
-    let exited = false;
-    let exitCode = null;
-    let exitSignal = null;
-    child.once("exit", (c, s) => {
-      exited = true;
-      exitCode = c;
-      exitSignal = s;
-    });
-
-    console.error(
-      `[upgrade] 新版 watchdog 已启动 (pid=${child.pid})，等待存活确认...`,
-    );
-    let attempts = 0;
-    const confirm = () => {
-      attempts++;
-      if (exited) {
-        console.error(
-          `[upgrade] 新版 watchdog 启动后即退出 (code=${exitCode}, signal=${exitSignal})，回退保持旧进程`,
-        );
-        this._recoverAfterFailedUpgrade();
-        return;
-      }
-      try {
-        process.kill(child.pid, 0); // 抛错说明进程已不存在
-      } catch {
-        console.error(
-          `[upgrade] 新版 watchdog 进程不存在 (pid=${child.pid})，回退保持旧进程`,
-        );
-        this._recoverAfterFailedUpgrade();
-        return;
-      }
-      if (attempts >= 6) {
-        console.error(`[upgrade] 新版 watchdog 存活确认，旧进程退出`);
-        this.stop();
-        setTimeout(() => process.exit(0), 500);
-        return;
-      }
-      setTimeout(confirm, 1000);
-    };
-    setTimeout(confirm, 1000);
-  }
-
-  /**
-   * 升级/重启失败后的回退恢复：重新拉起 daemon 并同步业务进程
-   */
-  _recoverAfterFailedUpgrade() {
-    this._daemonStopping = false;
-    if (this.spawnDaemon && !this.clashDaemon) {
-      console.error(`[upgrade] 恢复 clash daemon...`);
-      this._spawnClashDaemon();
-    }
-    console.error(`[upgrade] 恢复业务进程（等待心跳同步命令）...`);
-    this._sendHeartbeat().catch(() => {});
-  }
-
   /**
    * 信号处理
    */

package/src/watchdog/llm-analyzer.js

@@ -15,18 +15,34 @@ export async function analyzeProcessLogs(processLogs, llmFetch) {
   const results = [];
   for (const proc of processLogs) {
     try {
-      console.error(`[llm-analyzer] 分析 ${proc.cmdId.substring(0, 40)}... (${proc.logs.length} 行日志)`);
+      console.error(
+        `[llm-analyzer] 分析 ${proc.cmdId.substring(0, 40)}... (${proc.logs.length} 行日志)`,
+      );
       const content = await llmFetch({
-        messages: [{ role: "user", content: buildPrompt(proc.cmdId, proc.logs.slice(-200).join("\n"), proc.uptimeSeconds, proc.restartCount) }],
+        messages: [
+          {
+            role: "user",
+            content: buildPrompt(
+              proc.cmdId,
+              proc.logs.slice(-200).join("\n"),
+              proc.uptimeSeconds,
+              proc.restartCount,
+            ),
+          },
+        ],
         max_tokens: 256,
         temperature: 0.1,
         enable_thinking: false,
       });
       const parsed = parseResponse(content);
-      console.error(`[llm-analyzer] ${proc.cmdId.substring(0, 30)} → ${parsed.severity}: ${parsed.summary}`);
+      console.error(
+        `[llm-analyzer] ${proc.cmdId.substring(0, 30)} → ${parsed.severity}: ${parsed.summary}`,
+      );
       results.push({ cmdId: proc.cmdId, ...parsed });
     } catch (e) {
-      console.error(`[llm-analyzer] ${proc.cmdId.substring(0, 30)} 失败: ${e.message}`);
+      console.error(
+        `[llm-analyzer] ${proc.cmdId.substring(0, 30)} 失败: ${e.message}`,
+      );
     }
   }
   return results;
@@ -39,21 +55,32 @@ async function createStandaloneFetch() {
     const { existsSync, readFileSync } = await import("fs");
     const { join } = await import("path");
     const { homedir } = await import("os");
-    const homeDir = homedir() || process.env.HOME || process.env.USERPROFILE || "";
+    const homeDir =
+      homedir() || process.env.HOME || process.env.USERPROFILE || "";
     let fileCfg = {};
     try {
       const cfgPath = join(homeDir, ".tt-help.json");
-      if (existsSync(cfgPath)) fileCfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
+      if (existsSync(cfgPath))
+        fileCfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
     } catch {}
-    const url = process.env.LLM_URL || fileCfg.llmUrl || "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions";
+    const url =
+      process.env.LLM_URL ||
+      fileCfg.llmUrl ||
+      "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions";
     const apiKey = process.env.LLM_API_KEY || fileCfg.llmApiKey || "";
     const model = process.env.LLM_MODEL || fileCfg.llmModel || "auto";
-    if (!apiKey) { console.error("[llm-analyzer] 未配置 LLM_API_KEY"); return null; }
+    if (!apiKey) {
+      console.error("[llm-analyzer] 未配置 LLM_API_KEY");
+      return null;
+    }
     console.error(`[llm-analyzer] 客户端模式: ${model} @ ${url}`);
     return async ({ messages, max_tokens = 256, temperature = 0.1 }) => {
       const resp = await fetch(url, {
         method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
         body: JSON.stringify({ model, messages, max_tokens, temperature }),
         signal: AbortSignal.timeout(30000),
       });
@@ -72,9 +99,17 @@ async function createStandaloneFetch() {
 // ── Prompt ──
 
 function buildPrompt(cmdId, logs, uptimeSeconds, restartCount) {
-  const uptime = uptimeSeconds >= 3600
-    ? Math.round(uptimeSeconds / 3600) + "h"
-    : uptimeSeconds + "s";
+  const uptime =
+    uptimeSeconds >= 3600
+      ? Math.round(uptimeSeconds / 3600) + "h"
+      : uptimeSeconds + "s";
+  const logText = logs || "(无日志)";
+  // 统计错误码 209002（TikTok 验证码/风控）出现次数，写入 prompt 避免 LLM 误判为故障
+  const captchaCount = logText.split("209002").length - 1;
+  const captchaNote =
+    captchaCount > 0
+      ? `\n背景: 日志中出现 ${captchaCount} 处错误码 209002（TikTok 验证码/风控，正常现象，程序会自动重试），判断时请忽略它们，不要当作 error，也不要在建议里写"账号被封禁/更换账号/更换IP"。`
+      : "";
   return `你是 TikTok 数据采集工具的运维助手。以下是进程 "${cmdId}" 的最近 10 分钟日志，请分析是否有异常。
 
 进程信息:
@@ -83,15 +118,16 @@ function buildPrompt(cmdId, logs, uptimeSeconds, restartCount) {
 - 历史重启: ${restartCount} 次
 
 最近日志:
-${logs || "(无日志)"}
+${logText}${captchaNote}
 
 请返回 JSON（仅 JSON，无其他内容）:
 {"severity":"ok"|"warn"|"error","summary":"一句话中文总结，不超过 50 字","suggestions":["建议1","建议2"]}
 
 判断标准:
 - ok: 无异常，正常运行
-- warn: 有偶发错误（验证码、403、超时 < 3次）或内存偏高
-- error: 严重错误（连续崩溃、登录失效、端口占用、大量 403）
+- warn: 有偶发错误（403、超时 < 3次）或内存偏高
+- error: 严重错误（连续崩溃、登录失效、端口占用、大量 403/超时）
+- 重要: 错误码 209002 = 验证码/风控，是正常限流，不是故障，不算 error；只有真正的登录失效/崩溃/端口占用才算 error
 - 每个 suggestions 是简洁可操作的建议，不超过 3 条`;
 }
 
@@ -100,15 +136,31 @@ ${logs || "(无日志)"}
 function parseResponse(content) {
   try {
     const parsed = JSON.parse(content);
-    return { severity: parsed.severity || "ok", summary: parsed.summary || "", suggestions: Array.isArray(parsed.suggestions) ? parsed.suggestions.slice(0, 3) : [] };
+    return {
+      severity: parsed.severity || "ok",
+      summary: parsed.summary || "",
+      suggestions: Array.isArray(parsed.suggestions)
+        ? parsed.suggestions.slice(0, 3)
+        : [],
+    };
   } catch {
     const match = content.match(/\{[\s\S]*\}/);
     if (match) {
       try {
         const parsed = JSON.parse(match[0]);
-        return { severity: parsed.severity || "ok", summary: parsed.summary || "", suggestions: Array.isArray(parsed.suggestions) ? parsed.suggestions.slice(0, 3) : [] };
+        return {
+          severity: parsed.severity || "ok",
+          summary: parsed.summary || "",
+          suggestions: Array.isArray(parsed.suggestions)
+            ? parsed.suggestions.slice(0, 3)
+            : [],
+        };
       } catch {}
     }
-    return { severity: "warn", summary: content.substring(0, 100), suggestions: [] };
+    return {
+      severity: "warn",
+      summary: content.substring(0, 100),
+      suggestions: [],
+    };
   }
 }

package/src/watchdog/upgrader.js

@@ -5,11 +5,11 @@
  * 发现新版本 → 回调通知 agent → agent 负责停进程 → 升级 → 重启。
  */
 
-import { exec } from "child_process";
-import { readFileSync } from "fs";
+import { exec, spawn } from "child_process";
+import { readFileSync, writeFileSync, unlinkSync, openSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
-import { homedir } from "os";
+import { homedir, tmpdir } from "os";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_PATH = join(__dirname, "..", "..", "package.json");
@@ -156,3 +156,199 @@ export function startUpgradeChecker({
     },
   };
 }
+
+// ══════════════════════════════════════════════
+// 独立升级器（直接运行模式）
+// ══════════════════════════════════════════════
+//
+// 设计目标：让升级变得简单、无竞态。
+//   旧 watchdog 检测到新版 → spawn 独立升级器（detached）→ 旧 watchdog 继续正常运行（业务不断）
+//   升级器：npm install → 写结果文件 → 等旧 watchdog 退出 → spawn 新版 watchdog → 自身退出
+//   旧 watchdog 看到结果 ok → 停心跳/停业务/停 daemon → 退出，由新版接管。
+//
+// 结果文件：tmpdir/tt-help-upgrade-result.json
+//  - 由升级器写入 { status: "ok" | "fail", error?, at }，旧 watchdog 轮询读取
+//
+// 用法（旧 watchdog 调用）：
+//   node upgrader.js --upgrade --old-pid <pid> [--interactive] [--server ...] [--client-id ...] [--interval ...] [--no-daemon]
+
+const UPGRADE_RESULT_FILE = join(tmpdir(), "tt-help-upgrade-result.json");
+
+function writeUpgradeResult(state) {
+  try {
+    writeFileSync(
+      UPGRADE_RESULT_FILE,
+      JSON.stringify({ ...state, at: Date.now() }, null, 2),
+      "utf-8",
+    );
+  } catch {}
+}
+
+/** 轮询等待指定 pid 退出，返回是否已退出（超时返回 false） */
+async function waitProcessExit(
+  pid,
+  { timeoutMs = 60_000, pollMs = 1000 } = {},
+) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      process.kill(pid, 0); // 存在则继续等
+    } catch {
+      return true; // 已退出
+    }
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  return false;
+}
+
+/**
+ * 独立升级器主流程（由旧 watchdog 以子进程方式启动）
+ * @param {string[]} argv - process.argv.slice(2)
+ */
+export async function runUpgradeMode(argv) {
+  const get = (f) => (argv.includes(f) ? argv[argv.indexOf(f) + 1] : undefined);
+  const oldPid = parseInt(get("--old-pid"), 10) || 0;
+  const interactive = argv.includes("--interactive");
+  const serverUrl = get("--server");
+  const clientId = get("--client-id");
+  const intervalSec = parseInt(get("--interval"), 10) || 15;
+  const noDaemon = argv.includes("--no-daemon");
+
+  console.error(
+    `[upgrade-proc] 开始下载新版: npm install -g ${PACKAGE}@latest ...`,
+  );
+  const result = await performUpgrade();
+  if (!result.success) {
+    const err = result.output.substring(0, 300);
+    console.error(`[upgrade-proc] 下载失败: ${err}`);
+    writeUpgradeResult({ status: "fail", error: err });
+    process.exit(1);
+  }
+  console.error(`[upgrade-proc] 下载完成，通知旧 watchdog 退出`);
+  writeUpgradeResult({ status: "ok" });
+
+  // 等旧 watchdog 退出，避免与其 stopAll 竞态（它退出后才会让新版接管业务）
+  if (oldPid) {
+    const exited = await waitProcessExit(oldPid);
+    if (!exited) {
+      console.error(
+        `[upgrade-proc] 等待旧 watchdog(pid=${oldPid}) 退出超时，继续启动新版`,
+      );
+    }
+  }
+
+  // 启动新版 watchdog（interactive 时继承控制台接管窗口；否则后台 + 日志文件）
+  const cliPath = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "cli.js",
+  );
+  const args = ["watchdog"];
+  if (serverUrl) args.push("--server", serverUrl);
+  if (clientId) args.push("--client-id", clientId);
+  args.push("--interval", String(intervalSec));
+  if (noDaemon) args.push("--no-daemon");
+
+  let logFd = undefined;
+  try {
+    const logPath = join(tmpdir(), `tt-help-watchdog-${Date.now()}.log`);
+    logFd = openSync(logPath, "a");
+    console.error(`[upgrade-proc] 新版 watchdog 日志: ${logPath}`);
+  } catch {}
+
+  let child;
+  try {
+    child = spawn(process.execPath, [cliPath, ...args], {
+      detached: !interactive,
+      stdio: interactive
+        ? "inherit"
+        : ["ignore", logFd || "ignore", logFd || "ignore"],
+      windowsHide: !interactive,
+    });
+    if (!interactive) child.unref();
+  } catch (e) {
+    console.error(`[upgrade-proc] 新版 watchdog 启动失败: ${e.message}`);
+    process.exit(1);
+  }
+  console.error(`[upgrade-proc] 新版 watchdog 已启动 (pid=${child.pid})`);
+  process.exit(0);
+}
+
+/**
+ * 旧 watchdog 调用：spawn 独立升级器并轮询结果文件
+ * @returns {Promise<"ok"|"fail"|"timeout">}
+ */
+export function spawnUpgraderAndWait({
+  serverUrl,
+  clientId,
+  intervalSec = 15,
+  spawnDaemon = true,
+  interactive = false,
+  oldPid = 0,
+  timeoutMs = 180_000,
+} = {}) {
+  return new Promise((resolve) => {
+    // 清理上次结果
+    try {
+      unlinkSync(UPGRADE_RESULT_FILE);
+    } catch {}
+
+    const upgraderPath = fileURLToPath(import.meta.url);
+    const args = ["--upgrade", "--old-pid", String(oldPid || process.pid)];
+    if (serverUrl) args.push("--server", serverUrl);
+    if (clientId) args.push("--client-id", clientId);
+    args.push("--interval", String(intervalSec));
+    if (!spawnDaemon) args.push("--no-daemon");
+    if (interactive) args.push("--interactive");
+
+    let child;
+    try {
+      child = spawn(process.execPath, [upgraderPath, ...args], {
+        // 交互：升级器接管控制台（后续新版 watchdog 也继承窗口）；非交互：后台 + 日志
+        detached: !interactive,
+        stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"],
+        windowsHide: !interactive,
+      });
+      if (!interactive) child.unref();
+    } catch (e) {
+      console.error(`[watchdog] 升级程序启动失败: ${e.message}`);
+      resolve("fail");
+      return;
+    }
+    child.stderr?.on("data", (d) => {
+      const m = d.toString().trim();
+      if (m) console.error(`[upgrade-proc] ${m.substring(0, 200)}`);
+    });
+
+    const started = Date.now();
+    const timer = setInterval(() => {
+      try {
+        const data = JSON.parse(readFileSync(UPGRADE_RESULT_FILE, "utf-8"));
+        if (data && data.status) {
+          clearInterval(timer);
+          resolve(data.status === "ok" ? "ok" : "fail");
+        }
+      } catch {}
+      if (Date.now() - started > timeoutMs) {
+        clearInterval(timer);
+        try {
+          unlinkSync(UPGRADE_RESULT_FILE);
+        } catch {}
+        console.error(
+          `[watchdog] 升级程序 ${timeoutMs / 1000}s 无结果，放弃等待`,
+        );
+        resolve("timeout");
+      }
+    }, 2000);
+  });
+}
+
+// 直接运行时自动进入独立升级器模式
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  runUpgradeMode(process.argv.slice(2)).catch((e) => {
+    console.error(`[upgrade-proc] 升级器异常: ${e.message}`);
+    writeUpgradeResult({ status: "fail", error: e.message });
+    process.exit(1);
+  });
+}

package/src/webserver/server.mjs

@@ -86,6 +86,9 @@ let scraperInitPromise = null;
 let restartPromise = null; // 防重入：同一时间只允许一个 restartScraper
 let consecutiveErrors = 0;
 const MAX_CONSECUTIVE_ERRORS = 10;
+// TikTok 明确返回的状态码中可重试的（验证码/风控 209002）；
+// 其余明确状态码（10202 被封、10221 不存在等）虽不可重试，同样属于业务结果而非 webserver 故障
+const TIKTOK_RETRYABLE_NORMAL_CODES = new Set([209002]);
 let warmTimer = null;
 let lastWarmTime = 0;
 let healthTimer = null; // 每 10 分钟健康心跳日志（始终输出，防假死检测误判重启）
@@ -252,15 +255,29 @@ async function handleTiktokUser(req, res) {
     });
   }
 
+  if (result.error && result.statusCode) {
+    // TikTok 明确返回的状态码（209002 验证码、10202 被封、10221 不存在等）：
+    // 属业务结果而非 webserver 故障，不计入连续错误、不触发 scraper 重启
+    const retryable = TIKTOK_RETRYABLE_NORMAL_CODES.has(result.statusCode);
+    apiLog(
+      `[webserver] user business | ${clientIP} | @${body.uniqueId} | ${elapsed}ms | statusCode=${result.statusCode}${retryable ? " (可重试)" : ""}`,
+    );
+    recordRequest(true);
+    return sendJSON(res, 503, {
+      error: `TikTok statusCode=${result.statusCode}`,
+      retryable,
+      tiktokStatusCode: result.statusCode,
+    });
+  }
   if (result.error) {
+    // 无明确状态码但 error（解析/结构异常）→ 才算 webserver 故障
     console.error(
-      `[webserver] user FAIL | ${clientIP} | @${body.uniqueId} | ${elapsed}ms | TikTok statusCode=${result.statusCode}`,
+      `[webserver] user FAIL | ${clientIP} | @${body.uniqueId} | ${elapsed}ms | parse error (无明确 statusCode)`,
     );
     recordRequest(false);
     return sendJSON(res, 502, {
-      error: `TikTok error (statusCode=${result.statusCode})`,
+      error: "TikTok error (无明确 statusCode)",
       retryable: false,
-      tiktokStatusCode: result.statusCode,
     });
   }