magic-agent 2.4.3 → 2.6.0

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,
@@ -149,6 +154,25 @@ 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）")
+	delay := fs.Duration("delay", 0, "停旧实例前等多久（服务端自重启用，给响应留时间）")
+	_ = fs.Parse(args)
+
+	st, err := client.RestartDaemon(client.RestartOptions{StatePath: *statePath, Delay: *delay})
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "magic-client:", err)
+		return 1
+	}
+	printStarted(st)
+	return 0
+}
+
 func runClientStatus(args []string) int {
 	fs := newFlagSet("status")
 	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json）")
@@ -181,7 +205,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 +238,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",

package/cmd/magic-client/main.go

@@ -9,11 +9,12 @@
 //
 //	magic-client serve --profile ./profiles/zhantianping.json --ui-dir ./client-ui
 //	magic-client serve --print-url          # 只打印带令牌的地址，不启动（脚本用）
-//	magic-client start --lan                # 后台常驻（关掉终端也还在），手机可连
+//	magic-client start                      # 后台常驻（关掉终端也还在），默认手机可连
+//	magic-client start --local              # 只绑 127.0.0.1（不给局域网）
 //	magic-client status | stop              # 看状态 / 停掉后台实例
 //
-// 默认**只绑 127.0.0.1**，并需要 X-Magic-Token：同机任意进程都能访问本地端口，
-// 不开鉴权等于把引擎执行权交给它们。
+// 默认绑 0.0.0.0:9100（手机可直接连），并强制 X-Magic-Token：
+// 局域网内令牌是唯一门锁；只想本机访问时加 --local。
 package main
 
 import (
@@ -38,8 +39,11 @@ func main() {
 		os.Exit(2)
 	}
 	switch os.Args[1] {
-	case "start", "stop", "status":
+	case "start", "stop", "status", "restart":
 		os.Exit(runClientCommandWithExit(os.Args[1], os.Args[2:]))
+	case "browse":
+		// 浏览器输入驱动端（见 browsectl.go），不落 serve 流程
+		os.Exit(runBrowseDriver(os.Args[2:]))
 	case "serve":
 		// 落下去走下面的前台流程
 	case "-h", "--help", "help":
@@ -54,18 +58,33 @@ func main() {
 		profilePath = fs.String("profile", "", "profile JSON 路径（空 = 内置默认）")
 		uiDir       = fs.String("ui-dir", "", "静态资源目录（基础版 UI 与业务模块）")
 		mobileDir   = fs.String("mobile-dir", "", "移动端界面目录（client-ui-mobile）。配了之后 /m/ 远程提供它，APK 壳可远程加载、改界面免重打")
-		addr        = fs.String("addr", "", "监听地址（默认 127.0.0.1:0；带 --lan 时是 0.0.0.0:0）")
-		lan         = fs.Bool("lan", false, "绑到局域网（0.0.0.0），让手机 / 平板连得上。⚠️ 开了之后令牌是唯一门锁")
-		token       = fs.String("token", "", "访问令牌（空 = 随机生成并打印；--lan 时至少要 24 个字符）")
+		addr        = fs.String("addr", "", "监听地址（默认 0.0.0.0:9100，手机可连；带 --local 时 127.0.0.1:0）")
+		lan         = fs.Bool("lan", true, "绑到局域网（默认 0.0.0.0:9100），让手机 / 平板连得上。⚠️ 令牌是唯一门锁")
+		localOnly   = fs.Bool("local", false, "只绑 127.0.0.1（关闭默认的局域网监听，手机连不上）")
+		token       = fs.String("token", "", "访问令牌（空 = 随机生成并打印；局域网模式下至少要 24 个字符）")
 		magicAgent  = fs.String("magic-agent", os.Getenv("MAGIC_AGENT_BIN"), "core 可执行文件（空 = 从 PATH 找 magic-agent）")
 		printURL    = fs.Bool("print-url", false, "只打印带令牌的访问地址后退出（不启动服务）")
 		proxyAddr   = fs.String("proxy-addr", "", "SOCKS5 出口监听地址（供移动端 VPN 隧道核心使用），如 0.0.0.0:1080")
 		browseUA    = fs.String("browse-ua", "", "内置浏览器中转的 User-Agent：mobile（默认）/ desktop / 任意自定义串")
 		readyFile   = fs.String("ready-file", "", "监听成功后把 {pid,port,url,lanAddrs} 原子写到这个路径（`magic-client start` 用它拿端口，别手工传）")
-		anyOrigin   = fs.Bool("allow-any-origin", false, "对任意 Origin 回 CORS 头（默认只放行本机页面）。--lan 时自动开启；令牌仍是唯一门锁")
+		anyOrigin   = fs.Bool("allow-any-origin", false, "对任意 Origin 回 CORS 头（默认只放行本机页面）。局域网模式自动开启；令牌仍是唯一门锁")
 	)
 	_ = fs.Parse(os.Args[2:])
 
+	// 局域网是默认行为（手机开箱能连）；--local 或显式回环地址回到「只给本机」。
+	lanEnabled := *lan && !*localOnly
+	listenAddr := strings.TrimSpace(*addr)
+	if listenAddr == "" {
+		if lanEnabled {
+			listenAddr = client.DefaultLanAddr
+		} else {
+			listenAddr = "127.0.0.1:0"
+		}
+	}
+	if lanEnabled && isLoopbackListenAddr(listenAddr) {
+		lanEnabled = false
+	}
+
 	prof, err := client.LoadProfile(*profilePath)
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "magic-client:", err)
@@ -75,9 +94,9 @@ func main() {
 	if tok == "" {
 		tok = randToken() // 16 字节 = 32 位十六进制，远强于局域网那条线
 	}
-	/* 绑到局域网时令牌是**唯一**门锁：内网能被扫到，短令牌等于没有。
+	/* 局域网模式下令牌是**唯一**门锁：内网能被扫到，短令牌等于没有。
 	   默认生成的那个够强，所以这条只在用户显式给了弱令牌时报错。 */
-	if *lan {
+	if lanEnabled {
 		if err := client.ValidateLanToken(tok); err != nil {
 			fmt.Fprintln(os.Stderr, "magic-client:", err)
 			os.Exit(2)
@@ -89,12 +108,12 @@ func main() {
 		UIRoot:     *uiDir,
 		MobileRoot: *mobileDir,
 		Token:      tok,
-		Lan:        *lan,
+		Lan:        lanEnabled,
 		BrowseUA:   *browseUA,
-		/* 绑到局域网 = 「允许来自任意 IP 的页面访问」：再按 loopback 卡 CORS Origin
+		/* 局域网 = 「允许来自任意 IP 的页面访问」：再按 loopback 卡 CORS Origin
 		   等于把手机 / 别的设备的页面全判成跨域（用户侧就是「只能本地访问」）。
 		   显式 --allow-any-origin 也可以单独打开（绑回环但要给容器页面用）。 */
-		AllowAnyOrigin: *anyOrigin || *lan,
+		AllowAnyOrigin: *anyOrigin || lanEnabled,
 	})
 	if err != nil {
 		// 契约不匹配是**要立刻停**的错误：带着不匹配的能力跑起来只会让人以为是界面 bug。
@@ -102,23 +121,21 @@ func main() {
 		os.Exit(1)
 	}
 
-	listenAddr := strings.TrimSpace(*addr)
-	if listenAddr == "" {
-		if *lan {
-			listenAddr = "0.0.0.0:0"
-		} else {
-			listenAddr = "127.0.0.1:0"
-		}
-	}
 	ln, err := net.Listen("tcp", listenAddr)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, "magic-client: 监听失败:", err)
+		// 固定默认端口是新引入的失败形态（被占用），给一句能落地的指引；
+		// 显式 --addr 的失败照旧只报错 —— 用户自己选的地址不需要教学。
+		if listenAddr == client.DefaultLanAddr && strings.TrimSpace(*addr) == "" {
+			fmt.Fprintf(os.Stderr, "magic-client: 监听失败: %v（%s 被占用？先 magic-client stop，或用 --addr 换个端口）\n", err, listenAddr)
+		} else {
+			fmt.Fprintf(os.Stderr, "magic-client: 监听失败: %v\n", err)
+		}
 		os.Exit(1)
 	}
 	port := ln.Addr().(*net.TCPAddr).Port
 	url := fmt.Sprintf("http://127.0.0.1:%d/?token=%s", port, tok)
 	if *printURL {
-		// 只打印本机地址：脚本拿它做探活，局域网地址在 --lan 下另有输出。
+		// 只打印本机地址：脚本拿它做探活，局域网地址在局域网模式下另有输出。
 		fmt.Println(url)
 		_ = ln.Close()
 		return
@@ -133,7 +150,7 @@ func main() {
 	}
 	fmt.Fprintf(os.Stderr, "magic-client: 接口 /desk/{health,contract,engines,modules,sessions,profile,suggest,asks,ask,ask/{id}/control} + 业务转发 /api/*（都要 X-Magic-Token）\n")
 	var lanAddrs []string
-	if *lan {
+	if lanEnabled {
 		// 绑到局域网就把可用地址全打出来：一台机器常有多个网卡，猜错比多打两行麻烦。
 		fmt.Fprintln(os.Stderr, "magic-client: ⚠️ 已绑到局域网（0.0.0.0）：同网络内的设备都能访问，令牌是唯一门锁")
 		lanAddrs = client.LanAddresses(port)
@@ -164,7 +181,7 @@ func main() {
 		}()
 		proxyActual = pln.Addr().String()
 		fmt.Fprintf(os.Stderr, "magic-client: SOCKS5 出口 %s（用户名随意，口令 = 令牌）\n", proxyActual)
-	} else if *lan {
+	} else if lanEnabled {
 		fmt.Fprintln(os.Stderr, "magic-client: 未开 SOCKS5 出口（移动端隧道需要它：加 --proxy-addr 0.0.0.0:1080）")
 	}
 
@@ -180,7 +197,7 @@ func main() {
 			Port:      port,
 			Addr:      ln.Addr().String(),
 			URL:       url,
-			Lan:       *lan,
+			Lan:       lanEnabled,
 			LanAddrs:  lanURLs,
 			ProxyAddr: proxyActual,
 		}); err != nil {
@@ -214,3 +231,17 @@ func randToken() string {
 	}
 	return hex.EncodeToString(b)
 }
+
+// isLoopbackListenAddr 判断监听地址是否只绑回环（127.0.0.1 / localhost / ::1）。
+// 空 host（":9100"）= 所有网卡，不算回环。
+func isLoopbackListenAddr(addr string) bool {
+	host, _, err := net.SplitHostPort(addr)
+	if err != nil || host == "" {
+		return false
+	}
+	if strings.EqualFold(host, "localhost") {
+		return true
+	}
+	ip := net.ParseIP(host)
+	return ip != nil && ip.IsLoopback()
+}

package/internal/agent/ask.go

@@ -360,6 +360,27 @@ func EncodeAskAnswer(engine string, req *AskRequest, ans AskAnswer) ([]byte, err
 		return nil, fmt.Errorf("ask: engine %q has no known ask-answer protocol shape", engine)
 	}
 
+	/* codebuddy / codebuddy-ai 的权限应答形状与 claude SDK 不同（2026-10-25 抓包 + 读包内代码核实）：
+	   CLI 的 SdkPermissionClient.handleResponse 只认
+	       {"allowed":true} / {"allowed":false,"reason":"…"}
+	   传 claude 那套 {"behavior":"allow"} 会被解析成 allowed=false（整个表达式取不到 allowed），
+	   实测表现就是「发了 allow，CLI 回了『用户不想继续这个计划』的拒绝结果」。
+	   见 codebuddy-code dist/codebuddy.js 的 sdk_permission_client 段。 */
+	if req.Kind == AskKindPermission && askPermissionUsesAllowed(engine) {
+		out := map[string]any{"allowed": !ans.Denied}
+		if ans.Denied {
+			msg := ans.Message
+			if msg == "" {
+				msg = "User declined"
+			}
+			out["reason"] = msg
+			if ans.Interrupt && AskInterruptSupportOf(engine) {
+				out["interrupt"] = true
+			}
+		}
+		return json.Marshal(out)
+	}
+
 	if ans.Denied {
 		out := map[string]any{"behavior": "deny"}
 		msg := ans.Message
@@ -536,6 +557,30 @@ func askAnswerShapeKnown(engine string) bool {
 	return equalFold(engine, "claude") || equalFold(engine, "codebuddy") || equalFold(engine, "codebuddy-ai")
 }
 
+// AskAnswerControlOf 引擎是否支持「原地回审批」：宿主能通过 Request.Reply 往子进程 stdin
+// 写一行 control_response，把这一轮正阻塞等着的裁决交回去。
+//
+// 只有 stream-json 输入通道的引擎（claude / codebuddy / codebuddy-ai）有这条路；
+// 其余引擎要么没有控制协议，要么命令行侧根本没有 stdin 通道。
+func AskAnswerControlOf(engine string) bool {
+	engine = CapabilityFamilyOf(engine)
+	switch engine {
+	case "claude", "codebuddy", "codebuddy-ai":
+		return true
+	}
+	return false
+}
+
+// askPermissionUsesAllowed 权限应答是否用 codebuddy 的 `{"allowed":…}` 形状。
+//
+// claude SDK 的 can_use_tool 回调结果是 {"behavior":"allow"|"deny",…}；
+// 而 codebuddy CLI 的 SdkPermissionClient 只读 `allowed` / `reason` / `interrupt`（见
+// EncodeAskAnswer 里的实测注脚）。两者不能混用 —— 混了不报错，只会静默变成「拒绝」。
+func askPermissionUsesAllowed(engine string) bool {
+	engine = CapabilityFamilyOf(engine)
+	return equalFold(engine, "codebuddy") || equalFold(engine, "codebuddy-ai")
+}
+
 // AskInterruptSupportOf 拒绝时是否支持 interrupt（拒绝并中断整个会话）。
 //
 // 只有 codebuddy 的官方文档写了该字段；claude 的 SDK 文档只给 behavior/message，

package/internal/agent/ask_test.go

@@ -262,6 +262,45 @@ func TestEncodeAskAnswerPermissionKind(t *testing.T) {
 	}
 }
 
+// codebuddy 的权限应答是 `{"allowed":…}` 而不是 claude 的 `{"behavior":"allow"}`。
+// 2026-10-25 真机 + 读包内代码核实（codebuddy-code dist/codebuddy.js 的 SdkPermissionClient）：
+// 传 behavior 形状会被读成 allowed=false —— 表现是「发了允许，CLI 回一句用户不想继续」。
+func TestEncodeAskAnswerPermissionCodebuddy(t *testing.T) {
+	req, ok := ParseAskLine("codebuddy", askPermissionControlRequestDoc)
+	if !ok {
+		t.Fatal("素材没解析出来")
+	}
+	out, err := EncodeAskAnswer("codebuddy", req, AskAnswer{})
+	if err != nil {
+		t.Fatalf("渲染失败: %v", err)
+	}
+	var allow struct {
+		Allowed bool `json:"allowed"`
+	}
+	if err := json.Unmarshal(out, &allow); err != nil {
+		t.Fatalf("输出不是合法 JSON: %v", err)
+	}
+	if !allow.Allowed {
+		t.Errorf("codebuddy 放行必须是 {\"allowed\":true}: %s", out)
+	}
+
+	denyOut, err := EncodeAskAnswer("codebuddy", req, AskAnswer{Denied: true, Message: "先改改计划", Interrupt: true})
+	if err != nil {
+		t.Fatalf("拒绝渲染失败: %v", err)
+	}
+	var deny struct {
+		Allowed   bool   `json:"allowed"`
+		Reason    string `json:"reason"`
+		Interrupt bool   `json:"interrupt"`
+	}
+	if err := json.Unmarshal(denyOut, &deny); err != nil {
+		t.Fatalf("拒绝输出不是合法 JSON: %v", err)
+	}
+	if deny.Allowed || deny.Reason != "先改改计划" || !deny.Interrupt {
+		t.Errorf("codebuddy 拒绝形状不对: %s", denyOut)
+	}
+}
+
 func TestEncodeAskAnswerErrors(t *testing.T) {
 	dup := `{"type":"assistant","message":{"content":[{"type":"tool_use","id":"c","name":"AskUserQuestion","input":{"questions":[
 		{"question":"同一个问题？","header":"A","multiSelect":false,"options":[{"label":"是"},{"label":"否"}]},

package/internal/agent/attachments_test.go

@@ -421,8 +421,12 @@ func TestLLMCLIArgsUseAttachmentFlag(t *testing.T) {
 
 func TestTraePromptCarriesAttachmentPath(t *testing.T) {
 	img := writeTestPNG(t, "shot.png")
-	// 假 trae-cli：把收到的参数原样回显（纯文本输出）。
-	cli := writeFakeCLI(t, "trae-cli", "#!/bin/sh\necho \"$*\"\n")
+	// 假 traex：把收到的参数塞进 agent_message，走 2.0 的 JSONL 事件流回读。
+	cli := writeFakeCLI(t, "trae-cli", `#!/bin/sh
+printf '%s\n' '{"type":"thread.started","thread_id":"th-1"}'
+printf '{"type":"item.completed","item":{"id":"i","type":"agent_message","text":"%s"}}\n' "$*"
+printf '%s\n' '{"type":"turn.completed"}'
+`)
 	e := &TraeEngine{BinPath: cli}
 	res, err := e.Complete(context.Background(), Request{
 		Messages:    []Message{{Role: "user", Content: "看图"}},

package/internal/agent/capability.go

@@ -167,9 +167,15 @@ const (
 	// 客户端据此决定要不要显示「需求」页签：老版本 core 没有这个 feature，
 	// 界面必须把入口藏起来，而不是给一个点下去只会报错的按钮。
 	FeatureRequirements = "feature.requirements"
+	// FeatureRequirementShots `--requirement-shot`：给功能点追加「页面完成情况」截图。
+	//
+	// 与 FeatureRequirements 分开是因为它是**后加的**能力：core 支持需求聚合
+	// 但还不支持截图的版本存在（2026-10-25）。客户端要能分别判断 ——
+	// 老 core 上「需求」页签照常用，只是「截图」入口藏起来。
+	FeatureRequirementShots = "feature.requirement.shots"
 )
 
 // CoreFeatures 返回 core 自身提供的通道能力（字典序，稳定）。
 func CoreFeatures() []string {
-	return []string{FeatureRequirements, FeatureSessionControl, FeatureSessionEvents, FeatureSessionHosted, FeatureSessionTeam}
+	return []string{FeatureRequirementShots, FeatureRequirements, FeatureSessionControl, FeatureSessionEvents, FeatureSessionHosted, FeatureSessionTeam}
 }

package/internal/agent/claude.go

@@ -52,7 +52,6 @@ package agent
 import (
 	"context"
 	"fmt"
-	"io"
 	"os"
 	"path/filepath"
 	"strings"
@@ -288,22 +287,28 @@ func (e *ClaudeEngine) Stream(ctx context.Context, req Request, onEvent func(Str
 	//
 	// 常驻会话（Request.Append 非 nil）的区别只在 stdin 是个**流**：
 	// 追加消息源源不断写进去，通道关闭才 EOF（子进程随之收尾）。
-	var stdin io.Reader
-	if req.Append != nil {
-		pipe, perr := streamJSONInputPipe(prompt, req.Attachments, req.Append)
-		if perr != nil {
-			return StreamResult{}, perr
-		}
-		stdin = pipe
-	} else {
-		line, serr := streamJSONUserLine(prompt, req.Attachments)
-		if serr != nil {
-			return StreamResult{}, serr
-		}
-		stdin = strings.NewReader(line)
+	// Reply 非 nil（要回控制协议行）时同样是流：stdin 保持打开到本轮收尾，
+	// 否则 CLI 发出 control_request 时已经没有可写回的落点（见 Request.Reply）。
+	stdin, closeStdin, serr := streamJSONStdinFor(req, prompt)
+	if serr != nil {
+		return StreamResult{}, serr
 	}
+	defer closeStdin()
 	args := streamJSONArgs(e.buildArgsBase(req), prompt, true)
-	acc := &streamAccumulator{Engine: e.Name(), OnEvent: onEvent, OnSessionID: req.OnSessionID}
+	var acc *streamAccumulator
+	if onEvent == nil && req.Reply == nil {
+		acc = &streamAccumulator{Engine: e.Name(), OnSessionID: req.OnSessionID}
+	} else {
+		acc = &streamAccumulator{Engine: e.Name(), OnSessionID: req.OnSessionID,
+			OnEvent: func(ev StreamEvent) {
+				if streamTerminalKind(ev.Kind) {
+					closeStdin()
+				}
+				if onEvent != nil {
+					onEvent(ev)
+				}
+			}}
+	}
 	var fin streamJSONResult
 	var cliStderr streamStderrBuf
 	seen, err := runStreamJSONIn(ctx, req.Workspace, nil, bin, args, stdin, acc, &fin, &cliStderr)