magic-agent 1.0.111 → 2.3.0

package/internal/cli/suggest.go

@@ -0,0 +1,98 @@
+package cli
+
+// suggest.go - `--suggest-followups <file|->`：一轮结束后生成「用户下一句」的快捷回复。
+//
+// 为什么要单独一条 CLI（用户 2026-10-23：「在回复结束后 ai 自动生成下一轮的建议，
+// 点击即可发送」）：界面（移动端 / PC）不该自己拼提示词、自己调模型 —— 那样每端一份，
+// 同一轮回答在两处会给出不同建议。口径收进 core 之后只有一份（internal/suggest），
+// 客户端（magic-client 的 /desk/suggest）exec 这一条即可。
+//
+// 与 `--summarize-title` 同一套旁路调用：独立进程、新会话、ToolsOff，不续接当前对话，
+// 因此不会污染用户正在聊的那条上下文；也不写会话登记 / 日志（不经过 ask 主流程）。
+//
+// 退出码：
+//
+//	0  成功（哪怕建议为空数组 —— 「没有下一步」是合法结果，调用方不画按钮）
+//	1  引擎失败（不可用 / 超时 / 报错）
+//	2  参数错（请求 JSON 读不到 / 不合法 / 缺 reply）
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/darren/magic-agent/internal/suggest"
+)
+
+// runSuggestFollowups 读取请求 JSON → 调 suggest.Generate → 打印 JSON 结果。
+func runSuggestFollowups(cmd *cobra.Command, opts *askOptions) error {
+	body, err := readSuggestInput(cmd, opts.suggestInput)
+	if err != nil {
+		return &usageError{err}
+	}
+	/* 引擎：没显式传 -e 时用 llm（纯文本、无工具、没有 CLI 会话副作用，与 --title-engine 同口径）；
+	   传了就以调用方的为准 —— 移动端把当前引擎带下来，用户的机器上一定装过它。 */
+	engine := suggest.DefaultEngine
+	if flagChanged(cmd, "engine") {
+		engine = opts.engine
+	}
+	model := ""
+	if flagChanged(cmd, "model") {
+		model = opts.model
+	}
+	res, err := suggest.Generate(cmd.Context(), suggest.Request{
+		User:    body.User,
+		Reply:   body.Reply,
+		Engine:  engine,
+		Model:   model,
+		Timeout: suggest.DefaultTimeout,
+	})
+	if err != nil {
+		return fmt.Errorf("--suggest-followups: 生成失败: %w", err)
+	}
+	if res.Suggestions == nil {
+		res.Suggestions = []string{}
+	}
+	return printJSON(cmd.OutOrStdout(), res)
+}
+
+// readSuggestInput 读请求 JSON：`-` = stdin，其余按文件路径（支持 `@file` 写法）。
+// 上限 1MB：建议只该带「这一轮」的正文，超了说明调用方把整条会话塞进来了。
+func readSuggestInput(cmd *cobra.Command, spec string) (suggest.RequestBody, error) {
+	var body suggest.RequestBody
+	src := strings.TrimSpace(spec)
+	switch src {
+	case "":
+		return body, fmt.Errorf("--suggest-followups 需要请求 JSON：传文件路径或 \"-\"（stdin）")
+	case "-":
+		b, err := io.ReadAll(io.LimitReader(cmd.InOrStdin(), 1<<20))
+		if err != nil {
+			return body, fmt.Errorf("读 stdin 失败：%w", err)
+		}
+		if err := json.Unmarshal(b, &body); err != nil {
+			return body, fmt.Errorf("stdin 不是合法 JSON：%w", err)
+		}
+	default:
+		path := strings.TrimPrefix(src, "@")
+		if strings.HasPrefix(path, "~/") {
+			if home, herr := os.UserHomeDir(); herr == nil {
+				path = home + path[1:]
+			}
+		}
+		b, err := os.ReadFile(path)
+		if err != nil {
+			return body, fmt.Errorf("读请求文件失败：%w", err)
+		}
+		if err := json.Unmarshal(b, &body); err != nil {
+			return body, fmt.Errorf("请求文件不是合法 JSON：%w", err)
+		}
+	}
+	if strings.TrimSpace(body.Reply) == "" {
+		return body, fmt.Errorf(`请求 JSON 缺少 reply（本轮回答正文）：形如 {"user":"…","reply":"…"}`)
+	}
+	return body, nil
+}

package/internal/cli/suggest_test.go

@@ -0,0 +1,54 @@
+package cli
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/darren/magic-agent/internal/suggest"
+)
+
+// TestSuggestFollowupsJSON 走完整 CLI：读 stdin 的请求 JSON → 假引擎 → 输出建议。
+func TestSuggestFollowupsJSON(t *testing.T) {
+	registerFake(&stringEngine{
+		name: "fake-suggest-cli",
+		text: "这是建议：\n```json\n{\"suggestions\":[\"好的，执行吧\",\"先看一下 diff\"]}\n```",
+	})
+	body := `{"user":"改完了吗","reply":"要我继续吗？"}`
+	out, errOut, err := runAskCmd(t, body, "--suggest-followups", "-", "-e", "fake-suggest-cli")
+	if err != nil {
+		t.Fatalf("suggest: %v（stderr=%s）", err, errOut)
+	}
+	var res suggest.Result
+	if uerr := json.Unmarshal([]byte(out), &res); uerr != nil {
+		t.Fatalf("输出不是 JSON：%v\n%s", uerr, out)
+	}
+	if len(res.Suggestions) != 2 || res.Suggestions[0] != "好的，执行吧" {
+		t.Fatalf("Suggestions = %#v", res.Suggestions)
+	}
+	if res.Engine != "fake-suggest-cli" {
+		t.Fatalf("Engine = %q", res.Engine)
+	}
+}
+
+// TestSuggestFollowupsEmptyReply 没有 reply 是**参数错**，不能当成空建议静默成功。
+func TestSuggestFollowupsEmptyReply(t *testing.T) {
+	_, _, err := runAskCmd(t, `{"user":"只说了一句"}`, "--suggest-followups", "-", "-e", "fake-suggest-cli")
+	if err == nil {
+		t.Fatal("缺 reply 应报参数错")
+	}
+	if !strings.Contains(err.Error(), "reply") {
+		t.Fatalf("报错没说清缺什么：%v", err)
+	}
+}
+
+// TestSuggestFollowupsBadJSON 非法 JSON 也必须明确报错（exit 2 的语义）。
+func TestSuggestFollowupsBadJSON(t *testing.T) {
+	_, _, err := runAskCmd(t, `not json`, "--suggest-followups", "-", "-e", "fake-suggest-cli")
+	if err == nil {
+		t.Fatal("非法 JSON 应报参数错")
+	}
+	if _, ok := err.(*usageError); !ok {
+		t.Fatalf("应是 usageError（exit 2），实际 %T: %v", err, err)
+	}
+}

package/internal/cli/team.go

@@ -17,6 +17,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"strings"
+	"sync"
+	"time"
 
 	"github.com/spf13/cobra"
 
@@ -98,7 +100,50 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	// 事件出口：--no-thinking 只压思考。
 	// 团队模式下主会话只出现任务列表快照（KindTasks）与汇总，子任务的过程事件
 	// 走各自子会话的日志（见 team_session.go），不再带 parent 转发进来。
-	emit := func(ev agent.StreamEvent) {
+	//
+	// ⚠️ 登记表的「还活着」靠这里续期（2026-10-22 报障：「团队模式子任务还在跑 主会话
+	// 就说结束了」）。流式路径（ask.go）对**每条事件**都写一次状态，团队路径此前只在
+	// 开跑前写一次 running —— 计划 + 子任务几分钟里 updated_at 一动不动，网关的尾随
+	// 连接（followStateEvery=5s）据 terminalSessionState 判「这一轮已结束」，画面落
+	// 红点收尾行，而子任务进程其实还在跑。团队模式没有 turn_end 可依，所以任何**主会话
+	// 自己发出的事件**（计划、任务列表快照、心跳、汇总）都当成一次「还在跑」。
+	// （h 在下面才建：闭包定义在这里不带值，第一次调用在 beginSession 之后。）
+	var emit func(agent.StreamEvent)
+
+	ctx := cmd.Context()
+	if !opts.keepAlive || flagChanged(cmd, "timeout") {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, opts.timeout)
+		defer cancel()
+	}
+	// --control 的打断：取消 ctx → 在跑的子任务进程组一起收。
+	var cancelAll context.CancelFunc
+	if opts.control {
+		ctx, cancelAll = context.WithCancel(ctx)
+		defer cancelAll()
+	}
+
+	h := beginSession(engine.Name(), req, opts.saveRegistry)
+	/* 团队模式**不挂** spawn hook：登记表里的 pid 必须一直是 magic-agent 自己。
+	   团队路径会多次 spawn 主引擎（计划 / 汇总 / 补充规划），hook 会把 pid 换成
+	   这些**短命**子进程的 pid；第一个（计划阶段）一退，normalizeDead 见 pid 不在
+	   就判整条主会话 gone —— 而此刻子任务正在跑。真机复现：24 分钟的一轮里主会话
+	   在第 32 秒就被判死，直到收尾才写回 done。
+	   子引擎进程不靠这条登记收：它们各有自己的子会话记录（openSubSession），
+	   异常退出时由 orphanSubs 按进程组收。 */
+	_ = withSessionHook
+	if h != nil {
+		// 开跑前就标上：计划阶段可能几十秒，这期间列表里已经能看到这条会话了。
+		h.SetMode(session.ModeTeam)
+		h.Mark(session.StateRunning)
+	}
+	emit = func(ev agent.StreamEvent) {
+		h.Mark(session.StateRunning)
+		/* 续期（2026-10-22 真机复现）：Mark 在新旧状态相同时**不写盘**，所以上面那一句
+		   对「已经 running」的会话等于空操作 —— updated_at 从第一条事件起就冻住了，
+		   网关尾随连接据此判终态，画面在子任务还在跑时就落「这一轮已结束」。
+		   Touch 才是真正的续期；5 秒节流对齐网关的 followStateEvery。 */
+		h.Touch(5 * time.Second)
 		if ev.Kind == agent.KindThinking && opts.noThinking {
 			return
 		}
@@ -136,27 +181,6 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 			})
 		}
 	}
-
-	ctx := cmd.Context()
-	if !opts.keepAlive || flagChanged(cmd, "timeout") {
-		var cancel context.CancelFunc
-		ctx, cancel = context.WithTimeout(ctx, opts.timeout)
-		defer cancel()
-	}
-	// --control 的打断：取消 ctx → 在跑的子任务进程组一起收。
-	var cancelAll context.CancelFunc
-	if opts.control {
-		ctx, cancelAll = context.WithCancel(ctx)
-		defer cancelAll()
-	}
-
-	h := beginSession(engine.Name(), req, opts.saveRegistry)
-	ctx = withSessionHook(ctx, h)
-	if h != nil {
-		// 开跑前就标上：计划阶段可能几十秒，这期间列表里已经能看到这条会话了。
-		h.SetMode(session.ModeTeam)
-		h.Mark(session.StateRunning)
-	}
 	if sessionLog != nil && h != nil {
 		sessionLog.setRunID(h.RunID())
 	}
@@ -180,6 +204,10 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	if h != nil {
 		runID = h.RunID()
 	}
+	/* 本次运行开出来的子会话（按 pid 收进程组用，见 orphanSubs）。
+	   写它的是跑子任务的 goroutine，读的是异常退出那一支 —— 加锁。 */
+	var mu sync.Mutex
+	var subs []*subSession
 	res, err := team.Run(ctx, team.Options{
 		Engine:            engine,
 		Model:             req.Model,
@@ -204,13 +232,48 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 		PlanOnly:          opts.teamPlanOnly,
 		Adaptive:          opts.teamAdaptive,
 		// 每个子任务 = 一条普通会话：登记记录 + 自己的日志，父指针挂在本会话下。
+		//
+		// 开出来的子会话都记进 subs：父进程异常退出时要按它们的 pid 收进程组
+		// （见下面的 orphan sweep），否则主会话没了、子引擎还在跑，列表里挂一条永远
+		// running 的子会话。
 		OpenSubSession: func(t team.Task, runDir, engine, model string) team.SubSession {
-			return openSubSession(h, opts.saveRegistry, opts.saveHistory, stderr, t, runDir, engine, model)
+			s := openSubSession(h, opts.saveRegistry, opts.saveHistory, stderr, t, runDir, engine, model)
+			if ss, ok := s.(*subSession); ok && ss != nil {
+				mu.Lock()
+				subs = append(subs, ss)
+				mu.Unlock()
+			}
+			return s
 		},
 		OnEvent: emit,
+		// 计划阶段不发事件的续期（见 team.Options.OnTick）。
+		OnTick: func() { h.Touch(0) },
 	})
+	mu.Lock()
+	running := append([]*subSession(nil), subs...)
+	mu.Unlock()
 	if err != nil {
-		finishSession(h, "", session.StateFailed)
+		/* 异常退出也要有**终态**（2026-10-22）：团队模式没有 turn_end 可依，父进程失败时
+		   一条终态事件都不发 —— 客户端只能看登记表，而登记表停在 running，网关按「还在跑」
+		   一直等（或按内核被杀归一成 gone）。这里补一条 turn_failed：走的是流式路径
+		   同一条收尾口径（turn_failed → 画面一行「本轮异常收尾」），调用方不必再猜。 */
+		interrupted := ctx.Err() != nil
+		reason := ""
+		if interrupted {
+			reason = "已中断（主进程被取消或被杀）"
+		} else {
+			reason = err.Error()
+		}
+		emit(agent.StreamEvent{Kind: agent.KindTurnFailed, Text: reason, Reason: reason})
+		state := session.StateFailed
+		if interrupted {
+			state = session.StateInterrupted
+		}
+		finishSession(h, "", state)
+		/* 子引擎是独立进程组（子会话上下文里挂的 SpawnHook 按组登记 pid）：
+		   父这一轮已经作废，把还在跑的一起收掉 —— 否则会话列表里永远挂着一条 running
+		   的子会话，用户点进去只看到半截过程，而且它会一直烧额度。 */
+		orphanSubs(running)
 		if format == agent.FormatJSON {
 			_ = sink.event(streamErrorPayload(engine.Name(), err))
 			_ = agent.WriteError(stderr, format, engine.Name(), 1, err)
@@ -253,6 +316,30 @@ func runTeamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	return nil
 }
 
+// orphanSubs 收掉还没落定的子会话对应的子引擎进程组。
+//
+// 只在团队这一轮**异常退出**时调：正常收尾时每个子会话都在 runTask 的 end() 里
+// Finish 过（进程已经自己退了）。这里兜的是「父进程这一轮作废、子引擎还在跑」那条路
+// —— 不收就是孤儿进程：它一边烧额度，一边让会话列表里那条子会话永远 running。
+//
+// 幂等：进程已经不在（PIDAlive=false）就只补登记表状态，不再发信号。
+func orphanSubs(list []*subSession) {
+	for _, s := range list {
+		if s == nil {
+			continue
+		}
+		rec := s.h.Record()
+		if rec.PID > 0 && agent.PIDAlive(rec.PID) {
+			_ = agent.KillPID(rec.PID, rec.KillGroup)
+		}
+		s.h.Finish(rec.SessionID, session.StateInterrupted)
+		if s.log != nil {
+			s.log.close()
+			s.log = nil
+		}
+	}
+}
+
 // agentRefs 把子任务结果按「类别 + 引擎 + 模型」归并成登记表里的 Agents。
 //
 // 为什么按类别归并而不是一个任务一条：登记表是列表页的数据源，一个 6 任务的团队会话

package/internal/client/apk.go

@@ -0,0 +1,135 @@
+package client
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// 移动端 APK 的分发（2026-10-22，用户：「移动端版本跟着 npm 走」+「在版本号的地方
+// 可以显示版本也可检测最新版本号并触发升级」）。
+//
+// 版本号只有一个来源：npm 包里的 package.json。构建时 magic-test 的
+// tools/build-mobile-apk.cjs 把同一个版本写进 APK 的 versionName，并把 release 包放到
+// npm/apk/ 下随包发布。本插件负责把它通过局域网递给手机：
+//
+//	GET /desk/app     -> {version, size, url}（手机「我的」→「版本」点一下先问这个）
+//	GET /desk/app.apk -> 真正的安装包（浏览器/系统下载器用 ?token= 过鉴权）
+//
+// 为什么由桌面端发：手机和桌面已经配对、这条路一定通；不依赖 GitHub Release / 应用市场，
+// 也不需要把 7MB 的 APK 塞进每个平台的 npm 二进制目录。
+
+// apkManifest 与 npm/apk/version.json 对应，由 magic-test 的打包脚本生成。
+type apkManifest struct {
+	Version     string `json:"version"`
+	VersionCode int    `json:"versionCode"`
+}
+
+// findBundledAPK 从可执行文件所在目录向上找 npm/apk/magic-agent-mobile-release.apk。
+//
+// 两种布局都要能命中：
+//   - 开发态：<repo>/bin/magic-client          → <repo>/npm/apk/...
+//   - npm 全局：<pkg>/npm/dist/<os>-<arch>/magic-client → <pkg>/npm/apk/...
+//
+// 不写死层级：向上最多找 6 层，遇到根就停。cwd 也找一遍 —— 开发时从别的目录启动、
+// 但包目录在 cwd 下面时仍能命中。
+func findBundledAPK() string {
+	const rel = "npm/apk/magic-agent-mobile-release.apk"
+	var roots []string
+	addAncestors := func(start string) {
+		dir, err := filepath.Abs(start)
+		if err != nil {
+			return
+		}
+		for i := 0; i < 6; i++ {
+			roots = append(roots, dir)
+			parent := filepath.Dir(dir)
+			if parent == dir {
+				break
+			}
+			dir = parent
+		}
+	}
+	if exe, err := os.Executable(); err == nil {
+		if real, err := filepath.EvalSymlinks(exe); err == nil {
+			exe = real
+		}
+		addAncestors(filepath.Dir(exe))
+	}
+	if wd, err := os.Getwd(); err == nil {
+		addAncestors(wd)
+	}
+	for _, root := range roots {
+		p := filepath.Join(root, filepath.FromSlash(rel))
+		if st, err := os.Stat(p); err == nil && st.Mode().IsRegular() {
+			return p
+		}
+	}
+	return ""
+}
+
+// apkVersion 读 version.json；缺失时从文件名兜底（magic-agent-mobile-<ver>-release.apk）。
+func apkVersion(path string) string {
+	b, err := os.ReadFile(filepath.Join(filepath.Dir(path), "version.json"))
+	if err == nil {
+		var m apkManifest
+		if json.Unmarshal(b, &m) == nil && strings.TrimSpace(m.Version) != "" {
+			return strings.TrimSpace(m.Version)
+		}
+	}
+	name := filepath.Base(path)
+	name = strings.TrimSuffix(name, ".apk")
+	name = strings.TrimPrefix(name, "magic-agent-mobile-")
+	name = strings.TrimSuffix(name, "-release")
+	if name != "" && name != filepath.Base(path) {
+		return name
+	}
+	return ""
+}
+
+func (s *Service) apkAvailable() bool {
+	if s.apkPath == "" {
+		return false
+	}
+	st, err := os.Stat(s.apkPath)
+	return err == nil && st.Mode().IsRegular()
+}
+
+// handleAppInfo GET /desk/app：告诉手机「桌面端这份 npm 包里带的 APK 是哪一版」。
+// 没带 APK 时也回 200 + 空 version —— 手机据此说「暂无可安装包」，而不是把 404 当网络错误。
+func (s *Service) handleAppInfo(w http.ResponseWriter, r *http.Request) {
+	out := struct {
+		Version string `json:"version"`
+		Size    int64  `json:"size"`
+		URL     string `json:"url"`
+	}{}
+	if s.apkAvailable() {
+		if st, err := os.Stat(s.apkPath); err == nil {
+			out.Version = apkVersion(s.apkPath)
+			out.Size = st.Size()
+			out.URL = "/desk/app.apk"
+		}
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+// handleAppAPK GET /desk/app.apk：把包里的 APK 原样送出去。
+// token 可以走查询参数 —— 系统浏览器/下载器带不了 X-Magic-Token，guard 已经支持 ?token=。
+func (s *Service) handleAppAPK(w http.ResponseWriter, r *http.Request) {
+	if !s.apkAvailable() {
+		writeErr(w, http.StatusNotFound, "这个 magic-client 包里没有 APK（npm/apk/ 为空）")
+		return
+	}
+	ver := apkVersion(s.apkPath)
+	name := "magic-agent-mobile.apk"
+	if ver != "" {
+		name = "magic-agent-mobile-" + ver + ".apk"
+	}
+	w.Header().Set("Content-Type", "application/vnd.android.package-archive")
+	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%q", name))
+	w.Header().Set("Cache-Control", "no-store")
+	http.ServeFile(w, r, s.apkPath)
+}

package/internal/client/apk_test.go

@@ -0,0 +1,99 @@
+package client
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// 2026-10-22：移动端「我的」→「版本」点一下要能问桌面端「包里带的 APK 是哪一版」，
+// 再决定是否触发下载。这里钉住两个接口的形状与空包时的行为。
+
+func writeTestAPK(t *testing.T, dir, version string) string {
+	t.Helper()
+	apk := filepath.Join(dir, "magic-agent-mobile-release.apk")
+	body := []byte("fake-apk-" + version)
+	if err := os.WriteFile(apk, body, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	m := apkManifest{Version: version, VersionCode: 20102}
+	b, _ := json.Marshal(m)
+	if err := os.WriteFile(filepath.Join(dir, "version.json"), b, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return apk
+}
+
+func TestAppInfoAndAPK(t *testing.T) {
+	dir := t.TempDir()
+	apk := writeTestAPK(t, dir, "2.1.2")
+	s := &Service{apkPath: apk}
+
+	rec := httptest.NewRecorder()
+	s.handleAppInfo(rec, httptest.NewRequest(http.MethodGet, "/desk/app", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("app info code = %d, want 200", rec.Code)
+	}
+	var got struct {
+		Version string `json:"version"`
+		Size    int64  `json:"size"`
+		URL     string `json:"url"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	if got.Version != "2.1.2" || got.URL != "/desk/app.apk" || got.Size != int64(len("fake-apk-2.1.2")) {
+		t.Fatalf("app info = %+v", got)
+	}
+
+	rec = httptest.NewRecorder()
+	s.handleAppAPK(rec, httptest.NewRequest(http.MethodGet, "/desk/app.apk", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("apk code = %d, want 200", rec.Code)
+	}
+	if rec.Body.String() != "fake-apk-2.1.2" {
+		t.Fatalf("apk body = %q", rec.Body.String())
+	}
+	if ct := rec.Header().Get("Content-Type"); ct != "application/vnd.android.package-archive" {
+		t.Fatalf("content-type = %q", ct)
+	}
+	if cd := rec.Header().Get("Content-Disposition"); cd == "" {
+		t.Fatal("缺少 Content-Disposition，浏览器会拿不到 .apk 文件名")
+	}
+}
+
+func TestAppInfoWithoutAPK(t *testing.T) {
+	s := &Service{}
+	rec := httptest.NewRecorder()
+	s.handleAppInfo(rec, httptest.NewRequest(http.MethodGet, "/desk/app", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("code = %d, want 200（没包也要让手机能说「暂无」）", rec.Code)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	if got["version"] != "" || got["url"] != "" {
+		t.Fatalf("空包 info = %+v", got)
+	}
+
+	rec = httptest.NewRecorder()
+	s.handleAppAPK(rec, httptest.NewRequest(http.MethodGet, "/desk/app.apk", nil))
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("空包 apk code = %d, want 404", rec.Code)
+	}
+}
+
+func TestAPKVersionFallsBackToFilename(t *testing.T) {
+	dir := t.TempDir()
+	apk := filepath.Join(dir, "magic-agent-mobile-3.2.1-release.apk")
+	if err := os.WriteFile(apk, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if got := apkVersion(apk); got != "3.2.1" {
+		t.Fatalf("apkVersion = %q, want 3.2.1", got)
+	}
+}

package/internal/client/prefs.go

@@ -0,0 +1,99 @@
+package client
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+)
+
+/* 移动端「环境配置」的远端存储（2026-10-22 用户：
+ * 「环境的配置应该在远程上 不是浏览器缓存 否则同一个环境多个客户端配置还不一致」）。
+ *
+ * 为什么放在桌面端：默认引擎/模型、团队配置、空间选择这些描述的是**这台桌面怎么干活**，
+ * 不是某台手机的屏幕习惯。存在浏览器 localStorage 里，手机 A 改了手机 B 不知道；
+ * 换一台手机连同一台桌面，看到的还是另一套配置。
+ *
+ *   GET  /desk/prefs -> 这台桌面当前的配置 JSON（没有就是 {}）
+ *   PUT  /desk/prefs -> 整份覆盖（移动端改完推上来）
+ *
+ * 只存一个 JSON 文件，字段由移动端定义、桌面端不解释 —— 这样加一个配置项不用改这里。
+ * 落在 ~/.magic-agent/mobile-prefs.json，与 core 的其它数据同层次。
+ *
+ * 不做版本/合并：多端同时改就是「后写覆盖」。这些是偏好而不是业务数据，
+ * 冲突代价低；真需要并发控制时再加 version 字段也不迟。
+ */
+
+const mobilePrefsMaxBytes = 256 << 10
+
+func mobilePrefsPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".magic-agent", "mobile-prefs.json")
+}
+
+func (s *Service) handlePrefs(w http.ResponseWriter, r *http.Request) {
+	switch r.Method {
+	case http.MethodGet:
+		w.Header().Set("Cache-Control", "no-store")
+		p := mobilePrefsPath()
+		if p == "" {
+			writeJSON(w, http.StatusOK, map[string]any{})
+			return
+		}
+		b, err := os.ReadFile(p)
+		if err != nil || len(b) == 0 {
+			// 没存过 = 空配置，不把「文件不存在」当成错误。
+			writeJSON(w, http.StatusOK, map[string]any{})
+			return
+		}
+		if !json.Valid(b) {
+			writeJSON(w, http.StatusOK, map[string]any{})
+			return
+		}
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		_, _ = w.Write(b)
+
+	case http.MethodPut:
+		body, err := io.ReadAll(io.LimitReader(r.Body, mobilePrefsMaxBytes+1))
+		if err != nil {
+			writeErr(w, http.StatusBadRequest, "读请求体失败："+err.Error())
+			return
+		}
+		if len(body) > mobilePrefsMaxBytes {
+			writeErr(w, http.StatusRequestEntityTooLarge, "配置超过 256KB")
+			return
+		}
+		var v map[string]any
+		if err := json.Unmarshal(body, &v); err != nil {
+			writeErr(w, http.StatusBadRequest, "不是合法的 JSON 对象")
+			return
+		}
+		p := mobilePrefsPath()
+		if p == "" {
+			writeErr(w, http.StatusInternalServerError, "找不到用户目录")
+			return
+		}
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			writeErr(w, http.StatusInternalServerError, "建目录失败："+err.Error())
+			return
+		}
+		// 先写临时文件再 rename：多端同时推的时候不会读到写了一半的 JSON。
+		tmp := p + ".tmp"
+		if err := os.WriteFile(tmp, body, 0o600); err != nil {
+			writeErr(w, http.StatusInternalServerError, "写配置失败："+err.Error())
+			return
+		}
+		if err := os.Rename(tmp, p); err != nil {
+			writeErr(w, http.StatusInternalServerError, "落盘失败："+err.Error())
+			return
+		}
+		writeJSON(w, http.StatusOK, map[string]any{"ok": true})
+
+	default:
+		writeErr(w, http.StatusMethodNotAllowed, "只支持 GET / PUT")
+	}
+}