企业官网建设流程全解析

在 eve 中挂载 @agent-browser/eve：让 Agent 一次性获得完整的浏览器自动化工具集

【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/GitHub_Trending/agen/agent-browser

@agent-browser/eve是 agent-browser 官方提供的 eve 扩展包：挂载一次，Agent 即可获得约 20 个命名空间的浏览器工具——导航、带稳定元素引用的无障碍快照、点击、表单填写、语义化元素查找、等待、截图、JavaScript 求值、标签页管理、网络与控制台检查等，无需手写任何工具。本文将基于该包在仓库中的 README 与源码实现，完整讲解安装、挂载、配置、工具清单、覆写机制与底层工作原理，帮助你把它真正跑起来并理解其内部机制。

安装：一个包 + 一个 peer 依赖

在安装 eve 应用的依赖时，直接安装本包即可：

npm install @agent-browser/eve

需要注意两点：

• eve是 peer dependency（在 package.json 中声明为"eve": ">=0.39.1"），扩展运行在你应用里已安装的 eve 上，因此 eve 需由你的应用自行安装，版本不低于 0.39.1；
• 包体本身要求 Node.js>=24.0.0，与 eve 生态的运行时要求保持一致。

从包的exports映射可以看出它对外暴露三个入口：

• @agent-browser/eve：扩展主体（./dist/index.mjs）；
• @agent-browser/eve/tools：各个独立工具的定义（./dist/tools/index.mjs），用于覆写场景；
• @agent-browser/eve/sandbox：沙箱侧安装与命令构造工具（./dist/sandbox/sandbox.js）。

包只依赖@agent-browser/sandbox（工作区内构建）与zod，自身不带任何浏览器二进制，浏览器由沙箱安装流程负责。

挂载：一个文件即可拥有全部工具

在 eve 应用中，在agent/extensions/下创建挂载文件，文件名即成为工具命名空间：

// agent/extensions/browser.ts import browser from "@agent-browser/eve"; export default browser({});

挂载完成后，Agent 立即拥有browser__navigate、browser__snapshot、browser__click等全部工具，同时获得一段 instructions 片段（见 extension/instructions.md），向模型讲授 snapshot-refs 工作流：先navigate再snapshot，快照中的[ref=e12]可在其他工具中作为@e12选择器使用等。

首次使用自动安装，生产环境预热模板

在全新的沙箱中首次使用工具时，扩展会自动安装 agent-browser（以及 Chromium 及其系统库）。但从源码看，自动安装仅发生在工具真正被调用时：runBrowser会先ensureInstalled，用command -v <binary>探测二进制是否存在，缺失时才触发安装（见 extension/lib/browser.ts）。这一探测结果会按沙箱 id 缓存，安装失败会自动清除缓存以便下次重试。

对于生产环境，官方建议在沙箱 bootstrap 中预装，让会话从“预热模板”启动：

// agent/sandbox.ts import { agentBrowserRevalidationKey, installAgentBrowser } from "@agent-browser/eve/sandbox"; import { defineSandbox } from "eve/sandbox"; import { vercel } from "eve/sandbox/vercel"; export default defineSandbox({ backend: vercel({ resources: { vcpus: 2 } }), revalidationKey: () => agentBrowserRevalidationKey(), async bootstrap({ use }) { const sandbox = await use(); await installAgentBrowser(sandbox); }, });

这里的关键设计是agentBrowserRevalidationKey()（实现在 extension/lib/sandbox.ts）：它把agent-browser、bootstrap 修订号4、安装 spec、是否含浏览器、是否含系统依赖拼成一个模板校验键，当这些输入发生变化时，沙箱模板会自动失效并重建，从而保证预热模板始终与当前包版本一致，而不是长期缓存一个过期环境。

从手写工具调用 agent-browser

@agent-browser/eve/sandbox还导出了runAgentBrowser，供你在手写的 eve 工具里直接调用 agent-browser。它从 eve 沙箱 id 推导出一个短且稳定的会话名；当多个相互独立的浏览器会话需要共享同一个沙箱时，传入session指定固定的会话名即可。

配置：全部可选，一行一个开关

扩展的全部配置字段均为可选，完整示例：

export default browser({ // Safety allowedDomains: ["example.com", "*.example.com"], // restrict navigation and sub-resources caCert: "/etc/ssl/certs/proxy-ca.pem", clearCaCert: false, contentBoundaries: true, // wrap page output in markers the model can recognize maxOutputChars: 50_000, // truncate page output // Output inlineScreenshots: true, // embed screenshots in tool output as data URLs for channels/UIs // (hidden from the model via toModelOutput; capped at 4 MB per image) // Install behavior autoInstall: true, // install agent-browser on first use when missing installSpec: "agent-browser@0.31.2", // defaults to the version matching this package installBrowser: true, // download Chromium during auto-install installSystemDependencies: true, // apt/dnf Chromium libraries during auto-install // Session & runtime session: undefined, // fixed session name; defaults to one derived from the sandbox id sessionPrefix: "eve", // prefix for the derived session name binary: "agent-browser", // binary name or path inside the sandbox proxy: undefined, // proxy server URL });

对照 extension/extension.ts 中 zod 模式的默认值与 extension/lib/browser.ts 中configArgs()的转换逻辑，可以精确理解每个字段的底层行为：

值得强调的细节：

• 会话名推导：defaultSessionName(config.sessionPrefix, sandbox.id)将前缀与沙箱 id 组合为稳定会话名，因此同一沙箱内的多次工具调用共享同一个浏览器会话与页面状态；
• 系统依赖安装脚本：buildLinuxSystemDependenciesCommand()（见 extension/lib/sandbox.ts）检测apt-get或dnf，分别安装约 40 个 Chromium 运行库（含fonts-noto-color-emoji、fonts-noto-cjk等字体包），且对libgtk-3-0t64、libasound2t64等 t64 变体做了apt-cache show探测回退，兼容新版 Debian/Ubuntu 的 64 位时间戳重命名；
• 安装链路：installAgentBrowser依次执行“装系统依赖 →npm install -g <spec>→agent-browser install（下载 Chromium）”，每一步失败都会立即抛出，不会静默继续。

工具清单：约 20 个命名空间工具

挂载后 Agent 获得以下工具（定义于 extension/tools/ 下，每个工具一个文件）：

几个值得展开的细节（源自各工具源码）：

• navigate（navigate.ts）：action支持goto/back/forward/reload，其中goto必须带url，底层调用 CLI 的open命令；导航本身已等待页面加载完成，因此之后可以直接snapshot或read；
• snapshot（snapshot.ts）：支持compact（默认开，去掉空结构元素）、depth、includeUrls、interactiveOnly与selector作用域；对“导航中途快照”可能触发的瞬时 CDP 竞态，会延迟 500ms 重试一次；作用域选择器无效时会回退为整页快照，因为整页必然覆盖目标元素；
• read（read.ts）：带 URL 时走无浏览器抓取，不带时读取当前已渲染的活动标签页（包含登录态），适合阅读文章与文档；llms支持index/full以读取站点llms.txt索引或llms-full.txt；
• wait_for（wait_for.ts）：可同时给多种条件，按“加载状态优先、固定延时最后”的顺序依次等待；单个条件默认超时 10s（上限 30s）；超时不是报错——返回satisfied: false，避免模型陷入重试循环；空字符串条件会被当作未提供，防止模型填""后空耗超时；
• screenshot（screenshot.ts）：支持annotate（在交互元素上叠加与快照 ref 对应的编号标签）与fullPage；inlineScreenshots开启时会通过沙箱的readBinaryFile读出图片（单张 >4MB 则放弃内联），转成 data URL 放进工具输出供 UI 渲染，但通过toModelOutput对模型隐藏 base64 与沙箱路径——模型只会被告知“截图已捕获并展示给用户”，避免它回复“已保存到 /workspace/… 之类”的内部细节；
• find（find.ts）：按role/text/label/placeholder/alt/title/testid/first/last匹配，配合click/fill/check/hover/text动作一步完成，适合“知道元素是什么但不想先快照”的场景；--name用于限定 role 的 accessible name，--exact切换精确匹配；
• evaluate（evaluate.ts）：运行任意 JS 表达式并返回 JSON 可序列化结果，是扩展能力的“逃生舱”。

有意不暴露的命令

Cookie、storage 与已保存认证状态相关命令有意不作为工具暴露——它们会让凭据材料直接出现在模型的视野中。如果确实需要，官方建议在你的 agent 中自行添加带守卫的 scoped 工具（或通过下面的 override 机制），并按你的应用要求设置护栏。

覆写：按目录挂载，逐工具加闸门

eve 标准的扩展覆写机制在此同样适用。把扩展挂载为目录，即可替换或剔除单个工具：

// agent/extensions/browser/extension.ts import browser from "@agent-browser/eve"; export default browser({});

// agent/extensions/browser/tools/evaluate.ts — require approval for raw JS import { evaluate } from "@agent-browser/eve/tools"; import { defineTool } from "eve/tools"; import { always } from "eve/tools/approval"; export default defineTool({ ...evaluate, approval: always() });

// agent/extensions/browser/tools/upload.ts — or drop a tool entirely import { disableTool } from "eve/tools"; export default disableTool();

三个典型用法：

1. 给高风险工具加审批：对evaluate（任意 JS 执行）套上approval: always()，每次调用都需用户确认；
2. 整体禁用某工具：用disableTool()直接让upload等工具不存在于 Agent 的工具列表中；
3. 替换实现：defineTool({ ...原工具, ...你的覆写 })可同时保留原输入 schema、替换执行逻辑或描述。

注意工具目录结构必须与源码的 extension/tools/ 一一对应：目录名是工具名，extension.ts是扩展主体。

工作原理：沙箱内 CLI 驱动，应用运行时只做转发

理解整个体系的关键在于“边界划分”：

每个工具在ctx.getSandbox()拿到的沙箱内，以子进程方式调用agent-browserCLI，使用以沙箱 id 命名的隔离浏览器会话，并解析其--json载荷返回。浏览器及其全部状态完全活在沙箱里；应用运行时只负责中转命令。

这条设计带来三个直接推论：

• 安全隔离：浏览器进程、下载的 Chromium、页面状态都不进入应用运行时，agent 主进程无浏览器依赖；
• 会话连续性：defaultSessionName("eve", sandbox.id)让同一沙箱内的工具调用共享同一会话，跨工具保持登录态与页面状态；多个独立会话需要共享沙箱时用session固定名字即可；
• 健壮性：runBrowser（extension/lib/browser.ts）对“获取沙箱会话”和“单条命令运行”都套了 180 秒的withDeadline兜底（防止沙箱在（重）开会话时卡死导致整轮 stuck），命令非零退出或--json信封报告失败都会转为清晰的错误信息。

包在 extension/test/ 下配有extension.test.mjs与sandbox.test.mjs测试（运行pnpm -C packages/@agent-browser/eve test可验证），从测试侧覆盖了扩展挂载与沙箱安装/命令构造的核心行为。

完整示例

仓库中的 examples/eve/ 是一个完整的 Next.js eve 应用示例，挂载了本扩展，包含agent/extensions/browser.ts、agent/sandbox.ts、agent/tools/等完整目录结构，可以直接作为新项目脚手架参考。示例应用的agent/extensions/与agent/sandbox.ts目录结构与上文两段挂载代码一一对应。

许可

@agent-browser/eve以 Apache-2.0 协议开源（见 LICENSE），可自由集成到你的 eve 应用与 Agent 产品中。

【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/GitHub_Trending/agen/agent-browser