mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-06-06 10:30:39 +08:00
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）
This commit is contained in:
142
skills/web-access/references/browser-tools.md
Normal file
142
skills/web-access/references/browser-tools.md
Normal file
@@ -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 子进程
|
||||
```
|
||||
Reference in New Issue
Block a user