magic-agent 1.0.49 → 1.0.108

package/internal/team/schedule.go

@@ -0,0 +1,241 @@
+package team
+
+// schedule.go - 执行调度：就绪即跑（Kahn 就绪队列）+ 失败级联，收在一个窄接口后面。
+//
+// 为什么不是「按层」：分层会把同层里无关的任务捆在一起 —— t3 只依赖 t1，却要等同层
+// 跑得最慢的 t2 结束才能开始。任务数是个位数时差异不明显，但没有任何理由为「分层」
+// 付这份空转，而就绪队列的代码量并不比分层多。
+//
+// 为什么抽接口：调度语义（谁就绪、谁被跳过、并发多少、取消怎么收）和执行语义
+// （跑引擎、落盘、投影事件）是两件事。接口把前者钉死，将来换实现或接外部编排器时
+// 不用动 execute。
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// Worker 跑一个**已就绪**的任务。upstream 是此刻已结束任务的结局快照（依赖必在其中）。
+// 返回的 TaskResult 由调度器统一收进结果表；State 为空时按失败处理。
+type Worker func(ctx context.Context, t Task, upstream map[string]TaskResult) TaskResult
+
+// SkipFunc 处理一个因上游未完成（含级联）而跳过的任务：留档与收卡由调用方做。
+type SkipFunc func(t Task, reason string)
+
+// Scheduler 执行调度器。
+//
+// 契约（实现必须满足）：
+//   - 每个任务恰好被 work 或 skip 处理一次，返回值按计划顺序排列；
+//   - 只有依赖全部结束的任务才会进入 work，upstream 里至少有它的全部依赖；
+//   - 并发的 work 调用不超过上限；
+//   - 计划不合法（重复 id / 缺依赖 / 成环）返回 error，不调用任何回调；
+//   - ctx 取消后不再启动新任务，剩余任务按「已取消」跳过（可级联）。
+type Scheduler interface {
+	Run(ctx context.Context, plan Plan, work Worker, skip SkipFunc) ([]TaskResult, error)
+}
+
+// ReadyQueue 就绪即跑的调度器：依赖一结束就入队，不等同层其他任务。
+type ReadyQueue struct {
+	// Parallel 同时跑几个；<=0 取 defaultParallel（4）。
+	Parallel int
+}
+
+var _ Scheduler = ReadyQueue{}
+
+func (q ReadyQueue) parallel() int {
+	if q.Parallel > 0 {
+		return q.Parallel
+	}
+	return defaultParallel
+}
+
+func (q ReadyQueue) Run(ctx context.Context, plan Plan, work Worker, skip SkipFunc) ([]TaskResult, error) {
+	if work == nil {
+		return nil, fmt.Errorf("调度器缺少 worker")
+	}
+	n := len(plan.Tasks)
+	if n == 0 {
+		return nil, fmt.Errorf("计划里没有任务")
+	}
+
+	// 图：入度 + 反向边。id 与 deps 都先 TrimSpace —— 计划是模型产出的，
+	// " t1 " 这种写法不该变成一条不存在的依赖。
+	type node struct {
+		task       Task
+		indegree   int
+		dependents []string
+	}
+	nodes := make(map[string]*node, n)
+	order := make([]string, 0, n)
+	for _, t := range plan.Tasks {
+		id := strings.TrimSpace(t.ID)
+		if id == "" {
+			return nil, fmt.Errorf("有任务缺少 id")
+		}
+		if _, dup := nodes[id]; dup {
+			return nil, fmt.Errorf("任务 id 重复：%s", id)
+		}
+		nodes[id] = &node{task: t}
+		order = append(order, id)
+	}
+	for _, t := range plan.Tasks {
+		id := strings.TrimSpace(t.ID)
+		for _, raw := range t.Deps {
+			dep := strings.TrimSpace(raw)
+			up, ok := nodes[dep]
+			if !ok {
+				return nil, fmt.Errorf("任务 %s 依赖了不存在的任务 %q", id, dep)
+			}
+			nodes[id].indegree++
+			up.dependents = append(up.dependents, id)
+		}
+	}
+
+	// 初始就绪集：入度 0。按 id 排序，保证同一张计划每次跑的顺序一致。
+	ready := make([]string, 0, n)
+	for _, id := range order {
+		if nodes[id].indegree == 0 {
+			ready = append(ready, id)
+		}
+	}
+	sort.Strings(ready)
+
+	type completion struct {
+		id string
+		r  TaskResult
+	}
+	// 容量 n：worker 永远不会因为没人收而卡住。
+	completions := make(chan completion, n)
+	results := make(map[string]TaskResult, n)
+	blocked := make(map[string]string, n) // 任务 id → 根因（它为何没能完成）
+	finished, running := 0, 0
+
+	// 释放一个任务的后续：入度减一，归零即入就绪队列。
+	release := func(id string) {
+		for _, dep := range nodes[id].dependents {
+			nodes[dep].indegree--
+			if nodes[dep].indegree == 0 {
+				ready = append(ready, dep)
+			}
+		}
+		sort.Strings(ready)
+	}
+
+	// 记一个跳过并级联：根因继续往下传，下游报的是「最初为什么没跑成」，
+	// 而不是一层层套娃的「上游的上游……」。
+	markSkipped := func(id, reason, root string) {
+		t := nodes[id].task
+		r := TaskResult{ID: t.ID, Kind: t.EffectiveKind(), Role: t.Role, Title: t.Title, State: TaskSkipped, Reason: reason}
+		results[id] = r
+		blocked[id] = root
+		if skip != nil {
+			skip(t, reason)
+		}
+		finished++
+		release(id)
+	}
+
+	for finished < n {
+		// ① 填满并发：有依赖结束就补位，不等「整层」。
+		for running < q.parallel() && len(ready) > 0 {
+			id := ready[0]
+			ready = ready[1:]
+			t := nodes[id].task
+
+			// 上游必需任务没完成 → 本任务不跑（并级联到它的下游）。
+			if dep, root, bad := blockedBy(t, blocked); bad {
+				markSkipped(id, "上游 "+dep+" 未完成（"+root+"）", root)
+				continue
+			}
+			// 已取消：不再起新进程，剩余任务一律按「已取消」收尾。
+			if ctx.Err() != nil {
+				markSkipped(id, "已取消", "已取消")
+				continue
+			}
+
+			running++
+			upstream := snapshotResults(results)
+			go func(t Task, upstream map[string]TaskResult) {
+				completions <- completion{id: strings.TrimSpace(t.ID), r: work(ctx, t, upstream)}
+			}(t, upstream)
+		}
+
+		// ② 填完这一轮可能刚好全部收尾（尤其是级联跳过的情形），别误判成环。
+		if finished >= n {
+			break
+		}
+		// 没有在跑的、也没有就绪的 → 剩下的全卡在环上。
+		if running == 0 {
+			if len(ready) == 0 {
+				return nil, fmt.Errorf("任务依赖成环：%s", strings.Join(pendingIDs(order, results), " → "))
+			}
+			continue
+		}
+
+		// ③ 等一个结束，记结局并释放下游。
+		c := <-completions
+		running--
+		finished++
+		if strings.TrimSpace(c.r.ID) == "" {
+			c.r.ID = c.id
+		}
+		if c.r.State == "" {
+			c.r.State = TaskFailed
+		}
+		if c.r.State != TaskDone && nodes[c.id].task.IsRequired() {
+			root := strings.TrimSpace(c.r.Reason)
+			if root == "" {
+				root = "未完成"
+			}
+			blocked[c.id] = root
+		}
+		results[c.id] = c.r
+		release(c.id)
+	}
+
+	out := make([]TaskResult, 0, n)
+	for _, id := range order {
+		if r, ok := results[id]; ok {
+			out = append(out, r)
+			continue
+		}
+		out = append(out, TaskResult{ID: id, State: TaskSkipped, Reason: "未执行"})
+	}
+	return out, nil
+}
+
+// blockedBy 判断本任务是否被**必需的**上游阻断，返回直接上游 id 与根因。
+//
+// 只认 blocked 表：非必需任务失败不会进表，因此它的下游照常跑（尽力而为的语义）。
+func blockedBy(t Task, blocked map[string]string) (dep, root string, bad bool) {
+	for _, d := range t.Deps {
+		d = strings.TrimSpace(d)
+		if r, ok := blocked[d]; ok {
+			return d, r, true
+		}
+	}
+	return "", "", false
+}
+
+// snapshotResults 拿一份已结束结局的副本：worker 只读，主循环继续写。
+func snapshotResults(m map[string]TaskResult) map[string]TaskResult {
+	out := make(map[string]TaskResult, len(m))
+	for k, v := range m {
+		out[k] = v
+	}
+	return out
+}
+
+// pendingIDs 还没有结局的任务 id（成环时报错用），排序保证输出稳定。
+func pendingIDs(order []string, results map[string]TaskResult) []string {
+	var out []string
+	for _, id := range order {
+		if _, ok := results[id]; !ok {
+			out = append(out, id)
+		}
+	}
+	sort.Strings(out)
+	return out
+}

package/internal/team/schedule_test.go

@@ -0,0 +1,286 @@
+package team
+
+// schedule_test.go - 调度语义的用例。**不碰真引擎**：Worker 就是普通函数，
+// 因此这里能只测「谁先跑、谁被跳过、并发多少」，跟引擎可用性无关。
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func schedPlan(tasks ...Task) Plan { return Plan{Goal: "g", Tasks: tasks} }
+
+func schedTask(id string, deps ...string) Task {
+	return Task{ID: id, Kind: KindText, Prompt: "p", Deps: deps}
+}
+
+// TestReadyQueueStartsTaskAsSoonAsItsDepsFinish 钉住这次优化的核心：
+// t3 只依赖 t2，就不该等慢任务 t1 —— 按层调度会让它一直等到 t1 结束。
+func TestReadyQueueStartsTaskAsSoonAsItsDepsFinish(t *testing.T) {
+	plan := schedPlan(
+		schedTask("t1"),       // 慢任务：卡住不返回
+		schedTask("t2"),       // 快任务
+		schedTask("t3", "t2"), // 只依赖 t2
+	)
+
+	releaseCh := make(chan struct{})
+	var releaseOnce sync.Once
+	release := func() { releaseOnce.Do(func() { close(releaseCh) }) }
+	defer release() // 断言失败也不把 worker 永久挂住
+
+	t3ran := make(chan struct{})
+	var t1done atomic.Bool
+
+	work := func(_ context.Context, tk Task, upstream map[string]TaskResult) TaskResult {
+		switch tk.ID {
+		case "t1":
+			<-releaseCh
+			t1done.Store(true)
+		case "t2":
+			return TaskResult{ID: "t2", State: TaskDone, Text: "上游结论"}
+		case "t3":
+			if _, ok := upstream["t2"]; !ok {
+				t.Errorf("t3 的 upstream 应含 t2，实际：%v", upstream)
+			}
+			if t1done.Load() {
+				t.Error("t3 不该等 t1：它只依赖 t2（调度退化回按层了）")
+			}
+			close(t3ran)
+		}
+		return TaskResult{ID: tk.ID, State: TaskDone}
+	}
+
+	type outcome struct {
+		results []TaskResult
+		err     error
+	}
+	done := make(chan outcome, 1)
+	go func() {
+		rs, err := (ReadyQueue{Parallel: 2}).Run(context.Background(), plan, work, nil)
+		done <- outcome{rs, err}
+	}()
+
+	select {
+	case <-t3ran:
+	case <-time.After(3 * time.Second):
+		release()
+		t.Fatal("t3 在 t1 结束前没有开跑：仍然是按层阻塞")
+	}
+	release()
+
+	select {
+	case o := <-done:
+		if o.err != nil {
+			t.Fatal(o.err)
+		}
+		if len(o.results) != 3 {
+			t.Fatalf("应当 3 个结局，得到 %d", len(o.results))
+		}
+		for i, want := range []string{"t1", "t2", "t3"} {
+			if o.results[i].ID != want || o.results[i].State != TaskDone {
+				t.Fatalf("第 %d 个结局应为 done 的 %s，得到 %+v", i, want, o.results[i])
+			}
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("调度没有结束")
+	}
+}
+
+// TestReadyQueueCascadesRequiredFailure 钉住级联语义与**根因传递**：
+// t3 报的是最初的原因「超时」，而不是「上游 t2 未完成（上游 t1 未完成）」这种套娃。
+func TestReadyQueueCascadesRequiredFailure(t *testing.T) {
+	plan := schedPlan(
+		schedTask("t1"),
+		schedTask("t2", "t1"),
+		schedTask("t3", "t2"),
+		schedTask("t4"),
+	)
+
+	var workCalls sync.Map
+	work := func(_ context.Context, tk Task, _ map[string]TaskResult) TaskResult {
+		workCalls.Store(tk.ID, true)
+		if tk.ID == "t1" {
+			return TaskResult{ID: "t1", State: TaskFailed, Reason: "超时"}
+		}
+		return TaskResult{ID: tk.ID, State: TaskDone}
+	}
+
+	var skipped []string
+	results, err := (ReadyQueue{Parallel: 4}).Run(context.Background(), plan, work,
+		func(tk Task, reason string) { skipped = append(skipped, tk.ID+"："+reason) })
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(results) != 4 || results[0].ID != "t1" || results[3].ID != "t4" {
+		t.Fatalf("结局应按计划顺序返回：%+v", results)
+	}
+	if results[0].State != TaskFailed {
+		t.Fatalf("t1 应失败，得到 %s", results[0].State)
+	}
+	if _, ran := workCalls.Load("t2"); ran {
+		t.Fatal("上游必需任务失败后，t2 不该跑")
+	}
+	if _, ran := workCalls.Load("t3"); ran {
+		t.Fatal("被级联跳过的 t3 不该跑")
+	}
+	if results[1].State != TaskSkipped || !strings.Contains(results[1].Reason, "上游 t1 未完成（超时）") {
+		t.Fatalf("t2 的跳过原因不对：%+v", results[1])
+	}
+	if results[2].State != TaskSkipped || !strings.Contains(results[2].Reason, "上游 t2 未完成（超时）") {
+		t.Fatalf("t3 应继承根因「超时」：%+v", results[2])
+	}
+	if results[3].State != TaskDone {
+		t.Fatalf("无关任务 t4 应照常完成，得到 %s", results[3].State)
+	}
+	if len(skipped) != 2 {
+		t.Fatalf("应当跳过 2 个（t2/t3），得到 %v", skipped)
+	}
+}
+
+// TestReadyQueueNonRequiredFailureDoesNotBlockDownstream 钉住「尽力而为」语义：
+// required=false 的任务失败不进 blocked 表，下游照常跑。
+func TestReadyQueueNonRequiredFailureDoesNotBlockDownstream(t *testing.T) {
+	no := false
+	plan := schedPlan(
+		Task{ID: "t1", Kind: KindText, Prompt: "p", Required: &no},
+		schedTask("t2", "t1"),
+	)
+
+	work := func(_ context.Context, tk Task, _ map[string]TaskResult) TaskResult {
+		if tk.ID == "t1" {
+			return TaskResult{ID: "t1", State: TaskFailed, Reason: "没画成"}
+		}
+		return TaskResult{ID: tk.ID, State: TaskDone}
+	}
+	skipped := 0
+	results, err := (ReadyQueue{Parallel: 2}).Run(context.Background(), plan, work,
+		func(Task, string) { skipped++ })
+	if err != nil {
+		t.Fatal(err)
+	}
+	if results[0].State != TaskFailed || results[1].State != TaskDone || skipped != 0 {
+		t.Fatalf("非必需任务失败不该阻断下游：%+v（skipped=%d）", results, skipped)
+	}
+}
+
+// TestReadyQueueCancellationSkipsWithoutStarting 钉住取消语义：
+// 已经取消的 ctx 下不起任何新任务，全部按「已取消」收尾且仍有终态。
+func TestReadyQueueCancellationSkipsWithoutStarting(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	var started atomic.Int32
+	results, err := (ReadyQueue{Parallel: 2}).Run(ctx,
+		schedPlan(schedTask("t1"), schedTask("t2"), schedTask("t3", "t1")),
+		func(_ context.Context, tk Task, _ map[string]TaskResult) TaskResult {
+			started.Add(1)
+			return TaskResult{ID: tk.ID, State: TaskDone}
+		}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if started.Load() != 0 {
+		t.Fatalf("已取消时不该启动任务，实际启动 %d 个", started.Load())
+	}
+	for _, r := range results {
+		if r.State != TaskSkipped {
+			t.Fatalf("%s 应跳过，得到 %+v", r.ID, r)
+		}
+	}
+	if results[0].Reason != "已取消" || results[1].Reason != "已取消" {
+		t.Fatalf("无依赖任务的原因应为「已取消」：%+v", results)
+	}
+	if !strings.Contains(results[2].Reason, "上游 t1 未完成（已取消）") {
+		t.Fatalf("下游应继承「已取消」根因：%+v", results[2])
+	}
+}
+
+// TestReadyQueueRejectsInvalidPlans 钉住「非法计划不调用任何回调」。
+func TestReadyQueueRejectsInvalidPlans(t *testing.T) {
+	cases := []struct {
+		name string
+		plan Plan
+		want string
+	}{
+		{"空计划", Plan{}, "没有任务"},
+		{"重复 id", schedPlan(schedTask("t1"), schedTask("t1")), "重复"},
+		{"缺依赖", schedPlan(schedTask("t1", "t9")), "不存在的任务"},
+		{"成环", schedPlan(schedTask("t1", "t2"), schedTask("t2", "t1")), "成环"},
+		{"自依赖", schedPlan(schedTask("t1", "t1")), "成环"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			called := false
+			_, err := (ReadyQueue{Parallel: 2}).Run(context.Background(), c.plan,
+				func(_ context.Context, tk Task, _ map[string]TaskResult) TaskResult {
+					called = true
+					return TaskResult{ID: tk.ID, State: TaskDone}
+				}, func(Task, string) { called = true })
+			if err == nil || !strings.Contains(err.Error(), c.want) {
+				t.Fatalf("应报含 %q 的错误，得到 %v", c.want, err)
+			}
+			if called {
+				t.Fatal("非法计划不该调用 worker / skip")
+			}
+		})
+	}
+}
+
+// TestReadyQueueRespectsParallel 钉住并发上限：满了就不再启动，释放一个才补一个。
+func TestReadyQueueRespectsParallel(t *testing.T) {
+	plan := schedPlan(schedTask("t1"), schedTask("t2"), schedTask("t3"), schedTask("t4"))
+
+	releaseCh := make(chan struct{})
+	var releaseOnce sync.Once
+	release := func() { releaseOnce.Do(func() { close(releaseCh) }) }
+	defer release()
+
+	started := make(chan string, 8)
+	var mu sync.Mutex
+	running, peak := 0, 0
+
+	work := func(_ context.Context, tk Task, _ map[string]TaskResult) TaskResult {
+		mu.Lock()
+		running++
+		if running > peak {
+			peak = running
+		}
+		mu.Unlock()
+
+		started <- tk.ID
+		<-releaseCh
+
+		mu.Lock()
+		running--
+		mu.Unlock()
+		return TaskResult{ID: tk.ID, State: TaskDone}
+	}
+
+	done := make(chan error, 1)
+	go func() {
+		_, err := (ReadyQueue{Parallel: 2}).Run(context.Background(), plan, work, nil)
+		done <- err
+	}()
+
+	<-started
+	<-started
+	select {
+	case id := <-started:
+		t.Fatalf("并发上限为 2，却又启动了 %s", id)
+	case <-time.After(150 * time.Millisecond):
+	}
+
+	release()
+	if err := <-done; err != nil {
+		t.Fatal(err)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if peak != 2 {
+		t.Fatalf("峰值并发应为 2，得到 %d", peak)
+	}
+}

package/internal/team/subsession.go

@@ -0,0 +1,27 @@
+package team
+
+// subsession.go - 子任务的「会话化」出口。
+//
+// 团队包不依赖 internal/session 与日志实现（那是 CLI 的职责），只通过 SubSession
+// 把三件事委托出去：登记（可出现在会话列表、可单独停止）、过程事件写自己的日志、
+// 收尾状态。调用方不提供（OpenSubSession 为空）时退回旧行为：只在主会话里留任务行。
+
+import (
+	"context"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// SubSession 一个子任务在调用方侧对应的会话。
+type SubSession interface {
+	// RunID 这条子会话的登记 id（空 = 没登记，例如调用方没开 --save-registry）。
+	RunID() string
+	// SetSessionID 引擎一给出会话 id 就通知（通常早于事件流里出现）。
+	SetSessionID(id string)
+	// Push 子任务的一条过程事件：写它自己的会话日志，不进主会话。
+	Push(ev agent.StreamEvent)
+	// Finish 收尾。state 取 TaskDone / TaskFailed / TaskSkipped。
+	Finish(sessionID, state, reason string)
+	// Context 在子任务 ctx 上挂「子引擎 pid 登记」的钩子，返回新 ctx。
+	Context(parent context.Context) context.Context
+}