chrome-automation

技能：Chrome 自动化 (agent-browser)

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

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

---

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

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

例外：浏览器视口录制是一个单独的模式。对于账户、凭证、云控制台或演示录制，请使用 Agent Browser 的 record 命令配合专用的有头配置文件，而不是用户日常使用的 Chrome。

始终先列出标签页

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

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. 导航与交互

# 列出标签页以查找现有页面
agent-browser --auto-connect tab list

# 切换到现有标签页（如果找到）
agent-browser --auto-connect tab <index>

# 或打开新页面
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect wait --load networkidle

# 截取快照以查看交互元素
agent-browser --auto-connect snapshot -i

# 点击、填写等
agent-browser --auto-connect click @e3
agent-browser --auto-connect fill @e5 "some text"

2. 从页面提取数据

# 获取所有文本内容
agent-browser --auto-connect get text body

# 截取屏幕截图以进行视觉检查
agent-browser --auto-connect screenshot

# 执行 JavaScript 以获取结构化数据
agent-browser --auto-connect eval "JSON.stringify(document.querySelectorAll('table tr').length)"

3. 回放 Chrome DevTools 录制

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

4. 录制浏览器视口演示

对于仅浏览器的演示，最终视频应包含页面内容，但不包含 Chrome 地址栏、标签栏、自动化信息栏或桌面，请使用 Agent Browser 视口录制：

• 在正式录制前运行版本预检：

  python3 <skill-root>/scripts/check_browser_recording_versions.py
  

• 使用 --headed --profile <dedicated-profile> 并显式指定 --namespace 和 --session。
• 不要将用户日常使用的 Chrome 配置文件用于正式的账户、凭证或云控制台录制。
• 不要对账户、凭证或云控制台录制使用无头模式；仅将无头模式用于公共/本地验证。
• 将特定站点的剧本、演示脚本、后处理包装器和时间线约定保留在项目特定或私有技能中。

不要将此模式用于 Finder、系统下载对话框、桌面应用或浏览器 chrome 本身；请使用 Mac 屏幕录制技能来处理这些。

---

逐步交互指南

截取快照

使用 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>

如何区分输入类型

• 标准 input/textarea → 使用 fill
• Contenteditable div / 富文本编辑器（LinkedIn 消息框、Gmail 撰写、Slack、CMS 编辑器）→ 先点击/聚焦，然后使用 keyboard inserttext

引用生命周期

引用（@e1、@e2、...）在页面更改时失效。在以下情况后务必重新截取快照：

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

验证

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

agent-browser --auto-connect snapshot -i   # 检查交互状态
agent-browser --auto-connect screenshot     # 视觉验证

---

回放录制

接受的格式

1. JSON（推荐）——结构化，可以逐步读取：

   # 统计步骤数
   jq '.steps | length' recording.json
   
   # 读取前 5 步
   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"	清空并填写标准 input/textarea
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”），不要尝试在单个对话中完成所有平台。相反，启动顺序子代理/工作进程，每个平台一个。选择此技能即明确允许为此多平台工作流使用子代理/工作进程。

为什么使用子代理

每个平台操作消耗约 25-40K 令牌（参考文件 + 快照 + 交互）。在一个上下文中运行 3-5 个平台可能会触及上下文限制并降低后期平台的准确性。每个子代理/工作进程获得自己全新的上下文窗口。

如何执行

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

子代理的提示模板

您正在 [PLATFORM] 上自动化浏览器任务。

首先，阅读以下文件以获取上下文：
- /absolute/path/to/skills/chrome-automation/references/[platform].md
- 已安装的 agent-browser 技能文件（如果可用）（agent-browser 命令参考）

然后使用 `agent-browser --auto-connect` 连接到用户的 Chrome 浏览器，并执行以下任务：

[任务描述]

要发布的内容：
[内容]

重要提示：
- 始终先列出标签页（`tab list`）并复用现有的已登录标签页
- 每次导航或操作后重新截取快照
- 在提交/发布前与用户确认（破坏性操作）
- 如果需要登录或出现 CAPTCHA，请停止并解释

何时不使用子代理

• 单一平台——直接在当前对话中执行即可。
• 只读任务（浏览、搜索、提取数据）——上下文使用较轻；单个对话可以处理 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。