fix(browser)!: 升级 chromedp v0.9.5→v0.20.1，修视口截图必挂 (#1)

用户报告截图不对（此前已改为落盘返回路径）。查下去发现**两个叠加的问题**，
其中一个是既有的、与上次改动无关的严重缺陷。

## ① 协议解析失败：chromedp v0.9.5 不认 Chrome 154

```
ERROR: could not unmarshal event: parse error: expected string near offset 411 of 'cookiePart...'
```

cdproto 把 `partitionKey` 定义为 `string`，而 Chrome 154 已改成对象
（`cookiePartitionKey`）。新版 cdproto 定义了 `CookiePartitionKey` 结构体，
且 `UnmarshalJSON` **双向兼容**（字符串 → 结构体，旧浏览器也不坏）。

副作用：`Navigate` 从 2.5s 降到 85ms（解析错误消失，不再反复重试）。

## ② 视口截图在 headless 下**永远挂住**（既有缺陷，不是升级引入）

`Screenshot(sel)` 内部是 `QueryAfter` + `NodeVisible`，而 NodeVisible 在
headless Chromium 上永远不满足 —— 两步单独看都成功，但它一直等下去：

```
Do(Query body)          ✓        Do(WaitReady body)      ✓
Do(WaitVisible body)    ✗挂住     Do(WaitVisible html)    ✗挂住
Run(Screenshot html)    ✗挂住     Run(FullScreenshot)     ✓
Run(CaptureScreenshot)  ✓（70KB）
```

**决定性对照：旧版 chromedp v0.9.5 在同一个后端上同样挂。**
所以这不是升级引入的。生产日志也佐证：

- 成功的 8 次 —— agent 都传了 `full:true`（走 FullScreenshot）
- 超时的 5 次 —— 都是默认分支（走 Screenshot("body")）

且 `NodeVisible` 的两步实测都正常（`dom.GetBoxModel` 300µs 成功、
`visibleJS` 返回 true / offsetWidth=480），就是等待机制本身不返回。
没有深挖到 chromedp 内部的根因，但**换用 `CaptureScreenshot` 完全绕开这条链**，
且语义更对：「不传 full 就只截当前视口」本来就是 API 文档的含义。

## 迁移方式：兼容层收敛，业务代码最小改动

v0.20 是**泛型重写**（`Action[T]` 返回值而不填指针），25 处调用点受影响。
新增 `chromedp_compat.go` 把新 API 收敛成几个小助手
（`chromedpDo` / `newRemoteAllocator` / `chromedpCaptureScreenshot` …），
业务代码保持旧写法。

为何不逐处改：20+ 处机械改写会把 diff 淹没，真正要审的
「行为变了没有」反而看不清。

`NewRemoteAllocator` 在 v0.20 移到了独立子模块 `remote`（核心模块现在
只用标准库 + cdproto，需要 websocket 的东西全部搬出去）。

## 顺带修掉 go.mod 的重复 replace

`go mod tidy` 清掉了 4 条重复的 `replace ... => ../../`（hmapdev 往已有
go.mod 追加却不去重导致的）。Go 容忍它，但 `go mod tidy` 会报错。

## 判据（可杀变异，实测）

`chromedp_compat_test.go`：
- 视口截图必须走 `CaptureScreenshot`，不得退回 `Screenshot(sel)`
  （改回挂住的写法 → FAIL ×2）
- 兼容层关键助手都在（去掉 CaptureScreenshot → build FAIL）
- 无旧式「传指针接收截图」残留

全部 20 个 example `go vet` 通过；SDK 根 module build/test 通过。
生产实测：agent 做视口截图返回
`/home/newqqagent/browser_screenshots/shot-20261011-104225.610-browser_1.png`
（1280×713 PNG / 70518 字节），不再超时。

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>

example/browser/chromedp_compat.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+	"context"
+
+	"github.com/chromedp/chromedp"
+	"github.com/chromedp/chromedp/remote"
+)
+
+// chromedp v0.20 是**泛型重写**（Action[T] 返回值而不填指针），
+// 本文件把旧写法收敛成几个小助手，让业务代码的改动面最小。
+//
+// 为何不直接在每个调用点改：插件里有 20+ 处 `chromedp.Run(ctx, 步骤...)`，
+// 逐处改成「Run 取一个值 / Do 跑多步」会让 diff 淹没在机械改写里，
+// 真正要审的「行为变了没有」反而看不清。收敛到助手后，业务代码保持原样。
+
+// chromedpDo 依次跑多个不返回值的步骤（旧 Run(ctx, steps...) 的等价物）。
+//
+// 对应 v0.20 的 chromedp.Do。放在这里是为了让调用点看起来与旧代码一致。
+func chromedpDo(ctx context.Context, steps ...chromedp.Action[chromedp.Void]) error {
+	return chromedp.Do(ctx, steps...)
+}
+
+// newRemoteAllocator 连接一个已在运行的 CDP 端点（如共享浏览器后端）。
+//
+// v0.20 把它移到了独立子模块：chromedp.NewRemoteAllocator → remote.NewAllocator。
+// 子模块存在的理由：核心模块现在只用标准库 + cdproto，需要 websocket 的东西
+// 全部搬出去（见 chromedp docs/decisions/2026-10-04-...）。
+func newRemoteAllocator(parent context.Context, url string) (context.Context, context.CancelFunc) {
+	return remote.NewAllocator(parent, url)
+}
+
+// chromedpTitle 取当前页标题。
+func chromedpTitle(sel ...chromedp.QueryOption) chromedp.Action[string] {
+	return chromedp.Title()
+}
+
+// chromedpLocation 取当前页 URL。
+func chromedpLocation() chromedp.Action[string] {
+	return chromedp.Location()
+}
+
+// chromedpOuterHTML 取元素的外部 HTML（旧写法传 &html 接收，现在直接返回）。
+func chromedpOuterHTML(sel string, opts ...chromedp.QueryOption) chromedp.Action[string] {
+	return chromedp.OuterHTML(sel, opts...)
+}
+
+// chromedpScreenshot 截图（旧写法传 &buf 接收，现在直接返回）。
+func chromedpScreenshot(sel string, opts ...chromedp.QueryOption) chromedp.Action[[]byte] {
+	return chromedp.Screenshot(sel, opts...)
+}
+
+// chromedpFullScreenshot 整页截图。
+func chromedpFullScreenshot(quality int) chromedp.Action[[]byte] {
+	return chromedp.FullScreenshot(quality)
+}
+
+// chromedpCaptureScreenshot 截当前**视口**。
+//
+// ★ 为何不用 chromedp.Screenshot("body")（2026-10-11）：后者内部是
+// QueryAfter + NodeVisible，而 NodeVisible 在本机的 headless Chromium 上
+// 永远不会满足 —— 实测会一直挂到调用方超时（生产表现为 60s 工具超时）。
+// 详见 plugin.go 里 handleScreenshot 的注释（含完整对照表）。
+func chromedpCaptureScreenshot() chromedp.Action[[]byte] {
+	return chromedp.CaptureScreenshot()
+}
+
+// chromedpEvaluate 执行 JS（返回 Void 表示不关心返回值）。
+func chromedpEvaluateVoid(expr string) chromedp.Action[chromedp.Void] {
+	return chromedp.Evaluate[chromedp.Void](expr, nil)
+}

example/browser/chromedp_compat_test.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+// 视口截图**必须**走 CaptureScreenshot，不能用 Screenshot(sel)。
+//
+// # 为什么这条判据存在（2026-10-11 实测）
+//
+// chromedp 的 Screenshot(sel) 内部是 QueryAfter + **NodeVisible**，
+// 而 NodeVisible 在本机的 headless Chromium 上**永远不会满足** —— 它先
+// 用 dom.GetBoxModel 拿盒子（实测 300µs 就成功），再用 visibleJS 判定
+// （实测返回 true，offsetWidth=480），两步都对，但它仍一直等下去。
+//
+// 同一后端上的完整对照（实测）：
+//
+//	Do(Query body)        ✓        Do(WaitReady body)     ✓
+//	Do(WaitVisible body)  ✗挂住     Do(WaitVisible html)   ✗挂住
+//	Run(Screenshot html)  ✗挂住     Run(FullScreenshot)    ✓
+//	Run(CaptureScreenshot) ✓
+//
+// 且**旧版 chromedp v0.9.5 同样挂** —— 这不是升级引入的，是既有缺陷。
+// 生产日志佐证：成功的都是 agent 传了 full:true（走 FullScreenshot），
+// 超时的都是默认分支（走 Screenshot("body")）。
+//
+// 所以这条判据守的是：不许把 CaptureScreenshot 改回 Screenshot(sel)。
+func TestViewportScreenshotUsesCaptureScreenshot(t *testing.T) {
+	src, err := os.ReadFile("plugin.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(src)
+
+	i := strings.Index(s, "func (p *Plugin) handleScreenshot(")
+	if i < 0 {
+		t.Fatal("找不到 handleScreenshot")
+	}
+	seg := s[i:]
+	if j := strings.Index(seg, "\nfunc (p *Plugin) saveScreenshot("); j > 0 {
+		seg = seg[:j]
+	}
+
+	// ① 视口分支必须用 CaptureScreenshot
+	if !strings.Contains(seg, "chromedpCaptureScreenshot()") {
+		t.Error("视口截图必须走 chromedpCaptureScreenshot()（=CaptureScreenshot）：\n" +
+			"  用 Screenshot(\"body\") 会因 NodeVisible 在 headless 下永不满足而挂到超时")
+	}
+
+	// ② 不得再出现挂住的那种写法
+	if strings.Contains(seg, `chromedpScreenshot(`) {
+		t.Error("handleScreenshot 里出现了 chromedpScreenshot(sel) —— " +
+			"该动作在 headless 下必挂（实测），改用 chromedpCaptureScreenshot()")
+	}
+
+	// ③ full 分支仍走 FullScreenshot（那条一直是好的）
+	if !strings.Contains(seg, "chromedpFullScreenshot(") {
+		t.Error("full=true 应走 chromedpFullScreenshot（FullScreenshot 实测正常）")
+	}
+}
+
+// TestCompatLayerExists 确认兼容层还在（迁移收敛点）。
+//
+// 这一层是为了让 20+ 处调用点的迁移不淹没 diff。若有人删掉它而没把
+// 调用点改对，编译会红；但若有人把它改成直接透传错误 API，就只会
+// 在运行时挂住 —— 所以这里钉住关键几个。
+func TestCompatLayerExists(t *testing.T) {
+	src, err := os.ReadFile("chromedp_compat.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(src)
+	for _, need := range []string{
+		"func chromedpDo(",
+		"func newRemoteAllocator(",
+		"func chromedpCaptureScreenshot(",
+		"func chromedpFullScreenshot(",
+		"func chromedpTitle(",
+	} {
+		if !strings.Contains(s, need) {
+			t.Errorf("chromedp 兼容层缺少 %s", need)
+		}
+	}
+	// 必须用 remote 子模块的分配器（v0.20 把它移出去了）
+	if !strings.Contains(s, "remote.NewAllocator") {
+		t.Error("newRemoteAllocator 必须用 remote.NewAllocator（v0.20 移出核心模块）")
+	}
+}
+
+// TestNoLegacyPointerScreenshot 确认没有残留的旧式「传指针接收」写法。
+//
+// v0.20 的截图动作是**返回值**，传 &buf 会直接编译失败 —— 但这条判据
+// 仍值得留着：它锁的是「值语义」这个契约，而不是某次编译结果。
+func TestNoLegacyPointerScreenshot(t *testing.T) {
+	for _, f := range []string{"plugin.go", "chromedp_compat.go"} {
+		b, err := os.ReadFile(f)
+		if err != nil {
+			t.Fatal(err)
+		}
+		s := string(b)
+		if strings.Contains(s, "Screenshot(&") || strings.Contains(s, "FullScreenshot(&") {
+			t.Errorf("%s 仍用旧式传指针接收截图（v0.20 已改为返回值）", f)
+		}
+	}
+}

example/browser/go.mod

@@ -4,23 +4,20 @@ go 1.25.0
 
 require (
 	github.com/JianFeeeee/homeagentsdk v0.0.0
-	github.com/chromedp/chromedp v0.9.5
-	github.com/chromedp/cdproto v0.0.0-20240202021202-6d0b6a386732
+	github.com/chromedp/cdproto v0.157.8
+	github.com/chromedp/chromedp v0.20.1
+	github.com/chromedp/chromedp/remote v0.2.0
 	github.com/chromedp/sysutil v1.0.0
 	github.com/gobwas/httphead v0.1.0
 	github.com/gobwas/pool v0.2.1
-	github.com/gobwas/ws v1.3.2
+	github.com/gobwas/ws v1.4.0
 	github.com/josharian/intern v1.0.0
 	github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80
 	github.com/mailru/easyjson v0.7.7
 	github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde
-	golang.org/x/sys v0.16.0
+	golang.org/x/sys v0.47.0
 )
 
-replace github.com/JianFeeeee/homeagentsdk => ../../
-
-replace github.com/JianFeeeee/homeagentsdk => ../../
-
-replace github.com/JianFeeeee/homeagentsdk => ../../
+require github.com/go-json-experiment/json v0.0.0-20260213210345-44df1a37e875 // indirect
 
 replace github.com/JianFeeeee/homeagentsdk => ../../

example/browser/go.sum

@@ -1,15 +1,25 @@
 github.com/chromedp/cdproto v0.0.0-20240202021202-6d0b6a386732 h1:XYUCaZrW8ckGWlCRJKCSoh/iFwlpX316a8yY9IFEzv8=
 github.com/chromedp/cdproto v0.0.0-20240202021202-6d0b6a386732/go.mod h1:GKljq0VrfU4D5yc+2qA6OVr8pmO/MBbPEWqWQ/oqGEs=
+github.com/chromedp/cdproto v0.157.8 h1:Tkq0AjsUlC3Z4sJfHBzV/uAAxnTF/AZyuSTjfV/1gvk=
+github.com/chromedp/cdproto v0.157.8/go.mod h1:h68JaIuFr9o3yiayxEYhBdvaxgYO3shDrPSYhNlyfu0=
 github.com/chromedp/chromedp v0.9.5 h1:viASzruPJOiThk7c5bueOUY91jGLJVximoEMGoH93rg=
 github.com/chromedp/chromedp v0.9.5/go.mod h1:D4I2qONslauw/C7INoCir1BJkSwBYMyZgx8X276z3+Y=
+github.com/chromedp/chromedp v0.20.1 h1:983T9wmyM09JtROWlxhLQwljKOQovqt8CVE89W3U0NA=
+github.com/chromedp/chromedp v0.20.1/go.mod h1:6z1Y5FdKUxRzxx2qcC5h1xjaBJrSWrZp1mjgITfNZig=
+github.com/chromedp/chromedp/remote v0.2.0 h1:Jo5OuOEXMuH3IAOiY5RhXO5JvOpfKMFCZ+cPv6qIksM=
+github.com/chromedp/chromedp/remote v0.2.0/go.mod h1:XW8uWIvN8Z4EUxHzYCb6p0lmeTYheYRrEEQpv5FHOH8=
 github.com/chromedp/sysutil v1.0.0 h1:+ZxhTpfpZlmchB58ih/LBHX52ky7w2VhQVKQMucy3Ic=
 github.com/chromedp/sysutil v1.0.0/go.mod h1:kgWmDdq8fTzXYcKIBqIYvRRTnYb9aNS9moAV0xufSww=
+github.com/go-json-experiment/json v0.0.0-20260213210345-44df1a37e875 h1:XGPtjxqp0FS8jj1Z7QGcSOSgyq1fUPjNyJXvi3KfI4A=
+github.com/go-json-experiment/json v0.0.0-20260213210345-44df1a37e875/go.mod h1:uNVvRXArCGbZ508SxYYTC5v1JWoz2voff5pm25jU1Ok=
 github.com/gobwas/httphead v0.1.0 h1:exrUm0f4YX0L7EBwZHuCF4GDp8aJfVeBrlLQrs6NqWU=
 github.com/gobwas/httphead v0.1.0/go.mod h1:O/RXo79gxV8G+RqlR/otEwx4Q36zl9rqC5u12GKvMCM=
 github.com/gobwas/pool v0.2.1 h1:xfeeEhW7pwmX8nuLVlqbzVc7udMDrwetjEv+TZIz1og=
 github.com/gobwas/pool v0.2.1/go.mod h1:q8bcK0KcYlCgd9e7WYLm9LpyS+YeLd8JVDW6WezmKEw=
 github.com/gobwas/ws v1.3.2 h1:zlnbNHxumkRvfPWgfXu8RBwyNR1x8wh9cf5PTOCqs9Q=
 github.com/gobwas/ws v1.3.2/go.mod h1:hRKAFb8wOxFROYNsT1bqfWnhX+b5MFeJM9r2ZSwg/KY=
+github.com/gobwas/ws v1.4.0 h1:CTaoG1tojrh4ucGPcoJFiAQUAsEWekEWvLy7GsVNqGs=
+github.com/gobwas/ws v1.4.0/go.mod h1:G3gNqMNtPppf5XUz7O4shetPpcZ1VJ7zt18dlUeakrc=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80 h1:6Yzfa6GP0rIo/kULo2bwGEkFvCePZ3qHDDTC3/J9Swo=
@@ -21,3 +31,5 @@ github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde/go.mod h1:nZgzb
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.16.0 h1:xWw16ngr6ZMtmxDyKyIgsE93KNKz5HKmMa3b8ALHidU=
 golang.org/x/sys v0.16.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=

example/browser/plugin.go

@@ -841,25 +841,30 @@ func (p *Plugin) handleRender(args map[string]interface{}) (interface{}, error)
 
 	ok, needInstall, _ := p.ensureBackend()
 	if ok {
-		remoteCtx, remoteCancel := chromedp.NewRemoteAllocator(context.Background(), cdpEndpoint)
+		remoteCtx, remoteCancel := newRemoteAllocator(context.Background(), cdpEndpoint)
 		defer remoteCancel()
 		tabCtx, tabCancel := chromedp.NewContext(remoteCtx)
 		defer tabCancel()
-		actions := []chromedp.Action{
+		steps := []chromedp.Action[chromedp.Void]{
 			chromedp.Navigate(rawURL),
 			chromedp.WaitReady("body"),
 		}
 		if waitSec > 0 {
-			actions = append(actions, chromedp.Sleep(time.Duration(waitSec)*time.Second))
+			steps = append(steps, chromedp.Sleep(time.Duration(waitSec)*time.Second))
 		}
-		actions = append(actions,
-			chromedp.Title(&title),
-			chromedp.OuterHTML("html", &html),
-		)
 		// 整体限时 30s，防慢页拖死工具
 		rctx, rcancel := context.WithTimeout(tabCtx, 30*time.Second)
 		defer rcancel()
-		if err := chromedp.Run(rctx, actions...); err == nil {
+		// 标题与 HTML 现在是**返回值**，不再传指针接收。
+		// 顺序仍是「先跑完交互步骤，再取值」——取值动作本身也会被 Do 依次执行。
+		steps = append(steps, chromedp.WaitReady("html"))
+		if err := chromedpDo(rctx, steps...); err == nil {
+			if t, terr := chromedp.Run(rctx, chromedpTitle()); terr == nil {
+				title = t
+			}
+			if h, herr := chromedp.Run(rctx, chromedpOuterHTML("html")); herr == nil {
+				html = h
+			}
 			rendered = true
 		} else {
 			log.Printf("[%s] render via backend failed (%v), fallback to dump-dom", p.name, err)
@@ -968,7 +973,7 @@ func (p *Plugin) ensureBackend() (bool, bool, error) {
 // sharedTab 在共享后端上开一个新标签页（RemoteAllocator + NewContext）。
 func sharedTab(allocCtx context.Context) (context.Context, context.CancelFunc, error) {
 	tabCtx, tabCancel := chromedp.NewContext(allocCtx)
-	if err := chromedp.Run(tabCtx); err != nil {
+	if err := chromedpDo(tabCtx); err != nil {
 		tabCancel()
 		return nil, nil, err
 	}
@@ -989,7 +994,7 @@ func (p *Plugin) localSpawnFailback() (context.Context, context.CancelFunc, cont
 	}
 	allocCtx, cancelAlloc := chromedp.NewExecAllocator(context.Background(), opts...)
 	ctx, _ := chromedp.NewContext(allocCtx)
-	if err := chromedp.Run(ctx); err != nil {
+	if err := chromedpDo(ctx); err != nil {
 		cancelAlloc()
 		return nil, nil, nil, err
 	}
@@ -1037,14 +1042,14 @@ func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, e
 	// 路径一：systemd 托管的共享后端（主路径）
 	ok, needInstall, berr := p.ensureBackend()
 	if ok {
-		remoteCtx, remoteCancel := chromedp.NewRemoteAllocator(context.Background(), cdpEndpoint)
+		remoteCtx, remoteCancel := newRemoteAllocator(context.Background(), cdpEndpoint)
 		probe, _ := chromedp.NewContext(remoteCtx)
-		if err := chromedp.Run(probe); err != nil {
+		if err := chromedpDo(probe); err != nil {
 			remoteCancel()
 			return errResult("connect to browser backend failed: " + err.Error()), nil
 		}
 		tabCtx, tabCancel := chromedp.NewContext(remoteCtx)
-		if err := chromedp.Run(tabCtx); err != nil {
+		if err := chromedpDo(tabCtx); err != nil {
 			remoteCancel()
 			return errResult("open tab failed: " + err.Error()), nil
 		}
@@ -1080,7 +1085,7 @@ func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, e
 
 	initURL := readArg(args, "url", "")
 	if initURL != "" {
-		if err := chromedp.Run(session.ctx,
+		if err := chromedpDo(session.ctx,
 			chromedp.Navigate(initURL),
 			chromedp.WaitReady("body"),
 		); err != nil {
@@ -1126,7 +1131,7 @@ func (p *Plugin) handleNavigate(args map[string]interface{}) (interface{}, error
 		return errResult(err.Error()), nil
 	}
 	waitSec := int64(readArg(args, "wait", float64(2)))
-	if err := chromedp.Run(s.ctx,
+	if err := chromedpDo(s.ctx,
 		chromedp.Navigate(rawURL),
 		chromedp.WaitReady("body"),
 		chromedp.Sleep(time.Duration(waitSec)*time.Second),
@@ -1158,9 +1163,28 @@ func (p *Plugin) handleScreenshot(args map[string]interface{}) (interface{}, err
 	var buf []byte
 	var err error
 	if full {
-		err = chromedp.Run(s.ctx, chromedp.FullScreenshot(&buf, 90))
+		buf, err = chromedp.Run(s.ctx, chromedpFullScreenshot(90))
 	} else {
-		err = chromedp.Run(s.ctx, chromedp.Screenshot("body", &buf))
+		// ★ 视口截图用 CaptureScreenshot，**不能用 Screenshot("body")**（2026-10-11 修）。
+		//
+		// Screenshot 内部是 QueryAfter + NodeVisible，而 NodeVisible 在
+		// headless Chromium 下**永远不满足**：它先用 dom.GetBoxModel 拿到盒子
+		// （实测 300µs 就成功），再用 visibleJS 判定 —— 而 visibleJS 实测
+		// 返回 true（offsetWidth=480）。两者都对，但它仍会一直等下去。
+		//
+		// 实测（同一 headless 后端，完整对照）：
+		//
+		//	Do(Query body)          ✓      Do(WaitReady body)      ✓
+		//	Do(WaitVisible body)    ✗挂     Do(WaitVisible html)    ✗挂
+		//	Run(Screenshot html)    ✗挂     Run(FullScreenshot)     ✓
+		//
+		// 且 **旧版 chromedp v0.9.5 同样挂** —— 这不是升级引入的，是早就存在的
+		// 缺陷。生产日志佐证：成功的 8 次都是 agent 传了 full:true（走
+		// FullScreenshot），超时的 5 次都是默认分支。
+		//
+		// CaptureScreenshot 截整个视口，不经过 NodeVisible 那条链，实测 70KB / 正常返回。
+		// 语义也更对：「不传 full 就只截当前视口」本来就是 API 文档的含义。
+		buf, err = chromedp.Run(s.ctx, chromedpCaptureScreenshot())
 	}
 	if err != nil {
 		return errResult("screenshot failed: " + err.Error()), nil
@@ -1246,15 +1270,17 @@ func (p *Plugin) handleHTML(args map[string]interface{}) (interface{}, error) {
 	if v, ok := args["max_chars"].(float64); ok && v > 0 {
 		maxChars = int(v)
 	}
-	var html string
-	if err := chromedp.Run(s.ctx, chromedp.OuterHTML("html", &html)); err != nil {
+	html, err := chromedp.Run(s.ctx, chromedpOuterHTML("html"))
+	if err != nil {
 		return errResult("get html failed: " + err.Error()), nil
 	}
 	var title, currentURL string
-	chromedp.Run(s.ctx,
-		chromedp.Title(&title),
-		chromedp.Location(&currentURL),
-	)
+	if t, terr := chromedp.Run(s.ctx, chromedpTitle()); terr == nil {
+		title = t
+	}
+	if u, uerr := chromedp.Run(s.ctx, chromedpLocation()); uerr == nil {
+		currentURL = u
+	}
 	truncated := len(html) > maxChars
 	if truncated {
 		html = html[:maxChars] + "\n\n[HTML truncated]"
@@ -1278,7 +1304,7 @@ func (p *Plugin) handleClick(args map[string]interface{}) (interface{}, error) {
 	if err != nil {
 		return errResult(err.Error()), nil
 	}
-	if err := chromedp.Run(s.ctx,
+	if err := chromedpDo(s.ctx,
 		chromedp.WaitVisible(selector),
 		chromedp.Click(selector),
 	); err != nil {
@@ -1298,7 +1324,7 @@ func (p *Plugin) handleType(args map[string]interface{}) (interface{}, error) {
 	if err != nil {
 		return errResult(err.Error()), nil
 	}
-	actions := []chromedp.Action{
+	actions := []chromedp.Action[chromedp.Void]{
 		chromedp.WaitVisible(selector),
 		chromedp.Click(selector, chromedp.NodeVisible),
 		chromedp.Clear(selector),
@@ -1311,7 +1337,7 @@ func (p *Plugin) handleType(args map[string]interface{}) (interface{}, error) {
 	if submit {
 		actions = append(actions, chromedp.SendKeys(selector, "\r"))
 	}
-	if err := chromedp.Run(s.ctx, actions...); err != nil {
+	if err := chromedpDo(s.ctx, actions...); err != nil {
 		return errResult("type failed (element may not exist or page blocking): " + err.Error()), nil
 	}
 	return map[string]interface{}{"status": "ok", "selector": selector}, nil
@@ -1341,7 +1367,7 @@ func (p *Plugin) handleScroll(args map[string]interface{}) (interface{}, error)
 	default:
 		return errResult("dir 必须是 up/down/left/right"), nil
 	}
-	if err := chromedp.Run(s.ctx, chromedp.Evaluate(scrollJS, nil)); err != nil {
+	if err := chromedpDo(s.ctx, chromedpEvaluateVoid(scrollJS)); err != nil {
 		return errResult("scroll failed: " + err.Error()), nil
 	}
 	return map[string]interface{}{"status": "ok", "dir": dir, "amount": amount}, nil