fix(web-access): 修正内置浏览器工具文档与客户端版本门控 (#73)

跟进 desirecore/desirecore#1718 的 Codex review，修掉 web-access v2.1.0 正文中 4 处与真实工具实现不符的地方（均对照 desirecore@origin/dev 源码核实）： - 补 market.required_client_version: 10.0.98，避免老客户端把可用的 v2.0 换成调用不存在工具的说明 - BrowserImport 动作名修正：真实枚举 discover/create_plan/dry_run/apply/rollback/list_plans，无 'plan'；domains 由 create_plan 消费；planId 前缀 bimp_ - input.wheel 示例补 x/y（schema 硬要求），capabilities 示例补 browser.input.pointer.wheel 并说明显式列表是做减法 - BrowserImport 降级为需额外授权的可选路径：browser.import.* 不在 agentDefault 内且 agentElevated 在工具层零引用，登录态默认改回 L3-fallback CDP skill 2.1.0 → 2.1.1，manifest 1.2.19 → 1.2.20，human-locked 的 en-US 已重新对齐 source_hash。
2026-09-05 19:03:50 +08:00 · 2026-08-06 01:36:49 +08:00
parent b4cafe4edd
commit b2865d501d
7 changed files with 71 additions and 31 deletions
--- a/manifest.json
+++ b/manifest.json
@@ -1,6 +1,6 @@
 {
  "name": "DesireCore Official Market",
-  "version": "1.2.19",
+  "version": "1.2.20",
  "schemaVersion": "1.1.0",
  "supportedLocales": ["zh-CN", "en-US"],
  "defaultLocale": "en-US",
--- a/skills/web-access/SKILL.md
+++ b/skills/web-access/SKILL.md
@@ -16,7 +16,7 @@ description: >-
  新闻、网址、URL、找一下、搜一下、查一下、小红书、B站、微博、飞书、Twitter、
  推特、X、知乎、公众号、已登录、登录状态。
 license: Complete terms in LICENSE.txt
-version: 2.1.0
+version: 2.1.1
 type: procedural
 risk_level: low
 status: enabled
@@ -53,14 +53,14 @@ metadata:
      short_desc: 联网搜索、网页抓取、内置受管浏览器登录态访问、研究调研工作流
      description: 四层联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器登录态访问、Python Playwright CDP 兜底。
      body: ./SKILL.zh-CN.md
-      source_hash: sha256:2e6753fc05142e9a
+      source_hash: sha256:ce46e1982de8cd65
      translated_by: human
    en-US:
      name: Web Access
      short_desc: Web search, page fetching, logged-in access via the governed built-in browser, research workflows
      description: A four-layer web-access toolkit — search public pages, fetch heavy pages via Jina Reader, reach logged-in sites through the governed built-in browser, and fall back to Chrome CDP.
      body: ./SKILL.md
-      source_hash: sha256:2e6753fc05142e9a
+      source_hash: sha256:ce46e1982de8cd65
      translated_by: human
 market:
  icon: >-
@@ -79,6 +79,7 @@ market:
    fill-opacity="0.12"/><path d="M20.5 20.5l2 2" stroke="#34C759"
    stroke-width="1.8" stroke-linecap="round"/></svg>
  category: research
+  required_client_version: 10.0.98
  maintainer:
    name: DesireCore Official
    verified: true
@@ -111,7 +112,7 @@ When you call `Skill('web-access')`, the following 8 tools are injected into the
 | BrowserManage | Create/destroy isolated BrowserSpace, start sessions, manage tabs |
 | BrowserSnapshot | `semantic` / `accessibility` / `visual` page snapshots — the primary way to read a page |
 | BrowserAct | One governed action per call: navigate, click, type, scroll, screenshot, … |
-| BrowserImport | Import Cookies from the user's Chrome/Edge/Firefox/Safari profile (human-approved) |
+| BrowserImport | Import Cookies from the user's Chrome/Edge/Firefox/Safari profile (human-approved; **needs `browser.import.*` granted by the Host — not available to a plain `create_space` session**) |
 | BrowserShare | Delegate a Space/Session to another Agent (isolated / snapshot / copy-on-write / live) |
 | SitePatternRead / SitePatternWrite | Per-domain "site experience" (AgentFS three-layer) |
 | LocalBookmarks | Search local Chrome bookmarks / history |
@@ -131,7 +132,7 @@ When you call `Skill('web-access')`, the following 8 tools are injected into the

 - **Four-layer progression**: from lightweight search to heavy JS rendering to logged-in access — pick on demand
 - **Token optimization**: Jina Reader cuts token usage by 50–80% by default
- **Logged-in session reuse**: import the user's existing Cookies into an isolated Space via BrowserImport (or attach to their Chrome via CDP in the fallback layer) — no re-login required
+- **Logged-in session reuse**: attach to the user's Chrome via CDP in the fallback layer, or — where the Host has granted `browser.import.*` — import their Cookies into an isolated Space via BrowserImport; either way, no re-login required

 ## L2: Detailed Specification

@@ -147,7 +148,7 @@ If any fetch fails, explicitly tell the user which URL failed and which fallback

 ## Prerequisites: Chrome CDP Setup (for login-gated sites)

-**Only required for the L3-fallback layer** (Python Playwright). The L3-fast built-in browser does not need this — use `BrowserImport` to reuse the user's login instead.
+**Required for the L3-fallback layer** (Python Playwright) — and, in practice, still the reliable way to reuse a login. The L3-fast built-in browser can skip it only when the Host has granted `browser.import.*` so that `BrowserImport` actually works; otherwise set this up.

 ### One-time setup

@@ -206,9 +207,10 @@ User intent
  │          (Jina Reader = default for JS-rendered content, saves tokens)
  │
  ├─ "Read this login-gated page" (Xiaohongshu/Bilibili/Weibo/Feishu/Twitter/Zhihu/WeChat)
-  │     ├─→ Reach it: BrowserManage(create_space/start_session) → BrowserImport(cookies for
-  │     │              that domain) → BrowserAct(tab.navigate) → tab.activate + page.screenshot
-  │     │              to confirm you landed on the content (semantic snapshot has no body text)
+  │     ├─→ Reach it: BrowserManage(create_space/start_session) → BrowserAct(tab.navigate)
+  │     │              → tab.activate + page.screenshot to confirm you landed on the content
+  │     │              (semantic snapshot has no body text). Logged-in? BrowserImport only if
+  │     │              browser.import.* was granted — otherwise reuse the login via CDP below.
  │     └─→ Extract the text: verify CDP ready, then python3 playwright.connect_over_cdp()
  │                   → page.content() → Jina Reader / BeautifulSoup
  │
@@ -363,9 +365,9 @@ See [references/cdp-browser.md](references/cdp-browser.md) for:
 | `BrowserSnapshot({ mode: 'semantic' })` | Read the page: interactive elements + `ref` handles |
 | `BrowserAct({ action: 'input.click', params: { ref } })` | Click by snapshot `ref`, never by raw x/y |
 | `BrowserAct({ action: 'input.text', params: { text } })` | Type into the focused element |
-| `BrowserAct({ action: 'input.wheel', params: { deltaX: 0, deltaY: 720 } })` | Scroll to trigger lazy loading |
+| `BrowserAct({ action: 'input.wheel', params: { x: 640, y: 400, deltaX: 0, deltaY: 720 } })` | Scroll to trigger lazy loading — `x`/`y` (or `ref`) is **required**, and the session needs `browser.input.pointer.wheel` |
 | `BrowserAct({ action: 'tab.activate', params: { bounds } })` → `page.screenshot` | **activate first, then screenshot** |
-| `BrowserImport({ action: 'discover' \| 'plan' \| 'apply' })` | Reuse the user's login cookies (human-approved) |
+| `BrowserImport({ action: 'discover' \| 'create_plan' \| 'dry_run' \| 'apply' \| 'rollback' \| 'list_plans' })` | Reuse the user's login cookies — those 6 are the **complete** action set; happy path is `discover → create_plan → dry_run → apply`. **Needs `browser.import.*`, which `create_space` does not grant** (see below) |

 Full API and edge cases: see [references/browser-tools.md](references/browser-tools.md).

@@ -385,7 +387,10 @@ Full API and edge cases: see [references/browser-tools.md](references/browser-to
 ```
 1. BrowserManage({ action: 'create_space', name: 'xhs-note', persistence: 'ephemeral' })
 2. BrowserManage({ action: 'start_session', spaceId, capabilities: [...] })
-3. BrowserImport({ action: 'discover' }) → plan → apply for xiaohongshu.com  ← reuse login
+   ← an explicit list *narrows* the lease; include browser.input.pointer.wheel if you will scroll
+3. Reuse the login: L3-fallback Playwright against the user's own Chrome is the default path.
+   BrowserImport({ action: 'discover' → 'create_plan' → 'dry_run' → 'apply' }) only works if the
+   Host granted browser.import.* separately — create_space alone does not. If it is denied, fall back.
 4. BrowserAct({ action: 'tab.navigate', params: { url: 'https://www.xiaohongshu.com/explore/abc123' } })
 5. BrowserSnapshot({ mode: 'semantic' })   ← element refs for interaction (no body text)
   tab.activate + page.screenshot           ← confirm the note actually rendered
--- a/skills/web-access/SKILL.zh-CN.md
+++ b/skills/web-access/SKILL.zh-CN.md
@@ -26,7 +26,7 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供四层互
 | BrowserManage | 建/销隔离 BrowserSpace、启动会话、管理标签页 |
 | BrowserSnapshot | `semantic` / `accessibility` / `visual` 快照——读页面的主通道 |
 | BrowserAct | 一次调用一个受管动作：导航、点击、输入、滚动、截图…… |
-| BrowserImport | 从用户 Chrome/Edge/Firefox/Safari 配置导入 Cookie（需人工审批） |
+| BrowserImport | 从用户 Chrome/Edge/Firefox/Safari 配置导入 Cookie（需人工审批；**还需 Host 授予 `browser.import.*`，普通 `create_space` 会话拿不到**） |
 | BrowserShare | 把 Space/Session 委派给其他 Agent（隔离 / 快照 / 写时复制 / 实时共享） |
 | SitePatternRead / SitePatternWrite | 按域名累积"站点经验"（AgentFS 三层） |
 | LocalBookmarks | 检索本地 Chrome 书签 / 历史 |
@@ -46,7 +46,7 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供四层互

 - **四层递进**：从轻量搜索到重度 JS 渲染到登录态访问，按需选择
 - **Token 优化**：Jina Reader 默认减少 50-80% Token 消耗
- **登录态复用**：用 BrowserImport 把用户已有 Cookie 导入隔离 Space（兜底层仍可 CDP 连用户 Chrome），无需重复登录
+- **登录态复用**：兜底层 CDP 连用户 Chrome，或在 Host 已授予 `browser.import.*` 时用 BrowserImport 把 Cookie 导入隔离 Space；两条路都不必重新登录

 ## L2：详细规范

@@ -62,7 +62,7 @@ If any fetch fails, explicitly tell the user which URL failed and which fallback

 ## Prerequisites: Chrome CDP Setup (for login-gated sites)

-**Only required for the L3-fallback layer**（Python Playwright）。L3-fast 内置浏览器不需要——用 `BrowserImport` 复用登录态即可。
+**L3-fallback 层（Python Playwright）必需**，实际上也仍是复用登录态最稳的一条路。L3-fast 内置浏览器只有在 Host 已授予 `browser.import.*`、`BrowserImport` 真能用的前提下才可以跳过这一步；否则照样要配。

 ### One-time setup

@@ -121,9 +121,10 @@ User intent
  │          (Jina Reader = default for JS-rendered content, saves tokens)
  │
  ├─ "Read this login-gated page" (小红书/B站/微博/飞书/Twitter/知乎/公众号)
-  │     ├─→ 到达：BrowserManage(create_space/start_session) → BrowserImport(按域导入 Cookie)
-  │     │        → BrowserAct(tab.navigate) → tab.activate + page.screenshot 确认落到正文页
+  │     ├─→ 到达：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
  │
@@ -278,9 +279,9 @@ See [references/cdp-browser.md](references/cdp-browser.md) for:
 | `BrowserSnapshot({ mode: 'semantic' })` | 读页面：可交互元素 + `ref` 句柄 |
 | `BrowserAct({ action: 'input.click', params: { ref } })` | 按快照 `ref` 点击，不要用裸 x/y |
 | `BrowserAct({ action: 'input.text', params: { text } })` | 向聚焦元素输入文本 |
-| `BrowserAct({ action: 'input.wheel', params: { deltaX: 0, deltaY: 720 } })` | 滚动触发懒加载 |
+| `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' \| 'plan' \| 'apply' })` | 复用用户登录态 Cookie（需人工审批） |
+| `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)。

@@ -300,7 +301,10 @@ See [references/cdp-browser.md](references/cdp-browser.md) for:
 ```
 1. BrowserManage({ action: 'create_space', name: 'xhs-note', persistence: 'ephemeral' })
 2. BrowserManage({ action: 'start_session', spaceId, capabilities: [...] })
-3. BrowserImport({ action: 'discover' }) → plan → apply 授权 xiaohongshu.com  ← 复用登录态
+   ← 显式列表是做减法；要滚动就必须把 browser.input.pointer.wheel 列进去
+3. 复用登录态：默认走 L3-fallback Playwright 连用户自己的 Chrome。
+   BrowserImport({ action: 'discover' → 'create_plan' → 'dry_run' → 'apply' }) 只有在 Host 另行
+   授予 browser.import.* 时才走得通 —— 光靠 create_space 拿不到；被拒就直接回落。
 4. BrowserAct({ action: 'tab.navigate', params: { url: 'https://www.xiaohongshu.com/explore/abc123' } })
 5. BrowserSnapshot({ mode: 'semantic' })   ← 只拿交互用的元素 ref（不含正文）
   tab.activate + page.screenshot           ← 确认确实渲染出了笔记
--- a/skills/web-access/references/browser-tools.md
+++ b/skills/web-access/references/browser-tools.md
@@ -13,7 +13,7 @@

 | 场景 | 推荐 |
 |------|------|
-| 到达并操作登录态站点（小红书 / B站 / 微博 / 飞书 / 知乎） | **内置浏览器**（配合 BrowserImport 导入 Cookie） |
+| 到达并操作登录态站点（小红书 / B站 / 微博 / 飞书 / 知乎） | **内置浏览器**（登录态优先走 L3-fallback CDP；仅在已授予 `browser.import.*` 时才用 BrowserImport 导入 Cookie） |
 | 抽取登录态站点的长正文 | Python Playwright（内置浏览器没有批量取文通道，见下） |
 | 简单点击 / 滚动 / 截图 | **内置浏览器** |
 | 多个任务要互不串扰地并行 | **内置浏览器**（一任务一 Space） |
@@ -57,9 +57,13 @@ BrowserManage:
    - browser.navigate.url
    - browser.navigate.activate-tab
    - browser.input.pointer.click
+    - browser.input.pointer.wheel   # 要滚动加载就必须带上，漏了 input.wheel 会被策略拒绝
    - browser.input.keyboard
 ```

+**显式传 `capabilities` 就是在做减法**：不传时按 `agentDefault` 全量签发租约，传了就只签这一份
+列表。所以别照抄示例——把你这次真正要用的动作对应的能力都列全。
+
 `create_space` 会触发一次用户确认。任务收尾用 `close_session` 释放。

 ### BrowserSnapshot
@@ -122,23 +126,49 @@ BrowserAct:
  params: { format: png }       # 结果落 artifact store，回执给 artifact.id / sha256 / bytes
 ```

-### BrowserImport（**需人工审批**）
+### BrowserImport（**需人工审批 + 额外授权**）

-把用户浏览器里的登录态 Cookie 导入当前 Space，替代旧版「attach 用户已登录的 Chrome」。
+把用户浏览器里的登录态 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）**，那是当前更稳的登录态复用方式。
+
+动作枚举只有这 6 个：`discover` | `create_plan` | `dry_run` | `apply` | `rollback` | `list_plans`
+（**没有 `plan`**）。完整流程是 `discover → create_plan → dry_run → apply`：

 ```yaml
 BrowserImport:
-  action: discover              # discover | plan | apply | ...
+  action: discover              # 列出可导入的来源，返回不透明 sourceProfileId
 ```

 ```yaml
 BrowserImport:
-  action: apply
-  planId: bip_xxx
+  action: create_plan           # 域名授权、来源、冲突策略都在这一步定死
+  sourceKind: chromium-profile  # chromium-profile | firefox-profile | safari-profile
+                                # | browser-extension | cookie-file
+  sourceProfileId: <discover 返回的 ID>
  domains: [xiaohongshu.com]    # 必须逐域显式授权
-  conflictStrategy: newer-wins
+  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 上下文或审计日志**。

 ### BrowserShare
--- a/skills/web-access/references/site-patterns/feishu.cn.md
+++ b/skills/web-access/references/site-patterns/feishu.cn.md
@@ -19,7 +19,7 @@ updated_at: '2026-08-06'

 ## 推荐流程
 1. 公开文档（companion 页面/官方文档站点 `feishu.cn/hc/...`）→ WebFetch / Jina
-2. 用户文档 → 内置浏览器 BrowserImport 导入 Cookie + BrowserAct(tab.navigate) 到达，正文抽取回落 Playwright
+2. 用户文档 → 内置浏览器 BrowserAct(tab.navigate) 到达（登录态：已授予 `browser.import.*` 才用 BrowserImport，否则直接回落），正文抽取回落 Playwright
 3. 长期程序化访问 → 申请 OpenAPI access_token，走 HTTP，避免 CDP

 ## 推荐选择器
--- a/skills/web-access/references/site-patterns/weibo.com.md
+++ b/skills/web-access/references/site-patterns/weibo.com.md
@@ -18,7 +18,7 @@ updated_at: '2026-08-06'

 ## 推荐流程
 1. 单条公开微博 → 优先尝试 `https://m.weibo.cn/status/<id>`，WebFetch 看是否拿到正文
-2. 拿不到 → 内置浏览器 BrowserImport 导入 Cookie + BrowserAct(tab.navigate) + BrowserAct(input.click ref) 点"展开"，正文抽取回落 Playwright
+2. 拿不到 → 内置浏览器 BrowserAct(tab.navigate) + BrowserAct(input.click ref) 点"展开"（登录态：已授予 `browser.import.*` 才用 BrowserImport，否则直接回落），正文抽取回落 Playwright
 3. 用户主页时间线：必须登录，BrowserAct(input.wheel) 触发懒加载

 ## 推荐选择器
--- a/skills/web-access/references/site-patterns/xiaohongshu.com.md
+++ b/skills/web-access/references/site-patterns/xiaohongshu.com.md
@@ -18,7 +18,8 @@ updated_at: '2026-08-06'
 - xsec_token：详情页 URL 包含 `xsec_token=...`，**通过站内交互生成**——直接拼 URL 容易失败

 ## 推荐流程
-1. BrowserManage(create_space/start_session) → BrowserImport 按域导入 xiaohongshu.com 的 Cookie
+1. BrowserManage(create_space/start_session)；登录态若已授予 `browser.import.*`，用
+   BrowserImport(discover → create_plan[domains: xiaohongshu.com] → dry_run → apply)，否则回落 CDP
 2. BrowserAct(tab.navigate) 打开笔记；列表页用 BrowserSnapshot(semantic) 收 `.note-card` 链接的 ref
 3. 正文抽取回落 L3-fallback Playwright（内置浏览器的 semantic 快照不含正文，accessibility 在本站会超限）
 4. 收尾 BrowserManage(close_session)；ephemeral Space 不留 Profile