magic-agent 1.0.49 → 1.0.109

package/internal/client/service_test.go

@@ -64,7 +64,7 @@ echo '{"v":1,"seq":4,"type":"result","text":"hi"}'
 	return path
 }
 
-const goodContract = `{"contractVersion":1,"features":["feature.session.events","feature.session.control"],"engines":[{"engine":"claude","ok":true,"capabilities":["session.stream"]}]}`
+const goodContract = `{"contractVersion":2,"features":["feature.session.events","feature.session.control"],"engines":[{"engine":"claude","ok":true,"capabilities":["session.stream"]}]}`
 
 func newTestService(t *testing.T, core string) *Service {
 	t.Helper()
@@ -90,7 +90,7 @@ func TestNewRejectsContractMismatch(t *testing.T) {
 	})
 
 	t.Run("缺通道能力", func(t *testing.T) {
-		core := fakeCore(t, `{"contractVersion":1,"features":["feature.session.events"],"engines":[]}`)
+		core := fakeCore(t, `{"contractVersion":2,"features":["feature.session.events"],"engines":[]}`)
 		_, err := New(Options{MagicAgent: core, Profile: DefaultProfile()})
 		if err == nil {
 			t.Fatal("缺 control 能力应当报错")
@@ -125,6 +125,51 @@ func TestAuthRequired(t *testing.T) {
 	}
 }
 
+/*
+TestHealthCarriesVersion `/desk/health.version` 必须是 core 的版本号：
+
+	移动端「我的」页靠它显示「当前连着的 magic-agent 是哪一版」。老 core 没有该字段时
+	如实给空串（界面显示「—」），不编假版本。
+*/
+func TestHealthCarriesVersion(t *testing.T) {
+	cases := []struct {
+		name     string
+		contract string
+		want     string
+	}{
+		{
+			name:     "新版 core",
+			contract: `{"contractVersion":2,"version":"1.0.103","features":["feature.session.events","feature.session.control"],"engines":[]}`,
+			want:     "1.0.103",
+		},
+		{
+			name:     "老 core 没有 version",
+			contract: `{"contractVersion":2,"features":["feature.session.events","feature.session.control"],"engines":[]}`,
+			want:     "",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			svc := newTestService(t, fakeCore(t, tc.contract))
+			req := httptest.NewRequest(http.MethodGet, "/desk/health?token=tok", nil)
+			rec := httptest.NewRecorder()
+			svc.Handler().ServeHTTP(rec, req)
+			if rec.Code != http.StatusOK {
+				t.Fatalf("health 状态码 = %d want 200（body: %s）", rec.Code, rec.Body.String())
+			}
+			var got struct {
+				Version string `json:"version"`
+			}
+			if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+				t.Fatalf("解析 health 失败: %v（%s）", err, rec.Body.String())
+			}
+			if got.Version != tc.want {
+				t.Errorf("health.version = %q want %q", got.Version, tc.want)
+			}
+		})
+	}
+}
+
 func TestProfileGateEngine(t *testing.T) {
 	prof := DefaultProfile()
 	prof.Engines = []string{"claude"}

package/internal/client/session_events_test.go

@@ -1,14 +1,20 @@
 package client
 
 import (
+	"bufio"
+	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
+
+	"github.com/darren/magic-agent/internal/session"
 )
 
 // 增量续读端点 `GET /desk/session/{id}/events?after=<seq>` 的边界。
@@ -186,6 +192,320 @@ func TestHandleSessionEvents(t *testing.T) {
 	})
 }
 
+// follow 端点 `GET /desk/session/{id}/follow`（SSE 持续尾随）的行为钉死。
+//
+// 这条端点的存在理由就是「跨进程看进度」：不靠本插件进程的 asks 内存，
+// 只读 core 落的 `~/.magic-agent/sessions/<id>.jsonl`。所以这一组测试也全部
+// 只碰磁盘文件（模拟「另一个进程在写」），不经过任何 ask 通道。
+//
+// ⚠️ SSE 是长连接，`doGET` 会读完整个 body 才能返回（永远等不到），
+// 这里必须自己拿 `http.Response.Body` 逐帧读。
+func TestHandleSessionFollow(t *testing.T) {
+	home := t.TempDir()
+	dir := filepath.Join(home, ".magic-agent", "sessions")
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("HOME", home)
+	t.Setenv(session.EnvDir, dir)
+
+	writeLog := func(t *testing.T, id string, lines ...string) {
+		t.Helper()
+		if err := os.WriteFile(filepath.Join(dir, id+".jsonl"), []byte(strings.Join(lines, "\n")+"\n"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	appendLog := func(t *testing.T, name, line string) {
+		t.Helper()
+		f, err := os.OpenFile(filepath.Join(dir, name), os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600)
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer f.Close()
+		if _, err := f.WriteString(line + "\n"); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	svc := newTestService(t, fakeCore(t, goodContract))
+	srv := httptest.NewServer(svc.Handler())
+	defer srv.Close()
+
+	followURL := func(id, query string) string {
+		return srv.URL + "/desk/session/" + id + "/follow?token=tok" + query
+	}
+
+	t.Run("首屏全量 → 增量 → 终态收尾", func(t *testing.T) {
+		const id = "sess-follow"
+		writeLog(t, id,
+			`{"seq":1,"kind":"user","text":"问题","session_id":"`+id+`"}`,
+			`{"seq":2,"kind":"text","text":"答一","session_id":"`+id+`"}`,
+		)
+		st := openFollow(t, followURL(id, ""))
+		defer st.stop()
+
+		// 首屏：先 open 帧（告诉客户端起始游标），紧接着把已有历史推完。
+		if f := st.next(); f.event != "open" {
+			t.Fatalf("首帧应是 open，实得 %q（data=%s）", f.event, f.data)
+		} else if m := frameData(t, f); m["session"] != id || m["after"] != float64(0) {
+			t.Fatalf("open 帧内容不对：%v", m)
+		}
+		if seq := frameSeq(t, st.next()); seq != 1 {
+			t.Fatalf("首屏首条期望 seq=1，实得 %d", seq)
+		}
+		if seq := frameSeq(t, st.next()); seq != 2 {
+			t.Fatalf("首屏第二条期望 seq=2，实得 %d", seq)
+		}
+
+		// 增量：模拟另一个进程在追写（PC 壳直连 core 的真实形态）。
+		appendLog(t, id+".jsonl", `{"seq":3,"kind":"text","text":"答二","session_id":"`+id+`"}`)
+		st.until("seq=3 增量", func(f followFrame) bool {
+			return f.event == "" && frameSeq(t, f) == 3
+		})
+
+		// 终态：turn_end 到了以后还要等 grace（把紧随其后的收尾行补齐），
+		// 然后必须给一帧 end —— 客户端靠它停掉「同步进度」的定时器。
+		appendLog(t, id+".jsonl", `{"seq":4,"kind":"turn_end","text":"完成","session_id":"`+id+`"}`)
+		end := st.until("end 帧", func(f followFrame) bool { return f.event == "end" })
+		m := frameData(t, end)
+		if m["reason"] != "terminal" {
+			t.Fatalf("end.reason 期望 terminal，实得 %v", m["reason"])
+		}
+		if m["after"] != float64(4) {
+			t.Fatalf("end.after 期望 4，实得 %v", m["after"])
+		}
+	})
+
+	t.Run("after 排他", func(t *testing.T) {
+		const id = "sess-follow-after"
+		writeLog(t, id,
+			`{"seq":1,"kind":"user","text":"一","session_id":"`+id+`"}`,
+			`{"seq":2,"kind":"text","text":"二","session_id":"`+id+`"}`,
+			`{"seq":3,"kind":"text","text":"三","session_id":"`+id+`"}`,
+		)
+		st := openFollow(t, followURL(id, "&after=1"))
+		defer st.stop()
+
+		if f := st.next(); f.event != "open" {
+			t.Fatalf("首帧应是 open，实得 %q", f.event)
+		} else if m := frameData(t, f); m["after"] != float64(1) {
+			t.Fatalf("open.after 应回显 1，实得 %v", m["after"])
+		}
+		// 排他：不能把 seq=1 再回一遍（客户端续读不该依赖去重）。
+		if seq := frameSeq(t, st.next()); seq != 2 {
+			t.Fatalf("after=1 后首条期望 seq=2，实得 %d", seq)
+		}
+		if seq := frameSeq(t, st.next()); seq != 3 {
+			t.Fatalf("第二条期望 seq=3，实得 %d", seq)
+		}
+	})
+
+	t.Run("游标超前 = snapshot 帧", func(t *testing.T) {
+		const id = "sess-follow-ahead"
+		writeLog(t, id,
+			`{"seq":1,"kind":"user","text":"一","session_id":"`+id+`"}`,
+			`{"seq":2,"kind":"text","text":"二","session_id":"`+id+`"}`,
+		)
+		st := openFollow(t, followURL(id, "&after=99"))
+		defer st.stop()
+
+		if f := st.next(); f.event != "open" {
+			t.Fatalf("首帧应是 open，实得 %q", f.event)
+		}
+		// 游标比磁盘还新（日志被重置 / 游标串了会话）⇒ 明说 snapshot，让客户端重拉全量。
+		snap := st.until("snapshot 帧", func(f followFrame) bool { return f.event == "snapshot" })
+		if m := frameData(t, snap); m["lastSeq"] != float64(2) {
+			t.Fatalf("snapshot.lastSeq 期望 2，实得 %v", m["lastSeq"])
+		}
+	})
+
+	t.Run("lean=1 裁掉 snapshot 字段", func(t *testing.T) {
+		const id = "sess-follow-lean"
+		writeLog(t, id,
+			`{"seq":1,"kind":"text","text":"好","snapshot":"好","session_id":"`+id+`"}`,
+		)
+		st := openFollow(t, followURL(id, "&lean=1"))
+		defer st.stop()
+
+		if f := st.next(); f.event != "open" {
+			t.Fatalf("首帧应是 open，实得 %q", f.event)
+		}
+		ev := st.until("lean 事件", func(f followFrame) bool { return f.event == "" && frameSeq(t, f) == 1 })
+		if _, ok := frameData(t, ev)["snapshot"]; ok {
+			t.Fatalf("lean=1 时不该带 snapshot：%s", ev.data)
+		}
+	})
+
+	// 「刚发起就看进度」的关键形态：core 先写登记表、后开日志文件。
+	// 此时不能 404（会让客户端以为会话不存在），要等到文件出现；
+	// 文件在进行中还会被改名（<run_id>.jsonl → <session_id>.jsonl），
+	// 每轮都得重新翻译，否则进度就停在改名那一刻。
+	t.Run("登记表有日志未建 = 放行等待，改名后继续", func(t *testing.T) {
+		const rid, sid = "run-pending", "sess-renamed"
+		now := time.Now()
+		rec := session.Record{
+			RunID: rid, SessionID: sid, Engine: "claude", State: session.StateRunning,
+			StartedAt: now, UpdatedAt: now,
+		}
+		body, _ := json.Marshal(rec)
+		if err := os.WriteFile(filepath.Join(dir, rid+".json"), body, 0o600); err != nil {
+			t.Fatal(err)
+		}
+		st := openFollow(t, followURL(rid, ""))
+		defer st.stop()
+
+		if f := st.next(); f.event != "open" {
+			t.Fatalf("首帧应是 open，实得 %q（data=%s）", f.event, f.data)
+		} else if m := frameData(t, f); m["session"] != rid {
+			t.Fatalf("open.session 期望 %s，实得 %v", rid, m["session"])
+		}
+		// 日志文件此刻还不存在 —— 连接必须还活着。
+		appendLog(t, rid+".jsonl", `{"seq":1,"kind":"user","text":"开始","session_id":"`+sid+`"}`)
+		st.until("登场后的 seq=1", func(f followFrame) bool {
+			return f.event == "" && frameSeq(t, f) == 1
+		})
+
+		// 进行中改名：之后的新事件只在 <session_id>.jsonl 里。
+		if err := os.Rename(filepath.Join(dir, rid+".jsonl"), filepath.Join(dir, sid+".jsonl")); err != nil {
+			t.Fatal(err)
+		}
+		appendLog(t, sid+".jsonl", `{"seq":2,"kind":"text","text":"继续","session_id":"`+sid+`"}`)
+		st.until("改名后的 seq=2", func(f followFrame) bool {
+			return f.event == "" && frameSeq(t, f) == 2
+		})
+	})
+
+	t.Run("不存在会话 = 404", func(t *testing.T) {
+		resp := doGET(t, followURL("no-such-session", ""), true)
+		if resp.statusCode != http.StatusNotFound {
+			t.Fatalf("期望 404，实得 %d（%s）", resp.statusCode, resp.body)
+		}
+	})
+
+	t.Run("after 非法 = 400", func(t *testing.T) {
+		const id = "sess-follow-bad-after"
+		writeLog(t, id, `{"seq":1,"kind":"user","text":"一","session_id":"`+id+`"}`)
+		for _, bad := range []string{"abc", "-1", "1.5"} {
+			resp := doGET(t, followURL(id, "&after="+bad), true)
+			if resp.statusCode != http.StatusBadRequest {
+				t.Fatalf("after=%q 期望 400，实得 %d", bad, resp.statusCode)
+			}
+		}
+	})
+
+	t.Run("缺令牌 = 401", func(t *testing.T) {
+		resp := doGET(t, srv.URL+"/desk/session/sess-follow/follow", false)
+		if resp.statusCode != http.StatusUnauthorized {
+			t.Fatalf("期望 401，实得 %d", resp.statusCode)
+		}
+	})
+}
+
+// followFrame 一帧 SSE：event 为空表示纯 data 帧（增量事件），ping 表示心跳注释。
+type followFrame struct {
+	event string
+	data  string
+	ping  bool
+}
+
+type followStream struct {
+	t    *testing.T
+	br   *bufio.Reader
+	stop func()
+}
+
+// openFollow 建一条 SSE 连接。超时只兜「等不到的帧」，正常路径靠 end / stop 收尾。
+func openFollow(t *testing.T, url string) *followStream {
+	t.Helper()
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		cancel()
+		t.Fatal(err)
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		cancel()
+		t.Fatalf("打开 follow 失败：%v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		resp.Body.Close()
+		cancel()
+		t.Fatalf("follow 期望 200，实得 %d（%s）", resp.StatusCode, body)
+	}
+	return &followStream{
+		t:  t,
+		br: bufio.NewReader(resp.Body),
+		stop: func() {
+			resp.Body.Close()
+			cancel()
+		},
+	}
+}
+
+func (s *followStream) next() followFrame {
+	s.t.Helper()
+	var f followFrame
+	var has bool
+	for {
+		line, err := s.br.ReadString('\n')
+		if err != nil {
+			s.t.Fatalf("读 SSE 失败：%v", err)
+		}
+		line = strings.TrimRight(line, "\r\n")
+		if line == "" {
+			if !has {
+				continue
+			}
+			return f
+		}
+		has = true
+		switch {
+		case strings.HasPrefix(line, "event:"):
+			f.event = strings.TrimSpace(strings.TrimPrefix(line, "event:"))
+		case strings.HasPrefix(line, "data:"):
+			f.data = strings.TrimSpace(strings.TrimPrefix(line, "data:"))
+		case strings.HasPrefix(line, ":"):
+			f.ping = true
+		}
+	}
+}
+
+// until 一帧帧读到 pred 成立（跳过心跳帧）。
+func (s *followStream) until(what string, pred func(followFrame) bool) followFrame {
+	s.t.Helper()
+	for {
+		f := s.next()
+		if f.ping {
+			continue
+		}
+		if pred(f) {
+			return f
+		}
+	}
+}
+
+func frameData(t *testing.T, f followFrame) map[string]any {
+	t.Helper()
+	var m map[string]any
+	if err := json.Unmarshal([]byte(f.data), &m); err != nil {
+		t.Fatalf("帧不是 JSON：%v（%s）", err, f.data)
+	}
+	return m
+}
+
+// frameSeq 增量帧的 seq；不像事件帧（open/snapshot/end）时返回 0。
+func frameSeq(t *testing.T, f followFrame) uint64 {
+	t.Helper()
+	if f.event != "" {
+		return 0
+	}
+	m := frameData(t, f)
+	seq, _ := m["seq"].(float64)
+	return uint64(seq)
+}
+
 // TestTruncRunes 钉住按字符（不是字节）截断，且不切坏多字节字符。
 func TestTruncRunes(t *testing.T) {
 	cases := []struct {

package/internal/client/team_flags.go

@@ -0,0 +1,204 @@
+package client
+
+// team_flags.go - 把 POST /desk/ask 的 team 字段翻成 core 的 --team-* flags。
+//
+// 为什么单独一个文件：这段是**纯翻译 + 预校验**，与 HTTP 无关，可以单独测
+// （service_test.go 里的团队用例直接调它，不必起服务、不必 spawn core）。
+//
+// 分工（改这里之前先看 internal/team/route.go）：
+//   - 插件负责：字段名 → flag 名的映射、类别名合法性、引擎白名单。
+//   - core 负责：类别 → 引擎的**最终裁决**（写死的任务级路由 > 配置 > 主引擎回落）。
+// 两边都判一遍类别名，是因为报错要发生在**请求那一刻**（400 + 中文原因），
+// 而不是等 core 跑完计划才以 exit 2 失败 —— 那时用户已经等了几十秒。
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// teamKinds 与 internal/team.RouteKinds 同源（这里不 import team 是为了让插件不必
+// 依赖 core 的内部包 —— 插件走的是 core 的**命令行契约**，不是 Go API）。
+// plan = 计划阶段（谁来拆任务），其余五类是子任务类别。
+var teamKinds = []string{"plan", "text", "code", "image", "video", "game"}
+
+// FeatureSessionTeam core 的团队模式能力位（与 internal/agent.FeatureSessionTeam 同值）。
+//
+// 这是**可选**特性：老 core 没有它，插件照常工作，只是拒绝带 team 的请求
+// （见 handleAsk）—— 不塞进 requiredFeatures，否则升级插件就得同步升 core。
+const FeatureSessionTeam = "feature.session.team"
+
+// teamFlags 把请求体翻成 core 参数。err 非空时调用方应回 400。
+//
+// roles 是 core `--contract` 上报的角色名清单（s.teamRoleNames()）。空 = 老 core，
+// 此时 role:<name> 只做格式校验，名字交给 core 裁决 —— 插件不替 core 维护角色表。
+func teamFlags(t *teamRequest, profile Profile, roles []string) ([]string, error) {
+	if t == nil {
+		return nil, nil
+	}
+	args := []string{"--team"}
+	if t.PlanOnly {
+		args = append(args, "--team-plan-only")
+	}
+	if t.Parallel > 0 {
+		args = append(args, "--team-parallel", fmt.Sprint(t.Parallel))
+	}
+	if s := strings.TrimSpace(t.TaskTimeout); s != "" {
+		args = append(args, "--team-task-timeout", s)
+	}
+	if s := strings.TrimSpace(t.Split); s != "" {
+		split, err := normalizeTeamSplit(s)
+		if err != nil {
+			return nil, err
+		}
+		args = append(args, "--team-split", split)
+	}
+	if t.SplitCode != nil && *t.SplitCode {
+		args = append(args, "--team-split-code")
+	}
+	if t.Adaptive != nil && !*t.Adaptive {
+		args = append(args, "--team-adaptive=false")
+	}
+	// 角色规则（「这类任务适合什么」）：按角色名排序，理由同路由 —— 同样的请求
+	// 必须产生同样的命令行。空文本 = 用 core 内置的描述，不传。
+	ruleKeys := make([]string, 0, len(t.Rules))
+	for k := range t.Rules {
+		ruleKeys = append(ruleKeys, k)
+	}
+	sort.Strings(ruleKeys)
+	for _, rawKey := range ruleKeys {
+		key, err := normalizeTeamRuleKey(rawKey, roles)
+		if err != nil {
+			return nil, err
+		}
+		text := strings.Join(strings.Fields(t.Rules[rawKey]), " ")
+		if text == "" {
+			continue
+		}
+		args = append(args, "--team-rule", key+"="+text)
+	}
+	// 路由按类别排序输出：map 遍历无序，不排序的话同样的请求会产生不同的命令行，
+	// 排障时（`ps` 看参数 / 日志比对）会误以为请求变了。
+	kinds := make([]string, 0, len(t.Routes))
+	for k := range t.Routes {
+		kinds = append(kinds, k)
+	}
+	sort.Strings(kinds)
+	for _, rawKind := range kinds {
+		kind, err := normalizeTeamRouteKey(rawKind, roles)
+		if err != nil {
+			return nil, err
+		}
+		r := t.Routes[rawKind]
+		engine := strings.TrimSpace(r.Engine)
+		model := strings.TrimSpace(r.Model)
+		if engine == "" {
+			if model != "" {
+				// 只给模型不给引擎：语义不明（模型属于某一家引擎），不猜。
+				return nil, fmt.Errorf("team.routes.%s 给了 model 但没给 engine", kind)
+			}
+			continue // 整条空 = 该类跟随主引擎
+		}
+		if !profile.AllowsEngine(engine) {
+			return nil, fmt.Errorf("team.routes.%s 的引擎 %q 不在 profile 白名单内", kind, engine)
+		}
+		spec := kind + "=" + engine
+		if model != "" {
+			spec += "/" + model
+		}
+		args = append(args, "--team-route", spec)
+	}
+	return args, nil
+}
+
+// normalizeTeamRuleKey 规则键归一：只认角色（`role:<name>` 或裸角色名）。
+//
+// 与路由键不同，这里**不**接受类别键 —— 类别没有自由文本规则（计划是拆解粒度，
+// 其余类别由角色派生）。老 core（roles 为空）只做格式校验，名字交给 core 裁决。
+func normalizeTeamRuleKey(raw string, roles []string) (string, error) {
+	name := strings.TrimSpace(strings.TrimPrefix(strings.ToLower(strings.TrimSpace(raw)), "role:"))
+	if name == "" {
+		return "", fmt.Errorf("team.rules 里有空角色键 %q（应写成 role:<角色名>）", raw)
+	}
+	if len(roles) > 0 && !containsStr(roles, name) {
+		return "", fmt.Errorf("team.rules 里有未知角色 %q（可选 %s）", raw, strings.Join(roles, " | "))
+	}
+	return "role:" + name, nil
+}
+
+// normalizeTeamSplit 拆解粒度归一（与 core 的 team.NormalizeSplit 同口径）。
+//
+// 插件也判一遍：粒度写错要在请求那一刻回 400，而不是等 core 跑到计划阶段才失败。
+func normalizeTeamSplit(raw string) (string, error) {
+	switch s := strings.ToLower(strings.TrimSpace(raw)); s {
+	case teamSplitCoarse, teamSplitStandard, teamSplitFine:
+		return s, nil
+	default:
+		return "", fmt.Errorf("team.split 取值 %q 不合法（可选 %s | %s | %s）",
+			raw, teamSplitCoarse, teamSplitStandard, teamSplitFine)
+	}
+}
+
+const (
+	teamSplitCoarse   = "coarse"
+	teamSplitStandard = "standard"
+	teamSplitFine     = "fine"
+)
+
+// validTeamKind 类别名是否合法（大小写不敏感，调用方已归一）。
+func validTeamKind(kind string) bool {
+	for _, k := range teamKinds {
+		if k == kind {
+			return true
+		}
+	}
+	return false
+}
+
+// normalizeTeamRouteKey 路由键归一成 core 认的写法。
+//
+// 两类键：
+//   - 类别（plan/text/code/image/video/game）→ 原样返回；
+//   - 角色 → "role:<name>"（core 的 --team-route 用这个前缀）。
+//
+// 裸角色名也认（core 的 ParseRoutes 同口径），但**只在它不是类别时** ——
+// 否则将来哪天真有角色叫 code，会跟类别键抢。
+func normalizeTeamRouteKey(raw string, roles []string) (string, error) {
+	key := strings.ToLower(strings.TrimSpace(raw))
+	if name, ok := strings.CutPrefix(key, "role:"); ok {
+		name = strings.TrimSpace(name)
+		if name == "" {
+			return "", fmt.Errorf("team.routes 里有空角色键 %q（应写成 role:<角色名>）", raw)
+		}
+		if len(roles) > 0 && !containsStr(roles, name) {
+			return "", fmt.Errorf("team.routes 里有未知角色 %q（可选 %s）",
+				raw, strings.Join(roles, " | "))
+		}
+		return "role:" + name, nil
+	}
+	if validTeamKind(key) {
+		return key, nil
+	}
+	if len(roles) > 0 && containsStr(roles, key) {
+		return "role:" + key, nil
+	}
+	return "", fmt.Errorf("team.routes 里有未知类别 %q（可选 %s；按角色指定用 role:<%s>）",
+		raw, strings.Join(teamKinds, " | "), roleHint(roles))
+}
+
+// roleHint 错误文案里的角色示例：有清单就列出来，没有就举个通用例子。
+func roleHint(roles []string) string {
+	if len(roles) == 0 {
+		return "角色名"
+	}
+	return strings.Join(roles, "|")
+}
+
+func containsStr(list []string, s string) bool {
+	for _, v := range list {
+		if v == s {
+			return true
+		}
+	}
+	return false
+}