Browser Agent 是一个面向 Windows 桌面环境的可视化浏览器 E2E 测试 MVP。它使用 Playwright 启动真实、可见、保留登录态的 Chromium 浏览器，并通过独立控制台提供 Agent、 Steps 和 Manual 三种运行模式。
当前定位是单机、单浏览器会话的开发验证工具，不是多用户测试平台。服务没有鉴权、任务队列、 高风险动作审批或完整 CI Runner，请只在受控测试环境使用。
- 启动持久化、有头的 Microsoft Edge / Chrome / Playwright Chromium。
- Agent 模式通过 OpenAI-compatible Chat Completions + 自定义 Function Calling 分析 DOM 元素地图、选择动作并录制结构化步骤。
- Steps 模式确定性回放 7 类 JSON 步骤；Manual 模式支持坐标点击、输入、按键和滚动。
- 回放失败时采集错误、失败步骤、页面截图与页面摘要，并可调用 LLM 辅助诊断。
- 通过 WebSocket 实时同步状态、当前动作和最多 200 条执行时间线。
- 使用独立 Electron 透明窗口绘制 Container Cursor Overlay，不修改目标网页 DOM。
- 每次鼠标操作按
moveSequence → renderer arrived ACK → Playwright 输入执行，避免真实点击 抢在光标动画前发生。
截图只用于失败证据与诊断；目标应用始终运行在真实浏览器窗口中。
旧版方案通过 addInitScript 把光标节点注入目标页面。当前版本已改为容器外覆盖层：
BrowserController
├─ 读取浏览器窗口与 viewport 坐标
├─ IPC 发送 viewport + moveSequence
▼
Electron 透明、置顶、点击穿透窗口
├─ requestAnimationFrame 绘制贝塞尔轨迹
└─ 到达目标点后返回 arrived(sequence)
▼
BrowserController 再调用 page.mouse.move/click
这与 Codex 内置浏览器的“宿主层绘制光标、到达后再派发输入”属于同一分层思路；本项目因为
Playwright 浏览器是独立桌面窗口，所以使用透明 Electron 窗口对齐页面 viewport，而不是
Codex 内部的 WebView sibling overlay。详细设计见
docs/container-cursor-overlay.md。
- Node.js 22+
- pnpm
- Windows 10/11（Container Overlay 默认只在 Windows 开启）
- Microsoft Edge、Google Chrome，或已安装的 Playwright Chromium
pnpm install
pnpm start打开 http://localhost:4317，点击“启动 Chromium”。
首次安装 Electron 时会下载对应平台二进制，耗时取决于网络。
开发模式可使用 pnpm dev；修改 TypeScript 服务端文件后会自动重启。
复制 .env.example 为 .env：
PORT=4317
START_URL=https://example.com
BROWSER_CHANNEL=msedge
CURSOR_OVERLAY_MODE=container
OPENAI_API_KEY=
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_MODEL=qwen-plus
MAX_AGENT_STEPS=30仓库中的 .env.example 使用百炼 OpenAI-compatible 接口作为示例；也可以把
OPENAI_BASE_URL 和 OPENAI_MODEL 改为其他兼容服务。未配置 API Key 时，Manual 和
Steps 模式仍可使用，Agent 执行与 AI 回放诊断不可用。.env 可能包含密钥且已被
.gitignore 排除，不要提交或粘贴到日志中。
常用浏览器 Channel：
msedge：本机 Microsoft Edge，Windows 默认值。chrome：本机 Google Chrome。- 留空：Playwright Chromium；先执行
pnpm install:browser。
CURSOR_OVERLAY_MODE：
container：启用独立 Electron Container Overlay。off：关闭光标可视化；真实 Playwright 输入仍正常执行。
Overlay 启动或通信失败时，控制器会记录时间线并降级继续执行输入，不会让可视化层阻断测试。
[
{
"action": "goto",
"url": "https://example.com"
},
{
"action": "expectText",
"text": "Example Domain"
},
{
"action": "click",
"selector": "a"
},
{
"action": "wait",
"ms": 1000
}
]支持 goto、click、fill、press、scroll、wait、expectText。
pnpm check
pnpm test
pnpm test:overlay
pnpm verify:overlaypnpm check：TypeScript 严格类型检查。pnpm test：不启动桌面窗口的单元测试。pnpm test:overlay：真实启动 Electron，验证渲染进程 ACK 协议。pnpm verify:overlay：启动本地页面、真实 Edge 与 Overlay，验证 ACK 后点击到达， 并断言目标 DOM 中不存在旧版注入式光标。
2026-07-27 的本机验证结果：类型检查通过；6 个单元测试通过；1 个 Electron 进程集成测试 通过；完整 Overlay E2E 验证通过。
运行时浏览器 Profile 与日志保存在 .runtime/，不进入版本控制。
项目结构与运行逻辑分析-简历产出.md：逐模块架构、 三条执行链路、状态模型、设计取舍、风险审计与简历/面试表述。docs/API与协议参考.md：13 个 HTTP API、8 类 WebSocket 事件、 9 类底层动作与 7 类结构化步骤。docs/开发测试与排障.md：环境、启动、验证矩阵、常见故障与安全注意事项。docs/container-cursor-overlay.md：透明 Electron Overlay、坐标换算、ACK 门控和降级策略。完善计划.md：按风险和收益排序的工程化路线图及验收标准。
Dashboard
│ HTTP + WebSocket
▼
Express + BrowserController
├─ Structured Step Runner
├─ LLM Function Calling Agent
├─ Timeline / Failure Evidence
└─ Cursor ACK Gate
│ IPC
▼
Electron Container Overlay
│ arrived(sequence)
▼
Playwright ──► Visible Edge / Chrome / Chromium
当前服务没有鉴权、租户隔离或高风险动作审批，只适合受控的本地测试环境。Agent 模式不要直接 操作生产账号、支付、删除或其他不可逆流程。
服务当前调用 app.listen(port)，没有显式绑定 127.0.0.1；具体可访问范围受 Node、系统网络栈
和防火墙影响。不要把端口暴露到不可信网络。持久化 Profile 可能包含 Cookie、Local Storage 和
登录态，.runtime/ 应按敏感数据目录处理。
- Agent 只读取 DOM 元素地图，不使用页面截图做视觉理解。
- 定位器会优先选择唯一候选，但在没有唯一候选时可能回退到多匹配候选并取第一个，不是强唯一保证。
- Agent 工具执行失败会作为结果返回给模型；当前不会强制阻止模型随后调用
done。 expectText是唯一断言类型；SPA 等待、iframe、Shadow DOM、文件上传下载和复杂拖拽支持有限。- 停止为动作/轮次边界上的协作式停止，不能立即取消正在进行的模型请求或 Playwright 动作。
- 回放失败上下文会通过 WebSocket 发出，但当前控制台没有展示失败截图和页面摘要。
- 单 Controller 没有任务互斥；请勿并发调用 Agent、Steps 和 Manual 执行接口。