ai-browser-tester AGENTS.md

AGENTS.md

本文件为后续 Codex / AI agent 在本项目中工作的项目级说明。

项目概述

本项目目标是构建一个 MCP-first 浏览器控制工具，供 Codex、Claude Code 或任何兼容 MCP client 执行自动化测试：

• 浏览器侧通过 Chrome/Edge 扩展或早期油猴脚本注入页面。
• 页面侧把 DOM、可访问性信息、可交互元素和页面事件转换成 LLM 可消费的结构化快照。
• MCP client 负责规划；本项目通过 MCP 暴露受控、可审计、ref-only 的浏览器能力。
• 控制方式优先采用 snapshot -> ref -> action -> result -> snapshot -> assertion 的闭环。

主要计划文档在：

• docs/ai-browser-tester-plan.md

当前项目状态

第一轮闭环（implementation-order Phase 1–7）已落地：

• 已初始化 pnpm TypeScript monorepo。
• packages/protocol：Zod 协议 schemas + 单元测试（JSON-RPC、握手、tab、snapshot、action、result、event、error、redaction、safety）。
• packages/page-controller：与浏览器无关的 PageController（snapshot/act/getEvents、ref registry、action executor、event collector、snapshot redaction）。
• apps/bridge：WebSocket handshake、pairing token 校验、协议版本协商、session manager、extension router、policy 层、audit log（JSONL + fill 值遮蔽）、严格 BrowserTools、以及与传输解耦的 MCP tool adapter（createMcpToolServer）。
• apps/extension：MV3 manifest（host 权限仅 localhost/127.0.0.1，无 <all_urls>）、background service worker、pairing token WebSocket client、tab registry、page 请求路由、content script + PageController。dev-only automation hook 仅在 AI_BROWSER_TESTER_DEV=1 编译。
• tests/：共享 e2e/harness.ts + 8 个 E2E 规格（login、form、todo/modal、open shadow DOM + same-origin iframe、SPA route change、blocked/stale-tab URL、high-risk 确认、内部滚动容器），真实加载 unpacked MV3 扩展跑通 snapshot -> ref -> action -> assert -> events，并校验 audit、密码遮蔽、无 evaluate、无 <all_urls>、policy fail-closed。
• docs/：protocol.md、security.md、architecture.md、testing.md 已同步到实现现状。

当前优先项：

• 2026-07-10 已完成 production unpacked Chrome + Codex stdio MCP 真实浏览器测试及阻断问题复测，证据见 docs/mcp-live-test-report-2026-07-10.md；用户随后已授权发布 @ryn-mic/ai-browser-tester npm MCP 以及包含独立 extension ZIP/SHA assets 的 GitHub Release，扩展签名和商店上架仍搁置。
• Phase 12 snapshot quality/scale controls 已落地：可配置文本/元素上限、landmark 提取、ARIA widget 状态（checked/expanded/selected）、精确重复文本去重、列表/表格/dialog/内部滚动容器语义摘要、显式 truncation/去重元数据（page.truncated）、遮蔽先于输出/去重/裁剪，以及大页面/密钥密集回归测试。稳定 ref、事件/错误聚合摘要为有意后延项。
• Phase 13 extension installation/permissions model 已落地：unpacked extension 构建包含 options page，README 提供 Chrome/Edge 安装与 pairing token/bridge URL 配置说明；manifest 永久 host permissions 仍仅 localhost/127.0.0.1，无 <all_urls>；非本地站点通过 options page 逐 origin 请求 optional host permission，并用动态 content script registration 注入 page agent。
• Phase 14 observability/diagnostics 已落地：browser_diagnostics 只读工具、SessionManager.diagnostics() 会话/标签/策略健康摘要、BRIDGE_ERROR_CATALOG 全错误码目录、诊断 URL 遮蔽与 troubleshooting 文档。
• Phase 15 agent regression/release readiness 已落地：pnpm test:agent scripted agent 回归、AgentScenarioRecorder 指标 JSON（成功率/工具调用数/耗时/snapshot 大小/错误分布）、pnpm release:gate 发布门禁、兼容矩阵与 release checklist。
• CI（.github/workflows/release-gate.yml）在 PR 和 push 上运行 pnpm release:gate；pnpm smoke:mcp（scripts/Codex-mcp-smoke.mjs）对真实 stdio MCP CLI 做 transport smoke（initialize/tools.list/tools.call diagnostics），见 docs/Codex-mcp-smoke.md。
• docs/next-phase-plan.md 中的 MCP readiness、手动扩展安装、Codex MCP 注册和真实浏览器测试已经完成；CI 打包已落地，HTTP、内置 real-model regression、扩展签名/商店发布仍后置。