From bffe21103e2fe644908e66175b2ea080502ed700 Mon Sep 17 00:00:00 2001 From: xyx <124608760@qq.com> Date: Wed, 14 Oct 2026 21:36:50 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20approved=20external=20browser=20startup?= =?UTF-8?q?=20/=20=E5=8F=97=E5=AE=A1=E6=89=B9=E5=90=AF=E5=8A=A8=E5=A4=96?= =?UTF-8?q?=E9=83=A8=E6=B5=8F=E8=A7=88=E5=99=A8=20(#217)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 外部 Chrome 调试端口关闭时，原技能要求用户手动输入命令，无法完成一句话启动并操作的流程。 本更新声明受工具审批的 BrowserExternalLaunch：使用客户端检测到的原生可执行文件与独立 Profile，验真 CDP 后打开网页；成功后高级交互使用预置解释器。Probe 保持只读，拒绝审批不启动，端口冲突和启动失败如实报告。浏览器本身仍需单独安装。旧客户端未提供启动工具时保留只展示的手动备用方式。 主仓实现见 desirecore/desirecore#4811。中英正文、参考材料、版本元数据和翻译摘要同步。校验 0 错误；已有治理警告未改。新公开内容与路径采用通用产品术语，私有测试目录与用户身份不进入提交。 The skill uses an approved native browser-launch tool when advertised by the client, followed by verified CDP and the bundled interpreter for advanced interaction. Older builds retain a display-only manual fallback. Browser installation and site sign-in remain operator prerequisites. Metadata validation and translation freshness checks pass. --- skills/web-access/SKILL.md | 53 +++++++++---------- skills/web-access/SKILL.zh-CN.md | 35 ++++-------- skills/web-access/catalog-metadata.v1.json | 6 +-- skills/web-access/references/browser-tools.md | 2 +- skills/web-access/references/cdp-browser.md | 8 +-- 5 files changed, 46 insertions(+), 58 deletions(-) diff --git a/skills/web-access/SKILL.md b/skills/web-access/SKILL.md index 2669e9a..8d37315 100644 --- a/skills/web-access/SKILL.md +++ b/skills/web-access/SKILL.md @@ -15,8 +15,8 @@ description: >- 新闻、网址、URL、找一下、搜一下、查一下、小红书、B站、微博、飞书、Twitter、 推特、X、知乎、公众号、已登录、登录状态。 license: MIT -version: 3.5.0 -compatibility: Requires a DesireCore build with the bundled external-browser Playwright runtime; Chrome/Edge/Chromium remains separately installed and manually started with CDP. +version: 3.6.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 status: enabled @@ -34,6 +34,7 @@ provides: - BrowserManage - BrowserExternalProbe - BrowserExternalOpen + - BrowserExternalLaunch - BrowserSnapshot - BrowserAct - BrowserScript @@ -54,16 +55,16 @@ metadata: zh-CN: name: 联网访问 short_desc: 联网搜索、网页抓取、内置受管浏览器登录态访问与取文、研究调研工作流 - description: 联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器完成登录态访问与取文，以及用户点名时接管他自己的 Chrome/Edge/Chromium。 + description: 联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器完成登录态访问与取文，以及用户点名时接管他自己的 Chrome/Edge/Chromium。 外部浏览器需单独安装并满足其使用条款；提供启动工具的客户端可经审批启动，旧客户端需手动开启调试。 body: ./SKILL.zh-CN.md - source_hash: sha256:f623f9ef0bebcd16 + source_hash: sha256:a81f7a90824259f0 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. + 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. body: ./SKILL.md - source_hash: sha256:f623f9ef0bebcd16 + source_hash: sha256:a81f7a90824259f0 translated_by: human market: icon: >- @@ -110,12 +111,13 @@ A note of history on L3-external: v3.0 deleted it outright, on the grounds that ### v3.0: governed built-in browser (default-hidden, exposed only after Skill activation) -When you call `Skill('web-access')`, the following tools are injected into the current session. Most `Browser*` tools drive the built-in browser; `BrowserExternalProbe` and `BrowserExternalOpen` are the explicitly named external-browser exceptions: +When you call `Skill('web-access')`, the following tools are injected into the current session. Most `Browser*` tools drive the built-in browser; `BrowserExternalProbe`, `BrowserExternalOpen`, and `BrowserExternalLaunch` are the explicitly named external-browser exceptions: | Tool | Purpose | |------|---------| | BrowserManage | Create/destroy isolated BrowserSpace, start sessions, manage tabs | | BrowserExternalProbe | Read-only check for installed Chrome/Edge/Chromium and loopback CDP readiness; never launches or reads a profile; any returned manual command is display-only | +| BrowserExternalLaunch | Through tool approval, natively start the exact installed browser in an isolated profile, verify CDP and visibly open the requested URL; never download the browser or dependencies | | BrowserExternalOpen | After `BrowserExternalProbe` returns `ready` in the same runtime session, visibly open one HTTP(S) URL in the exact external browser; no shell, Python, or Playwright | | BrowserSnapshot | `semantic` / `text` / `accessibility` / `visual` snapshots — the primary way to read a page | | BrowserAct | One governed action per call: navigate, input, extract text, wait, element ops, screenshot, … | @@ -175,30 +177,26 @@ Handle the structured result exactly: |---|---| | `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** | -| `debug_port_closed` | Show the returned `launchCommand`, end the turn, and wait for the user to launch it and log in manually; never execute it with a tool | +| `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_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 | -Compatibility rule for released 10.0.128 clients: they may include `launchCommand` in statuses other -than `debug_port_closed`. **Never execute `launchCommand` from any status.** Only show it and end the -turn for `debug_port_closed`; for every other status, ignore that field and follow the status row above. +`BrowserExternalProbe` stays read-only. `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. +A rejected approval must not start a process. Port mismatch, missing browser or startup failure must +be reported faithfully; never switch products automatically. Existing ready endpoints may be reused. +After launch, probe again with `prepareAutomationRuntime: true` before advanced interaction and use +its returned prepared interpreter. Keep the user's browser window open after completing the task. -`launchCommand` uses an isolated DesireCore profile. On clients that return the adjacent fields, they are normative: -`requiredAction: wait_for_user_to_launch_browser` means **end the current turn**, and -`commandPolicy: display_only_never_execute` means **never pass the command to Bash, PowerShell, -a terminal, a script, or any other execution tool**. This remains true when the user's earlier wording -said “continue”, “open it for me”, or otherwise sounded like permission to proceed. Only the user may -manually run this suggestion; a future dedicated browser-launch capability would require its own contract. -New clients deliver this display-only notice directly and terminate the turn before the model can call -another tool; do not add a second paraphrase or continue execution after the tool result. - -After the user launches it: - -1. The user logs in manually to the sites they need. -2. That external browser window stays open. -3. Call `BrowserExternalProbe` again. Only `ready` authorizes `BrowserExternalOpen` or an advanced CDP attach attempt. +`launchCommand` remains a display-only manual fallback; never execute it through shell tools. +Older clients reporting `requiredAction: wait_for_user_to_launch_browser` require a manual fallback. +Clients providing `requiredAction: request_approved_browser_launch` allow the governed launch tool; +a closed-port probe does not itself authorize or perform a launch. Site sign-in remains a user action +when required; approval to launch does not grant access to a daily browser profile. Do not replace this probe with `curl`: a refused connection cannot distinguish “browser not installed” from “browser installed but debugging disabled”, and a random HTTP service must not be accepted as CDP. @@ -254,7 +252,8 @@ User intent │ BrowserExternalProbe(exact requested browser), then only on `ready`: │ simple open/navigation → BrowserExternalOpen(exact detected browser + port + URL) │ advanced search/read/click/extract → isolated Playwright connect_over_cdp() - │ Otherwise follow the status guidance and wait; never route to WebSearch/WebFetch/Jina/built-in browser + │ Closed port → approved BrowserExternalLaunch opens the URL, then re-probe for advanced interaction. + │ For other non-ready statuses, follow the guidance and wait; never route to WebSearch/WebFetch/Jina/built-in browser │ ├─ "Local browser" without saying built-in or external │ └─→ Ask which browser identity the user means before selecting any route or tool @@ -337,7 +336,7 @@ When what they asked for and what you're giving differ, the wording has to make | L1 | Public, static | `WebFetch` | Low | | L2 | JS-heavy, long articles, token savings | `Bash curl r.jina.ai` | **Lowest** (Markdown pre-cleaned) | | **L3** | **Login-gated navigation, interaction & extraction (PRIMARY)** | **built-in browser (BrowserManage / BrowserAct / BrowserSnapshot / BrowserScript)** | Medium | -| L3-external | **User named their own browser**, or explicitly accepted this route after you explained why it is needed | Simple open/navigation: `BrowserExternalProbe` → `BrowserExternalOpen`; advanced interaction: ready probe → platform-native shell (`PowerShell` on Windows) + DesireCore isolated venv + Playwright `connect_over_cdp` (see references/cdp-browser.md) | Medium | +| L3-external | **User named their own browser**, or explicitly accepted this route after you explained why it is needed | Simple open/navigation: Probe → Open when ready, or approved BrowserExternalLaunch when closed; advanced interaction: approved launch if closed → ready probe → platform-native shell (`PowerShell` on Windows) + DesireCore isolated venv + Playwright `connect_over_cdp` (see references/cdp-browser.md) | Medium | **Default priority**: L1 for simple public pages → L2 for heavy → **L3 for login-gated (body text and in-site API data included)**. diff --git a/skills/web-access/SKILL.zh-CN.md b/skills/web-access/SKILL.zh-CN.md index bf83c93..c934d1a 100644 --- a/skills/web-access/SKILL.zh-CN.md +++ b/skills/web-access/SKILL.zh-CN.md @@ -22,12 +22,13 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供四层互 ### v3.0：内置受管浏览器（默认隐藏，激活后才暴露） -调用 `Skill('web-access')` 加载本技能时会注入以下工具。大多数 `Browser*` 工具驱动内置浏览器；`BrowserExternalProbe` 与 `BrowserExternalOpen` 是名称明确的外部浏览器例外： +调用 `Skill('web-access')` 加载本技能时会注入以下工具。大多数 `Browser*` 工具驱动内置浏览器；`BrowserExternalProbe`、`BrowserExternalOpen` 与 `BrowserExternalLaunch` 是名称明确的外部浏览器例外： | 工具 | 用途 | |------|------| | BrowserManage | 建/销隔离 BrowserSpace、启动会话、管理标签页 | | BrowserExternalProbe | 只读检查 Chrome/Edge/Chromium 安装与 loopback CDP 就绪状态；绝不启动浏览器或读取 Profile；返回的手工命令只能展示 | +| BrowserExternalLaunch | 经工具审批原生启动用户点名的已安装浏览器与独立 Profile，验证 CDP 后可见打开 URL；不下载浏览器或依赖 | | BrowserExternalOpen | 同一 session 的 probe 返回 `ready` 后，在精确外部浏览器中可见打开一个 HTTP(S) URL；不使用 shell、Python 或 Playwright | | BrowserSnapshot | `semantic` / `text` / `accessibility` / `visual` 四种快照——读页面的主通道 | | BrowserAct | 一次调用一个受管动作：导航、输入、取文、等待、元素操作、截图…… | @@ -56,7 +57,7 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供四层互 - **分层递进**：从轻量搜索到重度 JS 渲染到登录态访问，按需选择；用户点名时还可直接用他自己的浏览器 - **Token 优化**：Jina Reader 默认减少 50-80% Token 消耗；`page.extract-text` 的 maxBytes/cursor 分页让登录态长文也可控 - **登录态复用**：Host 授予 `browser.import.*` 时用 BrowserImport 把 Cookie 导入隔离 Space，不必重新登录 -- **用户无需安装依赖包**：内置浏览器不要求 Python/Playwright；外部路线使用客户端预置运行时，外部 Chromium 浏览器本身仍需单独安装、由用户手动启动调试，且仅在明确用户意图后使用 +- **用户无需安装依赖包**：内置浏览器不要求 Python/Playwright；外部路线使用客户端预置运行时，外部 Chromium 浏览器本身仍需单独安装、支持新启动工具的客户端可经工具审批自动启动调试，且仅在明确用户意图后使用 ## L2：详细规范 @@ -87,32 +88,17 @@ If any fetch fails, explicitly tell the user which URL failed and which fallback |---|---| | `ready` | 简单打开/导航调用 `BrowserExternalOpen`，参数使用返回的精确浏览器 id 与端口；点击、读取、提取等高级交互才继续隔离 Playwright `connect_over_cdp`。如实说出检测到的外部浏览器；`any` 已有 ready 端口时，即使还安装了其他产品，也以该端口作为用户已准备的选择 | | `browser_not_installed` | 明确说未检测到用户点名的浏览器；若有 `alternatives`，询问是否改用其中之一，**绝不自动替换** | -| `debug_port_closed` | 展示返回的 `launchCommand`，结束当前回合，等待用户手工启动并登录；绝不能用工具执行它 | +| `debug_port_closed` | 客户端提供 BrowserExternalLaunch 时，按用户点名的精确浏览器、端口与 URL 经现有审批启动并打开网页，成功后重新 Probe；不要求用户输入命令。旧客户端没有该工具时才提供只展示的手动备用方式 | | `browser_choice_required` | 没有 ready 端口且检测到多个外部浏览器；只列 id/name 并询问用户选哪个，再 probe 精确选择 | | `browser_mismatch` | 说明端口上实际是什么、用户点名的是什么；让用户修正端口或明确同意改用实际浏览器 | | `invalid_cdp_endpoint` | 说明端口虽有服务但不是合法 Chrome DevTools 端点；不得连接 | | `host_unavailable` | 说明当前 Agent Service 无法探测用户桌面宿主；不得猜已安装浏览器，也不得静默改用内置浏览器 | -已发布的 10.0.128 客户端可能在 `debug_port_closed` 以外的状态中也带上 `launchCommand`。 -**任何状态的 `launchCommand` 都绝不能执行。**只有 `debug_port_closed` 可以展示后结束回合； -其他状态必须忽略该字段，严格按上表对应状态处理。 +`BrowserExternalProbe` 保持只读；受审批的副作用由 `BrowserExternalLaunch` 完成。只传用户点名的精确 browser、loopback port 与 HTTP(S) URL；宿主检测原生路径并使用客户端独立 Profile，验证 CDP 后才宣称 opened。拒绝审批时不启动；端口不匹配、未安装或启动失败须如实报告，不自动换浏览器。已 ready 的端点可验真后复用。 -`launchCommand` 使用 DesireCore 专属隔离 Profile；支持相邻字段的客户端必须把它们视为强制契约： -`requiredAction: wait_for_user_to_launch_browser` 表示**必须结束当前回合**， -`commandPolicy: display_only_never_execute` 表示**绝不能把命令传给 Bash、PowerShell、终端、脚本或任何其他执行工具**。 -即使用户此前说过「继续」「帮我打开」或其他看似授权继续的表述，这条规则也不改变。当前只能由用户手工运行该建议； -未来若增加专用浏览器启动能力，必须另行定义并审批其契约。 -新客户端会直接投递这条只展示提示并在模型能调用其他工具前终止本轮；工具返回后不要再追加改写或继续执行。 +启动成功后，高级交互重新 Probe 并设置 `prepareAutomationRuntime: true`，取得预置解释器后填写/点击/提取。完成后保留外部窗口供用户查看。登录仍由用户在该独立 Profile 完成，不访问日常浏览器 Profile。 -用户启动后： - -1. 用户在该外部浏览器里手工登录所需站点。 -2. 外部浏览器窗口保持打开。 -3. 再调用一次 `BrowserExternalProbe`；只有 `ready` 才允许调用 `BrowserExternalOpen` 或尝试高级 CDP attach。 - -不得用 `curl` 替代本探测：连接拒绝无法区分「未安装浏览器」与「已安装但没开调试」，普通 HTTP 服务也不能冒充 CDP。 - -必须按上表的结构化状态提示用户并等待；不要因为内置浏览器也能做就擅自改用内置的。 +`launchCommand` 仍是仅展示的手动备用建议，不得交给 shell 执行。旧客户端返回 `requiredAction: wait_for_user_to_launch_browser` 时走手动备用；新客户端的 `request_approved_browser_launch` 可进入受审批启动工具。Probe 返回端口关闭本身不执行或授予启动。 ⚠️ 用 CDP attach 时**绝不能调 `browser.close()`**，那会关掉用户自己的外部浏览器；只关你开的 page。 完整配方见 [references/cdp-browser.md](references/cdp-browser.md)。 @@ -133,7 +119,7 @@ ready grant 有短时、一次性、精确 browser+port 绑定。宿主会在同 仅在 probe 返回 `ready` 后需要高级交互时，创建或执行 attach 脚本前**必须先确认当前操作系统**： -1. **使用客户端已准备的 `/runtime/external-browser-playwright` 专属 venv**。推荐 Python、Playwright 和依赖从安装包离线准备，用户不需要手动安装；不得另建工作区 venv 或选用系统/全局 Python。Chrome/Edge/Chromium 本身仍需单独安装并由用户手动启动 CDP。 +1. **使用客户端已准备的 `/runtime/external-browser-playwright` 专属 venv**。推荐 Python、Playwright 和依赖从安装包离线准备，用户不需要手动安装；不得另建工作区 venv 或选用系统/全局 Python。Chrome/Edge/Chromium 本身仍需单独安装；支持 BrowserExternalLaunch 的客户端可经工具审批原生启动 CDP。 2. import 与 attach 只调用这个 venv 的解释器并加 `-B`；不得执行 pip 安装、切换索引/代理或 `playwright install`。运行时缺失属于客户端准备失败：报告原始错误，不要求用户安装依赖；依赖状态与浏览器 ready 状态分别报告。 3. Unix-like 主机使用 Bash 路径和语法；Windows 的整个流程必须使用 `PowerShell` 工具和 venv 的 `Scripts\python.exe`，不得调用 `Bash` 工具。以 PowerShell here-string 和 `[IO.File]::WriteAllText(...)` 创建临时 `.py`。**绝不能把 `cat < **范围**：本文只描述 DesireCore **内置**受管浏览器，所以 v10.0.98+ 是本层基础能力的最低版本， -> 不是整个 web-access v3.5.0 的兼容门槛。外部 Chrome/Edge/Chromium 高级操作需要带预置 +> 不是整个 web-access v3.6.0 的兼容门槛。外部 Chrome/Edge/Chromium 高级操作需要带预置 > external-browser 运行时的客户端；简单打开走 `BrowserExternalProbe → BrowserExternalOpen`，高级 CDP/Playwright > 交互见 [cdp-browser.md](cdp-browser.md)。不要把本文的 BrowserManage/Act 路线用于冒充外部浏览器。 > diff --git a/skills/web-access/references/cdp-browser.md b/skills/web-access/references/cdp-browser.md index 7a9b6d9..b5faafa 100644 --- a/skills/web-access/references/cdp-browser.md +++ b/skills/web-access/references/cdp-browser.md @@ -2,7 +2,7 @@ Detailed recipes for accessing sites through the user-approved external Chromium browser, via Chrome DevTools Protocol (CDP) + Python Playwright. -**Scope**: this manual is only for advanced external-browser interaction such as clicking, reading dynamic content, extraction, or form work. A simple open/navigation must use `BrowserExternalProbe` → `BrowserExternalOpen` and must not invoke shell, Python, pip, or Playwright. +**Scope**: this manual is only for advanced external-browser interaction such as clicking, reading dynamic content, extraction, or form work. For simple open/navigation, probe first: a ready endpoint uses `BrowserExternalOpen`; a closed endpoint on a capable client uses approved `BrowserExternalLaunch`, which already opens the URL. Do not call Open again for that same URL after a successful launch. Neither route invokes shell, Python, pip, or Playwright. **Precondition for advanced interaction**: `BrowserExternalProbe` has returned `ready` for the exact browser the user requested, that browser is running with its DesireCore-isolated profile, and the user has manually logged in to the target sites. Never infer readiness from a failed/successful `curl`; see the main SKILL.md status table. @@ -308,7 +308,7 @@ print(clean_md) Do not guess that the browser is merely closed. Call `BrowserExternalProbe` again: -- `debug_port_closed` → show its current `launchCommand`, end the turn, and wait for the user; +- `debug_port_closed` → on a client advertising BrowserExternalLaunch, request that approved native launch with the exact browser, port and URL, then re-probe; on older clients only, show the manual fallback and wait; `commandPolicy: display_only_never_execute` forbids passing it to Bash, PowerShell, a terminal, a script, or any other execution tool even when the user previously said “continue” - `browser_mismatch` → report the actual/requested products and ask the user to correct or approve the change @@ -328,7 +328,7 @@ The approved external Chromium browser is running but no windows are open. Ask t DesireCore prepares `/runtime/external-browser-playwright` from the installation package using its bundled Python and complete local wheel profile. No user package installation, network index, or browser download is needed. Chrome/Edge/Chromium remains separately installed, -subject to its own terms, and manually started with CDP. Run the import-only check with the prepared +subject to its own terms, and started with CDP through approved BrowserExternalLaunch when available (manual fallback on older builds). Run the import-only check with the prepared interpreter. Missing files or import errors are client preparation failures: report the original error and do not install packages, create another venv, or attach until the runtime is available. @@ -421,3 +421,5 @@ ask before changing the execution route. CDP is specifically the "right tool" for: **small number of pages + login required + human-like behavior needed**. Before advanced interaction, probe with `prepareAutomationRuntime: true`; require `automationRuntime.status: ready` and use its returned `pythonExecutable`. Ordinary external URL opening does not require this runtime. + +For a closed debugging port on a client advertising BrowserExternalLaunch, use that governed tool with the exact browser, port and requested URL through approval. Do not execute the display-only launchCommand through PowerShell/Bash. After launch, obtain browser and automation runtime readiness from Probe before attaching. The browser product remains separately installed; the tool does not download it.