magic-agent 2.4.2 → 2.6.0

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)

package/internal/team/fallback_route_test.go

@@ -0,0 +1,80 @@
+package team
+
+// fallback_route_test.go - 团队路由的主备解析（2026-10-24）。
+//
+// 关注三件事：某一类/角色可以单独配「备」；只配备用 = 主引擎跟随主引擎；
+// 配错的备用引擎在开跑前就报（别等主引擎失败才发现降级目标也没有）。
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestRouteForFallback(t *testing.T) {
+	main := &fakeEngine{name: "main"}
+	opts := Options{
+		Engine:         main,
+		FallbackEngine: "main-backup",
+		Routes: map[string]Route{
+			"role:coder": {Engine: "coder-engine", FallbackEngine: "coder-backup"},
+			"image":      {FallbackEngine: "image-backup"}, // 只配备用
+		},
+	}
+
+	// 角色路由：主备都取角色那一路。
+	r := RouteFor(Task{ID: "t1", Role: "coder"}, opts)
+	if r.Engine != "coder-engine" || r.FallbackEngine != "coder-backup" {
+		t.Errorf("coder 路由 = %+v", r)
+	}
+
+	// 只配备用：主引擎仍是主引擎，备用是这一类自己的。
+	r = RouteFor(Task{ID: "t2", Role: "designer"}, opts)
+	if r.Engine != "main" || r.FallbackEngine != "image-backup" {
+		t.Errorf("只配了备用的 image 路由 = %+v", r)
+	}
+
+	// 完全没配：主备都跟随主引擎。
+	r = RouteFor(Task{ID: "t3", Role: "writer"}, opts)
+	if r.Engine != "main" || r.FallbackEngine != "main-backup" {
+		t.Errorf("跟随主引擎的 writer 路由 = %+v", r)
+	}
+}
+
+func TestPlanRouteFallback(t *testing.T) {
+	main := &fakeEngine{name: "main"}
+	r := PlanRoute(Options{Engine: main, FallbackEngine: "main-backup"})
+	if r.Engine != "main" || r.FallbackEngine != "main-backup" {
+		t.Errorf("plan 跟随主引擎 = %+v", r)
+	}
+	r = PlanRoute(Options{Engine: main, Routes: map[string]Route{KindPlan: {Engine: "planner", FallbackEngine: "planner-bk"}}})
+	if r.Engine != "planner" || r.FallbackEngine != "planner-bk" {
+		t.Errorf("plan 显式路由 = %+v", r)
+	}
+}
+
+func TestApplyFallbacks(t *testing.T) {
+	routes, err := ParseRoutes([]string{"image=img"})
+	if err != nil {
+		t.Fatalf("ParseRoutes: %v", err)
+	}
+	routes, err = ApplyFallbacks(routes, []string{"image=img-bk/m2", "role:coder=cd-bk"})
+	if err != nil {
+		t.Fatalf("ApplyFallbacks: %v", err)
+	}
+	if r := routes["image"]; r.Engine != "img" || r.FallbackEngine != "img-bk" || r.FallbackModel != "m2" {
+		t.Errorf("image = %+v", r)
+	}
+	if r := routes["role:coder"]; r.Engine != "" || r.FallbackEngine != "cd-bk" {
+		t.Errorf("只给角色配备用时应保留空主引擎：%+v", r)
+	}
+	if _, err := ApplyFallbacks(nil, []string{"audio=x"}); err == nil {
+		t.Error("未知类别应当报错")
+	}
+}
+
+func TestValidateRoutesChecksFallback(t *testing.T) {
+	err := ValidateRoutes(map[string]Route{"image": {Engine: "llm", FallbackEngine: "不存在的引擎"}})
+	if err == nil || !strings.Contains(err.Error(), "备用") {
+		t.Fatalf("备用引擎不存在应当在开跑前报出来，得到 %v", err)
+	}
+}

package/internal/team/planner.go

@@ -198,8 +198,8 @@ func makePlan(ctx context.Context, opts Options) (Plan, string, error) {
 		prompt = strings.Join(hints, "\n\n") + "\n\n用户诉求：\n" + prompt
 	}
 
-	runner := &agent.Runner{Engine: eng, Timeout: taskTimeout(opts)}
-	resp, err := runner.Run(pctx, agent.Request{
+	runnerOpts := agent.RunOptions{Timeout: taskTimeout(opts)}
+	resp, _, err := agent.RunWithFallback(pctx, eng, agent.Request{
 		Engine:       eng.Name(),
 		Model:        route.Model,
 		SystemPrompt: strings.TrimSpace(opts.SystemPrompt + "\n\n" + plannerPrompt(opts)),
@@ -212,12 +212,24 @@ func makePlan(ctx context.Context, opts Options) (Plan, string, error) {
 		Reasoning:  opts.Reasoning,
 		SessionID:  sid,
 		Continue:   sid == "" && onMain && opts.Continue,
+		// 计划阶段同样主备：`plan` 行的备用引擎（没配就跟随主引擎的备用）。
+		// 这是最常见的故障点 —— 主引擎额度用尽时，计划都出不来（2026-10-24 报障）。
+		FallbackEngine: route.FallbackEngine,
+		FallbackModel:  route.FallbackModel,
+	}, runnerOpts, func(fe agent.FallbackEvent) {
+		opts.OnEvent(agent.StreamEvent{
+			Kind:     agent.KindFallback,
+			Text:     "团队模式：" + agent.FallbackNoticeText(fe),
+			Fallback: &fe,
+		})
 	})
 	if err != nil {
 		return Plan{}, "", err
 	}
 	plan, perr := parsePlan(resp.Text)
-	if !onMain {
+	/* 计划由**备用引擎**跑出来时，resp.SessionID 是备用引擎的会话：不能交给主引擎汇总
+	   （跨引擎续接是错的）。汇总改开新会话，计划内容本身不受影响。 */
+	if !onMain || !strings.EqualFold(resp.Engine, opts.Engine.Name()) {
 		return plan, "", perr
 	}
 	return plan, resp.SessionID, perr

package/internal/team/route.go

@@ -33,17 +33,32 @@ func RouteFor(t Task, opts Options) Route {
 		return Route{Engine: e, Model: strings.TrimSpace(t.Model)}
 	}
 	role := LookupRole(t.Role)
+	kind := t.EffectiveKind()
+	roleRoute, roleOK := Route{}, false
 	if role != nil {
-		if r, ok := routeForRole(opts.Routes, role.Name); ok {
-			m := strings.TrimSpace(r.Model)
-			if m == "" {
-				m = strings.TrimSpace(role.Model)
-			}
-			return Route{Engine: strings.TrimSpace(r.Engine), Model: m}
+		roleRoute, roleOK = routeForRole(opts.Routes, role.Name)
+	}
+	kindRoute, kindOK := opts.Routes[kind]
+
+	/* 备用取「最终选中那一路」的：角色 > 类别 > 主引擎。
+	   允许只配备用（主引擎留空 = 跟随主引擎 + 这一路的备）—— 界面上「主/备」
+	   两格本来就都可能单独填。 */
+	fbE, fbM := strings.TrimSpace(opts.FallbackEngine), strings.TrimSpace(opts.FallbackModel)
+	if e, m, ok := fallbackOf(roleRoute); ok {
+		fbE, fbM = e, m
+	} else if e, m, ok := fallbackOf(kindRoute); ok {
+		fbE, fbM = e, m
+	}
+
+	if roleOK && strings.TrimSpace(roleRoute.Engine) != "" {
+		m := strings.TrimSpace(roleRoute.Model)
+		if m == "" {
+			m = strings.TrimSpace(role.Model)
 		}
+		return Route{Engine: strings.TrimSpace(roleRoute.Engine), Model: m, FallbackEngine: fbE, FallbackModel: fbM}
 	}
-	if r, ok := opts.Routes[t.EffectiveKind()]; ok && strings.TrimSpace(r.Engine) != "" {
-		return Route{Engine: strings.TrimSpace(r.Engine), Model: strings.TrimSpace(r.Model)}
+	if kindOK && strings.TrimSpace(kindRoute.Engine) != "" {
+		return Route{Engine: strings.TrimSpace(kindRoute.Engine), Model: strings.TrimSpace(kindRoute.Model), FallbackEngine: fbE, FallbackModel: fbM}
 	}
 	// 默认「跟随主引擎」：不分类别，text / image / video / game 一视同仁。
 	if opts.Engine != nil {
@@ -52,13 +67,24 @@ func RouteFor(t Task, opts Options) Route {
 		if strings.TrimSpace(m) == "" && role != nil {
 			m = strings.TrimSpace(role.Model)
 		}
-		return Route{Engine: opts.Engine.Name(), Model: m}
+		return Route{Engine: opts.Engine.Name(), Model: m, FallbackEngine: fbE, FallbackModel: fbM}
 	}
 	return Route{}
 }
 
+// fallbackOf 取一条路由上配置的备用引擎（空 = 没配）。
+func fallbackOf(r Route) (string, string, bool) {
+	e := strings.TrimSpace(r.FallbackEngine)
+	if e == "" {
+		return "", "", false
+	}
+	return e, strings.TrimSpace(r.FallbackModel), true
+}
+
 // routeForRole 在路由表里找角色配置：规范键 `role:<name>` 优先，裸角色名也认
 // （客户端旧配置 / 手写 routes 里可能不带前缀）。
+//
+// 返回的引擎可能为空（只给这一路配了备用 = 主引擎仍跟随主引擎）；调用方按需判断。
 func routeForRole(routes map[string]Route, name string) (Route, bool) {
 	if len(routes) == 0 {
 		return Route{}, false
@@ -67,7 +93,7 @@ func routeForRole(routes map[string]Route, name string) (Route, bool) {
 		if key == "" {
 			continue
 		}
-		if r, ok := routes[key]; ok && strings.TrimSpace(r.Engine) != "" {
+		if r, ok := routes[key]; ok {
 			return r, true
 		}
 	}
@@ -79,11 +105,22 @@ func routeForRole(routes map[string]Route, name string) (Route, bool) {
 // 与子任务同一套语义：显式配了 plan 就用它，没配跟随主引擎 —— 计划本来就是主引擎的活。
 // 返回空引擎只发生在主引擎也为空时（Run 已提前拦掉）。
 func PlanRoute(opts Options) Route {
-	if r, ok := opts.Routes[KindPlan]; ok && strings.TrimSpace(r.Engine) != "" {
-		return Route{Engine: strings.TrimSpace(r.Engine), Model: strings.TrimSpace(r.Model)}
+	planRoute, hasPlan := opts.Routes[KindPlan]
+	fbE, fbM := strings.TrimSpace(opts.FallbackEngine), strings.TrimSpace(opts.FallbackModel)
+	if e, m, ok := fallbackOf(planRoute); ok {
+		fbE, fbM = e, m
+	}
+	if hasPlan && strings.TrimSpace(planRoute.Engine) != "" {
+		return Route{
+			Engine: strings.TrimSpace(planRoute.Engine), Model: strings.TrimSpace(planRoute.Model),
+			FallbackEngine: fbE, FallbackModel: fbM,
+		}
 	}
 	if opts.Engine != nil {
-		return Route{Engine: opts.Engine.Name(), Model: opts.Model}
+		return Route{
+			Engine: opts.Engine.Name(), Model: opts.Model,
+			FallbackEngine: fbE, FallbackModel: fbM,
+		}
 	}
 	return Route{}
 }
@@ -102,6 +139,11 @@ func ValidateRoutes(routes map[string]Route) error {
 		if agent.Lookup(name) == nil {
 			bad = append(bad, fmt.Sprintf("%s→%s", kind, name))
 		}
+		// 备用引擎同样要真实存在：配错了要在开跑前报，而不是等主引擎失败后
+		// 才发现「降级目标也没有」（那时用户已经白等一轮）。
+		if fb := strings.TrimSpace(r.FallbackEngine); fb != "" && agent.Lookup(fb) == nil {
+			bad = append(bad, fmt.Sprintf("%s→备用 %s", kind, fb))
+		}
 	}
 	if len(bad) > 0 {
 		return fmt.Errorf("未知引擎：%s（可用引擎见 magic-agent --engines）", strings.Join(bad, "、"))
@@ -114,6 +156,36 @@ func ValidateRoutes(routes map[string]Route) error {
 // 模型名里可能有 `/`（如 `anthropic/claude-x`），所以只按**第一个** `/` 切：
 // 前段是引擎，其余全是模型名。
 func ParseRoutes(values []string) (map[string]Route, error) {
+	return parseRouteSpecs(values, "--team-route")
+}
+
+// ApplyFallbacks 把 `--team-fallback <key>=<engine>[/<model>]` 合并进路由表：
+// 只给某一类 / 某个角色配备用引擎，主引擎仍由 routes 决定。
+//
+// 与 --team-route 同一套键（plan + 五类 + role:<name>）与同一套取值语法 ——
+// 客户端「团队模式」里每行一个「主 / 备」，下发时就是这两组 flag。
+func ApplyFallbacks(routes map[string]Route, values []string) (map[string]Route, error) {
+	specs, err := parseRouteSpecs(values, "--team-fallback")
+	if err != nil {
+		return routes, err
+	}
+	if len(specs) == 0 {
+		return routes, nil
+	}
+	if routes == nil {
+		routes = make(map[string]Route, len(specs))
+	}
+	for key, fb := range specs {
+		base := routes[key]
+		base.FallbackEngine = strings.TrimSpace(fb.Engine)
+		base.FallbackModel = strings.TrimSpace(fb.Model)
+		routes[key] = base
+	}
+	return routes, nil
+}
+
+// parseRouteSpecs 解析 `<key>=<engine>[/<model>]` 形态的重复 flag（路线 / 备用共用）。
+func parseRouteSpecs(values []string, flag string) (map[string]Route, error) {
 	if len(values) == 0 {
 		return nil, nil
 	}
@@ -125,16 +197,16 @@ func ParseRoutes(values []string) (map[string]Route, error) {
 		}
 		eq := strings.IndexByte(s, '=')
 		if eq <= 0 {
-			return nil, fmt.Errorf("--team-route 取值应为 <类别>=<引擎>[/<模型>]，收到 %q", v)
+			return nil, fmt.Errorf("%s 取值应为 <类别>=<引擎>[/<模型>]，收到 %q", flag, v)
 		}
 		kind := normalizeRouteKind(s[:eq])
 		if kind == "" {
-			return nil, fmt.Errorf("--team-route 的类别 %q 不支持（可选：%s；角色用 role:<%s>）",
-				s[:eq], strings.Join(RouteKinds, " / "), strings.Join(RoleNames(), " / "))
+			return nil, fmt.Errorf("%s 的类别 %q 不支持（可选：%s；角色用 role:<%s>）",
+				flag, s[:eq], strings.Join(RouteKinds, " / "), strings.Join(RoleNames(), " / "))
 		}
 		rest := strings.TrimSpace(s[eq+1:])
 		if rest == "" {
-			return nil, fmt.Errorf("--team-route %s 缺少引擎名", kind)
+			return nil, fmt.Errorf("%s %s 缺少引擎名", flag, kind)
 		}
 		r := Route{Engine: rest}
 		if i := strings.IndexByte(rest, '/'); i > 0 {

package/internal/team/team.go

@@ -81,6 +81,12 @@ var RouteKinds = []string{KindPlan, KindText, KindCode, KindImage, KindVideo, Ki
 type Route struct {
 	Engine string
 	Model  string
+	// FallbackEngine / FallbackModel 这一路的备用引擎（2026-10-24）。
+	//
+	// 主引擎只有过程、没有正文时自动降级一次（见 agent/fallback.go）。空 = 不降级。
+	// 客户端「团队模式」里每个角色都可以配主 / 备两档。
+	FallbackEngine string
+	FallbackModel  string
 }
 
 // Options 一次团队调用的全部输入。
@@ -89,6 +95,12 @@ type Options struct {
 	Engine agent.Engine
 	// Model 主引擎的模型（空 = 引擎默认）。
 	Model string
+	// FallbackEngine / FallbackModel 主引擎的备用（2026-10-24；口径见 agent/fallback.go）。
+	//
+	// 「跟随主引擎」的那几类子任务与计划阶段都用它做降级目标；某一类/角色单独配了
+	// route 时，以 route 自己的 Fallback* 为准。空 = 不降级。
+	FallbackEngine string
+	FallbackModel  string
 	// Prompt 用户原始诉求。
 	Prompt string
 	// SystemPrompt 主引擎的系统提示词（计划与汇总都注入）。
@@ -127,7 +139,8 @@ type Options struct {
 	// BaseDir 覆盖运行目录的父目录（空 = 按 chooseRunDir 推断）。
 	BaseDir string
 
-	// Permission 子任务的权限上限（默认 accept-edits，见 DefaultTaskPermission）。
+	// Permission 子任务的权限上限（空 = 用 DefaultTaskPermission；CLI 会传主会话的档位，
+	// 即默认**继承主会话**）。
 	Permission agent.PermissionTier
 	// PermissionOptions 与 Permission 配套的四档选项。
 	PermissionOptions agent.PermissionOptions
@@ -161,10 +174,11 @@ type Options struct {
 	OpenSubSession func(t Task, runDir, engine, model string) SubSession
 }
 
-// DefaultTaskPermission 子任务的默认权限上限。
+// DefaultTaskPermission Go 调用方的零值兜底（CLI 不传时会**继承主会话**，不走这里）。
 //
-// 刻意**低于**主会话的默认档（full）：子任务是自己拆出来的一段活，让它带
-// 「完全访问」等于把一次授权扩成 N 份。要放开就显式传 --team-permission。
+// 为什么兜底是 accept-edits 而不是 full：Options.Permission 为空说明调用方没表态，
+// 静默给「完全访问」等于把一次授权扩成 N 份。CLI 走的是继承路径（见 internal/cli/team.go），
+// 子任务权限与主会话一致；要把子任务压得更严再用 --team-permission 显式指定。
 const DefaultTaskPermission = agent.PermissionAcceptEdits
 
 const defaultParallel = 4

package/npm/apk/version.json

@@ -1,5 +1 @@
-{
-  "version": "2.4.2",
-  "versionCode": 20402,
-  "builtAt": "2026-10-23T11:49:45.889Z"
-}
+{ "versionCode": 20600, "version": "2.6.0", "builtAt": "2026-10-25T09:20:06.000Z" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-agent",
-  "version": "2.4.2",
+  "version": "2.6.0",
   "description": "专业的 agent CLI 代理工具 - 统一 claude / codebuddy / trae / llm / codex / openclaw 引擎",
   "license": "MIT",
   "bin": {
@@ -14,13 +14,19 @@
     "prepack": "node npm/build.js",
     "postinstall": "node npm/install.js",
     "check:ui": "node tests/check-ui-spec.mjs",
+    "check:notify": "node tests/check-notify.mjs",
     "check:pin": "node tests/check-task-pin.mjs",
+    "check:space": "node tests/check-space-label.mjs",
+    "check:space-ui": "node tests/check-space-label-ui.mjs",
+    "check:scripts": "node tests/check-scripts-ui.mjs",
+    "check:scripts-ui": "node tests/check-scripts-ui-browser.mjs",
     "check:conv": "node tests/check-conv-shards.mjs",
     "check:conv-host": "node tests/check-conv-shared-host.mjs",
     "check:conv-mobile": "node tests/check-conv-mobile-host.mjs",
     "check:conv-comp": "node tests/check-conv-component.mjs",
     "check:conv-queue": "node tests/check-conv-queue.mjs",
-    "check:follow": "node tests/check-follow-retry.mjs"
+    "check:follow": "node tests/check-follow-retry.mjs",
+    "check:req-shot": "node tests/check-req-shot.mjs"
   },
   "files": [
     "npm/bin/",