magic-agent 2.4.3 → 2.6.3

package/internal/client/singleinstance.go

@@ -0,0 +1,470 @@
+package client
+
+/* 单实例互斥（2026-10-26 用户：「同时只启动1个」）。
+ *
+ * ── 为什么必须在这一层 ──
+ * 同机多份 magic-client 是**唯一一个会让用户看到「明明跑完了却没有输出」的状态**：
+ *
+ *	· 它们共用同一个 ~/.magic-client/client.json 与固定端口名；
+ *	· 但作业队列的事件回放缓冲（askRun）是**进程内存**里的；
+ *	· 于是手机连 A 实例，任务被 B 实例执行 —— 作业文件两边都读得到（显示 done、
+ *	  甚至能读出 session_id），正文却长在 B 的内存里，A 拿不到，界面只剩
+ *	  「本轮没有收到任何输出（连接可能已断开）」。
+ *
+ * 更深一层的成因是「升级时二进制被替换」：老进程的可执行文件在磁盘上变成
+ * magic-client.stale（或直接被删），但它仍占着 9100/8977 与那条公网隧道。
+ * 用户以为自己在跑新版，实际连的是旧副本 —— 于是「版本已经处理了，还是不对」。
+ *
+ * ── 锁的粒度必须是「一份数据目录一把」，不是「一台机器一把」──
+ * 第一版写成了全机单锁，当场就把合法部署挡在门外：本机同时跑着
+ *   ① magic-test 的移动端网关（8977，storage.dir=~/.magic-test，令牌独立）；
+ *   ② magic-agent 自己的实例（9100 或随机端口，DataDir=~/.magic-client/magic-agent）。
+ * 两者数据目录不同、作业目录不同、令牌不同，**互不干扰**，属于正常用法。
+ * 真正会互相踩的是「同一个 DataDir 起两份」—— 它们共享 jobs/ 与 client.json，
+ * 才会出现上面那个空回复。仓库里已有的多实例租约（jobs.go 的 scheduler.lock）
+ * 也是按 jobs 目录划的，粒度一致。
+ *
+ * ── 为什么用锁文件而不是「探测端口」──
+ * 端口只是**结果**：两份实例可以绑不同端口（--addr / 被占用后换端口），彼此
+ * 连探测都发现不了对方，但照样会各跑一套队列去抢同一个工作区。判据必须是
+ * 「这份数据目录上有没有另一个活着的 magic-client」，与端口无关。
+ *
+ * ── 语义 ──
+ * O_CREATE|O_EXCL 原子创建，内容写 pid + 启动时间 + 版本 + 端口（便于报错时指认）。
+ * 持有进程已死（pid 探活失败）或文件超过 staleAfter → 判定陈旧并回收。
+ * 拿不到锁时**不静默退出**：把占用者身份打清楚 —— 用户要立刻知道该去停谁。
+ */
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// EnvLockPath 覆盖单实例锁文件位置（多实例联调 / 测试用；线上不要设）。
+const EnvLockPath = "MAGIC_CLIENT_LOCK"
+
+// EnvAppIDLockDir 覆盖 AppID 占用登记的目录（测试用；线上不要设）。
+const EnvAppIDLockDir = "MAGIC_CLIENT_APPID_LOCK_DIR"
+
+const (
+	// singleInstanceStale 锁文件超过这么久就按陈旧处理。
+	// 与工作空间锁同一个量级：进程崩溃没能删锁时，不能让用户等太久才能重启。
+	singleInstanceStale = 6 * time.Hour
+)
+
+// SingleInstanceHolder 锁文件的正文：占用者身份（报错 / 排障时指认用）。
+type SingleInstanceHolder struct {
+	PID     int       `json:"pid"`
+	Port    int       `json:"port,omitempty"`
+	Version string    `json:"version,omitempty"`
+	Exe     string    `json:"exe,omitempty"`
+	Cwd     string    `json:"cwd,omitempty"`
+	DataDir string    `json:"dataDir,omitempty"`
+	AppID   string    `json:"appID,omitempty"`
+	Since   time.Time `json:"since"`
+}
+
+// SingleInstanceLock 一把（或一组）已持有的单实例锁；Release 幂等。
+//
+// 允许一次持有多把：DataDir 锁 + AppID 登记是两道独立的闸门，任一道拿不到都不该起，
+// 而拿到了就必须在退出时**一起**放掉 —— 只放一把会在下次启动留下「持有者已死」的
+// 陈旧登记（虽然会被回收，但日志里会多一段困惑）。
+type SingleInstanceLock struct {
+	paths []string
+	held  bool
+}
+
+// DefaultLockPath 单实例锁的默认位置：与**该 profile 的数据目录**放一起
+// （<DataDir>/magic-client.lock）。
+//
+// 为什么跟 DataDir 走而不是 /tmp 或家目录根：/tmp 会被系统清理，锁文件凭空消失等于
+// 互斥失效；而「同一份数据目录」正是互斥的真正边界 —— 不同 AppID（magic-test 与
+// magic-agent）各自一把锁，能同时跑，互不误伤（这是 2026-10-26 第一版全机单锁的教训）。
+func DefaultLockPath(dataDir string) string {
+	if p := strings.TrimSpace(os.Getenv(EnvLockPath)); p != "" {
+		return expandHome(p)
+	}
+	dir := strings.TrimSpace(dataDir)
+	if dir == "" {
+		dir = filepath.Dir(DefaultStatePath())
+	}
+	return filepath.Join(dir, "magic-client.lock")
+}
+
+/* ── AppID 级占用登记（2026-10-26 补，治 DataDir 漂移）──
+
+光有 DataDir 锁还不够，实测踩到过：
+  同一个 magic-test 应用，一次启动算出 ~/.magic-test（profile 里写了 storage.dir），
+  另一次算出 ~/.magic-client/magic-test（profile 没读到，回落到 AppID 推导）。
+两条路径各自一把锁，**两份都放行**，但作业目录不同 —— 手机连着 A、
+任务在 B 里跑完，事件回放照样对不上，还是那句「没有收到任何输出」。
+
+所以互斥必须同时看两个维度：
+  · DataDir 锁  → 「这个目录上只能有一份」（同目录抢同一批作业文件）
+  · AppID 登记  → 「这个应用只能有一份」（同应用不许换着目录各跑一份）
+
+登记放 ~/.magic-client/appid-locks/<appid>.lock，内容记 DataDir + pid，
+所以冲突时能直接告诉用户「另一份在哪、用的哪个目录」。
+*/
+
+// appIDLockPath 某 AppID 的占用登记文件。
+//
+// AppID 里有 `.`（bundleId 形如 com.magic.test）和可能的 `/`，一律换成 `_`：
+// 前者本身无害，后者会变成路径分隔符、把文件写到别的目录里。
+func appIDLockPath(appID string) string {
+	appID = strings.TrimSpace(appID)
+	if appID == "" {
+		return ""
+	}
+	if p := strings.TrimSpace(os.Getenv(EnvAppIDLockDir)); p != "" {
+		dir := expandHome(p)
+		return filepath.Join(dir, sanitizeAppID(appID)+".lock")
+	}
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".magic-client", "appid-locks", sanitizeAppID(appID)+".lock")
+}
+
+// sanitizeAppID 把 AppID 变成安全的文件名。
+//
+// 规则：
+//   - 字母数字与 `.` `_` `-` 原样保留（bundleId 形如 com.magic.test 是常态）；
+//   - `/` `\` 换成 `_`（不换会把登记写到别的目录里，这是安全问题不是洁癖）；
+//   - 其它字符（含中文、空格、控制字符）**直接丢掉**而不是换成下划线 ——
+//     换掉的话 "名字" 会变成 "__"，既不认得出是谁，又可能和真实 AppID 撞名；
+//     丢完变空就兜底 "unknown"。
+func sanitizeAppID(appID string) string {
+	var b strings.Builder
+	for _, r := range appID {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9',
+			r == '.', r == '_', r == '-':
+			b.WriteRune(r)
+		case r == '/' || r == '\\':
+			b.WriteByte('_')
+		}
+	}
+	out := b.String()
+	// 全是 '.'/'..' 这类无意义名字：补兜底，别在目录里造出隐藏文件或上跳路径。
+	if out == "" || strings.Trim(out, ".") == "" {
+		return "unknown"
+	}
+	return out
+}
+
+// AcquireAppIDClaim 登记「这个 AppID 归我这份实例用」，并检查有没有别的 DataDir 在跑。
+//
+// 已被**活着的**进程占用、且它的 DataDir 与本次不同 → 返回 (nil, holder, nil)：
+// 这不是错误，是「同一应用另起了一份」，调用方负责报错退出（不要静默另开一套目录）。
+// 同一个 DataDir → 由 DataDir 锁去判，这里放行（否则同一份实例会被自己挡两道）。
+func AcquireAppIDClaim(appID, dataDir string) (*SingleInstanceLock, *SingleInstanceHolder, error) {
+	path := appIDLockPath(appID)
+	if path == "" {
+		// 定位不了就放行：登记只是加固，不能因为算不出路径就让用户起不来。
+		return nil, nil, nil
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return nil, nil, fmt.Errorf("建目录 %s 失败：%w", filepath.Dir(path), err)
+	}
+
+	myDataDir := strings.TrimSpace(dataDir)
+	for attempt := 0; attempt < 2; attempt++ {
+		f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+		if err == nil {
+			exe, _ := os.Executable()
+			wd, _ := os.Getwd()
+			h := SingleInstanceHolder{
+				PID: os.Getpid(), Version: clientVersion(),
+				Exe: exe, Cwd: wd, DataDir: myDataDir, AppID: appID, Since: time.Now(),
+			}
+			if b, merr := json.MarshalIndent(h, "", "  "); merr == nil {
+				_, _ = f.Write(append(b, '\n'))
+			}
+			_ = f.Close()
+			return &SingleInstanceLock{paths: []string{path}, held: true}, nil, nil
+		}
+		if !os.IsExist(err) {
+			return nil, nil, fmt.Errorf("创建占用登记 %s 失败：%w", path, err)
+		}
+
+		holder := ReadSingleInstanceHolder(path)
+		stale := holder == nil
+		if holder != nil {
+			switch {
+			case !lockPIDAlive(holder.PID):
+				stale = true
+			case !holder.Since.IsZero() && time.Since(holder.Since) > singleInstanceStale:
+				stale = true
+			case holder.PID == os.Getpid():
+				// 自己上一次已经登记过（同一进程重复调用）：续期即可。
+				return &SingleInstanceLock{paths: []string{path}, held: true}, nil, nil
+			case samePath(holder.DataDir, myDataDir):
+				// 同一个数据目录：DataDir 锁会挡住它，这里不重复判。
+				return nil, nil, nil
+			}
+		}
+		if !stale {
+			return nil, holder, nil
+		}
+		_ = os.Remove(path)
+	}
+	return nil, ReadSingleInstanceHolder(path), nil
+}
+
+// samePath 两个目录是否同一份（展开 ~ 后比较；解析失败就按字符串比）。
+func samePath(a, b string) bool {
+	a, b = strings.TrimSpace(a), strings.TrimSpace(b)
+	if a == "" || b == "" {
+		return false
+	}
+	ca, cb := filepath.Clean(expandHome(a)), filepath.Clean(expandHome(b))
+	if ca == cb {
+		return true
+	}
+	ra, ea := filepath.EvalSymlinks(ca)
+	rb, eb := filepath.EvalSymlinks(cb)
+	return ea == nil && eb == nil && ra == rb
+}
+
+// AppIDConflictMessage 同一 AppID 换了数据目录在跑时的说明。
+//
+// 要说清两件事：① 这是同一个应用的两个「家」，作业记录不互通；
+// ② 该去停哪一份（pid + 数据目录）。
+func AppIDConflictMessage(appID string, h *SingleInstanceHolder) string {
+	if h == nil {
+		return fmt.Sprintf("应用 %s 已有另一个实例在跑。先 `magic-client stop` 再启动。", appID)
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "应用 %s 已有另一个实例在跑（pid=%d", appID, h.PID)
+	if h.Version != "" {
+		fmt.Fprintf(&b, "，v%s", h.Version)
+	}
+	if !h.Since.IsZero() {
+		fmt.Fprintf(&b, "，已运行 %s", humanDuration(time.Since(h.Since)))
+	}
+	b.WriteString("）。\n")
+	if h.DataDir != "" {
+		fmt.Fprintf(&b, "它用的数据目录：%s\n", h.DataDir)
+	}
+	b.WriteString("同一个应用只能跑一份，**换数据目录也不算两份不同应用** —— 两个目录的作业记录\n")
+	b.WriteString("不互通，手机连着 A 时任务在 B 里跑完，界面就只剩「没有收到任何输出」。\n")
+	if h.Exe != "" {
+		fmt.Fprintf(&b, "正在跑的是：%s\n", h.Exe)
+	}
+	b.WriteString("先 `magic-client stop` 停掉它，再启动这一份（这会让两份回到同一个数据目录）。")
+	return b.String()
+}
+
+// lockPIDAlive 进程是否还活着。
+//
+// 不自己发信号 0：os.Process.Signal 在 Windows 上只支持 Kill，传 Signal(0) 恒返回
+// 错误 —— 那样写会让 Windows 上「持有者永远已死」，锁形同虚设（每次启动都回收别人
+// 的锁，两份实例照样并存）。agent.PIDAlive 是平台分派好的：
+// unix 走 kill(pid,0) 且把 EPERM 当活着，Windows 走 OpenProcess/GetExitCodeProcess。
+func lockPIDAlive(pid int) bool {
+	return agent.PIDAlive(pid)
+}
+
+// clientVersion 本实例的版本串（写进锁文件，报错时能看出「你连的是哪一版」）。
+//
+// 不做 ldflags 注入：magic-client 的版本由 core 契约统一上报（/desk/health 的
+// version 字段），这里只需要一个「大致是哪一版」的线索，取环境变量即可 ——
+// 缺了就不写，不编一个假的。
+func clientVersion() string {
+	return strings.TrimSpace(os.Getenv("MAGIC_CLIENT_VERSION"))
+}
+
+// ReadSingleInstanceHolder 读锁文件（不判断死活）。文件不存在 / 内容坏 → nil。
+func ReadSingleInstanceHolder(path string) *SingleInstanceHolder {
+	b, err := os.ReadFile(path)
+	if err != nil || len(b) == 0 {
+		return nil
+	}
+	var h SingleInstanceHolder
+	if err := json.Unmarshal(b, &h); err != nil {
+		// 老格式 / 半截写入：只认第一行的 pid，其余置零。
+		// 判死不靠这里，靠 lockPIDAlive —— 读不出身份不影响正确性。
+		line := strings.TrimSpace(strings.SplitN(string(b), "\n", 2)[0])
+		if pid, perr := strconv.Atoi(line); perr == nil && pid > 0 {
+			return &SingleInstanceHolder{PID: pid}
+		}
+		return nil
+	}
+	if h.PID <= 0 {
+		return nil
+	}
+	return &h
+}
+
+// AcquireInstanceLocks 一次性取两道锁：AppID 登记 + DataDir 锁。
+//
+// 顺序有讲究：**先 AppID 后 DataDir**。反过来的话，同一应用换了目录在跑时，
+// 第二份会先在自己那个（没人用的）目录上拿到锁，再被 AppID 挡下 —— 于是留下
+// 一个「持有者已死」的锁文件在空目录里，下次启动还得靠回收逻辑兜。
+//
+// 返回：
+//
+//	(lk, nil, nil)       两道都拿到，可以起
+//	(nil, holder, nil)   被挡住；which 说明是哪一道：
+//	                     "appid" → 同一应用换了数据目录在跑（AppIDConflictMessage）
+//	                     "datadir" → 同一数据目录上已有一份（SingleInstanceConflictMessage）
+//	(nil, nil, err)      真的 IO 故障
+func AcquireInstanceLocks(appID, dataDir string, port int) (lk *SingleInstanceLock, holder *SingleInstanceHolder, which string, err error) {
+	claim, appHolder, err := AcquireAppIDClaim(appID, dataDir)
+	if err != nil {
+		return nil, nil, "", err
+	}
+	if claim == nil && appHolder != nil {
+		return nil, appHolder, "appid", nil
+	}
+
+	dirLock, dirHolder, err := AcquireSingleInstance(dataDir, port)
+	if err != nil {
+		if claim != nil {
+			claim.Release()
+		}
+		return nil, nil, "", err
+	}
+	if dirLock == nil {
+		if claim != nil {
+			claim.Release()
+		}
+		return nil, dirHolder, "datadir", nil
+	}
+
+	// 两道都拿到：合成一把，退出时一起放。
+	all := &SingleInstanceLock{held: true}
+	if claim != nil {
+		all.paths = append(all.paths, claim.paths...)
+	}
+	if dirLock != nil {
+		all.paths = append(all.paths, dirLock.paths...)
+	}
+	return all, nil, "", nil
+}
+
+// AcquireSingleInstance 取单实例锁（dataDir = 该 profile 的数据目录）。
+//
+// 已被一个**活着的**进程持有 → 返回 (nil, holder, nil)，调用方负责报错退出。
+// 陈旧锁（进程没了 / 超过 staleAfter）→ 回收后重新创建。
+// 其它 IO 错误照常返回 err（写不了锁文件不是「有人在跑」，别混为一谈）。
+func AcquireSingleInstance(dataDir string, port int) (*SingleInstanceLock, *SingleInstanceHolder, error) {
+	path := DefaultLockPath(dataDir)
+	if path == "" {
+		return nil, nil, fmt.Errorf("定位单实例锁失败")
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return nil, nil, fmt.Errorf("建目录 %s 失败：%w", filepath.Dir(path), err)
+	}
+
+	// 最多两轮：第一轮 O_EXCL 成功即拿到；失败则判陈旧，回收后再来一次。
+	for attempt := 0; attempt < 2; attempt++ {
+		f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+		if err == nil {
+			exe, _ := os.Executable()
+			wd, _ := os.Getwd()
+			h := SingleInstanceHolder{
+				PID: os.Getpid(), Port: port, Version: clientVersion(),
+				Exe: exe, Cwd: wd, DataDir: dataDir, Since: time.Now(),
+			}
+			if b, merr := json.MarshalIndent(h, "", "  "); merr == nil {
+				_, _ = f.Write(append(b, '\n'))
+			}
+			_ = f.Close()
+			return &SingleInstanceLock{paths: []string{path}, held: true}, nil, nil
+		}
+		if !os.IsExist(err) {
+			return nil, nil, fmt.Errorf("创建锁文件 %s 失败：%w", path, err)
+		}
+
+		// 已存在：判死活。
+		holder := ReadSingleInstanceHolder(path)
+		stale := holder == nil
+		if holder != nil {
+			if !lockPIDAlive(holder.PID) {
+				stale = true
+			} else if !holder.Since.IsZero() && time.Since(holder.Since) > singleInstanceStale {
+				stale = true
+			}
+		}
+		if !stale {
+			return nil, holder, nil
+		}
+		_ = os.Remove(path) // 陈旧：清掉再来一轮
+	}
+	// 两轮都撞上 → 有人正在以毫秒级频率抢占，按「已有实例」处理更安全。
+	return nil, ReadSingleInstanceHolder(path), nil
+}
+
+// Release 释放锁（幂等）。只在**自己还持有**时删文件：
+// 被回收过又重新创建的情况下，删别人的锁会让互斥彻底失效 —— 所以核对 pid。
+func (l *SingleInstanceLock) Release() {
+	if l == nil || !l.held {
+		return
+	}
+	l.held = false
+	for _, p := range l.paths {
+		// 只删自己的：被回收过又重新创建的情况下，删别人的锁会让互斥彻底失效。
+		if h := ReadSingleInstanceHolder(p); h != nil && h.PID != os.Getpid() {
+			continue
+		}
+		_ = os.Remove(p)
+	}
+}
+
+// SingleInstanceConflictMessage 拿不到锁时给用户的说明（要能直接照着做）。
+//
+// 用户看到的不能只是「已在运行」——真正要传达的是：
+// 这台机器上还有另一份在跑，**它才是你手机连着的那个**；不先停掉它，
+// 新起的这份既占不到端口，也不会有任何请求进来。
+func SingleInstanceConflictMessage(h *SingleInstanceHolder) string {
+	if h == nil {
+		return "这份数据目录上已有另一个 magic-client 在跑。先 `magic-client stop` 再启动。"
+	}
+	age := ""
+	if !h.Since.IsZero() {
+		age = "，已运行 " + humanDuration(time.Since(h.Since))
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "这份数据目录上已有另一个 magic-client 在跑（pid=%d", h.PID)
+	if h.Version != "" {
+		fmt.Fprintf(&b, "，v%s", h.Version)
+	}
+	if h.Port > 0 {
+		fmt.Fprintf(&b, "，端口 %d", h.Port)
+	}
+	b.WriteString(age)
+	b.WriteString("）。\n")
+	if h.DataDir != "" {
+		fmt.Fprintf(&b, "数据目录：%s\n", h.DataDir)
+	}
+	b.WriteString("同一个数据目录只能跑一份 —— 两份共用同一批作业记录，任务会在其中一份里跑完，\n")
+	b.WriteString("而手机连着的那份拿不到输出（界面显示「没有收到任何输出」）。\n")
+	if h.Exe != "" {
+		fmt.Fprintf(&b, "正在跑的是：%s\n", h.Exe)
+	}
+	b.WriteString("先 `magic-client stop` 停掉它，再启动这一份。\n")
+	b.WriteString("（不同 AppID / 不同数据目录的实例互不影响，可以各自跑一份。）")
+	return b.String()
+}
+
+// humanDuration 粗粒度时长（报错文本用，不要精确到秒）。
+func humanDuration(d time.Duration) string {
+	switch {
+	case d < time.Minute:
+		return fmt.Sprintf("%d 秒", int(d.Seconds()))
+	case d < time.Hour:
+		return fmt.Sprintf("%d 分钟", int(d.Minutes()))
+	default:
+		return fmt.Sprintf("%d 小时", int(d.Hours()))
+	}
+}