magic-agent 2.4.3 → 2.6.0

package/internal/requirements/shots_test.go

@@ -0,0 +1,387 @@
+package requirements
+
+// shots_test.go - 「页面完成情况」截图的落盘、文档追加与往返保持。
+//
+// 重点盯三件事：
+//   · 追加截图**不动**用户手改过的内容（只加两行，不整篇重渲染）；
+//   · 归纳重写文档时**保住**截图段（否则用户攒的完成情况会被抹掉）；
+//   · 落盘路径是**正斜杠**（Windows 的反斜杠在 markdown 里是转义符）。
+
+import (
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// fakePNG 造一个最小 PNG（只需要文件头合法，core 不解码像素）。
+func fakePNG() []byte {
+	return append(append([]byte{}, pngMagic...), 0x00, 0x01, 0x02, 0x03)
+}
+
+// 造一篇已存在的功能点文档，返回工作区 id 与文档路径。
+func seedFeature(t *testing.T, module, name string) (string, string) {
+	t.Helper()
+	root := t.TempDir()
+	t.Setenv(EnvDir, filepath.Join(root, "requirements"))
+	id := "ws-abc1234567"
+	dir := filepath.Join(featuresDir(id), module)
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	file := filepath.Join(dir, SlugifyFeature(name)+".md")
+	doc := RenderDoc(name, Doc{
+		Desc:        "一个功能点",
+		Points:      []string{"要点一"},
+		Conclusions: []string{"结论一"},
+		Final:       "**目标**：一个功能点",
+	})
+	if err := os.WriteFile(file, []byte(doc), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return id, file
+}
+
+func TestAttachShotAppendsToDoc(t *testing.T) {
+	id, file := seedFeature(t, "任务列表", "需求页")
+	res, err := AttachShot(id, "任务列表", "需求页", "改成双列布局", fakePNG())
+	if err != nil {
+		t.Fatalf("追加截图失败: %v", err)
+	}
+	if !res.OK || res.Shots != 1 {
+		t.Fatalf("结果不对: %+v", res)
+	}
+	if !strings.Contains(res.Path, "/") || strings.Contains(res.Path, `\`) {
+		t.Errorf("截图路径应是正斜杠: %q", res.Path)
+	}
+	if _, err := os.Stat(filepath.FromSlash(res.Path)); err != nil {
+		t.Errorf("截图文件不在盘上: %v", err)
+	}
+	raw, err := os.ReadFile(file)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(raw)
+	if !strings.Contains(text, "## 页面完成情况") {
+		t.Fatalf("文档里没有新增段落:\n%s", text)
+	}
+	if !strings.Contains(text, "改成双列布局") {
+		t.Errorf("文档里没有标注说明:\n%s", text)
+	}
+	// 原有内容必须还在。
+	if !strings.Contains(text, "## 需求点") || !strings.Contains(text, "要点一") {
+		t.Errorf("原有内容被弄丢了:\n%s", text)
+	}
+	// 段的位置：在来源对话之前。
+	if strings.Index(text, "## 页面完成情况") > strings.Index(text, "## 来源对话") {
+		t.Errorf("新段应在来源对话之前:\n%s", text)
+	}
+}
+
+func TestAttachShotKeepsUserEdits(t *testing.T) {
+	// 用户在两次归纳之间手改了文档（加了一个自定义段 + 改了措辞）。
+	// 追加截图**不能**把那些内容抹掉 —— 这就是「文本级插入」的意义。
+	id, file := seedFeature(t, "任务列表", "需求页")
+	raw, _ := os.ReadFile(file)
+	edited := string(raw) + "\n## 我自己加的备注\n这段是用户手写的\n"
+	if err := os.WriteFile(file, []byte(edited), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := AttachShot(id, "任务列表", "需求页", "标注", fakePNG()); err != nil {
+		t.Fatalf("追加截图失败: %v", err)
+	}
+	after, _ := os.ReadFile(file)
+	if !strings.Contains(string(after), "## 我自己加的备注") {
+		t.Errorf("用户手写的内容被抹掉了:\n%s", after)
+	}
+	if !strings.Contains(string(after), "这段是用户手写的") {
+		t.Errorf("用户手写的内容被抹掉了:\n%s", after)
+	}
+}
+
+func TestAttachShotTwiceKeepsBoth(t *testing.T) {
+	id, file := seedFeature(t, "任务列表", "需求页")
+	if _, err := AttachShot(id, "任务列表", "需求页", "第一张", fakePNG()); err != nil {
+		t.Fatal(err)
+	}
+	res, err := AttachShot(id, "任务列表", "需求页", "第二张", fakePNG())
+	if err != nil {
+		t.Fatalf("第二次追加失败: %v", err)
+	}
+	if res.Shots != 2 {
+		t.Errorf("应有 2 张截图，实际 %d", res.Shots)
+	}
+	raw, _ := os.ReadFile(file)
+	text := string(raw)
+	if !strings.Contains(text, "第一张") || !strings.Contains(text, "第二张") {
+		t.Errorf("两张截图都该在文档里:\n%s", text)
+	}
+	// 占位符不该留着。
+	if strings.Contains(text, "（暂无）\n## 来源对话") {
+		t.Errorf("有图后不该还留着占位符:\n%s", text)
+	}
+}
+
+func TestAttachShotErrors(t *testing.T) {
+	id, _ := seedFeature(t, "任务列表", "需求页")
+	// 找不到功能点。
+	if _, err := AttachShot(id, "任务列表", "不存在的功能", "x", fakePNG()); err == nil {
+		t.Error("找不到功能点应当报错")
+	}
+	// 模块对不上。
+	if _, err := AttachShot(id, "别的模块", "需求页", "x", fakePNG()); err == nil {
+		t.Error("模块对不上应当报错")
+	}
+	// 不是 PNG。
+	if _, err := AttachShot(id, "任务列表", "需求页", "x", []byte("not a png")); err == nil {
+		t.Error("非 PNG 应当报错")
+	}
+	// 空内容。
+	if _, err := AttachShot(id, "任务列表", "需求页", "x", nil); err == nil {
+		t.Error("空内容应当报错")
+	}
+	// 超限。
+	if _, err := AttachShot(id, "任务列表", "需求页", "x", make([]byte, MaxShotBytes+1)); err == nil {
+		t.Error("超限应当报错")
+	}
+	// 功能点名空。
+	if _, err := AttachShot(id, "任务列表", "  ", "x", fakePNG()); err == nil {
+		t.Error("功能点名空应当报错")
+	}
+}
+
+func TestDocRoundTripKeepsShots(t *testing.T) {
+	// 归纳重写文档时（ParseDoc → RenderDoc）要保住截图与页面地址。
+	d := Doc{
+		Desc:        "描述",
+		Points:      []string{"要点"},
+		Conclusions: []string{"结论"},
+		PageURL:     "https://example.com/page",
+		Shots: []Shot{
+			{Path: "C:/Users/x/a b (v2)/1.png", Caption: "改完了", At: 1793000000000},
+		},
+	}
+	out := RenderDoc("需求页", d)
+	back := ParseDoc(out)
+	if back.PageURL != d.PageURL {
+		t.Errorf("页面地址丢了: %q", back.PageURL)
+	}
+	if len(back.Shots) != 1 {
+		t.Fatalf("截图丢了: %+v", back.Shots)
+	}
+	if back.Shots[0].Path != d.Shots[0].Path {
+		t.Errorf("截图路径不对: %q", back.Shots[0].Path)
+	}
+	if back.Shots[0].Caption != "改完了" {
+		t.Errorf("标注说明不对: %q", back.Shots[0].Caption)
+	}
+	if back.Shots[0].At != d.Shots[0].At {
+		t.Errorf("截图时间不对: %d", back.Shots[0].At)
+	}
+}
+
+func TestRenderDocWritesShotsSection(t *testing.T) {
+	out := RenderDoc("需求页", Doc{Points: []string{"要点"}})
+	if !strings.Contains(out, "## 页面完成情况") {
+		t.Errorf("空文档也该有这一段（占位）:\n%s", out)
+	}
+	if !strings.Contains(out, "（暂无）") {
+		t.Errorf("空段该写占位:\n%s", out)
+	}
+}
+
+func TestValidPageURL(t *testing.T) {
+	good := []string{"https://example.com", "http://a.b/c?d=1", "HTTPS://X.COM"}
+	bad := []string{"", "无", "待定", "见上文", "C:/Users/x", "ftp://x", "javascript:alert(1)"}
+	for _, u := range good {
+		if !validPageURL(u) {
+			t.Errorf("应认: %q", u)
+		}
+	}
+	for _, u := range bad {
+		if validPageURL(u) {
+			t.Errorf("不该认: %q", u)
+		}
+	}
+}
+
+func TestConsolidateKeepsShots(t *testing.T) {
+	// 假模型：返回一个已有功能点的增量（只有 desc）。
+	// 断言：重写文档后截图段仍在、页面地址仍在。
+	root := t.TempDir()
+	t.Setenv(EnvDir, filepath.Join(root, "requirements"))
+	id := "ws-abc1234567"
+	dir := filepath.Join(featuresDir(id), "任务列表")
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	file := filepath.Join(dir, "需求页.md")
+	doc := RenderDoc("需求页", Doc{
+		Desc:        "旧描述",
+		Points:      []string{"要点"},
+		PageURL:     "https://example.com/p",
+		Shots:       []Shot{{Path: "C:/x/1.png", Caption: "已改", At: 1793000000000}},
+		Conclusions: []string{},
+	})
+	if err := os.WriteFile(file, []byte(doc), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	merger := newDocMerger(id)
+	w := writeFeatureItem(id, featureOut{
+		Module: "任务列表",
+		Name:   "需求页",
+		Desc:   "新描述",
+	}, &writeCtx{merger: merger, kind: "归纳"})
+	if !w.ok {
+		t.Fatal("写入失败")
+	}
+	raw, _ := os.ReadFile(file)
+	back := ParseDoc(string(raw))
+	if len(back.Shots) != 1 {
+		t.Fatalf("归纳把截图抹掉了:\n%s", raw)
+	}
+	if back.Shots[0].Caption != "已改" {
+		t.Errorf("标注说明丢了: %+v", back.Shots)
+	}
+	if back.PageURL != "https://example.com/p" {
+		t.Errorf("页面地址丢了: %q", back.PageURL)
+	}
+	if back.Desc != "新描述" {
+		t.Errorf("描述没更新: %q", back.Desc)
+	}
+}
+
+func TestConsolidateKeepsPageURLWhenModelEmpty(t *testing.T) {
+	// 本轮模型没给 page_url（空串）→ 保留旧的，不能被空值抹掉。
+	root := t.TempDir()
+	t.Setenv(EnvDir, filepath.Join(root, "requirements"))
+	id := "ws-abc1234567"
+	dir := filepath.Join(featuresDir(id), "任务列表")
+	_ = os.MkdirAll(dir, 0o700)
+	file := filepath.Join(dir, "需求页.md")
+	doc := RenderDoc("需求页", Doc{Desc: "旧", PageURL: "https://example.com/keep"})
+	_ = os.WriteFile(file, []byte(doc), 0o600)
+	merger := newDocMerger(id)
+	w := writeFeatureItem(id, featureOut{Module: "任务列表", Name: "需求页", Desc: "新"}, &writeCtx{merger: merger, kind: "归纳"})
+	if !w.ok {
+		t.Fatal("写入失败")
+	}
+	raw, _ := os.ReadFile(file)
+	if back := ParseDoc(string(raw)); back.PageURL != "https://example.com/keep" {
+		t.Errorf("空 page_url 不该抹掉旧地址: %q", back.PageURL)
+	}
+}
+
+func TestConsolidateRejectsBadPageURL(t *testing.T) {
+	// 模型给了个非法地址（不是 http/https）→ 保留旧的，不写进去。
+	root := t.TempDir()
+	t.Setenv(EnvDir, filepath.Join(root, "requirements"))
+	id := "ws-abc1234567"
+	dir := filepath.Join(featuresDir(id), "任务列表")
+	_ = os.MkdirAll(dir, 0o700)
+	file := filepath.Join(dir, "需求页.md")
+	doc := RenderDoc("需求页", Doc{Desc: "旧", PageURL: "https://example.com/keep"})
+	_ = os.WriteFile(file, []byte(doc), 0o600)
+	merger := newDocMerger(id)
+	w := writeFeatureItem(id, featureOut{Module: "任务列表", Name: "需求页", Desc: "新", PageURL: "javascript:alert(1)"},
+		&writeCtx{merger: merger, kind: "归纳"})
+	if !w.ok {
+		t.Fatal("写入失败")
+	}
+	raw, _ := os.ReadFile(file)
+	if back := ParseDoc(string(raw)); back.PageURL != "https://example.com/keep" {
+		t.Errorf("非法地址不该写进去: %q", back.PageURL)
+	}
+}
+
+func TestAttachShotDedupesSamePath(t *testing.T) {
+	// 同一张图被写进文档两遍 → 段里只该有一行（留最后那条）。
+	// 触发方式：把同一行手工塞进文档，再追加一张**同名**的图。
+	id, file := seedFeature(t, "任务列表", "需求页")
+	if _, err := AttachShot(id, "任务列表", "需求页", "第一张", fakePNG()); err != nil {
+		t.Fatalf("追加截图失败: %v", err)
+	}
+	raw, _ := os.ReadFile(file)
+	// 把已有那行原样复制一遍（模拟重放/手工编辑造成的重复）。
+	lines := strings.Split(string(raw), "\n")
+	dup := ""
+	for _, l := range lines {
+		if strings.Contains(l, "第一张") {
+			dup = l
+			break
+		}
+	}
+	if dup == "" {
+		t.Fatalf("文档里没找到截图行:\n%s", raw)
+	}
+	edited := strings.Replace(string(raw), dup, dup+"\n"+dup, 1)
+	if err := os.WriteFile(file, []byte(edited), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	// 再追加一张新图 —— insertShot 应顺手把重复行去掉。
+	res, err := AttachShot(id, "任务列表", "需求页", "第二张", fakePNG())
+	if err != nil {
+		t.Fatalf("追加截图失败: %v", err)
+	}
+	if res.Shots != 2 {
+		t.Errorf("去重后应有 2 张（两张不同路径），实际 %d", res.Shots)
+	}
+	after, _ := os.ReadFile(file)
+	if n := strings.Count(string(after), "第一张"); n != 1 {
+		t.Errorf("重复的截图行没去掉，出现 %d 次:\n%s", n, after)
+	}
+}
+
+func TestTrimShotsDedupesAndTrims(t *testing.T) {
+	shots := []Shot{
+		{Path: "C:/x/1.png", Caption: "a"},
+		{Path: "C:/x/2.png", Caption: "b"},
+		{Path: "C:/x/1.png", Caption: "a2"},
+	}
+	out := TrimShots(shots)
+	if len(out) != 2 {
+		t.Fatalf("去重后应有 2 条，实际 %d: %+v", len(out), out)
+	}
+	// 留最后一条的**内容**，但位置不动（首次出现的位置）。
+	if out[0].Path != "C:/x/1.png" || out[0].Caption != "a2" {
+		t.Errorf("该留最后一条的内容（位置不动），实际 %+v", out[0])
+	}
+	if out[1].Path != "C:/x/2.png" {
+		t.Errorf("第二条不对: %+v", out[1])
+	}
+	// 超上限时丢最旧的。
+	many := make([]Shot, 0, MaxShots+5)
+	for i := 0; i < MaxShots+5; i++ {
+		many = append(many, Shot{Path: "C:/x/" + strconv.Itoa(i) + ".png"})
+	}
+	got := TrimShots(many)
+	if len(got) != MaxShots {
+		t.Fatalf("该裁到 %d 条，实际 %d", MaxShots, len(got))
+	}
+	if got[0].Path != "C:/x/5.png" {
+		t.Errorf("该丢最旧的 5 条，实际第一条 %q", got[0].Path)
+	}
+}
+
+func TestRenderDocShotLinesAreCounted(t *testing.T) {
+	// RenderDoc 写的是列表项 `- ![…](…)`；这行必须能被 countShots 数出来，
+	// 也必须能被 ParseDoc 解析回来 —— 否则归纳重渲染后截图就「消失」了。
+	out := RenderDoc("需求页", Doc{
+		PageURL: "https://example.com/p",
+		Shots:   []Shot{{Path: "C:/x/1.png", Caption: "改完了", At: 1793000000000}},
+	})
+	if !strings.Contains(out, "- ![改完了](C:/x/1.png)") {
+		t.Errorf("RenderDoc 的截图形状不对:\n%s", out)
+	}
+	if n := countShots(strings.Split(out, "\n")); n != 1 {
+		t.Errorf("countShots 数不出 RenderDoc 写的截图（得 %d）:\n%s", n, out)
+	}
+	back := ParseDoc(out)
+	if len(back.Shots) != 1 {
+		t.Fatalf("ParseDoc 解析不回来: %+v", back.Shots)
+	}
+	if back.Shots[0].Caption != "改完了" || back.Shots[0].Path != "C:/x/1.png" {
+		t.Errorf("解析结果不对: %+v", back.Shots[0])
+	}
+}

package/internal/session/session.go

@@ -133,6 +133,10 @@ const (
 	StateCancelled       = "cancelled"        // 被 --stop 取消
 	StateInterrupted     = "interrupted"      // 当前轮被打断（会话仍可继续）
 	StateGone            = "gone"             // 记录里是 running，但进程已不在（自然退出/被别处杀掉）
+	/* queued 已受理、还在作业队列里等（**不是**活着：没有进程，也没有会话日志）。
+	   由服务端作业队列预登记（见 RegisterQueued），真开跑时抹掉、交给 core 自己的
+	   running 记录。列表页据此把「排在前面的那几条」画出来。 */
+	StateQueued = "queued"
 )
 
 // isLiveState 这个状态是否代表「会话/进程还活着」（running / waiting_approval / idle）。
@@ -526,6 +530,78 @@ func Begin(o BeginOptions) (*Handle, error) {
 	return h, nil
 }
 
+// RegisterQueued 预登记一条「已受理、还没开跑」的会话（作业队列用）。
+//
+// 为什么（2026-10-24 用户：「没跑也先登记啊」）：串行模式下作业在服务端排队，
+// 此前只有真开跑（core 的 Begin）才写登记表 —— 排在后面的几条既不在 --sessions 里，
+// 也不在任何客户端的列表上，看起来像「发完凭空消失」。现在受理即登记（state=queued），
+// 谁排在队里、排第几，列表页从这一刻就能看见；真开跑 / 终结时由队列调 RemoveQueued
+// 抹掉占位，交给 core 自己的那条 running 记录。
+//
+// 口径：
+//   - RunID 用客户端的幂等键（request_id；没有就用 job id）：客户端据此把本地那条
+//     「等待中」和这条登记行认成同一条，不会画两行。core 的 run_id 是 run-… 前缀，
+//     两者不会撞。
+//   - PID 恒 0、state=queued：读侧（normalizeDead / externalBusy / Stop）都按
+//     「非活着」处理，不占工作空间锁、不会被误判成在跑。
+//   - 覆盖写是幂等的：队列每推进一次状态就同步一次。
+func RegisterQueued(rec Record) error {
+	dir := Dir()
+	rec.RunID = strings.TrimSpace(rec.RunID)
+	if dir == "" || rec.RunID == "" {
+		return fmt.Errorf("register queued: 缺少登记目录或 run_id")
+	}
+	/* RunID 会直接当文件名用（<run_id>.json），而排队占位的 id 来自客户端的
+	   request_id —— 不能让 `../x`、带分隔符的 id 逃出登记目录。作业队列侧已经
+	   做过一次安全化（见 client 的 queuedSessionID），这里再挡一道。 */
+	if !validRecordName(rec.RunID) {
+		return fmt.Errorf("register queued: 非法 run_id %q", rec.RunID)
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return err
+	}
+	rec.State = StateQueued
+	rec.PID = 0
+	rec.KillGroup = false
+	rec.PromptHead = head(rec.PromptHead, 80)
+	if rec.StartedAt.IsZero() {
+		rec.StartedAt = time.Now()
+	}
+	rec.UpdatedAt = time.Now()
+	data, err := json.MarshalIndent(rec, "", "  ")
+	if err != nil {
+		return err
+	}
+	path := filepath.Join(dir, rec.RunID+".json")
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, data, 0o600); err != nil {
+		return err
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		return err
+	}
+	setStatus(rec)
+	return nil
+}
+
+// RemoveQueued 抹掉排队占位（开跑 / 终结 / 取消时由作业队列调用）。
+// 没有占位文件就什么都不做 —— 也**不要**去清状态表：那条键可能已经是真实会话的了。
+func RemoveQueued(runID string) {
+	runID = strings.TrimSpace(runID)
+	dir := Dir()
+	if runID == "" || dir == "" || !validRecordName(runID) {
+		return
+	}
+	path := filepath.Join(dir, runID+".json")
+	if _, err := os.Stat(path); err != nil {
+		return
+	}
+	if err := os.Remove(path); err != nil {
+		return
+	}
+	dropStatuses(map[string]bool{runID: true})
+}
+
 // supersedeSiblings 停掉同一会话上**还活着**的上一次运行。
 //
 // 为什么（2026-10-21，用户：「两边的回话状态不一致，一边结束了，一边还在显示运行中」）：
@@ -582,6 +658,22 @@ func head(s string, n int) string {
 	return string(r[:n]) + "…"
 }
 
+// validRecordName 登记文件名是否安全：只允许字母 / 数字 / - _ .，且不能是 . / ..。
+// 只给排队占位用 —— 它的 id 可能来自客户端（request_id），不能直接拼进路径。
+func validRecordName(id string) bool {
+	if id == "" || id == "." || id == ".." || len(id) > 96 {
+		return false
+	}
+	for _, r := range id {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '-', r == '_', r == '.':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
 // cwdOf 取进程当前目录；拿不到就留空（需求归纳按 workspace 归属时会退回用
 // Workspace 字段，两者都没有就只是不参与按目录的自动分组，不影响会话本身）。
 func cwdOf() string {

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)