magic-agent 1.0.49 → 1.0.108

package/internal/team/planner.go

@@ -0,0 +1,294 @@
+package team
+
+// planner.go - 让主引擎产出计划。
+//
+// 只用一次「关工具」的非流式调用：计划必须是可解析的结构化输出，而开着工具时模型
+// 会把读文件 / 跑命令的中间过程混进正文，解析成功率会掉。
+//
+// **失败不抛**：调用方拿到 error 就降级为单任务（见 Run）。团队模式的价值是并行，
+// 不是「计划完美」；计划不成也照样把活干了。
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// 拆解粒度（--team-split）。三档只改「最多拆几个子任务」这一个口径：
+//   - coarse   最多 3 个：宁少勿多，能用一段话讲完的活不单开执行者；
+//   - standard 最多 6 个（默认）：按交付物拆；
+//   - fine     最多 10 个：交付物有独立验收面就单开一个。
+const (
+	SplitCoarse   = "coarse"
+	SplitStandard = "standard"
+	SplitFine     = "fine"
+)
+
+// NormalizeSplit 拆解粒度归一（大小写不敏感；空 = standard）。err 非空 = 非法值。
+func NormalizeSplit(raw string) (string, error) {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "", SplitStandard:
+		return SplitStandard, nil
+	case SplitCoarse:
+		return SplitCoarse, nil
+	case SplitFine:
+		return SplitFine, nil
+	}
+	return "", fmt.Errorf("拆解粒度 %q 不合法（coarse | standard | fine）", raw)
+}
+
+// splitMaxTasks 该粒度下计划允许的最大子任务数。
+func splitMaxTasks(split string) int {
+	switch split {
+	case SplitCoarse:
+		return 3
+	case SplitFine:
+		return 10
+	default:
+		return 6
+	}
+}
+
+// codeGateStrict / codeGateLoose 代码类任务的拆解门槛（填进模板的 {{CODE_GATE}}）。
+//
+// 默认 strict：简单代码单开一个执行者，成本远高于主引擎顺手给出。用户要「简单代码也拆」
+// 时用 loose（--team-split-code）。
+const codeGateStrict = `**代码的门槛要高**：只有复杂代码才拆 code 任务；**简单代码**不拆子任务，由主引擎在
+  最终回复里直接给出（不要写进 tasks）：
+  - 单文件脚本、一次性片段、几行配置修改；
+  - 用户只问「怎么写 / 为什么报错 / 这段什么意思」的问答式请求；
+  - 改动面明确、不需要独立验收命令的小修小补。
+  判断标准就一句：**这个代码活是否值得单开一个执行者、独立跑构建或测试**。拿不准就不拆。`
+
+const codeGateLoose = `**代码也要拆**：只要需求里要改代码，就拆成 code 任务交给 coder —— 包括单文件脚本、
+  一次性片段、几行配置修改、小修小补。唯一不拆的是**纯问答**（用户只问「这段什么意思 /
+  为什么报错」，不需要改文件）：那种由主引擎直接答。`
+
+// plannerPromptTemplate 计划阶段的系统提示词模板（{{MAX_TASKS}} / {{CODE_GATE}}
+// 由 plannerPrompt 填）。三条硬要求写在这里，因为它们是**解析器依赖的契约**
+// （不是风格建议）：纯 JSON、任务数上限、每项的必填字段。
+const plannerPromptTemplate = `你是任务规划器。把用户的诉求拆成若干**可独立执行**的子任务。
+
+只输出一个 JSON 对象，不要任何解释、不要 markdown 围栏。结构：
+
+{
+  "goal": "一句话说明这次要达成什么",
+  "tasks": [
+    {
+      "id": "t1",
+      "role": "writer|researcher|reviewer|coder|designer|director|builder（必填，选一个）",
+      "title": "给人看的短标题（不超过 12 字）",
+      "prompt": "子任务的完整指令：目标、要用的材料、硬约束、验收标准",
+      "deps": ["依赖的任务 id"],
+      "inputs": ["本任务需要的上游文件名（必须与产出它的任务的 deliverables 完全一致）"],
+      "deliverables": ["交付物文件名（含扩展名）"],
+      "constraints": ["必须遵守的约束"],
+      "acceptance": ["可核对的验收条件"],
+      "check": ["可机器判定的验收命令，如 test -s brief.md"],
+      "required": true
+    }
+  ]
+}
+
+怎么拆（比什么都重要）：
+- **按交付物拆，不按用户的自我描述拆。** 用户写的「这是两个独立的小任务」「帮我做三件事」
+  「这块可以合并」只是需求线索，不是计划：最终任务数由你按交付物判定，可以多于也可以少于
+  用户说的数。用户没说清楚的地方，按「做完整需要哪些产物」补齐。
+- **逐个交付物选角色**，每个交付物一个子任务；角色决定类别（见下面的角色表），
+  所以不要把两个不同类别的交付物塞进同一个任务：
+  - text：文档、分析、结论、文案 → writer / researcher / reviewer。
+  - code：代码产出（脚本、程序、构建 / 测试相关的改动）→ coder。
+  - image：画面类产出（位图 / 矢量：封面、插画、海报、图标）→ designer。
+  - video：影像类产出（分镜、剪辑、成片）→ director。
+  - game：可运行的游戏工程（代码 + 素材 + 启动方式）→ builder。
+- {{CODE_GATE}}
+- **需求里出现了对应类别的产物，就必须单独拆出该类任务**，哪怕用户没明说「配图 / 做成视频」。
+  例：「写 100 字游戏介绍并配 1 个封面」→ 1 个 writer + 1 个 designer；
+  「做个能玩的小游戏」→ 1 个 builder（若要同时写介绍文案，再加 1 个 writer）。
+- **反方向同样成立**：纯文字需求不要硬塞 designer / director / builder / coder 任务。
+  没有画面产物就别派 designer，没有影像产物就别派 director，代码是否拆分见上面 code 那条。
+- 角色只决定「去哪儿找人干」：某个类别没配专用引擎时跟随主引擎，不代表这类活不能拆。
+
+规则：
+1. 每个子任务必须**自带足够上下文**（它们不共享会话，互相看不到对话历史）。
+2. 有先后依赖的用 deps 串起来；互不依赖的并发跑，尽量拆成互不依赖的。
+3. 交付物写成**具体的文件名**（如 cover.png / brief.md），不要写「一份报告」。
+4. 只做用户真的要的东西，不要为了「看起来像团队」硬拆。
+5. 子任务数量不超过 {{MAX_TASKS}} 个；超过就合并同类交付物，而不是砍掉类别。
+6. required 默认 true；只有「做不做都不影响结果」的才写 false。
+7. inputs 只写「下游真的要读上游文件」的那些，文件名必须与上游任务的 deliverables 逐字一致；
+   写进去的文件不存在时 core 会在开跑前直接判失败（不重试）。不要用它表达「可以参考一下」。
+8. check 只写**退出码能说明问题**的命令（在工作目录内执行），例如 test -s brief.md；
+   没有把握就写空数组 []，不要写 ls / echo 这类永远成功的命令。
+9. 每个任务收尾时要输出一个 JSON 交接单（files / summary / interface / open），
+   所以 prompt 里要让执行者知道：做完后把结果写成可被下游直接读的文件。
+10. role 必填，只能从角色表里选一个 —— 它就是执行者，类别由它决定（选错角色等于派错引擎）。
+   角色不改变交付物与验收要求：同一个文档任务可以是 writer 也可以是 reviewer。`
+
+// plannerPrompt 按 Options 渲染计划提示词：只有「最多几个」和「代码门槛」两项随配置变，
+// 其余规则（按交付物拆、字段契约）是解析器依赖的硬约束，任何档位都不动。
+func plannerPrompt(opts Options) string {
+	gate := codeGateStrict
+	if opts.SplitSimpleCode {
+		gate = codeGateLoose
+	}
+	split, _ := NormalizeSplit(opts.Split)
+	s := strings.ReplaceAll(plannerPromptTemplate, "{{CODE_GATE}}", gate)
+	return strings.ReplaceAll(s, "{{MAX_TASKS}}", fmt.Sprint(splitMaxTasks(split)))
+}
+
+// plannerSystemPrompt 默认口径（standard + 简单代码不拆）。
+var plannerSystemPrompt = plannerPrompt(Options{})
+
+// planSchema 计划输出的结构化约束。
+//
+// 只约束最关键的两个顶层字段：支持 JSONSchema 的引擎会照着吐，不支持的引擎仍靠
+// 系统提示词（plannerSystemPrompt）与 parsePlan 的容错。刻意不把 tasks 子项展开写进
+// Properties —— 各引擎对嵌套 schema 的支持程度不一致，这里只做「别吐闲聊」这一层。
+func planSchema() *agent.JSONSchema {
+	return &agent.JSONSchema{
+		Type:       "object",
+		Properties: map[string]map[string]any{"goal": {"type": "string"}, "tasks": {"type": "array"}},
+		Required:   []string{"goal", "tasks"},
+	}
+}
+
+// makePlan 调主引擎产出计划，并返回该轮的会话 id（汇总阶段要接着同一个会话）。
+//
+// 为什么汇总要接计划的会话：主引擎在计划里已经想过「怎么拆、每块留给谁」，汇总时
+// 它需要的正是这份上下文。两轮接同一条会话，用户后续追问也能自然接上。
+// ⚠️ 只有主引擎如此；子任务永远是空会话（不共享上下文）。
+func makePlan(ctx context.Context, opts Options) (Plan, string, error) {
+	if opts.Engine == nil {
+		return Plan{}, "", fmt.Errorf("主引擎为空")
+	}
+	route := PlanRoute(opts)
+	eng := agent.Lookup(route.Engine)
+	if eng == nil {
+		return Plan{}, "", fmt.Errorf("计划引擎 %s 不可用", route.Engine)
+	}
+	// 计划与汇总共用主引擎的那条会话（见上面的注释）。一旦计划换了引擎，session id
+	// 就属于**别人**了：既不能把主引擎的 id 传进去，也不能把计划这一轮的 id 交给汇总
+	// （跨引擎续接是错的）。代价是这一轮计划 / 汇总各起一条新会话。
+	onMain := strings.EqualFold(eng.Name(), opts.Engine.Name())
+	sid := ""
+	if onMain {
+		sid = opts.SessionID
+	}
+	// 计划阶段的超时：给一个明确上限，别让「模型一直不吐 JSON」把整轮拖死。
+	// 取值与子任务超时同源（见 taskTimeout），因为它本质上也是一次子任务。
+	pctx, cancel := context.WithTimeout(ctx, taskTimeout(opts))
+	defer cancel()
+
+	// 提示词里带上用户可用的引擎清单：模型据此把 image / video 类任务分配到真的
+	// 存在的引擎上（否则会写出一个谁都不认识的引擎名，路由阶段只能报「没有可用引擎」）。
+	prompt := strings.TrimSpace(opts.Prompt)
+	var hints []string
+	if hint := routeHint(opts); hint != "" {
+		hints = append(hints, hint)
+	}
+	if hint := roleHint(opts.Rules); hint != "" {
+		hints = append(hints, hint)
+	}
+	if len(hints) > 0 {
+		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{
+		Engine:       eng.Name(),
+		Model:        route.Model,
+		SystemPrompt: strings.TrimSpace(opts.SystemPrompt + "\n\n" + plannerPrompt(opts)),
+		// 关工具：计划要可解析，不要中间过程。
+		Tools: agent.ToolsOff,
+		// 计划输出本来就是 JSON，让支持结构化输出的引擎直接约束形状：
+		// 少一次「正文里找 JSON」的猜测，解析失败率跟着降。
+		JSONSchema: planSchema(),
+		Messages:   []agent.Message{{Role: "user", Content: prompt}},
+		Reasoning:  opts.Reasoning,
+		SessionID:  sid,
+		Continue:   sid == "" && onMain && opts.Continue,
+	})
+	if err != nil {
+		return Plan{}, "", err
+	}
+	plan, perr := parsePlan(resp.Text)
+	if !onMain {
+		return plan, "", perr
+	}
+	return plan, resp.SessionID, perr
+}
+
+// routeHint 把「这次五类任务分别落到哪个引擎」写进计划提示词。
+//
+// 五类**一律列出**，没配专用引擎的写「跟随主引擎」。早先的做法是把没配的类别整条略去
+// 并注明「不要拆出来」，结果本机全部跟随主引擎时，image / video / game 这类按需求该出现
+// 的子任务被提示词直接抹掉，计划永远只剩 text —— 拆几个任务应由需求决定，不该由
+// 「有没有配专用引擎」决定。
+//
+// 计划里只写角色，所以每行都带上该类别的角色名：模型挑角色时就知道会派到哪个引擎。
+func routeHint(opts Options) string {
+	main := ""
+	if opts.Engine != nil {
+		main = opts.Engine.Name()
+	}
+	pick := func(kind string) string {
+		if r, ok := opts.Routes[kind]; ok && strings.TrimSpace(r.Engine) != "" {
+			return r.Engine + modelSlash(r.Model)
+		}
+		if main == "" {
+			return "未配置"
+		}
+		return main + modelSlash(opts.Model) + "（跟随主引擎）"
+	}
+	var b strings.Builder
+	b.WriteString("子任务的类别由角色决定，各类分别交给：\n")
+	b.WriteString("- text（writer / researcher / reviewer）→ " + pick(KindText) + "\n")
+	b.WriteString("- code（coder）→ " + pick(KindCode) + "\n")
+	b.WriteString("- image（designer）→ " + pick(KindImage) + "\n")
+	b.WriteString("- video（director）→ " + pick(KindVideo) + "\n")
+	b.WriteString("- game（builder）→ " + pick(KindGame) + "\n")
+	b.WriteString("标了「跟随主引擎」的类别同样可以拆；拆不拆只看需求里有没有这类产物。\n")
+	if opts.SplitSimpleCode {
+		b.WriteString("code（coder）与其他类别一样：只要需求里要改代码就拆；只有纯问答（不改文件）由主引擎直接答。")
+	} else {
+		b.WriteString("唯一的例外是 code（coder）：只有复杂代码才拆，简单代码由主引擎在最终回复里直接给出。")
+	}
+	return b.String()
+}
+
+func modelSlash(model string) string {
+	if strings.TrimSpace(model) == "" {
+		return ""
+	}
+	return "/" + strings.TrimSpace(model)
+}
+
+// taskTimeout 单个子任务的超时。
+//
+// 推导规则（写死，别改成「就用总超时」）：总预算的一半，上限 20 分钟，下限 1 分钟。
+// 为什么是「一半」：一整轮里还有计划 + 汇总两段要跑，子任务全吃掉预算的话，
+// 最需要时间的汇总阶段会被 context deadline 掐掉 —— 而那一步才是用户看到的答案。
+func taskTimeout(opts Options) time.Duration {
+	if opts.TaskTimeout > 0 {
+		return opts.TaskTimeout
+	}
+	const (
+		floor = time.Minute
+		cap   = 20 * time.Minute
+	)
+	if opts.Timeout <= 0 {
+		return cap
+	}
+	d := opts.Timeout / 2
+	if d > cap {
+		d = cap
+	}
+	if d < floor {
+		d = floor
+	}
+	return d
+}

package/internal/team/reduce.go

@@ -0,0 +1,192 @@
+package team
+
+// reduce.go - 汇总：把各子任务的产出喂回主引擎，产出一份最终回答。
+//
+// 三条纪律：
+//
+//  1. **只喂摘要，不回灌全文**。子任务的正文已经落在 OUT-<id>.md 里，全灌进主引擎
+//     只会把上下文撑爆、把最有用的那句结论淹掉。每个任务给首段 + 产物清单 + 结局。
+//  2. **失败也要有答案**。reducer 自己失败时回落「产物清单 + 各任务首段」，仍以正常
+//     结果收尾 —— 用户至少知道谁做了什么、东西在哪。
+//  3. **缺失如实报**。交付物没找到就说没找到，不替子任务圆场。
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"strings"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// reduceCap 每个子任务喂给汇总阶段的正文上限（rune）。
+//
+// 1200 字 ≈ 一段摘要的量。任务多时总量仍可控（上限 6 个任务 ≈ 7k 字），而首段往往
+// 就是结论所在 —— 真要看细节，OUT-<id>.md 就在那儿。
+const reduceCap = 1200
+
+// reduce 调主引擎汇总；失败回落清单。planSession 是计划那一轮的会话 id（接同一条会话）。
+func reduce(ctx context.Context, opts Options, plan Plan, results []TaskResult, planSession string, emit func(agent.StreamEvent)) (string, string) {
+	emit(agent.StreamEvent{Kind: agent.KindNotice, Text: "团队模式：正在汇总…"})
+
+	prompt := reducePrompt(plan, results)
+	rctx, cancel := context.WithTimeout(ctx, taskTimeout(opts))
+	defer cancel()
+
+	runner := &agent.Runner{Engine: opts.Engine, Timeout: taskTimeout(opts)}
+	resp, err := runner.Run(rctx, agent.Request{
+		Engine:       opts.Engine.Name(),
+		Model:        opts.Model,
+		SystemPrompt: strings.TrimSpace(opts.SystemPrompt + "\n\n" + reduceSystemPrompt),
+		// 汇总也关工具：它只该整理已完成的产出，不该再去跑新东西。
+		Tools:     agent.ToolsOff,
+		Messages:  []agent.Message{{Role: "user", Content: prompt}},
+		Reasoning: opts.Reasoning,
+		// 接计划那一轮的会话：主引擎在计划里已经想过怎么拆，汇总要用的正是这份上下文。
+		SessionID: planSession,
+	})
+	if err != nil || strings.TrimSpace(resp.Text) == "" {
+		reason := "汇总失败"
+		if err != nil {
+			reason = agent.ReasonOf(err)
+			if reason == "" {
+				reason = err.Error()
+			}
+		}
+		text := fallbackSummary(plan, results, reason)
+		emit(agent.StreamEvent{Kind: agent.KindText, Text: text})
+		return text, ""
+	}
+	// 产物清单由 core 确定性追加，不交给模型（理由见 artsBlock）。
+	text := strings.TrimSpace(resp.Text) + artsBlock(results)
+	emit(agent.StreamEvent{Kind: agent.KindText, Text: text})
+	return text, resp.SessionID
+}
+
+const reduceSystemPrompt = `你是任务汇总者。下面是若干子任务的产出，请整合成一份**给用户看的最终答复**。
+
+要求：
+- 直接回答用户最初的诉求，不要把子任务逐个复述一遍。
+- 结果有冲突或缺口时**如实说明**，不要编造不存在的内容。
+- 不要在答复末尾罗列产物路径（系统会自动附上产物清单）；正文里提到文件时用短名字或相对路径。
+- 用中文，简洁。不要提到「子任务」「团队模式」这类实现细节。`
+
+// reducePrompt 组装汇总输入。
+func reducePrompt(plan Plan, results []TaskResult) string {
+	var b strings.Builder
+	b.WriteString("目标：" + orDash(plan.Goal) + "\n\n")
+	b.WriteString("各子任务产出：\n")
+	for _, r := range results {
+		b.WriteString("\n### " + r.ID + " · " + orDash(r.Title) + "（" + r.Kind + "）\n")
+		b.WriteString("结局：" + r.State)
+		if r.Reason != "" && r.State != TaskDone {
+			b.WriteString("（" + r.Reason + "）")
+		}
+		b.WriteString("\n")
+		if s := strings.TrimSpace(r.Text); s != "" {
+			b.WriteString(Truncate(s, reduceCap) + "\n")
+		}
+		if len(r.Arts) > 0 {
+			b.WriteString("产物：\n")
+			for _, a := range r.Arts {
+				b.WriteString("- " + a + "\n")
+			}
+		}
+		if len(r.Missing) > 0 {
+			b.WriteString("**缺少声明的交付物**：" + strings.Join(r.Missing, "、") + "\n")
+		}
+	}
+	b.WriteString("\n请据此产出最终答复。\n")
+	return b.String()
+}
+
+// artsBlock 生成确定性的「产物」清单（markdown 无序列表）。
+//
+// 为什么不让模型写（2026-10-22 用户报「产物显示异常」）：模型照「一行一个绝对路径」的
+// 要求输出后，markdown 把单换行折成空格 —— 三条长路径（`…/.magic/team/run-xxx/t1/impl/…`）
+// 粘成一大段，既读不出来也把运行内部目录整个摊在用户面前。路径是确定性数据：
+// 由 core 直接出列表，项各占一行、只显示相对**运行目录**的短路径，运行目录在末尾给一次。
+func artsBlock(results []TaskResult) string {
+	runDir := runDirOf(results)
+	type item struct{ rel, title string }
+	var items []item
+	for _, r := range results {
+		for _, a := range r.Arts {
+			items = append(items, item{rel: relArt(runDir, a), title: orDash(r.Title)})
+		}
+	}
+	if len(items) == 0 {
+		return ""
+	}
+	var b strings.Builder
+	b.WriteString("\n\n**产物**\n\n")
+	for _, it := range items {
+		b.WriteString("- `" + it.rel + "` · " + it.title + "\n")
+	}
+	if runDir != "" {
+		b.WriteString("\n全部位于：`" + runDir + "`")
+	}
+	return b.String()
+}
+
+// runDirOf 从任一任务的 OUT 路径反推运行目录（所有任务同属一次运行）。
+// 推不出来（没写过 OUT）就返回空串 —— 那时产物只能给绝对路径，宁可长也不给假短路径。
+func runDirOf(results []TaskResult) string {
+	for _, r := range results {
+		if r.OutputPath != "" {
+			return filepath.Dir(r.OutputPath)
+		}
+	}
+	return ""
+}
+
+// relArt 产物绝对路径 → 相对运行目录的短路径；不在运行目录下就原样返回。
+func relArt(runDir, abs string) string {
+	if runDir == "" {
+		return abs
+	}
+	s, err := filepath.Rel(runDir, abs)
+	if err != nil || s == ".." || strings.HasPrefix(s, ".."+string(filepath.Separator)) {
+		return abs
+	}
+	return s
+}
+
+// fallbackSummary reducer 失败时的兜底：清单式汇报。
+//
+// 它不好看，但它**每一句都是真的**，而且产物路径一个不少 —— 这正是失败时最该保证的。
+func fallbackSummary(plan Plan, results []TaskResult, reason string) string {
+	runDir := runDirOf(results)
+	var b strings.Builder
+	b.WriteString("已完成 " + fmt.Sprintf("%d", countDone(results)) + " / " + fmt.Sprintf("%d", len(results)) + " 项。\n")
+	b.WriteString("（汇总失败：" + reason + "，以下为原始结果。）\n\n")
+	for _, r := range results {
+		b.WriteString("## " + orDash(r.Title) + " · " + r.Kind + "\n")
+		b.WriteString("结局：" + r.State)
+		if r.Reason != "" && r.State != TaskDone {
+			b.WriteString("（" + r.Reason + "）")
+		}
+		b.WriteString("\n")
+		if s := strings.TrimSpace(r.Text); s != "" {
+			b.WriteString(Truncate(s, reduceCap) + "\n")
+		}
+		if len(r.Arts) > 0 {
+			b.WriteString("\n产物：\n")
+			for _, a := range r.Arts {
+				b.WriteString("- " + relArt(runDir, a) + "\n")
+			}
+		}
+		b.WriteString("\n")
+	}
+	return strings.TrimSpace(b.String())
+}
+
+func countDone(results []TaskResult) int {
+	n := 0
+	for _, r := range results {
+		if r.State == TaskDone {
+			n++
+		}
+	}
+	return n
+}