@ada-mcp/mcp-server 0.1.18 → 0.1.20

package/README.md

@@ -8,27 +8,27 @@ ADA MCP server package that supports:
 
 ## 标准安装（Cursor / MCP）
 
-请使用 **`@ada-mcp/launcher@0.1.17`** 拉起本包（见 [launcher README](../ada-mcp-launcher/README.md)）：
+请使用 **`@ada-mcp/launcher@0.1.19`** 拉起本包（见 [launcher README](../ada-mcp-launcher/README.md)）：
 
 ```json
 {
   "mcpServers": {
     "ada-mcp": {
       "command": "pnpm",
-      "args": ["dlx", "@ada-mcp/launcher@0.1.17"]
+      "args": ["dlx", "@ada-mcp/launcher@0.1.19"]
     }
   }
 }
 ```
 
-本包版本：**`@ada-mcp/mcp-server@0.1.18`**（由 launcher 默认拉取；依赖锁定 `playwright@1.59.1`）。
+本包版本：**`@ada-mcp/mcp-server@0.1.19`**（由 launcher 默认拉取；依赖锁定 `playwright@1.59.1`）。
 
 直接调试本包（无 launcher 拉包前测速）：
 
 ```bash
-pnpm dlx @ada-mcp/mcp-server@0.1.18
+pnpm dlx @ada-mcp/mcp-server@0.1.19
 # npx 等价：
-npx -y @ada-mcp/mcp-server@0.1.18
+npx -y @ada-mcp/mcp-server@0.1.19
 ```
 
 ## 启动时自动安装依赖（默认仅 Playwright）
@@ -83,27 +83,27 @@ npx -y @ada-mcp/mcp-server@0.1.18
 在标准 `args` 后追加，例如安装全部依赖：
 
 ```json
-"args": ["dlx", "@ada-mcp/launcher@0.1.17", "--install-deps=all"]
+"args": ["dlx", "@ada-mcp/launcher@0.1.19", "--install-deps=all"]
 ```
 
 ## Cursor MCP 配置
 
-**pnpm（推荐）**：`pnpm` + `dlx @ada-mcp/launcher@0.1.17`
+**pnpm（推荐）**：`pnpm` + `dlx @ada-mcp/launcher@0.1.19`
 
-**npx 等价**（`launcher@0.1.7+`）：`npx` + `-y @ada-mcp/launcher@0.1.17`（内层同样 `npx -y` mcp-server，测速逻辑与 pnpm 一致）
+**npx 等价**（`launcher@0.1.7+`）：`npx` + `-y @ada-mcp/launcher@0.1.19`（内层同样 `npx -y` mcp-server，测速逻辑与 pnpm 一致）
 
 ```json
 {
   "mcpServers": {
     "ada-mcp": {
       "command": "npx",
-      "args": ["-y", "@ada-mcp/launcher@0.1.17"]
+      "args": ["-y", "@ada-mcp/launcher@0.1.19"]
     }
   }
 }
 ```
 
-Windows 若找不到 `pnpm`，可将 `command` 改为 `pnpm.cmd` 绝对路径；无 pnpm 时只能直接 `npx -y @ada-mcp/mcp-server@0.1.18`（无 launcher 拉包测速）。
+Windows 若找不到 `pnpm`，可将 `command` 改为 `pnpm.cmd` 绝对路径；无 pnpm 时只能直接 `npx -y @ada-mcp/mcp-server@0.1.19`（无 launcher 拉包测速）。
 
 ## Remote mode
 

package/dist/cli.cjs

@@ -3005,14 +3005,55 @@ async function resolveNativeDriversDir(workspaceRoot) {
   }
   return import_node_path4.default.join(root, DEFAULT_NATIVE_DRIVERS_DIR);
 }
-function platformArchiveSuffix() {
+function geckodriverMirrorBase() {
+  const fromEnv = process.env.ADA_GECKODRIVER_MIRROR?.trim();
+  return (fromEnv || DEFAULT_GECKODRIVER_MIRROR).replace(/\/$/, "");
+}
+function geckodriverPlatformAsset(tag) {
+  const t = tag.startsWith("v") ? tag : `v${tag}`;
   if (process.platform === "win32") {
-    return "win64.zip";
+    const winSuffix = process.arch === "arm64" ? "win-aarch64" : process.arch === "ia32" ? "win32" : "win64";
+    return { fileName: `geckodriver-${t}-${winSuffix}.zip`, archiveKind: "zip" };
   }
   if (process.platform === "darwin") {
-    return process.arch === "arm64" ? "macos-aarch64.zip" : "macos.zip";
+    const macSuffix = process.arch === "arm64" ? "macos-aarch64" : "macos";
+    return { fileName: `geckodriver-${t}-${macSuffix}.tar.gz`, archiveKind: "tar.gz" };
+  }
+  const linuxSuffix = process.arch === "arm64" ? "linux-aarch64" : process.arch === "ia32" ? "linux32" : "linux64";
+  return { fileName: `geckodriver-${t}-${linuxSuffix}.tar.gz`, archiveKind: "tar.gz" };
+}
+function parseSemverTuple(version2) {
+  const m = version2.replace(/^v/i, "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) {
+    return null;
+  }
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function compareSemverDesc(a, b) {
+  const pa = parseSemverTuple(a);
+  const pb = parseSemverTuple(b);
+  if (!pa || !pb) {
+    return 0;
+  }
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) {
+      return pb[i] - pa[i];
+    }
+  }
+  return 0;
+}
+async function fetchGeckodriverLatestFromMirror(mirrorBase) {
+  const res = await fetch(`${mirrorBase}/`);
+  if (!res.ok) {
+    return null;
+  }
+  const html = await res.text();
+  const tags = /* @__PURE__ */ new Set();
+  for (const m of html.matchAll(/href="v(\d+\.\d+\.\d+)\//gi)) {
+    tags.add(`v${m[1]}`);
   }
-  return "linux64.zip";
+  const sorted = Array.from(tags).sort(compareSemverDesc);
+  return sorted[0] ?? null;
 }
 function platformChromeLabel() {
   if (process.platform === "win32") {
@@ -3197,6 +3238,21 @@ async function extractZip(zipPath, destDir) {
   }
   await runCommand("unzip", ["-o", zipPath, "-d", destDir]);
 }
+async function extractTarGz(archivePath, destDir) {
+  await import_promises4.default.mkdir(destDir, { recursive: true });
+  if (process.platform === "win32") {
+    await runCommand("tar", ["-xzf", archivePath, "-C", destDir]);
+    return;
+  }
+  await runCommand("tar", ["-xzf", archivePath, "-C", destDir]);
+}
+async function extractDriverArchive(archivePath, destDir, kind) {
+  if (kind === "zip") {
+    await extractZip(archivePath, destDir);
+    return;
+  }
+  await extractTarGz(archivePath, destDir);
+}
 async function findFileRecursive(dir, fileName) {
   const entries = await import_promises4.default.readdir(dir, { withFileTypes: true });
   for (const ent of entries) {
@@ -3224,13 +3280,26 @@ async function fetchGeckodriverReleaseVersion(requested) {
   if (requested && requested !== "latest") {
     return requested.startsWith("v") ? requested : `v${requested}`;
   }
-  const res = await fetch("https://api.github.com/repos/mozilla/geckodriver/releases/latest");
-  if (!res.ok) {
-    throw new Error(`Failed to fetch geckodriver latest release: HTTP ${res.status}`);
+  const mirrorLatest = await fetchGeckodriverLatestFromMirror(geckodriverMirrorBase());
+  if (mirrorLatest) {
+    return mirrorLatest;
   }
-  const json3 = await res.json();
-  const tag = json3.tag_name ?? "v0.36.0";
-  return tag.startsWith("v") ? tag : `v${tag}`;
+  try {
+    const res = await fetch("https://api.github.com/repos/mozilla/geckodriver/releases/latest");
+    if (res.ok) {
+      const json3 = await res.json();
+      const tag = json3.tag_name ?? "v0.36.0";
+      return tag.startsWith("v") ? tag : `v${tag}`;
+    }
+  } catch {
+  }
+  return "v0.36.0";
+}
+function buildGeckodriverDownloadUrls(tag) {
+  const { fileName, archiveKind } = geckodriverPlatformAsset(tag);
+  const mirror = `${geckodriverMirrorBase()}/${tag}/${fileName}`;
+  const github = `${GITHUB_GECKODRIVER_RELEASES}/download/${tag}/${fileName}`;
+  return { mirror, github, fileName, archiveKind };
 }
 async function listChromedriverCfTVersions() {
   const res = await fetch(CHROME_FOR_TESTING_JSON);
@@ -3474,26 +3543,39 @@ async function downloadToFile(url2, destPath) {
 async function downloadGeckodriver(driversDir, versionInput, onLogLine) {
   const tag = await fetchGeckodriverReleaseVersion(versionInput);
   const version2 = tag.replace(/^v/, "");
-  const suffix = platformArchiveSuffix();
-  const assetName = `geckodriver-${tag}-${suffix}`.replace("vv", "v");
-  const url2 = `https://github.com/mozilla/geckodriver/releases/download/${tag}/geckodriver-${tag}-${suffix}`;
+  const { mirror, github, fileName, archiveKind } = buildGeckodriverDownloadUrls(tag);
   await import_promises4.default.mkdir(driversDir, { recursive: true });
-  const zipPath = import_node_path4.default.join(driversDir, `_download_geckodriver_${version2}.zip`);
+  const archiveExt = archiveKind === "zip" ? "zip" : "tar.gz";
+  const archivePath = import_node_path4.default.join(driversDir, `_download_geckodriver_${version2}.${archiveExt}`);
   const extractDir = import_node_path4.default.join(driversDir, `_extract_geckodriver_${version2}`);
-  onLogLine?.(`[selenium] \u4E0B\u8F7D geckodriver ${tag} \u2192 ${driversDir}`);
-  onLogLine?.(`[selenium] URL: ${url2}`);
-  await downloadToFile(url2, zipPath);
+  onLogLine?.(`[selenium] ?? geckodriver ${tag}?${fileName}?? ${driversDir}`);
+  onLogLine?.(`[selenium] ??: ${mirror}`);
+  let downloaded = false;
+  try {
+    await downloadToFile(mirror, archivePath);
+    downloaded = true;
+  } catch (mirrorError) {
+    onLogLine?.(
+      `[selenium][warn] ?????????: ${mirrorError instanceof Error ? mirrorError.message : String(mirrorError)}`
+    );
+    onLogLine?.(`[selenium] ?? GitHub: ${github}`);
+    await downloadToFile(github, archivePath);
+    downloaded = true;
+  }
+  if (!downloaded) {
+    throw new Error(`geckodriver download failed for ${tag}`);
+  }
   await import_promises4.default.rm(extractDir, { recursive: true, force: true });
-  await extractZip(zipPath, extractDir);
+  await extractDriverArchive(archivePath, extractDir, archiveKind);
   const found = await findFileRecursive(extractDir, geckodriverExeName());
   if (!found) {
-    throw new Error(`geckodriver binary not found after extracting ${assetName}`);
+    throw new Error(`geckodriver binary not found after extracting ${fileName}`);
   }
   const dest = import_node_path4.default.join(driversDir, geckodriverExeName());
   await copyExecutable(found, dest);
-  await import_promises4.default.rm(zipPath, { force: true });
+  await import_promises4.default.rm(archivePath, { force: true });
   await import_promises4.default.rm(extractDir, { recursive: true, force: true });
-  onLogLine?.(`[selenium] geckodriver \u5DF2\u5199\u5165: ${dest}`);
+  onLogLine?.(`[selenium] geckodriver ???: ${dest}`);
   return { path: dest, version: tag };
 }
 async function downloadChromedriver(driversDir, versionInput, onLogLine) {
@@ -3653,7 +3735,7 @@ async function ensureNativeWebDrivers(options = {}) {
   }
   return resolved;
 }
-var import_node_child_process, import_promises4, import_node_path4, DEFAULT_NATIVE_DRIVERS_DIR, CHROME_FOR_TESTING_JSON;
+var import_node_child_process, import_promises4, import_node_path4, DEFAULT_NATIVE_DRIVERS_DIR, CHROME_FOR_TESTING_JSON, DEFAULT_GECKODRIVER_MIRROR, GITHUB_GECKODRIVER_RELEASES, SELENIUM_DRIVER_MANUAL_DOWNLOAD_REFERENCES;
 var init_src2 = __esm({
   "../../packages/native-drivers/src/index.ts"() {
     "use strict";
@@ -3662,6 +3744,46 @@ var init_src2 = __esm({
     import_node_path4 = __toESM(require("node:path"), 1);
     DEFAULT_NATIVE_DRIVERS_DIR = "dirver";
     CHROME_FOR_TESTING_JSON = "https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json";
+    DEFAULT_GECKODRIVER_MIRROR = "https://mirrors.huaweicloud.com/geckodriver";
+    GITHUB_GECKODRIVER_RELEASES = "https://github.com/mozilla/geckodriver/releases";
+    SELENIUM_DRIVER_MANUAL_DOWNLOAD_REFERENCES = [
+      {
+        browser: "Chrome/Chromium",
+        platforms: "Windows/Linux/macOS",
+        vendor: "\u8C37\u6B4C",
+        url: "https://chromedriver.storage.googleapis.com/index.html"
+      },
+      {
+        browser: "Firefox",
+        platforms: "Windows/Linux/macOS",
+        vendor: "Mozilla / ?????",
+        url: `${DEFAULT_GECKODRIVER_MIRROR}/v0.36.0/?????????????? ${GITHUB_GECKODRIVER_RELEASES}?`
+      },
+      {
+        browser: "Edge",
+        platforms: "win10",
+        vendor: "\u5FAE\u8F6F",
+        url: "https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/"
+      },
+      {
+        browser: "Internet Explorer",
+        platforms: "Windows",
+        vendor: "Selenium \u9879\u76EE\u7EC4",
+        url: "https://selenium-release.storage.googleapis.com/index.html"
+      },
+      {
+        browser: "Safari",
+        platforms: "macOS El Capitan \u53CA\u66F4\u9AD8\u7248\u672C",
+        vendor: "\u82F9\u679C",
+        url: "\uFF08\u7CFB\u7EDF\u5185\u7F6E\uFF0C\u65E0\u9700\u5355\u72EC\u4E0B\u8F7D\uFF09"
+      },
+      {
+        browser: "Opera",
+        platforms: "Windows/macOS/Linux",
+        vendor: "Opera",
+        url: "https://github.com/operasoftware/operachromiumdriver/releases"
+      }
+    ];
   }
 });
 
@@ -3818,7 +3940,14 @@ function briefErrorMessage(error2) {
   }
   return String(error2).split(/\r?\n/)[0]?.trim() || String(error2);
 }
+function depsVerboseEnabled() {
+  return isTruthyEnv("ADA_DEPS_VERBOSE");
+}
 function shouldEmitPlaywrightCliLine(line) {
+  if (depsVerboseEnabled()) {
+    const t2 = line.trim();
+    return t2.length > 0 && !/^\s*at\s/.test(t2) && !t2.includes("processTicksAndRejections");
+  }
   const t = line.trim();
   if (!t) {
     return false;
@@ -3848,7 +3977,8 @@ function summarizePlaywrightCliLine(line) {
     return "[playwright][warn] \u5F53\u524D\u955C\u50CF\u672A\u5B89\u88C5\u6210\u529F";
   }
   if (/^Progress:/i.test(t)) {
-    return null;
+    const pct = t.match(/(\d{1,3})%/)?.[1];
+    return pct ? `[playwright] \u4E0B\u8F7D\u8FDB\u5EA6 ${pct}%` : "[playwright] \u4E0B\u8F7D\u4E2D\u2026";
   }
   if (t.length > 200) {
     return `[playwright] ${t.slice(0, 120)}\u2026`;
@@ -3860,15 +3990,27 @@ function createPlaywrightInstallLogSink(onLogLine) {
     return void 0;
   }
   const seen = /* @__PURE__ */ new Set();
+  let lastProgressEmitAt = 0;
   return (line) => {
     if (!shouldEmitPlaywrightCliLine(line)) {
       return;
     }
+    if (depsVerboseEnabled()) {
+      onLogLine(line.trimEnd());
+      return;
+    }
     const summary = summarizePlaywrightCliLine(line);
     if (!summary) {
       return;
     }
-    if (seen.has(summary)) {
+    const isProgress = /^Progress:/i.test(line.trim());
+    if (isProgress) {
+      const now = Date.now();
+      if (now - lastProgressEmitAt < 12e3) {
+        return;
+      }
+      lastProgressEmitAt = now;
+    } else if (seen.has(summary)) {
       return;
     }
     seen.add(summary);
@@ -4045,7 +4187,13 @@ function installStrategyTimeoutMs() {
   return parsePositiveMs(process.env.ADA_INSTALL_STRATEGY_TIMEOUT_MS, 12e4);
 }
 function playwrightInstallTimeoutMs() {
-  return parsePositiveMs(process.env.ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS, 9e5);
+  return parsePositiveMs(process.env.ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS, 18e5);
+}
+function playwrightInstallAttemptTimeoutMs(attemptIndex, baseTimeoutMs) {
+  if (attemptIndex <= 0) {
+    return baseTimeoutMs;
+  }
+  return Math.min(baseTimeoutMs, 6e5);
 }
 function majorOf(versionLike) {
   const text = versionLike.trim().replace(/^v/i, "");
@@ -4102,6 +4250,32 @@ function appiumDriverPackageName(driver) {
   }
   return null;
 }
+function resolveAppiumDriverInstallTargets(driver, appiumMajor, compatibleSpecs) {
+  const pkg = appiumDriverPackageName(driver);
+  if (appiumMajor !== null && appiumMajor >= 3) {
+    if (!APPIUM3_BUILTIN_DRIVER_NAMES.has(driver)) {
+      const envHarmony = process.env.ADA_APPIUM_DRIVER_SPEC_HARMONYOS?.trim();
+      if (driver === "harmonyos" && (envHarmony || pkg)) {
+        return [envHarmony || pkg];
+      }
+      return pkg ? [pkg] : [driver];
+    }
+    const envOverride = driver === "uiautomator2" ? process.env.ADA_APPIUM_DRIVER_SPEC_UIAUTOMATOR2?.trim() : driver === "xcuitest" ? process.env.ADA_APPIUM_DRIVER_SPEC_XCUITEST?.trim() : "";
+    if (envOverride) {
+      return [envOverride, driver];
+    }
+    return [driver];
+  }
+  const baseTarget = pkg ?? driver;
+  return compatibleSpecs.length > 0 ? compatibleSpecs : [baseTarget];
+}
+function buildAppiumDriverInstallArgs(target, appiumMajor) {
+  const useNpmPackageSpec = appiumMajor === null || appiumMajor < 3 || target.includes("@") || target.startsWith("appium-") || target.includes("/");
+  if (useNpmPackageSpec) {
+    return ["exec", "appium", "driver", "install", "--source=npm", target];
+  }
+  return ["exec", "appium", "driver", "install", target];
+}
 async function getAppiumMajorVersion() {
   let version2 = "";
   try {
@@ -4149,12 +4323,73 @@ function stepMeta(stage) {
     stepTotal: PROGRESS_STEPS.length
   };
 }
+function formatProgressDetail(stage, details) {
+  if (!details) {
+    return null;
+  }
+  if (stage === "registry.probe.result") {
+    const candidate = String(details.candidate ?? "");
+    const latency = details.latencyMs;
+    return `[deps] npm \u955C\u50CF ${candidate} -> ${latency === null || latency === void 0 ? "fail" : `${latency}ms`}`;
+  }
+  if (stage === "playwright.host.probe.result") {
+    const candidate = String(details.candidate ?? "");
+    const latency = details.latencyMs;
+    const artifactOk = details.artifactOk === true;
+    const tail = artifactOk ? "\uFF0C\u6D4F\u89C8\u5668\u5305\u53EF\u4E0B\u8F7D" : latency === null || latency === void 0 ? "" : "\uFF0C\u4EC5\u8FDE\u901A";
+    return `[playwright] CDN ${candidate} -> ${latency === null || latency === void 0 ? "fail" : `${latency}ms`}${tail}`;
+  }
+  if (stage === "packages.install.done") {
+    const strategy = String(details.strategy ?? "");
+    return strategy ? `[deps] \u5305\u5B89\u88C5\u5B8C\u6210\uFF08${strategy}\uFF09` : null;
+  }
+  if (stage === "playwright.browser.install.done") {
+    const host = String(details.selectedHost ?? "");
+    const attempt = details.attempt;
+    return host ? `[playwright] \u6D4F\u89C8\u5668\u5B89\u88C5\u5B8C\u6210\uFF08${host}${attempt ? `\uFF0C\u7B2C ${attempt} \u4E2A\u955C\u50CF` : ""}\uFF09` : null;
+  }
+  return null;
+}
+function structuredLogToHuman(level, payload) {
+  const { event, details } = payload;
+  const d = details && typeof details === "object" ? details : {};
+  if (event === "deps.playwright.browser.install.host.fail") {
+    return `[playwright][warn] \u955C\u50CF ${d.host} \u5931\u8D25 (${d.attempt}): ${d.message}`;
+  }
+  if (event === "deps.install.strategy.try") {
+    return `[deps] \u5C1D\u8BD5\u5B89\u88C5\u7B56\u7565: ${d.strategy}`;
+  }
+  if (event === "deps.install.strategy.ok") {
+    return `[deps] \u5305\u5B89\u88C5\u6210\u529F: ${d.strategy}`;
+  }
+  if (event === "deps.install.strategy.fail") {
+    return `[deps][warn] \u5B89\u88C5\u7B56\u7565\u5931\u8D25 (${d.strategy}): ${d.message}`;
+  }
+  if (event === "deps.registry.auto-selected") {
+    return `[deps] \u9009\u7528 npm \u955C\u50CF: ${d.selected}`;
+  }
+  if (event === "deps.playwright.host.auto-selected") {
+    return `[playwright] CDN \u6D4B\u901F\u6392\u5E8F: ${Array.isArray(d.ranked) ? d.ranked.join(" -> ") : d.selected}`;
+  }
+  if (level === "warn" || level === "error") {
+    const msg = d.message ?? d.detail;
+    return `[deps][${level}] ${event}${msg ? `: ${msg}` : ""}`;
+  }
+  if (depsVerboseEnabled()) {
+    return `[deps] ${event}${Object.keys(d).length > 0 ? ` ${JSON.stringify(d)}` : ""}`;
+  }
+  return null;
+}
 function progress(stage, details) {
   if (depsHumanLog) {
     const label = PROGRESS_HUMAN_LABELS[stage];
     if (label) {
       depsHumanLog(label);
     }
+    const detail = formatProgressDetail(stage, details);
+    if (detail) {
+      depsHumanLog(detail);
+    }
     return;
   }
   const meta3 = stepMeta(stage);
@@ -4169,6 +4404,10 @@ function progress(stage, details) {
 }
 function depsStructuredLog(level, payload) {
   if (depsHumanLog) {
+    const human = structuredLogToHuman(level, payload);
+    if (human) {
+      depsHumanLog(human);
+    }
     return;
   }
   log(level, payload);
@@ -4267,12 +4506,42 @@ function playwrightProbeUrls(host) {
   }
   return [h];
 }
+function isChinaFriendlyNpmRegistry(registry2) {
+  const r = registry2.toLowerCase();
+  return CHINA_NPM_REGISTRY_HINTS.some((hint) => r.includes(hint));
+}
+function isTruthyEnv(name) {
+  const s = String(process.env[name] ?? "").trim().toLowerCase();
+  return s === "1" || s === "true" || s === "yes" || s === "on";
+}
+function playwrightHostConfiguredByUser(config2) {
+  if (process.env.ADA_PLAYWRIGHT_HOST_FROM_PREINSTALL === "1") {
+    return "";
+  }
+  const raw = process.env.PLAYWRIGHT_DOWNLOAD_HOST?.trim() || playwrightDownloadHost(config2).trim();
+  return raw ? normalizeHostUrl(raw) : "";
+}
+function preferPlaywrightHostsForNpmRegistry(ranked, npmRegistry) {
+  if (!isTruthyEnv("ADA_PLAYWRIGHT_PREFER_CN_MIRROR") && !isChinaFriendlyNpmRegistry(npmRegistry)) {
+    return ranked;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const url2 of [...CHINA_PLAYWRIGHT_HOST_PRIORITY, ...ranked]) {
+    const n = normalizeHostUrl(url2);
+    if (!seen.has(n)) {
+      seen.add(n);
+      out.push(n);
+    }
+  }
+  return out;
+}
 function playwrightHostCandidates(config2) {
-  const configured = normalizeHostUrl(playwrightDownloadHost(config2));
+  const configured = playwrightHostConfiguredByUser(config2);
   const fromConfig = Array.isArray(config2.dependencies.playwrightHostCandidates) ? config2.dependencies.playwrightHostCandidates.map((x) => normalizeHostUrl(String(x).trim())).filter(Boolean) : [];
   const configuredList = fromConfig.length > 0 ? fromConfig : [...DEFAULT_PLAYWRIGHT_HOST_CANDIDATES];
   const extra = process.env.ADA_PLAYWRIGHT_HOST_CANDIDATES ? process.env.ADA_PLAYWRIGHT_HOST_CANDIDATES.split(",").map((x) => normalizeHostUrl(x.trim())).filter(Boolean) : [];
-  const ordered = [configured, ...configuredList, ...extra];
+  const ordered = configured ? [configured, ...configuredList, ...extra] : [...configuredList, ...extra];
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const url2 of ordered) {
@@ -4408,6 +4677,7 @@ async function runInstallWithPriority(config2, packages, onLogLine) {
   let lastError = void 0;
   for (const strategy of strategies) {
     try {
+      onLogLine?.(`[deps] \u5C1D\u8BD5 ${strategy.name} \u5B89\u88C5\u5305\u2026`);
       depsStructuredLog("info", { event: "deps.install.strategy.try", details: { strategy: strategy.name, packages } });
       await strategy.run();
       depsStructuredLog("info", { event: "deps.install.strategy.ok", details: { strategy: strategy.name } });
@@ -4431,13 +4701,14 @@ async function runAppiumDriverInstallWithPriority(config2, driver, onLogLine) {
   onLogLine?.(`[appium] \u5B89\u88C5\u9A71\u52A8: ${driver}`);
   const compatibleSpecs = await resolveCompatibleDriverSpecs(driver);
   const appiumMajor = await getAppiumMajorVersion();
-  const directPackage = appiumDriverPackageName(driver);
-  const baseTarget = directPackage ?? driver;
-  const targets = appiumMajor !== null && appiumMajor < 3 ? compatibleSpecs.length > 0 ? compatibleSpecs : [baseTarget] : [baseTarget, ...compatibleSpecs];
-  const uniqueTargets = Array.from(new Set(targets.filter(Boolean)));
+  if (appiumMajor !== null && appiumMajor >= 3) {
+    onLogLine?.(`[appium] \u68C0\u6D4B\u5230 Appium ${appiumMajor}.x\uFF0C\u4F7F\u7528\u5B98\u65B9\u9A71\u52A8\u540D\u5B89\u88C5\uFF08\u5982 uiautomator2\uFF09`);
+  }
+  const uniqueTargets = resolveAppiumDriverInstallTargets(driver, appiumMajor, compatibleSpecs);
   let lastError = void 0;
   for (const target of uniqueTargets) {
-    const installArgs = ["exec", "appium", "driver", "install", "--source=npm", target];
+    const installArgs = buildAppiumDriverInstallArgs(target, appiumMajor);
+    onLogLine?.(`[appium] \u6267\u884C: npm ${installArgs.join(" ")}`);
     const strategies = [
       {
         name: "npm",
@@ -4524,24 +4795,32 @@ async function installPlaywrightBrowser(config2, onLogLine, options) {
   if (targets.length > 0) {
     installArgs.push(...targets);
   }
-  const rankedHosts = await rankPlaywrightHosts(config2);
-  const timeoutMs = playwrightInstallTimeoutMs();
-  onLogLine?.(`[playwright] \u5B89\u88C5\u8D85\u65F6\u4E0A\u9650 ${Math.round(timeoutMs / 1e3)}s\uFF08\u53EF\u7528 ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS \u8C03\u6574\uFF09`);
+  const npmRegistry = await detectBestRegistry(config2, npmProxyRegistry());
+  let rankedHosts = await rankPlaywrightHosts(config2);
+  rankedHosts = preferPlaywrightHostsForNpmRegistry(rankedHosts, npmRegistry);
+  const baseTimeoutMs = playwrightInstallTimeoutMs();
+  onLogLine?.(
+    `[playwright] \u5B89\u88C5\u8D85\u65F6\uFF1A\u9996\u4E2A\u955C\u50CF ${Math.round(baseTimeoutMs / 1e3)}s\uFF0C\u540E\u7EED\u955C\u50CF\u81F3\u591A 600s\uFF08ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS \u53EF\u8C03\uFF09`
+  );
+  if (isChinaFriendlyNpmRegistry(npmRegistry) || isTruthyEnv("ADA_PLAYWRIGHT_PREFER_CN_MIRROR")) {
+    onLogLine?.(`[playwright] \u56FD\u5185 npm \u6E90 ${npmRegistry}\uFF0C\u4F18\u5148 npmmirror Playwright CDN`);
+  }
   let lastHost = "";
   for (let i = 0; i < rankedHosts.length; i++) {
     const host = rankedHosts[i];
+    const attemptTimeoutMs = playwrightInstallAttemptTimeoutMs(i, baseTimeoutMs);
     lastHost = host;
     if (i > 0) {
-      onLogLine?.(`[playwright] \u6362\u955C\u50CF: ${host}`);
+      onLogLine?.(`[playwright] \u6362\u955C\u50CF (${i + 1}/${rankedHosts.length}): ${host}`);
     } else {
       onLogLine?.(
-        `[playwright] playwright@${version2}\uFF0CCDN ${host}\uFF0C\u76EE\u6807 ${targets.length ? targets.join(",") : "chromium"}`
+        `[playwright] playwright@${version2}\uFF0CCDN ${host}\uFF08${i + 1}/${rankedHosts.length}\uFF09\uFF0C\u76EE\u6807 ${targets.length ? targets.join(",") : "chromium"}`
       );
     }
     try {
       await runCommand2(command, installArgs, {
         env: { PLAYWRIGHT_DOWNLOAD_HOST: host },
-        timeoutMs,
+        timeoutMs: attemptTimeoutMs,
         onLogLine: createPlaywrightInstallLogSink(onLogLine)
       });
       progress("playwright.browser.install.done", { selectedHost: host, attempt: i + 1 });
@@ -4560,7 +4839,7 @@ async function installPlaywrightBrowser(config2, onLogLine, options) {
     }
   }
   onLogLine?.(
-    `[playwright][warn] \u6D4F\u89C8\u5668\u672A\u5B89\u88C5\u5B8C\u6210\uFF08\u5DF2\u5C1D\u8BD5 ${rankedHosts.length} \u4E2A CDN\uFF09\u3002\u53EF\u8BBE\u7F6E PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.playwright.dev \u540E\u91CD\u8BD5\uFF0C\u6216\u6267\u884C: npx playwright@${PINNED_PLAYWRIGHT_VERSION} install chromium`
+    `[playwright][warn] \u6D4F\u89C8\u5668\u672A\u5B89\u88C5\u5B8C\u6210\uFF08\u5DF2\u5C1D\u8BD5 ${rankedHosts.length} \u4E2A CDN\uFF09\u3002\u56FD\u5185\u5EFA\u8BAE: set PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright \u5E76\u589E\u5927 ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS=1800000\uFF1B\u6216\u624B\u52A8: npx playwright@${PINNED_PLAYWRIGHT_VERSION} install chromium`
   );
   if (lastHost) {
     onLogLine?.(`[playwright][warn] \u6700\u540E\u5C1D\u8BD5: ${lastHost}`);
@@ -5052,7 +5331,7 @@ async function getDependencyHealth(config2) {
     missingAppiumDrivers
   };
 }
-var import_node_module, import_node_fs, import_node_child_process2, import_promises5, import_node_path5, require2, PINNED_PLAYWRIGHT_VERSION, PINNED_ZOD_VERSION, depsHumanLog, DEFAULT_NPM_REGISTRY_CANDIDATES, detectedBestRegistryByKey, PROGRESS_STEPS, PROGRESS_HUMAN_LABELS, DEFAULT_PLAYWRIGHT_HOST_CANDIDATES, PLAYWRIGHT_HOST_FALLBACK, PW_INSTALL_TARGETS;
+var import_node_module, import_node_fs, import_node_child_process2, import_promises5, import_node_path5, require2, PINNED_PLAYWRIGHT_VERSION, PINNED_ZOD_VERSION, depsHumanLog, DEFAULT_NPM_REGISTRY_CANDIDATES, APPIUM3_BUILTIN_DRIVER_NAMES, detectedBestRegistryByKey, PROGRESS_STEPS, PROGRESS_HUMAN_LABELS, DEFAULT_PLAYWRIGHT_HOST_CANDIDATES, CHINA_NPM_REGISTRY_HINTS, CHINA_PLAYWRIGHT_HOST_PRIORITY, PLAYWRIGHT_HOST_FALLBACK, PW_INSTALL_TARGETS;
 var init_dependency_installer = __esm({
   "../ada-agent/src/dependency-installer.ts"() {
     import_node_module = require("node:module");
@@ -5072,6 +5351,16 @@ var init_dependency_installer = __esm({
       "https://repo.huaweicloud.com/repository/npm",
       "https://registry.npmjs.org"
     ];
+    APPIUM3_BUILTIN_DRIVER_NAMES = /* @__PURE__ */ new Set([
+      "uiautomator2",
+      "xcuitest",
+      "espresso",
+      "mac2",
+      "windows",
+      "safari",
+      "gecko",
+      "chromium"
+    ]);
     detectedBestRegistryByKey = /* @__PURE__ */ new Map();
     PROGRESS_STEPS = [
       "deps.ensure.start",
@@ -5086,9 +5375,16 @@ var init_dependency_installer = __esm({
       "deps.ensure.start": "[deps] \u5F00\u59CB\u68C0\u6D4B\u4F9D\u8D56",
       "registry.probe.start": "[deps] \u63A2\u6D4B npm \u955C\u50CF\u2026",
       "packages.install.start": "[deps] \u5B89\u88C5 npm \u5305\u2026",
+      "packages.install.done": "[deps] npm \u5305\u5B89\u88C5\u5B8C\u6210",
       "playwright.host.probe.start": "[playwright] \u63A2\u6D4B\u6D4F\u89C8\u5668 CDN\u2026",
       "playwright.browser.install.start": "[playwright] \u5B89\u88C5\u6D4F\u89C8\u5668\u2026",
+      "playwright.browser.install.done": "[playwright] \u6D4F\u89C8\u5668\u5B89\u88C5\u5B8C\u6210",
+      "playwright.selfcheck.start": "[playwright] \u81EA\u68C0\u2026",
+      "playwright.selfcheck.done": "[playwright] \u81EA\u68C0\u5B8C\u6210",
       "appium.driver.ensure.start": "[appium] \u5B89\u88C5\u9A71\u52A8\u2026",
+      "appium.driver.ensure.done": "[appium] \u9A71\u52A8\u5B89\u88C5\u5B8C\u6210",
+      "selenium.check.start": "[selenium] \u68C0\u6D4B\u539F\u751F\u9A71\u52A8\u2026",
+      "selenium.check.done": "[selenium] \u68C0\u6D4B\u5B8C\u6210",
       "deps.ensure.done": "[deps] \u4F9D\u8D56\u68C0\u6D4B\u5B8C\u6210"
     };
     DEFAULT_PLAYWRIGHT_HOST_CANDIDATES = [
@@ -5097,6 +5393,11 @@ var init_dependency_installer = __esm({
       "https://npmmirror.com/mirrors/playwright",
       "https://cdn.npmmirror.com/binaries/playwright"
     ];
+    CHINA_NPM_REGISTRY_HINTS = ["npmmirror.com", "tencent", "huaweicloud", "huawei.com"];
+    CHINA_PLAYWRIGHT_HOST_PRIORITY = [
+      "https://cdn.npmmirror.com/binaries/playwright",
+      "https://npmmirror.com/mirrors/playwright"
+    ];
     PLAYWRIGHT_HOST_FALLBACK = DEFAULT_PLAYWRIGHT_HOST_CANDIDATES[0];
     PW_INSTALL_TARGETS = /* @__PURE__ */ new Set([
       "chromium",
@@ -32976,7 +33277,9 @@ function resolveBootstrapInstallDeps(argv2) {
 }
 var PREINSTALL_PLAYWRIGHT_HOST_ALLOW = /* @__PURE__ */ new Set([
   "https://cdn.playwright.dev",
-  "https://playwright.azureedge.net"
+  "https://playwright.azureedge.net",
+  "https://cdn.npmmirror.com/binaries/playwright",
+  "https://npmmirror.com/mirrors/playwright"
 ]);
 function normalizePlaywrightHost(url2) {
   return url2.replace(/\/$/, "");
@@ -32994,7 +33297,8 @@ function applyPreinstallPlaywrightHostFile() {
       const host = normalizePlaywrightHost(import_node_fs3.default.readFileSync(file2, "utf8").trim());
       if (host.length > 0 && PREINSTALL_PLAYWRIGHT_HOST_ALLOW.has(host)) {
         process.env.PLAYWRIGHT_DOWNLOAD_HOST = host;
-        console.error(`[ADA-MCP] using playwright CDN from ${file2}: ${host}`);
+        process.env.ADA_PLAYWRIGHT_HOST_FROM_PREINSTALL = "1";
+        console.error(`[ADA-MCP] using playwright CDN from ${file2}: ${host} (install-deps \u5C06\u91CD\u65B0\u6D4B\u901F\u6392\u5E8F)`);
         return;
       }
       if (host.length > 0) {
@@ -33012,7 +33316,7 @@ function ensureDefaultInstallTimeouts() {
     process.env.ADA_INSTALL_STRATEGY_TIMEOUT_MS = "120000";
   }
   if (!process.env.ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS?.trim()) {
-    process.env.ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS = "900000";
+    process.env.ADA_PLAYWRIGHT_INSTALL_TIMEOUT_MS = "1800000";
   }
 }
 async function runBootstrapInstallDeps(argv2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ada-mcp/mcp-server",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "ADA MCP server for web/mobile automation (stdio + remote HTTP)",
   "private": false,
   "type": "commonjs",

package/plugins/driver-selenium.cjs

@@ -232,6 +232,46 @@ var import_node_child_process = require("node:child_process");
 var import_promises = __toESM(require("node:fs/promises"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var DEFAULT_NATIVE_DRIVERS_DIR = "dirver";
+var DEFAULT_GECKODRIVER_MIRROR = "https://mirrors.huaweicloud.com/geckodriver";
+var GITHUB_GECKODRIVER_RELEASES = "https://github.com/mozilla/geckodriver/releases";
+var SELENIUM_DRIVER_MANUAL_DOWNLOAD_REFERENCES = [
+  {
+    browser: "Chrome/Chromium",
+    platforms: "Windows/Linux/macOS",
+    vendor: "\u8C37\u6B4C",
+    url: "https://chromedriver.storage.googleapis.com/index.html"
+  },
+  {
+    browser: "Firefox",
+    platforms: "Windows/Linux/macOS",
+    vendor: "Mozilla / ?????",
+    url: `${DEFAULT_GECKODRIVER_MIRROR}/v0.36.0/?????????????? ${GITHUB_GECKODRIVER_RELEASES}?`
+  },
+  {
+    browser: "Edge",
+    platforms: "win10",
+    vendor: "\u5FAE\u8F6F",
+    url: "https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/"
+  },
+  {
+    browser: "Internet Explorer",
+    platforms: "Windows",
+    vendor: "Selenium \u9879\u76EE\u7EC4",
+    url: "https://selenium-release.storage.googleapis.com/index.html"
+  },
+  {
+    browser: "Safari",
+    platforms: "macOS El Capitan \u53CA\u66F4\u9AD8\u7248\u672C",
+    vendor: "\u82F9\u679C",
+    url: "\uFF08\u7CFB\u7EDF\u5185\u7F6E\uFF0C\u65E0\u9700\u5355\u72EC\u4E0B\u8F7D\uFF09"
+  },
+  {
+    browser: "Opera",
+    platforms: "Windows/macOS/Linux",
+    vendor: "Opera",
+    url: "https://github.com/operasoftware/operachromiumdriver/releases"
+  }
+];
 async function fileExists(filePath) {
   try {
     await import_promises.default.access(filePath);

package/scripts/preinstall-probes.mjs

@@ -62,11 +62,16 @@ async function main() {
     console.error(`[ada-mcp preinstall]   registry ${candidate} -> ${latency === null ? "fail" : `${latency}ms`}`);
   }
 
-  /** preinstall 阶段依赖尚未安装，无法校验浏览器包是否存在；仅测官方 CDN，避免写入国内镜像后 404 */
-  const pwCandidates = [
-    "https://cdn.playwright.dev",
-    "https://playwright.azureedge.net"
-  ];
+  const chinaRegistry = /npmmirror|tencent|huaweicloud|huawei\.com/i.test(reg.best);
+  /** preinstall 无 playwright 包时无法 HEAD 浏览器包；国内 registry 时优先写入 npmmirror CDN */
+  const pwCandidates = chinaRegistry
+    ? [
+        "https://cdn.npmmirror.com/binaries/playwright",
+        "https://npmmirror.com/mirrors/playwright",
+        "https://cdn.playwright.dev",
+        "https://playwright.azureedge.net"
+      ]
+    : ["https://cdn.playwright.dev", "https://playwright.azureedge.net"];
   const pw = await detectBestPlaywrightHost(pwCandidates);
   const hostFile = path.join(root, ".ada-mcp-playwright-host");
   fs.writeFileSync(hostFile, `${pw.best}\n`, "utf8");