fix(web-access): 开发者工具类动作指向 BrowserDevtools，兼容拆分前的客户端（3.4.5） (#206)

desirecore/desirecore#3899 把 BrowserAct 的 21 个开发者工具类动作拆到独立工具 BrowserDevtools，它不随本技能注入。技能在工具表后说明：需要时先 DiscoverTools(query="select:BrowserDevtools") 加载，参数与 BrowserAct 相同；查不到说明客户端早于拆分，同样的 action 与参数在 BrowserAct 上调用。写法不依赖客户端版本，所以不设 required_client_version，也不把 BrowserDevtools 加进 provides.tools。 references/browser-tools.md 新增 BrowserDevtools 一节，cdp.raw 的已知边界、错误处理与调用链路同步更新。技能版本 3.4.5，sidecar 的 release.version 与 catalogUpdatedAt 同步，i18n source_hash 重算。 English: Point web-access's developer-tool actions at BrowserDevtools, the tool split out of BrowserAct in desirecore/desirecore#3899. The skill loads it on demand through DiscoverTools and falls back to the same action on BrowserAct for clients that predate the split, so no client version floor is needed. Bump to 3.4.5 with synced sidecar metadata and a recomputed i18n source hash. 验证 / Validation: i18n validation and catalog metadata checks report zero errors (existing repository warnings remain); translation freshness check passes.
2026-10-21 04:04:25 +08:00 · 2026-10-03 23:27:59 -07:00
parent 9bd9f6dfdb
commit a7411ab07c
4 changed files with 36 additions and 10 deletions
--- 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.4.4
+version: 3.4.5
 type: procedural
 risk_level: low
 status: enabled
@@ -43,7 +43,7 @@ provides:
    - LocalBookmarks
 metadata:
  author: desirecore
-  updated_at: '2026-08-29'
+  updated_at: '2026-10-03'
  i18n:
    default_locale: en-US
    source_locale: zh-CN
@@ -55,14 +55,14 @@ metadata:
      short_desc: 联网搜索、网页抓取、内置受管浏览器登录态访问与取文、研究调研工作流
      description: 联网访问工具包——搜索公开页面、Jina 优化抓取、内置受管浏览器完成登录态访问与取文，以及用户点名时接管他自己的 Chrome/Edge/Chromium。
      body: ./SKILL.zh-CN.md
-      source_hash: sha256:c8c7be6cf577d445
+      source_hash: sha256:5a2d3f06ce8eca10
      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:c8c7be6cf577d445
+      source_hash: sha256:5a2d3f06ce8eca10
      translated_by: human
 market:
  icon: >-
@@ -124,6 +124,8 @@ When you call `Skill('web-access')`, the following tools are injected into the c
 | SitePatternRead / SitePatternWrite | Per-domain "site experience" (AgentFS three-layer) |
 | LocalBookmarks | Search local Chrome bookmarks / history |

+> **Developer-tool actions are not in the table above**: network observe / intercept / modify and network profiles, cookies and site storage, console reads, performance metrics, coverage, cache, service workers, extensions, tracing, opening DevTools and raw CDP (`cdp.raw`) belong to a separate `BrowserDevtools` tool on newer clients, and this skill does not inject it. When you need one, first call `DiscoverTools(query="select:BrowserDevtools")` to load it; its parameters match BrowserAct (`action` + `sessionId` / `tabId` + `params`). If it is not found, the client predates the split: call the same action with the same parameters on `BrowserAct`.
+
 > **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.
--- a/skills/web-access/SKILL.zh-CN.md
+++ b/skills/web-access/SKILL.zh-CN.md
@@ -37,6 +37,8 @@ web-access 是一个**流程型技能（Procedural Skill）**，提供四层互
 | SitePatternRead / SitePatternWrite | 按域名累积"站点经验"（AgentFS 三层） |
 | LocalBookmarks | 检索本地 Chrome 书签 / 历史 |

+> **开发者工具类动作不在上表**：网络观察 / 拦截 / 改写与网络配置、Cookie 与站点存储、Console 读取、性能指标、覆盖率、缓存、Service Worker、扩展、Tracing、打开 DevTools 与原始 CDP（`cdp.raw`），在较新的客户端里由独立的 `BrowserDevtools` 承担，它不随本技能注入。需要时先调用 `DiscoverTools(query="select:BrowserDevtools")` 加载，参数与 BrowserAct 相同（`action` + `sessionId` / `tabId` + `params`）；查不到说明客户端早于拆分，同样的 action 与参数直接在 `BrowserAct` 上调用。
+
 > **重要**：未调用 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 的更新版本。
--- a/skills/web-access/catalog-metadata.v1.json
+++ b/skills/web-access/catalog-metadata.v1.json
@@ -32,14 +32,14 @@
  },
  "release": {
    "state": "known",
-    "version": "3.4.4",
+    "version": "3.4.5",
    "versionScheme": "semver"
  },
  "timestamps": {
    "catalogUpdatedAt": {
      "state": "known",
-      "value": "2026-08-30T03:00:58Z",
-      "precision": "second"
+      "value": "2026-10-03",
+      "precision": "day"
    },
    "releasePublishedAt": {
      "state": "unknown"
--- a/skills/web-access/references/browser-tools.md
+++ b/skills/web-access/references/browser-tools.md
@@ -1,7 +1,7 @@
 # 内置受管浏览器工具速查（L3）

 > **范围**：本文只描述 DesireCore **内置**受管浏览器，所以 v10.0.98+ 是本层基础能力的最低版本，
-> 不是整个 web-access v3.4.3 的兼容门槛。用户点名自己的外部 Chrome/Edge/Chromium 时需要
+> 不是整个 web-access v3.4.5 的兼容门槛。用户点名自己的外部 Chrome/Edge/Chromium 时需要
 > 客户端 v10.0.128+；简单打开走 `BrowserExternalProbe → BrowserExternalOpen`，高级 CDP/Playwright
 > 交互见 [cdp-browser.md](cdp-browser.md)。不要把本文的 BrowserManage/Act 路线用于冒充外部浏览器。
 >
@@ -210,6 +210,27 @@ scope（viewport/full_page/ref）+ ref + snapshotId、format（markdown/text）
 `captureBeyondViewport`、`clip={x,y,width,height,scale}`。结果落 artifact store，回执给
 artifact.id / sha256 / bytes；截图像素直接进结果（见「截图」节）。

+### BrowserDevtools（开发者工具类动作，按需加载）
+
+调试与检查网页本身的动作在较新的客户端里从 BrowserAct 拆到了这个工具：`cdp.raw`、
+`network.observe` / `network.intercept` / `network.modify` / `network.profile.apply`、
+`storage.cookies.metadata` / `storage.cookies.write` / `storage.clear`、`devtools.open`、`console.read`、
+`performance.metrics`、`coverage.start` / `coverage.stop`、`cache.clear`、
+`service-worker.list` / `service-worker.stop-all`、`extension.install` / `extension.list` / `extension.remove`、
+`tracing.start` / `tracing.stop`。
+
+```yaml
+BrowserDevtools:
+  action: console.read
+  params: {}
+```
+
+- 它不隐藏，但也不随 web-access 注入：需要时先 `DiscoverTools(query="select:BrowserDevtools")` 加载。参数形状与
+  BrowserAct 相同（`action` + `sessionId` / `tabId` + 随 action 变化的 `params`），能力、来源、审批与宿主隔离检查也完全一致
+- 查不到这个工具说明客户端早于拆分：同样的 action 与参数直接在 BrowserAct 上调用
+- 会改变会话网络、存储或扩展状态的动作（如 `storage.clear`、`network.modify`、`extension.install`）按受管能力走审批，
+  `cdp.raw` 永远人工审批（见「已知边界」）；只读的 `console.read`、`performance.metrics`、`service-worker.list` 对观察者开放
+
 ### BrowserScript（代码模式，S17+S18）

 一段异步 JS 在 Worker 里跑，通过注入的 `page` / `tab` / `input` / `snapshot` / `console` /
@@ -333,7 +354,7 @@ Agent 会话（actor ≠ user）的标签页**常驻离屏原位，保住合成
 | 边界 | 说明 |
 |------|------|
 | **`page.evaluate` 走人工闸门** | 能力 `browser.page.evaluate` 属 always-human-gate：非 allow-all 模式每次弹审批卡。返回值已原样过界（超预算截断标 `truncated`），登录态取接口走 fetch.browser 配方 |
-| **`cdp.raw` 需人工审批** | `browser.raw_cdp.*` 属于永远人工闸门的能力，无人值守流程用不了。元素级裁剪 / 整页截图用 `clip` / `captureBeyondViewport`，别走它 |
+| **`cdp.raw` 需人工审批** | 在 `BrowserDevtools` 上调用（客户端早于拆分时在 BrowserAct 上）。`browser.raw_cdp.*` 属于永远人工闸门的能力，无人值守流程用不了。元素级裁剪 / 整页截图用 `clip` / `captureBeyondViewport`，别走它 |
 | **`page.element` 没有 click** | 指针动作必须走 `input.*`（拟真轨迹、可审计）；JS 直调 `el.click()` 是明确禁止的回退 |
 | **`fill` 拒绝密码框** | `input[type=password]` 一律拒绝——密码输入只走 `input.text`（拟真键入） |
 | **单条命令 30 s deadline** | 超时只掐掉**这一条命令**（stop 加载），标签页仍可用，重试即可；不再打掉宿主。等待类命令超时连 stop 都跳过 |
@@ -363,6 +384,7 @@ SitePatternWrite:
 | 错误 | 原因 | 解决 |
 |------|------|------|
 | `该旧 BrowserXxx/cdp-proxy 入口已停用` | 还在调 v2.0 的旧工具 | 改用 BrowserManage / BrowserSnapshot / BrowserAct |
+| `action="…" 已从 BrowserAct 拆到 BrowserDevtools` | 在 BrowserAct 上调了开发者工具类动作 | 先 `DiscoverTools(query="select:BrowserDevtools")` 加载，再用同样的 action 与参数调用 BrowserDevtools |
 | `BROWSER_TAB_HOST_NOT_FOUND` | 标签页宿主真的没了（渲染进程崩溃/销毁） | 重建 Session。命令超时**不再**引发此错误——超时只 stop 这一条命令，标签页保留 |
 | `BROWSER_COMMAND_DEADLINE_EXCEEDED` | 单条命令超 30 s | 标签页仍停在上一页/空白页，直接重试；慢加载常态不算故障 |
 | `BROWSER_VIEWPORT_UNAVAILABLE` | embedded 多标签会话的后台 tab 没有可用视口 | 先 `tab.activate` 再截图（秒级快判，不是挂死） |
@@ -374,7 +396,7 @@ SitePatternWrite:
 ## 调用链路

 ```
-Agent → BrowserManage/Snapshot/Act/Script → browser-use service（Capability/Grant/Lease/Policy 校验）
+Agent → BrowserManage/Snapshot/Act/Devtools/Script → browser-use service（Capability/Grant/Lease/Policy 校验）
      → BrowserHost（electron-embedded 或 standalone-managed）→ Chromium
                                    ↑ 每步产出带 digest 的回执，写入审计事件流
 ```