浏览器自动化

CDP Chrome 自动化 — 快照、点击、导航、截图、标签页。通过基于 ref 的元素定位，使用 cli-jaw browser 命令控制 Chrome。

快速参考

前置条件

• cli-jaw serve 必须正在运行 — 浏览器技能通过 cli-jaw 服务器进行通信。
• 必须安装 Google Chrome。
• 必须在 cli-jaw 项目中安装 playwright-core（用于 CDP 通信）。
• 可选： brew install cliclick，用于基于坐标的鼠标操作。

核心工作流

所有浏览器自动化遵循相同的循环：先获取快照以查看可交互元素，然后通过 ref ID 执行操作，再获取快照以验证结果。

在导航、刷新、切换标签页或任何导致页面内容发生重大变化的操作后，请使用新的快照。Ref ID 属于最近一次可用的快照，可能会过时。

快速开始

# 启动自动化会话（无头模式，无可见窗口）
cli-jaw browser start --agent

# 启动交互式浏览器（手动模式，可见窗口）
cli-jaw browser start

# 导航到 URL
cli-jaw browser navigate "https://example.com"

# 获取交互式快照（显示 ref ID）
cli-jaw browser snapshot --interactive

# 点击一个 ref
cli-jaw browser click e3

# 输入文本并提交
cli-jaw browser type e5 "hello" --submit

# 截图
cli-jaw browser screenshot

快照输出

snapshot --interactive 命令返回页面上可交互元素的紧凑列表，每个元素都有一个短的 ref ID，供后续命令使用。

像 e3 这样的 ref ID 是短期有效的，作用域仅限于最近一次快照。页面变化后请务必重新获取快照。

命令参考

支持标签

规则和约束

• Ref ID 是临时的。它们的作用域仅限于最近一次快照。在导航、刷新、切换标签页或任何页面变化后，请务必重新运行 snapshot --interactive。
• 快照优先使用 --interactive 以节省 token 预算 — 完整快照包含非交互节点，数据量可能很大。
• 自动化会话请使用 --agent。它以无头模式启动，避免弹出可见浏览器窗口。
• 切勿关闭通过 ps 找到的 Chrome 进程。只能使用 cleanup-runtimes --close --force，它会通过持久运行时记录验证 jaw 拥有的进程。
• 执行 reset 前请先询问。reset 命令会清除浏览器配置文件和截图。仅在用户明确请求时使用。
• evaluate 仅用于诊断。请勿在更高级别的工作流中通过 evaluate 传递任意用户提供的 JavaScript。
• 非 DOM 元素（Canvas、WebGL、跨域 iframe、自定义 UI）应在确认没有可用 ref 后，才回退到 vision-click 技能。

常见工作流

网页搜索

cli-jaw browser start --agent
cli-jaw browser navigate "https://www.google.com"
cli-jaw browser snapshot --interactive
cli-jaw browser type e3 "search query" --submit
cli-jaw browser snapshot --interactive
cli-jaw browser click e7

表单填写

cli-jaw browser snapshot --interactive
cli-jaw browser type e1 "John Doe"
cli-jaw browser type e2 "john@example.com"
cli-jaw browser click e3           # 提交按钮
cli-jaw browser snapshot           # 验证提交结果

读取页面内容

cli-jaw browser navigate "https://news.ycombinator.com"
cli-jaw browser text               # 纯文本提取
cli-jaw browser text --format html # HTML 内容
cli-jaw browser snapshot --interactive

AI 网页工作流

对于 ChatGPT 或其他 web-ai 工作流，请使用 web-ai 技能。浏览器技能负责底层页面控制；web-ai 负责结构化问题渲染、活动标签页安全性和响应基线处理。

~해줌 示例

触发浏览器技能的自然语言请求。支持韩语和英语。

无头模式

三种运行 Chrome 无头模式的方式：

# 推荐用于自动化
cli-jaw browser start --agent

# 手动模式显式指定无头
cli-jaw browser start --headless

# 通过环境变量
CHROME_HEADLESS=1 cli-jaw browser start

所有代理自动化请使用 --agent。它避免弹出可见浏览器窗口，是自动化会话的预期默认值。

环境变量

默认 CDP 端口从 cli-jaw 服务器端口派生。仅在需要显式覆盖时使用 cli-jaw browser start --port <port>。

独立 agbrowse 替代方案

当你明确需要驱动单个 Chrome 实例（例如，保持一个已登录的配置文件打开，避免同时运行 cli-jaw serve 和第二个 CDP 会话）时，相同的浏览器命令可通过独立的 agbrowse CLI（npm install -g agbrowse）使用。命令参数完全相同；仅二进制前缀不同。

运行时清理

# 诊断运行时状态
cli-jaw browser doctor --json

# 试运行：查看将被清理的内容
cli-jaw browser cleanup-runtimes

# 实际关闭 jaw 拥有的孤儿运行时
cli-jaw browser cleanup-runtimes --close --force

cleanup-runtimes 设计上是保守的。它仅作用于 jaw 拥有的 Chrome 启动时写入的持久 browser-runtime-owner.json 记录。进程命令行必须仍然匹配记录的 PID、CDP 端口和配置文件。包含 --type= 的 Chrome 辅助进程会被拒绝。切勿将通用 ps 输出作为 Chrome 进程可安全关闭的依据。

恢复策略

出现问题时，请先停下来检查状态，再执行下一步操作。

故障排除

计划中的运行时差异

以下命令是来自 30_browser 参考设计的计划对等目标。除非在后续 PRD 中明确升级，否则它们在当前运行时中不可用。

计划中的观察和诊断命令

cli-jaw browser console --clear --reload --duration 3000
cli-jaw browser network --reload --duration 1000
cli-jaw browser wait 2000

计划中的操作命令

cli-jaw browser resize 0 0 --fullscreen
cli-jaw browser scroll down
cli-jaw browser scroll up --amount 1000

相关技能

注意事项

• Ref ID 是短期有效的，应视为仅限最近一次快照的作用域。
• 在导航或重大页面变化后，请务必重新运行 snapshot --interactive。
• 优先使用 --interactive 以节省 token 预算。
• 截图保存至 ~/.cli-jaw/screenshots/。
• start --agent 应作为代理自动化的默认选择。
• Canvas、WebGL、跨域 iframe 和自定义 UI 等非 DOM 元素，应仅在作为显式回退时使用 vision-click 技能。