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 09: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/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：初版基线