| name | browser-cdp |
| description | 打开/浏览/操作网页前，先跑 ensure_cdp.sh 确保本地 9222 调试 Chrome 就绪，然后用 browser_navigate / browser_snapshot / browser_click 操作（不要用 browser_cdp）。解决『无法为浏览器引擎建立稳定前台会话 / connection issue』这类 CDP 未连报错。 |
| metadata | {"openclaw":{"emoji":"🌐","os":["darwin"],"requires":{"bins":["curl"]}},"allowed-tools":["exec"]} |
Browser CDP 自检自启（浏览器调试通道）
浏览器操作需要一个本地 Chrome 实例在 127.0.0.1:9222 上开着调试端口。Chrome 一关端口就没了，
随后操作会报「无法为浏览器引擎建立稳定的前台会话 / connection issue / connection refused」。
两条铁律：
- 任何浏览器操作【之前】，先跑
ensure_cdp.sh，退出码 0（CDP_READY）才继续。
- 就绪后用
browser_navigate / browser_snapshot / browser_click 操作，绝不要用 browser_cdp。
0. 用哪个工具（关键，之前一直踩这里）
- ✅
browser_navigate（打开网页）、browser_snapshot（读页面）、browser_click / browser_type（交互）
—— 这些是无条件注册的标准浏览器工具，会自动连 9222。这才是正路。
- ❌
browser_cdp —— 它只有在网关启动那刻 9222 已活着才注册；否则会被系统静默改写成
browser_type，表现为"看似导航实则空转、反复 connection issue"。别调它。 想低层 CDP 也先走
browser_navigate，除非主人明确要求裸 CDP。
绝对禁止（这些正是之前 Chrome 反复被杀、连不上的元凶）：
- ❌
pkill "Google Chrome" / pkill -9 "Google Chrome" —— 会连主人的日常 Chrome 一起杀。
只允许精确杀调试实例：pkill -f -- "--remote-debugging-port=9222"。
- ❌ 用
nohup '…Chrome' … & 或任何 … & 从 shell 起 Chrome —— exec 一返回进程被回收，Chrome 秒死。
启动一律交给 ensure_cdp.sh（内部用 open -na 脱离 shell 才持久）。
- ❌ 自带的
chrome-cdp skill 里教的 … & 启动和 pkill -9 "Google Chrome" —— 不要照做，以本 skill 为准。
0.5 动态页交互铁律：ref 用完就废 + 提交用 browser_press_key（B站实测）
在 B站首页这类动态页反复失败的真根因有两条（CDP 亲验，别再误判为"页面结构诡异"）：
① ref 会过期——这是头号杀手。 browser_snapshot 给的 @e63 这类 ref，只对那一刻的
快照有效。B站首页搜索框 placeholder 是滚动热搜词（"AG超玩会官方账号"→"救了一万次的你"…几秒一换），
每换一次 a11y 树就重建、旧 ref 立即作废。Jarvis 之前正是上一轮 snapshot、隔轮才 browser_type，
撞上 Unknown ref: e63 而失败。
→ 铁律：browser_snapshot 与紧随的 browser_type/browser_click 必须在同一轮、连续调用，
用最新快照里的 ref；绝不复用上一轮的 ref。 一旦报 Unknown ref / not found in snapshot，
不要重试同一个 ref，先重新 browser_snapshot 拿新 ref。
② 工具只认 ref，不认 CSS 选择器/坐标。 browser_click(ref)、browser_type(ref, text) 的
参数是快照里的 ref（如 @e5），传 .nav-search-btn 这种 CSS 选择器必然 not found in snapshot
（而且 B站那个搜索按钮是无 role 的 <div>，本就不进快照）。提交搜索用 browser_press_key("Enter")
——实测可信 Enter 能正常提交（早前"Enter 没反应"是脏状态/非可信合成事件导致的误判，已排除）。
可靠动作序列（搜索类页面通用）：
browser_navigate <url>（导航返回的快照即最新，可直接用其 ref，无需再 snapshot）；browser_type(<搜索框最新ref>, "关键词")（会先清空再输入，走可信输入，Vue v-model 同步正常）；browser_press_key("Enter") 提交（不要去点 .nav-search-btn，那是 CSS 选择器点不了）；- 结果常在新标签页打开（如
search.bilibili.com/all?keyword=…）：别只看原页 URL 没变就判"失败"，
browser_snapshot 刷新 / 切到新标签确认。
经验法则：① 每个 ref 当"一次性用品"，snapshot 完立刻用、隔轮作废；② 提交用 browser_press_key，
不要臆想点某个 CSS 选择器；③ 动作后先确认是否弹了新标签，再判成败。
1. 每次必跑：确保 CDP 就绪
bash "$HOME/.openclaw/workspace/voice-assistant/assistant-x-openclaw/skills/browser-cdp/ensure_cdp.sh"
（脚本就在本技能目录下，路径不确定时用 find ~ -name ensure_cdp.sh -path '*browser-cdp*' 定位。）
脚本行为（幂等、可反复调）：
- 检查
127.0.0.1:9222 是否已有可用调试 Chrome（校验 webSocketDebuggerUrl，不是只看端口通）。
- 已就绪 → 立即返回
CDP_READY，不重复启动。
- 未就绪 → 用
open -na 拉起一个独立调试 Chrome（--user-data-dir=$HOME/.hermes/chrome-debug），
然后阻塞轮询到真就绪再返回。
- 退出码：
0=就绪可用；非 0=启动失败（打印 CDP_FAILED）。
判定： 看到 CDP_READY / 退出码 0 → 继续浏览器操作；否则中止，走第 3 节排查，别硬闯。
为什么必须脚本 + open -na：从 exec 的 shell 里 nohup '…Chrome' … & 起的进程是该 shell 的子进程，
exec 一返回进程组被回收，Chrome 立刻死 → 随后连 9222 必然 connection refused。
open -na 把进程交给 macOS launchservices，脱离 shell，才能持续存活。这是之前反复失败的真根因。
2. 前提（已就绪，通常无需管）
jarvis profile 的 ~/.hermes/profiles/jarvis/config.yaml 里 cdp_url: http://127.0.0.1:9222
已配好——这是每个 profile 独立的配置。不要去动 hermes 默认的 ~/.hermes/config.yaml。
若哪天发现 profile 的 cdp_url 变空，向主人说明、经其确认后再改 profile 配置并重启网关，别擅自动。
3. 排查兜底（脚本返回 CDP_FAILED 时）
curl -s http://127.0.0.1:9222/json/version 看返回；无响应=Chrome 没起来。lsof -nP -iTCP:9222 -sTCP:LISTEN 看端口是否被占/监听。- 有僵死实例占坑：
pkill -f -- "--remote-debugging-port=9222" 清掉，再跑一次 ensure_cdp.sh
（只杀调试实例，不动日常 Chrome）。
- 数据目录被锁（profile in use）：已有一个同目录 Chrome 在跑；先跑脚本确认它是否已在 9222 服务，
是就直接用，别再起第二个。
4. 安全规则（强制）
- 只操作专用调试实例（
--user-data-dir=$HOME/.hermes/chrome-debug），绝不拿主人日常
Chrome 的默认 profile 开调试端口。
- 不自行重启 hermes 网关、不自行改
config.yaml——这些先报主人、经批准再动。
- 与 jarvis
TOOLS.md 的「敏感操作规则」一致：破坏性/不可逆动作先确认。
