# 浏览器运行铁律（小红书）

所有网页操作走 clclaw 的 `browser` 工具。小红书对自动化敏感，下面是为"稳 + 抗风控 + 省 token"定的硬规矩。

## 工具映射（别手搓 shell）

| 要做的事 | 用 |
|---|---|
| 打开页面 | `browser{action:"open", url:"..."}` |
| **抽数据（首选）** | `browser{action:"eval", js:"..."}` |
| 看清页面结构/拿可点元素 ref | `browser{action:"snapshot"}`（节制使用） |
| 点/输入 | `browser{action:"act", kind:"click"/"fill", ref, text}` |
| 看一眼当前画面 | `browser{action:"screenshot"}`（更省的是 eval） |
| 等待 | `browser{action:"wait", ms}` 或 `until` |
| 登录 / 环境 | `browser{action:"login"/"status"}` |

## 省 token：eval 优先，snapshot 节制

- **能 `eval` 拿到的就别 `snapshot`**：eval 直接返回结构化文本，snapshot 是整棵树、又长又费 token。
- `snapshot` 只在**关键转场**用：确认登录成功、进到笔记详情页、确认搜索结果出来了。
- **不要整页截图**除非用户明确要看画面。

## 进笔记的正确姿势（重要）

- **从搜索结果卡片点进去**，不要自己拼 `/explore/<id>` 直接导航——直链经常 404 或触发校验。
- 流程：`open` 搜索页 → `eval`/`snapshot` 拿到结果卡片 → `act` 点卡片**本体**（别点作者头像，会跳去作者页）。
- 进去先核验：不是 404、有正文、有可见的点赞/评论区，再开始抽数据。

## 采样时的过滤

- 分析"别人/赛道"时，**跳过账号主自己**的笔记。
- 优先采**高互动**样本；留意"收藏 > 点赞"和"评论区高频提问"的笔记，信息量最大。

## 出错就降级，别硬刚（抗风控核心）

- 单步操作**最多重试 1 次**。
- 点击/进页**连续失败 2 次或遇 404** → 回到搜索结果，换下一条，别在同一个上死磕。
- 报"no tab"/页面崩了 → 先 `browser{action:"status"}` 看会话，必要时重新 `open`。
- **出现异常先告诉用户再继续**，不要默默乱试。遇到登录态失效/验证码，停下让用户处理，绝不自动绕验证。
- 节奏放慢、headed 模式（`browser` 默认就是），别像压测一样连发动作。

### 触发风控/校验（关键，open 后必看落地 URL）

`open` 后**先看真实落地 URL**（`browser{action:"eval", js:"(()=>location.href)()"}`，注意要用 IIFE 自调用、否则只返回函数），出现这些就别硬抽：

- `website-login/error?...error_code=300012`（"IP 存在风险，请切换可靠网络环境后重试"）：**风控拦截**。实测它是**间歇的、不是稳定硬墙**——触发点是**自动化指纹**而非 IP（同机 Safari 一直能开）。**clclaw 的 `browser` 工具已默认抗指纹**：open/login 启动浏览器时注入 `--disable-blink-features=AutomationControlled`，使 `navigator.webdriver=false`（2026-06-16 实测：加这个 flag 后打开 explore 不再撞 300012、能稳定抽到卡片）。所以**正常情况你不用做额外动作**，工具已托底。若<b>仍</b>偶发被拦（频繁请求/冷启动首帧）：放慢节奏、过几秒重试一次即可；连续多次仍拦再停下告诉用户"稍等重试，或换网络/换 IP/关代理"，**别在同一秒反复刷**（越刷越容易被持续拦）。
  - 自查指纹是否生效：`browser{action:"eval", js:"navigator.webdriver"}` 应返回 `false`。若返回 `true`，多半是浏览器是更早残留进程冷启动的——`browser{action:"close"}` 后重新 `open` 即可让抗风控参数重新生效。
- `404?...error_code=300031`（"当前笔记暂时无法浏览"）：**直链笔记被拦**——直接 `open` 拼的 `/explore/<id>` 缺 `xsec_token`，必被这个 404 挡。**必须从列表/搜索结果点卡片进**（见上"进笔记的正确姿势"），不是换选择器能解决的。

判定后**立即停下先告诉用户**，不要继续 `eval`/`snapshot`/重试刷。

## 数据可信度

抽取依赖 CSS 选择器，小红书改版会让选择器失效。**抽不到就如实报"没抽到"**，不要编数字；
关键结论附"建议人工核对"。具体抽取写法见 `eval-patterns.md`。