magic-agent 2.4.3 → 2.6.3

package/internal/session/status_test.go

@@ -142,3 +142,31 @@ func TestDeleteDropsStatuses(t *testing.T) {
 		t.Fatalf("删除后状态该被清掉，实得 %q", got)
 	}
 }
+
+// TestStatusOfMatchesStatusForAny 快照读取必须与逐条读取**逐字一致**。
+//
+// 为什么单独立一条（2026-10-26）：列表页从 StatusForAny 换成了 StatusSnapshot + StatusOf
+// （逐行调前者会让底层把整张表深拷贝一遍，407 行 = 407 次全表拷贝）。这类「为了性能换一条
+// 取数路径」的改动最容易悄悄改变语义 —— 键优先级（session 优先 / run 兜底）只要漏一处，
+// 列表上的状态就会一部分对、一部分错，而且极难看出来。这里把两者钉成同一个答案。
+func TestStatusOfMatchesStatusForAny(t *testing.T) {
+	withStatusHome(t)
+	now := time.Now()
+	setStatus(Record{RunID: "run-a", SessionID: "sess-a", State: StateIdle, StartedAt: now})
+	setStatus(Record{RunID: "run-b", State: StateRunning, StartedAt: now})
+	snap := StatusSnapshot()
+
+	cases := [][2]string{
+		{"sess-a", "run-a"}, // 两个键都有：取 session
+		{"", "run-b"},       // 只有 run：取 run
+		{"sess-a", "run-b"}, // 撞车：session 优先（与 StatusForAny 同口径）
+		{"nope", "nope2"},   // 都没有：空
+		{"", ""},            // 空 id：空
+	}
+	for _, c := range cases {
+		want := StatusForAny(c[0], c[1])
+		if got := StatusOf(snap, c[0], c[1]); got != want {
+			t.Fatalf("StatusOf(%q,%q) = %q，StatusForAny 却是 %q", c[0], c[1], got, want)
+		}
+	}
+}

package/internal/session/title.go

@@ -133,6 +133,22 @@ func TitleForAny(sessionID, runID string) string {
 	return m[strings.TrimSpace(runID)]
 }
 
+// TitleSnapshot 取整张标题表的**只读快照**，供批量读取（列表页）用。
+//
+// 与 StatusSnapshot 同一个理由（2026-10-26）：TitleForAny 每次都会让 loadTitles()
+// 把整张表深拷贝一份（缓存不能交给调用方乱改）。列表页逐行调它，407 行就是 407 次
+// 全表拷贝 —— 而它要的只是一个 O(1) 的查表。这里拷一次，调用方自己按 id 取。
+func TitleSnapshot() map[string]string { return Titles() }
+
+// TitleOf 从快照里取一条会话的标题：**session_id 优先，其次 run_id** ——
+// 与 TitleForAny 同口径，只是不再重复加载表。
+func TitleOf(snapshot map[string]string, sessionID, runID string) string {
+	if t := snapshot[strings.TrimSpace(sessionID)]; t != "" {
+		return t
+	}
+	return snapshot[strings.TrimSpace(runID)]
+}
+
 // AdoptTitle 把标题从 run_id 迁到 session_id（幂等），并**清掉那个 run_id 键**。
 //
 // 只在新键**为空**时搬：用户可能已经手动重命名过（那就是权威值），不能被旧键覆盖回去。

package/internal/session/title_test.go

@@ -296,3 +296,29 @@ func TestSummarizeCachedAcrossKeys(t *testing.T) {
 		t.Fatal("命中时应把标题迁到 session_id（否则下一轮又要重算）")
 	}
 }
+
+// TestTitleOfMatchesTitleForAny 快照读取必须与逐条读取**逐字一致**（理由见 status_test.go
+// 的 TestStatusOfMatchesStatusForAny：列表页为省掉逐行全表拷贝换了取数路径）。
+func TestTitleOfMatchesTitleForAny(t *testing.T) {
+	withTitleHome(t)
+	if err := SetTitle("sess-a", "会话标题"); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetTitle("run-b", "只按 run 存的"); err != nil {
+		t.Fatal(err)
+	}
+	snap := TitleSnapshot()
+
+	cases := [][2]string{
+		{"sess-a", "run-b"}, // 撞车：session 优先
+		{"", "run-b"},       // 只按 run
+		{"nope", "nope"},    // 都没有
+		{"", ""},            // 空 id
+	}
+	for _, c := range cases {
+		want := TitleForAny(c[0], c[1])
+		if got := TitleOf(snap, c[0], c[1]); got != want {
+			t.Fatalf("TitleOf(%q,%q) = %q，TitleForAny 却是 %q", c[0], c[1], got, want)
+		}
+	}
+}

package/internal/session/workspace_lock.go

@@ -3,6 +3,7 @@ package session
 import (
 	"crypto/sha1"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -13,25 +14,51 @@ import (
 	"github.com/darren/magic-agent/internal/agent"
 )
 
-/* ── 工作空间串行锁（2026-10-23，多客户端串行的一部分）──
+/* ── 工作空间串行锁（2026-10-23 起；2026-10-26 改成「多客户端默认生效」）──
 
-为什么要锁在 core 而不是只靠 magic-client 的调度器：
-  · 同一台桌面上，除了 magic-client 起的轮次，还有人直接跑 `magic-agent -p`；
-  · 多台手机连的是同一个 magic-client，但**进程间**（多个 magic-client 实例）也可能并存。
-调度器只能管自己进程里的队列；一个落在文件系统上的锁才能让「谁先跑」对所有进程一致。
+为什么会存在这件事：**同一个工作空间不能同时跑两个引擎**。
+两个 agent 同时改同一批文件，冲突是必然的；更隐蔽的是同一 session_id 被两端
+同时 resume 时，两边的 sessionWriter 各算各的 seq，同一份 jsonl 里出现成对重号，
+读侧按 `--after seq` 增量续读会把另一条 lane 的事件全滤掉 —— 一端「已完成」、
+另一端永远等不到终态（2026-10-21 用户报障的正是这个）。
 
-为什么是选入式（MAGIC_AGENT_WORKSPACE_LOCK=1）：
-  默认开启会改变 CLI 的既有语义（两条命令并发跑本来是允许的），也会让团队模式的
-  子任务与主任务互相等待。这里只在 magic-client spawn core 时注入该环境变量，
-  团队子任务（ParentRunID 非空）自动跳过。
+为什么锁必须落在 core 而不是只靠某个客户端的调度器：
+  · 能起轮次的地方**不止一个客户端**：桌面壳直接 exec 本 CLI、HTTP 插件排自己的队列、
+    手机连同一个插件、还有人手工 `magic-agent -p` / CI / 别的 magic-* 应用；
+  · 任何进程内的队列都只管得住自己那一份。只有落在**文件系统**上的锁，
+    才能让「谁先跑」对所有进程一致。
+  这就是「magic-agent 本身要支持多客户端」的字面含义：**仲裁在 core，不在各宿主**。
+  宿主可以自己再排一层（为了显示排队位次、让路给别的客户端），但那是**视图与礼貌**，
+  不是正确性的来源 —— 少一个宿主忘了实现，文件就已经被两个进程改了。
 
-锁的形态：<sessions dir>/locks/<sha1(workspace)>.lock，内容 `<pid>\n<unix nano>`。
-  · 用 O_CREATE|O_EXCL 原子创建；
-  · 持锁进程已不在 / 文件超过 staleAfter → 视为陈旧并回收；
-  · 进程退出没来得及删也不会永久堵住（下一步的持有者会按 pid 判死回收）。
+── 2026-10-26 改了什么（原先只在插件起 core 时选入）──
+
+改前：`MAGIC_AGENT_WORKSPACE_LOCK=1` 才生效，且只有 magic-client 注入。
+      于是「壳直接 exec core」这条路**完全绕过**串行 —— 用户实测：手机在跑时，
+      PC 能在同一目录立刻起第二个引擎，两边同时改文件。补在每个宿主里是不收敛的
+      （N 个宿主 = N 份实现，且新宿主天然漏掉）。
+
+改后：**默认生效**，只有显式 `MAGIC_AGENT_WORKSPACE_LOCK=0` 才关。
+      保留关闭开关的理由：那些「本来就允许并发」的用法不该被悄悄改语义 ——
+      跑批、测试、团队模式子任务（它们与主任务同空间，见 Begin 里的 ParentRunID 判断）。
+
+── 等待方要能看见「在等谁」──
+
+锁文件里除 pid 外还记 `client` / `source` / `run_id` / `session_id` / 起始时间。
+原先是 `pid\n时间戳`，等待方只能打一句「有人在跑」——用户看到的是「卡住了」，
+既不知道是手机上那条、也不知道该去停谁。现在 `LockHolder()` 能把持有者读出来，
+`--sessions` 与客户端都能据此显示「等谁」。
+
+锁的形态：`<sessions dir>/locks/<sha1(workspace)>.lock`，JSON 内容（兼容旧的纯文本）。
+  · `O_CREATE|O_EXCL` 原子创建；
+  · 持有进程已不在 / 文件超过 staleAfter → 陈旧，回收；
+  · 进程崩溃没删也不会永久堵住（下一个持有者按 pid 判死回收）。
 */
 
-// EnvWorkspaceLock 打开「工作空间串行锁」的环境变量（值为 "1" 时生效）。
+// EnvWorkspaceLock 开关「工作空间串行锁」的环境变量。
+//
+// 取值语义（2026-10-26 起）：未设置 = **启用**；`0` / `false` / `off` / `no` = 关闭；
+// 其余非空值 = 启用。改前是「必须为 1 才启用」，见文件头「改了什么」。
 const EnvWorkspaceLock = "MAGIC_AGENT_WORKSPACE_LOCK"
 
 // EnvWorkspaceLockWait 等锁上限（Go duration；默认 10m）。
@@ -42,14 +69,33 @@ const (
 	workspaceLockStale = 6 * time.Hour
 )
 
+// LockHolder 锁的持有者信息（等待方 / 列表页用来回答「我在等谁」）。
+type LockHolder struct {
+	PID       int       `json:"pid"`
+	Client    string    `json:"client,omitempty"`   // 发起方应用（如 magic-test / com.magic.test）
+	Source    string    `json:"source,omitempty"`   // 设备形态（mobile | pc）
+	RunID     string    `json:"run_id,omitempty"`   // 占用者那一轮的 run_id
+	SessionID string    `json:"session_id,omitempty"`
+	Engine    string    `json:"engine,omitempty"`
+	Since     time.Time `json:"since"`              // 拿到锁的时刻
+	// Workspace 归一路径（只是为了回报时不用调用方再算一次）。
+	Workspace string `json:"workspace,omitempty"`
+}
+
 // WorkspaceLock 一把已持有的工作空间锁；Release 幂等。
 type WorkspaceLock struct {
 	path string
 	held bool
 }
 
+// workspaceLockEnabled 锁是否启用（默认启用；见 EnvWorkspaceLock 的取值语义）。
 func workspaceLockEnabled() bool {
-	return strings.TrimSpace(os.Getenv(EnvWorkspaceLock)) == "1"
+	switch strings.ToLower(strings.TrimSpace(os.Getenv(EnvWorkspaceLock))) {
+	case "0", "false", "off", "no":
+		return false
+	default:
+		return true
+	}
 }
 
 func workspaceLockWait() time.Duration {
@@ -61,7 +107,12 @@ func workspaceLockWait() time.Duration {
 	return 10 * time.Minute
 }
 
-// lockKey 归一工作空间：空 = 进程 cwd；返回绝对路径 + 哈希文件名。
+// LockKey 归一工作空间：空 = 进程 cwd；返回绝对路径 + 哈希文件名。
+//
+// 导出是因为客户端要自己判断「我这条和它那条是不是同一个目录」——
+// 让它们各写一份归一逻辑，迟早在「尾斜杠算不算同一个」上分叉。
+func LockKey(workspace string) (key, file string) { return workspaceLockKey(workspace) }
+
 func workspaceLockKey(workspace string) (key, file string) {
 	ws := strings.TrimSpace(workspace)
 	if ws == "" {
@@ -75,13 +126,117 @@ func workspaceLockKey(workspace string) (key, file string) {
 	return ws, hex.EncodeToString(sum[:])
 }
 
+// lockDirPath 锁目录（与登记表同目录，见 Dir）。
+func lockDirPath() string {
+	dir := Dir()
+	if dir == "" {
+		return ""
+	}
+	return filepath.Join(dir, "locks")
+}
+
+// lockFilePath 某个 workspace 的锁文件路径（空 = 环境不可用）。
+func lockFilePath(workspace string) string {
+	ld := lockDirPath()
+	if ld == "" {
+		return ""
+	}
+	_, name := workspaceLockKey(workspace)
+	return filepath.Join(ld, name+".lock")
+}
+
+/* ── 锁文件的内容编解码 ────────────────────────────────────────────
+ * 新格式是 JSON（能带持有者身份）。旧格式是两行纯文本 `pid\n纳秒时间`。
+ * 读的时候两种都认 —— 升级途中会有上一个版本留下的锁文件，
+ * 不认它就会把「有人在跑」误判成「锁文件坏了」，进而当成陈旧锁抢过来（两个进程同时跑）。
+ */
+
+// encodeLock 锁文件的正文。
+func encodeLock(h LockHolder) []byte {
+	if h.Since.IsZero() {
+		h.Since = time.Now()
+	}
+	b, err := json.Marshal(h)
+	if err != nil { // 理论上不可达（字段全是可序列化的基本类型）；退化成旧格式也别写坏文件
+		return []byte(fmt.Sprintf("%d\n%d\n", h.PID, h.Since.UnixNano()))
+	}
+	return append(b, '\n')
+}
+
+// decodeLock 解析锁文件正文；两种格式都认。
+func decodeLock(b []byte) LockHolder {
+	trimmed := strings.TrimSpace(string(b))
+	if trimmed == "" {
+		return LockHolder{}
+	}
+	// JSON 形状：以 { 开头。旧格式第一行是纯数字，不会撞。
+	if strings.HasPrefix(trimmed, "{") {
+		var h LockHolder
+		if err := json.Unmarshal([]byte(trimmed), &h); err == nil {
+			return h
+		}
+	}
+	lines := strings.Split(trimmed, "\n")
+	var h LockHolder
+	if len(lines) > 0 {
+		if pid, err := strconv.Atoi(strings.TrimSpace(lines[0])); err == nil {
+			h.PID = pid
+		}
+	}
+	if len(lines) > 1 {
+		if ns, err := strconv.ParseInt(strings.TrimSpace(lines[1]), 10, 64); err == nil && ns > 0 {
+			h.Since = time.Unix(0, ns)
+		}
+	}
+	return h
+}
+
+/* ── 持有者查询（等待方 / 列表页用）────────────────────────────────
+ *  与 acquire 是**只读**的一对：这里绝不创建、绝不回收 —— 回收只在真正要取锁时做
+ *  （见 reapStaleWorkspaceLock）。原因：查询方可能只是个列表页，
+ *  它凭什么替别人判定「那把锁已经死了」然后删掉？判死要取锁方才做的决定。
+ */
+
+// LockHolderFor 读某个 workspace 上当前锁的持有者（没有锁 / 环境不可用 → 0 值）。
+//
+// ⚠️ 不判活、不回收：pid 可能已经死了但文件还在。要不要清理是取锁方的事。
+// 调用方若要「这锁还算不算数」，请自己看 PIDAlive（agent.PIDAlive 与这里同口径）。
+func LockHolderFor(workspace string) (LockHolder, bool) {
+	p := lockFilePath(workspace)
+	if p == "" {
+		return LockHolder{}, false
+	}
+	b, err := os.ReadFile(p)
+	if err != nil {
+		return LockHolder{}, false
+	}
+	h := decodeLock(b)
+	if h.PID <= 0 {
+		return LockHolder{}, false
+	}
+	if ws, _ := workspaceLockKey(workspace); h.Workspace == "" {
+		h.Workspace = ws
+	}
+	if h.Since.IsZero() {
+		// 旧格式没带时间就退回文件 mtime —— 至少能报「占多久了」。
+		if st, err := os.Stat(p); err == nil {
+			h.Since = st.ModTime()
+		}
+	}
+	return h, true
+}
+
+/* ── 取锁 ─────────────────────────────────────────────────────────── */
+
 /*
-AcquireWorkspaceLock 取工作空间锁（阻塞，直到拿到或超时）。
+acquireWorkspaceLock 取工作空间锁（阻塞，直到拿到或超时）。
 
 	o.NoPersist 没关系：锁在 sessions 目录，不依赖会话记录落盘。
 	返回 nil 表示未启用（调用方无需处理）。
+	who 是持有者身份（pid / client / run_id…），写进锁文件供等待方读取；
+	传零值时按本进程 pid 兜底，绝不写一个 pid<=0 的锁（那会被当成陈旧锁立刻回收）。
 */
-func acquireWorkspaceLock(workspace string) (*WorkspaceLock, error) {
+func acquireWorkspaceLock(workspace string, who LockHolder) (*WorkspaceLock, error) {
 	if !workspaceLockEnabled() {
 		return nil, nil
 	}
@@ -95,12 +250,22 @@ func acquireWorkspaceLock(workspace string) (*WorkspaceLock, error) {
 	}
 	ws, name := workspaceLockKey(workspace)
 	path := filepath.Join(lockDir, name+".lock")
+
+	if who.PID <= 0 {
+		who.PID = os.Getpid()
+	}
+	who.Workspace = ws
+	if who.Since.IsZero() {
+		who.Since = time.Now()
+	}
+	body := encodeLock(who)
+
 	deadline := time.Now().Add(workspaceLockWait())
 	announced := false
 	for {
 		f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
 		if err == nil {
-			_, _ = fmt.Fprintf(f, "%d\n%d\n", os.Getpid(), time.Now().UnixNano())
+			_, _ = f.Write(body)
 			_ = f.Close()
 			return &WorkspaceLock{path: path, held: true}, nil
 		}
@@ -111,16 +276,63 @@ func acquireWorkspaceLock(workspace string) (*WorkspaceLock, error) {
 			continue
 		}
 		if time.Now().After(deadline) {
+			/* 超时的报错里带上「谁占着」—— 原来的文案只有工作空间路径，
+			   用户看到的是「等超时了」却不知道该去停谁（手机上那条？还是另一个窗口？）。 */
+			if h, ok := LockHolderFor(workspace); ok {
+				return nil, fmt.Errorf("等待工作空间 %s 上的上一个任务超时（%s，占用者 pid=%d%s%s），可用 %s 调整",
+					ws, workspaceLockWait(), h.PID, lockWhoText(h), lockSinceText(h), EnvWorkspaceLockWait)
+			}
 			return nil, fmt.Errorf("等待工作空间 %s 上的上一个任务超时（%s），可用 %s 调整", ws, workspaceLockWait(), EnvWorkspaceLockWait)
 		}
 		if !announced {
 			announced = true
-			fmt.Fprintf(os.Stderr, "magic-agent: 同一工作空间已有任务在跑，等待其结束（%s）…\n", ws)
+			/* 同理：等待时第一句就交代「在等谁」。这一行是 stderr，
+			   客户端会转给界面（magic-client 的 SSE / 壳的 notice）。 */
+			if h, ok := LockHolderFor(workspace); ok {
+				fmt.Fprintf(os.Stderr, "magic-agent: 同一工作空间已有任务在跑，等待其结束（%s；占用者 pid=%d%s）…\n",
+					ws, h.PID, lockWhoText(h))
+			} else {
+				fmt.Fprintf(os.Stderr, "magic-agent: 同一工作空间已有任务在跑，等待其结束（%s）…\n", ws)
+			}
 		}
 		time.Sleep(workspaceLockPoll)
 	}
 }
 
+// lockWhoText 「谁在占着」的人话后缀：` / 客户端 com.magic.test / 手机`。
+// 没有任何身份信息时返回空串（旧锁文件），调用方据此不加多余的分隔符。
+func lockWhoText(h LockHolder) string {
+	var parts []string
+	if c := strings.TrimSpace(h.Client); c != "" {
+		parts = append(parts, "客户端 "+c)
+	}
+	switch h.Source {
+	case SourceMobile:
+		parts = append(parts, "手机")
+	case SourcePC:
+		parts = append(parts, "电脑")
+	}
+	if len(parts) == 0 {
+		return ""
+	}
+	return " / " + strings.Join(parts, " / ")
+}
+
+// lockSinceText 「占了多久」的人话后缀（读不出时间就给空串）。
+func lockSinceText(h LockHolder) string {
+	if h.Since.IsZero() {
+		return ""
+	}
+	d := time.Since(h.Since)
+	if d < 0 {
+		d = 0
+	}
+	if d < time.Minute {
+		return fmt.Sprintf("，已占用 %d 秒", int(d.Seconds()))
+	}
+	return fmt.Sprintf("，已占用 %d 分", int(d.Minutes()))
+}
+
 // reapStaleWorkspaceLock 回收陈旧锁（pid 已不在 / 文件太老）；返回是否已删。
 func reapStaleWorkspaceLock(path string) bool {
 	st, err := os.Stat(path)
@@ -130,12 +342,12 @@ func reapStaleWorkspaceLock(path string) bool {
 	stale := time.Since(st.ModTime()) > workspaceLockStale
 	if !stale {
 		if b, err := os.ReadFile(path); err == nil {
-			lines := strings.Split(strings.TrimSpace(string(b)), "\n")
-			if len(lines) > 0 {
-				if pid, err := strconv.Atoi(strings.TrimSpace(lines[0])); err == nil {
-					if pid <= 0 || !agent.PIDAlive(pid) {
-						stale = true
-					}
+			/* 两种格式都认（见 decodeLock）：只按旧格式解析的话，
+			   新格式的 JSON 首行是 `{"pid":123,...}`，Atoi 失败 → 判不出死进程 →
+			   一个崩溃留下的锁要等到 6 小时 stale 才回收。 */
+			if h := decodeLock(b); h.PID > 0 {
+				if !agent.PIDAlive(h.PID) {
+					stale = true
 				}
 			}
 		}
@@ -147,6 +359,32 @@ func reapStaleWorkspaceLock(path string) bool {
 	return true
 }
 
+// noteRun 拿到锁之后再补写一次持有者身份（run_id 在取锁时还没生成）。
+//
+// 为什么值得多写一次文件：等待方拿到的线索里，run_id 是**唯一能直接对上
+// `--sessions` 那一行**的键。只有 pid 的话，界面上只能显示一个数字，
+// 用户没法点进去看「到底是谁在跑」，也没法据此决定要不要停掉它。
+// 失败不影响持有（锁已经拿到了，身份信息只是附加价值）。
+func (l *WorkspaceLock) noteRun(runID string) {
+	if l == nil || !l.held || strings.TrimSpace(runID) == "" {
+		return
+	}
+	cur, ok := LockHolderFor("")
+	b, err := os.ReadFile(l.path)
+	if err != nil {
+		return
+	}
+	h := decodeLock(b)
+	if h.PID != os.Getpid() {
+		return // 已不是自己的锁（被别人回收后重取了），不要覆盖
+	}
+	h.RunID = strings.TrimSpace(runID)
+	if ok && cur.RunID == h.RunID {
+		return // 没变化，不重复写
+	}
+	_ = os.WriteFile(l.path, encodeLock(h), 0o600)
+}
+
 // Release 释放锁；只删自己持有的那把（内容里的 pid 对得上）。
 func (l *WorkspaceLock) Release() {
 	if l == nil || !l.held {
@@ -157,8 +395,7 @@ func (l *WorkspaceLock) Release() {
 	if err != nil {
 		return
 	}
-	first := strings.TrimSpace(strings.SplitN(string(b), "\n", 2)[0])
-	if first != strconv.Itoa(os.Getpid()) {
+	if decodeLock(b).PID != os.Getpid() {
 		return
 	}
 	_ = os.Remove(l.path)

package/internal/suggest/suggest.go

@@ -13,7 +13,8 @@
 //     去重、形态校验，挡掉「AI 的回答」冒充「用户的话」。
 //
 // 与 `--summarize-title`（internal/session/title.go::Summarize）的分工：那条把会话首问压成
-// 标题、结果落进标题表；这条只产出一组**临时**建议，不落盘、不缓存 —— 下一轮结束就重算。
+// 标题、结果落进标题表；这条只产出一组**临时**建议，core 侧不落盘 —— 同一轮的重复请求
+// 由 magic-client 插件层缓存（internal/client/suggest.go），下一轮问答换了内容自然重算。
 package suggest
 
 import (
@@ -51,6 +52,12 @@ type Request struct {
 	Engine string
 	// Model 模型标识（空 = 引擎默认）。
 	Model string
+	// FallbackEngine / FallbackModel 用户配的备用引擎（2026-10-24）。
+	//
+	// 主引擎失败时**优先**试它，再落到内置的 llm 兜底；空 = 直接用内置兜底。
+	// 这样界面上「建议引擎」也能配主 / 备，与默认引擎、团队模式同一套语义。
+	FallbackEngine string
+	FallbackModel  string
 	// Count 最多几条（<=0 = DefaultCount）。
 	Count int
 	// Timeout 单次调用超时（<=0 = DefaultTimeout）。
@@ -205,6 +212,21 @@ func Generate(ctx context.Context, in Request) (Result, error) {
 	if err == nil {
 		return res, nil
 	}
+	/* 用户配的备用引擎：优先于内置 llm 兜底（2026-10-24）。它更贴近用户的意图
+	   （例如「建议用 codebuddy，额度不够就换 dsh」），llm 只是最后的保底。 */
+	if fb := strings.TrimSpace(in.FallbackEngine); fb != "" && !strings.EqualFold(fb, name) {
+		if agent.Lookup(fb) != nil {
+			remain := timeout - time.Since(start)
+			if remain < 2*time.Second {
+				remain = 2 * time.Second
+			}
+			fbIn := in
+			fbIn.Model = strings.TrimSpace(in.FallbackModel)
+			if fbRes, ferr := tryGenerate(cctx, fbIn, fb, remain, start); ferr == nil {
+				return fbRes, nil
+			}
+		}
+	}
 	if name == DefaultEngine {
 		return Result{}, err
 	}

package/internal/team/event.go

@@ -6,7 +6,9 @@ package team
 //   · 计划        → 一条 notice（一行提示 + 计划文档路径），任务本身在画布上表现为
 //                  后续的委派卡，不需要一张额外的「计划卡」；
 //   · 每个子任务  → tool_use(name=Task) 开卡 + 带 Parent 的子事件 + tool_result 收卡；
-//   · 降级/汇总   → notice。
+//   · 降级        → `fallback` 帧（2026-10-26）：谁换成了谁，客户端据此把子任务标成
+//                   「备用作答」（以前只有一行 notice，主备到底生效没有无从判断）；
+//   · 汇总        → notice。
 //
 // 于是客户端（三端共用同一份渲染内核）**零改动**就能画出团队模式 —— 它看起来
 // 就是主代理连续委派了几次。要加「计划总览卡」时再补新 kind，那是一次独立的

package/internal/team/execute.go

@@ -153,7 +153,11 @@ func runTask(ctx context.Context, opts Options, plan Plan, t Task, runDir string
 		got.ID, got.Kind, got.Title = t.ID, t.EffectiveKind(), t.Title
 		got.Role = t.Role
 		got.OutputPath = OutputPath(runDir, t.ID)
-		got.Engine, got.Model = eng.Name(), route.Model
+		// 引擎标签以**尝试自己记的**为准：runAttempt 在备用接上时已改成备用那一路，
+		// 这里若再盖回主引擎，用户就看不到「这一行是备用给的」。
+		if got.Engine == "" {
+			got.Engine, got.Model = eng.Name(), route.Model
+		}
 		got.Attempts = attempt
 		r = got
 
@@ -235,7 +239,7 @@ func runAttempt(ctx context.Context, opts Options, t Task, runDir string, route
 		board.setSession(t.ID, id, "")
 	}
 
-	res, err := streamer.Stream(tctx, agent.Request{
+	res, fbInfo, err := agent.StreamWithFallback(tctx, eng, agent.Request{
 		Engine: eng.Name(),
 		Model:  route.Model,
 		// 角色片段追加在主系统提示词之后（见 role.go）；未设角色时与原来一致。
@@ -249,7 +253,11 @@ func runAttempt(ctx context.Context, opts Options, t Task, runDir string, route
 		Permission:        permissionFor(opts, t),
 		PermissionOptions: opts.PermissionOptions,
 		OnSessionID:       setSID,
-		Messages:          []agent.Message{{Role: "user", Content: prompt}},
+		// 主引擎只有过程、没有正文时降级到这一路的备用（额度用尽 / 单模型故障）。
+		// 降级发生时 agent 层已经发过 fallback 帧（下面原样交给子会话）。
+		FallbackEngine: route.FallbackEngine,
+		FallbackModel:  route.FallbackModel,
+		Messages:       []agent.Message{{Role: "user", Content: prompt}},
 	}, func(ev agent.StreamEvent) {
 		if ev.SessionID != "" {
 			setSID(ev.SessionID)
@@ -270,6 +278,12 @@ func runAttempt(ctx context.Context, opts Options, t Task, runDir string, route
 		}
 		board.touch(t.ID, ev)
 	})
+	/* 备用接上了：任务结果如实记成「谁给出的答案」（主备没生效时用户只能看到一个
+	   失败的子任务，分不清是没配还是配了没试）。只改展示字段，State 由下面的
+	   err 决定 —— 备用成功时 err 必然为 nil。 */
+	if fbInfo.Used {
+		r.Engine, r.Model = fbInfo.Engine, fbInfo.Model
+	}
 
 	if err != nil {
 		r.State = TaskFailed
@@ -396,8 +410,7 @@ func completeTask(ctx context.Context, opts Options, eng agent.Engine, route Rou
 	r.Engine, r.Model = eng.Name(), route.Model
 	rctx, cancel := context.WithTimeout(ctx, taskTimeout(opts))
 	defer cancel()
-	runner := &agent.Runner{Engine: eng, Timeout: taskTimeout(opts)}
-	resp, err := runner.Run(rctx, agent.Request{
+	resp, _, err := agent.RunWithFallback(rctx, eng, agent.Request{
 		Engine:            eng.Name(),
 		Model:             route.Model,
 		SystemPrompt:      systemPromptFor(opts, t),
@@ -406,8 +419,10 @@ func completeTask(ctx context.Context, opts Options, eng agent.Engine, route Rou
 		Reasoning:         opts.Reasoning,
 		Permission:        permissionFor(opts, t),
 		PermissionOptions: opts.PermissionOptions,
+		FallbackEngine:    route.FallbackEngine,
+		FallbackModel:     route.FallbackModel,
 		Messages:          []agent.Message{{Role: "user", Content: prompt}},
-	})
+	}, agent.RunOptions{Timeout: taskTimeout(opts)}, nil)
 	r.SessionID = resp.SessionID
 	r.Text = resp.Text
 	collectDeliverables(TaskDir(runDir, t.ID), t.Deliverables, &r)