agent-chrome
本机 AI 浏览器自动化的统一 Chrome 启动器与约定:每个登录态一个 profile(~/.chrome-profiles/<站点>-<别名>),用正式版 Google Chrome 在固定 CDP 端口上 up/down,agent-browser、Playwright、python CDP 都只连端口、不自己起浏览器。Use when 需要浏览器自动化、需要某网站的登录态、要起 Chro
SKILL.mdagent-chrome/SKILL.md
GitHubagent-chrome
一个脚本管所有带登录态的自动化 Chrome:scripts/agent_chrome.py(python3 标准库;种 cookie、开后台窗口、优雅关闭用 Node ≥ 22 内置 WebSocket)。
约定
- 二进制:需要登录态的一律用正式版
/Applications/Google Chrome.app。Chrome for Testing / Playwright 自带 Chromium 只用于无登录的渲染测试。 - 根目录与命名:profile 都在
~/.chrome-profiles/($AGENT_CHROME_ROOT可改),登记在registry.json。名字一律<站点>-<别名>,首个账号别名固定main(x-main、goofish-main),永不用裸站点名;site_defaults把站点简名映射到默认 profile,所以up x等于up x-main。 - 登录态只存 profile 一份:不导出 cookie 文件、不用
--state/--session-name另存、不每次注入。 - 主 Chrome 只读:用户自己的 Chrome 不启动、不 kill、不写;只在
seed --from-main时复制它的 Cookies 库读一次,作为新 profile 的首次引导。 - 启动与端口:端口池 19300–19399,登记时分配、固定不变;禁用 9222。headless 优先;有头窗口用
open -g+ 无启动窗口 + CDP 后台开窗,不抢焦点。 - 生命周期:用前
up,用完down(走 Browser.close,cookie 才落盘)。脚本里只down自己拉起的(up输出reused:false),reused:true说明别人在用,不要关。daemon:true的常驻 profile 没有--force拒绝关闭。 - keychain 自动识别:Playwright 建的 profile 用 mock keychain 加密 cookie,正式 Chrome 建的用系统钥匙串;
add时自动检测写进 registry,up据此决定是否加--use-mock-keychain,否则会整体掉登录。 - 新代码只走本脚本:老代码(registry 里 note 写着 legacy 的)逐步迁,迁之前它们仍用自带端口或 Playwright 直接起,别同时用两边打开同一个目录。
CLI 速查
AC="$(dirname "$(readlink -f "$0")")/scripts/agent_chrome.py" # skill 目录下的脚本
python3 "$AC" ls # name/port/sites/daemon/running
python3 "$AC" add x-alt --sites x.com,twitter.com # 新账号;--dir 已有目录名 / --daemon / --note / --default-for x
python3 "$AC" resolve x # -> x-main
python3 "$AC" up x --headless [--url URL] # -> {"profile","dir","port","ws","pid","headless","reused"}
python3 "$AC" down x-main [--force]
python3 "$AC" status [x-main] # running/pid/port/headless/started/occupied_by_other
python3 "$AC" seed x-main --from-main --domains x.com,twitter.com
bash "$(dirname "$AC")/test_agent_chrome.sh" # 改脚本后跑,临时根目录,全 headless
失败时退出码非 0,stderr 一句中文原因。down 例外:Browser.close 走不通(缺 node、helper 超时)时降级为 SIGTERM,仍关掉浏览器,stderr 提示最近的 cookie 改动可能没落盘,退出码 0。目录被别的 Chrome 占着(端口不对)时只报 pid,不杀。
接法
agent-browser:每条命令带 --cdp <port>,并用独立 --session;close 在 --cdp 下只断开,不关浏览器。
PORT=$(python3 "$AC" up x --headless | python3 -c 'import json,sys;print(json.load(sys.stdin)["port"])')
agent-browser --session my-task --cdp "$PORT" open https://x.com/home
agent-browser --session my-task --cdp "$PORT" get title
Playwright(Node):chromium.connectOverCDP,用已有 context,不要 launch*。
const { port } = JSON.parse(execFileSync("python3", [AC, "up", "x", "--headless"], { encoding: "utf8" }));
const browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`);
const page = browser.contexts()[0].pages()[0] ?? await browser.contexts()[0].newPage();
python CDP:取 ws 字段直连浏览器级 WebSocket,或用 Playwright for Python 同样 connect_over_cdp。
info = json.loads(subprocess.check_output(["python3", AC, "up", "x", "--headless"]))
browser = sync_playwright().start().chromium.connect_over_cdp(f"http://127.0.0.1:{info['port']}")
# 或者裸 CDP: websocket 连 info["ws"],发 {"id":1,"method":"Target.getTargets"}
登录过期
业务脚本发现登录页时不要自己尝试登录,打印下面两条之一交给用户:
- 有头扫码:
python3 "$AC" down <name>(若在跑)→python3 "$AC" up <name> --url <登录页>,窗口在后台打开,告诉用户去 Chrome 里扫码 / 输验证码,完成后down <name>。 - 从主 Chrome 引导:用户的主 Chrome 已登录同一账号时,
python3 "$AC" seed <name> --from-main --domains <主域,...>。只读复制主 Chrome 的 Cookies 库,用钥匙串(首次可能弹授权框)解密后经 CDP 写进 profile,打印导入条数;之后登录态就只在 profile 里续期。
新增账号同理:add <站点>-<别名> 后用上面任一方式登录一次。