tt-help-cli-ycl 1.4.166 → 1.4.168

package/src/clash/checker.js

@@ -5,7 +5,7 @@
  *   1. 检测 Clash Verge 进程/API 存活（跨平台 mac/win）
  *   2. 自动发现代理端口（GET /configs → mixed-port）
  *   3. 节点健康检测（curl 穿透代理请求 TikTok）
- *   4. 国家过滤（按节点名 emoji 匹配）
+ *   4. 国家过滤（全词文本 + emoji 国旗 + 单字方言三层匹配）
  *   5. 健康节点列表持久化 + 故障切换
  *   6. CLI 入口硬门控预检
  */
@@ -311,18 +311,95 @@ export function normalizeCountries(v) {
   return [];
 }
 
-/** 把国家过滤值归一化为匹配模式数组（多国取并集），未知国家自动忽略 */
-function getCountryPatterns(country) {
-  const pats = normalizeCountries(country)
-    .map((c) => COUNTRY_PATTERNS[c])
-    .filter(Boolean);
-  return pats.length ? pats : null;
+// ── 层2：emoji 国旗（全局启用）──
+// 国旗是 regional indicator 成对编码（🇩🇪 = U+1F1E9 U+1F1EA），无歧义，
+// 比节点名文本更可靠。7899/topman 类机场节点名只有国旗或单字缩写
+// （S德🇩🇪56、🇭🇰261008节点、S0港🇭🇰4），全词文本模式全部落空（实测 0/20）。
+// 偏召回设计：公告伪节点误认由 delay 初测淘汰，漏检则永远进不了候选集。
+const FLAG_RE = /[\u{1F1E6}-\u{1F1FF}]{2}/u;
+const FLAG_OFFSET = 0x1f1e6 - 65; // regional indicator → 大写字母
+
+/** emoji 国旗 → ISO 国家码，无旗返回 null */
+export function matchCountryByEmoji(name) {
+  const m = String(name || "").match(FLAG_RE);
+  if (!m) return null;
+  const [a, b] = [...m[0]].map((ch) => ch.codePointAt(0) - FLAG_OFFSET);
+  return String.fromCharCode(a, b);
+}
+
+// ── 层3：单字缩写（按方言门控）──
+// 误伤半径大，仅在检测到方言命名风格的订阅上启用（见 detectSingleCharDialect）。
+// 刻意不含 新/加/印/台/澳 等高歧义单字（新节点/加速器/打印/平台/澳门）
+const SINGLE_CHAR_PATTERNS = {
+  美: "US",
+  英: "GB",
+  法: "FR",
+  德: "DE",
+  日: "JP",
+  韩: "KR",
+  港: "HK",
+  俄: "RU",
+};
+
+// 单字边界：前后不得紧邻其他汉字 —— 放行 "S美🇺🇸86"/"S0港4"/"TEST日🇯🵵10"，
+// 排除全词（"美国"/"香港"，层1已覆盖）与嵌字（"完美网络"不含国家义）
+const SINGLE_CHAR_BOUNDARY_RE = /(^|[^一-鿿])[美德日韩港英法俄](?![一-鿿])/;
+
+// 预编译：国家码 → 单字边界正则数组
+const SINGLE_CHAR_RES = {};
+for (const [ch, c] of Object.entries(SINGLE_CHAR_PATTERNS)) {
+  (SINGLE_CHAR_RES[c] ??= []).push(
+    new RegExp(`(^|[^一-鿿])${ch}(?![一-鿿])`),
+  );
+}
+
+// "仅靠 emoji 可识别（全词文本不命中）"的节点占比 ≥ 阈值 → emoji/单字方言机场。
+// 老机场命名带全词（"🇺🇸美国HY1"）文本层即可命中，占比≈0；topman 类占比 >0.6
+const DIALECT_MIN_RATIO = 0.3;
+const DIALECT_MIN_SAMPLE = 5; // 样本太少不判定，避免小列表误翻转
+
+/**
+ * 方言探测：该订阅是否属于 emoji/单字命名风格（决定单字层是否启用）。
+ * 两路信号取大者：① 仅靠 emoji 可识别（全词文本不命中）占比 —— topman 类；
+ * ② 单字边界风格占比 —— 兼顾无 emoji 纯单字缩写的机场。
+ * 老机场（"🇺🇸美国HY1"）两路占比均≈0，单字层不启用、行为与旧版一致
+ * @param {string[]} nodes 全量节点名
+ */
+function detectSingleCharDialect(nodes) {
+  const usable = (Array.isArray(nodes) ? nodes : []).filter(isUsableProxyNode);
+  if (usable.length < DIALECT_MIN_SAMPLE) return false;
+  let emojiOnly = 0;
+  let singleCharStyle = 0;
+  for (const n of usable) {
+    const code = matchCountryByEmoji(n);
+    const pat = code && COUNTRY_PATTERNS[code];
+    if (pat && !pat.test(n)) emojiOnly++;
+    if (SINGLE_CHAR_BOUNDARY_RE.test(n)) singleCharStyle++;
+  }
+  const ratio = Math.max(emojiOnly, singleCharStyle) / usable.length;
+  return ratio >= DIALECT_MIN_RATIO;
+}
+
+/** 单节点是否命中指定国家的任一匹配层（emoji / 全词文本 / 单字方言） */
+function matchNodeCountry(name, code, useSingleChar) {
+  if (matchCountryByEmoji(name) === code) return true;
+  const pat = COUNTRY_PATTERNS[code];
+  if (pat && pat.test(name)) return true;
+  if (useSingleChar) {
+    for (const re of SINGLE_CHAR_RES[code] || []) {
+      if (re.test(String(name))) return true;
+    }
+  }
+  return false;
 }
 
 export function filterNodesByCountry(nodes, country) {
-  const pats = getCountryPatterns(country);
-  if (!pats) return { filtered: nodes, excluded: 0 };
-  const filtered = nodes.filter((n) => pats.some((p) => p.test(n)));
+  const countries = normalizeCountries(country);
+  if (!countries.length) return { filtered: nodes, excluded: 0 };
+  const useSingleChar = detectSingleCharDialect(nodes);
+  const filtered = nodes.filter((n) =>
+    countries.some((c) => matchNodeCountry(n, c, useSingleChar)),
+  );
   return { filtered, excluded: nodes.length - filtered.length };
 }
 
@@ -349,15 +426,20 @@ const BUILTIN_POLICY_NAMES = new Set([
 const INFO_NODE_PATTERN =
   /剩余|流量|到期|过期|官网|重置|套餐|订阅|工单|[\d.]\s*[KMGTP]B$/i;
 
-/**
- * 判定节点名是否可用作业务出口（内置策略与机场信息节点返回 false）
- * 在候选集写口（runDelayProbe）与读口（loadHealthyList）统一调用
+// []【】()（）注解段。机场常把"实时更新订阅/0倍率/移动优化"等字样放进注解，
+// 主名才是节点标识。信息节点判定只看主名，避免注解关键词误杀真节点
+// （2026-01 生产实锤：S韩🇰🇷55[实时更新订阅]、🇺🇸 2[0倍率][实时更新订阅] 被"订阅"误杀）
+const ANNOTATION_RE = /\[[^\]]*\]|【[^】]*】|\([^)]*\)|（[^）]*）/g;
+
+/** 判定节点名是否可用作业务出口（内置策略与机场信息节点返回 false）
+ *  在候选集写口（runDelayProbe）与读口（loadHealthyList）统一调用
  */
 export function isUsableProxyNode(name) {
   const n = String(name || "").trim();
   if (!n) return false;
   if (BUILTIN_POLICY_NAMES.has(n.toUpperCase())) return false;
-  if (INFO_NODE_PATTERN.test(n)) return false;
+  // 信息节点只看主名：注解里的"订阅/更新"等字样不算（见 ANNOTATION_RE 注释）
+  if (INFO_NODE_PATTERN.test(n.replace(ANNOTATION_RE, " "))) return false;
   return true;
 }
 

package/src/cli/attach.js

@@ -160,13 +160,26 @@ export async function handleAttach(options) {
         data = await res.json();
       } catch {}
       if (!res.ok) {
-        // CDN 限流：抛 CDNBlockedError，外层据此冷却（webserver 模式同样生效）
+        // CDN 限流：抛 CDNBlockedError，外层据此冷却（webserver 模式同样生效）。
+        // 服务端冷却期返回 503 + error="CDN cooldown active, cooling IP"（server.mjs），
+        // 并携带 cdnCooldownSec=剩余秒数，一并识别；秒数挂到 err.serverCooldownSec
+        // 供外层精确对齐冷却窗口，避免冷却期整批空转猛冲。
         if (
           data &&
           typeof data.error === "string" &&
-          data.error.includes("CDN限流")
+          (data.error.includes("CDN限流") ||
+            data.error.includes("CDN cooldown"))
         ) {
-          throw new CDNBlockedError(data.error);
+          const cdnErr = new CDNBlockedError(data.error);
+          if (data.cdnCooldownSec > 0)
+            cdnErr.serverCooldownSec = data.cdnCooldownSec;
+          throw cdnErr;
+        }
+        if (data && data.cdnCooldownSec > 0) {
+          // 文案兜底：只要响应带冷却秒数字段就按 CDN 限流处理
+          const cdnErr = new CDNBlockedError("CDN限流 (cooldown)");
+          cdnErr.serverCooldownSec = data.cdnCooldownSec;
+          throw cdnErr;
         }
         // 其余失败（504 超时 / 503 / 502 / 500 等）：抛出带状态码与错误详情的异常，
         // 让外层日志显示真实原因（如 page.goto 超时）而非笼统"未获取到用户信息"。
@@ -221,6 +234,7 @@ export async function handleAttach(options) {
     let browserRestartCount = 0;
     let taskBatchCount = 0;
     let consecutiveCdnBlocks = 0; // 连续 CDN 限流轮数（自适应：前几次切换节点，之后长等待）
+    let consecutiveHighFail = 0; // 连续高失败率轮数（webserver 模式通用阶梯冷却）
 
     while (!shuttingDown) {
       loopCount++;
@@ -299,6 +313,7 @@ export async function handleAttach(options) {
       let successCount = 0;
       let failCount = 0;
       let cdnBlockedCount = 0;
+      let serverCdnCooldownSec = 0; // 服务端告知的剩余冷却秒数（webserver 503 响应携带）
       let needRestart = false;
 
       // 收集抓取成功的任务，记录抓取失败的
@@ -308,8 +323,16 @@ export async function handleAttach(options) {
           const { uniqueId, info, error } = result.value;
           if (error) {
             if (error instanceof CDNBlockedError) {
-              attachLog(`  ⚠ @${uniqueId} CDN限流 (Access Denied)`);
+              attachLog(
+                error.serverCooldownSec
+                  ? `  ⚠ @${uniqueId} CDN限流 (服务端冷却中，剩余 ${error.serverCooldownSec}s)`
+                  : `  ⚠ @${uniqueId} CDN限流 (Access Denied)`,
+              );
               cdnBlockedCount++;
+              serverCdnCooldownSec = Math.max(
+                serverCdnCooldownSec,
+                error.serverCooldownSec || 0,
+              );
               failCount++;
             } else if (isBrowserClosedError(error)) {
               needRestart = true;
@@ -384,9 +407,13 @@ export async function handleAttach(options) {
 
       attachLog(`  本批结果: ${successCount} 成功, ${failCount} 失败\n`);
 
-      // CDN 限流比例超过 30% 时：自适应策略（前几次切节点，连续限流则长等待）
+      // 失败率冷却策略：
+      // - 本地浏览器模式（scraper）：CDN 限流 >30% 触发切节点 + 冷却（主动绕过）
+      // - webserver 模式：统一按总失败率阶梯冷却（出口在远端，分类对客户端无意义，
+      //   唯一手段是等；冷却期服务端 503 会带 cdnCooldownSec，优先精确对齐窗口）
       const cdnRatio = tasks.length > 0 ? cdnBlockedCount / tasks.length : 0;
-      if (cdnRatio > 0.3) {
+      const failRatio = tasks.length > 0 ? failCount / tasks.length : 0;
+      if (cdnRatio > 0.3 && scraper) {
         consecutiveCdnBlocks++;
         // 冷却指数退避：60s→120s→240s→…上限 300s（切换后短等，持续限流则长等窗口过去）
         const coolDownSeconds = Math.min(
@@ -394,12 +421,7 @@ export async function handleAttach(options) {
           MAX_CDN_COOLDOWN_SEC,
         );
         const shouldSwitch = consecutiveCdnBlocks <= MAX_CDN_SWITCH_ATTEMPTS;
-        if (!scraper) {
-          // webserver 模式：限流发生在远端 webserver 出口，本地切节点无效，仅冷却等待
-          attachLog(
-            `  [Attach] CDN限流比例 ${(cdnRatio * 100).toFixed(0)}% (${cdnBlockedCount}/${tasks.length})，webserver 模式不切节点，冷却 ${coolDownSeconds} 秒...`,
-          );
-        } else if (shouldSwitch) {
+        if (shouldSwitch) {
           // 用现有 IPC 接口通知 daemon 从候选集切下一个健康节点（换 IP 绕过 CDN 限流）
           try {
             writeCommand({
@@ -417,16 +439,42 @@ export async function handleAttach(options) {
           );
         }
         await new Promise((r) => setTimeout(r, coolDownSeconds * 1000));
-        if (scraper) {
-          await recycleScraper(
-            scraper,
-            `CDN限流比例过高 (${cdnBlockedCount}/${tasks.length})`,
-          );
-          browserRestartCount++;
-        }
+        await recycleScraper(
+          scraper,
+          `CDN限流比例过高 (${cdnBlockedCount}/${tasks.length})`,
+        );
+        browserRestartCount++;
+        taskBatchCount = 0;
+      } else if (
+        webserverUrl &&
+        tasks.length >= 5 &&
+        failRatio > 0.5
+      ) {
+        // webserver 模式统一阶梯：总失败率 >50% 即冷却（含 CDN 限流/goto 超时/
+        // 验证码/网络错误等所有类型）。首次 30s 低代价试探，连续则指数升级
+        // 30→60→120→240→300s 封顶；服务端告知冷却剩余秒数时优先精确对齐；
+        // 失败率回落 ≤30% 清零
+        consecutiveHighFail++;
+        const coolDownSeconds = serverCdnCooldownSec
+          ? Math.min(
+              Math.max(serverCdnCooldownSec + 5, 30),
+              MAX_CDN_COOLDOWN_SEC,
+            )
+          : Math.min(
+              30 * Math.pow(2, consecutiveHighFail - 1),
+              MAX_CDN_COOLDOWN_SEC,
+            );
+        const cdnTag = cdnBlockedCount
+          ? `（其中 CDN限流 ${cdnBlockedCount}）`
+          : "";
+        attachLog(
+          `  [Attach] 失败率 ${(failRatio * 100).toFixed(0)}% (${failCount}/${tasks.length})${cdnTag}，冷却 ${coolDownSeconds} 秒...`,
+        );
+        await new Promise((r) => setTimeout(r, coolDownSeconds * 1000));
         taskBatchCount = 0;
       } else {
         consecutiveCdnBlocks = 0; // 正常批次重置连续限流计数
+        if (failRatio <= 0.3) consecutiveHighFail = 0; // 失败率回落清零阶梯计数
       }
 
       if (scraper) {

package/src/lib/browser/cdp.js

@@ -222,22 +222,66 @@ function killEdgeProcesses(targetDir, port) {
   });
 }
 
+/** 查询监听指定端口的进程 PID 列表（netstat，不依赖 WMI）；查询失败返回 [] */
+function getListeningPidsOnPort(port) {
+  try {
+    const out = execSync("netstat -ano", {
+      encoding: "utf-8",
+      timeout: 10000,
+      windowsHide: true,
+    });
+    return parseNetstatListeningPids(out, port);
+  } catch {
+    return [];
+  }
+}
+
+/** tasklist 验证 PID 存活且属于 msedge（不依赖 WMI）：true/false；查询失败返回 null */
+function isEdgePidAliveWin(pid) {
+  try {
+    const out = execSync(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`, {
+      encoding: "utf-8",
+      timeout: 5000,
+      windowsHide: true,
+    });
+    return out.toLowerCase().includes("msedge");
+  } catch {
+    return null;
+  }
+}
+
 /**
- * 查找"残留" Edge 主进程：命令行包含指定 user-data-dir、但不带
- * --remote-debugging-port（Edge 自动更新/崩溃自恢复、上次强杀残留等，
- * 占着 profile 却没监听 CDP 端口）。
- * 排除带 --type= 的子进程：渲染进程等子进程同样带 user-data-dir 却没有
- * CDP 参数，误杀会打断同 profile 的健康实例。
+ * 读取 profile 目录下 lockfile 里的数字（ProcessSingleton 持有者 PID 候选）。
+ * Chromium 写入格式随版本有差异，返回前 5 个数字串，由调用方逐一验证。
+ */
+function readLockPidCandidates(userDataDir) {
+  try {
+    const content = fs.readFileSync(path.join(userDataDir, "lockfile"), "utf-8");
+    return (content.match(/\d+/g) || []).slice(0, 5);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 查找"残留" Edge 主进程：占着指定 user-data-dir 的实例（调用前已确认
+ * CDP 端口未监听，故带 --remote-debugging-port 参数的僵死实例同样算残留）。
+ * 排除带 --type= 的子进程：渲染进程等子进程同样带 user-data-dir，
+ * 误杀会打断同 profile 的健康实例。
  *
  * 这类实例必须先杀掉再启动：否则新 msedge 会因 Chromium ProcessSingleton
  * 把命令行转发给旧实例，变成"旧实例开一个 about:blank 新 tab"，CDP 端口
  * 永远起不来 → 等待超时 → watchdog 自动重启 → 每轮再开一个 tab。
  *
  * killEdgeProcesses 在 Windows 上按监听端口找 PID，对这类实例无效，
- * 故单独按命令行匹配精确清理。
+ * 故单独按命令行/lockfile 匹配精确清理，且不依赖 WMI：
+ *  1. PowerShell 枚举 msedge 命令行按 user-data-dir 匹配（需 WMI，
+ *     WMI 损坏的机器上可能返回空）
+ *  2. lockfile 兜底：读 profile 目录 lockfile 中的 PID，用 tasklist 验证
+ *     存活且是 msedge（不依赖 WMI，覆盖 WMI 损坏 + 带 CDP 参数的僵死实例）
  *
  * @param {string} targetDir - user-data-dir 路径
- * @returns {string[]|null} PID 列表；无法枚举进程命令行（PowerShell/WMI 不可用）时返回 null
+ * @returns {string[]|null} PID 列表；命令行枚举失败且 lockfile 无可信结论时返回 null
  */
 function findStaleEdgePids(targetDir) {
   const platform = os.platform();
@@ -245,31 +289,61 @@ function findStaleEdgePids(targetDir) {
     let out;
     if (platform === "win32") {
       // PowerShell 为主（wmic 已从新版 Win11 移除；项目其他模块同样依赖 PowerShell）
-      out = decodeWinOutput(
-        execSync(
-          'powershell -NoProfile -Command "Get-CimInstance Win32_Process | Where-Object { $_.Name -eq \'msedge.exe\' } | ForEach-Object { Write-Output ($_.ProcessId.ToString() + \'|\' + $_.CommandLine) }"',
-          { encoding: "buffer", timeout: 10000, windowsHide: true },
-        ),
-      );
-    } else {
-      out = execSync("ps -eo pid,args", {
-        encoding: "utf-8",
-        timeout: 10000,
-      });
+      let byCmdline = null;
+      try {
+        out = decodeWinOutput(
+          execSync(
+            'powershell -NoProfile -Command "Get-CimInstance Win32_Process | Where-Object { $_.Name -eq \'msedge.exe\' } | ForEach-Object { Write-Output ($_.ProcessId.ToString() + \'|\' + $_.CommandLine) }"',
+            { encoding: "buffer", timeout: 10000, windowsHide: true },
+          ),
+        );
+        const dirLower = targetDir.toLowerCase();
+        const pids = [];
+        for (const line of out.split(/\r?\n/)) {
+          const lower = line.toLowerCase();
+          if (!lower.includes(dirLower)) continue; // 只匹配本 profile
+          // 边界保护：避免 _p9222 误匹配 _p92221 这类前缀目录
+          const idx = lower.indexOf(dirLower);
+          const next = lower[idx + dirLower.length];
+          if (next && /[a-z0-9_]/.test(next)) continue;
+          if (lower.includes("--type=")) continue; // 子进程，误杀会打断健康实例
+          // 提取 PID：win 格式 "PID|命令行"
+          const m = line.match(/^\s*(\d+)\|/);
+          if (m && !pids.includes(m[1])) pids.push(m[1]);
+        }
+        byCmdline = pids;
+      } catch (e) {
+        console.error(`[findStaleEdgePids] PowerShell 枚举失败: ${e.message}`);
+        byCmdline = null;
+      }
+      if (byCmdline && byCmdline.length > 0) return byCmdline;
+
+      // lockfile 兑底：WMI 损坏时命令行枚举为空/失败；或残留实例带 CDP
+      // 参数时命令行匹配可能误报为空，lockfile 直接给出持有者 PID
+      for (const cand of readLockPidCandidates(targetDir)) {
+        if (isEdgePidAliveWin(cand) === true) return [cand];
+      }
+
+      // 命令行枚举失败且 lockfile 没找到活持有者 → 无法判断
+      if (byCmdline === null) return null;
+      return [];
     }
+
+    out = execSync("ps -eo pid,args", {
+      encoding: "utf-8",
+      timeout: 10000,
+    });
     const dirLower = targetDir.toLowerCase();
     const pids = [];
     for (const line of out.split(/\r?\n/)) {
       const lower = line.toLowerCase();
       if (!lower.includes(dirLower)) continue; // 只匹配本 profile
-      // 边界保护：避免 _p9222 误匹配 _p92221 这类前缀目录
       const idx = lower.indexOf(dirLower);
       const next = lower[idx + dirLower.length];
       if (next && /[a-z0-9_]/.test(next)) continue;
-      if (lower.includes("remote-debugging-port")) continue; // 健康 CDP 实例，不动
       if (lower.includes("--type=")) continue; // 子进程，误杀会打断健康实例
-      // 提取 PID：win 格式 "PID|命令行"，unix 格式 "  PID 命令行"
-      const m = line.match(/^\s*(\d+)(?:\||\s)/);
+      // 提取 PID：unix 格式 "  PID 命令行"
+      const m = line.match(/^\s*(\d+)\s/);
       if (m && !pids.includes(m[1])) pids.push(m[1]);
     }
     return pids;
@@ -308,6 +382,66 @@ function killEdgeStale(pids) {
   });
 }
 
+/**
+ * CDP 等待超时后的现场诊断：端口被谁占用、msedge 进程总数、profile 锁持有者。
+ * 输出随超时错误一起打印/上报，远程节点无需人工登录即可定位问题。
+ * @param {number} port
+ * @param {string} userDataDir
+ * @returns {string} 形如 "[诊断] ...; ..." 的摘要；收集失败返回 ""
+ */
+function collectTimeoutDiagnostics(port, userDataDir) {
+  const parts = [];
+  try {
+    if (os.platform() === "win32") {
+      const listenPids = getListeningPidsOnPort(port);
+      if (listenPids.length > 0) {
+        const names = listenPids.map((pid) => {
+          try {
+            const out = execSync(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`, {
+              encoding: "utf-8",
+              timeout: 5000,
+              windowsHide: true,
+            });
+            return out.split(",")[0]?.replace(/"/g, "").trim() || pid;
+          } catch {
+            return pid;
+          }
+        });
+        parts.push(
+          `端口 ${port} 正被监听但 CDP 未响应 (PID: ${listenPids.join(", ")}, 进程: ${names.join(", ")})`,
+        );
+      } else {
+        parts.push(`端口 ${port} 无任何进程监听`);
+      }
+      try {
+        const out = execSync(
+          'tasklist /FI "IMAGENAME eq msedge.exe" /FO CSV /NH',
+          {
+            encoding: "utf-8",
+            timeout: 5000,
+            windowsHide: true,
+          },
+        );
+        const count = out
+          .split(/\r?\n/)
+          .filter((l) => l.toLowerCase().includes("msedge")).length;
+        parts.push(`msedge 进程总数: ${count}`);
+      } catch {}
+      const lockPids = readLockPidCandidates(userDataDir).filter(
+        (pid) => isEdgePidAliveWin(pid) !== false,
+      );
+      parts.push(
+        lockPids.length
+          ? `profile lockfile 持有者: ${lockPids.join(", ")}`
+          : "profile lockfile 无存活持有者",
+      );
+    }
+  } catch (e) {
+    parts.push(`诊断收集失败: ${e.message}`);
+  }
+  return parts.length ? `[诊断] ${parts.join("; ")}` : "";
+}
+
 function launchEdgeWithCDP(port, userDataDir, proxyServer) {
   return new Promise((resolve, reject) => {
     const platform = os.platform();
@@ -405,14 +539,32 @@ export async function ensureBrowserReady(options = {}) {
         console.error(`CDP 端口 ${port} 未就绪，正在启动 Edge 浏览器...`);
       }
     }
-    // 残留实例清理：占着该 user-data-dir 却没开 CDP 的旧 Edge 必须先杀掉，
-    // 否则 launch 会被 ProcessSingleton 转发成"旧实例开新 tab"，CDP 永远起不来。
+    // （Windows）CDP 端口被非 Edge 进程占用 → 立即报错，避免干等 60 秒超时
+    if (os.platform() === "win32") {
+      const listenPids = getListeningPidsOnPort(port);
+      if (listenPids.length > 0) {
+        const isEdge = listenPids.map((pid) => isEdgePidAliveWin(pid));
+        if (isEdge.every((v) => v === false)) {
+          throw new Error(
+            `CDP 端口 ${port} 被非 Edge 进程占用 (PID: ${listenPids.join(", ")})，` +
+              `无法启动浏览器。请释放该端口或更换 --cdp-port`,
+          );
+        }
+        // Edge 在监听但 HTTP 未响应 → 视为僵死，按残留处理（下方清理）
+      }
+    }
+
+    // 残留实例清理：占着该 user-data-dir 但 CDP 端口未监听的旧 Edge 必须先杀掉
+    //（含带 --remote-debugging-port 参数的僵死实例），否则 launch 会被
+    // ProcessSingleton 转发成"旧实例开新 tab"，CDP 永远起不来。
     const stalePids = findStaleEdgePids(userDataDir);
     if (stalePids === null) {
-      console.error("[浏览器] 无法枚举 Edge 进程命令行，跳过残留实例检测");
+      console.error(
+        "[浏览器] 无法判断是否存在残留 Edge 实例（WMI/lockfile 均不可用），跳过清理",
+      );
     } else if (stalePids.length > 0) {
       console.error(
-        `[浏览器] 检测到占用 ${path.basename(userDataDir)} 但未开 CDP 的残留 Edge 实例 (PID: ${stalePids.join(", ")})，正在清理...`,
+        `[浏览器] 检测到占用 ${path.basename(userDataDir)} 但 CDP 端口未监听的残留 Edge 实例 (PID: ${stalePids.join(", ")})，正在清理...`,
       );
       await killEdgeStale(stalePids);
       await new Promise((r) => setTimeout(r, 3000));
@@ -427,8 +579,11 @@ export async function ensureBrowserReady(options = {}) {
       os.platform() === "win32" ? 60000 : 30000,
     );
     if (!launched) {
+      const diag = collectTimeoutDiagnostics(port, userDataDir);
+      if (diag) console.error(`[浏览器] ${diag}`);
       throw new Error(
-        `等待 CDP 端口 ${port} 超时。请确认 Edge 浏览器已安装，\n` +
+        `等待 CDP 端口 ${port} 超时。${diag ? diag + "\n" : ""}` +
+          `请确认 Edge 浏览器已安装，\n` +
           `或手动启动: Microsoft Edge --remote-debugging-port=${port} [参见 cdp.js extraArgs]`,
       );
     }