mooncat-browser 0.1.0

package/schemas/browser.getCookies.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.getCookies.schema.json",
+  "title": "browser.getCookies",
+  "description": "Cookie 操作",
+  "type": "object",
+  "properties": {
+    "filter": {
+      "type": null
+    }
+  },
+  "required": []
+}

package/schemas/browser.getDownload.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.getDownload.schema.json",
+  "title": "browser.getDownload",
+  "description": "查单个下载状态",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "id"
+  ]
+}

package/schemas/browser.health.schema.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.health.schema.json",
+  "title": "browser.health",
+  "description": "连接探测: browserd 是否活着 + 是否已 open",
+  "type": "object",
+  "properties": {},
+  "required": []
+}

package/schemas/browser.listDownloads.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.listDownloads.schema.json",
+  "title": "browser.listDownloads",
+  "description": "列出最近下载 (chrome.downloads.search 实时查)",
+  "type": "object",
+  "properties": {
+    "limit": {
+      "type": null,
+      "description": "[Type Gap: 未类型化]"
+    }
+  },
+  "required": [
+    "limit"
+  ]
+}

package/schemas/browser.listTabs.schema.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.listTabs.schema.json",
+  "title": "browser.listTabs",
+  "description": "列出标签页 (返回 TabInfo[], 每项 pageHandle 必有 pageId; 规范化 browserd wrapper)。",
+  "type": "object",
+  "properties": {},
+  "required": []
+}

package/schemas/browser.newTab.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.newTab.schema.json",
+  "title": "browser.newTab",
+  "description": "新建标签页",
+  "type": "object",
+  "properties": {
+    "options": {
+      "type": null
+    }
+  },
+  "required": [
+    "options"
+  ]
+}

package/schemas/browser.open.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.open.schema.json",
+  "title": "browser.open",
+  "description": "打开浏览器 (宿主 Chrome, 双路由自动选择 extension/cdp)",
+  "type": "object",
+  "properties": {
+    "options": {
+      "type": null
+    }
+  },
+  "required": [
+    "options"
+  ]
+}

package/schemas/browser.operate.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.operate.schema.json",
+  "title": "browser.operate",
+  "description": "在页面上执行动作 (click/fill/goto/snapshot/evaluate/...)",
+  "type": "object",
+  "properties": {
+    "params": {
+      "type": null
+    }
+  },
+  "required": [
+    "params"
+  ]
+}

package/schemas/browser.reuseTab.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.reuseTab.schema.json",
+  "title": "browser.reuseTab",
+  "description": "复用 tab: 按 urlMatch 找已开的 tab, 有则切过去复用, 无则 newTab(url)。",
+  "type": "object",
+  "properties": {
+    "options": {
+      "type": null
+    }
+  },
+  "required": [
+    "options"
+  ]
+}

package/schemas/browser.setCookies.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.setCookies.schema.json",
+  "title": "browser.setCookies",
+  "description": "browser.setCookies input",
+  "type": "object",
+  "properties": {
+    "cookies": {
+      "type": null
+    }
+  },
+  "required": [
+    "cookies"
+  ]
+}

package/schemas/browser.waitFor.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.waitFor.schema.json",
+  "title": "browser.waitFor",
+  "description": "通用等待: selector 或 text 出现。延迟轮询 + 刷新重试 + maxRefresh 次后仍未出现返回 ok:false。\nframeId 指定时在对应 iframe 内检测; 刷新整页 (location.reload) 后 frameId 可能变, 重新 listFrames。",
+  "type": "object",
+  "properties": {
+    "options": {
+      "type": null
+    }
+  },
+  "required": [
+    "options"
+  ]
+}

package/schemas/browser.waitForDownload.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mooncat/sdk/browser.waitForDownload.schema.json",
+  "title": "browser.waitForDownload",
+  "description": "轮询等下载完成 (基于 chrome.downloads 原生状态)。\n返回 { download, reason }: reason=complete 成功, timeout 超时。",
+  "type": "object",
+  "properties": {
+    "options": {
+      "type": null
+    }
+  },
+  "required": [
+    "options"
+  ]
+}

package/skills/browser/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: browser
+description: "Drive the user's local Chrome via @mooncat/browser (BrowserClient -> browserd RPC) for page probing, data collection, form automation, screenshots. Long-session co-work model (open once, reuse handle across turns), never judge route, stepwise with artifacts on disk. Use when the user wants to probe/collect/automate a web page, mentions browser automation, sycm/taobao scraping, or form filling. Independent toolkit - no mooncat distribution / workspace / PM2 dependency."
+---
+
+# browser
+
+通过 `@mooncat/browser` 的 `BrowserClient` 驱动**用户本地 Chrome**（用户看得见的浏览器，
+不是无头集群），做页面探查、采集、表单自动化、截图。
+
+`BrowserClient` 是薄 HTTP RPC client，连接常驻的 **browserd 服务**（`mooncat-browser start`
+拉起）。browserd 才是真正持有 Chrome 的进程，client 只发指令。
+
+**这不是批处理脚本，是 co-work**——和用户一起，看着同一个打开的浏览器，一步一步推进。
+
+## 三个铁律
+
+1. **handle 是纯数据，绝不判断路由。** 拿到 `pageHandle` 就直接用，所有页面动作走
+   `browser.operate({ pageHandle, action, params })`。绝不写
+   `if (ph.mode === 'cdp') {...}`——路由（extension/CDP）是 browserd 内部的事。
+   handle 不可变，没有"切当前 tab"的操作，要操作哪个 page 就拿它的 pageHandle。
+
+2. **会话长生命周期，用户满意前不释放。** `browser.open()` 一次，跨多步复用
+   handle。**绝不**每步都 open/close——启动 Chrome 慢，反复开关丢登录态/cookie。
+   只在用户说"完成"或要换完全不同的浏览器实例时才 `browser.close()`。`open()` 是幂等的：
+   浏览器还活着就复用当前 handle，被关了才重启。
+
+3. **步进式 co-work，一步一确认。** 一次一步，每步落盘中间产物（snapshot/截图/数据），
+   给用户看、等反馈。**绝不**把所有操作塞进一个调用——任何中间步失败（弹窗/验证码/加载慢）
+   都会让已改的状态不一致，且用户根本没看到过程。
+
+## 怎么用
+
+```ts
+import { BrowserClient } from "@mooncat/browser";
+
+// 连接到已启动的服务（端口要和 mooncat-browser start --port 一致，默认 17322）
+const browser = new BrowserClient({ baseUrl: "http://127.0.0.1:17322" });
+
+// 探测 browserd 是否就绪
+const h = await browser.health();
+if (!h?.browserOpen) await browser.open({ headless: false });
+
+// 打开页面 (newTab 返回 TabInfo, operate 传 tab.pageHandle)
+const tab = await browser.newTab({ url: "https://example.com" });
+
+// 所有页面动作走 operate (action 清单见包内 references/operate-actions 或 README)
+const snap = await browser.operate({ pageHandle: tab.pageHandle, action: "snapshot" });
+await browser.operate({ pageHandle: tab.pageHandle, action: "click", params: { selector: "#login" } });
+```
+
+> 服务必须先启动：`mooncat-browser start --port 17322`（另一个终端，常驻）。
+> 没启动时 `health()` 返回 null，`operate` 会连接拒绝报错。CLI 一键开页验证：
+> `mooncat-browser open --url https://example.com`。
+
+**操作清单不在本 skill 列**——`operate` 的 40+ 个 action（导航/交互/读取/等待/存储/截图）
+是公开契约，查包内 `README.md` 的 "operate 的 action 清单" 或
+`browser-op/backend/browserd.cjs` 的 `rpcOperate`（始终权威）。
+
+## 步进式 co-work 的标准节奏
+
+用户："帮我把这个网站我的订单都导出来。"
+
+```
+[回合1] 探查: open + newTab + status → "看到登录页,我先探查,你手动登录后告诉我?"
+[回合2] 用户:登录好了 → 进订单页: waitForSelector + snapshot 落盘 → "看到50条订单,要导出吗?"
+[回合3] 用户:导出 → 点导出: click + 截图确认 → "导出按钮点了,等下载"
+[回合4] 用户:好了 → 收尾: 用户满意才 close
+```
+
+全程 browser 只 open 一次（幂等复用），跨越所有回合，最后一回合才 close。
+**每一步的中间产物落盘**（snapshot yaml / 截图 / 抓取的数据），便于审计 + 给用户看。
+
+## 路由不泄漏
+
+`operate` 的 action 在 extension/CDP 两条路由上行为统一（少数例外见 high-risk.md 的 ext 列）。
+**绝不**：
+
+- 绝不 `if (ph.mode === 'cdp') { ph.page.click() }` —— 路由泄漏
+- 绝不直接调 browserd 内部模块 —— 那是 BrowserClient 背后的实现
+- 绝不修改 handle —— `ph.tabId = xxx` 是错的
+
+路由相关（如换 profile、切 extension↔cdp）只能 `close()` 后重新 `open()`，不能中途换。
+
+## 出错时怎么办
+
+**STOP。报告具体错误。等用户指示。** 绝不强杀 Chrome 进程（`taskkill` 丢登录态、留僵尸端口、
+用户未保存表单丢失），绝不自动重试轰炸。`open()` 失败时看返回的 notice/error。
+
+句柄过期（用户手滑关了浏览器、CDP 断）时不要推倒重来——重新 `open()` attach 即可（便宜），
+不要 close+relaunch。
+
+## 失败可见化（通用纪律，不依赖任何通知框架）
+
+任何一步失败（登录态丢失 / selector 失效 / 下载超时 / 风控拦截 / RPC 错），统一动作：
+
+1. **截图取证**（`screenshot`，extension 模式先 `activate`）——落盘到本地路径。
+2. **报告用户**：错误 + 截图路径 + 判断（验证码？登录失效？被限流？DOM 变了？）。
+3. **STOP**——绝不吞错静默跳过，绝不重试轰炸（高危平台重试会加速封号）。
+
+> 如果你在一个更大的系统里（有自己的通知渠道，如飞书/Slack/webhook），
+> 把"报告用户"换成你的通知机制即可。本 skill 只规定"必须可见化 + 叫人"的纪律，
+> 不规定具体通知后端——`@mooncat/browser` 是独立工具包，不带任何通知能力。
+
+## 参考
+
+- [references/collect.md](references/collect.md) — **★标准采集工作流**：三件套范式（复用 tab / 清弹窗 / 等就绪），SPA 采集必读
+- [references/probing.md](references/probing.md) — **★探查方法论**：frame 意识（元素查不到怎么系统性枚举）/ 同名消歧（位置 context）/ SOP 截图识图纪律
+- [references/high-risk.md](references/high-risk.md) — 高危平台专题（淘宝/京东/银行）：扩展路由 + 验证码 + 拟人化
+- [references/operate-actions.md](references/operate-actions.md) — operate 的 40+ 个 action 速查（按导航/交互/读取/等待/存储/截图分组）

package/skills/browser/references/collect.md

@@ -0,0 +1,163 @@
+# 标准采集工作流
+
+采集类任务的固定范式。三个动作串起来，解决 SPA 场景三大坑：
+**重复打开同页堆积 tab、弹窗挡住主体、主体没渲染就采**。
+
+## 三件套（缺一不可）
+
+| 动作 | 解决的坑 | 怎么做 |
+|---|---|---|
+| 复用已有 tab | 重复打开同一页面，堆积 tab | `browser.listTabs()` 找同 host 的 tab，有就复用，没有才 newTab |
+| 清弹窗 | 网页内弹窗挡住主体，snapshot/点击失效 | `evaluate` 关闭 modal/popup，或点关闭按钮 |
+| 等就绪 | SPA 加载慢，采集时主体还没渲染 | `waitForSelector` 等业务节点出现 |
+
+## 标准采集 step 模板
+
+```ts
+import { BrowserClient } from "@mooncat/browser";
+
+const SITE = "example.com";
+const browser = new BrowserClient({ baseUrl: "http://127.0.0.1:17322" });
+
+// 1. 复用已有 tab (不要盲目 newTab)
+await browser.open({ headless: false });
+const tabs = await browser.listTabs();
+let tab = tabs.find((t) => t.url?.includes(SITE));
+if (!tab) tab = await browser.newTab({ url: `https://${SITE}/orders` });
+// newTab()/listTabs() 统一返回 TabInfo, operate 传 tab.pageHandle
+const page = tab.pageHandle;
+
+// 2. 清弹窗 (网页内 modal/popup, 会挡住主体)
+await browser.operate({
+  pageHandle: page, action: "evaluate",
+  params: { source: "() => { document.querySelectorAll('.modal-close,.popup-close').forEach(b=>b.click()); return document.querySelectorAll('[class*=modal]').length }" },
+});
+
+// 3. 等就绪 (业务节点出现才算能采)
+await browser.operate({
+  pageHandle: page, action: "waitForSelector",
+  params: { selector: "#orders-table", timeout: 30000 },
+});
+
+// 4. 采集 (此时主体已就绪, 没弹窗)
+const data = await browser.operate({
+  pageHandle: page, action: "evaluate",
+  params: { source: "() => Array.from(document.querySelectorAll('.order')).map(e=>e.innerText)" },
+});
+```
+
+## 顺序不能乱
+
+```
+复用 tab (listTabs 找)
+    ↓
+清弹窗 (弹窗可能挡住就绪判定元素)
+    ↓
+等就绪 (主体渲染完成)
+    ↓
+采集
+```
+
+**清弹窗在等就绪前**：弹窗挡住时，`waitForSelector` 可能抓不到就绪元素（遮罩盖住），
+导致误判没就绪。先清弹窗，再判就绪。
+
+**不能跳过等就绪**：SPA 主体是 JS 动态渲染的，`goto`/`newTab` 返回时主体大概率没出来。
+直接采会采到空。
+
+## 弹窗类型区分（只有两类）
+
+所有弹窗本质只有模态 / 非模态两类, 处理逻辑完全不同, 看点空白能不能关:
+
+| 弹窗类型 | 特征 | 处理 |
+|---|---|---|
+| **模态弹窗** | 有遮罩(mask/overlay), 点空白**不能**关, 阻塞主体 | 找弹窗内**关闭按钮点掉**(×/关闭/我知道了/确定) |
+| **非模态弹窗** | 无遮罩 或 点空白/遮罩区**能**关, 不阻塞 | **点空白处关**(点 body/遮罩外侧) 或直接隐藏 |
+| 浏览器原生 dialog | alert/confirm/prompt | `setDialogHandler` action 注册处理器 |
+
+国内站点引导弹窗（"我知道了/开始使用/领取优惠"）常见, 模态的按文本点关闭:
+
+```ts
+await browser.operate({
+  pageHandle: page, action: "evaluate",
+  params: { source: "() => { const btns=[...document.querySelectorAll('button,span,a')]; const t=btns.find(b=>/我知道了|确定|关闭|开始使用/.test(b.textContent||'')); if(t){t.click();return true} return false }" },
+});
+```
+
+**优先判定"点空白能不能关", 不看弹窗叫什么名字。** 模态点空白没用必须找按钮;
+非模态点空白就关。混淆会点不到或点错。
+
+### 通用清弹窗范式（开页第一件事, 关键页操作前必走一次）
+
+开页后第一件事是清弹窗, 然后才等就绪/采数据/点控件。万相台/生意参谋/淘宝系站点尤其多
+新手引导热点遮罩（**文本为空的半透明遮罩**, 不存盘只看 DOM 极隐蔽）。
+
+```ts
+// 通用清弹窗: 模态找按钮点, 非模态点空白关。一次扫两类。
+// 返回关了几个, 供日志。每个关键页操作前必走一次。
+async function clearPopups(page) {
+  return await browser.operate({
+    pageHandle: page, action: "evaluate",
+    params: { source: `() => {
+      let cleared = 0;
+      // 1. 模态弹窗: 有遮罩且有按钮的, 点按钮(优先 ×/关闭/我知道了/确定)
+      const modals = [...document.querySelectorAll('[class*=modal],[class*=dialog],[class*=popup],[role=dialog],[class*=mask],[class*=overlay],[class*=guide-hotspot],[class*=hotspot]')]
+        .filter(e => e.offsetParent);
+      for (const m of modals) {
+        const btn = [...m.querySelectorAll('button,span,a,i,div,[role=button]')]
+          .find(b => b.offsetParent && /×|✕|关闭|我知道了|知道了|确定|不再提示|跳过|开始使用|下次再说/.test((b.textContent||'').trim()));
+        if (btn) { btn.click(); cleared++; }
+      }
+      // 2. 通用兜底: 全局找 ×/关闭/我知道了 按钮
+      const gBtns = [...document.querySelectorAll('button,span,a,i,[role=button]')]
+        .filter(e => e.offsetParent && /×|✕|关闭|我知道了|知道了|确定|跳过/.test((e.textContent||'').trim().slice(0,8)));
+      for (const b of gBtns.slice(0,3)) { b.click(); cleared++; }
+      // 3. 非模态弹窗: 点空白处关(点 body 顶层, 触发 clickoutside)
+      const masksNoBtn = modals.filter(m => ![...m.querySelectorAll('*')].some(b => b.offsetParent && /×|关闭|我知道了|确定/.test((b.textContent||''))));
+      if (masksNoBtn.length) { document.body.click(); cleared++; }
+      return { cleared, remainModal: modals.length };
+    }` },
+  }).catch(() => ({ cleared: 0 }));
+}
+
+// 每个关键页操作前的标准顺序: goto → 清弹窗 → 等就绪 → 操作
+await browser.operate({ pageHandle: page, action: "goto", params: { url } });
+await sleep(2500);
+await clearPopups(page);          // ← 开页第一件事, 清弹窗
+await browser.operate({ pageHandle: page, action: "waitForSelector", params: { selector: targetEl, timeout: 15000 } });
+```
+
+**为什么清弹窗在等就绪前**: 弹窗遮罩盖住主体时, waitForSelector 可能抽不到就绪元素,
+误判没就绪; 点控件会点到遮罩上。先清干净再判就绪。
+
+## 等就绪的判定源
+
+`waitForSelector` 等业务元素出现即就绪。判定源选择：
+
+- **selector**：业务关键节点（如 `#orders-table`、`.data-panel`）出现即就绪
+- **兜底**：用 `waitForLoadState`（state=networkidle）等网络空闲
+
+没就绪的处理：等待超时后**停下报告用户**，不要采垃圾数据。SPA 主体没出来就采，
+采到的是空壳，浪费整轮。
+
+## 何时不用这套
+
+- **简单静态页**（无弹窗、主体在 DOMContentLoaded 就绪）：直接 `waitForSelector` + 采集。
+- **纯读取场景**（status/snapshot/screenshot）：本身不改状态，但若页面有弹窗挡住，仍建议先清弹窗。
+
+## 中间产物落盘
+
+采集每一步的中间产物（snapshot / 截图 / 抓取的数据）建议落盘到本地目录，便于审计 + 给用户看。
+用 Node 原生 `fs` 写即可（`@mooncat/browser` 不提供文件落盘能力，那是你应用层的职责）：
+
+```ts
+import { writeFileSync } from "node:fs";
+
+const snap = await browser.operate({ pageHandle: page, action: "snapshot" });
+writeFileSync("./trace/orders-snapshot.yaml", snap.yaml);
+
+const shot = await browser.operate({ pageHandle: page, action: "screenshot" });
+if (shot?.dataUrl) writeFileSync("./trace/orders.png", Buffer.from(shot.dataUrl.split(",")[1], "base64"));
+```
+
+> 如果你在更大的系统里（有自己的 trace/artifacts 体系，如 mooncat 的 var/probe + cateye-probe），
+> 用那套体系替代这里的手动 fs 即可。本 skill 只规定"中间产物要落盘"的纪律。

package/skills/browser/references/high-risk.md

@@ -0,0 +1,161 @@
+# 高危平台注意事项
+
+高危平台（淘宝/京东/生意参谋/银行/小红书等强风控站点）的探查/采集约束。
+
+## 核心约束：CDP 端口会被风控识别
+
+CDP 路由通过 `--remote-debugging-port` 暴露调试端口，**强风控脚本会检测这个端口**
+（以及 webdriver 标记）。在淘宝/京东/银行这类站点走 CDP 路由，大概率被判定为自动化，
+触发验证码、限流、甚至封号。
+
+## 路由选择
+
+`browser.open({ routeMode })` 的取值：
+
+| routeMode | 行为 | 适用 |
+|---|---|---|
+| `auto`（默认）| 自动检测 profile 是否装 WebPlater 扩展，装了走 extension，没装走 CDP | 通用 |
+| `extension` | 强制走扩展路（无 CDP 端口，无 webdriver 标记） | **高危平台必选** |
+| `cdp` | 强制走 CDP（暴露调试端口） | 静态页/调试/非风控站点 |
+
+**高危平台必须走 extension 路由**：`open({ routeMode: "extension" })`。
+若 profile 没装扩展，extension 路会失败——此时**停下来报告用户**，不要降级到 CDP 凑合。
+
+## WebPlater 扩展安装（每个 profile 一次性）
+
+extension 路由依赖 WebPlater 扩展。**扩展装在具体 Chrome profile 里**——换 profile 就要重装。
+首次使用高危平台前，用户需在目标 profile 装 WebPlater：
+
+1. `mooncat-browser install-extension` 拿到扩展目录绝对路径（包内 `browser-op/webplater/dist/chrome-mv3/`）。
+2. `mooncat-browser start --port 17322` 启动服务，`browser.open({ routeMode: "auto" })` 启动 Chrome，
+   拿到 profile 的 user-data-dir（默认 `%LOCALAPPDATA%\mooncat-browser\profile`，或 `--profile` 指定）。
+3. 用户在该 Chrome 访问 `chrome://extensions`，开「开发者模式」。
+4. 点「加载已解压的扩展程序」，选第 1 步拿到的扩展目录（校验路径下有 `manifest.json`）。
+5. 等几秒 background service worker 连上 WS server。
+6. 重新 `open`（routeMode=auto），看返回的 `mode` 是否为 `extension`。
+
+**必须先算好扩展绝对路径再告诉用户**，不要让用户自己找。`mooncat-browser install-extension`
+会打印路径。校验路径下有 `manifest.json`。
+
+## 装了扩展后必须重启浏览器
+
+扩展装上后，`open()` 返回的 `mode` 可能仍是 `cdp`（因为 open 时 routeMode 已锁定）。
+**必须 `browser.close()` 再重新 `open()`**，mode 才会切到 extension。不能中途静默切换。
+
+## 探查动作的拟人化
+
+⚠️ **重要**：BrowserClient（薄 RPC 到 browserd）**不暴露 humanize/riskLevel 选项**。
+裸 `operate` 的 click/fill 是机器特征（瞬点、无轨迹），高危平台即使走 extension 路由，
+风控仍可能通过交互节奏识别。
+
+高危平台探查时：
+
+- **优先只读操作**（status/snapshot/innerText/screenshot）——只读不触发风控交互检测。
+- **交互操作（click/fill）谨慎用**：必须交互时，操作间加 `waitForTimeout` 随机延迟，
+  降低节奏特征。
+- **触发验证码立即停下**：检测到验证码（页面出现验证码元素/被重定向到验证页），
+  **STOP，报告用户**，不要尝试自动过验证码。
+
+### probe 长会话分阶段（高危平台是安全红线，不只是效率）
+
+探查天然分阶段——开一次页面 + 导航到位后，**复用同一个 tab**继续探下一个问题，不重开。
+**严禁每个小问题都重新 newTab + 导航**。
+
+**为什么在高危平台这是红线，不只是效率问题**:
+- 每开一次 newTab + 导航 + 等 SPA = 一次完整页面加载请求。反复重开 = 高频异常访问。
+- 生意参谋/天猫/京东等强风控站点，**重开页面越多，风控触发越快**——推向验证码/限流/封号。
+- 探查阶段本就高频操作，再叠加反复重开，等于主动触雷。
+
+→ **同一个页面一旦打开，在会话内反复复用，用多次 evaluate 探不同问题，绝不为每个小问题
+  重新 newTab+导航。** 探查动作只读优先（status/snapshot/screenshot），减少交互请求；
+  必须交互时控制频率。
+
+复用方式: `browser.listTabs()` 按 url 匹配找到已开的 tab，拿它的 `pageHandle` 继续操作。
+
+## 验证码检测
+
+操作后用只读 snapshot/innerText 检测是否被验证码拦截。**注意:iframe 内的拦截要从对应 frameId 读**
+（淘宝/阿里统一登录在 havanalogin iframe，顶层 document 读不到）。
+
+```ts
+// 顶层页面文本
+const topText = await browser.operate({
+  pageHandle: tab.pageHandle, action: "innerText",
+  params: { selector: "body" },
+});
+// 登录 iframe 内文本 (跨域, 必须用 frameId eval)
+const iframeText = await browser.operate({
+  pageHandle: tab.pageHandle, action: "evaluate",
+  params: { frameId: loginFrameId, source: "() => document.body ? document.body.innerText : ''" },
+});
+const combined = String(topText.value) + String(iframeText?.value || iframeText || "");
+if (/验证码|滑动验证|请完成验证|向右滑动|captcha|拖动|安全验证/i.test(combined)) {
+  // STOP: 截图 + 报告用户被验证码拦截, 不自动过
+}
+```
+
+命中后**绝不**继续操作，绝不尝试自动识别/绕过验证码。停下来让用户手动过。
+
+## 不可自动化的拦截类型（检测到即报告用户，绝不对抗）
+
+高危平台登录链路有一类拦截是**根本无法自动化**的（自动过 = 对抗风控 = 封号风险）。
+这些不是 bug，是平台风控设计，唯一正确动作是**检测 → 报告用户 → 暂停等人工**。
+
+| 拦截类型 | 识别特征（页面文本） | 能否自动 |
+|---|---|---|
+| **滑块验证** | `向右滑动验证` / `拖动滑块` / `滑动验证` | ❌ 不能。轨迹是风控核心，机器滑动必被识破 |
+| **手机/短信验证码** | `短信验证码` / `获取验证码` / `手机验证` | ❌ 不能。要人手机收码 |
+| **图形验证码** | `输入图中字符` / `看不清` / 图形验证 | ❌ 不能。OCR 过码违反平台规则 |
+| **人脸/实名** | `人脸识别` / `实名认证` | ❌ 不能。生物特征，只能人 |
+| **风险提醒** | `检测到风险` / `异常登录` / `环境异常` | ❌ 不能。需人工按提示操作 |
+
+**统一处理范式**（无论哪种拦截，用截图 + 报告代替通知框架）:
+
+```ts
+// 检测到拦截 (滑块/验证码/风险提醒任一)
+if (blocked) {
+  // 1. 截图取证 (extension 模式先 activate, 否则 screenshot 报错)
+  await browser.operate({ pageHandle: tab.pageHandle, action: "activate" }).catch(() => {});
+  const shot = await browser.operate({ pageHandle: tab.pageHandle, action: "screenshot" });
+  let imgPath = null;
+  if (shot?.dataUrl) {
+    const { writeFileSync } = await import("node:fs");
+    imgPath = "./trace/login-blocked.png";
+    writeFileSync(imgPath, Buffer.from(shot.dataUrl.split(",")[1], "base64"));
+  }
+
+  // 2. 报告用户叫人来处理 (用你应用层的通知机制; @mooncat/browser 不带通知能力)
+  //    内容: 拦截类型 + 截图路径 + "请打开浏览器完成验证, 会话将在登录态恢复后继续"
+  reportToUser({ type: "登录拦截", 拦截类型, screenshot: imgPath });
+
+  // 3. STOP — 不重试, 不对抗, 等人。会话在此挂起, 下次重新检测登录态
+  return;
+}
+```
+
+> 上例的 `reportToUser` 是占位——你的应用层用什么通知（飞书/Slack/webhook/console 打印 +
+> 等待）就用什么。`@mooncat/browser` 是独立工具包，**不带任何通知能力**，本 skill 只规定
+> "必须可见化 + 叫人"的纪律，不规定通知后端。
+
+**关键心态**：这些拦截"不能搞定"是**正常预期**，不是失败。职责是**第一时间发现并叫人**，
+不是去破解。把"无法自动过"当问题去解，就是在对抗风控，违反铁律。
+
+### 登录态复用（避免每次都撞拦截）
+
+既然登录拦截无法自动，正确架构是 **不碰登录填表，只做登录态检测**:
+- 启动 → `browser.open()` + 访问目标页 → 读 url/snapshot 判断是否已登录
+- 已登录（cookie 在 profile 里）→ 直接进业务步骤
+- 未登录/被拦 → 报告用户叫人，会话挂起
+- 人工登录一次后（过滑块/验证码），cookie 留在 profile，后续会话复用，不再撞拦截
+
+这条"登录态复用"是高危平台的标准模式。
+
+## 出错纪律（高危平台更严）
+
+1. **STOP**，不要重试轰炸。
+2. 截图记录当前状态（`screenshot` 到产物）。
+3. 报告用户：错误 + 截图 + 判断（验证码？登录失效？被限流？）。
+4. 等用户决定下一步。
+
+**绝不**：强杀 Chrome（`taskkill`）、清 cookie 重来、自动切换 profile——这些在高危平台都会
+放大风险（清 cookie 可能触发异地登录风控，切 profile 丢登录态）。