magic-agent 1.0.49 → 1.0.108

package/internal/team/team.go

@@ -0,0 +1,401 @@
+// Package team - 团队模式：主引擎做计划，子引擎分头执行，主引擎汇总。
+//
+// ── 为什么不新造一个引擎 ──
+// 团队模式是**会话层的一种运行模式**，不是一个后端。同一个会话里仍然只有一个
+// session_id、一条事件流、一个 result 收尾；变的只是「谁在干活」：主引擎（当前
+// `-e`）负责拆解与汇总，子任务各起各的进程、各用各的模型、各在自己的目录里跑。
+//
+// ── 上下文策略：**不共享** ──
+// 子任务不接续主会话，也不互相接续（用户 2026-10-21 定稿）。代价是每个子任务都要
+// 自带全部上下文；收益是可控、可并行、可单独重跑。所以：
+//
+//	PLAN.md        全队共享的**唯一事实源**，由 core 写一次、之后只读（0444）
+//	TASK-<id>.md   每个子任务的详细任务书（输入 + 约束 + 交付物 + 验收），只读
+//	<task_id>/     子引擎自己的工作目录（进程 cwd），互不可见
+//	OUT-<id>.md    子任务正文，core 收尾时抄写（不信任子引擎自报）
+//	ARTS-<id>.json 该任务的产物清单，core 从事件里归拢
+//
+// 写权是**机制保证**的，不是约定：子引擎只拿到自己工作目录的写权，PLAN/TASK 是只读
+// 文件，OUT/ARTS 由 core 写。于是「谁改了计划」这种问题不存在。
+//
+// ── 子任务 = 普通会话（2026-10-22 用户定稿） ──
+// 每个子任务在会话列表里就是**一条普通会话**：各自有登记记录与日志（由调用方通过
+// Options.OpenSubSession 提供），靠父指针挂在主会话下显示，点进去能看到它完整的
+// 思考 / 正文 / 工具过程，也能单独停止。子任务之间仍不共享上下文。
+//
+// 主会话里只出现**一张任务列表卡**（agent.KindTasks 快照）：一行一个子任务，
+// 带状态（pending / running / done / failed / skipped）与对应的子会话 id。
+// 因此子任务的内部事件**不再转发**到主会话 —— 它们属于子会话自己的日志。
+package team
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// Kinds 支持的子任务类别（顺序即 --help / 报错文案的顺序）。
+//
+// 类别是**派生值**：任务的唯一作者字段是 role（见 role.go），类别由角色的 Kind 决定，
+// 再据此选引擎。类别回答的是「这类活该派给谁」，不是「必须产出什么文件」——
+// 分派依据是**引擎擅长什么**（例如带视频 skill 的引擎接 video 类）。
+//
+//	text   文档、分析、结论、文案
+//	code   复杂代码改动（多文件 / 要构建或测试 / 有明确改动面），交给擅长写代码的引擎
+//	image  画面类产出（位图 / 矢量），交给擅长画图的引擎
+//	video  影像类产出，交给擅长做视频的引擎（如带视频 skill 的）
+//	game   可运行的游戏工程（复合：代码 + 素材，由子引擎自己再拆）
+//
+// code 只收「复杂到值得单开一个执行者」的代码活；简单代码由主引擎在汇总里直接给出，
+// 不拆子任务（规则写在 plannerSystemPrompt 里）。
+var Kinds = []string{KindText, KindCode, KindImage, KindVideo, KindGame}
+
+// 类别常量。
+const (
+	KindText  = "text"
+	KindCode  = "code"
+	KindImage = "image"
+	KindVideo = "video"
+	KindGame  = "game"
+
+	// KindPlan 计划阶段（planner）的路由键。
+	//
+	// 它是**阶段**，不是子任务类别，所以刻意不放进 Kinds：任务的类别由角色派生，
+	// 永远不会是 plan（NormalizeKind 也不认它），否则会拆出一个叫「计划」的执行子任务。
+	// 它只用于「谁来拆任务」——见 RouteKinds / PlanRoute。
+	KindPlan = "plan"
+)
+
+// RouteKinds 可配置路由的全部键（`--team-route` / 客户端 routes 的合法类别）。
+//
+// = 计划阶段 + 五类子任务。与 Kinds 分开是上面的原因（plan 不能当子任务）；
+// 顺序即报错文案的顺序。
+var RouteKinds = []string{KindPlan, KindText, KindCode, KindImage, KindVideo, KindGame}
+
+// Route 某一类子任务该交给哪个引擎 / 模型。空引擎 = 跟随主引擎（主引擎为空时才真的没有）。
+type Route struct {
+	Engine string
+	Model  string
+}
+
+// Options 一次团队调用的全部输入。
+type Options struct {
+	// Engine 主引擎（计划 + 汇总都用它）。必填。
+	Engine agent.Engine
+	// Model 主引擎的模型（空 = 引擎默认）。
+	Model string
+	// Prompt 用户原始诉求。
+	Prompt string
+	// SystemPrompt 主引擎的系统提示词（计划与汇总都注入）。
+	SystemPrompt string
+	// Reasoning 思考档位（原样透传子任务，空 = 不传）。
+	Reasoning string
+	// SessionID 主引擎的会话续接 id（空 = 新会话）。
+	//
+	// ⚠️ 只有**主引擎**（计划 + 汇总）会拿到它，子任务永远是空 —— 这正是用户
+	// 2026-10-21 定稿的「不共享上下文」：主引擎与用户保持对话连续，子任务各自从零开始。
+	SessionID string
+
+	// Routes 路由键 → 引擎/模型。键取 RouteKinds（plan + 五类子任务），
+	// 缺项跟随主引擎（见 RouteFor / PlanRoute）。
+	Routes map[string]Route
+	// Parallel 并发度（<=0 取 defaultParallel）。
+	Parallel int
+	// Split 拆解粒度：coarse（最多 3 个）| standard（6，默认）| fine（10）。空 = standard。
+	Split string
+	// SplitSimpleCode 简单代码也单独拆给 coder（默认 false：简单代码由主引擎直接给出）。
+	SplitSimpleCode bool
+	// Rules 角色规则覆盖（键 role:<name>，值「这类任务适合什么」）。
+	//
+	// 只改计划阶段的角色表描述（用户配置：「描述好每一类适合的规则」），
+	// 不改执行者的系统提示词。
+	Rules map[string]string
+	// TaskTimeout 单个子任务的超时（<=0 按总超时推算，见 taskTimeout）。
+	TaskTimeout time.Duration
+	// Timeout 整轮预算（<=0 不限）。
+	Timeout time.Duration
+
+	// Workspace 用户选的工作空间（空 = 默认空间）。
+	Workspace string
+	// RunID 本次运行 id（由会话登记表分配，决定运行目录名）。
+	RunID string
+	// BaseDir 覆盖运行目录的父目录（空 = 按 chooseRunDir 推断）。
+	BaseDir string
+
+	// Permission 子任务的权限上限（默认 accept-edits，见 DefaultTaskPermission）。
+	Permission agent.PermissionTier
+	// PermissionOptions 与 Permission 配套的四档选项。
+	PermissionOptions agent.PermissionOptions
+	// Tools 子任务的工具模式（默认 ToolsOn —— 子任务要能读写文件才有意义）。
+	Tools agent.ToolsMode
+
+	// PlanOnly 只出计划与任务书，不执行（--team-plan-only）。
+	PlanOnly bool
+	// Adaptive 第一轮执行完后，按失败与交接单 open 项再规划一轮补充任务
+	// （--team-adaptive，CLI 默认开；Go 零值关，测试与程序化调用默认不受影响）。
+	//
+	// 只补一轮、最多 adaptiveMaxTasks 个；追加失败不会打断整轮。
+	Adaptive bool
+	// Continue 主引擎的「续接最近一次会话」（--continue；与 SessionID 互斥，id 优先）。
+	Continue bool
+
+	// OnEvent 事件出口（由 CLI 层接到 eventSink）。并发安全由调用方保证。
+	OnEvent func(agent.StreamEvent)
+
+	// OpenSubSession 为一个子任务开一条**普通会话**（登记 + 独立日志）。
+	//
+	// 由 CLI 层实现（team 包不依赖 internal/session 与日志实现，见 subsession.go）。
+	// 返回 nil = 这条子任务不单独登记：过程事件不转发给任何人，只在任务列表里留一行。
+	// runDir 是本次运行的根目录，engine / model 是实际解析出来的路由结果。
+	OpenSubSession func(t Task, runDir, engine, model string) SubSession
+}
+
+// DefaultTaskPermission 子任务的默认权限上限。
+//
+// 刻意**低于**主会话的默认档（full）：子任务是自己拆出来的一段活，让它带
+// 「完全访问」等于把一次授权扩成 N 份。要放开就显式传 --team-permission。
+const DefaultTaskPermission = agent.PermissionAcceptEdits
+
+const defaultParallel = 4
+
+// TaskResult 一个子任务的结局。
+type TaskResult struct {
+	ID string
+	// Kind 任务类别（由 Role 派生，见 Task.EffectiveKind）。
+	Kind string
+	// Role 执行角色（规范名；任务必填，归一化后一定非空）。
+	Role   string
+	Title  string
+	Engine string
+	Model  string
+	State  string // done | failed | skipped
+	Reason string
+	Text   string
+	// SessionID 子引擎自己为这个子任务开的会话 id（可能为空）。
+	//
+	// 它**不是**这条会话的锚点（主会话的 id 在 Result.SessionID），而是绑定在主会话
+	// 下面的一条子会话：只用于登记 / 留档，事件流里刻意抹掉（见 execute.go）。
+	SessionID string
+	// OutputPath OUT-<id>.md 的绝对路径（失败时也写，内容是失败原因）。
+	OutputPath string
+	// Arts 该任务产出的产物绝对路径（从事件里归拢，已去重）。
+	Arts []string
+	// Missing 任务书里声明、但跑完没找到的交付物文件名。
+	Missing []string
+	// Handoff 子任务正文末尾的交接单（解析不出为 nil，下游回落到正文截断）。
+	Handoff *Handoff
+	// Checks 验收命令的执行结果（只在任务跑完时执行）。
+	Checks []CheckResult
+	// Attempts 实际尝试次数（1 = 一次通过；>1 = 验收未过重试过）。
+	Attempts int
+}
+
+// Result 一次团队调用的结果。
+type Result struct {
+	// Text 最终正文（reducer 产出；reducer 失败时是兜底清单）。
+	Text string
+	// RunDir 运行目录（PLAN.md 所在）。
+	RunDir   string
+	PlanPath string
+	Tasks    []TaskResult
+	// SessionID 主引擎的会话 id（reducer 那一轮）。
+	SessionID string
+	Latency   time.Duration
+}
+
+// Run 执行一次团队调用。
+//
+// 失败语义（写死，别改成别的）：
+//   - 计划生成失败 / 解析失败 / 依赖成环 → **降级单任务团队**，明说一行，不打死整轮；
+//   - 某个子任务失败 → 按 required 决定「继续」或「整轮失败」；
+//   - reducer 失败 → 回落「产物清单 + 各任务正文首段」，仍以正常结果收尾。
+//
+// 这三种降级都不会让事件流少一个终态 —— 调用方的「每轮以 result 或 error 收尾」
+// 不变量照旧成立。
+func Run(ctx context.Context, opts Options) (Result, error) {
+	if opts.Engine == nil {
+		return Result{}, fmt.Errorf("team: 主引擎为空")
+	}
+	if strings.TrimSpace(opts.Prompt) == "" {
+		return Result{}, fmt.Errorf("team: 提示词为空")
+	}
+	started := time.Now()
+	if opts.Parallel <= 0 {
+		opts.Parallel = defaultParallel
+	}
+	if opts.Permission == "" {
+		opts.Permission = DefaultTaskPermission
+	}
+	if opts.Tools == nil {
+		opts.Tools = agent.ToolsOn
+	}
+	if opts.OnEvent == nil {
+		opts.OnEvent = func(agent.StreamEvent) {}
+	}
+
+	emit := opts.OnEvent
+	emit(agent.StreamEvent{Kind: agent.KindNotice, Text: "团队模式：正在生成计划…"})
+
+	/* 计划阶段：主引擎**关工具**跑一次。
+	   关工具不是为了省事 —— 计划必须是可解析的结构化输出，开着工具时模型会把
+	   中间过程（读文件 / 跑命令）混进正文，解析成功率会掉下来。 */
+	plan, planSession, planErr := planWithHeartbeat(ctx, opts, emit)
+	degraded := ""
+	if planErr != nil {
+		degraded = "计划生成失败，已降级为单任务：" + planErr.Error()
+		plan = fallbackPlan(opts.Prompt)
+	}
+	if err := plan.Validate(); err != nil {
+		degraded = "计划不可用，已降级为单任务：" + err.Error()
+		plan = fallbackPlan(opts.Prompt)
+	}
+	if degraded != "" {
+		emit(agent.StreamEvent{Kind: agent.KindNotice, Text: degraded})
+	}
+
+	// 运行目录与计划文档（唯一事实源）。
+	runDir, err := chooseRunDir(opts)
+	if err != nil {
+		return Result{}, err
+	}
+	res := Result{RunDir: runDir, PlanPath: PlanPath(runDir)}
+	if err := WritePlanDoc(runDir, plan, opts); err != nil {
+		return Result{}, fmt.Errorf("team: 写计划文档失败：%w", err)
+	}
+	emitPlanEvent(emit, res.PlanPath, plan, opts.PlanOnly)
+
+	// 任务书（每个子任务一份）。写在 `PlanOnly` 判断**之前**：--team-plan-only 的用途
+	// 就是「先确认方案」—— 用户要看的是「真要跑起来，每个子任务会收到什么」，
+	// 只给一份总览等于看不到最关键的那一层（帮助文案也一直是这么写的）。
+	// 写不出就整轮失败 —— 没有任务书等于子任务没有输入。
+	for _, t := range plan.Tasks {
+		if err := WriteTaskDoc(runDir, plan, t); err != nil {
+			return res, fmt.Errorf("team: 写任务书 %s 失败：%w", t.ID, err)
+		}
+		if err := EnsureTaskDir(runDir, t.ID); err != nil {
+			return res, fmt.Errorf("team: 建工作目录 %s 失败：%w", t.ID, err)
+		}
+	}
+
+	// 计划一确定就把**全部**子任务登记进任务列表卡（含还在等上游的）。
+	//
+	// 为什么提前登记：execute 按依赖分层，有 deps 的子任务要等上一层跑完才轮到它 ——
+	// 期间界面上连「有这个任务」都看不到。
+	board := newBoard(emit)
+	for _, t := range plan.Tasks {
+		board.add(t, RouteFor(t, opts))
+	}
+	board.announce()
+
+	if opts.PlanOnly {
+		res.Text = "# 计划已生成\n\n" + res.PlanPath + "\n\n" + PlanMarkdown(plan) +
+			"\n\n（任务书已就绪：" + TaskDocPath(runDir, plan.Tasks[0].ID) + " 等 " +
+			strconv.Itoa(len(plan.Tasks)) + " 份；去掉了 --team-plan-only 就按这些任务书执行）"
+		res.SessionID = planSession
+		emit(agent.StreamEvent{Kind: agent.KindText, Text: res.Text})
+		res.Latency = time.Since(started)
+		return res, nil
+	}
+
+	// 执行。
+	results := executeWithHeartbeat(ctx, opts, plan, runDir, board)
+	if opts.Adaptive {
+		// 再规划只补一轮：它读的是第一轮的结果，追加的任务不再触发第二轮。
+		plan, results = adaptiveReplan(ctx, opts, plan, results, runDir, planSession, board)
+	}
+	res.Tasks = results
+
+	// 汇总。
+	text, sid := reduce(ctx, opts, plan, results, planSession, emit)
+	res.Text = text
+	if sid != "" {
+		res.SessionID = sid
+	} else {
+		res.SessionID = planSession
+	}
+	res.Latency = time.Since(started)
+	return res, nil
+}
+
+// planHeartbeat 计划阶段的进度播报间隔。
+const planHeartbeat = 5 * time.Second
+
+// planWithHeartbeat 跑计划阶段，等待期间定期播报「已等 N 秒」。
+//
+// 计划是一次**非流式**调用（ToolsOff，要模型整段吐 JSON），实测 40 秒起步；
+// 这期间一条事件都没有，客户端看起来就是「发出去了没反应」。心跳不伪造进度，
+// 只证明 core 还活着 —— 这是「无响应」里最长、也最容易被当成挂死的一段。
+//
+// 退出顺序：close(stop) 之后 wg.Wait()，保证心跳 goroutine 彻底停了才返回，
+// 否则它的 notice 可能插到「计划已生成」后面。
+func planWithHeartbeat(ctx context.Context, opts Options, emit func(agent.StreamEvent)) (Plan, string, error) {
+	stop := make(chan struct{})
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		start := time.Now()
+		tick := time.NewTicker(planHeartbeat)
+		defer tick.Stop()
+		for {
+			select {
+			case <-stop:
+				return
+			case <-ctx.Done():
+				return
+			case <-tick.C:
+				emit(agent.StreamEvent{
+					Kind: agent.KindNotice,
+					Text: fmt.Sprintf("团队模式：正在生成计划…（已 %d 秒）", int(time.Since(start).Seconds())),
+				})
+			}
+		}
+	}()
+	plan, sid, err := makePlan(ctx, opts)
+	close(stop)
+	wg.Wait()
+	return plan, sid, err
+}
+
+// 执行阶段的心跳参数。
+//
+// 子引擎可能几十秒到十几分钟不吐一条事件：模型侧 request 超时后 claude CLI 会自己
+// 重试，重试期间不产生任何 stream-json。此时任务列表里只有一行「运行中」，跟卡死
+// 无法区分。心跳不伪造进度，只证明「这个子任务还活着」。
+const (
+	taskHeartbeat = 20 * time.Second
+	taskQuiet     = 30 * time.Second
+)
+
+// executeWithHeartbeat 跑执行阶段，并对长时间没动静的子任务定期播报。
+func executeWithHeartbeat(ctx context.Context, opts Options, plan Plan, runDir string, board *Board) []TaskResult {
+	stop := make(chan struct{})
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tick := time.NewTicker(taskHeartbeat)
+		defer tick.Stop()
+		for {
+			select {
+			case <-stop:
+				return
+			case <-ctx.Done():
+				return
+			case <-tick.C:
+				for _, text := range board.quietLines() {
+					board.notice(text)
+				}
+			}
+		}
+	}()
+	results := execute(ctx, opts, plan, runDir, board)
+	close(stop)
+	wg.Wait()
+	return results
+}