企业官网建设流程全解析

Expect架构全景图：Supervisor、Agent、Browser、Cookies五大核心包如何协作

【免费下载链接】expectExpect tests your agent's code in a real browser项目地址: https://gitcode.com/gh_mirrors/expect6/expect

Expect 是一款让 AI 编程代理在真实浏览器里测试自己代码的开源工具：它读取你的 Git 变更、自动生成测试计划，并用 Playwright 在真实浏览器中执行，检查性能、安全、设计与完整性问题，再报告给代理去修复。下面从架构视角拆解 Expect 的五大核心包——supervisor、agent、browser、cookies、shared 各自负责什么，以及它们如何协作完成一次完整的测试。

一、Expect 是什么：一条命令的浏览器测试

和 Puppeteer、Cypress 等工具需要你手写脚本、维护选择器不同，Expect 的定位是"给代理装上 QA 超能力"：

• 读取代码变更：自动分析 unstaged、分支 diff 或指定 commit
• 生成测试计划：把变更转成可执行的测试步骤
• 真实浏览器执行：用 Playwright + CDP 驱动真实 Chrome，还能注入你系统浏览器的 Cookie，模拟"已登录的真实用户"
• 报告驱动修复：把发现的问题交还代理，修复后重跑验证

二、整体架构：一个仓库，分工明确

Expect 是一个 pnpm monorepo（配合 turbo 做构建编排），通过 pnpm-workspace.yaml 定义了packages/*与apps/*两组工作区：

依赖关系呈现出清晰的分层结构：supervisor 依赖 agent 与 browser；agent 依赖 browser；browser 依赖 cookies；而 shared 不依赖任何业务包，是所有包的公共底座。

三、supervisor：编排全流程的"总指挥"

supervisor 包（packages/supervisor/package.json）是整个系统的调度中心，核心组件包括：

• Executor（executor.ts）：执行引擎。先通过 Git 服务收集当前分支、变更文件、diff 预览与近期提交，再构造执行上下文，驱动代理按计划逐条执行测试步骤
• Planner（planner.ts）：把代码变更翻译成结构化测试计划（TestPlan）
• Reporter（reporter.ts）：汇总每步结果，输出最终测试报告
• Git / Github（git/git.ts）：分支、diff、提交等 Git 操作封装
• Watch（watch.ts）：持续监听模式，代码变更时自动评估并触发测试
• FlowStorage（flow-storage.ts）：保存与复用测试流程（flow），支持-f <slug>快速重跑

你可以把它理解为"项目经理"：自己不写测试，但知道每一步该让谁做什么。

四、agent：打通各家编码代理的统一桥

Expect 支持 Claude Code、Codex、GitHub Copilot、Gemini CLI、Cursor、OpenCode、Factory Droid 等多家代理。agent 包（packages/agent/package.json）通过ACP（Agent Client Protocol）实现了统一抽象：

• detect-agents.ts：扫描PATH自动检测本机安装了哪些代理，支持-a <provider>手动指定
• acp-client.ts：与代理建立 ACP 会话，流式接收执行事件与用量信息
• agent.ts：Agent服务的核心实现，向上暴露统一的流式接口

这样 supervisor 无需关心"背后到底是哪个代理"，换一家代理只需换一个后端实现，架构上的"可插拔性"就来自这里。

五、browser：真实浏览器自动化的核心

browser 包是 Expect 的"手脚"，基于 Playwright 提供真实 DOM 级自动化（而非截图+坐标的"计算机使用"路线）：

• Browser 服务（browser.ts）：启动/连接 Chrome（headed 或 headless），创建页面并执行点击、输入等动作
• CDP 自动发现（cdp-discovery.ts）：可接管一个已打开的 Chrome 实例（--cdp或--profile复用现有配置文件）
• 快照与 Diff（diff.ts）：把页面压缩成带引用编号的可读树状快照，并对比两次快照找出变化，让代理能"看懂"页面
• MCP 服务（mcp/server.ts、mcp/start-http.ts）：把浏览器能力封装成 MCP 工具，供各类代理按需调用，文档见 docs/mcp.md
• 可视化 Overlay（runtime/overlay/）：用 React 在页面上渲染光标、操作标记与进度，让测试过程"看得见"

六、cookies：让测试用户变成"真实用户"

很多 Bug 只在登录态下出现。cookies 包（packages/cookies/）负责从你的系统浏览器中提取真实 Cookie 并注入到测试浏览器中：

• 浏览器检测（browser-detector.ts）：自动发现本机安装的 Chrome、Firefox、Safari 等及其配置
• Chromium 系读取（chromium.ts）：解析 SQLite Cookie 库并完成解密
• CDP 通道（cdp-client.ts）：通过 CDP 直接从运行中的浏览器拉取 Cookie
• 一键提取（cookies.ts）：统一入口，browser 包在执行前调用它完成身份注入

CI 场景下可用--no-cookies或--ci跳过该步骤，无头运行、自动确认计划。

七、shared：五大包脚下的公共底座

shared 包被其余所有业务包依赖，提供"约定"与通用能力：

• 模型定义（models.ts）：TestPlan、执行事件等跨包共享的数据结构
• 提示词工程（prompts.ts）：构造规划与执行阶段给代理的提示词
• 浏览器容量估算（estimate-browser-capacity.ts）：根据系统内存估算可安全开多少个浏览器实例
• 可观测性与分析（observability/、analytics/）：链路追踪与遥测

八、端到端协作：一次测试是怎么跑的

把五个包串起来，一次典型的/expect运行流程如下：

1. CLI 入口：apps/cli/ 的终端界面解析参数（变更范围、代理、目标 URL、浏览器模式）
2. 上下文收集：supervisor 的 Executor 调 Git 拿到分支、变更文件与 diff 预览
3. 规划：Planner 把变更翻译成测试计划，展示给用户确认（-y可跳过）
4. 执行：agent 包建立 ACP 会话，代理借助 browser 包的 MCP 工具逐步操作真实页面；如需登录态，cookies 包已提前注入身份
5. 报告与修复：Reporter 汇总失败项，代理修复代码后自动重跑验证，直到通过

整个链路中，supervisor 出题、agent 做题、browser 动手、cookies 提供身份、shared 提供规则——职责边界干净，这也是它容易扩展新代理、新浏览器能力的根本原因。

九、上手指南：三步体验

🚀 如果你想在本地跑起来：

git clone https://gitcode.com/gh_mirrors/expect6/expect cd expect && pnpm install

1. 安装技能：按官方说明让代理拉取 Expect 页面并执行初始化脚本
2. 启动测试：在 Claude Code、Codex 等代理中输入/expect
3. 看它工作：代理生成计划 → 真实浏览器逐步执行 → 发现问题并自动修复重验

小结：Expect 的架构精髓在于分层清晰——supervisor 编排、agent 适配、browser 自动化、cookies 注入身份、shared 统一约定，五包各司其职又通过 Effect 依赖注入紧密协作，把"让 AI 代理在真实浏览器里验收自己的代码"变成了一条命令的事。

【免费下载链接】expectExpect tests your agent's code in a real browser项目地址: https://gitcode.com/gh_mirrors/expect6/expect