GPU_GUARD_MONOREPO/packages/backend/skills/netabrowser-cli/SKILL.md

name	description	license	metadata
netabrowser-cli	Neta 反风控+拟人化浏览器自动化 CLI。养号、电商自动化、AI 探索复杂网页时使用。 比 playwright-cli 更难被反风控识别（fingerprint-chromium 内核 + patchright 反自动化 + 贝塞尔曲线鼠标轨迹）。100 账号矩阵养号场景首选。所有操作通过 scripts/nb.sh （或 nb.cmd）调用，不需要 HTTP/curl。	MIT	version category 2.0 browser-automation

netabrowser-cli

通过 CLI wrapper 操作常驻浏览器 daemon。daemon 持有 chromium 实例 + 登录态 + session profile，CLI 是连 daemon 的薄客户端。AI 全程只用 scripts/nb.sh <cmd>， 永远不用 curl 或 HTTP。

快速验证环境

每次开始任务前先验证 daemon 是否启动：

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 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 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 持久化保留）

最简任务模板

# 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/<sessionName>/，cookie/localStorage 在 close 后保留。每个账号固定一个 sessionName（如 taobao-main），下次 open 自动恢复登录。不要每次换 sessionName——会重新登录。

2. 首页"立即登录"≠ 没登录

淘宝/拼多多/京东等 SPA 首页加载完后异步读 cookie 渲染用户名，snapshot 拍得太早会看到"立即登录"。正确判断方式：

• snapshot 里有"已买到"/"我的淘宝"/"我的订单"等只有登录后才出现的链接 → 已登录
• 直接点"已买到"，看跳转到订单页还是登录页 → 实际验证

不要看到"立即登录"就向用户要账号密码。

3. 头部 hover 触发的链接（淘宝"已买到"等）

淘宝头部"已买到"是 hover 触发的下拉菜单项，单纯 click 不跳转。两种解法：

# 方法 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 <url> --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 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 <ref> --session=NAME [--mode=full|fast|off] 点击（含 visible+scrollIntoView 检查）
• hover <ref> --session=NAME [--mode=...] 悬停（触发 hover 菜单等）
• fill <ref> <value> --session=NAME focus + 清空 + 拟人化输入
• type <text> --session=NAME 在已 focused 输入框打字
• press <key> --session=NAME 按键（Enter/Tab/Escape/Control+A 等）
• select <ref> <value> --session=NAME 选择 <select> 的某个 option
• check <ref> --session=NAME [--uncheck] 复选框勾选/取消
• scroll <deltaY> --session=NAME [--mode=...] 滚动（正数向下）

导航 + 等待

• goto <url> --session=NAME 跳转
• wait --session=NAME [--ref=eN] [--state=visible|hidden] [--load-state=networkidle] [--timeout=ms] 等待

状态持久化

• cookie-list --session=NAME [--domain=DOM] 获取 cookies
• state-save --session=NAME [--output=PATH] 保存完整登录态（默认 <dataDir>/states/<session>.json）
• state-load --session=NAME --input=PATH 恢复

全局选项

• --raw 输出单行 JSON（便于管道处理）
• NETA_BROWSER_HUMANIZE_MODE=full|fast|off 环境变量设定本会话默认 mode

---

拟人化档位

--mode	单命令开销	适用场景
full（默认）	2-5s	养号、敏感操作、AI 探索复杂页面
fast	0.3-0.7s	批量发布、批量评论
off	<100ms	测试、CI

养号场景每号约 30 操作 × 5s ≈ 2.5min。100 号串行 ≈ 4 小时。批量任务用 --mode=fast。

---

详细参考文档

• 拟人化档位详解
• 指纹参数（fingerprintSeed 何时用）
• 代理配置
• 典型场景示例