magic-agent 2.4.3 → 2.6.0

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)
+	}
+}

package/internal/client/corecmd.go

@@ -0,0 +1,23 @@
+package client
+
+import (
+	"context"
+	"os/exec"
+)
+
+// newCoreCmd 起一条 core 子进程（插件侧唯一入口）。
+//
+// 为什么统一走这里（2026-10-24 用户：「返回会话列表很忙，需求很快」）：
+// `magic-client start` 把服务以 **DETACHED_PROCESS** 放到后台（见 detach_windows.go），
+// 那个进程**没有控制台**。此后它每 spawn 一次 core（`--sessions` / `--contract` /
+// `--requirements` / 归纳标题 / 真开跑），Windows 都要为这个控制台程序新建一个
+// conhost —— 实测每次多花 **3.1 秒**（前台 serve 260ms，后台 3.4s，同一台机器、
+// 同一个 core 二进制）。手机上就是「进出会话列表很忙」、发任务起步慢。
+//
+// 加 CREATE_NO_WINDOW 之后子进程不再分配控制台：stdin/stdout 管道照常工作，
+// 只是没有那个看不见的窗口。
+func newCoreCmd(ctx context.Context, exe string, args ...string) *exec.Cmd {
+	cmd := exec.CommandContext(ctx, exe, args...)
+	noConsole(cmd)
+	return cmd
+}

package/internal/client/corecmd_other.go

@@ -0,0 +1,8 @@
+//go:build !windows
+
+package client
+
+import "os/exec"
+
+// noConsole 非 Windows 平台无需处理（没有「控制台分配」这回事）。
+func noConsole(cmd *exec.Cmd) {}

package/internal/client/corecmd_windows.go

@@ -0,0 +1,24 @@
+//go:build windows
+
+package client
+
+import (
+	"os/exec"
+	"syscall"
+)
+
+// createNoWindow 不分配控制台窗口（CreationFlags）。
+// 后台服务（DETACHED_PROCESS）本身没有控制台，子进程每起一次都要新建 conhost —— 实测 3.1s。
+const createNoWindow = 0x08000000
+
+// noConsole 给 core 子进程关掉控制台分配（保留调用方可能设过的其它标志）。
+func noConsole(cmd *exec.Cmd) {
+	if cmd == nil {
+		return
+	}
+	if cmd.SysProcAttr == nil {
+		cmd.SysProcAttr = &syscall.SysProcAttr{}
+	}
+	cmd.SysProcAttr.CreationFlags |= createNoWindow
+	cmd.SysProcAttr.HideWindow = true
+}

package/internal/client/daemon.go

@@ -3,11 +3,12 @@ package client
 /* 后台常驻（`magic-client start|stop|status`）的落地层。
  *
  * ── 为什么需要这一层 ──
- * 手机的连接入口是「一个还在跑的 serve 进程 + 它的端口 + 令牌」。手工 `serve --lan`
- * 是**前台**进程：关掉终端就没了；而端口是 0（系统分配），下次启动又是另一个端口 ——
- * 用户既记不住，也没法把它抄进手机。所以这里把
+ * 手机的连接入口是「一个还在跑的 serve 进程 + 它的端口 + 令牌」。手工 `serve`
+ * 是**前台**进程：关掉终端就没了；所以这里把
  * 「pid + 端口 + 令牌 + 局域网地址」落成一份 0600 的状态文件，
  * start / status / stop 三个动作围绕同一份事实工作，谁也不再猜。
+ * 端口本身也稳了：默认（局域网）未显式给 --addr 时固定绑 DefaultLanAddr（9100）——
+ * 手机里存的是「地址 + 令牌」，端口一变配对就作废。
  *
  * ── 为什么由 serve 自己写 ready 文件，而不是父进程猜端口 ──
  * 端口在 bind 之后才知道（`net.Listen("tcp","0.0.0.0:0")`），父进程只能事后读日志正则 ——
@@ -41,6 +42,13 @@ const (
 	EnvLog = "MAGIC_CLIENT_LOG"
 )
 
+// DefaultLanAddr 默认（局域网）且未显式给 --addr 时的监听地址：固定 9100。
+//
+// 为什么不用 :0 随机：手机里存的是「地址 + 令牌」，端口一变配对就作废，
+// 用户侧现象是「每次重启都得重新配对」。固定端口的代价是可能被占用 ——
+// 那就让 serve 明确报错（--addr 换一个），绝不悄悄换回随机端口骗人。
+const DefaultLanAddr = "0.0.0.0:9100"
+
 const (
 	// defaultReadyWait 等 serve 报端口的时长。第一次启动要跑 `--contract` 探测引擎，
 	// 慢机器上 3~5s 很常见，给到 15s 留余量。
@@ -164,6 +172,12 @@ type DaemonState struct {
 	LogPath   string    `json:"logPath"`
 	StatePath string    `json:"statePath"`
 	Exe       string    `json:"exe"`
+	/* 以下三个是 `restart` 重建启动参数用的（2026-10-24，移动端「我的 → 重启服务」）。
+	   只增字段：老状态文件没有它们 → 空串，重启时各走自己的默认（地址按 Lan 推、UA 内置、
+	   core 从 PATH 找），行为与旧版 start 一致。 */
+	Addr       string `json:"addr,omitempty"`
+	BrowseUA   string `json:"browseUA,omitempty"`
+	MagicAgent string `json:"magicAgent,omitempty"`
 }
 
 // Base 本机根地址（不带令牌）。
@@ -382,6 +396,9 @@ func StartDaemon(o StartOptions) (*DaemonState, error) {
 	appendIf("--magic-agent", o.MagicAgent)
 	if o.Lan {
 		args = append(args, "--lan")
+	} else {
+		// serve 的默认已改为局域网；显式传 --local 才能关掉。
+		args = append(args, "--local")
 	}
 
 	cmd := exec.Command(exe, args...)
@@ -422,20 +439,23 @@ func StartDaemon(o StartOptions) (*DaemonState, error) {
 	_ = os.Remove(readyPath)
 
 	st := &DaemonState{
-		PID:       info.PID,
-		Port:      info.Port,
-		URL:       info.URL,
-		LanAddrs:  info.LanAddrs,
-		Lan:       info.Lan,
-		Profile:   o.Profile,
-		UIRoot:    o.UIRoot,
-		MobileDir: o.MobileDir,
-		ProxyAddr: info.ProxyAddr,
-		Token:     tok,
-		StartedAt: time.Now(),
-		LogPath:   logPath,
-		StatePath: statePath,
-		Exe:       exe,
+		PID:        info.PID,
+		Port:       info.Port,
+		URL:        info.URL,
+		LanAddrs:   info.LanAddrs,
+		Lan:        info.Lan,
+		Profile:    o.Profile,
+		UIRoot:     o.UIRoot,
+		MobileDir:  o.MobileDir,
+		ProxyAddr:  info.ProxyAddr,
+		Token:      tok,
+		StartedAt:  time.Now(),
+		LogPath:    logPath,
+		StatePath:  statePath,
+		Exe:        exe,
+		Addr:       o.Addr,
+		BrowseUA:   o.BrowseUA,
+		MagicAgent: o.MagicAgent,
 	}
 	if st.PID == 0 {
 		st.PID = cmd.Process.Pid
@@ -486,6 +506,59 @@ func StopDaemon(o StopOptions) (bool, *DaemonState, error) {
 	return true, st, nil
 }
 
+// RestartOptions `restart` 的参数。
+type RestartOptions struct {
+	StatePath string
+	// Delay 停旧实例之前等多久。服务端「自重启」用它先把 HTTP 响应写回手机
+	// （响应一发完，本进程就会在 Delay 之后被 TerminatePID 带走）。
+	Delay time.Duration
+}
+
+// RestartDaemon 按**当前实例自己的启动参数**重启：读状态文件 → 停旧实例 → 拉起新实例。
+//
+// 为什么参数要从状态文件重建（2026-10-24，移动端「我的」里加了「重启服务」）：
+// 发起重启的是手机，它只知道「连着的那个实例」，不知道这台机器当初是怎么起来的
+// （端口、令牌、界面目录、profile、SOCKS5…）。状态文件里都记着，照着起即可 ——
+// 令牌沿用，手机里存的「地址 + 令牌」不会因为重启作废。
+//
+// 只能用于后台实例（`magic-client start`）：前台 `serve` 不写状态文件，无从得知参数。
+func RestartDaemon(o RestartOptions) (*DaemonState, error) {
+	statePath := strings.TrimSpace(o.StatePath)
+	if statePath == "" {
+		statePath = DefaultStatePath()
+	}
+	prev, err := ReadDaemonState(statePath)
+	if err != nil {
+		return nil, err
+	}
+	if prev == nil {
+		return nil, fmt.Errorf("没有后台实例的状态文件（%s）：重启只支持 `magic-client start` 起的实例", statePath)
+	}
+	if o.Delay > 0 {
+		time.Sleep(o.Delay)
+	}
+	if _, _, err := StopDaemon(StopOptions{StatePath: statePath}); err != nil {
+		return nil, err
+	}
+	/* 旧进程退出到端口真正释放之间还有一小段窗口（Windows 上关句柄不是瞬时），
+	   不等这一下，新实例会立刻撞「地址已在使用」—— 也就是手机上那句「重启后连不上」。 */
+	time.Sleep(300 * time.Millisecond)
+	return StartDaemon(StartOptions{
+		Exe:        prev.Exe,
+		MagicAgent: prev.MagicAgent,
+		Profile:    prev.Profile,
+		UIRoot:     prev.UIRoot,
+		MobileDir:  prev.MobileDir,
+		Addr:       prev.Addr,
+		Token:      prev.Token,
+		ProxyAddr:  prev.ProxyAddr,
+		BrowseUA:   prev.BrowseUA,
+		Lan:        prev.Lan,
+		StatePath:  statePath,
+		LogPath:    prev.LogPath,
+	})
+}
+
 // DaemonStatus 一份对外可读的运行状态（给 `status` 与排障用）。
 type DaemonStatus struct {
 	Running bool         `json:"running"`

package/internal/client/daemon_test.go

@@ -9,6 +9,8 @@ package client
 //  3) status 的判据是「进程在 **且** 健康检查答得上」，不是只看 pid。
 
 import (
+	"io"
+	"log"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -198,6 +200,37 @@ func TestStopClearsStaleState(t *testing.T) {
 	}
 }
 
+// RestartDaemon 没有状态文件时必须在**停任何东西之前**失败：前台 serve 起的实例没有这份
+// 文件，参数无从重建；硬重启会把「不知道参数」变成「先把服务停掉再报错」。
+func TestRestartDaemonNeedsStateFile(t *testing.T) {
+	_, err := RestartDaemon(RestartOptions{StatePath: filepath.Join(t.TempDir(), "nope.json")})
+	if err == nil {
+		t.Fatal("没有状态文件时应当报错（不能猜参数、也不能先停实例）")
+	}
+	if !strings.Contains(err.Error(), "状态文件") {
+		t.Errorf("错误信息要能落地（说明缺的是状态文件）：%v", err)
+	}
+}
+
+// POST /desk/restart 的两道闸：只收 POST；状态文件不指向本进程时 409。
+// 后者是安全阀 —— 同机可能跑着两个实例，照着别人的状态文件重启会重启**别人**。
+func TestHandleRestartGuards(t *testing.T) {
+	t.Setenv(EnvState, filepath.Join(t.TempDir(), "client.json"))
+	s := &Service{log: log.New(io.Discard, "", 0)}
+
+	rec := httptest.NewRecorder()
+	s.handleRestart(rec, httptest.NewRequest(http.MethodGet, "/desk/restart", nil))
+	if rec.Code != http.StatusMethodNotAllowed {
+		t.Errorf("GET 的状态码 = %d，want 405", rec.Code)
+	}
+
+	rec = httptest.NewRecorder()
+	s.handleRestart(rec, httptest.NewRequest(http.MethodPost, "/desk/restart", nil))
+	if rec.Code != http.StatusConflict {
+		t.Errorf("没有指向本进程的状态文件时 = %d，want 409（不许乱重启）", rec.Code)
+	}
+}
+
 func portOf(t *testing.T, rawURL string) int {
 	t.Helper()
 	i := strings.LastIndex(rawURL, ":")

package/internal/client/engines_checkin_test.go

@@ -0,0 +1,57 @@
+package client
+
+// engines_checkin_test.go - 领取积分后同步引擎清单兜底缓存（避免重开弹层又显示「领取」）。
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestPatchEnginesCacheAfterCheckin(t *testing.T) {
+	home := t.TempDir()
+	// Windows 上 os.UserHomeDir() 读 USERPROFILE，只设 HOME 隔离不住真机路径。
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+
+	p, err := enginesCachePath()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	before := `[{"engine":"codebuddy","ok":true,"checkin_today":false,"checkin_credit":"100","credit_left":"5830.7"},` +
+		`{"engine":"trae","ok":true}]`
+	if err := os.WriteFile(p, []byte(before), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	// 业务失败（今天已签）也要把状态翻成已领；余额沿用旧值。
+	patchEnginesCacheAfterCheckin([]byte(`{"engine":"codebuddy","ok":false,"checked_today":true,"message":"今天已签到"}`))
+
+	raw, err := os.ReadFile(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var rows []map[string]any
+	if err := json.Unmarshal(raw, &rows); err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 2 {
+		t.Fatalf("rows = %d, want 2", len(rows))
+	}
+	if rows[0]["checkin_today"] != true {
+		t.Errorf("checkin_today = %v, want true", rows[0]["checkin_today"])
+	}
+	if rows[0]["checkin_credit"] != "" {
+		t.Errorf("checkin_credit = %v, want 空串", rows[0]["checkin_credit"])
+	}
+	if rows[0]["credit_left"] != "5830.7" {
+		t.Errorf("credit_left 应保留旧值，实际 %v", rows[0]["credit_left"])
+	}
+	if rows[1]["engine"] != "trae" {
+		t.Errorf("其他引擎行不应被改动：%v", rows[1])
+	}
+}

package/internal/client/fallback_flags_test.go

@@ -0,0 +1,64 @@
+package client
+
+// fallback_flags_test.go - 主备（2026-10-24）在插件侧的翻译：
+// /desk/ask 的 fallbackEngine / fallbackModel 必须变成 core 的 --fallback-engine / --fallback-model。
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestPrepareAskFallbackFlags(t *testing.T) {
+	svc := &Service{opts: Options{Profile: DefaultProfile()}}
+	_, args, st, err := svc.prepareAsk(askRequest{
+		Engine:         "claude",
+		Prompt:         "hi",
+		FallbackEngine: "codebuddy",
+		FallbackModel:  "hy3",
+	})
+	if err != nil {
+		t.Fatalf("prepareAsk: %v (status=%d)", err, st)
+	}
+	joined := strings.Join(args, " ")
+	if !strings.Contains(joined, "--fallback-engine codebuddy") {
+		t.Fatalf("备用引擎没透传：%v", args)
+	}
+	if !strings.Contains(joined, "--fallback-model hy3") {
+		t.Fatalf("备用模型没透传：%v", args)
+	}
+}
+
+func TestPrepareAskFallbackWhitelist(t *testing.T) {
+	prof := DefaultProfile()
+	prof.Engines = []string{"claude"}
+	svc := &Service{opts: Options{Profile: prof}}
+	_, _, st, err := svc.prepareAsk(askRequest{
+		Engine:         "claude",
+		Prompt:         "hi",
+		FallbackEngine: "codebuddy",
+	})
+	if err == nil || st != http.StatusForbidden {
+		t.Fatalf("备用引擎不在白名单时应 403，得到 st=%d err=%v", st, err)
+	}
+}
+
+func TestJobAskRequestKeepsFallback(t *testing.T) {
+	// 作业会落盘并在真正开跑时还原：备用配置必须跟着 Job 走，
+	// 否则「直接提交能降级、排队后不能」。
+	req := (&Job{Engine: "dsh", Prompt: "hi", FallbackEngine: "codebuddy", FallbackModel: "hy3"}).askRequest()
+	if req.FallbackEngine != "codebuddy" || req.FallbackModel != "hy3" {
+		t.Fatalf("作业还原丢了备用：%+v", req)
+	}
+}
+
+func TestPrepareAskFallbackIgnoredWhenEmpty(t *testing.T) {
+	svc := &Service{opts: Options{Profile: DefaultProfile()}}
+	_, args, _, err := svc.prepareAsk(askRequest{Engine: "claude", Prompt: "hi"})
+	if err != nil {
+		t.Fatalf("prepareAsk: %v", err)
+	}
+	if strings.Contains(strings.Join(args, " "), "--fallback") {
+		t.Fatalf("没配备用不该下发 fallback 参数：%v", args)
+	}
+}