Merge pull request #35 from Approaching-AI/hotfix/v0.3.2

hotfix(v0.3.2): simplify onboarding manifest generation

Author: rjckkkkk

catalog/ui-onboarding.json

@@ -258,11 +258,11 @@ func run() error {
 		SupportManifest: supportSvc.GoUXManifestJSON,
 		OnboardingManifest: func(ctx context.Context) (json.RawMessage, error) {
 			_ = ctx
-			raw, err := catalog.FS.ReadFile("ui-onboarding.json")
+			raw, err := buildOnboardingManifestJSON(cat)
 			if err != nil {
-				return nil, fmt.Errorf("read ui onboarding manifest: %w", err)
+				return nil, fmt.Errorf("build ui onboarding manifest: %w", err)
 			}
-			return json.RawMessage(raw), nil
+			return raw, nil
 		},
 	})
 

cmd/aima/main.go

@@ -18,10 +18,12 @@ import (
 	state "github.com/jguan/aima/internal"
 	"github.com/jguan/aima/internal/agent"
 	benchpkg "github.com/jguan/aima/internal/benchmark"
+	"github.com/jguan/aima/internal/cli"
 	"github.com/jguan/aima/internal/engine"
 	"github.com/jguan/aima/internal/knowledge"
 	"github.com/jguan/aima/internal/mcp"
 	aimaRuntime "github.com/jguan/aima/internal/runtime"
+	"github.com/spf13/cobra"
 )
 
 type fakeRuntime struct {
@@ -50,6 +52,29 @@ type mockCommandRunner struct {
 	pipe      func(context.Context, []string, []string) error
 }
 
+type onboardingManifestDoc struct {
+	Locales map[string]*onboardingLocaleDoc `json:"locales"`
+}
+
+type onboardingLocaleDoc struct {
+	FullCommands onboardingFullCommandsDoc `json:"full_commands"`
+}
+
+type onboardingFullCommandsDoc struct {
+	Groups []onboardingGroupDoc `json:"groups"`
+}
+
+type onboardingGroupDoc struct {
+	ID    string                 `json:"id"`
+	Items []onboardingCommandDoc `json:"items"`
+}
+
+type onboardingCommandDoc struct {
+	ID          string `json:"id"`
+	Command     string `json:"command"`
+	Description string `json:"description"`
+}
+
 func (m *mockCommandRunner) Run(ctx context.Context, name string, args ...string) ([]byte, error) {
 	if m.run != nil {
 		return m.run(ctx, name, args...)
@@ -106,6 +131,235 @@ func TestOnboardingManifestEmbeddedShape(t *testing.T) {
 	}
 }
 
+func TestBuildOnboardingManifestJSON_IncludesAllTopLevelCommands(t *testing.T) {
+	t.Parallel()
+
+	raw, err := buildOnboardingManifestJSON(&knowledge.Catalog{})
+	if err != nil {
+		t.Fatalf("build onboarding manifest: %v", err)
+	}
+
+	manifest := decodeOnboardingManifest(t, raw)
+	zh, ok := manifest.Locales["zh"]
+	if !ok || zh == nil {
+		t.Fatalf("zh locale missing: %#v", manifest.Locales)
+	}
+
+	topLevel := findOnboardingGroup(t, zh.FullCommands.Groups, "top_level_commands")
+
+	root := cli.NewRootCmd(&cli.App{})
+	root.InitDefaultHelpCmd()
+	root.InitDefaultCompletionCmd()
+
+	want := make(map[string]struct{})
+	for _, cmd := range root.Commands() {
+		if cmd == nil || cmd.Hidden {
+			continue
+		}
+		want["/cli "+cmd.Name()] = struct{}{}
+	}
+
+	got := make(map[string]struct{})
+	for _, item := range topLevel.Items {
+		got[item.Command] = struct{}{}
+	}
+
+	if len(got) != len(want) {
+		t.Fatalf("top_level_commands item count = %d, want %d\nitems=%#v", len(got), len(want), topLevel.Items)
+	}
+
+	for command := range want {
+		if _, ok := got[command]; !ok {
+			t.Fatalf("top_level_commands missing command %s\nitems=%#v", command, topLevel.Items)
+		}
+	}
+
+	for command := range got {
+		if _, ok := want[command]; !ok {
+			t.Fatalf("top_level_commands has unexpected command %s\nitems=%#v", command, topLevel.Items)
+		}
+	}
+}
+
+func TestBuildOnboardingManifestJSON_MarksSampleModelExamplesAsReplaceable(t *testing.T) {
+	t.Parallel()
+
+	cat := &knowledge.Catalog{
+		ModelAssets: []knowledge.ModelAsset{
+			{
+				Metadata: knowledge.ModelMetadata{
+					Name:           "demo-llm",
+					Type:           "llm",
+					Family:         "demo",
+					ParameterCount: "1B",
+				},
+			},
+		},
+	}
+
+	raw, err := buildOnboardingManifestJSON(cat)
+	if err != nil {
+		t.Fatalf("build onboarding manifest: %v", err)
+	}
+
+	text := string(raw)
+	for _, want := range []string{
+		`"/cli help"`,
+		`"/cli model pull demo-llm"`,
+		`"/cli deploy demo-llm --dry-run"`,
+		`"/cli run demo-llm"`,
+		"demo-llm 是示例模型名，可替换成你自己的模型名",
+		"demo-llm is an example model name; replace it with your own model name",
+	} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("generated manifest missing %q\nmanifest=%s", want, text)
+		}
+	}
+}
+
+func TestBuildOnboardingManifestJSON_UsesLocalizedTemplates(t *testing.T) {
+	t.Parallel()
+
+	sourceRaw, err := catalog.FS.ReadFile("ui-onboarding.json")
+	if err != nil {
+		t.Fatalf("read embedded onboarding manifest: %v", err)
+	}
+
+	source := decodeOnboardingManifest(t, sourceRaw)
+	zhSource, ok := source.Locales["zh"]
+	if !ok || zhSource == nil {
+		t.Fatalf("source zh locale missing: %#v", source.Locales)
+	}
+	enSource, ok := source.Locales["en"]
+	if !ok || enSource == nil {
+		t.Fatalf("source en locale missing: %#v", source.Locales)
+	}
+
+	zhTemplates := findOnboardingGroup(t, zhSource.FullCommands.Groups, "top_level_commands")
+	enTemplates := findOnboardingGroup(t, enSource.FullCommands.Groups, "top_level_commands")
+	zhHelpTemplate := findOnboardingCommandByID(t, zhTemplates.Items, "help")
+	zhModelTemplate := findOnboardingCommandByID(t, zhTemplates.Items, "model")
+	zhDeployTemplate := findOnboardingCommandByID(t, zhTemplates.Items, "deploy")
+	enHelpTemplate := findOnboardingCommandByID(t, enTemplates.Items, "help")
+
+	for _, template := range []onboardingCommandDoc{zhHelpTemplate, zhModelTemplate, zhDeployTemplate, enHelpTemplate} {
+		if strings.TrimSpace(template.Description) == "" {
+			t.Fatalf("top_level_commands template missing description: %#v", template)
+		}
+	}
+
+	raw, err := buildOnboardingManifestJSON(&knowledge.Catalog{
+		ModelAssets: []knowledge.ModelAsset{
+			{
+				Metadata: knowledge.ModelMetadata{
+					Name:           "demo-llm",
+					Type:           "llm",
+					Family:         "demo",
+					ParameterCount: "1B",
+				},
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("build onboarding manifest: %v", err)
+	}
+
+	manifest := decodeOnboardingManifest(t, raw)
+	zh := manifest.Locales["zh"]
+	en := manifest.Locales["en"]
+	if zh == nil || en == nil {
+		t.Fatalf("missing locales: %#v", manifest.Locales)
+	}
+
+	zhHelp := findOnboardingCommandDescription(t, zh.FullCommands.Groups, "top_level_commands", "/cli help")
+	if want := replaceSampleModelPlaceholder(zhHelpTemplate.Description, "demo-llm"); zhHelp != want {
+		t.Fatalf("zh /cli help description = %q, want %q", zhHelp, want)
+	}
+
+	enHelp := findOnboardingCommandDescription(t, en.FullCommands.Groups, "top_level_commands", "/cli help")
+	if want := replaceSampleModelPlaceholder(enHelpTemplate.Description, "demo-llm"); enHelp != want {
+		t.Fatalf("en /cli help description = %q, want %q", enHelp, want)
+	}
+
+	zhModel := findOnboardingCommandDescription(t, zh.FullCommands.Groups, "top_level_commands", "/cli model")
+	if want := replaceSampleModelPlaceholder(zhModelTemplate.Description, "demo-llm"); zhModel != want {
+		t.Fatalf("zh /cli model description = %q, want %q", zhModel, want)
+	}
+
+	zhDeploy := findOnboardingCommandDescription(t, zh.FullCommands.Groups, "top_level_commands", "/cli deploy")
+	if want := replaceSampleModelPlaceholder(zhDeployTemplate.Description, "demo-llm"); zhDeploy != want {
+		t.Fatalf("zh /cli deploy description = %q, want %q", zhDeploy, want)
+	}
+}
+
+func TestBuildTopLevelOnboardingItems_FallsBackToCommandShort(t *testing.T) {
+	t.Parallel()
+
+	root := &cobra.Command{Use: "aima"}
+	root.AddCommand(&cobra.Command{
+		Use:   "version",
+		Short: "Show version information",
+	})
+
+	items := buildTopLevelOnboardingItems(root, map[string]string{})
+	if len(items) != 1 {
+		t.Fatalf("buildTopLevelOnboardingItems() item count = %d, want 1", len(items))
+	}
+	if got := items[0]["description"]; got != "Show version information" {
+		t.Fatalf("buildTopLevelOnboardingItems() description = %#v, want %q", got, "Show version information")
+	}
+}
+
+func decodeOnboardingManifest(t *testing.T, raw []byte) onboardingManifestDoc {
+	t.Helper()
+
+	var manifest onboardingManifestDoc
+	if err := json.Unmarshal(raw, &manifest); err != nil {
+		t.Fatalf("unmarshal onboarding manifest: %v", err)
+	}
+	return manifest
+}
+
+func findOnboardingGroup(t *testing.T, groups []onboardingGroupDoc, groupID string) onboardingGroupDoc {
+	t.Helper()
+
+	for _, group := range groups {
+		if group.ID == groupID {
+			return group
+		}
+	}
+
+	t.Fatalf("group %q not found", groupID)
+	return onboardingGroupDoc{}
+}
+
+func findOnboardingCommandByID(t *testing.T, items []onboardingCommandDoc, id string) onboardingCommandDoc {
+	t.Helper()
+
+	for _, item := range items {
+		if item.ID == id {
+			return item
+		}
+	}
+
+	t.Fatalf("command id %q not found", id)
+	return onboardingCommandDoc{}
+}
+
+func findOnboardingCommandDescription(t *testing.T, groups []onboardingGroupDoc, groupID, command string) string {
+	t.Helper()
+
+	group := findOnboardingGroup(t, groups, groupID)
+	for _, item := range group.Items {
+		if item.Command == command {
+			return item.Description
+		}
+	}
+
+	t.Fatalf("command %q not found in group %q", command, groupID)
+	return ""
+}
+
 func TestParseExtraParamsStrict(t *testing.T) {
 	tests := []struct {
 		name    string