learnaihubc/browseroperator/browser-operator

Browser Operator

Use this skill for all browser clicks and automation. Use the bundled CLI instead of writing separate Playwright/CDP scripts; do not use el.click() or DOM events as the default. The CLI manages a persistent Chrome profile and a local background process (daemon). Login state can be reused across commands and sessions while the cookies and server-side session remain valid.

页面标注与配置

• ~/.dsh/browser-operator/config.json 中的 annotationEnabled 布尔值决定是否显示标注按钮。设置了 BROWSER_OPERATOR_HOME 时，读取该目录下的 config.json。没有配置时默认开启，所有 Profile 共用这个设置。
• 开启后，打开、刷新或跳转页面时，右下角都会显示标注按钮。用户点击后，按钮变为“请选择”，此时可以拖出矩形框；记录标注后，按钮变为“清空标注”。
• 用户明确说“关闭标注”时，执行 annotate cancel --profile <profile>，将配置保存为 annotationEnabled: false，并移除当前浏览器各标签页的标注。以后打开页面或重启浏览器，都不再显示标注入口。
• 用户明确说“开启标注”或“需要标注”时，执行 annotate start --profile <profile>，将配置保存为 annotationEnabled: true，恢复标注入口。平时打开页面或结束任务时，不要反复执行 start/cancel，以免覆盖用户的设置。
• 点击框右上角的 × 只删除该框；“清空标注”会清空所有框并退出绘制，按钮仍保留，配置也不变。按 Esc 可以退出本次绘制。
• 用户要求查看框选内容时，执行 annotate read --profile <profile>，直接读取 DOM 元素、文字、唯一 CSS 选择器、元素边界 rect 和中心点 center，不需要截图。坐标以页面可见区域为基准，单位是 CSS 像素，返回值为 coordinateSpace: viewport。

登录与验证

默认由用户在可见的浏览器窗口中完成登录和验证。用户没有明确要求代登录时，遵守以下规则：

• 不输入用户名、密码、手机号、OTP 或其他凭据。
• 不点击“登录”“注册”“登录/注册”“发送验证码”“扫码登录”、Sign in、Log in、Continue with ... 等入口，也不提交登录表单。
• 不操作或重试滑块、CAPTCHA、“访问验证”“滑动验证”“人机验证”。
• Agent 负责打开页面，报告 login.likely、challenge.likely 和 manualAuth 的结果，按需切到可见窗口模式（headed），再用 wait-login 或 wait-verification 等待。
• manualAuth.required 为 true 时，click / drag / eval / fill / press / select 默认返回 manual-auth-required。此时可以用 snapshot、query、console、network、screenshot、debug 查看页面，请用户在可见窗口中完成登录或验证。

只有用户在当前对话中明确说“你帮我输入账号密码登录”“用这组账号登进去”“帮我点登录”等指令时，Agent 才能代为登录：

• 对登录页执行 fill / click / press 时，必须加 --allow-auth：

``bash "$BROWSER" fill "#username" "<用户提供的账号>" --allow-auth --profile mysite "$BROWSER" fill "#password" "<用户提供的密码>" --allow-auth --profile mysite "$BROWSER" click "#btnLoginNow" --allow-auth --profile mysite --wait-nav ``

• 只使用用户在对话中提供的凭据，不从文件、历史记录或其他站点查找、猜测或复用。
• 不把凭据写进经验文件、日志、截图说明或最终答复；只说明登录是否成功。
• --allow-auth 仅对 manualAuth.kind === "login" 生效。滑块或 CAPTCHA（kind: "verification"）仍会被拦截，必须由用户完成。
• “打开看看”“试试看”不代表授权代登录，仍按默认方式处理。

任何情况下，都不能用 --js、--force、直接调用 DOM 或其他脚本绕过登录和验证拦截。

站点经验：任务前读取，探索成功后更新

每次探索成功后，都要保存入口、选择器和操作方法，让下一个会话能继续使用。

固定位置：~/.dsh/browser-operator/experiences/<canonical-domain>.md （例如 www.baidu.com → baidu.com.md；子域名保留，只去掉开头的 www.）

每次任务开始前：

"$BROWSER" experience show <domain-or-url>

• found:true：先按 content 里的“快速路径”“选择器”和“陷阱”操作，不要从头探索。
• found:false：先检查返回的 related。如果有同一应用或相似域名在其他环境（dev/sit/uat/prod）的经验，先读最接近的那份。可以参考页面结构，但 URL、账号、机构代号、数据对象 OID 等必须按当前环境重新确认。没有相关经验时，再从头探索。
• related 中的 match 说明匹配原因：app 表示同一应用，alias 表示域名别名，normalized-domain 表示去掉 dev/sit/uat/prod 等环境词后域名相同。
• 如果 open 后发生重定向，例如 127.0.0.1 → localhost、http → https、裸域 → www，用 experience current 按最终 state.url 中的主机名再查一次。localhost 和 127.0.0.1 建议都查。
• 经验过期或页面改版：更新文件，并用 log add 记录变化。

探索成功后，必须用文件写入工具保存或更新经验，不能只留在对话中：

• 先读模板：references/experience-template.md
• 写入固定路径：~/.dsh/browser-operator/experiences/<domain>.md
• 必须包含 YAML frontmatter：site、domain、updated、confidence
• 同一应用有多个环境或域名时，建议加 app、environment、aliases：
• app：各环境共用的应用标识，如 my-admin，不要带环境名
• environment：local|dev|sit|test|stage|uat|prod|other
• aliases：同应用的其他域名（含 127.0.0.1 这类别名）
• 必须包含章节：## 快速路径、## 选择器、## 结果读取、## 陷阱、## 空页面/异常兜底、## 验证记录
• 写清下一个会话需要的信息：入口 URL 模板、搜索框和按钮的选择器、结果条目选择器、第 N 个结果的点击规则、详情读取方式，以及广告、懒加载、新标签页等需要注意的情况。
• 只记录站点结构和选择器，不写 Cookie、token、密码、手机号或完整个人数据。
• 写完用 "$BROWSER" experience validate <domain> 校验格式。
• 查询同应用其他环境："$BROWSER" experience related <domain>；experience show / experience current 也会返回 related 列表。

给最终答复前，必须完成以下检查：

1. 再执行一次 "$BROWSER" experience show <domain>；如果本次页面发生过重定向，用 "$BROWSER" experience current 以最终 host 复查。
2. 对照本次操作，检查入口 URL、选择器、结果读取方式、失败后的处理方法和注意事项是否有变化。
3. 有新增/变化：更新经验文件，再执行 experience validate <domain>。
4. 无论经验有没有变化，都要记录本次运行："$BROWSER" log add <domain> "<任务>" --result ok|failed|partial --note "<结果/备注>"。按实际结果填写 --result；任务成功且没有新发现时，记 ok，备注写“无新增”。

验证标准：新会话不依赖旧对话，只读经验文件，就能用少量命令完成同类任务。验证结果也要写入日志。

验证日志

每个域名的验证记录单独存放，不追加到经验文件中：

• 位置：~/.dsh/browser-operator/logs/<canonical-domain>/log.md
• 固定格式（一行一次，只追加、不改历史行）：

- YYYY-MM-DD HH:mm | 任务 | 结果(ok|failed|partial) | 备注

• 追加："$BROWSER" log add <domain> "<任务>" --result ok|failed|partial --note "<备注>"
• 查看："$BROWSER" log show <domain> [--limit N]；全部域名："$BROWSER" log list
• 经验文件的 ## 验证记录 只保留日志路径。迁移旧经验时，先把原表格或条目原样保存到日志的 ## 历史记录（经验迁移 …） 下，再将经验中的旧记录替换为日志路径。CLI 不会自动迁移历史内容。
• 使用 log add 生成记录，不要手工改格式；log show 只能解析上述格式。

操作脚本（recipe）

经验文件说明站点结构和操作方法，脚本保存可以重复执行的步骤。同一域名、同一任务已成功执行 2 次（次数: 2），第 3 次仍成功时，把步骤写成脚本。以后优先用 recipe run 执行，失败后由 Agent 在当前页面继续操作并修正脚本。

固定位置：~/.dsh/browser-operator/脚本/<canonical-domain>.md（与 experiences/ 同层级；去掉开头 www.，子域名保留）

每个域名保存一份 Markdown。文件开头的 YAML 信息（frontmatter）与经验文件一致，包含 site、domain、app、environment、updated，可选 profile。每个任务用一个 ## 小节：

## 搜索并读取结果
- 次数: 3
- 参数: query=搜索词
- 最近: 2026-11-05
 

open https://example.com/ --profile example fill "#kw" "{{query}}" click "#su" --wait-nav wait "#content_left" query "#content_left"

规则：

• steps 每行一个 browser 子命令（不写 browser 前缀），支持 open/goto/state/fill/click/press/select/hover/wait/query/snapshot/screenshot/switch/close/mode/focus/console/network/debug/eval/drag 等；stop/status/recipe/experience/profiles 不允许。
• 动态内容用 {{name}} 占位，在 - 参数: 行用 name=说明 声明，运行时通过 --var name=value 传入。不要把真实账号、密码、token、OTP、证件号写进文件或参数说明。
• 不在 steps 中保存 --allow-auth。只有用户在当前对话明确要求代登录时，才在 recipe run 命令上加这个参数；脚本文件不保存授权。滑块和 CAPTCHA 仍由用户完成。
• --profile 可以写在第一个 open 步骤或 frontmatter 中，recipe run 会将它传给后续步骤；单个步骤也可以指定其他 Profile。
• 点击成功后，用 wait 或 --wait-nav 等待页面变化，再用 query 或 snapshot 读取结果。除非用户明确要求，否则避免使用 --js。

流程：

1. 任务开始时，先执行 "$BROWSER" recipe show <domain> "<任务>"。返回 recorded:true 时，直接用 "$BROWSER" recipe run <domain> "<任务>" --var name=value 执行。
2. 没有脚本时，照常操作页面。如果文件或任务小节不存在，先按 references/recipe-template.md 创建；还没有验证过的步骤时，删除模板中的示例 steps。
3. recipe run 返回 ok:false 时，查看 failedStep、该步的 error 和 screenshot。使用同一 Profile 在当前页面继续完成任务，不要重新打开页面。成功后修正选择器、等待条件或参数，再执行一次脚本验证；连续两次失败时，删除 steps 或只保留文字说明。
4. 本次任务成功后，只执行一次 "$BROWSER" recipe log <domain> "<任务>" 来累计次数。返回 count>=3 且尚无 steps 时，把验证过的步骤写入 steps 代码块，再用 recipe run 验证。
5. 结束时，用 log add 记录实际结果，并说明脚本是否可用、是否修正。recipe run 不会自动累计次数、追加验证日志，也不会生成或修正脚本，这些都由 Agent 完成。

查看全部："$BROWSER" recipe list [domain-filter]；只看次数和参数：recipe show <domain>。recipe run --dry-run 只校验参数与命令，不执行。

Quick start

The currently locked Playwright dependency requires Node.js 20 or later. You also need npm and Chrome. The bin/browser launcher uses Bash, including on Windows. Without Bash, run node <skill-directory>/scripts/browser.mjs ... directly. The examples use the default installation path; adjust it if you installed with --dest or a custom DSH_HOME.

BROWSER="$HOME/.dsh/skills/browser-operator/bin/browser"
 
# 1. Install dependencies if the installer has not already done so
npm install --prefix "$HOME/.dsh/skills/browser-operator/scripts"
 
# 2. Read the saved experience first (if any)
"$BROWSER" experience show example.com
 
# 3. Open a site with a named profile (headless by default; add --headed to watch)
"$BROWSER" open "https://example.com" --profile mysite
 
# 4. If login/challenge is detected, `open` auto-switches to headed.
#    If you need to do it explicitly:
"$BROWSER" mode headed --profile mysite
#    Bring the window forward when the user needs to log in:
"$BROWSER" focus --profile mysite
#    Ask the user to complete login/verification, then wait:
"$BROWSER" wait-login --profile mysite --timeout 300000
#    Stay headed after login unless restore-session was enabled before login.
#    With restore-session on, you may switch back using mode headless.
 
# 5. See what is clickable (returns selectors you can copy)
"$BROWSER" snapshot --mode interactive --profile mysite
 
# 6. Read the heading on example.com; use snapshot selectors for business actions
"$BROWSER" query "h1" --profile mysite
 
# 7. Close the browser when done; the profile keeps login state
"$BROWSER" stop --profile mysite

Chrome runs without a visible window (headless) by default. Add --headed to open, or use mode headed, when a visible window is needed. Detecting login or verification switches it to headed unless --no-auto-headed is set. To return to headless, follow the session-cookie guidance below.

Window focus on macOS. Before launching visible Chrome, the daemon records which app is in front and tries to return focus to it afterward. Navigation and clicks in headed mode skip page.bringToFront(), so the browser may stay behind other apps:

• When the user needs to log in or verify, tell them “Chrome 已在后台打开，请切换过去”, or run browser focus --profile <name> to bring it forward.
• wait-login and wait-verification only check the page repeatedly; they do not bring the window forward.
• If the user asks to watch, run focus once so they see it.

Changing mode closes and relaunches Chrome. Plain open and goto keep the current mode unless you pass --headed or --headless, or login or verification triggers a visible window. --no-auto-headed disables the automatic switch for that navigation. Restarting loses session cookies, such as Tomcat JSESSIONID, unless the profile has restore-session on (see below).

Login persistence

open target site (headless) → reuse existing profile
  → if login/verification is needed: mode headed (or auto-escalated by open)
  → user logs in / solves verification in the visible Chrome
  → wait-login / wait-verification
  → stay headed, or mode headless if restore-session was enabled before login
  → snapshot → click → verify
  → stop (cookies + localStorage stay in the profile)

• Profiles live under ~/.dsh/browser-operator/profiles/<name>/chrome-profile.
• Use one stable profile per site, e.g. --profile wechat, --profile xiaohongshu, --profile company-sso.
• Opening the same profile again reuses its cookies and local storage. Ask the user to log in again only if the page shows a login screen.
• Chrome does not reload session cookies without an Expires attribute, such as Tomcat JSESSIONID, after a restart by default. Run restore-session on --profile <name> to use --restore-last-session on the next launch. This lets a mode switch or daemon restart retain the login while the server-side session remains valid. The setting is saved per profile and stops the daemon once, taking effect on the next open. Duplicate restored tabs are closed automatically.
• wait-login polls until login.likely becomes false (no visible password input / login URL / "登录超时" text), up to the timeout.
• state and snapshot include login.likely, login.reasons, and challenge.likely. If challenge.likely is true (slider/CAPTCHA), ask the user to complete it in the visible Chrome, then run wait-verification.
• The browser stays open between CLI commands, so sessionStorage, tabs, and popups survive while the daemon is running.
• Never read, print, copy, or upload chrome-profile/, cookies, daemon.json, or the daemon token. Do not ask the user to paste a password into chat; let them type it in the visible browser. Only use credentials the user volunteers with an explicit instruction to log in, and never echo them back.

Browser fingerprint (fixed per profile)

Each profile gets a fingerprint on first launch, stored under fingerprint in ~/.dsh/browser-operator/profiles/<name>/settings.json. It stays the same across pages, reloads, mode switches, and daemon restarts.