magic-agent 2.4.3 → 2.6.3

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 (
@@ -30,6 +31,7 @@ import (
 	"time"
 
 	"github.com/darren/magic-agent/internal/client"
+	"github.com/darren/magic-agent/internal/config"
 )
 
 func main() {
@@ -38,8 +40,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,15 +59,22 @@ 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 头（默认只放行本机页面）。局域网模式自动开启；令牌仍是唯一门锁")
+		/* 前台 serve 自登记（2026-10-26）：
+		   `POST /desk/restart` 需要知道「这台实例是怎么起的」，否则手机点重启只能 409。
+		   `magic-client start` 起的实例一直有 client.json 可读；前台 serve（magic-test 的
+		   桥接就是这种）过去什么都不写，于是按钮永远点不动。 */
+		statePath = fs.String("state", "", "把本实例的启动参数登记到这个状态文件（空 = <数据目录>/serve.json）。重启接口靠它认领自己")
+		hostPID   = fs.Int("host-pid", 0, "托管本服务的父进程 pid（桌面壳）。它退出后本服务跟着退出，避免重启后留下孤儿占端口")
 	)
 	_ = fs.Parse(os.Args[2:])
 
@@ -71,30 +83,100 @@ func main() {
 		fmt.Fprintln(os.Stderr, "magic-client:", err)
 		os.Exit(1)
 	}
+
+	/* 单实例互斥（2026-10-26 用户：「同时只启动1个」）。
+	 *
+	 * 位置：紧跟 LoadProfile（要 profile 才能算出 AppID 与数据目录），**早于
+	 * client.New / net.Listen**，原因是：
+	 *   · client.New 会跑 `magic-agent --contract`（20s 超时）并建起作业队列，
+	 *     那一步已经会去碰共用的 <DataDir>/jobs 与状态文件。晚于它就等于
+	 *     「先动了手再问有没有别人」；
+	 *   · 晚于 net.Listen 的话，第二份实例的报错会变成「端口被占用」—— 那是在描述
+	 *     症状不是原因（端口撞了只是这份目录上已有一份在跑的结果）；
+	 *   · --addr 各不相同的话，端口探测根本发现不了对方，但两份照样各跑一套作业
+	 *     队列去抢同一批工作区 —— 手机连着 A、任务在 B 里跑完，界面空回复。
+	 *
+	 * 两道闸门（缺一不可，见 singleinstance.go 的长注释）：
+	 *   ① AppID 登记：同一应用**换了数据目录**也不算两份不同应用；
+	 *   ② DataDir 锁：同一个目录上只能有一份。
+	 * 只做 ② 会漏掉「同一次部署被算出两个数据目录」这种漂移（本机真有：
+	 * magic-test 既有 ~/.magic-test 又有 ~/.magic-client/magic-test）。
+	 *
+	 * 只跳过 --print-url（脚本探活用的，它连服务都不起，不该占锁）。 */
+	var instLock *client.SingleInstanceLock
+	if !*printURL {
+		lk, holder, which, lerr := client.AcquireInstanceLocks(prof.AppID(), prof.DataDir(), 0)
+		if lerr != nil {
+			fmt.Fprintln(os.Stderr, "magic-client:", lerr)
+			os.Exit(1)
+		}
+		if lk == nil {
+			if which == "appid" {
+				fmt.Fprintln(os.Stderr, "magic-client:", client.AppIDConflictMessage(prof.AppID(), holder))
+			} else {
+				fmt.Fprintln(os.Stderr, "magic-client:", client.SingleInstanceConflictMessage(holder))
+			}
+			os.Exit(3)
+		}
+		instLock = lk
+		defer instLock.Release()
+	}
+
+	// 局域网是默认行为（手机开箱能连）；--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
+	}
+
 	tok := strings.TrimSpace(*token)
 	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)
 		}
 	}
+	/* 飞书推送凭据（2026-10-26）：config.json 的 feishu 节 / MAGIC_AGENT_FEISHU_APP_ID|SECRET。
+	   读不到配置文件不算错 —— 没配就是没开推送，界面里会提示去填（见 internal/client/feishu.go）。 */
+	feishuCfg, _ := config.Load()
+	/* 本实例的自登记路径，**在 New 之前**就算出来：Service 要靠它「认领自己」
+	   （手机点重启时 selfDaemonState 按这条路找回状态，见 coreupgrade.go）。
+	   空串不可能 —— prof 一定有数据目录；真没有就退回 <数据目录>/serve.json 的约定。 */
+	selfStatePath := strings.TrimSpace(*statePath)
+	if selfStatePath == "" {
+		selfStatePath = client.SelfStatePath(prof.DataDir())
+	}
 	svc, err := client.New(client.Options{
-		MagicAgent: *magicAgent,
-		Profile:    prof,
-		UIRoot:     *uiDir,
-		MobileRoot: *mobileDir,
-		Token:      tok,
-		Lan:        *lan,
-		BrowseUA:   *browseUA,
-		/* 绑到局域网 = 「允许来自任意 IP 的页面访问」：再按 loopback 卡 CORS Origin
+		MagicAgent:      *magicAgent,
+		FeishuAppID:     feishuCfg.Feishu.AppID,
+		FeishuAppSecret: feishuCfg.Feishu.AppSecret,
+		Profile:         prof,
+		UIRoot:          *uiDir,
+		MobileRoot:      *mobileDir,
+		Token:           tok,
+		Lan:             lanEnabled,
+		BrowseUA:        *browseUA,
+		/* 局域网 = 「允许来自任意 IP 的页面访问」：再按 loopback 卡 CORS Origin
 		   等于把手机 / 别的设备的页面全判成跨域（用户侧就是「只能本地访问」）。
 		   显式 --allow-any-origin 也可以单独打开（绑回环但要给容器页面用）。 */
-		AllowAnyOrigin: *anyOrigin || *lan,
+		AllowAnyOrigin: *anyOrigin || lanEnabled,
+		/* 前台 serve 自登记的落点：重启接口靠它认领本进程（见 daemon.go 的 SelfStateName）。 */
+		SelfStatePath: selfStatePath,
+		/* 托管父进程：重启之后的实例是 detach 的，壳退出杀不到它。
+		   记下来交给服务自己盯（见 service.go 的 WatchHost）。 */
+		HostPID: *hostPID,
 	})
 	if err != nil {
 		// 契约不匹配是**要立刻停**的错误：带着不匹配的能力跑起来只会让人以为是界面 bug。
@@ -102,23 +184,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 +213,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 +244,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 +260,7 @@ func main() {
 			Port:      port,
 			Addr:      ln.Addr().String(),
 			URL:       url,
-			Lan:       *lan,
+			Lan:       lanEnabled,
 			LanAddrs:  lanURLs,
 			ProxyAddr: proxyActual,
 		}); err != nil {
@@ -190,10 +270,94 @@ func main() {
 		}
 	}
 
+	/* 自登记（2026-10-26 用户：「通过 magic-test 启动的无法在移动端点击重启服务重启」）。
+	 *
+	 * 手机「重启服务」＝ POST /desk/restart。它要做的第一件事是「确认我说的是本进程、
+	 * 并且知道当初是怎么把我起来的」—— 重启助手要照这份参数停旧起新。`magic-client start`
+	 * 起的实例一直有 client.json；前台 serve（magic-test 桥接、手工调试都是这种）过去
+	 * 什么都不写，于是 409「当前实例不是后台启动的」，按钮永远点不动。
+	 *
+	 * 记到 <数据目录>/serve.json（**不是** client.json：那份是 start 的唯一实例记录，
+	 * 详见 daemon.go 的 SelfStateName）。带 HostPID 是为了重启出来的 detach 实例还能
+	 * 跟着壳一起退（见 svc.WatchHost）。
+	 *
+	 * 顺序：**监听成功之后**。写早了会把一个还没 Serve 的端口登记出去，手机拿着它去
+	 * 探活／重启都会撞空。
+	 *
+	 * ⚠️ `magic-client start` 拉起的 serve **不登记**（ready 文件就是它那条路的标志）：
+	 *    那条路已经有 client.json（信息更全：LogPath / 幂等判据都在里面），再写一份
+	 *    serve.json 会让 selfDaemonState 先认领到这份**信息更少**的登记 —— 重启后
+	 *    日志位置丢了、`stop` 的幂等判据也没了。两条启动路径各登记各的，不交叉。 */
+	/* 无论走哪条启动路径，只要知道「我那份登记在哪」，退出就清理（下面 defer）。
+	 *
+	 * 为什么 start 路径也要清：重启出来的实例不是被 `stop` 停掉的，而是 WatchHost
+	 * 发现宿主没了、自己 srv.Close() 收摊 —— 那条路上没有任何人删登记，留着就是一个
+	 * 指向死 pid 的陈旧文件（实测：serve.json 残留在 35444 这个已退出的 pid 上）。
+	 * RemoveSelfState 带 pid 校验，新实例已经接管时不会误删它的。
+	 *
+	 * 但**写**登记只有前台 serve 才做：start 路径的 client.json 由 StartDaemon 写
+	 *（它信息更全，含日志位置），serve 再写一遍等于用一份更少的覆盖它。 */
+	if !*printURL && selfStatePath != "" {
+		defer client.RemoveSelfState(selfStatePath)
+	}
+	if !*printURL && strings.TrimSpace(*readyFile) == "" {
+		lanURLs := make([]string, 0, len(lanAddrs))
+		for _, a := range lanAddrs {
+			lanURLs = append(lanURLs, fmt.Sprintf("http://%s/?token=%s", a, tok))
+		}
+		/* Exe 必须是**本进程自己的可执行文件**：重启助手照它拉新实例
+		   （RestartDaemon → StartDaemon 的 Exe）。记空的话新实例会退回
+		   「当前进程自己」，而助手是另一个进程 —— 那就成了拉起助手自己。 */
+		exePath, _ := os.Executable()
+		p, werr := client.WriteSelfStateAt(selfStatePath, prof.DataDir(), &client.DaemonState{
+			PID:        os.Getpid(),
+			Port:       port,
+			URL:        url,
+			LanAddrs:   lanURLs,
+			Lan:        lanEnabled,
+			Profile:    *profilePath,
+			UIRoot:     *uiDir,
+			MobileDir:  *mobileDir,
+			ProxyAddr:  proxyActual,
+			Token:      tok,
+			StartedAt:  time.Now(),
+			LogPath:    "",
+			Exe:        exePath,
+			Addr:       strings.TrimSpace(*addr),
+			BrowseUA:   *browseUA,
+			MagicAgent: *magicAgent,
+			AnyOrigin:  *anyOrigin,
+			HostPID:    *hostPID,
+		})
+		if werr != nil {
+			/* 登记失败不致命：服务照常能用，只是手机点重启会 409。
+			   绝不因此退出 —— 那等于「为了一个按钮把服务弄挂」。 */
+			fmt.Fprintf(os.Stderr, "magic-client: 警告 - 没能登记本实例状态（%v）：手机端「重启服务」会不可用\n", werr)
+		} else {
+			fmt.Fprintf(os.Stderr, "magic-client: 实例状态 %s（手机可一键重启本实例）\n", p)
+		}
+	}
+
+	/* 飞书启动通知（2026-10-26 用户：「重新启动后如果绑定了飞书 触发一下发送访问地址」）：
+	   重启是手机最容易失联的时刻（换网 / 换端口 / 隧道换域名），飞书是唯一不依赖那条
+	   连接的通道。没绑定 / 关了推送时 NotifyStartup 直接返回，不发任何请求；它在后台
+	   等隧道、可能试几十秒，不能挡住 Serve。局域网入口传进去，没有公网时拿它兜底。 */
+	startupEntry := ""
+	if len(lanAddrs) > 0 {
+		startupEntry = fmt.Sprintf("http://%s/?token=%s", lanAddrs[0], tok)
+	}
+	go svc.NotifyStartup(startupEntry)
+
 	srv := &http.Server{
 		Handler:           svc.Handler(),
 		ReadHeaderTimeout: 10 * time.Second,
 	}
+	/* 托管父进程没了就收摊（见 service.go 的 WatchHost）。
+	   只在重启链路里才有意义：重启出来的实例是 detach 的，壳的 r.stop() 杀不到它，
+	   没有这一条就会留下孤儿占着端口与单实例锁，下次开壳「插件启动即退出」。 */
+	svc.WatchHost(func() {
+		_ = srv.Close()
+	})
 	go func() {
 		stop := make(chan os.Signal, 1)
 		signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
@@ -214,3 +378,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)