diff --git a/manifest.json b/manifest.json index 47fa94b..1fb23d2 100644 --- 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", diff --git a/skills/web-access/SKILL.md b/skills/web-access/SKILL.md index d4fa022..9f15d4b 100644 --- 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//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//agents//memory/site-patterns/ (user-private) + → agents//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. --- diff --git a/skills/web-access/SKILL.zh-CN.md b/skills/web-access/SKILL.zh-CN.md index 5c21c5d..5b4de6b 100644 --- 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//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//agents//memory/site-patterns/ (用户私有) + → agents//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 层写敏感信息。 --- diff --git a/skills/web-access/references/browser-tools.md b/skills/web-access/references/browser-tools.md new file mode 100644 index 0000000..453e6ac --- /dev/null +++ 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: + 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: + selector: button.submit + mode: real-mouse # 默认 js;登录态站点反爬严格时建议 real-mouse +``` + +`mode: real-mouse` 走 CDP `Input.dispatchMouseEvent` 派发真实鼠标事件——能触发文件对话框、绕过部分反自动化检测。 + +### BrowserScreenshot + +```yaml +BrowserScreenshot: + target: + filename: 自定义文件名.png # 可选;写入 ~/.desirecore/screenshots/ +``` + +### BrowserScroll + +```yaml +BrowserScroll: + target: + direction: bottom # 或 top;与 y 二选一 + # y: 3000 # 按像素滚动 +``` + +### BrowserSetFiles(**需用户确认**) + +为 input[type=file] 设置本地文件,绕过文件对话框。涉及上传,必须经 user confirmation。 + +```yaml +BrowserSetFiles: + target: + selector: input[type=file] + files: + - /Users/me/Pictures/photo.png +``` + +### BrowserCloseTab + +```yaml +BrowserCloseTab: + target: +``` + +任务收尾建议清理你创建的临时 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 子进程 +``` diff --git a/skills/web-access/references/site-patterns/_index.md b/skills/web-access/references/site-patterns/_index.md new file mode 100644 index 0000000..aaa2299 --- /dev/null +++ b/skills/web-access/references/site-patterns/_index.md @@ -0,0 +1,21 @@ +# 站点经验基线索引 + +本目录是 web-access 技能内置的"全局基线 site-pattern"——所有 Agent 默认能读到,但**写入时请用 `SitePatternWrite(scope='agent')`** 落到 Agent 共享层(`agents//memory/site-patterns/`),不要直接修改本目录。 + +读取顺序(最先命中即返回): + +1. **用户私有**:`users//agents//memory/site-patterns/.md` +2. **Agent 共享**:`agents//memory/site-patterns/.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//memory/site-patterns/`,对所有 Agent 用户可见。 diff --git a/skills/web-access/references/site-patterns/bilibili.com.md b/skills/web-access/references/site-patterns/bilibili.com.md new file mode 100644 index 0000000..ced7636 --- /dev/null +++ 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:初版基线,待实际验证调整 diff --git a/skills/web-access/references/site-patterns/feishu.cn.md b/skills/web-access/references/site-patterns/feishu.cn.md new file mode 100644 index 0000000..9862b22 --- /dev/null +++ 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:初版基线 diff --git a/skills/web-access/references/site-patterns/weibo.com.md b/skills/web-access/references/site-patterns/weibo.com.md new file mode 100644 index 0000000..af99701 --- /dev/null +++ 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/`,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:初版基线 diff --git a/skills/web-access/references/site-patterns/xiaohongshu.com.md b/skills/web-access/references/site-patterns/xiaohongshu.com.md new file mode 100644 index 0000000..45fa2b4 --- /dev/null +++ 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) diff --git a/skills/web-access/references/site-patterns/zhihu.com.md b/skills/web-access/references/site-patterns/zhihu.com.md new file mode 100644 index 0000000..e24e2cd --- /dev/null +++ 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/`:通常完全公开,WebFetch 即可 +- 问答 `zhihu.com/question/`:未登录可看部分回答;完整内容、评论、点赞数需登录 +- 移动 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:初版基线