magic-agent 2.4.3 → 2.6.3

package/internal/agent/env.go

@@ -6,8 +6,10 @@ package agent
 // 「只能属于父进程」的变量。见 childEnvDenylist。
 
 import (
+	"net"
 	"os"
 	"strings"
+	"time"
 )
 
 // serverEnvPrefix 剔除的前缀：父会话内置 HTTP 服务的监听地址。
@@ -98,24 +100,194 @@ var envDenylist = map[string]bool{
 	//   - CODEBUDDY_CONFIG_DIR / CODEBUDDY_CODE_IMAGE_COMPRESSION_MAX_DIMENSION /
 	//     CODEBUDDY_SAFE_DELETE_BULK_GUARD —— 宿主配置/沙箱细节，claude/codebuddy
 	//     不需要。
+	// Electron 的「拿 Electron 当 node 跑」开关。宿主应用（WorkBuddy）把它设成 1，
+	// 子进程继承后，任何 Electron 可执行文件都会以 node 模式启动 —— 引擎 CLI 不需要
+	// 这个身份，留着只会把宿主的启动链路带进来（2026-10-26 实测，见下方 NODE_OPTIONS）。
+	"ELECTRON_RUN_AS_NODE": true,
+
 	"CODEBUDDY_MCP_CONFIG":                           true,
 	"CODEBUDDY_CONFIG_DIR":                           true,
 	"CODEBUDDY_CODE_IMAGE_COMPRESSION_MAX_DIMENSION": true,
 	"CODEBUDDY_SAFE_DELETE_BULK_GUARD":               true,
 }
 
+// hostNodeShim 判断一条 NODE_OPTIONS 是否是**宿主 Electron 应用**注入的垫片。
+//
+// 2026-10-26 实测：从 WorkBuddy 的终端里重启 magic-client，父进程环境带着
+//
+//	NODE_OPTIONS=--require=".../WorkBuddy.app/Contents/Resources/app.asar.unpacked/
+//	              cli/vendor/shim/node-language-shim.cjs"
+//	ELECTRON_RUN_AS_NODE=1
+//
+// 于是**每一个**引擎子进程（node 系的 dsh/codex/claude，连 llm 的 node 包装）启动时
+// 都被迫加载那个 shim；shim 要去连 WorkBuddy 的 broker，而 broker 只在 WorkBuddy
+// 运行时存在 —— 报 `connect failed: Connection refused`，任务全部 failed。
+// 不是引擎坏了，是继承了一份不属于它的启动垫片。
+//
+// 只认「.asar / WorkBuddy」这两个特征：用户自己设的 `--max-old-space-size` 之类
+// 照常保留，别误伤。
+func hostNodeShim(val string) bool {
+	v := strings.ToLower(val)
+	return strings.Contains(v, ".asar") || strings.Contains(v, "workbuddy")
+}
+
+// hostShimDir 判断 PATH 里的一段是不是宿主 Electron 应用塞进来的「假命令」目录。
+//
+// 2026-10-26 真机实测（比 NODE_OPTIONS 更隐蔽的那个）：从 WorkBuddy 的终端起
+// magic-client，继承到的 PATH **最前面**是
+//
+//	/Applications/WorkBuddy.app/.../cli/vendor/shim/brokered-bin
+//
+// 里面有 29 个被替换掉的基础命令（cat / cp / dd / chmod / 7z …）。命中它们之后，
+// 那个 shell 脚本会 require `node-brokered-fs-shim.cjs`，去连 WorkBuddy 的 broker；
+// broker 只在 WorkBuddy 运行时存在 —— 于是引擎一调 `cat` 就
+// `connect failed: Connection refused`，整条任务 failed。
+//
+// 只认 `.asar` 与 `brokered-bin` 两个特征，用户自己的 PATH 顺序原样保留。
+func hostShimDir(seg string) bool {
+	v := strings.ToLower(seg)
+	return strings.Contains(v, ".asar") || strings.Contains(v, "brokered-bin")
+}
+
+// stripHostShimPath 从 PATH 值里摘掉宿主垫片目录，其余段与顺序不动。
+func stripHostShimPath(val string) string {
+	parts := strings.Split(val, string(os.PathListSeparator))
+	kept := parts[:0]
+	for _, p := range parts {
+		if p == "" || hostShimDir(p) {
+			continue
+		}
+		kept = append(kept, p)
+	}
+	return strings.Join(kept, string(os.PathListSeparator))
+}
+
+// proxyVarNames 参与「死端口」检查的代理变量名。
+//
+// 大小写两套都列：unix 上 HTTP_PROXY 与 http_proxy 是**两个不同的变量**，
+// 而 Node / Go / curl 各读各的（Node 优先小写、Go 优先大写、curl 只读小写）
+// —— 只清一套等于没清。
+//
+// NO_PROXY **不在列**：它是「绕过名单」而不是代理地址，按地址去探测没有意义。
+var proxyVarNames = []string{
+	"HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY",
+	"http_proxy", "https_proxy", "all_proxy",
+}
+
+// proxyProbeTimeout 探测本机代理端口的上限。
+//
+// 回环地址只有两种结局：立刻连上，或立刻 ECONNREFUSED —— 不存在「慢慢超时」。
+// 留 100ms 只为兜个别平台上 SYN 被丢弃的情况，别让探测本身变成新的延迟。
+const proxyProbeTimeout = 100 * time.Millisecond
+
+// loopbackProxyAddr 从一条代理变量值里取出 host:port；**不是本机回环**就返回空。
+//
+// 只认回环是刻意的保守选择：沙箱 / 隧道环境把出网流量转到 127.0.0.1:<会漂移的端口>，
+// 进程启动时拿到的快照一旦过期就是这个状态（见 strippedProxyKeys 的实测数据）。
+// 非回环（公司代理、远程 squid）**一律不碰** —— 那可能只是这一瞬间抖动，清掉会让
+// 本来能出网的引擎彻底断网，代价远大于收益。
+func loopbackProxyAddr(val string) string {
+	v := strings.TrimSpace(val)
+	if v == "" {
+		return ""
+	}
+	if i := strings.Index(v, "://"); i >= 0 { // 去 scheme：http:// https:// socks5://
+		v = v[i+3:]
+	}
+	if i := strings.IndexAny(v, "/?#"); i >= 0 { // 去 path / query
+		v = v[:i]
+	}
+	if i := strings.LastIndexByte(v, '@'); i >= 0 { // 去 user:pass@
+		v = v[i+1:]
+	}
+	host, port, err := net.SplitHostPort(v)
+	if err != nil || port == "" {
+		return ""
+	}
+	host = strings.Trim(host, "[]")
+	if !strings.EqualFold(host, "localhost") {
+		if ip := net.ParseIP(host); ip == nil || !ip.IsLoopback() {
+			return ""
+		}
+	}
+	return net.JoinHostPort(host, port)
+}
+
+// proxyAddrDead 本机 addr 上是否已经没人监听。
+func proxyAddrDead(addr string) bool {
+	c, err := net.DialTimeout("tcp", addr, proxyProbeTimeout)
+	if err != nil {
+		return true
+	}
+	c.Close()
+	return false
+}
+
+// strippedProxyKeys 返回需要**剔除**的代理变量名（可能为空）。
+//
+// 2026-10-26 实测（本机 dsh 0.2.0-rc.2，同一句提示词，各跑两遍）：
+//
+//	代理端口活着  → 首个输出 2.0~2.5s，内容正常
+//	代理端口已死  → 首个输出 **15.4s / 16.7s**，内容是 dsh: TRANSPORT: Connection error.
+//	清掉代理变量  → 首个输出 **2.0s / 2.1s**，内容正常
+//
+// 一次失败的代理连接要白等十几秒才报错 —— 这正是「会话发出去半天没响应」。
+// 而沙箱代理端口随会话漂移（旧会话留下的进程快照必然过期），所以这个状态很常见。
+// 15 秒 vs 至多一次 100ms 的探测，这个取舍没什么可犹豫的。
+//
+// 注意：**只有本机回环地址才会去探**，且同一地址在一次调用里只探一次。
+func strippedProxyKeys() []string {
+	dead := map[string]bool{} // addr → 已确认没人监听
+	var out []string
+	for _, name := range proxyVarNames {
+		addr := loopbackProxyAddr(os.Getenv(name))
+		if addr == "" {
+			continue
+		}
+		v, seen := dead[addr]
+		if !seen {
+			v = proxyAddrDead(addr)
+			dead[addr] = v
+		}
+		if v {
+			out = append(out, name)
+		}
+	}
+	return out
+}
+
 // environ 返回供子 CLI 继承的环境变量（已剔除父进程专属项）。
 func environ() []string {
 	src := os.Environ()
 	out := make([]string, 0, len(src))
+	/* 先算出「指向死端口的本机代理」，循环里直接不继承。
+	   子进程环境里就**不该出现**这个变量 —— 只补空值不行：空值虽然能压下
+	   exec 的「重复 key 取后者」，但环境块里仍留着一条 `HTTP_PROXY=http://...`
+	   的原值，任何「先写入者胜」或自己拼 map 的读取方都还会看到死地址。 */
+	deadProxy := map[string]bool{}
+	for _, k := range strippedProxyKeys() {
+		deadProxy[k] = true
+	}
 	for _, kv := range src {
 		name, _, ok := strings.Cut(kv, "=")
 		if !ok {
 			continue
 		}
-		if envDenied(name) {
+		if envDenied(name) || deadProxy[name] {
 			continue
 		}
+		if name == "NODE_OPTIONS" && hostNodeShim(kv) {
+			continue
+		}
+		/* PATH 不能整条丢（引擎全靠它找 node/python），只摘掉宿主的假命令目录。 */
+		if name == "PATH" {
+			if _, v, ok := strings.Cut(kv, "="); ok {
+				if cleaned := stripHostShimPath(v); cleaned != v {
+					out = append(out, "PATH="+cleaned)
+					continue
+				}
+			}
+		}
 		out = append(out, kv)
 	}
 	return out

package/internal/agent/env_test.go

@@ -9,6 +9,7 @@ package agent
 // 本文件锁定「SERVER__ 前缀必须被剔除」这一行为，防止回归。
 
 import (
+	"net"
 	"os"
 	"strings"
 	"testing"
@@ -146,3 +147,116 @@ func TestEnvDenied(t *testing.T) {
 		}
 	}
 }
+
+// ── 本机代理端口已死时的剔除（2026-10-26）─────────────────────────
+//
+// 背景：沙箱 / 隧道环境把出网流量转到 127.0.0.1:<会漂移的端口>，进程启动时
+// 拿到的快照一旦过期，子 CLI 每次请求都要白等十几秒才报
+// `dsh: TRANSPORT: Connection error.` —— 用户看到的就是「发出去半天没响应」。
+// 实测：代理活着 2.0s、代理已死 15.4s、清掉代理 2.0s。
+
+func TestLoopbackProxyAddr(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"http://127.0.0.1:54107", "127.0.0.1:54107"},
+		{"http://127.0.0.1:54107/", "127.0.0.1:54107"},
+		{"https://127.0.0.1:8080", "127.0.0.1:8080"},
+		{"socks5://127.0.0.1:1080", "127.0.0.1:1080"},
+		{"http://user:pass@127.0.0.1:3128", "127.0.0.1:3128"},
+		{"http://localhost:8080", "localhost:8080"},
+		{"http://[::1]:8080", "[::1]:8080"},
+		{"127.0.0.1:9999", "127.0.0.1:9999"},
+		// 非回环一律返回空：公司代理 / 远程 squid 不能因为一次抖动就断网。
+		{"http://proxy.corp.example:8080", ""},
+		{"http://10.0.0.1:8080", ""},
+		{"", ""},
+		{"   ", ""},
+		{"http://127.0.0.1", ""}, // 没端口
+		{"not a url", ""},
+	}
+	for _, c := range cases {
+		if got := loopbackProxyAddr(c.in); got != c.want {
+			t.Errorf("loopbackProxyAddr(%q) = %q, want %q", c.in, got, c.want)
+		}
+	}
+}
+
+// 死端口必须从环境块里**消失**（不是补空值：留着原值会让「先写入者胜」的
+// 读取方仍看到死地址）。大小写两套都要处理（Node/Go/curl 各读各的）。
+func TestEnvironStripsDeadLoopbackProxy(t *testing.T) {
+	dead := "http://127.0.0.1:1" // 1 号端口不会有服务
+	for _, k := range []string{"HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"} {
+		t.Setenv(k, dead)
+	}
+	for _, kv := range environ() {
+		name, val, _ := strings.Cut(kv, "=")
+		if isProxyNameForTest(name) && val == dead {
+			t.Errorf("%s 仍指向死端口：%s", name, kv)
+		}
+	}
+}
+
+// 活着的回环代理必须**原样保留** —— 断掉用户本来能用的代理是更严重的事故。
+func TestEnvironKeepsLiveLoopbackProxy(t *testing.T) {
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Skipf("无法监听回环端口：%v", err)
+	}
+	defer ln.Close()
+	go func() {
+		for {
+			c, err := ln.Accept()
+			if err != nil {
+				return
+			}
+			c.Close()
+		}
+	}()
+	live := "http://" + ln.Addr().String()
+	t.Setenv("HTTP_PROXY", live)
+	t.Setenv("http_proxy", live)
+
+	for _, kv := range environ() {
+		name, val, _ := strings.Cut(kv, "=")
+		if name == "HTTP_PROXY" || name == "http_proxy" {
+			if val != live {
+				t.Fatalf("%s 本来可用却被改了：want %q, got %q", name, live, val)
+			}
+		}
+	}
+}
+
+// 非回环代理一律不动 —— 哪怕连不上，也可能是这一瞬间抖动。
+func TestEnvironKeepsRemoteProxy(t *testing.T) {
+	remote := "http://proxy.invalid.example:3128"
+	t.Setenv("HTTP_PROXY", remote)
+	for _, kv := range environ() {
+		name, val, _ := strings.Cut(kv, "=")
+		if name == "HTTP_PROXY" && val != remote {
+			t.Fatalf("非回环代理不该被改：want %q, got %q", remote, val)
+		}
+	}
+}
+
+// NO_PROXY 是绕过名单，不是代理地址，绝不能被当成死代理剔掉。
+func TestEnvironKeepsNoProxy(t *testing.T) {
+	t.Setenv("NO_PROXY", "localhost,127.0.0.1,.internal")
+	found := false
+	for _, kv := range environ() {
+		if kv == "NO_PROXY=localhost,127.0.0.1,.internal" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatal("NO_PROXY 被误删了")
+	}
+}
+
+// isProxyNameForTest 测试侧的白名单判断（生产侧的白名单在 env.go）。
+func isProxyNameForTest(name string) bool {
+	switch name {
+	case "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY",
+		"http_proxy", "https_proxy", "all_proxy":
+		return true
+	}
+	return false
+}

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
+}