tt-help-cli-ycl 1.4.128 → 1.4.131

package/package.json

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

package/scripts/test-daemon-failover.mjs

@@ -0,0 +1,197 @@
+/**
+ * daemon _handleFailover 三级响应单测（2026-08-22，无需 Clash 运行）
+ *
+ * 验证：
+ *   - 探针健康 → 窗口内 failover 仅检查不切换（前 N-1 次）
+ *   - 探针不健康 → 立即切换（无视窗口）
+ *   - 壳页 → 视为链路正常，仅检查不切换（与巡检口径一致）
+ *   - 窗口过期 → 计数重置
+ *   - 窗口内到达 failoverEscapeAfter 次 → 按业务级封禁轮换一次
+ *   - 实际切换后 → 窗口与计数重置
+ *   - escapeAfter 可配置
+ *   - 候选集为空 → 触发 delay 初测且不切换
+ *
+ * 运行: node --test scripts/test-daemon-failover.mjs
+ *      （若当前 Node 版本 module mock 仍需 flag: --experimental-test-module-mocks）
+ */
+import { test, mock, before } from "node:test";
+import assert from "node:assert/strict";
+
+// ── 可配置假依赖状态 ──
+const state = {
+  health: {
+    healthy: true,
+    httpCode: 200,
+    timeTotal: 1.2,
+    sizeDownload: 100000,
+    numRedirects: 0,
+    title: "TikTok - Make Your Day",
+    error: null,
+  },
+  nodes: ["🇭🇰 香港01", "🇲🇾 马来02"],
+  currentNode: "🇭🇰 香港01",
+  switches: [],
+  closes: 0,
+};
+
+function resetState() {
+  state.health = {
+    healthy: true,
+    httpCode: 200,
+    timeTotal: 1.2,
+    sizeDownload: 100000,
+    numRedirects: 0,
+    title: "TikTok - Make Your Day",
+    error: null,
+  };
+  state.nodes = ["🇭🇰 香港01", "🇲🇾 马来02"];
+  state.currentNode = "🇭🇰 香港01";
+  state.switches = [];
+  state.closes = 0;
+}
+
+// ── 注册模块 mock（必须在 import daemon.js 之前） ──
+before(async () => {
+  mock.module("../src/clash/checker.js", {
+    namedExports: {
+      normalizeCountries: (v) => (Array.isArray(v) ? [...v] : v ? [v] : []),
+      CONFIG: {
+        groupName: "GLOBAL",
+        testUrl: "https://www.tiktok.com/explore",
+        proxyUrl: "http://127.0.0.1:7897",
+        nodeCountryFilter: null,
+      },
+      checkNodeHealth: () => ({ ...state.health }),
+      loadHealthyList: () => ({ nodes: [...state.nodes] }),
+      switchToNode: async (n) => {
+        state.switches.push(n);
+        state.currentNode = n;
+        // 模拟真实世界：故障属于原节点，切换后的新节点健康（候选内容验证通过）
+        state.health = { ...state.health, healthy: true, error: null };
+        return true;
+      },
+      applyDiscovered: () => {},
+      runDelayProbe: async () => ({
+        nodes: [...state.nodes],
+        total: state.nodes.length,
+      }),
+      saveHealthyList: () => {},
+    },
+  });
+  mock.module("../src/clash/api.js", {
+    namedExports: {
+      configure: () => {},
+      getCurrentNode: async () => state.currentNode,
+      closeAllConnections: async () => {
+        state.closes += 1;
+      },
+    },
+  });
+  mock.module("../src/clash/ipc.js", {
+    namedExports: {
+      writeHealth: () => {},
+      listCommandChannels: () => [],
+      readCommand: () => null,
+      clearCommand: () => {},
+    },
+  });
+  mock.module("../src/clash/discover.js", {
+    namedExports: {
+      discoverAll: async () => [],
+      invalidateDiscoverCache: () => {},
+    },
+  });
+  ({ ClashDaemon } = await import("../src/clash/daemon.js"));
+});
+
+let ClashDaemon = null;
+
+function makeCtx(opts = {}) {
+  const d = new ClashDaemon({
+    failoverCooldownMs: 600000,
+    failoverEscapeAfter: 3,
+    ...opts,
+  });
+  const c = { proxyPort: 7897 };
+  return { d, c };
+}
+
+test("F1 探针健康：前 2 次 failover 仅检查不切换，第 3 次轮换", async () => {
+  resetState();
+  const { d, c } = makeCtx();
+  await d._handleFailover({ reason: "F1-1" }, c);
+  await d._handleFailover({ reason: "F1-2" }, c);
+  assert.equal(state.switches.length, 0, "前 2 次不应切换");
+  assert.equal(state.closes, 0, "前 2 次不应断开连接");
+  await d._handleFailover({ reason: "F1-3" }, c);
+  assert.deepEqual(state.switches, ["🇲🇾 马来02"], "第 3 次按轮换切换到候选");
+  assert.equal(state.closes, 1, "切换后应断开旧连接");
+});
+
+test("F2 探针不健康：立即切换（无视窗口）", async () => {
+  resetState();
+  const { d, c } = makeCtx();
+  state.health = { ...state.health, healthy: false, error: "timeout" };
+  await d._handleFailover({ reason: "F2" }, c);
+  assert.deepEqual(state.switches, ["🇲🇾 马来02"], "不健康应立即切换");
+});
+
+test("F3 壳页视为链路正常：仅检查不切换", async () => {
+  resetState();
+  const { d, c } = makeCtx();
+  // 壳页签名：200 + 无跳转 + 无 error + 无 title
+  state.health = {
+    healthy: false,
+    httpCode: 200,
+    timeTotal: 1.0,
+    sizeDownload: 43000,
+    numRedirects: 0,
+    title: "",
+    error: null,
+  };
+  await d._handleFailover({ reason: "F3" }, c);
+  assert.equal(state.switches.length, 0, "壳页不应触发切换");
+});
+
+test("F4 窗口过期：计数重置，不累计到逃生阈值", async () => {
+  resetState();
+  const { d, c } = makeCtx({ failoverCooldownMs: 150 });
+  await d._handleFailover({ reason: "F4-1" }, c); // count=1
+  await new Promise((r) => setTimeout(r, 200)); // 窗口过期
+  await d._handleFailover({ reason: "F4-2" }, c); // 重置后 count=1
+  await d._handleFailover({ reason: "F4-3" }, c); // count=2
+  assert.equal(state.switches.length, 0, "窗口过期后不应累计旧计数");
+  await d._handleFailover({ reason: "F4-4" }, c); // count=3 → 轮换
+  assert.equal(state.switches.length, 1, "第 3 次才应轮换");
+});
+
+test("F5 切换后窗口重置：重新从仅检查开始", async () => {
+  resetState();
+  const { d, c } = makeCtx();
+  await d._handleFailover({ reason: "F5-1" }, c); // skip
+  await d._handleFailover({ reason: "F5-2" }, c); // skip
+  await d._handleFailover({ reason: "F5-3" }, c); // switch
+  assert.equal(state.switches.length, 1, "第 3 次应切换");
+  await d._handleFailover({ reason: "F5-4" }, c); // 重置后 count=1 → skip
+  assert.equal(state.switches.length, 1, "切换后应重置窗口，不连续切换");
+  await d._handleFailover({ reason: "F5-5" }, c); // count=2 → skip
+  await d._handleFailover({ reason: "F5-6" }, c); // count=3 → switch
+  assert.equal(state.switches.length, 2, "第 6 次才应再次轮换");
+});
+
+test("F6 escapeAfter 可配置：=1 时首次健康 failover 即轮换", async () => {
+  resetState();
+  const { d, c } = makeCtx({ failoverEscapeAfter: 1 });
+  await d._handleFailover({ reason: "F6" }, c);
+  assert.equal(state.switches.length, 1, "escapeAfter=1 应首次即切换");
+});
+
+test("F7 候选集为空：触发 delay 初测且不切换", async () => {
+  resetState();
+  const { d, c } = makeCtx();
+  state.health = { ...state.health, healthy: false, error: "timeout" };
+  state.nodes = [];
+  await d._handleFailover({ reason: "F7" }, c);
+  assert.equal(state.switches.length, 0, "无候选不应切换");
+  assert.ok(c._lastProbeAt, "应触发过 delay 初测");
+});

package/scripts/verify-kill-edge.mjs

@@ -0,0 +1,108 @@
+// verify-kill-edge.mjs — 在 Windows 上端到端验证 killEdgeProcesses（netstat 方案）
+// 场景模拟：业务开一个带 --remote-debugging-port 的 Edge 实例，
+// 看门狗关闭时调用 killEdgeProcesses(null, port) 杀浏览器。
+// 安全：只用独立端口 19222 + 独立 user-data-dir，不碰机器上其他 Edge。
+import { exec, execSync } from "node:child_process";
+
+const PKG =
+  process.env.APPDATA.replace(/\\/g, "/") +
+  "/npm/node_modules/tt-help-cli-ycl";
+const { killEdgeProcesses, parseNetstatListeningPids } = await import(
+  "file:///" + PKG + "/src/lib/browser/cdp.js"
+);
+
+const PORT = 19222;
+const USER_DATA_DIR =
+  process.env.TEMP.replace(/\\/g, "/") + "/edge-test-" + PORT;
+
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function netstatPids(port) {
+  const out = execSync("netstat -ano", {
+    encoding: "utf-8",
+    timeout: 5000,
+    windowsHide: true,
+  });
+  return parseNetstatListeningPids(out, port);
+}
+
+async function cleanup() {
+  const pids = netstatPids(PORT);
+  for (const pid of pids) {
+    try {
+      execSync(`taskkill /F /T /PID ${pid}`, {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } catch {}
+  }
+  try {
+    execSync(`rd /s /q "${USER_DATA_DIR}"`, {
+      stdio: "ignore",
+      windowsHide: true,
+    });
+  } catch {}
+}
+
+async function main() {
+  // [1] 解析器静态验证：用当前真实 netstat 输出
+  {
+    const out = execSync("netstat -ano", {
+      encoding: "utf-8",
+      timeout: 5000,
+      windowsHide: true,
+    });
+    const sample = out
+      .split(/\r?\n/)
+      .filter((l) => l.includes("LISTENING"))
+      .slice(0, 5);
+    console.log("[1] 当前真实 LISTENING 行:");
+    for (const l of sample) console.log("   " + l.trim());
+    const clash = parseNetstatListeningPids(out, 9097);
+    console.log("[1] 9097 解析 PID = " + JSON.stringify(clash));
+  }
+
+  // [2] 启动真实 Edge CDP 测试实例
+  console.log("[2] 启动 Edge CDP 测试实例 (port=" + PORT + ") ...");
+  exec(
+    `start "" msedge --remote-debugging-port=${PORT} --user-data-dir="${USER_DATA_DIR}" --no-first-run --no-default-browser-check --disable-background-mode --disable-component-update --disable-crash-reporter --disable-breakpad --disable-sync --disable-background-networking`,
+    { windowsHide: true },
+  );
+
+  let readyPids = [];
+  for (let i = 0; i < 30; i++) {
+    await delay(1000);
+    readyPids = netstatPids(PORT);
+    if (readyPids.length > 0) break;
+  }
+  console.log("[2] 端口 " + PORT + " 监听 PID = " + JSON.stringify(readyPids));
+  if (readyPids.length === 0) {
+    console.log("RESULT: SETUP_FAIL（Edge 未监听端口）");
+    await cleanup();
+    process.exit(2);
+  }
+
+  // [3] 调用包内真实 killEdgeProcesses（与看门狗关闭时同一函数）
+  console.log("[3] 调用 killEdgeProcesses(null, " + PORT + ") ...");
+  const t0 = Date.now();
+  await killEdgeProcesses(null, PORT);
+  await delay(2000);
+
+  const after = netstatPids(PORT);
+  console.log(
+    "[3] 调用耗时 " +
+      (Date.now() - t0) +
+      "ms，杀后端口监听 PID = " +
+      JSON.stringify(after),
+  );
+
+  console.log(after.length === 0 ? "RESULT: PASS" : "RESULT: FAIL");
+  await cleanup();
+  process.exit(after.length === 0 ? 0 : 1);
+}
+
+main().catch(async (e) => {
+  console.error("脚本异常: " + e.message);
+  await cleanup();
+  process.exit(3);
+});

package/scripts/verify-stop-command.mjs

@@ -0,0 +1,159 @@
+// verify-stop-command.mjs — 211 上验证修复后的"看门狗关闭"完整时序
+// 模拟：看门狗托管业务命令 refresh-mini --port 19223，业务启动 Edge CDP 实例。
+// 修复后 stopCommand 顺序：先 killEdgeProcesses(端口) 杀浏览器 → 再 taskkill 业务进程树。
+// 验证：Edge 进程树全灭（端口释放）+ 业务进程被杀。
+import { execSync, spawn } from "node:child_process";
+
+const PKG =
+  process.env.APPDATA.replace(/\\/g, "/") +
+  "/npm/node_modules/tt-help-cli-ycl";
+// 包内真实函数（当前 1.4.128 的 netstat 实现）
+const { killEdgeProcesses } = await import(
+  "file:///" + PKG + "/src/lib/browser/cdp.js"
+);
+
+const PORT = 19223;
+const USER_DATA_DIR =
+  process.env.TEMP.replace(/\\/g, "/") + "/edge-test-" + PORT;
+
+// 修复后的 extractCdpPorts（与本地 process-manager.js 修改一致）
+const BROWSER_CMD_RE =
+  /\b(?:explore|auto|attach|scrape|comments|refresh|recheck|precheck|search|videos|videostats|open|tag|login-check)\b/;
+function extractCdpPorts(cmdLine) {
+  const baseMatch = cmdLine.match(/--base-port\s+(\d+)/);
+  if (baseMatch) {
+    const base = parseInt(baseMatch[1], 10);
+    const countMatch = cmdLine.match(/--port-count\s+(\d+)/);
+    const count = countMatch ? parseInt(countMatch[1], 10) : 1;
+    const ports = [];
+    for (let i = 0; i < count; i++) ports.push(base + i);
+    return ports;
+  }
+  if (BROWSER_CMD_RE.test(cmdLine)) {
+    const m = cmdLine.match(/--port\s+(\d+)/);
+    if (m) return [parseInt(m[1], 10)];
+  }
+  return [];
+}
+
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function listeningPids(port) {
+  const out = execSync("netstat -ano", {
+    encoding: "utf-8",
+    timeout: 5000,
+    windowsHide: true,
+  });
+  const pids = [];
+  for (const line of out.split(/\r?\n/)) {
+    if (!line.includes("LISTENING") || !line.includes(":" + port + " ")) continue;
+    const parts = line.trim().split(/\s+/);
+    const pid = parts[parts.length - 1];
+    if (/^\d+$/.test(pid) && !pids.includes(pid)) pids.push(pid);
+  }
+  return pids;
+}
+
+function pidAlive(pid) {
+  try {
+    const out = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+      encoding: "utf-8",
+      timeout: 5000,
+      windowsHide: true,
+    });
+    // 解析输出文本判断（tasklist 无匹配时可能仍 exit 0，不能依赖退出码）
+    return new RegExp("\\b" + pid + "\\b").test(out);
+  } catch {
+    return false;
+  }
+}
+
+async function cleanup() {
+  for (const pid of listeningPids(PORT)) {
+    try {
+      execSync(`taskkill /F /T /PID ${pid}`, {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } catch {}
+  }
+  try {
+    execSync(`rd /s /q "${USER_DATA_DIR}"`, {
+      stdio: "ignore",
+      windowsHide: true,
+    });
+  } catch {}
+}
+
+async function main() {
+  const CMD_LINE = `tt-help refresh-mini --preset slow --port ${PORT} --rotate-min 0`;
+
+  // [1] 端口提取（修复后逻辑）
+  const ports = extractCdpPorts(CMD_LINE);
+  console.log("[1] extractCdpPorts(" + CMD_LINE + ") = " + JSON.stringify(ports));
+  if (JSON.stringify(ports) !== JSON.stringify([PORT])) {
+    console.log("RESULT: FAIL（端口提取不对）");
+    process.exit(1);
+  }
+
+  // [2] 启动业务进程（node 长驻占位）与 Edge CDP 实例（脱离进程树，模拟 start 启动）
+  const biz = spawn(
+    process.execPath,
+    ["-e", "setInterval(()=>{},1000)"],
+    { stdio: ["ignore", "ignore", "ignore"], windowsHide: true },
+  );
+  console.log("[2] 业务进程 PID = " + biz.pid);
+
+  execSync(
+    `start "" msedge --remote-debugging-port=${PORT} --user-data-dir="${USER_DATA_DIR}" --no-first-run --no-default-browser-check --disable-background-mode --disable-component-update --disable-crash-reporter --disable-breakpad --disable-sync --disable-background-networking`,
+    { stdio: "ignore", windowsHide: true },
+  );
+
+  let edgePids = [];
+  for (let i = 0; i < 30; i++) {
+    await delay(1000);
+    edgePids = listeningPids(PORT);
+    if (edgePids.length > 0) break;
+  }
+  console.log("[2] Edge 监听 " + PORT + " PID = " + JSON.stringify(edgePids));
+  if (edgePids.length === 0) {
+    console.log("RESULT: SETUP_FAIL（Edge 未监听端口）");
+    await cleanup();
+    try { biz.kill(); } catch {}
+    process.exit(2);
+  }
+
+  // [3] 修复后的 stopCommand 顺序：先杀浏览器，再杀业务进程树
+  console.log("[3] 先 killEdgeProcesses(null, " + PORT + ") ...");
+  for (const port of ports) {
+    await killEdgeProcesses(null, port);
+  }
+  await delay(2000);
+  const edgeAfter = listeningPids(PORT);
+  console.log("[3] 杀浏览器后端口监听 = " + JSON.stringify(edgeAfter));
+
+  console.log("[3] 再 taskkill /F /T /PID " + biz.pid + " ...");
+  try {
+    execSync(`taskkill /F /T /PID ${biz.pid}`, {
+      stdio: "ignore",
+      timeout: 5000,
+      windowsHide: true,
+    });
+  } catch (e) {
+    console.log("[3] taskkill 业务返回: " + e.message);
+  }
+  await delay(3000);
+  const bizAlive = pidAlive(biz.pid);
+  console.log("[3] 业务进程存活: " + bizAlive);
+
+  const ok = edgeAfter.length === 0 && !bizAlive;
+  console.log(ok ? "RESULT: PASS" : "RESULT: FAIL");
+  await cleanup();
+  process.exit(ok ? 0 : 1);
+}
+
+main().catch(async (e) => {
+  console.error("脚本异常: " + e.message);
+  await cleanup();
+  process.exit(3);
+});

package/src/clash/daemon.js

@@ -20,8 +20,10 @@ function fmtCountries(v) {
   return list.length ? list.join(",") : "无";
 }
 
-// failover 切换冷却期（默认 45s，可经 opts.failoverCooldownMs 覆盖）
-const FAILOVER_COOLDOWN_MS = 45_000;
+// failover 检查窗口（默认 10 分钟，与候选集 delay 初测周期对齐；可经 opts.failoverCooldownMs 覆盖）
+const FAILOVER_COOLDOWN_MS = 600_000;
+// 窗口内探针健康时的切换阈值（默认 3：前 2 次仅检查，第 3 次按业务级封禁轮换）
+const FAILOVER_ESCAPE_AFTER = 3;
 
 // ══════════════════════════════════════════════
 // ClashDaemon
@@ -35,6 +37,10 @@ export class ClashDaemon {
       opts.failoverCooldownMs > 0
         ? opts.failoverCooldownMs
         : FAILOVER_COOLDOWN_MS;
+    this.failoverEscapeAfter =
+      opts.failoverEscapeAfter > 0
+        ? opts.failoverEscapeAfter
+        : FAILOVER_ESCAPE_AFTER;
     this.dryRun = !!opts.dryRun;
     // 控制端发现参数（CLI 显式值优先，内部再合并 ~/.tt-help.json）
     this._discoverOpts = {
@@ -602,32 +608,48 @@ export class ClashDaemon {
   /**
    * 看门狗指令: 主动故障切换（不依赖巡检发现，强制从候选集切下一个可用节点）
    * 用于业务进程连续报错（CDN限流/网络异常/封 IP 等）时换出口节点
+   *
+   * failover 三级响应（2026-08-22，替代原 45s 冷却）：
+   *   1. 每次 failover 先检查当前节点（消除冷却期外盲切）；
+   *   2. 探针不健康 → 立即切换（有依据才切，无视窗口）；
+   *   3. 探针健康 → 窗口内默认只检查不切换；同一窗口内 failover 到达
+   *      failoverEscapeAfter 次（默认 3）→ 视为业务级封禁（curl 探针感知不到
+   *      TikTok 业务风控）→ 按轮换逻辑切一次。
+   * 实际切换（成功或恢复原节点）或触发候选初测后重置窗口与计数，给新节点干净
+   * 观察窗口；窗口 = failoverCooldownMs（默认 10 分钟，与候选集初测周期对齐）。
+   * 按控制端独立记录（多控制端互不影响）；对外接口（命令动作/IPC/health）不变。
    */
   async _handleFailover(cmd, c) {
     try {
-      // ── failover 冷却 + 健康验证（2026-08-18）──
-      // 冷却期内再次收到 failover：先验证当前节点健康，健康则跳过并续冷却
-      // （持续健康 → 持续不切，避免冷却期结束后又白切健康节点；同时过滤滞后/重连误报），
-      // 不健康才继续切换。按控制端独立记录冷却（多控制端互不影响）；
-      // 对外接口（命令动作 / IPC / health 格式）保持不变。
+      const reason = (cmd && cmd.reason) || "看门狗主动故障切换";
       const now = Date.now();
-      const lastAt = c._lastFailoverAt || 0;
-      if (lastAt > 0 && now - lastAt < this.failoverCooldownMs) {
-        const h = checker.checkNodeHealth();
-        if (h && h.healthy) {
-          c._lastFailoverAt = now; // 续冷却：持续健康则持续不切
-          this._log(
-            `🔄 冷却期内节点健康 [${c.proxyPort}]，跳过重复 failover（上次判定 ${Math.round((now - lastAt) / 1000)}s 前）`,
-          );
-          return;
-        }
+      const w =
+        c._failoverWindow || (c._failoverWindow = { startAt: 0, count: 0 });
+      if (now - w.startAt >= this.failoverCooldownMs) {
+        w.startAt = now;
+        w.count = 0;
+      }
+      w.count += 1;
+
+      // 第 1 级：先检查当前节点（壳页 = 链路正常，按健康对待，与巡检口径一致）
+      const h = checker.checkNodeHealth();
+      const probeOk = !!h && (h.healthy || this._isShellPage(h));
+      if (probeOk && w.count < this.failoverEscapeAfter) {
+        this._log(
+          `🔄 [${c.proxyPort}] 探针健康，窗口内第 ${w.count}/${this.failoverEscapeAfter} 次 failover 仅检查不切换 [${reason}]`,
+        );
+        return;
+      }
+      if (probeOk) {
+        this._log(
+          `🔄 [${c.proxyPort}] 窗口内第 ${w.count} 次 failover：探针健康但业务持续报错，按业务级封禁轮换 [${reason}]`,
+        );
+      } else {
         this._log(
-          `🔄 冷却期内节点不健康 [${c.proxyPort}]，继续故障切换（有依据才切）`,
+          `🔄 [${c.proxyPort}] 探针不健康（${(h && (h.error || `HTTP ${h.httpCode}`)) || "无响应"}），立即故障切换 [${reason}]`,
         );
       }
-      c._lastFailoverAt = now;
 
-      const reason = (cmd && cmd.reason) || "看门狗主动故障切换";
       const node = await api
         .getCurrentNode(checker.CONFIG.groupName)
         .catch(() => "?");
@@ -637,6 +659,9 @@ export class ClashDaemon {
       const { nodes } = checker.loadHealthyList();
       if (!nodes.length) {
         this._log("🔄 候选集为空，触发 delay 初测");
+        // 初测即处置：重置窗口，避免健康探测每轮重复触发初测
+        w.startAt = now;
+        w.count = 0;
         await this._runDelayProbeController(c);
         return;
       }
@@ -660,6 +685,10 @@ export class ClashDaemon {
         }
         this._log(`  ↺ ${cand} 内容验证未通过，下一个`);
       }
+      // 本次 failover 已尽力处置（成功切换或恢复原节点）：重置窗口，给新节点干净观察窗口
+      w.startAt = now;
+      w.count = 0;
+
       if (!target) {
         await checker.switchToNode(node).catch(() => {});
         this._markSwitch(c, node);
@@ -801,5 +830,8 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
     secret: getArg("--secret") || undefined,
     selection: getArg("--selection") || undefined,
     configPaths: configPaths.length ? configPaths : undefined,
+    failoverCooldownMs: parseInt(getArg("--failover-cooldown-ms")) || undefined,
+    failoverEscapeAfter:
+      parseInt(getArg("--failover-escape-after")) || undefined,
   }).start();
 }

package/src/cli/attach.js

@@ -389,7 +389,12 @@ export async function handleAttach(options) {
           MAX_CDN_COOLDOWN_SEC,
         );
         const shouldSwitch = consecutiveCdnBlocks <= MAX_CDN_SWITCH_ATTEMPTS;
-        if (shouldSwitch) {
+        if (!scraper) {
+          // webserver 模式：限流发生在远端 webserver 出口，本地切节点无效，仅冷却等待
+          attachLog(
+            `  [Attach] CDN限流比例 ${(cdnRatio * 100).toFixed(0)}% (${cdnBlockedCount}/${tasks.length})，webserver 模式不切节点，冷却 ${coolDownSeconds} 秒...`,
+          );
+        } else if (shouldSwitch) {
           // 用现有 IPC 接口通知 daemon 从候选集切下一个健康节点（换 IP 绕过 CDN 限流）
           try {
             writeCommand({

package/src/cli/precheck.js

@@ -429,18 +429,25 @@ export async function handlePrecheck(options) {
       const cdnRatio =
         candidates.length > 0 ? cdnBlockedCount / candidates.length : 0;
       if (cdnRatio > 0.3) {
-        // 用现有 IPC 接口通知 daemon 从候选集切下一个健康节点（换 IP 绕过 CDN 限流）
-        try {
-          writeCommand({
-            action: "failover",
-            reason: `precheck CDN限流 (${(cdnRatio * 100).toFixed(0)}%)`,
-          });
-        } catch {}
         // 切换节点后新 IP 生效需短暂等待，冷却可缩短（替代纯硬等 120s）
         const coolDownSeconds = cdnRatio > 0.8 ? 90 : 60;
-        precheckLog(
-          `  [Precheck] CDN限流比例 ${(cdnRatio * 100).toFixed(0)}% (${cdnBlockedCount}/${candidates.length})，已通知 daemon 切换节点，冷却 ${coolDownSeconds} 秒...`,
-        );
+        if (scraper) {
+          // 本地模式：用现有 IPC 接口通知 daemon 从候选集切下一个健康节点（换 IP 绕过 CDN 限流）
+          try {
+            writeCommand({
+              action: "failover",
+              reason: `precheck CDN限流 (${(cdnRatio * 100).toFixed(0)}%)`,
+            });
+          } catch {}
+          precheckLog(
+            `  [Precheck] CDN限流比例 ${(cdnRatio * 100).toFixed(0)}% (${cdnBlockedCount}/${candidates.length})，已通知 daemon 切换节点，冷却 ${coolDownSeconds} 秒...`,
+          );
+        } else {
+          // webserver 模式：限流发生在远端 webserver 出口，本地切节点无效，仅冷却等待
+          precheckLog(
+            `  [Precheck] CDN限流比例 ${(cdnRatio * 100).toFixed(0)}% (${cdnBlockedCount}/${candidates.length})，webserver 模式不切节点，冷却 ${coolDownSeconds} 秒...`,
+          );
+        }
         await new Promise((r) => setTimeout(r, coolDownSeconds * 1000));
         if (scraper) {
           await recycleScraper(

package/src/watchdog/agent.js

@@ -103,6 +103,15 @@ function isCollectorCommand(cmdDef) {
   return COLLECTOR_KEYWORDS.some((k) => s.includes(k));
 }
 
+/**
+ * 检测命令是否运行在 webserver 模式（不启动本地浏览器，抓取由远端集中完成）。
+ * 该模式下限流/网络错误发生在远端 webserver 出口，本地切换节点无法解决，
+ * 因此错误触发切换统计应排除此类进程。
+ */
+function isWebserverMode(cmdDef) {
+  return /--webserver(?=\s|=|$)/.test(cmdDef?.command || "");
+}
+
 /** 自动发现 daemon.js 路径 */
 function findDaemonPath() {
   // 1. 内部打包路径优先（npm publish 后 src/clash/daemon.js，升级即最新）
@@ -388,6 +397,8 @@ export class WatchdogAgent {
     let failoverTriggered = false; // 本轮是否已触发全局切换
     for (const { cmdId, cmdDef, newErrors } of scanned) {
       if (!isCollectorCommand(cmdDef)) continue;
+      // webserver 模式：错误发生在远端出口，本地切节点无法解决，不计入错误触发统计
+      if (isWebserverMode(cmdDef)) continue;
       let st = this._errorStates.get(cmdId) || {
         consecutive: 0,
         firstErrorAt: 0,

package/src/watchdog/process-manager.js

@@ -78,16 +78,29 @@ function printProcessLine(id, msg) {
   }
 }
 
-// 从命令行中提取 CDP 端口列表（解析 --base-port 和 --port-count）
+// 会启动 CDP 浏览器的采集类命令（用于识别单端口形式 --port 的归属）
+// 排除 webserver/watch 等 --port 是服务端口的命令，避免误杀
+const BROWSER_CMD_RE =
+  /\b(?:explore|auto|attach|scrape|comments|refresh|recheck|precheck|search|videos|videostats|open|tag|login-check)\b/;
+
+// 从命令行中提取 CDP 端口列表（解析 --base-port/--port-count 和单端口 --port）
 function extractCdpPorts(cmdLine) {
-  const match = cmdLine.match(/--base-port\s+(\d+)/);
-  if (!match) return [];
-  const base = parseInt(match[1], 10);
-  const countMatch = cmdLine.match(/--port-count\s+(\d+)/);
-  const count = countMatch ? parseInt(countMatch[1], 10) : 1;
-  const ports = [];
-  for (let i = 0; i < count; i++) ports.push(base + i);
-  return ports;
+  // 多端口形式：--base-port N [--port-count M] → N..N+M-1
+  const baseMatch = cmdLine.match(/--base-port\s+(\d+)/);
+  if (baseMatch) {
+    const base = parseInt(baseMatch[1], 10);
+    const countMatch = cmdLine.match(/--port-count\s+(\d+)/);
+    const count = countMatch ? parseInt(countMatch[1], 10) : 1;
+    const ports = [];
+    for (let i = 0; i < count; i++) ports.push(base + i);
+    return ports;
+  }
+  // 单端口形式（如 refresh-mini --port 5222）：仅浏览器类命令提取
+  if (BROWSER_CMD_RE.test(cmdLine)) {
+    const m = cmdLine.match(/--port\s+(\d+)/);
+    if (m) return [parseInt(m[1], 10)];
+  }
+  return [];
 }
 
 // 引号感知的命令拆分："a b" "c d" → ["a b", "c d"]
@@ -382,6 +395,13 @@ export class ProcessManager extends EventEmitter {
         const cmdLine = info.cmdDef?.command || "";
         const ports = extractCdpPorts(cmdLine);
 
+        // 必须先杀浏览器再杀业务进程树：业务进程被强杀后 Edge 主进程可能随之
+        // 退出、CDP 端口释放，此时按端口找监听 PID 会落空，导致 Edge 子进程残留。
+        // 先杀时端口必在监听，netstat 找 PID → taskkill /T 可杀干净整个 Edge 进程树。
+        for (const port of ports) {
+          killEdgeProcesses(null, port);
+        }
+
         if (IS_WIN) {
           // Windows: shell:true 产生 cmd.exe 中间层，必须杀整个进程树
           execSync(`taskkill /PID ${info.child.pid} /T /F`, {
@@ -401,10 +421,6 @@ export class ProcessManager extends EventEmitter {
           }, 2000);
         }
 
-        // 全平台：关闭脱离进程树的浏览器（open -a / start msedge 启动的）
-        for (const port of ports) {
-          killEdgeProcesses(null, port);
-        }
       } catch (e) {
         console.error(`[watchdog] 停止命令 ${cmdId} 失败: ${e.message}`);
       }