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

skills/web-access/references/browser-tools.md

@@ -1,26 +1,15 @@
-# 内置受管浏览器工具速查（L3-fast）
+# 内置受管浏览器工具速查（L3）
 
-> v2.1 起，本层从「cdp-proxy 驱动用户自己的 Chrome」改为「DesireCore 内置受管浏览器」。
+> v2.1 起本层从「cdp-proxy 驱动用户自己的 Chrome」改为「DesireCore 内置受管浏览器」；v3.0 补全能力面（批量取文 / 元素操作 / 等待 / 代码模式）并移除 Python Playwright 回落。
 > 每个任务跑在独立 BrowserSpace 里（Cookie / Storage / 缓存互不串扰），每个动作都经过
 > Capability → Grant → Lease → Origin → Host fencing 校验并留下可审计回执。
 >
-> 要求客户端 **v10.0.98+**。旧的 `BrowserListTabs` / `BrowserNavigate` / `BrowserEval` /
-> `BrowserClick` / `BrowserScreenshot` / `BrowserScroll` / `BrowserSetFiles` /
-> `BrowserCloseTab` 与其背后的 cdp-proxy 已停用，调用会直接返回
+> 要求客户端 **v10.0.98+**。`page.extract-text` / `page.element` / `page.wait` / 内联 wait 块 /
+> 跨源 iframe 快照需 **v10.0.112+**；`BrowserScript` 需包含 S17/S18 的版本。旧的
+> `BrowserListTabs` / `BrowserNavigate` / `BrowserEval` / `BrowserClick` / `BrowserScreenshot` /
+> `BrowserScroll` / `BrowserSetFiles` / `BrowserCloseTab` 与其背后的 cdp-proxy 已停用，调用会直接返回
 > 「该旧 BrowserXxx/cdp-proxy 入口已停用；请改用 BrowserManage、BrowserSnapshot 或 BrowserAct」。
 
-## 何时用内置浏览器 vs Python Playwright
-
-| 场景 | 推荐 |
-|------|------|
-| 到达并操作登录态站点（小红书 / B站 / 微博 / 飞书 / 知乎） | **内置浏览器**（登录态优先走 L3-fallback CDP；仅在已授予 `browser.import.*` 时才用 BrowserImport 导入 Cookie） |
-| 抽取登录态站点的长正文 | Python Playwright（内置浏览器没有批量取文通道，见下） |
-| 简单点击 / 滚动 / 截图 | **内置浏览器** |
-| 多个任务要互不串扰地并行 | **内置浏览器**（一任务一 Space） |
-| 需要复杂等待逻辑（wait_for_selector + race condition） | Python Playwright（cdp-browser.md） |
-| 需要在浏览器内运行长时间脚本（>30 s） | Python Playwright（内置浏览器单条命令 30 s deadline） |
-| 需要对元素做放大裁剪截图 | Python Playwright（内置浏览器只有整页截图） |
-
 ## 前置条件
 
 1. 客户端 v10.0.98+，`~/.desirecore/config/browser.json` 里 `electron-embedded` 或
@@ -68,27 +57,52 @@ BrowserManage:
 
 ### BrowserSnapshot
 
-读页面的**主通道**。返回可交互元素及其 `ref` 句柄、`rect`、`disabled` 状态。
+读页面的**主通道**。四种 mode：
 
 ```yaml
 BrowserSnapshot:
-  mode: semantic        # semantic（默认）| accessibility | visual
+  mode: semantic        # semantic（默认）| text | accessibility | visual
   sessionId: bss_xxx    # 当前 Agent 有多个会话时用于消歧
-  tabId: btab_xxx
+  tabId: btab_xxx       # 非活动标签页时用于消歧
+  options: {...}        # 各 mode 专属参数，见下
 ```
 
-提示：
-- `semantic` 只列 button / input / a 等可交互元素，**不含图片和正文文本节点**
-- 元素 `name` 往往是 placeholder（如「请输入」），无标签时只能靠 `rect.y` 排序定位
-- 页面重排后旧 `ref` 会失效——**每次交互前重新取快照**
-- `accessibility` 能拿到 StaticText 正文，但**只在很简单的页面上可用**：实测
-  example.com 正常返回，维基百科条目一律 `BROWSER_RESULT_TOO_LARGE`（回执上限 2 MB），
-  且 schema 里的 `depth` 参数目前被宿主忽略（硬编码 depth=50），调小也没用
-- 因此**取真实页面正文仍要靠 L2 Jina Reader（公开页）或 L3-fallback Playwright（登录态）**
+**semantic** —— 可交互元素清单（button / input / a 等）+ `ref` 句柄。每行形如
+`[ref=e12] [loc=...] 按钮 提交`：
+- `loc=` 是该元素的稳定选择器（S7）：仅当能产出时才给出，五级优先级 data-testid →
+  唯一 CSS 安全 id → name 属性 → 链接 href（剥 query 前缀匹配）→ role+name
+- 跨源 iframe（OOPIF）的元素并入同一棵树，ref 全局连续编号（S35）
+- 页面重排后旧 `ref` 会失效——**每次交互前重新取快照**；带 ref 的命令要同时给签发该
+  ref 的快照 `snapshotId`
+- `options`：`scope`（viewport=视口内元素优先截断）、`maxElements`（默认 400 上限 2000）、
+  `maxBytes`（默认 256KB 上限 1MB）、`cursor` 翻页、`limit`
+
+**text** —— 正文批量取文通道之一（S3/S4）：
+```yaml
+BrowserSnapshot:
+  mode: text
+  options:
+    format: markdown       # markdown（默认，保留标题/列表/表格）| text（纯文本）
+    maxBytes: 65536        # 默认 65536，最大 524288；超出不报错，截断并返回 nextCursor
+    cursor: t1:...:...     # 上一页返回的 nextCursor，同参数续读
+    scope: full_page       # full_page（默认）| viewport | ref（配 ref + snapshotId 取子树）
+    includeLinks: true     # 链接目标写进正文（只写 http/https）
+    includeTables: true    # 表格保留逐行结构
+```
+
+**accessibility** —— AX 树（S8 起**尊重 `depth`、预算截断不炸**）：
+`options.depth`（默认 50 上限 100）、`maxElements`、`maxBytes`、`cursor`。真实内容页不再
+`BROWSER_RESULT_TOO_LARGE` 整体失败——超预算截断给 nextCursor 续读。
+
+**visual** —— 截图（像素直接进结果）：
+`options.format`（png/jpeg）、`quality`、`captureBeyondViewport`（整页）、
+`clip={x,y,width,height,scale}`（元素级裁剪放大，`scale` 最大 4）。
 
 ### BrowserAct
 
-一次调用一个受管动作。完整 `action` 见工具 schema，常用的：
+一次调用一个受管动作。`action` 分组：
+
+**tab.*** —— `navigate` / `back` / `forward` / `reload` / `activate` / `close`：
 
 ```yaml
 BrowserAct:
@@ -96,10 +110,15 @@ BrowserAct:
   params: { url: https://www.xiaohongshu.com/explore/... }
 ```
 
+**input.*** —— `move` / `click` / `double-click` / `drag` / `wheel` / `touch` / `pinch` /
+`key` / `text`。走 #1808 输入拟真（坐标派发、拟真轨迹、身份一致性），**反检测站点的交互首选**：
+
 ```yaml
 BrowserAct:
   action: input.click
-  params: { ref: bref_xxx }     # 用快照 ref；坐标会因页面重排失效
+  params:
+    ref: e12                    # 语义快照签发的短号 ref（不要裸 x/y）
+    snapshotId: snap-xxx        # 签发该 ref 的快照回执里的 snapshotId，必带
 ```
 
 ```yaml
@@ -114,37 +133,120 @@ BrowserAct:
   params: { deltaX: 0, deltaY: 720, x: 640, y: 400 }
 ```
 
-```yaml
-BrowserAct:
-  action: tab.activate          # 截图前必须先做这一步
-  params: { bounds: { x: 0, y: 0, width: 1280, height: 900 } }
-```
+带元素 ref 的 `input.*` 必须在 params 顶层同时带同一条快照回执的 `snapshotId`——ref 序号跨
+快照会重复，缺 snapshotId 一律拒绝执行。
+
+**page.element** —— 判别式元素命令（op × selector，九 op，S10）。**表单批量填充等站点
+不检测场景用**；反检测站点交互走 input.*：
 
 ```yaml
 BrowserAct:
-  action: page.screenshot
-  params: { format: png }       # 结果落 artifact store，回执给 artifact.id / sha256 / bytes
+  action: page.element
+  params:
+    op: fill                  # 写类：fill | select-option | check | uncheck | scroll-into-view
+                              # 读类：get-attribute | bounding-box | count | all-inner-texts
+    selector: loc=css:input#email   # loc= 方言或 e12 / ref=e12（配 snapshotId）
+    value: user@example.com   # fill / select-option 用
+    snapshotId: bsnp_xxx      # selector 用 ref 时必带
 ```
 
+- 写类走 `browser.input.keyboard` 能力档（与 input.text 同档）；读类走 `browser.observe.snapshot` 只读档
+- `fill` 对 `input[type=password]` **一律拒绝**
+- `selector` 方言：`e<序号>` / `ref=e<序号>`、`loc=css:` / `loc=role:` / `loc=text:` /
+  `loc=testid:`、裸 CSS，可叠 `internal:nth/last/scope/filter`。未知前缀（如 `loc=xpath:`）显式报错，绝不静默降级
+
+**page.wait** —— 判别式等待（until，九种，S11）。等待不改页面状态，走只读档：
+
+```yaml
+BrowserAct:
+  action: page.wait
+  params:
+    until: networkidle        # load | domcontentloaded | networkidle | selector | url | timeout
+                              # | request | response | download
+    timeoutMs: 10000          # 默认 10000，上限 60000
+    idleMs: 500               # networkidle 静默窗，默认 500
+```
+
+- 轮询型（load/domcontentloaded/networkidle/selector/url/timeout）超时返回 `waited: false`，不抛错
+- 事件型（request/response/download）超时**抛错**
+- `waitForFunction` 刻意不在枚举里——任意 JS 走 page.evaluate 的能力档与审批
+
+**内联 wait 块**（S14）—— `tab.navigate` / `input.click` / `input.key` / `page.element{op:"fill"}`
+支持 `params.wait`（形态与 page.wait 参数同构），一条回执完成「动作→等结果」，等待器先于动作注册，
+不跨两次 IPC 出竞态：
+
+```yaml
+BrowserAct:
+  action: tab.navigate
+  params:
+    url: https://example.com/login
+    wait: { until: networkidle, timeoutMs: 15000 }
+```
+
+**page.evaluate** —— 页面上下文求值（S2 起返回真实值）：
+
+```yaml
+BrowserAct:
+  action: page.evaluate
+  params:
+    expression: document.title
+    awaitPromise: true        # 默认 true
+```
+
+- 返回值**原样过界**（字符串/对象/数组都真实返回）；超预算截断并标 `truncated`，不抛错
+- 能力档 `browser.page.evaluate` 属人工闸门：非 allow-all 模式每次调用弹审批卡
+- 登录态取站内接口走 [fetch.browser 配方]（见下节）
+
+**page.extract-text** —— 与 `BrowserSnapshot mode:text` 同款取文通道，作为动作下发：
+scope（viewport/full_page/ref）+ ref + snapshotId、format（markdown/text）、maxBytes（默认
+65536 最大 524288）、cursor（`^t1:` 续读）、includeLinks、includeTables。超出预算截断 + nextCursor。
+
+**page.screenshot** —— 与 `BrowserSnapshot mode:visual` 同款：`format`、`quality`、
+`captureBeyondViewport`、`clip={x,y,width,height,scale}`。结果落 artifact store，回执给
+artifact.id / sha256 / bytes；截图像素直接进结果（见「截图」节）。
+
+### BrowserScript（代码模式，S17+S18）
+
+一段异步 JS 在 Worker 里跑，通过注入的 `page` / `tab` / `input` / `snapshot` / `console` /
+`performance` 门面连续下发命令——**导航→快照→点击→等待→取文一气呵成**，消除逐动作往返：
+
+```yaml
+BrowserScript:
+  code: |
+    const snap = await snapshot.semantic();
+    receipt.log(snap.content);
+    await input.click({ ref: 'e12', snapshotId: snap.snapshotId });
+    await page.wait({ until: 'networkidle' });
+    receipt.log(await page['extract-text']({ format: 'markdown' }));
+  sessionId: bss_xxx          # 可选，多会话消歧
+  tabId: btab_xxx             # 可选，缺省用会话活动 tab
+  totalBudgetMs: 180000       # 默认 180000，上限 600000；审批等待不计入
+  maxCommands: 500            # 每次运行命令条数上限
+```
+
+- ❗**信任级别等同 Bash**：Worker 不是沙箱，脚本可访问 Node fs/net/child_process。两层审批：
+  脚本源码先过一次与 Bash 同档的人类审批（allow-all / ask-external 豁免；脚本源码不可记忆），
+  其内每个受管浏览器能力再按「能力 × 本次运行」各问一次
+- helper 白名单 24 个：`snapshot.*` / `page.extract-text` / `tab.*` / `input.*` /
+  `page.evaluate` / `page.wait` / `page.element` / `console.read` / `performance.metrics`；
+  `console.log(page)` 可输出各 helper 的 signature/params/example 文档
+- 会话被用户接管、Lease 轮换 ⇒ **硬停**：后续命令一律不再下发
+- 需要 `browser.*` 相应能力；`receipt.log(...)` 或 `console.log` 输出文本
+
 ### BrowserImport（**需人工审批 + 额外授权**）
 
-把用户浏览器里的登录态 Cookie 导入当前 Space。
+把用户浏览器里的登录态 Cookie 导入当前 Space——**唯一的登录态复用通道**。
 
 > **前置条件（先看这里，别直接试）**：`browser.import.discover` /
 > `browser.import.cookies.inspect` / `browser.import.cookies` 三个能力**不在 `agentDefault` 里**，
 > 而 `BrowserManage(create_space)` 建的 Agent grant 就是按 `agentDefault` 签的。也就是说
 > **仅靠 create_space / start_session 走不通 BrowserImport**，必须由 Host/用户侧另行授予 import
-> 能力（`agentElevated` 或 Workbench 路径）。没有这层授权就别在这条路上耗——**直接回落
-> L3-fallback（Python Playwright 连用户已登录的 Chrome）**，那是当前更稳的登录态复用方式。
+> 能力（`agentElevated` 或 Workbench 路径）。没有这层授权就别在这条路上耗——如实告诉用户
+> 「当前无法复用你的登录态」，按无登录态继续或放弃。
 
 动作枚举只有这 6 个：`discover` | `create_plan` | `dry_run` | `apply` | `rollback` | `list_plans`
 （**没有 `plan`**）。完整流程是 `discover → create_plan → dry_run → apply`：
 
-```yaml
-BrowserImport:
-  action: discover              # 列出可导入的来源，返回不透明 sourceProfileId
-```
-
 ```yaml
 BrowserImport:
   action: create_plan           # 域名授权、来源、冲突策略都在这一步定死
@@ -155,57 +257,85 @@ BrowserImport:
   conflictStrategy: newer-wins  # keep-target | replace-target | newer-wins | fail-on-conflict
 ```
 
-```yaml
-BrowserImport:
-  action: dry_run               # 先看命中多少条，再决定要不要真的写入
-  planId: bimp_xxx              # create_plan 返回的 ID，前缀是 bimp_
-```
-
-```yaml
-BrowserImport:
-  action: apply                 # 只认 planId；域名/策略在 create_plan 时已固化
-  planId: bimp_xxx
-```
-
-写坏了用 `action: rollback` + 同一个 `planId` 回退；`list_plans` 查当前 Space 的历史 plan。
-
-解密与过滤全在 Host 侧完成，**Cookie 值不会进入 Agent 上下文或审计日志**。
+`dry_run` 先看命中多少条再 `apply`（只认 `create_plan` 返回的 `planId`，前缀 `bimp_`）；写坏了
+用 `rollback` + 同一个 planId 回退；`list_plans` 查历史。解密与过滤全在 Host 侧完成，
+**Cookie 值不会进入 Agent 上下文或审计日志**。
 
 ### BrowserShare
 
 把 Space / Session 委派给另一个 Agent，`shareMode` 可选 `snapshot`（只读副本）、
 `copy-on-write`（写时复制）、`live-shared`（实时共享）、`handoff`（移交控制权）。
 
+## fetch.browser 配方：带登录态取接口数据
+
+站内接口（列表、评论、订单等 JSON）在登录态下的正解——**页面上下文跑 `fetch`**，自动带该
+origin 的 Cookie，同 origin、受 Grant origins 约束，走 `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
+```
+
+- 先 `tab.navigate` 到该站任意页面建立 origin 与 Cookie，再发 fetch；路径写**相对路径**
+- 只能访问当前 tab origin；跨站接口先导航过去
+- 大 JSON 用 `.text()` 拿原文自己截取，或分页多次取
+- 非 allow-all 模式会弹审批卡（page.evaluate 人工闸门），向用户说明用途即可
+
+## 交互通道选用：input.* vs page.element（反检测决策）
+
+| 场景 | 用什么 | 原因 |
+|------|--------|------|
+| 反检测站点（小红书/微博/B站等）的一切点击/输入 | **`input.*`** | 坐标派发 + #1808 拟真轨迹 + 身份一致性（UA/UA-CH 无 Electron/Headless 痕迹） |
+| 表单批量填充等**站点不检测**的场景 | **`page.element` 写类** | 一条命令完成 fill/select-option/check，比逐元素 input.* 快得多 |
+| 需要元素属性/坐标/计数/批量文本 | `page.element` 读类 | 只读档（browser.observe.snapshot），无写审批 |
+| 任何「用 JS 直调 el.click()」的想法 | ❌ 禁止 | 绕开全部拟真投入（S10 红线）；指针动作只走 input.* |
+
 ## 截图：像素直接给你，通常不需要再 Read
 
-> **需要客户端 10.0.100+。** 更老的版本上截图只回元数据；
-> 若需要画面信息请改用 `semantic` / `accessibility` 快照，或回落 Jina / Playwright。
+`BrowserSnapshot mode:visual` 与 `BrowserAct page.screenshot` 会把截图像素作为 image 块
+**直接放进工具结果**——视觉模型当场就能看，不必再调 `Read`。
 
-`BrowserSnapshot` `mode: visual` 与 `BrowserAct` `page.screenshot` 会把截图像素作为
-image 块**直接放进工具结果**——视觉模型当场就能看，不必再调 `Read`。
-
-只有这几种情况才需要走 `result.artifact.absolutePath` 再 `Read` 一次：
-
-- 结果里明确写了「截图已保存，但…未附带像素」（超出单图预算、或体积过大）
-- 你需要的是**原始分辨率**，而附带的像素被压缩过
-
-对同一张图既看 image 块又 `Read` 一遍，只会让它在上下文里占两份。
+- **元素级裁剪放大**：`options.clip={x,y,width,height,scale}`（`scale` 最大 4）。先用
+  `semantic` 快照拿到元素坐标，再截那一块并放大——验证码、小按钮在整页截图里只有几十像素，
+  看不清时用它。**不必走 `cdp.raw`**
+- **整页截图**：`captureBeyondViewport: true`（超出视口部分也截）
+- 只有结果里明确写了「截图已保存，但…未附带像素」（超预算/体积过大）或需要原始分辨率时，
+  才走 `result.artifact.absolutePath` 再 `Read` 一次
 
 当前模型不支持视觉输入时，结果会明说「你看不到它的内容」——**此时不要凭空描述画面**，
-改用 `semantic` / `accessibility` 快照拿页面信息。
+改用 `semantic` / `text` 快照拿页面信息。
+
+## 视口与 tab.activate（S36 起）
+
+Agent 会话（actor ≠ user）的标签页**常驻离屏原位，保住合成表面**，不再停放成 1×1：
+
+| 场景 | 行为 |
+|------|------|
+| embedded，单标签会话 | 无需 `tab.activate` 即可截图/取视口（presentation 即呈现） |
+| embedded，多标签会话的后台 tab | 仍需先 `tab.activate`；未激活的视口快判**秒级**报 `BROWSER_VIEWPORT_UNAVAILABLE`，不再挂满 30s，也不会毁掉标签页 |
+| standalone | 后台 tab 可直接截图 |
+
+多 Space 依然可以并发导航/快照/输入，互不串扰。
 
 ## 已知边界（照做，别试探）
 
 | 边界 | 说明 |
 |------|------|
-| **截图前必须 `tab.activate`** | 标签页默认停在 `(-10000,-10000,1x1)`，没有合成表面。直接截图会卡满 30 s deadline，**并把标签页宿主打掉**，之后全部报 `BROWSER_TAB_HOST_NOT_FOUND` |
-| **同时只有一个可见标签页** | `tab.activate` 绑定主窗口、全局互斥。多 Space 可以并发导航/快照/输入，但截图必须逐个 activate 串行 |
-| **`page.evaluate` 基本不可用** | 每次调用需人工审批；返回的字符串/对象被替换为 `[REDACTED:browser-runtime-value]`（只有 number/boolean/null 穿透）；反调试站点会把它挂起几十秒。读页面用 `BrowserSnapshot` |
-| **`cdp.raw` 需人工审批** | `browser.raw_cdp.*` 属于永远人工闸门的能力，无人值守流程用不了。**元素级裁剪不必走它**（需 10.0.100+）——`BrowserSnapshot` 的 `options.clip={x,y,width,height,scale}` 直接支持（`scale` 最大 4）：先用 `semantic` 快照拿到元素坐标，再截那一块并放大。验证码、小按钮在整页截图里只有几十像素，看不清时用它 |
-| **没有批量取文通道** | `semantic` 不含正文，`accessibility` 在真实页面上超限，`page.evaluate` 被审批+脱敏。要正文请回落 Jina / Playwright |
-| **单条命令 30 s deadline** | 超时即判 `browser.host.gone`，会话作废 |
-| **用户真实操作会抢控制权** | 在可见标签页上**点击、按键、滚轮、触摸**会触发 `trusted-user-input` 并递增 control epoch，打断 Agent 的租约。**鼠标只是划过不会**（默认策略 `intentional-input`，需 10.0.100+；更老版本上划过也会打断），所以用户看着页面移动光标是安全的 |
-| **artifact 不要走 `/save`** | 该接口会弹系统「另存为」对话框等人点。**用回执里的 `result.artifact.absolutePath`**（需 10.0.100+；更老版本没有这个字段，只能放弃直接读，改用页面内提取）（工具会把它登记进本次会话的可读白名单），不要自己拼路径——`${DESIRECORE_ROOT}` 这类变量在路径展开里不认（只认 `~` / `$HOME` / `$USERPROFILE`），拼出来是相对路径、`Read` 会报「文件不存在」。默认保留 24 小时 |
+| **`page.evaluate` 走人工闸门** | 能力 `browser.page.evaluate` 属 always-human-gate：非 allow-all 模式每次弹审批卡。返回值已原样过界（超预算截断标 `truncated`），登录态取接口走 fetch.browser 配方 |
+| **`cdp.raw` 需人工审批** | `browser.raw_cdp.*` 属于永远人工闸门的能力，无人值守流程用不了。元素级裁剪 / 整页截图用 `clip` / `captureBeyondViewport`，别走它 |
+| **`page.element` 没有 click** | 指针动作必须走 `input.*`（拟真轨迹、可审计）；JS 直调 `el.click()` 是明确禁止的回退 |
+| **`fill` 拒绝密码框** | `input[type=password]` 一律拒绝——密码输入只走 `input.text`（拟真键入） |
+| **单条命令 30 s deadline** | 超时只掐掉**这一条命令**（stop 加载），标签页仍可用，重试即可；不再打掉宿主。等待类命令超时连 stop 都跳过 |
+| **多标签后台 tab 先 activate** | embedded 多标签会话里后台 tab 截图前先 `tab.activate`，否则秒级 `BROWSER_VIEWPORT_UNAVAILABLE` |
+| **用户真实操作会抢控制权** | 在可见标签页上**点击、按键、滚轮、触摸**会触发 `trusted-user-input` 并递增 control epoch，打断 Agent 的租约。**鼠标只是划过不会**（默认策略 `intentional-input`），所以用户看着页面移动光标是安全的 |
+| **BrowserScript 信任级别等同 Bash** | 脚本可访问 Node fs/net/child_process；源码过一次与 Bash 同档审批 + 每能力一问；接管/Lease 轮换即硬停 |
+| **artifact 不要走 `/save`** | 该接口会弹系统「另存为」对话框等人点。**用回执里的 `result.artifact.absolutePath`**（工具会把它登记进本次会话的可读白名单），不要自己拼路径——`${DESIRECORE_ROOT}` 这类变量在路径展开里不认（只认 `~` / `$HOME` / `$USERPROFILE`），拼出来是相对路径、`Read` 会报「文件不存在」。默认保留 24 小时 |
 
 ## SitePatternRead / SitePatternWrite
 
@@ -228,17 +358,18 @@ SitePatternWrite:
 | 错误 | 原因 | 解决 |
 |------|------|------|
 | `该旧 BrowserXxx/cdp-proxy 入口已停用` | 还在调 v2.0 的旧工具 | 改用 BrowserManage / BrowserSnapshot / BrowserAct |
-| `BROWSER_TAB_HOST_NOT_FOUND` | 标签页宿主已销毁（多因上一条命令超时） | 重建 Session；检查是否漏了 `tab.activate` |
-| `BROWSER_COMMAND_DEADLINE_EXCEEDED` | 单条命令超 30 s | 截图先 activate；避免 `page.evaluate` |
+| `BROWSER_TAB_HOST_NOT_FOUND` | 标签页宿主真的没了（渲染进程崩溃/销毁） | 重建 Session。命令超时**不再**引发此错误——超时只 stop 这一条命令，标签页保留 |
+| `BROWSER_COMMAND_DEADLINE_EXCEEDED` | 单条命令超 30 s | 标签页仍停在上一页/空白页，直接重试；慢加载常态不算故障 |
+| `BROWSER_VIEWPORT_UNAVAILABLE` | embedded 多标签会话的后台 tab 没有可用视口 | 先 `tab.activate` 再截图（秒级快判，不是挂死） |
 | `BROWSER_TOOL_SESSION_FORBIDDEN` | 会话已关闭/崩溃，或不属于当前 Agent | 重新 `list_sessions`，必要时重建 |
 | `BROWSER_TOOL_SESSION_AMBIGUOUS` | 当前 Agent 有多个会话且未传 sessionId | 显式传 `sessionId` |
-| `BROWSER_HUMAN_APPROVAL_REQUIRED` | 触到人工闸门能力（evaluate / raw_cdp / 上传下载 / Cookie 导入等） | 向用户说明用途并等待审批，或换用无需审批的路径 |
-| `BROWSER_RESULT_TOO_LARGE` | 回执超过 2 MB（`accessibility` 快照最常见） | 改用 `semantic` 快照 + 截图；取正文回落 Jina / Playwright |
+| `BROWSER_HUMAN_APPROVAL_REQUIRED` | 触到人工闸门能力（evaluate / raw_cdp / 上传下载 / Cookie 导入等） | 向用户说明用途并等待审批，或换用无需审批的路径（取文用 extract-text，裁剪用 clip） |
+| `BROWSER_RESULT_TOO_LARGE` | 回执超过结果上限 | text/semantic/accessibility 都有 maxBytes + cursor 分页，调小 maxBytes 续读即可，不再整体失败 |
 
 ## 调用链路
 
 ```
-Agent → BrowserManage/Snapshot/Act → browser-use service（Capability/Grant/Lease/Policy 校验）
+Agent → BrowserManage/Snapshot/Act/Script → browser-use service（Capability/Grant/Lease/Policy 校验）
       → BrowserHost（electron-embedded 或 standalone-managed）→ Chromium
                                     ↑ 每步产出带 digest 的回执，写入审计事件流
 ```