tt-help-cli-ycl 1.4.76 → 1.4.79

package/package.json

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

package/src/clash/api.js

@@ -0,0 +1,168 @@
+/**
+ * Clash Verge (mihomo) RESTful API 客户端
+ *
+ * API 参考: https://wiki.metacubex.one/en/api
+ * 认证方式: Authorization: Bearer ${secret}
+ * 依赖 Clash Verge GUI 运行时绑定的 TCP 127.0.0.1:9097
+ */
+
+const BASE_URL = "http://127.0.0.1:9097";
+const SECRET = "abcdefg";
+
+function headers() {
+  return {
+    Authorization: `Bearer ${SECRET}`,
+    "Content-Type": "application/json",
+  };
+}
+
+async function request(path, options = {}) {
+  const url = `${BASE_URL}${path}`;
+  const res = await fetch(url, {
+    ...options,
+    headers: { ...headers(), ...options.headers },
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`HTTP ${res.status} ${res.statusText}: ${body}`);
+  }
+  if (res.status === 204) return null;
+  const text = await res.text();
+  return text ? JSON.parse(text) : null;
+}
+
+// ===== 代理相关 =====
+
+export async function getProxies() {
+  return request("/proxies");
+}
+
+export async function getProxy(name) {
+  return request(`/proxies/${encodeURIComponent(name)}`);
+}
+
+export async function switchProxy(groupName, nodeName) {
+  return request(`/proxies/${encodeURIComponent(groupName)}`, {
+    method: "PUT",
+    body: JSON.stringify({ name: nodeName }),
+  });
+}
+
+export async function getGroups() {
+  const data = await getProxies();
+  const proxies = data.proxies || {};
+  const groups = [];
+  const groupTypes = new Set([
+    "Selector",
+    "URLTest",
+    "Fallback",
+    "LoadBalance",
+  ]);
+  for (const [name, info] of Object.entries(proxies)) {
+    if (groupTypes.has(info.type)) {
+      groups.push({
+        name,
+        type: info.type,
+        now: info.now || "",
+        all: info.all || [],
+      });
+    }
+  }
+  return groups;
+}
+
+export async function getNodes() {
+  const data = await getProxies();
+  const proxies = data.proxies || {};
+  const nodes = [];
+  const groupTypes = new Set([
+    "Selector",
+    "URLTest",
+    "Fallback",
+    "LoadBalance",
+  ]);
+  for (const [name, info] of Object.entries(proxies)) {
+    if (!groupTypes.has(info.type)) {
+      nodes.push({
+        name,
+        type: info.type,
+        alive: info.alive ?? false,
+        delay:
+          info.history?.length > 0
+            ? info.history[info.history.length - 1].delay
+            : null,
+        udp: info.udp ?? false,
+      });
+    }
+  }
+  return nodes;
+}
+
+export async function getConfigs() {
+  return request("/configs");
+}
+export async function patchConfigs(patch) {
+  return request("/configs", { method: "PATCH", body: JSON.stringify(patch) });
+}
+export async function reloadConfigs() {
+  return request("/configs?force=true", { method: "PUT" });
+}
+export async function getVersion() {
+  return request("/version");
+}
+export async function getMemory() {
+  return request("/memory");
+}
+export async function getConnections() {
+  return request("/connections");
+}
+export async function closeConnection(id) {
+  return request(`/connections/${id}`, { method: "DELETE" });
+}
+export async function closeAllConnections() {
+  return request("/connections", { method: "DELETE" });
+}
+export async function getRules() {
+  return request("/rules");
+}
+export async function getProxyProviders() {
+  return request("/providers/proxies");
+}
+export async function updateProxyProvider(name) {
+  return request(`/providers/proxies/${encodeURIComponent(name)}`, {
+    method: "PUT",
+  });
+}
+export async function healthCheckProvider(name) {
+  return request(`/providers/proxies/${encodeURIComponent(name)}/healthcheck`);
+}
+
+export async function getCurrentNode(groupName) {
+  const proxy = await getProxy(groupName);
+  return proxy.now || null;
+}
+
+export async function listGroupNodes(groupName) {
+  const proxy = await getProxy(groupName);
+  return proxy.all || [];
+}
+
+export async function getAliveNodes() {
+  const nodes = await getNodes();
+  return nodes
+    .filter((n) => n.alive && n.delay !== null && n.delay > 0)
+    .sort((a, b) => (a.delay ?? Infinity) - (b.delay ?? Infinity));
+}
+
+export async function switchToFastest(groupName) {
+  const alive = await getAliveNodes();
+  if (alive.length === 0) throw new Error("没有存活的节点");
+  const groupNodes = await listGroupNodes(groupName);
+  for (const node of alive) {
+    if (groupNodes.includes(node.name)) {
+      await switchProxy(groupName, node.name);
+      return node;
+    }
+  }
+  throw new Error("存活节点都不在目标组中");
+}

package/src/clash/checker.js

@@ -0,0 +1,166 @@
+/**
+ * 节点健康检测 — 纯函数模块
+ *
+ * 职责：
+ *   1. 检测 Clash Verge 进程存活（跨平台 mac/win）
+ *   2. 检测当前代理节点对目标 URL 的健康状态
+ *   3. 健康节点列表持久化
+ *   4. 故障切换候选节点选取
+ */
+import { spawnSync } from "child_process";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const IS_WIN = process.platform === "win32";
+const HEALTHY_FILE = join(tmpdir(), "clash-healthy-nodes.json");
+
+export const CONFIG = {
+  testUrl: "https://www.tiktok.com/explore",
+  proxyUrl: "http://127.0.0.1:7897",
+  apiPort: 9097,
+  groupName: "GLOBAL",
+  curlTimeout: 12,
+  minPageSize: 50 * 1024,
+};
+
+// ---- 进程检测 ----
+
+export function checkClashAlive() {
+  try {
+    if (IS_WIN) {
+      const r = spawnSync(
+        "tasklist",
+        ["/FI", "IMAGENAME eq verge-mihomo.exe", "/NH"],
+        {
+          encoding: "utf-8",
+          timeout: 5000,
+          stdio: ["pipe", "pipe", "pipe"],
+        },
+      );
+      if (r.stdout?.includes("verge-mihomo.exe")) return true;
+    } else {
+      const r = spawnSync("pgrep", ["-x", "verge-mihomo"], {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      if (r.status === 0 && r.stdout.trim()) return true;
+    }
+  } catch {
+    /* fallthrough */
+  }
+
+  try {
+    const exe = IS_WIN ? "curl.exe" : "curl";
+    const r = spawnSync(
+      exe,
+      ["-s", "--max-time", "3", `http://127.0.0.1:${CONFIG.apiPort}/version`],
+      {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
+    return r.stdout.includes('"version"');
+  } catch {
+    return false;
+  }
+}
+
+// ---- 节点健康检测 ----
+
+export function checkNodeHealth(url = CONFIG.testUrl) {
+  const args = [
+    "-s",
+    "-w",
+    "\n__CURL_META__%{http_code}|%{time_total}|%{size_download}",
+    "--proxy",
+    CONFIG.proxyUrl,
+    "--max-time",
+    String(CONFIG.curlTimeout),
+    "-L",
+    "-A",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
+    url,
+  ];
+  const result = spawnSync("curl", args, {
+    encoding: "utf-8",
+    timeout: (CONFIG.curlTimeout + 5) * 1000,
+    stdio: ["pipe", "pipe", "pipe"],
+    maxBuffer: 10 * 1024 * 1024,
+  });
+
+  const stdout = result.stdout || "";
+  const idx = stdout.lastIndexOf("__CURL_META__");
+  let body = "",
+    metaLine = "";
+  if (idx >= 0) {
+    body = stdout.substring(0, idx).trimEnd();
+    metaLine = stdout.substring(idx + 13).trim();
+  }
+  const parts = metaLine.split("|");
+  const httpCode = parseInt(parts[0]) || 0;
+  const timeTotal = parseFloat(parts[1]) || 0;
+  const sizeDownload = parseInt(parts[2]) || 0;
+
+  let title = "";
+  const m = body.match(/<title>([^<]*)<\/title>/i);
+  if (m) title = m[1].trim();
+
+  let error = null;
+  if (result.error) error = result.error.message;
+  else if (result.status !== 0) error = `curl exit ${result.status}`;
+
+  const healthy =
+    !error &&
+    httpCode === 200 &&
+    sizeDownload >= CONFIG.minPageSize &&
+    title.includes("TikTok") &&
+    !title.startsWith("About |") &&
+    !body.includes("SlardarWAF") &&
+    !body.includes("_wafchallengeid");
+
+  return { healthy, httpCode, timeTotal, sizeDownload, title, error };
+}
+
+// ---- 健康节点列表持久化 ----
+
+export function loadHealthyList() {
+  try {
+    if (existsSync(HEALTHY_FILE)) {
+      const d = JSON.parse(readFileSync(HEALTHY_FILE, "utf-8"));
+      return {
+        updated: d.updated || "",
+        nodes: Array.isArray(d.nodes) ? d.nodes : [],
+      };
+    }
+  } catch (e) {
+    console.error(`[checker] 读取健康列表失败: ${e.message}`);
+  }
+  return { updated: "", nodes: [] };
+}
+
+export function saveHealthyList(nodes) {
+  try {
+    writeFileSync(
+      HEALTHY_FILE,
+      JSON.stringify({ updated: new Date().toISOString(), nodes }, null, 2),
+      "utf-8",
+    );
+  } catch (e) {
+    console.error(`[checker] 保存健康列表失败: ${e.message}`);
+  }
+}
+
+// ---- 故障切换候选选取 ----
+
+export function pickFailoverNode(currentNode, healthyNodes) {
+  if (!healthyNodes?.length) return null;
+  const candidates = healthyNodes.filter((n) => n !== currentNode);
+  if (!candidates.length) {
+    console.error(`[checker] 无可用候选节点（共${healthyNodes.length}个）`);
+    return null;
+  }
+  return candidates[Math.floor(Math.random() * candidates.length)];
+}

package/src/clash/daemon.js

@@ -0,0 +1,242 @@
+/**
+ * ClashDaemon — 代理节点健康守护
+ *
+ * 定时巡检当前节点 TikTok 可达性，异常时自动故障切换。
+ * 定期执行全量基准测速刷新健康节点列表。
+ * 通过 IPC 文件向 watchdog 上报状态。
+ */
+import { spawn } from "child_process";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { readFileSync, existsSync } from "fs";
+import * as api from "./api.js";
+import * as checker from "./checker.js";
+import * as ipc from "./ipc.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function findBenchmarkScript() {
+  const candidates = [
+    join(
+      __dirname,
+      "..",
+      "..",
+      "..",
+      "clash-verge-explore",
+      "speedtest-tiktok.mjs",
+    ),
+    join(__dirname, "speedtest-tiktok.mjs"),
+  ];
+  for (const p of candidates) if (existsSync(p)) return p;
+  return null;
+}
+
+export class ClashDaemon {
+  constructor(opts = {}) {
+    this.intervalMs = (opts.intervalSec || 30) * 1000;
+    this.benchmarkMs = (opts.benchmarkMin || 40) * 60 * 1000;
+    this.dryRun = !!opts.dryRun;
+    this.benchmarkScript = findBenchmarkScript();
+    this._running = false;
+    this._timers = [];
+    this._benchmarkRunning = false;
+  }
+
+  async start() {
+    if (this._running) return;
+    this._running = true;
+    this._logBanner();
+    this._setupSignals();
+
+    const list = checker.loadHealthyList();
+    const ageMin = list.updated
+      ? Math.round((Date.now() - new Date(list.updated).getTime()) / 60000)
+      : Infinity;
+    const isStale = !list.nodes.length || ageMin >= this.benchmarkMs / 60000;
+
+    if (list.nodes.length) {
+      this._log(
+        `已加载 ${list.nodes.length} 个健康节点${isStale ? ` (已过期 ${ageMin}min，立即刷新)` : ""}`,
+      );
+    } else {
+      this._log("健康列表为空，将立即执行基准测速");
+    }
+
+    await this._healthCheck();
+    this._timers.push(setInterval(() => this._healthCheck(), this.intervalMs));
+
+    const initial = isStale ? 5000 : this.benchmarkMs;
+    setTimeout(() => {
+      this._runBenchmark();
+      this._timers.push(
+        setInterval(() => this._runBenchmark(), this.benchmarkMs),
+      );
+    }, initial);
+
+    this._log("守护进程已启动");
+  }
+
+  async stop() {
+    this._running = false;
+    this._timers.forEach(clearInterval);
+    this._timers = [];
+    this._log("守护进程已停止");
+  }
+
+  // ---- 巡检 ----
+
+  async _healthCheck() {
+    if (!this._running || this._benchmarkRunning) return;
+    try {
+      if (!checker.checkClashAlive()) {
+        ipc.writeHealth({ node: "?", healthy: false, error: "Clash 未运行" });
+        return;
+      }
+      const node = await api
+        .getCurrentNode(checker.CONFIG.groupName)
+        .catch(() => "?");
+      const h = checker.checkNodeHealth();
+      ipc.writeHealth({
+        node,
+        healthy: h.healthy,
+        httpCode: h.httpCode,
+        timeTotal: h.timeTotal,
+        sizeDownload: h.sizeDownload,
+        title: h.title,
+      });
+
+      if (h.healthy) {
+        if (Math.random() < 0.17)
+          this._log(
+            `✓ ${h.timeTotal.toFixed(1)}s ${(h.sizeDownload / 1024).toFixed(0)}KB`,
+          );
+        return;
+      }
+
+      const reason =
+        h.error || `HTTP ${h.httpCode} ${(h.sizeDownload / 1024).toFixed(0)}KB`;
+      const { nodes } = checker.loadHealthyList();
+      const target = checker.pickFailoverNode(node, nodes);
+      if (!target) {
+        this._log(`✗ ${reason} — 无法切换`);
+        return;
+      }
+      if (this.dryRun) {
+        this._log(`[DRY-RUN] 应切换到 ${target}`);
+        return;
+      }
+
+      await api.switchProxy(checker.CONFIG.groupName, target);
+      await new Promise((r) => setTimeout(r, 600));
+      const h2 = checker.checkNodeHealth();
+      this._log(
+        `⚠ ${node} → ${target} (${h2.timeTotal.toFixed(1)}s ${(h2.sizeDownload / 1024).toFixed(0)}KB)`,
+      );
+      ipc.writeHealth({
+        node: target,
+        healthy: h2.healthy,
+        httpCode: h2.httpCode,
+        timeTotal: h2.timeTotal,
+        sizeDownload: h2.sizeDownload,
+        title: h2.title,
+        lastSwitch: `${node} → ${target}`,
+      });
+    } catch (e) {
+      this._log(`巡检异常: ${e.message}`);
+      ipc.writeHealth({ node: "?", healthy: false, error: e.message });
+    }
+  }
+
+  // ---- 基准 ----
+
+  _runBenchmark() {
+    if (!this.benchmarkScript || this._benchmarkRunning) return;
+    this._benchmarkRunning = true;
+    this._log("=== 基准测速开始 ===");
+    const start = Date.now();
+    const child = spawn(
+      process.execPath,
+      [this.benchmarkScript, "--timeout", "12"],
+      {
+        cwd: dirname(this.benchmarkScript),
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    let stderr = "";
+    child.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    child.on("close", (code) => {
+      this._benchmarkRunning = false;
+      const elapsed = ((Date.now() - start) / 1000).toFixed(0);
+      if (code === 0) {
+        try {
+          const rp = join(
+            dirname(this.benchmarkScript),
+            "speedtest-result.json",
+          );
+          if (existsSync(rp)) {
+            const nodes =
+              JSON.parse(readFileSync(rp, "utf-8")).realNodes?.map(
+                (r) => r.node,
+              ) || [];
+            if (nodes.length) {
+              checker.saveHealthyList(nodes);
+              this._log(
+                `=== 基准测速完成 (${elapsed}s): ${nodes.length} 个健康节点 ===`,
+              );
+            } else this._log(`=== 基准测速完成: 0 个健康节点 ===`);
+          }
+        } catch (e) {
+          this._log(`解析结果失败: ${e.message}`);
+        }
+      } else {
+        this._log(`=== 基准测速失败 (exit ${code}, ${elapsed}s) ===`);
+      }
+    });
+    child.on("error", (err) => {
+      this._benchmarkRunning = false;
+      this._log(`基准测速异常: ${err.message}`);
+    });
+  }
+
+  // ---- helpers ----
+
+  _log(msg) {
+    console.error(
+      `[daemon ${new Date().toLocaleTimeString("zh-CN", { hour12: false })}] ${msg}`,
+    );
+  }
+
+  _logBanner() {
+    console.error("═".repeat(50));
+    console.error("  Clash Verge 节点健康守护");
+    console.error(
+      `  检测: ${checker.CONFIG.testUrl}  |  巡检: ${this.intervalMs / 1000}s  |  基准: ${this.benchmarkMs / 60000}min`,
+    );
+    console.error(
+      `  基准脚本: ${this.benchmarkScript || "(不可用)"}  |  模式: ${this.dryRun ? "DRY-RUN" : "正常"}`,
+    );
+    console.error("═".repeat(50));
+  }
+
+  _setupSignals() {
+    const s = (sig) => {
+      this._log(`收到 ${sig}，退出`);
+      this.stop();
+      process.exit(0);
+    };
+    process.on("SIGINT", () => s("SIGINT"));
+    process.on("SIGTERM", () => s("SIGTERM"));
+  }
+}
+
+// 直接运行时（watchdog spawn 或 node daemon.js），自动启动
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const args = process.argv.slice(2);
+  new ClashDaemon({
+    intervalSec: parseInt(args[args.indexOf("--interval") + 1]) || undefined,
+    benchmarkMin: parseInt(args[args.indexOf("--benchmark") + 1]) || undefined,
+    dryRun: args.includes("--dry-run"),
+  }).start();
+}

package/src/clash/health-checker.js

@@ -0,0 +1,248 @@
+/**
+ * 节点健康检测模块
+ *
+ * 职责：
+ *   1. 检测 Clash Verge 进程是否存活
+ *   2. 检测当前节点对目标 URL 是否健康
+ *   3. 故障切换：从健康节点列表中随机选取并切换
+ *   4. 健康节点列表持久化
+ */
+
+import { spawnSync } from "child_process";
+import * as api from "./api.js";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const HEALTHY_FILE = join(tmpdir(), "clash-healthy-nodes.json");
+
+// ====== 可配置参数 ======
+export const CONFIG = {
+  testUrl: "https://www.tiktok.com/explore",
+  proxyUrl: "http://127.0.0.1:7897",
+  apiPort: 9097,
+  groupName: "GLOBAL",
+  curlTimeout: 12,
+  minPageSize: 50 * 1024,
+};
+
+// ====== 进程检测（跨平台 mac/win） ======
+
+const IS_WIN = process.platform === "win32";
+
+export function checkClashAlive() {
+  try {
+    if (IS_WIN) {
+      const result = spawnSync(
+        "tasklist",
+        ["/FI", "IMAGENAME eq verge-mihomo.exe", "/NH"],
+        {
+          encoding: "utf-8",
+          timeout: 5000,
+          stdio: ["pipe", "pipe", "pipe"],
+        },
+      );
+      if (result.stdout && result.stdout.includes("verge-mihomo.exe"))
+        return true;
+    } else {
+      const result = spawnSync("pgrep", ["-x", "verge-mihomo"], {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      if (result.status === 0 && result.stdout.trim()) return true;
+    }
+  } catch {
+    /* fallthrough */
+  }
+
+  try {
+    const curlExe = IS_WIN ? "curl.exe" : "curl";
+    const result = spawnSync(
+      curlExe,
+      ["-s", "--max-time", "3", `http://127.0.0.1:${CONFIG.apiPort}/version`],
+      {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
+    return result.stdout.includes('"version"');
+  } catch {
+    return false;
+  }
+}
+
+// ====== 节点健康检测 ======
+
+export function checkNodeHealth(url = CONFIG.testUrl) {
+  const args = [
+    "-s",
+    "-w",
+    "\n__CURL_META__%{http_code}|%{time_total}|%{size_download}",
+    "--proxy",
+    CONFIG.proxyUrl,
+    "--max-time",
+    String(CONFIG.curlTimeout),
+    "-L",
+    "-A",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
+    url,
+  ];
+
+  const result = spawnSync("curl", args, {
+    encoding: "utf-8",
+    timeout: (CONFIG.curlTimeout + 5) * 1000,
+    stdio: ["pipe", "pipe", "pipe"],
+    maxBuffer: 10 * 1024 * 1024,
+  });
+
+  const stdout = result.stdout || "";
+  const sentinel = "__CURL_META__";
+  const idx = stdout.lastIndexOf(sentinel);
+
+  let body = "",
+    metaLine = "";
+  if (idx >= 0) {
+    body = stdout.substring(0, idx).trimEnd();
+    metaLine = stdout.substring(idx + sentinel.length).trim();
+  }
+
+  const parts = metaLine.split("|");
+  const httpCode = parseInt(parts[0]) || 0;
+  const timeTotal = parseFloat(parts[1]) || 0;
+  const sizeDownload = parseInt(parts[2]) || 0;
+
+  let title = "";
+  const titleMatch = body.match(/<title>([^<]*)<\/title>/i);
+  if (titleMatch) title = titleMatch[1].trim();
+
+  let error = null;
+  if (result.error) {
+    error = result.error.message || "spawn error";
+  } else if (result.status !== 0) {
+    error = `curl exit ${result.status}`;
+  }
+
+  const healthy =
+    error === null &&
+    httpCode === 200 &&
+    sizeDownload >= CONFIG.minPageSize &&
+    title.includes("TikTok") &&
+    !title.startsWith("About |") &&
+    !body.includes("SlardarWAF") &&
+    !body.includes("_wafchallengeid");
+
+  return { healthy, httpCode, timeTotal, sizeDownload, title, error };
+}
+
+// ====== 健康节点列表持久化 ======
+
+export function loadHealthyList() {
+  try {
+    if (existsSync(HEALTHY_FILE)) {
+      const data = JSON.parse(readFileSync(HEALTHY_FILE, "utf-8"));
+      return {
+        updated: data.updated || "",
+        nodes: Array.isArray(data.nodes) ? data.nodes : [],
+      };
+    }
+  } catch (e) {
+    console.error(`[health] 读取健康列表失败: ${e.message}`);
+  }
+  return { updated: "", nodes: [] };
+}
+
+export function saveHealthyList(nodes) {
+  try {
+    const data = { updated: new Date().toISOString(), nodes };
+    writeFileSync(HEALTHY_FILE, JSON.stringify(data, null, 2), "utf-8");
+  } catch (e) {
+    console.error(`[health] 保存健康列表失败: ${e.message}`);
+  }
+}
+
+// ====== 故障切换 ======
+
+export function pickFailoverNode(currentNode, healthyNodes) {
+  if (!healthyNodes || healthyNodes.length === 0) return null;
+  const candidates = healthyNodes.filter((n) => n !== currentNode);
+  if (candidates.length === 0) {
+    console.error(
+      `[health] 健康列表中无可用候选节点（共${healthyNodes.length}个），保持在当前节点`,
+    );
+    return null;
+  }
+  const idx = Math.floor(Math.random() * candidates.length);
+  return candidates[idx];
+}
+
+export async function switchToNode(nodeName) {
+  try {
+    await api.switchProxy(CONFIG.groupName, nodeName);
+    await new Promise((r) => setTimeout(r, 600));
+    const current = await api.getCurrentNode(CONFIG.groupName);
+    if (current !== nodeName) {
+      console.error(`[health] 切换验证失败: 期望 ${nodeName}, 实际 ${current}`);
+      return false;
+    }
+    return true;
+  } catch (e) {
+    console.error(`[health] 切换节点失败: ${e.message}`);
+    return false;
+  }
+}
+
+// ====== 便捷入口 ======
+
+export async function runHealthCheck() {
+  if (!checkClashAlive()) {
+    return { action: "skipped", detail: "Clash Verge 未运行" };
+  }
+
+  const health = checkNodeHealth();
+  if (health.healthy) {
+    return {
+      action: "ok",
+      detail: `${health.timeTotal.toFixed(1)}s ${(health.sizeDownload / 1024).toFixed(0)}KB`,
+    };
+  }
+
+  const reason = health.error
+    ? `错误: ${health.error}`
+    : `HTTP ${health.httpCode} ${(health.sizeDownload / 1024).toFixed(0)}KB "${health.title}"`;
+
+  let currentNode = "";
+  try {
+    currentNode = await api.getCurrentNode(CONFIG.groupName);
+  } catch (e) {
+    return { action: "failed", detail: `无法获取当前节点: ${e.message}` };
+  }
+
+  const { nodes: healthyNodes } = loadHealthyList();
+  if (healthyNodes.length === 0) {
+    return { action: "failed", detail: `${reason} — 健康列表为空，无法切换` };
+  }
+
+  const target = pickFailoverNode(currentNode, healthyNodes);
+  if (!target) {
+    return { action: "failed", detail: `${reason} — 无可用候选节点` };
+  }
+
+  const switched = await switchToNode(target);
+  if (!switched) {
+    return { action: "failed", detail: `${reason} → 切换到 ${target} 失败` };
+  }
+
+  const newHealth = checkNodeHealth();
+  if (newHealth.healthy) {
+    return {
+      action: "switched",
+      detail: `${currentNode} → ${target} (${newHealth.timeTotal.toFixed(1)}s ${(newHealth.sizeDownload / 1024).toFixed(0)}KB)`,
+    };
+  }
+  return {
+    action: "switched",
+    detail: `${currentNode} → ${target} (切换后仍异常: ${newHealth.httpCode} ${(newHealth.sizeDownload / 1024).toFixed(0)}KB)`,
+  };
+}

package/src/clash/index.js

@@ -0,0 +1,7 @@
+/**
+ * Clash 模块统一入口
+ */
+export { ClashDaemon } from "./daemon.js";
+export * as api from "./api.js";
+export * as checker from "./checker.js";
+export * as ipc from "./ipc.js";

package/src/clash/ipc.js

@@ -0,0 +1,75 @@
+/**
+ * 文件 IPC 模块
+ *
+ * 与 watchdog 进程间通信，通过 tmpdir 下的 JSON 文件。
+ *
+ *   clash-health.json  — daemon → watchdog（代理健康状态）
+ *   clash-cmd.json     — watchdog → daemon（远程命令，预留）
+ */
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const HEALTH_FILE = join(tmpdir(), "clash-health.json");
+const CMD_FILE = join(tmpdir(), "clash-cmd.json");
+
+// ---- health（daemon → watchdog） ----
+
+export function writeHealth(state) {
+  try {
+    writeFileSync(
+      HEALTH_FILE,
+      JSON.stringify(
+        {
+          ...state,
+          lastCheck: new Date().toISOString(),
+        },
+        null,
+        2,
+      ),
+      "utf-8",
+    );
+  } catch {
+    /* 非关键路径 */
+  }
+}
+
+export function readHealth() {
+  try {
+    if (!existsSync(HEALTH_FILE)) return null;
+    const data = JSON.parse(readFileSync(HEALTH_FILE, "utf-8"));
+    const age = Date.now() - new Date(data.lastCheck || 0).getTime();
+    return {
+      ...data,
+      stale: age > 120_000,
+      ageSeconds: Math.round(age / 1000),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ---- command（watchdog → daemon，预留） ----
+
+export function writeCommand(cmd) {
+  try {
+    writeFileSync(CMD_FILE, JSON.stringify(cmd, null, 2), "utf-8");
+  } catch {
+    /* 非关键路径 */
+  }
+}
+
+export function readCommand() {
+  try {
+    if (!existsSync(CMD_FILE)) return null;
+    return JSON.parse(readFileSync(CMD_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function clearCommand() {
+  try {
+    if (existsSync(CMD_FILE)) writeFileSync(CMD_FILE, "{}", "utf-8");
+  } catch {}
+}

package/src/cli/clash-daemon.js

@@ -0,0 +1,18 @@
+/**
+ * clash-daemon CLI 命令入口
+ *
+ * 用法: tt-help clash-daemon [--interval 30] [--benchmark 40] [--dry-run]
+ */
+import { ClashDaemon } from "../clash/daemon.js";
+
+export async function handleClashDaemon(options) {
+  const d = new ClashDaemon({
+    intervalSec: parseInt(options.interval) || undefined,
+    benchmarkMin: parseInt(options.benchmark) || undefined,
+    dryRun:
+      options["dry-run"] === "" ||
+      options["dry-run"] === true ||
+      process.argv.includes("--dry-run"),
+  });
+  await d.start();
+}

package/src/lib/args.js

@@ -655,6 +655,40 @@ function parseWatchdogArgs(args) {
   };
 }
 
+function parseClashDaemonArgs(args) {
+  let interval = 30;
+  let benchmark = 40;
+  let dryRun = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--interval") {
+      interval = parseInt(args[++i]) || 30;
+    } else if (arg === "--benchmark") {
+      benchmark = parseInt(args[++i]) || 40;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    }
+  }
+
+  return {
+    subcommand: "clash-daemon",
+    interval,
+    benchmark,
+    "dry-run": dryRun,
+    urls: [],
+    outputFormat: "json",
+    exploreCount: 0,
+    showConfig: false,
+    showHelp: false,
+    customProxy: null,
+    configAction: null,
+    configValue: null,
+    pipeMode: false,
+    filterStr: null,
+  };
+}
+
 function parseAttachArgs(args) {
   let parallel = 1;
   let interval = 10;
@@ -1362,6 +1396,10 @@ export function parseArgs() {
     return parseWatchdogArgs(args.slice(1));
   }
 
+  if (args.length > 0 && args[0] === "clash-daemon") {
+    return parseClashDaemonArgs(args.slice(1));
+  }
+
   if (args.length > 0 && args[0] === "precheck") {
     return parsePrecheckArgs(args.slice(1));
   }

package/src/main.js

@@ -23,6 +23,7 @@ import {
 import { handleRawSync } from "./cli/raw-sync.js";
 import { handleSearch } from "./cli/search.js";
 import { handleWatchdog } from "./cli/watchdog.js";
+import { handleClashDaemon } from "./cli/clash-daemon.js";
 
 async function main() {
   const parsed = parseArgs();
@@ -68,6 +69,8 @@ async function main() {
       return handleSearch(parsed);
     case "watchdog":
       return handleWatchdog(parsed);
+    case "clash-daemon":
+      return handleClashDaemon(parsed);
   }
 
   const {

package/src/watchdog/agent.js

@@ -42,7 +42,11 @@ function findDaemonPath() {
     }
   } catch {}
 
-  // 2. 相对于 tiktok-cli 同级目录
+  // 2. 内部打包路径（npm publish 后 src/clash/daemon.js）
+  const internalPath = join(__dirname, "..", "clash", "daemon.js");
+  if (existsSync(internalPath)) return internalPath;
+
+  // 3. 开发模式：clash-verge-explore 同级目录
   const candidates = [
     join(__dirname, "..", "..", "..", "clash-verge-explore", "daemon.js"),
     join(__dirname, "..", "..", "..", "..", "clash-verge-explore", "daemon.js"),

package/src/webserver/server.mjs

@@ -35,6 +35,14 @@ function sendJSON(res, status, data) {
 
 const MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB
 
+function getClientIP(req) {
+  return (
+    req.headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
+    req.socket.remoteAddress ||
+    ""
+  );
+}
+
 function readBody(req) {
   return new Promise((resolve, reject) => {
     let body = "";
@@ -73,6 +81,11 @@ let consecutiveErrors = 0;
 const MAX_CONSECUTIVE_ERRORS = 10;
 let warmTimer = null;
 let lastWarmTime = 0;
+// 滑动窗口错误率追踪（用于 /health 上报，不触发重启）
+let recentTotal = 0;
+let recentErrors = 0;
+let recentWindowStart = Date.now();
+const RECENT_WINDOW_MS = 60000; // 60 秒滑动窗口
 
 async function getScraper() {
   if (scraperInstance && !scraperClosing) {
@@ -100,6 +113,23 @@ async function getScraper() {
   }
 }
 
+function recordRequest(success) {
+  const now = Date.now();
+  if (now - recentWindowStart > RECENT_WINDOW_MS) {
+    recentTotal = 0;
+    recentErrors = 0;
+    recentWindowStart = now;
+  }
+  recentTotal++;
+  if (!success) recentErrors++;
+  if (success) consecutiveErrors = 0;
+}
+
+function isDegraded() {
+  // 仅当 scraper 正在恢复/关闭中才算降级，初始冷状态不算
+  return scraperClosing || scraperInitPromise !== null;
+}
+
 async function restartScraper(reason) {
   console.error(`[webserver] 重启 scraper: ${reason}`);
   if (scraperInstance) {
@@ -156,13 +186,39 @@ async function handleTiktokUser(req, res) {
   if (!body.uniqueId) {
     return sendJSON(res, 400, { error: "missing uniqueId" });
   }
+  const clientIP = getClientIP(req);
+  const startTime = Date.now();
   const scraper = await getScraper();
   const result = await scraper.getUserInfo(body.uniqueId);
+  const elapsed = Date.now() - startTime;
+
   if (!result) {
-    return sendJSON(res, 404, {
-      error: "User not found or failed to parse data",
+    console.error(
+      `[webserver] user FAIL | ${clientIP} | @${body.uniqueId} | ${elapsed}ms | empty SSR / parse failed`,
+    );
+    recordRequest(false);
+    return sendJSON(res, 503, {
+      error: "Temporary failure: unable to fetch user data",
+      retryable: true,
     });
   }
+
+  if (result.error) {
+    console.error(
+      `[webserver] user FAIL | ${clientIP} | @${body.uniqueId} | ${elapsed}ms | TikTok statusCode=${result.statusCode}`,
+    );
+    recordRequest(false);
+    return sendJSON(res, 502, {
+      error: `TikTok error (statusCode=${result.statusCode})`,
+      retryable: false,
+      tiktokStatusCode: result.statusCode,
+    });
+  }
+
+  console.error(
+    `[webserver] user OK | ${clientIP} | @${body.uniqueId} | ${elapsed}ms | verified=${result.verified} followers=${result.followerCount}`,
+  );
+  recordRequest(true);
   return sendJSON(res, 200, result);
 }
 
@@ -171,13 +227,27 @@ async function handleTiktokVideo(req, res) {
   if (!body.videoUrl) {
     return sendJSON(res, 400, { error: "missing videoUrl" });
   }
+  const clientIP = getClientIP(req);
+  const startTime = Date.now();
   const scraper = await getScraper();
   const result = await scraper.getVideoInfo(body.videoUrl);
+  const elapsed = Date.now() - startTime;
+
   if (!result) {
-    return sendJSON(res, 404, {
-      error: "Video not found or failed to parse data",
+    console.error(
+      `[webserver] video FAIL | ${clientIP} | ${body.videoUrl.slice(0, 60)} | ${elapsed}ms | empty SSR / parse failed`,
+    );
+    recordRequest(false);
+    return sendJSON(res, 503, {
+      error: "Temporary failure: unable to fetch video data",
+      retryable: true,
     });
   }
+
+  console.error(
+    `[webserver] video OK | ${clientIP} | @${result.author?.uniqueId || "?"} | ${elapsed}ms | plays=${result.stats?.playCount}`,
+  );
+  recordRequest(true);
   return sendJSON(res, 200, result);
 }
 
@@ -186,13 +256,27 @@ async function handleTiktokLookup(req, res) {
   if (!body.videoUrl) {
     return sendJSON(res, 400, { error: "missing videoUrl" });
   }
+  const clientIP = getClientIP(req);
+  const startTime = Date.now();
   const scraper = await getScraper();
   const result = await scraper.getUserAndVideo(body.videoUrl);
+  const elapsed = Date.now() - startTime;
+
   if (!result) {
-    return sendJSON(res, 404, {
-      error: "Video not found or failed to parse data",
+    console.error(
+      `[webserver] lookup FAIL | ${clientIP} | ${body.videoUrl.slice(0, 60)} | ${elapsed}ms | empty SSR / parse failed`,
+    );
+    recordRequest(false);
+    return sendJSON(res, 503, {
+      error: "Temporary failure: unable to fetch video/user data",
+      retryable: true,
     });
   }
+
+  console.error(
+    `[webserver] lookup OK | ${clientIP} | @${result.user?.uniqueId || "?"} | ${elapsed}ms | videoId=${result.video?.id}`,
+  );
+  recordRequest(true);
   return sendJSON(res, 200, result);
 }
 
@@ -201,10 +285,7 @@ async function handleTiktokProduct(req, res) {
   if (!body.url) {
     return sendJSON(res, 400, { error: "missing url" });
   }
-  const clientIP =
-    req.headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
-    req.socket.remoteAddress ||
-    "";
+  const clientIP = getClientIP(req);
   // URL 标准化：www.tiktok.com/shop/pdp → shop.tiktok.com/us/pdp
   const normalizedUrl = body.url.replace(
     "www.tiktok.com/shop/pdp",
@@ -221,18 +302,41 @@ async function handleTiktokProduct(req, res) {
     console.error(
       `[webserver] product OK | ${clientIP} | rating=${result.rating ?? "-"} sold=${result.soldCount ?? "-"} name=${(result.productName || "").slice(0, 40)}`,
     );
+    recordRequest(true);
     return sendJSON(res, 200, result);
   } catch (e) {
     console.error(`[webserver] product FAIL | ${clientIP} | ${e.message}`);
+    recordRequest(false);
 
-    // 如果是 captcha，先触发上报+恢复（不阻塞其他请求）
-    // 必须在 sendJSON 之前调用，否则 sendJSON 抛异常会导致验证码通知丢失
+    // captcha：触发上报+恢复（不阻塞其他请求），返回 503 让 nginx 可 failover
     if (e.message?.includes("Blocked by TikTok")) {
       scheduleCaptchaRecovery(normalizedUrl, SCRAPER_CONFIG.proxyServer);
+      return sendJSON(res, 503, {
+        error: "Blocked by TikTok security check (captcha)",
+        retryable: true,
+      });
     }
 
-    sendJSON(res, 502, { error: e.message });
-    return;
+    // 网络超时类错误 → 504
+    if (
+      e.name === "HeadersTimeoutError" ||
+      e.name === "BodyTimeoutError" ||
+      e.message?.includes("timeout") ||
+      e.message?.includes("ETIMEDOUT") ||
+      e.message?.includes("ECONNREFUSED") ||
+      e.message?.includes("ECONNRESET")
+    ) {
+      return sendJSON(res, 504, {
+        error: `Upstream timeout or network error: ${e.message}`,
+        retryable: true,
+      });
+    }
+
+    // 其他上游错误 → 502
+    return sendJSON(res, 502, {
+      error: e.message,
+      retryable: true,
+    });
   }
 }
 
@@ -311,10 +415,16 @@ async function scheduleCaptchaRecovery(url, proxy) {
 }
 
 function handleHealth(req, res) {
-  return sendJSON(res, 200, {
-    status: "ok",
+  const degraded = isDegraded();
+  const recentErrorRate = recentTotal > 0 ? recentErrors / recentTotal : 0;
+  return sendJSON(res, degraded ? 503 : 200, {
+    status: degraded ? "degraded" : "ok",
     scraperReady: scraperInstance !== null && !scraperClosing,
+    scraperInitializing: scraperInitPromise !== null,
     consecutiveErrors,
+    recentErrorRate: Math.round(recentErrorRate * 100) / 100,
+    recentTotal,
+    recentErrors,
     lastWarmSec: lastWarmTime
       ? Math.round((Date.now() - lastWarmTime) / 1000)
       : null,
@@ -384,11 +494,48 @@ export async function startWebserver(
     } catch (e) {
       // 自动恢复：连续错误超过阈值时重启 scraper
       consecutiveErrors++;
+      recordRequest(false);
+
+      // 区分错误类型，返回正确的 HTTP 状态码供 nginx 判断
+      let status = 500;
+      let retryable = false;
+
+      if (e.name === "CDNBlockedError") {
+        // CDN 限流（Akamai Access Denied）→ 503 临时不可用
+        status = 503;
+        retryable = true;
+      } else if (e.message?.includes("Server is shutting down")) {
+        // 服务正在关闭 → 503
+        status = 503;
+        retryable = true;
+      } else if (
+        e.message?.includes("Timeout") ||
+        e.message?.includes("timeout") ||
+        e.name === "TimeoutError"
+      ) {
+        // 超时 → 504
+        status = 504;
+        retryable = true;
+      } else if (
+        e.message?.includes("Protocol error") ||
+        e.message?.includes("Target closed") ||
+        e.message?.includes("Browser closed") ||
+        e.message?.includes("Session closed")
+      ) {
+        // 浏览器/页面崩溃 → 503
+        status = 503;
+        retryable = true;
+      }
+
       if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
         await restartScraper(`连续 ${consecutiveErrors} 次错误`);
       }
+
       if (!res.headersSent) {
-        return sendJSON(res, 500, { error: e.message });
+        return sendJSON(res, status, {
+          error: e.message,
+          retryable,
+        });
       }
       // 响应已发送（流式等场景），记录日志并销毁 socket
       console.error(