mirror of https://git.openapi.site/https://github.com/desirecore/market.git synced 2026-06-06 07:10:44 +08:00

Files

yi-ge 93fd40f661 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-05-06 12:05:39 +08:00

4.3 KiB

Raw Blame History

BrowserXxx 工具速查（L3-fast）

适配自 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

前置条件

用户已启动调试模式 Chrome（端口 9222；见 SKILL.md 的 Prerequisites 部分）
cdp-proxy 子进程会在首次工具调用时由 agent-service lazy spawn

工具一览

每个工具默认 hidden: true，只有 web-access 技能被激活后才暴露给 LLM。

BrowserListTabs

列出已打开 tab。返回每行 [targetId] title — url。

BrowserListTabs:
  # 无参数

BrowserNavigate

打开 URL；省略 target 时新开 tab。

BrowserNavigate:
  url: https://www.xiaohongshu.com/explore/...
  target: <可选 targetId>

BrowserEval

在指定 tab 内执行 JS（returnByValue: true + awaitPromise: true）。

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

BrowserClick:
  target: <targetId>
  selector: button.submit
  mode: real-mouse   # 默认 js；登录态站点反爬严格时建议 real-mouse

mode: real-mouse 走 CDP Input.dispatchMouseEvent 派发真实鼠标事件——能触发文件对话框、绕过部分反自动化检测。

BrowserScreenshot

BrowserScreenshot:
  target: <targetId>
  filename: 自定义文件名.png  # 可选；写入 ~/.desirecore/screenshots/

BrowserScroll

BrowserScroll:
  target: <targetId>
  direction: bottom    # 或 top；与 y 二选一
  # y: 3000           # 按像素滚动

BrowserSetFiles（需用户确认）

为 input[type=file] 设置本地文件，绕过文件对话框。涉及上传，必须经 user confirmation。

BrowserSetFiles:
  target: <targetId>
  selector: input[type=file]
  files:
    - /Users/me/Pictures/photo.png

BrowserCloseTab

BrowserCloseTab:
  target: <targetId>

任务收尾建议清理你创建的临时 tab，避免 cdp-proxy 的 tab 池堆积（15 min 后会自动 GC，但显式关更整洁）。

SitePatternRead / SitePatternWrite

参见 SKILL.md 的"站点经验积累"章节。任务结束如果发现新陷阱、新选择器，调用：

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 子进程

4.3 KiB Raw Blame History Unescape Escape