magic-agent 1.0.46 → 1.0.108

package/internal/team/execute.go

@@ -0,0 +1,648 @@
+package team
+
+// execute.go - 跑完整张计划，把每个子任务当成一条普通会话跑。
+//
+// 并发模型：**就绪即跑**（见 schedule.go）。依赖一结束任务就入队，不等同层其他任务；
+// 并发上限由 --team-parallel 控制，失败级联与取消也在调度器里。本文件只负责
+// 「一个任务怎么跑」，不再自己算依赖。
+//
+// 事件去向（2026-10-22 用户定稿）：子任务是独立会话，它的事件**原样**交给
+// Options.OpenSubSession 返回的 SubSession 写进自己的日志，主会话只从 Board 拿到
+// 任务列表快照（agent.KindTasks）。这里不再改写 Parent / session_id / item_id，
+// 也不再合成委派卡 —— 那套投影是「子任务只是父卡下的一段过程」时代的做法。
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// 任务结局词表（与 session 的状态词表不同轴：这里说的是「这个子任务」）。
+const (
+	TaskDone    = "done"
+	TaskFailed  = "failed"
+	TaskSkipped = "skipped"
+)
+
+// execute 跑完整张计划，返回每个任务的结局（顺序与计划一致）。
+//
+// 这里只做两件事：把「跑一个任务」包成 Worker，把「跳过」包成 SkipFunc（留档 + 落定一行）。
+// 谁先跑、谁被跳过、并发多少，全在 Scheduler 里。
+func execute(ctx context.Context, opts Options, plan Plan, runDir string, board *Board) []TaskResult {
+	results, err := (ReadyQueue{Parallel: opts.Parallel}).Run(ctx, plan,
+		func(ctx context.Context, t Task, upstream map[string]TaskResult) TaskResult {
+			return runTask(ctx, opts, plan, t, runDir, upstream, board)
+		},
+		func(t Task, reason string) {
+			// 跳过也要留档、也要落定那一行：否则任务列表里永远挂着一条「待运行」，
+			// 运行目录里也查不到它为什么没跑。
+			r := TaskResult{ID: t.ID, Kind: t.EffectiveKind(), Role: t.Role, Title: t.Title, State: TaskSkipped, Reason: reason}
+			writeOutput(runDir, r, nil)
+			board.finish(t, r)
+		})
+	if err != nil {
+		// Validate 已经在 Run 里拦过；走到这里说明计划在校验之后被改过，
+		// 按全跳过处理，绝不让一轮团队调用没有终态。
+		out := make([]TaskResult, 0, len(plan.Tasks))
+		for _, t := range plan.Tasks {
+			r := TaskResult{ID: t.ID, Kind: t.EffectiveKind(), Role: t.Role, Title: t.Title, State: TaskSkipped, Reason: err.Error()}
+			writeOutput(runDir, r, nil)
+			board.finish(t, r)
+			out = append(out, r)
+		}
+		return out
+	}
+	return results
+}
+
+// 重试与验收的固定参数。
+const (
+	// taskMaxAttempts 一个子任务最多跑几次（1 次 + 1 次重试）。
+	//
+	// 只对「模型跑完了但没交出东西」重试：执行本身失败（超时 / 引擎报错）不重试 ——
+	// 同一提示词再来一次只会把成本和耗时翻倍，而且大概率同样失败。
+	taskMaxAttempts = 2
+	// checkTimeout 单条验收命令的超时。
+	checkTimeout = 2 * time.Minute
+)
+
+// CheckResult 一条验收命令的执行结果。
+type CheckResult struct {
+	// Cmd 计划里写的命令原文。
+	Cmd string `json:"cmd"`
+	// Code 退出码（0 = 通过；-1 = 起不来 / 超时）。
+	Code int `json:"code"`
+	// Output 合并后的 stdout+stderr（写进 OUT 时截断）。
+	Output string `json:"output"`
+}
+
+// runTask 跑一个子任务：点亮任务列表那一行 → 开子会话 → 核对交付物/验收命令 → 落 OUT / ARTS → 落定结局。
+//
+// 核对不过（缺交付物 / 验收命令非零）重试一次，并把「上次为什么没过」写进重试提示词。
+// 重试前已经产出的文件不会丢：产物按路径去重合并，模型可以接着改而不是推倒重来。
+func runTask(ctx context.Context, opts Options, plan Plan, t Task, runDir string, upstream map[string]TaskResult, board *Board) TaskResult {
+	r := TaskResult{ID: t.ID, Kind: t.EffectiveKind(), Role: t.Role, Title: t.Title, OutputPath: OutputPath(runDir, t.ID)}
+
+	route := RouteFor(t, opts)
+	r.Engine, r.Model = route.Engine, route.Model
+	board.start(t, route.Engine, route.Model)
+
+	// sub 在「确实要起进程」之后才开；此前的失败路径没有过程可看，开一条空会话只是噪音。
+	var sub SubSession
+	end := func(res TaskResult) TaskResult {
+		if sub != nil {
+			sub.Finish(res.SessionID, res.State, res.Reason)
+		}
+		board.finish(t, res)
+		return res
+	}
+
+	if strings.TrimSpace(route.Engine) == "" {
+		r.State = TaskFailed
+		r.Reason = fmt.Sprintf("没有可用引擎：角色 %s（类别 %s）没配引擎，主引擎也为空", t.Role, t.EffectiveKind())
+		writeOutput(runDir, r, nil)
+		return end(r)
+	}
+	eng := agent.Lookup(route.Engine)
+	if eng == nil {
+		r.State = TaskFailed
+		r.Reason = fmt.Sprintf("引擎不存在：%s", route.Engine)
+		writeOutput(runDir, r, nil)
+		return end(r)
+	}
+	r.Engine, r.Model = eng.Name(), route.Model
+
+	// 上游输入核对：计划声明「由 deps 产出」的文件却不在，直接失败 —— 子任务看得见
+	// 的上下文只有任务书，让它去猜上游为什么没交等于白烧一次模型。
+	if missing := MissingInputs(runDir, plan, t); len(missing) > 0 {
+		r.State = TaskFailed
+		r.Reason = "缺少上游输入：" + strings.Join(missing, "、")
+		writeOutput(runDir, r, t.Deliverables)
+		return end(r)
+	}
+
+	// 子任务的会话在开跑这一刻登记：会话列表里立刻能看到它挂在主会话下面，
+	// 点进去就是这次执行的完整过程。
+	if opts.OpenSubSession != nil {
+		if s := opts.OpenSubSession(t, runDir, eng.Name(), route.Model); s != nil {
+			sub = s
+			board.setSession(t.ID, "", s.RunID())
+		}
+	}
+
+	base := taskPrompt(runDir, plan, t, upstream)
+	var problems []string
+	for attempt := 1; attempt <= taskMaxAttempts; attempt++ {
+		got := runAttempt(ctx, opts, t, runDir, route, eng, attemptPrompt(base, attempt, problems), board, sub)
+		// 前几次尝试已经落盘的产物要带上：重试是「补齐」，不是「重来」。
+		got.Arts = dedupeStrings(append(got.Arts, r.Arts...))
+		if got.SessionID == "" {
+			got.SessionID = r.SessionID
+		}
+		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
+		got.Attempts = attempt
+		r = got
+
+		// 执行本身失败（超时 / 引擎报错）不重试，见 taskMaxAttempts 的注释。
+		if r.State != TaskDone {
+			break
+		}
+		problems = verifyTask(ctx, runDir, plan, t, &r)
+		if len(problems) == 0 {
+			r.State = TaskDone
+			r.Reason = ""
+			break
+		}
+		r.State = TaskFailed
+		r.Reason = strings.Join(problems, "；")
+		if attempt >= taskMaxAttempts || ctx.Err() != nil {
+			break
+		}
+		board.notice(fmt.Sprintf("团队模式：%s「%s」未通过核对（%s），重试一次", t.ID, t.Title, r.Reason))
+	}
+
+	writeOutput(runDir, r, t.Deliverables)
+	return end(r)
+}
+
+// runAttempt 跑一次尝试（流式引擎走 Stream，非流式退化成一次 Complete）。
+//
+// prompt 由调用方给：首次是任务书，重试会追加「上一次未通过」那一节。
+// 子任务的事件原样交给 sub（它写自己的日志）；主会话只通过 board 看到状态与心跳。
+func runAttempt(ctx context.Context, opts Options, t Task, runDir string, route Route, eng agent.Engine, prompt string, board *Board, sub SubSession) TaskResult {
+	r := TaskResult{ID: t.ID, Kind: t.EffectiveKind(), Role: t.Role, Title: t.Title, OutputPath: OutputPath(runDir, t.ID)}
+	r.Engine, r.Model = eng.Name(), route.Model
+	dir := TaskDir(runDir, t.ID)
+
+	streamer := agent.AsStreamer(eng)
+	if streamer == nil {
+		// 非流式引擎：退化成一次 Complete（子任务事件少，用不上增量）。
+		got := completeTask(ctx, opts, eng, route, t, runDir, prompt)
+		if sub != nil {
+			if got.SessionID != "" {
+				sub.SetSessionID(got.SessionID)
+			}
+			if text := strings.TrimSpace(got.Text); text != "" {
+				sub.Push(agent.StreamEvent{Kind: agent.KindText, Text: got.Text})
+			}
+		}
+		return got
+	}
+
+	tctx, cancel := context.WithTimeout(ctx, taskTimeout(opts))
+	defer cancel()
+	// 子会话的 ctx：SpawnHook 是 context 值，换掉只影响这次子任务进程的 pid 归属，
+	// 不会动主会话那条（agent.WithSpawnHook 用 WithValue 覆盖，见 runcmd.go）。
+	if sub != nil {
+		tctx = sub.Context(tctx)
+	}
+
+	/* 子会话 id 的**早期来源**：正文 / 思考事件不携带 session_id（只有 ask 与
+	   turn_end 带），所以「等事件里出现再记」会让整段执行期都没有会话 id。
+	   引擎一读到 init 行就会回调 OnSessionID（claude / codebuddy / trae 同一条路），
+	   这里当场收下并转给子会话（登记表 + 日志文件名都靠它）。
+	   回调与 onEvent 引擎侧不保证同 goroutine（见 Request.OnSessionID 注释），加锁。 */
+	var sidMu sync.Mutex
+	subSID := func() string {
+		sidMu.Lock()
+		defer sidMu.Unlock()
+		return r.SessionID
+	}
+	setSID := func(id string) {
+		if id == "" {
+			return
+		}
+		sidMu.Lock()
+		r.SessionID = id
+		sidMu.Unlock()
+		if sub != nil {
+			sub.SetSessionID(id)
+		}
+		board.setSession(t.ID, id, "")
+	}
+
+	res, err := streamer.Stream(tctx, agent.Request{
+		Engine: eng.Name(),
+		Model:  route.Model,
+		// 角色片段追加在主系统提示词之后（见 role.go）；未设角色时与原来一致。
+		SystemPrompt: systemPromptFor(opts, t),
+		Tools:        toolsFor(opts, t),
+		// 子任务**不接续任何会话**：这是「不共享上下文」的落地点。
+		SessionID:         "",
+		Continue:          false,
+		Workspace:         dir,
+		Reasoning:         opts.Reasoning,
+		Permission:        permissionFor(opts, t),
+		PermissionOptions: opts.PermissionOptions,
+		OnSessionID:       setSID,
+		Messages:          []agent.Message{{Role: "user", Content: prompt}},
+	}, func(ev agent.StreamEvent) {
+		if ev.SessionID != "" {
+			setSID(ev.SessionID)
+		}
+		if ev.Kind == agent.KindImage {
+			if p := artFromDataURI(ev.Text, runDir, t.ID, len(r.Arts)); p != "" {
+				r.Arts = append(r.Arts, p)
+				// 图已落盘 → 事件里改成路径，别再往历史里灌一整段 base64。
+				ev.Text = p
+			}
+		}
+		if ev.Kind == agent.KindToolResult {
+			r.Arts = append(r.Arts, artsFromText(ev.Text)...)
+		}
+		// 原样交给子会话：这是它自己的日志，Parent / item_id / session_id 都该是它本来的样子。
+		if sub != nil {
+			sub.Push(ev)
+		}
+		board.touch(t.ID)
+	})
+
+	if err != nil {
+		r.State = TaskFailed
+		r.Reason = agent.ReasonOf(err)
+		if r.Reason == "" {
+			r.Reason = err.Error()
+		}
+		if sid := subSID(); sid == "" {
+			setSID(res.SessionID) // 失败也可能已经建过会话（引擎 init 行就给了 id）
+		}
+		// 失败也要核对交付物：子任务可能在超时**之前**就把文件写出来了（实测：画了
+		// 20 分钟的封面在超时前 1 分钟落盘，只报「失败」会让用户以为什么都没产出）。
+		collectDeliverables(dir, t.Deliverables, &r)
+		r.Arts = dedupeStrings(r.Arts)
+		return r
+	}
+	r.Text = res.Text
+	if sid := subSID(); sid == "" {
+		setSID(res.SessionID)
+	}
+	collectDeliverables(dir, t.Deliverables, &r)
+	r.Arts = dedupeStrings(r.Arts)
+	r.Handoff = parseHandoff(res.Text)
+	r.State = TaskDone
+	return r
+}
+
+// verifyTask 核对一次尝试的产出：执行成功 → 交付物齐 → 验收命令全过 → 交接单合格。
+//
+// 返回空 = 通过。Checks 只在执行成功时跑（任务都没跑完，跑验收命令只会得到噪音）。
+func verifyTask(ctx context.Context, runDir string, plan Plan, t Task, r *TaskResult) []string {
+	if r.State != TaskDone {
+		return []string{"执行失败：" + orDash(r.Reason)}
+	}
+	if len(r.Missing) > 0 {
+		return []string{"缺少交付物：" + strings.Join(r.Missing, "、")}
+	}
+	r.Checks = runChecks(ctx, runDir, t)
+	var problems []string
+	for _, c := range r.Checks {
+		if c.Code == 0 {
+			continue
+		}
+		msg := fmt.Sprintf("验收命令未通过（退出码 %d）：%s", c.Code, c.Cmd)
+		if out := strings.TrimSpace(c.Output); out != "" {
+			msg += " —— " + oneLine(Truncate(out, 200))
+		}
+		problems = append(problems, msg)
+	}
+	// 交接单是下游的输入：被下游当硬输入的任务必须交齐 files / summary。
+	// 叶子任务不强制 —— 没人读它的交接单，强制只会多一次重试。
+	problems = append(problems, handoffProblems(plan, t, r)...)
+	return problems
+}
+
+// attemptPrompt 重试时在任务书后面追加「上一次为什么没过」。
+//
+// 只追加不替换：任务书里是全部上下文，重试需要的是同一份要求 + 明确的差距。
+func attemptPrompt(base string, attempt int, problems []string) string {
+	if attempt <= 1 || len(problems) == 0 {
+		return base
+	}
+	var b strings.Builder
+	b.WriteString(base)
+	b.WriteString("\n## 上一次尝试未通过\n\n")
+	b.WriteString("core 核对上一次的产出，发现：\n")
+	for _, p := range problems {
+		b.WriteString("- " + oneLine(p) + "\n")
+	}
+	b.WriteString("\n请在工作目录里补齐 / 修正后重新收尾；已经产出的文件可以继续用，不要推倒重来。\n")
+	return b.String()
+}
+
+// runChecks 逐条执行任务声明的验收命令。
+func runChecks(ctx context.Context, runDir string, t Task) []CheckResult {
+	var out []CheckResult
+	for _, raw := range t.Check {
+		cmd := strings.TrimSpace(raw)
+		if cmd == "" {
+			continue
+		}
+		out = append(out, runCheck(ctx, runDir, t.ID, cmd))
+	}
+	return out
+}
+
+// runCheck 在工作目录里跑一条命令：退出码 0 才算通过。
+func runCheck(ctx context.Context, runDir, taskID, cmd string) CheckResult {
+	cctx, cancel := context.WithTimeout(ctx, checkTimeout)
+	defer cancel()
+	c := exec.CommandContext(cctx, shellName(), shellArgs(cmd)...)
+	c.Dir = TaskDir(runDir, taskID)
+	out, err := c.CombinedOutput()
+	res := CheckResult{Cmd: cmd, Output: string(out)}
+	if err == nil {
+		return res
+	}
+	res.Code = -1
+	var ee *exec.ExitError
+	if errors.As(err, &ee) && ee.ExitCode() != 0 {
+		res.Code = ee.ExitCode()
+	}
+	return res
+}
+
+// shellName / shellArgs 验收命令的解释器：Windows 没有 sh，得用 cmd /c。
+func shellName() string {
+	if runtime.GOOS == "windows" {
+		return "cmd"
+	}
+	return "sh"
+}
+
+func shellArgs(cmd string) []string {
+	if runtime.GOOS == "windows" {
+		return []string{"/c", cmd}
+	}
+	return []string{"-c", cmd}
+}
+
+// completeTask 非流式引擎的退化路径（一次性 Complete）。
+func completeTask(ctx context.Context, opts Options, eng agent.Engine, route Route, t Task, runDir, prompt string) TaskResult {
+	r := TaskResult{ID: t.ID, Kind: t.EffectiveKind(), Role: t.Role, Title: t.Title, OutputPath: OutputPath(runDir, t.ID)}
+	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{
+		Engine:            eng.Name(),
+		Model:             route.Model,
+		SystemPrompt:      systemPromptFor(opts, t),
+		Tools:             toolsFor(opts, t),
+		Workspace:         TaskDir(runDir, t.ID),
+		Reasoning:         opts.Reasoning,
+		Permission:        permissionFor(opts, t),
+		PermissionOptions: opts.PermissionOptions,
+		Messages:          []agent.Message{{Role: "user", Content: prompt}},
+	})
+	r.SessionID = resp.SessionID
+	r.Text = resp.Text
+	collectDeliverables(TaskDir(runDir, t.ID), t.Deliverables, &r)
+	r.Arts = dedupeStrings(r.Arts)
+	if err != nil {
+		r.State = TaskFailed
+		r.Reason = agent.ReasonOf(err)
+		if r.Reason == "" {
+			r.Reason = err.Error()
+		}
+		return r
+	}
+	r.Handoff = parseHandoff(resp.Text)
+	r.State = TaskDone
+	return r
+}
+
+// taskPrompt 子任务的完整提示词（任务书全文内联 + 关键路径）。
+//
+// 为什么不只给路径让子引擎自己读：trae / openclaw / codebuddy-gateway 这类引擎的
+// 附件通道只有 prompt 降级（把路径写进提示词、靠它自己的读文件工具），而「读文件的
+// 工具」在 tools=off 或引擎没有文件系统语义时并不存在。**内联是最低保证**，
+// 路径是给有工具的引擎留的第二条路。
+func taskPrompt(runDir string, plan Plan, t Task, upstream map[string]TaskResult) string {
+	return TaskDoc(runDir, plan, t, upstream)
+}
+
+// writeOutput 写 OUT-<id>.md、ARTS-<id>.json 与 HANDOFF-<id>.json（core 自己写，不信任子引擎自报）。
+func writeOutput(runDir string, r TaskResult, deliverables []string) {
+	var b strings.Builder
+	b.WriteString("# " + strings.ToUpper(r.ID) + " · " + orDash(r.Title) + "\n\n")
+	b.WriteString("结局：" + r.State + "\n")
+	if r.Role != "" {
+		b.WriteString("角色：" + roleDetail(r.Role) + " · 类别：" + orDash(r.Kind) + "\n")
+	}
+	if r.Engine != "" {
+		b.WriteString("引擎：" + r.Engine + modelSlash(r.Model) + "\n")
+	}
+	// 子引擎自己的会话 id：绑定在主会话下（不当作本会话的锚点），留档便于回去追。
+	if r.SessionID != "" {
+		b.WriteString("会话：" + r.SessionID + "\n")
+	}
+	// 只在真重试过时留档：一次通过的任务写「尝试：1 次」是噪音。
+	if r.Attempts > 1 {
+		b.WriteString("尝试：" + strconv.Itoa(r.Attempts) + " 次\n")
+	}
+	if r.Reason != "" {
+		b.WriteString("原因：" + r.Reason + "\n")
+	}
+	b.WriteString("\n")
+	if s := strings.TrimSpace(r.Text); s != "" {
+		b.WriteString("## 正文\n\n" + s + "\n\n")
+	}
+	if len(deliverables) > 0 {
+		b.WriteString("## 交付物\n\n")
+		for _, d := range deliverables {
+			mark := "✓"
+			for _, m := range r.Missing {
+				if m == d {
+					mark = "✗"
+				}
+			}
+			b.WriteString("- " + mark + " `" + d + "`\n")
+		}
+		b.WriteString("\n")
+	}
+	if len(r.Checks) > 0 {
+		b.WriteString("## 验收命令\n\n")
+		for _, c := range r.Checks {
+			mark := "✓"
+			if c.Code != 0 {
+				mark = "✗"
+			}
+			b.WriteString("- " + mark + " `" + c.Cmd + "`（退出码 " + strconv.Itoa(c.Code) + "）\n")
+			if c.Code != 0 {
+				if out := strings.TrimSpace(c.Output); out != "" {
+					b.WriteString("\n```\n" + Truncate(out, 2000) + "\n```\n\n")
+				}
+			}
+		}
+		b.WriteString("\n")
+	}
+	if r.Handoff != nil {
+		b.WriteString("## 交接单\n\n" + handoffMarkdown(runDir, r.ID, r.Handoff) + "\n")
+	}
+	if len(r.Arts) > 0 {
+		b.WriteString("## 产物\n\n")
+		for _, a := range r.Arts {
+			b.WriteString("- " + a + "\n")
+		}
+	}
+	_ = os.WriteFile(OutputPath(runDir, r.ID), []byte(b.String()), 0o644)
+	arts, _ := json.MarshalIndent(map[string]any{
+		"id": r.ID, "state": r.State, "kind": r.Kind, "role": r.Role,
+		"engine": r.Engine, "model": r.Model,
+		"session_id": r.SessionID,
+		"attempts":   r.Attempts,
+		"arts":       r.Arts, "missing": r.Missing, "checks": r.Checks,
+	}, "", "  ")
+	_ = os.WriteFile(ArtsPath(runDir, r.ID), arts, 0o644)
+	// 交接单单独落一份 JSON：下游任务与外部工具都可以直接读，不必从 OUT 里再解析一遍。
+	if r.Handoff != nil {
+		if hb, err := json.MarshalIndent(r.Handoff, "", "  "); err == nil {
+			_ = os.WriteFile(HandoffPath(runDir, r.ID), hb, 0o644)
+		}
+	}
+}
+
+// collectDeliverables 逐个 stat 任务书里声明的交付物：存在的记进 Arts（绝对路径，
+// 前端按产物卡渲染 / 点得开），缺的记进 Missing。
+//
+// 失败路径同样要调 —— 子任务可能在超时前就把文件写出来了，只报「失败」会让用户以为
+// 什么都没产出（实测：t2 画完 cover.png 后 1 分钟超时，汇总说「没有封面」）。
+//
+// ⚠️ 声明是**相对任务目录**的路径，允许带子目录（`impl/fizzbuzz.js`）：模型常把文件
+// 分目录放，早前一律取 basename 再去任务根目录找，于是明明写出来了也判「缺少交付物」
+// （2026-10-22 实测 6/6 全误判）。越界（绝对路径 / `../`）仍然只取文件名，落地路径
+// 必须仍在任务目录内。
+func collectDeliverables(dir string, want []string, r *TaskResult) {
+	for _, w := range want {
+		// 保留子目录相对路径（impl/fizzbuzz.js）；越界写法在 cleanRel 里收窄成文件名。
+		name := cleanRel(w)
+		if name == "" {
+			continue
+		}
+		p := filepath.Join(dir, name)
+		if !withinDir(dir, p) { // `a/../../etc/passwd` 这类清洗后才越界的写法
+			name = filepath.Base(name)
+			p = filepath.Join(dir, name)
+		}
+		if _, err := os.Stat(p); err != nil {
+			r.Missing = append(r.Missing, name)
+			continue
+		}
+		r.Arts = append(r.Arts, p)
+	}
+}
+
+// withinDir 判断 p 是否落在 dir 之内（含 dir 本身）。
+func withinDir(dir, p string) bool {
+	rel, err := filepath.Rel(filepath.Clean(dir), filepath.Clean(p))
+	if err != nil {
+		return false
+	}
+	return rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator))
+}
+
+// artsFromText 从工具结果正文里捞产物路径（与前端 qaArtCollect 同一份后缀口径的简化版）。
+//
+// 只认**绝对路径且带已知后缀**：正文里出现的相对文件名太容易误判（"报告.md" 可能
+// 只是模型在说话），而团队产物的价值在于「点得开」，宁缺勿滥。
+func artsFromText(text string) []string {
+	var out []string
+	for _, tok := range strings.FieldsFunc(text, func(r rune) bool {
+		switch r {
+		case ' ', '\t', '\n', '\r', '"', '\'', '`', '(', ')', '[', ']', '<', '>', '，', '。', '；', '、':
+			return true
+		}
+		return false
+	}) {
+		tok = strings.TrimRight(tok, ",.;:!?")
+		if !strings.HasPrefix(tok, "/") && !strings.HasPrefix(tok, "~/") {
+			continue
+		}
+		if !artExt(tok) {
+			continue
+		}
+		if _, err := os.Stat(tok); err != nil {
+			continue
+		}
+		out = append(out, tok)
+	}
+	return out
+}
+
+// artExt 是否为已知产物后缀（与 client-ui/shared/conv/02-media-kinds.js 的清单同源）。
+func artExt(p string) bool {
+	ext := strings.ToLower(filepath.Ext(p))
+	switch ext {
+	case ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg", ".heic", ".avif",
+		".mp4", ".mov", ".m4v", ".webm", ".mkv", ".avi",
+		".mp3", ".wav", ".m4a", ".aac", ".ogg", ".flac",
+		".md", ".markdown", ".txt", ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+		".csv", ".zip", ".glb", ".gltf", ".psd", ".fig", ".html", ".json":
+		return true
+	}
+	return false
+}
+
+// artFromDataURI 把子引擎产出的内嵌图片落成文件（data URI 只有超长时才落盘）。
+//
+// 为什么落盘：内嵌在事件里的图**在历史回放里会变成一条巨大的 base64**，而且用户
+// 拿不走。落到运行目录后，事件里只往前端发路径（前端按产物卡渲染）。
+func artFromDataURI(uri, runDir, taskID string, seq int) string {
+	const prefix = "data:image/"
+	if !strings.HasPrefix(uri, prefix) {
+		return ""
+	}
+	comma := strings.IndexByte(uri, ',')
+	if comma < 0 || !strings.Contains(uri[:comma], "base64") {
+		return ""
+	}
+	media := strings.TrimSuffix(strings.TrimPrefix(uri[:comma], prefix), ";base64")
+	ext := ".png"
+	switch strings.ToLower(media) {
+	case "image/jpeg", "image/jpg":
+		ext = ".jpg"
+	case "image/gif":
+		ext = ".gif"
+	case "image/webp":
+		ext = ".webp"
+	case "image/svg+xml":
+		ext = ".svg"
+	}
+	dir := TaskDir(runDir, taskID)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return ""
+	}
+	name := fmt.Sprintf("image-%02d%s", seq+1, ext)
+	path := filepath.Join(dir, name)
+	if err := os.WriteFile(path, []byte(uri[comma+1:]), 0o644); err != nil {
+		return ""
+	}
+	return path
+}
+
+func dedupeStrings(in []string) []string {
+	seen := make(map[string]bool, len(in))
+	out := make([]string, 0, len(in))
+	for _, s := range in {
+		if s == "" || seen[s] {
+			continue
+		}
+		seen[s] = true
+		out = append(out, s)
+	}
+	return out
+}