From b073b7bccd5d03584c961e9a88c1f93f8de0159a Mon Sep 17 00:00:00 2001
From: WJZ_P <110795301+WJZ-P@users.noreply.github.com>
Date: Mon, 16 Mar 2026 01:21:28 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E4=BC=98=E5=8C=96=E6=B5=8F=E8=A7=88?=
 =?UTF-8?q?=E5=99=A8=E5=90=AF=E5=8A=A8=E9=94=99=E8=AF=AF=E6=8F=90=E7=A4=BA?=
 =?UTF-8?q?=EF=BC=8C=E6=96=B0=E5=A2=9E=E7=94=A8=E6=88=B7=E6=95=B0=E6=8D=AE?=
 =?UTF-8?q?=E7=9B=AE=E5=BD=95=E5=8D=A0=E7=94=A8=E6=A3=80=E6=B5=8B=E4=B8=8E?=
 =?UTF-8?q?=E5=A4=84=E7=90=86=E5=BB=BA=E8=AE=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore     |  3 ++-
 src/browser.js | 23 +++++++++++++++++++++--
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index 161f94f..5f08bc7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,4 +4,5 @@ node_modules/
 dist/
 output/
 .env.development
-.env.*.local
\ No newline at end of file
+.env.*.local
+gemini-skill.code-workspace
\ No newline at end of file
diff --git a/src/browser.js b/src/browser.js
index e29b949..0e832ee 100644
--- a/src/browser.js
+++ b/src/browser.js
@@ -385,12 +385,31 @@ export async function ensureBrowser(opts = {}) {
       `[browser] 端口 ${port} 无可用浏览器，且未找到可执行文件。\n` +
       `请通过以下任一方式解决：\n` +
       `  1. 设置环境变量 BROWSER_PATH 指向 Chrome / Edge / Chromium 的可执行文件\n` +
-      `  2. 手动启动浏览器：chrome --remote-debugging-port=${port} --user-data-dir="${userDataDir}"\n` +
+      `  2. 手动启动浏览器并开启调试端口：\n` +
+      `     msedge --remote-debugging-port=${port}\n` +
+      `     chrome --remote-debugging-port=${port}\n` +
       `  3. 安装 Chrome 或 Edge 到默认位置`
     );
   }
 
-  _browser = await launchBrowser({ executablePath: resolvedPath, port, userDataDir, headless });
+  try {
+    _browser = await launchBrowser({ executablePath: resolvedPath, port, userDataDir, headless });
+  } catch (err) {
+    // 大概率是用户数据目录被正在运行的浏览器锁住了
+    if (err.message?.includes('EPERM') || err.message?.includes('lock') || err.message?.includes('already')) {
+      throw new Error(
+        `[browser] 无法启动浏览器，用户数据目录可能被占用：${userDataDir}\n` +
+        `这通常是因为该浏览器正在运行且锁定了数据目录。\n\n` +
+        `请选择以下任一方式解决：\n` +
+        `  方式 1（推荐）：关闭正在运行的浏览器，让 skill 自动启动带调试端口的实例\n` +
+        `  方式 2：保持浏览器运行，手动启用调试端口后重启浏览器：\n` +
+        `          ${resolvedPath} --remote-debugging-port=${port}\n` +
+        `  方式 3：设置 BROWSER_USER_DATA_DIR 为独立目录（将无法复用登录态）`
+      );
+    }
+    throw err;
+  }
+
   const page = await findOrCreateGeminiPage(_browser);
   return { browser: _browser, page };
 }