# Shared browser / Agent 接入协议

这是带人工接管能力的 Playwright MCP 服务。服务地址为本文件 URL 去掉 `/agent.md`。
密钥由管理员以环境变量 AGENT_TOKEN 提供，不要把密钥写入聊天、URL 或日志。

推荐：在 Agent 所在机器下载本项目、执行 npm ci，配置 stdio MCP：
command: node
args: ["/absolute/path/browser-handoff/agent-bridge.mjs"]
env: BROWSER_SERVICE_URL=https://browser.example.com, AGENT_TOKEN=<由密钥配置注入>
适配器自动领取使用权，使用标准 Playwright MCP 工具，正常退出时释放。
服务端不会调用模型，不要求安装 Codex，任何支持 MCP 的 Agent 均可接入。

也可以直接使用 Streamable HTTP：
1. POST /api/lease，Authorization: Bearer <AGENT_TOKEN>，领取 leaseId。
2. MCP 地址 /mcp；每次请求携带 Authorization 和 X-Browser-Lease: <leaseId>。
3. 按 MCP 标准初始化、列出工具、调用 browser_snapshot、browser_click 等。
4. 结束时关闭 MCP 传输，再 DELETE /api/lease，携带相同两个请求头。

## 协作规则
- 一个实例只有一个浏览器使用权。409 占用时不得抢占、重试写操作或创建绕行连接。
- 人工接管时，新 tools/call 会被拒绝；已经发出的操作必须结束后才交接。
- 人工接管只禁止浏览器操作，不会暂停你的推理进程。收到接管提示后等待人处理。
- GET /api/status 可读取 mode；恢复为 ai 后，先 browser_tabs(list)，对照 status.pageId 对应的界面标签信息选择页面，再 browser_snapshot，重新理解页面后继续。
- 控制服务的 pageId 与 Playwright 的标签序号不是同一个 ID；按标题/URL核对，不直接拿 pageId 当 index。
- 网络失败时写操作结果可能未知，先检查页面，不自动重复点击/提交。
- 不直接连接底层 CDP，这会绕过人工接管。底层浏览器密钥仅供服务管理员使用。
- 不主动关闭整个浏览器。下载文件可能位于远程浏览器或 MCP 服务所在主机；本项目不提供文件同步。
- 强制杀死 Agent 后，使用权不会超时转给别人，避免上一条操作尚在执行；由人工页面释放。