diff --git a/skills/web-access/SKILL.md b/skills/web-access/SKILL.md index 8d37315..e0140d1 100644 --- a/skills/web-access/SKILL.md +++ b/skills/web-access/SKILL.md @@ -15,7 +15,7 @@ description: >- 新闻、网址、URL、找一下、搜一下、查一下、小红书、B站、微博、飞书、Twitter、 推特、X、知乎、公众号、已登录、登录状态。 license: MIT -version: 3.6.0 +version: 3.7.0 compatibility: Requires a DesireCore build with the bundled external-browser Playwright runtime; Chrome/Edge/Chromium remains separately installed. Builds advertising BrowserExternalLaunch can start it through tool approval in an isolated profile; older builds require manual CDP startup. type: procedural risk_level: low @@ -45,7 +45,7 @@ provides: - LocalBookmarks metadata: author: desirecore - updated_at: '2026-10-14' + updated_at: '2026-10-22' i18n: default_locale: en-US source_locale: zh-CN @@ -55,16 +55,16 @@ metadata: zh-CN: name: 联网访问 short_desc: 联网搜索、网页抓取、内置受管浏览器登录态访问与取文、研究调研工作流 - description: 联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器完成登录态访问与取文,以及用户点名时接管他自己的 Chrome/Edge/Chromium。 外部浏览器需单独安装并满足其使用条款;提供启动工具的客户端可经审批启动,旧客户端需手动开启调试。 + description: 联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器完成登录态访问与取文,以及用户点名时接管他自己的 Chrome/Edge/Chromium。 外部浏览器需单独安装并满足其使用条款;提供启动工具的客户端可经审批启动,旧客户端需手动开启调试。 支持新客户端按显式路径审批启动系统浏览器;原生启动与 CDP 自动化就绪分别核验,依赖从随包资产离线准备。 body: ./SKILL.zh-CN.md - source_hash: sha256:a81f7a90824259f0 + source_hash: sha256:5a3b56b621b6edc3 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 web-access toolkit — search public pages, fetch heavy pages via Jina Reader, reach and read logged-in sites through the governed built-in browser, and drive the user's named Chrome/Edge/Chromium over CDP on request. The external browser is separately installed and subject to its usage terms; clients with the launch tool support approved startup, while older clients require manual debugging startup. + description: A web-access toolkit — search public pages, fetch heavy pages via Jina Reader, reach and read logged-in sites through the governed built-in browser, and drive the user's named Chrome/Edge/Chromium over CDP on request. The external browser is separately installed and subject to its usage terms; clients with the launch tool support approved startup, while older clients require manual debugging startup. New clients support approved native launch by explicit executable path; native startup and CDP automation readiness are verified separately, with automation dependencies prepared from bundled offline assets. body: ./SKILL.md - source_hash: sha256:a81f7a90824259f0 + source_hash: sha256:5a3b56b621b6edc3 translated_by: human market: icon: >- @@ -160,9 +160,17 @@ If any fetch fails, explicitly tell the user which URL failed and which fallback ## Prerequisites: external browser + CDP (L3-external only) -**Only needed when taking the L3-external route.** The built-in browser has no prerequisites. +### System-installed browsers and offline readiness -### Always probe before attaching +Only clients whose declared Launch schema includes system and executablePath accept `BrowserExternalLaunch(browser="system", executablePath=, url=...)` for any locally installed browser. Use OS registration facts from `BrowserExternalProbe(requestedBrowser="any")` or an authorized executable path; never infer absence from the Chrome/Edge fixed-directory list alone. Approval must identify the actual executable. Operators must separately install the browser and comply with its licence and usage terms. + +`system` returns `launched` with `automation="native"`: this proves process creation only, not navigation or automation readiness. Choose an available approved desktop-control method and verify the real window; do not pass this receipt to BrowserAct/BrowserScript or claim task completion. For compatible custom Chromium installations, clients accepting `executablePath` can launch the selected executable with its matching CDP family and isolated profile. Inspect the receipt and fresh Probe before interaction. Never silently replace a named product. + +For advanced CDP interaction, use Probe's returned `automationRuntime.pythonExecutable`. The client prepares its interpreter and wheels from fixed bundled assets independently of Hatch/Volta and system Python. If unavailable, report the structured deployment error. Do not try system Python, online pip/npm installation or an invented internal session. Missing packaged assets require installation repair; opening a login page is not evidence that automation is ready. + +**The remainder of this prerequisite section applies only to the CDP route.** Native system launch follows the section above and does not require a ready CDP endpoint or a Python runtime. The built-in browser has no external prerequisites. + +### CDP only: always probe before attaching Map the user's words to an exact probe request: @@ -176,14 +184,14 @@ Handle the structured result exactly: | status | Required response | |---|---| | `ready` | For a simple open/navigation, call `BrowserExternalOpen` with the returned exact browser id and port. For advanced click/read/extract interaction, continue with isolated Playwright `connect_over_cdp`. Name the detected external browser honestly. For `any`, the already-ready endpoint is the prepared choice even if other products are installed | -| `browser_not_installed` | Say the requested browser was not detected. If `alternatives` is non-empty, ask whether the user wants one of them; **never switch automatically** | +| `browser_not_installed` | Say the requested browser was not detected; this does not prove absence. Use authorized read-only OS registration/shortcut inspection for nonstandard installations. If its executable is found, use the supported explicit-path launch mode. Ask before substituting another product unless the user already authorized that choice | | `debug_port_closed` | On a client advertising `BrowserExternalLaunch`, call it with the exact chosen browser, port and URL through the existing approval flow; probe again after success. Do not ask the user to type a command. On older clients without this tool, offer the manual display-only fallback | -| `browser_choice_required` | No endpoint is ready and multiple external browsers are installed. List id/name only and ask which one the user wants; probe that exact choice next | +| `browser_choice_required` | Multiple installations need a selection. If the user delegated the choice, select a listed installation; otherwise ask. CDP selections use an exact probe; system selections use the returned executable path for approved native launch | | `browser_mismatch` | Say which browser is actually on the port and which one was requested; ask the user to correct the port or explicitly approve the other browser | | `invalid_cdp_endpoint` | Explain that something is listening on the port but it is not a valid Chrome DevTools endpoint; do not attach | | `host_unavailable` | Explain that this Agent Service cannot inspect the user's desktop host; do not assume a browser is installed or silently use the built-in browser | -`BrowserExternalProbe` stays read-only. `BrowserExternalLaunch` is the approved effectful entry: +For CDP mode, `BrowserExternalProbe` stays read-only and `BrowserExternalLaunch` is the approved effectful entry: use the user's exact browser id, the selected loopback port and requested HTTP(S) URL. It launches only the detected native executable with a client-owned isolated profile, waits for verified CDP, and returns `opened` with `started`, process id and profile when a new process was started. @@ -204,9 +212,9 @@ from “browser installed but debugging disabled”, and a random HTTP service m ⚠️ When attached over CDP, **never call `browser.close()`** — that would close the user's own external browser. Only close the page you opened. Full recipes in [references/cdp-browser.md](references/cdp-browser.md). -### Simple external open/navigation: use the dedicated tool +### CDP only: simple external open/navigation -When the user's requested action is only to open or navigate to an HTTP(S) URL in their named external browser: +For the CDP route, when the requested action is only to open or navigate to an HTTP(S) URL: 1. Call `BrowserExternalProbe` and require `ready`. 2. In the same runtime session, call `BrowserExternalOpen` with `browser: detectedBrowser.id`, the exact probe `port`, and the URL. @@ -246,6 +254,9 @@ the missing prerequisite. Do not improvise a cross-shell command and do not fall ``` User intent + │ + ├─ Other installed browser / explicit executable path + │ └─→ Inspect installation facts if needed; advertised system Launch → native desktop control and real-window verification. No CDP-ready grant or Python prerequisite │ ├─ **Any request that names "my own / my machine's / external Chrome/Edge/Chromium"** │ └─→ L3-external first, whether the verb is search/read/open/click: diff --git a/skills/web-access/SKILL.zh-CN.md b/skills/web-access/SKILL.zh-CN.md index c934d1a..b6f4284 100644 --- a/skills/web-access/SKILL.zh-CN.md +++ b/skills/web-access/SKILL.zh-CN.md @@ -71,9 +71,20 @@ If any fetch fails, explicitly tell the user which URL failed and which fallback ## Prerequisites:外部浏览器 + CDP(仅 L3-external 需要) +### 系统已安装浏览器与离线就绪 + +仅在客户端声明的 Launch Schema 包含 system 和 executablePath 时,支持 `BrowserExternalLaunch(browser="system", executablePath=<获授权的浏览器绝对可执行路径>, url=...)`,按路径启动任何本机已安装浏览器。通过 `BrowserExternalProbe(requestedBrowser="any")` 读取系统登记,或使用获授权的明确路径;仅在 Chrome/Edge 固定目录未发现文件不能证明未安装。审批必须显示实际可执行文件。部署方仍须另行安装浏览器并遵守其许可与使用条款。 + +`system` 返回 `launched` 和 `automation="native"` 只证明创建进程,不证明页面加载或自动化就绪。Agent 应选择可用且获授权的桌面控制方式并核对真实窗口;不得把该回执交给 BrowserAct/BrowserScript,也不得据此声称任务完成。兼容的自定义 Chromium 安装可以在支持 executablePath 的客户端中,按匹配的 CDP 协议族与独立 Profile 启动指定可执行文件,核对回执并重新 Probe 后再交互。不得静默替换用户点名的产品。 + +高级 CDP 操作只能使用 Probe 返回的 `automationRuntime.pythonExecutable`。客户端从随包固定资产准备解释器与 wheel,不依赖 Hatch/Volta 或系统 Python。不可用时如实报告结构化部署错误;不要尝试系统 Python、联网 pip/npm 安装或杜撰内置会话。包内资产缺失须修复安装;成功打开登录页不证明自动化已就绪。 + **只有走 L3-external 时才需要。** 内置浏览器零前置条件。 -### 每次连接前必须先结构化探测 + +本前置节以下规则仅适用于 CDP 路线。system 原生启动按上节执行,不要求 CDP ready 或 Python。 + +### CDP 模式:每次连接前必须先结构化探测 按用户原话映射精确请求: @@ -87,14 +98,14 @@ If any fetch fails, explicitly tell the user which URL failed and which fallback | status | 必须采取的动作 | |---|---| | `ready` | 简单打开/导航调用 `BrowserExternalOpen`,参数使用返回的精确浏览器 id 与端口;点击、读取、提取等高级交互才继续隔离 Playwright `connect_over_cdp`。如实说出检测到的外部浏览器;`any` 已有 ready 端口时,即使还安装了其他产品,也以该端口作为用户已准备的选择 | -| `browser_not_installed` | 明确说未检测到用户点名的浏览器;若有 `alternatives`,询问是否改用其中之一,**绝不自动替换** | +| `browser_not_installed` | 明确说未检测到,不等于证明未安装;可用已授权只读工具检查系统登记和桌面快捷方式等非标准安装。找到路径后按客户端支持的显式路径模式启动;替换产品须用户授权,已授权自由选择时无需重复询问 | | `debug_port_closed` | 客户端提供 BrowserExternalLaunch 时,按用户点名的精确浏览器、端口与 URL 经现有审批启动并打开网页,成功后重新 Probe;不要求用户输入命令。旧客户端没有该工具时才提供只展示的手动备用方式 | -| `browser_choice_required` | 没有 ready 端口且检测到多个外部浏览器;只列 id/name 并询问用户选哪个,再 probe 精确选择 | +| `browser_choice_required` | 多个安装需要选择。用户已委派选择时自主选取已列安装,否则询问;CDP 选择再精确探测,system 选择按返回路径审批原生启动 | | `browser_mismatch` | 说明端口上实际是什么、用户点名的是什么;让用户修正端口或明确同意改用实际浏览器 | | `invalid_cdp_endpoint` | 说明端口虽有服务但不是合法 Chrome DevTools 端点;不得连接 | | `host_unavailable` | 说明当前 Agent Service 无法探测用户桌面宿主;不得猜已安装浏览器,也不得静默改用内置浏览器 | -`BrowserExternalProbe` 保持只读;受审批的副作用由 `BrowserExternalLaunch` 完成。只传用户点名的精确 browser、loopback port 与 HTTP(S) URL;宿主检测原生路径并使用客户端独立 Profile,验证 CDP 后才宣称 opened。拒绝审批时不启动;端口不匹配、未安装或启动失败须如实报告,不自动换浏览器。已 ready 的端点可验真后复用。 +CDP 模式下,`BrowserExternalProbe` 保持只读;受审批的副作用由 `BrowserExternalLaunch` 完成。只传用户点名的精确 browser、loopback port 与 HTTP(S) URL;宿主检测原生路径并使用客户端独立 Profile,验证 CDP 后才宣称 opened。拒绝审批时不启动;端口不匹配、未安装或启动失败须如实报告,不自动换浏览器。已 ready 的端点可验真后复用。 启动成功后,高级交互重新 Probe 并设置 `prepareAutomationRuntime: true`,取得预置解释器后填写/点击/提取。完成后保留外部窗口供用户查看。登录仍由用户在该独立 Profile 完成,不访问日常浏览器 Profile。 @@ -103,9 +114,9 @@ If any fetch fails, explicitly tell the user which URL failed and which fallback ⚠️ 用 CDP attach 时**绝不能调 `browser.close()`**,那会关掉用户自己的外部浏览器;只关你开的 page。 完整配方见 [references/cdp-browser.md](references/cdp-browser.md)。 -### 简单外部打开/导航:使用专用工具 +### 仅 CDP 模式:简单外部打开/导航 -当用户只要求在点名的外部浏览器中打开或导航到一个 HTTP(S) URL: +在 CDP 路线中,当用户只要求打开或导航到一个 HTTP(S) URL: 1. 调用 `BrowserExternalProbe`,且必须得到 `ready`。 2. 在同一 runtime session 调用 `BrowserExternalOpen`,传入 `browser: detectedBrowser.id`、probe 的精确 `port` 与 URL。 @@ -131,6 +142,8 @@ ready grant 有短时、一次性、精确 browser+port 绑定。宿主会在同 ## Tool Selection Decision Tree +其它已安装品牌或明确可执行路径:按需读取安装事实 → 客户端声明支持的 system Launch → 原生桌面控制与真实窗口验证;不以 CDP ready 或 Python 作为前置。下方 Chrome/Edge/Chromium 分支为 CDP 模式。 + ``` User intent │ diff --git a/skills/web-access/catalog-metadata.v1.json b/skills/web-access/catalog-metadata.v1.json index 8fa760e..421be1c 100644 --- a/skills/web-access/catalog-metadata.v1.json +++ b/skills/web-access/catalog-metadata.v1.json @@ -11,12 +11,12 @@ "zh-CN": { "name": "联网访问", "summary": "联网搜索、网页抓取、内置受管浏览器登录态访问与取文、研究调研工作流", - "description": "联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器完成登录态访问与取文,以及用户点名时接管他自己的 Chrome/Edge/Chromium。 外部浏览器需单独安装并满足其使用条款;提供启动工具的客户端可经审批启动,旧客户端需手动开启调试。" + "description": "联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器完成登录态访问与取文,以及用户点名时接管他自己的 Chrome/Edge/Chromium。 外部浏览器需单独安装并满足其使用条款;提供启动工具的客户端可经审批启动,旧客户端需手动开启调试。 支持新客户端按显式路径审批启动系统浏览器;原生启动与 CDP 自动化就绪分别核验,依赖从随包资产离线准备。" }, "en-US": { "name": "Web Access", "summary": "Web search, page fetching, logged-in access via the governed built-in browser, research workflows", - "description": "A web-access toolkit — search public pages, fetch heavy pages via Jina Reader, reach and read logged-in sites through the governed built-in browser, and drive the user's named Chrome/Edge/Chromium over CDP on request. The external browser is separately installed and subject to its usage terms; clients with the launch tool support approved startup, while older clients require manual debugging startup." + "description": "A web-access toolkit — search public pages, fetch heavy pages via Jina Reader, reach and read logged-in sites through the governed built-in browser, and drive the user's named Chrome/Edge/Chromium over CDP on request. The external browser is separately installed and subject to its usage terms; clients with the launch tool support approved startup, while older clients require manual debugging startup. New clients support approved native launch by explicit executable path; native startup and CDP automation readiness are verified separately, with automation dependencies prepared from bundled offline assets." } }, "category": "research", @@ -32,7 +32,7 @@ }, "release": { "state": "known", - "version": "3.6.0", + "version": "3.7.0", "versionScheme": "semver" }, "timestamps": {