magic-agent 1.0.49 → 1.0.108

package/internal/client/team_flags_test.go

@@ -0,0 +1,254 @@
+package client
+
+// team_flags_test.go - 插件侧团队参数的翻译与预校验。
+//
+// 这里只测「字段 → flag」与「请求那一刻就该拒的输入」。路由的最终裁决在
+// core（internal/team/route.go 有自己的测试），两边不重复覆盖同一件事。
+
+import (
+	"strings"
+	"testing"
+)
+
+// testRoles core 正常上报的角色清单（顺序同 internal/team 的内置表）。
+var testRoles = []string{"writer", "researcher", "reviewer", "coder", "designer", "director", "builder"}
+
+func TestTeamFlagsMinimal(t *testing.T) {
+	args, err := teamFlags(&teamRequest{}, Profile{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	want := []string{"--team"}
+	if strings.Join(args, " ") != strings.Join(want, " ") {
+		t.Fatalf("args = %v, want %v", args, want)
+	}
+}
+
+func TestTeamFlagsAllOptions(t *testing.T) {
+	args, err := teamFlags(&teamRequest{
+		PlanOnly:    true,
+		Parallel:    2,
+		TaskTimeout: "5m",
+		Routes: map[string]teamRoute{
+			"image": {Engine: "llm", Model: "hunyuan-image-3.0"},
+			"text":  {Engine: "claude"},
+		},
+	}, Profile{}, testRoles)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	got := strings.Join(args, " ")
+	for _, want := range []string{
+		"--team",
+		"--team-plan-only",
+		"--team-parallel 2",
+		"--team-task-timeout 5m",
+		// 路由按类别名排序输出（map 遍历无序，排序后命令行才可复现）。
+		"--team-route image=llm/hunyuan-image-3.0 --team-route text=claude",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("args = %q, 缺少 %q", got, want)
+		}
+	}
+}
+
+// 拆解规则三项：粒度归一后透传，两个布尔按 core 默认值**只在需要时**出现。
+func TestTeamFlagsSplit(t *testing.T) {
+	yes, no := true, false
+	cases := []struct {
+		name string
+		req  teamRequest
+		want []string
+		deny []string
+	}{
+		{"粒度归一", teamRequest{Split: "FINE"}, []string{"--team-split fine"}, nil},
+		{"简单代码也拆", teamRequest{SplitCode: &yes}, []string{"--team-split-code"}, nil},
+		{"默认值不传", teamRequest{SplitCode: &no, Adaptive: &yes}, nil,
+			[]string{"--team-split-code", "--team-adaptive"}},
+		{"关掉自动补任务", teamRequest{Adaptive: &no}, []string{"--team-adaptive=false"}, nil},
+	}
+	for _, c := range cases {
+		args, err := teamFlags(&c.req, Profile{}, testRoles)
+		if err != nil {
+			t.Fatalf("%s: unexpected err: %v", c.name, err)
+		}
+		got := strings.Join(args, " ")
+		for _, w := range c.want {
+			if !strings.Contains(got, w) {
+				t.Fatalf("%s: args = %q, 缺少 %q", c.name, got, w)
+			}
+		}
+		for _, d := range c.deny {
+			if strings.Contains(got, d) {
+				t.Fatalf("%s: args = %q, 不该有 %q", c.name, got, d)
+			}
+		}
+	}
+}
+
+func TestTeamFlagsRejectsBadSplit(t *testing.T) {
+	if _, err := teamFlags(&teamRequest{Split: "tiny"}, Profile{}, testRoles); err == nil {
+		t.Fatal("非法粒度应在请求那一刻就报错")
+	}
+}
+
+// 角色规则：键归一成 role:<name>，空白折叠，按角色名排序（同样的请求 → 同样的命令行）。
+func TestTeamFlagsRules(t *testing.T) {
+	args, err := teamFlags(&teamRequest{Rules: map[string]string{
+		"writer":     "  把  材料写成文档 ",
+		"role:coder": "只拆多文件、要构建或测试的改动",
+		"reviewer":   "   ",
+	}}, Profile{}, testRoles)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	got := strings.Join(args, " ")
+	for _, want := range []string{
+		"--team-rule role:coder=只拆多文件、要构建或测试的改动",
+		"--team-rule role:writer=把 材料写成文档",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("args = %q, 缺少 %q", got, want)
+		}
+	}
+	if strings.Contains(got, "role:reviewer") {
+		t.Fatalf("空规则不该传：%q", got)
+	}
+	if strings.Index(got, "role:coder") > strings.Index(got, "role:writer") {
+		t.Fatalf("规则应按角色名排序：%q", got)
+	}
+}
+
+func TestTeamFlagsRejectsBadRuleKey(t *testing.T) {
+	for _, key := range []string{"image", "role:", "role:nobody"} {
+		if _, err := teamFlags(&teamRequest{Rules: map[string]string{key: "x"}}, Profile{}, testRoles); err == nil {
+			t.Fatalf("规则键 %q 应被拒绝（只认已知角色）", key)
+		}
+	}
+}
+
+func TestTeamFlagsSkipsEmptyRoute(t *testing.T) {
+	// 整条空 = 该类跟随主引擎，不该产生 --team-route（否则 core 会当成
+	// 「显式指定了空引擎」）。
+	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"image": {}}}, Profile{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if strings.Contains(strings.Join(args, " "), "--team-route") {
+		t.Fatalf("空路由不该下发 --team-route：%v", args)
+	}
+}
+
+func TestTeamFlagsRejectsModelWithoutEngine(t *testing.T) {
+	_, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"video": {Model: "kling-video-v3"}}}, Profile{}, nil)
+	if err == nil || !strings.Contains(err.Error(), "没给 engine") {
+		t.Fatalf("err = %v, want 提到「没给 engine」", err)
+	}
+}
+
+func TestTeamFlagsAcceptsPlanRoute(t *testing.T) {
+	// plan = 计划阶段（谁来拆任务），与五类子任务一样可以单独指定引擎。
+	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"plan": {Engine: "claude"}}}, Profile{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if !strings.Contains(strings.Join(args, " "), "--team-route plan=claude") {
+		t.Fatalf("plan 路由没下发：%v", args)
+	}
+}
+
+func TestTeamFlagsAcceptsCodeRoute(t *testing.T) {
+	// code 类子任务必须能过插件白名单，否则客户端配了代码引擎会被 400。
+	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"code": {Engine: "claude", Model: "sonnet"}}}, Profile{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if !strings.Contains(strings.Join(args, " "), "--team-route code=claude/sonnet") {
+		t.Fatalf("code 路由没下发：%v", args)
+	}
+}
+
+func TestTeamFlagsRejectsUnknownKind(t *testing.T) {
+	_, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"audio": {Engine: "llm"}}}, Profile{}, testRoles)
+	if err == nil || !strings.Contains(err.Error(), "未知类别") {
+		t.Fatalf("err = %v, want 「未知类别」", err)
+	}
+}
+
+func TestTeamFlagsKindCaseInsensitive(t *testing.T) {
+	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"IMAGE": {Engine: "llm"}}}, Profile{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if !strings.Contains(strings.Join(args, " "), "image=llm") {
+		t.Fatalf("类别应归一成小写：%v", args)
+	}
+}
+
+func TestTeamFlagsRejectsEngineOutsideProfile(t *testing.T) {
+	_, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"image": {Engine: "llm"}}},
+		Profile{Engines: []string{"claude"}}, nil)
+	if err == nil || !strings.Contains(err.Error(), "白名单") {
+		t.Fatalf("err = %v, want 「白名单」", err)
+	}
+}
+
+func TestTeamFlagsAcceptsRoleRoute(t *testing.T) {
+	// 角色级路由：客户端下发 role:<name>，插件必须原样翻成 --team-route。
+	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{
+		"role:writer": {Engine: "claude", Model: "sonnet"},
+		"role:Coder":  {Engine: "codex"},
+	}}, Profile{}, testRoles)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	got := strings.Join(args, " ")
+	for _, want := range []string{
+		"--team-route role:writer=claude/sonnet",
+		"--team-route role:coder=codex",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("args = %q, 缺少 %q", got, want)
+		}
+	}
+}
+
+func TestTeamFlagsAcceptsBareRoleName(t *testing.T) {
+	// 裸角色名与 core 的 ParseRoutes 同口径（只能在不是类别时才认）。
+	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"writer": {Engine: "claude"}}}, Profile{}, testRoles)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if !strings.Contains(strings.Join(args, " "), "--team-route role:writer=claude") {
+		t.Fatalf("裸角色名没归一成 role: 前缀：%v", args)
+	}
+}
+
+func TestTeamFlagsRejectsUnknownRole(t *testing.T) {
+	_, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"role:nobody": {Engine: "claude"}}},
+		Profile{}, testRoles)
+	if err == nil || !strings.Contains(err.Error(), "未知角色") {
+		t.Fatalf("err = %v, want 「未知角色」", err)
+	}
+}
+
+func TestTeamFlagsRoleWithoutCatalogAcceptsAnyName(t *testing.T) {
+	// 老 core 没有 teamRoles 清单：插件只做格式校验，名字交给 core 裁决
+	// （否则升级插件就得同步升 core）。
+	args, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"role:whatever": {Engine: "claude"}}},
+		Profile{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if !strings.Contains(strings.Join(args, " "), "--team-route role:whatever=claude") {
+		t.Fatalf("role 路由没下发：%v", args)
+	}
+}
+
+func TestTeamFlagsRejectsEmptyRoleName(t *testing.T) {
+	_, err := teamFlags(&teamRequest{Routes: map[string]teamRoute{"role:": {Engine: "claude"}}},
+		Profile{}, testRoles)
+	if err == nil || !strings.Contains(err.Error(), "空角色键") {
+		t.Fatalf("err = %v, want 「空角色键」", err)
+	}
+}

package/internal/requirements/bootstrap.go

@@ -0,0 +1,423 @@
+package requirements
+
+// bootstrap.go - 首次「初始化」：按工作区目录反推一版需求基线。
+//
+// 为什么需要它（2026-10-22 用户）：
+//
+//	「整理需要判断是否有初始化过；没有就按空间目录重新生成需求，否则只处理上次
+//	 整理好的新会话。」
+//
+// 业务项目（magic-test desktop/requirements.cjs 的 bootstrapWorkspace）已经验证过这条路：
+// 新建工作区时用**带工具**的 agent 扫目录、读代码，把「已经实现了什么」反推成功能点基线；
+// 之后的对话只做增量补充。本包把它收进 core，但**触发时机不同**：
+//
+//   - magic-test 在工作区创建时后台自动跑；
+//   - 这里工作区是「会话/目录」隐式形成的，没有创建事件，所以由用户点「整理」时判断：
+//     state.BootstrapAt == 0 → 跑一次目录基线；否则只消费上次游标之后的新会话。
+//     自动归纳（防抖 / 每日兜底）不会触发初始化 —— 它可能每轮都跑，不能悄悄花几分钟读代码。
+//
+// 两个必须坚持的口径：
+//
+//	① 反推必须**读代码** → 只能用带工具、且能指定工作目录的引擎。归纳默认的 llm 引擎
+//	   没有文件系统语义，拿它反推只会得到一段凭空编的功能清单。
+//	② 产出是**需求**（用户视角），不是技术说明。prompt 里的强制规则与 magic-test 同一套：
+//	   不写语言/框架/库/API/参数/文件格式，判据是「用户能不能感知到」。
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// DefaultBootstrapTimeout 首次初始化（带工具的 agent 读目录）的单次上限。
+//
+// 与归纳的 240s 分开：读代码 + 组织 JSON 是分钟级长任务（magic-test 实测几分钟）。
+// 客户端手动整理的总超时是 10 分钟，这里给 9 分钟，留出进程收尾余量。
+const DefaultBootstrapTimeout = 9 * time.Minute
+
+// 目录扫描的上限（与 magic-test 同一口径：给树 + 清单当起点，其余让 agent 自己按需读）。
+const (
+	scanMaxEntries     = 400
+	scanMaxDepth       = 3
+	scanDirMaxChildren = 14
+	scanTreeMax        = 12000
+	scanManifestMax    = 4000
+)
+
+var scanSkipDirs = map[string]bool{
+	"node_modules": true, ".git": true, "dist": true, "build": true, "out": true,
+	".next": true, ".nuxt": true, "target": true, "vendor": true, "coverage": true,
+	".cache": true, "__pycache__": true, ".venv": true, "venv": true, "env": true,
+	".idea": true, ".vscode": true, "tmp": true, "Pods": true, ".gradle": true,
+	".tox": true, "playwright-report": true, ".trae-cn": true,
+}
+
+var scanSkipExt = map[string]bool{
+	".png": true, ".jpg": true, ".jpeg": true, ".gif": true, ".webp": true, ".bmp": true,
+	".ico": true, ".icns": true, ".svg": true, ".mp4": true, ".mov": true, ".avi": true,
+	".mkv": true, ".webm": true, ".mp3": true, ".wav": true, ".m4a": true, ".zip": true,
+	".tar": true, ".gz": true, ".7z": true, ".rar": true, ".pdf": true, ".db": true,
+	".sqlite": true, ".woff": true, ".woff2": true, ".ttf": true, ".otf": true,
+	".eot": true, ".lock": true, ".log": true, ".map": true, ".pyc": true,
+	".class": true, ".jar": true, ".dmg": true, ".exe": true,
+}
+
+var scanManifests = []string{
+	"README.md", "readme.md", "README.MD", "package.json", "pyproject.toml",
+	"requirements.txt", "Cargo.toml", "go.mod", "composer.json", "Makefile", "index.html",
+}
+
+// projectScan 有界扫描结果（直接渲染进 prompt）。
+type projectScan struct {
+	Tree      string
+	Manifests []scanManifest
+	FileCount int
+	Truncated bool
+}
+
+type scanManifest struct {
+	Name    string
+	Content string
+}
+
+// scanProject 扫目录：只列源码/文档，跳过依赖与构建目录；每一项目录最多列 14 项。
+func scanProject(dir string) (projectScan, error) {
+	st, err := os.Stat(dir)
+	if err != nil {
+		return projectScan{}, fmt.Errorf("目录不存在或不可读: %w", err)
+	}
+	if !st.IsDir() {
+		return projectScan{}, fmt.Errorf("不是目录: %s", dir)
+	}
+	scan := projectScan{}
+	lines := make([]string, 0, scanMaxEntries)
+	n := 0
+	var walk func(d string, depth int, prefix string)
+	walk = func(d string, depth int, prefix string) {
+		if n >= scanMaxEntries || depth > scanMaxDepth {
+			return
+		}
+		entries, err := os.ReadDir(d)
+		if err != nil {
+			return
+		}
+		// 目录在前、同类按名字排序（与 magic-test 一致：先看布局，再看文件）。
+		sort.Slice(entries, func(i, j int) bool {
+			di, dj := entries[i].IsDir(), entries[j].IsDir()
+			if di != dj {
+				return di
+			}
+			return entries[i].Name() < entries[j].Name()
+		})
+		shown := 0
+		for _, e := range entries {
+			if n >= scanMaxEntries {
+				return
+			}
+			name := e.Name()
+			if strings.HasPrefix(name, ".") {
+				continue
+			}
+			if e.IsDir() && scanSkipDirs[name] {
+				lines = append(lines, prefix+name+"/ …")
+				continue
+			}
+			if !e.IsDir() && scanSkipExt[strings.ToLower(filepath.Ext(name))] {
+				continue
+			}
+			if shown >= scanDirMaxChildren {
+				lines = append(lines, prefix+"…（本目录另有若干项，已省略）")
+				return
+			}
+			shown++
+			n++
+			if e.IsDir() {
+				lines = append(lines, prefix+name+"/")
+				walk(filepath.Join(d, name), depth+1, prefix+"  ")
+			} else {
+				lines = append(lines, prefix+name)
+			}
+		}
+	}
+	walk(dir, 1, "")
+	scan.FileCount = n
+	scan.Truncated = n >= scanMaxEntries
+	tree := strings.Join(lines, "\n")
+	if len([]rune(tree)) > scanTreeMax {
+		tree = string([]rune(tree)[:scanTreeMax]) + "\n…（目录树已截断）"
+	}
+	scan.Tree = tree
+
+	for _, name := range scanManifests {
+		p := filepath.Join(dir, name)
+		st, err := os.Stat(p)
+		if err != nil || !st.Mode().IsRegular() || st.Size() > 200_000 {
+			continue
+		}
+		b, err := os.ReadFile(p)
+		if err != nil {
+			continue
+		}
+		scan.Manifests = append(scan.Manifests, scanManifest{
+			Name:    name,
+			Content: truncRunes(string(b), scanManifestMax),
+		})
+	}
+	return scan, nil
+}
+
+// bootstrapResult 一轮初始化（目录反推）的结果。
+type bootstrapResult struct {
+	// Empty 没有可用的目录基线 —— 目录为空，或模型明确返回 features:[]。
+	// 不是错误：调用方应回落到会话增量，并把初始化标记为完成（否则每次点击都重扫一遍）。
+	Empty bool
+	// Called 是否真的调用了模型（目录为空时不调）。
+	Called bool
+	// Engine 实际用来读目录的引擎。
+	Engine string
+	// Scanned 扫描到的条目数（排障用）。
+	Scanned     int
+	Updated     int
+	Created     int
+	Points      int
+	Conclusions int
+}
+
+// bootstrapWorkspace 按工作区目录反推一版需求基线。
+//
+// 目录为空时返回 Empty=true（不调模型）；有内容但引擎不可用/输出不可解析时返回错误，
+// 让调用方把原因写进 state.LastError，下一次点「整理」还能重试。
+func bootstrapWorkspace(ctx context.Context, ws workspaceEntry, opts Options) (bootstrapResult, error) {
+	res := bootstrapResult{}
+	if ws.Dir == "" {
+		res.Empty = true
+		return res, nil
+	}
+	scan, err := scanProject(ws.Dir)
+	if err != nil {
+		return res, err
+	}
+	res.Scanned = scan.FileCount
+	if scan.FileCount == 0 {
+		res.Empty = true
+		return res, nil
+	}
+
+	engineName, err := bootstrapEnginePicker(opts.Engine)
+	if err != nil {
+		return res, err
+	}
+	res.Engine = engineName
+
+	existing := make([]string, 0, 8)
+	for _, f := range listFeatureFiles(ws.ID) {
+		existing = append(existing, f.Name)
+	}
+	prompt := buildBootstrapPrompt(ws.Name, scan, existing)
+	timeout := bootstrapTimeout(opts.Timeout)
+	res.Called = true
+	/* 显式默认引擎时，模型也跟着配置走（claude + 它自己的模型是合法组合）。
+	   自动挑引擎时不能用 opts.Model：那是给另一个（通常是 llm）引擎的模型名，
+	   传给 claude / codebuddy 只会报「模型不存在」。 */
+	bootstrapModel := ""
+	if strings.TrimSpace(opts.Engine) != "" {
+		bootstrapModel = opts.Model
+	}
+	text, err := runBootstrapAgent(ctx, engineName, bootstrapModel, ws.Dir, prompt, timeout)
+	if err != nil {
+		return res, fmt.Errorf("初始化引擎 %s 失败: %w", engineName, err)
+	}
+	outs, err := parseFeatures(text)
+	if err != nil {
+		head := collapseSpace(text)
+		if len([]rune(head)) > 200 {
+			head = string([]rune(head)[:200])
+		}
+		return res, fmt.Errorf("初始化输出不可解析: %w｜开头：%s", err, head)
+	}
+	if len(outs) == 0 {
+		/* 目录里没有可识别的产品能力（只有构建脚本 / 依赖 / 占位文件）也是合法结果：
+		   标记初始化完成并回落到会话增量。把它当失败会让用户每点一次「整理」就白扫一遍目录。 */
+		res.Empty = true
+		return res, nil
+	}
+
+	merger := newDocMerger(ws.ID)
+	baseLine := "[初始化] 空间目录基线 · " + todayStr() + "（引擎 " + engineName + "）"
+	for _, o := range outs {
+		w := writeFeatureItem(ws.ID, o, &writeCtx{
+			merger: merger,
+			alias:  map[string]string{},
+			kind:   "初始化",
+			sourcesOf: func(featureOut) []string {
+				return []string{baseLine}
+			},
+		})
+		if !w.ok {
+			continue
+		}
+		res.Points += w.points
+		res.Conclusions += w.conclusions
+		if w.created {
+			res.Created++
+		} else {
+			res.Updated++
+		}
+	}
+	if res.Created+res.Updated == 0 {
+		/* 模型给了 features 但全是空壳（只有名字、没有描述/要点/结论）→ 没有基线。
+		   与 features:[] 同样处理：标记初始化完成，回落到会话增量，不要把旧会话吞掉。 */
+		res.Empty = true
+	}
+	return res, nil
+}
+
+// bootstrapTimeout 初始化单次调用上限。
+//
+// 归纳默认 240s 对「读代码 + 组织输出」太短；但调用方显式设了别的值就尊重它
+// （CLI 的 --requirement-timeout 同时作用于两者，文档里写清楚）。
+func bootstrapTimeout(t time.Duration) time.Duration {
+	if t <= 0 || t == DefaultTimeout {
+		return DefaultBootstrapTimeout
+	}
+	return t
+}
+
+// bootstrapEnginePicker 是 pickBootstrapEngine 的可替换入口（单测不依赖本机装了哪个 CLI）。
+var bootstrapEnginePicker = pickBootstrapEngine
+
+// pickBootstrapEngine 选首次初始化用哪个引擎。
+//
+// 口径（2026-10-22 用户）：「整理的引擎就是配置的默认引擎」。
+//   - 调用方显式给了引擎（移动端 / PC 的默认引擎）→ **就用它**，不再偷偷换成别的；
+//     它不能读目录（llm / arkclaw / openclaw / codebuddy-gateway）或本机不可用，直接报错，
+//     让用户知道该去设置里换一个，而不是拿另一个引擎的结果冒充「默认引擎」。
+//   - 调用方没给（「自动（首个可用）」/ 直接跑 CLI）→ 按 claude → codebuddy →
+//     codebuddy-ai → codex → trae → dsh 找第一个能读目录且本机可用的。
+func pickBootstrapEngine(preferred string) (string, error) {
+	preferred = strings.TrimSpace(preferred)
+	if preferred != "" {
+		if !bootstrapCapable(preferred) {
+			return "", fmt.Errorf("默认引擎 %s 不能读目录，无法按空间目录初始化；请在设置里换一个能读代码的引擎（如 claude / codebuddy / codex / dsh）", preferred)
+		}
+		if !engineAvailable(preferred) {
+			return "", fmt.Errorf("默认引擎 %s 本机不可用，无法按空间目录初始化；请先安装它，或在设置里换一个可用引擎", preferred)
+		}
+		return preferred, nil
+	}
+	for _, name := range []string{"claude", "codebuddy", "codebuddy-ai", "codex", "trae", "dsh"} {
+		if bootstrapCapable(name) && engineAvailable(name) {
+			return name, nil
+		}
+	}
+	return "", fmt.Errorf("没有可用于首次初始化的引擎：需要能读目录的引擎（如 claude / codebuddy / codex / dsh），当前都不可用")
+}
+
+// bootstrapCapable 引擎能不能在指定目录里读文件。
+func bootstrapCapable(name string) bool {
+	if strings.TrimSpace(name) == "" {
+		return false
+	}
+	return agent.WorkspaceSupportOf(name) != "none"
+}
+
+func engineAvailable(name string) bool {
+	e := agent.Lookup(name)
+	if e == nil {
+		return false
+	}
+	ok, _ := e.Detect()
+	return ok
+}
+
+// runBootstrapAgent 默认的初始化调用器（单测可替换）。
+//
+// 与归纳的 llm 调用刻意分开：这里是**带工具的 agent**，工作目录必须是目标目录；
+// 权限档位用 auto（沙箱内读代码），只有引擎支持四档权限时才下发 —— 不支持的下发
+// 会被 CLI 以 exit 2 打回，整轮白跑。
+var runBootstrapAgent = func(ctx context.Context, engineName, model, dir, prompt string, timeout time.Duration) (string, error) {
+	engine := agent.Lookup(engineName)
+	if engine == nil {
+		return "", fmt.Errorf("未知引擎: %s", engineName)
+	}
+	req := agent.Request{
+		Messages:   []agent.Message{{Role: "user", Content: prompt}},
+		Tools:      agent.ToolsOn,
+		Model:      model,
+		Workspace:  dir,
+		JSONSchema: outSchema,
+		Timeout:    timeout,
+	}
+	if agent.PermissionSupportOf(engineName) != "none" {
+		req.Permission = agent.PermissionAuto
+	}
+	runner := &agent.Runner{Engine: engine, Timeout: timeout}
+	resp, err := runner.Run(ctx, req)
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(resp.Text), nil
+}
+
+// buildBootstrapPrompt 组「按目录反推需求」的 prompt。
+//
+// 口径（用户视角 / 只写代码里真实存在的东西 / 有节制地读文件 / 只输出 JSON）与
+// magic-test 一致；这里把规则压短，省下的上下文留给目录树与源码。
+func buildBootstrapPrompt(wsName string, scan projectScan, existing []string) string {
+	var manif strings.Builder
+	for i, m := range scan.Manifests {
+		if i > 0 {
+			manif.WriteString("\n\n")
+		}
+		manif.WriteString("--- " + m.Name + " ---\n" + m.Content)
+	}
+	if manif.Len() == 0 {
+		manif.WriteString("（无）")
+	}
+	tree := scan.Tree
+	if strings.TrimSpace(tree) == "" {
+		tree = "（空）"
+	}
+	var ex strings.Builder
+	if len(existing) > 0 {
+		ex.WriteString("== 已有功能点（逐字沿用 name，不要重复建）==\n")
+		ex.WriteString(strings.Join(existing, "、"))
+		ex.WriteString("\n\n")
+	}
+	return "你是资深产品经理。现在接手一个**已经写好代码**的项目目录（工作区：" + wsName + "）。\n" +
+		"任务：**反推**它已经实现的功能点，为「功能点需求文档」建立**基线**。\n" +
+		"⚠️ 产出的是**需求**（用户视角），不是**技术说明**（实现视角）—— 读代码是为了知道「用户能做什么」，\n" +
+		"然后把代码事实翻译成用户语言。\n" +
+		"⚠️ **输出只有一样东西**：最后把 JSON 直接写在回复正文里。不要写文件，不要加解释，不要代码围栏。\n\n" +
+		"== 目录结构（有界扫描，已跳过依赖 / 构建目录）==\n" + tree + "\n\n" +
+		"== 关键文件（清单 / 说明，已截断）==\n" + manif.String() + "\n\n" +
+		ex.String() +
+		"== 你要做的 ==\n" +
+		"1. 用工具继续读这个目录里的关键源码（入口文件、路由/菜单定义、主要模块、README），\n" +
+		"   把「用户实际能做什么」搞清楚；不要只看文件名猜。\n" +
+		"   探索要有节制：读 10 个左右最关键的源码文件就够了，不要试图读完全部代码。\n" +
+		"2. 按「大功能点（module）→ 功能点（name）」两级归纳已经实现的能力：\n" +
+		"   · module：产品模块名（如「设置」「需求管理」「对话交互」），≤" + itoa(ModuleMaxChars) + " 个汉字；\n" +
+		"   · name：这个功能点在做什么，≤" + itoa(TitleMaxChars) + " 个汉字；\n" +
+		"   · desc：一句话说明**用户拿它做什么**；\n" +
+		"   · points：用户能做什么 / 看到什么，每条 ≤30 字；\n" +
+		"   · conclusions：用户可感知的取舍或约束（默认值、可选范围、明确不做的），每条 ≤30 字；\n" +
+		"     确认不了就给空数组 []，不要猜。\n" +
+		"3. 强制规则（违反即不合格）：\n" +
+		"   · 不写实现方式：编程语言 / 框架 / 库 / API / 命令行参数 / 配置文件 / 文件格式 /\n" +
+		"     存储与传输方式 / 数据表与字段名 / 协议 / 类名函数名，一个都不许出现；\n" +
+		"   · 主语是用户，动词是用户动作（看到 / 点击 / 选择 / 收到 / 切换 / 导入 / 导出 / 记住…）；\n" +
+		"     判据只有一条：**用户能不能感知到**；\n" +
+		"   · 素材里本来有技术措辞时，改写成用户语言再写进来；\n" +
+		"   · 输出前逐条自检：读一遍，问「用户能看到 / 做到这件事吗？」，答不上来的删掉。\n" +
+		"4. 只写代码里**真实存在**的东西：不要写「建议」「应该」「待实现」，不要写日期。\n" +
+		"5. 数量控制在 5-20 个：只保留真正的产品能力；目录结构、依赖、构建脚本、配置文件都不是功能点。\n" +
+		"6. 最后只输出 JSON（不要代码围栏）：\n" +
+		`{"features":[{"module":"…","name":"…","desc":"…","points":["…"],"conclusions":["…"]}]}`
+}