feat(web-access): v2.0 — Skill-Scoped 工具门控 + cdp-proxy 子模块 + BrowserXxx 工具家族

升级 web-access 技能 v1.1.2 → v2.0.0，与 desirecore/desirecore PR #536 同步。新增内容（在 i18n 1.1 schema 下保持双语一致）： - SKILL.md / SKILL.zh-CN.md：补充 BrowserXxx 工具家族说明、L3-fast vs L3-fallback 分层策略（默认 BrowserXxx，复杂场景兜底 Python Playwright）、SKILL 激活前后的 hidden 工具门控行为、SitePattern 三层学习库语义 - frontmatter 新增 `provides.tools`：声明 11 个 hidden 工具（8 个 BrowserXxx + SitePatternRead/Write + LocalBookmarks），客户端按 Skill 激活解锁 - references/browser-tools.md：8 个 BrowserXxx 工具的完整参数与典型用法 - references/site-patterns/ 5 个基线站点模板：xiaohongshu / bilibili / weibo / zhihu / feishu，含 _index 总览 manifest.json：stats.lastUpdated 同步到 2026-05-06。关联： - 主仓库 PR：desirecore/desirecore#536 - ADR-027 Node CDP 代理子模块（desirecore-docs）
2026-06-06 04:30:42 +08:00 · 2026-05-06 12:05:39 +08:00
parent bffb9d24b4
commit 93fd40f661
10 changed files with 573 additions and 16 deletions
--- a/manifest.json
+++ b/manifest.json
@@ -28,7 +28,7 @@
  "stats": {
    "totalAgents": 1,
    "totalSkills": 23,
-    "lastUpdated": "2026-05-05"
+    "lastUpdated": "2026-05-06"
  },
  "features": [
    "verified-only",
--- a/skills/web-access/SKILL.md
+++ b/skills/web-access/SKILL.md
@@ -14,7 +14,7 @@ description: >-
  新闻、网址、URL、找一下、搜一下、查一下、小红书、B站、微博、飞书、Twitter、
  推特、X、知乎、公众号、已登录、登录状态。
 license: Complete terms in LICENSE.txt
-version: 1.1.2
+version: 2.0.0
 type: procedural
 risk_level: low
 status: enabled
@@ -27,9 +27,22 @@ tags:
  - browsing
  - cdp
  - playwright
+provides:
+  tools:
+    - BrowserListTabs
+    - BrowserNavigate
+    - BrowserEval
+    - BrowserClick
+    - BrowserScreenshot
+    - BrowserScroll
+    - BrowserSetFiles
+    - BrowserCloseTab
+    - SitePatternRead
+    - SitePatternWrite
+    - LocalBookmarks
 metadata:
  author: desirecore
-  updated_at: '2026-05-03'
+  updated_at: '2026-05-05'
  i18n:
    default_locale: en-US
    source_locale: zh-CN
@@ -84,7 +97,28 @@ A three-layer web-access toolkit — search public pages, optimize fetches via J

 ### Capability

-web-access is a **procedural skill** that provides three complementary layers of web access: Layer 1 (WebSearch + WebFetch) for public pages; Layer 2 (Jina Reader) for JS-rendered heavy pages, saving tokens by default; Layer 3 (Chrome CDP) for sites requiring a logged-in session (Xiaohongshu / Bilibili / Weibo / Feishu / Twitter).
+web-access is a **procedural skill** that provides four complementary layers of web access:
+
+- **L1** (WebSearch + WebFetch): public, static pages
+- **L2** (Jina Reader): JS-rendered heavy pages, saving tokens by default
+- **L3-fast** (BrowserXxx builtin tool family — **new in v2.0**): preferred for logged-in sites — zero Python dependency, in-process cdp-proxy, supports CDP real-mouse events
+- **L3-fallback** (Chrome CDP + Python Playwright): backup for complex automation (long waits, race conditions, custom in-browser scripts)
+
+### v2.0 — BrowserXxx tool family (default-hidden, exposed only after Skill activation)
+
+When you call `Skill('web-access')`, the following 11 tools are injected into the current session so the LLM can drive Chrome directly:
+
+| Tool | Purpose |
+|------|---------|
+| BrowserListTabs / BrowserNavigate / BrowserCloseTab | Tab management |
+| BrowserEval | Run JS to extract data |
+| BrowserClick (`mode: js \| real-mouse`) | Click elements; real-mouse defeats anti-bot |
+| BrowserScreenshot / BrowserScroll | Screenshots, scroll to trigger lazy loading |
+| BrowserSetFiles | Upload local files (requires user confirmation) |
+| SitePatternRead / SitePatternWrite | Per-domain "site experience" (AgentFS three-layer) |
+| LocalBookmarks | Search local Chrome bookmarks / history |
+
+> **Important**: before `Skill('web-access')` is called, none of these tools appear in the LLM tools list — default conversations don't pay their token cost. See [references/browser-tools.md](references/browser-tools.md).

 ### Use Cases

@@ -95,7 +129,7 @@ web-access is a **procedural skill** that provides three complementary layers of

 ### Core Value

- **Three-layer progression**: from lightweight search to heavy JS rendering to logged-in access — pick on demand
+- **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**: connect to the user's already-logged-in Chrome via CDP — no re-login required

@@ -184,18 +218,22 @@ User intent
  │          - PyPI:   curl https://pypi.org/pypi/<pkg>/json
  │
  └─ "Real-time interactive task" (click, fill form, scroll, screenshot)
-        └─→ CDP + Playwright (see references/cdp-browser.md)
+        ├─→ **Default: BrowserXxx tools** (BrowserNavigate / BrowserEval / BrowserClick / BrowserScreenshot —
+        │     see references/browser-tools.md, no Python needed)
+        └─→ Fallback: CDP + Python Playwright (references/cdp-browser.md) when BrowserXxx is insufficient
+            (e.g., complex race conditions, multi-event waits, long-running in-browser scripts)
 ```

-### Three-layer strategy summary
+### Four-layer strategy summary

 | 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 | Login-gated, interactive | `Bash + Python Playwright CDP` | Medium (raw HTML, then clean via Jina or BS4) |
+| **L3-fast** | **Login-gated, interactive (PRIMARY)** | **BrowserXxx tool family** | Medium |
+| L3-fallback | Complex automation (race / long-wait / custom scripts) | `Bash + Python Playwright CDP` | Medium |

-**Default priority**: L1 for simple public pages → L2 for anything heavy → L3 only when login is required.
+**Default priority**: L1 for simple public pages → L2 for heavy → **L3-fast for login-gated** → L3-fallback only when BrowserXxx is insufficient.

 ---

@@ -311,6 +349,64 @@ See [references/cdp-browser.md](references/cdp-browser.md) for:

 ---

+## L3-fast: BrowserXxx Tool Cheatsheet (v2.0 recommended)
+
+**Only after you call `Skill('web-access')` will the following tools appear in `tools[]`.**
+
+| Tool | One-line example |
+|------|-----------------|
+| `BrowserListTabs()` | List all open tabs |
+| `BrowserNavigate({ url })` | Open URL in a new tab |
+| `BrowserNavigate({ target, url })` | Navigate an existing tab |
+| `BrowserEval({ target, expression })` | Run JS in the tab to extract structured data |
+| `BrowserClick({ target, selector, mode: 'real-mouse' })` | Real-mouse mode for anti-bot-strict sites |
+| `BrowserScreenshot({ target })` | Saved under ~/.desirecore/screenshots/ |
+| `BrowserScroll({ target, direction: 'bottom' })` | Trigger lazy loading |
+| `BrowserSetFiles({ target, selector, files })` | Upload local files (**user confirmation required**) |
+| `BrowserCloseTab({ target })` | Clean up temporary tabs at task end |
+
+Full API and edge cases: see [references/browser-tools.md](references/browser-tools.md).
+
+### Recommended flow (Xiaohongshu example)
+
+```
+1. BrowserListTabs() → check whether there's an already-logged-in xhs tab
+2. If not → BrowserNavigate({ url: "https://www.xiaohongshu.com/explore/abc123" })
+3. BrowserEval({ target, expression: "...JSON.stringify({title, content})" })
+4. SitePatternRead({ domain: "xiaohongshu.com" })  ← read accumulated experience
+5. At task end → BrowserCloseTab({ target })
+6. If you find a new pitfall → SitePatternWrite({ domain, scope: "agent", mode: "merge", content })
+```
+
+---
+
+## Site Experience Accumulation (v2.0)
+
+When the task ends and you've discovered new anti-bot pitfalls, effective selectors, or platform quirks, call:
+
+```
+SitePatternWrite({
+  domain: "xiaohongshu.com",
+  scope: "agent",     // agent=shared (Git-tracked, can be published); user=private
+  mode: "merge",      // merge appends; replace overwrites
+  content: "## Known pitfalls\n- 2026-05: ...",
+  confidence: "medium"
+})
+```
+
+Reads use a three-layer priority order:
+
+```
+SitePatternRead({ domain: "xiaohongshu.com" })
+  → users/<userId>/agents/<agentId>/memory/site-patterns/   (user-private)
+  → agents/<agentId>/memory/site-patterns/                  (agent-shared, Git)
+  → defaults/global-skills/web-access/references/site-patterns/  (global baseline, read-only)
+```
+
+Content containing cookies / tokens / phone numbers / emails will **automatically downgrade scope='user'** and notify you.
+
+---
+
 ## Common Workflows

 Read [references/workflows.md](references/workflows.md) for detailed templates:
@@ -351,6 +447,9 @@ Read [references/jina-reader.md](references/jina-reader.md) for Jina Reader posi
 - ❌ **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.
 - ❌ **Citing only after the fact** — collect URLs as you fetch, not from memory afterwards.
+- ❌ **(v2.0) Writing Python heredoc when BrowserXxx would do** — slow, requires Python+Playwright install, and bloats context. Prefer L3-fast; fall back to Python only when BrowserXxx is insufficient (race / long-wait / custom scripts).
+- ❌ **(v2.0) Discovering new pitfalls and not writing a site-pattern** — next time the same Agent runs the task, it'll repeat the same mistakes. Anything that took 2+ steps to figure out is worth `SitePatternWrite(scope='agent', mode='merge')`.
+- ❌ **(v2.0) Writing cookies / phone numbers to scope='agent'** — that layer is Git-tracked and may be published to the marketplace. SitePatternWrite auto-downgrades, but don't deliberately write secrets to the agent layer.

 ---

--- a/skills/web-access/SKILL.zh-CN.md
+++ b/skills/web-access/SKILL.zh-CN.md
@@ -4,13 +4,34 @@

 ## L0：一句话摘要

-三层联网访问工具包——搜索公开页面、Jina 优化抓取、CDP 登录态浏览器访问。
+四层联网访问工具包——搜索公开页面、Jina 优化抓取、BrowserXxx 内置工具家族（v2.0）、Python Playwright CDP 兜底。

 ## L1：概述与使用场景

 ### 能力描述

-web-access 是一个**流程型技能（Procedural Skill）**，提供三层互补的联网访问能力：Layer 1（WebSearch + WebFetch）用于公开页面；Layer 2（Jina Reader）用于 JS 渲染的重页面，默认节省 Token；Layer 3（Chrome CDP）用于需要登录态的站点（小红书/B站/微博/飞书/Twitter）。
+web-access 是一个**流程型技能（Procedural Skill）**，提供四层互补的联网访问能力：
+
+- **L1**（WebSearch + WebFetch）：公开页面，轻量
+- **L2**（Jina Reader）：JS 渲染的重页面，默认节省 Token
+- **L3-fast**（BrowserXxx 内置工具家族，**v2.0 新增**）：登录态站点首选——零 Python 依赖、内置 cdp-proxy 子进程、支持 CDP 真实鼠标事件
+- **L3-fallback**（Chrome CDP + Python Playwright）：复杂自动化场景兜底（长等待、特殊 race condition 等）
+
+### v2.0 新增：BrowserXxx 工具家族（默认隐藏，激活后才暴露）
+
+调用 `Skill('web-access')` 加载本技能时，以下 11 个工具被注入到当前会话，让 LLM 直接驱动浏览器：
+
+| 工具 | 用途 |
+|------|------|
+| BrowserListTabs / BrowserNavigate / BrowserCloseTab | tab 管理 |
+| BrowserEval | 执行 JS 提取数据 |
+| BrowserClick (`mode: js \| real-mouse`) | 点击元素，real-mouse 反爬更强 |
+| BrowserScreenshot / BrowserScroll | 截图、滚动触发懒加载 |
+| BrowserSetFiles | 上传本地文件（需用户确认） |
+| SitePatternRead / SitePatternWrite | 按域名累积"站点经验"（AgentFS 三层） |
+| LocalBookmarks | 检索本地 Chrome 书签 / 历史 |
+
+> **重要**：未调用 Skill('web-access') 之前，这些工具**不会**出现在 LLM 的 tools 列表里——默认对话不消耗其 token。详见 [references/browser-tools.md](references/browser-tools.md)。

 ### 使用场景

@@ -21,7 +42,7 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供三层互

 ### 核心价值

- **三层递进**：从轻量搜索到重度 JS 渲染到登录态访问，按需选择
+- **四层递进**：从轻量搜索到重度 JS 渲染到登录态访问，按需选择
 - **Token 优化**：Jina Reader 默认减少 50-80% Token 消耗
 - **登录态复用**：通过 CDP 连接用户已登录的 Chrome，无需重复登录

@@ -110,18 +131,22 @@ User intent
  │          - PyPI:   curl https://pypi.org/pypi/<pkg>/json
  │
  └─ "Real-time interactive task" (click, fill form, scroll, screenshot)
-        └─→ CDP + Playwright (see references/cdp-browser.md)
+        ├─→ **Default: BrowserXxx tools** (BrowserNavigate / BrowserEval / BrowserClick / BrowserScreenshot —
+        │     see references/browser-tools.md, no Python needed)
+        └─→ Fallback: CDP + Python Playwright (references/cdp-browser.md) when BrowserXxx is insufficient
+            (e.g., complex race conditions, multi-event waits, long-running in-browser scripts)
 ```

-### Three-layer strategy summary
+### 四层策略总结

 | 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 | Login-gated, interactive | `Bash + Python Playwright CDP` | Medium (raw HTML, then clean via Jina or BS4) |
+| **L3-fast** | **Login-gated, interactive (PRIMARY)** | **BrowserXxx 工具家族** | Medium |
+| L3-fallback | 复杂自动化（race / long-wait / 自定义脚本） | `Bash + Python Playwright CDP` | Medium |

-**Default priority**: L1 for simple public pages → L2 for anything heavy → L3 only when login is required.
+**Default priority**: L1 for simple public pages → L2 for heavy → **L3-fast for login-gated** → L3-fallback only when BrowserXxx 不够用。

 ---

@@ -237,6 +262,64 @@ See [references/cdp-browser.md](references/cdp-browser.md) for:

 ---

+## L3-fast: BrowserXxx 工具速查（v2.0 推荐）
+
+**只在你调用 `Skill('web-access')` 加载本技能后，下面这组工具才会出现在 tools[] 里。**
+
+| 工具 | 一行示例 |
+|------|---------|
+| `BrowserListTabs()` | 列出所有打开 tab |
+| `BrowserNavigate({ url })` | 在新 tab 打开 URL |
+| `BrowserNavigate({ target, url })` | 在指定 tab 跳转 |
+| `BrowserEval({ target, expression })` | 在 tab 内跑 JS，提取结构化数据 |
+| `BrowserClick({ target, selector, mode: 'real-mouse' })` | 反爬严格站点用真实鼠标事件 |
+| `BrowserScreenshot({ target })` | 写入 ~/.desirecore/screenshots/ |
+| `BrowserScroll({ target, direction: 'bottom' })` | 触发懒加载 |
+| `BrowserSetFiles({ target, selector, files })` | 上传本地文件（**需用户确认**） |
+| `BrowserCloseTab({ target })` | 任务收尾清理临时 tab |
+
+完整 API 与边界条件见 [references/browser-tools.md](references/browser-tools.md)。
+
+### 推荐流程（小红书示例）
+
+```
+1. BrowserListTabs() → 看是否已有登录态 tab
+2. 没有 → BrowserNavigate({ url: "https://www.xiaohongshu.com/explore/abc123" })
+3. BrowserEval({ target, expression: "(...)JSON.stringify({title, content})" })
+4. SitePatternRead({ domain: "xiaohongshu.com" })  ← 读累积经验
+5. 任务结束 → BrowserCloseTab({ target })
+6. 如发现新陷阱 → SitePatternWrite({ domain, scope: "agent", mode: "merge", content })
+```
+
+---
+
+## 站点经验积累（v2.0 新增）
+
+任务结束如果发现新的反爬陷阱、有效选择器、平台特征，调用：
+
+```
+SitePatternWrite({
+  domain: "xiaohongshu.com",
+  scope: "agent",     // agent=共享（受 Git 管理，发布给其他用户）；user=私有
+  mode: "merge",      // merge 追加，replace 覆盖
+  content: "## 已知陷阱\n- 2026-05: ...",
+  confidence: "medium"
+})
+```
+
+读取走三层优先级：
+
+```
+SitePatternRead({ domain: "xiaohongshu.com" })
+  → users/<userId>/agents/<agentId>/memory/site-patterns/   (用户私有)
+  → agents/<agentId>/memory/site-patterns/                  (Agent 共享, Git)
+  → defaults/global-skills/web-access/references/site-patterns/  (全局基线，只读)
+```
+
+含 cookie / token / 手机号 / 邮箱时 SitePatternWrite **自动降级 scope='user'** 并提示。
+
+---
+
 ## Common Workflows

 Read [references/workflows.md](references/workflows.md) for detailed templates:
@@ -277,6 +360,9 @@ Read [references/jina-reader.md](references/jina-reader.md) for Jina Reader posi
 - ❌ **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.
 - ❌ **Citing only after the fact** — collect URLs as you fetch, not from memory afterwards.
+- ❌ **(v2.0) 在能用 BrowserXxx 时仍写 Python heredoc** — 慢、依赖 Python+Playwright 安装、上下文体积大。优先 L3-fast；只在 BrowserXxx 不够（race / 长等待 / 自定义脚本）时才回退。
+- ❌ **(v2.0) 任务结束发现新陷阱却不写 site-pattern** — 下次同 Agent 再做相同任务会重复踩坑。任何"花了 2+ 步才搞清楚的细节"都值得 `SitePatternWrite(scope='agent', mode='merge')`。
+- ❌ **(v2.0) 把含 cookie / 手机号的内容写到 scope='agent'** — 这层会被 Git 提交、可能发布到市场。SitePatternWrite 会自动降级，但你不该故意往 agent 层写敏感信息。

 ---

--- a/skills/web-access/references/browser-tools.md
+++ b/skills/web-access/references/browser-tools.md
@@ -0,0 +1,142 @@
+# BrowserXxx 工具速查（L3-fast）
+
+> 适配自 [eze-is/web-access](https://github.com/eze-is/web-access) 的 `references/cdp-api.md`（MIT，作者 一泽 Eze）。
+> DesireCore 把 cdp-proxy 内嵌为子进程，并通过这组 BuiltinTool 调用——比直接 curl 更安全（不暴露端口给 prompt 注入）、比 Python heredoc 更轻（无 Python/Playwright 依赖）。
+
+## 何时用 BrowserXxx vs Python Playwright
+
+| 场景 | 推荐 |
+|------|------|
+| 抓取登录态站点（小红书 / B站 / 微博 / 飞书 / 知乎） | **BrowserXxx**（fast，零 Python） |
+| 简单点击 / 滚动 / 截图 / 上传文件 | **BrowserXxx** |
+| 需要复杂等待逻辑（page.wait_for_selector + race condition） | Python Playwright（cdp-browser.md） |
+| 需要在浏览器内运行长时间脚本（>30 s） | Python Playwright |
+
+## 前置条件
+
+1. 用户已启动调试模式 Chrome（端口 9222；见 SKILL.md 的 Prerequisites 部分）
+2. cdp-proxy 子进程会在首次工具调用时由 agent-service lazy spawn
+
+## 工具一览
+
+每个工具默认 `hidden: true`，**只有 web-access 技能被激活后才暴露给 LLM**。
+
+### BrowserListTabs
+
+列出已打开 tab。返回每行 `[targetId] title — url`。
+
+```yaml
+BrowserListTabs:
+  # 无参数
+```
+
+### BrowserNavigate
+
+打开 URL；省略 `target` 时新开 tab。
+
+```yaml
+BrowserNavigate:
+  url: https://www.xiaohongshu.com/explore/...
+  target: <可选 targetId>
+```
+
+### BrowserEval
+
+在指定 tab 内执行 JS（`returnByValue: true` + `awaitPromise: true`）。
+
+```yaml
+BrowserEval:
+  target: <targetId>
+  expression: |
+    (() => {
+      const t = document.querySelector('h1.video-title')?.textContent || ''
+      const d = document.querySelector('.video-desc')?.textContent || ''
+      return JSON.stringify({ title: t.trim(), desc: d.trim() })
+    })()
+```
+
+提示：
+- DOM 节点不能直接返回，要提取属性
+- 大量数据用 `JSON.stringify()` 包裹返回字符串
+- 风险等级 medium：是任意 JS 入口，不要执行不可信代码
+
+### BrowserClick
+
+```yaml
+BrowserClick:
+  target: <targetId>
+  selector: button.submit
+  mode: real-mouse   # 默认 js；登录态站点反爬严格时建议 real-mouse
+```
+
+`mode: real-mouse` 走 CDP `Input.dispatchMouseEvent` 派发真实鼠标事件——能触发文件对话框、绕过部分反自动化检测。
+
+### BrowserScreenshot
+
+```yaml
+BrowserScreenshot:
+  target: <targetId>
+  filename: 自定义文件名.png  # 可选；写入 ~/.desirecore/screenshots/
+```
+
+### BrowserScroll
+
+```yaml
+BrowserScroll:
+  target: <targetId>
+  direction: bottom    # 或 top；与 y 二选一
+  # y: 3000           # 按像素滚动
+```
+
+### BrowserSetFiles（**需用户确认**）
+
+为 input[type=file] 设置本地文件，绕过文件对话框。涉及上传，必须经 user confirmation。
+
+```yaml
+BrowserSetFiles:
+  target: <targetId>
+  selector: input[type=file]
+  files:
+    - /Users/me/Pictures/photo.png
+```
+
+### BrowserCloseTab
+
+```yaml
+BrowserCloseTab:
+  target: <targetId>
+```
+
+任务收尾建议清理你创建的临时 tab，避免 cdp-proxy 的 tab 池堆积（15 min 后会自动 GC，但显式关更整洁）。
+
+## SitePatternRead / SitePatternWrite
+
+参见 SKILL.md 的"站点经验积累"章节。任务结束如果发现新陷阱、新选择器，调用：
+
+```yaml
+SitePatternWrite:
+  domain: xiaohongshu.com
+  scope: agent           # agent=共享（受 Git 管理，可发布）；user=私有
+  mode: merge            # 默认 merge 追加；replace 覆盖
+  content: |
+    ## 已知陷阱
+    - 2026-05: ...
+```
+
+含 cookie/token/手机号/邮箱时会自动降级 scope='user'。
+
+## 错误处理
+
+| 错误 | 原因 | 解决 |
+|------|------|------|
+| `Chrome 未开启远程调试端口` | 用户没启动调试 Chrome | 引导用户跑 SKILL.md 中的启动命令 |
+| `attach 失败` | targetId 无效或 tab 已关闭 | 重新 `BrowserListTabs` |
+| `CDP 命令超时` | 页面长时间未响应 | 检查页面状态，必要时 `BrowserCloseTab` 后重开 |
+| `CDP proxy 请求被中止或超时` | 代理子进程异常或网络故障 | 等待 ProxyController 自动重启（最多 3 次） |
+
+## 调用链路
+
+```
+Agent → BrowserXxx 工具 → proxy-client → cdp-proxy 子进程 → Chrome (DevTools Protocol)
+                          ↑ 首次调用 lazy spawn 子进程
+```
--- a/skills/web-access/references/site-patterns/_index.md
+++ b/skills/web-access/references/site-patterns/_index.md
@@ -0,0 +1,21 @@
+# 站点经验基线索引
+
+本目录是 web-access 技能内置的"全局基线 site-pattern"——所有 Agent 默认能读到，但**写入时请用 `SitePatternWrite(scope='agent')`** 落到 Agent 共享层（`agents/<id>/memory/site-patterns/`），不要直接修改本目录。
+
+读取顺序（最先命中即返回）：
+
+1. **用户私有**：`users/<userId>/agents/<agentId>/memory/site-patterns/<domain>.md`
+2. **Agent 共享**：`agents/<agentId>/memory/site-patterns/<domain>.md`（受 Git 管理，可发布）
+3. **全局基线**：本目录（只读，跟随 web-access 技能版本发布）
+
+## 已知站点
+
+| Domain | 别名 | 推荐路径 |
+|--------|------|---------|
+| `xiaohongshu.com` | 小红书 / 红薯 / xhs | L3 CDP（强制登录） |
+| `bilibili.com` | B站 / 哔哩哔哩 | L3 CDP（视频描述、评论需登录） |
+| `weibo.com` | 微博 | L3 CDP（长微博需登录） |
+| `zhihu.com` | 知乎 | L3 CDP（长文 + 评论需登录） |
+| `feishu.cn` | 飞书 / Lark | L3 CDP（必须登录） |
+
+后续 Agent 自学积累的新站点会落在 `agents/<id>/memory/site-patterns/`，对所有 Agent 用户可见。
--- a/skills/web-access/references/site-patterns/bilibili.com.md
+++ b/skills/web-access/references/site-patterns/bilibili.com.md
@@ -0,0 +1,41 @@
+---
+domain: bilibili.com
+aliases: [B站, 哔哩哔哩, 小破站]
+type: site-pattern
+pinned: true
+confidence: medium
+learned_at: '2026-05-05'
+updated_at: '2026-05-05'
+---
+
+## L0
+公开主页可 WebFetch；视频详情 / 评论 / 长简介 / 收藏夹建议 L3 CDP。
+
+## 平台特征
+- 视频页：基础信息（标题、UP 主、播放数）公开 SSR；完整描述 / 弹幕 / 评论需 JS 渲染或登录
+- 列表页（首页 / 分区）：大部分公开，可走 WebFetch + Jina
+- API：`api.bilibili.com/x/...` 部分接口公开，可 curl 直接拉数据
+
+## 推荐流程
+- 仅取标题/UP 主/播放数 → WebFetch 即可
+- 取完整简介 / 评论 → BrowserNavigate + BrowserEval
+- 批量数据 → 优先尝试 `api.bilibili.com` 公开接口（有专门的 wbi 签名机制）
+
+## 推荐选择器
+- 视频标题：`h1.video-title` 或 `[class*='video-title']`
+- UP 主：`a.up-name` / `.up-detail-top a`
+- 视频简介：`.video-desc` / `[class*='desc-info']`
+- 评论：`.reply-item .content`
+- 弹幕：通过 `api.bilibili.com/x/v1/dm/list.so` 拉 XML
+
+## 已知陷阱
+- ❌ headless 抓详情：部分元素只在 viewport 内才渲染（懒加载）
+- ❌ 用户主页评论：必须登录
+- ⚠️ 直接 fetch `api.bilibili.com` 高频接口（如 `wbi/...`）需要 wbi 签名，否则返回 -403
+
+## 反爬细节
+- 视频 BV 号 ↔ AV 号：可通过本地工具或 `api.bilibili.com/x/web-interface/view?bvid=...` 互转
+- 弹幕 `oid`（cid）需先从视频元数据接口拿到
+
+## 历史更新
+- 2026-05-05：初版基线，待实际验证调整
--- a/skills/web-access/references/site-patterns/feishu.cn.md
+++ b/skills/web-access/references/site-patterns/feishu.cn.md
@@ -0,0 +1,40 @@
+---
+domain: feishu.cn
+aliases: [飞书, Lark, lark.com]
+type: site-pattern
+pinned: true
+confidence: high
+learned_at: '2026-05-05'
+updated_at: '2026-05-05'
+---
+
+## L0
+**强登录、强权限**站点；必须 L3 CDP 复用用户登录态；优先用飞书 OpenAPI。
+
+## 平台特征
+- 文档 / 多维表格 / 知识库：完全 SPA，未登录无法访问
+- 权限模型严格：用户即使登录，也可能因企业空间隔离打不开他人文档
+- OpenAPI 完整：`open.feishu.cn/open-apis/...`，企业可申请 access_token 获取大多数数据
+- 国际版 `lark.com` 与国内版 `feishu.cn` 有不同的鉴权域
+
+## 推荐流程
+1. 公开文档（companion 页面/官方文档站点 `feishu.cn/hc/...`）→ WebFetch / Jina
+2. 用户文档 → BrowserNavigate（已登录 Chrome）+ BrowserEval 抓正文
+3. 长期程序化访问 → 申请 OpenAPI access_token，走 HTTP，避免 CDP
+
+## 推荐选择器
+- 文档标题：`.title-input` / `header [class*='title']`
+- 富文本正文：`.lark-editor-render` / `[contenteditable] .ace-line`
+- 评论：`.lark-comment` / `[class*='comment']`
+
+## 已知陷阱
+- ❌ 直接 WebFetch 用户文档 URL：返回登录占位 HTML
+- ❌ 跨企业空间访问：即使登录也是 403，DOM 提示"无权限"
+- ⚠️ Lark vs 飞书：URL 结构相似但 cookie 域不同，不能复用同一登录态
+
+## 反爬细节
+- session 强绑定 IP + 设备指纹，跨设备复用 cookie 会失效
+- 自动化操作（高频 click/scroll）可能触发企业管理员告警
+
+## 历史更新
+- 2026-05-05：初版基线
--- a/skills/web-access/references/site-patterns/weibo.com.md
+++ b/skills/web-access/references/site-patterns/weibo.com.md
@@ -0,0 +1,40 @@
+---
+domain: weibo.com
+aliases: [微博, 围脖]
+type: site-pattern
+pinned: true
+confidence: medium
+learned_at: '2026-05-05'
+updated_at: '2026-05-05'
+---
+
+## L0
+长微博 / 视频微博 / 用户主页几乎都需登录；走 L3 CDP；移动版 m.weibo.cn 部分公开。
+
+## 平台特征
+- 桌面版（weibo.com）：未登录跳登录墙
+- 移动版（m.weibo.cn）：列表与单条详情有时可匿名访问，且 DOM 简洁
+- 长微博：触发"展开全文"按钮后才渲染完整内容
+
+## 推荐流程
+1. 单条公开微博 → 优先尝试 `https://m.weibo.cn/status/<id>`，WebFetch 看是否拿到正文
+2. 拿不到 → BrowserNavigate（已登录态 Chrome）+ BrowserClick 点"展开" + BrowserEval 取正文
+3. 用户主页时间线：必须登录，BrowserScroll 触发懒加载
+
+## 推荐选择器
+- 单条详情：`.weibo-text` / `[class*='WB_text']`
+- 展开全文按钮：`a:has-text("展开全文")` 或 `.toggle-full`
+- 时间戳：`a[class*='time']`
+- 转发链：`.weibo-og`（被转发的原文）
+
+## 已知陷阱
+- ❌ 桌面版未登录抓取：HTML 几乎是空壳
+- ❌ JS 关闭：m.weibo.cn 仍依赖 JS 渲染长内容
+- ⚠️ 视频微博：流地址有 referer / token 校验，直接 yt-dlp 可能失败
+
+## 反爬细节
+- 桌面 weibo.com 严格检查 cookies 中的 SUB / SUBP；过期立即跳转登录
+- 短时间高频访问会触发"小黑屋"——账号被禁登录
+
+## 历史更新
+- 2026-05-05：初版基线
--- a/skills/web-access/references/site-patterns/xiaohongshu.com.md
+++ b/skills/web-access/references/site-patterns/xiaohongshu.com.md
@@ -0,0 +1,47 @@
+---
+domain: xiaohongshu.com
+aliases: [小红书, 红薯, xhs, RED]
+type: site-pattern
+pinned: true
+confidence: high
+learned_at: '2026-05-05'
+updated_at: '2026-05-05'
+---
+
+## L0
+强登录站点，必须走 L3 CDP；笔记详情 `.note-content`，列表卡片 `.note-card`；URL 必带 `xsec_token`。
+
+## 平台特征
+- 强制登录：未登录会跳转登录墙，DOM 中没有正文
+- 富 SPA：路由全靠 JS，WebFetch 拿到的 HTML 几乎是空壳
+- 反爬严格：短时间多次请求会触发风控（验证码 / 限流）
+- xsec_token：详情页 URL 包含 `xsec_token=...`，**通过站内交互生成**——直接拼 URL 容易失败
+
+## 推荐流程
+1. 通过 BrowserListTabs 找到已登录的 xhs tab；如无，BrowserNavigate 打开
+2. BrowserEval 注入选择器抓取标题与正文
+3. 列表页用 `[...document.querySelectorAll('.note-card a')].map(a => a.href)` 收集详情页链接
+4. 单条笔记结尾调用 `BrowserCloseTab` 释放 tab，避免 tab 池溢出
+
+## 推荐选择器
+- 笔记标题：`#detail-title` 或 `h1[class*="title"]`
+- 笔记正文：`#detail-desc` 或 `.note-content`
+- 评论区：`.comments-container .comment-item`
+- 列表卡：`.note-card`，链接 `.note-card a.cover`
+
+## 已知陷阱
+- ❌ 直接 WebFetch 笔记 URL：返回登录墙 HTML，解析无效
+- ❌ Headless 模式访问：丢失登录态，触发风控
+- ❌ 高频抓取：>30 req/min 易触发验证码
+
+## 反爬细节
+- xsec_token 由前端生成，与会话/路由绑定，不能跨 tab 复用太久
+- User-Agent 检查较弱，但 navigator.webdriver 必须为 false（cdp-proxy 已默认绕过）
+- click 操作建议优先用 `mode='real-mouse'`（CDP 真实鼠标事件），避免被 .click() 检测
+
+## 速率限制
+- 自评：单 IP 每分钟 ≤ 30 个详情页请求；超过会出验证码
+- 风控触发后：等 5-10 分钟自然解除；同账号短期内反复触发可能短封
+
+## 历史更新
+- 2026-05-05：初版基线（基于公开经验整理，待 Agent 实际验证升级 confidence）
--- a/skills/web-access/references/site-patterns/zhihu.com.md
+++ b/skills/web-access/references/site-patterns/zhihu.com.md
@@ -0,0 +1,41 @@
+---
+domain: zhihu.com
+aliases: [知乎]
+type: site-pattern
+pinned: true
+confidence: medium
+learned_at: '2026-05-05'
+updated_at: '2026-05-05'
+---
+
+## L0
+专栏文章公开可 WebFetch；问答详情、评论、回答列表建议 L3 CDP。
+
+## 平台特征
+- 文章 `zhuanlan.zhihu.com/p/<id>`：通常完全公开，WebFetch 即可
+- 问答 `zhihu.com/question/<qid>`：未登录可看部分回答；完整内容、评论、点赞数需登录
+- 移动 web `m.zhihu.com`：约束更松，对匿名相对友好
+
+## 推荐流程
+1. 专栏文章 → WebFetch / Jina Reader 优先
+2. 问答详情 → BrowserNavigate + BrowserEval；批量回答用 `[...document.querySelectorAll('.AnswerItem')].map(...)`
+3. 评论 → 必须登录，BrowserClick 展开，BrowserScroll 加载更多
+
+## 推荐选择器
+- 文章标题：`h1.Post-Title` / `h1[class*='Title']`
+- 文章正文：`div.Post-RichText` / `[class*='RichText']`
+- 回答列表：`.AnswerItem` / `[class*='AnswerItem']`
+- 单条回答：`.RichContent-inner`
+- 评论：`.CommentItemV2 .CommentRichText`
+
+## 已知陷阱
+- ❌ 直接 WebFetch 问答详情：只看到登录引导
+- ⚠️ 长回答有"展开"按钮，触发前 DOM 不完整
+- ⚠️ 知乎付费内容（盐选）即使登录也需会员
+
+## 反爬细节
+- d_c0、z_c0 等 cookie 决定登录态
+- 风控：异常 UA / 短时高频 → 触发滑动验证码
+
+## 历史更新
+- 2026-05-05：初版基线