Browser Harness 共学笔记

1. 学习总览

本次共学以 browser-harness 为核心，完成了从安装、连接隔离 Chrome、网页操作、自然语言任务、复杂网页提取、canvas 页游观察、前端调试，到 helper 沉淀的完整闭环。

2. browser-harness 的定位

browser-harness 是面向 LLM Agent 的真实浏览器控制工具，通过 CDP 连接真实 Chrome/Chromium，让 Agent 能像人一样观察和操作网页。

用户自然语言任务
    ↓
Agent 规划与判断
    ↓
browser-harness CLI
    ↓
Chrome DevTools Protocol
    ↓
真实浏览器页面

3. 安装与连接隔离 Chrome

安装

git clone https://github.com/browser-use/browser-harness.git
uv tool install -e "/e/CodeLab/AiLab/browser-harness-learn/browser-harness"

本次安装后 CLI 位于 /c/Users/Administrator/.local/bin/browser-harness，可用 browser-harness --doctor 做连接诊断。

启动隔离 Chrome

powershell.exe -NoProfile -Command "Start-Process -FilePath 'C:\Program Files\Google\Chrome\Application\chrome.exe' -ArgumentList '--remote-debugging-port=9222','--user-data-dir=E:\CodeLab\AiLab\browser-harness-learn\chrome-profile','about:blank'"

连接

BU_CDP_URL=http://127.0.0.1:9222 browser-harness <<'PY'
print(page_info())
PY

BU_CDP_URL 是环境变量，告诉 browser-harness 直接连接指定 CDP 地址。启动后应验证 page_info() 和截图，不假设页面已经正确加载。

4. 基础操作能力

打开页面与截图

new_tab('https://github.com/browser-use/browser-harness')
wait_for_load()
print(page_info())
capture_screenshot()

坐标点击

capture_screenshot()
click_at_xy(x, y)
capture_screenshot()

点击前可用 document.elementFromPoint(x, y) 校准坐标命中元素。

输入与验证

输入后必须读回真实值，如 input.value、select.value、checkbox.checked。本次发现 fill_input() 在当前环境可能出现字符重复，因此更稳做法是 JS 清空后再 type_text()，并读回字段值确认。

5. 从 API 到自然语言任务

最终使用方式不是用户手写 Python，而是用户用自然语言描述目标，Agent 在背后调用 browser-harness。

你：请打开页面并提取最新 10 条结果，过滤广告和重复内容。
Agent：打开页面 → 截图 → 提取 → 去重 → 汇总 → 复盘用到的能力

6. X 搜索场景

登录墙

遇到 X 登录页时，停止并让用户手动登录，不读取或输入密码、验证码。

去噪

• 关键词命中。
• 语义相关。
• 排除广告、刷量、垃圾内容和关键词误伤。
• 区分高相关、低信息量和重复模板。

无限滚动

每一轮读取当前 DOM
→ 用 status 链接去重保存
→ 滚动
→ 等待
→ 再读取

证据链

对“张雪机车年度冠军前景”追踪时，步骤是先搜索精确关键词，再找最像来源或信息量最高的帖子，打开详情页检查正文、时间、图片、视频、引用帖、外链和来源标注。

本次结论是：X 内传播较多，并出现“来源：美丽浙江”等转述线索，但缺少 WSBK 官方链接、美丽浙江原始链接或官方积分榜，因此可信度为中等，仍需外部官方来源核验。

7. 页游 canvas 操作经验

访问 https://codomino.99.com/ 后发现页面主体是 canvas，DOM 几乎没有文本。

Mummy Reborn 试玩判断

本次普通玩家级试玩中最终赢分显示为 407,500。

8. CDP、CloakBrowser 与 BU_CDP_URL

browser-harness 连接的是 CDP endpoint。只要某浏览器基于 Chromium、开启 remote debugging、提供 CDP 地址，就可尝试连接。

BU_CDP_URL=http://127.0.0.1:9242 browser-harness <<'PY'
print(page_info())
PY

CloakBrowser 基于 Chromium，支持 Playwright/Puppeteer 和 CDP remote connection，因此理论上可由 browser-harness 连接。

多浏览器并行可配合 BU_NAME：

BU_NAME=cloak BU_CDP_URL=http://127.0.0.1:9242 browser-harness <<'PY'
print(page_info())
PY

9. 前端调试练习

简单 bug 页

点击“加载用户信息”后请求 /api/user，服务端故意返回 500。

标准调试流程

打开页面
→ 截图初始状态
→ 安装 console/fetch 监听
→ 点击按钮
→ 截图异常状态
→ 读取 console/network/storage
→ 判断原因

综合练习页

页面地址：http://127.0.0.1:8766

完成：表单填写、保存草稿、localStorage 验证、失败 API 调试。

10. 沉淀机制

browser-harness 提供 Agent 可编辑工作区：

agent-workspace/agent_helpers.py
agent-workspace/domain-skills/

核心理解：

写入不自动，复用自动。

• helper 写入后，下次 browser-harness 自动加载。
• domain-skills 启用后，goto_url 可按域名暴露相关 skill。
• browser-harness 不会后台自动总结和写文件。

11. get_debug_snapshot helper

本次实际沉淀了一个 helper：

def get_debug_snapshot():
    from browser_harness.helpers import js

    return js(r"""
(() => ({
  visibleText: document.body ? document.body.innerText : '',
  console: window.__comprehensiveDebug?.console || window.__debugRun?.console || window.__debugPractice?.console || [],
  network: window.__comprehensiveDebug?.network || window.__debugRun?.network || window.__debugPractice?.network || [],
  localStorage: Object.fromEntries(Object.entries(localStorage)),
  sessionStorage: Object.fromEntries(Object.entries(sessionStorage)),
  url: location.href,
  title: document.title
}))()
""")

第一次验证遇到 NameError: name 'js' is not defined，原因是 agent_helpers.py 独立模块加载，修复为函数内部导入 js。

自然语言调用

请复现这个问题，然后用 get_debug_snapshot 收集页面可见文本、console、network、localStorage 和 sessionStorage，并基于快照判断问题原因。

12. 卸载与清理

browser-harness --reload
uv tool uninstall browser-harness
rm -rf "/e/CodeLab/AiLab/browser-harness-learn/chrome-profile"
rm -rf "/e/CodeLab/AiLab/browser-harness-learn/browser-harness"

如需保留 helper，应先备份 agent-workspace/agent_helpers.py。

隔离 Chrome profile 可能包含登录后 cookie/session，若要清理登录痕迹，应删除该 profile。

13. 可复用自然语言模板

请打开 [网址]，先截图观察页面状态，然后完成 [目标]。每一步操作后截图验证。如果遇到登录、付费、验证码或不可逆操作，先停下来问我。

请复现 [bug]。先截图初始状态，然后执行用户操作，读取 console、network、storage，最后判断是 UI、JS、接口、鉴权还是数据问题。

请围绕 [说法] 做证据链追踪。先列出需要验证的事实，再找官方来源、媒体来源和用户转述，最后区分原始来源、二次传播和观点判断。

请复现这个问题，然后用 get_debug_snapshot 收集页面可见文本、console、network、localStorage 和 sessionStorage，并基于快照判断问题原因。

14. 复习测验