feat(web-access): v3.0 内置浏览器能力面同步——删除 Python Playwright 回落（S31） (#85)

## 变更内容 / What 浏览器升级计划 S31 最终验收信号：web-access 技能与内置受管浏览器新能力面对齐，**删除「用户手工启动调试 Chrome + Python Playwright」回落路径**。 - **删除回落路径**：Prerequisites: Chrome CDP Setup、Layer 3 CDP Browser（Python Playwright 模板）、Installation Note（pip install playwright）整段删除；references/cdp-browser.md 文件删除；jina-reader.md 的 CDP 引用改为 page.extract-text - **订正陈旧断言**： - 「没有批量取文通道」→ BrowserSnapshot mode:text / page.extract-text（maxBytes/cursor 分页，超出截断给 nextCursor） - 「page.evaluate 基本不可用」→ 返回真实值（expression/awaitPromise，超预算截断标 truncated）；仍走人工闸门 - 「截图前必须 tab.activate / 串行截图 / BROWSER_TAB_HOST_NOT_FOUND」→ S36 订正：Agent 单标签会话免 activate；多标签后台 tab 秒级报 BROWSER_VIEWPORT_UNAVAILABLE；命令超时只 stop 不 close，标签页可重试 - 「accessibility 超限即失败」→ 尊重 depth + maxBytes 截断翻页（S8） - 「只有整页截图」→ clip{x,y,width,height,scale≤4} + captureBeyondViewport - **provides.tools 加 BrowserScript**（code-mode；信任级别等同 Bash） - **新增选用规则（D4 唯一约束机制）**：反检测站点一律优先 input.*（#1808 输入拟真 + 身份一致性）；page.element 写类仅用于表单批量填充等站点不检测场景；JS 直调 el.click() 为禁止回退 - **新增 fetch.browser 配方**：page.evaluate 页面上下文跑 fetch（带 origin Cookie、同 origin、受 Grant origins 约束）——登录态取站内接口的正解 - **能力速查**：page.element 九 op / page.wait 九 until / inline wait 块 / loc= 方言 / BrowserScript / 跨源 iframe 快照（S35） - **版本** 2.2.1 → 3.0.0（删除回落层为 breaking）；source_hash 重算；required_client_version 维持 10.0.98（新能力在正文标注 10.0.112+） ## Why v2.x 时代回落路径存在的每一条理由（无批量取文、evaluate 不可用、截图必须串行 activate）均已被 S2–S14/S35/S36 覆盖；文档继续引导用户手工起调试 Chrome 会误导新 Agent 走已废弃路径。双语同步修改（SKILL.md / SKILL.zh-CN.md heading 数一致，i18n-validate 通过）。 - [x] CLA
2026-09-05 19:23:51 +08:00 · 2026-08-17 01:25:46 -04:00
parent 43239669e5
commit 0d4d7b208b
5 changed files with 482 additions and 868 deletions
--- a/skills/web-access/SKILL.zh-CN.md
+++ b/skills/web-access/SKILL.zh-CN.md
@@ -4,28 +4,30 @@

 ## L0：一句话摘要

-四层联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器登录态访问（v2.1）、Python Playwright CDP 兜底。
+三层联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器完成登录态访问与交互（v3.0 起取文/等待/脚本全部内置，不再需要 Python Playwright 兜底）。

 ## L1：概述与使用场景

 ### 能力描述

-web-access 是一个**流程型技能（Procedural Skill）**，提供四层互补的联网访问能力：
+web-access 是一个**流程型技能（Procedural Skill）**，提供三层互补的联网访问能力：

 - **L1**（WebSearch + WebFetch）：公开页面，轻量
 - **L2**（Jina Reader）：JS 渲染的重页面，默认节省 Token
- **L3-fast**（内置受管浏览器，**v2.1 重写**）：到达并*操作*登录态/交互站点——每个任务独立 BrowserSpace 隔离、零 Python 依赖、每次动作都有可审计回执。**抽取长正文仍归 L2 / L3-fallback**，见下方取文说明
- **L3-fallback**（Chrome CDP + Python Playwright）：复杂自动化场景兜底（长等待、特殊 race condition 等）
+- **L3**（内置受管浏览器，v3.0 能力面补全）：到达、操作并**读取**登录态/交互站点——每个任务独立 BrowserSpace 隔离、零 Python 依赖、每次动作都有可审计回执。批量取文（`page.extract-text`）、判别式等待（`page.wait`）、代码模式（`BrowserScript`）都在本层内闭环

-### v2.1 重写：内置受管浏览器（默认隐藏，激活后才暴露）
+v2.x 时代的第四层「用户手工启动调试 Chrome + Python Playwright CDP」已在 v3.0 移除：它依赖的每一条理由（无批量取文通道、evaluate 不可用、截图必须串行 activate）都被内置浏览器的新能力覆盖，见下方速查。

-调用 `Skill('web-access')` 加载本技能时，以下 8 个工具被注入到当前会话，让 LLM 直接驱动内置浏览器：
+### v3.0：内置受管浏览器（默认隐藏，激活后才暴露）
+
+调用 `Skill('web-access')` 加载本技能时，以下 9 个工具被注入到当前会话，让 LLM 直接驱动内置浏览器：

 | 工具 | 用途 |
 |------|------|
 | BrowserManage | 建/销隔离 BrowserSpace、启动会话、管理标签页 |
-| BrowserSnapshot | `semantic` / `accessibility` / `visual` 快照——读页面的主通道 |
-| BrowserAct | 一次调用一个受管动作：导航、点击、输入、滚动、截图…… |
+| BrowserSnapshot | `semantic` / `text` / `accessibility` / `visual` 四种快照——读页面的主通道 |
+| BrowserAct | 一次调用一个受管动作：导航、输入、取文、等待、元素操作、截图…… |
+| BrowserScript | **代码模式**：一段异步 JS 连续下发浏览器命令，消除逐动作往返（信任级别等同 Bash） |
 | BrowserImport | 从用户 Chrome/Edge/Firefox/Safari 配置导入 Cookie（需人工审批；**还需 Host 授予 `browser.import.*`，普通 `create_space` 会话拿不到**） |
 | BrowserShare | 把 Space/Session 委派给其他 Agent（隔离 / 快照 / 写时复制 / 实时共享） |
 | SitePatternRead / SitePatternWrite | 按域名累积"站点经验"（AgentFS 三层） |
@@ -33,20 +35,22 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供四层互

 > **重要**：未调用 Skill('web-access') 之前，这些工具**不会**出现在 LLM 的 tools 列表里——默认对话不消耗其 token。详见 [references/browser-tools.md](references/browser-tools.md)。
 >
-> **v2.1 已移除**：`BrowserListTabs` / `BrowserNavigate` / `BrowserEval` / `BrowserClick` / `BrowserScreenshot` / `BrowserScroll` / `BrowserSetFiles` / `BrowserCloseTab` 及其背后的 cdp-proxy 已停用，调用会返回「该旧 BrowserXxx/cdp-proxy 入口已停用」。本版要求客户端 v10.0.98+。
+> **v2.1 已移除**：`BrowserListTabs` / `BrowserNavigate` / `BrowserEval` / `BrowserClick` / `BrowserScreenshot` / `BrowserScroll` / `BrowserSetFiles` / `BrowserCloseTab` 及其背后的 cdp-proxy 已停用，调用会返回「该旧 BrowserXxx/cdp-proxy 入口已停用」。本版要求客户端 v10.0.98+；`page.extract-text` / `page.element` / `page.wait` / 内联 wait 块 / 跨源 iframe 快照需 v10.0.112+，`BrowserScript` 需包含 S17/S18 的更新版本。

 ### 使用场景

 - 用户需要搜索当前信息或研究特定主题
 - 用户需要抓取公开网页内容或技术文档
- 用户需要访问登录态站点（小红书、B站、微博、飞书、Twitter 等）
+- 用户需要访问登录态站点（小红书、B站、微博、飞书、Twitter 等）并**读出正文**
+- 用户需要在登录态下调站内接口取数（列表、评论、订单等）
 - 用户需要对比产品、聚合新闻或调查 API/库版本

 ### 核心价值

- **四层递进**：从轻量搜索到重度 JS 渲染到登录态访问，按需选择
- **Token 优化**：Jina Reader 默认减少 50-80% Token 消耗
- **登录态复用**：兜底层 CDP 连用户 Chrome，或在 Host 已授予 `browser.import.*` 时用 BrowserImport 把 Cookie 导入隔离 Space；两条路都不必重新登录
+- **三层递进**：从轻量搜索到重度 JS 渲染到登录态访问，按需选择
+- **Token 优化**：Jina Reader 默认减少 50-80% Token 消耗；`page.extract-text` 的 maxBytes/cursor 分页让登录态长文也可控
+- **登录态复用**：Host 授予 `browser.import.*` 时用 BrowserImport 把 Cookie 导入隔离 Space，不必重新登录
+- **零外部依赖**：不再要求 Python/Playwright 安装，也不再要求用户手工启动调试 Chrome

 ## L2：详细规范

@@ -58,53 +62,6 @@ When you complete a research task, you **MUST** cite all source URLs in your res

 If any fetch fails, explicitly tell the user which URL failed and which fallback you used.

---
-
-## Prerequisites: Chrome CDP Setup (for login-gated sites)
-
-**L3-fallback 层（Python Playwright）必需**，实际上也仍是复用登录态最稳的一条路。L3-fast 内置浏览器只有在 Host 已授予 `browser.import.*`、`BrowserImport` 真能用的前提下才可以跳过这一步；否则照样要配。
-
-### One-time setup
-
-Launch a dedicated Chrome instance with remote debugging enabled:
-
-**macOS**:
-```bash
-/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
-  --remote-debugging-port=9222 \
-  --user-data-dir="${DESIRECORE_ROOT}/chrome-profile"
-```
-
-**Linux**:
-```bash
-google-chrome \
-  --remote-debugging-port=9222 \
-  --user-data-dir="${DESIRECORE_ROOT}/chrome-profile"
-```
-
-**Windows (PowerShell)**:
-```powershell
-& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
-  --remote-debugging-port=9222 `
-  --user-data-dir="$env:USERPROFILE\.desirecore\chrome-profile"
-```
-
-After launch:
-1. Manually log in to the sites you need (小红书、B站、微博、飞书 …)
-2. Leave this Chrome window open in the background
-3. Verify the debug endpoint: `curl -s http://localhost:9222/json/version` should return JSON
-
-### Verify CDP is ready
-
-Before any CDP operation, always run:
-```bash
-curl -s http://localhost:9222/json/version | python3 -c "import sys,json; d=json.load(sys.stdin); print('CDP ready:', d.get('Browser'))"
-```
-
-If the command fails, tell the user: "请先启动 Chrome 并开启远程调试端口（见 web-access 技能的 Prerequisites 部分）。"
-
---
-
 ## Tool Selection Decision Tree

 ```
@@ -121,12 +78,12 @@ User intent
  │          (Jina Reader = default for JS-rendered content, saves tokens)
  │
  ├─ "Read this login-gated page" (小红书/B站/微博/飞书/Twitter/知乎/公众号)
-  │     ├─→ 到达：BrowserManage(create_space/start_session) → BrowserAct(tab.navigate)
-  │     │        → tab.activate + page.screenshot 确认落到正文页
-  │     │          （semantic 快照不含正文，不能用来读内容）
-  │     │          要登录态：仅在已授予 browser.import.* 时用 BrowserImport，否则走下面的 CDP
-  │     └─→ 取正文：确认 CDP 就绪后 python3 playwright.connect_over_cdp()
-  │              → page.content() → Jina Reader / BeautifulSoup
+  │     └─→ BrowserManage(create_space/start_session) → BrowserAct(tab.navigate)
+  │         → BrowserAct(page.extract-text)          ← 正文直接读出，支持 maxBytes/cursor 分页
+  │         要登录态：仅在已授予 browser.import.* 时用 BrowserImport
+  │
+  ├─ "Pull data from the site's API in a logged-in context"
+  │     └─→ fetch.browser 配方：BrowserAct(page.evaluate) 里跑 fetch（带该 origin 的 Cookie）
  │
  ├─ "API documentation / GitHub / npm package info"
  │     └─→ Prefer official API endpoints over scraping HTML:
@@ -135,24 +92,19 @@ User intent
  │          - PyPI:   curl https://pypi.org/pypi/<pkg>/json
  │
  └─ "Real-time interactive task" (click, fill form, scroll, screenshot)
-        ├─→ **Default: 内置受管浏览器** (BrowserManage → BrowserAct → BrowserSnapshot —
-        │     see references/browser-tools.md, no Python needed)
-        └─→ Fallback: CDP + Python Playwright (references/cdp-browser.md) when 内置浏览器 is insufficient
-            (e.g., complex race conditions, multi-event waits, long-running in-browser scripts)
+        └─→ 内置受管浏览器 (BrowserManage → BrowserAct → BrowserSnapshot —
+             see references/browser-tools.md, no Python needed)
 ```

-### 四层策略总结
+### 三层策略总结

 | Layer | Use case | Primary tool | Token cost |
 |-------|----------|--------------|------------|
 | L1 | Public, static | `WebFetch` | Low |
 | L2 | JS-heavy, long articles, token savings | `Bash curl r.jina.ai` | **Lowest** (Markdown pre-cleaned) |
-| **L3-fast** | **登录态导航与交互 (PRIMARY)** | **内置受管浏览器（BrowserManage / BrowserAct / BrowserSnapshot）** | Medium |
-| L3-fallback | 复杂自动化（race / long-wait / 自定义脚本） | `Bash + Python Playwright CDP` | Medium |
+| **L3** | **登录态导航、交互与取文 (PRIMARY)** | **内置受管浏览器（BrowserManage / BrowserAct / BrowserSnapshot / BrowserScript）** | Medium |

-**Default priority**: L1 for simple public pages → L2 for heavy → **L3-fast for login-gated** → L3-fallback only when 内置浏览器不够用。
-
---
+**Default priority**: L1 for simple public pages → L2 for heavy → **L3 for login-gated（含正文与站内接口取数）**。

 ## Supported Sites Matrix

@@ -162,16 +114,14 @@ User intent
 | GitHub README, issues, PRs | `gh api` (best) → L1 WebFetch | Prefer API |
 | Hacker News, Reddit | L1 WebFetch | Public content |
 | Medium, Dev.to | L2 Jina Reader | JS-rendered, member gates |
-| Twitter/X | L3 CDP (or L2 Jina with `x.com`) | Login required for full thread |
-| 小红书 (xiaohongshu.com) | L3 CDP | 强制登录 |
-| B站 (bilibili.com) | L3 CDP | 视频描述/评论需登录 |
-| 微博 (weibo.com) | L3 CDP | 长微博需登录 |
-| 知乎 (zhihu.com) | L3 CDP | 长文+评论需登录 |
-| 飞书文档 (feishu.cn) | L3 CDP | 必须登录 |
+| Twitter/X | L3（或 L2 Jina with `x.com`） | Login required for full thread |
+| 小红书 (xiaohongshu.com) | L3 内置浏览器 + BrowserImport | 强制登录；正文走 page.extract-text |
+| B站 (bilibili.com) | L3 内置浏览器 + BrowserImport | 视频描述/评论需登录 |
+| 微博 (weibo.com) | L3 内置浏览器 + BrowserImport | 长微博需登录 |
+| 知乎 (zhihu.com) | L3 内置浏览器 + BrowserImport | 长文+评论需登录 |
+| 飞书文档 (feishu.cn) | L3 内置浏览器 + BrowserImport | 必须登录 |
 | 公众号 (mp.weixin.qq.com) | L2 Jina Reader | 通常公开，Jina 处理更干净 |
-| LinkedIn | L3 CDP | 登录墙 |
-
---
+| LinkedIn | L3 内置浏览器 + BrowserImport | 登录墙 |

 ## Tool Reference

@@ -194,11 +144,11 @@ WebFetch(url="https://example.com/article")
 Tips:
 - Results cached for 15 min
 - Returns cleaned Markdown with title + URL + body
- If body < 200 chars or looks garbled → escalate to Layer 2 (Jina) or Layer 3 (CDP)
+- If body < 200 chars or looks garbled → escalate to Layer 2 (Jina) or Layer 3 (built-in browser)

-### Layer 2: Jina Reader (default for heavy pages)
+### Layer 2: Jina Reader（重页默认）

-Jina Reader (`r.jina.ai`) is a free public proxy that renders pages server-side and returns clean Markdown. Use it as the **default** for any page where WebFetch produces garbled or truncated output, and as the **preferred** extractor for JS-heavy SPAs.
+Jina Reader (`r.jina.ai`) 免费公共代理，服务端渲染页面并返回干净 Markdown。WebFetch 输出乱码/截断时的默认升级路径，JS 重页面的首选抓取器。

 ```bash
 curl -sL "https://r.jina.ai/https://example.com/article"
@@ -212,111 +162,93 @@ Why Jina is the default token-saver:

 See [references/jina-reader.md](references/jina-reader.md) for advanced endpoints and rate limits.

-### Layer 3: CDP Browser (login-gated access)
+### Layer 3: 内置受管浏览器（登录态与交互）

-Use Python Playwright's `connect_over_cdp()` to attach to the user's running Chrome (which already has login cookies). **No re-login needed.**
+完整命令面、能力档位与边界条件见 [references/browser-tools.md](references/browser-tools.md)。这里的循环是：

-**Minimal template**:
-```bash
-python3 << 'PY'
-from playwright.sync_api import sync_playwright
+1. `BrowserManage(create_space)` → `BrowserManage(start_session)` 拿 sessionId + 首个 tab
+2. 需要登录态 → `BrowserImport`（仅当 Host 已授予 `browser.import.*`；没有这层授权就无法复用用户 Cookie，告诉用户并按无登录态继续或放弃）
+3. `BrowserAct(tab.navigate)` 到达页面
+4. `BrowserSnapshot(semantic)` 拿可交互元素 `ref`（跨源 iframe 的元素也在同一棵树里，ref 全局连续编号）
+5. 交互用 `input.*`（拟真轨迹）或 `page.element`（表单批量写）；等结果用 `page.wait` 或内联 wait 块
+6. 取正文用 `BrowserSnapshot(text)` 或 `BrowserAct(page.extract-text)`；取接口数据用 fetch.browser 配方
+7. 任务收尾 `BrowserManage(close_session)`

-TARGET_URL = "https://www.xiaohongshu.com/explore/..."
+多动作连续编排（导航→快照→点击→等待→取文）可用 `BrowserScript` 一段脚本完成，省去逐动作 IPC 往返。

-with sync_playwright() as p:
-    browser = p.chromium.connect_over_cdp("http://localhost:9222")
-    context = browser.contexts[0]  # reuse user's default context (has cookies)
-    page = context.new_page()
-    page.goto(TARGET_URL, wait_until="domcontentloaded")
-    page.wait_for_timeout(2000)  # let lazy content load
-    html = page.content()
-    page.close()
+## L3 速查（v3.0）

-# Print first 500 chars to verify
-print(html[:500])
-PY
-```
-
-**Extract text via BeautifulSoup** (no Jina round-trip):
-```bash
-python3 << 'PY'
-from playwright.sync_api import sync_playwright
-from bs4 import BeautifulSoup
-
-with sync_playwright() as p:
-    browser = p.chromium.connect_over_cdp("http://localhost:9222")
-    page = browser.contexts[0].new_page()
-    page.goto("https://www.bilibili.com/video/BV...", wait_until="networkidle")
-    html = page.content()
-    page.close()
-
-soup = BeautifulSoup(html, "html.parser")
-title = soup.select_one("h1.video-title")
-desc = soup.select_one(".video-desc")
-print("Title:", title.get_text(strip=True) if title else "N/A")
-print("Desc:",  desc.get_text(strip=True)  if desc  else "N/A")
-PY
-```
-
-See [references/cdp-browser.md](references/cdp-browser.md) for:
- Per-site selectors (小红书/B站/微博/知乎/飞书)
- Scrolling & lazy-load patterns
- Screenshot & form-fill recipes
- Troubleshooting connection issues
-
---
-
-## L3-fast: 内置受管浏览器速查（v2.1）
-
-**只在你调用 `Skill('web-access')` 加载本技能后，下面这组工具才会出现在 tools[] 里。**
-
-| 工具 | 一行示例 |
-|------|---------|
-| `BrowserManage({ action: 'create_space', name, persistence: 'ephemeral' })` | 每个任务一个隔离 Space |
-| `BrowserManage({ action: 'start_session', spaceId, capabilities })` | 启动会话，返回 sessionId 与首个标签页 |
-| `BrowserManage({ action: 'list_tabs' \| 'create_tab' \| 'close_session' })` | 标签页与生命周期管理 |
-| `BrowserAct({ action: 'tab.navigate', params: { url } })` | 当前标签页导航 |
-| `BrowserSnapshot({ mode: 'semantic' })` | 读页面：可交互元素 + `ref` 句柄 |
-| `BrowserAct({ action: 'input.click', params: { ref } })` | 按快照 `ref` 点击，不要用裸 x/y |
-| `BrowserAct({ action: 'input.text', params: { text } })` | 向聚焦元素输入文本 |
-| `BrowserAct({ action: 'input.wheel', params: { x: 640, y: 400, deltaX: 0, deltaY: 720 } })` | 滚动触发懒加载 —— `x`/`y`（或 `ref`）**必填**，且会话要带 `browser.input.pointer.wheel` |
-| `BrowserAct({ action: 'tab.activate', params: { bounds } })` → `page.screenshot` | **先 activate 再截图** |
-| `BrowserImport({ action: 'discover' \| 'create_plan' \| 'dry_run' \| 'apply' \| 'rollback' \| 'list_plans' })` | 复用用户登录态 Cookie —— 这 6 个就是**全部**动作，主流程走 `discover → create_plan → dry_run → apply`。**需要 `browser.import.*`，而 `create_space` 不会授予**（见下） |
-
-完整 API 与边界条件见 [references/browser-tools.md](references/browser-tools.md)。
-
-**怎么读页面** —— 按需求选通道：
+### 读页面：按需求选通道

 | 你要什么 | 用什么 | 说明 |
 |----------|--------|------|
-| 可交互元素 + `ref` 句柄 | `BrowserSnapshot({ mode: 'semantic' })` | 只有按钮/输入框/链接，**不含正文文本** |
-| 小页面的正文 | `BrowserSnapshot({ mode: 'accessibility' })` | 返回 StaticText 节点；真实内容页会报 `BROWSER_RESULT_TOO_LARGE`（结果上限 2 MB，且 `depth` 参数当前被宿主忽略） |
-| 真实页面的正文 | L2 Jina Reader（公开页）或 L3-fallback Playwright（登录态） | 内置浏览器目前没有可用的批量取文通道 |
-| 页面长什么样 | `tab.activate` → `BrowserAct({ action: 'page.screenshot' })` | 只有整页截图，靠看图读 |
+| 可交互元素 + `ref` / `loc=` 句柄 | `BrowserSnapshot({ mode: 'semantic' })` | 按钮/输入框/链接 + 每行 `[ref=eN]` 与（能产出时）`[loc=...]` 稳定选择器；跨源 iframe 元素同树 |
+| 页面正文 | `BrowserSnapshot({ mode: 'text' })` 或 `BrowserAct({ action: 'page.extract-text' })` | markdown/text 两种格式；超 maxBytes 截断并给 nextCursor 续读（cursor 分页），不报错 |
+| 辅助功能树 | `BrowserSnapshot({ mode: 'accessibility' })` | 尊重 `depth`（默认 50 上限 100）与 maxBytes 预算，超出截断+翻页，不再整体报错 |
+| 页面长什么样 | `BrowserSnapshot({ mode: 'visual' })` 或 `BrowserAct({ action: 'page.screenshot' })` | 像素直接进结果（视觉模型当场看）；支持 `clip={x,y,width,height,scale}` 元素级裁剪放大（scale 最大 4）与 `captureBeyondViewport` 整页截图 |

-`page.evaluate` **不是**取文通道：每次调用需人工审批，且字符串/对象返回值会被替换成 `[REDACTED:browser-runtime-value]`。
+### 命令面速览
+
+`BrowserAct` 的 `action` 按用途分组（完整枚举见工具 schema）：
+
+- **tab.***：`navigate` / `back` / `forward` / `reload` / `activate` / `close`
+- **input.***：`move` / `click` / `double-click` / `drag` / `wheel` / `touch` / `pinch` / `key` / `text` —— 走输入拟真（#1808：UA/UA-CH 身份一致 + 真实轨迹），反检测站点的交互首选
+- **page.element**（判别式 op × selector，九 op）：写类 `fill` / `select-option` / `check` / `uncheck` / `scroll-into-view`；读类 `get-attribute` / `bounding-box` / `count` / `all-inner-texts`。selector 说 `loc=` 方言或快照 `ref`（配 snapshotId）。`fill` 拒绝 `input[type=password]`
+- **page.wait**（判别式 until，九种）：轮询型 `load` / `domcontentloaded` / `networkidle` / `selector` / `url` / `timeout` 超时返回 `waited:false`；事件型 `request` / `response` / `download` 超时抛错。默认 10s、上限 60s
+- **内联 wait 块**：`tab.navigate` / `input.click` / `input.key` / `page.element{op:"fill"}` 的 `params.wait`（形态与 page.wait 同构）——一条回执完成「动作→等结果」，等待器先于动作注册，无跨 IPC 竞态
+- **page.evaluate**：`{ expression, awaitPromise }`，返回值原样过界（超预算截断并标 `truncated`，不抛错）；能力档 `browser.page.evaluate` 走人工闸门（allow-all 模式免卡片）
+- **page.extract-text / page.screenshot / page.wait**：见上表与 fetch.browser 配方
+
+`loc=` 选择器方言（S7/S9）：`e<序号>`（须配签发该 ref 的快照 snapshotId）、`loc=css:` / `loc=role:` / `loc=text:` / `loc=testid:`、裸 CSS，可叠 `internal:nth/last/scope/filter`。未知前缀显式报错，绝不静默降级。
+
+### 交互通道选用：input.* vs page.element
+
+- **反检测站点（小红书/微博/B站等）一律优先 `input.*`**：走 #1808 的输入行为拟真（坐标派发、拟真轨迹、可视化可审计），配套身份一致性层让 UA/UA-CH 不带 Electron/Headless 痕迹
+- **`page.element` 写类适用于表单批量填充等站点不检测的场景**：一次调用完成 fill/select-option/check，比逐元素 input.click+input.text 快得多
+- **红线**：`page.element` 刻意不含 click——指针动作必须走 `input.*`，用 JS 直调 `el.click()` 会绕开全部拟真投入，属于明确禁止的回退
+
+### fetch.browser 配方：带登录态取接口数据
+
+登录态下取站内接口（列表、评论、订单等 JSON）的正解：在**页面上下文**里跑 `fetch`——自动带该 origin 的 Cookie，同 origin、受 Grant origins 约束，走 `page.evaluate` 已有闸门。这是 `BrowserAct({ action: 'page.evaluate' })` 的封装用法：
+
+```yaml
+BrowserAct:
+  action: page.evaluate
+  params:
+    expression: |
+      fetch('/api/v1/comments?page=1&size=20', {
+        headers: { accept: 'application/json' }
+      }).then(r => r.text())
+    awaitPromise: true        # 默认 true；表达式返回 Promise 时等它 settle
+```
+
+要点：
+- 先 `tab.navigate` 到该站任意页面（建立 origin 与 Cookie），再发 fetch；路径写相对路径，天然同 origin
+- 返回值原样过界；大 JSON 用 `.text()` 拿原文自己截取，或分页多次取
+- 只能访问当前 tab origin（Grant origins 约束）；跨站接口请先导航过去
+- `page.evaluate` 属人工闸门能力：非 allow-all 模式会弹审批卡，向用户说明用途即可

 ### 推荐流程（小红书示例）

 ```
 1. BrowserManage({ action: 'create_space', name: 'xhs-note', persistence: 'ephemeral' })
 2. BrowserManage({ action: 'start_session', spaceId, capabilities: [...] })
-   ← 显式列表是做减法；要滚动就必须把 browser.input.pointer.wheel 列进去
-3. 复用登录态：默认走 L3-fallback Playwright 连用户自己的 Chrome。
-   BrowserImport({ action: 'discover' → 'create_plan' → 'dry_run' → 'apply' }) 只有在 Host 另行
-   授予 browser.import.* 时才走得通 —— 光靠 create_space 拿不到；被拒就直接回落。
+   ← 显式列表是做减法；要滚动就把 browser.input.pointer.wheel 列进去，
+     要取文就带 browser.observe.snapshot
+3. 复用登录态：仅在 Host 已授予 browser.import.* 时走
+   BrowserImport({ action: 'discover' → 'create_plan' → 'dry_run' → 'apply' })。
+   没有这层授权就无法复用用户 Cookie——如实告诉用户，按无登录态继续或放弃。
 4. BrowserAct({ action: 'tab.navigate', params: { url: 'https://www.xiaohongshu.com/explore/abc123' } })
-5. BrowserSnapshot({ mode: 'semantic' })   ← 只拿交互用的元素 ref（不含正文）
-   tab.activate + page.screenshot           ← 确认确实渲染出了笔记
-   → 正文抽取走 L3-fallback Playwright
-6. SitePatternRead({ domain: 'xiaohongshu.com' })  ← 读累积经验
-7. 任务结束 → BrowserManage({ action: 'close_session', sessionId })
-8. 如发现新陷阱 → SitePatternWrite({ domain, scope: 'agent', mode: 'merge', content })
+5. BrowserSnapshot({ mode: 'semantic' })        ← 拿交互元素 ref（跨源 iframe 同树）
+6. BrowserAct({ action: 'page.extract-text', params: { format: 'markdown' } })
+   ← 正文直接读出；太长就传上一页返回的 nextCursor 续读
+7. 需要确认渲染效果 → BrowserSnapshot({ mode: 'visual' })（像素直接可看）
+8. SitePatternRead({ domain: 'xiaohongshu.com' })  ← 读累积经验
+9. 任务结束 → BrowserManage({ action: 'close_session', sessionId })
+10. 如发现新陷阱 → SitePatternWrite({ domain, scope: 'agent', mode: 'merge', content })
 ```

---
-
-## 站点经验积累（v2.0 新增）
+## 站点经验积累

 任务结束如果发现新的反爬陷阱、有效选择器、平台特征，调用：

@@ -325,7 +257,7 @@ SitePatternWrite({
  domain: "xiaohongshu.com",
  scope: "agent",     // agent=共享（受 Git 管理，发布给其他用户）；user=私有
  mode: "merge",      // merge 追加，replace 覆盖
-  content: "## 已知陷阱\n- 2026-05: ...",
+  content: "## 已知陷阱\n- 2026-08: ...",
  confidence: "medium"
 })
 ```
@@ -341,8 +273,6 @@ SitePatternRead({ domain: "xiaohongshu.com" })

 含 cookie / token / 手机号 / 邮箱时 SitePatternWrite **自动降级 scope='user'** 并提示。

---
-
 ## Common Workflows

 Read [references/workflows.md](references/workflows.md) for detailed templates:
@@ -351,11 +281,9 @@ Read [references/workflows.md](references/workflows.md) for detailed templates:
 - 新闻聚合与时间线 (News aggregation)
 - API/库版本调查 (Library version investigation)

-Read [references/cdp-browser.md](references/cdp-browser.md) for login-gated site recipes (小红书/B站/微博/知乎/飞书).
-
 Read [references/jina-reader.md](references/jina-reader.md) for Jina Reader positioning, rate limits, and advanced endpoints.

---
+Read [references/browser-tools.md](references/browser-tools.md) for the full built-in browser command surface, capability tiers, and known boundaries.

 ## Quick Workflow: Multi-Source Research

@@ -369,27 +297,22 @@ Read [references/jina-reader.md](references/jina-reader.md) for Jina Reader posi
 7. Report with inline [source](url) citations + a Sources list at the end
 ```

---
-
 ## Anti-Patterns (Avoid)

 - ❌ **Using WebFetch on obviously heavy sites** — Medium, Twitter, 小红书 will waste tokens or fail. Jump straight to L2/L3.
- ❌ **Launching headless Chrome instead of CDP attach** — loses user's login state, triggers anti-bot, slow cold start. Always use `connect_over_cdp()` to attach to the user's existing session.
 - ❌ **Fetching one URL at a time when you need 5** — batch in a single message.
 - ❌ **Trusting a single source** — cross-check ≥ 2 sources for non-trivial claims.
 - ❌ **Fetching the search result page itself** — WebSearch already returns snippets; fetch the actual articles.
 - ❌ **Ignoring the cache** — WebFetch caches 15 min, reuse freely.
- ❌ **Scraping when an API exists** — GitHub, npm, PyPI, Wikipedia all have JSON APIs.
+- ❌ **Scraping when an API exists** — GitHub, npm, PyPI, Wikipedia all have JSON APIs; 登录态站内接口走 fetch.browser 配方.
 - ❌ **Forgetting the year in time-sensitive queries** — "best AI models" returns 2023 results; "best AI models 2026" returns current.
- ❌ **Hardcoding login credentials in scripts** — always rely on the user's pre-logged CDP session.
+- ❌ **Hardcoding login credentials in scripts** — 登录态只能来自 BrowserImport 导入的 Cookie.
 - ❌ **Citing only after the fact** — collect URLs as you fetch, not from memory afterwards.
- ❌ **(v2.1) 在能用内置浏览器时仍写 Python heredoc** — 慢、依赖 Python+Playwright 安装、上下文体积大。优先 L3-fast；只在内置浏览器不够（race / 长等待 / 自定义脚本）时才回退。
- ❌ **(v2.1) 没 `tab.activate` 就直接 `page.screenshot`** — 标签页默认停在窗口外 `(-10000,-10000,1x1)`，没有合成表面，截图会卡满 30 秒 deadline **并把标签页宿主打掉**，之后所有调用都报 `BROWSER_TAB_HOST_NOT_FOUND`。务必先用真实 bounds `tab.activate`。
- ❌ **(v2.1) 用 `page.evaluate` 读页面** — 每次调用都需人工审批，返回的字符串/对象会被治理策略替换为 `[REDACTED:browser-runtime-value]`（只有 number/boolean/null 能穿透），且反调试站点会把它挂起几十秒。读页面请用 `BrowserSnapshot`。
- ❌ **(v2.1) 任务结束发现新陷阱却不写 site-pattern** — 下次同 Agent 再做相同任务会重复踩坑。任何"花了 2+ 步才搞清楚的细节"都值得 `SitePatternWrite(scope='agent', mode='merge')`。
- ❌ **(v2.1) 把含 cookie / 手机号的内容写到 scope='agent'** — 这层会被 Git 提交、可能发布到市场。SitePatternWrite 会自动降级，但你不该故意往 agent 层写敏感信息。
-
---
+- ❌ **(v3.0) 在反检测站点用 page.element 批量交互** — 它是 JS 直调，绕开拟真轨迹；反检测站点一律 `input.*`，`page.element` 只用于不检测场景的表单批量填充。
+- ❌ **(v3.0) 用截图靠"看图读字"取正文** — `page.extract-text` / `BrowserSnapshot(text)` 直接给 markdown/text，带分页预算；截图留给版面确认与验证码这类必须看图的场合。
+- ❌ **(v3.0) 逐动作往返还能忍时不换 BrowserScript** — 导航→快照→点击→等待→取文五连用一段脚本完成；但记住 BrowserScript 信任级别等同 Bash，脚本源码要过一次人工审批。
+- ❌ **(v3.0) 任务结束发现新陷阱却不写 site-pattern** — 下次同 Agent 再做相同任务会重复踩坑。任何"花了 2+ 步才搞清楚的细节"都值得 `SitePatternWrite(scope='agent', mode='merge')`。
+- ❌ **(v3.0) 把含 cookie / 手机号的内容写到 scope='agent'** — 这层会被 Git 提交、可能发布到市场。SitePatternWrite 会自动降级，但你不该故意往 agent 层写敏感信息。

 ## Example Interaction

@@ -398,26 +321,15 @@ Read [references/jina-reader.md](references/jina-reader.md) for Jina Reader posi
 **Agent workflow**:
 ```
 1. 识别 → 小红书是 L3 登录态站点
-2. 检查 CDP：curl -s http://localhost:9222/json/version
-   ├─ 失败 → 提示用户启动 Chrome 调试模式，终止
-   └─ 成功 → 继续
-3. Bash: python3 connect_over_cdp 脚本 → page.goto(url) → page.content()
-4. BeautifulSoup 提取 h1 title、.note-content、.comments
+2. BrowserManage(create_space + start_session)
+   需要登录态 → 已授予 browser.import.* 就走 BrowserImport 四步；
+   没授予 → 告诉用户无法复用登录态，按公开可见部分继续
+3. BrowserAct(tab.navigate → 笔记 URL)
+4. BrowserAct(page.extract-text, format: markdown)
+   ← 正文直接读出；超预算就按 nextCursor 续读
 5. 返回给用户时：
   - 引用原 URL
-   - 若内容很长，用 Jina 清洗一遍节省 token
-6. 告知用户：「已通过你的登录态抓取，原链接：[xhs](url)」
+   - 引用正文事实，标注来源链接
+6. 告知用户：「已通过内置浏览器抓取，原链接：[xhs](url)」
+7. BrowserManage(close_session)
 ```
-
---
-
-## Installation Note
-
-CDP features require Python + Playwright installed:
-
-```bash
-pip3 install playwright beautifulsoup4
-python3 -m playwright install chromium  # only needed if user hasn't installed Chrome
-```
-
-If `playwright` is not installed when the user requests a login-gated site, run the install commands in Bash and explain you're setting up the browser automation dependency.