dev-browser

Dev Browser

用途

Dev Browser 是一个浏览器自动化工具，定位为回退（fallback）路径：仅当 @browser-use 不可用或被阻止时才使用它。资料明确要求不要用 Puppeteer、独立 Playwright 或原始 Chrome DevTools 来替代这一回退路径。

主要能力

它通过连接一个长期运行的调试 Chrome 实例（默认 127.0.0.1:9222）来执行浏览器自动化，并复用该实例的持久化状态（包括登录状态）。资料建议保持一个持久的调试 Chrome，而不是为每次任务启动一次性浏览器实例。脚本中可使用 browser.getPage("persistent-main") 获取主应用页面。

安装

npm install -g dev-browser dev-browser install

运行 dev-browser --help 可了解更多信息。

使用方式

默认使用 dev-browser --connect http://127.0.0.1:9222，不要先对 9222 做预检。只有在直接连接尝试失败后，才去检查 9222。

建议使用一个专用的 Chrome --user-data-dir 作为调试浏览器目录，而不是用户日常使用的 Chrome 数据目录。做法是：将已登录的 Chrome 配置文件克隆到专用调试目录，再从该克隆启动调试浏览器。

在 macOS 上，使用 open -na "Google Chrome" --args ... --remote-debugging-port=9222 启动调试浏览器，使其作为独立的 Chrome 实例打开，而不劫持用户正常窗口。

不要关闭或停止用户已连接的调试浏览器，保持该调试窗口打开并复用；仅在需要时关闭具名页面。保持脚本简短直接。

在 Plate 场景下，默认使用 dev-browser --connect http://127.0.0.1:9222；对于 Plate registry/browser 验证，当存在独立的 /blocks/[id]-demo 路由时，优先使用它而非 docs 包装页。使用 dev-browser 而非 agent-browser 或 next-devtools 的 browser_eval。

如果 dev-browser 被人为提示阻塞或在同一步骤上循环，应停止并请用户解除阻塞。

回退设置

仅当 dev-browser --connect http://127.0.0.1:9222 因没有可复用的调试 Chrome 或 CDP 端点损坏而失败后，才使用此回退设置。

规则：优先使用一个永久调试浏览器/配置文件，而非一次性自动化浏览器；自定义 --user-data-dir 是强制要求而非可选（Chrome 136+ 期望远程调试在专用配置文件下进行）；在该配置文件中保留认证信息，除非用户要求，不要回退到 cookie 转储或状态文件；使用单独的已登录 Chrome 配置文件（如 dev）进行浏览器工作，不要使用用户日常的 Default 配置文件作为源；将该单独的已登录配置文件克隆到专用调试 --user-data-dir，不要把 9222 直接指向用户日常 Chrome 数据目录；在 macOS 上使用 open -na "Google Chrome" --args ... 启动调试浏览器。

首选形态

使用带以下参数的专用浏览器/配置文件：

--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 持久化的 --user-data-dir=<debug-profile-dir>

在该专用浏览器中登录一次，并持续复用于代理工作。

快速健全性检查：

curl -sS http://127.0.0.1:9222/json/version

健康输出包含带 webSocketDebuggerUrl 的 JSON 对象。空输出或 404 表示 9222 被错误的进程占用。

然后验证：

dev-browser --connect http://127.0.0.1:9222 <<'EOF' const page = await browser.getPage("persistent-main"); console.log(await page.title()); EOF

如果 /json/version 健康但直接连接仍无法解析 CDP，则使用确切的 websocket URL 连接：

WS=$(curl -sS http://127.0.0.1:9222/json/version | jq -r '.webSocketDebuggerUrl')

dev-browser --connect "$WS" <<'EOF' const page = await browser.getPage("persistent-main"); console.log(await page.title()); EOF

Google Chrome 路径（macOS 默认设置）

选择一个单独的已登录 Chrome 配置文件用于代理工作（如 dev），而非日常 Default 配置文件；将该面向人类的 Chrome 配置文件名称映射到 Local State 中的真实文件夹；将该配置文件克隆到专用调试目录；在 9222 上启动独立的 Chrome 实例；保持该调试窗口打开并复用。

python3 - <<'PY' import json, pathlib p = pathlib.Path('~/Library/Application Support/Google/Chrome/Local State').expanduser() obj = json.loads(p.read_text()) for key, val in obj.get('profile', {}).get('info_cache', {}).items(): print(f"{key}\tname={val.get('name')}\tgaia_name={val.get('gaia_name')}") PY

Example: if dev maps to Profile 1, clone Profile 1.

mkdir -p "$HOME/.config/google-chrome-debug-profile/Default" rsync -a --delete
--exclude='Singleton*'
--exclude='DevToolsActivePort'
--exclude='lockfile'
"$HOME/Library/Application Support/Google/Chrome/Profile 1/"
"$HOME/.config/google-chrome-debug-profile/Default/" cp "$HOME/Library/Application Support/Google/Chrome/Local State"
"$HOME/.config/google-chrome-debug-profile/Local State"

open -na "Google Chrome" --args
--user-data-dir="$HOME/.config/google-chrome-debug-profile"
--profile-directory="Default"
--remote-debugging-address=127.0.0.1
--remote-debugging-port=9222

不要把 9222 指向日常 Default Chrome 配置文件。如果错误的 Chrome 抢占了 9222，用以下命令识别：

lsof -nP -iTCP:9222 -sTCP:LISTEN

终止该监听进程并重新启动专用调试浏览器。不要继续针对陈旧的 404 或空 /json/version 占用者进行调试。

适用场景

适用于需要在已登录状态下进行浏览器自动化、且 Browser Use 不可用或被阻止的场景，尤其是需要复用持久登录状态、避免重复登录的代理工作。

限制

仅作为回退路径使用，不应替代 Browser Use；不得用 Puppeteer、独立 Playwright 或原始 Chrome DevTools 替代；自定义 --user-data-dir 为强制要求；遇到人为提示阻塞或循环时应停止并请求用户解除。