tt-help-cli-ycl 1.4.130 → 1.4.132

package/package.json

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

package/scripts/test-daemon-failover.mjs

@@ -1,14 +1,11 @@
 /**
- * daemon _handleFailover 三级响应单测（2026-08-22，无需 Clash 运行）
+ * daemon _handleFailover 单测（2026-08-25，时间锚点方案，无需 Clash 运行）
  *
  * 验证：
- *   - 探针健康 → 窗口内 failover 仅检查不切换（前 N-1 次）
- *   - 探针不健康 → 立即切换（无视窗口）
- *   - 壳页 → 视为链路正常，仅检查不切换（与巡检口径一致）
- *   - 窗口过期 → 计数重置
- *   - 窗口内到达 failoverEscapeAfter 次 → 按业务级封禁轮换一次
- *   - 实际切换后 → 窗口与计数重置
- *   - escapeAfter 可配置
+ *   - 探针不健康 → 立即切换（无视冷却）
+ *   - 探针健康（含壳页）→ 距上次切换 < 冷却期仅检查不切换
+ *   - 探针健康 → 距上次切换 >= 冷却期 → 按业务级封禁轮换一次
+ *   - 切换后（含手动/巡检/failover）更新 _lastSwitchAt 锚点，冷却期内不再切
  *   - 候选集为空 → 触发 delay 初测且不切换
  *
  * 运行: node --test scripts/test-daemon-failover.mjs
@@ -116,29 +113,32 @@ function makeCtx(opts = {}) {
   return { d, c };
 }
 
-test("F1 探针健康：前 2 次 failover 仅检查不切换，第 3 次轮换", async () => {
+test("F1 探针健康：冷却期外首次 failover 即轮换，并更新锚点", 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 次按轮换切换到候选");
+  c._lastSwitchAt = Date.now() - 600_001; // 距上次切换 > 10min 冷却
+  await d._handleFailover({ reason: "F1" }, c);
+  assert.deepEqual(state.switches, ["🇲🇾 马来02"], "冷却期外应轮换切换");
   assert.equal(state.closes, 1, "切换后应断开旧连接");
+  assert.ok(
+    c._lastSwitchAt && c._lastSwitchAt > Date.now() - 5000,
+    "切换后应更新锚点",
+  );
 });
 
-test("F2 探针不健康：立即切换（无视窗口）", async () => {
+test("F2 探针不健康：立即切换（无视冷却）", async () => {
   resetState();
   const { d, c } = makeCtx();
+  c._lastSwitchAt = Date.now(); // 刚切过，但探针不健康时不看锚点
   state.health = { ...state.health, healthy: false, error: "timeout" };
   await d._handleFailover({ reason: "F2" }, c);
   assert.deepEqual(state.switches, ["🇲🇾 马来02"], "不健康应立即切换");
 });
 
-test("F3 壳页视为链路正常：仅检查不切换", async () => {
+test("F3 壳页视为链路正常：冷却期内仅检查不切换", async () => {
   resetState();
   const { d, c } = makeCtx();
+  c._lastSwitchAt = Date.now(); // 冷却期内
   // 壳页签名：200 + 无跳转 + 无 error + 无 title
   state.health = {
     healthy: false,
@@ -150,41 +150,45 @@ test("F3 壳页视为链路正常：仅检查不切换", async () => {
     error: null,
   };
   await d._handleFailover({ reason: "F3" }, c);
-  assert.equal(state.switches.length, 0, "壳页不应触发切换");
+  assert.equal(state.switches.length, 0, "冷却期内壳页不应触发切换");
 });
 
-test("F4 窗口过期：计数重置，不累计到逃生阈值", async () => {
+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 次才应轮换");
+  const { d, c } = makeCtx();
+  // 首次 failover（无锚点）→ 按冷却期外处理 → 轮换
+  await d._handleFailover({ reason: "F4-1" }, c);
+  assert.equal(state.switches.length, 1, "首次应轮换切换");
+  // 锚点刚更新，冷却期内再次 failover（探针健康）→ 不切
+  await d._handleFailover({ reason: "F4-2" }, c);
+  assert.equal(state.switches.length, 1, "冷却期内不应再切换");
+  // 冷却期过后 → 再次轮换
+  c._lastSwitchAt = Date.now() - 600_001;
+  await d._handleFailover({ reason: "F4-3" }, c);
+  assert.equal(state.switches.length, 2, "冷却期过后应再切换");
 });
 
-test("F5 切换后窗口重置：重新从仅检查开始", async () => {
+test("F5 手动切换同样更新锚点：切换后冷却期内 failover 不再切", 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 次才应再次轮换");
+  // 手动切换（用户主动切，立即执行）
+  await d._handleSwitchNode({ node: "🇲🇾 马来02", proxyPort: 7897 }, c);
+  assert.equal(state.switches.length, 1, "手动切换应立即执行");
+  assert.ok(
+    c._lastSwitchAt && c._lastSwitchAt > Date.now() - 5000,
+    "手动切换应更新锚点",
+  );
+  // 手动切换后冷却期内，探针健康的 failover 不再切
+  await d._handleFailover({ reason: "F5-2" }, c);
+  assert.equal(
+    state.switches.length,
+    1,
+    "手动切换后冷却期内 failover 不应再切",
+  );
 });
 
-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 应首次即切换");
-});
+// F6 已移除：failoverEscapeAfter 计数方案已弃用（2026-08-25 改为时间锚点），
+// 不再存在"连报 N 次"阈值；字段保留仅为兼容外部传参，不影响行为。
 
 test("F7 候选集为空：触发 delay 初测且不切换", async () => {
   resetState();

package/scripts/test-probe-live.mjs

@@ -0,0 +1,83 @@
+/**
+ * 探测模块集成测试（真实浏览器 + 真实 TikTok）
+ *
+ * 用法:
+ *   node scripts/test-probe-live.mjs [ports] [points]
+ *   例: node scripts/test-probe-live.mjs 4222
+ *       node scripts/test-probe-live.mjs 4222 video,comment
+ *
+ * 说明:
+ *   - 连接本地已启动的 CDP 端口（不 kill 业务浏览器）
+ *   - 会对 TikTok 真实发起访问（探测本身是访问行为）
+ *   - 断言输出结构 + 至少能完成调度；业务可用性结果只打印不判成败
+ */
+import assert from "node:assert/strict";
+import { runProbe, POINT_NAMES } from "../src/lib/probe/index.js";
+
+const ports = (process.argv[2] || "4222")
+  .split(",")
+  .map((s) => Number(s.trim()))
+  .filter((n) => Number.isInteger(n) && n > 0);
+const points = process.argv[3]
+  ? process.argv[3].split(",").map((s) => s.trim()).filter(Boolean)
+  : POINT_NAMES;
+
+console.error(`[live-test] ports=${ports.join(",")} points=${points.join(",")}`);
+console.error(`[live-test] 说明：将对 TikTok 真实访问，属正常探测行为\n`);
+
+const t0 = Date.now();
+const result = await runProbe({ ports, points, log: console.error });
+const totalMs = Date.now() - t0;
+
+console.error(`\n[结果] 总耗时 ${totalMs}ms`);
+console.log(JSON.stringify(result, null, 2));
+
+// ── 结构断言（不判业务成败，只判调度/输出正确） ──
+let failed = 0;
+try {
+  assert.ok(Array.isArray(result.ports), "ports 应为数组");
+  assert.equal(result.ports.length, ports.length, "端口数应一致");
+  assert.ok(result.ports.every((p) => Number.isInteger(p.port)), "端口号应为整数");
+  assert.ok(
+    result.ports.every((p) => typeof p.loggedIn === "boolean"),
+    "loggedIn 应为布尔",
+  );
+  // 每端口包含请求的功能点键
+  for (const p of result.ports) {
+    for (const name of points) {
+      assert.ok(
+        name in p.points,
+        `端口 ${p.port} 应包含功能点 ${name}`,
+      );
+      const r = p.points[name];
+      assert.equal(typeof r.ok, "boolean", `${name}.ok 应为布尔`);
+      assert.equal(typeof r.count, "number", `${name}.count 应为数字`);
+      assert.equal(typeof r.elapsedMs, "number", `${name}.elapsedMs 应为数字`);
+      assert.ok(
+        typeof r.error === "string" || r.error === null,
+        `${name}.error 应为 string|null`,
+      );
+    }
+  }
+  console.error(`\n[断言] 结构校验全部通过 ✓`);
+} catch (e) {
+  failed = 1;
+  console.error(`\n[断言] 失败: ${e.message}`);
+}
+
+// 汇总业务结果
+console.error("\n[业务汇总]");
+for (const p of result.ports) {
+  for (const name of points) {
+    const r = p.points[name];
+    if (!r) continue;
+    const tag = r.skipped
+      ? `跳过(${r.skipReason})`
+      : r.ok
+        ? `✓ ${r.count}`
+        : `✗ ${r.error}`;
+    console.error(`  port ${p.port}  ${name.padEnd(8)} ${tag} [${r.elapsedMs}ms]`);
+  }
+}
+
+process.exit(failed);

package/scripts/test-probe.mjs

@@ -0,0 +1,315 @@
+/**
+ * 探测模块单元测试（离线，不连浏览器）
+ *
+ * 覆盖：
+ *   - common:   classifyError / withTimeout / cleanMessage / makePointResult
+ *   - targets:  DEFAULT_TARGETS / resolveTargets
+ *   - index:    POINT_NAMES / normalizePoints / runProbe 空端口与异常端口
+ *   - points:   comment 无视频 skipped、follow 未登录 skipped、POINT_NAME 注册
+ *
+ * 运行: node scripts/test-probe.mjs
+ */
+import assert from "node:assert/strict";
+import {
+  classifyError,
+  withTimeout,
+  cleanMessage,
+  makePointResult,
+  isTransientKind,
+  retryOnTransient,
+} from "../src/lib/probe/common.js";
+import { DEFAULT_TARGETS, resolveTargets } from "../src/lib/probe/targets.js";
+import {
+  POINTS,
+  POINT_NAMES,
+  normalizePoints,
+  runProbe,
+} from "../src/lib/probe/index.js";
+import {
+  POINT_NAME as COMMENT_POINT_NAME,
+  probeComment,
+} from "../src/lib/probe/points/comment.js";
+import {
+  POINT_NAME as FOLLOW_POINT_NAME,
+  probeFollow,
+} from "../src/lib/probe/points/follow.js";
+
+let passed = 0;
+const failures = [];
+const allTests = [];
+function test(name, fn) {
+  allTests.push(
+    Promise.resolve().then(() => {
+      try {
+        fn();
+        passed++;
+        console.log(`✓ ${name}`);
+      } catch (e) {
+        failures.push({ name, error: e });
+        console.error(`✗ ${name}: ${e.message}`);
+      }
+    }),
+  );
+}
+function testAsync(name, fn) {
+  allTests.push(
+    Promise.resolve().then(async () => {
+      try {
+        await fn();
+        passed++;
+        console.log(`✓ ${name}`);
+      } catch (e) {
+        failures.push({ name, error: e });
+        console.error(`✗ ${name}: ${e.message}`);
+      }
+    }),
+  );
+}
+
+// ── common.classifyError ──
+test("classifyError: 被封 → blocked", () => {
+  assert.equal(classifyError(new Error("被封: abc")).kind, "blocked");
+});
+test("classifyError: CDN限流 → rate_limited", () => {
+  assert.equal(classifyError(new Error("CDN限流: abc")).kind, "rate_limited");
+});
+test("classifyError: Access Denied → rate_limited", () => {
+  assert.equal(classifyError("Access Denied").kind, "rate_limited");
+});
+test("classifyError: 验证码 → captcha", () => {
+  assert.equal(classifyError("验证码出现").kind, "captcha");
+});
+test("classifyError: captcha → captcha", () => {
+  assert.equal(classifyError("captcha verify").kind, "captcha");
+});
+test("classifyError: Timeout → timeout", () => {
+  assert.equal(classifyError(new Error("Timeout 123")).kind, "timeout");
+});
+test("classifyError: 超时 → timeout", () => {
+  assert.equal(classifyError("请求超时").kind, "timeout");
+});
+test("classifyError: login_required → login_required", () => {
+  assert.equal(classifyError("login_required").kind, "login_required");
+});
+test("classifyError: 未登录 → login_required", () => {
+  assert.equal(classifyError("请先登录").kind, "login_required");
+});
+test("classifyError: region → region_blocked", () => {
+  assert.equal(
+    classifyError("not available in your region").kind,
+    "region_blocked",
+  );
+});
+test("classifyError: 普通错误 → error", () => {
+  assert.equal(classifyError("boom something").kind, "error");
+});
+test("classifyError: 空 → error + 未知错误", () => {
+  const c = classifyError(null);
+  assert.equal(c.kind, "error");
+  assert.equal(c.message, "未知错误");
+});
+
+// ── common.cleanMessage ──
+test("cleanMessage: 去 ANSI + 首行 + 限长", () => {
+  const out = cleanMessage("\x1b[31mline1\x1b[0m\nline2\n".repeat(50));
+  assert.ok(!out.includes("\x1b"));
+  assert.ok(!out.includes("\n"));
+  assert.ok(out.length <= 300);
+});
+
+// ── common.withTimeout ──
+testAsync("withTimeout: 正常完成返回结果", async () => {
+  const r = await withTimeout(Promise.resolve("ok"), 2000, "t");
+  assert.equal(r, "ok");
+});
+testAsync("withTimeout: 超时 reject", async () => {
+  let timedOut = false;
+  try {
+    await withTimeout(new Promise(() => {}), 30, "超时测试");
+  } catch (e) {
+    timedOut = true;
+    assert.ok(e.message.includes("超时测试"));
+  }
+  assert.ok(timedOut, "应超时 reject");
+});
+
+// ── common.makePointResult ──
+test("makePointResult: 默认空 → kind=empty", () => {
+  const r = makePointResult({ ok: false });
+  assert.equal(r.kind, "empty");
+  assert.equal(r.count, 0);
+  assert.equal(r.skipped, false);
+});
+test("makePointResult: ok → kind=null + extra 合并", () => {
+  const r = makePointResult({ ok: true, count: 3, extra: { a: 1 } });
+  assert.equal(r.kind, null);
+  assert.equal(r.a, 1);
+});
+test("makePointResult: skipped + 显式 kind", () => {
+  const r = makePointResult({
+    ok: false,
+    skipped: true,
+    skipReason: "no_video",
+    kind: "login_required",
+  });
+  assert.equal(r.kind, "login_required");
+  assert.equal(r.skipReason, "no_video");
+});
+
+// ── common.isTransientKind / retryOnTransient ──
+test("isTransientKind: 瞬时型为 true", () => {
+  for (const k of ["timeout", "empty", "error", "waf_challenge"]) {
+    assert.equal(isTransientKind(k), true, `${k} 应为瞬时`);
+  }
+});
+test("isTransientKind: 确定型与空为 false", () => {
+  for (const k of [
+    "blocked",
+    "rate_limited",
+    "captcha",
+    "login_required",
+    "region_blocked",
+    null,
+    undefined,
+    "",
+  ]) {
+    assert.equal(isTransientKind(k), false, `${k} 不应为瞬时`);
+  }
+});
+testAsync("retryOnTransient: 成功即返回（只调 1 次）", async () => {
+  let calls = 0;
+  const r = await retryOnTransient(async () => {
+    calls++;
+    return makePointResult({ ok: true, count: 3 });
+  }, { retries: 2, retryDelayMs: 0 });
+  assert.equal(r.ok, true);
+  assert.equal(calls, 1);
+});
+testAsync("retryOnTransient: 确定性失败不重试（只调 1 次）", async () => {
+  let calls = 0;
+  const r = await retryOnTransient(async () => {
+    calls++;
+    return makePointResult({ ok: false, kind: "blocked" });
+  }, { retries: 2, retryDelayMs: 0 });
+  assert.equal(r.ok, false);
+  assert.equal(r.kind, "blocked");
+  assert.equal(calls, 1);
+});
+testAsync("retryOnTransient: 瞬时失败后第 2 次成功", async () => {
+  let calls = 0;
+  const r = await retryOnTransient(async () => {
+    calls++;
+    if (calls === 1) return makePointResult({ ok: false, kind: "waf_challenge" });
+    return makePointResult({ ok: true, count: 5 });
+  }, { retries: 2, retryDelayMs: 0 });
+  assert.equal(r.ok, true);
+  assert.equal(calls, 2);
+});
+testAsync("retryOnTransient: 瞬时失败耗尽返回最后结果", async () => {
+  let calls = 0;
+  const r = await retryOnTransient(async () => {
+    calls++;
+    return makePointResult({ ok: false, kind: "timeout" });
+  }, { retries: 2, retryDelayMs: 0 });
+  assert.equal(r.ok, false);
+  assert.equal(r.kind, "timeout");
+  assert.equal(calls, 3); // 1 次初始 + 2 次重试
+});
+testAsync("retryOnTransient: 重试间有间隔延迟", async () => {
+  const t0 = Date.now();
+  let calls = 0;
+  await retryOnTransient(
+    async () => {
+      calls++;
+      return makePointResult({ ok: false, kind: "empty" });
+    },
+    { retries: 1, retryDelayMs: 150 },
+  );
+  assert.equal(calls, 2);
+  assert.ok(Date.now() - t0 >= 150, "应有重试间隔");
+});
+
+// ── targets ──
+test("targets: 默认值", () => {
+  assert.equal(DEFAULT_TARGETS.author, "tiktok");
+  assert.equal(DEFAULT_TARGETS.searchQuery, "dog");
+  assert.equal(DEFAULT_TARGETS.video, null);
+});
+test("targets: resolveTargets 覆盖 + 保留默认", () => {
+  const t = resolveTargets({ author: "foo", video: "x" });
+  assert.equal(t.author, "foo");
+  assert.equal(t.searchQuery, "dog");
+  assert.equal(t.video, "x");
+});
+test("targets: resolveTargets 空覆盖 → 全默认", () => {
+  const t = resolveTargets();
+  assert.deepEqual(t, DEFAULT_TARGETS);
+});
+test("targets: resolveTargets null → 全默认", () => {
+  const t = resolveTargets(null);
+  assert.deepEqual(t, DEFAULT_TARGETS);
+});
+
+// ── index.normalizePoints ──
+test("normalizePoints: 空 → 全部功能点", () => {
+  assert.deepEqual(normalizePoints(), [...POINT_NAMES]);
+  assert.deepEqual(normalizePoints([]), [...POINT_NAMES]);
+  assert.deepEqual(normalizePoints(null), [...POINT_NAMES]);
+});
+test("normalizePoints: 全非法 → 全部功能点", () => {
+  assert.deepEqual(normalizePoints(["bad", "xxx"]), [...POINT_NAMES]);
+});
+test("normalizePoints: 过滤非法 + 去重 + 保序", () => {
+  assert.deepEqual(normalizePoints(["video", "video", "bad", "comment"]), [
+    "video",
+    "comment",
+  ]);
+});
+test("POINTS 注册表完整", () => {
+  assert.equal(POINT_NAMES.length, 5);
+  for (const n of POINT_NAMES) assert.equal(typeof POINTS[n], "function");
+});
+
+// ── points 注册与离线可判定分支 ──
+test("points: 各模块 POINT_NAME 常量正确", () => {
+  assert.equal(COMMENT_POINT_NAME, "comment");
+  assert.equal(FOLLOW_POINT_NAME, "follow");
+});
+testAsync("probeComment: 无视频 → skipped(no_video)", async () => {
+  const r = await probeComment(null, {
+    target: { video: null },
+    videoHref: null,
+  });
+  assert.equal(r.skipped, true);
+  assert.equal(r.skipReason, "no_video");
+  assert.equal(r.ok, false);
+});
+testAsync("probeFollow: 未登录 → skipped(not_logged_in)", async () => {
+  const r = await probeFollow(null, { target: {}, loggedIn: false });
+  assert.equal(r.skipped, true);
+  assert.equal(r.skipReason, "not_logged_in");
+  assert.equal(r.kind, "login_required");
+});
+
+// ── runProbe 空端口 / 非法端口 ──
+testAsync("runProbe: 空端口 → 空结果结构", async () => {
+  const r = await runProbe({ ports: [], log: () => {} });
+  assert.deepEqual(r.ports, []);
+  assert.ok(Array.isArray(r.points));
+  assert.equal(typeof r.checkedAt, "string");
+  assert.equal(typeof r.durationMs, "number");
+});
+testAsync("runProbe: 非法端口被过滤", async () => {
+  const r = await runProbe({ ports: [0, -1, NaN, "abc"], log: () => {} });
+  assert.deepEqual(r.ports, []);
+});
+// 注：真实端口连接（存在/不存在端口）属集成测试范畴（会启动/连接 Edge），见 scripts/test-probe-live.mjs
+
+// ── 汇总（等全部测试完成） ──
+await Promise.all(allTests);
+console.log(`\n${passed} 通过, ${failures.length} 失败`);
+if (failures.length > 0) {
+  for (const f of failures)
+    console.error(`  FAIL: ${f.name}\n    ${f.error.stack}`);
+  process.exit(1);
+}

package/src/clash/checker.js

@@ -26,7 +26,7 @@ const HEALTHY_FILE = join(tmpdir(), "clash-healthy-nodes.json");
 let _healthyFile = HEALTHY_FILE;
 
 export const CONFIG = {
-  testUrl: "https://www.tiktok.com/explore",
+  testUrl: "https://www.tiktok.com/@tiktok",
   proxyUrl: "http://127.0.0.1:7897",
   apiPort: 9097,
   groupName: "GLOBAL",

package/src/clash/daemon.js

@@ -20,9 +20,10 @@ function fmtCountries(v) {
   return list.length ? list.join(",") : "无";
 }
 
-// failover 检查窗口（默认 10 分钟，与候选集 delay 初测周期对齐；可经 opts.failoverCooldownMs 覆盖）
+// failover 冷却期（默认 10 分钟，与候选集 delay 初测周期对齐；可经 opts.failoverCooldownMs 覆盖）
+// 锚点 = 最近一次实际切换节点的时间（_lastSwitchAt）：冷却期内探针健康不切换
 const FAILOVER_COOLDOWN_MS = 600_000;
-// 窗口内探针健康时的切换阈值（默认 3：前 2 次仅检查，第 3 次按业务级封禁轮换）
+// 已弃用（2026-08-25 改为时间锚点方案）：旧版"窗口内连报 N 次"计数，字段保留仅为兼容外部传参
 const FAILOVER_ESCAPE_AFTER = 3;
 
 // ══════════════════════════════════════════════
@@ -97,6 +98,11 @@ export class ClashDaemon {
     c._switchHistory.set(nodeName, Date.now());
   }
 
+  /** 记录最近一次实际切换节点的时间（failover/巡检/手动切换共用锚点，冷却期判断依据） */
+  _markSwitchTime(c) {
+    if (c) c._lastSwitchAt = Date.now();
+  }
+
   /**
    * 壳页判定：TikTok SSR 降级响应（HTTP 200 + 无跳转 + 无 error + 无 title）。
    * 壳页 = 加载页（data-downgrade 骨架屏），链路正常、浏览器会自行渲染，不算节点故障。
@@ -428,6 +434,7 @@ export class ClashDaemon {
         // 全部候选不可用，恢复原节点
         await checker.switchToNode(node).catch(() => {});
         this._markSwitch(c, node);
+        this._markSwitchTime(c);
         await api.closeAllConnections().catch(() => {});
         this._log(
           `✗ [${c.proxyPort}] 恢复原节点 ${node}（原因: ${reason} — 候选全部不可用）`,
@@ -447,6 +454,7 @@ export class ClashDaemon {
       // 切换后断开所有旧连接：mihomo 不主动掐旧连接，浏览器 keep-alive 会继续走旧节点
       // 导致"时好时坏"（实测旧连接可存活 8+ 分钟），必须强制重建才即时生效
       await api.closeAllConnections().catch(() => {});
+      this._markSwitchTime(c);
       this._writeHealth(c, {
         node: target,
         healthy: h2.healthy,
@@ -585,6 +593,7 @@ export class ClashDaemon {
         });
       }
       this._markSwitch(c, cmd.node);
+      this._markSwitchTime(c);
       const h = checker.checkNodeHealth();
       // 切换后断开所有旧连接，浏览器立即重建到新节点（同巡检切换）
       await api.closeAllConnections().catch(() => {});
@@ -609,40 +618,36 @@ export class ClashDaemon {
    * 看门狗指令: 主动故障切换（不依赖巡检发现，强制从候选集切下一个可用节点）
    * 用于业务进程连续报错（CDN限流/网络异常/封 IP 等）时换出口节点
    *
-   * failover 三级响应（2026-08-22，替代原 45s 冷却）：
+   * failover 处理（2026-08-25，改为时间锚点方案）：
    *   1. 每次 failover 先检查当前节点（消除冷却期外盲切）；
-   *   2. 探针不健康 → 立即切换（有依据才切，无视窗口）；
-   *   3. 探针健康 → 窗口内默认只检查不切换；同一窗口内 failover 到达
-   *      failoverEscapeAfter 次（默认 3）→ 视为业务级封禁（curl 探针感知不到
-   *      TikTok 业务风控）→ 按轮换逻辑切一次。
-   * 实际切换（成功或恢复原节点）或触发候选初测后重置窗口与计数，给新节点干净
-   * 观察窗口；窗口 = failoverCooldownMs（默认 10 分钟，与候选集初测周期对齐）。
+   *   2. 探针不健康 → 立即切换（有依据才切，无视冷却）；
+   *   3. 探针健康（含壳页）→ 距上次实际切换（含巡检/手动/failover，见
+   *      _lastSwitchAt）< failoverCooldownMs（默认 10 分钟）→ 仅检查不切换；
+   *      距上次切换 >= 冷却期 → 视为业务级封禁（curl 探针感知不到 TikTok 业务
+   *      风控）→ 按轮换逻辑切一次。
+   * 每次实际切换（成功采用候选或恢复原节点）后更新 _lastSwitchAt 锚点，保证
+   * 10 分钟内最多切 1 次，给新节点干净观察期。
    * 按控制端独立记录（多控制端互不影响）；对外接口（命令动作/IPC/health）不变。
    */
   async _handleFailover(cmd, c) {
     try {
       const reason = (cmd && cmd.reason) || "看门狗主动故障切换";
       const now = Date.now();
-      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) {
+        // 探针健康：受冷却期约束（锚点 = 最近一次实际切换节点的时间 _lastSwitchAt）
+        const gap = now - (c._lastSwitchAt || 0);
+        if (gap < this.failoverCooldownMs) {
+          this._log(
+            `🔄 [${c.proxyPort}] 探针健康，距上次切换 ${Math.round(gap / 1000)}s（<${this.failoverCooldownMs / 60000}min 冷却），仅检查不切换 [${reason}]`,
+          );
+          return;
+        }
         this._log(
-          `🔄 [${c.proxyPort}] 窗口内第 ${w.count} 次 failover：探针健康但业务持续报错，按业务级封禁轮换 [${reason}]`,
+          `🔄 [${c.proxyPort}] 探针健康但业务持续报错，距上次切换已过冷却期，按业务级封禁轮换 [${reason}]`,
         );
       } else {
         this._log(
@@ -658,11 +663,15 @@ export class ClashDaemon {
       );
       const { nodes } = checker.loadHealthyList();
       if (!nodes.length) {
-        this._log("🔄 候选集为空，触发 delay 初测");
-        // 初测即处置：重置窗口，避免健康探测每轮重复触发初测
-        w.startAt = now;
-        w.count = 0;
-        await this._runDelayProbeController(c);
+        const gap = now - (c._lastProbeAt || 0);
+        if (gap >= this.benchmarkMs) {
+          this._log("🔄 候选集为空，触发 delay 初测");
+          await this._runDelayProbeController(c);
+        } else {
+          this._log(
+            `🔄 候选集为空（初测冷却中 ${Math.round((this.benchmarkMs - gap) / 1000)}s）`,
+          );
+        }
         return;
       }
       // 逐个切换候选 + 内容验证，第一个满足即采用（跳过当前节点）
@@ -685,9 +694,8 @@ export class ClashDaemon {
         }
         this._log(`  ↺ ${cand} 内容验证未通过，下一个`);
       }
-      // 本次 failover 已尽力处置（成功切换或恢复原节点）：重置窗口，给新节点干净观察窗口
-      w.startAt = now;
-      w.count = 0;
+      // 本次 failover 已尽力处置（成功切换或恢复原节点）：更新锚点，给新节点干净观察期
+      this._markSwitchTime(c);
 
       if (!target) {
         await checker.switchToNode(node).catch(() => {});

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，升级即最新）
@@ -242,6 +251,11 @@ export class WatchdogAgent {
     this._graceEnded = false; // 宽限期是否已结束
     // 业务日志错误统计 → 触发节点切换
     this._errorStates = new Map(); // cmdId -> {consecutive, firstErrorAt, lastErrorAt}
+    // 进程（重新）启动 → 重置该命令的错误计数（新进程实例从干净观察窗口开始，
+    // 避免把上一个进程实例的错误延续到新实例而误触发节点切换）
+    this.processManager.on("process-started", ({ cmdId }) => {
+      this._errorStates.delete(cmdId);
+    });
     this._errorTriggerTimer = null;
     this._errorTriggerEnabled = false; // 默认不启用（后端下发开启才生效）
     this._errorTriggerCount = ERROR_TRIGGER_COUNT;
@@ -388,6 +402,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

@@ -377,6 +377,8 @@ export class ProcessManager extends EventEmitter {
       logs: [],
       lastLogTime: Date.now(), // 初始化为启动时间，用于假死检测
     });
+    // 通知上层：进程（重新）启动，可重置该命令的跨实例状态（如错误计数）
+    this.emit("process-started", { cmdId: id, cmdDef });
   }
 
   /**
@@ -420,7 +422,6 @@ export class ProcessManager extends EventEmitter {
             } catch {}
           }, 2000);
         }
-
       } catch (e) {
         console.error(`[watchdog] 停止命令 ${cmdId} 失败: ${e.message}`);
       }
@@ -487,7 +488,9 @@ export class ProcessManager extends EventEmitter {
     const result = [];
     for (const [cmdId, info] of this.processes) {
       if (info.stopped || !info.logs || info.logs.length === 0) continue;
-      // 日志可能被 LLM 分析清空过，偏移需收敛到当前长度
+      // 日志可能被 LLM 分析清空过（_errSeen 未同步）：长度小于偏移说明
+      // 是清空后重建的日志，重置偏移，确保新日志从头扫描不遗漏
+      if ((info._errSeen || 0) > info.logs.length) info._errSeen = 0;
       const seen = Math.min(info._errSeen || 0, info.logs.length);
       const newLines = info.logs.slice(seen);
       info._errSeen = info.logs.length;
@@ -515,6 +518,9 @@ export class ProcessManager extends EventEmitter {
       });
       // 清空已读取的日志，避免重复分析
       info.logs = [];
+      // 同步重置增量扫描偏移：否则 scanErrorLogs 会把清空后新日志
+      // 误判为"已扫描"（logs.length < _errSeen 时 slice 到空），造成错误漏统计
+      info._errSeen = 0;
     }
     return result;
   }