fix: use bundled Playwright runtime for offline Chrome operations (#215)

外部 Chrome 高级操作原先要求 Agent 在线 pip 安装 Playwright，内网部署缺少依赖时无法填写或点击。

技能改为使用客户端准备的 `runtime/external-browser-playwright`，删除在线安装与另建工作区 venv
的规程；缺少预置运行时时报告客户端准备错误。Chrome 本身仍由用户安装、手动开启 CDP。中英正文、参考手册、版本和翻译摘要同步更新。

对应主仓修复预置推荐 Python 的六平台 wheel profile，并在启动时离线建立 venv。Windows 干净目录实测：首次
installed、重复 already-valid，Chrome 本地表单提交成功，pip/npm 配置哈希不变。

Validation: focused skill/catalog validation reports 0 errors;
translation freshness check passed. Existing repository governance
warnings remain unchanged.

External Chrome automation previously attempted online pip installation.
The skill now consumes the client-prepared isolated runtime, preserving
browser consent and CDP readiness checks. Python and Playwright are
prepared by the accompanying client fix; no package-index fallback is
instructed.

skills/web-access/SKILL.md

@@ -15,7 +15,8 @@ description: >-
   新闻、网址、URL、找一下、搜一下、查一下、小红书、B站、微博、飞书、Twitter、
   推特、X、知乎、公众号、已登录、登录状态。
 license: MIT
-version: 3.4.5
+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.
 type: procedural
 risk_level: low
 status: enabled
@@ -43,7 +44,7 @@ provides:
     - LocalBookmarks
 metadata:
   author: desirecore
-  updated_at: '2026-10-03'
+  updated_at: '2026-10-14'
   i18n:
     default_locale: en-US
     source_locale: zh-CN
@@ -55,14 +56,14 @@ metadata:
       short_desc: 联网搜索、网页抓取、内置受管浏览器登录态访问与取文、研究调研工作流
       description: 联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器完成登录态访问与取文，以及用户点名时接管他自己的 Chrome/Edge/Chromium。
       body: ./SKILL.zh-CN.md
-      source_hash: sha256:5a2d3f06ce8eca10
+      source_hash: sha256:f623f9ef0bebcd16
       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.
       body: ./SKILL.md
-      source_hash: sha256:5a2d3f06ce8eca10
+      source_hash: sha256:f623f9ef0bebcd16
       translated_by: human
 market:
   icon: >-
@@ -80,7 +81,7 @@ market:
     fill-opacity="0.12"/><path d="M20.5 20.5l2 2" stroke="#34C759"
     stroke-width="1.8" stroke-linecap="round"/></svg>
   category: research
-  required_client_version: 10.0.128
+  required_client_version: 10.0.181
   maintainer:
     name: DesireCore Official
     verified: true
@@ -128,7 +129,7 @@ When you call `Skill('web-access')`, the following tools are injected into the c
 
 > **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).
 >
-> **Removed in v2.1**: `BrowserListTabs` / `BrowserNavigate` / `BrowserEval` / `BrowserClick` / `BrowserScreenshot` / `BrowserScroll` / `BrowserSetFiles` / `BrowserCloseTab` and the cdp-proxy behind them are retired. Calling them now returns "该旧 BrowserXxx/cdp-proxy 入口已停用". This skill version requires client v10.0.128+; `page.extract-text` / `page.element` / `page.wait` / inline wait blocks / cross-origin iframe snapshots were introduced in v10.0.112+, and `BrowserScript` needs a build containing S17/S18.
+> **Removed in v2.1**: `BrowserListTabs` / `BrowserNavigate` / `BrowserEval` / `BrowserClick` / `BrowserScreenshot` / `BrowserScroll` / `BrowserSetFiles` / `BrowserCloseTab` and the cdp-proxy behind them are retired. Calling them now returns "该旧 BrowserXxx/cdp-proxy 入口已停用". This skill version requires client v10.0.181+ with the bundled external-browser runtime; `page.extract-text` / `page.element` / `page.wait` / inline wait blocks / cross-origin iframe snapshots were introduced in v10.0.112+, and `BrowserScript` needs a build containing S17/S18.
 
 ### Use Cases
 
@@ -143,7 +144,7 @@ When you call `Skill('web-access')`, the following tools are injected into the c
 - **Layered progression**: from lightweight search to heavy JS rendering to logged-in access — pick on demand; plus the user's own browser whenever they name it
 - **Token optimization**: Jina Reader cuts token usage by 50–80% by default; `page.extract-text`'s maxBytes/cursor paging keeps even long logged-in articles under control
 - **Logged-in session reuse**: where the Host has granted `browser.import.*`, BrowserImport brings the user's Cookies into an isolated Space — no re-login required
-- **Zero external dependencies by default**: the built-in browser needs no Python/Playwright install and no manually launched external Chromium browser (L3-external does, and only after explicit user intent)
+- **Zero user package installation**: the built-in browser needs no Python/Playwright; the external route uses the client-bundled runtime and a separately installed, user-started Chromium browser, only after explicit user intent
 
 ## L2: Detailed Specification
 
@@ -221,10 +222,14 @@ invalid, or mismatched endpoint, call the probe again and follow its status guid
 
 Only for advanced interaction after a `ready` probe, identify the current OS **before** creating or running an attach script:
 
-1. **Create or select the DesireCore-owned isolated venv first.** Do not probe a global interpreter
+1. **For advanced interaction, call `BrowserExternalProbe` with `prepareAutomationRuntime: true` and require both browser `status: ready` and `automationRuntime.status: ready`. Use the returned `automationRuntime.pythonExecutable`.** Simple opening/navigation uses the default probe and does not wait for Python.
-   for Playwright. A system/bootstrap Python may only run `-m venv` when the venv does not exist.
+
-2. From that point onward, use only the venv interpreter for import, pinned install, re-import, and
+   **Use the application-prepared venv at `<DESIRECORE_HOME>/runtime/external-browser-playwright`.**
-   attach. Never use bare `python`, bare `pip`, `pip --user`, a global install, or `playwright install`.
+   DesireCore prepares its Python, Playwright and dependencies from the installation package, including offline.
+   Do not create a workspace venv or select system/global Python.
+2. Use only this venv interpreter with `-B` for import and attach. Do not run pip installation,
+   change package indexes/proxies, or run `playwright install`. Missing runtime files indicate a client
+   preparation failure: report the exact error rather than asking the user to install dependencies.
    A missing dependency is separate from browser readiness: report it explicitly and do not attach yet.
 3. On Unix-like hosts, use Bash paths and shell syntax. On Windows, every command in this flow must use
    the `PowerShell` tool and the venv's `Scripts\python.exe`; do not call the `Bash` tool. Use a
@@ -234,7 +239,7 @@ Only for advanced interaction after a `ready` probe, identify the current OS **b
    `Scripts\python.exe` on Windows), remove only the temporary script you created, and leave the
    external browser running.
 
-If the platform cannot be determined or no isolated runtime can be created safely, stop and report
+If the platform cannot be determined or the prepared runtime is unavailable, stop and report
 the missing prerequisite. Do not improvise a cross-shell command and do not fall back to BrowserManage.
 
 ---

skills/web-access/SKILL.zh-CN.md

@@ -41,7 +41,7 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供四层互
 
 > **重要**：未调用 Skill('web-access') 之前，这些工具**不会**出现在 LLM 的 tools 列表里——默认对话不消耗其 token。详见 [references/browser-tools.md](references/browser-tools.md)。
 >
-> **v2.1 已移除**：`BrowserListTabs` / `BrowserNavigate` / `BrowserEval` / `BrowserClick` / `BrowserScreenshot` / `BrowserScroll` / `BrowserSetFiles` / `BrowserCloseTab` 及其背后的 cdp-proxy 已停用，调用会返回「该旧 BrowserXxx/cdp-proxy 入口已停用」。本技能版本要求客户端 v10.0.128+；`page.extract-text` / `page.element` / `page.wait` / 内联 wait 块 / 跨源 iframe 快照自 v10.0.112 起可用，`BrowserScript` 需包含 S17/S18 的更新版本。
+> **v2.1 已移除**：`BrowserListTabs` / `BrowserNavigate` / `BrowserEval` / `BrowserClick` / `BrowserScreenshot` / `BrowserScroll` / `BrowserSetFiles` / `BrowserCloseTab` 及其背后的 cdp-proxy 已停用，调用会返回「该旧 BrowserXxx/cdp-proxy 入口已停用」。本技能版本要求带预置外部浏览器运行时的客户端 v10.0.181+；`page.extract-text` / `page.element` / `page.wait` / 内联 wait 块 / 跨源 iframe 快照自 v10.0.112 起可用，`BrowserScript` 需包含 S17/S18 的更新版本。
 
 ### 使用场景
 
@@ -56,7 +56,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 浏览器（L3-external 需要，且仅在明确用户意图后才用）
+- **用户无需安装依赖包**：内置浏览器不要求 Python/Playwright；外部路线使用客户端预置运行时，外部 Chromium 浏览器本身仍需单独安装、由用户手动启动调试，且仅在明确用户意图后使用
 
 ## L2：详细规范
 
@@ -133,13 +133,13 @@ ready grant 有短时、一次性、精确 browser+port 绑定。宿主会在同
 
 仅在 probe 返回 `ready` 后需要高级交互时，创建或执行 attach 脚本前**必须先确认当前操作系统**：
 
-1. **必须先创建或选择 DesireCore 拥有的隔离 venv**，不得先用全局解释器探测 Playwright。venv 不存在时，系统/引导 Python 只能用于执行 `-m venv`。
+1. **使用客户端已准备的 `<DESIRECORE_HOME>/runtime/external-browser-playwright` 专属 venv**。推荐 Python、Playwright 和依赖从安装包离线准备，用户不需要手动安装；不得另建工作区 venv 或选用系统/全局 Python。Chrome/Edge/Chromium 本身仍需单独安装并由用户手动启动 CDP。
-2. 此后 import、固定版本安装、重新 import 与 attach 全部只能调用 venv 解释器；严禁裸 `python`、裸 `pip`、`pip --user`、全局安装或 `playwright install`。依赖缺失与浏览器 ready 是两件事：明确报告缺失，暂不 attach。
+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 <<EOF`、`/tmp/...` 或其他 POSIX heredoc 交给 PowerShell。**
 4. 调用 venv 对应平台的 Python（Unix 为 `bin/python`，Windows 为 `Scripts\python.exe`），只删除本轮创建的临时脚本，外部浏览器保持运行。
 
-无法判断平台或无法安全创建隔离运行时时，停止并报告缺失前置；不得即兴混用 shell，也不得回落 BrowserManage。
+无法判断平台或客户端预置运行时不可用时，停止并报告缺失前置；不得即兴混用 shell，也不得回落 BrowserManage。
 
 ---
 
@@ -494,3 +494,5 @@ Read [references/browser-tools.md](references/browser-tools.md) for the full bui
 6. 告知用户：「已通过内置浏览器抓取，原链接：[xhs](url)」
 7. BrowserManage(close_session)
 ```
+
+高级外部浏览器交互前，调用 `BrowserExternalProbe` 并设置 `prepareAutomationRuntime: true`，要求浏览器 `status: ready` 与 `automationRuntime.status: ready` 同时成立，使用返回的 `automationRuntime.pythonExecutable`。简单打开或导航使用默认探测，不等待 Python；运行时不可用时如实报告客户端准备错误。

skills/web-access/catalog-metadata.v1.json

@@ -32,13 +32,13 @@
   },
   "release": {
     "state": "known",
-    "version": "3.4.5",
+    "version": "3.5.0",
     "versionScheme": "semver"
   },
   "timestamps": {
     "catalogUpdatedAt": {
       "state": "known",
-      "value": "2026-10-03",
+      "value": "2026-10-14",
       "precision": "day"
     },
     "releasePublishedAt": {
@@ -69,7 +69,7 @@
     "platforms": {
       "state": "unknown"
     },
-    "requiredClientVersion": "10.0.128"
+    "requiredClientVersion": "10.0.181"
   },
   "spec": {
     "kind": "skill",

skills/web-access/references/browser-tools.md

@@ -1,8 +1,8 @@
 # 内置受管浏览器工具速查（L3）
 
 > **范围**：本文只描述 DesireCore **内置**受管浏览器，所以 v10.0.98+ 是本层基础能力的最低版本，
-> 不是整个 web-access v3.4.5 的兼容门槛。用户点名自己的外部 Chrome/Edge/Chromium 时需要
+> 不是整个 web-access v3.5.0 的兼容门槛。外部 Chrome/Edge/Chromium 高级操作需要带预置
-> 客户端 v10.0.128+；简单打开走 `BrowserExternalProbe → BrowserExternalOpen`，高级 CDP/Playwright
+> external-browser 运行时的客户端；简单打开走 `BrowserExternalProbe → BrowserExternalOpen`，高级 CDP/Playwright
 > 交互见 [cdp-browser.md](cdp-browser.md)。不要把本文的 BrowserManage/Act 路线用于冒充外部浏览器。
 >
 > v2.1 起本层从「cdp-proxy 驱动用户自己的 Chrome」改为「DesireCore 内置受管浏览器」；v3.0 补全能力面（批量取文 / 元素操作 / 等待 / 代码模式）并移除 Python Playwright 回落。

skills/web-access/references/cdp-browser.md

@@ -325,19 +325,18 @@ The approved external Chromium browser is running but no windows are open. Ask t
 
 ### Playwright not installed
 
-First ensure the isolated venv exists, then run the import-only check with **that venv's interpreter**.
+DesireCore prepares `<DESIRECORE_HOME>/runtime/external-browser-playwright` from the installation
-Do not generate or execute the attach script until this succeeds.
+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
+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.
 
 #### Unix-like hosts
 
 ```bash
-test -x "<DESIRECORE_HOME>/runtime/external-browser-playwright/bin/python" || \
+"<DESIRECORE_HOME>/runtime/external-browser-playwright/bin/python" -B -c 'import playwright.sync_api, bs4' || {
-  python3 -m venv "<DESIRECORE_HOME>/runtime/external-browser-playwright"
+  echo 'The bundled external-browser runtime is unavailable' >&2
-if ! "<DESIRECORE_HOME>/runtime/external-browser-playwright/bin/python" -c 'import playwright'; then
-  "<DESIRECORE_HOME>/runtime/external-browser-playwright/bin/python" -m pip install 'playwright==1.55.0' beautifulsoup4
-fi
-"<DESIRECORE_HOME>/runtime/external-browser-playwright/bin/python" -c 'import playwright' || {
-  echo 'Playwright is still unavailable in the isolated venv' >&2
   exit 1
 }
 # No need for `playwright install` — we're attaching to an existing browser, not downloading one
@@ -346,26 +345,19 @@ fi
 #### Windows hosts
 
 Use the `PowerShell` tool. Resolve `<DESIRECORE_HOME>` from the current DesireCore instance; do not
-guess another instance's directory. The only permitted system/bootstrap `python.exe` use is running
+guess another instance's directory. Never use the `Bash` tool, bare `python`, bare `pip`,
-`-m venv` when the isolated venv is missing. Never use the `Bash` tool, bare `python`, bare `pip`,
+`pip --user`, or a global interpreter. Import and attach use the prepared venv's `Scripts\python.exe`
-`pip --user`, or a global interpreter for any Playwright import, install, re-check, or attach step;
+with `-B`. Keep stdout UTF-8 when returning text, or use JSON ASCII escapes to avoid code-page confusion.
-all of those steps must use the venv's `Scripts\python.exe`.
 
 ```powershell
 $venv = Join-Path '<DESIRECORE_HOME>' 'runtime\external-browser-playwright'
 $python = Join-Path $venv 'Scripts\python.exe'
 if (-not (Test-Path -LiteralPath $python)) {
-    $bootstrapPython = (Get-Command python.exe -ErrorAction Stop).Source
+    throw 'The client-prepared external-browser runtime is missing.'
-    & $bootstrapPython -m venv $venv
-    if ($LASTEXITCODE -ne 0) { throw 'Failed to create the isolated Playwright venv.' }
 }
-& $python -c "import playwright"
+& $python -B -c "import playwright.sync_api, bs4"
 if ($LASTEXITCODE -ne 0) {
-    # Explain the missing dependency and obtain any required install approval first.
+    throw 'The bundled external-browser runtime failed its import check.'
-    & $python -m pip install 'playwright==1.55.0' beautifulsoup4
-    if ($LASTEXITCODE -ne 0) { throw 'Failed to install Playwright in the isolated venv.' }
-    & $python -c "import playwright"
-    if ($LASTEXITCODE -ne 0) { throw 'Playwright is still unavailable in the isolated venv.' }
 }
 # Do NOT run `playwright install`; CDP attach uses the already-running external browser.
 ```
@@ -380,7 +372,7 @@ $script = @'
 '@
 try {
     [IO.File]::WriteAllText($scriptPath, $script, (New-Object Text.UTF8Encoding($false)))
-    & $python $scriptPath
+    & $python -B $scriptPath
     if ($LASTEXITCODE -ne 0) { throw "Playwright attach failed with exit code $LASTEXITCODE." }
 } finally {
     Remove-Item -LiteralPath $scriptPath -ErrorAction SilentlyContinue
@@ -427,3 +419,5 @@ ask before changing the execution route.
 - **You need thousands of pages** → CDP is not built for scale; look into proper scrapers
 
 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.