zcode-cdp

为 AI Coding Agent 设计的"已登录浏览器接管"框架 —— 让 agent 用真人已登录的 Chrome 干活，配套生产级端口租约 / 看门狗 / 状态机治理。

English: a logged-in browser takeover framework for AI coding agents (ZCode / Claude Code / Codex). Drives your real, already-logged-in Chrome via the Chrome DevTools Protocol, with production-grade port lease / watchdog / state-machine governance.

为什么用它

通用浏览器自动化（Playwright / Puppeteer / browser-use）的共同前提是每次起一个全新的、无登录态的浏览器实例。当你的场景是：

• agent 要操作已登录账号（公司后台、扫码登录生态、短信验证站点、付费订阅内容），不想把密码/2FA 重新喂给临时浏览器；

• 多个 agent 会话要并发各持一个 Chrome，互不抢端口、互不串数据；

• Chrome 需要长期存活（durable），跨客户端复用，而不是每次冷启动；

zcode-cdp 的答案：

Agent 客户端 (ZCode / Claude Code / Codex / Python 脚本)
        │ MCP stdio 或 CDP 直连
        ▼
zcode-cdp-proxy (懒加载状态机) ── zcode-cdp-lease (端口租约)
        ▼
cdp-takeover (Chrome 启动器 + profile rsync)
        ▼
N 个已登录 Chrome：会话临时池 9223-9229（7 槽）+ 脚本固定端口 93xx（durable）

Related MCP server: chrome-devtools-mcp

快速开始

前置：Node.js ≥ 18、Chrome、npm install -g @playwright/mcp。

1. 克隆仓库，把 bin/ 加入 PATH：

   git clone https://github.com/Lumos-789/zcode-cdp.git
   export PATH="$PWD/zcode-cdp/bin:$PATH"   # 或写进 ~/.zshrc

2. 注册 MCP（按你的客户端三选一）：

   ZCode（~/.zcode/cli/config.json）/ Claude Code（~/.claude.json 或项目级 .mcp.json）：

   {
     "mcpServers": {
       "cdp": { "type": "stdio", "command": "node",
                "args": ["/absolute/path/to/zcode-cdp/bin/zcode-cdp-proxy.js"] }
     }
   }

   Codex（CLI / ChatGPT.app 内置版，~/.codex/config.toml）：

   [mcp_servers.cdp]
   command = "/usr/local/bin/node"   # 绝对路径
   args = ["/absolute/path/to/zcode-cdp/bin/zcode-cdp-proxy.js"]

3. 重启 agent，对它说：「打开 https://your-dashboard.example.com，把今天的订单数读出来」。首次调用自动：rsync 你日常 Chrome 的登录态 → 启动接管 Chrome → 工具直达。browser_close 用完即释放。

首次 rsync 需要几十秒（取决于日常 profile 大小），之后秒级。

三种使用方式

cdp-takeover 9324              # durable：给脚本一个固定端口
cdp-takeover 9324 --refresh    # 强制从日常 Chrome 重 rsync 登录态（实例须已关）
cdp-takeover status            # 端口占用总览

from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp("http://127.0.0.1:9324")
    # 用你已登录的真人 Chrome 干活；用完只断连接，绝不杀 Chrome

文档

配置

所有环境变量都有默认值，不设也能跑。常用的：

完整列表见脚本头部注释或 docs/architecture.md。

兼容性

• macOS 主力测试；Linux 应可用（profile 源路径需手动调整）；Windows 未测试。

• 客户端：任何能注册 stdio MCP server 的 agent（ZCode、Claude Code、Codex 均实测）。

免责声明

⚠️ 本工具仅用于自动化你有合法权限访问的账号和站点。请遵守目标网站的 ToS 与当地法律；对滥用本工具进行批量抓取、规避反爬、账号滥用等行为，作者不承担责任。接管已登录 profile 意味着真实登录态会暴露给 agent，请仅在可信环境中使用。

License

MIT © 2026 Lumos-789