agent-chrome

一个脚本管所有带登录态的自动化 Chrome：scripts/agent_chrome.py（python3 标准库；种 cookie、开后台窗口、优雅关闭用 Node ≥ 22 内置 WebSocket）。

约定

1. 二进制：需要登录态的一律用正式版 /Applications/Google Chrome.app。Chrome for Testing / Playwright 自带 Chromium 只用于无登录的渲染测试。
2. 根目录与命名：profile 都在 ~/.chrome-profiles/（$AGENT_CHROME_ROOT 可改），登记在 registry.json。名字一律 <站点>-<别名>，首个账号别名固定 main（x-main、goofish-main），永不用裸站点名；site_defaults 把站点简名映射到默认 profile，所以 up x 等于 up x-main。
3. 登录态只存 profile 一份：不导出 cookie 文件、不用 --state / --session-name 另存、不每次注入。
4. 主 Chrome 只读：用户自己的 Chrome 不启动、不 kill、不写；只在 seed --from-main 时复制它的 Cookies 库读一次，作为新 profile 的首次引导。
5. 启动与端口：端口池 19300–19399，登记时分配、固定不变；禁用 9222。headless 优先；有头窗口用 open -g + 无启动窗口 + CDP 后台开窗，不抢焦点。
6. 生命周期：用前 up，用完 down（走 Browser.close，cookie 才落盘）。脚本里只 down 自己拉起的（up 输出 reused:false），reused:true 说明别人在用，不要关。daemon:true 的常驻 profile 没有 --force 拒绝关闭。
7. keychain 自动识别：Playwright 建的 profile 用 mock keychain 加密 cookie，正式 Chrome 建的用系统钥匙串；add 时自动检测写进 registry，up 据此决定是否加 --use-mock-keychain，否则会整体掉登录。
8. 新代码只走本脚本：老代码（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"}

登录过期

业务脚本发现登录页时不要自己尝试登录，打印下面两条之一交给用户：

1. 有头扫码：python3 "$AC" down <name>（若在跑）→ python3 "$AC" up <name> --url <登录页>，窗口在后台打开，告诉用户去 Chrome 里扫码 / 输验证码，完成后 down <name>。
2. 从主 Chrome 引导：用户的主 Chrome 已登录同一账号时，python3 "$AC" seed <name> --from-main --domains <主域,...>。只读复制主 Chrome 的 Cookies 库，用钥匙串（首次可能弹授权框）解密后经 CDP 写进 profile，打印导入条数；之后登录态就只在 profile 里续期。

新增账号同理：add <站点>-<别名> 后用上面任一方式登录一次。