企业官网建设流程全解析

LobeHub「Web Surface」使用指南：用 agent-browser 为前端与全栈改动产出端到端验收证据

【免费下载链接】lobehub🤯 LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub

本文讲解 LobeHub 内置 acceptance 技能中 Web surface 的完整用法：浏览器是"网络请求与渲染 UI 可同时被观察"的唯一位置，因此它是前端改动与全栈改动的默认证明面。读完你会掌握如何启动被测应用、用命名会话完成登录态注入、驱动页面交互、截取 UI 与抓取 HAR 网络证据，并遵守关于"证据来源""时间型行为""OS 级步骤"的边界约束，最终把证据上传到 acceptance round。

一、这是什么：acceptance 技能下的"证明面"体系

在 LobeHub 仓库中，packages/builtin-skills/src/acceptance 目录承载了名为acceptance（v0.3.0）的内置技能——它用于任何交付物的端到端验证与"自我取证"（builder self-evidence）。技能入口 SKILL.md 声明其运行路径：

author (or discover) the plan → pick the surface → capture evidence → publish the round → self-check coverage

其中"pick the surface"这一步是判断工作量的关键：不同性质的改动应选择最便宜、最能证明问题的证明面，而不是一律打开浏览器。SKILL.md 中的对应选择表给出映射：

这些 surface 指南连同其参考资料，被统一注册进 acceptance/index.ts 的AcceptanceSkill.resources（第 4–22 行逐一 import 各 markdown，第 63–82 行以references/*.md、surfaces/*.md为 key 挂载），资源 key 保留.md扩展名，使得磁盘拉取后与真实文件一一对应、技能内的相对链接可解析。

本文档即该体系中的 surfaces/web.md，它回答"当前改动属于前端或全栈时，如何驱动真实浏览器、捕获可视证据"。

二、何时选用 Web 面：默认面及其判断准则

Web 面是前端改动与全栈改动的默认证明面。其底层理由是：浏览器是"网络请求与渲染 UI 能被放在一起观察"的唯一场所——在普通浏览器、应用 dev server 或已部署 URL 上，一次运行可以同时断言一条契约的两侧（发出的请求与渲染出的界面）。驱动它的引擎是agent-browser，一套通过 Chrome DevTools Protocol 自动化 Chromium 系应用（Electron、Chrome、Web）的 CLI，其完整命令手册见 references/agent-browser.md。

判断准则：

• 当行为在"普通浏览器 + 应用的 dev server 或部署 URL"上表现一致时，选择 Web；
• 若判定条件依赖桌面外壳（Electron 壳、IPC、原生窗口），或可完全由后端/CLI 输出证明，则应返回 surface 选择路由，改用 surfaces/electron.md 或 surfaces/cli.md；
• 一句话原则：不要为后端改动打开浏览器——命令输出作为text证据是最强、最便宜的证明。

三、Setup：让应用可达、让会话通过登录

Web 面的前置条件有两条（原文 Setup 部分）：

1. 让被测应用在一个 URL 上可达：可以是本地启动的 dev server（例如http://localhost:<port>），也可以是任务指向的部署/预览 URL。注意项目级约定——该仓库自身的启动命令、端口、服务与 auth 流程记录在项目层.agents/acceptance/PROJECT.md，不要凭空发明（见 SKILL.md）。
2. 若被测状态在登录墙之后，先让 agent-browser 会话完成认证，详见 references/auth-web.md。务必使用具名的--session，使 cookies 跨命令持久化。

一个典型的起步会话（web.md 原文示例）：

SESSION=app agent-browser --session $SESSION open "http://localhost:3000/" agent-browser --session $SESSION snapshot -i # interact via refs, then capture agent-browser --session $SESSION screenshot ./proof/state.png

--session命名会话会自动保存并恢复 cookies 与 localStorage（agent-browser.md 的 Parallel sessions 一节）。认证手段包括：

• 具名会话内先完成一次真实登录、之后复用同一会话；
• state save/load（Playwright 风格存储态）；
• auth save/login（加密凭据库 + 表单重放）；
• --profile专用持久化浏览器 profile。

对本地开发，还存在"从已登录浏览器 DevTools Network 复制 Cookie 头 → 构建 state 文件并 load 进命名会话"的兜底方案。它的三个硬性细节：必须复制 Network 请求的完整Cookie:头而不是document.cookie（HttpOnly 会话 cookie 在后者中不可见）；cookie domain 必须与目标主机完全一致（localhost≠127.0.0.1，本地域无前导点）；注入后要重开受保护 URL 验证未被重定向回登录页。

四、证据来源的铁律：只有自动化会话本身能作证

web.md 在 Setup 之后给出第一条边界规则，其措辞非常硬：

Use the authenticated session as the evidence source. Donotuse a separate ordinary-Chrome screenshot as proof — it doesn't prove the automated session reached the state. Ordinary Chrome is only a cookie source for auth fallback.

翻译过来即：认证后的 agent-browser 会话必须同时是证据来源。一张来自"另一个普通 Chrome"的截图不能作为证明——它无法证明自动化会话本身到达了该状态；普通 Chrome 仅仅被允许作为认证兜底时的 cookie 提供者。这一点与 references/auth-web.md 的决策流相互呼应：认证要加在"将采集证据的那个命名会话"上，且重开受保护 URL 后应先用agent-browser get url确认没有落在 sign-in 路由上，再开始捕获。

从技能整体看，这属于跨面证据契约的一部分——references/evidence.md 将证据类型约束为text/markdown/dom_snapshot/screenshot/gif/video/audio/transcript，声明的requiredEvidence类型具有约束力，截图不能替代要求 video 的检查，DOM 快照也不能用散文替代。

五、全栈场景：网络层与渲染层双重断言

当判定条件跨越"新增/变更的 API"和"消费该 API 的 UI"时，需要同时捕获网络交换与渲染结果——只断言其中一层，契约只算"证明了一半"。这正是 SKILL.md 选择表中"New/changed APIplusthe UI consuming it → Web, full-stack"那一行的具体操作（web.md#web-full-stack一节）：

SESSION=app agent-browser --session $SESSION network har start # ... drive the scenario that triggers the API ... agent-browser --session $SESSION network requests --type xhr,fetch # inspect calls agent-browser --session $SESSION network har stop ./proof/capture.har agent-browser --session $SESSION screenshot ./proof/result.png

流程解读：

1. network har start开启 HAR 录制；
2. 驱动触发该 API 的场景（交互步骤用前文的 refs）；
3. network requests --type xhr,fetch检查调用（也可用--method POST按 HTTP 方法过滤，见 agent-browser.md）；
4. network har stop ./proof/capture.har停止并落盘；
5. 最后对渲染结果截图。

上传动作（web.md 原文）：截图按--type screenshot上传；网络证据按两种粒度之一上传——完整 HAR 用--type text --file ./proof/capture.har，聚焦的 request/response 用--type text --content …内联提交。这与 evidence.md 的提交契约一致（--file用于二进制与较大文本，--content用于短文本断言，二者只传其一），实际提交命令形如：

lh acceptance run result submit --operation "$OPERATION_ID" --item "$CHECK_ITEM_ID" \ --type "$EVIDENCE_TYPE" --file "$ARTIFACT_PATH" --by "$PROVENANCE" --desc "…"

需要说明：在网络工具层面，agent-browser.md 还提供agent-browser network requests（无过滤时列出全部被追踪请求）以及针对 alert/confirm/prompt 等对话框的dialog accept/dismiss/status系列命令，可用于排除"对话框阻塞一切命令"的卡死场景。

六、本地前端 + 远程后端：能证明什么、不能证明什么

web.md 专门用一节提醒一种容易被高估的拓扑：

If you can only run the frontend locally but the backend is remote, drive the frontend URL the same way — just remember the backend is not your branch, so it proves frontend behavior, not backend changes.

即：当只能本地跑前端、后端在远端时，驱动方式不变，但后端并非你当前分支的代码，因此这种运行能证明前端行为，却不能证明后端的改动。把这一判定落到 evidence 语义上，就是要避免把"连上了远端后端"误当成"后端分支改动已被验证"——后者仍需要后端侧自己的证明路径。

七、时间型行为与 OS 级步骤：两种逃生通道

7.1 行为随时间变化 → 录制 CDP 帧，而不是截图

流式输出、loading→loaded 过渡、计时器、动画、多步流程这类"随时间表现"的判定，静态截图无法证明，需要片段而非图片。Web/Electron 面统一走 references/recording-cdp.md：通过 CDP 从渲染器抓帧，绝不录制宿主机屏幕。其典型做法是：

FRAME_DIR=$(mktemp -d) capture_frame() { agent-browser --session app screenshot "$1"; } # Web 面 i=0 while [ "$i" -lt 40 ]; do # 约 20 秒（每帧 0.5s） printf -v frame_number "%06d" "$i" capture_frame "$FRAME_DIR/frame_$frame_number.png" i=$((i + 1)); sleep 0.5 done

随后用ffmpeg以-framerate 2合成 MP4（libx264 -crf 23 -pix_fmt yuv420p），或走 palette 两步法生成 GIF，最后用ffprobe校验时长/分辨率/帧率，并在引用前人工检查首帧、动作帧、瞬时态与稳定帧。证据归属遵循 evidence.md：CDP 帧标--by agent-browser，合成的媒体成品标--by program。类型层面，短片约 10 秒内可选gif，更长的动画/手势/多步流程应选video。

7.2 页面无法脚本化的原生步骤 → 临时切到 Computer Use

文件选择器、OS 权限弹窗、Save 对话框这类"页面脚本无法覆盖的原生步骤"，应针对该步骤下沉到 macOS Computer Use（osascript/screencapture），完成后再返回 agent-browser 会话继续，见 references/computer-use.md。该手册强调其适用面：它只能驱动 agent-browser 够不到的东西（非 Chromium 原生应用、OS 级 chrome、无 CDP 目标时的读屏），是macOS-only、不可云端移植的，CDP 可达时应优先 CDP。

八、三条边界纪律

web.md 在 Boundaries 一节给出三条必须遵守的边界：

1. Provenance（来源标注）：由agent-browser捕获的工件统一标注--by agent-browser；只有"直接由 CDP 客户端捕获"才用--by cdp。与之配套，evidence.md 要求：未被修改的直接捕获源用它真实的来源，确定性测试/脚本/媒体变换标--by program，且不要从文件扩展名推断 provenance。
2. Headless / Cloud（无头与云端）：Web 面天生云原生——无头 Chromium 与 CDP 截图不需要显示器即可工作，因此应优先用 CDP 捕获而非 OS 级截屏（后者依赖真实 macOS 会话与显示，见 computer-use.md 的不可移植性说明）。
3. HMR 会打失效 refs：开发期热更新后，旧 refs 一律失效，先重新snapshot再交互。agent-browser.md 的 Ref lifecycle 补充了更一般规则：点击导航链接/按钮、表单提交、动态内容加载导致的页面变化都会使 refs 失效，交互前必须 re-snapshot。

九、由本指南延伸的阅读路径

围绕 Web surface，可在当前仓库按需取用以下材料（均已转换为仓库根目录相对路径）：

十、小结

把 web.md 的要点收拢成一条可执行的心智模型：选面（前端/全栈默认 Web，Electron/CLI 能力边界之外才换面）→就位（URL 可达 + 具名会话过登录）→驱动（open → snapshot -i → 用 refs 交互，HMR 后必须 re-snapshot）→双证（全栈场景同时交 HAR 网络证据与渲染截图）→守界（只用自动化会话作证据、--by agent-browser标注来源、时间型行为录帧而非截图、OS 步骤临时下沉 Computer Use）。浏览器是唯一能同屏观察"请求与渲染"两个层面的位置，而正确的证据纪律保证了这些观察真的来自被验证的那次自动化运行。

【免费下载链接】lobehub🤯 LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub