--- name: netabrowser-cli description: > Neta 反风控+拟人化浏览器自动化 CLI。养号、电商自动化、AI 探索复杂网页时使用。 比 playwright-cli 更难被反风控识别（fingerprint-chromium 内核 + patchright 反自动化 + 贝塞尔曲线鼠标轨迹）。100 账号矩阵养号场景首选。所有操作通过 scripts/nb.sh （或 nb.cmd）调用，不需要 HTTP/curl。 license: MIT metadata: version: "2.0" category: browser-automation --- # netabrowser-cli 通过 CLI wrapper 操作常驻浏览器 daemon。daemon 持有 chromium 实例 + 登录态 + session profile，CLI 是连 daemon 的薄客户端。AI 全程只用 `scripts/nb.sh `， **永远不用 curl 或 HTTP**。 ## 快速验证环境 每次开始任务前先验证 daemon 是否启动： ```bash bash scripts/nb.sh list ``` 期望返回 `{ok: true, ...}` 或会话列表。如果连接失败 → backend 没启动，告知用户。 ### Chromium 自动下载 `nb.sh` / `nb.cmd` 每次启动都会先跑 `scripts/ensure-chromium.cjs`： - `packages/netabrowser-cli/chromium/win64/chrome.exe` 已存在 → 秒过。 - 缺失 → 自动从默认 URL 下载 zip（约 170MiB），解压到 `packages/netabrowser-cli/chromium/win64/`，归一化为 397MB 的 Chromium 产物。 - 覆盖： - `NETA_CHROMIUM_PATH` 指定已有 `chrome.exe` 绝对路径 → 直接复用，**不会自动下载到别处**（缺失时会报错提醒，避免误下）。 - `NETA_CHROMIUM_URL` 指定自定义 zip 下载地址（内网镜像/CDN）。 - 解压：Windows 走 PowerShell `Expand-Archive`，Linux/macOS 走 `unzip`（失败回落 `tar`）。 第一次执行任何 `nb` 命令时会看到 `[ensure-chromium] downloading ...` 日志，耐心等完即可。 --- ## When to use vs playwright-cli vs patchwright-cli | Skill | 适用场景 | |---|---| | **netabrowser-cli**（本）| 国内反风控严的站（小红书/抖音/淘宝/拼多多/微博）+ 多账号矩阵 + 养号 | | **patchwright-cli** | 国外 Cloudflare/DataDome 等反爬保护 | | **playwright-cli** | 测试、无反风控的站 | **目标是中国电商/社交站点 → 用本 skill。** --- ## 拟人化 vs 效率的选择规则 **用户明确要求"拟人化"/"移动鼠标"/"模拟人工操作"时**：必须用 `snapshot → click/hover` 操作页面元素，不要用 `goto` 直跳 URL。拟人化的价值在于让反风控系统看到真实的鼠标轨迹和点击行为。 **用户只要求"查看/获取信息"没提拟人化时**：优先用 `goto` 直跳目标 URL，更快更稳定。 **典型拟人化流程**（用户要求拟人操作时）： ```bash bash scripts/nb.sh open https://www.taobao.com --session=tb-main --headed bash scripts/nb.sh snapshot --session=tb-main # 找到"已买到"的 ref bash scripts/nb.sh hover e123 --session=tb-main # 拟人化 hover 触发下拉 bash scripts/nb.sh wait --session=tb-main --timeout=1000 bash scripts/nb.sh snapshot --session=tb-main # 重新 snapshot 找下拉项 bash scripts/nb.sh click e456 --session=tb-main # 拟人化点击 bash scripts/nb.sh wait --session=tb-main --load-state=networkidle bash scripts/nb.sh snapshot --session=tb-main # 读取结果 ``` **典型效率流程**（只要结果时）： ```bash bash scripts/nb.sh open https://www.taobao.com --session=tb-main --headed bash scripts/nb.sh goto https://buyertrade.taobao.com/trade/itemlist/list_bought_items.htm --session=tb-main bash scripts/nb.sh wait --session=tb-main --load-state=networkidle bash scripts/nb.sh snapshot --session=tb-main ``` --- ## 核心工作流 ``` nb.sh open → 启动会话（同名 session 自动恢复登录态） nb.sh snapshot → 拿 ARIA 树（YAML 格式，含 ref） nb.sh click/fill/hover [ref] → 拟人化操作 nb.sh wait → 等元素/页面状态 nb.sh close → 关闭（profile 持久化保留） ``` ### 最简任务模板 ```bash # 1. 打开（同名 session 复用 profile，登录态自动恢复） bash scripts/nb.sh open https://www.taobao.com --session=tb-main --headed # 2. 看页面结构（输出是 ARIA YAML，每个交互元素带 [ref=eN]） bash scripts/nb.sh snapshot --session=tb-main # 3. 操作（用 snapshot 中的 ref） bash scripts/nb.sh click e123 --session=tb-main bash scripts/nb.sh fill e45 "搜索关键词" --session=tb-main bash scripts/nb.sh press Enter --session=tb-main # 4. 等加载完 bash scripts/nb.sh wait --session=tb-main --load-state=networkidle # 5. 完事关闭（profile 留着下次复用） bash scripts/nb.sh close --session=tb-main ``` --- ## ⚠️ 关键陷阱（不读这段会浪费 token） ### 1. 同名 sessionName 自动复用登录态 profile 目录在 `.netabrowser-data/profiles//`，cookie/localStorage 在 close 后保留。**每个账号固定一个 sessionName**（如 `taobao-main`），下次 open 自动恢复登录。**不要每次换 sessionName**——会重新登录。 ### 2. 首页"立即登录"≠ 没登录 淘宝/拼多多/京东等 SPA 首页加载完后**异步**读 cookie 渲染用户名，snapshot 拍得太早会看到"立即登录"。**正确判断方式：** - snapshot 里有"已买到"/"我的淘宝"/"我的订单"等只有登录后才出现的链接 → 已登录 - 直接点"已买到"，看跳转到订单页还是登录页 → 实际验证 **不要看到"立即登录"就向用户要账号密码。** ### 3. 头部 hover 触发的链接（淘宝"已买到"等） 淘宝头部"已买到"是 hover 触发的下拉菜单项，单纯 click 不跳转。两种解法： ```bash # 方法 A：先 hover 触发下拉，再 click bash scripts/nb.sh hover e123 --session=tb-main # hover 父菜单 bash scripts/nb.sh wait --session=tb-main --timeout=1000 bash scripts/nb.sh snapshot --session=tb-main # 重新 snapshot 找下拉项 bash scripts/nb.sh click e456 --session=tb-main # 方法 B（更快）：直接 goto 目标 URL bash scripts/nb.sh goto https://buyertrade.taobao.com/trade/itemlist/list_bought_items.htm --session=tb-main ``` 常用直达 URL： - 淘宝已购：`https://buyertrade.taobao.com/trade/itemlist/list_bought_items.htm`（注意是 `buyertrade` 不是 `buyer.trade`） - 拼多多订单：`https://mobile.yangkeduo.com/orders.html` - 京东订单：`https://order.jd.com/center/list.action` ### 4. 何时停止重试（重要） 遇到以下错误**立即停止**，告知用户而不是反复重试： | 错误 | 含义 | 行动 | |---|---|---| | `net::ERR_NAME_NOT_RESOLVED` | DNS 失败 | 报告用户，可能是网络/代理问题 | | `net::ERR_TIMED_OUT` 连续 2 次 | 站点不可达 | 报告用户 | | `Ref 'eN' has no bounding box` 同 ref 2 次 | 元素消失或变化 | 重新 snapshot 找新 ref | | 进入 `chrome-error://` 错误页 | 浏览器内部错误 | 报告用户检查代理/网络 | **不要：** - 用不同 URL 瞎试 - snapshot 看到一样内容超过 2 次说明操作没生效，停下分析 - 看到 chrome-error 就反复 reload --- ## Commands ### 会话管理 - `open --session=NAME [--proxy=URL] [--fingerprint-seed=N] [--profile-dir=NAME] [--headed] [--priority=low|normal|high] [--queue]` 启动会话 - `close --session=NAME` 关闭（profile 保留供下次复用） - `list` 列出所有活跃会话 **代理必须在 open 时指定**，不能给已有 session 追加代理。如果需要换代理，先 close 再 open： ```bash bash scripts/nb.sh close --session=tb-main bash scripts/nb.sh open https://www.taobao.com --session=tb-main --headed --proxy=socks5://user:pass@host:port ``` **代理协议必须匹配**：SOCKS5 代理用 `socks5://`，HTTP 代理用 `http://`。写错协议会 400/超时。 **⚠️ 走代理 + headed 时必须延长 bash 工具 timeout**：默认 bash timeout 是 30s，但走代理首次打开浏览器需要 30-60s。**调用 bash 工具时务必传 `timeout: 60000`（毫秒）**——这是 bash 工具的参数（不是 nb.sh 的 --timeout）： ``` // AI 调 bash 工具时这样传： { "command": "bash scripts/nb.sh open ... --proxy=socks5://...", "timeout": 60000 } ``` 不传 timeout 默认 30s 会被 NetaClaw kill 掉，导致 ECONNRESET。 ### 检查 - `snapshot --session=NAME` 获取页面 ARIA 树（YAML 格式，含 ref） - `screenshot --session=NAME [--full-page] [--out=path]` 截图 ### 交互（默认拟人化 mode=full） - `click --session=NAME [--mode=full|fast|off]` 点击（含 visible+scrollIntoView 检查） - `hover --session=NAME [--mode=...]` 悬停（触发 hover 菜单等） - `fill --session=NAME` focus + 清空 + 拟人化输入 - `type --session=NAME` 在已 focused 输入框打字 - `press --session=NAME` 按键（Enter/Tab/Escape/Control+A 等） - `select --session=NAME` 选择 `