magic-agent 1.0.46 → 1.0.108

package/internal/team/role.go

@@ -0,0 +1,334 @@
+package team
+
+// role.go - 子任务角色（对齐 Claude subagent：一个任务只有一个执行角色）。
+//
+// **角色就是执行者**，类别是角色的属性而不是另一个作者字段：
+//
+//	role  writer / coder / designer / …
+//	  └─ kind  text / code / image / …   ← 由角色派生，只读
+//
+// 所以计划里只写 role。类别由 RoleKind(role) 推出来，用来选引擎（见 RouteFor）、
+// 渲染计划文档与事件流；模型即便写了 kind 也以角色为准，避免出现
+// `{"kind":"image","role":"coder"}` 这种「派给图片引擎却带着代码人设」的矛盾。
+//
+// 角色决定三件事：注入的系统提示词片段、默认模型、所属类别。
+// 它**不改变交付要求**：交付物、验收命令、依赖仍由计划里的任务本身决定。
+
+import (
+	"fmt"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// Role 一个执行角色。字段刻意只留「会影响请求」的那些，不做角色编排系统。
+type Role struct {
+	// Name 规范名（计划里写的就是它）。
+	Name string
+	// Duty 一句话职责（写进计划文档与任务书）。
+	Duty string
+	// SystemPrompt 该角色的系统提示词片段（追加在主系统提示词之后）。
+	SystemPrompt string
+	// Kind 该角色所属的类别；任务的类别一律由它派生（RoleKind）。
+	Kind string
+	// Model 该角色的默认模型：只在路由没指定模型时生效。
+	Model string
+	// Tools 工具白名单（空 = 沿用 Options.Tools）。
+	Tools []string
+	// Permission 权限档位（空 = 沿用 Options.Permission）。
+	Permission agent.PermissionTier
+}
+
+// builtinRoles 内置角色表。
+//
+// **按五类子任务对齐**（text / code / image / video / game）：每一类都至少有一个角色，
+// 表里的 Kind 就是该类任务的类别 —— 计划只写角色，类别由角色派生。
+// 顺序即 roleHint / 文档里的顺序（先按类别，再按同类别内的常用度）。
+//
+// 只放跨项目都成立的通用分工；未知名会被清空并回退到默认角色，所以这里保持
+// 「少而稳」，不追求覆盖所有职业。
+var builtinRoles = []Role{
+	{
+		Name:         "writer",
+		Duty:         "把材料写成结构清晰、可直接交付的文档",
+		SystemPrompt: "你的角色是写作者。先想清楚读者与用途，再组织结构；只写任务书要求的内容，不编造事实与数据；交付前自检标题层级、术语一致性与文件名。",
+		Kind:         KindText,
+	},
+	{
+		Name:         "researcher",
+		Duty:         "查证事实、比对方案，给出有依据的结论",
+		SystemPrompt: "你的角色是调研者。先列出需要回答的问题，再逐条取证；区分事实、推断与未知，找不到依据就明说；结论要能落到可核对的来源或文件路径上。",
+		Kind:         KindText,
+	},
+	{
+		Name:         "reviewer",
+		Duty:         "按验收标准挑问题，不重写别人的产出",
+		SystemPrompt: "你的角色是评审者。逐条对照任务书的验收标准给出结论（通过 / 不通过 + 证据）；只指出可验证的问题，并给出最小修改建议；不要顺手重写交付物。",
+		Kind:         KindText,
+	},
+	{
+		Name:         "coder",
+		Duty:         "把复杂代码改动落到可构建、可测试的文件上",
+		SystemPrompt: "你的角色是代码实现者。先读懂现有代码与改动面，再动手；只改任务书点名的范围，不做顺手重构；每处改动都要能通过任务书给出的构建或测试命令，失败就修到通过为止；交付时说明改了哪些文件、怎么验证。",
+		Kind:         KindCode,
+	},
+	{
+		Name:         "designer",
+		Duty:         "产出可直接使用的画面资产",
+		SystemPrompt: "你的角色是视觉设计者。先定构图与信息层级，再落笔；严格遵守任务书给出的尺寸、格式与文件名；除非任务要求，不要把说明文字画进图里。",
+		Kind:         KindImage,
+	},
+	{
+		Name:         "director",
+		Duty:         "把脚本 / 分镜变成可播放的影像",
+		SystemPrompt: "你的角色是影像导演。先定镜头顺序与节奏，再逐段生成；严格遵守任务书给出的时长、画幅、格式与文件名；交付前确认成片能完整播放、字幕与画面同步。",
+		Kind:         KindVideo,
+	},
+	{
+		Name:         "builder",
+		Duty:         "交付能跑起来的工程与可复现的启动方式",
+		SystemPrompt: "你的角色是游戏 / 工程构建者。优先让产物可运行：先搭最小可运行骨架，再补功能；所有命令都要在工作目录内可复现，依赖与启动方式写进交付物。",
+		Kind:         KindGame,
+	},
+}
+
+// DefaultRoleForKind 某一类的默认角色。
+//
+// 只在两条兼容路径上使用：计划漏写 role（或写了认不出的角色）时，按旧的 kind 字段
+// 回退到该类的默认角色；直接构造 Task{Kind: …} 的调用方同理。
+func DefaultRoleForKind(kind string) *Role {
+	for i := range builtinRoles {
+		if builtinRoles[i].Kind == kind {
+			return &builtinRoles[i]
+		}
+	}
+	return nil
+}
+
+// RoleKind 角色所属的类别（空 = 未知角色）。任务的 Kind 一律由它派生，不再从模型输出取。
+func RoleKind(name string) string {
+	if r := LookupRole(name); r != nil {
+		return r.Kind
+	}
+	return ""
+}
+
+// roleAliases 计划里可能出现的近义写法 → 规范名。
+//
+// 与 NormalizeKind 同一套思路：收不拢的写法不该让整份计划作废，丢掉角色即可。
+var roleAliases = map[string]string{
+	"writer":     "writer",
+	"author":     "writer",
+	"写作":         "writer",
+	"写手":         "writer",
+	"researcher": "researcher",
+	"research":   "researcher",
+	"调研":         "researcher",
+	"研究":         "researcher",
+	"designer":   "designer",
+	"design":     "designer",
+	"视觉":         "designer",
+	"设计":         "designer",
+	// 影像导演。刻意不收录 "video" / "视频"：它们是类别路由的键，收进来会把
+	// `--team-route video=…` 抢成 `role:director=…`（normalizeRouteKind 先查角色）。
+	"director":  "director",
+	"film":      "director",
+	"filmmaker": "director",
+	"导演":        "director",
+	"影像":        "director",
+	"短片":        "director",
+	// 代码实现角色。别名只收「职种」写法，刻意不收 "code" / "代码"：它们是类别路由的键，
+	// 收进来会把 `--team-route code=…` 抢成 `role:coder=…`（normalizeRouteKind 先查角色）。
+	"coder":      "coder",
+	"engineer":   "coder",
+	"developer":  "coder",
+	"programmer": "coder",
+	"工程":         "coder",
+	"开发":         "coder",
+	"程序员":        "coder",
+	"builder":    "builder",
+	"gamedev":    "builder",
+	"游戏":         "builder",
+	"reviewer":   "reviewer",
+	"review":     "reviewer",
+	"评审":         "reviewer",
+	"审查":         "reviewer",
+}
+
+// NormalizeRole 把模型 / 配置里的角色写法归一到规范名；认不出返回空串。
+func NormalizeRole(s string) string {
+	s = strings.ToLower(strings.TrimSpace(s))
+	s = strings.TrimSpace(strings.TrimPrefix(s, "role:"))
+	if s == "" {
+		return ""
+	}
+	if name, ok := roleAliases[s]; ok {
+		return name
+	}
+	return ""
+}
+
+// LookupRole 按名字取角色；未知 / 空返回 nil。
+func LookupRole(name string) *Role {
+	n := NormalizeRole(name)
+	if n == "" {
+		return nil
+	}
+	for i := range builtinRoles {
+		if builtinRoles[i].Name == n {
+			return &builtinRoles[i]
+		}
+	}
+	return nil
+}
+
+// RoleInfo 角色的**机器可读描述**，供 `--contract` 的 teamRoles 使用。
+//
+// 客户端据此渲染角色路由行（移动端「团队模式」子页面，缩进在所属类别行下面），
+// 不必在客户端硬编码角色名 —— 以后往 builtinRoles 里加角色，界面自动多一行。
+type RoleInfo struct {
+	Name string `json:"name"`
+	Kind string `json:"kind"`
+	Duty string `json:"duty"`
+	// Model 角色默认模型（空 = 不指定）；客户端只展示，不参与路由决策。
+	Model string `json:"model,omitempty"`
+}
+
+// RoleInfos 输出角色清单（顺序同 builtinRoles，即提示词与界面里的顺序）。
+func RoleInfos() []RoleInfo {
+	out := make([]RoleInfo, 0, len(builtinRoles))
+	for _, r := range builtinRoles {
+		out = append(out, RoleInfo{Name: r.Name, Kind: r.Kind, Duty: r.Duty, Model: r.Model})
+	}
+	return out
+}
+
+// RoleNames 规范名清单（顺序即提示词里的顺序）。
+func RoleNames() []string {
+	out := make([]string, 0, len(builtinRoles))
+	for _, r := range builtinRoles {
+		out = append(out, r.Name)
+	}
+	return out
+}
+
+// RoleKey 角色在路由表里的键。
+//
+// 加 `role:` 前缀是为了与类别键（plan / text / code / image / video / game）共处一张表
+// 而不打架：`--team-route role:reviewer=claude`。
+func RoleKey(name string) string {
+	n := NormalizeRole(name)
+	if n == "" {
+		return ""
+	}
+	return "role:" + n
+}
+
+// roleHint 把角色清单写进计划提示词。
+//
+// 角色是任务唯一的作者字段，类别由它决定：这里带上类别，模型挑角色时就等于同时
+// 决定了「派给哪类引擎」，不会写出角色与类别互相矛盾的计划。
+//
+// rules 是用户改写的「这类任务适合什么」（--team-rule role:<name>=…）；有就替掉
+// 内置 Duty，没有就用内置的一句。只影响**计划怎么判断**，不改执行者的系统提示词。
+func roleHint(rules map[string]string) string {
+	var b strings.Builder
+	b.WriteString("角色表（任务的 role 字段必填，只能选一个；方括号是它决定的类别）：\n")
+	for _, r := range builtinRoles {
+		duty := r.Duty
+		if v, ok := rules[RoleKey(r.Name)]; ok && strings.TrimSpace(v) != "" {
+			duty = strings.TrimSpace(v)
+		}
+		b.WriteString("- " + r.Name + " [" + r.Kind + "] —— " + duty + "\n")
+	}
+	b.WriteString("角色就是执行者：它决定类别（进而决定派给哪个引擎）、系统提示词与默认模型；" +
+		"角色的职责描述不改变任务书里的交付物与验收要求。")
+	return b.String()
+}
+
+// RulesMaxLen 单条角色规则的长度上限（字符）。规则整段进系统提示词，
+// 太长会挤掉计划本身的输出空间。
+const RulesMaxLen = 500
+
+// NormalizeRuleText 把用户写的规则收成一行（折叠空白）：它要嵌进角色表的
+// 「- <role> [<kind>] —— <规则>」这一条，换行会把列表结构撑断。
+func NormalizeRuleText(s string) string {
+	return strings.Join(strings.Fields(s), " ")
+}
+
+// ParseRules 解析 --team-rule 的取值：`role:<name>=<规则文本>`。
+//
+// 只认角色：计划与类别没有自由文本规则 —— 计划的「规则」是拆解粒度
+// （--team-split / --team-split-code），类别是角色的派生。
+func ParseRules(values []string) (map[string]string, error) {
+	if len(values) == 0 {
+		return nil, nil
+	}
+	out := make(map[string]string, len(values))
+	for _, v := range values {
+		eq := strings.IndexByte(v, '=')
+		if eq <= 0 {
+			return nil, fmt.Errorf("--team-rule 取值应为 role:<角色>=<规则>，收到 %q", v)
+		}
+		role := LookupRole(v[:eq])
+		if role == nil {
+			return nil, fmt.Errorf("--team-rule 的角色 %q 不存在（可选：%s）",
+				strings.TrimSpace(v[:eq]), strings.Join(RoleNames(), " / "))
+		}
+		text := NormalizeRuleText(v[eq+1:])
+		if text == "" {
+			return nil, fmt.Errorf("--team-rule %s 的规则为空", role.Name)
+		}
+		if utf8.RuneCountInString(text) > RulesMaxLen {
+			return nil, fmt.Errorf("--team-rule %s 的规则超过 %d 字", role.Name, RulesMaxLen)
+		}
+		out[RoleKey(role.Name)] = text
+	}
+	return out, nil
+}
+
+// roleText 计划总览表格里的角色列（未设角色给 ——）。
+func roleText(name string) string {
+	if r := LookupRole(name); r != nil {
+		return r.Name
+	}
+	return "—"
+}
+
+// roleDetail 计划详情里的角色描述：`writer（把材料写成…）`；未设角色给「—」。
+func roleDetail(name string) string {
+	r := LookupRole(name)
+	if r == nil {
+		return "—"
+	}
+	if strings.TrimSpace(r.Duty) == "" {
+		return r.Name
+	}
+	return r.Name + "（" + r.Duty + "）"
+}
+
+// systemPromptFor 子任务实际使用的系统提示词：主提示词 + 角色片段。
+func systemPromptFor(opts Options, t Task) string {
+	parts := []string{strings.TrimSpace(opts.SystemPrompt)}
+	if r := LookupRole(t.Role); r != nil && strings.TrimSpace(r.SystemPrompt) != "" {
+		parts = append(parts, strings.TrimSpace(r.SystemPrompt))
+	}
+	return strings.TrimSpace(strings.Join(parts, "\n\n"))
+}
+
+// toolsFor 子任务实际使用的工具模式：角色白名单优先，否则沿用全局。
+func toolsFor(opts Options, t Task) agent.ToolsMode {
+	if r := LookupRole(t.Role); r != nil && len(r.Tools) > 0 {
+		return agent.ToolsAllowlist(r.Tools)
+	}
+	return opts.Tools
+}
+
+// permissionFor 子任务实际使用的权限档位：角色声明优先，否则沿用全局。
+func permissionFor(opts Options, t Task) agent.PermissionTier {
+	if r := LookupRole(t.Role); r != nil && r.Permission != "" {
+		return r.Permission
+	}
+	return opts.Permission
+}

package/internal/team/route.go

@@ -0,0 +1,206 @@
+package team
+
+// route.go - 类别 → 引擎/模型的路由，以及运行目录的选址。
+//
+// 两条规矩：
+//
+//  1. **显式优先**。--team-route / 客户端下发的 routes 里写了的，一律照办（引擎不存在
+//     才报错）。用户说「图像任务用 X」，这里不去猜 X 到底行不行。
+//  2. **没配就跟随主引擎**。计划阶段与五类子任务（plan / text / code / image / video / game）
+//     一致：这一类没被指定引擎时，就用主引擎 + 主模型 —— 「跟随主引擎」是默认，也是一个
+//     可改的选择（客户端「我的 → 团队模式」里每类都能单独改）。主引擎为空才返回空路由，
+//     由 execute 标失败。
+//
+// 任务的类别不是用户/模型直接写的字段，而是由角色派生（Task.EffectiveKind）：
+// 角色表是唯一作者面，路由表仍是「类别」这一级，两者用 RoleKind 对齐。
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// RouteFor 解析某个任务最终该用哪个引擎 / 模型。
+//
+// 顺序：任务里写死的 > 角色路由（role:<name>）> 类别路由（Options.Routes）> 主引擎。
+// 角色排在类别之前：角色是**更具体**的那一层（用户点名「评审都用 X」），而类别是
+// 「这类活默认派给谁」。返回的 engine 为空只发生在主引擎也为空时，调用方必须按失败处理。
+func RouteFor(t Task, opts Options) Route {
+	if e := strings.TrimSpace(t.Engine); e != "" {
+		return Route{Engine: e, Model: strings.TrimSpace(t.Model)}
+	}
+	role := LookupRole(t.Role)
+	if role != nil {
+		if r, ok := routeForRole(opts.Routes, role.Name); ok {
+			m := strings.TrimSpace(r.Model)
+			if m == "" {
+				m = strings.TrimSpace(role.Model)
+			}
+			return Route{Engine: strings.TrimSpace(r.Engine), Model: m}
+		}
+	}
+	if r, ok := opts.Routes[t.EffectiveKind()]; ok && strings.TrimSpace(r.Engine) != "" {
+		return Route{Engine: strings.TrimSpace(r.Engine), Model: strings.TrimSpace(r.Model)}
+	}
+	// 默认「跟随主引擎」：不分类别，text / image / video / game 一视同仁。
+	if opts.Engine != nil {
+		m := opts.Model
+		// 主引擎没配模型时，角色声明的默认模型才生效（不覆盖用户显式选择）。
+		if strings.TrimSpace(m) == "" && role != nil {
+			m = strings.TrimSpace(role.Model)
+		}
+		return Route{Engine: opts.Engine.Name(), Model: m}
+	}
+	return Route{}
+}
+
+// routeForRole 在路由表里找角色配置：规范键 `role:<name>` 优先，裸角色名也认
+// （客户端旧配置 / 手写 routes 里可能不带前缀）。
+func routeForRole(routes map[string]Route, name string) (Route, bool) {
+	if len(routes) == 0 {
+		return Route{}, false
+	}
+	for _, key := range []string{RoleKey(name), NormalizeRole(name)} {
+		if key == "" {
+			continue
+		}
+		if r, ok := routes[key]; ok && strings.TrimSpace(r.Engine) != "" {
+			return r, true
+		}
+	}
+	return Route{}, false
+}
+
+// PlanRoute 计划阶段该用哪个引擎 / 模型。
+//
+// 与子任务同一套语义：显式配了 plan 就用它，没配跟随主引擎 —— 计划本来就是主引擎的活。
+// 返回空引擎只发生在主引擎也为空时（Run 已提前拦掉）。
+func PlanRoute(opts Options) Route {
+	if r, ok := opts.Routes[KindPlan]; ok && strings.TrimSpace(r.Engine) != "" {
+		return Route{Engine: strings.TrimSpace(r.Engine), Model: strings.TrimSpace(r.Model)}
+	}
+	if opts.Engine != nil {
+		return Route{Engine: opts.Engine.Name(), Model: opts.Model}
+	}
+	return Route{}
+}
+
+// ValidateRoutes 校验显式配置里的引擎都真实存在。
+//
+// 在开跑前一次性报错（而不是等某个任务跑到一半才 failed）：配置错了是**配置问题**，
+// 早说一秒就少浪费一轮。
+func ValidateRoutes(routes map[string]Route) error {
+	var bad []string
+	for kind, r := range routes {
+		name := strings.TrimSpace(r.Engine)
+		if name == "" {
+			continue
+		}
+		if agent.Lookup(name) == nil {
+			bad = append(bad, fmt.Sprintf("%s→%s", kind, name))
+		}
+	}
+	if len(bad) > 0 {
+		return fmt.Errorf("未知引擎：%s（可用引擎见 magic-agent --engines）", strings.Join(bad, "、"))
+	}
+	return nil
+}
+
+// ParseRoutes 解析 --team-route 的取值：`<kind>=<engine>[/<model>]`。
+//
+// 模型名里可能有 `/`（如 `anthropic/claude-x`），所以只按**第一个** `/` 切：
+// 前段是引擎，其余全是模型名。
+func ParseRoutes(values []string) (map[string]Route, error) {
+	if len(values) == 0 {
+		return nil, nil
+	}
+	out := make(map[string]Route, len(values))
+	for _, v := range values {
+		s := strings.TrimSpace(v)
+		if s == "" {
+			continue
+		}
+		eq := strings.IndexByte(s, '=')
+		if eq <= 0 {
+			return nil, fmt.Errorf("--team-route 取值应为 <类别>=<引擎>[/<模型>]，收到 %q", v)
+		}
+		kind := normalizeRouteKind(s[:eq])
+		if kind == "" {
+			return nil, fmt.Errorf("--team-route 的类别 %q 不支持（可选：%s；角色用 role:<%s>）",
+				s[:eq], strings.Join(RouteKinds, " / "), strings.Join(RoleNames(), " / "))
+		}
+		rest := strings.TrimSpace(s[eq+1:])
+		if rest == "" {
+			return nil, fmt.Errorf("--team-route %s 缺少引擎名", kind)
+		}
+		r := Route{Engine: rest}
+		if i := strings.IndexByte(rest, '/'); i > 0 {
+			r.Engine = strings.TrimSpace(rest[:i])
+			r.Model = strings.TrimSpace(rest[i+1:])
+		}
+		out[kind] = r
+	}
+	return out, nil
+}
+
+// normalizeRouteKind 把配置里的键归一到 RouteKinds 或角色键（role:<name>）。
+//
+// plan 是**阶段**不是子任务类别，所以不走 NormalizeKind（那张近义词表只服务类别回退）；
+// 这里单独认几个写法，其余先看角色表，再交给 NormalizeKind。
+func normalizeRouteKind(s string) string {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case KindPlan, "计划", "计划任务", "planner", "planning":
+		return KindPlan
+	}
+	if key := RoleKey(s); key != "" {
+		return key
+	}
+	return NormalizeKind(s)
+}
+
+// chooseRunDir 决定运行目录（团队模式的全部落盘都在它下面）。
+//
+// 选址规则（与用户 2026-10-21 的确认一致）：
+//
+//	选了工作空间 → <ws>/.magic/team/<run_id>
+//	默认空间     → ~/.magic-agent/team/<run_id>
+//
+// 为什么不一律丢 cwd：默认空间下 cwd 是 core 进程的启动目录（可能是任何地方），
+// 往里写团队产物等于污染用户当前的项目。落在 ~/.magic-agent 下有个固定位置可找，
+// 而显式选了空间时，用户本来就期望产物在那个空间里。
+func chooseRunDir(opts Options) (string, error) {
+	if base := strings.TrimSpace(opts.BaseDir); base != "" {
+		return filepath.Join(base, sanitizeID(opts.RunID)), nil
+	}
+	if ws := strings.TrimSpace(opts.Workspace); ws != "" {
+		return filepath.Join(ws, ".magic", "team", sanitizeID(opts.RunID)), nil
+	}
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return "", fmt.Errorf("team: 无法确定运行目录（既没有工作空间，也读不到 HOME）")
+	}
+	return filepath.Join(home, ".magic-agent", "team", sanitizeID(opts.RunID)), nil
+}
+
+// sanitizeID 把 id 收成安全的目录名（run_id 里有 `-` 与 base36 字符，正常不会被改）。
+func sanitizeID(s string) string {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return "run"
+	}
+	var b strings.Builder
+	for _, r := range s {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9':
+			b.WriteRune(r)
+		case r == '-' || r == '_' || r == '.':
+			b.WriteRune(r)
+		default:
+			b.WriteByte('_')
+		}
+	}
+	return b.String()
+}