From b2865d501dff2da99961a80df874c58647b09f56 Mon Sep 17 00:00:00 2001 From: Yige Date: Thu, 6 Aug 2026 01:36:49 +0800 Subject: [PATCH] =?UTF-8?q?fix(web-access):=20=E4=BF=AE=E6=AD=A3=E5=86=85?= =?UTF-8?q?=E7=BD=AE=E6=B5=8F=E8=A7=88=E5=99=A8=E5=B7=A5=E5=85=B7=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E4=B8=8E=E5=AE=A2=E6=88=B7=E7=AB=AF=E7=89=88=E6=9C=AC?= =?UTF-8?q?=E9=97=A8=E6=8E=A7=20(#73)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 跟进 desirecore/desirecore#1718 的 Codex review，修掉 web-access v2.1.0 正文中 4 处与真实工具实现不符的地方（均对照 desirecore@origin/dev 源码核实）： - 补 market.required_client_version: 10.0.98，避免老客户端把可用的 v2.0 换成调用不存在工具的说明 - BrowserImport 动作名修正：真实枚举 discover/create_plan/dry_run/apply/rollback/list_plans，无 'plan'；domains 由 create_plan 消费；planId 前缀 bimp_ - input.wheel 示例补 x/y（schema 硬要求），capabilities 示例补 browser.input.pointer.wheel 并说明显式列表是做减法 - BrowserImport 降级为需额外授权的可选路径：browser.import.* 不在 agentDefault 内且 agentElevated 在工具层零引用，登录态默认改回 L3-fallback CDP skill 2.1.0 → 2.1.1，manifest 1.2.19 → 1.2.20，human-locked 的 en-US 已重新对齐 source_hash。 --- manifest.json | 2 +- skills/web-access/SKILL.md | 29 +++++++----- skills/web-access/SKILL.zh-CN.md | 20 +++++---- skills/web-access/references/browser-tools.md | 44 ++++++++++++++++--- .../references/site-patterns/feishu.cn.md | 2 +- .../references/site-patterns/weibo.com.md | 2 +- .../site-patterns/xiaohongshu.com.md | 3 +- 7 files changed, 71 insertions(+), 31 deletions(-) diff --git a/manifest.json b/manifest.json index 6ae6e4b..af59429 100644 --- a/manifest.json +++ b/manifest.json @@ -1,6 +1,6 @@ { "name": "DesireCore Official Market", - "version": "1.2.19", + "version": "1.2.20", "schemaVersion": "1.1.0", "supportedLocales": ["zh-CN", "en-US"], "defaultLocale": "en-US", diff --git a/skills/web-access/SKILL.md b/skills/web-access/SKILL.md index 5dcaf45..e32fffc 100644 --- a/skills/web-access/SKILL.md +++ b/skills/web-access/SKILL.md @@ -16,7 +16,7 @@ description: >- 新闻、网址、URL、找一下、搜一下、查一下、小红书、B站、微博、飞书、Twitter、 推特、X、知乎、公众号、已登录、登录状态。 license: Complete terms in LICENSE.txt -version: 2.1.0 +version: 2.1.1 type: procedural risk_level: low status: enabled @@ -53,14 +53,14 @@ metadata: short_desc: 联网搜索、网页抓取、内置受管浏览器登录态访问、研究调研工作流 description: 四层联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器登录态访问、Python Playwright CDP 兜底。 body: ./SKILL.zh-CN.md - source_hash: sha256:2e6753fc05142e9a + source_hash: sha256:ce46e1982de8cd65 translated_by: human en-US: name: Web Access short_desc: Web search, page fetching, logged-in access via the governed built-in browser, research workflows description: A four-layer web-access toolkit — search public pages, fetch heavy pages via Jina Reader, reach logged-in sites through the governed built-in browser, and fall back to Chrome CDP. body: ./SKILL.md - source_hash: sha256:2e6753fc05142e9a + source_hash: sha256:ce46e1982de8cd65 translated_by: human market: icon: >- @@ -79,6 +79,7 @@ market: fill-opacity="0.12"/> category: research + required_client_version: 10.0.98 maintainer: name: DesireCore Official verified: true @@ -111,7 +112,7 @@ When you call `Skill('web-access')`, the following 8 tools are injected into the | BrowserManage | Create/destroy isolated BrowserSpace, start sessions, manage tabs | | BrowserSnapshot | `semantic` / `accessibility` / `visual` page snapshots — the primary way to read a page | | BrowserAct | One governed action per call: navigate, click, type, scroll, screenshot, … | -| BrowserImport | Import Cookies from the user's Chrome/Edge/Firefox/Safari profile (human-approved) | +| BrowserImport | Import Cookies from the user's Chrome/Edge/Firefox/Safari profile (human-approved; **needs `browser.import.*` granted by the Host — not available to a plain `create_space` session**) | | BrowserShare | Delegate a Space/Session to another Agent (isolated / snapshot / copy-on-write / live) | | SitePatternRead / SitePatternWrite | Per-domain "site experience" (AgentFS three-layer) | | LocalBookmarks | Search local Chrome bookmarks / history | @@ -131,7 +132,7 @@ When you call `Skill('web-access')`, the following 8 tools are injected into the - **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**: import the user's existing Cookies into an isolated Space via BrowserImport (or attach to their Chrome via CDP in the fallback layer) — no re-login required +- **Logged-in session reuse**: attach to the user's Chrome via CDP in the fallback layer, or — where the Host has granted `browser.import.*` — import their Cookies into an isolated Space via BrowserImport; either way, no re-login required ## L2: Detailed Specification @@ -147,7 +148,7 @@ If any fetch fails, explicitly tell the user which URL failed and which fallback ## Prerequisites: Chrome CDP Setup (for login-gated sites) -**Only required for the L3-fallback layer** (Python Playwright). The L3-fast built-in browser does not need this — use `BrowserImport` to reuse the user's login instead. +**Required for the L3-fallback layer** (Python Playwright) — and, in practice, still the reliable way to reuse a login. The L3-fast built-in browser can skip it only when the Host has granted `browser.import.*` so that `BrowserImport` actually works; otherwise set this up. ### One-time setup @@ -206,9 +207,10 @@ User intent │ (Jina Reader = default for JS-rendered content, saves tokens) │ ├─ "Read this login-gated page" (Xiaohongshu/Bilibili/Weibo/Feishu/Twitter/Zhihu/WeChat) - │ ├─→ Reach it: BrowserManage(create_space/start_session) → BrowserImport(cookies for - │ │ that domain) → BrowserAct(tab.navigate) → tab.activate + page.screenshot - │ │ to confirm you landed on the content (semantic snapshot has no body text) + │ ├─→ Reach it: BrowserManage(create_space/start_session) → BrowserAct(tab.navigate) + │ │ → tab.activate + page.screenshot to confirm you landed on the content + │ │ (semantic snapshot has no body text). Logged-in? BrowserImport only if + │ │ browser.import.* was granted — otherwise reuse the login via CDP below. │ └─→ Extract the text: verify CDP ready, then python3 playwright.connect_over_cdp() │ → page.content() → Jina Reader / BeautifulSoup │ @@ -363,9 +365,9 @@ See [references/cdp-browser.md](references/cdp-browser.md) for: | `BrowserSnapshot({ mode: 'semantic' })` | Read the page: interactive elements + `ref` handles | | `BrowserAct({ action: 'input.click', params: { ref } })` | Click by snapshot `ref`, never by raw x/y | | `BrowserAct({ action: 'input.text', params: { text } })` | Type into the focused element | -| `BrowserAct({ action: 'input.wheel', params: { deltaX: 0, deltaY: 720 } })` | Scroll to trigger lazy loading | +| `BrowserAct({ action: 'input.wheel', params: { x: 640, y: 400, deltaX: 0, deltaY: 720 } })` | Scroll to trigger lazy loading — `x`/`y` (or `ref`) is **required**, and the session needs `browser.input.pointer.wheel` | | `BrowserAct({ action: 'tab.activate', params: { bounds } })` → `page.screenshot` | **activate first, then screenshot** | -| `BrowserImport({ action: 'discover' \| 'plan' \| 'apply' })` | Reuse the user's login cookies (human-approved) | +| `BrowserImport({ action: 'discover' \| 'create_plan' \| 'dry_run' \| 'apply' \| 'rollback' \| 'list_plans' })` | Reuse the user's login cookies — those 6 are the **complete** action set; happy path is `discover → create_plan → dry_run → apply`. **Needs `browser.import.*`, which `create_space` does not grant** (see below) | Full API and edge cases: see [references/browser-tools.md](references/browser-tools.md). @@ -385,7 +387,10 @@ Full API and edge cases: see [references/browser-tools.md](references/browser-to ``` 1. BrowserManage({ action: 'create_space', name: 'xhs-note', persistence: 'ephemeral' }) 2. BrowserManage({ action: 'start_session', spaceId, capabilities: [...] }) -3. BrowserImport({ action: 'discover' }) → plan → apply for xiaohongshu.com ← reuse login + ← an explicit list *narrows* the lease; include browser.input.pointer.wheel if you will scroll +3. Reuse the login: L3-fallback Playwright against the user's own Chrome is the default path. + BrowserImport({ action: 'discover' → 'create_plan' → 'dry_run' → 'apply' }) only works if the + Host granted browser.import.* separately — create_space alone does not. If it is denied, fall back. 4. BrowserAct({ action: 'tab.navigate', params: { url: 'https://www.xiaohongshu.com/explore/abc123' } }) 5. BrowserSnapshot({ mode: 'semantic' }) ← element refs for interaction (no body text) tab.activate + page.screenshot ← confirm the note actually rendered diff --git a/skills/web-access/SKILL.zh-CN.md b/skills/web-access/SKILL.zh-CN.md index 38ebb20..51b7d2a 100644 --- a/skills/web-access/SKILL.zh-CN.md +++ b/skills/web-access/SKILL.zh-CN.md @@ -26,7 +26,7 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供四层互 | BrowserManage | 建/销隔离 BrowserSpace、启动会话、管理标签页 | | BrowserSnapshot | `semantic` / `accessibility` / `visual` 快照——读页面的主通道 | | BrowserAct | 一次调用一个受管动作：导航、点击、输入、滚动、截图…… | -| BrowserImport | 从用户 Chrome/Edge/Firefox/Safari 配置导入 Cookie（需人工审批） | +| BrowserImport | 从用户 Chrome/Edge/Firefox/Safari 配置导入 Cookie（需人工审批；**还需 Host 授予 `browser.import.*`，普通 `create_space` 会话拿不到**） | | BrowserShare | 把 Space/Session 委派给其他 Agent（隔离 / 快照 / 写时复制 / 实时共享） | | SitePatternRead / SitePatternWrite | 按域名累积"站点经验"（AgentFS 三层） | | LocalBookmarks | 检索本地 Chrome 书签 / 历史 | @@ -46,7 +46,7 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供四层互 - **四层递进**：从轻量搜索到重度 JS 渲染到登录态访问，按需选择 - **Token 优化**：Jina Reader 默认减少 50-80% Token 消耗 -- **登录态复用**：用 BrowserImport 把用户已有 Cookie 导入隔离 Space（兜底层仍可 CDP 连用户 Chrome），无需重复登录 +- **登录态复用**：兜底层 CDP 连用户 Chrome，或在 Host 已授予 `browser.import.*` 时用 BrowserImport 把 Cookie 导入隔离 Space；两条路都不必重新登录 ## L2：详细规范 @@ -62,7 +62,7 @@ If any fetch fails, explicitly tell the user which URL failed and which fallback ## Prerequisites: Chrome CDP Setup (for login-gated sites) -**Only required for the L3-fallback layer**（Python Playwright）。L3-fast 内置浏览器不需要——用 `BrowserImport` 复用登录态即可。 +**L3-fallback 层（Python Playwright）必需**，实际上也仍是复用登录态最稳的一条路。L3-fast 内置浏览器只有在 Host 已授予 `browser.import.*`、`BrowserImport` 真能用的前提下才可以跳过这一步；否则照样要配。 ### One-time setup @@ -121,9 +121,10 @@ User intent │ (Jina Reader = default for JS-rendered content, saves tokens) │ ├─ "Read this login-gated page" (小红书/B站/微博/飞书/Twitter/知乎/公众号) - │ ├─→ 到达：BrowserManage(create_space/start_session) → BrowserImport(按域导入 Cookie) - │ │ → BrowserAct(tab.navigate) → tab.activate + page.screenshot 确认落到正文页 + │ ├─→ 到达：BrowserManage(create_space/start_session) → BrowserAct(tab.navigate) + │ │ → tab.activate + page.screenshot 确认落到正文页 │ │ （semantic 快照不含正文，不能用来读内容） + │ │ 要登录态：仅在已授予 browser.import.* 时用 BrowserImport，否则走下面的 CDP │ └─→ 取正文：确认 CDP 就绪后 python3 playwright.connect_over_cdp() │ → page.content() → Jina Reader / BeautifulSoup │ @@ -278,9 +279,9 @@ See [references/cdp-browser.md](references/cdp-browser.md) for: | `BrowserSnapshot({ mode: 'semantic' })` | 读页面：可交互元素 + `ref` 句柄 | | `BrowserAct({ action: 'input.click', params: { ref } })` | 按快照 `ref` 点击，不要用裸 x/y | | `BrowserAct({ action: 'input.text', params: { text } })` | 向聚焦元素输入文本 | -| `BrowserAct({ action: 'input.wheel', params: { deltaX: 0, deltaY: 720 } })` | 滚动触发懒加载 | +| `BrowserAct({ action: 'input.wheel', params: { x: 640, y: 400, deltaX: 0, deltaY: 720 } })` | 滚动触发懒加载 —— `x`/`y`（或 `ref`）**必填**，且会话要带 `browser.input.pointer.wheel` | | `BrowserAct({ action: 'tab.activate', params: { bounds } })` → `page.screenshot` | **先 activate 再截图** | -| `BrowserImport({ action: 'discover' \| 'plan' \| 'apply' })` | 复用用户登录态 Cookie（需人工审批） | +| `BrowserImport({ action: 'discover' \| 'create_plan' \| 'dry_run' \| 'apply' \| 'rollback' \| 'list_plans' })` | 复用用户登录态 Cookie —— 这 6 个就是**全部**动作，主流程走 `discover → create_plan → dry_run → apply`。**需要 `browser.import.*`，而 `create_space` 不会授予**（见下） | 完整 API 与边界条件见 [references/browser-tools.md](references/browser-tools.md)。 @@ -300,7 +301,10 @@ See [references/cdp-browser.md](references/cdp-browser.md) for: ``` 1. BrowserManage({ action: 'create_space', name: 'xhs-note', persistence: 'ephemeral' }) 2. BrowserManage({ action: 'start_session', spaceId, capabilities: [...] }) -3. BrowserImport({ action: 'discover' }) → plan → apply 授权 xiaohongshu.com ← 复用登录态 + ← 显式列表是做减法；要滚动就必须把 browser.input.pointer.wheel 列进去 +3. 复用登录态：默认走 L3-fallback Playwright 连用户自己的 Chrome。 + BrowserImport({ action: 'discover' → 'create_plan' → 'dry_run' → 'apply' }) 只有在 Host 另行 + 授予 browser.import.* 时才走得通 —— 光靠 create_space 拿不到；被拒就直接回落。 4. BrowserAct({ action: 'tab.navigate', params: { url: 'https://www.xiaohongshu.com/explore/abc123' } }) 5. BrowserSnapshot({ mode: 'semantic' }) ← 只拿交互用的元素 ref（不含正文） tab.activate + page.screenshot ← 确认确实渲染出了笔记 diff --git a/skills/web-access/references/browser-tools.md b/skills/web-access/references/browser-tools.md index 522dc48..5c6dcd0 100644 --- a/skills/web-access/references/browser-tools.md +++ b/skills/web-access/references/browser-tools.md @@ -13,7 +13,7 @@ | 场景 | 推荐 | |------|------| -| 到达并操作登录态站点（小红书 / B站 / 微博 / 飞书 / 知乎） | **内置浏览器**（配合 BrowserImport 导入 Cookie） | +| 到达并操作登录态站点（小红书 / B站 / 微博 / 飞书 / 知乎） | **内置浏览器**（登录态优先走 L3-fallback CDP；仅在已授予 `browser.import.*` 时才用 BrowserImport 导入 Cookie） | | 抽取登录态站点的长正文 | Python Playwright（内置浏览器没有批量取文通道，见下） | | 简单点击 / 滚动 / 截图 | **内置浏览器** | | 多个任务要互不串扰地并行 | **内置浏览器**（一任务一 Space） | @@ -57,9 +57,13 @@ BrowserManage: - browser.navigate.url - browser.navigate.activate-tab - browser.input.pointer.click + - browser.input.pointer.wheel # 要滚动加载就必须带上，漏了 input.wheel 会被策略拒绝 - browser.input.keyboard ``` +**显式传 `capabilities` 就是在做减法**：不传时按 `agentDefault` 全量签发租约，传了就只签这一份 +列表。所以别照抄示例——把你这次真正要用的动作对应的能力都列全。 + `create_space` 会触发一次用户确认。任务收尾用 `close_session` 释放。 ### BrowserSnapshot @@ -122,23 +126,49 @@ BrowserAct: params: { format: png } # 结果落 artifact store，回执给 artifact.id / sha256 / bytes ``` -### BrowserImport（**需人工审批**） +### BrowserImport（**需人工审批 + 额外授权**） -把用户浏览器里的登录态 Cookie 导入当前 Space，替代旧版「attach 用户已登录的 Chrome」。 +把用户浏览器里的登录态 Cookie 导入当前 Space。 + +> **前置条件（先看这里，别直接试）**：`browser.import.discover` / +> `browser.import.cookies.inspect` / `browser.import.cookies` 三个能力**不在 `agentDefault` 里**， +> 而 `BrowserManage(create_space)` 建的 Agent grant 就是按 `agentDefault` 签的。也就是说 +> **仅靠 create_space / start_session 走不通 BrowserImport**，必须由 Host/用户侧另行授予 import +> 能力（`agentElevated` 或 Workbench 路径）。没有这层授权就别在这条路上耗——**直接回落 +> L3-fallback（Python Playwright 连用户已登录的 Chrome）**，那是当前更稳的登录态复用方式。 + +动作枚举只有这 6 个：`discover` | `create_plan` | `dry_run` | `apply` | `rollback` | `list_plans` +（**没有 `plan`**）。完整流程是 `discover → create_plan → dry_run → apply`： ```yaml BrowserImport: - action: discover # discover | plan | apply | ... + action: discover # 列出可导入的来源，返回不透明 sourceProfileId ``` ```yaml BrowserImport: - action: apply - planId: bip_xxx + action: create_plan # 域名授权、来源、冲突策略都在这一步定死 + sourceKind: chromium-profile # chromium-profile | firefox-profile | safari-profile + # | browser-extension | cookie-file + sourceProfileId: domains: [xiaohongshu.com] # 必须逐域显式授权 - conflictStrategy: newer-wins + conflictStrategy: newer-wins # keep-target | replace-target | newer-wins | fail-on-conflict ``` +```yaml +BrowserImport: + action: dry_run # 先看命中多少条，再决定要不要真的写入 + planId: bimp_xxx # create_plan 返回的 ID，前缀是 bimp_ +``` + +```yaml +BrowserImport: + action: apply # 只认 planId；域名/策略在 create_plan 时已固化 + planId: bimp_xxx +``` + +写坏了用 `action: rollback` + 同一个 `planId` 回退；`list_plans` 查当前 Space 的历史 plan。 + 解密与过滤全在 Host 侧完成，**Cookie 值不会进入 Agent 上下文或审计日志**。 ### BrowserShare diff --git a/skills/web-access/references/site-patterns/feishu.cn.md b/skills/web-access/references/site-patterns/feishu.cn.md index d9a7945..129788b 100644 --- a/skills/web-access/references/site-patterns/feishu.cn.md +++ b/skills/web-access/references/site-patterns/feishu.cn.md @@ -19,7 +19,7 @@ updated_at: '2026-08-06' ## 推荐流程 1. 公开文档（companion 页面/官方文档站点 `feishu.cn/hc/...`）→ WebFetch / Jina -2. 用户文档 → 内置浏览器 BrowserImport 导入 Cookie + BrowserAct(tab.navigate) 到达，正文抽取回落 Playwright +2. 用户文档 → 内置浏览器 BrowserAct(tab.navigate) 到达（登录态：已授予 `browser.import.*` 才用 BrowserImport，否则直接回落），正文抽取回落 Playwright 3. 长期程序化访问 → 申请 OpenAPI access_token，走 HTTP，避免 CDP ## 推荐选择器 diff --git a/skills/web-access/references/site-patterns/weibo.com.md b/skills/web-access/references/site-patterns/weibo.com.md index 9f64671..291a955 100644 --- a/skills/web-access/references/site-patterns/weibo.com.md +++ b/skills/web-access/references/site-patterns/weibo.com.md @@ -18,7 +18,7 @@ updated_at: '2026-08-06' ## 推荐流程 1. 单条公开微博 → 优先尝试 `https://m.weibo.cn/status/`，WebFetch 看是否拿到正文 -2. 拿不到 → 内置浏览器 BrowserImport 导入 Cookie + BrowserAct(tab.navigate) + BrowserAct(input.click ref) 点"展开"，正文抽取回落 Playwright +2. 拿不到 → 内置浏览器 BrowserAct(tab.navigate) + BrowserAct(input.click ref) 点"展开"（登录态：已授予 `browser.import.*` 才用 BrowserImport，否则直接回落），正文抽取回落 Playwright 3. 用户主页时间线：必须登录，BrowserAct(input.wheel) 触发懒加载 ## 推荐选择器 diff --git a/skills/web-access/references/site-patterns/xiaohongshu.com.md b/skills/web-access/references/site-patterns/xiaohongshu.com.md index 122542d..9c47a1c 100644 --- a/skills/web-access/references/site-patterns/xiaohongshu.com.md +++ b/skills/web-access/references/site-patterns/xiaohongshu.com.md @@ -18,7 +18,8 @@ updated_at: '2026-08-06' - xsec_token：详情页 URL 包含 `xsec_token=...`，**通过站内交互生成**——直接拼 URL 容易失败 ## 推荐流程 -1. BrowserManage(create_space/start_session) → BrowserImport 按域导入 xiaohongshu.com 的 Cookie +1. BrowserManage(create_space/start_session)；登录态若已授予 `browser.import.*`，用 + BrowserImport(discover → create_plan[domains: xiaohongshu.com] → dry_run → apply)，否则回落 CDP 2. BrowserAct(tab.navigate) 打开笔记；列表页用 BrowserSnapshot(semantic) 收 `.note-card` 链接的 ref 3. 正文抽取回落 L3-fallback Playwright（内置浏览器的 semantic 快照不含正文，accessibility 在本站会超限） 4. 收尾 BrowserManage(close_session)；ephemeral Space 不留 Profile