magic-agent 2.4.3 → 2.6.3

package/internal/client/coreupgrade.go

@@ -0,0 +1,866 @@
+package client
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+/* magic-agent（core）自身的 npm 升级 —— 移动端「我的 → 版本」在装新 APK 的同时也要把
+ * 桌面端这份从 npm 装出来的 CLI 升上去（2026-10-23 用户：「我的 tab 版本中除了升级 apk，
+ * 也要触发 npm 升级」）。
+ *
+ * ── 为什么是「同一件事的两半」──
+ * 移动端界面、APK、桌面端的 magic-agent/magic-client 是**同一个 npm 包**（版本号同源）。
+ * 只装新 APK ⇒ 手机是新的、桌面还是旧的：新界面依赖的新接口（/desk/core、字段）会 404。
+ * 所以两半要一起完成；任一半失败都如实告诉用户，不假装整件事成功。
+ *
+ * ── 实现是什么 ──
+ * 在**桌面端**执行 `npm install -g magic-agent@latest --prefix <magic-agent 原来所在的前缀>`
+ * ——与 `npm run bump` 之后人工装两份前缀是同一个动作。命令只来自服务端拼装：
+ * 包名固定、前缀来自本机探测，接口不接受客户端传来的任何命令片段；版本号先过正则。
+ *
+ * ── 装完要重启才生效 ──
+ * 契约与 `/desk/health.version` 都是插件**启动时**缓存的（见 health 的注释），新二进制
+ * 换上去后正在跑的 serve 仍是旧代码；而 magic-client 是从 PATH 找到的魔数 —— 重启后
+ * 自然就是新版本。后台常驻（`magic-client start`）的实例用记录下来的启动参数原地重启，
+ * 前端凭证与端口都不变；手工 serve 的实例只提示「重启后生效」，不替用户杀掉前台进程。
+ */
+
+// npmEnv 交给 npm 子进程的环境。
+//
+// 为什么不能直接继承：宿主 IDE 会给客户端塞 `HTTP_PROXY=http://127.0.0.1:<会漂移的端口>`，
+// 那是它自己那层沙箱的出口，进程活久了端口早就没人监听（2026-10-27 实测：客户端里的
+// `npm view` 因此**静默失败**，手机看到的是「桌面端没有可升级版本」而 registry 明明有）。
+// agent.ChildEnvWith 会剔掉指向**死回环端口**的代理变量与宿主垫片（见 internal/agent/env.go），
+// 非回环代理一律不动。
+func npmEnv() []string { return agent.ChildEnvWith(nil) }
+
+// npmViewTimeout 查 npm registry 的等待上限。只为显示「有没有新版」，拿不到就不显示。
+var npmViewTimeout = 6 * time.Second
+
+// coreRepoName npm 上的包名（package.json 的 name）。
+const coreRepoName = "magic-agent"
+
+// coreInfo GET /desk/core 的响应。字段只增不改；读取方按字段缺失处理旧插件。
+type coreInfo struct {
+	// Version 此刻真正跑着的版本（与 /desk/health.version 同源：契约里的 version）。
+	Version string `json:"version"`
+	// Installed 本机 PATH 上找到的 magic-agent 版本（`magic-agent --version`）。
+	// 与 Version 不同 = 盘上已经是新版、只是服务没重启。
+	Installed string `json:"installed,omitempty"`
+	// Latest npm registry 上的最新版；空 = 没查到（离线 / npm 不在 PATH / 超时）。
+	Latest      string `json:"latest,omitempty"`
+	Upgradable  bool   `json:"upgradable"`        // 有更新的 npm 版本可装
+	RestartOnly bool   `json:"restartOnly"`       // 盘上已是新版，只差重启
+	Upgrade     string `json:"upgrade,omitempty"` // 将要执行的命令（给人看、可复制）
+	Bin         string `json:"bin,omitempty"`     // 将被替换的可执行文件
+	Prefix      string `json:"prefix,omitempty"`  // 它所属的 npm 前缀
+	CanUpgrade  bool   `json:"canUpgrade"`        // npm 与目标二进制都找得到
+	Daemon      bool   `json:"daemon"`            // 后台常驻（自带 state 文件）⇒ 能原地重启
+	Note        string `json:"note,omitempty"`    // 为什么不能升级 / 为什么需要重启
+}
+
+// coreUpgradeTarget 本次升级要装到哪、怎么装。零值 CanUpgrade=false。
+type coreUpgradeTarget struct {
+	Bin        string
+	Prefix     string
+	CanUpgrade bool     // npm 与目标二进制都找得到
+	Installed  string   // 盘上那份 magic-agent 的版本（升级前）
+	Latest     string   // npm registry 上的最新版
+	Replaced   bool     // 盘上那份是本进程启动后才换上去的（旧版读不出新版本号）
+	Args       []string // npm 的参数（不含 npm 自身）；空 = 不用升级
+	Note       string
+	Npm        string // npm 可执行文件（升级时用它跑 Args）
+}
+
+var semverRe = regexp.MustCompile(`\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.\-]+)?`)
+
+// parseSemver 从 `magic-agent v2.4.2` / `2.4.2` 这类输出里取出版本号。
+func parseSemver(s string) string { return semverRe.FindString(s) }
+
+// resolveLink 解析符号链接（npm 全局 bin 多为 symlink）；失败就原样返回。
+func resolveLink(p string) string {
+	if p == "" {
+		return ""
+	}
+	if real, err := filepath.EvalSymlinks(p); err == nil {
+		return real
+	}
+	return p
+}
+
+/*
+coreInstall 描述「这台机器上的 magic-agent 装在哪儿」——
+
+	升级要**装回原处**：npm i -g 会写进 <prefix>/{lib/,}node_modules/<pkg>，
+	前缀算错就会装到别处（实测 Homebrew 上曾算出包内目录，结果版本没变 —— 白跑一趟）。
+	所以这里认三样东西：
+	  · PkgDir  npm 包根（…/node_modules/magic-agent，含 package.json）
+	  · Bin    真正会被替换掉的那个二进制（包内 dist 产物，不依赖 node 还在 PATH 上）
+	  · Prefix 装回原处要用的 --prefix（npm 全局前缀）
+*/
+type coreInstall struct {
+	Bin    string
+	PkgDir string
+	Prefix string
+	// ReplacedAfter 这个二进制是**本进程启动之后**才被换上去的（npm 已装好新版、只差重启）。
+	// 见 replacedAfterStart。
+	ReplacedAfter bool
+}
+
+// corePackageOf 从一个路径往上找 npm 包根（package.json 的 name == magic-agent）。
+//
+// 两条硬要求：
+//  1. 路径先绝对化 —— PATH 里可能有 "." 之类的相对项，不绝对化就会在当前目录里乱认；
+//  2. 包必须**装在 node_modules 下** —— 源码目录（仓库根也有 package.json，name 同样是
+//     magic-agent）不算 npm 装的那份：npm i -g 换不掉它。
+//
+// 认不出就返回空 —— 那份二进制不是 npm 装的（自行编译 / 别的发行方式）。
+// inspectPackage npm 包根 → 安装信息（顺带判「是不是装好了没重启」）。
+func (s *Service) inspectPackage(pkgDir string) coreInstall {
+	inst := coreInstall{PkgDir: pkgDir, Prefix: npmPrefixForPackage(pkgDir)}
+	inst.Bin = coreBinaryInPackage(pkgDir)
+	if inst.Bin != "" {
+		inst.ReplacedAfter = s.replacedAfterStart(inst.Bin)
+	}
+	return inst
+}
+
+func corePackageOf(path string) string {
+	if path == "" {
+		return ""
+	}
+	if abs, err := filepath.Abs(path); err == nil {
+		path = abs
+	}
+	p := filepath.Dir(path)
+	for i := 0; i < 10; i++ {
+		if pkgNameAt(p) == coreRepoName {
+			parent := filepath.Dir(p)
+			if strings.EqualFold(filepath.Base(parent), "node_modules") {
+				return p
+			}
+			return "" // 名字对但不是 node_modules 下的 —— 源码目录，不是 npm 装的
+		}
+		parent := filepath.Dir(p)
+		if parent == p {
+			break
+		}
+		p = parent
+	}
+	return ""
+}
+
+// npmPrefixForPackage 包根 → 装回原处要用的 npm 全局前缀。
+//
+// npm 的全局根固定是 <prefix>/lib/node_modules（Windows 是 <prefix>/node_modules），
+// 所以从包根反推前缀只有两种形状：
+//
+//	…/<prefix>/lib/node_modules/magic-agent   → 前缀 = …/<prefix>
+//	…/<prefix>/node_modules/magic-agent       → 前缀 = …/<prefix>（Windows 形状）
+//
+// 认不出（布局不常见）就返回空：交给 npm 用它自己的默认前缀，
+// 事后由「版本到底变没变」来判定成败（不谎报）。
+func npmPrefixForPackage(pkgDir string) string {
+	if pkgDir == "" {
+		return ""
+	}
+	root := filepath.Dir(pkgDir) // …/node_modules
+	if !strings.EqualFold(filepath.Base(root), "node_modules") {
+		return ""
+	}
+	parent := filepath.Dir(root) // …/lib 或 <prefix>
+	if strings.EqualFold(filepath.Base(parent), "lib") {
+		return filepath.Dir(parent)
+	}
+	return parent
+}
+
+// coreBinaryInPackage 包内真正会被 npm 替换掉的那个二进制（dist 产物）。
+// 没有 dist 产物时回落到包里的 bin 转发脚本。
+func coreBinaryInPackage(pkgDir string) string {
+	if pkgDir == "" {
+		return ""
+	}
+	cands := []string{
+		filepath.Join(pkgDir, "npm", "dist", runtime.GOOS+"-"+runtime.GOARCH, "magic-agent"+exeSuffix()),
+		filepath.Join(pkgDir, "bin", "magic-agent"+exeSuffix()),
+	}
+	for _, p := range cands {
+		if fileExists(p) {
+			return resolveLink(p)
+		}
+	}
+	return ""
+}
+
+// procStart 本进程的启动时刻；读不到就退回到「本进程可执行文件的 mtime」。
+//
+// 为什么不直接写 mtime：npm 换包时是先删再写，新二进制与本进程自己的 mtime 可能只差
+// 毫秒，同一文件系统上只能按秒比；而「本进程启动时刻」在快机器上几乎总是与本进程
+// 可执行文件同一秒 —— 按秒判就会漏掉「刚换上去」的那种。Linux 上 /proc/self/stat 精确到
+// 毫秒（见 procstart_linux.go），能稳稳分开。测试里可替换成固定时刻。
+var procStart = func() (time.Time, bool) {
+	self, err := os.Executable()
+	if err != nil {
+		return time.Time{}, false
+	}
+	st, err := os.Stat(resolveLink(self))
+	if err != nil {
+		return time.Time{}, false
+	}
+	return fileTime(st), true
+}
+
+// fileTime 文件修改时刻（**丢掉单调时钟读数**：os.Stat 给的时间在本进程里其实带着
+// m=+… 的单调读数，和 time.Now() 比时会优先拿它比 —— 结论取决于跑多久，而不是 mtime）。
+func fileTime(st os.FileInfo) time.Time {
+	if st == nil {
+		return time.Time{}
+	}
+	return st.ModTime().Round(0)
+}
+
+// replacedAfterStart 盘上那个可执行文件是不是**本进程启动之后**才被写上去的。
+//
+// 为什么需要它：升级成功后本进程**原地重启**，但重启前这一小段时间里旧进程还在跑 ——
+// 新起来的那个读到的是**旧版**的 magic-agent --version（旧版不认识改过的升级参数，回的
+// 是 `magic-agent v2.4.1`），于是界面上「检测更新」又亮起来，再点一次就是**降级安装**。
+// 盘上的文件比本进程新 ⇒ 它已经是新装的那份，只差重启，不许再拿它的「版本」去判升级。
+//
+// 这里**不**用来证明「升级真的成功了」——那是版本号 / 重启后新实例来证明的；它只用来在
+// 原地重启的那几秒里不让界面再喊一次升级（再点就是降级）。非 Linux 上 procStart 退回
+// 本进程 mtime，精度只到秒，判不准就返回 false（宁可多喊一次升级）。
+func replacedAfterStart(bin string) bool { return (&Service{}).replacedAfterStart(bin) }
+
+// replacedAfterStart s 版的 replacedAfterStart：测试可以钉住「本进程启动时刻」（procStartOverride），
+// 免得结果取决于测试进程已经跑了多久。
+func (s *Service) replacedAfterStart(bin string) bool {
+	if bin == "" {
+		return false
+	}
+	st, err := os.Stat(resolveLink(bin))
+	if err != nil {
+		return false
+	}
+	startFn := procStart
+	if s.procStartOverride != nil {
+		startFn = s.procStartOverride
+	}
+	start, ok := startFn()
+	if !ok {
+		return false
+	}
+	return st.ModTime().After(start)
+}
+
+// npmPrefixForBinDir `<prefix>/bin/magic-agent`（非 npm 包的普通安装）→ `<prefix>`。
+// npm 的全局 bin 就装在 <prefix>/bin，所以这是「装回原处」的前缀。
+func npmPrefixForBinDir(bin string) string {
+	dir := filepath.Dir(bin)
+	if strings.EqualFold(filepath.Base(dir), "bin") && runtime.GOOS != "windows" {
+		return filepath.Dir(dir)
+	}
+	return ""
+}
+
+// resolveCoreInstall 找出「这台机器上该被 npm 升级替换的那份 magic-agent」。
+//
+// 候选顺序：**正在跑的那份**（hint = 本服务用的 core 路径）→ PATH 上的 magic-agent →
+// 本进程所在目录的 magic-agent。逐个看它是不是 **npm 装的那份**（在 node_modules 下）：
+// 是就以那个包为目标（npm i -g 换的就是它）；都不是就退回 hint 本身，并按
+// <prefix>/bin/… 的形状推前缀（装不装得回原处，交给 npm 与事后校验）。
+func resolveCoreInstall(hint string) coreInstall { return (&Service{}).resolveCoreInstall(hint) }
+
+// resolveCoreInstall s 版（带测试覆盖）。
+func (s *Service) resolveCoreInstall(hint string) coreInstall {
+	var cands []string
+	if hint != "" {
+		cands = append(cands, hint)
+	}
+	if p, err := exec.LookPath("magic-agent"); err == nil {
+		cands = append(cands, p)
+	}
+	if exe, err := os.Executable(); err == nil {
+		cands = append(cands, filepath.Join(filepath.Dir(resolveLink(exe)), "magic-agent"+exeSuffix()))
+	}
+	var fallback coreInstall
+	for _, c := range cands {
+		if c == "" {
+			continue
+		}
+		c = resolveLink(c)
+		if pkg := corePackageOf(c); pkg != "" {
+			inst := s.inspectPackage(pkg)
+			inst.Bin = coreBinaryInPackage(pkg)
+			if inst.Bin == "" {
+				inst.Bin = c
+			}
+			return inst
+		}
+		if fallback.Bin == "" {
+			fallback = coreInstall{Bin: c, Prefix: npmPrefixForBinDir(c), ReplacedAfter: s.replacedAfterStart(c)}
+		}
+	}
+	return fallback
+}
+
+// findCoreBin 兼容旧调用点：只要那个二进制路径（探测用，不带 hint）。
+func findCoreBin() string { return resolveCoreInstall("").Bin }
+
+func exeSuffix() string {
+	if runtime.GOOS == "windows" {
+		return ".exe"
+	}
+	return ""
+}
+
+func fileExists(p string) bool {
+	st, err := os.Stat(p)
+	return err == nil && !st.IsDir()
+}
+
+// pkgNameAt 读 dir/package.json 的 name；不是 npm 包目录返回空。
+func pkgNameAt(dir string) string {
+	b, err := os.ReadFile(filepath.Join(dir, "package.json"))
+	if err != nil {
+		return ""
+	}
+	var pkg struct {
+		Name string `json:"name"`
+	}
+	if json.Unmarshal(b, &pkg) != nil {
+		return ""
+	}
+	return strings.TrimSpace(pkg.Name)
+}
+
+// resolveCoreUpgrade 决定怎么升级：找 npm、找目标二进制、清理版本号，拼出参数表。
+// latest 为空表示没查到 registry（只做「盘上已是新版就重启」的判断）。
+func resolveCoreUpgrade(latest string, hint string) coreUpgradeTarget {
+	return (&Service{}).resolveCoreUpgrade(latest, hint)
+}
+
+// resolveCoreUpgrade s 版：s 上带测试用的覆盖（procStartOverride），生产路径没有。
+func (s *Service) resolveCoreUpgrade(latest string, hint string) coreUpgradeTarget {
+	var t coreUpgradeTarget
+	inst := s.resolveCoreInstall(hint)
+	bin := inst.Bin
+	if bin != "" {
+		t.Bin = resolveLink(bin)
+		t.Prefix = inst.Prefix
+	}
+	latest = parseSemver(latest)
+	t.Latest = latest
+	// 盘上那份被 npm 换掉之后才是「重装好」的判断依据；空 = 读不出来（老版本 / 不可执行）。
+	t.Installed = coreBinaryVersion(bin)
+	// 本进程启动之后盘上才换上去的 ⇒ coreStatus 要跟「正在跑的那份」比一比再定夺
+	// （见 coreStatus 里 RestartOnly 的判断）。
+	t.Replaced = inst.ReplacedAfter
+
+	if bin == "" {
+		t.Note = "没找到本机的 magic-agent 可执行文件：不知道要升级哪一份"
+		return t
+	}
+	npm, npmErr := exec.LookPath("npm")
+	if npmErr != nil {
+		t.Note = "PATH 上没有 npm：没法在这台电脑上执行 npm 升级（请手工在终端里执行 npm i -g magic-agent@latest）"
+		return t
+	}
+	if latest == "" {
+		t.Note = "没查到 npm 上的最新版本（离线？npm 不在 PATH？），所以不做 npm 升级"
+		return t
+	}
+	// 版本号已过正则（只可能是 x.y.z[-pre]），不会被 npm 当成参数。
+	t.Npm = npm
+	/* `-g` 放最后（2026-10-26）：npm 自己能容忍这个顺序，但「假 npm」（测试里顶替 registry
+	   的那份）按 `$1 = install`、`$3 = 包@版本` 读参数 —— 在中间插一个 `-g` 会让所有
+	   升级类单测悄悄测不到 install，甚至让「什么都没装」被当成「装好了」。 */
+	t.Args = []string{"install", coreRepoName + "@" + latest, "--no-fund", "--no-audit", "-g"}
+	if t.Prefix != "" {
+		t.Args = append(t.Args, "--prefix", t.Prefix)
+	}
+	t.CanUpgrade = true
+	return t
+}
+
+// coreUpgradeCommand 给人看的完整命令（复制到终端也能跑）。
+func (t coreUpgradeTarget) Command() string {
+	if !t.CanUpgrade {
+		return ""
+	}
+	return "npm " + strings.Join(t.Args, " ")
+}
+
+// fetchNpmLatest 问 registry「magic-agent 的最新版是多少」。拿不到就返回空（不是错误）。
+//
+// 为什么不走 HTTP 直连 registry：npm 自带的代理 / 镜像 / 认证配置都在 npm 里，
+// 自己发请求会得到与 `npm i` 不一样的答案（用户开了镜像时尤其明显）。
+func fetchNpmLatest(ctx context.Context) string {
+	npm, err := exec.LookPath("npm")
+	if err != nil {
+		return ""
+	}
+	c, cancel := context.WithTimeout(ctx, npmViewTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(c, npm, "view", coreRepoName, "version", "--json")
+	cmd.Env = npmEnv()
+	out, err := cmd.Output()
+	if err != nil {
+		return ""
+	}
+	var s string
+	if json.Unmarshal(out, &s) != nil {
+		s = string(out)
+	}
+	return parseSemver(s)
+}
+
+// runningBinaryVersion 「正在跑的那份」的版本 —— 与 coreStatus 用同一条判据（见 runningVersion）。
+// bin 为空或跑不起来时退回契约缓存（空 = 不知道）。
+func (s *Service) runningBinaryVersion(bin string) string {
+	if v := coreBinaryVersion(bin); v != "" {
+		return v
+	}
+	if s.coreTarget != nil && s.opts.MagicAgent == "" {
+		// 测试桩：没有真实路径可跑时以桩给的 Installed 为准。
+		return s.coreTarget(context.Background()).Installed
+	}
+	return s.contract.Version
+}
+
+// coreBinaryVersion 跑 `<bin> --version` 拿盘上那份的版本。
+func coreBinaryVersion(bin string) string {
+	if bin == "" {
+		return ""
+	}
+	c, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(c, bin, "--version").Output()
+	if err != nil {
+		return ""
+	}
+	return parseSemver(string(out))
+}
+
+// selfDaemonState 本服务如果由 `magic-client start` 拉起（或前台 serve 自登记过），
+// 返回它那份状态记录（可原地重启）。
+func (s *Service) selfDaemonState() *DaemonState {
+	bin := resolveLink(selfExe())
+	if bin == "" {
+		return nil
+	}
+	/* 先看服务自己**启动时用过的**状态文件（`--state` / MAGIC_CLIENT_STATE 决定的，
+	   存在 Service 里 —— 不在请求时重新读环境变量：后台常驻进程可能已经跑了好几天）。 */
+	var paths []string
+	if p := strings.TrimSpace(s.opts.StatePath); p != "" {
+		paths = []string{expandHome(p)}
+	} else if p := strings.TrimSpace(os.Getenv("MAGIC_CLIENT_STATE")); p != "" {
+		paths = []string{expandHome(p)}
+	} else if p := strings.TrimSpace(s.opts.SelfStatePath); p != "" {
+		/* 前台 serve 自登记的那份（<数据目录>/serve.json，见 daemon.go 的 SelfStateName）。
+		   必须显式列出来：它不在 DefaultStatePath 那个目录里，下面那段扫目录扫不到它 ——
+		   而「扫不到」正是过去手机点重启一律 409 的直接原因。
+		   ⚠️ 排在 StatePath / 环境变量**之后**：`magic-client start` 起的实例两者都有值，
+		     那时必须认 client.json（信息更全，含日志位置），不能被 serve.json 抢先。 */
+		paths = []string{expandHome(p)}
+	} else {
+		dir := filepath.Dir(DefaultStatePath())
+		ents, err := os.ReadDir(dir)
+		if err != nil {
+			return nil
+		}
+		for _, e := range ents {
+			n := e.Name()
+			// client.json 是唯一的实例；client-<hash>.json 是多实例（见 instance.go）。
+			if !e.IsDir() && strings.HasPrefix(n, "client") && strings.HasSuffix(n, ".json") {
+				paths = append(paths, filepath.Join(dir, n))
+			}
+		}
+	}
+	me := os.Getpid()
+
+	for _, p := range paths {
+		st, err := ReadDaemonState(p)
+		if err != nil || st == nil {
+			continue
+		}
+		// 必须就是**本进程**：同一份二进制可能还跑着别的实例（别的端口/别的用户），
+		// 重启错的那一个等于把别人的服务踢掉。
+		// 按「Exe 是**同一个 magic-client 文件**」认领，而不是按 core 路径：升级前 PATH 上
+		// 的 core 可能还指向旧目录（npm 前缀里被驱动覆盖的那份），拿 core 路径比对会认不出来。
+		if st.PID != me || st.PID <= 0 {
+			continue
+		}
+		self, _ := os.Executable()
+		if st.Exe != "" && resolveLink(st.Exe) != resolveLink(self) {
+			continue
+		}
+		return st
+	}
+	return nil
+}
+
+// coreStatus 汇总 GET /desk/core（不升级，只回答「是不是最新」）。
+func (s *Service) coreStatus(ctx context.Context) coreInfo {
+	t := s.coreUpgradeTarget(ctx)
+	running := s.runningVersion(t)
+	info := coreInfo{
+		Version:   running,
+		Installed: t.Installed,
+		Latest:    t.Latest,
+		Bin:       t.Bin,
+		Prefix:    t.Prefix,
+		Note:      t.Note,
+	}
+	// 升级的判据以「盘上那份」为准：重启之后 running 会追上来，两者相等即无需升级。
+	base := t.Installed
+	if base == "" {
+		base = running
+	}
+	if t.Latest != "" && cmpSemver(t.Latest, base) > 0 {
+		info.Upgradable = true
+	}
+	if t.CanUpgrade {
+		info.CanUpgrade = true
+		// 只在**真的有更高版本**时才给命令：registry 上的 latest 可能比本机旧（开发版 /
+		// 预发版），照着这条命令敲就是降级（接口那头会拒，但别把坑摆在界面上）。
+		if info.Upgradable {
+			info.Upgrade = t.Command()
+		}
+	}
+	/* 盘上已经是新版 ⇒ 只差重启：
+	   · Installed 读得出且比正在跑的更新（典型：刚 npm 装完、没重启服务）；
+	   · 或盘上那份是**本进程启动后**才换上去的（原地重启那几秒，旧版二进制读不出新版本号，
+	     见 replacedAfterStart）—— 这时 Latest 也可能是空的（没连上 registry），照样算「只差重启」，
+	     因为「比本进程新」本身就说明刚才那次装成功了。 */
+	if (t.Installed != "" && running != "" && cmpSemver(t.Installed, running) > 0) ||
+		(t.Replaced && (t.Latest == "" || running == "" || cmpSemver(t.Latest, running) > 0)) {
+		info.Upgradable = false
+		info.RestartOnly = true
+		if info.Note == "" {
+			info.Note = "盘上已经是 " + orDash(t.Installed) + "，正在运行的仍是 " + running + "：重启 magic-client 后生效"
+		}
+	}
+	info.Daemon = s.selfDaemonState() != nil
+	return info
+}
+
+// coreUpgradeTarget 「最新版 + 该升哪一份」——coreStatus 与 handleCoreUpgrade 共用这一个入口
+// （测试里只替换它一处，就能同时钉住「绝不碰真 core」，见 coreupgrade_test.go）。
+func (s *Service) coreUpgradeTarget(ctx context.Context) coreUpgradeTarget {
+	if s.coreTarget != nil {
+		return s.coreTarget(ctx)
+	}
+	latest := ""
+	if s.latestFn != nil {
+		latest = s.latestFn(ctx)
+	} else {
+		latest = fetchNpmLatest(ctx)
+	}
+	return s.resolveCoreUpgrade(latest, s.opts.MagicAgent)
+}
+
+// parseArgVersion 从 `magic-agent@2.4.3` 这类参数里取版本。
+func parseArgVersion(args []string) string {
+	for _, a := range args {
+		if i := strings.LastIndex(a, "@"); i >= 0 {
+			return parseSemver(a[i+1:])
+		}
+	}
+	return ""
+}
+
+// cmpSemver 比较 a、b 两段 x.y.z（忽略预发布后缀）。a > b 返回正数。
+func cmpSemver(a, b string) int {
+	pa := strings.SplitN(a, ".", 3)
+	pb := strings.SplitN(b, ".", 3)
+	for i := 0; i < 3; i++ {
+		var x, y int
+		if i < len(pa) {
+			fmt.Sscanf(strings.TrimLeft(pa[i], "v"), "%d", &x)
+		}
+		if i < len(pb) {
+			fmt.Sscanf(strings.TrimLeft(pb[i], "v"), "%d", &y)
+		}
+		if x != y {
+			if x > y {
+				return 1
+			}
+			return -1
+		}
+	}
+	return 0
+}
+
+// runningVersion 「此刻真正在跑的那份 core 是哪一版」。
+//
+// ⚠️ 盘上的二进制在**本进程启动之后**被 npm 换掉时（t.Replaced），`--version` 跑的是
+// **新文件**，答的却是我们没在跑的版本 —— 这时以契约缓存（启动时校验过的那份）为准，
+// 才能把「装好了、只差重启」跟「还在跑旧版」区分开。
+func (s *Service) runningVersion(t coreUpgradeTarget) string {
+	if !t.Replaced {
+		if v := coreBinaryVersion(s.opts.MagicAgent); v != "" {
+			return v
+		}
+	}
+	if v := parseSemver(s.contract.Version); v != "" {
+		return v
+	}
+	if v := coreBinaryVersion(s.opts.MagicAgent); v != "" {
+		return v
+	}
+	if s.coreTarget != nil && s.opts.MagicAgent == "" {
+		return t.Installed
+	}
+	return ""
+}
+
+// handleCoreInfo GET /desk/core：桌面端 CLI 的版本信息（当前 / 盘上 / npm 最新）。
+func (s *Service) handleCoreInfo(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	writeJSON(w, http.StatusOK, s.coreStatus(r.Context()))
+}
+
+/* handleCoreUpgrade POST /desk/core/upgrade
+ *
+ * 与插件安装同一套 SSE 口径：`open`（要跑的命令）→ `step` → `line`（逐行输出）→ `end`
+ * （ok / code / 升级后的信息）。升级成功后**本进程已经是被换掉的那个旧二进制**，
+ * 所以成功时按需原地重启 —— 重启发生在 end 之后，前端先收到「完成」再收到断线。
+ *
+ * ── 重启为什么交给 restart.go 的那条链路 ──
+ * 不能在本进程里起新实例：新实例要先抢占旧实例的端口，而旧实例还活着（端口被占），
+ * 只能等旧进程先退出 —— 那样 handler 已经跟着进程一起消失了。所以照 `POST /desk/restart`
+ * 的做法：先答、再由定时器拉起一个脱离终端的 `magic-client restart` 助手（它停旧起新、
+ * 参数全来自状态文件，端口 / 令牌 / 界面目录沿用）。手机探活靠 /desk/health.restarting
+ * 分辨「旧实例认账」与「新实例已起」。
+ */
+func (s *Service) handleCoreUpgrade(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	ctx := context.WithoutCancel(r.Context())
+	t := s.coreUpgradeTarget(ctx)
+	if !t.CanUpgrade {
+		writeErr(w, http.StatusConflict, t.Note)
+		return
+	}
+	/* 绝不降级：registry 上的 latest 可能比本地还旧（本地是开发版 / 预发版，
+	   或者别人先发了旧版本）。`npm i -g magic-agent@<latest>` 是**无条件安装**，
+	   不挡住就是把好的那份换成旧的 —— 这里明确拒绝并说明。 */
+	if t.Replaced {
+		// 盘上已经是本进程启动后换上去的新版（旧版二进制读不出自己的版本号）：再装一遍
+		// 没有意义，而且「装完版本没变」会把它误报成失败 —— 要的是重启。
+		writeErr(w, http.StatusConflict, "盘上已经是 npm 最新版 v"+t.Latest+"，只差重启 magic-client 后生效")
+		return
+	}
+	if t.Installed != "" && cmpSemver(t.Latest, t.Installed) <= 0 {
+		writeErr(w, http.StatusConflict,
+			"npm 上的最新版是 v"+t.Latest+"，不高于本机已装的 v"+t.Installed+"：不做降级安装")
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("X-Accel-Buffering", "no")
+	flusher, _ := w.(http.Flusher)
+	send := func(event string, payload any) {
+		b, _ := json.Marshal(payload)
+		if event != "" {
+			fmt.Fprintf(w, "event: %s\n", event)
+		}
+		fmt.Fprintf(w, "data: %s\n\n", b)
+		if flusher != nil {
+			flusher.Flush()
+		}
+	}
+
+	send("open", map[string]any{"command": t.Command(), "bin": t.Bin, "from": s.contract.Version, "to": parseArgVersion(t.Args)})
+	send("step", map[string]any{"index": 0, "command": t.Command()})
+	code, err := runPluginStep(ctx, pluginStep{Args: append([]string{t.Npm}, t.Args...), Env: npmEnv()}, func(line string) {
+		send("line", map[string]any{"index": 0, "line": line})
+	})
+	if err == nil && code != 0 {
+		err = fmt.Errorf("%s 退出码 %d", t.Command(), code)
+	}
+	if err != nil {
+		send("end", map[string]any{"ok": false, "code": code, "error": err.Error(), "core": s.coreStatus(ctx)})
+		return
+	}
+
+	/**
+	 * 不谎报成功：以**盘上那份的版本真的变了**为判据。
+	 * （`npm i -g` 退出 0 但装到了别的前缀、或 registry 还没同步时，都会走到这里。）
+	 */
+	after := s.coreStatus(ctx)
+	newVer := coreBinaryVersion(t.Bin)
+	/* 新二进制**旧版读不出新版本号**（本进程启动后才换上、回的还是旧版式输出）：
+	   升级本身是成功的，只是没法从这里读出它的版本 —— 交给重启后的新实例回答，
+	   不能因为「读不出」就报失败。 */
+	replacedOnly := newVer == "" || (t.Installed != "" && cmpSemver(newVer, t.Installed) <= 0)
+	if replacedOnly && after.RestartOnly {
+		newVer = orDash(after.Latest)
+	} else if newVer == "" || newVer == t.Installed || cmpSemver(newVer, t.Installed) <= 0 {
+		send("end", map[string]any{"ok": false, "code": 0,
+			"error": "npm 已执行，但 " + t.Bin + " 的版本没有变化（仍是 " + orDash(newVer) + "）：可能装到了别的前缀，或 npm 源还没同步",
+			"core":  after})
+		return
+	}
+
+	restarted := false
+	note := ""
+	if s.selfDaemonState() != nil {
+		// 与 POST /desk/restart 同一套：立标志（挡住并发的第二次升级）、先答、定时器后拉助手。
+		restartMu.Lock()
+		already := restartPending
+		restartPending = true
+		restartMu.Unlock()
+		restarted = true
+		switch {
+		case already:
+			note = "已装好 " + newVer + "；服务已在重启中，几秒后自动重连"
+		default:
+			note = "已装好 " + newVer + "，正在重启后台服务，几秒后自动重连"
+		}
+		/* 状态文件路径一并交给助手（2026-10-26）：本实例可能是前台 serve（magic-test 那种），
+		   它的登记在 <数据目录>/serve.json，助手按默认 client.json 找会去重启**别的**实例。 */
+		statePath := statePathOf(s.selfDaemonState())
+		if exe := selfExe(); exe != "" {
+			if !already {
+				time.AfterFunc(restartDelay, func() { restartSpawner(exe, s.log, statePath) })
+			}
+		} else {
+			restarted = false
+			note = "npm 已装好新版本；没能定位自身可执行文件，请手工重启 magic-client 后生效"
+		}
+	} else {
+		note = "npm 已装好新版本；当前是前台 serve 且没有登记过自己，重启 magic-client 后生效"
+	}
+	send("end", map[string]any{"ok": true, "code": 0, "restarting": restarted, "note": note, "core": after})
+	if flusher != nil {
+		flusher.Flush()
+	}
+}
+
+// coreQuickInfo /desk/health 里顺带的那一小块：不查 registry、不起子进程（探活要快）。
+//
+// 只说两件事：npm 与目标二进制在不在（能不能让手机一键升级）、能不能原地重启。
+// 具体版本要升级前再问 GET /desk/core。
+func (s *Service) coreQuickInfo() map[string]any {
+	return s.coreQuickInfoWith(true)
+}
+
+// upgradableCore 「这台机器上能不能让手机一键升级桌面端（npm）」—— 与 /desk/health 的
+// core.available 同一条判据。/desk/app 用它随 APK 信息一起告诉界面（2026-10-26）。
+func (s *Service) upgradableCore() bool { return s.coreQuickInfoWith(false)["available"] == true }
+
+func (s *Service) coreQuickInfoWith(withRestart bool) map[string]any {
+	out := map[string]any{
+		"available": false, // 能不能执行 npm 升级（npm 在 PATH 上且找得到目标二进制）
+		"version":   s.contract.Version,
+	}
+	if withRestart {
+		out["restart"] = false // 能不能原地重启（后台常驻实例）
+	}
+	inst := resolveCoreInstall(s.opts.MagicAgent)
+	if _, err := exec.LookPath("npm"); err == nil && inst.Bin != "" {
+		out["available"] = true
+		out["bin"] = inst.Bin
+		out["prefix"] = inst.Prefix
+	}
+	if withRestart && s.selfDaemonState() != nil {
+		out["restart"] = true
+	}
+	return out
+}
+
+// restartDaemon 已并入 POST /desk/restart 的同一条链路（restart.go 的 restartSpawner）：
+// 「先立标志、先答、定时器后拉助手停旧起新」，升级完不再自己起第二个实例。
+
+func orDash(v string) string {
+	if v == "" {
+		return "—"
+	}
+	return v
+}
+
+// selfExe 本进程自己的可执行文件（解析符号链接）。`start` 之后 serve 跑的就是它。
+func selfExe() string {
+	p, err := os.Executable()
+	if err != nil {
+		return ""
+	}
+	return resolveLink(p)
+}
+
+// ReadCoreContract 跑 `<bin> --contract` 并按插件要求校验（契约版本 + 必需的通道能力）。
+// 报错文案与启动流程里的那条保持一致 —— 用户看到的必须是同一句话。
+func ReadCoreContract(bin string) (Contract, error) {
+	if strings.TrimSpace(bin) == "" {
+		bin = "magic-agent"
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, bin, "--contract").Output()
+	if err != nil {
+		return Contract{}, fmt.Errorf("读 core 契约失败（%s --contract）：%w", bin, err)
+	}
+	var c Contract
+	if err := json.Unmarshal(out, &c); err != nil {
+		return Contract{}, fmt.Errorf("解析 core 契约失败：%w", err)
+	}
+	if c.ContractVersion != RequiredContractVersion {
+		return c, fmt.Errorf("core 契约版本 %d 与本插件要求的 %d 不一致：请升级 magic-agent（或换用匹配的插件版本）",
+			c.ContractVersion, RequiredContractVersion)
+	}
+	for _, f := range requiredFeatures {
+		if !hasStr(c.Features, f) {
+			return c, fmt.Errorf("core 缺通道能力 %s（需要支持 --stream --events 与 --control 的版本）", f)
+		}
+	}
+	return c, nil
+}
+
+// CoreContractProblem 返回空串 = 这个 core 能用；否则是不能用的原因（给人看的）。
+func CoreContractProblem(bin string) string {
+	if _, err := ReadCoreContract(bin); err != nil {
+		return err.Error()
+	}
+	return ""
+}
+
+// PrecheckCore 由 `magic-client start` 调用（内部子命令 core-check）：判定 core 能不能用。
+//
+// 为什么新开一个子进程：升级之后父进程 exec 到的「本进程的路径」在磁盘上已经是新二进制，
+// 但判定逻辑（契约版本、必需能力）必须来自**新二进制自己的那份代码** —— 老代码不知道
+// 新版本对契约的要求会不会变，那样升级完可能启动到一个用不了的服务而没人发现。
+func PrecheckCore(coreBin string) (bool, string) {
+	bin := strings.TrimSpace(coreBin)
+	if bin == "" {
+		p, err := exec.LookPath("magic-agent")
+		if err != nil {
+			return false, "PATH 上没有 magic-agent"
+		}
+		bin = p
+	}
+	c, err := ReadCoreContract(bin)
+	if err != nil {
+		return false, err.Error()
+	}
+	return true, c.Version
+}