Browser Agent：共享 Chrome 运行时架构与接入手册

把真实 Chrome、固定 Profile、CDP 和恢复流程收敛为一个本地运行时；业务 Agent 只连接、创建页面并完成自己的任务。

把多个 Agent 都接到同一个 Chrome，并不等于让它们共享同一个任务。真正应该被共享的是运行时：一个可见的真实 Chrome、一个固定 Profile、一条固定 CDP 通道和一套可恢复的生命周期。每个业务任务仍只拥有自己的页面、选择器与结果。

先分清：谁管理运行时，谁完成网页任务

Browser Agent 不是采集器，也不是远程浏览器集群。它只在一台可执行本地命令的机器上管理 Chrome 进程、共享 Profile 和 CDP。业务 Skill 或 Python 项目负责进入网站、读取页面、提交表单或提取数据。

这样可以消除常见的重复劳动：每个项目各自寻找 Chrome、各自创建临时 Profile、各自抢端口、连接失败后各自重启进程。只要业务脚本遵守“只关闭自己 Page”的规则，任务结束时就不会主动带走其他任务仍在复用的共享 Chrome。

固定约定是一份连接合同

这套工具的当前默认配置将运行时放在用户目录下，使用本机回环地址的 19312 端口。上游配置的 Chrome 可执行文件默认值是 macOS 的 Google Chrome 路径；若部署在其他系统，必须通过配置确认可执行文件路径，而不是照抄默认值。

如果要自定义路径、端口或会话名，先检查 config.env 中的 CHROME_BIN、CDP_PORT 与 BROWSER_AGENT_SESSION。修改后是否仍能启动和连接属于运行环境事实，需运行验证。

ensure 把“能否连接”收敛为一个状态机

业务代码不应该先猜 Chrome 是否已启动。它应当把判断交给 ensure：脚本先访问 /json/version，再根据共享 Profile 进程与端口状态决定复用、报错或恢复。

~/browser-agent/browser-agent ensure

这里有一个很重要的边界：ensure 解决的是“Chrome/CDP 是否可用”，不是“页面是否加载成功”“Cookie 是否过期”或“验证码是否已处理”。后几项仍要由业务任务观察并在需要时交给人处理。

接入顺序：保证运行时，再拥有自己的页面

外部 Python 项目最小接入步骤是：先运行 ensure，再以 CDP 附着到 Chrome；从已有 context 中新建页面；完成后只关闭该页面。下面的代码保留了连接与关闭边界，适合作为业务脚本的起点。

import subprocess
from pathlib import Path

from playwright.sync_api import sync_playwright


browser_agent = Path.home() / "browser-agent" / "browser-agent"

subprocess.run([str(browser_agent), "ensure"], check=True)

with sync_playwright() as playwright:
    browser = playwright.chromium.connect_over_cdp(
        "http://127.0.0.1:19312"
    )
    context = browser.contexts[0]
    page = context.new_page()

    try:
        page.goto("https://example.com")
        # 只写当前项目的网站业务逻辑。
    finally:
        page.close()

如果该运行时没有可用 context，或 CDP 协议与客户端版本不兼容，上面示例会失败；这是接入环境而非网页业务本身的问题，需运行验证后再决定如何处理。

复用登录态，不复用页面控制权

同一 Profile 让不同任务看见同一份登录状态。上游规则仍明确要求默认不要并发操作，并让不同任务各自创建页面；因此页面隔离只是最低限度的协作约定，不是多租户安全边界。

验证码、扫码和账号安全验证不应尝试绕过。让用户在可见的 Chrome 中完成验证，再继续运行任务。对有写入、副作用或资金风险的网站，业务层还应自行设计确认、幂等和结果复核；Browser Agent 不替代这些控制。

日常命令：先看状态，再做可定位的动作

除了给 Python 接入，控制入口还封装了 Playwright CLI 的常用页面操作。它会在需要时附着到 CDP；其中 start 当前是 ensure 的别名，close 被显式拒绝，以避免误关共享 Chrome。

snapshot、click、fill 中的引用值取决于当时的页面结构，示例里的 e12 与 e20 不是可跨页面复用的固定选择器。实际页面命令、登录状态和站点反馈均需运行验证。

出现故障时，按影响范围回到正确层级

项目仓库：apexcheng/browser-agent