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:
@@ -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 层写敏感信息。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user