multi-agents-browser: Instructions file for Codex

ma-browser Agent 开发规范

经验见 learnings.md

架构

CLI (packages/cli) ──HTTP──▶ Daemon (packages/daemon) ──CDP WebSocket──▶ Chrome
MCP (packages/mcp) ──HTTP──┘       │
                              ┌────┴────┐
                              │  HTTP   │
                              │ Server  │
                              └────┬────┘
                                   │
                         ┌─────────┼─────────┐
                         │         │         │
                    CdpConnection  │  CommandDispatch
                    (WebSocket)    │  (request → handler)
                                   │
                            TabStateManager
                            (短 ID, seq 序号,
                             per-tab 事件缓冲)

Daemon 组件：

• CdpConnection — 维持到 Chrome DevTools Protocol 的 WebSocket 长连接。自动发现 Chrome，管理 session 复用（每个 tab 一个 session）。
• TabStateManager — 管理 per-tab 状态。分配短 ID（targetId 末 4+ 位 hex，保证唯一）。维护全局单调递增 seq 计数器。每个 tab 持有环形缓冲事件集合（network/console/errors）。
• CommandDispatch — 将 Request.action 映射到处理函数。所有处理器接收 CdpConnection 和解析后的 TabState，返回带 tab（短 ID）和 seq 的 Response。

核心概念：

• 短 tab ID — 取 CDP targetId 末尾，最少 4 字符，碰撞时自动扩展。所有请求/响应中用短 ID 标识 tab。
• seq 计数器 — 全局单调递增整数，每次操作和每个捕获事件都递增。支持 since 过滤做增量查询。
• Per-tab 事件缓冲 — 环形缓冲（network: 500 条, console: 200 条, errors: 100 条），带 seq 标签。通过 since、filter、method、status、limit 查询。

共享类型定义：packages/shared/src/protocol.ts

添加新命令

3 个文件：

1. packages/shared/src/protocol.ts — 添加 ActionType + Request 字段 + ResponseData 字段
2. packages/daemon/src/command-dispatch.ts — 在 dispatchRequest 中添加处理分支
3. packages/cli/src/commands/<name>.ts + packages/cli/src/index.ts — CLI 命令 + 路由

可选：packages/mcp/src/index.ts — 如果需要暴露为 MCP tool

设计不变量

改代码前必读。违反任何一条都是 bug。

• INV-1: 所有操作响应必须包含 tab（短 ID）和 seq（序号）
• INV-2: 观察类响应（network/console/errors）必须包含 cursor
• INV-3: 无效 tab ID 必须报错，不允许静默 fallback
• INV-4: seq 全局单调递增，不可回退
• INV-5: per-tab 事件隔离 — tab A 的事件不会出现在 tab B 的查询中
• INV-6: tab 关闭时释放短 ID，清除事件缓冲
• INV-7: tab_new 在零 tab 时仍可工作（在 ensurePageTarget 之前处理）