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

@@ -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`。
2. 此后 import、固定版本安装、重新 import 与 attach 全部只能调用 venv 解释器;严禁裸 `python`、裸 `pip`、`pip --user`、全局安装或 `playwright install`。依赖缺失与浏览器 ready 是两件事:明确报告缺失,暂不 attach。
1. **使用客户端已准备的 `<DESIRECORE_HOME>/runtime/external-browser-playwright` 专属 venv**。推荐 Python、Playwright 和依赖从安装包离线准备,用户不需要手动安装;不得另建工作区 venv 或选用系统/全局 Python。Chrome/Edge/Chromium 本身仍需单独安装并由用户手动启动 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 <<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;运行时不可用时如实报告客户端准备错误。