magic-agent 2.4.3 → 2.6.3

package/internal/client/browseinput.go

@@ -0,0 +1,481 @@
+package client
+
+import (
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+/* 内置浏览器的**输入中继**（手机端远程触控）。
+ *
+ * ── 分工（2026-10-25 内置浏览器 MCP 改基 agent-browser 后）──
+ * 驱动/截图面（`magic-client browse …`、需求截图）走 **agent-browser**
+ * （真实 Chromium/CDP，见 ab.go）——真实事件、CDP 级截图。
+ * 本中继只承担手机端「远程触控」：页面跑在手机的 WebView iframe 里，
+ * agent-browser 的浏览器在服务端，两者是两个上下文 —— 手机用户触屏操控
+ * iframe 里的页面仍走这里。
+ *
+ * ── 形状 ──
+ *   viewer（页面内 relay 脚本，同一时刻至多一个，后连顶掉前连）
+ *     → server：hello / state / ack
+ *     ← server：input / ping
+ *   driver（手机 UI，可多个）
+ *     → server：input（server 重编 seq 后转发给 viewer）
+ *     ← server：state / ack / viewer 上下线通知
+ *
+ * 坐标系 = 被代理页面自身的 CSS 像素；viewer 在 hello/state 里上报页面宽高，
+ * driver 需要换算时用它。VPN 开启或未配对时页面不走中转、脚本不注入，
+ * 鼠标中继自然不可用 —— 与浏览中转同边界。
+ *
+ * 已知边界：合成事件 isTrusted=false，个别反自动化站点会忽略 —— 如实记录，不假装是 CDP。
+ */
+
+const browseWSPath = "/browse-input"
+
+// BrowseWSPath 导出给驱动端 CLI（cmd/magic-client）拼连接地址用。
+const BrowseWSPath = browseWSPath
+
+// 输入动作白名单：白名单外的 action 直接回 ack 失败，不往页面派。
+//
+// （2026-10-25）shot 已退役：截图改走服务端 agent-browser（internal/client/ab.go，
+// POST /desk/requirements/shot-remote）。relay 只承担「远程鼠标」——
+// 真实事件、CDP 级截图交给 agent-browser，页面内栅格化的路子（html2canvas）
+// 有跨域污染 / iframe 抓不到 / 慢页超时三个硬伤，不再保留。
+var browseInputActions = map[string]bool{
+	"move": true, "down": true, "up": true, "click": true, "dblclick": true,
+	"scroll": true, "type": true, "key": true,
+}
+
+// browseMsg 中继线上的统一信封。字段全部可选，按 type 取用。
+type browseMsg struct {
+	Type string `json:"type"`
+	// input 帧
+	Seq    int      `json:"seq,omitempty"`
+	Action string   `json:"action,omitempty"`
+	X      float64  `json:"x,omitempty"`
+	Y      float64  `json:"y,omitempty"`
+	DX     float64  `json:"dx,omitempty"`
+	DY     float64  `json:"dy,omitempty"`
+	Text   string   `json:"text,omitempty"`
+	Key    string   `json:"key,omitempty"`
+	Mods   []string `json:"modifiers,omitempty"`
+	// state / hello 帧
+	Title string `json:"title,omitempty"`
+	URL   string `json:"url,omitempty"`
+	W     int    `json:"w,omitempty"`
+	H     int    `json:"h,omitempty"`
+	// ack 帧（OK 用指针：false 不能被 omitempty 吞掉，又不想让 input 帧带 ok 字段）
+	OK     *bool  `json:"ok,omitempty"`
+	Reason string `json:"reason,omitempty"`
+	// viewer 帧
+	Online bool `json:"online,omitempty"`
+	// Data 截图帧带回的数据（当前只有 shot 用：staging 上传后的 URL）。
+	Data string `json:"data,omitempty"`
+}
+
+// boolPtr ack 帧的小工具。
+func boolPtr(v bool) *bool { return &v }
+
+// browsePeer 一条已升级的连接：写互斥（gorilla 的 WriteJSON 并发不安全）。
+type browsePeer struct {
+	conn *websocket.Conn
+	wmu  sync.Mutex
+}
+
+func (p *browsePeer) write(msg *browseMsg) error {
+	p.wmu.Lock()
+	defer p.wmu.Unlock()
+	return p.conn.WriteJSON(msg)
+}
+
+// browseInputHub 中继枢纽。零值不可用，用 Service.inputHub() 惰性建。
+type browseInputHub struct {
+	mu      sync.Mutex
+	viewer  *browsePeer
+	drivers map[*browsePeer]bool
+	seq     int
+}
+
+func (s *Service) inputHub() *browseInputHub {
+	s.inputHubOnce.Do(func() { s.inputHubRef = &browseInputHub{drivers: map[*browsePeer]bool{}} })
+	return s.inputHubRef
+}
+
+func (h *browseInputHub) setViewer(p *browsePeer) (old *browsePeer) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	old = h.viewer
+	h.viewer = p
+	return old
+}
+
+func (h *browseInputHub) clearViewer(p *browsePeer) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.viewer == p {
+		h.viewer = nil
+	}
+}
+
+func (h *browseInputHub) addDriver(p *browsePeer) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	h.drivers[p] = true
+}
+
+func (h *browseInputHub) removeDriver(p *browsePeer) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	delete(h.drivers, p)
+}
+
+// toDrivers 把一帧广播给所有 driver（state / ack / viewer 上下线）。
+func (h *browseInputHub) toDrivers(msg *browseMsg) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	for d := range h.drivers {
+		_ = d.write(msg) // 单条失败留给读循环发现并清理
+	}
+}
+
+// dispatch driver 的 input 帧：重编 seq（保证全局有序且 ack 能对上），转给 viewer。
+func (h *browseInputHub) dispatch(action string, in *browseMsg) *browseMsg {
+	if !browseInputActions[action] {
+		return &browseMsg{Type: "ack", OK: boolPtr(false), Reason: "未知动作：" + action}
+	}
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.viewer == nil {
+		return &browseMsg{Type: "ack", OK: boolPtr(false), Reason: "页面未连接（viewer 离线）"}
+	}
+	h.seq++
+	in.Seq = h.seq
+	if err := h.viewer.write(in); err != nil {
+		return &browseMsg{Type: "ack", OK: boolPtr(false), Reason: "派发失败：" + err.Error()}
+	}
+	return nil // ack 由 viewer 回
+}
+
+func (s *Service) handleBrowseInput(w http.ResponseWriter, r *http.Request) {
+	// 鉴权：与 /b/、/proxy-ws 同口径 —— 查询令牌或 cookie。
+	if want := strings.TrimSpace(s.opts.Token); want != "" {
+		got := strings.TrimSpace(r.URL.Query().Get("token"))
+		if got == "" {
+			if c, err := r.Cookie(browseCookie); err == nil {
+				got = c.Value
+			}
+		}
+		if got != want {
+			http.Error(w, "缺少或错误的访问令牌", http.StatusUnauthorized)
+			return
+		}
+	}
+
+	role := r.URL.Query().Get("role")
+	if role != "viewer" && role != "driver" {
+		role = "driver"
+	}
+
+	c, err := wsUpgrader.Upgrade(w, r, nil)
+	if err != nil {
+		return // Upgrade 已写过响应
+	}
+	peer := &browsePeer{conn: c}
+	hub := s.inputHub()
+
+	defer func() {
+		_ = c.WriteControl(websocket.CloseMessage,
+			websocket.FormatCloseMessage(websocket.CloseNormalClosure, ""),
+			time.Now().Add(time.Second))
+		_ = c.Close()
+	}()
+
+	switch role {
+	case "viewer":
+		old := hub.setViewer(peer)
+		if old != nil {
+			_ = old.conn.Close() // 后连顶前连：旧 viewer 的读循环随即退出
+		}
+		hub.toDrivers(&browseMsg{Type: "viewer", Online: true})
+		defer func() {
+			hub.clearViewer(peer)
+			hub.toDrivers(&browseMsg{Type: "viewer", Online: false})
+		}()
+		s.browseViewerLoop(hub, peer)
+	default: // driver
+		hub.addDriver(peer)
+		defer hub.removeDriver(peer)
+		// 新 driver 上线：把当前 viewer 在线状态与最后一次页面状态同步给它。
+		hub.mu.Lock()
+		online := hub.viewer != nil
+		hub.mu.Unlock()
+		_ = peer.write(&browseMsg{Type: "viewer", Online: online})
+		s.browseDriverLoop(hub, peer)
+	}
+}
+
+// browseViewerLoop 读 viewer 的帧：hello/state 转给 drivers，其余忽略。
+func (s *Service) browseViewerLoop(hub *browseInputHub, peer *browsePeer) {
+	s.log.Printf("browse-input: viewer 已连接 (%s)", peer.conn.RemoteAddr())
+	defer s.log.Printf("browse-input: viewer 已断开")
+	for {
+		var m browseMsg
+		if err := peer.conn.ReadJSON(&m); err != nil {
+			return
+		}
+		switch m.Type {
+		case "hello", "state", "ack":
+			// hello/state 广播给所有 driver；ack 按 seq 归属，典型只有一个 driver，
+			// 这里同样广播，由 driver 自己按 seq 认领。
+			hub.toDrivers(&m)
+		default:
+			// ping 等 server 主动发；viewer 发来的其它类型不认识就不转发。
+		}
+	}
+}
+
+// browseDriverLoop 读 driver 的帧：只认 input，派发给 viewer；其余回 ack 失败。
+func (s *Service) browseDriverLoop(hub *browseInputHub, peer *browsePeer) {
+	for {
+		var m browseMsg
+		if err := peer.conn.ReadJSON(&m); err != nil {
+			return
+		}
+		switch m.Type {
+		case "input":
+			if ack := hub.dispatch(m.Action, &m); ack != nil {
+				_ = peer.write(ack)
+			}
+		case "ping":
+			// 让 viewer 报一次当前状态（CLI 的 `browse state` 靠它）。
+			hub.mu.Lock()
+			v := hub.viewer
+			hub.mu.Unlock()
+			if v != nil {
+				_ = v.write(&browseMsg{Type: "ping"})
+			} else {
+				_ = peer.write(&browseMsg{Type: "ack", OK: boolPtr(false), Reason: "页面未连接（viewer 离线）"})
+			}
+		default:
+			_ = peer.write(&browseMsg{Type: "ack", OK: boolPtr(false), Reason: "driver 只能发 input/ping 帧"})
+		}
+	}
+}
+
+/* browseRelayJS 注入到中转页面里的 relay 脚本。
+ *
+ * 职责：
+ *   - 连回 /browse-input?role=viewer（cookie 鉴权由浏览器自动带上；断线重连）
+ *   - 收 input 帧在被代理页面里派发合成事件（页面自身 CSS 像素坐标）
+ *   - 叠加一只虚拟鼠标：对称导航箭头（绿色），跟随 driver 的移动/点击，点击有双涟漪反馈
+ *   - 页面加载完成 / 标题变化时上报 state；每条 input 回 ack
+ *
+ * 刻意不做的：不拦截页面自身事件、不做 DOM 摘要 —— 只当一只「远程鼠标」。
+ */
+const browseRelayJS = `(function () {
+  'use strict';
+  var SENTINEL = '__magicBrowseRelay';
+  if (window[SENTINEL]) return;            // 防 SPA 反复执行
+  window[SENTINEL] = true;
+
+  var ws = null, seqSeen = 0, titleTimer = null;
+  var curEl = null, curSvg = null, curDot = null, curPressed = false, curX = -100, curY = -100;
+
+  // ---- 虚拟鼠标：对称导航箭头（绿填充+白描边），热点=顶部尖端；按压点+点击双涟漪。
+  //      pointer-events:none，不干扰页面事件。 ----
+  function ensureCursor() {
+    if (curEl) return;
+    var doc = document;
+    curEl = doc.createElement('div');
+    curEl.id = '__magic_vmouse';
+    curEl.setAttribute('style',
+      'position:fixed;left:0;top:0;z-index:2147483647;pointer-events:none;will-change:transform;');
+    curEl.innerHTML =
+      '<svg width="50" height="50" viewBox="0 0 32 32" style="display:block;transition:transform .1s;' +
+      'filter:drop-shadow(0 2px 6px rgba(46,160,100,.5))">' +
+      '<path d="M16 1.5 L30 28.5 L16 21.8 L2 28.5 Z" ' +
+      'fill="#2fbf71" stroke="#fff" stroke-width="1.6" stroke-linejoin="round"/></svg>';
+    curSvg = curEl.firstChild;
+    curDot = doc.createElement('div');
+    curDot.setAttribute('style',
+      'position:fixed;left:0;top:0;z-index:2147483647;pointer-events:none;width:16px;height:16px;margin:-8px;' +
+      'border-radius:50%;background:rgba(47,191,113,.4);border:3px solid #fff;' +
+      'box-shadow:0 0 10px rgba(47,191,113,.9);transition:transform .1s;');
+    doc.body.appendChild(curEl);
+    doc.body.appendChild(curDot);
+    curEl.style.transform = 'translate(' + (curX - 25) + 'px,' + (curY - 2.3) + 'px)';
+    curDot.style.transform = 'translate(' + curX + 'px,' + curY + 'px) scale(0)';
+  }
+
+  function moveCursor(x, y) {
+    if (typeof x !== 'number' || typeof y !== 'number') return;
+    curX = x; curY = y;
+    ensureCursor();
+    // viewBox 0 0 32 32 → 50px：尖端在 (25, 2.3)，把它对齐到坐标点
+    curEl.style.transform = 'translate(' + (x - 25) + 'px,' + (y - 2.3) + 'px)';
+    curDot.style.transform = 'translate(' + x + 'px,' + y + 'px) scale(' + (curPressed ? 1 : 0) + ')';
+  }
+
+  function pressCursor(down) {
+    curPressed = down;
+    if (curSvg) curSvg.style.transform = down ? 'scale(.9)' : 'scale(1)';
+    if (curDot) curDot.style.transform =
+      'translate(' + curX + 'px,' + curY + 'px) scale(' + (down ? 1 : 0) + ')';
+  }
+
+  function rippleCursor(x, y) {
+    ensureCursor();
+    var mk = function (scale, opacity) {
+      var d = document.createElement('div');
+      var size = 60;
+      d.setAttribute('style',
+        'position:fixed;left:' + (x - size / 2) + 'px;top:' + (y - size / 2) + 'px;width:' + size + 'px;height:' + size + 'px;' +
+        'margin:0;border-radius:50%;border:3px solid rgba(47,191,113,.85);pointer-events:none;z-index:2147483646;' +
+        'box-shadow:0 0 14px rgba(47,191,113,.45);transform:scale(' + scale + ');opacity:' + opacity + ';' +
+        'transition:transform .45s ease-out,opacity .45s ease-out;');
+      document.body.appendChild(d);
+      requestAnimationFrame(function () {
+        d.style.transform = 'scale(' + (scale + 0.35) + ')';
+        d.style.opacity = '0';
+      });
+      setTimeout(function () { if (d.parentNode) d.parentNode.removeChild(d); }, 520);
+    };
+    mk(0.45, 0.95);   // 快环
+    mk(0.85, 0.5);    // 慢环
+  }
+
+  function pageState(type) {
+    return { type: type || 'state', title: document.title || '',
+             url: location.href, w: window.innerWidth, h: window.innerHeight };
+  }
+
+  function send(m) {
+    try { if (ws && ws.readyState === 1) ws.send(JSON.stringify(m)); } catch (e) {}
+  }
+
+  function fireMouse(action, m) {
+    var x = m.x || 0, y = m.y || 0;
+    var opts = { bubbles: true, cancelable: true, view: window,
+                 clientX: x, clientY: y, button: 0, buttons: 0 };
+    var tgt = document.elementFromPoint(x, y) || document.body;
+    if (!tgt) return;
+    function ev(Type, extra) {
+      var o = {}; for (var k in opts) o[k] = opts[k];
+      if (extra) for (var k2 in extra) o[k2] = extra[k2];
+      return typeof PointerEvent === 'function' ? new PointerEvent(Type, o) : new MouseEvent(Type, o);
+    }
+    if (action === 'move') { tgt.dispatchEvent(ev('pointermove', { pointerType: 'mouse' })); tgt.dispatchEvent(new MouseEvent('mousemove', opts)); return; }
+    if (action === 'scroll') {
+      tgt.dispatchEvent(new WheelEvent('wheel', { bubbles: true, cancelable: true, view: window,
+        clientX: x, clientY: y, deltaX: m.dx || 0, deltaY: m.dy || 0 }));
+      window.scrollBy(m.dx || 0, m.dy || 0);
+      return;
+    }
+    var down = (action === 'down' || action === 'click' || action === 'dblclick');
+    var up = (action === 'up' || action === 'click' || action === 'dblclick');
+    if (down) { tgt.dispatchEvent(ev('pointerdown', { pointerType: 'mouse', isPrimary: true, buttons: 1 })); tgt.dispatchEvent(new MouseEvent('mousedown', Object.assign({}, opts, { buttons: 1 }))); }
+    if (up) {
+      tgt.dispatchEvent(ev('pointerup', { pointerType: 'mouse', isPrimary: true }));
+      tgt.dispatchEvent(new MouseEvent('mouseup', opts));
+      tgt.dispatchEvent(new MouseEvent('click', opts));
+      if (action === 'dblclick') tgt.dispatchEvent(new MouseEvent('dblclick', opts));
+    }
+  }
+
+  function fireKey(m) {
+    var tgt = document.activeElement || document.body;
+    var base = { bubbles: true, cancelable: true, view: window, key: m.key || '', code: m.key || '' };
+    tgt.dispatchEvent(new KeyboardEvent('keydown', base));
+    tgt.dispatchEvent(new KeyboardEvent('keyup', base));
+  }
+
+  function fireType(m) {
+    var x = m.x, y = m.y, tgt = null;
+    if (typeof x === 'number' && typeof y === 'number') tgt = document.elementFromPoint(x, y);
+    tgt = tgt || document.activeElement || document.body;
+    if (tgt.focus) { try { tgt.focus(); } catch (e) {} }
+    var text = m.text || '';
+    if (tgt && (tgt.tagName === 'INPUT' || tgt.tagName === 'TEXTAREA' || tgt.isContentEditable)) {
+      var v = tgt.value !== undefined ? tgt.value : tgt.textContent;
+      var merged = (v || '') + text;
+      if (tgt.value !== undefined) { tgt.value = merged; } else { tgt.textContent = merged; }
+      tgt.dispatchEvent(new Event('input', { bubbles: true }));
+      tgt.dispatchEvent(new Event('change', { bubbles: true }));
+      return;
+    }
+    fireKey({ key: text });
+  }
+
+  function handle(m) {
+    if (!m || m.type !== 'input' || !m.action) return;
+    try {
+      switch (m.action) {
+        case 'move': case 'down': case 'up': case 'click': case 'dblclick': case 'scroll': case 'type':
+          if (typeof m.x === 'number' && typeof m.y === 'number') {
+            moveCursor(m.x, m.y);
+            if (m.action === 'down') pressCursor(true);
+            if (m.action === 'up') pressCursor(false);
+            if (m.action === 'click' || m.action === 'dblclick') rippleCursor(m.x, m.y);
+          }
+          break;
+        default: break;
+      }
+      switch (m.action) {
+        case 'move': case 'down': case 'up': case 'click': case 'dblclick': case 'scroll':
+          fireMouse(m.action, m); break;
+        case 'type': fireType(m); break;
+        case 'key': fireKey(m); break;
+        default: send({ type: 'ack', seq: m.seq, ok: false, reason: '未知动作' }); return;
+      }
+      seqSeen = m.seq;
+      send({ type: 'ack', seq: m.seq, ok: true });
+    } catch (e) {
+      send({ type: 'ack', seq: m.seq, ok: false, reason: String(e && e.message || e) });
+    }
+  }
+
+  /* 连接用的令牌：中转 URL 上的 magicToken 就是访问令牌（browse.go 的鉴权口径）。
+     APK 壳的 iframe 与桌面端**跨站**，SameSite=Lax 的 cookie 不随 WebSocket
+     握手发送 —— 只靠 cookie 会连不上 viewer。 */
+  function pageToken(fallback) {
+    try {
+      var q = new URLSearchParams(location.search);
+      var t = q.get('magicToken');
+      if (t) return t;
+    } catch (e) {}
+    return fallback || '';
+  }
+
+  function connect() {
+    var proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    /* 令牌：优先取页面地址里的 magicToken（每条改写出的 URL 都带它）。
+       没有就退回 cookie（同源场景能过）—— 但 APK 壳的跨站 iframe 两者都可能没有，
+       那时连不上 viewer：如实表现为「页面未连接」，不假装能驱动。 */
+    var wsUrl = proto + '//' + location.host + '/browse-input?role=viewer';
+    var tok = pageToken();
+    if (tok) wsUrl += '&token=' + encodeURIComponent(tok);
+    try { ws = new WebSocket(wsUrl); }
+    catch (e) { setTimeout(connect, 4000); return; }
+    ws.onopen = function () { send(pageState('hello')); };
+    ws.onmessage = function (e) {
+      var m; try { m = JSON.parse(e.data); } catch (err) { return; }
+      if (m.type === 'ping') { send(pageState('state')); return; }
+      handle(m);
+    };
+    ws.onclose = function () { setTimeout(connect, 2000); };
+    ws.onerror = function () { try { ws.close(); } catch (e2) {} };
+  }
+
+  connect();
+  // 标题/地址变化探测：轻量轮询足够（SPA 改标题不派事件）。
+  var lastTitle = document.title, lastHref = location.href;
+  titleTimer = setInterval(function () {
+    if (document.title !== lastTitle || location.href !== lastHref) {
+      lastTitle = document.title; lastHref = location.href;
+      send(pageState('state'));
+    }
+  }, 1500);
+})();`

package/internal/client/browseinput_test.go

@@ -0,0 +1,216 @@
+package client
+
+import (
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+// TestRelayJSServed /b/relay.js 是我们自己的资源，必须原样可取（不能当主机名去抓）。
+func TestRelayJSServed(t *testing.T) {
+	s := &Service{}
+	proxy := httptest.NewServer(http.HandlerFunc(s.handleBrowse))
+	defer proxy.Close()
+
+	resp, err := http.Get(proxy.URL + "/b/relay.js")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("relay.js 应 200，实际 %d", resp.StatusCode)
+	}
+	if ct := resp.Header.Get("Content-Type"); !strings.Contains(ct, "text/javascript") {
+		t.Errorf("relay.js Content-Type 应为 text/javascript，实际 %q", ct)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !strings.Contains(string(body), "browse-input") {
+		t.Error("relay.js 应包含 /browse-input 连接逻辑")
+	}
+}
+
+// TestRelayInjected 改写后的 HTML 应注入 relay 脚本（与 <base> 同位置）。
+func TestRelayInjected(t *testing.T) {
+	page := mustURL(t, "https://example.com/a")
+	out := string(rewriteBrowseHTML([]byte(`<html><head><title>x</title></head><body></body></html>`),
+		page, testProxyBase, ""))
+	if !strings.Contains(out, `<script src="http://p/b/relay.js" defer></script>`) {
+		t.Errorf("应注入 relay 脚本，实际：%s", out)
+	}
+	if !strings.Contains(out, `<base href="http://p/b/https/example.com/a">`) {
+		t.Errorf("<base> 注入不应被破坏，实际：%s", out)
+	}
+}
+
+func dialWS(t *testing.T, urlStr string) *websocket.Conn {
+	t.Helper()
+	u, err := url.Parse(urlStr)
+	if err != nil {
+		t.Fatal(err)
+	}
+	u.Scheme = "ws"
+	c, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
+	if err != nil {
+		t.Fatalf("连接 %s 失败：%v", u, err)
+	}
+	t.Cleanup(func() { _ = c.Close() })
+	return c
+}
+
+func readMsg(t *testing.T, c *websocket.Conn) browseMsg {
+	t.Helper()
+	_ = c.SetReadDeadline(time.Now().Add(5 * time.Second))
+	var m browseMsg
+	if err := c.ReadJSON(&m); err != nil {
+		t.Fatalf("读帧失败：%v", err)
+	}
+	return m
+}
+
+// TestBrowseInputAuth 有令牌的服务：握手不带令牌必须被拒。
+func TestBrowseInputAuth(t *testing.T) {
+	s := &Service{opts: Options{Token: "sekret"}}
+	proxy := httptest.NewServer(http.HandlerFunc(s.handleBrowseInput))
+	defer proxy.Close()
+
+	u, _ := url.Parse(proxy.URL)
+	u.Scheme = "ws"
+	_, resp, err := websocket.DefaultDialer.Dial(u.String(), nil)
+	if err == nil {
+		t.Fatal("缺令牌的握手应失败")
+	}
+	if resp == nil || resp.StatusCode != http.StatusUnauthorized {
+		t.Errorf("缺令牌应 401，实际：%v", err)
+	}
+}
+
+// TestBrowseInputDispatch 端到端：driver 发 input → viewer 收到（seq 由 server 重编），
+// viewer 回 ack → driver 收到。也验证无 viewer 时 ack 失败、未知动作被拦。
+func TestBrowseInputDispatch(t *testing.T) {
+	// log 必须给：viewer 循环会打连接日志，nil logger 会 panic（被 net/http recover
+	// 吃掉后 defer 又把 viewer 清掉，表象是「viewer 永远离线」）。
+	s := &Service{log: log.New(io.Discard, "", 0)}
+	proxy := httptest.NewServer(http.HandlerFunc(s.handleBrowseInput))
+	defer proxy.Close()
+
+	viewer := dialWS(t, proxy.URL+"/browse-input?role=viewer")
+	time.Sleep(100 * time.Millisecond) // 等服务端把 viewer 登记进 hub（dial 返回与 setViewer 有竞态）
+	driver := dialWS(t, proxy.URL+"/browse-input?role=driver")
+
+	// 新 driver 上线会先收到 viewer 状态帧（此时 viewer 已连 → online）。
+	if m := readMsg(t, driver); m.Type != "viewer" || !m.Online {
+		t.Fatalf("driver 首帧应是 viewer 上线通知，实际：%+v", m)
+	}
+
+	// 未知动作：直接 ack 失败，不往页面派。
+	_ = driver.WriteJSON(browseMsg{Type: "input", Action: "hack"})
+	if m := readMsg(t, driver); m.Type != "ack" || m.OK == nil || *m.OK {
+		t.Fatalf("未知动作应 ack 失败，实际：%+v", m)
+	}
+
+	// 正常 click：viewer 收到重编过 seq 的 input，回 ack，driver 收到。
+	_ = driver.WriteJSON(browseMsg{Type: "input", Action: "click", X: 10, Y: 20})
+	in := readMsg(t, viewer)
+	if in.Type != "input" || in.Action != "click" || in.X != 10 || in.Y != 20 || in.Seq == 0 {
+		t.Fatalf("viewer 应收到 input 帧，实际：%+v", in)
+	}
+	_ = viewer.WriteJSON(browseMsg{Type: "ack", Seq: in.Seq, OK: boolPtr(true)})
+	if m := readMsg(t, driver); m.Type != "ack" || m.OK == nil || !*m.OK || m.Seq != in.Seq {
+		t.Fatalf("driver 应收到 ack，实际：%+v", m)
+	}
+
+	// viewer 上报 state → driver 收到。
+	_ = viewer.WriteJSON(browseMsg{Type: "state", Title: "T", W: 390, H: 844})
+	if m := readMsg(t, driver); m.Type != "state" || m.Title != "T" || m.W != 390 {
+		t.Fatalf("driver 应收到 state，实际：%+v", m)
+	}
+
+	// viewer 掉线后再派发：ack 失败。
+	_ = viewer.Close()
+	time.Sleep(100 * time.Millisecond) // 给服务端读循环时间清理 viewer
+	// driver 会先收到 viewer 下线通知帧。
+	if m := readMsg(t, driver); m.Type != "viewer" || m.Online {
+		t.Fatalf("应先收到 viewer 下线通知，实际：%+v", m)
+	}
+	_ = driver.WriteJSON(browseMsg{Type: "input", Action: "click"})
+	if m := readMsg(t, driver); m.Type != "ack" || m.OK == nil || *m.OK {
+		t.Fatalf("viewer 离线后派发应 ack 失败，实际：%+v", m)
+	}
+}
+
+// TestBrowseRelayJSON 形状自检：ack/OK 等字段按 omitempty 序列化，不能互相污染。
+func TestBrowseRelayJSON(t *testing.T) {
+	b, err := json.Marshal(browseMsg{Type: "input", Seq: 3, Action: "click", X: 1.5, Y: 2})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m map[string]any
+	if err := json.Unmarshal(b, &m); err != nil {
+		t.Fatal(err)
+	}
+	if m["type"] != "input" || m["action"] != "click" {
+		t.Errorf("序列化形状不对：%s", b)
+	}
+	if _, ok := m["ok"]; ok {
+		t.Errorf("ack 专用的 ok 字段不应出现在 input 帧里：%s", b)
+	}
+	if b2, _ := json.Marshal(browseMsg{Type: "ack", OK: boolPtr(false), Reason: "x"}); !strings.Contains(string(b2), `"ok":false`) {
+		t.Errorf("ack 的 ok=false 不能被 omitempty 吞掉：%s", b2)
+	}
+}
+
+// TestRelayJSHasNoShotBranch relay 不再承担截图（2026-10-25 改基 agent-browser）：
+// 页面内栅格化的代码必须删干净，不然页面里还会去加载已经不存在的 /b/shotlib.js。
+func TestRelayJSHasNoShotBranch(t *testing.T) {
+	for _, banned := range []string{
+		"doShot", "/b/shotlib.js", "/desk/upload", "html2canvas",
+	} {
+		if strings.Contains(browseRelayJS, banned) {
+			t.Errorf("relay 脚本不应再含 %q —— 页面内截图已退役", banned)
+		}
+	}
+}
+
+// TestShotLibGone /b/shotlib.js 已随页面内截图退役，必须 404（不能吐空文件假装成功）。
+func TestShotLibGone(t *testing.T) {
+	s := &Service{}
+	proxy := httptest.NewServer(http.HandlerFunc(s.handleBrowse))
+	defer proxy.Close()
+
+	resp, err := http.Get(proxy.URL + "/b/shotlib.js")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	// 不走中转特判后，"shotlib.js" 会被当主机名去抓 —— 无论哪种结果都不该 200。
+	if resp.StatusCode == http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		t.Errorf("shotlib.js 应已下线，实际 200（内容前 80 字节: %.80q）", body)
+	}
+}
+
+// TestShotActionRejected shot 动作已从白名单移除（截图走 agent-browser）：
+// driver 发 shot 必须立刻 ack 失败「未知动作」，而不是悄悄派给页面。
+func TestShotActionRejected(t *testing.T) {
+	s := &Service{log: log.New(io.Discard, "", 0)}
+	proxy := httptest.NewServer(http.HandlerFunc(s.handleBrowseInput))
+	defer proxy.Close()
+
+	driver := dialWS(t, proxy.URL+"/browse-input?role=driver")
+	if m := readMsg(t, driver); m.Type != "viewer" || m.Online {
+		t.Fatalf("首帧应是 viewer 状态（离线），实际：%+v", m)
+	}
+	_ = driver.WriteJSON(browseMsg{Type: "input", Action: "shot"})
+	m := readMsg(t, driver)
+	if m.Type != "ack" || m.OK == nil || *m.OK {
+		t.Fatalf("shot 应 ack 失败（动作已退役），实际：%+v", m)
+	}
+}