magic-agent 2.6.0 → 2.6.3

package/internal/client/service.go

@@ -89,6 +89,25 @@ type Options struct {
 	// 打开它 = 任意网页都能**读**响应；真正的门锁仍是令牌（没有 X-Magic-Token 一律 401）。
 	// `--lan` 时默认开启（都绑 0.0.0.0 了，再按 loopback 卡 Origin 没有意义）。
 	AllowAnyOrigin bool
+	/* StatePath 本实例（若是 `magic-client start` 起的）状态文件路径，来自 `--state` /
+	   MAGIC_CLIENT_STATE。升级与重启要「认领自己」：同机可能还跑着别的实例，按路径找状态
+	   文件比按默认路径猜准（默认路径下存的是另一个实例时，重启会重启别人）。 */
+	StatePath string
+	/* SelfStatePath 前台 serve 自登记的状态文件（<数据目录>/serve.json，见 daemon.go）。
+	   与 StatePath 分开两个字段而不是复用一个：两者的语义不同 —— StatePath 是
+	   `start` 的实例记录（还决定日志/令牌位置），SelfStatePath 只是「我是谁」，
+	   重启与升级靠它认领自己。空 = 本实例是 start 起的（走 StatePath / 默认路径）。 */
+	SelfStatePath string
+	/* FeishuAppID / FeishuAppSecret 飞书自建应用的凭据（2026-10-26，「登录后推送通知」）。
+	   优先级：移动端写入的本机 feishu-notify.json > 环境变量 MAGIC_FEISHU_APP_ID/SECRET
+	   > 这里（config.json 的 feishu 节）。空 = 没配置，界面提示去填。见 feishu.go。 */
+	FeishuAppID     string
+	FeishuAppSecret string
+	/* HostPID 托管本服务的父进程（桌面壳 / 测试宿主）。0 = 没人托管。
+	   重启出来的新实例是 detach 的（必须如此，否则旧实例退出会连带杀掉它），
+	   壳就再也杀不到它 —— 于是由服务自己盯着这个 pid：主人没了就优雅退出，
+	   免得孤儿占着端口与单实例锁让下次开壳「插件启动即退出」。见 WatchHost。 */
+	HostPID int
 }
 
 // Service 本地服务。
@@ -110,6 +129,16 @@ type Service struct {
 	// inst 服务实例的稳定 id（见 instance.go）：同一台桌面的多个入口靠它归一。
 	inst instanceIDCache
 
+	/* 本进程的启动时刻（2026-10-27）。
+	 *
+	 * 为什么需要：重启换的是**进程**，会话、任务、设置全在磁盘上，所以界面重启前后
+	 * 长得一模一样 —— 用户点了「重启服务」，看到列表没变，只会得出「没效果」。
+	 * `instanceId` 帮不上忙：它是**同一台桌面**的稳定身份（多入口归一要靠它），
+	 * 跨重启必须不变，所以不能用它判断新旧代。
+	 * 这里给 /desk/health 补一对「这次真的是新进程」的证据：pid + 启动时刻。
+	 * 只增字段，不升 contractVersion；老插件没有 → 客户端退回原判据。 */
+	startedAt time.Time
+
 	// 内置浏览器中转用的 HTTP 客户端（惰性建、带 cookie jar，按上游 host 存会话）。
 	// 见 browse.go —— 它让 iframe 的流量走**桌面端网络**，而不是手机直连。
 	browseOnce sync.Once
@@ -126,15 +155,41 @@ type Service struct {
 	// 脚本清单与运行态（「发现 → 脚本」，见 scripts.go）。
 	scripts *scriptManager
 
+	// 工作台应用（「发现 → 应用」，见 apps.go）：magic-shorts / magic-video 的本地
+	// 工作台在这里启停，并经 /workbench/{id}/ 反代给手机内置浏览器。
+	apps *appManager
+
+	/* 会话清单（/desk/sessions）的短 TTL 缓存 + 单飞（2026-10-26，见 sessions_cache.go）。
+	   为什么必须缓存：这个接口每次请求都 spawn 一个 core 进程（`--sessions` 本身约 20ms，
+	   但在负载高的机器上、且 core 是 npm 转发脚本时要 200~900ms）。而列表页是**轮询**驱动的
+	   —— 移动端主列表每 5s 拉一次，一次 loadSessions 还会并发问 5 个接口；PC 左栏在有会话
+	   跑着时每 30s 一次。用户报「会话列表显示很慢」实测就是这个：同一个 core 直连 20ms，
+	   经本插件 400~900ms，10 并发时每个都到 1.6s。 */
+	sessCache sessionsCache
+
 	// 随包发布的移动端 APK（空 = 这个包里没带）。见 apk.go。
 	apkPath string
 
+	// coreTarget 覆盖「桌面端 CLI 的最新版 + 该升哪一份」的解析（只给测试用，见
+	// coreupgrade.go::coreUpgradeTarget）。nil = 按本机真实探测。
+	coreTarget func(context.Context) coreUpgradeTarget
+	// procStartOverride 覆盖「本进程启动时刻」（只给测试用，见 coreupgrade.go::replacedAfterStart）。
+	procStartOverride func() (time.Time, bool)
+	// latestFn 覆盖「问 npm registry 最新版」（只给测试用：不联网）。nil = 真去问。
+	latestFn func(context.Context) string
+
 	/* 公网入口探测（2026-10-22）：隧道是**壳**起的，插件不知道它的域名，而 quick tunnel
-	   每次启动都换域名。这里缓存 probePublicURL 的结果，让 /desk/health 不必每次都扫端口。 */
-	pubMu   sync.Mutex
-	pubURL  string
-	pubExp  time.Time
-	pubBusy bool
+	   每次启动都换域名。这里缓存 probePublicURL 的结果，让 /desk/health 不必每次都扫端口。
+	   2026-10-25：结果**落盘**（见 publicurl.go）—— 客户端重启不该让手机把公网地址换成
+	   局域网地址。pubLoaded 保证只读一次盘；pubMiss 记连续探空次数（两次才认定隧道真没了）；
+	   pubGraceTo 是重启后的宽限期，期内探空不撤已知域名。 */
+	pubMu      sync.Mutex
+	pubURL     string
+	pubExp     time.Time
+	pubBusy    bool
+	pubLoaded  bool
+	pubMiss    int
+	pubGraceTo time.Time
 
 	/* 知识库（OpenViking）的最新版本缓存 + 安装互斥（见 knowledge.go）。
 	   成功缓存 6h、失败缓存 15min —— 失败不该每次开页面都重试一次外网。
@@ -144,6 +199,10 @@ type Service struct {
 	ovLatestOK bool
 	ovLatestAt time.Time
 	ovBusy     bool
+
+	// 飞书推送（/desk/feishu*，见 feishu.go）：惰性建，状态落 ~/.magic-agent/feishu-notify.json。
+	feishuOnce sync.Once
+	feishuN    *feishuNotifier
 }
 
 // Contract core `--contract` 里本插件关心的部分。
@@ -186,10 +245,12 @@ func New(opts Options) (*Service, error) {
 	if opts.Logger == nil {
 		opts.Logger = log.New(os.Stderr, "magic-client: ", 0)
 	}
-	if strings.TrimSpace(opts.MagicAgent) == "" {
-		opts.MagicAgent = "magic-agent"
-	}
-	s := &Service{opts: opts, log: opts.Logger, runs: map[string]*askRun{}}
+	/* core 用**绝对路径**（优先同目录的真二进制），别让 exec 走 PATH ——
+	   PATH 上可能是 npm 的 node 转发脚本，宿主 IDE 的环境足以让它在 require 阶段就崩。
+	   详见 coreexe.go 顶部那段 2026-10-26 的真机记录。 */
+	selfExe, _ := os.Executable()
+	opts.MagicAgent = resolveCoreExe(opts.MagicAgent, selfExe)
+	s := &Service{opts: opts, log: opts.Logger, runs: map[string]*askRun{}, startedAt: time.Now()}
 	// 移动端 APK：显式路径优先；否则在包内 npm/apk/ 找（随 npm 包发布，见 apk.go）。
 	s.apkPath = strings.TrimSpace(opts.APKPath)
 	if s.apkPath == "" {
@@ -242,6 +303,43 @@ func (s *Service) Contract() Contract { return s.contract }
 // MagicAgentPath 实际使用的 core 可执行文件。
 func (s *Service) MagicAgentPath() string { return s.opts.MagicAgent }
 
+/* WatchHost 盯着托管本服务的父进程：它没了就调用 quit（2026-10-26）。
+ *
+ * ── 为什么需要 ──
+ * 「手机点重启」要求新实例 detach（独立会话），否则旧实例退出时会把同组的它一起带走。
+ * 可 detach 之后，掌天瓶壳的 `will-quit` 里那句 `r.stop()`（杀的是它 spawn 的那个句柄）
+ * 就管不到新实例了 —— 壳退出、服务还在，占着端口和单实例锁，下次开壳直接「插件启动即退出」，
+ * 用户只能去终端 magic-client stop 救。
+ *
+ * 这里把「主人是谁」变成服务自己的一条退出条件：壳没了，服务主动收摊。于是
+ * 「壳托管」这个语义在重启前后保持一致，不需要壳那边配合改任何东西。
+ *
+ * `magic-client start` 起的常驻实例 HostPID = 0（没人托管）→ 直接返回，行为不变。
+ *
+ * ⚠️ 只在**启动时**判一次「主人在不在」，之后每 2 秒看一次：
+ *    重启链路里父进程可能恰好在我们起来之前退出，那种情况下这个实例本来就没人要了。 */
+func (s *Service) WatchHost(quit func()) {
+	host := s.opts.HostPID
+	if host <= 0 || quit == nil {
+		return
+	}
+	go func() {
+		for {
+			if !HostAlive(host) {
+				s.log.Printf("托管进程（pid %d）已退出：本服务跟着收摊，避免留下孤儿占着端口", host)
+				quit()
+				return
+			}
+			time.Sleep(hostPollInterval)
+		}
+	}()
+}
+
+// hostPollInterval 盯父进程的轮询间隔。
+// 2 秒：壳退出到端口释放要在用户下次开壳前完成，这个粒度足够；又不会太密去打扰系统调用。
+// 是 var 不是 const：用例要把它压到毫秒级，否则测一次要等两秒。
+var hostPollInterval = 2 * time.Second
+
 // Handler 路由。
 func (s *Service) Handler() http.Handler {
 	mux := http.NewServeMux()
@@ -254,6 +352,11 @@ func (s *Service) Handler() http.Handler {
 	mux.HandleFunc("/desk/app", s.guard(s.handleAppInfo))
 	// 系统浏览器/下载器带不了自定义头，这个接口靠 guard 支持的 ?token= 过鉴权。
 	mux.HandleFunc("/desk/app.apk", s.guard(s.handleAppAPK))
+	/* 桌面端 CLI（npm 那份）的版本与升级（见 coreupgrade.go）。2026-10-26 用户：
+	   「版本检测需要同时考虑 apk 和 npm，都要支持升级」—— 升级链路一直有，但这两条
+	   路由从没挂上过（只有测试里手挂），手机根本问不到；这次补上。 */
+	mux.HandleFunc("/desk/core", s.guard(s.handleCoreInfo))
+	mux.HandleFunc("/desk/core/upgrade", s.guard(s.handleCoreUpgrade))
 	mux.HandleFunc("/desk/engines", s.guard(s.handleEngines))
 	// 每日积分领取（2026-10-24）：core --checkin <engine>，用该引擎自己的票据。
 	mux.HandleFunc("/desk/checkin", s.guard(s.handleCheckin))
@@ -280,6 +383,10 @@ func (s *Service) Handler() http.Handler {
 	// 移动端「环境配置」（引擎/模型/团队/空间选择）的远端存储：多客户端连同一台桌面时共用一份，
 	// 不再各存各的 localStorage（见 prefs.go）。
 	mux.HandleFunc("/desk/prefs", s.guard(s.handlePrefs))
+	/* 飞书推送（2026-10-26）：绑定码 / 绑定 / 开关 / 测试 / 幂等推送，见 feishu.go。
+	   子树路由、一个入口分派 —— 与 /desk/session/ 同一个理由（「有哪些子路径」集中在一处）。 */
+	mux.HandleFunc("/desk/feishu", s.guard(s.handleFeishu))
+	mux.HandleFunc("/desk/feishu/", s.guard(s.handleFeishu))
 	// 需求聚合（2026-10-22，见 requirements.go）：读清单 / 手动整理一轮。
 	// 自动归纳不在这里 —— 它是每轮 /desk/ask 收尾后的防抖动作。
 	mux.HandleFunc("/desk/requirements", s.guard(s.handleRequirements))
@@ -302,6 +409,13 @@ func (s *Service) Handler() http.Handler {
 	// 命令**只来自登记过的脚本定义**（不过 shell），客户端不能传任意命令行。
 	mux.HandleFunc("/desk/scripts", s.guard(s.handleScripts))
 	mux.HandleFunc("/desk/scripts/", s.guard(s.handleScriptSub))
+	/* 应用（2026-10-26）：magic-shorts / magic-video 的本地工作台，手机「发现 → 应用」起停。
+	   见 apps.go。反代入口 /workbench/{id}/ 不套 s.guard（与 /b/ 同理）：它只转给
+	   127.0.0.1 上那个工作台，工作台自己要不要鉴权是它的事；页面在根路径下跑时，
+	   由 handleStatic 按 Referer 转发（同样不套 guard —— 工作台的静态资源本就不带令牌）。 */
+	mux.HandleFunc("/desk/apps", s.guard(s.handleApps))
+	mux.HandleFunc("/desk/apps/", s.guard(s.handleAppAction))
+	mux.HandleFunc("/workbench/", s.handleWorkbench)
 	mux.HandleFunc("/desk/dirs", s.guard(s.handleDirs))
 	// /desk/session/{id}/messages 是**前缀匹配**路由 —— 标准 ServeMux 把它挂上后，
 	// 该前缀下任何 path 都先进这里（其它挂载顺序靠后也拦不住）。
@@ -311,7 +425,10 @@ func (s *Service) Handler() http.Handler {
 	mux.HandleFunc("/desk/ask", s.guard(s.handleAsk))
 	mux.HandleFunc("/desk/ask/", s.guard(s.handleAskSub))
 	// 业务模块的路由：原样转发到项目自己的后端（见 Profile.Backend 的注释）。
-	mux.HandleFunc("/api/", s.guard(s.handleProjectAPI))
+	/* /api/* 先看是不是工作台页面发出来的（发现 → 应用）：工作台的工作台页面在根路径下跑，
+	   页面里的 '/api/…' 是根相对的，不能落到项目后端引导师头上。判定见 apps.go 的 workbenchFor，
+	   命中就交给工作台，未命中再照旧（鉴权 + 转给 profile 的 backend）。 */
+	mux.HandleFunc("/api/", s.routeAPI)
 	// 业务模块的静态资源：优先项目自己的模块目录（profile 的 ui.modulesDir）。
 	mux.HandleFunc("/modules/", s.handleModulesStatic)
 	// 二维码配对：把「桌面地址 + 令牌」给手机扫。内容等同于令牌，所以用普通鉴权把门
@@ -452,7 +569,12 @@ func (s *Service) guard(next http.HandlerFunc) http.HandlerFunc {
 func (s *Service) handleHealth(w http.ResponseWriter, r *http.Request) {
 	// core 由本插件 spawn、继承本进程的 cwd；而 core 不传 -w 时默认工作空间就是 cwd。
 	// 所以这里的 cwd 就是「桌面默认工作空间」，客户端用它给空 workspace 的会话归类。
-	wd, _ := os.Getwd()
+	//
+	// ⚠️ 走 defaultWorkspace() 而不是直接 os.Getwd()（2026-10-26）：插件被 `cd /`
+	// 起来时 cwd 是文件系统根，把它当默认工作区会让移动端新建的会话全归到 `/`，
+	// 同空间冲突判定与 core 的工作空间锁也随之退化成「全机一个空间」。
+	// 规则与作业队列同源（defaultWorkspace：cwd 有意义用它，否则退回上次用的）。
+	wd := defaultWorkspace()
 	writeJSON(w, http.StatusOK, map[string]any{
 		"ok":              true,
 		"contractVersion": s.contract.ContractVersion,
@@ -473,6 +595,11 @@ func (s *Service) handleHealth(w http.ResponseWriter, r *http.Request) {
 		// 再探到该字段为假的 200 才是新一代起来。老插件没有该字段 → 客户端照旧
 		// 「先看到连不上、再看到 200」的判据。
 		"restarting": restartRequested(),
+		// 重启交接（2026-10-25，只增字段）：本实例受理重启、且已算出新实例的样子时，
+		// {urls:[手机可用入口，不带令牌], token:新实例令牌}。手机在「重启服务」的探活里
+		// 顺走它，改完原环境的连接地址与令牌再连 —— 地址随网卡变化、令牌重发都不会让
+		// 手机永远掉线（见 restart.go 的 restartHandoff）。不重启 / 算不出来 → 缺失。
+		"restartHandoff": restartHandoff(),
 		// 服务实例的稳定 id（2026-10-23，只增字段）：同一台桌面的本地 / 局域网 / 公网
 		// 入口可能有多条 URL，客户端据此把它们归一成同一个环境（队列与设置共用）。
 		// 老插件没有该字段 → 客户端退回按连接各自算环境。
@@ -496,6 +623,14 @@ func (s *Service) handleHealth(w http.ResponseWriter, r *http.Request) {
 		// 团队角色清单（2026-10-22）：移动端「团队模式」页要按角色配路由，
 		// 角色名不能由客户端硬编码。老 core 没有 teamRoles → null，客户端回落内置清单。
 		"teamRoles": s.contract.TeamRoles,
+		/* 「这次真的是新进程」的证据（2026-10-27，只增字段，不升 contractVersion）。
+		 *
+		 * 为什么加：重启换的是进程，会话/任务/设置全在盘上，界面重启前后一模一样 ——
+		 * 用户点了「重启服务」看见列表没变，只会说「没效果」（当天真机原话）。
+		 * instanceId 不能担此任：它是同一台桌面的稳定身份，跨重启**必须不变**。
+		 * → pid 变 + startedAt 变才是「换了一代」的硬证据，客户端据此把「已重启」说实。 */
+		"pid":       os.Getpid(),
+		"startedAt": s.startedAt.UTC().Format(time.RFC3339),
 	})
 }
 
@@ -541,9 +676,23 @@ const (
 // /quicktunnel 里，扫一小段端口就能拿到候选，再用**本服务自己的令牌**回打一次
 // /desk/health 确认「这条隧道确实指向我」（别人的隧道令牌不同 → 401）。
 //
-// 空返回 = 没开公网 / 还没扫到；调用方（移动端）退回局域网地址，不假装有。
+// 为什么还要落盘（2026-10-25 用户：「重启也尽量不要变 cloudflare 域名就可以了」）：
+// 域名只随**隧道**重启而变，magic-client 重启并不碰 cloudflared。可探测结果只在内存里，
+// 客户端一重启就空，手机就退回局域网地址 —— 表现成「重启后地址变了」。所以启动先读回
+// 上次的域名立刻顶上，后台探测再纠正（见 publicurl.go）。
+//
+// 空返回 = 没开公网 / 已确认没了；调用方（移动端）退回局域网地址，不假装有。
 func (s *Service) publicURL() string {
 	s.pubMu.Lock()
+	if !s.pubLoaded {
+		s.pubLoaded = true
+		if v := s.loadSavedPublicURL(); v != "" {
+			s.pubURL = v
+			/* exp 保持零值 = 立刻触发一次后台探测（只是别让 health 等它）；
+			   grace 期内探不到也不撤这个已知域名。 */
+			s.pubGraceTo = time.Now().Add(publicGrace)
+		}
+	}
 	cur, exp, busy := s.pubURL, s.pubExp, s.pubBusy
 	s.pubMu.Unlock()
 	if busy || time.Now().Before(exp) {
@@ -557,31 +706,95 @@ func (s *Service) publicURL() string {
 	s.pubBusy = true
 	s.pubMu.Unlock()
 
-	go func() {
-		u := s.probePublicURL()
-		s.pubMu.Lock()
-		changed := u != s.pubURL
-		s.pubURL = u
-		s.pubExp = time.Now().Add(publicTTL)
-		s.pubBusy = false
-		s.pubMu.Unlock()
-		if changed && s.log != nil {
-			if u == "" {
-				s.log.Printf("公网入口：未发现（本机没有指向本服务的 cloudflared quick tunnel）")
-			} else {
-				s.log.Printf("公网入口：%s", u)
-			}
-		}
-	}()
+	go func() { s.applyProbeResult(s.probePublicURL()) }()
 	return cur
 }
 
+// applyProbeResult 收下一次探测的结果：更新缓存、落盘、记探空次数。
+//
+// 抽成方法是为了能直接测（各人机器上网卡/隧道千差万别，靠真起 cloudflared 测不稳）。
+// 规则见 publicGrace 与 publicTTL 的注释：宽限期内探空不动已知域名；连续两次探空
+// 且过了宽限期才认定隧道真没了。
+func (s *Service) applyProbeResult(u string) {
+	s.pubMu.Lock()
+	prev := s.pubURL
+	inGrace := time.Now().Before(s.pubGraceTo)
+	/* 宽限期内探不到 → 已知域名继续顶着（cloudflared 可能比我们起得慢）。
+	   真探到了就以新值为准（隧道重起换了域名）。 */
+	next := u
+	if u == "" && inGrace && prev != "" {
+		next = prev
+	}
+	changed := next != prev
+	s.pubURL = next
+	s.pubExp = time.Now().Add(publicTTL)
+	s.pubBusy = false
+	if u == "" {
+		s.pubMiss++
+	} else {
+		s.pubMiss = 0
+	}
+	miss := s.pubMiss
+	s.pubMu.Unlock()
+
+	/* 落盘：探到了就存；连续两次探空（且过了宽限期）才认定隧道真没了、删掉旧域名。
+	   只探空一次就删太激进 —— cloudflared 刚起、metrics 还没就绪时也会空。 */
+	switch {
+	case u != "":
+		s.savePublicURL(u)
+	case miss >= 2 && !inGrace:
+		s.clearSavedPublicURL()
+	}
+
+	if changed && s.log != nil {
+		if next == "" {
+			s.log.Printf("公网入口：未发现（本机没有指向本服务的 cloudflared quick tunnel）")
+		} else {
+			s.log.Printf("公网入口：%s", next)
+		}
+	}
+}
+
 // probePublicURL 扫 cloudflared 的 metrics 端口，找出指向本服务的那条 quick tunnel。
 func (s *Service) probePublicURL() string {
 	tok := strings.TrimSpace(s.opts.Token)
 	if tok == "" {
 		return ""
 	}
+	cands := quickTunnelHosts()
+	if len(cands) == 0 {
+		return ""
+	}
+
+	// 用本服务的令牌回打一次：只有真正指向本服务的隧道才认这个令牌。
+	var (
+		mu    sync.Mutex
+		found string
+		wg    sync.WaitGroup
+	)
+	for _, h := range cands {
+		wg.Add(1)
+		go func(host string) {
+			defer wg.Done()
+			if !healthOK("https://"+host, tok, 3*time.Second) {
+				return
+			}
+			mu.Lock()
+			if found == "" {
+				found = "https://" + host
+			}
+			mu.Unlock()
+		}(h)
+	}
+	wg.Wait()
+	return found
+}
+
+// quickTunnelHosts 列出本机 cloudflared 当前挂在 metrics 端口上的 quick tunnel 域名。
+//
+// 单独抽出来是为了「验证式取址」：缓存里的域名可能是**上一轮隧道**留下的（进程重启
+// 就换域名），手机上表现为「卡片里的地址打不开」。发消息前要拿这份**当前**清单重新验。
+func quickTunnelHosts() []string {
 	hosts := make(chan string, quickTunnelPortHi-quickTunnelPortLo+1)
 	for p := quickTunnelPortLo; p <= quickTunnelPortHi; p++ {
 		go func(port int) {
@@ -608,46 +821,32 @@ func (s *Service) probePublicURL() string {
 			cands = append(cands, h)
 		}
 	}
-	if len(cands) == 0 {
-		return ""
-	}
+	return cands
+}
 
-	// 用本服务的令牌回打一次：只有真正指向本服务的隧道才认这个令牌。
-	var (
-		mu    sync.Mutex
-		found string
-		wg    sync.WaitGroup
-	)
-	for _, h := range cands {
-		wg.Add(1)
-		go func(host string) {
-			defer wg.Done()
-			req, err := http.NewRequest(http.MethodGet, "https://"+host+"/desk/health", nil)
-			if err != nil {
-				return
-			}
-			req.Header.Set("X-Magic-Token", tok)
-			resp, err := (&http.Client{Timeout: 3 * time.Second}).Do(req)
-			if err != nil {
-				return
-			}
-			defer resp.Body.Close()
-			if resp.StatusCode != http.StatusOK {
-				return
-			}
-			var v map[string]any
-			if json.NewDecoder(resp.Body).Decode(&v) != nil || v["ok"] != true {
-				return
-			}
-			mu.Lock()
-			if found == "" {
-				found = "https://" + host
-			}
-			mu.Unlock()
-		}(h)
+// healthOK 用本服务的令牌回打一次 /desk/health：只有真指向本服务的入口才会 200 + ok。
+// 这是「地址能不能用」的唯一可信判据 —— 不能只看域名像不像、也不能信缓存。
+func healthOK(base, tok string, timeout time.Duration) bool {
+	req, err := http.NewRequest(http.MethodGet, strings.TrimRight(base, "/")+"/desk/health", nil)
+	if err != nil {
+		return false
 	}
-	wg.Wait()
-	return found
+	if tok != "" {
+		req.Header.Set("X-Magic-Token", tok)
+	}
+	resp, err := (&http.Client{Timeout: timeout}).Do(req)
+	if err != nil {
+		return false
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return false
+	}
+	var v map[string]any
+	if json.NewDecoder(resp.Body).Decode(&v) != nil {
+		return false
+	}
+	return v["ok"] == true
 }
 
 // handleContract 原样转发 core 的契约（客户端拿它做能力降级，不需要经过插件再解释一遍）。
@@ -677,11 +876,54 @@ func (s *Service) handleProfile(w http.ResponseWriter, r *http.Request) {
 // （用户 2026-10-15：「通过 magic-test 新建的会话要在 magic-agent 移动端 h5 上看到，
 // 同时 magic-agent 上可以看到 magic-test 和 magic-agent 来源的会话」）。
 //
-// 名单两项：magic-test = 掌天瓶桌面壳；magic-agent = core 自身/直连 CLI 的显式标识。
-// ⚠️ 只放行**同族的 magic-* 来源**：匿名（空 client = 手工跑 / CI）与不相干应用仍被挡在
-// 外面 —— 这正是原过滤要避免的「把别人的任务混进本应用的会话列表」。
+// ⚠️ 2026-10-26（用户：「多个客户端要能拉到同样的会话历史」）：**从「认名字」改成
+// 「认同族」**。此前是钉死的两个字符串 `{magic-test, magic-agent}`，于是每接一个新
+// 客户端（另一个 magic-* 桌面应用、改了 bundleId 的构建、用户自己起的 magic-xxx）
+// 都得回来改这句常量 —— 忘了改的表现是**静默少一堆会话**，而且只有那个客户端看不见，
+// 极难归因。改成按前缀判定后不再有这个维护点。
+//
+// 判据（见 sessionClientVisible）：本插件自己的 AppID / 同族 magic-* 前缀 /
+// 本仓认得的历史遗留名。匿名（空 client = 手工跑 / CI）与不相干应用仍被挡住 ——
+// 那正是这次过滤要避免的「把别人的任务混进本应用的会话列表」。
 var extraSessionClients = []string{"magic-test", "magic-agent"}
 
+/*
+	sessionClientVisible 这个来源客户端该不该出现在本客户端的会话列表里。
+
+//
+// 三条放行理由，任一成立即可：
+//
+//	① 就是我（Profile.AppID）—— 从这台机器上、经本插件发起的；
+//	② 同族（前缀 magic-）—— 掌天瓶、别的 magic-* 桌面应用、直连 CLI 的显式标识。
+//	   族内互看是用户 2026-10-15 定的口径，2026-10-26 的多客户端需求只是把它推广开；
+//	③ 名单里显式列出的历史遗留名（extraSessionClients）。
+//
+// ⚠️ 为什么不干脆全放行（把 client 过滤整个删掉）：登记表在 ~/.magic-agent/sessions，
+// 是**全机共享**的 —— 用户手工跑的、CI 跑的、别的产品写的都在里面，client 为空。
+// 全放行的结果是把「不知道哪来的」会话混进本应用列表，那比少显示几条更难查。
+//
+// ⚠️ 前缀故意用 `magic-` 而不是更宽的 `magic`：`magic` 会把 magicclient、magical 之类
+// 的第三方标识也认进来，前缀带连字符才是这一族的命名约定。
+*/
+func sessionClientVisible(client, selfID string) bool {
+	c := strings.TrimSpace(client)
+	if c == "" {
+		return false // 匿名 = 手工跑 / CI / 旧记录：不混进本应用列表
+	}
+	if c == strings.TrimSpace(selfID) {
+		return true // ①
+	}
+	if strings.HasPrefix(c, "magic-") {
+		return true // ②
+	}
+	for _, allowed := range extraSessionClients {
+		if c == allowed {
+			return true // ③
+		}
+	}
+	return false
+}
+
 // handleSessions 会话登记表（core 的 `--sessions`）：列表页的「最近会话」用它。
 // 与 /desk/asks 的区别：asks 是**本进程正在跑的轮次**（内存里），sessions 是 core 的
 // 持久登记表（跨进程、含已结束的）。
@@ -690,11 +932,17 @@ var extraSessionClients = []string{"magic-test", "magic-agent"}
 // （~/.magic-agent/sessions），直接跑 CLI（匿名）、CI、别的 magic-* 应用都在往里写 ——
 // 原样转发等于把别人的任务混进本应用的会话列表。认客户端靠 core 落的 Record.Client
 // （本插件在 /desk/ask 时注入自己的 AppID；掌天瓶桌面壳注入 magic-test）。
-// 放行名单见 extraSessionClients（2026-10-15 起，不再是「只认自己」）。
+// 放行判据见 sessionClientVisible（2026-10-26 起按**同族前缀**判，不再认死名字）。
 func (s *Service) handleSessions(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
 	defer cancel()
-	out, err := newCoreCmd(ctx, s.opts.MagicAgent, "--sessions").Output()
+	/* 短 TTL 缓存 + 单飞（见 sessions_cache.go）：列表页是轮询驱动的，而这里每次都 spawn
+	   一个 core 进程 —— 实测同一个 core 直连 20ms、经本插件 200~900ms，10 并发各 1.6s。
+	   缓存的是 core 的**原始输出**，所以下面按 selfID 过滤仍然逐请求做（每个实例的
+	   AppID 不同，缓存过滤结果会让第二个实例看到别人的列表）。 */
+	out, err := s.sessCache.get(ctx, sessionsTTL(), func(ctx context.Context) ([]byte, error) {
+		return newCoreCmd(ctx, s.opts.MagicAgent, "--sessions").Output()
+	})
 	if err != nil {
 		writeErr(w, http.StatusBadGateway,
 			fmt.Sprintf("%s --sessions 失败：%v", s.opts.MagicAgent, err))
@@ -710,17 +958,18 @@ func (s *Service) handleSessions(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write(out)
 		return
 	}
-	allowed := map[string]bool{s.opts.Profile.AppID(): true}
-	for _, c := range extraSessionClients {
-		allowed[c] = true
-	}
+	selfID := s.opts.Profile.AppID()
 	mine := make([]map[string]any, 0, len(rows))
 	for _, row := range rows {
-		if c, _ := row["client"].(string); allowed[c] {
+		c, _ := row["client"].(string)
+		if sessionClientVisible(c, selfID) {
 			mine = append(mine, row)
 		}
 	}
-	writeJSON(w, http.StatusOK, mine)
+	/* 按会话折叠多轮记录（见 sessions_fold.go）：411 行里 302 行是同一会话的其它轮次，
+	   列表是**会话**视图，一屏也只画 60 行 —— 「最新那条会话排不进去」正是折叠前的问题。
+	   顺序在过滤之后：可见性逐行判（只看 client），折叠再按 session_id 归并，两步互不干扰。 */
+	writeJSON(w, http.StatusOK, foldSessionRuns(mine))
 }
 
 // handleSessionMessages 「看历史」持久化落盘的会话事件（`GET /desk/session/{id}/messages`）。
@@ -1090,6 +1339,8 @@ func (s *Service) handleSessionTitle(w http.ResponseWriter, r *http.Request, id
 		writeErr(w, http.StatusInternalServerError, "保存标题失败："+err.Error())
 		return
 	}
+	// 改名后列表里的标题要立刻变（见 sessions_cache.go）。
+	s.invalidateSessionsCache()
 	t := strings.TrimSpace(body.Title)
 	if t == "" {
 		t = session.TitleFor(id)
@@ -1145,6 +1396,10 @@ func (s *Service) handleSessionTitleSummarize(w http.ResponseWriter, r *http.Req
 		writeErr(w, http.StatusBadGateway, "core 回的归纳结果不是 JSON："+truncateForMsg(string(out)))
 		return
 	}
+	/* 归纳出了新标题 → 列表要立刻换（见 sessions_cache.go）。这条尤其重要：客户端
+	   补归纳是「列表画完之后逐条异步打」的（移动端 ensureTitle），如果缓存不失效，
+	   归纳结果要等一个 TTL 才反映到列表上，用户会以为没生效。 */
+	s.invalidateSessionsCache()
 	writeJSON(w, http.StatusOK, res)
 }
 
@@ -1173,6 +1428,9 @@ func truncateForMsg(s string) string {
 // 还没拿到轮次 id」）。
 func (s *Service) handleSessionStop(w http.ResponseWriter, r *http.Request, id string) {
 	res, err := session.Stop(id)
+	/* 停会话改了登记表的 state → 列表必须立刻反映（否则用户看到「停了但还在跑」
+	   停留一个 TTL）。见 sessions_cache.go。缓存没建立时这一步是空操作。 */
+	s.invalidateSessionsCache()
 	if err != nil {
 		writeErr(w, http.StatusNotFound, fmt.Sprintf("停止会话 %s 失败：%v", id, err))
 		return
@@ -1202,6 +1460,8 @@ func (s *Service) handleSessionDelete(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	res, err := session.Delete(id)
+	// 删掉了一条 → 列表必须立刻反映（见 sessions_cache.go）。
+	s.invalidateSessionsCache()
 	if err != nil {
 		writeErr(w, http.StatusBadRequest, fmt.Sprintf("删除会话 %s 失败：%v", id, err))
 		return
@@ -1598,6 +1858,18 @@ func (s *Service) handleModules(w http.ResponseWriter, r *http.Request) {
 //  2. **凭据服务端注入**：profile 里的 backend.token 由插件加进请求头，不进浏览器。
 //  3. **支持流式**：项目的后端可能用 SSE 推进度（magic-test 的派发流就是），
 //     所以用 ReverseProxy + 立即 flush，不缓冲整段响应。
+//
+// routeAPI 是 /api/* 的总入口：工作台页面发来的走工作台反代，其余走项目后端转发。
+func (s *Service) routeAPI(w http.ResponseWriter, r *http.Request) {
+	if spec, port, ok := s.workbenchFor(r); ok {
+		/* 路径原样交给工作台（'/api/…' 就是工作台的 '/api/…'）：serveWorkbench 的第三个参数
+		   是「要改写成什么路径」，传空 = 不改写。 */
+		s.serveWorkbench(w, r, spec, port, "")
+		return
+	}
+	s.guard(s.handleProjectAPI)(w, r)
+}
+
 func (s *Service) handleProjectAPI(w http.ResponseWriter, r *http.Request) {
 	target := strings.TrimSpace(s.opts.Profile.Backend.URL)
 	if target == "" || s.backend == nil {
@@ -2088,6 +2360,17 @@ type askRequest struct {
 	// Serial 是否参与「同一 workspace 单槽」串行（nil / true = 参与）。
 	// 客户端「并行模式」显式传 false；服务端仍会套一层全局并发上限。
 	Serial *bool `json:"serial,omitempty"`
+	/* Mode 任务模式（2026-10-26，只增）：**每个会话提交都过这一道**。
+	   "auto"     = 由服务端判「本轮与同空间运行中的任务是否冲突」再裁决串行/并行；
+	   "parallel" = 一律并行，不判定；
+	   "serial"   = 同空间单槽串行，不判定；
+	   空 / 其它  = 沿用 Serial 的老语义（老客户端一行不改也保持原有行为）。
+	 两者同时给时**以 Mode 为准**（用户选的那个说了算，Serial 只当缺省回退）。 */
+	Mode string `json:"mode,omitempty"`
+	/* JudgeEngine / JudgeModel 判定用哪个引擎（前端传用户配的「建议引擎」）。
+	   空 = core 默认 llm。判定预算是异步的，提交侧不等待（见 jobs_auto.go）。 */
+	JudgeEngine string `json:"judgeEngine,omitempty"`
+	JudgeModel  string `json:"judgeModel,omitempty"`
 }
 
 // teamRequest 团队模式的请求体（POST /desk/ask 的 team 字段）。
@@ -2366,7 +2649,17 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 
 	ctx := r.Context()
 	run, ok := s.jobs.waitStarted(ctx, job, func(pos int) {
-		send("queued", map[string]any{"job": job.ID, "state": JobQueued, "position": pos})
+		ev := map[string]any{"job": job.ID, "state": JobQueued, "position": pos}
+		/* 自动模式的判定结论随排队事件一起下发（2026-10-26，只增字段）：客户端要能
+		   当场说「为什么在排队」，否则只会显示一句「等待中」，看起来像模式开关没生效。
+		   判定是异步的，job 是提交时的副本 —— 这里重新取一次最新状态。 */
+		if cur := s.jobs.get(job.ID); cur != nil {
+			if cur.Auto != nil {
+				ev["auto"] = cur.Auto
+			}
+			ev["serial"] = cur.Serial
+		}
+		send("queued", ev)
 	})
 	if !ok {
 		/* 排队期间客户端断开：匿名提交（没有 request_id）没人会再来接，直接撤掉；
@@ -2503,6 +2796,24 @@ func (s *Service) prepareAsk(req askRequest) (string, []string, int, error) {
 	return engine, args, http.StatusOK, nil
 }
 
+/* workspaceLockEnv 决定给 core 传什么工作空间锁开关（2026-10-26）。
+ *
+ * 背景：core 的锁**默认生效**。于是"串行"是免费的（什么都不传），"并行"必须显式关。
+ * 这条以前是反的（只有传 `=1` 才开），语义一翻转就必须集中在一处 —— 散在 startAsk
+ * 里没人测得出来，而这正是会「看着开了、实际没生效」的那种 bug。
+ *
+ * 返回值：nil = 不追加任何环境变量（走 core 默认 = 串行）；否则是一条 K=V。
+ *   · serial 未指定（nil）→ 按串行处理，与 jobs.go 的默认值同一口径；
+ *   · serial=false → 显式 `=0`，让同空间的并行作业真能并行；
+ *   · serial=true → nil（不必冗余地写 `=1`，core 的默认就是开）。
+ */
+func workspaceLockEnv(serial *bool) []string {
+	if serial == nil || *serial {
+		return nil
+	}
+	return []string{session.EnvWorkspaceLock + "=0"}
+}
+
 /*
 	startAsk 真正拉起 core 并开始吸收 stdout（不绑任何 HTTP 请求）。
 
@@ -2515,17 +2826,15 @@ func (s *Service) startAsk(req askRequest, engine string, args []string, source
 	cmd := newCoreCmd(ctx, s.opts.MagicAgent, args...)
 	/* 两个「谁发起的」维度随环境变量传给 core，落到会话登记表：
 	   · EnvSource  设备形态（mobile / pc）—— 按请求 Origin 判定，列表页显示设备标志；
-	   · EnvClient  发起方应用（本插件的 AppID）—— 列表页据此**只显示本客户端发起的会话**。
-	   工作空间锁（选入式，见 internal/session/workspace_lock.go）**只对串行作业注入**：
-	   core 在 Begin 时先抢锁再写 running，让直接跑 CLI 的进程也参与同一套串行；
-	   并行作业注入了锁就会在同空间的 core Begin 处重新排队，把「并行」架空 ——
-	   模式互斥的裁决只在队列这一层做（jobs.go dispatch）。 */
-	cmd.Env = append(os.Environ(),
+	   · EnvClient  发起方应用（本插件的 AppID）—— 列表页据此**只显示本客户端发起的会话。
+	   工作空间锁按 workspaceLockEnv 的裁决传（串行 = 不传，并行 = 显式关）——
+	   细节与所以然都在那个函数上，别在这里再写一份判据。 */
+	/* cleanHostEnv：摘掉宿主 IDE 塞进来的 node 垫片与假命令目录 —— 否则引擎子进程
+	   连不上宿主的 broker，每条任务都 failed（2026-10-26 真机，见 hostenv.go）。 */
+	cmd.Env = append(cleanHostEnv(os.Environ()),
 		session.EnvSource+"="+source,
 		session.EnvClient+"="+s.opts.Profile.AppID())
-	if req.Serial == nil || *req.Serial {
-		cmd.Env = append(cmd.Env, session.EnvWorkspaceLock+"=1")
-	}
+	cmd.Env = append(cmd.Env, workspaceLockEnv(req.Serial)...)
 	stdin, err := cmd.StdinPipe()
 	if err != nil {
 		return nil, fmt.Errorf("stdin pipe: %w", err)
@@ -2848,6 +3157,13 @@ func (s *Service) handleStatic(w http.ResponseWriter, r *http.Request) {
 		writeErr(w, http.StatusInternalServerError, err.Error())
 		return
 	}
+	/* 工作台在根路径下跑（见 apps.go 的文件头）：页面用 '/api/…' 这种根相对地址，
+	   它们带着 Referer=…/workbench/{id}/，先转给工作台 —— 必须先于下面所有静态判定，
+	   否则 '/api/*' 会被当成 UI 目录里的文件（404），页面能出来、数据全空。 */
+	if spec, port, ok := s.workbenchFor(r); ok {
+		s.serveWorkbench(w, r, spec, port, "")
+		return
+	}
 	p := strings.TrimPrefix(r.URL.Path, "/")
 	if p == "" {
 		// 手机浏览器打开根地址 → 直接给移动端界面（/m/）。