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

@@ -17,6 +17,7 @@
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/selfupdate"
+	"github.com/larksuite/cli/internal/skillcontent"
 	"github.com/larksuite/cli/internal/skillscheck"
 	"github.com/larksuite/cli/internal/update"
 )
@@ -37,6 +38,9 @@
 	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 +116,11 @@
 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)
@@ -166,7 +175,7 @@
 	if !opts.Force && !update.IsNewer(latest, cur) {
 		var skillsResult *skillscheck.SyncResult
 		if !opts.Check {
-			skillsResult = runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout)
+			skillsResult = runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, embeddedOfficialSkills(opts.Factory))
 			if err := reportSkillsFailure(opts, io, skillsResult); err != nil {
 				return err
 			}
@@ -254,7 +263,7 @@
 }
 
 func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
-	skillsResult := runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout)
+	skillsResult := runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, embeddedOfficialSkills(opts.Factory))
 	reason := detect.ManualReason()
 	if opts.JSON {
 		out := map[string]interface{}{
@@ -349,7 +358,7 @@
 		return output.ErrBare(output.ExitAPI)
 	}
 
-	skillsResult := runSkillsAndState(updater, io, latest, opts.Force, opts.SkillsLayout)
+	skillsResult := runSkillsAndState(updater, io, latest, opts.Force, opts.SkillsLayout, embeddedOfficialSkills(opts.Factory))
 	if skillsResult != nil && skillsResult.Err != nil {
 		fields := map[string]interface{}{
 			"previous_version": cur, "current_version": latest,
@@ -379,7 +388,7 @@
 
 	fmt.Fprintf(io.ErrOut, "\n%s Successfully updated lark-cli from %s to %s\n", symOK(), cur, latest)
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
-	if skillsResult != nil {
+	if skillsResult != nil && skillsResult.Action != skillscheck.ActionNotInstalled {
 		skillsPM := "npx"
 		if detect.Method == selfupdate.InstallPnpm && detect.PnpmAvailable {
 			skillsPM = "pnpm dlx"
@@ -410,7 +419,7 @@
 	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): npm install -g %s@%s && npx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
 }
 
-func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool, requestedLayout string) *skillscheck.SyncResult {
+func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool, requestedLayout string, officialNames []string) *skillscheck.SyncResult {
 	layout, _ := skillscheck.ParseLayout(requestedLayout)
 	if !force {
 		if state, ok, err := skillscheck.ReadState(); err == nil && ok && normalizeVersion(state.Version) == normalizeVersion(stateVersion) {
@@ -420,17 +429,35 @@
 		}
 	}
 	result := syncSkills(skillscheck.SyncOptions{
-		Version: stateVersion,
-		Layout:  layout,
-		Force:   force,
-		Runner:  updater,
+		Version:             stateVersion,
+		Layout:              layout,
+		Force:               force,
+		Runner:              updater,
+		KnownOfficialSkills: officialNames,
 	})
 	if result.Err != nil && strings.Contains(result.Err.Error(), "state not written") {
 		fmt.Fprintf(io.ErrOut, "warning: %v\n", result.Err)
 	}
 	return result
 }
 
+// embeddedOfficialSkills lists the official skill names embedded in this
+// binary, or nil when the build ships none.
+func embeddedOfficialSkills(f *cmdutil.Factory) []string {
+	if f == nil || f.SkillContent == nil {
+		return nil
+	}
+	infos, err := skillcontent.New(f.SkillContent).List()
+	if err != nil {
+		return nil
+	}
+	names := make([]string, 0, len(infos))
+	for _, info := range infos {
+		names = append(names, info.Name)
+	}
+	return names
+}
+
 func reportSkillsFailure(opts *UpdateOptions, io *cmdutil.IOStreams, result *skillscheck.SyncResult) error {
 	return reportSkillsFailureWithFields(opts, io, result, nil)
 }
@@ -505,6 +532,9 @@
 		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 +571,9 @@
 			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

@@ -14,6 +14,7 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"testing/fstest"
 	"time"
 
 	"github.com/larksuite/cli/errs"
@@ -1201,7 +1202,7 @@ func TestRunSkillsAndState_DedupHit(t *testing.T) {
 			return &selfupdate.NpmResult{}
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "")
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", nil)
 	if got != nil {
 		t.Errorf("runSkillsAndState() = %+v, want nil for dedup hit", got)
 	}
@@ -1226,7 +1227,7 @@ func TestRunSkillsAndState_RequestedLayoutBypassesVersionDedup(t *testing.T) {
 		return &skillscheck.SyncResult{Action: "synced", Layout: skillscheck.LayoutSuite}
 	}
 
-	got := runSkillsAndState(&selfupdate.Updater{}, newTestIO(), "1.0.21", false, "suite")
+	got := runSkillsAndState(&selfupdate.Updater{}, newTestIO(), "1.0.21", false, "suite", nil)
 	if !called || got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState() = %+v, called = %v", got, called)
 	}
@@ -1249,7 +1250,7 @@ func TestRunSkillsAndState_UnknownOfficialSkillsBypassesVersionDedup(t *testing.
 		return &skillscheck.SyncResult{Action: "synced", Layout: skillscheck.LayoutSeparate}
 	}
 
-	got := runSkillsAndState(&selfupdate.Updater{}, newTestIO(), "1.0.21", false, "")
+	got := runSkillsAndState(&selfupdate.Updater{}, newTestIO(), "1.0.21", false, "", nil)
 	if !called || got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState() = %+v, called = %v", got, called)
 	}
@@ -1316,7 +1317,7 @@ func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 			return successfulSkillsCommand()(args...)
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true, "")
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true, "", nil)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState(force=true) = %+v, want successful result", got)
 	}
@@ -1331,7 +1332,7 @@ func TestRunSkillsAndState_SuccessWritesState(t *testing.T) {
 		SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 		SkillsCommandOverride:    successfulSkillsCommand(),
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "")
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", nil)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with nil Err", got)
 	}
@@ -1357,7 +1358,7 @@ func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
 			return r
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "")
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", nil)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with non-nil Err", got)
 	}
@@ -1650,7 +1651,7 @@ func TestRunSkillsAndState_StateWriteFailureWarns(t *testing.T) {
 	t.Cleanup(func() { syncSkills = origSync })
 
 	f, _, stderr := newTestFactory(t)
-	got := runSkillsAndState(&selfupdate.Updater{}, f.IOStreams, "1.0.21", false, "")
+	got := runSkillsAndState(&selfupdate.Updater{}, f.IOStreams, "1.0.21", false, "", nil)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with write error", got)
 	}
@@ -2044,3 +2045,163 @@ 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)
+	}
+}
+
+func TestRunSkillsAndState_CustomLarkPrefixedSkillIsNotInstalled(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	updater := &selfupdate.Updater{
+		SkillsIndexFetchOverride: func() *selfupdate.NpmResult {
+			t.Error("skills index fetched although only a custom lark- skill is installed")
+			return &selfupdate.NpmResult{Err: fmt.Errorf("unexpected index fetch")}
+		},
+		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+			r := &selfupdate.NpmResult{}
+			if strings.Join(args, " ") == "-y skills ls -g --json" {
+				r.Stdout.WriteString(`[{"name":"lark-custom","path":"/tmp/lark-custom","scope":"global","agents":["Codex"]}]`)
+			}
+			return r
+		},
+	}
+
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", []string{"lark-calendar", "lark-mail"})
+	if got == nil || got.Err != nil || got.Action != skillscheck.ActionNotInstalled {
+		t.Fatalf("runSkillsAndState() = %+v, want action %q", got, skillscheck.ActionNotInstalled)
+	}
+	if _, readable, err := skillscheck.ReadState(); readable || err != nil {
+		t.Errorf("ReadState() = (_, %v, %v), want no state written", readable, err)
+	}
+}
+
+func TestEmbeddedOfficialSkills_ReadsFactorySkillContent(t *testing.T) {
+	if got := embeddedOfficialSkills(nil); got != nil {
+		t.Errorf("embeddedOfficialSkills(nil) = %v, want nil", got)
+	}
+	f, _, _ := newTestFactory(t)
+	f.SkillContent = nil
+	if got := embeddedOfficialSkills(f); got != nil {
+		t.Errorf("embeddedOfficialSkills(no content) = %v, want nil", got)
+	}
+	f.SkillContent = fstest.MapFS{
+		"lark-calendar/SKILL.md": {Data: []byte("---\nname: lark-calendar\ndescription: calendar\n---\n")},
+		"lark-mail/SKILL.md":     {Data: []byte("---\nname: lark-mail\ndescription: mail\n---\n")},
+		"notes/README.md":        {Data: []byte("not a skill")},
+	}
+	got := embeddedOfficialSkills(f)
+	if strings.Join(got, ",") != "lark-calendar,lark-mail" {
+		t.Errorf("embeddedOfficialSkills() = %v, want [lark-calendar lark-mail]", got)
+	}
+}
+
+func TestUpdateNpm_Human_NothingInstalled_NoSkillsProgressLine(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, stderr := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{})
+
+	origFetch := fetchLatest
+	origVersion := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origVersion })
+	fetchLatest = func() (string, error) { return "2.0.0", nil }
+	currentVersion = func() string { return "1.0.0" }
+
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		u := selfupdate.New()
+		u.DetectOverride = func() selfupdate.DetectResult {
+			return selfupdate.DetectResult{Method: selfupdate.InstallNpm, ResolvedPath: "/node_modules/@larksuite/cli/bin/lark-cli", NpmAvailable: true}
+		}
+		u.NpmInstallOverride = func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
+		u.VerifyOverride = func(string) error { return nil }
+		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
+			t.Error("skills index fetched although no official skill is installed")
+			return &selfupdate.NpmResult{Err: fmt.Errorf("unexpected index fetch")}
+		}
+		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
+			r := &selfupdate.NpmResult{}
+			if strings.Join(args, " ") == "-y skills ls -g --json" {
+				r.Stdout.WriteString(`[{"name":"custom-skill","path":"/tmp/custom-skill","scope":"global","agents":["Codex"]}]`)
+			}
+			return r
+		}
+		return u
+	}
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stderr.String()
+	if !strings.Contains(out, "Successfully updated") {
+		t.Errorf("expected success message in stderr, got: %s", out)
+	}
+	if strings.Contains(out, "Updating skills via") {
+		t.Errorf("progress line printed although skills sync was skipped: %s", out)
+	}
+	if !strings.Contains(out, "Skills not installed") || !strings.Contains(out, skillsInstallCommand) {
+		t.Errorf("expected not-installed notice with install command, got: %s", out)
+	}
+}