magic-agent 2.4.3 → 2.6.3

package/cmd/magic-client/browsectl.go

@@ -0,0 +1,199 @@
+// browse 驱动端：`magic-client browse <动作> …`。
+//
+// 「内置浏览器 MCP」的驱动/截图面（2026-10-25 用户定调）：基于 **agent-browser**
+// 插件（vercel-labs，Rust 原生 CLI，驱动真实 Chromium/CDP）实现。
+//
+// 与旧实现的差别：不再连本插件的 /browse-input WS 派发**合成事件**（isTrusted=false，
+// 反自动化站点忽略），而是 spawn agent-browser 原生 exe —— 真实事件、CDP 级截图、
+// PDF、a11y 快照。手机端「看页面 + 触控」仍走 /b/ 中转 + relay 远程鼠标（不在此列）。
+//
+// 用法：
+//
+//	magic-client browse open <url>           # 打开页面（daemon 未起自动拉起）
+//	magic-client browse state                # 打印当前页面状态（标题/地址）
+//	magic-client browse click <x> <y>        # 在页面坐标 (x,y) 点击
+//	magic-client browse move <x> <y>         # 移动指针（不点击）
+//	magic-client browse dblclick <x> <y>     # 双击
+//	magic-client browse scroll <dx> <dy>     # 滚动（正数向下/右）
+//	magic-client browse type <文本>          # 向焦点元素输入文本
+//	magic-client browse key <键名>           # 如 Enter / Escape / a
+//	magic-client browse shot [--out 文件] [--full-page]  # 截当前页面，存成 PNG（默认 shot.png）
+//	magic-client browse eval <js>            # 在页面里跑一段 JS
+//	magic-client browse pdf <文件>           # 存成 PDF
+//	magic-client browse snap [-i]            # a11y 快照（-i 只出可交互元素）
+//
+// 会话固定 --session magic-client（与人类/其它工具的 default 会话隔离）。
+// 探测：MAGIC_AGENT_AGENT_BROWSER_BIN > npm 全局前缀 > PATH；都没有时报安装提示。
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+
+	"github.com/darren/magic-agent/internal/client"
+)
+
+// browseTimeout 兼容旧名（新的超时在 client.ABTimeout）。
+const browseTimeout = client.ABTimeout
+
+func runBrowseDriver(args []string) int {
+	fs := newFlagSet("browse")
+	_ = fs.Parse(args)
+	rest := fs.Args()
+
+	if len(rest) == 0 {
+		fmt.Fprintln(os.Stderr, "用法: magic-client browse open|state|click|move|dblclick|scroll|type|key|shot|eval|pdf|snap …")
+		return 2
+	}
+
+	action := strings.ToLower(rest[0])
+	argv := rest[1:]
+
+	switch action {
+	case "open":
+		if len(argv) < 1 {
+			return browseUsage("open 需要 <url>")
+		}
+		return browseCall("open "+argv[0], func() (any, error) {
+			return nil, client.ABOpen(context.Background(), argv[0])
+		})
+	case "state":
+		return browseCall("state", func() (any, error) {
+			url, title, err := client.ABState(context.Background())
+			if err != nil {
+				return nil, err
+			}
+			return map[string]any{"url": url, "title": title}, nil
+		})
+	case "click", "move", "dblclick":
+		if len(argv) < 2 {
+			return browseUsage(action + " 需要 x y")
+		}
+		x, e1 := strconv.ParseFloat(argv[0], 64)
+		y, e2 := strconv.ParseFloat(argv[1], 64)
+		if e1 != nil || e2 != nil {
+			return browseUsage(action + " 的坐标必须是数字")
+		}
+		return browseCall(action, func() (any, error) {
+			return nil, client.ABMouse(context.Background(), action, x, y)
+		})
+	case "scroll":
+		if len(argv) < 2 {
+			return browseUsage("scroll 需要 dx dy")
+		}
+		dx, e1 := strconv.ParseFloat(argv[0], 64)
+		dy, e2 := strconv.ParseFloat(argv[1], 64)
+		if e1 != nil || e2 != nil {
+			return browseUsage("scroll 的参数必须是数字")
+		}
+		return browseCall("scroll", func() (any, error) {
+			return nil, client.ABScroll(context.Background(), dx, dy)
+		})
+	case "type":
+		if len(argv) < 1 {
+			return browseUsage("type 需要 文本")
+		}
+		text := strings.Join(argv, " ")
+		return browseCall("type", func() (any, error) {
+			return nil, client.ABType(context.Background(), text)
+		})
+	case "key":
+		if len(argv) < 1 {
+			return browseUsage("key 需要 键名（如 Enter）")
+		}
+		return browseCall("key", func() (any, error) {
+			return nil, client.ABKey(context.Background(), argv[0])
+		})
+	case "shot":
+		return browseShot(argv)
+	case "eval":
+		if len(argv) < 1 {
+			return browseUsage("eval 需要 <js>")
+		}
+		return browseCall("eval", func() (any, error) {
+			return client.ABEval(context.Background(), strings.Join(argv, " "))
+		})
+	case "pdf":
+		if len(argv) < 1 {
+			return browseUsage("pdf 需要 <文件>")
+		}
+		out := argv[len(argv)-1]
+		return browseCall("pdf", func() (any, error) {
+			return nil, client.ABPDF(context.Background(), out)
+		})
+	case "snap":
+		interactive := false
+		for _, a := range argv {
+			if a == "-i" || a == "--interactive" {
+				interactive = true
+			}
+		}
+		return browseCall("snap", func() (any, error) {
+			return client.ABSnap(context.Background(), interactive)
+		})
+	default:
+		return browseUsage("未知动作 " + action)
+	}
+}
+
+func browseUsage(msg string) int {
+	fmt.Fprintln(os.Stderr, "magic-client browse:", msg)
+	return 2
+}
+
+// browseCall 统一跑一个 agent-browser 动作并把结果打印/报错。
+func browseCall(name string, fn func() (any, error)) int {
+	v, err := fn()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "magic-client browse %s: %v\n", name, err)
+		return 1
+	}
+	if v == nil {
+		fmt.Println("ok")
+		return 0
+	}
+	out, merr := json.MarshalIndent(v, "", "  ")
+	if merr != nil {
+		fmt.Println("ok")
+		return 0
+	}
+	fmt.Println(string(out))
+	return 0
+}
+
+// browseShot 截当前页面并存成 PNG（agent-browser 真实 Chromium 截图，直接落盘）。
+func browseShot(argv []string) int {
+	out := "shot.png"
+	fullPage := false
+	for i := 0; i < len(argv); i++ {
+		switch {
+		case argv[i] == "--out" && i+1 < len(argv):
+			out = argv[i+1]
+			i++
+		case strings.HasPrefix(argv[i], "--out="):
+			out = strings.TrimPrefix(argv[i], "--out=")
+		case argv[i] == "--full-page" || argv[i] == "--fullpage":
+			fullPage = true
+		case strings.HasPrefix(argv[i], "--"):
+			// 未知 flag 忽略
+		default:
+			out = argv[i] // 位置参数也认（`browse shot a.png`）
+		}
+	}
+	v, err := browseShotRun(out, fullPage)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "magic-client browse shot:", err)
+		return 1
+	}
+	_ = v
+	fmt.Println(out)
+	return 0
+}
+
+func browseShotRun(out string, fullPage bool) (any, error) {
+	return nil, client.ABShot(context.Background(), out, fullPage)
+}

package/cmd/magic-client/clientctl.go

@@ -47,7 +47,7 @@ func writeJSONStdout(v any) {
 	_ = enc.Encode(v)
 }
 
-// runClientCommand 处理 start / stop / status；未知动作返回 false 交给 serve 分支。
+// runClientCommand 处理 start / stop / status / restart；未知动作返回 false 交给 serve 分支。
 func runClientCommand(action string, args []string) (handled bool, code int) {
 	switch action {
 	case "start":
@@ -56,6 +56,8 @@ func runClientCommand(action string, args []string) (handled bool, code int) {
 		return true, runClientStop(args)
 	case "status":
 		return true, runClientStatus(args)
+	case "restart":
+		return true, runClientRestart(args)
 	}
 	return false, 0
 }
@@ -75,11 +77,13 @@ const clientUsage = `magic-client - magic-agent 的客户端插件（桌面 /
 用法：
   magic-client serve  [flags]     前台运行（看日志 / 排障用）
   magic-client start  [flags]     后台常驻（关掉终端也还在），打印手机可用的地址
+  magic-client restart            按当前参数重启后台实例（端口 / 令牌 / 目录沿用，手机不用改地址）
   magic-client status [--json]    看状态（是否在跑、端口、手机地址、健康检查）
   magic-client stop               停掉后台实例（本来没跑也算成功）
 
-手机要连**必须**用 start --lan（或 serve --lan）：默认只绑 127.0.0.1，同机可用、手机不可达。
---lan 时令牌是唯一门锁，至少 24 字符；start 会复用 ~/.magic-client/token，跨重启稳定
+手机要连**默认就行**：start / serve 默认绑 0.0.0.0:9100（--addr 可覆盖；端口跨重启稳定，
+手机里的地址不用改）。只想本机访问加 --local（绑 127.0.0.1:0）。
+局域网模式下令牌是唯一门锁，至少 24 字符；start 会复用 ~/.magic-client/token，跨重启稳定
 （手机里存的是「地址 + 令牌」，每次换就等于配对作废）。
 
 serve 的 flags 见 ` + "`magic-client serve --help`" + `；start 另有 --state / --log / --wait。
@@ -87,13 +91,14 @@ serve 的 flags 见 ` + "`magic-client serve --help`" + `；start 另有 --state
 
 func runClientStart(args []string) int {
 	fs := newFlagSet("start")
-	lan := fs.Bool("lan", false, "绑到局域网（0.0.0.0），让手机 / 平板连得上。⚠️ 开了之后令牌是唯一门锁")
-	addr := fs.String("addr", "", "监听地址（默认：带 --lan 时 0.0.0.0:0，否则 127.0.0.1:0）")
+	lan := fs.Bool("lan", true, "绑到局域网（默认 0.0.0.0:9100），让手机 / 平板连得上。⚠️ 令牌是唯一门锁")
+	localOnly := fs.Bool("local", false, "只绑 127.0.0.1（关闭默认的局域网监听，手机连不上）")
+	addr := fs.String("addr", "", "监听地址（默认 0.0.0.0:9100；带 --local 时 127.0.0.1:0）")
 	profilePath := fs.String("profile", "", "profile JSON 路径（空 = 内置默认）")
 	uiDir := fs.String("ui-dir", "", "桌面端界面目录（空 = 自动找与本程序同级的 client-ui）")
 	mobileDir := fs.String("mobile-dir", "", "移动端界面目录（空 = 自动找同级的 client-ui-mobile），/m/ 由它提供")
 	proxyAddr := fs.String("proxy-addr", "", "SOCKS5 出口监听地址（移动端 VPN 隧道核心用），如 0.0.0.0:1080")
-	token := fs.String("token", "", "访问令牌（空 = 复用 ~/.magic-client/token，没有就生成；--lan 时至少 24 字符）")
+	token := fs.String("token", "", "访问令牌（空 = 复用 ~/.magic-client/token，没有就生成；局域网模式至少 24 字符）")
 	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json；也可用 MAGIC_CLIENT_STATE）")
 	logPath := fs.String("log", "", "后台日志路径（默认 ~/.magic-client/logs/client.log；也可用 MAGIC_CLIENT_LOG）")
 	wait := fs.Duration("wait", 15*time.Second, "等后台服务报端口的时长（超时即判定启动失败）")
@@ -115,7 +120,7 @@ func runClientStart(args []string) int {
 		Token:      *token,
 		ProxyAddr:  *proxyAddr,
 		BrowseUA:   *browseUA,
-		Lan:        *lan,
+		Lan:        *lan && !*localOnly,
 		StatePath:  *statePath,
 		LogPath:    *logPath,
 		Wait:       *wait,
@@ -131,9 +136,18 @@ func runClientStart(args []string) int {
 func runClientStop(args []string) int {
 	fs := newFlagSet("stop")
 	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json）")
+	profilePath := fs.String("profile", "", "profile JSON 路径（决定单实例锁在哪个数据目录；空 = 内置默认）")
 	_ = fs.Parse(args)
 
-	stopped, st, err := client.StopDaemon(client.StopOptions{StatePath: *statePath})
+	/* AlsoLockHolder：前台 serve 起的实例、以及旧版（*.stale）起的实例都不写状态文件，
+	   只读状态文件的 stop 会答「本来就没在跑」，而端口与隧道实际还占着 —— 用户此时
+	   唯一的自救途径就是这条。DataDir / AppID 决定去查哪两处登记。 */
+	stopped, st, err := client.StopDaemon(client.StopOptions{
+		StatePath:      *statePath,
+		AlsoLockHolder: true,
+		DataDir:        dataDirOf(*profilePath),
+		AppID:          appIDOf(*profilePath),
+	})
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "magic-client:", err)
 		return 1
@@ -149,6 +163,51 @@ func runClientStop(args []string) int {
 	return 0
 }
 
+// runClientRestart 按**当前实例自己的参数**重启：停旧 → 起新（见 client.RestartDaemon）。
+//
+// 参数全部来自状态文件，所以这里只接 --state 与 --delay：
+// 手机点「重启服务」时由服务端 spawn 本动作，--delay 给那次 HTTP 响应留落地时间。
+func runClientRestart(args []string) int {
+	fs := newFlagSet("restart")
+	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json）")
+	profilePath := fs.String("profile", "", "profile JSON 路径（决定单实例锁在哪个数据目录；空 = 内置默认）")
+	delay := fs.Duration("delay", 0, "停旧实例前等多久（服务端自重启用，给响应留时间）")
+	_ = fs.Parse(args)
+
+	st, err := client.RestartDaemon(client.RestartOptions{
+		StatePath: *statePath,
+		Delay:     *delay,
+		DataDir:   dataDirOf(*profilePath),
+	})
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "magic-client:", err)
+		return 1
+	}
+	printStarted(st)
+	return 0
+}
+
+// dataDirOf 按 profile 算数据目录（单实例锁的位置由它决定）。
+//
+// 读不到 profile 就返回空串 —— 调用方会回落到「从状态文件目录推」的老行为，
+// 不能因为 profile 路径写错就让 `stop` 变成「什么都不做」。
+func dataDirOf(profilePath string) string {
+	prof, err := client.LoadProfile(profilePath)
+	if err != nil {
+		return ""
+	}
+	return prof.DataDir()
+}
+
+// appIDOf 按 profile 算 AppID（AppID 级占用登记的位置由它决定）。
+func appIDOf(profilePath string) string {
+	prof, err := client.LoadProfile(profilePath)
+	if err != nil {
+		return ""
+	}
+	return prof.AppID()
+}
+
 func runClientStatus(args []string) int {
 	fs := newFlagSet("status")
 	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json）")
@@ -181,7 +240,7 @@ func printStarted(st *client.DaemonState) {
 	fmt.Printf("  本机     %s\n", st.URL)
 	switch {
 	case len(st.LanAddrs) == 0:
-		fmt.Println("  局域网   （本次只绑了 127.0.0.1，手机连不上；要手机连请加 --lan）")
+		fmt.Println("  局域网   （本次用了 --local，只绑 127.0.0.1；去掉 --local 重启即可让手机连）")
 	default:
 		for _, u := range st.LanAddrs {
 			fmt.Printf("  手机     %s\n", u)
@@ -214,7 +273,7 @@ func printStatus(st *client.DaemonStatus) {
 		fmt.Printf("  手机     %s\n", u)
 	}
 	if len(s.LanAddrs) == 0 {
-		fmt.Println("  局域网   （未绑局域网，手机连不上）")
+		fmt.Println("  局域网   （未绑局域网，本次用了 --local）")
 	}
 	if st.Health != nil {
 		fmt.Printf("  应用     %s｜契约 v%d｜引擎 %d 个\n",