helixlife-v5-cli 1.2.8 → 1.2.9

package/lib/native-mode-patch.js

@@ -0,0 +1,288 @@
+'use strict';
+
+/**
+ * native-mode-patch
+ *
+ * 对 `node_modules/playwright-core/lib/coreBundle.js` 做幂等的纯文本补丁，
+ * 让 Playwright 启动的浏览器在交互层向「CDP 直连原生浏览器」对齐：
+ *
+ *   1) 上传：`Tab` 默认不再急切订阅 `filechooser`，原生选择框可被手动唤起；
+ *      仍以环境变量 `HELIX_NATIVE_FILE_CHOOSER=0` 切回旧行为（保留 `browser_file_upload` 工具）。
+ *   2) 下载：`acceptDownloads` 默认改为 `internal-browser-default`，不再下发
+ *      `Browser.setDownloadBehavior`，浏览器使用原生下载面板（真实文件名 + 原生图标）；
+ *      `HELIX_NATIVE_DOWNLOADS=0` 切回旧行为。
+ *   3) 沙箱：补全 `validateBrowserConfig` 的 `browser.browserName` 推断，
+ *      让 Windows/macOS 上的 `chromiumSandbox` 默认为 `true`，消除 `--no-sandbox` 黄条。
+ *
+ * 设计要点：
+ *   - 全部使用「精确字符串替换」，命中失败时仅打印 warning，不让安装失败；
+ *   - 每条补丁带哨兵注释（`/​* helix-native-mode-patch:<id> *​/`），第二次执行幂等跳过；
+ *   - 任意时刻可通过删除 `node_modules` + `npm i` 还原（postinstall 会再次打补丁）。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SENTINEL_PREFIX = '/* helix-native-mode-patch:';
+
+/**
+ * @typedef {Object} Patch
+ * @property {string} id           哨兵 id（同一文件内唯一）。
+ * @property {string[]} rel        相对 SKILL_ROOT 的路径片段。
+ * @property {string} find         精确匹配的源串（必须在文件中唯一）。
+ * @property {string} replace      替换串（首行写哨兵注释）。
+ */
+
+/** @type {Patch[]} */
+const PATCHES = [
+  {
+    id: 'tab-filechooser-lazy-v1',
+    rel: ['node_modules', 'playwright-core', 'lib', 'coreBundle.js'],
+    find:
+`          eventsHelper.addEventListener(p, "filechooser", (chooser) => {
+            this.setModalState({
+              type: "fileChooser",
+              description: "File chooser",
+              fileChooser: chooser,
+              clearedBy: { tool: uploadFile.schema.name, skill: "upload" }
+            });
+          }),`,
+    replace:
+`          /* helix-native-mode-patch:tab-filechooser-lazy-v1 */
+          (process.env.HELIX_NATIVE_FILE_CHOOSER === "0"
+            ? eventsHelper.addEventListener(p, "filechooser", (chooser) => {
+                this.setModalState({
+                  type: "fileChooser",
+                  description: "File chooser",
+                  fileChooser: chooser,
+                  clearedBy: { tool: uploadFile.schema.name, skill: "upload" }
+                });
+              })
+            : { dispose: () => {} }),`,
+  },
+  {
+    id: 'context-options-default-v1',
+    rel: ['node_modules', 'playwright-core', 'lib', 'coreBundle.js'],
+    find:
+`  if (options.acceptDownloads === void 0 && browserOptions.name !== "electron")
+    options.acceptDownloads = "accept";`,
+    replace:
+`  /* helix-native-mode-patch:context-options-default-v1 */
+  if (options.acceptDownloads === void 0 && browserOptions.name !== "electron")
+    options.acceptDownloads = process.env.HELIX_NATIVE_DOWNLOADS === "0" ? "accept" : "internal-browser-default";`,
+  },
+  {
+    id: 'sandbox-windows-default-v1',
+    rel: ['node_modules', 'playwright-core', 'lib', 'coreBundle.js'],
+    find:
+`  if (browser.browserName === "chromium" && browser.launchOptions.chromiumSandbox === void 0) {`,
+    replace:
+`  /* helix-native-mode-patch:sandbox-windows-default-v1 */
+  if (browser.browserName === void 0 && (browser.launchOptions.channel || browserName === "chromium")) browser.browserName = "chromium";
+  if (browser.browserName === "chromium" && browser.launchOptions.chromiumSandbox === void 0) {`,
+  },
+  {
+    id: 'tab-download-lazy-v1',
+    rel: ['node_modules', 'playwright-core', 'lib', 'coreBundle.js'],
+    find:
+`          eventsHelper.addEventListener(p, "dialog", (dialog) => this._dialogShown(dialog)),
+          eventsHelper.addEventListener(p, "download", (download) => {
+            void this._downloadStarted(download);
+          })`,
+    replace:
+`          eventsHelper.addEventListener(p, "dialog", (dialog) => this._dialogShown(dialog)),
+          /* helix-native-mode-patch:tab-download-lazy-v1 */
+          (process.env.HELIX_NATIVE_DOWNLOADS === "0"
+            ? eventsHelper.addEventListener(p, "download", (download) => {
+                void this._downloadStarted(download);
+              })
+            : { dispose: () => {} })`,
+  },
+  {
+    id: 'cr-download-skip-v1',
+    rel: ['node_modules', 'playwright-core', 'lib', 'coreBundle.js'],
+    find:
+`        if (this._browser.options.name !== "clank" && this._options.acceptDownloads !== "internal-browser-default") {
+          promises.push(this._browser._session.send("Browser.setDownloadBehavior", {
+            behavior: this._options.acceptDownloads === "accept" ? "allowAndName" : "deny",`,
+    replace:
+`        /* helix-native-mode-patch:cr-download-skip-v1 */
+        if (this._browser.options.name !== "clank" && this._options.acceptDownloads !== "internal-browser-default" && process.env.HELIX_NATIVE_DOWNLOADS === "0") {
+          promises.push(this._browser._session.send("Browser.setDownloadBehavior", {
+            behavior: this._options.acceptDownloads === "accept" ? "allowAndName" : "deny",`,
+  },
+  {
+    id: 'bidi-download-skip-v1',
+    rel: ['node_modules', 'playwright-core', 'lib', 'coreBundle.js'],
+    find:
+`        const downloadBehavior = this._options.acceptDownloads === "accept" ? { type: "allowed", destinationFolder: this._browser.options.downloadsPath } : { type: "denied" };
+        promises.push(this._browser._browserSession.send("browser.setDownloadBehavior", {
+          downloadBehavior,
+          userContexts: [this._userContextId()]
+        }));`,
+    replace:
+`        /* helix-native-mode-patch:bidi-download-skip-v1 */
+        if (this._options.acceptDownloads !== "internal-browser-default" && process.env.HELIX_NATIVE_DOWNLOADS === "0") {
+          const downloadBehavior = this._options.acceptDownloads === "accept" ? { type: "allowed", destinationFolder: this._browser.options.downloadsPath } : { type: "denied" };
+          promises.push(this._browser._browserSession.send("browser.setDownloadBehavior", {
+            downloadBehavior,
+            userContexts: [this._userContextId()]
+          }));
+        }`,
+  },
+  // 注意：曾有 skip-automation-controlled-v1 补丁，会在原生模式下抑制
+  //   `--disable-blink-features=AutomationControlled` 启动参数，导致
+  //   `navigator.webdriver === true` 被阿里云图形验证码风控判定为自动化设备。
+  //   该补丁已下线，由下方 REVERSE_PATCHES 在 postinstall 时自动回退到 Playwright 原行为。
+];
+
+/**
+ * @typedef {Object} ReversePatch
+ * @property {string} id          被回退的补丁 id（与历史哨兵注释 id 一致）。
+ * @property {string[]} rel       相对 SKILL_ROOT 的路径片段。
+ * @property {string} find        当前被打过补丁的代码块（含哨兵注释）。
+ * @property {string} replace     回退后的原始 Playwright 代码块。
+ */
+
+/**
+ * 历史补丁回退表：已经写进 node_modules 的旧补丁，在新版本安装/postinstall 时自动撤销，
+ * 保证未删除 node_modules 的用户也能拿到修复。
+ * 命中失败（说明本机其实没打过该补丁）会静默跳过。
+ *
+ * @type {ReversePatch[]}
+ */
+const REVERSE_PATCHES = [
+  {
+    id: 'skip-automation-controlled-v1',
+    rel: ['node_modules', 'playwright-core', 'lib', 'coreBundle.js'],
+    find:
+      '  /* helix-native-mode-patch:skip-automation-controlled-v1 */\n' +
+      '  if (browserName === "chromium") {\n' +
+      '    browser.launchOptions.args = browser.launchOptions.args ?? [];\n' +
+      '    if (process.env.HELIX_NATIVE_FILE_CHOOSER === "0" && !browser.launchOptions.args.some((a) => a.includes("--disable-blink-features")))\n' +
+      '      browser.launchOptions.args.push(`--disable-blink-features=AutomationControlled`);\n' +
+      '  }',
+    replace:
+      '  if (browserName === "chromium") {\n' +
+      '    browser.launchOptions.args = browser.launchOptions.args ?? [];\n' +
+      '    if (!browser.launchOptions.args.some((a) => a.includes("--disable-blink-features")))\n' +
+      '      browser.launchOptions.args.push(`--disable-blink-features=AutomationControlled`);\n' +
+      '  }',
+  },
+];
+
+/**
+ * 文件内是否已写入指定哨兵。
+ * @param {string} content
+ * @param {string} id
+ */
+function alreadyPatched(content, id) {
+  return content.includes(`${SENTINEL_PREFIX}${id} */`);
+}
+
+/**
+ * 回退历史补丁：把 REVERSE_PATCHES 中已写入 node_modules 的旧补丁还原成 Playwright 原始代码。
+ * 仅命中带哨兵的旧补丁，普通源码不受影响。
+ * @param {string} skillRoot
+ * @param {(msg: string) => void} log
+ * @returns {{ reverted: number }}
+ */
+function revertLegacyPatches(skillRoot, log) {
+  let reverted = 0;
+  for (const patch of REVERSE_PATCHES) {
+    const file = path.join(skillRoot, ...patch.rel);
+    if (!fs.existsSync(file)) {
+      continue;
+    }
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch (e) {
+      log(`无法读取 ${file}: ${e && e.message ? e.message : e}`);
+      continue;
+    }
+    if (!content.includes(patch.find)) {
+      continue;
+    }
+    const next = content.replace(patch.find, patch.replace);
+    if (next === content) {
+      continue;
+    }
+    try {
+      fs.writeFileSync(file, next, 'utf8');
+      reverted += 1;
+      log(`已回退历史补丁: ${patch.id}`);
+    } catch (e) {
+      log(`写入 ${file} 失败: ${e && e.message ? e.message : e}`);
+    }
+  }
+  return { reverted };
+}
+
+/**
+ * 在 skillRoot 上幂等应用全部补丁；执行前先回退历史 REVERSE_PATCHES，再依次应用 PATCHES。
+ * @param {string} skillRoot
+ * @param {{ log?: (msg: string) => void }} [options]
+ * @returns {{ applied: number, skipped: number, missed: string[] }}
+ */
+function applyAll(skillRoot, options = {}) {
+  const log = options.log || (() => {});
+  revertLegacyPatches(skillRoot, log);
+  let applied = 0;
+  let skipped = 0;
+  const missed = [];
+
+  for (const patch of PATCHES) {
+    const file = path.join(skillRoot, ...patch.rel);
+    if (!fs.existsSync(file)) {
+      // node_modules 还没装好（首次执行 postinstall 之前可能命中），正常跳过。
+      continue;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch (e) {
+      log(`无法读取 ${file}: ${e && e.message ? e.message : e}`);
+      continue;
+    }
+
+    if (alreadyPatched(content, patch.id)) {
+      skipped += 1;
+      continue;
+    }
+
+    if (!content.includes(patch.find)) {
+      missed.push(patch.id);
+      log(
+        `patch "${patch.id}" 未命中目标片段，可能 playwright-core 版本已变化；` +
+          `请核对源码后更新 lib/native-mode-patch.js 中的 PATCHES 表。`
+      );
+      continue;
+    }
+
+    const next = content.replace(patch.find, patch.replace);
+    if (next === content) {
+      missed.push(patch.id);
+      continue;
+    }
+
+    try {
+      fs.writeFileSync(file, next, 'utf8');
+      applied += 1;
+      log(`已应用补丁: ${patch.id}`);
+    } catch (e) {
+      log(`写入 ${file} 失败: ${e && e.message ? e.message : e}`);
+    }
+  }
+
+  return { applied, skipped, missed };
+}
+
+module.exports = {
+  applyAll,
+  revertLegacyPatches,
+  PATCHES,
+  REVERSE_PATCHES,
+  SENTINEL_PREFIX,
+};

package/lib/postinstall.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * npm `postinstall` 钩子：依赖安装完成后，立即隐藏依赖包内自带的嵌套 Skill，
+ * 确保对外只暴露唯一入口 `helixlife-v5-cli`，不会出现 playwright-cli /
+ * playwright-trace 等拆分工具项。
+ *
+ * 在 `npm install` 返回前同步执行，因此安装结束时嵌套 Skill 已不可被技能扫描器发现。
+ * 任何失败都不应让安装失败，故全程吞错并以 0 退出。
+ */
+
+const path = require('node:path');
+
+const skillRoot = path.join(__dirname, '..');
+
+try {
+  const { hideNestedSkills } = require('./hide-nested-skills');
+  hideNestedSkills(skillRoot, {
+    log: (msg) => console.error(`[helixlife-v5-cli] ${msg}`),
+  });
+} catch (e) {
+  if (process.env.HELIX_DEBUG) {
+    console.error(e);
+  }
+}
+
+try {
+  const { applyAll } = require('./native-mode-patch');
+  applyAll(skillRoot, {
+    log: (msg) => console.error(`[helixlife-v5-cli][native-mode-patch] ${msg}`),
+  });
+} catch (e) {
+  if (process.env.HELIX_DEBUG) {
+    console.error(e);
+  }
+}
+
+process.exit(0);

package/lib/profile-lock-guard.js

@@ -0,0 +1,187 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+/** Playwright/Chromium 报 profile 被占用时的典型日志片段 */
+const PROFILE_IN_USE_MARKERS = [
+  'Failed to create a ProcessSingleton for your profile directory.',
+  'profile is already in use',
+  'Opening in existing browser session.',
+  'Browser is already in use',
+];
+
+const UNIX_LOCK_FILES = ['SingletonLock', 'SingletonCookie', 'SingletonSocket'];
+const WIN_LOCK_FILES = ['lockfile'];
+
+function lockFilesForPlatform() {
+  return process.platform === 'win32' ? WIN_LOCK_FILES : UNIX_LOCK_FILES;
+}
+
+function isProfileInUseError(text) {
+  const t = String(text || '');
+  return PROFILE_IN_USE_MARKERS.some((m) => t.includes(m));
+}
+
+function normalizeForMatch(dir) {
+  return path.normalize(dir).replace(/\\/g, '/');
+}
+
+/**
+ * 是否有 Chrome/Chromium 进程正在占用该 user-data-dir。
+ * @param {string} profileDir
+ * @returns {boolean}
+ */
+function isChromeUsingProfile(profileDir) {
+  const needle = normalizeForMatch(profileDir);
+  if (process.platform === 'win32') {
+    const script = [
+      'Get-CimInstance Win32_Process |',
+      "Where-Object { $_.CommandLine -and ($_.CommandLine -like '*chrome*' -or $_.CommandLine -like '*chromium*') }",
+      '| Select-Object -ExpandProperty CommandLine',
+    ].join(' ');
+    const result = spawnSync(
+      'powershell',
+      ['-NoProfile', '-NonInteractive', '-Command', script],
+      { encoding: 'utf8', windowsHide: true },
+    );
+    const out = String(result.stdout || '');
+    return out.split(/\r?\n/).some((line) => {
+      const normalized = line.replace(/\\/g, '/');
+      return normalized.includes('user-data-dir') && normalized.includes(needle);
+    });
+  }
+
+  const result = spawnSync('ps', ['auxww'], { encoding: 'utf8' });
+  const out = String(result.stdout || '');
+  return out.split(/\r?\n/).some((line) => {
+    const lower = line.toLowerCase();
+    if (!lower.includes('user-data-dir')) return false;
+    const normalized = line.replace(/\\/g, '/');
+    return normalized.includes(needle);
+  });
+}
+
+/**
+ * 在无活跃 Chrome 进程时移除残留的 profile 锁文件。
+ * macOS 上用户手动关闭浏览器窗口后，SingletonLock 等文件常会残留，导致下次 open 失败。
+ * @param {string} profileDir
+ * @param {(msg: string) => void} [log]
+ * @returns {{ removed: string[], skipped?: boolean }}
+ */
+function removeStaleProfileLocks(profileDir, log) {
+  if (!profileDir || !fs.existsSync(profileDir)) {
+    return { removed: [] };
+  }
+  if (isChromeUsingProfile(profileDir)) {
+    return { removed: [], skipped: true };
+  }
+
+  const removed = [];
+  for (const name of lockFilesForPlatform()) {
+    const file = path.join(profileDir, name);
+    try {
+      if (fs.existsSync(file)) {
+        fs.rmSync(file, { force: true });
+        removed.push(name);
+      }
+    } catch (e) {
+      log?.(`无法删除 profile 锁文件 ${file}: ${e.message}`);
+    }
+  }
+  if (removed.length > 0) {
+    log?.(`已清理残留 profile 锁: ${removed.join(', ')}`);
+  }
+  return { removed };
+}
+
+/**
+ * 从 open 命令参数中解析 --profile 目录。
+ * @param {string[]} tokens
+ * @param {(dir?: string) => string} resolveProfileDir
+ * @returns {string | null}
+ */
+function extractProfileDirFromOpenArgs(tokens, resolveProfileDir) {
+  let i = 0;
+  if (tokens[i] === '--raw') i += 1;
+  if (tokens[i] === '--json') i += 1;
+  if (tokens[i] && tokens[i].startsWith('-s=')) i += 1;
+  if (tokens[i] !== 'open') return null;
+  i += 1;
+  for (; i < tokens.length; i += 1) {
+    const t = tokens[i];
+    if (t === '--profile') {
+      const next = tokens[i + 1];
+      if (next !== undefined) return resolveProfileDir(next);
+    } else if (t.startsWith('--profile=')) {
+      return resolveProfileDir(t.slice('--profile='.length));
+    } else if (t.startsWith('--') && !t.includes('=')) {
+      const next = tokens[i + 1];
+      if (next !== undefined && !next.startsWith('-')) i += 1;
+    }
+  }
+  return null;
+}
+
+/**
+ * open 前温和清理：结束可能已断开的 daemon 会话，并移除无进程占用的残留锁。
+ * @param {string} profileDir
+ * @param {(args: string[], opts?: object) => unknown} runPassthrough
+ * @param {(msg: string) => void} [log]
+ */
+function prepareProfileBeforeOpen(profileDir, runPassthrough, log) {
+  runPassthrough(['close'], { capture: true });
+  removeStaleProfileLocks(profileDir, log);
+}
+
+/**
+ * 对带 --profile 的 open 命令做锁文件自愈：先预防性清理，失败后再 kill-all 并重试一次。
+ * @param {string[]} tokens
+ * @param {(args: string[], opts?: object) => number | { code: number, stdout: string, stderr: string }} runPassthrough
+ * @param {{ resolveProfileDir: (dir?: string) => string, log?: (msg: string) => void }} options
+ * @returns {number | { code: number, stdout: string, stderr: string }}
+ */
+function runOpenWithProfileRecovery(tokens, runPassthrough, options) {
+  const profileDir = extractProfileDirFromOpenArgs(tokens, options.resolveProfileDir);
+  if (!profileDir) {
+    return runPassthrough(tokens);
+  }
+
+  prepareProfileBeforeOpen(profileDir, runPassthrough, options.log);
+
+  const first = runPassthrough(tokens, { capture: true });
+  if (first.code === 0) {
+    if (first.stdout) process.stdout.write(first.stdout);
+    if (first.stderr) process.stderr.write(first.stderr);
+    return 0;
+  }
+
+  const errText = `${first.stderr || ''}\n${first.stdout || ''}`;
+  if (!isProfileInUseError(errText)) {
+    if (first.stdout) process.stdout.write(first.stdout);
+    if (first.stderr) process.stderr.write(first.stderr);
+    return first.code;
+  }
+
+  options.log?.(
+    '[helixlife-v5-cli] 检测到 profile 被占用（常见于 macOS 手动关闭浏览器后），正在强制清理并重试 open…',
+  );
+  runPassthrough(['kill-all'], { capture: true });
+  removeStaleProfileLocks(profileDir, options.log);
+
+  const retry = runPassthrough(tokens, { capture: true });
+  if (retry.stdout) process.stdout.write(retry.stdout);
+  if (retry.stderr) process.stderr.write(retry.stderr);
+  return retry.code;
+}
+
+module.exports = {
+  PROFILE_IN_USE_MARKERS,
+  isProfileInUseError,
+  isChromeUsingProfile,
+  removeStaleProfileLocks,
+  extractProfileDirFromOpenArgs,
+  prepareProfileBeforeOpen,
+  runOpenWithProfileRecovery,
+};

package/lib/runtime-config.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * runtime-config
+ *
+ * 输出与 playwright-cli `--config` schema 兼容的「原生交互模式」浏览器配置片段。
+ * 由 `lib/visual.js` 的 `buildRuntimeBrowserConfig` 在生成 `.cli.runtime.generated.json`
+ * 时一并合并进 `browser` 对象，所有 open/attach 命令自动生效：
+ *
+ *   - `browser.contextOptions.acceptDownloads = "internal-browser-default"`
+ *     不再下发 `Browser.setDownloadBehavior`，浏览器使用原生下载面板（真实文件名 + 原生图标）。
+ *   - `browser.launchOptions.chromiumSandbox = true`
+ *     消除 `--no-sandbox` 黄条（Windows / macOS 上原本就该开启沙箱）。
+ *   - `browser.launchOptions.downloadsPath = <用户主目录>/Downloads`
+ *     用户回退到 `acceptDownloads:"accept"` 时也能落到熟悉的下载目录。
+ *
+ * 通过环境变量 `HELIX_NATIVE_DOWNLOADS=0` 关闭原生下载（保留 Playwright `download` 事件抓取）。
+ * 通过 `HELIX_NATIVE_FILE_CHOOSER=0` 关闭原生上传（恢复旧的 `browser_file_upload` 工具行为）。
+ * 这两个开关由 `lib/native-mode-patch.js` 在 `coreBundle.js` 中读取。
+ *
+ * 另外两个环境变量在本模块内生效：
+ *   - `HELIX_CHROMIUM_SANDBOX=0` 关闭 chromium 沙箱（仅排障，默认开启）。
+ *   - `HELIX_HIDE_WEBDRIVER=0`  跳过 `--disable-blink-features=AutomationControlled` 注入，
+ *     `navigator.webdriver` 将被暴露为 true（仅自我测试场景使用，正式环境会被风控判定为自动化）。
+ */
+
+const os = require('node:os');
+const path = require('node:path');
+
+/** Skill 根目录（含本仓库 package.json 的目录）。 */
+const SKILL_ROOT = path.join(__dirname, '..');
+
+/**
+ * 解析下载默认目录：
+ *   - 优先使用 `HELIX_DOWNLOADS_DIR` 环境变量；
+ *   - 否则统一落在用户主目录下的 `Downloads`（Win/macOS/Linux 均一致）。
+ */
+function resolveDownloadsPath() {
+  const explicit = process.env.HELIX_DOWNLOADS_DIR;
+  if (explicit && explicit.trim()) return explicit.trim();
+  return path.join(os.homedir(), 'Downloads');
+}
+
+/**
+ * 把原生交互模式的 launchOptions / contextOptions 合并进给定的 `browser` 对象。
+ * 已显式设值的字段不会被覆盖（用户/上层注入优先）。
+ *
+ * @param {Record<string, any>} browser
+ * @returns {Record<string, any>}
+ */
+function applyNativeBrowserOverrides(browser) {
+  const next = { ...(browser || {}) };
+
+  const launchOptions = { ...(next.launchOptions || {}) };
+  if (launchOptions.chromiumSandbox === undefined) {
+    launchOptions.chromiumSandbox = process.env.HELIX_CHROMIUM_SANDBOX !== '0';
+  }
+  if (launchOptions.downloadsPath === undefined) {
+    launchOptions.downloadsPath = resolveDownloadsPath();
+  }
+  // 防御性显式注入 `--disable-blink-features=AutomationControlled`：
+  //   - 与 Playwright 内部 `validateBrowserConfig` 的注入逻辑互不冲突（对方检测到任一
+  //     `--disable-blink-features` 即跳过，不会重复注入）；
+  //   - 即便未来上游默认行为变化或本仓库回退掉 `coreBundle.js` 的相关补丁，
+  //     `navigator.webdriver` 也始终为 undefined，避免被阿里云等图形验证码风控误判为自动化设备。
+  if (process.env.HELIX_HIDE_WEBDRIVER !== '0') {
+    const args = [...(launchOptions.args || [])];
+    if (!args.some((a) => String(a).includes('--disable-blink-features'))) {
+      args.push('--disable-blink-features=AutomationControlled');
+    }
+    launchOptions.args = args;
+  }
+  next.launchOptions = launchOptions;
+
+  const contextOptions = { ...(next.contextOptions || {}) };
+  const acceptDownloads =
+    contextOptions.acceptDownloads ?? 'internal-browser-default';
+  contextOptions.acceptDownloads = acceptDownloads;
+  next.contextOptions = contextOptions;
+  // launchPersistentContext 合并时 contextOptions 会 spread 到顶层；双写以防 merge 顺序问题。
+  next.launchOptions.acceptDownloads = acceptDownloads;
+
+  return next;
+}
+
+module.exports = {
+  applyNativeBrowserOverrides,
+  resolveDownloadsPath,
+  SKILL_ROOT,
+};