magic-agent 2.4.3 → 2.6.3

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")`），父进程只能事后读日志正则 ——
@@ -28,6 +29,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 
@@ -41,6 +43,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 留余量。
@@ -51,6 +60,48 @@ const (
 	probeTimeout = 1500 * time.Millisecond
 )
 
+/* SelfStateName 前台 `serve` 自己登记的那份状态文件名（落在 profile 的 DataDir 下）。
+ *
+ * ── 为什么前台 serve 也要落状态（2026-10-26 用户：「通过 magic-test 启动的无法在移动端
+ *    点击重启服务重启」）──
+ * `POST /desk/restart` 原本只认 `magic-client start` 写的那份 client.json，前台 serve
+ * 什么都不写，于是手机点重启一律 409「当前实例不是后台启动的」。可是 magic-test 的桥接
+ * （desktop/magic-client-bridge.cjs）正是用 `spawn(bin, ['serve', ...])` 起的实例 ——
+ * 用户手机上连的就是它，按钮却永远点不动。
+ *
+ * 修法不是把前台硬改成后台（那会丢掉「壳退出即服务退出」的托管语义），而是让 serve
+ * **如实登记自己是谁、怎么起的**：重启助手照这份记录停旧起新即可。
+ *
+ * ⚠️ 必须是**另一个文件名**，不能复用 client.json：那份是 `start` 的唯一实例记录，
+ *    两者混写会出现「start 起的实例被前台 serve 的登记覆盖」——重启时按它重建参数，
+ *    就会用一个根本不是 start 参数拼出来的命令行去起新实例。 */
+const SelfStateName = "serve.json"
+
+// SelfStatePath 前台 serve 的状态文件路径：<profile 数据目录>/serve.json。
+//
+// 按 DataDir 分而不是按 ~/.magic-client 分，理由与单实例锁一致：同机可能同时跑着
+// 好几个不同应用（magic-test 的 8977、magic-agent 自己的 9100），数据目录不同、
+// 令牌不同，各登记各的，谁也认领不到谁。
+func SelfStatePath(dataDir string) string {
+	d := strings.TrimSpace(expandHome(dataDir))
+	if d == "" {
+		return ""
+	}
+	return filepath.Join(d, SelfStateName)
+}
+
+// HostAlive 托管父进程是否还在（pid <= 0 = 没人托管，恒 true）。
+//
+// 重启后的新实例是 detach 出去的（不然它会被旧实例的退出带走），但它的「主人」仍然是
+// 拉起这台服务的桌面壳：壳退出了服务就该跟着退，否则会留下一个孤儿占着端口与单实例锁，
+// 下次开壳直接「插件启动即退出」。见 service.go 的 WatchHost。
+func HostAlive(pid int) bool {
+	if pid <= 0 {
+		return true
+	}
+	return agent.PIDAlive(pid)
+}
+
 // DefaultStatePath 状态文件默认位置：~/.magic-client/client.json。
 func DefaultStatePath() string {
 	if p := strings.TrimSpace(os.Getenv(EnvState)); p != "" {
@@ -164,6 +215,23 @@ 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"`
+	// AnyOrigin serve 那次是否对任意 Origin 回 CORS 头（`--allow-any-origin` 或 `--lan`）。
+	// 重启 / 升级后原地拉起时要原样带上，否则升级完手机页面突然跨域失败。
+	AnyOrigin bool `json:"anyOrigin,omitempty"`
+	/* HostPID 托管这台服务的父进程（桌面壳 / 测试宿主）。
+	 *
+	 * 2026-10-26 加：重启后的新实例必须 detach（否则旧实例退出会把它一起带走），可
+	 * detach 之后它就不在壳的进程组里了 —— 壳退出时 `r.stop()` 杀不到它，留下一个
+	 * 孤儿占着端口与单实例锁，下次开壳就是「插件启动即退出」。
+	 * 所以把「主人是谁」记下来，由服务自己盯着：主人没了就优雅退出（见 WatchHost）。
+	 * 0 = 没人托管（`magic-client start` 起的常驻实例），不盯。 */
+	HostPID int `json:"hostPid,omitempty"`
 }
 
 // Base 本机根地址（不带令牌）。
@@ -190,6 +258,60 @@ func writeDaemonState(path string, st *DaemonState) error {
 	return os.Rename(tmp, path)
 }
 
+// WriteSelfState 前台 `serve` 监听成功后，把自己是谁、怎么起的登记下来。
+//
+// 与 writeDaemonState 同一套落盘规则（0600 原子写），但**写到 serve.json**，
+// 绝不碰 `start` 独占的 client.json（理由见 SelfStateName）。
+//
+// 记的东西要和 `start` 那份一样全 —— 重启助手会拿它当**唯一的启动参数来源**重建
+// 命令行（RestartDaemon → StartDaemon），少记一项新实例就会少一个 flag：
+// 少了 Profile ⇒ 数据目录/业务模块全变；少了 Token ⇒ 手机里存的地址立刻作废；
+// 少了 Addr ⇒ 换端口，手机再也连不上。
+//
+// 返回路径，调用方负责在退出时删掉（见 RemoveSelfState）。
+func WriteSelfState(dataDir string, st *DaemonState) (string, error) {
+	return WriteSelfStateAt("", dataDir, st)
+}
+
+// WriteSelfStateAt 同上，但允许显式指定完整路径（`--state`）。
+// explicit 空 → 用 dataDir 推出来的 SelfStatePath。
+func WriteSelfStateAt(explicit, dataDir string, st *DaemonState) (string, error) {
+	path := strings.TrimSpace(expandHome(explicit))
+	if path == "" {
+		path = SelfStatePath(dataDir)
+	}
+	if path == "" {
+		return "", fmt.Errorf("没有数据目录：无法登记前台实例状态")
+	}
+	if st == nil {
+		return "", fmt.Errorf("状态为空")
+	}
+	if st.PID == 0 {
+		st.PID = os.Getpid()
+	}
+	// 状态文件自己那份路径要记对：重启助手按它找回来（见 selfDaemonState）。
+	st.StatePath = path
+	if err := writeDaemonState(path, st); err != nil {
+		return "", err
+	}
+	return path, nil
+}
+
+// RemoveSelfState 退出时删掉自己那份登记。
+//
+// 只删「pid 还是我」的那份：重启链路里旧实例退出时，新实例可能**已经**登记好了
+// （它先监听成功才轮到我们收尾），这时删掉就等于把新实例弄成"没有状态"的孤儿 ——
+// 手机再点重启又变成 409。判断错了会留下陈旧登记，但那比删掉活人的准。
+func RemoveSelfState(path string) {
+	if strings.TrimSpace(path) == "" {
+		return
+	}
+	if st, err := ReadDaemonState(path); err == nil && st != nil && st.PID != os.Getpid() {
+		return // 已经不是我的了（新实例接管），别动
+	}
+	_ = os.Remove(path)
+}
+
 // ReadDaemonState 读状态文件：不存在 → (nil, nil)。
 func ReadDaemonState(path string) (*DaemonState, error) {
 	if strings.TrimSpace(path) == "" {
@@ -299,6 +421,12 @@ type StartOptions struct {
 	Token     string
 	ProxyAddr string
 	BrowseUA  string
+	/* AnyOrigin 新实例要不要对任意 Origin 回 CORS 头。由 `restart` / 升级后重启按状态
+	   文件原样带回（`--lan` 时 create 自己也会开，这里不重复造条件，只是别丢）。 */
+	AnyOrigin bool
+	/* HostPID 托管父进程（见 DaemonState.HostPID）。0 = 没人托管。
+	   `restart` 按状态文件原样带回，于是重启出来的新实例继续盯着同一个主人。 */
+	HostPID   int
 	Lan       bool
 	StatePath string
 	LogPath   string
@@ -368,6 +496,14 @@ func StartDaemon(o StartOptions) (*DaemonState, error) {
 	defer logf.Close()
 
 	args := []string{"serve", "--ready-file", readyPath, "--token", tok}
+	/* --state（2026-10-26）：告诉子进程「哪份状态文件是你自己的」。
+	   两个用处，缺一不可：
+	     · 退出时清理 —— 重启出来的实例由 WatchHost 收摊（宿主退出），它不走 StopDaemon，
+	       没人删这份登记，留着就是一个指向死 pid 的陈旧文件；
+	     · 认领自己 —— selfDaemonState 按这条路径找回参数，重启/升级才能落到自己身上。
+	   不传的话子进程只知道 ready 文件，对「我那份登记在哪」一无所知（实测：重启后
+	   serve.json 残留 pid 已死的旧记录）。 */
+	args = append(args, "--state", statePath)
 	appendIf := func(flag, v string) {
 		if v = strings.TrimSpace(v); v != "" {
 			args = append(args, flag, v)
@@ -380,8 +516,17 @@ func StartDaemon(o StartOptions) (*DaemonState, error) {
 	appendIf("--proxy-addr", o.ProxyAddr)
 	appendIf("--browse-ua", o.BrowseUA)
 	appendIf("--magic-agent", o.MagicAgent)
+	if o.AnyOrigin {
+		args = append(args, "--allow-any-origin")
+	}
+	if o.HostPID > 0 {
+		args = append(args, "--host-pid", strconv.Itoa(o.HostPID))
+	}
 	if o.Lan {
 		args = append(args, "--lan")
+	} else {
+		// serve 的默认已改为局域网；显式传 --local 才能关掉。
+		args = append(args, "--local")
 	}
 
 	cmd := exec.Command(exe, args...)
@@ -422,20 +567,25 @@ 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,
+		AnyOrigin:  o.AnyOrigin,
+		HostPID:    o.HostPID,
 	}
 	if st.PID == 0 {
 		st.PID = cmd.Process.Pid
@@ -449,6 +599,40 @@ func StartDaemon(o StartOptions) (*DaemonState, error) {
 // StopOptions `stop` 的参数。
 type StopOptions struct {
 	StatePath string
+	/* AlsoLockHolder（2026-10-26）：状态文件里没有 / 指向的进程已死时，再按**单实例锁**
+	   里记的 pid 试一次。
+
+	   为什么必须有这一步：`magic-client serve`（前台）与旧版（不认锁、可执行文件已变成
+	   *.stale 的那些）都**不写状态文件**，于是 `stop` 只读状态文件就永远「本来就没在跑」，
+	   而 8977 / 54428 上实实在在还有两个进程占着隧道 —— 用户此刻正是这个现场：
+	   手机连着旧的、新版起不来、`stop` 又停不掉，只能手工 kill。
+
+	   `restart` 不传这个（它必须严格按状态文件重建参数，顺手停掉一个前台实例会把
+	   用户手上的调试会话一起干掉）。 */
+	AlsoLockHolder bool
+	/* DataDir（2026-10-26）：单实例锁的位置。空 → 从状态文件所在目录推（老调用方行为）。
+	   与 profile 同源 —— 锁是按数据目录分的，不知道是哪份目录就不知道该停谁。 */
+	DataDir string
+	/* AppID（2026-10-26）：AppID 级占用登记的位置。有了它才能停掉「同一应用换了
+	   数据目录在跑」的那一份 —— 那种情况下 DataDir 锁查不到它（在另一个目录）。 */
+	AppID string
+}
+
+// stopPID 发 SIGTERM，等 stopGrace，还在就 SIGKILL。返回是否真的停了。
+func stopPID(pid int) bool {
+	if !agent.PIDAlive(pid) {
+		return false
+	}
+	_ = agent.TerminatePID(pid, false)
+	deadline := time.Now().Add(stopGrace)
+	for time.Now().Before(deadline) {
+		if !agent.PIDAlive(pid) {
+			return true
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	_ = agent.KillPID(pid, false)
+	return true
 }
 
 // StopDaemon 停掉后台实例。
@@ -464,26 +648,106 @@ func StopDaemon(o StopOptions) (bool, *DaemonState, error) {
 	if err != nil {
 		return false, nil, err
 	}
-	if st == nil {
-		return false, nil, nil
+	if st == nil || !agent.PIDAlive(st.PID) {
+		if st != nil {
+			_ = os.Remove(statePath)
+		}
+		/* 状态文件这条路走不通：还有一份不写状态文件的实例（前台 serve / 旧版 .stale）
+		   占着锁的话，用户唯一的自救方式就是它。停掉并清锁 —— 不清的话下一次启动
+		   会因为「锁的持有者已死」走回收路径，虽然也能起来，但日志里会多一段困惑。 */
+		if o.AlsoLockHolder {
+			/* 两条路都要查：先按数据目录（最常见），再按 AppID 登记（治「同一应用
+			   换了目录在跑」—— 那一份的 DataDir 锁根本不在我们要找的目录里）。 */
+			type lockTarget struct{ path string }
+			var targets []lockTarget
+			if p := DefaultLockPath(o.DataDir); p != "" {
+				targets = append(targets, lockTarget{p})
+			}
+			if p := appIDLockPath(o.AppID); p != "" && p != DefaultLockPath(o.DataDir) {
+				targets = append(targets, lockTarget{p})
+			}
+			for _, t := range targets {
+				h := ReadSingleInstanceHolder(t.path)
+				if h == nil || h.PID == os.Getpid() || !stopPID(h.PID) {
+					continue
+				}
+				_ = os.Remove(t.path)
+				// 顺手把它的锁也清掉：不清的话它那个目录下次启动会撞「持有者已死」。
+				if h.DataDir != "" {
+					_ = os.Remove(DefaultLockPath(h.DataDir))
+				}
+				return true, &DaemonState{
+					PID: h.PID, Port: h.Port, Exe: h.Exe,
+				}, nil
+			}
+		}
+		if st == nil {
+			return false, nil, nil
+		}
+		return false, st, nil
 	}
-	if !agent.PIDAlive(st.PID) {
+	if stopPID(st.PID) {
 		_ = os.Remove(statePath)
-		return false, st, nil
+		return true, st, nil
 	}
-	// SIGTERM 先礼：serve 收到后会 srv.Close()，正在跑的请求有机会收尾。
-	_ = agent.TerminatePID(st.PID, false)
-	deadline := time.Now().Add(stopGrace)
-	for time.Now().Before(deadline) {
-		if !agent.PIDAlive(st.PID) {
-			_ = os.Remove(statePath)
-			return true, st, nil
-		}
-		time.Sleep(50 * time.Millisecond)
+	return false, st, nil
+}
+
+// RestartOptions `restart` 的参数。
+type RestartOptions struct {
+	StatePath string
+	// Delay 停旧实例之前等多久。服务端「自重启」用它先把 HTTP 响应写回手机
+	// （响应一发完，本进程就会在 Delay 之后被 TerminatePID 带走）。
+	Delay time.Duration
+	// DataDir 该实例的数据目录（决定单实例锁的位置）。
+	DataDir string
+}
+
+// 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, DataDir: o.DataDir}); err != nil {
+		return nil, err
 	}
-	_ = agent.KillPID(st.PID, false)
-	_ = os.Remove(statePath)
-	return true, st, nil
+	/* 旧进程退出到端口真正释放之间还有一小段窗口（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,
+		AnyOrigin:  prev.AnyOrigin,
+		HostPID:    prev.HostPID,
+		Lan:        prev.Lan,
+		StatePath:  statePath,
+		LogPath:    prev.LogPath,
+	})
 }
 
 // DaemonStatus 一份对外可读的运行状态（给 `status` 与排障用）。

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