magic-agent 1.0.46 → 1.0.108

package/internal/client/service.go

@@ -42,7 +42,7 @@ import (
  */
 
 // RequiredContractVersion 本插件能解析的 core 契约版本。
-const RequiredContractVersion = 1
+const RequiredContractVersion = 2
 
 // requiredFeatures 插件依赖的 core 通道能力。缺任何一个都不能工作：
 // 没有 events 就没有带游标的事件流，没有 control 就无法打断与回审批。
@@ -85,18 +85,44 @@ type Service struct {
 	// 见 browse.go —— 它让 iframe 的流量走**桌面端网络**，而不是手机直连。
 	browseOnce sync.Once
 	browseHTTP *http.Client
+
+	// 需求自动归纳的调度状态（每工作区一个防抖计时器，见 requirements.go）。
+	reqAuto reqAuto
 }
 
 // Contract core `--contract` 里本插件关心的部分。
 type Contract struct {
-	ContractVersion int      `json:"contractVersion"`
-	Features        []string `json:"features"`
-	Engines         []struct {
+	ContractVersion int `json:"contractVersion"`
+	// Version core 自身版本（2026-10-22，core 只增字段）。
+	// 客户端「我的」页显示它 —— 界面是 `/m/` 从桌面端远程加载的，页面本身不带版本，
+	// 真正该告诉用户的是「连着的这份 magic-agent 是哪一版」。老 core 没有该字段 → 空。
+	Version  string   `json:"version,omitempty"`
+	Features []string `json:"features"`
+	Engines  []struct {
 		Engine       string   `json:"engine"`
 		OK           bool     `json:"ok"`
 		Bin          string   `json:"bin"`
 		Capabilities []string `json:"capabilities"`
 	} `json:"engines"`
+	// TeamRoles 团队角色清单（2026-10-22，core 只增字段）。
+	// 客户端「团队模式」页据此渲染角色路由行（缩进在所属类别下）；老 core 没有这个字段 → 空，
+	// 插件对 role:<name> 就只做格式校验，不拒未知名字（交给 core 裁决）。
+	TeamRoles []struct {
+		Name string `json:"name"`
+		Kind string `json:"kind"`
+		Duty string `json:"duty"`
+	} `json:"teamRoles"`
+}
+
+// teamRoleNames 角色规范名清单（给 teamFlags 做白名单；空 = 老 core，不校验名字）。
+func (s *Service) teamRoleNames() []string {
+	out := make([]string, 0, len(s.contract.TeamRoles))
+	for _, r := range s.contract.TeamRoles {
+		if n := strings.TrimSpace(r.Name); n != "" {
+			out = append(out, n)
+		}
+	}
+	return out
 }
 
 // New 建服务并做契约校验。
@@ -166,6 +192,10 @@ func (s *Service) Handler() http.Handler {
 	// 按**绝对路径**读文本文件（Markdown / 日志 / 源码）：移动端产物卡「查看」在浮层里阅读。
 	mux.HandleFunc("/desk/path-read", s.guard(s.handlePathRead))
 	mux.HandleFunc("/desk/titles", s.guard(s.handleTitles))
+	// 需求聚合（2026-10-22，见 requirements.go）：读清单 / 手动整理一轮。
+	// 自动归纳不在这里 —— 它是每轮 /desk/ask 收尾后的防抖动作。
+	mux.HandleFunc("/desk/requirements", s.guard(s.handleRequirements))
+	mux.HandleFunc("/desk/requirements/consolidate", s.guard(s.handleRequirementsConsolidate))
 	// 插件目录（magic-shorts / magic-video 两个工程的 CLI）：介绍、安装状态、安装/升级。
 	// 与引擎无关 —— core 不认识它们，所以放在这一层而不是 core 的 --engines 里。
 	mux.HandleFunc("/desk/plugins", s.guard(s.handlePlugins))
@@ -313,13 +343,28 @@ func (s *Service) handleHealth(w http.ResponseWriter, r *http.Request) {
 	// 所以这里的 cwd 就是「桌面默认工作空间」，客户端用它给空 workspace 的会话归类。
 	wd, _ := os.Getwd()
 	writeJSON(w, http.StatusOK, map[string]any{
-		"ok":               true,
-		"contractVersion":  s.contract.ContractVersion,
+		"ok":              true,
+		"contractVersion": s.contract.ContractVersion,
+		// 版本号（2026-10-22）：移动端「我的」页显示「当前连着的 magic-agent 是哪一版」。
+		// 取 core 契约里的 version —— 与 `magic-agent --version` 同一份（ldflags 注入）。
+		// 老 core 没有这个字段 → 空串，界面显示「—」，不编一个假版本。
+		"version":          s.contract.Version,
 		"features":         s.contract.Features,
 		"app":              s.opts.Profile.App.Name,
 		"engines":          len(s.contract.Engines),
 		"defaultWorkspace": wd,
 		"workspacesRoot":   filepath.Dir(wd),
+		// 远程移动端界面在不在（见 handleMobileUI）。
+		// 客户端的闸门页要据此决定「跳远程 /m/ 还是用包里自带的 ui.html」。
+		// 为什么不放在 features 里：features 是**core 的能力位**（s.contract.Features），
+		// 由 core 上报；/m/ 是插件这一层的静态资源，core 根本不知道它。
+		// 为什么不省掉、让客户端自己去 HEAD 一次：多一次往返就是启动路径上多一段等待，
+		// 而且 HEAD 请求在 WebView 里常被记成 ERR_ABORTED 的失败请求（导航抢跑），
+		// 排查时是纯噪音。探活本来就要打这一枪，顺手带一句最省。
+		"remoteUI": s.hasMobileUI(),
+		// 团队角色清单（2026-10-22）：移动端「团队模式」页要按角色配路由，
+		// 角色名不能由客户端硬编码。老 core 没有 teamRoles → null，客户端回落内置清单。
+		"teamRoles": s.contract.TeamRoles,
 	})
 }
 
@@ -331,7 +376,7 @@ func (s *Service) handleContract(w http.ResponseWriter, r *http.Request) {
 // handleEngines 引擎清单（含模型；走 --no-models 的快路径由调用方决定）。
 func (s *Service) handleEngines(w http.ResponseWriter, r *http.Request) {
 	if r.URL.Query().Get("models") == "1" {
-		s.proxyCore(w, r, "--engines")
+		s.proxyEngines(w, r)
 		return
 	}
 	s.proxyCore(w, r, "--engines", "--no-models")
@@ -410,7 +455,8 @@ func (s *Service) handleSessions(w http.ResponseWriter, r *http.Request) {
 //   - 必须带 X-Magic-Token：这是会话数据（包含历史消息文本），没令牌读不到。
 //
 // 本函数同时是 `/desk/session/{id}/{action}` 这条前缀路由的**唯一入口**：
-// `action` 为空或 `messages` 走全量（下面这段），`events` 走增量续读（见 handleSessionEvents）。
+// `action` 为空或 `messages` 走全量（下面这段），`events` 走一次性增量续读
+// （见 handleSessionEvents），`follow` 走 SSE 持续尾随（见 handleSessionFollow）。
 // 为什么在一个 handler 里分派而不再注册一条更具体的 pattern：`/desk/session/` 是**子树匹配**，
 // 后注册的 pattern 并不会自动赢；而带 `{id}` 通配的新式 pattern 需要 Go 1.22+。
 // 在入口处显式分派既不看 Go 版本脸色，也让「有哪些子路径」集中在一处可读。
@@ -453,10 +499,13 @@ func (s *Service) handleSessionMessages(w http.ResponseWriter, r *http.Request)
 	case "events":
 		s.handleSessionEvents(w, r, id)
 		return
+	case "follow":
+		s.handleSessionFollow(w, r, id)
+		return
 	default:
 		// 未知子路径要**明说**，不能默默当全量返回 —— 否则客户端拼错路径时会拿到
 		// 一份看起来正常的全量历史，于是「增量没生效」被当成「增量没实现」。
-		writeErr(w, http.StatusNotFound, "未知子路径："+action+"（可用：messages / events）")
+		writeErr(w, http.StatusNotFound, "未知子路径："+action+"（可用：messages / events / follow）")
 		return
 	}
 	dir, derr := session.DefaultLogDir()
@@ -891,9 +940,10 @@ func parseSessionPath(path string) (id, action string, ok bool) {
 // 三种结果，调用方按 `snapshotRequired` 分流：
 //  1. 无新事件（含 after 正好等于最后一条）→ 200 + 空数组，snapshotRequired=false
 //  2. 有新事件 → 200 + 增量数组，snapshotRequired=false
-//  3. after **超前**于磁盘上的最大 seq → 200 + 空数组，snapshotRequired=**true**
-//     超前只可能是「日志被重置/截断」或「游标来自另一个会话」；两种情况下
-//     增量都不可信，客户端应改拉 `/messages` 全量重建。
+//  3. after **超前**于文件末尾那条的 seq → 200 + 空数组，snapshotRequired=**true**
+//     超前只可能是「日志被重置/截断」或「游标来自另一个会话」（含续跑导致的 seq
+//     回落：游标停在旧轮高位、新轮从 1 数起）；两种情况下增量都不可信，客户端应
+//     改拉 `/messages` 全量重建。
 //
 // 边界：after 省略或为 0 = 全量（等价 /messages，但多带 lastSeq/after 元信息）；
 // after 非数字或超 uint64 → 400（**不静默当 0** —— 那样客户端会以为拿到了增量，
@@ -944,11 +994,238 @@ func (s *Service) handleSessionEvents(w http.ResponseWriter, r *http.Request, id
 		"after":   after,
 		"lastSeq": maxSeq,
 		// 客户端游标比磁盘还新 ⇒ 增量不可信，去拉全量。
-		// ⚠️ 判据是**严格大于**：after == maxSeq 是「已经追平」，那是正常的空增量。
+		// 「还新」= 大于**文件末尾那条**的 seq（不是全文件最大：续跑会让 seq 回落）。
+		// ⚠️ 判据是**严格大于**：after == lastSeq 是「已经追平」，那是正常的空增量。
 		"snapshotRequired": after > maxSeq,
 	})
 }
 
+// follow 的几档节奏。集中在这里是为了「慢在哪、多久收尾」一眼可见（别散落在循环里）。
+const (
+	// followPollEvery 增量读盘的节奏。500ms 是「看起来是实时」与「一条会话一次只读
+	// 几十字节」的折中：读盘走 tailMark 快路径（seek 到上次消费的偏移），
+	// 没有新事件时只 stat + 一次空读。
+	followPollEvery = 500 * time.Millisecond
+	// followPingEvery 心跳：移动网络 / WebView 会把长时间零字节的连接当死连接掐掉
+	// （见 handleAsk 里 2026-10-19 那段报障）。
+	followPingEvery = 10 * time.Second
+	// followStateEvery 查登记表（会话是否已终结）的节奏。走磁盘读全量记录，
+	// 比读日志贵，没必要每 500ms 一次。
+	followStateEvery = 5 * time.Second
+	// followGrace 看到终态后**再多等一会**再收尾。core 写 jsonl 是 32KB 缓冲的追加写
+	// （另有 1s 定时 flush），且 turn_end 落盘与登记表写终态是两个动作 ——
+	// 立刻 end 会把紧随其后的收尾事件截掉。
+	followGrace = 2 * time.Second
+	// followMaxDuration 单条连接的最长寿命：会话还在跑就先 end，客户端重连接着跟。
+	// 避免僵尸连接常驻（也避开反向代理 / 移动网络的空闲上限）。
+	followMaxDuration = 30 * time.Minute
+)
+
+// terminalSessionKind 这些 kind 到了 = 这一轮已经收尾（词表与对话内核
+// client-ui/shared/conv/27-conv-ledger.js 的 TURN_END 同源）。
+func terminalSessionKind(kind string) bool {
+	switch kind {
+	case "turn_end", "turn_failed", "result", "error", "interrupted", "stopped", "end":
+		return true
+	}
+	return false
+}
+
+// terminalSessionState 登记表里「这一轮已经收尾」的状态（interrupted 也算：那一轮的进程
+// 已经结束；idle 是常驻会话的本轮已结束、进程还在等追加 —— 对跟进连接而言同样该收尾，
+// 否则客户端会对着一条已经跑完的会话空等到 30 分钟）。
+func terminalSessionState(st string) bool {
+	switch st {
+	case session.StateDone, session.StateFailed, session.StateCancelled,
+		session.StateInterrupted, session.StateGone, session.StateIdle:
+		return true
+	}
+	return false
+}
+
+// handleSessionFollow `GET /desk/session/{id}/follow?after=<seq>&lean=1`：
+// **持续尾随**一条会话的进度（SSE，跨进程）。
+//
+// 为什么需要它（2026-10-21 报障：「移动端发起的会话在 PC 上看不到进度，反向也一样」）：
+//   - `/desk/asks` 只覆盖**本插件进程里**跑起来的轮次（s.runs 是内存）——
+//     掌天瓶桌面壳直接 exec core，PC 发起的轮次在本插件眼里从来不存在；
+//   - `/desk/session/{id}/events` 是**一次性快照**，各端得自己定轮询节奏：
+//     移动端列表 3s、对话页 5s、PC 右栏 30s 且只刷列表 —— 详情页必然漂移。
+//
+// 所以把「尾随」收进网关：客户端一次连接，服务端按固定节奏增量读盘并推送，
+// 数据源是 core 落的 `~/.magic-agent/sessions/<id>.jsonl`（跨进程共享，谁跑的都看得到）。
+//
+// 帧格式与 `/desk/ask` 一致（各端已有 SSE 解析器，无需新代码）：
+//
+//	event: open      data: {session, after}                连接建立（after = 起始游标）
+//	data: <事件>                                             增量事件，一条一帧
+//	event: snapshot  data: {session, after, lastSeq}        游标超前（日志被重置/换会话）→ 重拉 /messages
+//	event: end       data: {session, after, state, reason}  收尾（state 为登记表状态，可能为空）
+//	: ping                                                  心跳注释帧（客户端忽略）
+//
+// ⚠️ 每轮都重新 ResolveLogID：run_id → session_id 的改名发生在会话**进行中**
+// （引擎吐出 session_id 后 writer 把 <run_id>.jsonl 改名）。只解一次会在改名后
+// 一直读老路径 —— 表现是「进度停在引擎吐 id 的那一刻」。
+func (s *Service) handleSessionFollow(w http.ResponseWriter, r *http.Request, id string) {
+	var after uint64
+	afterRaw := strings.TrimSpace(r.URL.Query().Get("after"))
+	if afterRaw != "" {
+		n, err := strconv.ParseUint(afterRaw, 10, 64)
+		if err != nil {
+			writeErr(w, http.StatusBadRequest, "after 必须是非负整数（收到 "+strconv.Quote(afterRaw)+"）")
+			return
+		}
+		after = n
+	}
+	dir, derr := session.DefaultLogDir()
+	if derr != nil {
+		writeErr(w, http.StatusInternalServerError, "读历史失败：找不到历史目录："+derr.Error())
+		return
+	}
+	lean := queryLean(r)
+	id = session.ResolveLogID(dir, id)
+	/* 既没日志、登记表里也没这条 id ⇒ 404 说清楚（拼错 id 时别让客户端白等 30 分钟）。
+	   ⚠️ 反过来的形态（登记表有、日志还没建）**必须放行**：core 是先写登记表、
+	   后开日志文件，follow 要等着 —— 这正是「刚发起就看进度」的时刻。 */
+	if !session.HasSessionLog(dir, id) {
+		_, found, ferr := session.Find(id)
+		if ferr != nil {
+			writeErr(w, http.StatusInternalServerError, "读会话登记表失败："+ferr.Error())
+			return
+		}
+		if !found {
+			writeErr(w, http.StatusNotFound, "没有这条会话："+id)
+			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{"session": id, "after": after})
+
+	var termSeen bool
+	lastState := ""
+	// read 拉一次增量并推送；返回「这次有没有新事件」。
+	read := func() bool {
+		cur := session.ResolveLogID(dir, id)
+		var evs []map[string]any
+		var maxSeq uint64
+		var err error
+		if lean {
+			evs, maxSeq, err = session.ReadSessionLogAfterLean(dir, cur, after, mapSeqOf, sessionEventMapFromJSON)
+		} else {
+			evs, maxSeq, err = session.ReadSessionLogAfter(dir, cur, after, mapSeqOf, sessionEventMapFromJSON)
+		}
+		if err != nil {
+			/* 读失败**不掐连接**：磁盘抖动 / 文件正在改名（rename 与 open 竞态）
+			   都只该少一拍，客户端下一拍就能补上。 */
+			return false
+		}
+		if after > maxSeq {
+			// 游标超前于磁盘：日志被重置 / 游标来自另一个会话 ⇒ 让客户端重拉全量。
+			send("snapshot", map[string]any{"session": cur, "after": after, "lastSeq": maxSeq})
+			after = maxSeq
+		}
+		if len(evs) == 0 {
+			return false
+		}
+		if lean {
+			evs = leanSessionEvents(evs)
+		}
+		for _, ev := range evs {
+			b, _ := json.Marshal(ev)
+			fmt.Fprintf(w, "data: %s\n\n", b)
+			if terminalSessionKind(eventKind(ev)) {
+				termSeen = true
+			}
+		}
+		// maxSeq 是**文件末尾那条**的 seq（不是本批的，也不是全文件最大 ——
+		// 续跑会让 seq 回落），直接当新游标不会漏，也不会停在高位。
+		after = maxSeq
+		if flusher != nil {
+			flusher.Flush()
+		}
+		return true
+	}
+
+	read() // 首屏：不等到第一个 tick 才给数据
+	// 一上来就是终态（打开一条早就结束的会话）时不必等 grace —— 首屏已经把整段
+	// 历史推出去了，下一拍补一次空读就收尾。
+	if rec, found, err := session.Find(id); err == nil && found {
+		lastState = rec.State
+		if terminalSessionState(rec.State) {
+			termSeen = true
+		}
+	}
+	poll := time.NewTicker(followPollEvery)
+	defer poll.Stop()
+	ping := time.NewTicker(followPingEvery)
+	defer ping.Stop()
+	deadline := time.NewTimer(followMaxDuration)
+	defer deadline.Stop()
+
+	var endAt time.Time // 非零 = 已看到终态，等 grace 补齐后收尾
+	if termSeen {
+		endAt = time.Now()
+	}
+	polls := 0
+	stateEveryTicks := int(followStateEvery / followPollEvery)
+	if stateEveryTicks < 1 {
+		stateEveryTicks = 1
+	}
+	finish := func(reason string) {
+		send("end", map[string]any{
+			"session": id, "after": after, "state": lastState, "reason": reason,
+		})
+	}
+	for {
+		select {
+		case <-r.Context().Done():
+			return
+		case <-deadline.C:
+			finish("max_duration")
+			return
+		case <-ping.C:
+			fmt.Fprint(w, ": ping\n\n")
+			if flusher != nil {
+				flusher.Flush()
+			}
+		case <-poll.C:
+			read()
+			polls++
+			// 终态一旦出现就每拍都查（要尽快收尾）；平时 5s 查一次登记表。
+			if termSeen || polls%stateEveryTicks == 0 || !endAt.IsZero() {
+				if rec, found, err := session.Find(id); err == nil && found {
+					lastState = rec.State
+					if terminalSessionState(rec.State) {
+						termSeen = true
+					}
+				}
+			}
+			if termSeen && endAt.IsZero() {
+				endAt = time.Now().Add(followGrace)
+			}
+			if !endAt.IsZero() && !time.Now().Before(endAt) {
+				read() // 最后一补：把 grace 期间落盘的收尾行拿走
+				finish("terminal")
+				return
+			}
+		}
+	}
+}
+
 // mapSeqOf 从解析后的 map 里取 seq。
 //
 // ⚠️ json.Unmarshal 进 `map[string]any` 时数字一律变 float64（除非开了 UseNumber），
@@ -1089,19 +1366,183 @@ func (s *Service) handleAsks(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, items)
 }
 
-// proxyCore 跑一条只读的 core 命令（--contract / --engines）并把 stdout 原样转发。
-func (s *Service) proxyCore(w http.ResponseWriter, r *http.Request, args ...string) {
-	ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
+// proxyCoreTimeout 插件侧等 core 的上限。
+//
+// ⚠️ 必须**明显大于** core 自己的模型探测超时（agent.DefaultModelProbeTimeout = 30s）：
+// 之前两边都是 30s，core 还在收尾时父进程就把它杀了 → 前端拿到 502 或干脆卡住。
+// 这里留 15s 余量（版本探测 5s + 收尾），超时统一按 504 报给客户端。
+const proxyCoreTimeout = 45 * time.Second
+
+// errCoreTimeout core 命令超时的哨兵（errors.Is 判定用）。
+var errCoreTimeout = errors.New("core 命令超时未返回")
+
+// runCore 跑一条只读的 core 命令，保证**有界返回**。
+func (s *Service) runCore(ctx context.Context, args ...string) ([]byte, error) {
+	ctx, cancel := context.WithTimeout(ctx, proxyCoreTimeout)
 	defer cancel()
-	out, err := exec.CommandContext(ctx, s.opts.MagicAgent, args...).Output()
+	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	/* WaitDelay 是有界返回的最后一道保险：exec 给 Stdout/Stderr 建的是内部管道，
+	   只要 core 的某个后代进程（引擎 CLI 的 node worker）还握着写端，Wait 就永远不返回 ——
+	   症状正是「弹层永远停在正在探测引擎与模型…」。设了 WaitDelay 后，ctx 到期再等这么久
+	   就关闭管道并返回 ErrWaitDelay，handler 一定能写出响应。 */
+	cmd.WaitDelay = 5 * time.Second
+	out, err := cmd.Output()
 	if err != nil {
-		writeErr(w, http.StatusBadGateway, fmt.Sprintf("%s %s 失败：%v", s.opts.MagicAgent, strings.Join(args, " "), err))
-		return
+		if ctx.Err() != nil || errors.Is(err, exec.ErrWaitDelay) {
+			return nil, fmt.Errorf("%w（%s）", errCoreTimeout, proxyCoreTimeout)
+		}
+		return nil, err
 	}
+	return out, nil
+}
+
+// writeCoreJSON 原样转发 core 的 stdout。
+func writeCoreJSON(w http.ResponseWriter, out []byte) {
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	_, _ = w.Write(out)
 }
 
+// proxyCore 跑一条只读的 core 命令（--contract / --engines）并把 stdout 原样转发。
+func (s *Service) proxyCore(w http.ResponseWriter, r *http.Request, args ...string) {
+	out, err := s.runCore(r.Context(), args...)
+	if err != nil {
+		code := http.StatusBadGateway
+		if errors.Is(err, errCoreTimeout) {
+			code = http.StatusGatewayTimeout
+		}
+		writeErr(w, code, fmt.Sprintf("%s %s 失败：%v", s.opts.MagicAgent, strings.Join(args, " "), err))
+		return
+	}
+	writeCoreJSON(w, out)
+}
+
+// enginesCacheTTL 兜底缓存的有效期：过期就不再拿旧清单充数（引擎可能已卸载 / 换了账号）。
+const enginesCacheTTL = 24 * time.Hour
+
+// enginesCachePath 探测结果的兜底缓存（与其他客户端状态同在 ~/.magic-agent）。
+func enginesCachePath() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return "", fmt.Errorf("解析家目录失败：%v", err)
+	}
+	return filepath.Join(home, ".magic-agent", "engines-cache.json"), nil
+}
+
+// saveEnginesCache 把一次成功的 --engines 输出原样落盘（tmp + rename，避免读到半个文件）。
+// 只做尽力而为：写不进去不影响本次响应。
+func saveEnginesCache(out []byte) {
+	if !json.Valid(out) {
+		return
+	}
+	/* 一个可用引擎都没有的结果没有兜底价值，别拿它覆盖上一次的好清单
+	   （否则「这次全挂了」会把兜底也一起弄坏）。 */
+	var rows []struct {
+		OK bool `json:"ok"`
+	}
+	if json.Unmarshal(out, &rows) != nil {
+		return
+	}
+	anyOK := false
+	for _, row := range rows {
+		if row.OK {
+			anyOK = true
+			break
+		}
+	}
+	if !anyOK {
+		return
+	}
+	p, err := enginesCachePath()
+	if err != nil {
+		return
+	}
+	if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+		return
+	}
+	tmp := p + ".tmp"
+	if err := os.WriteFile(tmp, out, 0o600); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, p)
+}
+
+// loadEnginesCache 读上次成功的清单；过期 / 损坏都当没有。
+func loadEnginesCache() ([]byte, time.Time, bool) {
+	p, err := enginesCachePath()
+	if err != nil {
+		return nil, time.Time{}, false
+	}
+	st, err := os.Stat(p)
+	if err != nil || time.Since(st.ModTime()) > enginesCacheTTL {
+		return nil, time.Time{}, false
+	}
+	out, err := os.ReadFile(p)
+	if err != nil || !json.Valid(out) {
+		return nil, time.Time{}, false
+	}
+	return out, st.ModTime(), true
+}
+
+// enginesProbeRunning 后台重探的 single-flight 标记：同一时刻只跑一个，
+// 避免用户反复开关弹层时叠出一堆 core 进程。
+var (
+	enginesProbeMu      sync.Mutex
+	enginesProbeRunning bool
+)
+
+// probeEnginesAsync 后台重探并把结果写进缓存（下次请求就能直接看到新的）。
+//
+// ⚠️ 必须用 context.Background()：请求此时已经用缓存响应完并结束了，
+// r.Context() 已被取消，拿它去跑 core 会立刻被杀。
+func (s *Service) probeEnginesAsync() {
+	enginesProbeMu.Lock()
+	if enginesProbeRunning {
+		enginesProbeMu.Unlock()
+		return
+	}
+	enginesProbeRunning = true
+	enginesProbeMu.Unlock()
+	go func() {
+		defer func() {
+			enginesProbeMu.Lock()
+			enginesProbeRunning = false
+			enginesProbeMu.Unlock()
+		}()
+		out, err := s.runCore(context.Background(), "--engines")
+		if err != nil {
+			return
+		}
+		saveEnginesCache(out)
+	}()
+}
+
+// proxyEngines 探测引擎与模型（--engines）。
+//
+// 策略是 stale-while-revalidate：
+//   - 有缓存 → **立刻**返回缓存（带 X-Magic-Engines-Stale），同时后台重探写缓存；
+//   - 没缓存 → 同步探测（45s 上限），成功即写缓存。
+//
+// 这样弹层永远是秒开：用户这次看到的是上次的结果，下一次打开就是新的。
+func (s *Service) proxyEngines(w http.ResponseWriter, r *http.Request) {
+	if cached, at, ok := loadEnginesCache(); ok {
+		w.Header().Set("X-Magic-Engines-Stale", at.Format(time.RFC3339))
+		writeCoreJSON(w, cached)
+		s.probeEnginesAsync()
+		return
+	}
+	out, err := s.runCore(r.Context(), "--engines")
+	if err == nil {
+		saveEnginesCache(out)
+		writeCoreJSON(w, out)
+		return
+	}
+	code := http.StatusBadGateway
+	if errors.Is(err, errCoreTimeout) {
+		code = http.StatusGatewayTimeout
+	}
+	writeErr(w, code, fmt.Sprintf("%s --engines 失败：%v", s.opts.MagicAgent, err))
+}
+
 // askRequest POST /desk/ask 的请求体。
 type askRequest struct {
 	Engine    string `json:"engine"`
@@ -1135,6 +1576,38 @@ type askRequest struct {
 	// 为什么不能只看 Origin：移动端是**加载 /m/ 页面**（与桌面同源）跑起来的，
 	// 同源请求分不出手机还是电脑，所以由客户端显式声明（见 shared/transport-http.js）。
 	Client string `json:"client,omitempty"`
+	// Team 团队模式（2026-10-21）。nil = 关（默认）。
+	//
+	// 为什么整个开关放在请求体、不落进 core 的配置文件：团队模式是**这一轮**的运行
+	// 方式，不是这台机器的属性。开关状态由客户端自己记（localStorage），每轮随 body
+	// 下发 —— core 因此完全无状态，「刚才那条为什么走了团队」在会话登记表里查得到。
+	Team *teamRequest `json:"team,omitempty"`
+}
+
+// teamRequest 团队模式的请求体（POST /desk/ask 的 team 字段）。
+type teamRequest struct {
+	// Routes 类别 → 引擎/模型。空 map / 缺项 = 该类跟随主引擎（五类一致）。
+	Routes map[string]teamRoute `json:"routes,omitempty"`
+	// Parallel 同时跑几个子任务（0 = core 默认 4）。
+	Parallel int `json:"parallel,omitempty"`
+	// PlanOnly 只出计划与任务书，不执行（调试用）。
+	PlanOnly bool `json:"planOnly,omitempty"`
+	// TaskTimeout 单个子任务超时（Go duration 字符串，空 = 按总超时推算）。
+	TaskTimeout string `json:"taskTimeout,omitempty"`
+	// Split 拆解粒度：coarse | standard | fine（空 = core 默认 standard）。
+	Split string `json:"split,omitempty"`
+	// SplitCode 简单代码也拆成独立子任务（nil / false = 由主引擎直接给出）。
+	SplitCode *bool `json:"splitCode,omitempty"`
+	// Adaptive 执行后是否再规划一轮补充任务（nil = core 默认开）。
+	Adaptive *bool `json:"adaptive,omitempty"`
+	// Rules 角色规则覆盖（键 role:<name>，值「这类任务适合什么」）。
+	Rules map[string]string `json:"rules,omitempty"`
+}
+
+// teamRoute 某一类子任务的路由项。
+type teamRoute struct {
+	Engine string `json:"engine,omitempty"`
+	Model  string `json:"model,omitempty"`
 }
 
 // askRun 一次 ask（跑完的还会短时保留，供断线续传补拉终态）。
@@ -1152,6 +1625,11 @@ type askRun struct {
 	   session_id 的事件到达时补写（见 appendEvent）。受 mu 保护。 */
 	session string
 
+	/* workspace 这一轮算在哪个目录（收尾后自动归纳按它定位）。建 run 时定死：
+	   请求带 -w 就用它，没带就用插件自己的 cwd（= core 记录的 cwd，见 handleHealth）。
+	   受 mu 保护只是为了与上面的字段同一把锁，写入只发生一次。 */
+	workspace string
+
 	/* run core 本次运行的 run_id（ready 行里带出）。引擎不吐 session_id 时，
 	   登记表里这条会话只有 run_id，/desk/asks 要把两者都给客户端才能认领。受 mu 保护。 */
 	run string
@@ -1349,6 +1827,28 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 	if req.NoThinking {
 		args = append(args, "--no-thinking")
 	}
+	/* 团队模式（2026-10-21）：开关随请求下发，插件只做「翻译 + 预校验」，
+	   路由规则本身全在 core（internal/team/route.go）—— 两边各判一套迟早会分叉。
+
+	   ⚠️ 顺序要紧：--team 必须在 -p 之前塞进去（这里就在），但更重要的是
+	      **不能**与--idle 语义混：团队模式没有常驻会话（子任务不共享上下文，
+	      主引擎也不是每轮都能续上），core 侧 runTeamAsk 直接忽略 --idle。
+	      这里不删它（core 若将来支持了自然就生效），只在注释里钉住。 */
+	if req.Team != nil {
+		/* 老 core 不认识 --team（exit 2），这里先挡下并**说清楚为什么**：
+		   让用户看到「core 太旧，请升级」比让它跑一轮后报 usage error 好得多。 */
+		if !hasStr(s.contract.Features, FeatureSessionTeam) {
+			writeErr(w, http.StatusNotImplemented,
+				"当前 core 不支持团队模式（缺少 "+FeatureSessionTeam+" 能力位，请升级 magic-agent）")
+			return
+		}
+		teamArgs, terr := teamFlags(req.Team, s.opts.Profile, s.teamRoleNames())
+		if terr != nil {
+			writeErr(w, http.StatusBadRequest, terr.Error())
+			return
+		}
+		args = append(args, teamArgs...)
+	}
 	// 附件：逐个 -a/--attach。这里先做与 core 同口径的校验（普通文件 + 32MB 上限），
 	// 免得把非法路径丢给 core 再让它以 usage error 退出（那时错误更难定位）。
 	for _, a := range req.Attachments {
@@ -1414,6 +1914,11 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 		done:    make(chan struct{}),
 		stderr:  newCappedBuffer(8 << 10),
 		session: strings.TrimSpace(req.Session),
+		/* 这一轮算在哪个工作区（收尾后自动归纳要按它定位）。
+		   请求没带 workspace 时 core 会用它自己的 cwd 记录会话 —— 插件 spawn core 时
+		   不换目录，所以那个 cwd 就是插件自己的 cwd（见 handleHealth 的 defaultWorkspace）。
+		   两处口径必须一致，否则「聊了半天需求页没变」：归纳去的是另一个目录。 */
+		workspace: pinnedWorkspace(req.Workspace),
 	}
 	cmd.Stderr = run.stderr
 	/* 用户这条提问先落进回放缓冲（不进 SSE 直播流）：core 的事件流里没有 user 事件，
@@ -1494,6 +1999,12 @@ func (s *Service) handleAsk(w http.ResponseWriter, r *http.Request) {
 			}
 		}
 		run.finish(code)
+		/* 需求自动归纳（2026-10-22）：一轮收尾后防抖触发（12s 内再来一轮顺延）。
+		   用 run 上记死的 workspace，不重新读 cwd —— 归纳必须落在**这一轮聊的那个目录**，
+		   而进程 cwd 在这期间可能被 profile 切换（--ui-dir 之类的启动参数不影响，但
+		   以后会有切换空间的功能；钉住是零成本的正确做法）。
+		   放在 finish 之后：先让 /desk/asks 与 SSE 看到本轮结束，再让后台开始整理。 */
+		s.maybeAutoConsolidate(run.workspace)
 		close(run.done)
 		/* 任务结束后**不立刻摘除**：客户端可能在断线重连后在补拉终态
 		   （`GET /desk/ask/{id}/events`），留 askRetention 的时间窗。
@@ -1757,6 +2268,21 @@ func (s *Service) mobileRoot() string {
 	return ""
 }
 
+// hasMobileUI 报「/m/ 现在真的能给出页面吗」。
+//
+// 与 mobileRoot 的区别：那个只回答「目录配在哪」，不看盘上有没有东西。
+// 客户端拿这个字段决定要不要跳 /m/，所以必须验到 index.html 真的存在 ——
+// 只看配置的话，--mobile-dir 指向一个空目录时会告诉客户端「有远程界面」，
+// 它跳过去得到 404，然后卡在一个错误页上（而不是退回包里的界面）。
+func (s *Service) hasMobileUI() bool {
+	root := s.mobileRoot()
+	if root == "" {
+		return false
+	}
+	st, err := os.Stat(filepath.Join(root, "index.html"))
+	return err == nil && !st.IsDir()
+}
+
 // handleMobileUI 远程移动端界面。
 //
 //	/m/            → <mobile>/index.html（页面本身）