browser-tools

浏览器工具

用于 Agent 辅助式网页自动化的 Chrome DevTools Protocol 工具。这些工具连接到已启用远程调试、运行在 :9222 上的 Chrome。

设置

首次使用前运行一次：

cd {baseDir}/browser-tools
npm install

启动 Chrome

{baseDir}/browser-start.js              # Fresh profile
{baseDir}/browser-start.js --profile    # Copy user's profile (cookies, logins)

启动 Chrome，并在 :9222 上启用远程调试。使用 --profile 保留用户的身份验证状态。

导航

{baseDir}/browser-nav.js https://example.com
{baseDir}/browser-nav.js https://example.com --new

导航到 URL。使用 --new 标志在新标签页中打开，而不是重用当前标签页。

执行 JavaScript

{baseDir}/browser-eval.js 'document.title'
{baseDir}/browser-eval.js 'document.querySelectorAll("a").length'

在活动标签页中执行 JavaScript。代码在异步上下文中运行。可用于提取数据、检查页面状态或以编程方式执行 DOM 操作。

截图

{baseDir}/browser-screenshot.js

捕获当前视口并返回临时文件路径。可用于直观检查页面状态或验证 UI 更改。

选择元素

{baseDir}/browser-pick.js "Click the submit button"

IMPORTANT：当用户想要选择页面上的特定 DOM 元素时，请使用此工具。它会启动一个交互式选择器，让用户点击要选取的元素。用户可以选择多个元素（Cmd/Ctrl+Click），完成后按 Enter。此工具会返回所选元素的 CSS 选择器。

常见用例：

• 用户说“我想点击那个按钮” → 使用此工具让用户选择它
• 用户说“从这些项目中提取数据” → 使用此工具让用户选择这些元素
• 需要特定选择器，但页面结构复杂或不明确时

Cookie

{baseDir}/browser-cookies.js

显示当前标签页的所有 Cookie，包括域、路径、httpOnly 和 secure 标志。可用于调试身份验证问题或检查会话状态。

提取页面内容

{baseDir}/browser-content.js https://example.com

导航到 URL 并将可读内容提取为 Markdown。使用 Mozilla Readability 提取文章，并使用 Turndown 将 HTML 转换为 Markdown。适用于包含 JavaScript 内容的页面（会等待页面加载）。

适用场景

• 在真实浏览器中测试前端代码
• 与需要 JavaScript 的页面交互
• 用户需要直观查看或与页面交互时
• 调试身份验证或会话问题
• 抓取需要执行 JS 的动态内容

---

效率指南

优先检查 DOM，而不是截图

不要通过截图查看页面状态。应当直接解析 DOM：

// Get page structure
document.body.innerHTML.slice(0, 5000)

// Find interactive elements
Array.from(document.querySelectorAll('button, input, [role="button"]')).map(e => ({
  id: e.id,
  text: e.textContent.trim(),
  class: e.className
}))

在单次调用中运行复杂脚本

将所有内容包装在 IIFE 中，以运行多条语句：

(function() {
  // Multiple operations
  const data = document.querySelector('#target').textContent;
  const buttons = document.querySelectorAll('button');
  
  // Interactions
  buttons[0].click();
  
  // Return results
  return JSON.stringify({ data, buttonCount: buttons.length });
})()

批量交互

不要为每次点击分别调用。应当批量执行：

(function() {
  const actions = ["btn1", "btn2", "btn3"];
  actions.forEach(id => document.getElementById(id).click());
  return "Done";
})()

输入序列

(function() {
  const text = "HELLO";
  for (const char of text) {
    document.getElementById("key-" + char).click();
  }
  document.getElementById("submit").click();
  return "Submitted: " + text;
})()

读取应用/游戏状态

通过一次调用提取结构化状态：

(function() {
  const state = {
    score: document.querySelector('.score')?.textContent,
    status: document.querySelector('.status')?.className,
    items: Array.from(document.querySelectorAll('.item')).map(el => ({
      text: el.textContent,
      active: el.classList.contains('active')
    }))
  };
  return JSON.stringify(state, null, 2);
})()

等待更新

如果操作后 DOM 会更新，请使用 bash 添加短暂延迟：

sleep 0.5 && {baseDir}/browser-eval.js '...'

先调查，再交互

始终先了解页面结构：

(function() {
  return {
    title: document.title,
    forms: document.forms.length,
    buttons: document.querySelectorAll('button').length,
    inputs: document.querySelectorAll('input').length,
    mainContent: document.body.innerHTML.slice(0, 3000)
  };
})()

然后根据检查结果定位特定元素。