mooncat-browser 0.1.0

package/skills/browser/references/operate-actions.md

@@ -0,0 +1,92 @@
+# operate 的 action 速查
+
+`browser.operate({ pageHandle, action, params })` 支持 40+ 个 action，覆盖导航/交互/读取/等待/存储/截图。
+这是内核公开契约的速查表；完整说明见包内 `dist/actions.md`。
+
+### 交互
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `clickAt` | `x`:number, `y`:number, `button`?:string=left, `clickCount`?:number=1 | {ok,x,y,route} | 坐标点击(绕过selector,CDP路真实鼠标/扩展路合成事件) | ✓ |
+| `clickByText` | `text`:string, `exact`?:boolean=false, `index`?:number=0, `offsetX`?:number=0, `offsetY`?:number=0 | {ok,text,x,y,match,route} | 定位可见文本后立即点击(原子,防DOM重渲染) | ✓ |
+| `click` | `selector`:string, `x`?:number, `y`?:number | {ok,selector} | 点击元素(或坐标x,y) | ✓ |
+| `fill` | `selector`:string, `value`:string | {ok,selector,value} | 在selector元素填入文本(先清空) | ✓ |
+| `type` | `selector`:string, `value`:string, `delay`?:number=0 | {ok,selector} | 逐字输入(带延迟,模拟键盘) | ✓ |
+| `press` | `selector`:string, `key`:string | {ok,selector,key} | 在元素上按键 | ✓ |
+| `hover` | `selector`:string, `x`?:number, `y`?:number | {ok,selector} | 悬停元素(或坐标) | ✓ |
+| `focus` | `selector`:string | {ok,selector} | 聚焦元素 | ✓ |
+| `check` | `selector`:string | {ok,selector} | 勾选checkbox/radio | ✓ |
+| `uncheck` | `selector`:string | {ok,selector} | 取消勾选 | ✓ |
+| `selectOption` | `selector`:string, `value`:string | {ok,selector,value} | 选择option | ✓ |
+| `dblclick` | `selector`:string | {ok,selector} | 双击元素 | ✓ |
+| `mouseMove` | `x`:number, `y`:number | {ok,x,y} | 移动鼠标到坐标 | ✓ |
+| `clickAt` | `x`:number, `y`:number, `button`?:string=left, `clickCount`?:number=1 | {ok,x,y,route} | 坐标点击(CDP路page.mouse真实鼠标) | ✓ |
+| `clickByText` | `text`:string, `exact`?:boolean=false, `index`?:number=0, `offsetX`?:number=0, `offsetY`?:number=0 | {ok,text,x,y,match,route} | 定位可见文本后立即点击(CDP路原子) | ✓ |
+| `dragTo` | `source`:string, `target`:string | {ok,source,target} | 拖拽source到target(双兼容mouse+HTML5) | ✓ |
+
+### 读取
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `locateVisibleText` | `text`:string, `exact`?:boolean=false, `index`?:number=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回bbox(不返回DOM handle) | ✓ |
+| `locateVisibleText` | `text`:string, `exact`?:boolean=false, `index`?:number=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回bbox | ✓ |
+| `innerHTML` | `selector`:string | {ok,selector,value} | 读元素innerHTML | ✓ |
+| `innerText` | `selector`:string | {ok,selector,value} | 读元素innerText | ✓ |
+| `textContent` | `selector`:string | {ok,selector,value} | 读元素textContent | ✓ |
+| `getAttribute` | `selector`:string, `name`:string | {ok,selector,name,value} | 读元素属性 | ✓ |
+| `inputValue` | `selector`:string, `timeout`?:number=10000 | {ok,selector,value} | 读input/select当前值 | ✓ |
+| `boundingBox` | `selector`:string | {ok,selector,x,y,width,height} | 读元素包围盒(坐标+尺寸) | ✓ |
+| `count` | `selector`:string | {ok,selector,count} | 统计selector匹配数 | ✓ |
+| `snapshot` | `depth`?:number, `timeout`?:number=15000 | {ok,yaml,totalChars} | aria无障碍快照(返回yaml) | ✓ |
+
+### 进阶
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `operateSequence` | `steps`:array | {ok,results} | 原子序列执行(locate/click/wait在同一页面上下文串行) | ✓ |
+| `setDialogHandler` | `handler`:string | {ok} | 设置JS对话框处理 | 仅 ext |
+| `operateSequence` | `steps`:array | {ok,results} | 原子序列执行 | ✓ |
+| `evaluate` | `source`:string, `args`?:any | 由函数返回值决定 | 执行页面JS函数(返回其结果) | ✓ |
+| `setInputFiles` | `selector`:string, `files`:array, `timeout`?:number=10000 | {ok,selector,count} | 上传文件到file input | ✓ |
+
+### 导航
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `goto` | `url`:string | {ok,url} | 导航到URL,等待DOMContentLoaded | ✓ |
+| `goBack` | `timeout`?:number=15000 | {ok,url} | 后退一页 | ✓ |
+| `goForward` | `timeout`?:number=15000 | {ok,url} | 前进一页 | ✓ |
+| `reload` | `timeout`?:number=15000 | {ok,url} | 刷新当前页 | ✓ |
+| `status` | — | {ok,url,title,readyState,textLength} | 读当前页状态(url/title/readyState) | ✓ |
+
+### 等待
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `waitForLoadState` | `state`?:string=load, `timeout`?:number=30000 | {ok} | 等待指定加载状态 | ✓ |
+| `waitForSelector` | `selector`:string, `timeout`?:number=30000 | {ok,selector,visible,inViewport} | 等待selector元素可见 | ✓ |
+| `waitForFunction` | `source`:string, `timeout`?:number=30000 | 由函数返回值决定 | 等待页面函数返回truthy | ✗ (extension路CSP拦截eval) |
+| `waitForURL` | `url`:string, `timeout`?:number=30000 | {ok,url} | 等待URL匹配 | ✓ |
+| `waitForTimeout` | `ms`?:number=1000 | {ok,ms} | 固定等待 | ✓ |
+
+### 标签页
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `closeTab` | — | {ok} | 关闭当前page | ✓ |
+| `activate` | — | {ok} | 切到最前(仅可视) | ✓ |
+
+### 截图
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `screenshot` | — | {ok,format,dataUrl} | 截整页PNG(返回dataUrl) | ✓ |
+
+### 存储
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `getLocalStorage` | `keys`?:array | {ok,storage} | 读localStorage(不传keys读全部) | ✓ |
+| `setLocalStorage` | `items`:object | {ok,count} | 写localStorage | ✓ |
+| `removeLocalStorage` | `keys`?:array | {ok,count} | 删localStorage(不传keys删全部) | ✓ |
+| `clearLocalStorage` | — | {ok} | 清空localStorage | ✓ |

package/skills/browser/references/probing.md

@@ -0,0 +1,302 @@
+# 探查方法论
+
+探查 = 搞清楚页面真实 DOM 结构，找出 selector / 就绪条件 / 元素位置。
+**探查优先，绝不照文字/截图猜 DOM**。本文件是通用探查方法论，不依赖任何特定运行时。
+
+## frame 意识（探查任何元素的前提）
+
+**现代 web 应用大量用 iframe 嵌套**（内容区、表单、tab、表格、弹窗、第三方组件都可能
+是独立 iframe）。**枚举不完哪些东西在 iframe 里**——登录表单会、内容区会、报表会、
+甚至一个按钮都可能。所以规则不是"X 在 iframe"（特定场景枚举），而是一个**通用前提**:
+探查任何 DOM 元素之前，先搞清楚页面有几层 frame，目标在哪个 frame。
+
+**铁律: 截图/文字里有的元素一定存在, 查不到就把全部可能枚举一遍, 不原地打转。**
+SOP 截图或文字描述里出现的元素, 页面上一定有。查不到不是"换 selector 再试", 而是系统性枚举
+所有可能的位置/形态逐个排查:
+
+1. **顶层 document** — 默认 evaluate 查的这里。
+2. **各子 iframe** — `operate({action:'listFrames'})` 拿到所有 frame（顶层 frameId:0 +
+   各子 iframe）, **逐个子 frame eval 找**。现代 web 大量用 iframe 嵌套, 枚举不完哪些在 iframe,
+   必须逐个查。
+3. **动态渲染** — SPA 异步加载, 元素还没出来。加 `waitForTimeout` / `waitForSelector` 重查。
+4. **portal 弹层** — ant-dropdown / modal / popover 等组件渲染在 `document.body` 末尾的
+   portal 里, 不在其逻辑父容器下。点触发后去 body 末尾找（如 `.ant-dropdown-menu-item`）。
+5. **shadow DOM** — 元素在 closed/open shadow root 里, 需穿透 shadow 查。
+
+**原地打转的反模式**: 只查顶层一个地方, 查不到就反复换 selector/class/正则。永远找不到
+iframe/portal/shadow 里的元素。正确做法是上面 5 类系统性枚举, 逐个排除。
+
+**跨域 iframe 的硬约束** (安全策略):
+- 跨域 iframe 不能从顶层读 contentDocument（为 null）。
+- 必须在 iframe 自己的 frame context 里 eval（`evaluate` 支持 `frameId` 参数, 直接进对应
+  Frame 执行）, 不能从顶层越权读。
+- 所以 frameId 不是可选参数——目标是子 frame 元素时, frameId 是必须的。
+
+### listFrames + 逐 frame eval 范式
+
+```ts
+import { BrowserClient } from "@mooncat/browser";
+const browser = new BrowserClient({ baseUrl: "http://127.0.0.1:17322" });
+
+const tab = await browser.newTab({ url: "https://example.com" });
+const page = tab.pageHandle;
+
+// 1. 先看页面有几层 frame
+const frames = await browser.operate({ pageHandle: page, action: "listFrames" });
+// frames: [{ frameId: 0, url: "...", parentFrameId: null }, { frameId: 1, ... }, ...]
+
+// 2. 在某个子 iframe 里 eval 找元素 (传 frameId)
+const found = await browser.operate({
+  pageHandle: page, action: "evaluate",
+  params: {
+    frameId: 1,   // 目标在子 iframe 时必须传
+    source: "() => { const el = document.querySelector('#login-form'); return el ? 'found' : 'none'; }",
+  },
+});
+```
+
+## 点击/验证节点必须复核位置（核心铁律）
+
+**找任何点击/验证节点，绝不能只靠文本匹配**。页面常出现**同名不同位置**的元素
+（文本完全一样，但在不同容器里），只靠 `textContent==='取数报表'` 点击，很可能点到错的那个。
+
+实战案例（生意参谋自助分析页）: 页面上有**两个** "取数报表":
+- 左侧菜单项（导航入口，父级）
+- 中间内容区 tab（分类筛选，子级）
+
+两者文本完全相同，但功能不同。**只有同时"左侧菜单在取数报表 + 中间 tab 选取数报表"才显示
+报表列表**。只靠文本匹配的 evaluate 永远会撞坑。
+
+**探查时必须确认节点的周边位置（context）**:
+- **所在容器**: 节点的祖先链是导航菜单? 内容区 tab 栏? 表格行操作列?
+  探查时返回 `el.closest('[class*=menu]')` / `el.closest('[class*=tab]')` / `el.closest('tr')` 确认在哪个区。
+- **同级兄弟**: 同一父级下还有哪些元素（定位是 tab 栏第 N 个，还是菜单第 N 项）。
+- **区分同名**: 多个同名时，用**容器 + 路径**消歧，不是靠文本。例:
+  `document.querySelector('[class*=menu] [class*=item]:nth-child(2)')`（左侧菜单第 2 项）
+  vs `[class*=tabs] [class*=tab]:nth-child(4)`（中间 tab 第 4 个）。
+
+**evaluate 探查必须返回 context，不只返回"找到了"**:
+```js
+// 正确: 返回周边位置, 能判定是哪个
+const t = all.find(e => e.textContent.trim() === '取数报表');
+return {
+  text: '取数报表',
+  tag: t.tagName,
+  inMenu: !!t.closest('[class*=menu],[class*=side]'),      // 关键: 在哪个容器
+  inTabBar: !!t.closest('[class*=tab],[role=tablist]'),
+  parentClass: t.parentElement?.className,
+  siblings: [...t.parentElement.children].map(e => e.textContent.trim()),  // 同级兄弟
+};
+// 错误: 只返回 ok:true, 无法区分是哪个同名元素
+```
+
+每个点击/验证节点都要写清**「在哪个容器 + 第几个」**，不能只写文字。
+文本不是全部，位置也是 DOM 的一部分。
+
+## 五阶段采集模型（写每个采集目标的根本方法论）
+
+一个采集目标 = 五个阶段，顺序不能乱，缺一不可。这五阶段来自真实探查验证，不是脑补：
+
+```
+开始环境 → 动作 → 采集环境 → 锁定物(waitFor) → 目标(采集)
+```
+
+| 阶段 | 是什么 | 举例（生意参谋粉丝数） |
+|---|---|---|
+| **开始环境** | goto 直达的页面（动作前的初始状态） | goto 首页 portal/home |
+| **动作** | 进入采集环境要做的交互（点 tab/切视图/滚动） | 点店铺资产 tab + 滚动到底 |
+| **采集环境** | 动作完成后，目标数据"应该出现"的页面状态 | 店铺资产板块展开 + 页面底部 |
+| **锁定物** | 在采集环境里 waitFor 的关键元素（确认环境就绪） | waitFor "粉丝" 文案出现 |
+| **目标** | 真正要采集的数据（读 DOM/表格/文本） | 读"累积了 X 个粉丝" |
+
+### 锁定物铁律
+
+**锁定物一定是在"采集环境"里 waitFor 的，不是在"开始环境"里。**
+
+- 错: goto 完就 waitFor 目标文案（此时还没做动作，文案当然没有）→ waitFor 触发刷新，把页面状态冲了
+- 对: 做完动作（点 tab/切视图/滚动）进入采集环境后，**才** waitFor 目标文案
+
+### waitFor 的 maxRefresh 区分场景
+
+waitFor 内部有 maxRefresh（等不到就刷新页面重试）。**不是所有场景都该刷新**:
+
+| 场景 | maxRefresh | 原因 |
+|---|---|---|
+| goto 直达页 | 2（可刷新） | 页面是初始态，刷新无害，应对风控/懒加载 |
+| 需动作才到的环境（点表格后/点 tab 后） | **0**（只轮询不刷新） | 刷新会丢失动作状态（表格视图收起/tab 收回） |
+
+**点过 tab/切过视图的页面，waitFor 绝不刷新（maxRefresh=0），只轮询等。** 刷新=丢失状态=白做动作。
+
+### 为什么固定 sleep 不够
+
+高危平台有风控/懒加载/SPA 异步渲染，goto 后内容**不一定出来**（可能风控拦截/慢加载/需触发）。
+固定 sleep N 秒后直接采，可能采到空。必须 waitFor 锁定物确认环境就绪。
+固定 sleep 只在 waitFor 之后做"渲染稳定"用（如 waitFor 到表头后 sleep 1s 让数据行填完）。
+
+## SOP 截图的识图纪律（高亮 = 位置与路径标识）
+
+用户给的 SOP 截图里，**高亮/红框/箭头标注不是"示意该点什么"**，而是硬性的**页面位置标识**:
+那个被高亮/选中的按钮或标签，标识了**用户当前停在哪个页面、从哪条路径进来的**。
+
+- **高亮所在的那一排** = 路径层级。在中间 tab 栏第 4 个被选中 = 当前视图是
+  「某模块 → 某分组 → 中间第 4 个 tab」。在左侧菜单某项被选中 = 当前在该菜单项的功能区。
+- **高亮的选中态** = 这个位置现在是 active。要复现到这个页面，就得**让那个位置变成选中态**，
+  即点到它高亮为止，不是点同名但不同位置的入口。
+- **高亮是路标，不是装饰**。读图的第一件事是**找所有高亮元素，读出它们的位置**，由此倒推
+  到达该页面的导航路径。而不是看截图"大概理解"后凭印象写 selector。
+
+### 识图只看三点（统一标准）
+
+用 `image_analyze` 读 SOP 截图时，统一问这三件事，不随手写 prompt:
+
+> **识图约定（写进 prompt 开头）**: 截图里所有**红色粗框、红色字体都是用户给的操作标注**，
+> 不是页面原有元素。**红色字体的数字编号（1/2/3...）是点击顺序**，按编号从小到大就是操作序列。
+
+1. **用户标注（最重要）**: 列出所有红框框选的文字、所有红字编号 + 说明、红色箭头指向。
+   按编号顺序整理成操作序列：1 点哪里、2 点哪里……
+2. **到达路径**: 哪些元素是选中态/高亮态（蓝色高亮/下划线/背景突出）？分别在什么位置
+   （哪个菜单选中、哪个 tab 选中）？由此倒推到达当前页面的导航路径。
+3. **重要文本的邻居上下文（不报方位，报邻居）**: 对要点/要读的元素，报告它**周围的文字和按钮**
+   ——它和哪些元素同处一组/互相挨着。邻居是防同名混淆的定位锚点，比"页面右下角"有用。
+   **严禁报"页面上方/下方/左上角"这种像素方位**——对 DOM 探查无意义。
+
+**为什么只问三点**: 卡片数值、logo、无关菜单都是噪音，淹没真正要的信息。prompt 越聚焦，
+模型报告越准。
+
+### 图证据 vs 探查结果矛盾
+
+**图证据 > probe 结果**，但不是二选一。两者矛盾时**两者都复查**:
+- 图显示某元素存在，探查顶层查不到 → 几乎总是**该元素在子 iframe**，listFrames + 进 iframe eval 就找到了。
+- 探查可能错（selector 漏/查错 frame/SPA 没渲染够），图也可能错（prompt 差/模型臆测）。
+- 矛盾时用更好 prompt 重读图 + 换手段重查（换 frame/换 selector/加等待），不要改结论迁就任一方。
+
+## 成功判据必须可判定
+
+把"加载完成""看到报表"这类人话，转成**机器可判定的二值判定**:
+- `waitForSelector X visible`（元素出现即就绪）
+- `innerText` / `snapshot` 含某文本
+
+不可判定的判据是失败源，必须补成可检查的。每一步都要有成功判据，没有判据 = 不知道成功没成功。
+
+## 下载类操作的两层判据
+
+点击下载/导出涉及产物文件，必须能**二值判定下载是否成功**，否则"点了下载但文件没下来"
+会静默失败。难点：浏览器下载是异步的，点按钮 ≠ 文件立即可见。判据分两层：
+
+- **触发判据**（点没点到）：点击后按钮状态变化（"下载中" loading）/ 出现"导出成功" toast /
+  `waitForSelector` 下载进度条出现。这是"动作生效"的证据，不是"文件就绪"。
+- **就绪判据**（文件真的下来了）：**轮询下载目录**——文件出现且**不再增长**（size 稳定，
+  即下载完成不是半截）+ 文件名含预期日期/关键词。
+
+常见坑:
+- 文件名带时间戳/随机串 → 判定用**模式匹配**（glob / 正则），不要等固定名。
+- 同名文件已存在被覆盖 → 下载前记录目录 snapshot，下载后 diff 出新文件。
+- 下载的是 .xls/.xlsx/.csv → 探查确认实际格式，别假设。
+- 大文件导出有"准备中"阶段 → 点完按钮先 `waitForTimeout` + 轮询，别点完立刻判。
+
+### 用 BrowserClient 的下载 API（仅 extension 模式）
+
+WebPlater 扩展路基于 `chrome.downloads` 原生 API，有专门的下载查询方法:
+
+```ts
+// 列出最近下载
+const { downloads } = await browser.listDownloads(20);
+
+// 查单个下载状态
+const { download } = await browser.getDownload(id);
+
+// 轮询等下载完成 (按 filenameRegex + sinceMs 匹配, 等 state=complete)
+const { download, reason } = await browser.waitForDownload({
+  filenameRegex: "每日数据_.*\\.xlsx$",
+  sinceMs: Date.now() - 1000,   // 只看点击后的新下载
+  timeoutMs: 60000,
+});
+if (reason === "complete") { /* download.filename 是落盘路径 */ }
+```
+
+### Chrome 下载拦截（隐蔽坑）
+
+Chrome 有**自动下载保护**：点击下载后，文件可能被浏览器**静默拦截**（顶部出现
+"xxx 已被拦截 / [保留危险文件]"黄色提示条），用户必须在浏览器 UI **手动点"保留"**
+才真正落盘。
+
+**这个拦截藏在浏览器 UI 层，不在页面 DOM 里**——页面 evaluate / snapshot / innerText 都读不到
+这条提示。表现就是"点了下载但文件迟迟不出现"。往往要靠人眼看浏览器才发现。
+
+判定: 点下载后轮询下载目录——文件出现且 size 稳定 = 成功；超时未出现 = 可能被拦截，
+**截图取证**（整页截图能拍下浏览器顶部的拦截条，人能从截图看到）+ 报告用户"下载超时，可能
+被浏览器拦截，请打开浏览器点[保留危险文件]"。
+
+**绝不在 flow 里尝试关闭 Chrome 安全下载保护**——那是用户安全设置，只能通知，不能改。
+
+## 探查留痕:配合 cateye-probe（推荐, 非本包依赖）
+
+探查的价值不只是"这次探出来了", 更是**过程可回溯**——事后能重建"当时怎么一步步探出来的、
+每步页面的反应是什么"。采集审计、bug 复现、问题排查都依赖这个。
+
+**[cateye-probe](https://www.npmjs.com/package/cateye-probe)** 是一个独立的 trace 工具（npm 包），
+能把探查过程结构化留痕：事件流（events.ndjson）+ 三态结果（pass/fail/skip）+ 产物附件（截图/数据）。
+它和 BrowserClient 是**天然搭档**：browser 做探查动作，cateye-probe 记录反应。
+
+> cateye-probe 是**可选推荐**，不是 `@mooncat/browser` 的依赖。不需要它也能探查（手动 fs 落盘
+> 即可）；需要可回溯 trace 时推荐搭配。两者都是独立包，互不耦合。
+
+### 分工
+
+| | 职责 | 来源 |
+|---|---|---|
+| browser | 决定做什么探查（导航/交互/读取），执行动作 | `@mooncat/browser` 的 `BrowserClient` |
+| cateye-probe | 把过程留痕（事件流/结果/产物） | 独立 npm 包 `cateye-probe`（`import { probe } from "cateye-probe/sdk"`） |
+
+### 组合范式骨架
+
+一个探查脚本里：browser 做动作，probe 在关键节点写痕迹。每个 step 问一个问题、留一段 trace。
+
+```ts
+import { BrowserClient } from "@mooncat/browser";
+import { probe } from "cateye-probe/sdk";   // 可选搭配, 独立包
+import { writeFileSync } from "node:fs";
+
+const browser = new BrowserClient({ baseUrl: "http://127.0.0.1:17322" });
+
+const done = probe.section("采集订单");          // 结构化段落
+
+await browser.open({ headless: false });
+const tab = await browser.newTab({ url: "https://example.com/orders" });
+const page = tab.pageHandle;
+await browser.operate({
+  pageHandle: page, action: "waitForSelector",
+  params: { selector: "#orders-table", timeout: 15000 },
+});
+
+const snap = await browser.operate({ pageHandle: page, action: "snapshot" });
+probe.metric("rows", String(snap.yaml).split("\n").length);   // 指标
+
+const shot = await browser.operate({ pageHandle: page, action: "screenshot" });
+writeFileSync("./tmp_shot.png", Buffer.from(shot.dataUrl.split(",")[1], "base64"));
+probe.attach("订单页截图", "./tmp_shot.png", "orders.png");   // 产物进 probe artifacts
+
+done();
+probe.pass("订单采集完成");                                    // 三态结果
+```
+
+### 探查长会话分阶段（trace 驱动的探查节奏）
+
+cateye-probe 的 session 天生分阶段——一个 session 跨多个 step，每个 step 问一个问题。
+**严禁把"开页面+导航+探查+截图"全塞进单个 step，然后每个 step 都重开页面**。那是把分阶段的
+step 退化成一次性脚本，白费了长会话。
+
+**正确模型**：前面的 step 把页面开好 + 导航到位（状态留在浏览器），后面的 step 直接
+**复用同一个 tab**（`browser.listTabs()` 按 url 匹配找到已开的 tab，拿它的 pageHandle）
+继续探下一个问题，不重开。浏览器状态跨 step 持久——这才是长会话的意义。
+
+> 高危平台（淘宝/京东/生意参谋）这是**安全红线**：反复 newTab+导航 = 高频异常访问 =
+> 加速风控触发。同一个页面一旦打开，在 session 内反复复用。详见 [high-risk.md](high-risk.md)。
+
+### 何时用这个组合
+
+- **要留 trace**：探查过程要给人/AI 事后回溯（采集审计、bug 复现、问题排查）→ 用组合
+- **一次操作即可**：随手打开页面看一眼、单次截图 → 直接 browser，不必套 cateye-probe
+
+browser 的调用纪律（步进 co-work / 长会话 / 路由不泄漏）见 [SKILL.md](../SKILL.md)，
+cateye-probe 的 API 与 session 管理见其包文档。本节只讲两者怎么在脚本里组合。