magic-agent 1.0.49 → 1.0.108

package/internal/team/plan.go

@@ -0,0 +1,903 @@
+package team
+
+// plan.go - 计划协议：结构、校验、拓扑排序、PLAN.md / TASK-<id>.md 的落盘。
+//
+// 两种形态，各归各的用途：
+//
+//	Plan（Go 结构）  主引擎产出的 JSON 解析而来，程序用；
+//	PLAN.md          给人看的计划文档，同时是**全队共享的事实源**（子任务只读它）。
+//
+// 为什么计划文档是 markdown 而不是 JSON：用户要能点开看、也要能看懂「它打算怎么干」。
+// JSON 只有程序读得懂，而团队模式的价值恰恰是过程可见。结构化数据仍留在内存里的
+// Plan 上，落盘只是投影。
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// Plan 主引擎给出的执行计划。
+type Plan struct {
+	// Goal 一句话目标（PLAN.md 的标题）。
+	Goal string `json:"goal"`
+	// Tasks 子任务；deps 允许为空（无依赖，可立即并发）。
+	Tasks []Task `json:"tasks"`
+}
+
+// Task 一个子任务。
+type Task struct {
+	ID string `json:"id"`
+	// Kind 任务类别。**派生字段**：由 Role 决定（见 EffectiveKind），计划 JSON 里不再写它。
+	// 保留是为了兼容旧计划 / 直接构造 Task 的调用方——它们只给 Kind 时按该类别的默认角色补 Role。
+	Kind string `json:"kind"`
+	// Role 执行角色（见 role.go）——任务的**唯一作者字段**，必填。
+	// 归一化后一定是内置角色之一；它与 Kind 冲突时以它为准。
+	Role  string `json:"role"`
+	Title string `json:"title"`
+	// Prompt 给子引擎的**完整**指令（不含 core 补的那层壳）。
+	Prompt string `json:"prompt"`
+	// Deps 依赖的任务 id（先跑完才启动本任务）。
+	Deps []string `json:"deps"`
+	// Engine / Model 指定引擎模型；空 = 按类别路由（见 RouteFor）。
+	Engine string `json:"engine"`
+	Model  string `json:"model"`
+	// Deliverables 交付物文件名（相对自己的工作目录）。core 收尾时逐个 stat。
+	Deliverables []string `json:"deliverables"`
+	// Inputs 本任务需要的上游文件名（必须与上游 deliverables 完全一致）。
+	// 由 deps 中的任务声明产出的算**硬依赖**：开跑前不存在就直接失败，不白跑模型。
+	Inputs []string `json:"inputs"`
+	// Check 验收命令（在工作目录内执行，退出码 0 才通过）。只接受可机器判定的命令。
+	Check []string `json:"check"`
+	// Required false = 失败不阻断汇总（尽力而为的子任务）。
+	Required *bool `json:"required"`
+	// Constraints 硬约束（逐条列进任务书）。
+	Constraints []string `json:"constraints"`
+	// Acceptance 验收标准（逐条列进任务书）。
+	Acceptance []string `json:"acceptance"`
+}
+
+// IsRequired 未显式声明时按「必需」处理 —— 计划里没写就不该静默降级。
+func (t Task) IsRequired() bool { return t.Required == nil || *t.Required }
+
+// EffectiveKind 任务实际生效的类别：角色的类别优先，其次旧的 Kind 字段，最后退 text。
+//
+// 这是**唯一**该被读取的类别口径（路由、校验、渲染、结果字段都用它）：Task.Kind 只是
+// 兼容用的回退输入，normalizeTask 会把派生结果写回它，但直接构造的 Task 未必过归一化。
+func (t Task) EffectiveKind() string {
+	if k := RoleKind(t.Role); k != "" {
+		return k
+	}
+	if k := NormalizeKind(t.Kind); k != "" {
+		return k
+	}
+	return KindText
+}
+
+// ParentID 该子任务在事件流里的委派卡 id。
+//
+// 形状是 `team_<task_id>`：`team_` 前缀让排障时一眼分出「这是团队模式合成的委派」
+// 与引擎原生的 tool_use id（toolu_… / call_…）。
+func (t Task) ParentID() string { return "team_" + t.ID }
+
+// InputSpec 一条 `inputs` 解析后的落点。
+//
+// 为什么要解析而不是直接拼路径：计划是模型写的，`inputs` 里可能写 `brief.md`，
+// 也可能写 `t1/brief.md`，还可能写绝对路径。更关键的是——**谁产出它**决定了
+// 「文件不在」意味着什么：由 deps 产出的缺失是硬错（上游没干完），
+// 计划里没人认领的只是个提示（可能就是用户自己提供的素材）。
+type InputSpec struct {
+	// Name 计划里声明的原名。
+	Name string
+	// Path 解析出的绝对路径（空 = 定位不到产出者）。
+	Path string
+	// From 产出该文件的任务 id（空 = 无来源）。
+	From string
+	// Hard 硬依赖：deps 中的任务声明了它作为交付物。
+	Hard bool
+}
+
+// ResolveInputs 把 `inputs` 解析成具体路径。
+//
+// 查找顺序：绝对路径 → deps 里声明的交付物 → 整张计划里声明的交付物。
+// 都找不到就给空 Path（任务书里只作提示，不判失败）。
+func ResolveInputs(runDir string, plan Plan, t Task) []InputSpec {
+	out := make([]InputSpec, 0, len(t.Inputs))
+	for _, raw := range t.Inputs {
+		name := strings.TrimSpace(raw)
+		if name == "" {
+			continue
+		}
+		spec := InputSpec{Name: name}
+		if filepath.IsAbs(name) {
+			spec.Path = name
+			out = append(out, spec)
+			continue
+		}
+		base := filepath.Base(name)
+		for _, d := range t.Deps {
+			dep, ok := findTask(plan, strings.TrimSpace(d))
+			if !ok {
+				continue
+			}
+			rel := declaredPath(dep, base)
+			if rel == "" {
+				continue
+			}
+			spec.Path = filepath.Join(TaskDir(runDir, dep.ID), rel)
+			spec.From = dep.ID
+			spec.Hard = true
+			break
+		}
+		if spec.From == "" {
+			for _, other := range plan.Tasks {
+				if strings.TrimSpace(other.ID) == strings.TrimSpace(t.ID) {
+					continue
+				}
+				rel := declaredPath(other, base)
+				if rel == "" {
+					continue
+				}
+				spec.Path = filepath.Join(TaskDir(runDir, other.ID), rel)
+				spec.From = other.ID
+				break
+			}
+		}
+		out = append(out, spec)
+	}
+	return out
+}
+
+// MissingInputs 硬依赖里**不存在**的文件（带来源说明）。
+//
+// 只核对 Hard：计划里没人认领的名字本来就无从核对，拿它判失败等于让模型的一处
+// 措辞断掉整条链。返回空 = 可以开跑。
+func MissingInputs(runDir string, plan Plan, t Task) []string {
+	var out []string
+	for _, spec := range ResolveInputs(runDir, plan, t) {
+		if !spec.Hard || spec.Path == "" {
+			continue
+		}
+		if _, err := os.Stat(spec.Path); err != nil {
+			out = append(out, fmt.Sprintf("%s（应由 %s 产出）", spec.Name, spec.From))
+		}
+	}
+	return out
+}
+
+func findTask(plan Plan, id string) (Task, bool) {
+	for _, t := range plan.Tasks {
+		if strings.TrimSpace(t.ID) == id {
+			return t, true
+		}
+	}
+	return Task{}, false
+}
+
+func declaresDeliverable(t Task, base string) bool {
+	return declaredPath(t, base) != ""
+}
+
+// declaredPath 在任务的交付物清单里找与 base 同名的项，返回它**相对任务目录**的路径
+// （保留子目录，如 impl/fizzbuzz.js）。找不到返回 ""。
+//
+// 为什么不能只取 filepath.Base：交付物常写在子目录里（impl/…、test/…），只留文件名
+// 会让 ResolveInputs 拼出 t1/fizzbuzz.js 这种不存在的路径，下游任务于是被判「缺少
+// 上游输入」——与 collectDeliverables 只认 basename 是同一类缺陷（2026-10-22 实测）。
+func declaredPath(t Task, base string) string {
+	for _, d := range t.Deliverables {
+		rel := cleanRel(d)
+		if rel == "" {
+			continue
+		}
+		if filepath.Base(rel) == base {
+			return rel
+		}
+	}
+	return ""
+}
+
+// cleanRel 把声明里的路径规整成「相对任务目录」的形式：去 ./、统一分隔符；
+// 绝对路径与 ../ 越界写法只保留文件名（子任务不该读写自己目录之外的东西）。
+// 返回空 = 没有有效路径。
+func cleanRel(p string) string {
+	name := strings.TrimSpace(p)
+	if name == "" {
+		return ""
+	}
+	name = filepath.ToSlash(name)
+	for strings.HasPrefix(name, "./") {
+		name = name[2:]
+	}
+	if name == "" {
+		return ""
+	}
+	if strings.HasPrefix(name, "/") || name == ".." || strings.HasPrefix(name, "../") {
+		name = filepath.Base(name)
+	}
+	return filepath.FromSlash(name)
+}
+
+// Handoff 子任务的交接单：正文末尾的一个 JSON 对象。
+//
+// 为什么不再只靠正文：下游需要的是「文件在哪、接口是什么、还有什么没解决」，
+// 让每个下游任务去读上游几千字正文里翻这些，等于把上下文成本转嫁给最需要
+// 省 token 的那一端。交接单是 core 能核对的**结构化收尾**。
+type Handoff struct {
+	Files     []string `json:"files"`
+	Summary   string   `json:"summary"`
+	Interface string   `json:"interface"`
+	Open      []string `json:"open"`
+}
+
+// parseHandoff 从子任务正文里取**最后一个** JSON 对象当交接单。
+//
+// 取最后一个：任务书本身、代码块里都可能出现 JSON，模型照约定会把交接单放在
+// 最后收尾。解析不出 / 全空字段时返回 nil，调用方回落到正文截断。
+func parseHandoff(text string) *Handoff {
+	raw, ok := lastJSONObject(text)
+	if !ok {
+		return nil
+	}
+	var h Handoff
+	if err := json.Unmarshal([]byte(raw), &h); err != nil {
+		return nil
+	}
+	if len(h.Files) == 0 && len(h.Open) == 0 &&
+		strings.TrimSpace(h.Summary) == "" && strings.TrimSpace(h.Interface) == "" {
+		return nil
+	}
+	return &h
+}
+
+// lastJSONObject 取文本里最后一个括号配对的 JSON 对象。
+func lastJSONObject(s string) (string, bool) {
+	var last string
+	found := false
+	for {
+		raw, ok := firstJSONObject(s)
+		if !ok {
+			return last, found
+		}
+		last, found = raw, true
+		i := strings.Index(s, raw)
+		s = s[i+len(raw):]
+	}
+}
+
+// handoffMarkdown 把交接单渲染成任务书里的「上游产出」区块。
+func handoffMarkdown(runDir, taskID string, h *Handoff) string {
+	var b strings.Builder
+	b.WriteString("**摘要**：" + orDash(h.Summary) + "\n\n")
+	if files := handoffFiles(runDir, taskID, h); len(files) > 0 {
+		b.WriteString("文件（绝对路径）：\n")
+		for _, f := range files {
+			b.WriteString("- " + f + "\n")
+		}
+		b.WriteString("\n")
+	}
+	if s := strings.TrimSpace(h.Interface); s != "" {
+		b.WriteString("**下游可直接使用的接口**：" + s + "\n\n")
+	}
+	if len(h.Open) > 0 {
+		b.WriteString("未解决：\n")
+		for _, o := range h.Open {
+			b.WriteString("- " + oneLine(o) + "\n")
+		}
+		b.WriteString("\n")
+	}
+	return b.String()
+}
+
+// handoffFiles 把交接单里的文件名补成绝对路径（相对路径按产出者自己的工作目录算）。
+func handoffFiles(runDir, taskID string, h *Handoff) []string {
+	var out []string
+	for _, f := range h.Files {
+		f = strings.TrimSpace(f)
+		if f == "" {
+			continue
+		}
+		if !filepath.IsAbs(f) {
+			f = filepath.Join(TaskDir(runDir, taskID), filepath.Base(f))
+		}
+		out = append(out, f)
+	}
+	return out
+}
+
+// HandoffSchema 交接单的结构（core 侧校验口径）。
+//
+// ⚠️ 刻意**不**塞进子任务的 agent.Request.JSONSchema：agent 的结构化输出后处理是
+// 「取文本里第一个匹配对象并整体替换正文」（见 agent/jsonextract.go），子任务正文
+// 会因此只剩那个 JSON —— 交接单本来就要和正文共存。planner 的输出是纯 JSON，才
+// 适合走 JSONSchema。所以子任务收尾靠这里的 schema 在 core 侧核对，核不过复用
+// 现有的「一次重试」路径。
+func HandoffSchema() *agent.JSONSchema {
+	return &agent.JSONSchema{
+		Type: "object",
+		Properties: map[string]map[string]any{
+			"files":     {"type": "array"},
+			"summary":   {"type": "string"},
+			"interface": {"type": "string"},
+			"open":      {"type": "array"},
+		},
+		Required: []string{"files", "summary"},
+	}
+}
+
+// handoffRequired 本任务的产物是否被下游当作**硬输入**。
+//
+// 只有这类任务才强制交接单：叶子任务的交接单没人读，强制只会把一次成功变成
+// 一次无谓重试。
+func handoffRequired(plan Plan, id string) bool {
+	self, ok := findTask(plan, id)
+	if !ok || len(self.Deliverables) == 0 {
+		return false
+	}
+	for _, t := range plan.Tasks {
+		if strings.TrimSpace(t.ID) == id {
+			continue
+		}
+		dep := false
+		for _, d := range t.Deps {
+			if strings.TrimSpace(d) == id {
+				dep = true
+				break
+			}
+		}
+		if !dep {
+			continue
+		}
+		for _, in := range t.Inputs {
+			if declaresDeliverable(self, filepath.Base(strings.TrimSpace(in))) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// handoffProblems 按 HandoffSchema 核对交接单；返回空 = 合格。
+func handoffProblems(plan Plan, t Task, r *TaskResult) []string {
+	if !handoffRequired(plan, t.ID) {
+		return nil
+	}
+	if r.Handoff == nil {
+		return []string{"缺少交接单：本任务的交付物是下游的硬输入，正文末尾必须给出 JSON 收尾对象"}
+	}
+	var lack []string
+	for _, field := range HandoffSchema().Required {
+		switch field {
+		case "files":
+			if len(r.Handoff.Files) == 0 {
+				lack = append(lack, field)
+			}
+		case "summary":
+			if strings.TrimSpace(r.Handoff.Summary) == "" {
+				lack = append(lack, field)
+			}
+		}
+	}
+	if len(lack) > 0 {
+		return []string{"交接单缺少必填字段：" + strings.Join(lack, "、")}
+	}
+	return nil
+}
+
+// Validate 校验计划：非空、id 唯一、类别合法、依赖存在、无环。
+//
+// 任一条不满足都返回错误 —— 调用方（Run）据它降级为单任务，**不硬跑一个坏计划**。
+func (p Plan) Validate() error {
+	if len(p.Tasks) == 0 {
+		return fmt.Errorf("计划里没有任务")
+	}
+	seen := make(map[string]bool, len(p.Tasks))
+	for _, t := range p.Tasks {
+		id := strings.TrimSpace(t.ID)
+		if id == "" {
+			return fmt.Errorf("有任务缺少 id")
+		}
+		if seen[id] {
+			return fmt.Errorf("任务 id 重复：%s", id)
+		}
+		seen[id] = true
+		if !ValidKind(t.EffectiveKind()) {
+			return fmt.Errorf("任务 %s 的类别 %q 不支持（可选：%s）", id, t.EffectiveKind(), strings.Join(Kinds, " / "))
+		}
+		if strings.TrimSpace(t.Prompt) == "" {
+			return fmt.Errorf("任务 %s 没有 prompt", id)
+		}
+	}
+	for _, t := range p.Tasks {
+		for _, d := range t.Deps {
+			if !seen[strings.TrimSpace(d)] {
+				return fmt.Errorf("任务 %s 依赖了不存在的任务 %q", t.ID, d)
+			}
+		}
+	}
+	if _, err := p.Order(); err != nil {
+		return err
+	}
+	return nil
+}
+
+// Order 拓扑排序，返回「按层」的任务分组：同一层的任务互不依赖。
+//
+// 这是**纯函数视图**：给校验和计划文档用（层 = 并行度的上界），不参与执行调度。
+// 真正跑的时候走 schedule.go 的 ReadyQueue —— 依赖一结束就开跑，不等同层其他任务。
+// 两者语义不同，别拿它当调度器。成环时返回错误（Validate 也靠它兜住环）。
+func (p Plan) Order() ([][]Task, error) {
+	byID := make(map[string]Task, len(p.Tasks))
+	for _, t := range p.Tasks {
+		byID[strings.TrimSpace(t.ID)] = t
+	}
+	done := make(map[string]bool, len(p.Tasks))
+	var layers [][]Task
+	for len(done) < len(byID) {
+		var layer []Task
+		for _, t := range p.Tasks {
+			id := strings.TrimSpace(t.ID)
+			if done[id] {
+				continue
+			}
+			ready := true
+			for _, d := range t.Deps {
+				if !done[strings.TrimSpace(d)] {
+					ready = false
+					break
+				}
+			}
+			if ready {
+				layer = append(layer, t)
+			}
+		}
+		if len(layer) == 0 {
+			// 剩下的都卡在依赖上 → 环。
+			var stuck []string
+			for _, t := range p.Tasks {
+				if id := strings.TrimSpace(t.ID); !done[id] {
+					stuck = append(stuck, id)
+				}
+			}
+			sort.Strings(stuck)
+			return nil, fmt.Errorf("任务依赖成环：%s", strings.Join(stuck, " → "))
+		}
+		// 层内顺序按 id 排，输出稳定（PLAN.md 的表格因此不会每次都不一样）。
+		sort.SliceStable(layer, func(i, j int) bool { return layer[i].ID < layer[j].ID })
+		for _, t := range layer {
+			done[strings.TrimSpace(t.ID)] = true
+		}
+		layers = append(layers, layer)
+	}
+	return layers, nil
+}
+
+// ValidKind 类别是否受支持。
+func ValidKind(k string) bool {
+	k = strings.TrimSpace(k)
+	for _, x := range Kinds {
+		if x == k {
+			return true
+		}
+	}
+	return false
+}
+
+// NormalizeKind 把模型可能给出的近义写法收拢到五类；认不出返回空串。
+//
+// 为什么要它：计划是模型产出的，`Text` / `image-generation` / `代码` 这类写法必然出现。
+// 收不拢就降级为 text（而不是整份计划作废）——一张图没画成远好过整轮白跑。
+//
+// code 必须排在 text 之前判断：早先把 "code" 归在 text 分支里，导致代码任务永远
+// 走不到代码引擎。
+func NormalizeKind(k string) string {
+	s := strings.ToLower(strings.TrimSpace(k))
+	switch {
+	case s == "":
+		return ""
+	case strings.Contains(s, "image"), strings.Contains(s, "img"), strings.Contains(s, "图"):
+		return KindImage
+	case strings.Contains(s, "video"), strings.Contains(s, "视频"):
+		return KindVideo
+	case strings.Contains(s, "game"), strings.Contains(s, "游"):
+		return KindGame
+	case strings.Contains(s, "code"), strings.Contains(s, "coding"),
+		strings.Contains(s, "代码"), strings.Contains(s, "编码"),
+		strings.Contains(s, "程序"), strings.Contains(s, "编程"):
+		return KindCode
+	case strings.Contains(s, "text"), strings.Contains(s, "doc"), strings.Contains(s, "文"):
+		return KindText
+	}
+	return ""
+}
+
+// parsePlan 从模型输出里取计划 JSON。
+//
+// 模型常见三种包裹：裸 JSON、```json 围栏、一段话里夹一个 JSON 对象。三种都认
+// （agent.firstJSONObject 是包内的，这里按同样的做法自己实现一份，避免为了一个
+// 函数把 team 包和 agent 包耦合得更深）。
+func parsePlan(text string) (Plan, error) {
+	raw, ok := firstJSONObject(text)
+	if !ok {
+		return Plan{}, fmt.Errorf("输出里没有 JSON 对象")
+	}
+	var plan Plan
+	if err := json.Unmarshal([]byte(raw), &plan); err != nil {
+		return Plan{}, fmt.Errorf("计划 JSON 解析失败：%w", err)
+	}
+	for i := range plan.Tasks {
+		plan.Tasks[i] = normalizeTask(plan.Tasks[i])
+	}
+	return plan, nil
+}
+
+// normalizeTask 把模型可能写歪的字段收拢到 core 的规范值。
+//
+// 计划轮与再规划轮共用：两条路径都直接吃模型输出，归一化必须一致。
+//
+// **角色是唯一来源**：Role 归一化后，Kind 一律取 RoleKind(Role)；模型写的 kind 只在
+// role 缺失/认不出时充当回退线索（旧计划兼容），不会与角色并存互相打架。
+func normalizeTask(t Task) Task {
+	t.ID = strings.TrimSpace(t.ID)
+	role := NormalizeRole(t.Role)
+	if role == "" {
+		// 没写角色 / 角色不在表里：按旧的 kind 回退到该类别的默认角色。
+		if r := DefaultRoleForKind(NormalizeKind(t.Kind)); r != nil {
+			role = r.Name
+		}
+	}
+	if role == "" {
+		role = "writer"
+	}
+	t.Role = role
+	t.Kind = RoleKind(role)
+	if strings.TrimSpace(t.Title) == "" {
+		t.Title = t.ID
+	}
+	return t
+}
+
+// firstJSONObject 从文本里截出第一个**括号配对**的 JSON 对象（含被 ``` 围栏包住的情况）。
+func firstJSONObject(s string) (string, bool) {
+	start := strings.Index(s, "{")
+	if start < 0 {
+		return "", false
+	}
+	depth, inStr, esc := 0, false, false
+	for i := start; i < len(s); i++ {
+		c := s[i]
+		if inStr {
+			switch {
+			case esc:
+				esc = false
+			case c == '\\':
+				esc = true
+			case c == '"':
+				inStr = false
+			}
+			continue
+		}
+		switch c {
+		case '"':
+			inStr = true
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				return s[start : i+1], true
+			}
+		}
+	}
+	return "", false
+}
+
+// fallbackPlan 降级用：把用户原话当成唯一一个 text 子任务。
+//
+// 刻意**不**把主引擎再跑一遍 —— 降级的语义是「计划这一步没做成，那就直接干」，
+// 再跑一次只会把失败时间翻倍。
+func fallbackPlan(prompt string) Plan {
+	one := true
+	return Plan{
+		Goal: firstLine(prompt, 60),
+		Tasks: []Task{{
+			ID:           "t1",
+			Kind:         KindText,
+			Role:         "writer",
+			Title:        "直接执行",
+			Prompt:       prompt,
+			Required:     &one,
+			Deliverables: nil,
+		}},
+	}
+}
+
+// PlanPath PLAN.md 的路径。
+func PlanPath(runDir string) string { return filepath.Join(runDir, "PLAN.md") }
+
+// TaskDocPath TASK-<id>.md 的路径。
+func TaskDocPath(runDir, id string) string { return filepath.Join(runDir, "TASK-"+id+".md") }
+
+// OutputPath OUT-<id>.md 的路径。
+func OutputPath(runDir, id string) string { return filepath.Join(runDir, "OUT-"+id+".md") }
+
+// ArtsPath ARTS-<id>.json 的路径。
+func ArtsPath(runDir, id string) string { return filepath.Join(runDir, "ARTS-"+id+".json") }
+
+// HandoffPath HANDOFF-<id>.json 的路径。
+func HandoffPath(runDir, id string) string { return filepath.Join(runDir, "HANDOFF-"+id+".json") }
+
+// TaskDir 子任务自己的工作目录。
+func TaskDir(runDir, id string) string { return filepath.Join(runDir, id) }
+
+// WritePlanDoc 写 PLAN.md 并置为只读。
+//
+// 只读是刻意的：它是全队共享的事实源，子任务（尤其带 full 权限的那些）不该改动它。
+// 置只读不防恶意，但足以让「子引擎顺手改了几笔」这种事故在第一次 open 时就暴露。
+func WritePlanDoc(runDir string, plan Plan, opts Options) error {
+	if err := os.MkdirAll(runDir, 0o755); err != nil {
+		return err
+	}
+	body := PlanMarkdown(plan)
+	head := fmt.Sprintf("# 计划 · %s\n\n"+
+		"run_id: %s\n"+
+		"主引擎: %s%s\n"+
+		"创建: %s\n\n"+
+		"> 这份文档是全队共享的事实源（只读）。子任务只读它，产物落在各自的工作目录。\n\n",
+		orDash(plan.Goal), orDash(opts.RunID), opts.Engine.Name(), modelSuffix(opts.Model),
+		time.Now().Format(time.RFC3339))
+	return writeReadOnly(PlanPath(runDir), head+body)
+}
+
+// PlanMarkdown 把计划渲染成 markdown（不含文件头的 run_id / 创建时间）。
+func PlanMarkdown(plan Plan) string {
+	var b strings.Builder
+	b.WriteString("## 任务总览\n\n")
+	b.WriteString("| id | 角色（类别） | 标题 | 依赖 | 引擎/模型 | 必需 | 交付物 |\n")
+	b.WriteString("| --- | --- | --- | --- | --- | --- | --- |\n")
+	for _, t := range plan.Tasks {
+		eng := orDash(t.Engine)
+		if t.Model != "" {
+			eng += "/" + t.Model
+		}
+		req := "是"
+		if !t.IsRequired() {
+			req = "否"
+		}
+		b.WriteString(fmt.Sprintf("| %s | %s | %s | %s | %s | %s | %s |\n",
+			t.ID, roleText(t.Role)+"（"+t.EffectiveKind()+"）", oneLine(t.Title), depsText(t.Deps), eng, req, depsText(t.Deliverables)))
+	}
+	for _, t := range plan.Tasks {
+		b.WriteString("\n## " + strings.ToUpper(t.ID) + " · " + oneLine(t.Title) + "\n\n")
+		b.WriteString("角色：" + roleDetail(t.Role) + "\n\n")
+		b.WriteString("类别：" + t.EffectiveKind() + "（由角色决定）· 必需：" + boolText(t.IsRequired()) + "\n\n")
+		b.WriteString(strings.TrimSpace(t.Prompt) + "\n")
+		if len(t.Inputs) > 0 {
+			b.WriteString("\n输入：" + depsText(t.Inputs) + "\n")
+		}
+		if len(t.Constraints) > 0 {
+			b.WriteString("\n约束：\n")
+			for _, c := range t.Constraints {
+				b.WriteString("- " + oneLine(c) + "\n")
+			}
+		}
+		if len(t.Acceptance) > 0 {
+			b.WriteString("\n验收：\n")
+			for _, c := range t.Acceptance {
+				b.WriteString("- " + oneLine(c) + "\n")
+			}
+		}
+		if len(t.Check) > 0 {
+			b.WriteString("\n验收命令（在工作目录内执行，退出码 0 才通过）：\n")
+			for _, c := range t.Check {
+				b.WriteString("- `" + oneLine(c) + "`\n")
+			}
+		}
+	}
+	return b.String()
+}
+
+// TaskDoc 渲染一个子任务的任务书（TASK-<id>.md）。
+//
+// 任务书是子任务**唯一的上下文来源**（不共享会话），所以四样东西必须齐：
+// 目标（干到什么算完）、上游产出（前面的人做了什么）、约束（不许做什么）、
+// 交付物（交什么、叫什么名字）。缺一样，子引擎就只能猜。
+func TaskDoc(runDir string, plan Plan, t Task, upstream map[string]TaskResult) string {
+	var b strings.Builder
+	b.WriteString("# 任务书 · " + strings.ToUpper(t.ID) + " · " + oneLine(t.Title) + "\n\n")
+	b.WriteString("你在一个团队任务里承担第 " + t.ID + " 个子任务。\n\n")
+	b.WriteString("- 计划文档（只读，全队共享）：" + PlanPath(runDir) + "\n")
+	b.WriteString("- 你的任务书（只读）：" + TaskDocPath(runDir, t.ID) + "\n")
+	b.WriteString("- 你的工作目录：" + TaskDir(runDir, t.ID) + "（**只能**在这里写文件）\n")
+	b.WriteString("- 全队目标：" + orDash(plan.Goal) + "\n\n")
+
+	if r := LookupRole(t.Role); r != nil {
+		b.WriteString("## 你的角色\n\n")
+		b.WriteString("**" + r.Name + "** —— " + orDash(r.Duty) + "\n\n")
+		b.WriteString("按这个角色的标准要求自己；任务书里的交付物与验收标准仍是硬要求，不能因为角色而打折。\n\n")
+	}
+
+	b.WriteString("## 任务\n\n" + strings.TrimSpace(t.Prompt) + "\n\n")
+
+	if len(t.Inputs) > 0 {
+		b.WriteString("## 输入\n\n")
+		for _, spec := range ResolveInputs(runDir, plan, t) {
+			switch {
+			case spec.Path == "":
+				b.WriteString("- `" + spec.Name + "` —— 计划里没写明谁产出它；先按任务描述自己找，找不到就说明缺什么\n")
+			case spec.Hard:
+				b.WriteString("- `" + spec.Name + "` → " + spec.Path + "（由 " + spec.From + " 产出，**必须读到**）\n")
+			default:
+				b.WriteString("- `" + spec.Name + "` → " + spec.Path + "（来自 " + spec.From + "）\n")
+			}
+		}
+		b.WriteString("\n")
+	}
+
+	if len(t.Deps) > 0 {
+		b.WriteString("## 上游产出\n\n")
+		for _, d := range t.Deps {
+			r, ok := upstream[strings.TrimSpace(d)]
+			b.WriteString("### " + d + " · " + orDash(r.Title) + "\n\n")
+			switch {
+			case !ok:
+				b.WriteString("（上游没有产出）\n\n")
+			case r.State != "done":
+				b.WriteString("（上游未完成：" + orDash(r.Reason) + "）\n\n")
+			default:
+				if r.Handoff != nil {
+					rid := r.ID
+					if strings.TrimSpace(rid) == "" {
+						rid = strings.TrimSpace(d)
+					}
+					b.WriteString(handoffMarkdown(runDir, rid, r.Handoff))
+				} else {
+					b.WriteString(Truncate(r.Text, upstreamCap) + "\n\n")
+				}
+				if len(r.Arts) > 0 {
+					b.WriteString("产物：\n")
+					for _, a := range r.Arts {
+						b.WriteString("- " + a + "\n")
+					}
+					b.WriteString("\n")
+				}
+			}
+		}
+	}
+
+	if len(t.Constraints) > 0 {
+		b.WriteString("## 必须遵守\n\n")
+		for _, c := range t.Constraints {
+			b.WriteString("- " + oneLine(c) + "\n")
+		}
+		b.WriteString("\n")
+	}
+
+	b.WriteString("## 交付物\n\n")
+	if len(t.Deliverables) == 0 {
+		b.WriteString("无强制交付物；把结论写清楚即可。\n\n")
+	} else {
+		for _, d := range t.Deliverables {
+			b.WriteString("- `" + d + "` —— 放在工作目录下，**必须用这个文件名**（汇总时按名字核对）\n")
+		}
+		b.WriteString("\n")
+	}
+
+	if len(t.Acceptance) > 0 {
+		b.WriteString("## 验收标准\n\n")
+		for _, c := range t.Acceptance {
+			b.WriteString("- " + oneLine(c) + "\n")
+		}
+		b.WriteString("\n")
+	}
+
+	b.WriteString("## 收尾要求\n\n" +
+		"做完（或确认做不到）后，用**一个 JSON 对象**收尾（可以放在 ```json 围栏里）：\n\n" +
+		"```json\n" +
+		"{\"files\":[\"交付物文件名\"],\"summary\":\"做了什么、结论是什么\",\"interface\":\"下游可以直接用的接口/路径\",\"open\":[\"未解决项\"]}\n" +
+		"```\n\n" +
+		"core 会把这个交接单（而不是整段正文）交给下游任务，所以 summary 要能独立读懂；" +
+		"没有的字段给空数组 / 空字符串，不要省略。\n")
+	if handoffRequired(plan, t.ID) {
+		b.WriteString("\n本任务的交付物是下游的**硬输入**：交接单必须给出非空的 files 与 summary，" +
+			"缺任一项视为未通过核对（会要求你补齐后重试一次）。\n")
+	}
+	return b.String()
+}
+
+// upstreamCap 上游正文写进任务书时的上限。
+//
+// 8KB ≈ 两三千汉字：够说清「上游做了什么、留了哪些接口」，又不至于把任务书撑成
+// 一整份上下文。超长给首尾两段（中间省略），因为结论常在首尾。
+const upstreamCap = 8192
+
+// WriteTaskDoc 写 TASK-<id>.md 并置为只读。
+func WriteTaskDoc(runDir string, plan Plan, t Task) error {
+	body := TaskDoc(runDir, plan, t, nil)
+	return writeReadOnly(TaskDocPath(runDir, t.ID), body)
+}
+
+// EnsureTaskDir 建子任务工作目录。
+func EnsureTaskDir(runDir, id string) error {
+	return os.MkdirAll(TaskDir(runDir, id), 0o755)
+}
+
+// writeReadOnly 原子写文件后置为 0444（已存在时先去掉只读位再覆盖）。
+func writeReadOnly(path, body string) error {
+	if _, err := os.Stat(path); err == nil {
+		_ = os.Chmod(path, 0o644)
+	}
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		return err
+	}
+	return os.Chmod(path, 0o444)
+}
+
+// Truncate 按 rune 截断，超过上限时保留首尾两段并标注省略了多少。
+func Truncate(s string, max int) string {
+	s = strings.TrimSpace(s)
+	if max <= 0 {
+		return s
+	}
+	r := []rune(s)
+	if len(r) <= max {
+		return s
+	}
+	headN := max * 2 / 3
+	tailN := max - headN
+	return string(r[:headN]) +
+		fmt.Sprintf("\n\n…（中间省略 %d 字）…\n\n", len(r)-headN-tailN) +
+		string(r[len(r)-tailN:])
+}
+
+func orDash(s string) string {
+	if strings.TrimSpace(s) == "" {
+		return "—"
+	}
+	return strings.TrimSpace(s)
+}
+
+func boolText(b bool) string {
+	if b {
+		return "是"
+	}
+	return "否"
+}
+
+func oneLine(s string) string {
+	return strings.TrimSpace(strings.ReplaceAll(strings.ReplaceAll(s, "\n", " "), "|", "\\|"))
+}
+
+func depsText(xs []string) string {
+	var out []string
+	for _, x := range xs {
+		if s := strings.TrimSpace(x); s != "" {
+			out = append(out, s)
+		}
+	}
+	if len(out) == 0 {
+		return "—"
+	}
+	return strings.Join(out, "、")
+}
+
+func modelSuffix(model string) string {
+	if strings.TrimSpace(model) == "" {
+		return ""
+	}
+	return "/" + strings.TrimSpace(model)
+}
+
+func firstLine(s string, max int) string {
+	s = strings.TrimSpace(s)
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		s = s[:i]
+	}
+	return Truncate(s, max)
+}