feat(install): add --no-skills and stop update from installing skills uninvited

Makefile

@@ -52,7 +52,7 @@ script-test:
 	bash scripts/ci-workflow.test.sh
 	bash scripts/release-workflow.test.sh
 	bash scripts/semantic-review-workflow.test.sh
-	$(NODE) --test scripts/e2e_domains.test.js scripts/fetch_e2e_tat.test.js scripts/install.test.js scripts/release-preflight.test.js scripts/release-publish-policy.test.js scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js
+	$(NODE) --test scripts/e2e_domains.test.js scripts/fetch_e2e_tat.test.js scripts/install.test.js scripts/install-wizard.test.js scripts/release-preflight.test.js scripts/release-publish-policy.test.js scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js
 
 # ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta

README.md

@@ -75,6 +75,8 @@ Choose **one** of the following methods:
 npx @larksuite/cli@latest install
 ```
 
+The wizard also installs the AI Agent [Skills](#agent-skills). Pass `--no-skills` to install only the CLI; skills can be added later with `npx skills add larksuite/cli -y -g`, and `lark-cli update` leaves skills alone until they are installed.
+
 **Option 2 — From source:**
 
 Requires Go `v1.23`+ and Python 3.

README.zh.md

@@ -75,6 +75,8 @@
 npx @larksuite/cli@latest install
 ```
 
+安装向导会同时安装 AI Agent [Skills](#agent-skills)。加 `--no-skills` 可以只安装 CLI；之后随时可用 `npx skills add larksuite/cli -y -g` 补装，未安装 Skills 时 `lark-cli update` 不会自动安装。
+
 **方式二 — 从源码安装：**
 
 需要 Go `v1.23`+ 和 Python 3。

cmd/update/update.go

@@ -37,6 +37,9 @@ var (
 	syncSkills     = func(opts skillscheck.SyncOptions) *skillscheck.SyncResult { return skillscheck.SyncSkills(opts) }
 )
 
+// skillsInstallCommand matches the README install step so hints stay in sync.
+const skillsInstallCommand = "npx skills add larksuite/cli -y -g"
+
 func isWindows() bool { return currentOS == osWindows }
 
 // normalizeVersion canonicalizes a version string for state comparison.
@@ -112,6 +115,11 @@ Detects the installation method automatically:
 Use --json for structured output (for AI agents and scripts).
 Use --check to only check for updates without installing.
 
+Official skills are synced only when they are already installed. When no
+official skill is installed and no sync state exists, skills are left alone;
+install them with: npx skills add larksuite/cli -y -g
+(--force and --skills-layout also install them).
+
 The skill name "lark-suite" is reserved for CLI-managed suite layout.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return updateRun(opts)
@@ -505,6 +513,9 @@ func applySkillsResult(env map[string]interface{}, r *skillscheck.SyncResult) {
 		env["skills_action"] = "failed"
 		env["skills_warning"] = fmt.Sprintf("skills update failed: %s", r.Err)
 		env["skills_summary"] = skillsSummary(r)
+	case r.Action == skillscheck.ActionNotInstalled:
+		env["skills_action"] = skillscheck.ActionNotInstalled
+		env["skills_hint"] = "official skills are not installed; to install them run: " + skillsInstallCommand
 	default:
 		env["skills_action"] = "synced"
 		env["skills_summary"] = skillsSummary(r)
@@ -541,6 +552,9 @@ func emitSkillsTextHints(io *cmdutil.IOStreams, r *skillscheck.SyncResult) {
 			fmt.Fprintf(io.ErrOut, "  Failed skills: %s\n", strings.Join(r.Failed, ", "))
 		}
 		fmt.Fprintf(io.ErrOut, "  To retry all official skills: lark-cli update --force\n")
+	case r.Action == skillscheck.ActionNotInstalled:
+		fmt.Fprintf(io.ErrOut, "%s Skills not installed; skills sync skipped\n", symArrow())
+		fmt.Fprintf(io.ErrOut, "  To install official skills: %s\n", skillsInstallCommand)
 	case r.Warning != "":
 		fmt.Fprintf(io.ErrOut, "%s Skills updated using %s layout\n", symOK(), r.Layout)
 		fmt.Fprintf(io.ErrOut, "%s %s\n", symWarn(), r.Warning)

cmd/update/update_test.go

@@ -2044,3 +2044,67 @@ func TestResolveSkillsBrand_RespectsActiveProfile(t *testing.T) {
 		t.Errorf("unexpected notice: %q", errBuf.String())
 	}
 }
+
+func TestUpdateRun_AlreadyLatest_NothingInstalled_SkipsSkillsSync(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.21", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	var skillsCommands []string
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			SkillsIndexFetchOverride: func() *selfupdate.NpmResult {
+				t.Error("skills index fetched although no official skill is installed")
+				return &selfupdate.NpmResult{Err: fmt.Errorf("unexpected index fetch")}
+			},
+			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+				joined := strings.Join(args, " ")
+				skillsCommands = append(skillsCommands, joined)
+				r := &selfupdate.NpmResult{}
+				if joined == "-y skills ls -g --json" {
+					r.Stdout.WriteString(`[{"name":"custom-skill","path":"/tmp/custom-skill","scope":"global","agents":["Codex"]}]`)
+				}
+				return r
+			},
+		}
+	}
+
+	f, stdout, _ := newTestFactory(t)
+	if err := updateRun(&UpdateOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("updateRun() err = %v, want nil", err)
+	}
+
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("json.Unmarshal stdout: %v\nstdout: %s", err, stdout.String())
+	}
+	if env["skills_action"] != skillscheck.ActionNotInstalled {
+		t.Errorf("skills_action = %v, want %q", env["skills_action"], skillscheck.ActionNotInstalled)
+	}
+	if hint, _ := env["skills_hint"].(string); !strings.Contains(hint, skillsInstallCommand) {
+		t.Errorf("skills_hint = %q, want install command %q", hint, skillsInstallCommand)
+	}
+	for _, command := range skillsCommands {
+		if strings.Contains(command, "skills add") {
+			t.Errorf("skills add was run for a CLI-only install: %q", command)
+		}
+	}
+	if _, readable, err := skillscheck.ReadState(); readable || err != nil {
+		t.Errorf("ReadState() = (_, %v, %v), want no state written", readable, err)
+	}
+}
+
+func TestEmitSkillsTextHints_NotInstalled(t *testing.T) {
+	f, _, stderr := newTestFactory(t)
+	emitSkillsTextHints(f.IOStreams, &skillscheck.SyncResult{Action: skillscheck.ActionNotInstalled, Layout: skillscheck.LayoutSeparate})
+	out := stderr.String()
+	if !strings.Contains(out, "Skills not installed") || !strings.Contains(out, skillsInstallCommand) {
+		t.Errorf("stderr = %q, want not-installed notice with install command", out)
+	}
+}

internal/skillscheck/sync.go

@@ -257,6 +257,13 @@ type SyncOptions struct {
 	Now     func() time.Time
 }
 
+// ActionNotInstalled reports that skills sync was skipped because no official
+// skill is installed and no sync state exists. That combination means the user
+// never installed skills (for example `npx @larksuite/cli install --no-skills`),
+// so update must not install them uninvited. --force and an explicit
+// --skills-layout are treated as a request to install and bypass the skip.
+const ActionNotInstalled = "not_installed"
+
 type SyncResult struct {
 	Action          string
 	Official        []string
@@ -281,6 +288,7 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	}
 
 	previous, readable, err := ReadState()
+	stateMissing := err == nil && !readable
 	if err != nil {
 		readable = false
 		previous = nil
@@ -293,6 +301,9 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	if err != nil {
 		return &SyncResult{Action: "failed", Layout: targetLayout, Err: err}
 	}
+	if skipNotInstalled(opts, stateMissing, installed) {
+		return &SyncResult{Action: ActionNotInstalled, Layout: targetLayout, Force: opts.Force}
+	}
 	localOfficial, err := localOfficialSkills(installed, previous, readable)
 	if err != nil {
 		// A suite whose installed path or references cannot be read is treated as
@@ -346,6 +357,24 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	return fallbackSeparate(opts, previous, readable, localOfficial, installed, fallbackPlan, reasons)
 }
 
+func skipNotInstalled(opts SyncOptions, stateMissing bool, installed []installedSkill) bool {
+	if !stateMissing || opts.Force || opts.Layout != "" {
+		return false
+	}
+	return !hasOfficialSkillCandidate(installed)
+}
+
+// hasOfficialSkillCandidate matches the lark- prefix instead of the official
+// index so a CLI-only update never fetches the skills index just to skip.
+func hasOfficialSkillCandidate(installed []installedSkill) bool {
+	for _, skill := range installed {
+		if strings.HasPrefix(skill.Name, "lark-") {
+			return true
+		}
+	}
+	return false
+}
+
 func fetchOfficialSkills(runner SkillsRunner, source string) ([]string, error) {
 	result := runner.FetchSkillsIndex(source)
 	if result == nil || result.Err != nil {

internal/skillscheck/sync_test.go

@@ -741,3 +741,67 @@ func assertStrings(t *testing.T, got, want []string) {
 		t.Fatalf("got %#v, want %#v", got, want)
 	}
 }
+
+func TestSyncSkillsNothingInstalledWithoutStateIsNotInstalled(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	runner := &fakeSkillsRunner{
+		sources:       []string{"primary"},
+		indexes:       map[string]string{"primary": officialSkillsIndexOutput("lark-calendar", "lark-mail")},
+		indexErrors:   map[string]error{},
+		installErrors: map[string]error{},
+		stageErrors:   map[string]error{},
+		globalJSON:    globalSkillsJSONOutput("custom-skill"),
+	}
+
+	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
+	if result.Err != nil || result.Action != ActionNotInstalled {
+		t.Fatalf("result = %+v, want action %q without error", result, ActionNotInstalled)
+	}
+	if len(runner.installs) != 0 {
+		t.Fatalf("installs = %v, want none", runner.installs)
+	}
+	if _, ok, err := ReadState(); ok || err != nil {
+		t.Fatalf("ReadState() = (_, %v, %v), want no state written", ok, err)
+	}
+}
+
+func TestSyncSkillsNothingInstalledStillInstallsWhenRequested(t *testing.T) {
+	for _, test := range []struct {
+		name      string
+		opts      SyncOptions
+		seedState bool
+		installed []string
+	}{
+		{name: "force", opts: SyncOptions{Force: true}},
+		{name: "explicit layout", opts: SyncOptions{Layout: LayoutSeparate}},
+		{name: "previous sync state", seedState: true},
+		{name: "official skill installed", installed: []string{"lark-calendar"}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+			if test.seedState {
+				if err := WriteState(SkillsState{Version: "1.0.32", Layout: LayoutSeparate, OfficialSkills: []string{"lark-calendar", "lark-mail"}}); err != nil {
+					t.Fatal(err)
+				}
+			}
+			runner := &fakeSkillsRunner{
+				sources:       []string{"primary"},
+				indexes:       map[string]string{"primary": officialSkillsIndexOutput("lark-calendar", "lark-mail")},
+				indexErrors:   map[string]error{},
+				installErrors: map[string]error{},
+				stageErrors:   map[string]error{},
+				globalJSON:    globalSkillsJSONOutput(test.installed...),
+			}
+			opts := test.opts
+			opts.Version = "1.0.33"
+			opts.Runner = runner
+			opts.Now = time.Now
+
+			result := SyncSkills(opts)
+			if result.Err != nil || result.Action != "synced" {
+				t.Fatalf("result = %+v, want synced without error", result)
+			}
+			assertStrings(t, runner.installs, []string{"primary:lark-calendar,lark-mail"})
+		})
+	}
+}

scripts/install-wizard.js

@@ -35,6 +35,7 @@ const messages = {
     step2Spinner:   "正在安装 Skills...",
     step2Done:      "Skills 已安装",
     step2Fail:      "Skills 安装失败。运行以下命令重试: npx skills add %s -y -g",
+    step2SkipRequested: "已按 --no-skills 跳过 Skills 安装。需要时运行: npx skills add %s -y -g",
     step3:          "正在配置应用...",
     step3NotFound:  "未找到 lark-cli，终止",
     step3Found:     "发现已配置应用 (App ID: %s)，继续使用？",
@@ -64,6 +65,7 @@ const messages = {
     step2Spinner:   "Installing skills...",
     step2Done:      "Skills installed",
     step2Fail:      "Failed to install skills. Run manually: npx skills add %s -y -g",
+    step2SkipRequested: "Skipped skills installation (--no-skills). To install later: npx skills add %s -y -g",
     step3:          "Configuring app...",
     step3NotFound:  "lark-cli not found. Aborting",
     step3Found:     "Found existing app (App ID: %s). Use this app?",
@@ -216,6 +218,11 @@ function parseLangArg() {
   return null;
 }
 
+/** True when a boolean flag such as --no-skills is present in process.argv. */
+function hasFlag(name) {
+  return process.argv.slice(2).includes(name);
+}
+
 // ---------------------------------------------------------------------------
 // Steps
 // ---------------------------------------------------------------------------
@@ -271,7 +278,11 @@ async function skillsAlreadyInstalled() {
   }
 }
 
-async function stepInstallSkills(msg) {
+async function stepInstallSkills(msg, skip) {
+  if (skip) {
+    p.log.info(fmt(msg.step2SkipRequested, SKILLS_REPO_FALLBACK));
+    return;
+  }
   const s = p.spinner();
   s.start(msg.step2Spinner);
   try {
@@ -363,18 +374,19 @@ async function main() {
   const isInteractive = !!process.stdin.isTTY;
   const lang = isInteractive ? await stepSelectLang() : (parseLangArg() || "en");
   const msg = messages[lang];
+  const skipSkills = hasFlag("--no-skills");
 
   if (isInteractive) {
     p.intro(msg.setup);
     await stepInstallGlobally(msg);
-    await stepInstallSkills(msg);
+    await stepInstallSkills(msg, skipSkills);
     await stepConfigInit(msg, lang);
     await stepAuthLogin(msg);
     p.outro(msg.done);
   } else {
     console.log(msg.setup);
     await stepInstallGlobally(msg);
-    await stepInstallSkills(msg);
+    await stepInstallSkills(msg, skipSkills);
     console.log(msg.nonTtyHint);
   }
 }