my-agent-browser

my-agent-browser

通过 chrome-devtools-mcp MCP 服务为 AI Agent 提供浏览器自动化。

版本 1.2.0，已通过 chrome-devtools-mcp 1.11.0 测试。建议使用 Node 24 LTS。无需启动 Chrome 即可检查已安装的封装程序：

node <skill-dir>/scripts/start-mcp.js --doctor --json

报告会标明封装程序、Node、Chrome、MCP 二进制文件和配置路径。如果封装程序与已安装的技能不一致，请先重新安装此技能，再排查浏览器问题。

设置检查

<skill-dir> 指包含此 SKILL.md 的目录（通常为 ~/.agents/skills/my-agent-browser/ 或 ~/.claude/skills/my-agent-browser/，具体取决于你的 Agent）。

如果工具列表中没有浏览器 MCP 工具（navigate_page、take_snapshot、click、fill）：

1. 安装：npm install -g [email protected]

2. 创建配置：

   mkdir -p ~/.config/agent-skills/my-agent-browser
   cp <skill-dir>/config.example.json ~/.config/agent-skills/my-agent-browser/config.json
   

3. 在 Agent/IDE 中注册 MCP 服务。MCP 服务条目如下：

   • 名称：browser
   • 命令：node
   • 参数：["<skill-dir>/scripts/start-mcp.js"]（将 <skill-dir> 替换为实际的绝对路径）

   注册方法因环境而异，请查阅 Agent 的 /help、官方文档或设置界面，了解 MCP 服务的配置位置。

4. 重启 Agent 会话

核心工作流

1. list_pages 或 new_page { url } — 获取 pageId（每次调用页面范围的工具时都必须提供）
2. navigate_page { pageId, url } — 打开页面（如果刚使用过 new_page，则跳过）
3. take_snapshot { pageId } — 读取包含 uid 引用的页面结构
4. click { pageId, uid } / fill { pageId, uid, value } / press_key { pageId, key } — 进行交互
5. 再次调用 take_snapshot { pageId } — 每次修改页面后，uid 都会变化

读取快照

take_snapshot 会返回缩进的无障碍树：

uid=1_0 RootWebArea "Sign in" url="https://example.com/login"
  uid=1_5 heading "Sign in" level="1"
  uid=1_7 textbox "Email" focusable required
  uid=1_9 textbox "Password" required
  uid=1_12 button "Sign in"
  uid=1_14 link "Forgot password?" url="..."

每个 uid=X_Y 都是传递给 click、fill、hover 等工具的标识符。

可用工具

导航

• navigate_page { pageId, url } — 前往 URL
• new_page { url } — 打开新标签页（返回其 pageId）
• list_pages — 列出所有标签页及其 pageId
• select_page { pageId } — 聚焦标签页（不会替代之后调用时传递 pageId）
• close_page { pageId } — 关闭标签页

读取

• take_snapshot { pageId } — 获取包含 uid 引用的无障碍树
• take_screenshot { pageId } — 捕获页面图像

交互

• click { pageId, uid } — 点击元素
• fill { pageId, uid, value } — 清空字段并输入值
• fill_form { pageId, elements: [{uid, value}] } — 填写多个字段
• type_text { pageId, text } — 在当前焦点处输入（不清空内容，也不指定目标）
• press_key { pageId, key } — 按下按键（Enter、Tab、Escape、ArrowDown 等）
• hover { pageId, uid } — 将鼠标悬停在元素上
• drag { pageId, from_uid, to_uid } — 在元素之间拖动
• upload_file { pageId, uid, filePath } — 将文件上传到输入框
• handle_dialog { pageId, action } — 接受或关闭对话框

实用工具

• evaluate_script { pageId, function } — 执行 JavaScript
• wait_for { pageId, text[] } — 等待文本出现
• resize_page { pageId, width, height } — 更改视口

高级工具

这些工具组默认可用——无需设置标志。详细工作流请参阅 references/advanced-tools.md。

• 性能：performance_start_trace / performance_stop_trace / performance_analyze_insight — 跟踪记录、Core Web Vitals
• 网络：list_network_requests / get_network_request — 检查请求/响应
• Lighthouse：lighthouse_audit — 审计（导航/快照、桌面/移动设备）
• 控制台：list_console_messages / get_console_message — 浏览器控制台
• 模拟：emulate — 限制网络/CPU、地理位置、配色方案

配置中的 mcp.flags 会直接传递给 chrome-devtools-mcp。可用它来缩减工具集（--no-categoryNetwork / --no-categoryPerformance / --no-categoryEmulation，或使用 --slim 将工具缩减为 3 个），也可用它来添加可选工具组（使用 --memoryDebugging / --experimentalMemory 进行堆快照分析，使用 --categoryExtensions，或使用 --experimentalVision 启用坐标 click_at）。权威标志列表：npx [email protected] --help。

关键规则

• 始终传入 pageId — chrome-devtools-mcp 要求页面级工具（click、fill、take_snapshot、navigate_page、evaluate_script、wait_for 等）传入该参数。通过 list_pages 或 new_page 获取。select_page 只会将该标签页设为焦点；后续调用仍需传入 pageId。
• UID 是临时的 — 任何会更改页面的导航或交互之后，先前的 UID 都会失效。在下一次交互前，务必再次执行 take_snapshot { pageId }。
• 输入内容使用 fill — 它会定位特定元素并先清空内容。type_text 会在当前焦点处输入，容易出错。
• 执行一个操作，然后重新读取 — 不要在未重新获取快照的情况下批量执行多个操作。第一个操作可能会使后续 UID 失效。
• 大型页面：使用基于文件的快照 — 见下文。

大型页面（重要）

包含大量 DOM 节点的页面（富文本编辑器、大型表格、聊天记录、管理面板）如果使用 includeSnapshot: true 或在其上使用 wait_for，可能会崩溃或卡住。

症状：浏览器无响应、出现“target closed”、注入内容后反复超时。

解决方案：

1. 在大型页面上使用 click、fill、hover 时，设置 includeSnapshot: false（或省略该参数）
2. 将快照保存到文件：take_snapshot { pageId, filePath: "/tmp/snap.txt" }
3. 只读取所需内容：tail -100 /tmp/snap.txt（对话框/模态框位于末尾）
4. 关闭无关标签页——每个标签页都会将其 DOM 保留在内存中

适用场景：注入内容后的所见即所得编辑器、包含 200 个以上重复元素的页面、滚动多次后的无限滚动页面。应在崩溃前主动切换到基于文件的工作流，而不是等崩溃后再切换。

抓取模式

简单场景：快照即可

导航 → wait_for { pageId, text } → take_snapshot { pageId } → 直接从无障碍树中读取文本/链接。大多数结构化页面无需 JS。

分页场景：优先使用基于 URL 的方式

循环执行 navigate_page { pageId, url: "...?page=N" }，而不是点击“下一页”按钮。这样更可靠，可避免 UID 过期，也便于在中断后恢复。

动态/延迟加载内容

执行 press_key { pageId, key: "End" } 触发延迟加载 → wait_for { pageId, text } 等待已知内容 → take_snapshot { pageId }。

复杂提取：evaluate_script

当无障碍树无法捕获表格行/列关系或深度嵌套数据时，使用 JS 提取：

evaluate_script { pageId, function: "() => JSON.stringify([...document.querySelectorAll('tr')].map(r => [...r.cells].map(c => c.textContent.trim())))" }

受登录限制的内容

选项 A：持久化配置文件 — 使用 headless: false 登录一次，然后复用 userDataDir。 选项 B：自动化 — 通过 fill + click + wait_for 填写凭据。 选项 C：连接到现有会话 — 在配置中设置 browserUrl。

多标签页模式

• new_page { url } 会打开一个标签页并返回其 pageId——后续调用请使用该 pageId，不要猜测
• 每次调用都传入目标标签页的 pageId。select_page 仅用于聚焦/切换到前台
• “在新标签页中打开、提取内容、关闭、返回”模式可避免在列表页上丢失当前位置
• 每个标签页彼此独立——快照、UID 和页面状态不会跨标签页共享

JavaScript 执行技巧

• evaluate_script 在浏览器页面上下文中运行（可访问 document、window 和页面库）
• 返回值必须可序列化为 JSON——对对象/数组使用 JSON.stringify()
• 可以返回 Promise（适用于轮询/等待模式）
• DOM 更改会保留——修改页面后，重新获取快照以获得新的 UID
• 常见用途：滚动、提取结构化数据、移除覆盖层、触发延迟加载、读取计算样式

错误恢复

• 点击后找不到元素 → 页面已更改，请重新执行 take_snapshot { pageId } 并查找新的 UID
• wait_for 超时 → 页面未加载预期内容，请执行 take_snapshot { pageId } 查看实际状态
• MCP 状态过期 → 包装器会替换并初始化其 MCP 子进程。在执行中的调用会明确失败，且不会重放。恢复后，执行 list_pages 并获取新快照；重试会更改状态的操作前，请先确认结果。
• Chrome 崩溃 / “target closed” → 在托管的延迟模式下，Chrome 会重新启动；执行 list_pages，然后使用新的 pageId 再次导航
• 反机器人检测 → 先检查 WebGL 渲染器和出口 IP，而不是 Chrome 标志。请参阅 references/anti-detection.md

示例：登录流程

1. list_pages → pageId (or new_page { url: "https://app.example.com/login" })
2. navigate_page { pageId, url: "https://app.example.com/login" }  — skip if new_page already loaded it
3. take_snapshot { pageId }
   → uid=1_7 textbox "Email", uid=1_9 textbox "Password", uid=1_12 button "Sign in"
4. fill_form { pageId, elements: [{uid: "1_7", value: "[email protected]"}, {uid: "1_9", value: "secret123"}] }
5. take_snapshot { pageId } → find the current Sign in button, e.g. uid=2_12
6. click { pageId, uid: "2_12" }
7. wait_for { pageId, text: ["Dashboard"] }
8. take_snapshot { pageId } → now on dashboard, new uids

故障排除速查表

问题	原因	解决方法
点击/填写没有反应	UID 已过期	重新执行 take_snapshot { pageId }，使用新的 UID
Required at pageId	未提供 pageId	执行 list_pages / new_page，然后在每次针对页面的调用中传入该 pageId
快照中没有元素	位于首屏下方 / iframe / 异步加载	先滚动，或执行 wait_for { pageId }，或执行 evaluate_script { pageId } 进行检查
wait_for 超时	文本始终未出现	执行 take_snapshot { pageId } 查看实际状态
Chrome 无法启动	未安装或端口被占用	检查 which google-chrome，检查端口冲突
快照为空/内容极少	JS 渲染的内容尚未就绪	获取快照前先执行 wait_for
内存溢出 / 崩溃	DOM 过大	使用基于文件的快照（见上文）
机器人检测	通常是 WebGL 渲染器或出口 IP，极少是标志	请参阅 references/anti-detection.md

详细故障排除指南：references/troubleshooting.md 网络调试工作流：references/network-debugging.md 高级抓取模式：references/scraping-patterns.md

特定领域的工作流

• 学术论文下载（CNKI、Google Scholar、MDPI）：references/domain/academic-paper-download.md

导航与脚本恢复

• 使用 navigate_page { pageId, type: "reload" } / { pageId, url } 刷新或导航。 调用 location.reload() 后继续等待任务的脚本可能会丢失执行上下文；请将导航和后续检查分开调用。
• evaluate_script.function 是一个 JavaScript 函数，例如 "() => document.title"。 不要传入裸表达式或 (window as any) 之类的 TypeScript 语法。
• No page found 表示需要使用 list_pages 重新查找 ID；不要反复重试旧 ID。
• 提取 HTTP 内容时，请先读取 status 和响应文本，再解析 JSON。空响应和 HTML 错误页面需要分别处理；仅有 JSON 解析错误并不能证明请求的更改失败。

升级浏览器依赖时，请阅读 dependency-upgrades.md，了解经过测试的版本、运行时要求以及文件／工具行为的变更。