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.
This commit is contained in:
2026-10-14 19:54:48 +08:00
committed by GitHub
parent 13c72eba29
commit e567c2d767
5 changed files with 46 additions and 45 deletions

View File

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

View File

@@ -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**.
Do not generate or execute the attach script until this succeeds.
DesireCore prepares `<DESIRECORE_HOME>/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
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" || \
python3 -m venv "<DESIRECORE_HOME>/runtime/external-browser-playwright"
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
"<DESIRECORE_HOME>/runtime/external-browser-playwright/bin/python" -B -c 'import playwright.sync_api, bs4' || {
echo 'The bundled external-browser runtime is unavailable' >&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
`-m venv` when the isolated venv is missing. Never use the `Bash` tool, bare `python`, bare `pip`,
`pip --user`, or a global interpreter for any Playwright import, install, re-check, or attach step;
all of those steps must use the venv's `Scripts\python.exe`.
guess another instance's directory. 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`
with `-B`. Keep stdout UTF-8 when returning text, or use JSON ASCII escapes to avoid code-page confusion.
```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
& $bootstrapPython -m venv $venv
if ($LASTEXITCODE -ne 0) { throw 'Failed to create the isolated Playwright venv.' }
throw 'The client-prepared external-browser runtime is missing.'
}
& $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.
& $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.' }
throw 'The bundled external-browser runtime failed its import check.'
}
# 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.