chrome-automation

技能：Chrome 自动化（agent-browser）

通过 agent-browser CLI 在用户真实的 Chrome 会话中自动执行浏览器任务。

前提条件：必须已安装 agent-browser，并且 Chrome 已启用远程调试。如果不确定，请参阅 references/agent-browser-setup.md。

---

核心原则：复用用户现有的 Chrome

此技能仅使用一个 Chrome 进程——用户的真实浏览器。没有会话管理、没有独立配置文件，也不会启动全新的 Playwright 浏览器。

始终先列出标签页

打开任何新页面前，始终先列出现有标签页：

agent-browser --auto-connect tab list

这会返回所有已打开标签页的索引编号、标题和 URL。检查所需页面是否已经打开：

• 如果目标页面已经打开 → 直接切换到该标签页，而不是打开新页面。用户可能已经登录，并且页面处于正确状态，因此才会将其打开。

  agent-browser --auto-connect tab <index>
  

• 如果目标页面尚未打开 → 在当前标签页或新标签页中打开。

  agent-browser --auto-connect open <url>
  

为什么这很重要

• 用户的 Chrome 中保存了他们的 Cookie、登录会话和浏览器状态
• 如果页面已经打开，再开新页面会浪费时间，还可能丢失登录状态
• 许多营销平台（社交媒体仪表板、广告管理工具、CMS 工具）都需要登录；复用已登录的标签页可以避免重新进行身份验证

---

连接

始终使用 --auto-connect 连接到用户正在运行的 Chrome 实例：

agent-browser --auto-connect <command>

此命令会自动发现已启用远程调试的 Chrome。如果连接失败，请指导用户启用远程调试（参阅 references/agent-browser-setup.md）。

Chrome 144+ WebSocket 专用回退方案

Chrome 144+ 可以通过 chrome://inspect/#remote-debugging 暴露远程调试的 WebSocket 专用端点。在这种状态下，页面会显示 Server running at: 127.0.0.1:9222，但传统的发现 URL 会返回 404：

curl http://127.0.0.1:9222/json/version
curl http://127.0.0.1:9222/json/list

较旧的 agent-browser 版本（例如 0.27.x）可能会报错 No running Chrome instance found，尽管 Chrome 已准备就绪。首先尝试使用最新版 CLI，而不更改全局安装：

npx -y agent-browser@latest connect "ws://127.0.0.1:9222/devtools/browser"
npx -y agent-browser@latest tab list

如果这样可以正常使用，接下来完成浏览器任务时请使用 npx -y agent-browser@latest <command>。如果遇到引擎警告或安装错误，请将 Node 升级到 24+，或全局安装最新版 agent-browser。

---

常见工作流

1. 导航并交互

# List tabs to find existing pages
agent-browser --auto-connect tab list

# Switch to an existing tab (if found)
agent-browser --auto-connect tab <index>

# Or open a new page
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect wait --load networkidle

# Take a snapshot to see interactive elements
agent-browser --auto-connect snapshot -i

# Click, fill, etc.
agent-browser --auto-connect click @e3
agent-browser --auto-connect fill @e5 "some text"

2. 从页面提取数据

# Get all text content
agent-browser --auto-connect get text body

# Take a screenshot for visual inspection
agent-browser --auto-connect screenshot

# Execute JavaScript for structured data
agent-browser --auto-connect eval "JSON.stringify(document.querySelectorAll('table tr').length)"

3. 重放 Chrome DevTools 录制

用户可能会提供从 Chrome DevTools Recorder 导出的录制文件（JSON、Puppeteer JS 或 @puppeteer/replay JS 格式）。请参阅下文的重放录制。

逐步交互指南

获取快照

使用 snapshot -i 查看所有带有引用标识（@e1、@e2 等）的交互元素：

agent-browser --auto-connect snapshot -i

输出会列出每个交互元素的角色、文本和引用标识。后续操作时请使用这些引用标识。

步骤类型映射

操作	命令
导航	agent-browser --auto-connect open <url>（可选使用 wait --load networkidle，但某些网站（如 Reddit）永远不会达到 networkidle 状态——如果 open 已显示页面标题，则跳过）
点击	snapshot -i → 查找引用标识 → click @eN
填写标准输入框	click @eN → fill @eN "text"
填写富文本编辑器	click @eN → keyboard inserttext "text"
按键	press <key>（Enter、Tab、Escape 等）
滚动	scroll down <amount> 或 scroll up <amount>
等待元素	wait @eN 或 wait "<css-selector>"
截图	screenshot 或 screenshot --annotate
获取页面文本	get text body
获取当前 URL	get url
运行 JavaScript	eval <js>

如何区分输入类型

• 标准输入框/文本区域 → 使用 fill
• 可编辑内容的 div / 富文本编辑器（LinkedIn 消息框、Gmail 撰写窗口、Slack、CMS 编辑器）→ 先点击/聚焦，然后使用 keyboard inserttext

Ref 生命周期

页面发生变化时，Refs（@e1、@e2 等）会失效。以下情况后务必重新获取快照：

• 点击会触发页面导航的链接或按钮
• 提交表单
• 触发动态内容加载（AJAX、SPA 导航）

验证

每次重要操作后，都要验证结果：

agent-browser --auto-connect snapshot -i   # check interactive state
agent-browser --auto-connect screenshot     # visual verification

---

重放录制内容

支持的格式

1. JSON（推荐）——结构化，可渐进读取：

   # Count steps
   jq '.steps | length' recording.json
   
   # Read first 5 steps
   jq '.steps[0:5]' recording.json
   

2. @puppeteer/replay JS（import { createRunner }）

3. Puppeteer JS（require('puppeteer')、page.goto、Locator.race）

如何重放

1. 解析录制内容——先了解完整意图再操作。概述录制内容执行的操作。
2. 先列出标签页——检查目标页面是否已经打开。
3. 导航——执行 navigate 步骤，尽可能重复使用现有标签页。
4. 对于每个交互步骤：
   • 获取快照（snapshot -i），查看当前可交互元素
   • 将录制中的 aria/... 选择器与快照进行匹配
   • 依次回退到 text/...、CSS 类提示，然后是截图
   • 不要依赖 ember ID、数字 ID 或精确 XPath——这些内容会在每次页面加载时变化
5. 每步操作后都要验证——通过快照或截图确认

---

包含大量 iframe 的网站

snapshot -i 仅针对主框架运行，无法访问 iframe 内部。LinkedIn、Gmail 和嵌入式编辑器等网站会在 iframe 内渲染内容。

检测 iframe 问题

• snapshot -i 返回的结果异常简短或为空
• 录制内容引用的元素未出现在快照输出中
• get text body 的内容与截图显示的内容不符

解决方法

1. 使用 eval 访问 iframe 内容：

   agent-browser --auto-connect eval --stdin <<'EVALEOF'
   const frame = document.querySelector('iframe[data-testid="interop-iframe"]');
   const doc = frame.contentDocument;
   const btn = doc.querySelector('button[aria-label="Send"]');
   btn.click();
   EVALEOF
   

   注意：仅适用于同源 iframe。

2. 使用 keyboard 盲输入：如果 iframe 元素已获得焦点，keyboard inserttext "..." 无论是否跨越框架边界，都会发送文本。

3. 使用 get text body 读取包括 iframe 在内的完整页面内容。

4. 当快照不可靠时，使用 screenshot 进行视觉验证。

何时询问用户

如果在同一步骤上尝试 2 次后解决方法仍无效，请暂停并说明：

• 页面使用了无法通过快照访问的 iframe
• 你需要哪个元素，以及预期结果是什么
• 请用户手动执行该步骤，然后再继续

---

处理意外情况

自动处理（不要停止）：

• 弹出窗口或横幅 → 将其关闭（find text "Dismiss" click 或 find text "Close" click）
• Cookie 同意对话框 → 接受或关闭
• 工具提示遮罩 → 先关闭
• 快照中没有该元素 → 尝试 find text "..." click，或使用 scroll down 300 滚动以显示该元素

暂停并询问用户：

• 需要登录/身份验证
• 出现 CAPTCHA
• 页面结构与预期完全不同
• 即将执行破坏性操作（删除数据、发送实际内容）——先确认
• 同一步骤尝试超过 2 次仍陷入停滞
• 所有 iframe 解决方法均已失效

暂停时，请清楚说明：你正在执行哪个步骤、预期结果是什么，以及你看到了什么。

关键命令参考

命令	描述
tab list	列出所有已打开的标签页及其索引、标题和 URL
tab <index>	根据索引切换到现有标签页
tab new	打开一个新的空白标签页
tab close	关闭当前标签页
open <url>	导航到 URL
snapshot -i	列出带有引用标识的交互元素
click @eN	根据引用标识点击元素
fill @eN "text"	清空并填写标准输入框/文本区域
type @eN "text"	输入文本，但不清空已有内容
keyboard inserttext "text"	插入文本（最适用于 contenteditable）
press <key>	按下键盘按键
scroll down/up <amount>	按像素滚动页面
wait @eN	等待元素出现
wait --load networkidle	等待网络活动结束
wait <ms>	等待指定时长
screenshot [path]	截取屏幕截图
screenshot --annotate	截取带编号标注的屏幕截图
eval <js>	在页面中执行 JavaScript
get text body	获取所有文本内容
get url	获取当前 URL
set viewport <w> <h>	设置视口大小
find text "..." click	通过语义查找并点击
close	关闭浏览器会话

---

已知限制

1. 无法识别 iframe 内容：snapshot -i 无法查看 iframe 内部。请参阅 包含大量 iframe 的网站。
2. find text 严格模式：多个元素匹配时会失败。请使用 snapshot -i 定位特定的引用标识。
3. fill 与 contenteditable：fill 仅适用于 <input> 和 <textarea>。对于富文本编辑器，请使用 keyboard inserttext。
4. eval 仅适用于主框架：要与 iframe 内容交互，请通过 document.querySelector('iframe').contentDocument... 遍历。

---

多平台操作

当用户要求在多个平台上执行操作（例如“将这篇文章发布到 Dev.to、LinkedIn 和 X”）时，请勿尝试在一次对话中完成所有平台的操作。应改为启动按顺序运行的子 Agent/工作进程，每个平台一个。选择此技能即明确授权在此多平台工作流中使用子 Agent/工作进程。

为什么要使用子 Agent

每个平台的操作会消耗约 25-40K 个令牌（参考文件、快照和交互）。在一个上下文中操作 3-5 个平台，可能会触及上下文限制，并降低后续平台操作的准确性。每个子 Agent/工作进程都有独立且全新的上下文窗口。

如何执行

1. 准备内容——与用户确认帖子文本、标题、标签，以及任何特定于平台的调整。
2. 针对每个平台，启动一个子 Agent/工作进程，并在提示词中包含：
   • 要发布的完整内容
   • 阅读相关参考文件的说明（例如 Read /path/to/skills/chrome-automation/references/x.md）
   • 阅读 agent-browser 技能文件以查阅命令参考的说明
   • 具体任务（发帖、评论、回复等）
   • 任何特定于平台的说明（例如“在 LinkedIn 上使用这些主题标签”）
3. 按顺序运行子 Agent/工作进程（一次一个），因为它们通过 --auto-connect 共用同一个 Chrome 浏览器。并行运行子 Agent/工作进程可能导致标签页冲突。
4. 每个子 Agent/工作进程完成后，先向用户报告结果，再启动下一个。

子 Agent 提示词模板

You are automating a browser task on [PLATFORM].

First, read these files for context:
- /absolute/path/to/skills/chrome-automation/references/[platform].md
- The installed agent-browser skill file, if available (agent-browser command reference)

Then connect to the user's Chrome browser using `agent-browser --auto-connect` and perform the following task:

[TASK DESCRIPTION]

Content to publish:
[CONTENT]

Important:
- Always list tabs first (`tab list`) and reuse existing logged-in tabs
- Re-snapshot after every navigation or action
- Confirm with the user before submitting/publishing (destructive action)
- If login is required or a CAPTCHA appears, stop and explain

不应使用子 Agent 的情况

• 单个平台——直接在当前对话中操作即可。
• 只读任务（浏览、搜索、提取数据）——这类任务占用的上下文较少，一次对话可处理 2-3 个平台。

---

平台参考

在特定平台上自动执行任务时，请参阅相关参考文档，了解页面结构详情、常见操作和已知问题：

平台	参考文档	主要说明
Reddit	references/reddit.md	自定义 faceplate-* 组件；永远不会达到 networkidle；评论文本框没有标签；由于元素重复，find text 会失败
X (Twitter)	references/x.md	open 经常超时（使用 tab list 复用现有标签页）；点击时间戳查看帖子详情（而不是用户名）；DraftJS contenteditable 输入框（data-testid="tweetTextarea_0"）；避免使用 networkidle
LinkedIn	references/linkedin.md	Ember.js SPA；按 Enter 键提交评论（换行请使用 Shift+Enter）；评论框和编辑框的标签相同；避免使用 networkidle；消息浮层可能会遮挡内容
Dev.to	references/devto.md	快速的服务端渲染 HTML（Forem/Rails）；评论和帖子使用标准 <textarea>（Markdown）；5 种回应类型；由 Algolia 提供支持的搜索；networkidle 通常可正常工作
Hacker News	references/hackernews.md	简洁的纯 HTML；所有表单字段都没有标签；link "reply" 会跳转到单独的页面；networkidle 可立即达到；帖子和评论有速率限制

---

有关安装和 Chrome 设置说明，请参阅 references/agent-browser-setup.md。