magic-agent 1.0.49 → 1.0.108

package/internal/session/status_test.go

@@ -0,0 +1,144 @@
+package session
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// withStatusHome 把状态表指到临时目录（不碰用户真实的 ~/.magic-agent）。
+// 缓存按路径失效（见 statusCachePath），所以这里只需换目录。
+func withStatusHome(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	t.Setenv(EnvDir, filepath.Join(dir, "sessions"))
+	statusMu.Lock()
+	statusCache, statusLoaded, statusCachePath = nil, false, ""
+	statusMu.Unlock()
+	return dir
+}
+
+// TestStatusFollowsHandleLifecycle 写登记表的每一步都要顺手更新会话级状态：
+// Begin → running、Mark → idle、Finish → done。客户端只读这一个字段。
+func TestStatusFollowsHandleLifecycle(t *testing.T) {
+	withStatusHome(t)
+	h, err := Begin(BeginOptions{Engine: "fake", SessionID: "sess-1", PID: os.Getpid()})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := StatusForAny("sess-1", h.RunID()); got != StateRunning {
+		t.Fatalf("Begin 后 status = %q，want %q", got, StateRunning)
+	}
+	h.Mark(StateIdle) // 常驻会话轮次之间
+	if got := StatusFor("sess-1"); got != StateIdle {
+		t.Fatalf("Mark(idle) 后 status = %q，want %q", got, StateIdle)
+	}
+	h.Finish("sess-1", StateDone)
+	if got := StatusFor("sess-1"); got != StateDone {
+		t.Fatalf("Finish(done) 后 status = %q，want %q", got, StateDone)
+	}
+	// 落盘形状：与标题表同目录、同风格，换实现不换位置。
+	p, err := StatusStorePath()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if filepath.Base(p) != "session-status.json" {
+		t.Fatalf("状态表文件名 = %s", p)
+	}
+	if b, err := os.ReadFile(p); err != nil || len(b) == 0 {
+		t.Fatalf("状态表没落盘：%v", err)
+	}
+}
+
+// TestStatusNoPersistLeavesNoTrace NoPersist 的会话连状态也不该留（与登记表一致）。
+func TestStatusNoPersistLeavesNoTrace(t *testing.T) {
+	withStatusHome(t)
+	h, err := Begin(BeginOptions{Engine: "fake", SessionID: "sess-np", NoPersist: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := StatusFor("sess-np"); got != "" {
+		t.Fatalf("NoPersist 会话不该有状态，实得 %q", got)
+	}
+	h.Finish("sess-np", StateDone)
+	if got := StatusFor("sess-np"); got != "" {
+		t.Fatalf("NoPersist 收尾后也不该有状态，实得 %q", got)
+	}
+}
+
+// TestStatusStaleRunCannotOverwriteNewer 旧一轮迟到的 done/gone 不能盖掉新一轮的 running。
+// 没有这条守卫时，界面会出现「明明在跑却显示已完成」。
+func TestStatusStaleRunCannotOverwriteNewer(t *testing.T) {
+	withStatusHome(t)
+	now := time.Now()
+	setStatus(Record{RunID: "run-new", SessionID: "sess-1", State: StateRunning, StartedAt: now})
+	setStatus(Record{RunID: "run-old", SessionID: "sess-1", State: StateDone,
+		StartedAt: now.Add(-time.Hour)})
+	if got := StatusFor("sess-1"); got != StateRunning {
+		t.Fatalf("旧一轮把新一轮盖掉了：status = %q，want %q", got, StateRunning)
+	}
+	// 反过来（新一轮写终态）必须生效。
+	setStatus(Record{RunID: "run-new", SessionID: "sess-1", State: StateDone, StartedAt: now})
+	if got := StatusFor("sess-1"); got != StateDone {
+		t.Fatalf("同一轮的状态更新没生效：%q", got)
+	}
+}
+
+// TestStatusMigratesRunKeyToSession 先落在 run_id 上的键，拿到 session_id 后迁走并删除旧键
+// —— 留着双键，按不同 id 读就会拿到两个状态（与标题同一个坑）。
+func TestStatusMigratesRunKeyToSession(t *testing.T) {
+	withStatusHome(t)
+	started := time.Now().Add(-time.Minute)
+	setStatus(Record{RunID: "run-1", State: StateRunning, StartedAt: started})
+	if got := StatusFor("run-1"); got != StateRunning {
+		t.Fatalf("前置条件：run 键上应有状态，实得 %q", got)
+	}
+	setStatus(Record{RunID: "run-1", SessionID: "sess-1", State: StateRunning, StartedAt: started})
+	if got := StatusFor("sess-1"); got != StateRunning {
+		t.Fatalf("session 键上应有状态，实得 %q", got)
+	}
+	if got := StatusFor("run-1"); got != "" {
+		t.Fatalf("迁移后旧 run 键该被清掉，实得 %q", got)
+	}
+}
+
+// TestStatusForAnyPrefersSession session_id 优先、run_id 兜底。
+func TestStatusForAnyPrefersSession(t *testing.T) {
+	withStatusHome(t)
+	now := time.Now()
+	setStatus(Record{RunID: "run-1", SessionID: "sess-1", State: StateIdle, StartedAt: now})
+	if got := StatusForAny("sess-1", "run-x"); got != StateIdle {
+		t.Fatalf("StatusForAny(按 session) = %q", got)
+	}
+	setStatus(Record{RunID: "run-2", State: StateRunning, StartedAt: now})
+	if got := StatusForAny("", "run-2"); got != StateRunning {
+		t.Fatalf("StatusForAny(按 run) = %q", got)
+	}
+	if got := StatusForAny("", ""); got != "" {
+		t.Fatalf("空 id 应为空，实得 %q", got)
+	}
+}
+
+// TestDeleteDropsStatuses 会话删了，状态覆盖也要清 —— 否则同 id 再建会话会继承过期状态。
+func TestDeleteDropsStatuses(t *testing.T) {
+	withStatusHome(t)
+	h, err := Begin(BeginOptions{Engine: "fake", SessionID: "sess-del", PID: os.Getpid()})
+	if err != nil {
+		t.Fatal(err)
+	}
+	h.Finish("sess-del", StateDone)
+	if got := StatusFor("sess-del"); got != StateDone {
+		t.Fatalf("前置条件：status = %q", got)
+	}
+	res, err := Delete("sess-del")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusesRemoved != 1 {
+		t.Fatalf("StatusesRemoved = %d，want 1", res.StatusesRemoved)
+	}
+	if got := StatusFor("sess-del"); got != "" {
+		t.Fatalf("删除后状态该被清掉，实得 %q", got)
+	}
+}

package/internal/team/adaptive.go

@@ -0,0 +1,293 @@
+package team
+
+// adaptive.go - 执行中再规划：按失败原因与交接单的 open 项追加补充任务。
+//
+// 静态计划只能基于「用户说了什么」。真正跑起来才知道哪里会失败、上游交接单里
+// 还留了哪些没解决的事。adaptive 在**一轮执行结束之后**读这两个信号，让主引擎
+// 判断要不要补任务：
+//
+//	信号一  必需任务失败（skipped 不算 —— 它是级联结果，根因在失败的那个任务上）
+//	信号二  已完成任务的交接单里有 open 项
+//
+// 纪律（写死，别放开）：
+//   - **只补一轮**、每次最多 adaptiveMaxTasks 个；避免「再规划 → 又失败 → 再规划」
+//     把一轮团队调用拖成无限循环。
+//   - **只增不改**：已跑完的任务与已写的 TASK-*.md 都不动，补充任务用独立 id
+//     （a1..aN）追加到任务列表末尾（board.add）。
+//   - 再规划失败 / 没有补充任务 / 与现有计划冲突 → 发一条 notice 后按当前结果收尾，
+//     **绝不**打断整轮（汇总仍会给出答案）。
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+const (
+	// adaptiveMaxTasks 一轮再规划最多补几个任务。
+	adaptiveMaxTasks = 3
+	// adaptiveOpenPerTask 每个任务最多取几条 open 项进提示词。
+	adaptiveOpenPerTask = 3
+	// adaptiveMarker 再规划请求的系统提示词标记（测试据此区分计划轮与再规划轮）。
+	adaptiveMarker = "再规划"
+)
+
+// adaptiveSystemPrompt 再规划阶段的补充要求（接在 plannerSystemPrompt 之后）。
+const adaptiveSystemPrompt = `你是同一个任务的**再规划**阶段：第一轮计划已经执行完，下面是失败的任务与交接单里留下的未解决项。
+
+只输出一个 JSON 对象，结构与上一轮完全相同（goal + tasks）：
+- 每个补充任务的 **role 必填**（同上一轮的角色表，类别由角色决定）；
+- 只列**补充任务**，不要复述已经完成的任务；
+- 最多 3 个；不需要补充就直接输出 {"goal":"…","tasks":[]}；
+- id 随便写，core 会重编号为 a1、a2…；
+- deps 只能引用本批补充任务的 id（不要引用已经跑完的原任务）；
+- 每个补充任务的 prompt 必须**自包含**：执行者看不到这段对话，也看不到原任务正文；
+  需要上游文件时，把绝对路径写进 prompt 或 inputs；
+- 只补「不做就交不了活」的缺口，不要为了凑数补任务。`
+
+// adaptiveSignals 收集触发再规划的信号。
+//
+// 返回空 = 本轮没有需要补的事，调用方应当**静默**返回（成功轮次不该被一条
+// 「正在再规划」打扰）。
+func adaptiveSignals(plan Plan, results []TaskResult) []string {
+	var out []string
+	for _, r := range results {
+		t, ok := findTask(plan, r.ID)
+		if !ok {
+			continue
+		}
+		// skipped 是级联结果：根因任务已经单独报过，再为它补一次只会重复。
+		if r.State == TaskSkipped {
+			continue
+		}
+		if r.State != TaskDone {
+			if !t.IsRequired() {
+				continue
+			}
+			out = append(out, fmt.Sprintf("任务 %s「%s」失败：%s",
+				r.ID, orDash(r.Title), orDash(r.Reason)))
+			continue
+		}
+		if r.Handoff == nil {
+			continue
+		}
+		var open []string
+		for _, o := range r.Handoff.Open {
+			if s := strings.TrimSpace(o); s != "" {
+				open = append(open, oneLine(s))
+			}
+			if len(open) >= adaptiveOpenPerTask {
+				break
+			}
+		}
+		if len(open) == 0 {
+			continue
+		}
+		out = append(out, fmt.Sprintf("任务 %s「%s」留下未解决项：%s",
+			r.ID, orDash(r.Title), strings.Join(open, "；")))
+	}
+	return out
+}
+
+// adaptiveReplan 执行一轮再规划，返回（合并后的计划，追加后的结果）。
+//
+// 失败路径全部收敛为「原样返回 + 一条 notice」：再规划是**增强**，不是必需环节，
+// 它不该让一轮本来能汇总的团队调用变成 error。
+func adaptiveReplan(ctx context.Context, opts Options, plan Plan, results []TaskResult,
+	runDir, planSession string, board *Board) (Plan, []TaskResult) {
+	signals := adaptiveSignals(plan, results)
+	if len(signals) == 0 {
+		return plan, results
+	}
+	board.notice(fmt.Sprintf("团队模式：发现 %d 个未完成 / 未解决项，正在判断是否补充任务…", len(signals)))
+
+	extra, err := makeAdaptivePlan(ctx, opts, plan, signals, planSession)
+	if err != nil {
+		board.notice("团队模式：补充任务规划失败，按当前结果收尾：" + err.Error())
+		return plan, results
+	}
+	var dup int
+	extra, dup = normalizeAdaptiveTasks(extra, plan)
+	if dup > 0 {
+		board.notice(fmt.Sprintf("团队模式：%d 个补充任务与原任务同名（等同重试，重试由执行器负责），已跳过", dup))
+	}
+	if len(extra) == 0 {
+		board.notice("团队模式：没有需要补充的任务，按当前结果收尾")
+		return plan, results
+	}
+
+	merged := Plan{
+		Goal:  plan.Goal,
+		Tasks: append(append([]Task{}, plan.Tasks...), extra...),
+	}
+	if err := merged.Validate(); err != nil {
+		board.notice("团队模式：补充任务与现有计划冲突，跳过：" + err.Error())
+		return plan, results
+	}
+	// PLAN.md 重写成「原计划 + 补充任务」：它是全队共享的事实源，后来者（补跑、
+	// 人工查看）必须看到完整的任务集合，而不是只有第一轮。
+	if err := WritePlanDoc(runDir, merged, opts); err != nil {
+		board.notice("团队模式：更新计划文档失败，跳过补充任务：" + err.Error())
+		return plan, results
+	}
+
+	var ids []string
+	for _, t := range extra {
+		if err := WriteTaskDoc(runDir, merged, t); err != nil {
+			board.notice(fmt.Sprintf("团队模式：写补充任务书 %s 失败，跳过：%v", t.ID, err))
+			return plan, results
+		}
+		if err := EnsureTaskDir(runDir, t.ID); err != nil {
+			board.notice(fmt.Sprintf("团队模式：建补充任务目录 %s 失败，跳过：%v", t.ID, err))
+			return plan, results
+		}
+		board.add(t, RouteFor(t, opts))
+		ids = append(ids, t.ID)
+	}
+	board.announce()
+	board.notice(fmt.Sprintf("团队模式：追加 %d 个补充任务（%s），继续执行",
+		len(extra), strings.Join(ids, "、")))
+
+	// 只跑补充任务：原任务已经跑过，重跑会把成本翻倍、也会覆盖 OUT/ARTS。
+	more := executeWithHeartbeat(ctx, opts, Plan{Goal: merged.Goal, Tasks: extra}, runDir, board)
+	return merged, append(results, more...)
+}
+
+// makeAdaptivePlan 让主引擎产出补充任务（与 makePlan 同一条非流式 + ToolsOff 路径）。
+func makeAdaptivePlan(ctx context.Context, opts Options, plan Plan, signals []string, planSession string) ([]Task, error) {
+	if opts.Engine == nil {
+		return nil, fmt.Errorf("主引擎为空")
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	route := PlanRoute(opts)
+	eng := agent.Lookup(route.Engine)
+	if eng == nil {
+		return nil, fmt.Errorf("计划引擎 %s 不可用", route.Engine)
+	}
+	// 会话沿用计划那一轮的 id **仅当**再规划还在主引擎上；换引擎时跨引擎续接是错的
+	// （同 makePlan 的 onMain 判定）。
+	onMain := strings.EqualFold(eng.Name(), opts.Engine.Name())
+	sid := ""
+	if onMain {
+		sid = planSession
+	}
+	rctx, cancel := context.WithTimeout(ctx, taskTimeout(opts))
+	defer cancel()
+
+	runner := &agent.Runner{Engine: eng, Timeout: taskTimeout(opts)}
+	resp, err := runner.Run(rctx, agent.Request{
+		Engine:       eng.Name(),
+		Model:        route.Model,
+		SystemPrompt: strings.TrimSpace(opts.SystemPrompt + "\n\n" + plannerPrompt(opts) + "\n\n" + adaptiveSystemPrompt),
+		Tools:        agent.ToolsOff,
+		JSONSchema:   planSchema(),
+		Messages:     []agent.Message{{Role: "user", Content: adaptivePrompt(plan, signals)}},
+		Reasoning:    opts.Reasoning,
+		SessionID:    sid,
+	})
+	if err != nil {
+		return nil, err
+	}
+	replan, perr := parsePlan(resp.Text)
+	if perr != nil {
+		return nil, perr
+	}
+	return replan.Tasks, nil
+}
+
+// adaptivePrompt 组装再规划输入：目标 + 信号 + 补充任务的写法要求。
+func adaptivePrompt(plan Plan, signals []string) string {
+	var b strings.Builder
+	b.WriteString("原计划目标：" + orDash(plan.Goal) + "\n\n")
+	b.WriteString("第一轮执行后发现的问题：\n")
+	for _, s := range signals {
+		b.WriteString("- " + oneLine(s) + "\n")
+	}
+	b.WriteString("\n请判断是否需要补充任务。" +
+		"需要就只输出补充任务（最多 " + fmt.Sprint(adaptiveMaxTasks) + " 个）；" +
+		"不需要就输出 {\"goal\":\"…\",\"tasks\":[]}。\n")
+	return b.String()
+}
+
+// normalizeAdaptiveTasks 收拢补充任务的 id / deps，返回可直接合并进原计划的任务，
+// 以及因**与原任务同名**被丢弃的个数。
+//
+//   - 没有 prompt 的丢弃（不可执行，也会让 Validate 失败）
+//   - 与原任务（或本批已收的任务）同名的丢弃：模型常把「没做成」直接原样再提一遍，
+//     那等价于重试，执行器自己会重试；收进来只会在任务卡上多出一行同名任务
+//     （2026-10-22 实测 t1/a1、t2/a2、t3/a3 各并列两行）
+//   - 最多 adaptiveMaxTasks 个
+//   - id 重编号为 a1..aN（跳过原计划已占用的 id）
+//   - deps 只保留指向本批补充任务的（重映射）；指向原任务的依赖丢弃 —— 原任务已经
+//     跑完，执行器拿不到它们，留着只会让整批校验失败
+func normalizeAdaptiveTasks(src []Task, plan Plan) ([]Task, int) {
+	taken := make(map[string]bool, len(plan.Tasks))
+	seen := make(map[string]bool, len(plan.Tasks)+len(src))
+	for _, t := range plan.Tasks {
+		taken[strings.TrimSpace(t.ID)] = true
+		seen[titleKey(t.Title)] = true
+	}
+
+	dropped := 0
+	kept := make([]Task, 0, len(src))
+	for _, t := range src {
+		if len(kept) >= adaptiveMaxTasks {
+			break
+		}
+		if strings.TrimSpace(t.Prompt) == "" {
+			continue
+		}
+		k := titleKey(t.Title)
+		if k != "" && seen[k] {
+			dropped++
+			continue
+		}
+		if k != "" {
+			seen[k] = true
+		}
+		kept = append(kept, normalizeTask(t))
+	}
+
+	// 原 id → 新 id（先定好全批映射，deps 才能指到后面的任务）。
+	newID := make(map[string]string, len(kept))
+	ids := make([]string, len(kept))
+	n := 1
+	for i, t := range kept {
+		for taken[fmt.Sprintf("a%d", n)] {
+			n++
+		}
+		ids[i] = fmt.Sprintf("a%d", n)
+		taken[ids[i]] = true
+		n++
+		if old := strings.TrimSpace(t.ID); old != "" {
+			newID[old] = ids[i]
+		}
+	}
+
+	out := make([]Task, 0, len(kept))
+	for i, t := range kept {
+		t.ID = ids[i]
+		var deps []string
+		seen := make(map[string]bool, len(t.Deps))
+		for _, d := range t.Deps {
+			nid, ok := newID[strings.TrimSpace(d)]
+			if !ok || nid == t.ID || seen[nid] {
+				continue
+			}
+			seen[nid] = true
+			deps = append(deps, nid)
+		}
+		t.Deps = deps
+		out = append(out, t)
+	}
+	return out, dropped
+}
+
+// titleKey 把任务标题归一成比较用的键（忽略大小写与首尾空白）。
+func titleKey(s string) string {
+	return strings.ToLower(strings.TrimSpace(s))
+}

package/internal/team/board.go

@@ -0,0 +1,216 @@
+package team
+
+// board.go - 主会话里的**任务列表卡**（agent.KindTasks 快照）。
+//
+// 为什么不再为每个子任务开一张委派卡（2026-10-22 用户定稿）：子任务已经是独立会话，
+// 过程都写在各自的日志里；主会话只需要一眼看清「拆了几件事、各自到哪了、点进去是哪条
+// 会话」。所以这里维护一份全量快照，任何一行状态变化就整份重发 —— 快照语义天然幂等，
+// 多端重连 / 乱序到达都不用做合并。
+
+import (
+	"encoding/json"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// 任务行的状态词表。
+//
+// done / failed / skipped 与 TaskResult.State 同词（落盘那套），只多两个过程态：
+// pending（计划里已确定、还没轮到）与 running。渲染层把它映射成
+// pending→pending / running→in_progress / done→completed / failed→failed / skipped→skipped。
+const (
+	RowPending = "pending"
+	RowRunning = "running"
+)
+
+// TaskRow 任务列表卡上的一行（wire 形状见 agent.KindTasks 的注释，两边必须一致）。
+type TaskRow struct {
+	ID     string   `json:"id"`
+	Title  string   `json:"title"`
+	Role   string   `json:"role,omitempty"`
+	Kind   string   `json:"kind,omitempty"`
+	Engine string   `json:"engine,omitempty"`
+	Model  string   `json:"model,omitempty"`
+	Status string   `json:"status"`
+	Deps   []string `json:"deps,omitempty"`
+	// Note 失败 / 跳过的一句话原因（成功时为空）。
+	Note string `json:"note,omitempty"`
+	// SessionID / RunID 这一行的子会话（点进去看过程）。RunID 在任务一开跑就有，
+	// SessionID 要等引擎给出；两个都可能为空（调用方没开登记 / 引擎不给 id）。
+	SessionID string `json:"session_id,omitempty"`
+	RunID     string `json:"run_id,omitempty"`
+	Output    string `json:"output,omitempty"`
+}
+
+// Board 任务列表的唯一写者（并发安全）。
+type Board struct {
+	emit func(agent.StreamEvent)
+
+	mu    sync.Mutex
+	order []string
+	rows  map[string]*TaskRow
+	// last 每一行最后一次「有动静」的时间（子事件 / 状态变化），心跳据此播报。
+	last map[string]time.Time
+}
+
+func newBoard(emit func(agent.StreamEvent)) *Board {
+	return &Board{
+		emit: emit,
+		rows: make(map[string]*TaskRow),
+		last: make(map[string]time.Time),
+	}
+}
+
+// update 改一次状态并整份广播：所有变更都走这里，避免漏发快照。
+func (b *Board) update(fn func()) {
+	b.mu.Lock()
+	fn()
+	text := b.snapshotLocked()
+	b.mu.Unlock()
+	if text == "" {
+		return
+	}
+	b.emit(agent.StreamEvent{Kind: agent.KindTasks, Text: text})
+}
+
+// snapshotLocked 生成 wire 形状（调用方持锁）。
+func (b *Board) snapshotLocked() string {
+	if len(b.order) == 0 {
+		return ""
+	}
+	rows := make([]TaskRow, 0, len(b.order))
+	for _, id := range b.order {
+		rows = append(rows, *b.rows[id])
+	}
+	data, err := json.Marshal(map[string]any{"tasks": rows})
+	if err != nil {
+		return ""
+	}
+	return string(data)
+}
+
+// add 计划确定时先把全部任务登记进列表（含还在等上游的）——
+// 否则有依赖的任务在轮到自己之前，界面上连「有这件事」都看不到。
+//
+// 登记**不发快照**：一批任务一次性 add 完再 announce，任务列表卡一出现就是完整的一张，
+// 而不是先闪一行、再长成两行。
+func (b *Board) add(t Task, route Route) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	if _, ok := b.rows[t.ID]; ok {
+		return
+	}
+	b.order = append(b.order, t.ID)
+	b.rows[t.ID] = &TaskRow{
+		ID: t.ID, Title: t.Title, Role: t.Role, Kind: t.EffectiveKind(),
+		Engine: route.Engine, Model: route.Model,
+		Status: RowPending, Deps: t.Deps,
+	}
+	b.last[t.ID] = time.Now()
+}
+
+// announce 整份广播当前任务列表（一批 add 之后调一次）。
+func (b *Board) announce() {
+	b.update(func() {})
+}
+
+// start 标记开跑（引擎 / 模型以实际解析结果为准）。
+func (b *Board) start(t Task, engine, model string) {
+	b.update(func() {
+		row := b.rows[t.ID]
+		if row == nil {
+			return
+		}
+		row.Status = RowRunning
+		row.Engine, row.Model = engine, model
+		row.Note = ""
+		b.last[t.ID] = time.Now()
+	})
+}
+
+// setSession 绑定子会话（run_id 开跑即有，session_id 引擎给了才有）。
+func (b *Board) setSession(id, sessionID, runID string) {
+	if sessionID == "" && runID == "" {
+		return
+	}
+	b.update(func() {
+		row := b.rows[id]
+		if row == nil {
+			return
+		}
+		if sessionID != "" {
+			row.SessionID = sessionID
+		}
+		if runID != "" {
+			row.RunID = runID
+		}
+	})
+}
+
+// finish 落定一行的结局。
+func (b *Board) finish(t Task, r TaskResult) {
+	b.update(func() {
+		row := b.rows[t.ID]
+		if row == nil {
+			// 没经过 add（理论上不会发生）：补一行，别让结果无处可落。
+			b.order = append(b.order, t.ID)
+			row = &TaskRow{ID: t.ID, Title: t.Title, Role: t.Role, Kind: t.EffectiveKind()}
+			b.rows[t.ID] = row
+		}
+		row.Status = r.State
+		if r.Engine != "" {
+			row.Engine = r.Engine
+		}
+		if r.Model != "" {
+			row.Model = r.Model
+		}
+		if r.SessionID != "" {
+			row.SessionID = r.SessionID
+		}
+		row.Output = r.OutputPath
+		if r.State != TaskDone {
+			row.Note = oneLine(r.Reason)
+		}
+		b.last[t.ID] = time.Now()
+	})
+}
+
+// touch 子任务有事件了（刷新心跳时间；事件本身写子会话的日志，不进主会话）。
+func (b *Board) touch(id string) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	if _, ok := b.rows[id]; ok {
+		b.last[id] = time.Now()
+	}
+}
+
+// quietLines 返回「已经 taskQuiet 没动静」的运行中任务的播报文案，并把它们的活跃时间
+// 推到此刻 —— 同一条任务因此每 taskHeartbeat 才播一次，秒数持续增长。
+func (b *Board) quietLines() []string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	now := time.Now()
+	var out []string
+	for _, id := range b.order {
+		row := b.rows[id]
+		if row == nil || row.Status != RowRunning {
+			continue
+		}
+		last := b.last[id]
+		if now.Sub(last) < taskQuiet {
+			continue
+		}
+		b.last[id] = now
+		out = append(out, fmt.Sprintf("团队模式：%s「%s」仍在运行…（已 %d 秒无新输出）",
+			id, row.Title, int(now.Sub(last).Seconds())))
+	}
+	return out
+}
+
+// notice 往主会话发一条过程提示（不属于任何子任务）。
+func (b *Board) notice(text string) {
+	b.emit(agent.StreamEvent{Kind: agent.KindNotice, Text: text})
+}

package/internal/team/event.go

@@ -0,0 +1,28 @@
+package team
+
+// event.go - 团队模式自己合成的**少量**事件。
+//
+// 原则：能用引擎已有的形状就用，不新造 kind。
+//   · 计划        → 一条 notice（一行提示 + 计划文档路径），任务本身在画布上表现为
+//                  后续的委派卡，不需要一张额外的「计划卡」；
+//   · 每个子任务  → tool_use(name=Task) 开卡 + 带 Parent 的子事件 + tool_result 收卡；
+//   · 降级/汇总   → notice。
+//
+// 于是客户端（三端共用同一份渲染内核）**零改动**就能画出团队模式 —— 它看起来
+// 就是主代理连续委派了几次。要加「计划总览卡」时再补新 kind，那是一次独立的
+// 契约变更（见 CLIENT-CONTRACT.md 的只增字段约定）。
+
+import (
+	"strconv"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// emitPlanEvent 播一条「计划已生成」提示。
+func emitPlanEvent(emit func(agent.StreamEvent), planPath string, plan Plan, planOnly bool) {
+	text := "计划已生成（" + strconv.Itoa(len(plan.Tasks)) + " 个子任务）：" + planPath
+	if planOnly {
+		text += "（仅出计划，不执行）"
+	}
+	emit(agent.StreamEvent{Kind: agent.KindNotice, Text: text})
+}