📦 Opencli BrowserUse

该 CLI 的第一读者是 agent，而非人类。每条子命令都会返回一个结构化信封，精确告知匹配了什么、置信度如何、未匹配时该怎么做。依赖这些信封——不要猜测。 本技能用于驱动实时浏览器完成 agent 任务。若要在 ~/.opencli/clis// 下构建可复用适配器，请改用 opencli-adapter-author。

---

前置条件

• opencli browser 命令已在调用间保持自动化会话。窗口持续开启，直到执行 opencli browser close 或空闲超时。
• --focus（或 OPENCLI_WINDOW_FOCUSED=1）将自动化窗口置于前台，用于实时观察页面。
• --live（或 OPENCLI_LIVE=1）主要用于浏览器支持的适配器命令，如 opencli xiaohongshu note ...。命令返回后仍保持适配器自动化窗口开启，便于检查最终页面状态。

---

心智模型

• Selector-first 目标协议。 每条交互命令（click、type、select、get text/value/attributes）均接受一个 ，它要么是 state/find 返回的数字引用，要么是 CSS 选择器。用 --nth 消除多个 CSS 匹配的歧义。
• 每个信封都会报告 matches_n 与 match_level。 match_level 为 exact、stable 或 reidentified——CLI 已替你应对轻度 DOM 漂移，但等级告诉你该有多自信。
• 先紧凑输出，按需再取完整载荷。 state 是预算友好的快照；get html --as json 支持 --depth/--children-max/--text-max；network 返回形状预览，用 --detail 重新获取单条 body。若直接吐出巨型载荷，你在浪费本不必浪费的上下文。
• 结构化错误可被机器读取。 失败时 CLI 输出 {error: {code, message, hint?, candidates?}}。按 code 分支，而非字符串匹配。

---

关键规则

• 行动前先 inspect。 先跑 state 或 find。绝不要跨会话硬记引用或选择器——索引仅对应当前快照。
• 一旦拥有数字引用，优先用它。 数字引用能轻度抵御 DOM 漂移，因为 CLI 会给每个标记元素打指纹。手写的 CSS 选择器在站点重渲染时立刻失效。
• 每次写入后读 match_level。 exact = 一切正常；stable = 元素相同但部分软属性漂移——操作仍生效；reidentified = 原引用已消失，CLI 找到唯一替代；请再次确认击中了正确元素。
• 表单控件用 compound 字段。 不要正则猜日期格式，也不要 state 两次去抓完整 选项列表。compound 信封内含格式字符串、最多 50 条完整选项、options_total 用于溢出，以及 的 accept/multiple。
• 关键写入要验证。 type 后跑 get value ；select 后跑 get value。自动完成、React 受控输入、掩码字段都会悄悄吞字，CLI 无法替你检测。
• 页面变化后遵循 state → 动作 → state。 导航、表单提交、SPA 路由切换都会使引用失效，拍新快照，不要复用过渡前的引用。
• 用 && 链式调用。 链式序列在同一 shell 内运行，第一条命令获取的引用第二条仍可用；分多次 shell 调用会丢失刚建好的会话上下文。
• eval 只读。 把 JS 包在 IIFE 里并返回 JSON。若要改动*页面，请用结构化 click / type / select / keys 命令——它们产出结构化输出与指纹，eval 不会。
• 优先 network 而非屏幕抓取。 若目标页面通过 JSON API 获取数据，该 API 几乎总比渲染后的 DOM 可靠。先捕获一次，查看形状，再用 --detail 取所需 body。

---

目标协议（click / type / select / get text|value|attributes 的 ）