企业官网建设流程全解析

• 人工智能
• AI Agent
• 多智能体
• MCP 服务
• 工具调用
• 浏览器控制

导读

本指南面向在 hive（Multi-Agent Harness for Production AI）中使用浏览器自动化工具（browser_interact、browser_snapshot、browser_navigate等）的 Agent 开发者与调试者。当工具在 LinkedIn、Twitter/X、各类 SPA（React/Vue/Angular）以及含 Shadow DOM 的复杂网站上出现"滚动无效、点击无响应、输入丢失、快照卡死"等诡异故障时，本文提供一套可复现、可定位、可修复的标准作业流程（SOP），并附上 hive 仓库中BeelineBridge的源码级实现证据与 17 个已登记边缘案例，帮助你快速把"假成功"变成"真成功"。

何时启用本技能

浏览器工具在简单静态站点上通常工作正常，故障几乎总是出在复杂站点上。当出现以下任一症状时，应启动本调试流程：

这些症状的共同特征是：工具返回{ok: true}，但页面状态没有变化。真正的根因往往藏在嵌套滚动容器、透明遮罩层、React 合成事件、超大 DOM 或 Shadow DOM 之中。

四阶段调试 SOP

Phase 1：复现与隔离（Reproduce & Isolate）

调试的第一步不是猜原因，而是构造最小复现并确认问题边界：

1. 编写最小测试用例复现故障；
2. 在简单站点（如example.com）上验证工具本身可用——这是基线；
3. 在问题站点上再次执行，确认是站点特有（site-specific）的边缘场景。

快速隔离测试可以直接在 Agent 环境中执行：

# Test 1: 工具本身是否可用（简单站点） await browser_navigate(tab_id, "https://example.com") result = await browser_interact(action="scroll", tab_id=tab_id, scroll_direction="down", scroll_amount=100) # 简单站点上应该正常 # Test 2: 是否在问题站点失败 await browser_navigate(tab_id, "https://linkedin.com/feed") result = await browser_interact(action="scroll", tab_id=tab_id, scroll_direction="down", scroll_amount=100) # 若此失败而 example.com 正常 → 站点特有边缘场景

仓库中提供了标准测试模板 .claude/skills/browser-edge-cases/scripts/test_case.py，其TEST_CASE字典可配置site、simple_site、category（scroll/click/input/snapshot/navigation），并内置了基线测试与问题站点测试的对比逻辑。按模板复制为test_#[编号]_[站点].py后，通过uv run python test_#[number]_[site].py运行，例如uv run python test_01_linkedin_scroll.py。现有用例包括 test_02_twitter_scroll.py、test_03_modal_scroll.py、test_04_element_covered.py、test_06_shadow_dom.py、test_07_contenteditable.py、test_08_autocomplete.py、test_10_huge_dom.py、test_13_spa_navigation.py、test_15_screenshot.py 等。

Phase 2：根因分析（Analyze Root Cause）

Step 2a：检查控制台错误

console = await browser_console(tab_id) # 重点寻找：CSP 违规、React 渲染错误、JavaScript 异常

Step 2b：检查 DOM 结构

html = await browser_html(tab_id) snapshot = await browser_snapshot(tab_id) # 重点寻找： # - 嵌套滚动 div（overflow: scroll/auto） # - Shadow DOM 根节点 # - iframe # - 自定义组件

Step 2c：识别症状模式

Phase 3：多层修复实现（Implement Multi-Layer Fix）

模式：始终保留兜底方案（Fallbacks）

复杂站点上没有任何单一方法绝对可靠，修复必须分层递进：

async def robust_operation(tab_id): # 方法 1：首选方案 try: result = await primary_method(tab_id) if verify_success(result): return result except Exception: pass # 方法 2：CDP 兜底 try: result = await cdp_fallback(tab_id) if verify_success(result): return result except Exception: pass # 方法 3：JavaScript 兜底 return await javascript_fallback(tab_id)

这与 hive 仓库 tools/BROWSER_USE_PATTERNS.md 中记录的 browser-use 集成经验一脉相承：元素几何计算依次尝试DOM.getContentQuads→DOM.getBoxModel→ JSgetBoundingClientRect，最后以 JavaScriptthis.click()作为终极手段，每步都有超时保护。

模式：始终添加超时（Timeouts）

# 错误示范 —— 可能永久挂起 result = await browser_snapshot(tab_id) # 正确示范 —— 快速失败并给出有用错误 try: result = await browser_snapshot(tab_id, timeout_s=10.0) except asyncio.TimeoutError: # 优雅处理超时 result = await fallback_snapshot(tab_id)

在源码层面，BeelineBridge.snapshot()已内置timeout_s参数（见 tools/src/gcu/browser/bridge.py 中的async def snapshot(self, tab_id, timeout_s=30.0, mode="default")），测试模板的test_problematic_site也用asyncio.TimeoutError捕获快照超时并统计耗时，这正是 Phase 1 模板验证过的做法。

Phase 4：验证修复（Verify Fix）

1. 针对问题站点运行 → 应修复成功；
2. 针对简单站点运行 → 应仍然正常（回归检查）；
3. 将案例登记到 registry.md。

模式库（Pattern Library）

P1：嵌套可滚动容器（Nested Scrollable Containers）

• 典型站点：LinkedIn、Twitter/X、任何带可滚动信息流的 SPA。
• 检测方法：找出最大的可滚动容器——先收集所有overflow含scroll/auto且尺寸大于 100×100 的元素，再按面积排序取最大者：

const candidates = []; document.querySelectorAll('*').forEach(el => { const style = getComputedStyle(el); if (style.overflow.includes('scroll') || style.overflow.includes('auto')) { const rect = el.getBoundingClientRect(); if (rect.width > 100 && rect.height > 100) { candidates.push({el, area: rect.width * rect.height}); } } }); candidates.sort((a, b) => b.area - a.area); return candidates[0]?.el;

• 修复方式：把滚动事件派发到容器中心，而不是视口中心。

这一模式已落地到BeelineBridge.scroll()（tools/src/gcu/browser/bridge.py）。其实现采用方向感知启发式：优先选择视口中心处可滚动的祖先元素（"Agent 正在看什么"比"页面上最大的元素"更能代表滚动目标），找不到再回退到可见的最大可滚动元素，最后回退到window.scrollBy；超过约 240px 的滚动会被拆分为多个小步scrollBy调用并插入随机短延迟，让 LinkedIn、X 等懒加载站点有时间触发 IntersectionObserver 加载下一批内容。registry 中的案例 #1 即记录了这一修复（bridge.py的 smart scroll with container detection）。

P2：元素被遮罩覆盖（Element Covered by Overlay）

• 典型站点：带弹窗、tooltip、加载遮罩的 SPA。
• 检测方法：命中测试——取元素几何中心点，用elementFromPoint检查真正落在该点的顶层元素：

const rect = element.getBoundingClientRect(); const centerX = rect.left + rect.width / 2; const centerY = rect.top + rect.height / 2; const topElement = document.elementFromPoint(centerX, centerY); return topElement === element || element.contains(topElement);

• 修复方式：等待遮罩消失，或改用 JavaScriptelement.click()。

hive 的点击实现（registry 案例 #4/#5）将JavaScript click 作为首选（bridge.py中 click 的 JavaScript-first 路径），并在命中探测脚本中实现了"点击点命中栈 + y±5/y±15 垂直条纹扫描"，可以检测"点击刚好落在元素边缘之外"这类人类视觉难以察觉的偏差，同时计算点击点相对元素中心的偏移量（dxFromCenter/dyFromCenter），为调试提供精确证据。

P3：React 合成事件（React Synthetic Events）

• 典型站点：React SPA、现代 Web 应用。
• 检测方法：CDP 点击不触发处理器，但手动点击可以。
• 修复方式：把 JavaScript click 作为首选：

element.click();

原理是 React 的事件系统基于合成事件，对纯 CDP 派发的鼠标事件可能无响应；registry 案例 #5 的检测方法是在页面上查找__reactFiber$或data-reactroot标记确认站点使用 React。

P4：超大 DOM / 无障碍树（Huge DOM / Accessibility Tree）

• 典型站点：LinkedIn、Facebook、Twitter（数千节点的信息流）。
• 检测方法：DOM 元素总数超过 5000：

document.querySelectorAll('*').length > 5000

• 修复方式：
  1. 为快照操作添加超时；
  2. 将树截断到 2000 个节点；
  3. 无障碍树过大时回退到基于 DOM 的快照。

registry 案例 #10 记录了 LinkedIn 场景：DOM 超过 1 万个节点、无障碍树超过 5 万个节点，browser_snapshot()无限挂起；添加timeout_s参数配合asyncio.timeout()后，在 LinkedIn 上实测约 0.08 秒完成。快照实现位于bridge.py的snapshot()（带超时保护），测试模板中对应test_10_huge_dom.py。

P5：SPA 水合延迟（SPA Hydration Delay）

• 典型站点：React、Vue、Angular SPA 导航后。
• 检测方法：检查 React 是否已完成水合：

document.querySelector('[data-reactroot]') || document.querySelector('[data-reactid]')

• 修复方式：导航后等待特定选择器出现：

await browser_navigate(tab_id, url, wait_until="load") await browser_interact(action="wait", tab_id=tab_id, wait_for_selector='[data-testid="content"]', timeout_ms=5000)

registry 案例 #11 的要点是：document.readyState === 'complete'不代表内容就绪，SPA 的客户端水合可能尚未完成，快照会显示旧内容；案例 #13 则指出wait_until="load"在客户端路由场景会过早触发，应改用wait_until="networkidle"或wait_for_selector（bridge.py的navigate()提供wait_until选项）。

P6：Shadow DOM

• 典型站点：使用 Shadow DOM 的组件、Lit 元素。
• 检测方法：页面上存在带shadowRoot的元素：

document.querySelectorAll('*').some(el => el.shadowRoot)

• 修复方式：穿透 shadow root——用>>>分隔符逐层下沉查询：

function queryShadow(selector) { const parts = selector.split('>>>'); let node = document; for (const part of parts) { if (node.shadowRoot) { node = node.shadowRoot.querySelector(part.trim()); } else { node = node.querySelector(part.trim()); } } return node; }

hive 的scroll()与点击路径均支持>>>穿透选择器（源码注释明确说明 scroll 支持 ">>>" shadow-piercing selectors）。测试用例 test_06_shadow_dom.py 会先构造一个带 open shadow root 的测试页面，再验证穿透查询与点击。

快查表（Quick Reference）

关于输入问题，源码给出了更精确的指引：BeelineBridge.type_text()在插入文本前会先对目标矩形发起真实的 CDP 指针点击（pointerdown/pointerup/click/focus 完整序列），这是 Draft.js、Lexical、ProseMirror、React 受控 contenteditable 等富文本编辑器识别"真实输入"的前提——JS 触发的el.focus()会被这些框架忽略（见 tools/src/gcu/browser/bridge.py 的type_text实现）。默认use_insert_text=True时走Input.insertText，该 CDP 方法绕过键盘事件管线、以 IME 提交方式写入文本，对普通<input>/<textarea>、contenteditable、Lexical、Draft.js、ProseMirror、Monaco 均有效（曾针对 LinkedIn 消息编辑器（Lexical）实测验证）；逐键keyDown/keyUp路径作为兜底，用于显式关闭 insertText 的场景。

边缘案例注册表（registry.md）

完整的 17 个已登记边缘案例位于 .claude/skills/browser-edge-cases/registry.md，按类别分布为：滚动问题 3 个、点击问题 4 个、输入问题 3 个、快照问题 3 个、导航问题 2 个、截图问题 2 个。其中几个代表性案例：

• #1 LinkedIn 嵌套滚动容器（2026-04-03 验证）：browser_interact(action="scroll")返回{ok: true}但页面不动，根因是内容位于overflow: scroll的嵌套 div 而非主窗口；
• #7 ContentEditable / 富文本编辑器：type不插入文本，根因是元素为contenteditable而非<input>/<textarea>，检测条件是element.contentEditable === 'true'，修复为 JS 聚焦后用execCommand('insertText')或Input.dispatchKeyEvent（对应bridge.py的 contentEditable 处理段）；
• #15 选择器截图未实现（2026-04-03 验证）：browser_screenshot(selector="h1")静默忽略 selector 参数，修复为先用Runtime.evaluate调getBoundingClientRect()取得元素矩形，再作为clip传给Page.captureScreenshot；
• #16 陈旧浏览器上下文（Group ID 不匹配）（2026-04-03 验证）：browser_open()报"No group with id: XXXXXXX"但browser_status显示running: true，根因是内存_contexts中保留了已被外部关闭的 Chrome 标签组 ID，修复是先browser_stop()清掉陈旧上下文再browser_open(url)懒创建新上下文；
• #17 X Chat 长会话静默失败（2026-07-17 验证）：浏览器会话闲置约 2 小时后，send_dm.py每次发送都返回send_unverified（点击落在按钮上但消息未入队、未投递），根因是 X Chat SPA 的发送链路在长会话中失效而非选择器问题，修复为browser_stop()+browser_open()整体重启浏览器后重试，且失败的点击不会延迟投递，重启重试不会造成重复发送。

如何新增边缘案例

若遇到未登记的新故障，按以下流程沉淀到注册表：

1. 复现：用最小测试用例复现问题；
2. 记录：按下述模板登记；
3. 修复：实现带多层兜底的方案；
4. 验证：同时在问题站点与简单站点验证；
5. 提交：追加到 registry.md。

登记模板

### #N: [简短标题] | Attribute | Value | |-----------|-------| | **Site** | [URL 或站点类型] | | **Symptom** | [用户观察到的现象] | | **Root Cause** | [技术解释] | | **Detection** | [用于检测该案例的 JavaScript] | | **Fix** | [解决方案] | | **Code** | [已实现时的 文件:行号 引用] | | **Verified** | [日期 或 "pending"] |

深入阅读

• .claude/skills/browser-edge-cases/registry.md：全部 17 个已知边缘案例的完整列表；
• .claude/skills/browser-edge-cases/scripts/test_case.py：测试新案例的模板脚本；
• tools/BROWSER_USE_PATTERNS.md：从 browser-use 集成中提炼的实现模式（元素几何多级回退、Input.dispatchKeyEvent键入、无障碍树快照、iframe 深度处理等）；
• tools/src/gcu/browser/bridge.py：BeelineBridge核心实现，涵盖navigate/click/type_text/scroll/snapshot/evaluate等全部浏览器动作及超时、穿透选择器、命中探测等机制；
• tools/tests/test_x_page_load_repro.py：X（Twitter）懒加载与 SPA 导航的复现测试。

• 人工智能
• AI Agent
• 多智能体
• MCP 服务
• 工具调用
• 浏览器控制