fix: merge main and adapt pnpm suite skills

test: improve lark suite skills coverage
fix: remove standalone skills sync hint
2026-07-07 17:45:15 +08:00 · 2026-07-07 17:08:33 +08:00 · 2026-07-07 16:20:31 +08:00 · 2026-07-07 14:59:22 +08:00 · 2026-07-07 14:50:49 +08:00 · 2026-07-07 12:56:23 +08:00
29 changed files with 1330 additions and 1036 deletions
--- a/cmd/root_integration_test.go
+++ b/cmd/root_integration_test.go
@@ -103,10 +103,6 @@ func parseTypedEnvelope(t *testing.T, stderr *bytes.Buffer) typedErrorEnvelope {
 }

 func buildStrictModeIntegrationRootCmd(t *testing.T, f *cmdutil.Factory) *cobra.Command {
-	return buildStrictModeIntegrationRootCmdWithSetup(t, f, nil)
-}
-
-func buildStrictModeIntegrationRootCmdWithSetup(t *testing.T, f *cmdutil.Factory, setup func(*cobra.Command)) *cobra.Command {
 	t.Helper()
 	rootCmd := &cobra.Command{Use: "lark-cli"}
 	rootCmd.SilenceErrors = true
@@ -119,9 +115,6 @@ func buildStrictModeIntegrationRootCmdWithSetup(t *testing.T, f *cmdutil.Factory
 	rootCmd.AddCommand(api.NewCmdApi(f, nil))
 	service.RegisterServiceCommands(rootCmd, f)
 	shortcuts.RegisterShortcuts(rootCmd, f)
-	if setup != nil {
-		setup(rootCmd)
-	}
 	if mode := f.ResolveStrictMode(context.Background()); mode.IsActive() {
 		pruneForStrictMode(rootCmd, mode)
 	}
@@ -362,16 +355,10 @@ func TestIntegration_StrictModeBot_ProfileOverride_ServiceExplicitUserReturnsEnv

 func TestIntegration_StrictModeUser_ProfileOverride_ServiceBotOnlyMethodReturnsEnvelope(t *testing.T) {
 	f, stdout, stderr := newStrictModeDefaultFactory(t, "target", core.StrictModeUser)
-	rootCmd := buildStrictModeIntegrationRootCmdWithSetup(t, f, func(rootCmd *cobra.Command) {
-		fixture := &cobra.Command{Use: "strict-fixture"}
-		botOnly := &cobra.Command{Use: "bot-only", RunE: func(*cobra.Command, []string) error { return nil }}
-		cmdutil.SetSupportedIdentities(botOnly, []string{"bot"})
-		fixture.AddCommand(botOnly)
-		rootCmd.AddCommand(fixture)
-	})
+	rootCmd := buildStrictModeIntegrationRootCmd(t, f)

 	code := executeRootIntegration(t, f, rootCmd, []string{
-		"strict-fixture", "bot-only",
+		"im", "images", "create", "--data", `{"image_type":"message","image":"x"}`, "--dry-run",
 	})

 	if code != output.ExitValidation {
--- a/cmd/update/update.go
+++ b/cmd/update/update.go
@@ -86,10 +86,13 @@ func symArrow() string {

 // UpdateOptions holds inputs for the update command.
 type UpdateOptions struct {
-	Factory *cmdutil.Factory
-	JSON    bool
-	Force   bool
-	Check   bool
+	Factory      *cmdutil.Factory
+	JSON         bool
+	Force        bool
+	Check        bool
+	SkillsLayout string
+	FlatSkills   string
+	FlatSet      bool
 }

 // NewCmdUpdate creates the update command.
@@ -109,6 +112,7 @@ Detects the installation method automatically:
 Use --json for structured output (for AI agents and scripts).
 Use --check to only check for updates without installing.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.FlatSet = cmd.Flags().Changed("flat-skills")
 			return updateRun(opts)
 		},
 	}
@@ -116,6 +120,8 @@ Use --check to only check for updates without installing.`,
 	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "force reinstall even if already up to date")
 	cmd.Flags().BoolVar(&opts.Check, "check", false, "only check for updates, do not install")
+	cmd.Flags().StringVar(&opts.SkillsLayout, "skills-layout", "", "skills layout: separate or hybrid")
+	cmd.Flags().StringVar(&opts.FlatSkills, "flat-skills", "", "comma-separated skills kept as top-level skills when the effective layout is hybrid")
 	cmdutil.SetRisk(cmd, "high-risk-write")

 	return cmd
@@ -123,6 +129,9 @@ Use --check to only check for updates without installing.`,

 func updateRun(opts *UpdateOptions) error {
 	io := opts.Factory.IOStreams
+	if err := validateSkillsLayoutOptions(opts); err != nil {
+		return reportError(opts, io, "validation_error", err)
+	}
 	cur := currentVersion()
 	updater := newUpdater()

@@ -148,7 +157,7 @@ func updateRun(opts *UpdateOptions) error {
 	if !opts.Force && !update.IsNewer(latest, cur) {
 		var skillsResult *skillscheck.SyncResult
 		if !opts.Check {
-			skillsResult = runSkillsAndState(updater, io, cur, opts.Force)
+			skillsResult = runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
 		}
 		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
@@ -209,7 +218,7 @@ func reportCheckResult(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest s
 }

 func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
-	skillsResult := runSkillsAndState(updater, io, cur, opts.Force)
+	skillsResult := runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)

 	reason := detect.ManualReason()
 	if opts.JSON {
@@ -228,9 +237,9 @@ func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest stri
 	fmt.Fprintf(io.ErrOut, "  Release:   %s\n", releaseURL(latest))
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
 	if detect.Method == selfupdate.InstallPnpm {
-		fmt.Fprintf(io.ErrOut, "\nOr install via pnpm (note: skills will not be synced):\n  pnpm add -g %s@%s\n  pnpm dlx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
+		fmt.Fprintf(io.ErrOut, "\nOr install via pnpm (note: skills will not be synced):\n  pnpm add -g %s@%s\n", selfupdate.NpmPackage, latest)
 	} else {
-		fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
+		fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n", selfupdate.NpmPackage, latest)
 	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
@@ -299,7 +308,7 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 		return output.ErrBare(output.ExitAPI)
 	}

-	skillsResult := runSkillsAndState(updater, io, latest, opts.Force)
+	skillsResult := runSkillsAndState(updater, io, latest, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)

 	if opts.JSON {
 		result := map[string]interface{}{
@@ -341,21 +350,25 @@ func verificationFailureHint(updater *selfupdate.Updater, latest, pm string) str
 		return "the previous version has been restored"
 	}
 	if pm == "pnpm" {
-		return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): pnpm add -g %s@%s && pnpm dlx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
+		return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): pnpm add -g %s@%s, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
 	}
-	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))
+	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): npm install -g %s@%s, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
 }

-func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool) *skillscheck.SyncResult {
-	if !force {
-		if existing, ok := skillscheck.ReadSyncedVersion(); ok && normalizeVersion(existing) == normalizeVersion(stateVersion) {
+func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool, requestedLayout, requestedFlat string, flatSet bool) *skillscheck.SyncResult {
+	layout, flat := resolveSkillsSyncOptions(requestedLayout, requestedFlat, flatSet)
+	layoutExplicit := strings.TrimSpace(requestedLayout) != ""
+	if !force && !layoutExplicit && !flatSet {
+		if existing, existingLayout, ok := skillscheck.ReadSyncedVersionAndLayout(); ok && existingLayout != "" && normalizeVersion(existing) == normalizeVersion(stateVersion) {
 			return nil
 		}
 	}
 	result := syncSkills(skillscheck.SyncOptions{
-		Version: stateVersion,
-		Force:   force,
-		Runner:  updater,
+		Version:    stateVersion,
+		Layout:     layout,
+		FlatSkills: flat,
+		Force:      force,
+		Runner:     updater,
 	})
 	if result.Err != nil && strings.Contains(result.Err.Error(), "state not written") {
 		fmt.Fprintf(io.ErrOut, "warning: %v\n", result.Err)
@@ -363,6 +376,38 @@ func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, state
 	return result
 }

+func validateSkillsLayoutOptions(opts *UpdateOptions) errs.TypedError {
+	if _, ok := skillscheck.NormalizeLayout(opts.SkillsLayout); !ok {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--skills-layout must be one of separate or hybrid").WithParam("--skills-layout")
+	}
+	return nil
+}
+
+func resolveSkillsSyncOptions(requestedLayout, requestedFlat string, flatSet bool) (string, []string) {
+	state, readable, err := skillscheck.ReadState()
+	if err != nil {
+		readable = false
+		state = nil
+	}
+
+	layout := skillscheck.LayoutSeparate
+	if strings.TrimSpace(requestedLayout) != "" {
+		layout, _ = skillscheck.NormalizeLayout(requestedLayout)
+	} else if readable && state != nil {
+		if stateLayout, ok := skillscheck.NormalizeLayout(state.Layout); ok && state.Layout != "" {
+			layout = stateLayout
+		}
+	}
+
+	if flatSet {
+		return layout, skillscheck.ParseFlatSkills(requestedFlat)
+	}
+	if readable && state != nil {
+		return layout, state.FlatSkills
+	}
+	return layout, []string{}
+}
+
 // reportAlreadyUpToDate emits the JSON / pretty output for the
 // already-up-to-date branch, including any skills_action / skills_warning
 // fields derived from skillsResult. When check is true, this is the pure
@@ -409,6 +454,12 @@ func applySkillsStatus(env map[string]interface{}, target string) {
 	if len(state.SkippedDeletedSkills) > 0 {
 		status["skipped_deleted"] = state.SkippedDeletedSkills
 	}
+	if state.Layout != "" {
+		status["layout"] = state.Layout
+	}
+	if len(state.FlatSkills) > 0 {
+		status["flat_skills"] = state.FlatSkills
+	}
 	env["skills_status"] = status
 }

@@ -419,6 +470,7 @@ func applySkillsResult(env map[string]interface{}, r *skillscheck.SyncResult) {
 	case r.Err != nil:
 		env["skills_action"] = "failed"
 		env["skills_warning"] = fmt.Sprintf("skills update failed: %s", r.Err)
+		env["skills_hint"] = skillsFailureHint()
 		env["skills_summary"] = skillsSummary(r)
 	default:
 		env["skills_action"] = "synced"
@@ -432,10 +484,17 @@ func skillsSummary(r *skillscheck.SyncResult) map[string]interface{} {
 		"updated":         len(r.Updated),
 		"added":           len(r.Added),
 		"skipped_deleted": len(r.SkippedDeleted),
+		"layout":          r.Layout,
 	}
 	if len(r.Failed) > 0 {
 		summary["failed"] = r.Failed
 	}
+	if len(r.Collected) > 0 {
+		summary["collected"] = r.Collected
+	}
+	if len(r.Flat) > 0 {
+		summary["flat"] = r.Flat
+	}
 	return summary
 }

@@ -447,13 +506,17 @@ func emitSkillsTextHints(io *cmdutil.IOStreams, r *skillscheck.SyncResult) {
 		if len(r.Failed) > 0 {
 			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")
+		fmt.Fprintf(io.ErrOut, "  %s\n", skillsFailureHint())
 	case r.Force:
-		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills\n", symOK(), len(r.Official))
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills (%s layout)\n", symOK(), len(r.Official), r.Layout)
 	default:
-		fmt.Fprintf(io.ErrOut, "%s Skills updated: %d official, %d updated, %d added, %d skipped because deleted locally\n", symOK(), len(r.Official), len(r.Updated), len(r.Added), len(r.SkippedDeleted))
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: %d official, %d updated, %d added, %d skipped because deleted locally (%s layout)\n", symOK(), len(r.Official), len(r.Updated), len(r.Added), len(r.SkippedDeleted), r.Layout)
 		if len(r.SkippedDeleted) > 0 {
 			fmt.Fprintf(io.ErrOut, "  To restore all official skills: lark-cli update --force\n")
 		}
 	}
 }
+
+func skillsFailureHint() string {
+	return "Retry: lark-cli update --force. To switch to separate top-level skills: lark-cli update --skills-layout separate (this saves layout=separate and clears saved flat_skills)."
+}
--- a/cmd/update/update_test.go
+++ b/cmd/update/update_test.go
@@ -204,6 +204,9 @@ func TestUpdatePnpm_Unavailable_ManualFallback(t *testing.T) {
 	if !strings.Contains(out, "pnpm add -g") {
 		t.Errorf("expected pnpm add -g hint, got: %s", out)
 	}
+	if strings.Contains(out, "pnpm dlx skills add larksuite/cli") {
+		t.Errorf("should not suggest standalone pnpm skills sync command, got: %s", out)
+	}
 }

 func TestNormalizeVersion(t *testing.T) {
@@ -728,8 +731,8 @@ func TestUpdateNpmVerifyFail_JSON_NoRestoreHintWhenBackupUnavailable(t *testing.
 	if !strings.Contains(out, "skills will not be synced") {
 		t.Errorf("expected skills-not-synced warning in rollback hint, got: %s", out)
 	}
-	if !strings.Contains(out, "npx skills add larksuite/cli -y -g") {
-		t.Errorf("expected npx skills add hint for skills sync, got: %s", out)
+	if strings.Contains(out, "npx skills add larksuite/cli -y -g") {
+		t.Errorf("should not suggest standalone skills sync command, got: %s", out)
 	}
 }

@@ -1133,7 +1136,7 @@ func newTestIO() *cmdutil.IOStreams {

 func TestRunSkillsAndState_DedupHit(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21", Layout: skillscheck.LayoutSeparate}); err != nil {
 		t.Fatal(err)
 	}
 	called := false
@@ -1143,7 +1146,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, "", "", false)
 	if got != nil {
 		t.Errorf("runSkillsAndState() = %+v, want nil for dedup hit", got)
 	}
@@ -1152,6 +1155,27 @@ func TestRunSkillsAndState_DedupHit(t *testing.T) {
 	}
 }

+func TestRunSkillsAndState_MissingLayoutDoesNotDedup(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
+		t.Fatal(err)
+	}
+	called := false
+	updater := &selfupdate.Updater{
+		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+			called = true
+			return successfulSkillsCommand()(args...)
+		},
+	}
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
+	if got == nil || got.Err != nil {
+		t.Fatalf("runSkillsAndState() = %+v, want successful sync when state lacks layout", got)
+	}
+	if !called {
+		t.Error("SkillsCommandOverride not called, want resync when state lacks layout")
+	}
+}
+
 func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
@@ -1164,7 +1188,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, "", "", false)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState(force=true) = %+v, want successful result", got)
 	}
@@ -1176,7 +1200,7 @@ func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 func TestRunSkillsAndState_SuccessWritesState(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	updater := &selfupdate.Updater{SkillsCommandOverride: successfulSkillsCommand()}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with nil Err", got)
 	}
@@ -1187,6 +1211,12 @@ func TestRunSkillsAndState_SuccessWritesState(t *testing.T) {
 	if state.Version != "1.0.21" {
 		t.Errorf("state.Version = %q, want \"1.0.21\"", state.Version)
 	}
+	if state.Layout != skillscheck.LayoutSeparate {
+		t.Errorf("state.Layout = %q, want %q", state.Layout, skillscheck.LayoutSeparate)
+	}
+	if len(state.FlatSkills) != 0 {
+		t.Errorf("state.FlatSkills = %#v, want empty", state.FlatSkills)
+	}
 }

 func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
@@ -1201,7 +1231,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, "", "", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with non-nil Err", got)
 	}
@@ -1214,6 +1244,50 @@ func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
 	}
 }

+func TestResolveSkillsSyncOptions_UsesStateAsFallback(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := skillscheck.WriteState(skillscheck.SkillsState{
+		Version:    "1.0.21",
+		Layout:     skillscheck.LayoutHybrid,
+		FlatSkills: []string{"lark-doc"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	layout, flat := resolveSkillsSyncOptions("", "", false)
+	if layout != skillscheck.LayoutHybrid {
+		t.Fatalf("layout = %q, want %q", layout, skillscheck.LayoutHybrid)
+	}
+	if len(flat) != 1 || flat[0] != "lark-doc" {
+		t.Fatalf("flat = %#v, want [lark-doc]", flat)
+	}
+}
+
+func TestValidateSkillsLayoutOptionsRejectsSuiteMode(t *testing.T) {
+	err := validateSkillsLayoutOptions(&UpdateOptions{SkillsLayout: "suite"})
+	if err == nil {
+		t.Fatal("validateSkillsLayoutOptions() err = nil, want validation error")
+	}
+	var validation *errs.ValidationError
+	if !errors.As(err, &validation) {
+		t.Fatalf("errors.As(err, *ValidationError) = false for %T", err)
+	}
+	if validation.Param != "--skills-layout" {
+		t.Fatalf("validation.Param = %q, want --skills-layout", validation.Param)
+	}
+}
+
+func TestValidateSkillsLayoutOptionsAllowsFlatSkillsFilteringAfterOfficialDiscovery(t *testing.T) {
+	err := validateSkillsLayoutOptions(&UpdateOptions{
+		SkillsLayout: skillscheck.LayoutHybrid,
+		FlatSkills:   "lark-shared,lark-unknown",
+		FlatSet:      true,
+	})
+	if err != nil {
+		t.Fatalf("validateSkillsLayoutOptions() err = %v, want nil", err)
+	}
+}
+
 func TestTruncate(t *testing.T) {
 	long := strings.Repeat("x", 3000)
 	got := selfupdate.Truncate(long, 2000)
@@ -1494,7 +1568,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, "", "", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with write error", got)
 	}
--- a/internal/errclass/codemeta_drive.go
+++ b/internal/errclass/codemeta_drive.go
@@ -10,22 +10,20 @@ import "github.com/larksuite/cli/errs"
 // ambiguous codes fall back to CategoryAPI via BuildAPIError.
 // BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
 var driveCodeMeta = map[int]CodeMeta{
-	1061001:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive "unknown error"
-	1061002:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // params error
-	1061004:   {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // forbidden
-	1061007:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // file has been deleted
-	1061043:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file size beyond limit
-	1061044:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // parent folder does not exist (upload)
-	1061101:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file quota exceeded
-	1062009:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // actual size inconsistent with declared size
-	1063001:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // secure label invalid parameter
-	1063002:   {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // secure label permission denied
-	1063013:   {Category: errs.CategoryValidation, Subtype: errs.SubtypeFailedPrecondition},    // secure label downgrade requires approval
-	1069302:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // comment endpoint "Invalid or missing parameters"
-	99992402:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // platform field validation failed
-	9499:      {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // invalid parameter type in JSON field
-	2200:      {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive tenant/internal errors
-	233523001: {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive/docs transient server error
+	1061001:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive "unknown error"
+	1061002:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // params error
+	1061004:  {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // forbidden
+	1061007:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // file has been deleted
+	1061043:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file size beyond limit
+	1061044:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // parent folder does not exist (upload)
+	1062009:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // actual size inconsistent with declared size
+	1063001:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // secure label invalid parameter
+	1063002:  {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // secure label permission denied
+	1063013:  {Category: errs.CategoryValidation, Subtype: errs.SubtypeFailedPrecondition},    // secure label downgrade requires approval
+	1069302:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // comment endpoint "Invalid or missing parameters"
+	99992402: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // platform field validation failed
+	9499:     {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // invalid parameter type in JSON field
+	2200:     {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive tenant/internal errors
 }

 func init() { mergeCodeMeta(driveCodeMeta, "drive") }
--- a/internal/errclass/codemeta_test.go
+++ b/internal/errclass/codemeta_test.go
@@ -114,35 +114,8 @@ func TestLookupCodeMeta_DrivePushCodes(t *testing.T) {
 		{1061004, errs.CategoryAuthorization, errs.SubtypePermissionDenied, false},
 		{1061007, errs.CategoryAPI, errs.SubtypeNotFound, false},
 		{1061043, errs.CategoryAPI, errs.SubtypeQuotaExceeded, false},
-		{1061101, errs.CategoryAPI, errs.SubtypeQuotaExceeded, false},
 		{1062009, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
 		{2200, errs.CategoryAPI, errs.SubtypeServerError, true},
-		{233523001, errs.CategoryAPI, errs.SubtypeServerError, true},
-	}
-	for _, tc := range cases {
-		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {
-			got, ok := LookupCodeMeta(tc.code)
-			if !ok {
-				t.Fatalf("LookupCodeMeta(%d) ok=false, want true", tc.code)
-			}
-			if got.Category != tc.wantCat || got.Subtype != tc.wantSubtype || got.Retryable != tc.wantRetry {
-				t.Fatalf("LookupCodeMeta(%d) = %+v, want Category=%v Subtype=%v Retryable=%v",
-					tc.code, got, tc.wantCat, tc.wantSubtype, tc.wantRetry)
-			}
-		})
-	}
-}
-
-func TestLookupCodeMeta_WikiCodes(t *testing.T) {
-	cases := []struct {
-		code        int
-		wantCat     errs.Category
-		wantSubtype errs.Subtype
-		wantRetry   bool
-	}{
-		{131002, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
-		{131005, errs.CategoryAPI, errs.SubtypeNotFound, false},
-		{131006, errs.CategoryAuthorization, errs.SubtypePermissionDenied, false},
 	}
 	for _, tc := range cases {
 		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {
--- a/internal/errclass/codemeta_wiki.go
+++ b/internal/errclass/codemeta_wiki.go
@@ -1,17 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import "github.com/larksuite/cli/errs"
-
-// wikiCodeMeta holds wiki-service Lark code -> CodeMeta mappings observed from
-// wiki shortcut failure telemetry. Keep these to wiki-wide meanings only; add
-// command-specific recovery guidance at the shortcut layer.
-var wikiCodeMeta = map[int]CodeMeta{
-	131002: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},          // param err: space_id is not int / invalid page_token
-	131005: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                   // wiki node / space not found
-	131006: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // wiki space/node read permission denied
-}
-
-func init() { mergeCodeMeta(wikiCodeMeta, "wiki") }
--- a/internal/selfupdate/updater.go
+++ b/internal/selfupdate/updater.go
@@ -50,6 +50,8 @@ const (
 var (
 	skillsIndexFetchTimeout = 10 * time.Second
 	officialSkillsIndexURL  = "https://open.feishu.cn/.well-known/skills/index.json"
+	isolatedSkillsSourceURL = "https://open.feishu.cn/lark-cli/isolated-skills"
+	isolatedSkillsFallback  = "larksuite/cli/isolated-skills"
 )

 // DetectResult holds installation detection results.
@@ -328,6 +330,14 @@ func (u *Updater) InstallAllSkills() *NpmResult {
 	return r
 }

+func (u *Updater) InstallSuiteSkill() *NpmResult {
+	r := u.runSkillsInstall(isolatedSkillsSourceURL, []string{"lark-suite"})
+	if r.Err != nil {
+		r = u.runSkillsInstall(isolatedSkillsFallback, []string{"lark-suite"})
+	}
+	return r
+}
+
 func (u *Updater) runSkillsAdd(source string) *NpmResult {
 	return u.runSkillsCommand("-y", "skills", "add", source, "-g", "-y")
 }
--- a/internal/selfupdate/updater_test.go
+++ b/internal/selfupdate/updater_test.go
@@ -208,6 +208,13 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 			},
 			want: "-y skills add https://open.feishu.cn -s lark-mail -g -y",
 		},
+		{
+			name: "install isolated suite skill",
+			run: func(u *Updater) *NpmResult {
+				return u.runSkillsInstall(isolatedSkillsSourceURL, []string{"lark-suite"})
+			},
+			want: "-y skills add https://open.feishu.cn/lark-cli/isolated-skills -s lark-suite -g -y",
+		},
 	}

 	for _, tt := range tests {
@@ -238,6 +245,76 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 	}
 }

+func TestInstallSuiteSkillFallsBackToIsolatedGitHubSource(t *testing.T) {
+	called := []string{}
+	u := &Updater{
+		SkillsCommandOverride: func(args ...string) *NpmResult {
+			called = append(called, strings.Join(args, " "))
+			r := &NpmResult{}
+			if strings.Contains(strings.Join(args, " "), isolatedSkillsSourceURL) {
+				r.Err = fmt.Errorf("isolated source unavailable")
+			}
+			return r
+		},
+	}
+
+	result := u.InstallSuiteSkill()
+	if result.Err != nil {
+		t.Fatalf("InstallSuiteSkill() err = %v, want nil", result.Err)
+	}
+	if len(called) != 2 {
+		t.Fatalf("calls = %#v, want primary and fallback", called)
+	}
+	if !strings.Contains(called[0], isolatedSkillsSourceURL) {
+		t.Fatalf("primary call = %q, want isolated source", called[0])
+	}
+	if !strings.Contains(called[1], isolatedSkillsFallback) {
+		t.Fatalf("fallback call = %q, want isolated GitHub fallback", called[1])
+	}
+}
+
+func TestInstallSuiteSkillUsesPnpmDlxForIsolatedSources(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("uses a POSIX shell script")
+	}
+	dir := t.TempDir()
+	logPath := filepath.Join(dir, "pnpm.log")
+	script := filepath.Join(dir, "pnpm")
+	scriptContent := fmt.Sprintf(`#!/bin/sh
+printf '%%s\n' "$*" >> %q
+case "$*" in
+  *%q*) exit 1 ;;
+  *) exit 0 ;;
+esac
+`, logPath, isolatedSkillsSourceURL)
+	if err := os.WriteFile(script, []byte(scriptContent), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+
+	u := New()
+	u.DetectOverride = func() DetectResult {
+		return DetectResult{Method: InstallPnpm, PnpmAvailable: true}
+	}
+
+	result := u.InstallSuiteSkill()
+	if result.Err != nil {
+		t.Fatalf("InstallSuiteSkill() err = %v, want nil", result.Err)
+	}
+	raw, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := strings.Split(strings.TrimSpace(string(raw)), "\n")
+	want := []string{
+		"dlx skills add " + isolatedSkillsSourceURL + " -s lark-suite -g -y",
+		"dlx skills add " + isolatedSkillsFallback + " -s lark-suite -g -y",
+	}
+	if strings.Join(got, "\n") != strings.Join(want, "\n") {
+		t.Fatalf("pnpm calls = %#v, want %#v", got, want)
+	}
+}
+
 func TestListOfficialSkillsIndexSuccess(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		fmt.Fprint(w, `{"skills":[{"name":"lark-calendar"}]}`)
--- a/internal/skillscheck/layout.go
+++ b/internal/skillscheck/layout.go
@@ -0,0 +1,389 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+const (
+	LayoutSeparate = "separate"
+	LayoutHybrid   = "hybrid"
+
+	suiteSkillName         = "lark-suite"
+	sharedSkillName        = "lark-shared"
+	suiteRoutesPlaceholder = "<!-- LARK_SUITE_ROUTES -->"
+)
+
+type GlobalSkillInfo struct {
+	Name string
+	Path string
+}
+
+func NormalizeLayout(layout string) (string, bool) {
+	switch strings.TrimSpace(layout) {
+	case "", LayoutSeparate:
+		return LayoutSeparate, true
+	case LayoutHybrid:
+		return LayoutHybrid, true
+	default:
+		return "", false
+	}
+}
+
+func ParseFlatSkills(value string) []string {
+	seen := map[string]bool{}
+	for _, part := range strings.Split(value, ",") {
+		name := strings.TrimSpace(part)
+		if name != "" {
+			seen[name] = true
+		}
+	}
+	return sortedKeys(seen)
+}
+
+func ParseGlobalSkillInfosJSON(text string) []GlobalSkillInfo {
+	infos, _ := parseGlobalSkillInfosJSON(text)
+	return infos
+}
+
+func parseGlobalSkillInfosJSON(text string) ([]GlobalSkillInfo, bool) {
+	type globalSkill struct {
+		Name string `json:"name"`
+		Path string `json:"path"`
+	}
+
+	var skills []globalSkill
+	if err := json.Unmarshal([]byte(text), &skills); err != nil {
+		return nil, false
+	}
+
+	seen := map[string]GlobalSkillInfo{}
+	for _, skill := range skills {
+		name := strings.TrimSpace(skill.Name)
+		path := strings.TrimSpace(skill.Path)
+		if name == "" || path == "" || !skillNamePattern.MatchString(name) {
+			continue
+		}
+		seen[name] = GlobalSkillInfo{Name: name, Path: path}
+	}
+
+	out := make([]GlobalSkillInfo, 0, len(seen))
+	for _, info := range seen {
+		out = append(out, info)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out, true
+}
+
+func installedSkillNamesFromInfos(infos []GlobalSkillInfo) []string {
+	seen := map[string]bool{}
+	for _, info := range infos {
+		seen[info.Name] = true
+		if info.Name == suiteSkillName {
+			for _, subskill := range listSuiteSubskills(info.Path) {
+				seen[subskill] = true
+			}
+		}
+	}
+	return sortedKeys(seen)
+}
+
+func listSuiteSubskills(suitePath string) []string {
+	entries, err := vfs.ReadDir(filepath.Join(suitePath, "references", "subskills"))
+	if err != nil {
+		return nil
+	}
+	seen := map[string]bool{}
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+		name := strings.TrimSpace(entry.Name())
+		if name != "" && skillNamePattern.MatchString(name) {
+			seen[name] = true
+		}
+	}
+	return sortedKeys(seen)
+}
+
+func normalOfficialSkills(skills []string) []string {
+	out := []string{}
+	for _, skill := range uniqueSorted(skills) {
+		if skill != suiteSkillName {
+			out = append(out, skill)
+		}
+	}
+	return out
+}
+
+func deletedOfficialSkills(official, local []string, previous *SkillsState, stateReadable, force bool, layout string) []string {
+	if force || !stateReadable || previous == nil {
+		return []string{}
+	}
+	officialSet := toSet(official)
+	localSet := toSet(local)
+	deleted := map[string]bool{}
+	for _, skill := range previous.OfficialSkills {
+		if !officialSet[skill] || localSet[skill] {
+			continue
+		}
+		if layout != LayoutSeparate && skill == sharedSkillName {
+			continue
+		}
+		deleted[skill] = true
+	}
+	return sortedKeys(deleted)
+}
+
+func suiteEffectiveSkills(official []string, deleted map[string]bool) []string {
+	out := []string{}
+	for _, skill := range normalOfficialSkills(official) {
+		if !deleted[skill] {
+			out = append(out, skill)
+		}
+	}
+	return uniqueSorted(out)
+}
+
+func resolveHybridSkillSets(layout string, requestedFlat, official []string, skippedDeleted []string) ([]string, []string, error) {
+	if layout == LayoutSeparate {
+		return []string{}, []string{}, nil
+	}
+
+	officialSet := toSet(official)
+	deletedSet := toSet(skippedDeleted)
+	configuredFlat := map[string]bool{}
+	effectiveFlat := map[string]bool{}
+	for _, skill := range uniqueSorted(requestedFlat) {
+		if skill == sharedSkillName {
+			continue
+		}
+		if !officialSet[skill] {
+			continue
+		}
+		configuredFlat[skill] = true
+		if !deletedSet[skill] {
+			effectiveFlat[skill] = true
+		}
+	}
+
+	collected := []string{}
+	for _, skill := range normalOfficialSkills(official) {
+		if skill == sharedSkillName {
+			collected = append(collected, skill)
+			continue
+		}
+		if deletedSet[skill] || effectiveFlat[skill] {
+			continue
+		}
+		collected = append(collected, skill)
+	}
+	return sortedKeys(configuredFlat), uniqueSortedWithFirst(collected, sharedSkillName), nil
+}
+
+func uniqueSortedWithFirst(values []string, first string) []string {
+	seen := toSet(values)
+	if !seen[first] {
+		return sortedKeys(seen)
+	}
+	delete(seen, first)
+	return append([]string{first}, sortedKeys(seen)...)
+}
+
+func assembleSuiteLayout(layout string, collected []string, keepSharedTopLevel bool, infos []GlobalSkillInfo) error {
+	if layout == LayoutSeparate {
+		return nil
+	}
+
+	infoByName := map[string]GlobalSkillInfo{}
+	for _, info := range infos {
+		infoByName[info.Name] = info
+	}
+	suiteInfo, ok := infoByName[suiteSkillName]
+	if !ok {
+		return fmt.Errorf("%s was not installed from isolated skills source", suiteSkillName)
+	}
+
+	subskillsDir := filepath.Join(suiteInfo.Path, "references", "subskills")
+	if err := vfs.RemoveAll(subskillsDir); err != nil {
+		return err
+	}
+	if err := vfs.MkdirAll(subskillsDir, 0o755); err != nil {
+		return err
+	}
+
+	for _, skill := range collected {
+		info, ok := infoByName[skill]
+		if !ok {
+			return fmt.Errorf("suite subskill %q was not installed", skill)
+		}
+		dst := filepath.Join(subskillsDir, skill)
+		if keepSharedTopLevel && skill == sharedSkillName {
+			if err := copyDir(info.Path, dst); err != nil {
+				return err
+			}
+			continue
+		}
+		if err := moveDir(info.Path, dst); err != nil {
+			return err
+		}
+	}
+	return renderSuiteRoutes(suiteInfo.Path, collected)
+}
+
+func renderSuiteRoutes(suitePath string, collected []string) error {
+	skillPath := filepath.Join(suitePath, "SKILL.md")
+	data, err := vfs.ReadFile(skillPath)
+	if err != nil {
+		return err
+	}
+	text := normalizeSuiteTemplateText(string(data))
+	routes := []string{}
+	for _, skill := range collected {
+		desc := skillDescription(filepath.Join(suitePath, "references", "subskills", skill, "SKILL.md"))
+		if desc == "" {
+			desc = skill
+		}
+		routes = append(routes, fmt.Sprintf("- %s: %s", skill, desc))
+	}
+	if !strings.Contains(text, suiteRoutesPlaceholder) {
+		return fmt.Errorf("%s route placeholder not found", suiteSkillName)
+	}
+	text = strings.Replace(text, suiteRoutesPlaceholder, strings.Join(routes, "\n"), 1)
+	return vfs.WriteFile(skillPath, []byte(text), 0o644)
+}
+
+func normalizeSuiteTemplateText(text string) string {
+	text = strings.ReplaceAll(text, "--collected-skills", "--flat-skills")
+	oldShared := "`lark-shared` 是共享基础能力，不作为 `--flat-skills` 的可选项。为了保证 suite 内子能力可用，hybrid 布局会同时保留顶层 `lark-shared`，并在 `lark-suite/references/subskills/lark-shared/SKILL.md` 中维护一份副本。"
+	newShared := "`lark-shared` 是共享基础能力，不作为 `--flat-skills` 的可选项。为了保证 suite 内子能力可用，它始终会进入 `lark-suite/references/subskills/lark-shared/SKILL.md`；只有 hybrid 布局存在平铺 skill 时，顶层才会额外保留一份 `lark-shared`。"
+	return strings.ReplaceAll(text, oldShared, newShared)
+}
+
+func skillDescription(path string) string {
+	data, err := vfs.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	lines := strings.Split(string(data), "\n")
+	if len(lines) == 0 || strings.TrimSpace(lines[0]) != "---" {
+		return ""
+	}
+	for i, line := range lines[1:] {
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "---" {
+			return ""
+		}
+		if strings.HasPrefix(trimmed, "description:") {
+			value := strings.TrimSpace(strings.TrimPrefix(trimmed, "description:"))
+			if value == ">" || value == "|" {
+				return foldedYAMLScalar(lines[i+2:])
+			}
+			return strings.Trim(value, `"'`)
+		}
+	}
+	return ""
+}
+
+func foldedYAMLScalar(lines []string) string {
+	parts := []string{}
+	for _, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" {
+			continue
+		}
+		if trimmed == "---" || !isIndentedYAMLLine(line) {
+			break
+		}
+		parts = append(parts, trimmed)
+	}
+	return strings.Join(parts, " ")
+}
+
+func isIndentedYAMLLine(line string) bool {
+	return strings.HasPrefix(line, " ") || strings.HasPrefix(line, "\t")
+}
+
+func moveDir(src, dst string) error {
+	if err := vfs.RemoveAll(dst); err != nil {
+		return err
+	}
+	if err := vfs.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+		return err
+	}
+	if err := vfs.Rename(src, dst); err == nil {
+		return nil
+	}
+	if err := copyDir(src, dst); err != nil {
+		return err
+	}
+	return vfs.RemoveAll(src)
+}
+
+func copyDir(src, dst string) error {
+	info, err := vfs.Stat(src)
+	if err != nil {
+		return err
+	}
+	if !info.IsDir() {
+		return fmt.Errorf("%s is not a directory", src)
+	}
+	if err := vfs.RemoveAll(dst); err != nil {
+		return err
+	}
+	return copyDirEntries(src, dst)
+}
+
+func copyDirEntries(src, dst string) error {
+	if err := vfs.MkdirAll(dst, 0o755); err != nil {
+		return err
+	}
+	entries, err := vfs.ReadDir(src)
+	if err != nil {
+		return err
+	}
+	for _, entry := range entries {
+		srcPath := filepath.Join(src, entry.Name())
+		dstPath := filepath.Join(dst, entry.Name())
+		if entry.IsDir() {
+			if err := copyDirEntries(srcPath, dstPath); err != nil {
+				return err
+			}
+			continue
+		}
+		if err := copyFile(srcPath, dstPath); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func copyFile(src, dst string) error {
+	in, err := vfs.Open(src)
+	if err != nil {
+		return err
+	}
+	defer in.Close()
+	if err := vfs.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+		return err
+	}
+	out, err := vfs.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o644)
+	if err != nil {
+		return err
+	}
+	if _, err := io.Copy(out, in); err != nil {
+		_ = out.Close()
+		return err
+	}
+	return out.Close()
+}
--- a/internal/skillscheck/state.go
+++ b/internal/skillscheck/state.go
@@ -23,10 +23,12 @@ var ErrUnreadableState = errors.New("skills state is unreadable")

 type SkillsState struct {
 	Version              string   `json:"version"`
+	Layout               string   `json:"layout,omitempty"`
 	OfficialSkills       []string `json:"official_skills"`
 	UpdatedSkills        []string `json:"updated_skills"`
 	AddedOfficialSkills  []string `json:"added_official_skills"`
 	SkippedDeletedSkills []string `json:"skipped_deleted_skills"`
+	FlatSkills           []string `json:"flat_skills"`
 	UpdatedAt            string   `json:"updated_at"`
 }

@@ -76,6 +78,14 @@ func ReadSyncedVersion() (string, bool) {
 	return state.Version, true
 }

+func ReadSyncedVersionAndLayout() (version string, layout string, ok bool) {
+	state, readable, err := ReadState()
+	if err != nil || !readable || state.Version == "" {
+		return "", "", false
+	}
+	return state.Version, state.Layout, true
+}
+
 func (s *SkillsState) ensureNonNilSlices() {
 	if s.OfficialSkills == nil {
 		s.OfficialSkills = []string{}
@@ -89,4 +99,7 @@ func (s *SkillsState) ensureNonNilSlices() {
 	if s.SkippedDeletedSkills == nil {
 		s.SkippedDeletedSkills = []string{}
 	}
+	if s.FlatSkills == nil {
+		s.FlatSkills = []string{}
+	}
 }
--- a/internal/skillscheck/state_test.go
+++ b/internal/skillscheck/state_test.go
@@ -32,10 +32,12 @@ func TestReadState_Valid(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	want := SkillsState{
 		Version:              "1.2.3",
+		Layout:               LayoutHybrid,
 		OfficialSkills:       []string{"lark-doc", "lark-im"},
 		UpdatedSkills:        []string{"lark-doc"},
 		AddedOfficialSkills:  []string{"lark-task"},
 		SkippedDeletedSkills: []string{"custom-skill"},
+		FlatSkills:           []string{"lark-doc"},
 		UpdatedAt:            "2026-05-18T10:00:00Z",
 	}
 	data, err := json.Marshal(want)
@@ -115,6 +117,9 @@ func TestWriteState_CreatesDirAndWritesState(t *testing.T) {
 	if got.SkippedDeletedSkills == nil {
 		t.Fatal("skipped_deleted_skills decoded as nil, want empty slice")
 	}
+	if got.FlatSkills == nil {
+		t.Fatal("flat_skills decoded as nil, want empty slice")
+	}
 }

 func TestReadSyncedVersionFromState(t *testing.T) {
@@ -137,3 +142,24 @@ func TestReadSyncedVersionFromState(t *testing.T) {
 		t.Fatalf("ReadSyncedVersion() = (%q, %v), want (\"\", false) for empty version", got, ok)
 	}
 }
+
+func TestReadSyncedVersionAndLayoutFromState(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+
+	if version, layout, ok := ReadSyncedVersionAndLayout(); ok || version != "" || layout != "" {
+		t.Fatalf("ReadSyncedVersionAndLayout() = (%q, %q, %v), want empty result for missing state", version, layout, ok)
+	}
+	if err := WriteState(SkillsState{Version: "1.2.3", Layout: LayoutHybrid}); err != nil {
+		t.Fatal(err)
+	}
+	if version, layout, ok := ReadSyncedVersionAndLayout(); !ok || version != "1.2.3" || layout != LayoutHybrid {
+		t.Fatalf("ReadSyncedVersionAndLayout() = (%q, %q, %v), want (\"1.2.3\", %q, true)", version, layout, ok, LayoutHybrid)
+	}
+	if err := WriteState(SkillsState{Layout: LayoutHybrid}); err != nil {
+		t.Fatal(err)
+	}
+	if version, layout, ok := ReadSyncedVersionAndLayout(); ok || version != "" || layout != "" {
+		t.Fatalf("ReadSyncedVersionAndLayout() = (%q, %q, %v), want empty result for empty version", version, layout, ok)
+	}
+}
--- a/internal/skillscheck/sync.go
+++ b/internal/skillscheck/sync.go
@@ -21,6 +21,7 @@ var (

 type SyncInput struct {
 	Version        string
+	Layout         string
 	OfficialSkills []string
 	LocalSkills    []string
 	PreviousState  *SkillsState
@@ -195,7 +196,18 @@ func parseOfficialSkillsList(lines []string) []string {
 }

 func PlanSync(input SyncInput) SyncPlan {
-	official := uniqueSorted(input.OfficialSkills)
+	official := normalOfficialSkills(input.OfficialSkills)
+	layout, _ := NormalizeLayout(input.Layout)
+	skippedDeleted := deletedOfficialSkills(official, input.LocalSkills, input.PreviousState, input.StateReadable, input.Force, layout)
+	if layout != LayoutSeparate {
+		return SyncPlan{
+			Version:        input.Version,
+			OfficialSkills: official,
+			ToUpdate:       suiteEffectiveSkills(official, toSet(skippedDeleted)),
+			Added:          newlyOfficialSkills(official, input.PreviousState, input.StateReadable),
+			SkippedDeleted: skippedDeleted,
+		}
+	}
 	if input.Force {
 		return SyncPlan{
 			Version:        input.Version,
@@ -208,19 +220,7 @@ func PlanSync(input SyncInput) SyncPlan {

 	officialSet := toSet(official)
 	installedOfficial := intersection(input.LocalSkills, officialSet)
-
-	previousOfficial := []string{}
-	if input.StateReadable && input.PreviousState != nil {
-		previousOfficial = input.PreviousState.OfficialSkills
-	}
-	previousSet := toSet(previousOfficial)
-
-	newAddedOfficial := []string{}
-	for _, skill := range official {
-		if !previousSet[skill] {
-			newAddedOfficial = append(newAddedOfficial, skill)
-		}
-	}
+	newAddedOfficial := newlyOfficialSkills(official, input.PreviousState, input.StateReadable)

 	updateSet := toSet(installedOfficial)
 	for _, skill := range newAddedOfficial {
@@ -229,19 +229,12 @@ func PlanSync(input SyncInput) SyncPlan {
 	toUpdate := sortedKeys(updateSet)
 	updateSet = toSet(toUpdate)

-	skipped := []string{}
-	for _, skill := range official {
-		if !updateSet[skill] {
-			skipped = append(skipped, skill)
-		}
-	}
-
 	return SyncPlan{
 		Version:        input.Version,
 		OfficialSkills: official,
 		ToUpdate:       toUpdate,
-		Added:          uniqueSorted(newAddedOfficial),
-		SkippedDeleted: skipped,
+		Added:          newAddedOfficial,
+		SkippedDeleted: skippedDeleted,
 	}
 }

@@ -252,13 +245,16 @@ type SkillsRunner interface {
 	ListGlobalSkills() *selfupdate.NpmResult
 	InstallSkill(nameList []string) *selfupdate.NpmResult
 	InstallAllSkills() *selfupdate.NpmResult
+	InstallSuiteSkill() *selfupdate.NpmResult
 }

 type SyncOptions struct {
-	Version string
-	Force   bool
-	Runner  SkillsRunner
-	Now     func() time.Time
+	Version    string
+	Layout     string
+	FlatSkills []string
+	Force      bool
+	Runner     SkillsRunner
+	Now        func() time.Time
 }

 type SyncResult struct {
@@ -271,6 +267,9 @@ type SyncResult struct {
 	Err            error
 	Detail         string
 	Force          bool
+	Layout         string
+	Flat           []string
+	Collected      []string
 }

 func SyncSkills(opts SyncOptions) *SyncResult {
@@ -280,16 +279,26 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	if opts.Runner == nil {
 		return &SyncResult{Action: "failed", Err: fmt.Errorf("skills runner is nil")}
 	}
+	layout, ok := NormalizeLayout(opts.Layout)
+	if !ok {
+		return &SyncResult{Action: "failed", Err: fmt.Errorf("unsupported skills layout %q", opts.Layout)}
+	}

 	// --- Step 1: List official skills ---
 	official, reason, ok := listOfficialSkills(opts.Runner)
 	if !ok {
+		if layout != LayoutSeparate {
+			return failedSync(layout, opts.Force, fmt.Errorf("failed to discover official skills for %s layout: %s", layout, reason), reason)
+		}
 		return fallbackFullInstall(opts, reason, nil)
 	}

 	// --- Step 2: List local (installed) skills ---
 	local, ok := listLocalSkills(opts.Runner)
 	if !ok {
+		if layout != LayoutSeparate {
+			return failedSync(layout, opts.Force, fmt.Errorf("failed to list local skills for %s layout", layout), "local skills list failed or parsed as empty")
+		}
 		return fallbackFullInstall(opts, "local skills list failed or parsed as empty", official)
 	}

@@ -302,12 +311,17 @@ func SyncSkills(opts SyncOptions) *SyncResult {

 	plan := PlanSync(SyncInput{
 		Version:        opts.Version,
+		Layout:         layout,
 		OfficialSkills: official,
 		LocalSkills:    local,
 		PreviousState:  previous,
 		StateReadable:  readable,
 		Force:          opts.Force,
 	})
+	flat, collected, err := resolveHybridSkillSets(layout, opts.FlatSkills, plan.OfficialSkills, plan.SkippedDeleted)
+	if err != nil {
+		return &SyncResult{Action: "failed", Err: err, Official: plan.OfficialSkills, Force: opts.Force, Layout: layout}
+	}

 	result := &SyncResult{
 		Action:         "synced",
@@ -316,25 +330,59 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 		Added:          plan.Added,
 		SkippedDeleted: plan.SkippedDeleted,
 		Force:          opts.Force,
+		Layout:         layout,
+		Flat:           flat,
+		Collected:      collected,
 	}

 	if len(plan.ToUpdate) == 0 {
+		if layout != LayoutSeparate {
+			return failedSync(layout, opts.Force, fmt.Errorf("no target skills to assemble %s layout", layout), "toUpdate skills empty")
+		}
 		return fallbackFullInstall(opts, "toUpdate skills empty fallback", official)
 	}

 	if len(plan.ToUpdate) > 0 {
 		installResult := opts.Runner.InstallSkill(plan.ToUpdate)
 		if installResult == nil || installResult.Err != nil {
+			if layout != LayoutSeparate {
+				return failedSync(layout, opts.Force, fmt.Errorf("failed to install skills for %s layout: %s", layout, resultDetail(installResult)), resultDetail(installResult))
+			}
 			return fallbackFullInstall(opts, resultDetail(installResult), official)
 		}
 	}
+	if layout != LayoutSeparate {
+		installSuiteResult := opts.Runner.InstallSuiteSkill()
+		if installSuiteResult == nil || installSuiteResult.Err != nil {
+			result.Action = "failed"
+			result.Err = fmt.Errorf("failed to install %s from isolated skills source: %s", suiteSkillName, resultDetail(installSuiteResult))
+			result.Detail = resultDetail(installSuiteResult)
+			return result
+		}
+		infosResult := opts.Runner.ListGlobalSkillsJSON()
+		if infosResult == nil || infosResult.Err != nil {
+			result.Action = "failed"
+			result.Err = fmt.Errorf("failed to list installed skills for %s assembly: %s", suiteSkillName, resultDetail(infosResult))
+			result.Detail = resultDetail(infosResult)
+			return result
+		}
+		infos := ParseGlobalSkillInfosJSON(infosResult.Stdout.String())
+		keepSharedTopLevel := layout == LayoutHybrid && len(flat) > 0
+		if err := assembleSuiteLayout(layout, collected, keepSharedTopLevel, infos); err != nil {
+			result.Action = "failed"
+			result.Err = fmt.Errorf("failed to assemble %s layout: %w", layout, err)
+			return result
+		}
+	}

 	state := SkillsState{
 		Version:              opts.Version,
+		Layout:               layout,
 		OfficialSkills:       plan.OfficialSkills,
 		UpdatedSkills:        plan.ToUpdate,
 		AddedOfficialSkills:  plan.Added,
 		SkippedDeletedSkills: plan.SkippedDeleted,
+		FlatSkills:           stateFlatSkills(layout, flat),
 		UpdatedAt:            opts.Now().UTC().Format(time.RFC3339),
 	}
 	if err := WriteState(state); err != nil {
@@ -346,6 +394,16 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	return result
 }

+func failedSync(layout string, force bool, err error, detail string) *SyncResult {
+	return &SyncResult{
+		Action: "failed",
+		Err:    err,
+		Detail: detail,
+		Force:  force,
+		Layout: layout,
+	}
+}
+
 func listOfficialSkills(runner SkillsRunner) ([]string, string, bool) {
 	reasons := []string{}

@@ -383,8 +441,9 @@ func listOfficialSkills(runner SkillsRunner) ([]string, string, bool) {
 func listLocalSkills(runner SkillsRunner) ([]string, bool) {
 	jsonResult := runner.ListGlobalSkillsJSON()
 	if jsonResult != nil && jsonResult.Err == nil {
-		if local := ParseGlobalSkillsJSON(jsonResult.Stdout.String()); len(local) > 0 {
-			return local, true
+		infos, valid := parseGlobalSkillInfosJSON(jsonResult.Stdout.String())
+		if valid {
+			return installedSkillNamesFromInfos(infos), true
 		}
 	}

@@ -411,6 +470,7 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			Err:    fmt.Errorf("full skills install failed: empty result (reason: %s)", reason),
 			Detail: reason,
 			Force:  opts.Force,
+			Layout: LayoutSeparate,
 		}
 	}
 	if installResult.Err != nil {
@@ -419,11 +479,13 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			Err:    fmt.Errorf("full skills install failed: %w (reason: %s)", installResult.Err, reason),
 			Detail: reason + "\n" + resultDetail(installResult),
 			Force:  opts.Force,
+			Layout: LayoutSeparate,
 		}
 	}

 	state := SkillsState{
 		Version:              opts.Version,
+		Layout:               LayoutSeparate,
 		OfficialSkills:       official,
 		UpdatedSkills:        official,
 		AddedOfficialSkills:  official,
@@ -439,6 +501,7 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			SkippedDeleted: []string{},
 			Detail:         reason + "\nstate write failed: " + writeErr.Error(),
 			Force:          opts.Force,
+			Layout:         LayoutSeparate,
 		}
 	}

@@ -450,9 +513,38 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 		SkippedDeleted: []string{},
 		Detail:         reason,
 		Force:          opts.Force,
+		Layout:         LayoutSeparate,
 	}
 }

+func stateFlatSkills(layout string, requested []string) []string {
+	if layout != LayoutHybrid {
+		return []string{}
+	}
+	out := []string{}
+	for _, skill := range uniqueSorted(requested) {
+		if skill != sharedSkillName {
+			out = append(out, skill)
+		}
+	}
+	return out
+}
+
+func newlyOfficialSkills(official []string, previous *SkillsState, stateReadable bool) []string {
+	previousOfficial := []string{}
+	if stateReadable && previous != nil {
+		previousOfficial = previous.OfficialSkills
+	}
+	previousSet := toSet(previousOfficial)
+	added := []string{}
+	for _, skill := range official {
+		if !previousSet[skill] {
+			added = append(added, skill)
+		}
+	}
+	return uniqueSorted(added)
+}
+
 func resultDetail(result *selfupdate.NpmResult) string {
 	if result == nil {
 		return ""
--- a/internal/skillscheck/sync_test.go
+++ b/internal/skillscheck/sync_test.go
@@ -8,6 +8,7 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
+	"sort"
 	"strings"
 	"testing"
 	"time"
@@ -43,6 +44,14 @@ func TestParseOfficialSkillsListAcceptsNonLarkOfficialNames(t *testing.T) {
 	}
 }

+func TestParseFlatSkillsTrimsDeduplicatesAndSorts(t *testing.T) {
+	got := ParseFlatSkills(" lark-doc, lark-im,,lark-doc, lark-base ")
+	want := []string{"lark-base", "lark-doc", "lark-im"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ParseFlatSkills() = %#v, want %#v", got, want)
+	}
+}
+
 func TestParseGlobalSkillsList(t *testing.T) {
 	input := `Global Skills

@@ -216,8 +225,10 @@ type fakeSkillsRunner struct {
 	globalErr        error
 	installErr       error
 	installAllErr    error
+	installSuiteErr  error
 	installed        [][]string
 	installedAll     int
+	installedSuite   int
 	listedIndex      int
 	listedOfficial   int
 	listedGlobalJSON int
@@ -319,6 +330,13 @@ func (f *fakeSkillsRunner) InstallAllSkills() *selfupdate.NpmResult {
 	return r
 }

+func (f *fakeSkillsRunner) InstallSuiteSkill() *selfupdate.NpmResult {
+	f.installedSuite++
+	r := &selfupdate.NpmResult{}
+	r.Err = f.installSuiteErr
+	return r
+}
+
 func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
@@ -472,6 +490,34 @@ func TestSyncSkills_OfficialDiscoveryEmptyFallsBackToFullInstallWithReasons(t *t
 	}
 }

+func TestSyncSkills_HybridOfficialDiscoveryFailureDoesNotFallback(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	runner := &fakeSkillsRunner{
+		officialIndexErr: fmt.Errorf("index unavailable"),
+		officialErr:      fmt.Errorf("list unavailable"),
+	}
+
+	result := SyncSkills(SyncOptions{
+		Version: "1.0.33",
+		Layout:  LayoutHybrid,
+		Runner:  runner,
+		Now:     time.Now,
+	})
+	if result.Action != "failed" {
+		t.Fatalf("SyncSkills() action = %q, want failed", result.Action)
+	}
+	if result.Layout != LayoutHybrid {
+		t.Fatalf("SyncSkills() layout = %q, want %q", result.Layout, LayoutHybrid)
+	}
+	if result.Err == nil || !strings.Contains(result.Err.Error(), "failed to discover official skills for hybrid layout") {
+		t.Fatalf("SyncSkills() err = %v, want hybrid discovery failure", result.Err)
+	}
+	if runner.installedAll != 0 {
+		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
+	}
+}
+
 func TestSyncSkills_ListOfficialFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
@@ -574,7 +620,7 @@ func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
 	}
 }

-func TestSyncSkills_ParseEmptyLocalListsFallBackToFullInstall(t *testing.T) {
+func TestSyncSkills_EmptyGlobalJSONInstallsAllOfficialIncrementally(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
@@ -585,14 +631,15 @@ func TestSyncSkills_ParseEmptyLocalListsFallBackToFullInstall(t *testing.T) {
 	}

 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Action != "fallback_synced" {
-		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
+	if result.Action != "synced" {
+		t.Fatalf("SyncSkills() action = %q, want synced", result.Action)
 	}
-	if len(runner.installed) != 0 {
-		t.Fatalf("installed = %#v, want no incremental installs", runner.installed)
+	if len(runner.installed) != 1 {
+		t.Fatalf("installed = %#v, want one incremental install", runner.installed)
 	}
-	if runner.installedAll != 1 {
-		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
+	assertStrings(t, runner.installed[0], []string{"lark-calendar", "lark-mail"})
+	if runner.installedAll != 0 {
+		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
 	}
 }

@@ -697,6 +744,200 @@ func TestSyncSkills_NilRunnerFails(t *testing.T) {
 	}
 }

+func TestSyncSkills_HybridAssemblesSuiteAndMovesCollectedSkills(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	paths := map[string]string{}
+	for _, name := range []string{"lark-calendar", "lark-doc", "lark-shared", "lark-suite"} {
+		paths[name] = filepath.Join(dir, name)
+		writeTestSkill(t, paths[name], name)
+	}
+
+	runner := &fakeSkillsRunner{
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-doc", "lark-shared"),
+		globalJSONOut:    globalSkillsJSONFromPaths(paths),
+	}
+
+	result := SyncSkills(SyncOptions{
+		Version:    "1.0.33",
+		Layout:     LayoutHybrid,
+		FlatSkills: []string{"lark-calendar"},
+		Runner:     runner,
+		Now:        time.Now,
+	})
+
+	if result.Err != nil {
+		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
+	}
+	if runner.installedSuite != 1 {
+		t.Fatalf("installedSuite = %d, want 1", runner.installedSuite)
+	}
+	assertStrings(t, result.Flat, []string{"lark-calendar"})
+	assertStrings(t, result.Collected, []string{"lark-shared", "lark-doc"})
+	if _, err := os.Stat(filepath.Join(paths["lark-suite"], "references", "subskills", "lark-doc", "SKILL.md")); err != nil {
+		t.Fatalf("suite lark-doc missing: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(paths["lark-suite"], "references", "subskills", "lark-shared", "SKILL.md")); err != nil {
+		t.Fatalf("suite lark-shared missing: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(paths["lark-calendar"], "SKILL.md")); err != nil {
+		t.Fatalf("flat lark-calendar missing: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(paths["lark-doc"], "SKILL.md")); !os.IsNotExist(err) {
+		t.Fatalf("collected lark-doc still exists at top level or unexpected err: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(paths["lark-shared"], "SKILL.md")); err != nil {
+		t.Fatalf("lark-shared should stay top-level when flat set is non-empty: %v", err)
+	}
+
+	state, readable, err := ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Layout != LayoutHybrid {
+		t.Fatalf("state.Layout = %q, want %q", state.Layout, LayoutHybrid)
+	}
+	assertStrings(t, state.FlatSkills, []string{"lark-calendar"})
+}
+
+func TestSyncSkills_HybridCollectsNewOfficialSkillOnNextUpdate(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	paths := map[string]string{}
+	for _, name := range []string{"lark-calendar", "lark-doc", "lark-shared", "lark-suite"} {
+		paths[name] = filepath.Join(dir, name)
+		writeTestSkill(t, paths[name], name)
+	}
+
+	runner := &fakeSkillsRunner{
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-doc", "lark-shared"),
+		globalJSONOut:    globalSkillsJSONFromPaths(paths),
+	}
+	first := SyncSkills(SyncOptions{
+		Version:    "1.0.33",
+		Layout:     LayoutHybrid,
+		FlatSkills: []string{"lark-calendar"},
+		Runner:     runner,
+		Now:        time.Now,
+	})
+	if first.Err != nil {
+		t.Fatalf("first SyncSkills() err = %v, want nil", first.Err)
+	}
+
+	paths["lark-new"] = filepath.Join(dir, "lark-new")
+	for _, name := range []string{"lark-doc", "lark-new", "lark-shared", "lark-suite"} {
+		writeTestSkill(t, paths[name], name)
+	}
+	runner.officialIndexOut = officialSkillsIndexOutput("lark-calendar", "lark-doc", "lark-new", "lark-shared")
+	runner.globalJSONOut = globalSkillsJSONFromPaths(paths)
+
+	second := SyncSkills(SyncOptions{
+		Version:    "1.0.34",
+		Layout:     LayoutHybrid,
+		FlatSkills: []string{"lark-calendar"},
+		Runner:     runner,
+		Now:        time.Now,
+	})
+	if second.Err != nil {
+		t.Fatalf("second SyncSkills() err = %v, want nil", second.Err)
+	}
+	assertStrings(t, second.Added, []string{"lark-new"})
+	assertStrings(t, second.Flat, []string{"lark-calendar"})
+	assertStrings(t, second.Collected, []string{"lark-shared", "lark-doc", "lark-new"})
+
+	if _, err := os.Stat(filepath.Join(paths["lark-suite"], "references", "subskills", "lark-new", "SKILL.md")); err != nil {
+		t.Fatalf("suite lark-new missing: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(paths["lark-new"], "SKILL.md")); !os.IsNotExist(err) {
+		t.Fatalf("new official skill should be collected, top-level path err: %v", err)
+	}
+	data, err := os.ReadFile(filepath.Join(paths["lark-suite"], "SKILL.md"))
+	if err != nil {
+		t.Fatalf("read suite SKILL.md: %v", err)
+	}
+	if !strings.Contains(string(data), "- lark-new: lark-new description") {
+		t.Fatalf("suite SKILL.md missing lark-new route:\n%s", data)
+	}
+
+	state, readable, err := ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
+	}
+	assertStrings(t, state.OfficialSkills, []string{"lark-calendar", "lark-doc", "lark-new", "lark-shared"})
+	assertStrings(t, state.AddedOfficialSkills, []string{"lark-new"})
+	assertStrings(t, state.FlatSkills, []string{"lark-calendar"})
+}
+
+func TestSyncSkills_HybridWithNoFlatSkillsDoesNotKeepSharedTopLevel(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	paths := map[string]string{}
+	for _, name := range []string{"lark-shared", "lark-suite"} {
+		paths[name] = filepath.Join(dir, name)
+		writeTestSkill(t, paths[name], name)
+	}
+
+	runner := &fakeSkillsRunner{
+		officialIndexOut: officialSkillsIndexOutput("lark-shared"),
+		globalJSONOut:    globalSkillsJSONFromPaths(paths),
+	}
+
+	result := SyncSkills(SyncOptions{
+		Version: "1.0.33",
+		Layout:  LayoutHybrid,
+		Runner:  runner,
+		Now:     time.Now,
+	})
+
+	if result.Err != nil {
+		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
+	}
+	if _, err := os.Stat(filepath.Join(paths["lark-shared"], "SKILL.md")); !os.IsNotExist(err) {
+		t.Fatalf("lark-shared should not stay top-level when flat set is empty; err: %v", err)
+	}
+	if result.Flat == nil || len(result.Flat) != 0 {
+		t.Fatalf("result.Flat = %#v, want empty slice", result.Flat)
+	}
+}
+
+func TestSyncSkills_HybridFiltersNonFlatOfficialSkills(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	paths := map[string]string{}
+	for _, name := range []string{"lark-calendar", "lark-shared", "lark-suite"} {
+		paths[name] = filepath.Join(dir, name)
+		writeTestSkill(t, paths[name], name)
+	}
+
+	runner := &fakeSkillsRunner{
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-shared"),
+		globalJSONOut:    globalSkillsJSONFromPaths(paths),
+	}
+
+	result := SyncSkills(SyncOptions{
+		Version:    "1.0.33",
+		Layout:     LayoutHybrid,
+		FlatSkills: []string{"lark-calendar", "lark-missing", "lark-shared"},
+		Runner:     runner,
+		Now:        time.Now,
+	})
+
+	if result.Err != nil {
+		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
+	}
+	assertStrings(t, result.Flat, []string{"lark-calendar"})
+
+	state, readable, err := ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
+	}
+	assertStrings(t, state.FlatSkills, []string{"lark-calendar"})
+}
+
 func TestSyncSkills_ParseEmptyWithNonEmptyStdoutFallsBack(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
@@ -733,6 +974,81 @@ func TestSyncSkills_ParseEmptyWithNonEmptyStdoutAndFullInstallFails(t *testing.T
 	}
 }

+func TestNormalizeSuiteTemplateTextRewritesLegacyFlatSkillWording(t *testing.T) {
+	input := "`lark-shared` 是共享基础能力，不作为 `--collected-skills` 的可选项。为了保证 suite 内子能力可用，hybrid 布局会同时保留顶层 `lark-shared`，并在 `lark-suite/references/subskills/lark-shared/SKILL.md` 中维护一份副本。"
+	got := normalizeSuiteTemplateText(input)
+	if strings.Contains(got, "--collected-skills") {
+		t.Fatalf("normalized text still contains legacy flag: %s", got)
+	}
+	if !strings.Contains(got, "--flat-skills") {
+		t.Fatalf("normalized text missing --flat-skills: %s", got)
+	}
+	if !strings.Contains(got, "只有 hybrid 布局存在平铺 skill 时，顶层才会额外保留一份") {
+		t.Fatalf("normalized text missing current lark-shared rule: %s", got)
+	}
+}
+
+func TestSkillDescriptionSupportsFoldedYAMLScalar(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "SKILL.md")
+	content := `---
+name: lark-whiteboard
+description: >
+  飞书画板：查询和编辑飞书云文档中的画板。
+  当用户需要查看画板内容、导出画板图片、编辑画板时使用此 skill。
+metadata:
+  requires:
+    bins: ["lark-cli"]
+---
+`
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got := skillDescription(path)
+	want := "飞书画板：查询和编辑飞书云文档中的画板。 当用户需要查看画板内容、导出画板图片、编辑画板时使用此 skill。"
+	if got != want {
+		t.Fatalf("skillDescription() = %q, want %q", got, want)
+	}
+}
+
+func TestAssembleSuiteLayoutSeparateIsNoop(t *testing.T) {
+	if err := assembleSuiteLayout(LayoutSeparate, []string{"lark-doc"}, false, nil); err != nil {
+		t.Fatalf("assembleSuiteLayout(separate) err = %v, want nil", err)
+	}
+}
+
+func TestAssembleSuiteLayoutMissingSuiteReturnsError(t *testing.T) {
+	err := assembleSuiteLayout(LayoutHybrid, []string{"lark-doc"}, false, []GlobalSkillInfo{
+		{Name: "lark-doc", Path: filepath.Join(t.TempDir(), "lark-doc")},
+	})
+	if err == nil || !strings.Contains(err.Error(), "lark-suite") {
+		t.Fatalf("assembleSuiteLayout() err = %v, want missing lark-suite error", err)
+	}
+}
+
+func TestCopyDirCopiesNestedFiles(t *testing.T) {
+	root := t.TempDir()
+	src := filepath.Join(root, "src")
+	dst := filepath.Join(root, "dst")
+	if err := os.MkdirAll(filepath.Join(src, "nested"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(src, "nested", "file.txt"), []byte("hello"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := copyDir(src, dst); err != nil {
+		t.Fatalf("copyDir() err = %v, want nil", err)
+	}
+	got, err := os.ReadFile(filepath.Join(dst, "nested", "file.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != "hello" {
+		t.Fatalf("copied file = %q, want hello", string(got))
+	}
+}
+
 func assertStrings(t *testing.T, got, want []string) {
 	t.Helper()
 	if !reflect.DeepEqual(got, want) {
@@ -740,6 +1056,38 @@ func assertStrings(t *testing.T, got, want []string) {
 	}
 }

+func writeTestSkill(t *testing.T, dir, name string) {
+	t.Helper()
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	content := fmt.Sprintf("---\nname: %s\ndescription: %s description\n---\n", name, name)
+	if name == suiteSkillName {
+		content = "---\nname: lark-suite\ndescription: Lark suite\n---\n<!-- LARK_SUITE_ROUTES -->\n"
+	}
+	if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func globalSkillsJSONFromPaths(paths map[string]string) string {
+	names := make([]string, 0, len(paths))
+	for name := range paths {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	var b strings.Builder
+	b.WriteString("[")
+	for i, name := range names {
+		if i > 0 {
+			b.WriteString(",")
+		}
+		fmt.Fprintf(&b, `{"name":%q,"path":%q,"scope":"global","agents":["Codex"]}`, name, paths[name])
+	}
+	b.WriteString("]")
+	return b.String()
+}
+
 func TestSyncSkills_FallbackWithUnknownOfficialWritesMinimalState(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
--- a/isolated-skills/lark-suite/SKILL.md
+++ b/isolated-skills/lark-suite/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: lark-suite
+version: 0.1.0
+description: 飞书/Lark 聚合能力入口：当用户需求涉及本文件列出的任一飞书能力时使用；仅负责选择并加载已安装到本 suite 的 lark-* 子能力，不替代具体子能力的操作细节。
+metadata:
+  requires:
+    bins:
+      - lark-cli
+---
+
+# Lark Suite
+
+你是飞书/Lark 能力的聚合路由层。你的职责是先判断用户要使用哪个 `lark-*` 子能力，再读取并遵循对应子能力的说明。
+
+`lark-suite` 不直接承载具体 API 操作步骤。除非对应子能力已被读取，否则不要仅根据本文件拼命令、猜参数或执行复杂操作。
+
+## 使用流程
+
+1. 根据用户意图从下方路由表选择一个或多个子能力；即使用户尚未提供链接、ID 或具体工作表，也先选择能力，再由子能力询问缺失信息。
+2. 仅使用本文件列出的路由与对应子能力入口，不要遍历或探测其他技能目录。
+3. 如果目标能力未列出，返回无法路由的明确提示。
+4. 仅读取当前已选子能力明确要求的前置文件。
+5. 按目标子能力的说明执行；认证、租户、身份、权限和通用排障优先遵循 `lark-shared`。
+
+`lark-shared` 是共享基础能力，不作为 `--flat-skills` 的可选项。为了保证 suite 内子能力可用，它始终会进入 `lark-suite/references/subskills/lark-shared/SKILL.md`；只有 hybrid 布局存在平铺 skill 时，顶层才会额外保留一份 `lark-shared`。
+
+多步任务可以组合多个子能力，但每一步都应由具体子能力驱动。例如“查联系人并发消息”先用 `lark-contact` 解析身份，再用 `lark-im` 发消息。
+
+## 能力路由
+
+根据用户意图从以下条目选择对应子能力；如果一个任务涉及多个能力，按实际操作顺序逐步读取并使用对应子能力。
+
+<!-- LARK_SUITE_ROUTES -->
--- a/shortcuts/drive/drive_pull.go
+++ b/shortcuts/drive/drive_pull.go
@@ -184,7 +184,6 @@ var DrivePull = common.Shortcut{

 		var downloaded, skipped, failed, deletedLocal int
 		downloadFailed := 0
-		aborted := false
 		items := make([]drivePullItem, 0)

 		// Deterministic iteration order for output stability.
@@ -195,7 +194,7 @@ var DrivePull = common.Shortcut{
 		sort.Strings(downloadablePaths)

 		for _, rel := range downloadablePaths {
-			if aborted {
+			if drivePullHasTerminalFailure(items) {
 				break
 			}
 			targetFile := remoteFiles[rel]
@@ -233,7 +232,6 @@ var DrivePull = common.Shortcut{
 				failed++
 				downloadFailed++
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +pull after terminal %s failure: %v\n", item.Phase, err)
 					break
 				}
@@ -300,7 +298,7 @@ var DrivePull = common.Shortcut{
 				"skipped":       skipped,
 				"failed":        failed,
 				"deleted_local": deletedLocal,
-				"aborted":       aborted,
+				"aborted":       drivePullHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -349,6 +347,15 @@ func drivePullFailedItem(relPath, fileToken, sourceID, action, phase string, err
 	return item, decision.Terminal
 }

+func drivePullHasTerminalFailure(items []drivePullItem) bool {
+	for _, item := range items {
+		if driveTerminalBatchErrorClass(item.ErrorClass) {
+			return true
+		}
+	}
+	return false
+}
+
 // drivePullDownload streams one Drive file into the local mirror target and
 // then best-effort aligns the local mtime to Drive's modified_time.
 func drivePullDownload(ctx context.Context, runtime *common.RuntimeContext, fileToken, target, remoteModifiedTime string) error {
--- a/shortcuts/drive/drive_push.go
+++ b/shortcuts/drive/drive_push.go
@@ -35,7 +35,6 @@ type drivePushItem struct {
 	Version    string `json:"version,omitempty"`
 	SizeBytes  int64  `json:"size_bytes,omitempty"`
 	Error      string `json:"error,omitempty"`
-	Hint       string `json:"hint,omitempty"`
 	Phase      string `json:"phase,omitempty"`
 	ErrorClass string `json:"error_class,omitempty"`
 	Code       int    `json:"code,omitempty"`
@@ -49,7 +48,6 @@ type driveBatchFailureDecision struct {
 	Subtype   string
 	Retryable bool
 	Terminal  bool
-	Hint      string
 }

 // DrivePush is a one-way, file-level mirror from a local directory onto a
@@ -242,7 +240,6 @@ var DrivePush = common.Shortcut{
 		// locally and now on Drive too), which is the worst-of-both-worlds
 		// outcome the review flagged.
 		uploadFailed := false
-		aborted := false

 		// folderCache holds rel_path → folder_token. Seeded from the remote
 		// listing (so we don't recreate folders that already exist) and
@@ -269,7 +266,6 @@ var DrivePush = common.Shortcut{
 				failed++
 				uploadFailed = true
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, ensureErr)
 					break
 				}
@@ -288,7 +284,7 @@ var DrivePush = common.Shortcut{

 		for _, rel := range localPaths {
 			localFile := localFiles[rel]
-			if uploadFailed && aborted {
+			if uploadFailed && drivePushHasTerminalFailure(items) {
 				break
 			}

@@ -305,7 +301,6 @@ var DrivePush = common.Shortcut{
 					failed++
 					uploadFailed = true
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, parentErr)
 						break
 					}
@@ -337,7 +332,6 @@ var DrivePush = common.Shortcut{
 					failed++
 					uploadFailed = true
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, upErr)
 						break
 					}
@@ -356,7 +350,6 @@ var DrivePush = common.Shortcut{
 				failed++
 				uploadFailed = true
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, ensureErr)
 					break
 				}
@@ -369,7 +362,6 @@ var DrivePush = common.Shortcut{
 				failed++
 				uploadFailed = true
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, upErr)
 					break
 				}
@@ -415,15 +407,10 @@ var DrivePush = common.Shortcut{
 						continue
 					}
 					if err := drivePushDeleteFile(ctx, runtime, entry.FileToken); err != nil {
-						if drivePushIsAlreadyDeleted(err) {
-							items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "already_deleted"})
-							continue
-						}
 						item, terminal := drivePushFailedItem(rel, entry.FileToken, "delete_failed", "delete", 0, err)
 						items = append(items, item)
 						failed++
 						if terminal {
-							aborted = true
 							fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, err)
 							abortDelete = true
 							break
@@ -442,7 +429,7 @@ var DrivePush = common.Shortcut{
 				"skipped":        skipped,
 				"failed":         failed,
 				"deleted_remote": deletedRemote,
-				"aborted":        aborted,
+				"aborted":        drivePushHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -580,7 +567,6 @@ func drivePushFailedItem(relPath, fileToken, action, phase string, sizeBytes int
 		Action:     action,
 		SizeBytes:  sizeBytes,
 		Error:      err.Error(),
-		Hint:       decision.Hint,
 		Phase:      phase,
 		ErrorClass: decision.Class,
 		Code:       decision.Code,
@@ -627,10 +613,6 @@ func driveClassifyBatchFailure(err error) driveBatchFailureDecision {
 		decision.Class = "file_size_limit"
 	case problem.Code == 1062009:
 		decision.Class = "upload_size_mismatch"
-	case problem.Code == 1061044:
-		decision.Class = "parent_node_missing"
-		decision.Terminal = true
-		decision.Hint = "The destination parent folder no longer exists or is not visible. Verify --folder-token, folder permissions, and whether a parent directory was deleted during push before retrying."
 	case problem.Subtype == errs.SubtypeNotFound || problem.Code == 1061007:
 		decision.Class = "remote_not_found"
 	case problem.Subtype == errs.SubtypeServerError || problem.Code == 1061001 || problem.Code == 2200:
@@ -644,9 +626,22 @@ func driveClassifyBatchFailure(err error) driveBatchFailureDecision {
 	return decision
 }

-func drivePushIsAlreadyDeleted(err error) bool {
-	problem, ok := errs.ProblemOf(err)
-	return ok && problem.Code == 1061007
+func drivePushHasTerminalFailure(items []drivePushItem) bool {
+	for _, item := range items {
+		if driveTerminalBatchErrorClass(item.ErrorClass) {
+			return true
+		}
+	}
+	return false
+}
+
+func driveTerminalBatchErrorClass(errorClass string) bool {
+	switch errorClass {
+	case "app_scope_missing", "user_scope_missing", "permission_denied", "invalid_api_parameters", "rate_limited", "server_error":
+		return true
+	default:
+		return false
+	}
 }

 func drivePushRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (map[string]driveRemoteEntry, map[string]driveRemoteEntry, map[string][]driveRemoteEntry, error) {
--- a/shortcuts/drive/drive_push_test.go
+++ b/shortcuts/drive/drive_push_test.go
@@ -732,65 +732,6 @@ func TestDrivePushDeleteRemoteAbortsAfterTerminalFailure(t *testing.T) {
 	}
 }

-func TestDrivePushDeleteRemoteTreatsAlreadyDeletedAsNoop(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_orphan", "name": "orphan.txt", "type": "file"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "DELETE",
-		URL:    "/open-apis/drive/v1/files/tok_orphan",
-		Body: map[string]interface{}{
-			"code": 1061007,
-			"msg":  "file has been delete.",
-		},
-	})
-
-	err := mountAndRunDrive(t, DrivePush, []string{
-		"+push",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--delete-remote",
-		"--yes",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("already-deleted remote should be an idempotent success, got: %v\nstdout: %s", err, stdout.String())
-	}
-
-	summary, items := splitDrivePushStdout(t, stdout.Bytes())
-	if got := summary["failed"]; got != float64(0) {
-		t.Fatalf("summary.failed = %v, want 0", got)
-	}
-	if got := summary["deleted_remote"]; got != float64(0) {
-		t.Fatalf("summary.deleted_remote = %v, want 0 because CLI did not delete it in this run", got)
-	}
-	if len(items) != 1 {
-		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
-	}
-	item := items[0]
-	if item["action"] != "already_deleted" || item["file_token"] != "tok_orphan" {
-		t.Fatalf("unexpected already-deleted item: %#v", item)
-	}
-}
-
 func TestDrivePushNewestOverwritesChosenDuplicateAndDeletesSibling(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())

@@ -1196,78 +1137,6 @@ func TestDrivePushAbortsAfterUploadParamsError(t *testing.T) {
 	}
 }

-func TestDrivePushAbortsAfterUploadParentNodeMissing(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	if err := os.WriteFile(filepath.Join("local", "a.txt"), []byte("A"), 0o644); err != nil {
-		t.Fatalf("WriteFile a: %v", err)
-	}
-	if err := os.WriteFile(filepath.Join("local", "b.txt"), []byte("B"), 0o644); err != nil {
-		t.Fatalf("WriteFile b: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/files/upload_all",
-		Body: map[string]interface{}{
-			"code": 1061044,
-			"msg":  "parent node not exist.",
-		},
-	})
-
-	err := mountAndRunDrive(t, DrivePush, []string{
-		"+push",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--as", "bot",
-	}, f, stdout)
-	if err == nil {
-		t.Fatalf("expected partial failure, got nil\nstdout: %s", stdout.String())
-	}
-	var pfErr *output.PartialFailureError
-	if !errors.As(err, &pfErr) {
-		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
-	}
-	summary, items := splitDrivePushStdout(t, stdout.Bytes())
-	if got := summary["failed"]; got != float64(1) {
-		t.Fatalf("summary.failed = %v, want 1", got)
-	}
-	if got := summary["aborted"]; got != true {
-		t.Fatalf("summary.aborted = %v, want true", got)
-	}
-	if len(items) != 1 {
-		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
-	}
-	item := items[0]
-	if item["rel_path"] != "a.txt" || item["phase"] != "upload" || item["error_class"] != "parent_node_missing" {
-		t.Fatalf("unexpected failed item: %#v", item)
-	}
-	if item["code"] != float64(1061044) || item["subtype"] != "not_found" || item["retryable"] != false {
-		t.Fatalf("unexpected failure metadata: %#v", item)
-	}
-	if got, _ := item["hint"].(string); !strings.Contains(got, "--folder-token") || !strings.Contains(got, "parent") {
-		t.Fatalf("hint should point at the destination parent folder, got item=%#v", item)
-	}
-	for _, item := range items {
-		if item["rel_path"] == "b.txt" {
-			t.Fatalf("parent-node missing must abort before b.txt, got items=%#v", items)
-		}
-	}
-}
-
 func TestDrivePushAbortsAfterCreateFolderMissingScope(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())

--- a/shortcuts/drive/drive_sync.go
+++ b/shortcuts/drive/drive_sync.go
@@ -268,7 +268,6 @@ var DriveSync = common.Shortcut{

 		// --- Phase 2: Execute sync operations ---
 		var pulled, pushed, skipped, failed int
-		aborted := false
 		items := make([]driveSyncItem, 0)

 		// Build push infrastructure: local walk for push + remote views + folder cache.
@@ -287,21 +286,16 @@ var DriveSync = common.Shortcut{
 		// Mirror local directory structure first (same as +push), so
 		// empty local directories are not silently dropped.
 		for _, relDir := range localDirs {
-			if aborted {
+			if driveSyncHasTerminalFailure(items) {
 				break
 			}
 			if _, alreadyRemote := folderCache[relDir]; alreadyRemote {
 				continue
 			}
 			if _, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, relDir, folderCache); ensureErr != nil {
-				item, terminal := driveSyncFailedItem(relDir, "", "failed", "push", "create_folder", ensureErr)
+				item, _ := driveSyncFailedItem(relDir, "", "failed", "push", "create_folder", ensureErr)
 				items = append(items, item)
 				failed++
-				if terminal {
-					aborted = true
-					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, ensureErr)
-					break
-				}
 				continue
 			}
 			items = append(items, driveSyncItem{RelPath: relDir, FileToken: folderCache[relDir], Action: "folder_created", Direction: "push"})
@@ -310,7 +304,7 @@ var DriveSync = common.Shortcut{

 		// 2a. Pull new_remote files.
 		for _, entry := range newRemote {
-			if aborted {
+			if driveSyncHasTerminalFailure(items) {
 				break
 			}
 			targetFile, ok := pullRemoteFiles[entry.RelPath]
@@ -324,7 +318,6 @@ var DriveSync = common.Shortcut{
 				items = append(items, item)
 				failed++
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, err)
 					break
 				}
@@ -336,7 +329,7 @@ var DriveSync = common.Shortcut{

 		// 2b. Push new_local files.
 		for _, entry := range newLocal {
-			if aborted {
+			if driveSyncHasTerminalFailure(items) {
 				break
 			}
 			localFile, ok := pushLocalFiles[entry.RelPath]
@@ -348,14 +341,9 @@ var DriveSync = common.Shortcut{
 			parentRel := drivePushParentRel(entry.RelPath)
 			parentToken, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, parentRel, folderCache)
 			if ensureErr != nil {
-				item, terminal := driveSyncFailedItem(entry.RelPath, "", "failed", "push", "create_folder", ensureErr)
+				item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "push", "create_folder", ensureErr)
 				items = append(items, item)
 				failed++
-				if terminal {
-					aborted = true
-					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, ensureErr)
-					break
-				}
 				continue
 			}
 			token, _, upErr := drivePushUploadFile(ctx, runtime, localFile, "", parentToken)
@@ -364,7 +352,6 @@ var DriveSync = common.Shortcut{
 				items = append(items, item)
 				failed++
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, upErr)
 					break
 				}
@@ -376,7 +363,7 @@ var DriveSync = common.Shortcut{

 		// 2c. Resolve modified files by --on-conflict strategy.
 		for _, entry := range modified {
-			if aborted {
+			if driveSyncHasTerminalFailure(items) {
 				break
 			}
 			remoteFile := remoteFiles[entry.RelPath]
@@ -410,7 +397,6 @@ var DriveSync = common.Shortcut{
 					items = append(items, item)
 					failed++
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, err)
 						break
 					}
@@ -429,14 +415,9 @@ var DriveSync = common.Shortcut{
 				}
 				parentToken, parentErr := drivePushEnsureFolder(ctx, runtime, folderToken, drivePushParentRel(entry.RelPath), folderCache)
 				if parentErr != nil {
-					item, terminal := driveSyncFailedItem(entry.RelPath, existingToken, "failed", "push", "create_folder", parentErr)
+					item, _ := driveSyncFailedItem(entry.RelPath, existingToken, "failed", "push", "create_folder", parentErr)
 					items = append(items, item)
 					failed++
-					if terminal {
-						aborted = true
-						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, parentErr)
-						break
-					}
 					continue
 				}
 				token, _, upErr := drivePushUploadFile(ctx, runtime, localFile, existingToken, parentToken)
@@ -454,7 +435,6 @@ var DriveSync = common.Shortcut{
 					items = append(items, item)
 					failed++
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, upErr)
 						break
 					}
@@ -523,7 +503,6 @@ var DriveSync = common.Shortcut{
 					items = append(items, item)
 					failed++
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, downloadErr)
 						break
 					}
@@ -552,7 +531,7 @@ var DriveSync = common.Shortcut{
 				"pushed":  pushed,
 				"skipped": skipped,
 				"failed":  failed,
-				"aborted": aborted,
+				"aborted": driveSyncHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -598,6 +577,15 @@ func driveSyncFailedItem(relPath, fileToken, action, direction, phase string, er
 	return item, decision.Terminal
 }

+func driveSyncHasTerminalFailure(items []driveSyncItem) bool {
+	for _, item := range items {
+		if driveTerminalBatchErrorClass(item.ErrorClass) {
+			return true
+		}
+	}
+	return false
+}
+
 // driveSyncAskConflict prompts the user for a conflict resolution strategy
 // for a single file. Returns the strategy string, or empty string if the
 // user chose to skip.
--- a/shortcuts/markdown/helpers.go
+++ b/shortcuts/markdown/helpers.go
@@ -715,15 +715,9 @@ func markdownUploadProblem(err error, action string) error {
 		case 90003087:
 			appendMarkdownProblemHint(err, "The current tenant or user may not have document capabilities enabled. Ask an administrator to verify document-module access.")
 		case 1061003, 1061044:
-			appendMarkdownProblemHint(err, "Check whether the target folder or wiki node still exists, and verify the parent token type. For Drive folders, pass --folder-token with a Drive folder token/URL; for wiki nodes, pass --wiki-token with a wiki node token/URL.")
+			appendMarkdownProblemHint(err, "Check whether the target folder or wiki node still exists, and verify the token you passed to the command.")
 		case 1061004, 1062501:
 			appendMarkdownProblemHint(err, "Check whether the current identity has write access to the target folder or wiki node.")
-		case 1061101:
-			appendMarkdownProblemHint(err, "The target Drive/wiki storage quota is exhausted. Free space, choose another parent folder/wiki node, or ask an administrator to raise quota before retrying.")
-		case 233523001:
-			appendMarkdownProblemHint(err, "The upstream document service returned a transient server error. Retry later; if it repeats, keep the log_id/request_id for service-side investigation.")
-		case 99991400:
-			appendMarkdownProblemHint(err, "The upload API is rate limited. Stop immediate retries and retry later with exponential backoff.")
 		}
 	}
 	return err
--- a/shortcuts/markdown/markdown_create.go
+++ b/shortcuts/markdown/markdown_create.go
@@ -9,7 +9,6 @@ import (
 	"io"
 	"strings"

-	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )

@@ -31,19 +30,27 @@ var MarkdownCreate = common.Shortcut{
 	Tips: []string{
 		"Omit both --folder-token and --wiki-token to create the Markdown file in the caller's Drive root folder.",
 		"Use --wiki-token <wiki_node_token> to create the Markdown file under a wiki node; the shortcut maps this to parent_type=wiki automatically.",
-		"--folder-token and --wiki-token also accept full Lark URLs and normalize them to the required token.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		spec, err := readMarkdownCreateSpec(runtime)
-		if err != nil {
-			return err
-		}
-		return validateMarkdownSpec(runtime, spec, true)
+		return validateMarkdownSpec(runtime, markdownUploadSpec{
+			FileName:    strings.TrimSpace(runtime.Str("name")),
+			FolderToken: strings.TrimSpace(runtime.Str("folder-token")),
+			WikiToken:   strings.TrimSpace(runtime.Str("wiki-token")),
+			FilePath:    strings.TrimSpace(runtime.Str("file")),
+			FileSet:     runtime.Changed("file"),
+			Content:     runtime.Str("content"),
+			ContentSet:  runtime.Changed("content"),
+		}, true)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		spec, err := readMarkdownCreateSpec(runtime)
-		if err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
+		spec := markdownUploadSpec{
+			FileName:    strings.TrimSpace(runtime.Str("name")),
+			FolderToken: strings.TrimSpace(runtime.Str("folder-token")),
+			WikiToken:   strings.TrimSpace(runtime.Str("wiki-token")),
+			FilePath:    strings.TrimSpace(runtime.Str("file")),
+			FileSet:     runtime.Changed("file"),
+			Content:     runtime.Str("content"),
+			ContentSet:  runtime.Changed("content"),
 		}
 		fileSize, err := markdownSourceSize(runtime, spec)
 		if err != nil {
@@ -64,9 +71,14 @@ var MarkdownCreate = common.Shortcut{
 		return dry
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		spec, err := readMarkdownCreateSpec(runtime)
-		if err != nil {
-			return err
+		spec := markdownUploadSpec{
+			FileName:    strings.TrimSpace(runtime.Str("name")),
+			FolderToken: strings.TrimSpace(runtime.Str("folder-token")),
+			WikiToken:   strings.TrimSpace(runtime.Str("wiki-token")),
+			FilePath:    strings.TrimSpace(runtime.Str("file")),
+			FileSet:     runtime.Changed("file"),
+			Content:     runtime.Str("content"),
+			ContentSet:  runtime.Changed("content"),
 		}
 		fileSize, err := markdownSourceSize(runtime, spec)
 		if err != nil {
@@ -103,139 +115,3 @@ var MarkdownCreate = common.Shortcut{
 		return nil
 	},
 }
-
-func readMarkdownCreateSpec(runtime *common.RuntimeContext) (markdownUploadSpec, error) {
-	spec := markdownUploadSpec{
-		FileName:    strings.TrimSpace(runtime.Str("name")),
-		FolderToken: strings.TrimSpace(runtime.Str("folder-token")),
-		WikiToken:   strings.TrimSpace(runtime.Str("wiki-token")),
-		FilePath:    strings.TrimSpace(runtime.Str("file")),
-		FileSet:     runtime.Changed("file"),
-		Content:     runtime.Str("content"),
-		ContentSet:  runtime.Changed("content"),
-	}
-	return normalizeMarkdownCreateTargetSpec(spec)
-}
-
-func normalizeMarkdownCreateTargetSpec(spec markdownUploadSpec) (markdownUploadSpec, error) {
-	if spec.FolderToken != "" {
-		token, err := normalizeMarkdownFolderToken(spec.FolderToken)
-		if err != nil {
-			return markdownUploadSpec{}, err
-		}
-		spec.FolderToken = token
-	}
-	if spec.WikiToken != "" {
-		token, err := normalizeMarkdownWikiToken(spec.WikiToken)
-		if err != nil {
-			return markdownUploadSpec{}, err
-		}
-		spec.WikiToken = token
-	}
-	return spec, nil
-}
-
-func normalizeMarkdownFolderToken(token string) (string, error) {
-	token = strings.TrimSpace(token)
-	if strings.Contains(token, "://") {
-		ref, ok := common.ParseResourceURL(token)
-		if !ok {
-			return "", markdownValidationParamError("--folder-token", "--folder-token URL is unsupported").
-				WithHint("Pass a Drive folder URL or raw folder token.")
-		}
-		if ref.Type != "folder" {
-			return "", markdownValidationParamError("--folder-token",
-				"--folder-token must identify a Drive folder; got a %s URL",
-				ref.Type,
-			).WithHint("Use --wiki-token for wiki nodes or pass a Drive folder URL/token.")
-		}
-		if err := validateMarkdownTargetTokenName(ref.Token, "--folder-token"); err != nil {
-			return "", err
-		}
-		return ref.Token, nil
-	}
-	if err := rejectMarkdownPartialToken(token, "--folder-token"); err != nil {
-		return "", err
-	}
-	switch markdownKnownResourceTokenKind(token) {
-	case "wiki":
-		return "", markdownValidationParamError("--folder-token", "--folder-token looks like a wiki node token").
-			WithHint("Pass it with --wiki-token instead.")
-	case "doc", "docx", "sheet", "bitable", "mindnote", "slides", "file":
-		return "", markdownValidationParamError("--folder-token", "--folder-token must be a Drive folder token, not a %s token", markdownKnownResourceTokenKind(token))
-	}
-	if err := validateMarkdownTargetTokenName(token, "--folder-token"); err != nil {
-		return "", err
-	}
-	return token, nil
-}
-
-func normalizeMarkdownWikiToken(token string) (string, error) {
-	token = strings.TrimSpace(token)
-	if strings.Contains(token, "://") {
-		ref, ok := common.ParseResourceURL(token)
-		if !ok {
-			return "", markdownValidationParamError("--wiki-token", "--wiki-token URL is unsupported").
-				WithHint("Pass a wiki node URL or raw wiki node token.")
-		}
-		if ref.Type != "wiki" {
-			return "", markdownValidationParamError("--wiki-token",
-				"--wiki-token must identify a wiki node; got a %s URL",
-				ref.Type,
-			).WithHint("Resolve document URLs with `lark-cli wiki +node-get --node-token <url>` and use the returned node_token.")
-		}
-		if err := validateMarkdownTargetTokenName(ref.Token, "--wiki-token"); err != nil {
-			return "", err
-		}
-		return ref.Token, nil
-	}
-	if err := rejectMarkdownPartialToken(token, "--wiki-token"); err != nil {
-		return "", err
-	}
-	if kind := markdownKnownResourceTokenKind(token); kind != "" && kind != "wiki" {
-		return "", markdownValidationParamError("--wiki-token", "--wiki-token must be a wiki node token, not a %s token", kind)
-	}
-	if err := validateMarkdownTargetTokenName(token, "--wiki-token"); err != nil {
-		return "", err
-	}
-	return token, nil
-}
-
-func rejectMarkdownPartialToken(token, flagName string) error {
-	if strings.ContainsAny(token, "/?#") {
-		return markdownValidationParamError(flagName, "%s must be a raw token, not a path, query, or fragment", flagName).
-			WithHint("Pass a full Lark URL, or copy only the token value without path/query/fragment characters.")
-	}
-	return nil
-}
-
-func validateMarkdownTargetTokenName(token, flagName string) error {
-	if err := validate.ResourceName(token, flagName); err != nil {
-		return markdownValidationParamError(flagName, "%s", err).WithCause(err)
-	}
-	return nil
-}
-
-func markdownKnownResourceTokenKind(token string) string {
-	lower := strings.ToLower(strings.TrimSpace(token))
-	switch {
-	case strings.HasPrefix(lower, "wik"):
-		return "wiki"
-	case strings.HasPrefix(lower, "docx"):
-		return "docx"
-	case strings.HasPrefix(lower, "doc"):
-		return "doc"
-	case strings.HasPrefix(lower, "sht"):
-		return "sheet"
-	case strings.HasPrefix(lower, "bas"):
-		return "bitable"
-	case strings.HasPrefix(lower, "mn"):
-		return "mindnote"
-	case strings.HasPrefix(lower, "sld"):
-		return "slides"
-	case strings.HasPrefix(lower, "box"), strings.HasPrefix(lower, "file"):
-		return "file"
-	default:
-		return ""
-	}
-}
--- a/shortcuts/markdown/markdown_test.go
+++ b/shortcuts/markdown/markdown_test.go
@@ -446,173 +446,6 @@ func TestMarkdownCreateDryRunWithWikiToken(t *testing.T) {
 	}
 }

-func TestMarkdownCreateDryRunNormalizesFolderURL(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, markdownTestConfig())
-
-	err := mountAndRunMarkdown(t, MarkdownCreate, []string{
-		"+create",
-		"--name", "README.md",
-		"--content", "# hello",
-		"--folder-token", "https://feishu.cn/drive/folder/fldcnMarkdownTarget",
-		"--dry-run",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"parent_type": "explorer"`) {
-		t.Fatalf("dry-run missing explorer parent_type: %s", out)
-	}
-	if !strings.Contains(out, `"parent_node": "fldcnMarkdownTarget"`) {
-		t.Fatalf("dry-run did not normalize folder URL to token: %s", out)
-	}
-	if strings.Contains(out, "https://feishu.cn/drive/folder/") {
-		t.Fatalf("dry-run leaked raw folder URL instead of token: %s", out)
-	}
-}
-
-func TestMarkdownCreateRejectsWikiURLInFolderToken(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, markdownTestConfig())
-
-	err := mountAndRunMarkdown(t, MarkdownCreate, []string{
-		"+create",
-		"--name", "README.md",
-		"--content", "# hello",
-		"--folder-token", "https://feishu.cn/wiki/wikcnWrongFlag",
-	}, f, stdout)
-	if err == nil {
-		t.Fatalf("expected folder-token URL type error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-	}
-	if !strings.Contains(p.Message, "must identify a Drive folder") || !strings.Contains(p.Hint, "Use --wiki-token") {
-		t.Fatalf("expected folder-token URL type error, got %v", err)
-	}
-}
-
-func TestMarkdownCreateRejectsDocURLInWikiToken(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, markdownTestConfig())
-
-	err := mountAndRunMarkdown(t, MarkdownCreate, []string{
-		"+create",
-		"--name", "README.md",
-		"--content", "# hello",
-		"--wiki-token", "https://feishu.cn/docx/docxWrongFlag",
-	}, f, stdout)
-	if err == nil {
-		t.Fatalf("expected wiki-token URL type error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-	}
-	if !strings.Contains(p.Message, "must identify a wiki node") || !strings.Contains(p.Hint, "+node-get") {
-		t.Fatalf("expected wiki-token URL type error, got %v", err)
-	}
-}
-
-func TestNormalizeMarkdownTargetTokensRejectAmbiguousInputs(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name     string
-		run      func() (string, error)
-		wantMsg  string
-		wantHint string
-	}{
-		{
-			name:     "wiki token passed as folder token",
-			run:      func() (string, error) { return normalizeMarkdownFolderToken("wik_placeholder_wrong") },
-			wantMsg:  "--folder-token looks like a wiki node token",
-			wantHint: "--wiki-token",
-		},
-		{
-			name:     "folder token path fragment",
-			run:      func() (string, error) { return normalizeMarkdownFolderToken("folder_token/child") },
-			wantMsg:  "--folder-token must be a raw token",
-			wantHint: "full Lark URL",
-		},
-		{
-			name:     "doc token passed as wiki token",
-			run:      func() (string, error) { return normalizeMarkdownWikiToken("docx_placeholder_wrong") },
-			wantMsg:  "--wiki-token must be a wiki node token",
-			wantHint: "",
-		},
-		{
-			name:     "wiki token query fragment",
-			run:      func() (string, error) { return normalizeMarkdownWikiToken("wik_placeholder?from=copy") },
-			wantMsg:  "--wiki-token must be a raw token",
-			wantHint: "path/query/fragment",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			_, err := tt.run()
-			if err == nil {
-				t.Fatalf("expected validation error")
-			}
-			p, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-			}
-			if !strings.Contains(p.Message, tt.wantMsg) {
-				t.Fatalf("message = %q, want substring %q", p.Message, tt.wantMsg)
-			}
-			if tt.wantHint != "" && !strings.Contains(p.Hint, tt.wantHint) {
-				t.Fatalf("hint = %q, want substring %q", p.Hint, tt.wantHint)
-			}
-		})
-	}
-}
-
-func TestNormalizeMarkdownTargetTokensAcceptRawTokens(t *testing.T) {
-	t.Parallel()
-
-	folderToken, err := normalizeMarkdownFolderToken("folder_token_raw")
-	if err != nil {
-		t.Fatalf("normalizeMarkdownFolderToken() error = %v", err)
-	}
-	if folderToken != "folder_token_raw" {
-		t.Fatalf("folder token = %q", folderToken)
-	}
-
-	wikiToken, err := normalizeMarkdownWikiToken("wik_placeholder_raw")
-	if err != nil {
-		t.Fatalf("normalizeMarkdownWikiToken() error = %v", err)
-	}
-	if wikiToken != "wik_placeholder_raw" {
-		t.Fatalf("wiki token = %q", wikiToken)
-	}
-}
-
-func TestMarkdownUploadProblemAddsQuotaAndServerHints(t *testing.T) {
-	t.Parallel()
-
-	quotaErr := errs.NewAPIError(errs.SubtypeQuotaExceeded, "file quota exceeded").WithCode(1061101)
-	got := markdownUploadProblem(quotaErr, markdownUploadAllAction)
-	p, ok := errs.ProblemOf(got)
-	if !ok {
-		t.Fatalf("ProblemOf(quotaErr) ok=false")
-	}
-	if !strings.Contains(p.Hint, "storage quota is exhausted") {
-		t.Fatalf("quota hint = %q", p.Hint)
-	}
-
-	serverErr := errs.NewAPIError(errs.SubtypeServerError, "NA").WithCode(233523001).WithRetryable()
-	got = markdownUploadProblem(serverErr, markdownUploadAllAction)
-	p, ok = errs.ProblemOf(got)
-	if !ok {
-		t.Fatalf("ProblemOf(serverErr) ok=false")
-	}
-	if !p.Retryable || !strings.Contains(p.Hint, "transient server error") {
-		t.Fatalf("server retryable=%v hint=%q", p.Retryable, p.Hint)
-	}
-}
-
 func TestMarkdownCreateDryRunReportsSourceFileError(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, markdownTestConfig())

--- a/shortcuts/wiki/wiki_helpers.go
+++ b/shortcuts/wiki/wiki_helpers.go
@@ -6,7 +6,6 @@ package wiki
 import (
 	"strings"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -27,17 +26,3 @@ func wikiNodeURL(brand core.LarkBrand, node *wikiNodeRecord) string {
 	}
 	return common.BuildResourceURL(brand, "wiki", node.NodeToken)
 }
-
-func appendWikiProblemHint(err error, hint string) error {
-	if strings.TrimSpace(hint) == "" {
-		return err
-	}
-	if p, ok := errs.ProblemOf(err); ok {
-		if strings.TrimSpace(p.Hint) != "" {
-			p.Hint = p.Hint + "\n" + hint
-		} else {
-			p.Hint = hint
-		}
-	}
-	return err
-}
--- a/shortcuts/wiki/wiki_list_copy_test.go
+++ b/shortcuts/wiki/wiki_list_copy_test.go
@@ -5,14 +5,12 @@ package wiki

 import (
 	"encoding/json"
-	"errors"
 	"net/http"
 	"net/url"
 	"reflect"
 	"strings"
 	"testing"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -132,147 +130,6 @@ func TestWikiNodeListRequiresSpaceID(t *testing.T) {
 	}
 }

-func TestWikiNodeListRejectsNonNumericSpaceID(t *testing.T) {
-	t.Parallel()
-
-	factory, _, _, _ := cmdutil.TestFactory(t, wikiTestConfig())
-	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "wikcnABC", "--as", "user",
-	}, factory, nil)
-	if err == nil {
-		t.Fatalf("expected numeric space_id validation error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-	}
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) {
-		t.Fatalf("expected ValidationError, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument || validationErr.Param != "--space-id" {
-		t.Fatalf("problem = %#v param=%q, want validation/invalid_argument/--space-id", p, validationErr.Param)
-	}
-	if !strings.Contains(p.Message, "--space-id must be a numeric wiki space_id") || !strings.Contains(p.Hint, "+space-list") {
-		t.Fatalf("expected numeric space_id validation error, got %v", err)
-	}
-}
-
-func TestWikiNodeListRejectsDocumentURLAsParentNodeToken(t *testing.T) {
-	t.Parallel()
-
-	factory, _, _, _ := cmdutil.TestFactory(t, wikiTestConfig())
-	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list",
-		"--space-id", "7211568716812369922",
-		"--parent-node-token", "https://feishu.cn/docx/docxABC",
-		"--as", "user",
-	}, factory, nil)
-	if err == nil {
-		t.Fatalf("expected parent-node-token URL type validation error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-	}
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) {
-		t.Fatalf("expected ValidationError, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument || validationErr.Param != "--parent-node-token" {
-		t.Fatalf("problem = %#v param=%q, want validation/invalid_argument/--parent-node-token", p, validationErr.Param)
-	}
-	if !strings.Contains(p.Message, "must identify a wiki node") || !strings.Contains(p.Hint, "+node-get") {
-		t.Fatalf("expected parent-node-token URL type validation error, got %v", err)
-	}
-}
-
-func TestWikiNodeListNormalizesWikiURLParentNodeToken(t *testing.T) {
-	t.Parallel()
-
-	token, err := normalizeWikiNodeListParentToken("https://feishu.cn/wiki/wikcnPARENT?from=copy")
-	if err != nil {
-		t.Fatalf("normalizeWikiNodeListParentToken() error = %v", err)
-	}
-	if token != "wikcnPARENT" {
-		t.Fatalf("token = %q, want wikcnPARENT", token)
-	}
-}
-
-func TestWikiNodeListRejectsAmbiguousSpaceAndParentTokens(t *testing.T) {
-	t.Parallel()
-
-	if err := validateWikiNodeListSpaceID("https://example.invalid/wiki/space"); err == nil {
-		t.Fatalf("expected URL space-id validation error")
-	} else {
-		p, ok := errs.ProblemOf(err)
-		if !ok {
-			t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-		}
-		if !strings.Contains(p.Message, "not a URL or path") || !strings.Contains(p.Hint, "+space-list") {
-			t.Fatalf("problem = %#v, want URL/path message and +space-list hint", p)
-		}
-	}
-
-	tests := []struct {
-		name    string
-		input   string
-		wantMsg string
-	}{
-		{
-			name:    "partial wiki path",
-			input:   "wik_placeholder/child",
-			wantMsg: "raw wiki node token",
-		},
-		{
-			name:    "document token",
-			input:   "docx_placeholder_parent",
-			wantMsg: "must be a wiki node token",
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			_, err := normalizeWikiNodeListParentToken(tt.input)
-			if err == nil {
-				t.Fatalf("expected parent token validation error")
-			}
-			p, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-			}
-			if !strings.Contains(p.Message, tt.wantMsg) {
-				t.Fatalf("message = %q, want substring %q", p.Message, tt.wantMsg)
-			}
-		})
-	}
-}
-
-func TestWikiNodeListAcceptsEmptyParentToken(t *testing.T) {
-	t.Parallel()
-
-	token, err := normalizeWikiNodeListParentToken("")
-	if err != nil {
-		t.Fatalf("normalizeWikiNodeListParentToken(empty) error = %v", err)
-	}
-	if token != "" {
-		t.Fatalf("token = %q, want empty", token)
-	}
-}
-
-func TestWikiNodeListProblemAddsActionableHint(t *testing.T) {
-	t.Parallel()
-
-	err := errs.NewAPIError(errs.SubtypeInvalidParameters, "param err: invalid page_token").WithCode(131002)
-	got := wikiNodeListProblem(err, nil)
-	p, ok := errs.ProblemOf(got)
-	if !ok {
-		t.Fatalf("ProblemOf() ok=false")
-	}
-	if !strings.Contains(p.Hint, "page token is invalid or stale") {
-		t.Fatalf("hint = %q, want invalid page token guidance", p.Hint)
-	}
-}
-
 func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())

@@ -280,14 +137,14 @@ func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {

 	reg.Register(&httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes",
 		Body: map[string]interface{}{
 			"code": 0,
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":          "7211568716812369922",
+						"space_id":          "space_123",
 						"node_token":        "wik_node_1",
 						"obj_token":         "docx_1",
 						"obj_type":          "docx",
@@ -297,7 +154,7 @@ func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 						"has_child":         true,
 					},
 					map[string]interface{}{
-						"space_id":          "7211568716812369922",
+						"space_id":          "space_123",
 						"node_token":        "wik_node_2",
 						"obj_token":         "docx_2",
 						"obj_type":          "docx",
@@ -313,7 +170,7 @@ func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 	})

 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "7211568716812369922", "--as", "bot",
+		"+node-list", "--space-id", "space_123", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -354,14 +211,14 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {

 	stub := &httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes?page_size=50&parent_node_token=wik_parent",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes?page_size=50&parent_node_token=wik_parent",
 		Body: map[string]interface{}{
 			"code": 0,
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":          "7211568716812369922",
+						"space_id":          "space_123",
 						"node_token":        "wik_child",
 						"obj_token":         "docx_child",
 						"obj_type":          "docx",
@@ -378,7 +235,7 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {
 	reg.Register(stub)

 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "7211568716812369922", "--parent-node-token", "wik_parent", "--as", "bot",
+		"+node-list", "--space-id", "space_123", "--parent-node-token", "wik_parent", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -429,7 +286,7 @@ func TestWikiNodeListResolvesMyLibraryForUser(t *testing.T) {
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"space": map[string]interface{}{
-					"space_id":   "7211568716812369923",
+					"space_id":   "space_personal_42",
 					"name":       "My Library",
 					"space_type": "my_library",
 				},
@@ -439,14 +296,14 @@ func TestWikiNodeListResolvesMyLibraryForUser(t *testing.T) {
 	// Step 2: list nodes in the resolved space.
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369923/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/space_personal_42/nodes",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":   "7211568716812369923",
+						"space_id":   "space_personal_42",
 						"node_token": "wik_personal_1",
 						"title":      "Personal Note",
 					},
@@ -477,8 +334,8 @@ func TestWikiNodeListResolvesMyLibraryForUser(t *testing.T) {
 	if envelope.Meta.Count != 1 {
 		t.Fatalf("meta.count = %v, want 1", envelope.Meta.Count)
 	}
-	if envelope.Data.Nodes[0]["space_id"] != "7211568716812369923" {
-		t.Fatalf("nodes[0].space_id = %v, want 7211568716812369923", envelope.Data.Nodes[0]["space_id"])
+	if envelope.Data.Nodes[0]["space_id"] != "space_personal_42" {
+		t.Fatalf("nodes[0].space_id = %v, want space_personal_42", envelope.Data.Nodes[0]["space_id"])
 	}
 }

@@ -901,21 +758,21 @@ func TestWikiNodeListDefaultIsSinglePage(t *testing.T) {
 	// test pins down the "default = single page" contract.
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"has_more":   true,
 				"page_token": "tok_next",
 				"items": []interface{}{
-					map[string]interface{}{"space_id": "7211568716812369922", "node_token": "wik_1", "title": "First"},
+					map[string]interface{}{"space_id": "space_123", "node_token": "wik_1", "title": "First"},
 				},
 			},
 		},
 	})

 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "7211568716812369922", "--as", "bot",
+		"+node-list", "--space-id", "space_123", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -945,14 +802,14 @@ func TestWikiNodeListPrettyFormatRendersFields(t *testing.T) {
 	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":   "7211568716812369922",
+						"space_id":   "space_123",
 						"node_token": "wik_1",
 						"obj_type":   "docx",
 						"obj_token":  "docx_1",
@@ -965,7 +822,7 @@ func TestWikiNodeListPrettyFormatRendersFields(t *testing.T) {
 	})

 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "7211568716812369922", "--format", "pretty", "--as", "bot",
+		"+node-list", "--space-id", "space_123", "--format", "pretty", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
--- a/shortcuts/wiki/wiki_node_list.go
+++ b/shortcuts/wiki/wiki_node_list.go
@@ -48,19 +48,27 @@ var WikiNodeList = common.Shortcut{
 		"--space-id my_library is a per-user alias and is only valid with --as user.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if _, err := readWikiNodeListSpec(runtime); err != nil {
+		spaceID := strings.TrimSpace(runtime.Str("space-id"))
+		// my_library is a per-user personal-library alias; it has no meaning
+		// for a tenant_access_token (--as bot), so reject early with a clear
+		// hint instead of deferring to API-time errors. Matches the contract
+		// used by +node-create and +move.
+		if runtime.As().IsBot() && spaceID == wikiMyLibrarySpaceID {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "bot identity does not support --space-id my_library; use an explicit --space-id").WithParam("--space-id")
+		}
+		if err := validateOptionalResourceName(spaceID, "--space-id"); err != nil {
+			return err
+		}
+		if err := validateOptionalResourceName(strings.TrimSpace(runtime.Str("parent-node-token")), "--parent-node-token"); err != nil {
 			return err
 		}
 		return validateWikiListPagination(runtime, wikiNodeListMaxPageSize)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		spec, err := readWikiNodeListSpec(runtime)
-		if err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
-		}
+		spaceID := strings.TrimSpace(runtime.Str("space-id"))
 		params := map[string]interface{}{"page_size": runtime.Int("page-size")}
-		if spec.ParentNodeToken != "" {
-			params["parent_node_token"] = spec.ParentNodeToken
+		if pt := strings.TrimSpace(runtime.Str("parent-node-token")); pt != "" {
+			params["parent_node_token"] = pt
 		}
 		if pt := strings.TrimSpace(runtime.Str("page-token")); pt != "" {
 			params["page_token"] = pt
@@ -72,7 +80,7 @@ var WikiNodeList = common.Shortcut{
 		// When the caller passes my_library, +node-list must first resolve it
 		// to the real per-user space_id before listing nodes, mirroring the
 		// two-step orchestration used by +node-create.
-		if spec.SpaceID == wikiMyLibrarySpaceID {
+		if spaceID == wikiMyLibrarySpaceID {
 			return d.
 				Desc("2-step orchestration: resolve my_library -> list nodes").
 				GET("/open-apis/wiki/v2/spaces/my_library").
@@ -83,17 +91,13 @@ var WikiNodeList = common.Shortcut{
 				Set("space_id", "<resolved_space_id>")
 		}
 		return d.
-			GET(fmt.Sprintf("/open-apis/wiki/v2/spaces/%s/nodes", validate.EncodePathSegment(spec.SpaceID))).
+			GET(fmt.Sprintf("/open-apis/wiki/v2/spaces/%s/nodes", validate.EncodePathSegment(spaceID))).
 			Params(params).
-			Set("space_id", spec.SpaceID)
+			Set("space_id", spaceID)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		warnIfConflictingPagingFlags(runtime)
-		spec, err := readWikiNodeListSpec(runtime)
-		if err != nil {
-			return err
-		}
-		spaceID := spec.SpaceID
+		spaceID := strings.TrimSpace(runtime.Str("space-id"))

 		// Resolve the my_library alias to the per-user real space_id before
 		// listing, so the subsequent request hits a concrete space endpoint.
@@ -106,7 +110,7 @@ var WikiNodeList = common.Shortcut{
 			spaceID = resolved
 		}

-		nodes, hasMore, nextToken, err := fetchWikiNodes(runtime, spaceID, spec.ParentNodeToken)
+		nodes, hasMore, nextToken, err := fetchWikiNodes(runtime, spaceID)
 		if err != nil {
 			return err
 		}
@@ -123,104 +127,10 @@ var WikiNodeList = common.Shortcut{
 	},
 }

-type wikiNodeListSpec struct {
-	SpaceID         string
-	ParentNodeToken string
-}
-
-func readWikiNodeListSpec(runtime *common.RuntimeContext) (wikiNodeListSpec, error) {
-	spaceID := strings.TrimSpace(runtime.Str("space-id"))
-	// my_library is a per-user personal-library alias; it has no meaning
-	// for a tenant_access_token (--as bot), so reject early with a clear
-	// hint instead of deferring to API-time errors. Matches the contract
-	// used by +node-create and +move.
-	if runtime.As().IsBot() && spaceID == wikiMyLibrarySpaceID {
-		return wikiNodeListSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "bot identity does not support --space-id my_library; use an explicit numeric --space-id").WithParam("--space-id")
-	}
-	if err := validateWikiNodeListSpaceID(spaceID); err != nil {
-		return wikiNodeListSpec{}, err
-	}
-
-	parentNodeToken, err := normalizeWikiNodeListParentToken(strings.TrimSpace(runtime.Str("parent-node-token")))
-	if err != nil {
-		return wikiNodeListSpec{}, err
-	}
-	return wikiNodeListSpec{SpaceID: spaceID, ParentNodeToken: parentNodeToken}, nil
-}
-
-func validateWikiNodeListSpaceID(spaceID string) error {
-	if spaceID == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--space-id is required").WithParam("--space-id")
-	}
-	if spaceID == wikiMyLibrarySpaceID {
-		return nil
-	}
-	if strings.Contains(spaceID, "://") || strings.ContainsAny(spaceID, "/?#") {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--space-id must be a numeric wiki space_id, not a URL or path",
-		).WithParam("--space-id").WithHint("Run `lark-cli wiki +space-list --as user` to discover space IDs.")
-	}
-	if !isDecimalWikiSpaceID(spaceID) {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--space-id must be a numeric wiki space_id; do not pass a wiki node token, document token, or title",
-		).WithParam("--space-id").WithHint("Run `lark-cli wiki +space-list --as user` to list accessible wiki spaces, then pass the numeric `space_id`.")
-	}
-	if err := validateOptionalResourceName(spaceID, "--space-id"); err != nil {
-		return err
-	}
-	return nil
-}
-
-func isDecimalWikiSpaceID(value string) bool {
-	if value == "" {
-		return false
-	}
-	for _, r := range value {
-		if r < '0' || r > '9' {
-			return false
-		}
-	}
-	return true
-}
-
-func normalizeWikiNodeListParentToken(parentNodeToken string) (string, error) {
-	if parentNodeToken == "" {
-		return "", nil
-	}
-	if strings.Contains(parentNodeToken, "://") {
-		ref, ok := common.ParseResourceURL(parentNodeToken)
-		if !ok {
-			return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--parent-node-token URL is unsupported",
-			).WithParam("--parent-node-token").WithHint("Pass a raw wiki node token from `wiki +node-get` or `wiki +node-list`.")
-		}
-		if ref.Type != "wiki" {
-			return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--parent-node-token must identify a wiki node; got a %s URL",
-				ref.Type,
-			).WithParam("--parent-node-token").WithHint("Resolve the document URL with `lark-cli wiki +node-get --node-token <url>` and use its `node_token`.")
-		}
-		parentNodeToken = ref.Token
-	}
-	if strings.ContainsAny(parentNodeToken, "/?#") {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--parent-node-token must be a raw wiki node token, not a partial URL or path",
-		).WithParam("--parent-node-token")
-	}
-	if !looksLikeWikiNodeToken(parentNodeToken) {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--parent-node-token must be a wiki node token; do not pass a docx/sheet/base/file token",
-		).WithParam("--parent-node-token").WithHint("Run `lark-cli wiki +node-get --node-token <url-or-token>` to resolve a document URL or obj_token to the wiki `node_token` first.")
-	}
-	if err := validateOptionalResourceName(parentNodeToken, "--parent-node-token"); err != nil {
-		return "", err
-	}
-	return parentNodeToken, nil
-}
-
-func fetchWikiNodes(runtime *common.RuntimeContext, spaceID, parentNodeToken string) ([]map[string]interface{}, bool, string, error) {
+func fetchWikiNodes(runtime *common.RuntimeContext, spaceID string) ([]map[string]interface{}, bool, string, error) {
 	pageSize := runtime.Int("page-size")
 	startToken := strings.TrimSpace(runtime.Str("page-token"))
+	parentNodeToken := strings.TrimSpace(runtime.Str("parent-node-token"))
 	auto := wikiListShouldAutoPaginate(runtime)
 	pageLimit := runtime.Int("page-limit")

@@ -243,7 +153,7 @@ func fetchWikiNodes(runtime *common.RuntimeContext, spaceID, parentNodeToken str
 		}
 		data, err := runtime.CallAPITyped("GET", apiPath, params, nil)
 		if err != nil {
-			return nil, false, "", wikiNodeListProblem(err, runtime)
+			return nil, false, "", err
 		}
 		items, _ := data["items"].([]interface{})
 		for _, item := range items {
@@ -267,36 +177,6 @@ func fetchWikiNodes(runtime *common.RuntimeContext, spaceID, parentNodeToken str
 	return nodes, lastHasMore, lastPageToken, nil
 }

-func wikiNodeListProblem(err error, runtime *common.RuntimeContext) error {
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		return err
-	}
-	switch p.Code {
-	case 131002:
-		msg := strings.ToLower(p.Message)
-		switch {
-		case strings.Contains(msg, "page_token"):
-			appendWikiProblemHint(err, "The page token is invalid or stale. Use only the `page_token` returned by the immediately preceding `wiki +node-list` response, or omit --page-token and start over.")
-		case strings.Contains(msg, "space_id"):
-			appendWikiProblemHint(err, "The --space-id value must be the numeric wiki space_id from `wiki +space-list`; do not pass a wiki URL, node token, document token, or title.")
-		default:
-			appendWikiProblemHint(err, "Check the wiki +node-list flags. Fix the parameter before retrying; this is not a transient error.")
-		}
-	case 131005:
-		appendWikiProblemHint(err, "The target wiki space or parent node was not found. Re-discover the space with `wiki +space-list` and the parent with `wiki +node-list`/`wiki +node-get`; do not retry the same stale token.")
-	case 131006:
-		if runtime != nil && runtime.As().IsBot() {
-			appendWikiProblemHint(err, "The bot/app identity cannot read this wiki space or node. Grant the app the required wiki scope and ensure the app or bot has access to the target knowledge space.")
-		} else {
-			appendWikiProblemHint(err, "The current user cannot read this wiki space or node. Switch to a user with access or ask the space owner to grant read permission.")
-		}
-	case 99991400:
-		appendWikiProblemHint(err, "Rate limited by the wiki API. Stop immediate retries and retry later with exponential backoff or a smaller --page-limit.")
-	}
-	return err
-}
-
 func wikiNodeListItem(m map[string]interface{}) map[string]interface{} {
 	return map[string]interface{}{
 		"space_id":          common.GetString(m, "space_id"),
--- a/skills/lark-drive/references/lark-drive-push.md
+++ b/skills/lark-drive/references/lark-drive-push.md
@@ -15,10 +15,9 @@
 | `summary.skipped` | 因 `--if-exists=skip` 或 `--if-exists=smart` 命中“无需传输”而跳过的文件数 |
 | `summary.failed` | 上传 / 覆盖 / 建目录 / 删除失败的条目数；**只要不为 0，命令就以非零状态退出**（结构化 `items[]` 仍在 stdout 上） |
 | `summary.deleted_remote` | 启用 `--delete-remote --yes` 时删除的云端文件数 |
-| `summary.aborted` | 命中终止性错误并停止后续批处理时为 `true` |
-| `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error` / `hint` / `phase` / `error_class` / `code` / `subtype` / `retryable`） |
+| `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error`） |

-`items[].action` 取值：`uploaded` / `overwritten` / `skipped` / `folder_created` / `deleted_remote` / `already_deleted` / `failed` / `delete_failed`。
+`items[].action` 取值：`uploaded` / `overwritten` / `skipped` / `folder_created` / `deleted_remote` / `failed` / `delete_failed`。

 > 本地目录（包括空目录）会被镜像到 Drive；新建的子目录会以 `action: "folder_created"` 出现在 `items[]` 里，但**不计入** `summary.uploaded`（该字段只数文件）。已存在的远端目录复用其 token，不会重复 `create_folder`，也不会出现在 `items[]` 里。

@@ -96,7 +95,6 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 - `--delete-remote`（无 `--yes`）→ Validate 直接报错：`--delete-remote requires --yes`，不会发起任何列表 / 上传 / 删除请求。
 - `--delete-remote --yes` → Validate 阶段还会**动态做一次** `space:document:delete` 的 scope 预检：缺这条 scope 时整次运行立刻失败、不发任何上传请求，避免出现"上传都成功了，但删除阶段才报 missing_scope"的半同步状态。
 - `--delete-remote --yes`（且 scope 已授权）→ 正常执行：先把本地文件 push 上去，再扫一遍远端 `type=file` 列表，把不在本地清单里的逐个删除。**任何上传 / 覆盖 / 建目录失败时，整段 `--delete-remote` 阶段会被跳过**（stderr 上有提示），命令以非零状态退出，远端不会被破坏。
- 删除阶段如果服务端返回 `1061007 file has been delete`，说明目标远端文件在本次 DELETE 前已经不存在；这已经满足 `--delete-remote` 的目标状态，输出会记为 `action: "already_deleted"`，不计入 `summary.failed`，也不计入 `summary.deleted_remote`。
 - 远端同名冲突且使用默认 `fail`，或冲突里混有 folder / 其他非 `type=file` 对象 → 在上传阶段前失败，删除阶段不会运行。
 - 不传 `--delete-remote` → `summary.deleted_remote` 永远是 0；命令对远端"多余"文件视而不见。
 - 在线文档（docx / sheet / bitable / ...）和快捷方式即使本地完全没有同名文件，也**不会**进入删除候选，因为它们从来不进 `summary.uploaded` 的对齐域。
@@ -112,46 +110,22 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
    "uploaded": 0,
    "skipped": 0,
    "failed": 0,
-    "deleted_remote": 0,
-    "aborted": false
+    "deleted_remote": 0
  },
  "items": [
    {"rel_path": "...", "file_token": "...", "action": "folder_created"},
    {"rel_path": "...", "file_token": "...", "action": "uploaded",       "size_bytes": 0},
    {"rel_path": "...", "file_token": "...", "action": "overwritten",    "version": "...", "size_bytes": 0},
    {"rel_path": "...", "file_token": "...", "action": "skipped",        "size_bytes": 0},
-    {"rel_path": "...",                       "action": "failed",        "size_bytes": 0, "error": "...", "hint": "...", "phase": "upload", "error_class": "...", "code": 0, "subtype": "...", "retryable": false},
+    {"rel_path": "...",                       "action": "failed",        "size_bytes": 0, "error": "..."},
    {"rel_path": "...", "file_token": "...", "action": "deleted_remote"},
-    {"rel_path": "...", "file_token": "...", "action": "already_deleted"},
-    {"rel_path": "...", "file_token": "...", "action": "delete_failed",  "error": "...", "hint": "...", "phase": "delete", "error_class": "...", "code": 0, "subtype": "...", "retryable": false}
+    {"rel_path": "...", "file_token": "...", "action": "delete_failed",  "error": "..."}
  ]
 }
 ```

 `rel_path` 始终用 `/` 作为分隔符（跨平台一致）。

-## 失败处理与 agent 行为
-
-`+push` 的失败项带结构化字段，agent 必须优先读 `items[].error_class` / `phase` / `code`，不要只看自然语言 `error` 文本。`summary.aborted=true` 表示命令已经遇到终止性错误并停止后续批处理；这时**不要原样重试**，先修复根因。
-
-常见终止性错误：
-
-| `error_class` | 常见 `code` | 含义 | Agent 应对 |
-|---|---:|---|---|
-| `app_scope_missing` | `99991672` | 应用身份缺少 Drive / 文件夹相关 scope | 停止重试，引导开通错误里列出的应用身份权限，例如 `space:folder:create` 或 `drive:drive` |
-| `user_scope_missing` | `99991679` | 用户身份缺少授权 | 停止重试，走 `lark-cli auth login --scope ...` 补错误里列出的 scope |
-| `permission_denied` | `1061004` / HTTP 403 | 当前身份无权操作目标资源 | 停止重试，检查目标文件夹权限、身份类型（user / bot）和资源可见性 |
-| `invalid_api_parameters` | `1061002` | API 参数被服务端拒绝 | 停止重试，检查 `--folder-token`、覆盖模式、`file_token`、文件名和上传参数；不要对同一参数组合批量重试 |
-| `parent_node_missing` | `1061044` | 上传 / 建目录使用的父文件夹不存在或当前身份不可见 | 停止重试，检查 `--folder-token` 是否仍存在、是否有权限、父目录是否在 push 过程中被删除；不要继续上传同一目录树 |
-| `rate_limited` | `99991400` | 触发频控 | 停止当前批次，退避后再重试 |
-| `server_error` | `1061001` / `2200` | Drive 服务端异常 | 停止当前批次，稍后重试；保留 `log_id` 便于排查 |
-
-非终止但需要解释的状态：
-
- `file_size_limit` / `1061043`：文件超过 Drive 上传限制。不要继续尝试同一文件；改拆分或换存储方式。
- `upload_size_mismatch` / `1062009`：本地文件在上传过程中发生变化，或声明大小与实际读取大小不一致。重新扫描本地文件后再 push。
- `remote_not_found` / `1061007`：一般表示远端文件已不存在。删除阶段的 `1061007` 会被视为 `already_deleted` 成功项；其他阶段需重新列表确认远端状态。
-
 ## 性能注意

 - 默认 `skip` 下，已存在的远端文件一律不碰；`overwrite` 下，重复跑会重传所有命中的同名文件；`smart` 下会按 `modified_time` 跳过已对齐的远端文件，但对“远端更旧”的文件仍会进入覆盖路径，因此它减少的是**不必要的重传**，不是把覆盖风险完全拿掉。
--- a/skills/lark-markdown/SKILL.md
+++ b/skills/lark-markdown/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: lark-markdown
-version: 1.2.2
+version: 1.2.1
 description: "飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。"
 metadata:
  requires:
@@ -25,8 +25,7 @@ metadata:
 - 用户要先拿 Markdown 文件的历史版本号，再做比较/下载/回滚，先用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +version-history`
 - 用户要把本地 Markdown **导入成在线新版文档（docx）**，不要用本 skill，改用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +import --type docx`
 - 用户要对 Markdown 文件做**rename / move / delete / 搜索 / 权限 / 评论**等云空间（云盘/云存储）操作，不要留在本 skill，切到 [`lark-drive`](../lark-drive/SKILL.md)
- `markdown +create` / `+overwrite` 命中 `missing scope`、`permission denied`、`not found`、`quota_exceeded`、`version limit` 时，默认停止重试并按报错 hint 处理；只有 `rate_limit`、`server_error` 或临时网络错误才做有限退避重试。
- `markdown +create` 的目标参数不要猜：Drive 文件夹用 `--folder-token`，Wiki 节点用 `--wiki-token`。如果用户给的是 URL，可以直接传完整 URL；CLI 会归一成 token。不要把 doc/sheet/wiki URL 放进 `--folder-token` 试错。
+- `markdown +create` / `+overwrite` 命中 `missing scope`、`permission denied`、`not found`、`version limit` 时，默认停止重试并按报错 hint 处理；只有 `rate limit` 或临时网络错误才做有限重试。

 ## 核心边界

--- a/skills/lark-markdown/references/lark-markdown-create.md
+++ b/skills/lark-markdown/references/lark-markdown-create.md
@@ -32,21 +32,11 @@ lark-cli markdown +create \
  --folder-token fldcn_xxx \
  --file ./README.md

-# 创建到指定文件夹（可直接传 Drive folder URL）
-lark-cli markdown +create \
-  --folder-token "https://feishu.cn/drive/folder/fldcn_xxx" \
-  --file ./README.md
-
 # 创建到指定 wiki 节点
 lark-cli markdown +create \
  --wiki-token wikcn_xxx \
  --file ./README.md

-# 创建到指定 wiki 节点（可直接传 wiki URL）
-lark-cli markdown +create \
-  --wiki-token "https://feishu.cn/wiki/wikcn_xxx" \
-  --file ./README.md
-
 # 预览底层请求
 lark-cli markdown +create \
  --name README.md \
@@ -58,8 +48,8 @@ lark-cli markdown +create \

 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--folder-token` | 否 | 目标 Drive 文件夹 token 或 Drive folder URL；与 `--wiki-token` 互斥；省略时创建到根目录 |
-| `--wiki-token` | 否 | 目标 wiki 节点 token 或 wiki URL；与 `--folder-token` 互斥；传入后自动映射为 `parent_type=wiki` |
+| `--folder-token` | 否 | 目标 Drive 文件夹 token；与 `--wiki-token` 互斥；省略时创建到根目录 |
+| `--wiki-token` | 否 | 目标 wiki 节点 token；与 `--folder-token` 互斥；传入后自动映射为 `parent_type=wiki` |
 | `--name` | 条件必填 | 文件名，**必须显式带 `.md` 后缀**；使用 `--content` 时必填；使用 `--file` 时可省略，默认取本地文件名 |
 | `--content` | 条件必填 | Markdown 内容；与 `--file` 互斥；支持直接传字符串、`@file`、`-`（stdin） |
 | `--file` | 条件必填 | 本地 `.md` 文件路径；与 `--content` 互斥 |
@@ -68,8 +58,6 @@ lark-cli markdown +create \

 - `--content` 与 `--file` 必须二选一
 - `--folder-token` 与 `--wiki-token` 互斥
- `--folder-token` 只能是 Drive 文件夹；不要传 wiki/doc/sheet/base/file token 或 URL
- `--wiki-token` 只能是 Wiki 节点；如果只有 docx/sheet/base 等文档 URL，先用 `lark-cli wiki +node-get --node-token <url>` 解析出 `node_token`
 - `--name` 必须带 `.md` 后缀
 - `--file` 指向的本地文件名也必须带 `.md` 后缀
 - 传 `--wiki-token` 时，返回值中不会附带 `/file/<token>` URL，因为 wiki 承载文件没有稳定的独立 file URL
@@ -100,14 +88,6 @@ lark-cli markdown +create \
 >
 > **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。

-## 失败处理
-
- `not_found` / `1061044`：父目录或 wiki 节点不存在，或 token 类型放错参数。修正 `--folder-token` / `--wiki-token` 后再试，不要重复提交同一参数。
- `quota_exceeded` / `1061101`：目标存储空间配额已满。释放空间、换父目录/节点或请管理员扩容后再试。
- `permission_denied` / `missing_scope`：区分身份处理。`--as user` 看用户授权和目标 ACL；`--as bot` 看应用 scope 与目标目录/节点 ACL。
- `rate_limit`：停止立即重试，使用退避。
- `server_error` / `233523001`：可以稍后有限重试；若重复出现，保留 `log_id` / request id 给服务端排查。
-
 ## 参考

 - [lark-markdown](../SKILL.md) — Markdown 域总览
--- a/skills/lark-wiki/SKILL.md
+++ b/skills/lark-wiki/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: lark-wiki
-version: 1.0.2
+version: 1.0.1
 description: "飞书知识库：管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。当用户给出 doubao.com 的 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：上传文件到知识库节点下（走 lark-drive）、编辑文档/表格/Base 内容（走 lark-doc / lark-sheets / lark-base）。"
 metadata:
  requires:
@@ -34,8 +34,6 @@ metadata:
  - 用户明确选定后再执行 `lark-cli wiki +delete-space --space-id <ID> --yes`（高风险写操作，必须显式 `--yes`）。
  - 反例：不要把 wiki URL / 名称直接当 `--space-id`（如 `--space-id "https://.../wiki/<wiki_token>"`）；务必先用 `wiki spaces get_node` 解析出 `data.node.space_id` 再传。
 - 用户要在知识库中创建新节点，优先使用 `lark-cli wiki +node-create`。
- 用户要列出 Wiki 节点：先用 `wiki +space-list --as user` 拿数字 `space_id`，再用 `wiki +node-list --space-id <space_id>`。不要把 wiki URL、node token、doc token、名称直接当 `--space-id`。钻子节点时 `--parent-node-token` 必须是 wiki node token；如果用户给的是 docx/sheet/base URL，先用 `wiki +node-get --node-token <url>` 解析出 `node_token`。
- `wiki +node-list` 命中 `invalid_parameters`、`not_found`、`permission_denied` 时，不要重复调用同一参数；按 hint 修 `space_id` / `parent_node_token` / 权限。只有 `rate_limit` 才做退避重试。
 - 用户说“给知识库添加成员/管理员”：先把目标解析成“用户 / 群 / 部门 / 应用”四类之一，再决定 `--member-type`，不要先调 `wiki +member-add` 再根据报错反推类型。
 - 用户说“部门 + bot”：这是已知不支持路径。不要继续尝试 `wiki +member-add --as bot`；直接提示必须改成 `--as user`，或明确告知当前要求无法完成。
 - 用户说“用户 / 群 / 应用 + 添加成员”：先解析对应 ID，再执行 `wiki +member-add`。
--- a/skills/lark-wiki/references/lark-wiki-node-list.md
+++ b/skills/lark-wiki/references/lark-wiki-node-list.md
@@ -11,9 +11,6 @@ lark-cli wiki +node-list --space-id <SPACE_ID>
 # Drill into a sub-directory (still single page by default)
 lark-cli wiki +node-list --space-id <SPACE_ID> --parent-node-token <NODE_TOKEN>

-# Drill with a wiki URL (CLI normalizes /wiki/<token> to node_token)
-lark-cli wiki +node-list --space-id <SPACE_ID> --parent-node-token "https://feishu.cn/wiki/wikcn_xxx"
-
 # Personal document library (user identity only)
 lark-cli wiki +node-list --space-id my_library --as user

@@ -34,8 +31,8 @@ lark-cli wiki +node-list --space-id <SPACE_ID> --format pretty

 | Flag | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
-| `--space-id` | string | **Yes** | — | Numeric wiki space ID. Use `my_library` for personal document library (user only) |
-| `--parent-node-token` | string | No | — | Parent wiki node token, or a `/wiki/<token>` URL; omit to list the space root |
+| `--space-id` | string | **Yes** | — | Wiki space ID. Use `my_library` for personal document library (user only) |
+| `--parent-node-token` | string | No | — | Parent node token; omit to list the space root |
 | `--page-size` | int | No | 50 | Page size, 1-50 |
 | `--page-token` | string | No | — | Page cursor; implies single-page fetch (no auto-pagination) |
 | `--page-all` | bool | No | `false` | Automatically paginate through all pages (capped by `--page-limit`) |
@@ -85,10 +82,6 @@ lark-cli wiki +node-list --space-id 6946843325487912356 --parent-node-token wikc
 ## Notes

 - `--space-id my_library` is a per-user alias and only valid with `--as user`. The shortcut will refuse `--as bot` with `my_library` upfront.
- `--space-id` is a numeric wiki `space_id`. Do not pass a wiki URL, wiki node token, document token, or title. Use `lark-cli wiki +space-list --as user` to discover it.
- `--parent-node-token` must resolve to a wiki node token. If you have a docx/sheet/base/file URL, first run `lark-cli wiki +node-get --node-token <url>` and use the returned `node_token`.
- Treat `invalid_parameters` (`space_id is not int`, `invalid page_token`), `not_found` (`node not found by parent node token`), and `permission_denied` as terminal for the current arguments. Fix the argument or permission before retrying.
- For `rate_limit`, stop immediate retries and retry later with exponential backoff or a smaller `--page-limit`.

 ## Required Scope
Author	SHA1	Message	Date
guokexin.02	38d54119cd	fix: merge main and adapt pnpm suite skills	2026-07-07 17:08:33 +08:00
guokexin.02	95fd8b3a5e	test: improve lark suite skills coverage	2026-07-07 16:20:31 +08:00
guokexin.02	cefa041696	fix: remove standalone skills sync hint	2026-07-07 14:59:22 +08:00
guokexin.02	9ea42d1bc6	fix: filter stale flat skills after official discovery	2026-07-07 14:50:49 +08:00
guokexin.02	d134da8536	fix: use vfs recursion for suite skill copy	2026-07-07 12:56:23 +08:00
guokexin.02	84ac346b74	test: cover hybrid collection for new official skills	2026-07-07 12:42:19 +08:00
guokexin.02	f3017c291e	fix: address lark suite review feedback	2026-07-07 11:43:02 +08:00
guokexin.02	f151ca9ac1	feat: support lark suite hybrid skills layout	2026-07-03 17:43:52 +08:00