magic-agent 2.4.2 → 2.6.0

package/internal/agent/engine_base_test.go

@@ -199,7 +199,7 @@ func TestInstallCommandOf(t *testing.T) {
 		"codex":        "npm install -g @openai/codex",
 		"openclaw":     "npm install -g openclaw@latest",
 		"dsh":          "npm i -g @deepseek-ai/dsh",
-		"trae":         `sh -c "$(curl -L https://trae.cn/trae-cli/install.sh)"`,
+		"trae":         `sh -c "$(curl -fsSL https://trae.cn/trae-cli/install_v2.sh)"`,
 		"llm":          "python3 -m venv ~/.llm-venv && ~/.llm-venv/bin/pip install llm",
 	}
 	for engine, want := range cases {
@@ -288,7 +288,7 @@ func TestFirstSemver(t *testing.T) {
 		{"codex-cli 0.154.0", "0.154.0"},
 		{"OpenClaw 2026.6.11 (e085fa1)", "2026.6.11"},
 		{"0.1.5-rc.2", "0.1.5-rc.2"},
-		{"trae-cli 0.120.52\n", "0.120.52"},
+		{"traecli 0.211.1\n", "0.211.1"},
 		{"1.2.3+build.7", "1.2.3+build.7"},
 		// 认不出来就空串（**不编**）
 		{"no version here", ""},

package/internal/agent/engine_test.go

@@ -4,10 +4,9 @@ package agent
 //
 // 用 fake CLI 脚本（写入临时目录的 shell 脚本）模拟三家 CLI 的行为，
 // 验证：
-//	- 参数构造（--model、--tools ""、--output-format、-c model.name、
-//	  --query-timeout 映射）
+//	- 参数构造（--model、--tools ""、--output-format、-m model、exec resume）
 //	- 输出解析（claude JSON envelope、codebuddy 三种 envelope、
-//	  user_query 回显剥离、trae 纯文本）
+//	  user_query 回显剥离、trae 2.0 的 exec --json 事件流）
 //	- FlattenPrompt 扁平化逻辑
 //	- 引擎注册表 / Lookup
 
@@ -209,7 +208,7 @@ func TestReasoningEffortArgs(t *testing.T) {
 	}
 	// dsh 的 launcher/headless 没有 reasoning 开关：NoThinking 对它保持现状，
 	// 不能塞 --effort（实测启动器报 "--profile <name> is required"）。
-	dshNo := dshHeadlessArgs("headless", "", "hi", false)
+	dshNo := dshHeadlessArgs("headless", "", "", "hi", false)
 	if len(dshNo) < 3 || dshNo[0] != "--profile" || dshNo[1] != "headless" {
 		t.Errorf("dsh 参数不应被 NoThinking 改坏: %v", dshNo)
 	}
@@ -488,11 +487,11 @@ func TestCodeBuddyDefaultModel(t *testing.T) {
 
 // ── Trae 引擎 ─────────────────────────────────────────────────
 
-func TestTraeCompletePlainText(t *testing.T) {
+func TestTraeComplete(t *testing.T) {
 	dir := t.TempDir()
 	log := filepath.Join(dir, "args.log")
-	cli := filepath.Join(dir, "trae-cli")
-	script := "#!/bin/sh\nprintf '%s\\n' \"$*\" > " + log + "\necho 'trae 的回答'\n"
+	cli := filepath.Join(dir, "traex")
+	script := "#!/bin/sh\nprintf '%s\\n' \"$*\" > " + log + "\n" + traeV2Stub("trae 的回答", "th-1")
 	if err := os.WriteFile(cli, []byte(script), 0o755); err != nil {
 		t.Fatal(err)
 	}
@@ -510,16 +509,18 @@ func TestTraeCompletePlainText(t *testing.T) {
 	if resp.Text != "trae 的回答" {
 		t.Errorf("Text = %q", resp.Text)
 	}
+	if resp.SessionID != "th-1" {
+		t.Errorf("SessionID = %q want th-1", resp.SessionID)
+	}
 
 	data, _ := os.ReadFile(log)
 	args := string(data)
-	// 默认模型：不传 -c model.name
-	if strings.Contains(args, "model.name") {
-		t.Errorf("default model should not pass -c model.name: %q", args)
+	// 2.0：exec --json，不再有 -p / --query-timeout / model.name
+	if !strings.Contains(args, "exec") || !strings.Contains(args, "--json") {
+		t.Errorf("2.0 应走 exec --json: %q", args)
 	}
-	// 超时映射到 --query-timeout
-	if !strings.Contains(args, "--query-timeout 1m30s") {
-		t.Errorf("--query-timeout not mapped: %q", args)
+	if strings.Contains(args, "--query-timeout") || strings.Contains(args, "model.name") {
+		t.Errorf("不应出现 1.x 参数: %q", args)
 	}
 	// 工具禁用
 	if !strings.Contains(args, "--disallowed-tool Bash") {
@@ -534,8 +535,8 @@ func TestTraeCompletePlainText(t *testing.T) {
 func TestTraeExplicitModel(t *testing.T) {
 	dir := t.TempDir()
 	log := filepath.Join(dir, "args.log")
-	cli := filepath.Join(dir, "trae-cli")
-	script := "#!/bin/sh\nprintf '%s\\n' \"$*\" > " + log + "\necho 'ok'\n"
+	cli := filepath.Join(dir, "traex")
+	script := "#!/bin/sh\nprintf '%s\\n' \"$*\" > " + log + "\n" + traeV2Stub("ok", "th-1")
 	if err := os.WriteFile(cli, []byte(script), 0o755); err != nil {
 		t.Fatal(err)
 	}
@@ -552,59 +553,19 @@ func TestTraeExplicitModel(t *testing.T) {
 	}
 	data, _ := os.ReadFile(log)
 	args := string(data)
-	if !strings.Contains(args, "-c model.name=My-MiniMax-M3") {
-		t.Errorf("-c model.name not passed: %q", args)
+	if !strings.Contains(args, "-m My-MiniMax-M3") {
+		t.Errorf("-m model not passed: %q", args)
 	}
 }
 
-func TestTraeTimeoutCappedAt600s(t *testing.T) {
-	dir := t.TempDir()
-	log := filepath.Join(dir, "args.log")
-	cli := filepath.Join(dir, "trae-cli")
-	script := "#!/bin/sh\nprintf '%s\\n' \"$*\" > " + log + "\necho 'ok'\n"
-	if err := os.WriteFile(cli, []byte(script), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	e := &TraeEngine{BinPath: cli}
-	_, err := e.Complete(context.Background(), Request{
-		Messages: []Message{{Role: "user", Content: "hi"}},
-		Timeout:  30 * time.Minute,
-	})
-	if err != nil {
-		t.Fatalf("Complete: %v", err)
-	}
-	data, _ := os.ReadFile(log)
-	if !strings.Contains(string(data), "--query-timeout 10m0s") {
-		t.Errorf("query-timeout should cap at 600s: %q", string(data))
-	}
+// traeV2Stub 造 trae 2.0 的 JSONL 事件流（thread.started + 正文 + turn.completed）。
+func traeV2Stub(text, sessionID string) string {
+	return "printf '%s\\n' '{\"type\":\"thread.started\",\"thread_id\":\"" + sessionID + "\"}'\n" +
+		"printf '%s\\n' '{\"type\":\"item.completed\",\"item\":{\"id\":\"i\",\"type\":\"agent_message\",\"text\":\"" + text + "\"}}'\n" +
+		"printf '%s\\n' '{\"type\":\"turn.completed\"}'\n"
 }
 
-// ── TraeDefaultModel 配置探测 ─────────────────────────────────
-
-func TestTraeDefaultModel(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
-
-	// 无配置文件 → 空串
-	if got := TraeDefaultModel(); got != "" {
-		t.Errorf("no config: got %q want empty", got)
-	}
-
-	// 有配置 → 读 model.name
-	cfgDir := filepath.Join(home, ".trae")
-	if err := os.MkdirAll(cfgDir, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	yaml := "model:\n    name: My-MiniMax-M3\nmodels:\n-  name: \"My-MiniMax-M3\"\n"
-	if err := os.WriteFile(filepath.Join(cfgDir, "trae_cli.yaml"), []byte(yaml), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if got := TraeDefaultModel(); got != "My-MiniMax-M3" {
-		t.Errorf("got %q want My-MiniMax-M3", got)
-	}
-}
-
-// ── 会话续接（SessionID → --resume 映射）──────────────────────
+// ── 会话续接（SessionID → exec resume 映射）────────────────────
 
 // argsCaptureCLI 写一个把 "$*" 逐行记入 args.log 的假 CLI，返回 (引擎, log 路径)。
 func argsCaptureCLI(t *testing.T, dir, name, cannedOutput string) (*engineWithLog, string) {
@@ -737,9 +698,9 @@ echo '{"type":"result","result":"好"}'
 	}
 }
 
-func TestTraeResumeSessionEqualsForm(t *testing.T) {
+func TestTraeResumeSession(t *testing.T) {
 	dir := t.TempDir()
-	w, log := argsCaptureCLI(t, dir, "trae-cli", `echo '续上了'`)
+	w, log := argsCaptureCLI(t, dir, "trae-cli", traeV2Stub("续上了", "tr-9"))
 	e := w.trae()
 	resp, err := e.Complete(context.Background(), Request{
 		Messages:  []Message{{Role: "user", Content: "hi"}},
@@ -748,21 +709,23 @@ func TestTraeResumeSessionEqualsForm(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Complete: %v", err)
 	}
-	// trae 纯文本模式 CLI 不回 session_id → 回显请求里的 id，保证逐轮透传。
+	// 2.0 的 thread.started 会给出真实会话 id。
 	if resp.SessionID != "tr-9" {
-		t.Errorf("Response.SessionID = %q want tr-9（请求回显）", resp.SessionID)
+		t.Errorf("Response.SessionID = %q want tr-9", resp.SessionID)
 	}
 	data, _ := os.ReadFile(log)
 	args := string(data)
-	// pflag 可选值风格：必须等号形式，空格形式下裸 id 会被吞成 AUTO。
-	if !strings.Contains(args, "--resume=tr-9") {
-		t.Errorf("--resume=tr-9 (equals form) not passed: %q", args)
+	if !strings.Contains(args, "exec resume tr-9") {
+		t.Errorf("exec resume tr-9 not passed: %q", args)
+	}
+	if strings.Contains(args, "--resume") {
+		t.Errorf("2.0 不应再出现 --resume: %q", args)
 	}
 }
 
 func TestTraeNewSessionDefault(t *testing.T) {
 	dir := t.TempDir()
-	w, log := argsCaptureCLI(t, dir, "trae-cli", `echo 'ok'`)
+	w, log := argsCaptureCLI(t, dir, "trae-cli", traeV2Stub("ok", "th-new"))
 	e := w.trae()
 	resp, err := e.Complete(context.Background(), Request{
 		Messages: []Message{{Role: "user", Content: "hi"}},
@@ -770,13 +733,12 @@ func TestTraeNewSessionDefault(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Complete: %v", err)
 	}
-	// 新会话：请求里没有 id，回显也是空。
-	if resp.SessionID != "" {
-		t.Errorf("Response.SessionID = %q want empty", resp.SessionID)
+	if resp.SessionID != "th-new" {
+		t.Errorf("Response.SessionID = %q want th-new", resp.SessionID)
 	}
 	data, _ := os.ReadFile(log)
-	if strings.Contains(string(data), "--resume") {
-		t.Errorf("默认新会话不应带 --resume: %q", string(data))
+	if strings.Contains(string(data), "resume") {
+		t.Errorf("默认新会话不应带 resume: %q", string(data))
 	}
 }
 
@@ -822,11 +784,10 @@ func TestCodeBuddyContinueSession(t *testing.T) {
 	}
 }
 
-// trae 无 --continue：裸 --resume 触发 AUTO（续接最近一次会话），
-// 且不能是等号形式（等号形式是显式 id 续接）。
-func TestTraeContinueBareResume(t *testing.T) {
+// trae 2.0：Continue → `exec resume --last`（不再有裸 --resume）。
+func TestTraeContinueResumeLast(t *testing.T) {
 	dir := t.TempDir()
-	w, log := argsCaptureCLI(t, dir, "trae-cli", `echo 'ok'`)
+	w, log := argsCaptureCLI(t, dir, "trae-cli", traeV2Stub("ok", "th-last"))
 	e := w.trae()
 	if _, err := e.Complete(context.Background(), Request{
 		Messages: []Message{{Role: "user", Content: "hi"}},
@@ -836,11 +797,11 @@ func TestTraeContinueBareResume(t *testing.T) {
 	}
 	data, _ := os.ReadFile(log)
 	args := string(data)
-	if !strings.Contains(args, "--resume") {
-		t.Errorf("bare --resume not passed: %q", args)
+	if !strings.Contains(args, "exec resume --last") {
+		t.Errorf("exec resume --last not passed: %q", args)
 	}
-	if strings.Contains(args, "--resume=") {
-		t.Errorf("Continue 应为裸 --resume，不带 =id: %q", args)
+	if strings.Contains(args, "--resume") {
+		t.Errorf("2.0 不应再出现 --resume: %q", args)
 	}
 }
 
@@ -857,7 +818,7 @@ func TestSessionPriorityOverContinue(t *testing.T) {
 	}{
 		{"claude", "s-1", "--resume s-1", "--continue", "claude", `echo '{"type":"result","result":"ok"}'`},
 		{"codebuddy", "cb-1", "--resume cb-1", "--continue", "codebuddy", `echo '{"type":"result","result":"ok"}'`},
-		{"trae", "tr-1", "--resume=tr-1", "--continue", "trae-cli", `echo 'ok'`},
+		{"trae", "tr-1", "exec resume tr-1", "--continue", "trae-cli", traeV2Stub("ok", "tr-1")},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
@@ -999,7 +960,7 @@ func TestTemperatureIgnoredByCLIs(t *testing.T) {
 				_, err := w.codebuddy().Complete(context.Background(), req)
 				return err
 			}},
-		{"trae", "trae-cli", `echo 'ok'`,
+		{"trae", "trae-cli", traeV2Stub("ok", "th-1"),
 			func(w *engineWithLog, req Request) error {
 				_, err := w.trae().Complete(context.Background(), req)
 				return err

package/internal/agent/fallback.go

@@ -0,0 +1,313 @@
+package agent
+
+// fallback.go - 主引擎失败时降级到备用引擎（2026-10-24；2026-10-26 按真机报障修口径）。
+//
+// 为什么需要它：额度用尽（如 dsh 的 402 Token Plan 上限）、临时不可用、单模型故障
+// 都不该让一整轮直接失败 —— 用户在一次设置里就能指定「主 + 备」，主的那条不行时
+// 自动换备用再跑一次。
+//
+// 2026-10-26 用户报「主备模型还没真的发挥作用」，真机作业记录给出了三个原因，逐个钉住：
+//
+//  1. **只当引擎变了才降级**：`fallback_engine == 主引擎` 直接被判「没配备用」。
+//     手机上最常见的配法恰恰是同引擎换模型（dsh 的 modelverse 主、volcengine 备；
+//     codebuddy 一个账号换另一个模型）—— 以前这一路**永远不会降级**。
+//  2. **备用模型被带到了备用引擎上**：清单是各引擎自己的，把 codebuddy 的模型喂给 dsh
+//     只会得到「未知模型」。以前又恰好因为第 1 条，这条错路没被走到。
+//     现在：同引擎沿用备用模型；换引擎时备用模型不往下传（FallbackDown），引擎用自己的默认。
+//  3. **主引擎吐过思考 / 计划 / 工具调用就不降级**：额度耗尽往往在**第一段输出之前**
+//     就会报出来，但有的引擎先吐空 delta 或只吐思考；只要不是正文，用户就没看到答案，
+//     更不该让这一轮直接死掉。
+//
+// 四条纪律（写死，别放开）：
+//
+//  1. **只有正文才算产出**：主引擎已经吐过正文 / 图片就不再换（工具结果也算 —— 说明
+//     它已经被喂过输出、可能动过手了）；思考、空正文、计划 / 待授权不拦降级 —— 换引擎
+//     重跑时这些都只是过程，用户不会看到两套答案。
+//  2. **降级清空会话锚点**：备用引擎没有主引擎那条会话（SessionID / Continue 都是
+//     别人的），带过去只会 resume 失败。降级一定是「新开一轮」。
+//  3. **只降一级**：备用失败就报「主备都失败」，不再链式找第三个 —— 配置里只有两档，
+//     行为要可预期。ctx 已取消 / 超时同样不降级（不是引擎的错，重试也没用）。
+//  4. **决定的理由进返回**：FallbackInfo 告诉调用方「降了没有、为什么没降」，
+//     由 CLI 落到事件流的 `fallback` 帧 —— 用户能一眼确认主备确实接上了（问题 1 的现场
+//     就是「配了、跑完了、没有任何痕迹」，没法判断到底生效没有）。
+//
+// 降级发生时先发一条 `fallback` 帧（结构化，客户端据此把这一轮标成「由备用引擎作答」），
+// 再发一条 KindNotice（人话一行，老客户端照旧看到「已降级到备用引擎」）。
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// RunOptions 一次非流式调用的编排参数（与 Runner 字段同义，供 RunWithFallback 复用）。
+type RunOptions struct {
+	Timeout time.Duration
+	Retries int
+	Backoff time.Duration
+	Verbose bool
+}
+
+// FallbackInfo 这一轮的主备结论（无论降没降都有，供 CLI 落 fallback 帧 / 打日志）。
+type FallbackInfo struct {
+	// PrimaryEngine / PrimaryModel 这一轮主引擎实际跑的引擎与模型。
+	PrimaryEngine string
+	PrimaryModel  string
+	// ConfiguredEngine / ConfiguredModel 用户配的备用（原样）。
+	ConfiguredEngine string
+	ConfiguredModel  string
+	// Used 是否真的降级并由备用引擎成功作答。
+	Used bool
+	// Engine / Model 备用引擎实际用的引擎与模型（Used 时有意义）。
+	Engine string
+	Model  string
+	// SwitchedEngine 备用是另一个引擎（而不是同引擎换模型）。
+	SwitchedEngine bool
+	// Reason 没降级的原因（人话，中文）；降级时为空。客户端直接显示。
+	Reason string
+	// Err 主引擎的原始错误（没降级且主引擎失败时非空）。
+	Err error
+}
+
+// FallbackEvent 降级那一刻发的事件正文（StreamEvent.Fallback）。
+type FallbackEvent struct {
+	FromEngine string `json:"from_engine"`
+	FromModel  string `json:"from_model,omitempty"`
+	ToEngine   string `json:"to_engine"`
+	ToModel    string `json:"to_model,omitempty"`
+	Switched   bool   `json:"switched_engine"`
+	Reason     string `json:"reason,omitempty"`
+}
+
+// event 把 FallbackEvent 转成一条 StreamEvent（Kind=fallback）。
+func (f FallbackEvent) event() StreamEvent {
+	return StreamEvent{Kind: KindFallback, Text: FallbackNoticeText(f), Fallback: &f}
+}
+
+// fallbackTarget 解析降级目标：返回备用引擎对象与改写后的请求。
+//
+// 没配 / 配的就是主引擎且没换模型 / 引擎不存在 / 引擎没有所需能力（流式）时 ok=false，
+// 原因在 reason（人话；没配备用时为空）。调用方保留原始错误。
+func fallbackTarget(primary Engine, req Request, needStream bool) (Engine, Request, string, bool) {
+	name := strings.TrimSpace(req.FallbackEngine)
+	if name == "" {
+		return nil, req, "", false
+	}
+	if strings.EqualFold(name, primary.Name()) && strings.TrimSpace(req.FallbackModel) == "" {
+		return nil, req, "备用就是主引擎（引擎与模型都相同），没有可降级的目标", false
+	}
+	eng := Lookup(name)
+	if eng == nil {
+		return nil, req, fmt.Sprintf("备用引擎「%s」不存在，没有降级", name), false
+	}
+	if needStream && AsStreamer(eng) == nil {
+		return nil, req, fmt.Sprintf("备用引擎「%s」不支持流式调用，没有降级", name), false
+	}
+	fb := req
+	fb.Engine = eng.Name()
+	// 会话锚点是主引擎的，备用引擎接不上（见文件头第 2 条）。
+	fb.SessionID = ""
+	fb.Continue = false
+	// 只降一级。
+	fb.FallbackEngine = ""
+	fb.FallbackModel = ""
+	fb.FallbackDown = true
+	if strings.EqualFold(eng.Name(), primary.Name()) {
+		// 同引擎换模型：备用模型就是这一路的意义所在，原样带上。
+		fb.Model = strings.TrimSpace(req.FallbackModel)
+	} else {
+		/* 换引擎：备用模型属于主引擎的清单（codebuddy 的 hy3 喂给 dsh = 未知模型）。
+		   清空 + FallbackDown，让备用引擎用自己的默认模型跑 —— 有答案胜过必然失败。 */
+		fb.Model = ""
+	}
+	return eng, fb, "", true
+}
+
+// configured 用户是否配了备用（引擎非空且与主引擎不同，或同引擎换了模型）。
+func configured(primary Engine, req Request) bool {
+	fb := strings.TrimSpace(req.FallbackEngine)
+	if fb == "" {
+		return false
+	}
+	if !strings.EqualFold(fb, primary.Name()) {
+		return true
+	}
+	return strings.TrimSpace(req.FallbackModel) != ""
+}
+
+// FallbackNoticeText 降级提示的文案（主会话里的一行，不是错误）。
+//
+// 同引擎换模型时说「已切到备用模型」—— 用户配的正是模型，提示里得看到它。
+func FallbackNoticeText(f FallbackEvent) string {
+	reason := strings.TrimSpace(f.Reason)
+	if reason == "" {
+		reason = "主引擎失败"
+	}
+	to := fmt.Sprintf("「%s」", f.ToEngine)
+	if f.ToModel != "" {
+		to = fmt.Sprintf("「%s」的 %s", f.ToEngine, f.ToModel)
+	}
+	if !f.Switched && f.FromEngine == f.ToEngine {
+		return fmt.Sprintf("「%s」执行失败（%s），已切到备用模型%s重试", f.FromEngine, reason, to)
+	}
+	return fmt.Sprintf("「%s」执行失败（%s），已降级到备用引擎%s重试", f.FromEngine, reason, to)
+}
+
+// eventProduced 这条事件算不算「已经有产出了」（见文件头纪律第 1 条）。
+//
+// 思考**不算**：它只是过程；用户没看到任何答案，换引擎重跑不会让他看到两套正文。
+// 空白正文也不算（有些引擎会发空 delta）。工具结果算 —— 主引擎已经动过手。
+func eventProduced(ev StreamEvent) bool {
+	switch ev.Kind {
+	case KindText, KindImage:
+		return strings.TrimSpace(ev.Text) != ""
+	case KindToolResult:
+		return strings.TrimSpace(ev.Text) != ""
+	}
+	return false
+}
+
+// stripNonResetKinds 去掉「结束这一轮」语义的过程帧：降级后备用引擎紧接着还要跑，
+// 调用方若把主引擎残留的 turn_end / turn_failed 转出去，这一轮会在备用引擎开口之前
+// 就被画成「已结束」（或直接关机），备用答案再无去处。
+//
+// 留下来的其它事件（思考、工具卡、计划 / 待授权、notice）照常转发：它们已落盘，是真实过程。
+func stripNonResetKinds(ev StreamEvent) (StreamEvent, bool) {
+	switch ev.Kind {
+	case KindTurnEnd, KindTurnFailed:
+		return StreamEvent{}, false
+	}
+	return ev, true
+}
+
+// StreamWithFallback 流式执行：主引擎失败或只有过程、没有正文时，自动换备用引擎重跑一次。
+//
+// primary 必须是 Streamer（团队子任务与 ask 的流式路径都满足）。
+// onEvent 收到的 fallback / notice 需要调用方照常转发（它们属于「过程」，不是错误）。
+// 返回的 info 说明这一轮的结论（没降级时的原因由调用方落 fallback 帧）。
+func StreamWithFallback(ctx context.Context, primary Engine, req Request, onEvent func(StreamEvent)) (StreamResult, FallbackInfo, error) {
+	info := FallbackInfo{
+		PrimaryEngine:    primary.Name(),
+		PrimaryModel:     req.Model,
+		ConfiguredEngine: strings.TrimSpace(req.FallbackEngine),
+		ConfiguredModel:  strings.TrimSpace(req.FallbackModel),
+	}
+	if st := AsStreamer(primary); st == nil {
+		return StreamResult{}, info, fmt.Errorf("%s 不支持流式调用", primary.Name())
+	}
+	if onEvent == nil {
+		onEvent = func(StreamEvent) {}
+	}
+	produced := false
+	watch := func(ev StreamEvent) {
+		if eventProduced(ev) {
+			produced = true
+		}
+		onEvent(ev)
+	}
+	res, err := AsStreamer(primary).Stream(ctx, req, watch)
+	if err == nil || produced || ctx.Err() != nil {
+		if produced && configured(primary, req) {
+			info.Reason = "主引擎已经输出正文，本轮不降级（避免两段互相矛盾的答案）"
+		}
+		return res, info, err
+	}
+	eng, fbReq, blocked, ok := fallbackTarget(primary, req, true)
+	if !ok {
+		info.Reason = blocked
+		return res, info, err
+	}
+	fe := FallbackEvent{
+		FromEngine: primary.Name(),
+		FromModel:  strings.TrimSpace(req.Model),
+		ToEngine:   eng.Name(),
+		ToModel:    strings.TrimSpace(fbReq.Model),
+		Switched:   !strings.EqualFold(eng.Name(), primary.Name()),
+		Reason:     shortReason(err),
+	}
+	onEvent(fe.event())
+	res2, err2 := AsStreamer(eng).Stream(ctx, fbReq, func(ev StreamEvent) {
+		if kept, ok := stripNonResetKinds(ev); ok {
+			onEvent(kept)
+		}
+	})
+	if err2 == nil {
+		info.Used = true
+		info.Engine = eng.Name()
+		info.Model = effectiveModel(strings.TrimSpace(res2.Model), fe.ToModel)
+		info.SwitchedEngine = fe.Switched
+		return res2, info, nil
+	}
+	return res2, info, fmt.Errorf("「%s」失败（%s）；备用引擎「%s」也失败：%w",
+		primary.Name(), shortReason(err), eng.Name(), err2)
+}
+
+// RunWithFallback 非流式执行（含超时与重试）：主引擎跑完仍失败且没拿到正文时，
+// 换备用引擎按同样的超时 / 重试策略再跑一次。
+//
+// onFallback 可为 nil；非空时在降级前调用一次（CLI 用它往 stderr / 事件流写提示）。
+func RunWithFallback(ctx context.Context, primary Engine, req Request, ro RunOptions, onFallback func(FallbackEvent)) (Response, FallbackInfo, error) {
+	info := FallbackInfo{
+		PrimaryEngine:    primary.Name(),
+		PrimaryModel:     req.Model,
+		ConfiguredEngine: strings.TrimSpace(req.FallbackEngine),
+		ConfiguredModel:  strings.TrimSpace(req.FallbackModel),
+	}
+	run := func(e Engine, r Request) (Response, error) {
+		return (&Runner{Engine: e, Timeout: ro.Timeout, Retries: ro.Retries, Backoff: ro.Backoff, Verbose: ro.Verbose}).Run(ctx, r)
+	}
+	resp, err := run(primary, req)
+	if err == nil || strings.TrimSpace(resp.Text) != "" || ctx.Err() != nil {
+		return resp, info, err
+	}
+	eng, fbReq, blocked, ok := fallbackTarget(primary, req, false)
+	if !ok {
+		info.Reason = blocked
+		return resp, info, err
+	}
+	fe := FallbackEvent{
+		FromEngine: primary.Name(),
+		FromModel:  strings.TrimSpace(req.Model),
+		ToEngine:   eng.Name(),
+		ToModel:    strings.TrimSpace(fbReq.Model),
+		Switched:   !strings.EqualFold(eng.Name(), primary.Name()),
+		Reason:     shortReason(err),
+	}
+	if onFallback != nil {
+		onFallback(fe)
+	}
+	resp2, err2 := run(eng, fbReq)
+	if err2 != nil {
+		// 备用也没成：Engine 留空 —— 它是「谁给出了答案」的标签，没答案就不记。
+		return resp2, info, fmt.Errorf("「%s」失败（%s）；备用引擎「%s」也失败：%w",
+			primary.Name(), shortReason(err), eng.Name(), err2)
+	}
+	info.Used = true
+	info.Engine = eng.Name()
+	info.SwitchedEngine = fe.Switched
+	info.Model = effectiveModel(strings.TrimSpace(resp2.Model), fe.ToModel)
+	return resp2, info, nil
+}
+
+// effectiveModel 备用引擎实际用的模型标签：引擎没回填时用降级目标上配的那个，
+// 两者都空 = 引擎默认模型（标签留空，不编）。
+func effectiveModel(reported, target string) string {
+	if reported != "" {
+		return reported
+	}
+	return target
+}
+
+// shortReason 降级提示里用的短原因：去掉重复的外层包装，压成一行。
+func shortReason(err error) string {
+	s := strings.TrimSpace(ReasonOf(err))
+	if s == "" {
+		s = strings.TrimSpace(err.Error())
+	}
+	s = strings.ReplaceAll(s, "\n", " ")
+	if n := len([]rune(s)); n > 160 {
+		s = string([]rune(s)[:160]) + "…"
+	}
+	return s
+}