feat: support wiki sources in drive export

Change-Id: Ic12b0828a0c148bcd3cb9702c027243ecf0f099a

cmd/update/update.go

@@ -86,13 +86,10 @@ func symArrow() string {
 
 // UpdateOptions holds inputs for the update command.
 type UpdateOptions struct {
-	Factory      *cmdutil.Factory
-	JSON         bool
-	Force        bool
-	Check        bool
-	SkillsLayout string
-	FlatSkills   string
-	FlatSet      bool
+	Factory *cmdutil.Factory
+	JSON    bool
+	Force   bool
+	Check   bool
 }
 
 // NewCmdUpdate creates the update command.
@@ -112,7 +109,6 @@ 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)
 		},
 	}
@@ -120,8 +116,6 @@ 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
@@ -129,9 +123,6 @@ 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()
 
@@ -157,7 +148,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, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
+			skillsResult = runSkillsAndState(updater, io, cur, opts.Force)
 		}
 		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
@@ -218,7 +209,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, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
+	skillsResult := runSkillsAndState(updater, io, cur, opts.Force)
 
 	reason := detect.ManualReason()
 	if opts.JSON {
@@ -237,9 +228,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", selfupdate.NpmPackage, latest)
+		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)
 	} else {
-		fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\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  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
 	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
@@ -308,7 +299,7 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 		return output.ErrBare(output.ExitAPI)
 	}
 
-	skillsResult := runSkillsAndState(updater, io, latest, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
+	skillsResult := runSkillsAndState(updater, io, latest, opts.Force)
 
 	if opts.JSON {
 		result := map[string]interface{}{
@@ -350,25 +341,21 @@ 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, 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 && 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): npm install -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))
 }
 
-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) {
+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) {
 			return nil
 		}
 	}
 	result := syncSkills(skillscheck.SyncOptions{
-		Version:    stateVersion,
-		Layout:     layout,
-		FlatSkills: flat,
-		Force:      force,
-		Runner:     updater,
+		Version: stateVersion,
+		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)
@@ -376,38 +363,6 @@ 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
@@ -454,12 +409,6 @@ 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
 }
 
@@ -470,7 +419,6 @@ 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"
@@ -484,17 +432,10 @@ 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
 }
 
@@ -506,17 +447,13 @@ 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, "  %s\n", skillsFailureHint())
+		fmt.Fprintf(io.ErrOut, "  To retry all official skills: lark-cli update --force\n")
 	case r.Force:
-		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills (%s layout)\n", symOK(), len(r.Official), r.Layout)
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills\n", symOK(), len(r.Official))
 	default:
-		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)
+		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))
 		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)."
-}

cmd/update/update_test.go

@@ -204,9 +204,6 @@ 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) {
@@ -731,8 +728,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("should not suggest standalone skills sync command, 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)
 	}
 }
 
@@ -1136,7 +1133,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", Layout: skillscheck.LayoutSeparate}); err != nil {
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
 		t.Fatal(err)
 	}
 	called := false
@@ -1146,7 +1143,7 @@ func TestRunSkillsAndState_DedupHit(t *testing.T) {
 			return &selfupdate.NpmResult{}
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got != nil {
 		t.Errorf("runSkillsAndState() = %+v, want nil for dedup hit", got)
 	}
@@ -1155,27 +1152,6 @@ 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 {
@@ -1188,7 +1164,7 @@ func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 			return successfulSkillsCommand()(args...)
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState(force=true) = %+v, want successful result", got)
 	}
@@ -1200,7 +1176,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, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with nil Err", got)
 	}
@@ -1211,12 +1187,6 @@ 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) {
@@ -1231,7 +1201,7 @@ func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
 			return r
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with non-nil Err", got)
 	}
@@ -1244,50 +1214,6 @@ 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)
@@ -1568,7 +1494,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, "", "", false)
+	got := runSkillsAndState(&selfupdate.Updater{}, f.IOStreams, "1.0.21", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with write error", got)
 	}

internal/selfupdate/updater.go

@@ -50,8 +50,6 @@ 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.
@@ -330,14 +328,6 @@ 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")
 }

internal/selfupdate/updater_test.go

@@ -208,13 +208,6 @@ 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 {
@@ -245,76 +238,6 @@ 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"}]}`)

internal/skillscheck/layout.go

@@ -1,389 +0,0 @@
-// 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()
-}

internal/skillscheck/state.go

@@ -23,12 +23,10 @@ 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"`
 }
 
@@ -78,14 +76,6 @@ 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{}
@@ -99,7 +89,4 @@ func (s *SkillsState) ensureNonNilSlices() {
 	if s.SkippedDeletedSkills == nil {
 		s.SkippedDeletedSkills = []string{}
 	}
-	if s.FlatSkills == nil {
-		s.FlatSkills = []string{}
-	}
 }

internal/skillscheck/state_test.go

@@ -32,12 +32,10 @@ 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)
@@ -117,9 +115,6 @@ 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) {
@@ -142,24 +137,3 @@ 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)
-	}
-}

internal/skillscheck/sync.go

@@ -21,7 +21,6 @@ var (
 
 type SyncInput struct {
 	Version        string
-	Layout         string
 	OfficialSkills []string
 	LocalSkills    []string
 	PreviousState  *SkillsState
@@ -196,18 +195,7 @@ func parseOfficialSkillsList(lines []string) []string {
 }
 
 func PlanSync(input SyncInput) SyncPlan {
-	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,
-		}
-	}
+	official := uniqueSorted(input.OfficialSkills)
 	if input.Force {
 		return SyncPlan{
 			Version:        input.Version,
@@ -220,7 +208,19 @@ func PlanSync(input SyncInput) SyncPlan {
 
 	officialSet := toSet(official)
 	installedOfficial := intersection(input.LocalSkills, officialSet)
-	newAddedOfficial := newlyOfficialSkills(official, input.PreviousState, input.StateReadable)
+
+	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)
+		}
+	}
 
 	updateSet := toSet(installedOfficial)
 	for _, skill := range newAddedOfficial {
@@ -229,12 +229,19 @@ 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:          newAddedOfficial,
-		SkippedDeleted: skippedDeleted,
+		Added:          uniqueSorted(newAddedOfficial),
+		SkippedDeleted: skipped,
 	}
 }
 
@@ -245,16 +252,13 @@ type SkillsRunner interface {
 	ListGlobalSkills() *selfupdate.NpmResult
 	InstallSkill(nameList []string) *selfupdate.NpmResult
 	InstallAllSkills() *selfupdate.NpmResult
-	InstallSuiteSkill() *selfupdate.NpmResult
 }
 
 type SyncOptions struct {
-	Version    string
-	Layout     string
-	FlatSkills []string
-	Force      bool
-	Runner     SkillsRunner
-	Now        func() time.Time
+	Version string
+	Force   bool
+	Runner  SkillsRunner
+	Now     func() time.Time
 }
 
 type SyncResult struct {
@@ -267,9 +271,6 @@ type SyncResult struct {
 	Err            error
 	Detail         string
 	Force          bool
-	Layout         string
-	Flat           []string
-	Collected      []string
 }
 
 func SyncSkills(opts SyncOptions) *SyncResult {
@@ -279,26 +280,16 @@ 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)
 	}
 
@@ -311,17 +302,12 @@ 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",
@@ -330,59 +316,25 @@ 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 {
@@ -394,16 +346,6 @@ 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{}
 
@@ -441,9 +383,8 @@ func listOfficialSkills(runner SkillsRunner) ([]string, string, bool) {
 func listLocalSkills(runner SkillsRunner) ([]string, bool) {
 	jsonResult := runner.ListGlobalSkillsJSON()
 	if jsonResult != nil && jsonResult.Err == nil {
-		infos, valid := parseGlobalSkillInfosJSON(jsonResult.Stdout.String())
-		if valid {
-			return installedSkillNamesFromInfos(infos), true
+		if local := ParseGlobalSkillsJSON(jsonResult.Stdout.String()); len(local) > 0 {
+			return local, true
 		}
 	}
 
@@ -470,7 +411,6 @@ 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 {
@@ -479,13 +419,11 @@ 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,
@@ -501,7 +439,6 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			SkippedDeleted: []string{},
 			Detail:         reason + "\nstate write failed: " + writeErr.Error(),
 			Force:          opts.Force,
-			Layout:         LayoutSeparate,
 		}
 	}
 
@@ -513,38 +450,9 @@ 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 ""

internal/skillscheck/sync_test.go

@@ -8,7 +8,6 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
-	"sort"
 	"strings"
 	"testing"
 	"time"
@@ -44,14 +43,6 @@ 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
 
@@ -225,10 +216,8 @@ type fakeSkillsRunner struct {
 	globalErr        error
 	installErr       error
 	installAllErr    error
-	installSuiteErr  error
 	installed        [][]string
 	installedAll     int
-	installedSuite   int
 	listedIndex      int
 	listedOfficial   int
 	listedGlobalJSON int
@@ -330,13 +319,6 @@ 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)
@@ -490,34 +472,6 @@ 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)
@@ -620,7 +574,7 @@ func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
 	}
 }
 
-func TestSyncSkills_EmptyGlobalJSONInstallsAllOfficialIncrementally(t *testing.T) {
+func TestSyncSkills_ParseEmptyLocalListsFallBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
@@ -631,15 +585,14 @@ func TestSyncSkills_EmptyGlobalJSONInstallsAllOfficialIncrementally(t *testing.T
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Action != "synced" {
-		t.Fatalf("SyncSkills() action = %q, want synced", result.Action)
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
 	}
-	if len(runner.installed) != 1 {
-		t.Fatalf("installed = %#v, want one incremental install", runner.installed)
+	if len(runner.installed) != 0 {
+		t.Fatalf("installed = %#v, want no incremental installs", runner.installed)
 	}
-	assertStrings(t, runner.installed[0], []string{"lark-calendar", "lark-mail"})
-	if runner.installedAll != 0 {
-		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
 	}
 }
 
@@ -744,200 +697,6 @@ 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)
@@ -974,81 +733,6 @@ 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) {
@@ -1056,38 +740,6 @@ 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)

isolated-skills/lark-suite/SKILL.md

@@ -1,33 +0,0 @@
----
-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 -->

shortcuts/calendar/calendar_create.go

@@ -306,6 +306,9 @@ var CalendarCreate = common.Shortcut{
 			"start":    startStr,
 			"end":      endStr,
 		}
+		if recurrence, _ := event["recurrence"].(string); recurrence != "" {
+			resultData["recurrence"] = recurrence
+		}
 
 		runtime.OutFormat(resultData, nil, func(w io.Writer) {
 			var rows []map[string]interface{}

shortcuts/calendar/calendar_get.go

@@ -0,0 +1,279 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// calendar +get — get a single calendar event detail by calendar_id and event_id
+
+package calendar
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// calendarEventTime mirrors start_time / end_time in the API response.
+type calendarEventTime struct {
+	Date      string `json:"date,omitempty"`
+	Timestamp string `json:"timestamp,omitempty"`
+	Timezone  string `json:"timezone,omitempty"`
+}
+
+// calendarEventVChat mirrors the vchat block in the API response.
+type calendarEventVChat struct {
+	VCType      string `json:"vc_type,omitempty"`
+	IconType    string `json:"icon_type,omitempty"`
+	Description string `json:"description,omitempty"`
+	MeetingURL  string `json:"meeting_url,omitempty"`
+}
+
+// calendarEventLocation mirrors the location block in the API response.
+type calendarEventLocation struct {
+	Name      string  `json:"name,omitempty"`
+	Address   string  `json:"address,omitempty"`
+	Latitude  float64 `json:"latitude,omitempty"`
+	Longitude float64 `json:"longitude,omitempty"`
+}
+
+// calendarEventReminder mirrors a reminder entry.
+type calendarEventReminder struct {
+	Minutes int `json:"minutes"`
+}
+
+// calendarEventOrganizer mirrors event_organizer.
+type calendarEventOrganizer struct {
+	UserID      string `json:"user_id,omitempty"`
+	DisplayName string `json:"display_name,omitempty"`
+}
+
+// calendarEventAttachment mirrors a single attachment entry.
+type calendarEventAttachment struct {
+	FileToken string `json:"file_token,omitempty"`
+	FileSize  string `json:"file_size,omitempty"`
+	Name      string `json:"name,omitempty"`
+}
+
+// calendarEventCheckInTime mirrors check_in_start_time / check_in_end_time.
+type calendarEventCheckInTime struct {
+	TimeType string `json:"time_type,omitempty"`
+	Duration int    `json:"duration"`
+}
+
+// calendarEventCheckIn mirrors event_check_in.
+type calendarEventCheckIn struct {
+	EnableCheckIn       bool                      `json:"enable_check_in"`
+	CheckInStartTime    *calendarEventCheckInTime `json:"check_in_start_time,omitempty"`
+	CheckInEndTime      *calendarEventCheckInTime `json:"check_in_end_time,omitempty"`
+	NeedNotifyAttendees bool                      `json:"need_notify_attendees"`
+}
+
+// calendarEvent mirrors the event object inside the API response.
+type calendarEvent struct {
+	EventID             string                    `json:"event_id,omitempty"`
+	OrganizerCalendarID string                    `json:"organizer_calendar_id,omitempty"`
+	Summary             string                    `json:"summary,omitempty"`
+	Description         string                    `json:"description,omitempty"`
+	StartTime           *calendarEventTime        `json:"start_time,omitempty"`
+	EndTime             *calendarEventTime        `json:"end_time,omitempty"`
+	VChat               *calendarEventVChat       `json:"vchat,omitempty"`
+	Visibility          string                    `json:"visibility,omitempty"`
+	AttendeeAbility     string                    `json:"attendee_ability,omitempty"`
+	FreeBusyStatus      string                    `json:"free_busy_status,omitempty"`
+	SelfRsvpStatus      string                    `json:"self_rsvp_status,omitempty"`
+	Location            *calendarEventLocation    `json:"location,omitempty"`
+	Color               int                       `json:"color,omitempty"`
+	Reminders           []calendarEventReminder   `json:"reminders,omitempty"`
+	Recurrence          string                    `json:"recurrence,omitempty"`
+	Status              string                    `json:"status,omitempty"`
+	IsException         bool                      `json:"is_exception,omitempty"`
+	RecurringEventID    string                    `json:"recurring_event_id,omitempty"`
+	CreateTime          string                    `json:"create_time,omitempty"`
+	EventOrganizer      *calendarEventOrganizer   `json:"event_organizer,omitempty"`
+	AppLink             string                    `json:"app_link,omitempty"`
+	Attachments         []calendarEventAttachment `json:"attachments,omitempty"`
+	EventCheckIn        *calendarEventCheckIn     `json:"event_check_in,omitempty"`
+}
+
+// parseCalendarEvent decodes the API response data into a typed calendarEvent.
+func parseCalendarEvent(data map[string]any) (*calendarEvent, error) {
+	rawEvent, ok := data["event"]
+	if !ok || rawEvent == nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event response missing 'event' field")
+	}
+	raw, err := json.Marshal(rawEvent)
+	if err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event response: marshal failed: %s", err).WithCause(err)
+	}
+	var event calendarEvent
+	if err := json.Unmarshal(raw, &event); err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event response: unmarshal failed: %s", err).WithCause(err)
+	}
+	return &event, nil
+}
+
+// buildCalendarEventOutput converts the typed event into the output map and
+// applies the four transformation rules:
+//  1. create_time -> RFC3339
+//  2. start_time / end_time timestamp -> datetime (RFC3339), drop timestamp
+//  3. flatten event into the top-level result
+//  4. when status != "cancelled", drop status (and adjust all-day end date)
+func buildCalendarEventOutput(event *calendarEvent) (map[string]interface{}, error) {
+	raw, err := json.Marshal(event)
+	if err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event marshal failed: %s", err).WithCause(err)
+	}
+	var out map[string]interface{}
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event unmarshal failed: %s", err).WithCause(err)
+	}
+
+	if ctStr, ok := out["create_time"].(string); ok && ctStr != "" {
+		if ts, err := strconv.ParseInt(ctStr, 10, 64); err == nil {
+			out["create_time"] = time.Unix(ts, 0).Local().Format(time.RFC3339)
+		}
+	}
+
+	if startMap, ok := out["start_time"].(map[string]interface{}); ok {
+		if tsStr, ok := startMap["timestamp"].(string); ok && tsStr != "" {
+			if ts, err := strconv.ParseInt(tsStr, 10, 64); err == nil {
+				startMap["datetime"] = time.Unix(ts, 0).Local().Format(time.RFC3339)
+				delete(startMap, "timestamp")
+			}
+		}
+	}
+	if endMap, ok := out["end_time"].(map[string]interface{}); ok {
+		if tsStr, ok := endMap["timestamp"].(string); ok && tsStr != "" {
+			if ts, err := strconv.ParseInt(tsStr, 10, 64); err == nil {
+				endMap["datetime"] = time.Unix(ts, 0).Local().Format(time.RFC3339)
+				delete(endMap, "timestamp")
+			}
+		}
+		// All-day event: end date is exclusive in the API; rewind by 1s and reformat.
+		if dt, _ := endMap["datetime"].(string); dt == "" {
+			if dateStr, ok := endMap["date"].(string); ok && dateStr != "" {
+				if t, err := time.ParseInLocation("2006-01-02", dateStr, time.UTC); err == nil {
+					endMap["date"] = t.Add(-1 * time.Second).Format("2006-01-02")
+				}
+			}
+		}
+	}
+
+	if status, _ := out["status"].(string); status != "cancelled" {
+		delete(out, "status")
+	}
+
+	return out, nil
+}
+
+// CalendarGet gets a single calendar event detail.
+var CalendarGet = common.Shortcut{
+	Service:     "calendar",
+	Command:     "+get",
+	Description: "Get a single calendar event detail by calendar-id and event-id",
+	Risk:        "read",
+	Scopes:      []string{"calendar:calendar.event:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
+		{Name: "event-id", Desc: "event ID", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
+		for _, flag := range []string{"calendar-id", "event-id"} {
+			if val := strings.TrimSpace(runtime.Str(flag)); val != "" {
+				if err := common.RejectDangerousCharsTyped("--"+flag, val); err != nil {
+					return err
+				}
+			}
+		}
+		eventId := strings.TrimSpace(runtime.Str("event-id"))
+		if eventId == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "event-id cannot be empty").WithParam("--event-id")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		calendarId := strings.TrimSpace(runtime.Str("calendar-id"))
+		d := common.NewDryRunAPI()
+		switch calendarId {
+		case "":
+			d.Desc("(calendar-id omitted) Will use primary calendar")
+			calendarId = "<primary>"
+		case "primary":
+			calendarId = "<primary>"
+		}
+		eventId := strings.TrimSpace(runtime.Str("event-id"))
+		return d.
+			GET("/open-apis/calendar/v4/calendars/:calendar_id/events/:event_id").
+			Set("calendar_id", calendarId).
+			Set("event_id", eventId)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		calendarId := strings.TrimSpace(runtime.Str("calendar-id"))
+		if calendarId == "" {
+			calendarId = PrimaryCalendarIDStr
+		}
+		eventId := strings.TrimSpace(runtime.Str("event-id"))
+
+		data, err := runtime.CallAPITyped("GET",
+			fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s",
+				validate.EncodePathSegment(calendarId),
+				validate.EncodePathSegment(eventId)),
+			nil, nil)
+		if err != nil {
+			return err
+		}
+
+		event, err := parseCalendarEvent(data)
+		if err != nil {
+			return err
+		}
+
+		out, err := buildCalendarEventOutput(event)
+		if err != nil {
+			return err
+		}
+
+		runtime.OutFormat(out, nil, func(w io.Writer) {
+			summary, _ := out["summary"].(string)
+			if summary == "" {
+				summary = "(untitled)"
+			}
+			startMap, _ := out["start_time"].(map[string]interface{})
+			endMap, _ := out["end_time"].(map[string]interface{})
+			startStr, _ := startMap["datetime"].(string)
+			if startStr == "" {
+				startStr, _ = startMap["date"].(string)
+			}
+			endStr, _ := endMap["datetime"].(string)
+			if endStr == "" {
+				endStr, _ = endMap["date"].(string)
+			}
+			eventIdOut, _ := out["event_id"].(string)
+			freeBusyStatus, _ := out["free_busy_status"].(string)
+			selfRsvpStatus, _ := out["self_rsvp_status"].(string)
+			row := map[string]interface{}{
+				"event_id":         eventIdOut,
+				"summary":          summary,
+				"start":            startStr,
+				"end":              endStr,
+				"free_busy_status": freeBusyStatus,
+				"self_rsvp_status": selfRsvpStatus,
+			}
+			output.PrintTable(w, []map[string]interface{}{row})
+			fmt.Fprintln(w)
+		})
+		return nil
+	},
+}

shortcuts/calendar/calendar_test.go

@@ -2304,17 +2304,17 @@ func TestResolveStartEnd_ExplicitValues(t *testing.T) {
 // Shortcuts() registration test
 // ---------------------------------------------------------------------------
 
-func TestShortcuts_Returns9(t *testing.T) {
+func TestShortcuts_Returns10(t *testing.T) {
 	shortcuts := Shortcuts()
-	if len(shortcuts) != 9 {
-		t.Fatalf("expected 9 shortcuts, got %d", len(shortcuts))
+	if len(shortcuts) != 10 {
+		t.Fatalf("expected 10 shortcuts, got %d", len(shortcuts))
 	}
 
 	names := map[string]bool{}
 	for _, s := range shortcuts {
 		names[s.Command] = true
 	}
-	for _, want := range []string{"+agenda", "+create", "+update", "+freebusy", "+room-find", "+rsvp", "+suggestion"} {
+	for _, want := range []string{"+agenda", "+create", "+update", "+freebusy", "+room-find", "+rsvp", "+suggestion", "+get"} {
 		if !names[want] {
 			t.Errorf("missing shortcut %s", want)
 		}
@@ -3178,3 +3178,193 @@ func TestSuggestion_RejectsDangerousTimezone_Typed(t *testing.T) {
 		t.Errorf("param=%q, want --timezone", ve.Param)
 	}
 }
+
+// ---------------------------------------------------------------------------
+// CalendarGet tests
+// ---------------------------------------------------------------------------
+
+func TestGet_Success_FlattensAndConvertsTimes(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_001",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id":    "evt_001",
+					"summary":     "Daily Sync",
+					"create_time": "1602504000",
+					"start_time": map[string]interface{}{
+						"timestamp": "1742515200",
+						"timezone":  "Asia/Shanghai",
+					},
+					"end_time": map[string]interface{}{
+						"timestamp": "1742518800",
+						"timezone":  "Asia/Shanghai",
+					},
+					"status": "confirmed",
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--calendar-id", "cal_test123",
+		"--event-id", "evt_001",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	// Expect flattened — fields appear directly under "data", not under "data.event"
+	if strings.Contains(out, "\"event\": {") {
+		t.Errorf("payload should be flattened (no event wrapper), got: %s", out)
+	}
+	if !strings.Contains(out, "\"event_id\": \"evt_001\"") {
+		t.Errorf("expected event_id in output, got: %s", out)
+	}
+	// status=confirmed should be dropped
+	if strings.Contains(out, "\"status\": \"confirmed\"") {
+		t.Errorf("status should be dropped when not cancelled, got: %s", out)
+	}
+	// timestamp must be replaced with datetime
+	if strings.Contains(out, "\"timestamp\":") {
+		t.Errorf("timestamp should be replaced with datetime, got: %s", out)
+	}
+	if !strings.Contains(out, "\"datetime\":") {
+		t.Errorf("expected datetime in output, got: %s", out)
+	}
+	// create_time must be RFC3339 (contain 'T' and timezone)
+	if !strings.Contains(out, "\"create_time\": \"2020-10-12T") {
+		t.Errorf("expected RFC3339 create_time, got: %s", out)
+	}
+}
+
+func TestGet_CancelledStatus_PreservesStatus(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_002",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id":    "evt_002",
+					"summary":     "Cancelled Meeting",
+					"create_time": "1602504000",
+					"start_time":  map[string]interface{}{"timestamp": "1742515200"},
+					"end_time":    map[string]interface{}{"timestamp": "1742518800"},
+					"status":      "cancelled",
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--calendar-id", "cal_test123",
+		"--event-id", "evt_002",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, "\"status\": \"cancelled\"") {
+		t.Errorf("status should be preserved when cancelled, got: %s", out)
+	}
+}
+
+func TestGet_AllDayEvent_AdjustsEndDate(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	// All-day event: start 2025-03-21, end 2025-03-22 (exclusive in API).
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_003",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id":   "evt_003",
+					"summary":    "All-day",
+					"start_time": map[string]interface{}{"date": "2025-03-21"},
+					"end_time":   map[string]interface{}{"date": "2025-03-22"},
+					"status":     "confirmed",
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--calendar-id", "cal_test123",
+		"--event-id", "evt_003",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	// end date 2025-03-22 should rewind by 1s -> 2025-03-21
+	if !strings.Contains(out, "\"date\": \"2025-03-21\"") {
+		t.Errorf("expected end date adjusted to 2025-03-21, got: %s", out)
+	}
+}
+
+func TestGet_EmptyEventID_Typed(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--event-id", "   ",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("want error for empty event-id")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("want *errs.ValidationError, got %T", err)
+	}
+	if ve.Param != "--event-id" {
+		t.Errorf("param=%q, want --event-id", ve.Param)
+	}
+}
+
+func TestGet_MissingEventField_TypedInternal(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_404",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--calendar-id", "cal_test123",
+		"--event-id", "evt_404",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("want error when event field is missing")
+	}
+	var ie *errs.InternalError
+	if !errors.As(err, &ie) {
+		t.Fatalf("want *errs.InternalError, got %T", err)
+	}
+	if ie.Subtype != errs.SubtypeInvalidResponse {
+		t.Errorf("subtype=%q, want invalid_response", ie.Subtype)
+	}
+}

shortcuts/calendar/shortcuts.go

@@ -17,5 +17,6 @@ func Shortcuts() []common.Shortcut {
 		CalendarSuggestion,
 		CalendarMeeting,
 		CalendarSearchEvent,
+		CalendarGet,
 	}
 }

shortcuts/drive/drive_export.go

@@ -39,7 +39,7 @@ func wrapExportContextErr(err error) error {
 var DriveExport = common.Shortcut{
 	Service:     "drive",
 	Command:     "+export",
-	Description: "Export a doc/docx/sheet/bitable/slides to a local file with limited polling",
+	Description: "Export a doc/docx/sheet/bitable/slides or wiki document to a local file with limited polling",
 	Risk:        "read",
 	Scopes: []string{
 		"docs:document.content:read",
@@ -47,10 +47,12 @@ var DriveExport = common.Shortcut{
 		"docx:document:readonly",
 		"drive:drive.metadata:readonly",
 	},
-	AuthTypes: []string{"user", "bot"},
+	ConditionalScopes: []string{"wiki:node:retrieve"},
+	AuthTypes:         []string{"user", "bot"},
 	Flags: []common.Flag{
-		{Name: "token", Desc: "source document token", Required: true},
-		{Name: "doc-type", Desc: "source document type: doc | docx | sheet | bitable | slides", Required: true, Enum: []string{"doc", "docx", "sheet", "bitable", "slides"}},
+		{Name: "url", Desc: "source document URL; doc type and token are inferred, and wiki URLs are resolved to the underlying document"},
+		{Name: "token", Desc: "source document token; bare tokens require --doc-type, while wiki tokens can use --doc-type wiki or fallback after file-token-invalid"},
+		{Name: "doc-type", Desc: "source document type: doc | docx | sheet | bitable | slides | wiki (required only when --token is a bare token)", Enum: []string{"doc", "docx", "sheet", "bitable", "slides", "wiki"}},
 		{Name: "file-extension", Desc: "export format: docx | pdf | xlsx | csv | markdown | base (bitable only) | pptx (slides only)", Required: true, Enum: []string{"docx", "pdf", "xlsx", "csv", "markdown", "base", "pptx"}},
 		{Name: "sub-id", Desc: "sub-table/sheet ID, required when exporting sheet/bitable as csv"},
 		{Name: "only-schema", Type: "bool", Desc: "export only bitable schema when --doc-type bitable --file-extension base"},
@@ -75,6 +77,7 @@ var DriveExport = common.Shortcut{
 // task and poll, but do not download" — callers that only need the ready file
 // token / status get it back without writing a local file.
 type ExportParams struct {
+	URL           string
 	Token         string
 	DocType       string
 	FileExtension string
@@ -87,6 +90,7 @@ type ExportParams struct {
 
 func (p ExportParams) spec() driveExportSpec {
 	return driveExportSpec{
+		URL:           p.URL,
 		Token:         p.Token,
 		DocType:       p.DocType,
 		FileExtension: p.FileExtension,
@@ -106,6 +110,7 @@ func exportParamsFromFlags(runtime *common.RuntimeContext) ExportParams {
 		outputDir = "."
 	}
 	return ExportParams{
+		URL:           runtime.Str("url"),
 		Token:         runtime.Str("token"),
 		DocType:       runtime.Str("doc-type"),
 		FileExtension: runtime.Str("file-extension"),
@@ -127,60 +132,93 @@ func validateExport(p ExportParams) error {
 
 // PlanExportDryRun builds the dry-run plan for an export without performing I/O.
 func PlanExportDryRun(runtime *common.RuntimeContext, p ExportParams) *common.DryRunAPI {
-	spec := p.spec()
+	spec, source, err := normalizeDriveExportSpecInput(p.spec())
+	if err != nil {
+		return common.NewDryRunAPI().Set("error", err.Error())
+	}
+	if err := validateDriveExportNormalizedSpecForSource(spec, source); err != nil {
+		return common.NewDryRunAPI().Set("error", err.Error())
+	}
+
+	dry := common.NewDryRunAPI()
+	if source.Type == "wiki" {
+		dry.GET("/open-apis/wiki/v2/spaces/get_node").
+			Desc("[0] Resolve wiki node to underlying document token").
+			Params(map[string]interface{}{"token": source.Token})
+		spec.Token = "obj_token_from_step_0"
+		if spec.DocType == "" {
+			spec.DocType = "obj_type_from_step_0"
+		}
+		dry.Set("wiki_token", source.Token)
+	}
+
 	// Markdown export is a special case: docx markdown comes from the V2
 	// docs_ai fetch API directly instead of the Drive export task API.
 	if spec.FileExtension == "markdown" {
 		apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/fetch", validate.EncodePathSegment(spec.Token))
-		dr := common.NewDryRunAPI().
-			Desc("2-step orchestration: fetch docx markdown -> write local file").
+		desc := "2-step orchestration: fetch docx markdown -> write local file"
+		if source.Type == "wiki" {
+			desc = "3-step orchestration: resolve wiki -> fetch docx markdown -> write local file"
+		}
+		dry.Desc(desc).
 			POST(apiPath).
 			Body(map[string]interface{}{
 				"format": "markdown",
 			}).
 			Set("output_dir", p.OutputDir)
 		if name := strings.TrimSpace(p.FileName); name != "" {
-			dr.Set("file_name", ensureExportFileExtension(sanitizeExportFileName(name, spec.Token), spec.FileExtension))
+			dry.Set("file_name", ensureExportFileExtension(sanitizeExportFileName(name, spec.Token), spec.FileExtension))
 		}
-		return dr
+		return dry
 	}
 
-	body := map[string]interface{}{
-		"token":          spec.Token,
-		"type":           spec.DocType,
-		"file_extension": spec.FileExtension,
+	desc := "3-step orchestration: create export task -> limited polling -> download file"
+	if source.Type == "wiki" {
+		desc = "4-step orchestration: resolve wiki -> create export task -> limited polling -> download file"
 	}
-	if strings.TrimSpace(spec.SubID) != "" {
-		body["sub_id"] = spec.SubID
-	}
-	if spec.OnlySchema {
-		body["only_schema"] = true
-	}
-
-	dr := common.NewDryRunAPI().
-		Desc("3-step orchestration: create export task -> limited polling -> download file").
+	dry.Desc(desc).
 		POST("/open-apis/drive/v1/export_tasks").
-		Body(body).
+		Body(buildDriveExportTaskBody(spec)).
 		Set("output_dir", p.OutputDir)
 	if name := strings.TrimSpace(p.FileName); name != "" {
-		dr.Set("file_name", ensureExportFileExtension(sanitizeExportFileName(name, spec.Token), spec.FileExtension))
+		dry.Set("file_name", ensureExportFileExtension(sanitizeExportFileName(name, spec.Token), spec.FileExtension))
 	}
-	return dr
+	if !source.WasURL {
+		dry.Set("wiki_token_fallback", "if export task returns file token invalid, the CLI will resolve --token as a wiki node and retry once")
+	}
+	return dry
 }
 
 // RunExport drives create export task -> bounded poll -> optional download. It
 // is the shared core behind both drive +export and sheets +workbook-export. An
 // empty p.OutputDir skips the download step and returns the ready file token.
 func RunExport(ctx context.Context, runtime *common.RuntimeContext, p ExportParams) error {
-	spec := p.spec()
+	spec, source, err := normalizeDriveExportSpecInput(p.spec())
+	if err != nil {
+		return err
+	}
+	if err := validateDriveExportNormalizedSpecForSource(spec, source); err != nil {
+		return err
+	}
+
 	outputDir := p.OutputDir
 	preferredFileName := strings.TrimSpace(p.FileName)
 	overwrite := p.Overwrite
 
+	var wikiResolution driveExportWikiResolution
+
 	// Markdown export bypasses the async export task and writes the fetched
 	// markdown content directly to disk. Uses the V2 docs_ai fetch API for
 	// higher-quality Lark-flavored Markdown output.
 	if spec.FileExtension == "markdown" {
+		if source.Type == "wiki" {
+			resolvedSpec, resolution, err := resolveDriveExportWikiSource(ctx, runtime, spec, source.Token)
+			if err != nil {
+				return err
+			}
+			spec = resolvedSpec
+			wikiResolution = resolution
+		}
 		fmt.Fprintf(runtime.IO().ErrOut, "Exporting docx as markdown: %s\n", common.MaskToken(spec.Token))
 		apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/fetch", validate.EncodePathSegment(spec.Token))
 		data, err := runtime.CallAPITyped(
@@ -222,21 +260,23 @@ func RunExport(ctx context.Context, runtime *common.RuntimeContext, p ExportPara
 			return err
 		}
 
-		runtime.Out(map[string]interface{}{
+		runtime.Out(annotateDriveExportWikiOutput(map[string]interface{}{
 			"token":          spec.Token,
 			"doc_type":       spec.DocType,
 			"file_extension": spec.FileExtension,
 			"file_name":      filepath.Base(savedPath),
 			"saved_path":     savedPath,
 			"size_bytes":     len(content),
-		}, nil)
+		}, wikiResolution), nil)
 		return nil
 	}
 
-	ticket, err := createDriveExportTask(runtime, spec)
+	ticket, resolvedSpec, resolution, err := createDriveExportTaskWithWikiFallback(ctx, runtime, spec, source)
 	if err != nil {
 		return err
 	}
+	spec = resolvedSpec
+	wikiResolution = resolution
 	fmt.Fprintf(runtime.IO().ErrOut, "Created export task: %s\n", ticket)
 
 	var lastStatus driveExportStatus
@@ -274,7 +314,7 @@ func RunExport(ctx context.Context, runtime *common.RuntimeContext, p ExportPara
 			// no local download (e.g. sheets +workbook-export without an output
 			// path). Skip the download and return the status envelope.
 			if strings.TrimSpace(outputDir) == "" {
-				runtime.Out(map[string]interface{}{
+				runtime.Out(annotateDriveExportWikiOutput(map[string]interface{}{
 					"ticket":         ticket,
 					"token":          spec.Token,
 					"doc_type":       spec.DocType,
@@ -284,7 +324,7 @@ func RunExport(ctx context.Context, runtime *common.RuntimeContext, p ExportPara
 					"file_size":      status.FileSize,
 					"ready":          true,
 					"downloaded":     false,
-				}, nil)
+				}, wikiResolution), nil)
 				return nil
 			}
 
@@ -307,7 +347,7 @@ func RunExport(ctx context.Context, runtime *common.RuntimeContext, p ExportPara
 			out["ticket"] = ticket
 			out["doc_type"] = spec.DocType
 			out["file_extension"] = spec.FileExtension
-			runtime.Out(out, nil)
+			runtime.Out(annotateDriveExportWikiOutput(out, wikiResolution), nil)
 			return nil
 		}
 
@@ -357,7 +397,19 @@ func RunExport(ctx context.Context, runtime *common.RuntimeContext, p ExportPara
 	if preferredFileName != "" {
 		result["file_name"] = ensureExportFileExtension(sanitizeExportFileName(preferredFileName, spec.Token), spec.FileExtension)
 	}
-	runtime.Out(result, nil)
+	runtime.Out(annotateDriveExportWikiOutput(result, wikiResolution), nil)
 	fmt.Fprintf(runtime.IO().ErrOut, "Export task is still in progress. Continue with: %s\n", nextCommand)
 	return nil
 }
+
+func annotateDriveExportWikiOutput(out map[string]interface{}, resolution driveExportWikiResolution) map[string]interface{} {
+	if !resolution.Resolved {
+		return out
+	}
+	out["wiki_token"] = resolution.WikiToken
+	out["wiki_node"] = map[string]interface{}{
+		"obj_token": resolution.ObjToken,
+		"obj_type":  resolution.ObjType,
+	}
+	return out
+}

shortcuts/drive/drive_export_common.go

@@ -27,9 +27,16 @@ var (
 	driveExportPollInterval = 5 * time.Second
 )
 
+const (
+	driveExportResolvedDocTypeValues = "doc, docx, sheet, bitable, slides"
+	driveExportInputDocTypeValues    = driveExportResolvedDocTypeValues + ", wiki"
+	driveExportFileExtensionValues   = "docx, pdf, xlsx, csv, markdown, base, pptx"
+)
+
 // driveExportSpec contains the normalized export request understood by the
 // shortcut and the underlying export task APIs.
 type driveExportSpec struct {
+	URL           string
 	Token         string
 	DocType       string
 	FileExtension string
@@ -37,6 +44,20 @@ type driveExportSpec struct {
 	OnlySchema    bool
 }
 
+type driveExportInputSource struct {
+	Type   string
+	Token  string
+	Param  string
+	WasURL bool
+}
+
+type driveExportWikiResolution struct {
+	Resolved  bool
+	WikiToken string
+	ObjToken  string
+	ObjType   string
+}
+
 // driveExportTaskResultCommand prints the resume command shown when bounded
 // export polling times out locally.
 func driveExportTaskResultCommand(ticket, docToken string) string {
@@ -127,45 +148,49 @@ func (s driveExportStatus) StatusLabel() string {
 // validateDriveExportSpec enforces shortcut-level export constraints before any
 // backend request is sent.
 func validateDriveExportSpec(spec driveExportSpec) error {
-	if err := validate.ResourceName(spec.Token, "--token"); err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+	normalized, source, err := normalizeDriveExportSpecInput(spec)
+	if err != nil {
+		return err
 	}
+	return validateDriveExportNormalizedSpecForSource(normalized, source)
+}
 
+func validateDriveExportNormalizedSpec(spec driveExportSpec) error {
 	switch spec.DocType {
 	case "doc", "docx", "sheet", "bitable", "slides":
 	default:
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --doc-type %q: allowed values are doc, docx, sheet, bitable, slides", spec.DocType).WithParam("--doc-type")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --doc-type %q: allowed values are %s", spec.DocType, driveExportInputDocTypeValues).
+			WithParam("--doc-type").
+			WithHint("use --url when you have a document URL; use --doc-type wiki only with a bare Wiki node token so the CLI can resolve the underlying document type")
+	}
+
+	if err := validate.ResourceName(spec.Token, "--token"); err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
 	}
 
 	switch spec.FileExtension {
 	case "docx", "pdf", "xlsx", "csv", "markdown", "base", "pptx":
 	default:
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --file-extension %q: allowed values are docx, pdf, xlsx, csv, markdown, base, pptx", spec.FileExtension).WithParam("--file-extension")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --file-extension %q: allowed values are %s", spec.FileExtension, driveExportFileExtensionValues).
+			WithParam("--file-extension").
+			WithHint("choose an export format supported by the source type; common choices are docx/pdf for docs, xlsx/csv for sheets, base for bitable, and pptx/pdf for slides")
 	}
 
-	if spec.FileExtension == "markdown" && spec.DocType != "docx" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file-extension markdown only supports --doc-type docx")
-	}
-
-	if spec.FileExtension == "base" && spec.DocType != "bitable" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file-extension base only supports --doc-type bitable")
+	if err := validateDriveExportFormatCompatibility(spec); err != nil {
+		return err
 	}
 
 	if spec.OnlySchema && (spec.DocType != "bitable" || spec.FileExtension != "base") {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--only-schema is only used when exporting bitable as base").WithParam("--only-schema")
-	}
-
-	if spec.FileExtension == "pptx" && spec.DocType != "slides" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file-extension pptx only supports --doc-type slides")
-	}
-
-	if spec.DocType == "slides" && spec.FileExtension != "pptx" && spec.FileExtension != "pdf" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--doc-type slides only supports --file-extension pptx or pdf")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--only-schema is only used when exporting bitable as base").
+			WithParam("--only-schema").
+			WithHint("retry with --doc-type bitable --file-extension base, or remove --only-schema")
 	}
 
 	if strings.TrimSpace(spec.SubID) != "" {
 		if spec.FileExtension != "csv" || (spec.DocType != "sheet" && spec.DocType != "bitable") {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--sub-id is only used when exporting sheet/bitable as csv").WithParam("--sub-id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--sub-id is only used when exporting sheet/bitable as csv").
+				WithParam("--sub-id").
+				WithHint("remove --sub-id, or retry with --doc-type sheet|bitable --file-extension csv")
 		}
 		if err := validate.ResourceName(spec.SubID, "--sub-id"); err != nil {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--sub-id")
@@ -173,15 +198,213 @@ func validateDriveExportSpec(spec driveExportSpec) error {
 	}
 
 	if spec.FileExtension == "csv" && (spec.DocType == "sheet" || spec.DocType == "bitable") && strings.TrimSpace(spec.SubID) == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--sub-id is required when exporting sheet/bitable as csv").WithParam("--sub-id")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--sub-id is required when exporting sheet/bitable as csv").
+			WithParam("--sub-id").
+			WithHint("retry with --sub-id <sheet_id_or_table_id>; if you need the whole workbook, use --file-extension xlsx instead")
 	}
 
 	return nil
 }
 
-// createDriveExportTask starts the asynchronous export job and returns its
-// ticket for subsequent polling.
-func createDriveExportTask(runtime *common.RuntimeContext, spec driveExportSpec) (string, error) {
+func validateDriveExportFormatCompatibility(spec driveExportSpec) error {
+	if driveExportFileExtensionAllowedForDocType(spec.DocType, spec.FileExtension) {
+		return nil
+	}
+	allowed := strings.Join(driveExportAllowedFileExtensions(spec.DocType), ", ")
+	return errs.NewValidationError(
+		errs.SubtypeInvalidArgument,
+		"unsupported export format: --doc-type %s cannot be exported as %s",
+		spec.DocType,
+		spec.FileExtension,
+	).
+		WithParam("--file-extension").
+		WithHint("retry with --file-extension %s. If the token came from a URL, prefer --url so the CLI infers the correct source type before validating the export format", allowed)
+}
+
+func driveExportFileExtensionAllowedForDocType(docType, fileExtension string) bool {
+	for _, allowed := range driveExportAllowedFileExtensions(docType) {
+		if fileExtension == allowed {
+			return true
+		}
+	}
+	return false
+}
+
+func driveExportAllowedFileExtensions(docType string) []string {
+	switch normalizeDriveExportDocType(docType) {
+	case "doc":
+		return []string{"docx", "pdf"}
+	case "docx":
+		return []string{"docx", "pdf", "markdown"}
+	case "sheet":
+		return []string{"xlsx", "csv", "pdf"}
+	case "bitable":
+		return []string{"xlsx", "csv", "base", "pdf"}
+	case "slides":
+		return []string{"pptx", "pdf"}
+	default:
+		return []string{"docx", "pdf", "xlsx", "csv", "markdown", "base", "pptx"}
+	}
+}
+
+func validateDriveExportNormalizedSpecForSource(spec driveExportSpec, source driveExportInputSource) error {
+	if source.Type == "wiki" && spec.DocType == "" {
+		return validateDriveExportPendingWikiSpec(spec, source)
+	}
+	return validateDriveExportNormalizedSpec(spec)
+}
+
+func validateDriveExportPendingWikiSpec(spec driveExportSpec, source driveExportInputSource) error {
+	param := source.Param
+	if param == "" {
+		param = "--token"
+	}
+	if err := validate.ResourceName(spec.Token, param); err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam(param)
+	}
+
+	switch spec.FileExtension {
+	case "docx", "pdf", "xlsx", "csv", "markdown", "base", "pptx":
+	default:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --file-extension %q: allowed values are %s", spec.FileExtension, driveExportFileExtensionValues).
+			WithParam("--file-extension").
+			WithHint("Wiki export format is validated after resolving the Wiki node; choose a format normally supported by the underlying document type")
+	}
+	if spec.OnlySchema && spec.FileExtension != "base" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--only-schema is only used when exporting bitable as base").
+			WithParam("--only-schema").
+			WithHint("retry with --file-extension base, or remove --only-schema")
+	}
+	if strings.TrimSpace(spec.SubID) != "" && spec.FileExtension != "csv" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--sub-id is only used when exporting sheet/bitable as csv").
+			WithParam("--sub-id").
+			WithHint("remove --sub-id, or retry with --file-extension csv if the Wiki node resolves to a sheet/bitable")
+	}
+	if strings.TrimSpace(spec.SubID) != "" {
+		if err := validate.ResourceName(spec.SubID, "--sub-id"); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--sub-id")
+		}
+	}
+	return nil
+}
+
+func normalizeDriveExportSpecInput(spec driveExportSpec) (driveExportSpec, driveExportInputSource, error) {
+	spec.URL = strings.TrimSpace(spec.URL)
+	spec.Token = strings.TrimSpace(spec.Token)
+	spec.DocType = strings.ToLower(strings.TrimSpace(spec.DocType))
+	spec.FileExtension = strings.ToLower(strings.TrimSpace(spec.FileExtension))
+
+	if spec.Token == "" && spec.URL == "" {
+		return spec, driveExportInputSource{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "either --url or --token is required").WithParam("--url")
+	}
+	if spec.Token != "" && spec.URL != "" {
+		return spec, driveExportInputSource{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--url and --token are mutually exclusive").WithParam("--url")
+	}
+
+	source := driveExportInputSource{
+		Type:  spec.DocType,
+		Token: spec.Token,
+		Param: "--token",
+	}
+
+	rawInput := spec.Token
+	inputParam := "--token"
+	if spec.URL != "" {
+		rawInput = spec.URL
+		inputParam = "--url"
+	}
+
+	if ref, ok := common.ParseResourceURL(rawInput); ok {
+		refType := normalizeDriveExportDocType(ref.Type)
+		source = driveExportInputSource{
+			Type:   refType,
+			Token:  ref.Token,
+			Param:  inputParam,
+			WasURL: true,
+		}
+		spec.Token = ref.Token
+		if refType != "wiki" {
+			if !isDriveExportDocType(refType) {
+				return spec, source, errs.NewValidationError(
+					errs.SubtypeInvalidArgument,
+					"%s URL type %q is not supported by drive +export; use a doc/docx/sheet/base/slides/wiki URL or token",
+					inputParam,
+					ref.Type,
+				).WithParam(inputParam)
+			}
+			if spec.DocType == "wiki" {
+				return spec, source, errs.NewValidationError(
+					errs.SubtypeInvalidArgument,
+					"--doc-type wiki conflicts with %s URL type %q",
+					inputParam,
+					refType,
+				).
+					WithParam("--doc-type").
+					WithHint("remove --doc-type when passing --url; the CLI will infer %q from the URL", refType)
+			}
+			if spec.DocType != "" && spec.DocType != refType {
+				return spec, source, errs.NewValidationError(
+					errs.SubtypeInvalidArgument,
+					"--doc-type %q conflicts with %s URL type %q",
+					spec.DocType,
+					inputParam,
+					refType,
+				).WithParam("--doc-type")
+			}
+			spec.DocType = refType
+		} else if spec.DocType == "wiki" {
+			spec.DocType = ""
+		}
+		return spec, source, nil
+	}
+
+	if strings.Contains(rawInput, "://") {
+		return spec, source, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"unsupported %s URL %q: use a recognized Lark document URL",
+			inputParam,
+			rawInput,
+		).WithParam(inputParam)
+	}
+	if spec.URL != "" {
+		return spec, source, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"unsupported --url %q: use a recognized Lark document URL",
+			spec.URL,
+		).WithParam("--url")
+	}
+	if spec.DocType == "" {
+		return spec, source, errs.NewValidationError(errs.SubtypeInvalidArgument, "--doc-type is required when --token is a bare token (allowed: %s)", driveExportInputDocTypeValues).
+			WithParam("--doc-type").
+			WithHint("if you have the original document link, prefer --url <document_url>; if this is a Wiki node token, use --doc-type wiki")
+	}
+	if spec.DocType == "wiki" {
+		source.Type = "wiki"
+		source.Token = spec.Token
+		spec.DocType = ""
+	}
+	return spec, source, nil
+}
+
+func normalizeDriveExportDocType(docType string) string {
+	switch strings.ToLower(strings.TrimSpace(docType)) {
+	case "base":
+		return "bitable"
+	default:
+		return strings.ToLower(strings.TrimSpace(docType))
+	}
+}
+
+func isDriveExportDocType(docType string) bool {
+	switch normalizeDriveExportDocType(docType) {
+	case "doc", "docx", "sheet", "bitable", "slides":
+		return true
+	default:
+		return false
+	}
+}
+
+func buildDriveExportTaskBody(spec driveExportSpec) map[string]interface{} {
 	body := map[string]interface{}{
 		"token":          spec.Token,
 		"type":           spec.DocType,
@@ -193,8 +416,13 @@ func createDriveExportTask(runtime *common.RuntimeContext, spec driveExportSpec)
 	if spec.OnlySchema {
 		body["only_schema"] = true
 	}
+	return body
+}
 
-	data, err := runtime.CallAPITyped("POST", "/open-apis/drive/v1/export_tasks", nil, body)
+// createDriveExportTask starts the asynchronous export job and returns its
+// ticket for subsequent polling.
+func createDriveExportTask(runtime *common.RuntimeContext, spec driveExportSpec) (string, error) {
+	data, err := runtime.CallAPITyped("POST", "/open-apis/drive/v1/export_tasks", nil, buildDriveExportTaskBody(spec))
 	if err != nil {
 		return "", err
 	}
@@ -206,6 +434,99 @@ func createDriveExportTask(runtime *common.RuntimeContext, spec driveExportSpec)
 	return ticket, nil
 }
 
+func resolveDriveExportWikiSource(ctx context.Context, runtime *common.RuntimeContext, spec driveExportSpec, wikiToken string) (driveExportSpec, driveExportWikiResolution, error) {
+	wikiToken = strings.TrimSpace(wikiToken)
+	if err := validate.ResourceName(wikiToken, "--token"); err != nil {
+		return spec, driveExportWikiResolution{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+	}
+
+	fmt.Fprintf(runtime.IO().ErrOut, "Resolving wiki node for export: %s\n", common.MaskToken(wikiToken))
+	data, err := driveInspectCallWithRetry(ctx, func() (map[string]interface{}, error) {
+		return runtime.CallAPITyped(
+			"GET",
+			"/open-apis/wiki/v2/spaces/get_node",
+			map[string]interface{}{"token": wikiToken},
+			nil,
+		)
+	})
+	if err != nil {
+		return spec, driveExportWikiResolution{}, err
+	}
+
+	node := common.GetMap(data, "node")
+	objType := normalizeDriveExportDocType(common.GetString(node, "obj_type"))
+	objToken := common.GetString(node, "obj_token")
+	if objType == "" || objToken == "" {
+		return spec, driveExportWikiResolution{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki get_node returned incomplete node data (obj_type=%q, obj_token=%q)", objType, objToken)
+	}
+	if !isDriveExportDocType(objType) {
+		return spec, driveExportWikiResolution{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"wiki resolved to %q, but drive +export only supports doc, docx, sheet, bitable, and slides",
+			objType,
+		).WithParam("--token")
+	}
+	if spec.DocType != "" && spec.DocType != objType {
+		return spec, driveExportWikiResolution{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"wiki resolved to %q, but --doc-type is %q; use --doc-type %s",
+			objType,
+			spec.DocType,
+			objType,
+		).WithParam("--doc-type")
+	}
+
+	spec.Token = objToken
+	spec.DocType = objType
+	if err := validateDriveExportNormalizedSpec(spec); err != nil {
+		return spec, driveExportWikiResolution{}, err
+	}
+	fmt.Fprintf(runtime.IO().ErrOut, "Resolved wiki to %s: %s\n", objType, common.MaskToken(objToken))
+	return spec, driveExportWikiResolution{
+		Resolved:  true,
+		WikiToken: wikiToken,
+		ObjToken:  objToken,
+		ObjType:   objType,
+	}, nil
+}
+
+func createDriveExportTaskWithWikiFallback(ctx context.Context, runtime *common.RuntimeContext, spec driveExportSpec, source driveExportInputSource) (string, driveExportSpec, driveExportWikiResolution, error) {
+	if source.Type == "wiki" {
+		resolvedSpec, resolution, err := resolveDriveExportWikiSource(ctx, runtime, spec, source.Token)
+		if err != nil {
+			return "", spec, resolution, err
+		}
+		ticket, err := createDriveExportTask(runtime, resolvedSpec)
+		return ticket, resolvedSpec, resolution, err
+	}
+
+	ticket, err := createDriveExportTask(runtime, spec)
+	if err == nil {
+		return ticket, spec, driveExportWikiResolution{}, nil
+	}
+	if source.WasURL || !shouldRetryDriveExportAsWiki(err) {
+		return "", spec, driveExportWikiResolution{}, err
+	}
+
+	resolvedSpec, resolution, resolveErr := resolveDriveExportWikiSource(ctx, runtime, spec, spec.Token)
+	if resolveErr != nil {
+		return "", spec, driveExportWikiResolution{}, appendDriveExportRecoveryHint(
+			err,
+			fmt.Sprintf("export task rejected --token; attempted wiki node resolution also failed: %v", resolveErr),
+		)
+	}
+	ticket, retryErr := createDriveExportTask(runtime, resolvedSpec)
+	return ticket, resolvedSpec, resolution, retryErr
+}
+
+func shouldRetryDriveExportAsWiki(err error) bool {
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem == nil {
+		return false
+	}
+	return problem.Code == 1069914
+}
+
 // getDriveExportStatus fetches the current backend state for a previously
 // created export task.
 func getDriveExportStatus(runtime *common.RuntimeContext, token, ticket string) (driveExportStatus, error) {

shortcuts/drive/drive_export_test.go

@@ -33,10 +33,36 @@ func TestValidateDriveExportSpec(t *testing.T) {
 			name: "markdown docx ok",
 			spec: driveExportSpec{Token: "docx123", DocType: "docx", FileExtension: "markdown"},
 		},
+		{
+			name: "docx url infers doc type",
+			spec: driveExportSpec{URL: "https://example.feishu.cn/docx/docxURL123", FileExtension: "pdf"},
+		},
+		{
+			name: "wiki url can defer doc type until resolution",
+			spec: driveExportSpec{URL: "https://example.feishu.cn/wiki/wikiURL123", FileExtension: "pdf"},
+		},
+		{
+			name: "wiki url with doc-type wiki can defer doc type until resolution",
+			spec: driveExportSpec{URL: "https://example.feishu.cn/wiki/wikiURL123", DocType: "wiki", FileExtension: "pdf"},
+		},
+		{
+			name: "wiki token with doc-type wiki can defer doc type until resolution",
+			spec: driveExportSpec{Token: "wiki123", DocType: "wiki", FileExtension: "pdf"},
+		},
+		{
+			name:    "bare token requires doc type",
+			spec:    driveExportSpec{Token: "docx123", FileExtension: "pdf"},
+			wantErr: "--doc-type is required",
+		},
 		{
 			name:    "markdown non docx rejected",
 			spec:    driveExportSpec{Token: "doc123", DocType: "doc", FileExtension: "markdown"},
-			wantErr: "only supports --doc-type docx",
+			wantErr: "cannot be exported as markdown",
+		},
+		{
+			name:    "docx csv rejected",
+			spec:    driveExportSpec{Token: "docx123", DocType: "docx", FileExtension: "csv"},
+			wantErr: "cannot be exported as csv",
 		},
 		{
 			name:    "csv without sub id rejected",
@@ -72,17 +98,17 @@ func TestValidateDriveExportSpec(t *testing.T) {
 		{
 			name:    "base non bitable rejected",
 			spec:    driveExportSpec{Token: "sheet123", DocType: "sheet", FileExtension: "base"},
-			wantErr: "only supports --doc-type bitable",
+			wantErr: "cannot be exported as base",
 		},
 		{
 			name:    "pptx non slides rejected",
 			spec:    driveExportSpec{Token: "docx123", DocType: "docx", FileExtension: "pptx"},
-			wantErr: "only supports --doc-type slides",
+			wantErr: "cannot be exported as pptx",
 		},
 		{
 			name:    "slides csv rejected",
 			spec:    driveExportSpec{Token: "slides123", DocType: "slides", FileExtension: "csv"},
-			wantErr: "slides only supports",
+			wantErr: "cannot be exported as csv",
 		},
 		{
 			name:    "unknown doc type rejected",
@@ -113,6 +139,29 @@ func TestValidateDriveExportSpec(t *testing.T) {
 	}
 }
 
+func TestValidateDriveExportUnsupportedFormatHasHint(t *testing.T) {
+	t.Parallel()
+
+	err := validateDriveExportSpec(driveExportSpec{
+		Token:         "docx123",
+		DocType:       "docx",
+		FileExtension: "csv",
+	})
+	if err == nil {
+		t.Fatal("expected unsupported format error, got nil")
+	}
+	var valErr *errs.ValidationError
+	if !errors.As(err, &valErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if valErr.Param != "--file-extension" {
+		t.Fatalf("param = %q, want --file-extension", valErr.Param)
+	}
+	if !strings.Contains(valErr.Hint, "docx, pdf, markdown") || !strings.Contains(valErr.Hint, "--url") {
+		t.Fatalf("hint = %q, want allowed formats and URL retry guidance", valErr.Hint)
+	}
+}
+
 func TestDriveExportMarkdownWritesFile(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	fetchStub := &httpmock.Stub{
@@ -440,6 +489,76 @@ func TestDriveExportMarkdownRejectsMissingDocumentContent(t *testing.T) {
 	}
 }
 
+func TestDriveExportURLInfersDocType(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_url"},
+		},
+	}
+	reg.Register(createStub)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_url",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"job_status":     0,
+					"file_token":     "box_url",
+					"file_name":      "url-report",
+					"file_extension": "pdf",
+					"type":           "docx",
+					"file_size":      3,
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/export_tasks/file/box_url/download",
+		Status:  200,
+		RawBody: []byte("pdf"),
+		Headers: http.Header{
+			"Content-Type":        []string{"application/pdf"},
+			"Content-Disposition": []string{`attachment; filename="url-report.pdf"`},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	prevAttempts, prevInterval := driveExportPollAttempts, driveExportPollInterval
+	driveExportPollAttempts, driveExportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveExportPollAttempts, driveExportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--url", "https://example.feishu.cn/docx/docxURL123",
+		"--file-extension", "pdf",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var createBody map[string]interface{}
+	if err := json.Unmarshal(createStub.CapturedBody, &createBody); err != nil {
+		t.Fatalf("unmarshal export_tasks body: %v", err)
+	}
+	if createBody["token"] != "docxURL123" {
+		t.Fatalf("export_tasks body token = %v, want token from URL", createBody["token"])
+	}
+	if createBody["type"] != "docx" {
+		t.Fatalf("export_tasks body type = %v, want inferred docx", createBody["type"])
+	}
+}
+
 func TestDriveExportAsyncSuccess(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	reg.Register(&httpmock.Stub{
@@ -510,6 +629,318 @@ func TestDriveExportAsyncSuccess(t *testing.T) {
 	}
 }
 
+func TestDriveExportWikiURLResolvesBeforeAsyncTask(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "docx",
+					"obj_token": "docxResolved",
+				},
+			},
+		},
+	})
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_wiki"},
+		},
+	}
+	reg.Register(createStub)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_wiki",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"job_status":     0,
+					"file_token":     "box_wiki",
+					"file_name":      "wiki-report",
+					"file_extension": "pdf",
+					"type":           "docx",
+					"file_size":      3,
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/export_tasks/file/box_wiki/download",
+		Status:  200,
+		RawBody: []byte("pdf"),
+		Headers: http.Header{
+			"Content-Type":        []string{"application/pdf"},
+			"Content-Disposition": []string{`attachment; filename="wiki-report.pdf"`},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	prevAttempts, prevInterval := driveExportPollAttempts, driveExportPollInterval
+	driveExportPollAttempts, driveExportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveExportPollAttempts, driveExportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--url", "https://example.feishu.cn/wiki/wikiNode123",
+		"--file-extension", "pdf",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var createBody map[string]interface{}
+	if err := json.Unmarshal(createStub.CapturedBody, &createBody); err != nil {
+		t.Fatalf("unmarshal export_tasks body: %v", err)
+	}
+	if createBody["token"] != "docxResolved" {
+		t.Fatalf("export_tasks body token = %v, want resolved docx token", createBody["token"])
+	}
+	if createBody["type"] != "docx" {
+		t.Fatalf("export_tasks body type = %v, want docx", createBody["type"])
+	}
+	if !strings.Contains(stdout.String(), `"wiki_token": "wikiNode123"`) {
+		t.Fatalf("stdout missing wiki token context: %s", stdout.String())
+	}
+}
+
+func TestDriveExportBareWikiTypeResolvesBeforeAsyncTask(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "docx",
+					"obj_token": "docxResolved",
+				},
+			},
+		},
+	})
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_wiki_token"},
+		},
+	}
+	reg.Register(createStub)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_wiki_token",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"job_status":     0,
+					"file_token":     "box_wiki_token",
+					"file_name":      "wiki-token-report",
+					"file_extension": "pdf",
+					"type":           "docx",
+					"file_size":      3,
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/export_tasks/file/box_wiki_token/download",
+		Status:  200,
+		RawBody: []byte("pdf"),
+		Headers: http.Header{
+			"Content-Type":        []string{"application/pdf"},
+			"Content-Disposition": []string{`attachment; filename="wiki-token-report.pdf"`},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	prevAttempts, prevInterval := driveExportPollAttempts, driveExportPollInterval
+	driveExportPollAttempts, driveExportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveExportPollAttempts, driveExportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "wikiNodeBare",
+		"--doc-type", "wiki",
+		"--file-extension", "pdf",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var createBody map[string]interface{}
+	if err := json.Unmarshal(createStub.CapturedBody, &createBody); err != nil {
+		t.Fatalf("unmarshal export_tasks body: %v", err)
+	}
+	if createBody["token"] != "docxResolved" {
+		t.Fatalf("export_tasks body token = %v, want resolved docx token", createBody["token"])
+	}
+	if createBody["type"] != "docx" {
+		t.Fatalf("export_tasks body type = %v, want resolved docx type", createBody["type"])
+	}
+	if !strings.Contains(stdout.String(), `"wiki_token": "wikiNodeBare"`) {
+		t.Fatalf("stdout missing wiki token context: %s", stdout.String())
+	}
+}
+
+func TestDriveExportBareWikiTokenFallbackAfterFileTokenInvalid(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	firstCreate := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Status: 404,
+		Body: map[string]interface{}{
+			"code":   1069914,
+			"msg":    "file token invalid",
+			"log_id": "20260708000000TEST",
+		},
+		BodyFilter: func(body []byte) bool {
+			return strings.Contains(string(body), `"token":"wikiNodeBare"`)
+		},
+	}
+	reg.Register(firstCreate)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "docx",
+					"obj_token": "docxResolved",
+				},
+			},
+		},
+	})
+	retryCreate := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_retry"},
+		},
+		BodyFilter: func(body []byte) bool {
+			return strings.Contains(string(body), `"token":"docxResolved"`)
+		},
+	}
+	reg.Register(retryCreate)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_retry",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"job_status":     0,
+					"file_token":     "box_retry",
+					"file_name":      "retry-report",
+					"file_extension": "pdf",
+					"type":           "docx",
+					"file_size":      3,
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/export_tasks/file/box_retry/download",
+		Status:  200,
+		RawBody: []byte("pdf"),
+		Headers: http.Header{
+			"Content-Type":        []string{"application/pdf"},
+			"Content-Disposition": []string{`attachment; filename="retry-report.pdf"`},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	prevAttempts, prevInterval := driveExportPollAttempts, driveExportPollInterval
+	driveExportPollAttempts, driveExportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveExportPollAttempts, driveExportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "wikiNodeBare",
+		"--doc-type", "docx",
+		"--file-extension", "pdf",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if len(firstCreate.CapturedBody) == 0 {
+		t.Fatal("first export task request was not sent with the original token")
+	}
+	var retryBody map[string]interface{}
+	if err := json.Unmarshal(retryCreate.CapturedBody, &retryBody); err != nil {
+		t.Fatalf("unmarshal retry export_tasks body: %v", err)
+	}
+	if retryBody["token"] != "docxResolved" {
+		t.Fatalf("retry export_tasks body token = %v, want resolved docx token", retryBody["token"])
+	}
+	if !strings.Contains(stdout.String(), `"wiki_token": "wikiNodeBare"`) {
+		t.Fatalf("stdout missing wiki token context: %s", stdout.String())
+	}
+}
+
+func TestDriveExportWikiResolvedTypeMismatch(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "sheet",
+					"obj_token": "shtResolved",
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "https://example.feishu.cn/wiki/wikiSheet123",
+		"--doc-type", "docx",
+		"--file-extension", "pdf",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected type mismatch error, got nil")
+	}
+	var valErr *errs.ValidationError
+	if !errors.As(err, &valErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if !strings.Contains(valErr.Message, `wiki resolved to "sheet"`) {
+		t.Fatalf("error message = %q, want resolved type", valErr.Message)
+	}
+}
+
 // TestDriveExportEmptyOutputDirDownloadsToCwd guards the export refactor: an
 // explicit empty --output-dir must still download to the current directory
 // (normalized to "."), not trigger the export-only no-download path that the

shortcuts/minutes/minutes_detail.go

@@ -28,7 +28,12 @@ import (
 const minutesDetailLogPrefix = "[minutes +detail]"
 
 // Error codes from the minutes API.
-const minutesDetailNoReadPermissionCode = 2091005
+const (
+	minutesDetailProcessingCode       = 2091003
+	minutesDetailNoReadPermissionCode = 2091005
+	minutesDetailWaitTimeoutDefault   = 300
+	minutesDetailWaitIntervalDefault  = 15
+)
 
 var validMinuteTokenDetail = regexp.MustCompile(`^[a-z0-9]+$`)
 
@@ -40,19 +45,31 @@ var scopesDetailMinuteTokens = []string{
 // minuteDetailItem represents a single minute detail result.
 type minuteDetailItem struct {
 	MinuteToken string         `json:"minute_token"`
+	Status      string         `json:"status,omitempty"`
 	Title       string         `json:"title"`
 	NoteID      string         `json:"note_id"`
 	Artifacts   map[string]any `json:"artifacts,omitempty"`
+	Retryable   bool           `json:"retryable,omitempty"`
 	Error       string         `json:"error,omitempty"`
+	Hint        string         `json:"hint,omitempty"`
+	NextCommand string         `json:"next_command,omitempty"`
 }
 
 // fetchMinuteDetail queries a single minute's metadata and selected artifacts.
 func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minuteToken string) *minuteDetailItem {
-	data, err := runtime.CallAPITyped(http.MethodGet,
-		fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil)
+	artifactFlags := requestedMinutesDetailArtifactFlags(runtime)
+	waitReady := runtime.Bool("wait-ready")
+	waitTimeout, waitInterval := minutesDetailWaitConfig(runtime)
+
+	data, err := callMinutesDetailAPIUntilReady(ctx, runtime, waitReady, waitTimeout, waitInterval, func() (map[string]interface{}, error) {
+		return runtime.CallAPITyped(http.MethodGet,
+			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil)
+	})
 	if err != nil {
 		result := &minuteDetailItem{MinuteToken: minuteToken}
-		if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailNoReadPermissionCode {
+		if isMinutesDetailProcessingError(err) {
+			markMinutesDetailProcessing(result, minuteToken, artifactFlags, "minute metadata is still being generated")
+		} else if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailNoReadPermissionCode {
 			result.Error = fmt.Sprintf("No read permission for minute %s. Ask the minute owner for minute file read permission", minuteToken)
 		} else {
 			result.Error = fmt.Sprintf("failed to query minute: %v", err)
@@ -81,10 +98,16 @@ func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minu
 	needKeyword := runtime.Bool("keyword")
 
 	if needSummary || needTodo || needChapter || needTranscript || needKeyword {
-		artData, err := runtime.CallAPITyped(http.MethodGet,
-			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/artifacts", validate.EncodePathSegment(minuteToken)), nil, nil)
+		artData, err := callMinutesDetailAPIUntilReady(ctx, runtime, waitReady, waitTimeout, waitInterval, func() (map[string]interface{}, error) {
+			return runtime.CallAPITyped(http.MethodGet,
+				fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/artifacts", validate.EncodePathSegment(minuteToken)), nil, nil)
+		})
 		if err != nil {
-			fmt.Fprintf(runtime.IO().ErrOut, "%s failed to fetch artifacts for %s: %v\n", minutesDetailLogPrefix, minuteToken, err)
+			if isMinutesDetailProcessingError(err) {
+				markMinutesDetailProcessing(result, minuteToken, artifactFlags, "minute artifacts are still being generated")
+			} else {
+				result.Error = fmt.Sprintf("failed to query minute artifacts: %v", err)
+			}
 		} else {
 			artifacts := make(map[string]any)
 			if needSummary {
@@ -133,6 +156,78 @@ func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minu
 	return result
 }
 
+func isMinutesDetailProcessingError(err error) bool {
+	if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailProcessingCode {
+		return true
+	}
+	return false
+}
+
+func minutesDetailWaitConfig(runtime *common.RuntimeContext) (time.Duration, time.Duration) {
+	timeoutSeconds, intervalSeconds := normalizeMinutesDetailWaitSeconds(runtime.Int("wait-timeout-seconds"), runtime.Int("wait-interval-seconds"))
+	return time.Duration(timeoutSeconds) * time.Second, time.Duration(intervalSeconds) * time.Second
+}
+
+func normalizeMinutesDetailWaitSeconds(timeoutSeconds, intervalSeconds int) (int, int) {
+	if timeoutSeconds <= 0 {
+		timeoutSeconds = minutesDetailWaitTimeoutDefault
+	}
+	if intervalSeconds <= 0 {
+		intervalSeconds = minutesDetailWaitIntervalDefault
+	}
+	return timeoutSeconds, intervalSeconds
+}
+
+func callMinutesDetailAPIUntilReady(ctx context.Context, runtime *common.RuntimeContext, waitReady bool, timeout, interval time.Duration, call func() (map[string]interface{}, error)) (map[string]interface{}, error) {
+	deadline := time.Now().Add(timeout)
+	for {
+		data, err := call()
+		if err == nil || !waitReady || !isMinutesDetailProcessingError(err) {
+			return data, err
+		}
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return nil, ctxErr
+		}
+		remaining := time.Until(deadline)
+		if remaining <= 0 || interval > remaining {
+			return nil, err
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "%s minute is still processing; retrying in %s\n", minutesDetailLogPrefix, interval)
+		timer := time.NewTimer(interval)
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			return nil, ctx.Err()
+		case <-timer.C:
+		}
+	}
+}
+
+func requestedMinutesDetailArtifactFlags(runtime *common.RuntimeContext) []string {
+	var flags []string
+	for _, flag := range []string{"summary", "todo", "chapter", "keyword", "transcript"} {
+		if runtime.Bool(flag) {
+			flags = append(flags, "--"+flag)
+		}
+	}
+	return flags
+}
+
+func markMinutesDetailProcessing(result *minuteDetailItem, minuteToken string, artifactFlags []string, reason string) {
+	result.Status = "processing"
+	result.Retryable = true
+	result.Error = reason
+	result.Hint = "The minute is still being generated. Retry later, or rerun the next_command to wait until it is ready."
+	result.NextCommand = minutesDetailNextCommand(minuteToken, artifactFlags)
+}
+
+func minutesDetailNextCommand(minuteToken string, artifactFlags []string) string {
+	parts := []string{"lark-cli", "minutes", "+detail", "--minute-tokens", minuteToken}
+	parts = append(parts, artifactFlags...)
+	parts = append(parts, "--wait-ready")
+	return strings.Join(parts, " ")
+}
+
 // saveDetailTranscript persists transcript bytes to the canonical artifact path.
 // With --output-dir, transcripts land under <output-dir>/artifact-<title>-<token>/
 // to mirror the legacy `vc +notes` layout. Otherwise falls back to the default
@@ -201,6 +296,9 @@ var MinutesDetail = common.Shortcut{
 		{Name: "keyword", Type: "bool", Desc: "include keywords"},
 		{Name: "output-dir", Desc: "output directory for transcript files (default: ./minutes/{minute_token}/)"},
 		{Name: "overwrite", Type: "bool", Desc: "overwrite existing transcript files"},
+		{Name: "wait-ready", Type: "bool", Desc: "wait until minute metadata/artifacts are ready", Hidden: true},
+		{Name: "wait-timeout-seconds", Type: "int", Default: "300", Desc: "maximum seconds to wait for readiness", Hidden: true},
+		{Name: "wait-interval-seconds", Type: "int", Default: "15", Desc: "seconds between readiness checks", Hidden: true},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		tokens := common.SplitCSV(runtime.Str("minute-tokens"))
@@ -282,8 +380,15 @@ var MinutesDetail = common.Shortcut{
 			for _, r := range results {
 				row := map[string]interface{}{"minute_token": r.MinuteToken}
 				if r.Error != "" {
-					row["status"] = "FAIL"
+					if r.Status == "processing" {
+						row["status"] = "PROCESSING"
+					} else {
+						row["status"] = "FAIL"
+					}
 					row["error"] = r.Error
+					if r.NextCommand != "" {
+						row["next_command"] = r.NextCommand
+					}
 				} else {
 					row["status"] = "OK"
 					row["title"] = r.Title

shortcuts/minutes/minutes_detail_test.go

@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net/http"
 	"os"
 	"strings"
 	"sync"
@@ -108,6 +109,17 @@ func detailArtifactsStub(token, transcript string) *httpmock.Stub {
 	}
 }
 
+func detailProcessingStub(path string) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    path,
+		Body: map[string]interface{}{
+			"code": 2091003,
+			"msg":  "minute is processing",
+		},
+	}
+}
+
 func TestDetail_Validation_MissingMinuteTokens(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
 	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--as", "user"}, f, nil)
@@ -172,6 +184,34 @@ func TestDetail_DryRun_WithArtifactFlags(t *testing.T) {
 	}
 }
 
+func TestDetail_HiddenWaitFlags(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	parent := &cobra.Command{Use: "minutes"}
+	MinutesDetail.Mount(parent, f)
+	parent.SetOut(stdout)
+	parent.SetArgs([]string{"+detail", "--help"})
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	if err := parent.Execute(); err != nil {
+		t.Fatalf("help failed: %v", err)
+	}
+	help := stdout.String()
+	for _, hidden := range []string{"wait-ready", "wait-timeout-seconds", "wait-interval-seconds"} {
+		if strings.Contains(help, hidden) {
+			t.Fatalf("hidden flag %q should not appear in help:\n%s", hidden, help)
+		}
+	}
+
+	stdout.Reset()
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "tok001", "--summary", "--wait-ready",
+		"--wait-timeout-seconds", "0", "--wait-interval-seconds", "0", "--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("hidden wait flags should parse: %v", err)
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Execute tests with mocked HTTP
 // ---------------------------------------------------------------------------
@@ -355,6 +395,136 @@ func TestDetail_Execute_MinuteNotFound(t *testing.T) {
 	}
 }
 
+func TestDetail_Execute_MetadataProcessing(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokpending"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokpending", "--summary", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	if m["status"] != "processing" {
+		t.Fatalf("status = %v, want processing", m["status"])
+	}
+	if m["retryable"] != true {
+		t.Fatalf("retryable = %v, want true", m["retryable"])
+	}
+	if !strings.Contains(fmt.Sprint(m["next_command"]), "minutes +detail --minute-tokens tokpending --summary --wait-ready") {
+		t.Fatalf("next_command = %v", m["next_command"])
+	}
+}
+
+func TestDetail_Execute_ArtifactsProcessing(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("tokartpending", "note_pending", "Pending Artifacts"))
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokartpending/artifacts"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokartpending", "--summary", "--todo", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	if m["status"] != "processing" {
+		t.Fatalf("status = %v, want processing", m["status"])
+	}
+	if m["title"] != "Pending Artifacts" || m["note_id"] != "note_pending" {
+		t.Fatalf("metadata should be preserved on artifacts processing, got title=%v note_id=%v", m["title"], m["note_id"])
+	}
+	if !strings.Contains(fmt.Sprint(m["next_command"]), "--summary --todo --wait-ready") {
+		t.Fatalf("next_command = %v", m["next_command"])
+	}
+}
+
+func TestDetail_WaitReady_MetadataEventuallyReady(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokwaitmeta"))
+	reg.Register(detailMinuteGetStub("tokwaitmeta", "", "Ready Metadata"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "tokwaitmeta", "--wait-ready",
+		"--wait-timeout-seconds", "5", "--wait-interval-seconds", "1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	if m["title"] != "Ready Metadata" {
+		t.Fatalf("title = %v, want Ready Metadata", m["title"])
+	}
+	if _, ok := m["artifacts"]; ok {
+		t.Fatal("artifacts should not be fetched without artifact flags")
+	}
+}
+
+func TestDetail_WaitReady_ArtifactsEventuallyReady(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("tokwaitart", "note_wait", "Ready Artifacts"))
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokwaitart/artifacts"))
+	reg.Register(detailArtifactsStub("tokwaitart", ""))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "tokwaitart", "--summary", "--wait-ready",
+		"--wait-timeout-seconds", "5", "--wait-interval-seconds", "1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	arts, _ := m["artifacts"].(map[string]any)
+	if arts == nil {
+		t.Fatal("expected artifacts")
+	}
+	if arts["summary"] != "Test summary content" {
+		t.Fatalf("summary = %v", arts["summary"])
+	}
+}
+
+func TestDetail_WaitReady_TimeoutUsesProcessingResult(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("toktimeout", "note_timeout", "Timeout Artifacts"))
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/toktimeout/artifacts"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "toktimeout", "--summary", "--wait-ready",
+		"--wait-timeout-seconds", "1", "--wait-interval-seconds", "2", "--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	if m["status"] != "processing" || m["title"] != "Timeout Artifacts" || m["note_id"] != "note_timeout" {
+		t.Fatalf("timeout should preserve processing status and metadata, got %+v", m)
+	}
+}
+
+func TestDetail_WaitReady_DoesNotPollNonProcessingErrors(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	var callCount int
+	reg.Register(&httpmock.Stub{
+		Method:   "GET",
+		URL:      "/open-apis/minutes/v1/minutes/tokmissing",
+		Body:     map[string]interface{}{"code": 2091004, "msg": "not found"},
+		Reusable: true,
+		OnMatch:  func(req *http.Request) { callCount++ },
+	})
+
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "tokmissing", "--wait-ready",
+		"--wait-timeout-seconds", "5", "--wait-interval-seconds", "1", "--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	if callCount != 1 {
+		t.Fatalf("non-processing error should not be retried, callCount=%d", callCount)
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Pure function tests
 // ---------------------------------------------------------------------------
@@ -378,6 +548,36 @@ func TestValidMinuteTokenDetail(t *testing.T) {
 	}
 }
 
+func TestNormalizeMinutesDetailWaitSeconds(t *testing.T) {
+	timeout, interval := normalizeMinutesDetailWaitSeconds(0, 0)
+	if timeout != minutesDetailWaitTimeoutDefault || interval != minutesDetailWaitIntervalDefault {
+		t.Fatalf("normalize(0,0) = (%d,%d), want defaults (%d,%d)", timeout, interval, minutesDetailWaitTimeoutDefault, minutesDetailWaitIntervalDefault)
+	}
+	timeout, interval = normalizeMinutesDetailWaitSeconds(-1, -2)
+	if timeout != minutesDetailWaitTimeoutDefault || interval != minutesDetailWaitIntervalDefault {
+		t.Fatalf("normalize(negative) = (%d,%d), want defaults", timeout, interval)
+	}
+	timeout, interval = normalizeMinutesDetailWaitSeconds(9, 3)
+	if timeout != 9 || interval != 3 {
+		t.Fatalf("normalize(9,3) = (%d,%d)", timeout, interval)
+	}
+}
+
+func firstDetailMinute(t *testing.T, raw []byte) map[string]any {
+	t.Helper()
+	var resp map[string]any
+	if err := json.Unmarshal(raw, &resp); err != nil {
+		t.Fatalf("failed to parse output: %v\n%s", err, string(raw))
+	}
+	data, _ := resp["data"].(map[string]any)
+	minutes, _ := data["minutes"].([]any)
+	if len(minutes) != 1 {
+		t.Fatalf("expected 1 minute, got %d in %s", len(minutes), string(raw))
+	}
+	m, _ := minutes[0].(map[string]any)
+	return m
+}
+
 // chdirForDetailTest switches cwd to a temp dir for the test.
 func chdirForDetailTest(t *testing.T) string {
 	t.Helper()

shortcuts/minutes/minutes_upload.go

@@ -5,6 +5,8 @@ package minutes
 
 import (
 	"context"
+	"net/url"
+	"strings"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
@@ -65,8 +67,25 @@ var MinutesUpload = common.Shortcut{
 		outData := map[string]interface{}{
 			"minute_url": minuteURL,
 		}
+		if minuteToken := extractUploadedMinuteToken(minuteURL); minuteToken != "" {
+			outData["minute_token"] = minuteToken
+		}
 
 		runtime.OutFormat(outData, nil, nil)
 		return nil
 	},
 }
+
+func extractUploadedMinuteToken(minuteURL string) string {
+	u, err := url.Parse(minuteURL)
+	if err != nil {
+		return ""
+	}
+	parts := strings.Split(strings.TrimRight(u.Path, "/"), "/")
+	for i, part := range parts {
+		if part == "minutes" && i+1 < len(parts) {
+			return parts[i+1]
+		}
+	}
+	return ""
+}

shortcuts/minutes/minutes_upload_test.go

@@ -143,4 +143,28 @@ func TestMinutesUpload_Execute(t *testing.T) {
 	if dataMap["minute_url"] != "https://sample.feishu.cn/minutes/obcnq3b9jl72l83w4f149w9c" {
 		t.Errorf("expected minute_url https://sample.feishu.cn/minutes/obcnq3b9jl72l83w4f149w9c, got %v", dataMap["minute_url"])
 	}
+	if dataMap["minute_token"] != "obcnq3b9jl72l83w4f149w9c" {
+		t.Errorf("expected minute_token obcnq3b9jl72l83w4f149w9c, got %v", dataMap["minute_token"])
+	}
+}
+
+func TestExtractUploadedMinuteToken(t *testing.T) {
+	tests := []struct {
+		name string
+		url  string
+		want string
+	}{
+		{name: "standard", url: "https://sample.feishu.cn/minutes/obcnq3b9jl72l83w4f149w9c", want: "obcnq3b9jl72l83w4f149w9c"},
+		{name: "query", url: "https://sample.feishu.cn/minutes/obcn123?from=upload", want: "obcn123"},
+		{name: "trailing slash", url: "https://sample.feishu.cn/minutes/obcn123/", want: "obcn123"},
+		{name: "invalid", url: "://bad", want: ""},
+		{name: "no minutes path", url: "https://sample.feishu.cn/docx/abc", want: ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := extractUploadedMinuteToken(tt.url); got != tt.want {
+				t.Fatalf("extractUploadedMinuteToken(%q) = %q, want %q", tt.url, got, tt.want)
+			}
+		})
+	}
 }

skills/lark-calendar/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 
 开始前先读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)（认证、权限处理）。
 
-**CRITICAL — 凡涉及预约日程/会议或查询/搜索会议室，第一步 MUST 读 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。禁止跳过此步直接调用 API 或 Shortcut！**
+**CRITICAL — 凡涉及预约日程/会议室、调整时间或查询/搜索会议室，第一步 MUST 读 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。仅编辑字段（改标题/描述）或增删参会人（不涉及时间和会议室）时可跳过，直接读 [`references/lark-calendar-update.md`](references/lark-calendar-update.md)。**
 
 ## 身份
 
@@ -30,26 +30,80 @@ lark-cli calendar +agenda --as user
 
 | Shortcut | 说明 |
 |----------|------|
-| [`+agenda`](references/lark-calendar-agenda.md) | 查看日程安排（默认今天） |
-| [`+search-event`](references/lark-calendar-search-event.md) | 按关键词、时间范围和参会人搜索日程, 仅返回 日程ID/主题/时间等信息，详情需走 `events get` |
+| `+agenda` | 查看日程安排（默认今天） |
 | [`+meeting`](references/lark-calendar-meeting.md) | 通过日程事件 ID 获取关联的视频会议信息（meeting_id、meeting_note），日程开过视频会议才会有meeting_id |
 | [`+create`](references/lark-calendar-create.md) | 创建日程并邀请参会人（ISO 8601 时间） |
 | [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室 |
-| [`+freebusy`](references/lark-calendar-freebusy.md) | 查询用户主日历的忙闲信息和 RSVP 状态 |
+| `+freebusy` | 查询用户主日历的忙闲信息和 RSVP 状态（纯查询场景；预约场景走 `+suggestion`） |
 | [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（无明确时间时禁止直接调用，需先走 +suggestion） |
 | [`+rsvp`](references/lark-calendar-rsvp.md) | 回复日程（接受/拒绝/待定） |
 | [`+suggestion`](references/lark-calendar-suggestion.md) | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 |
 
+### `+get` — 单日程详情
+
+通过 `calendar_id` + `event_id` 获取**单个日程**详情。
+
+```bash
+# calendar_id不传，默认primary
+lark-cli calendar +get --calendar-id <calendar_id> --event-id <event_id>
+```
+
+### `+search-event` — 按关键词、时间范围和参会人搜索日程
+
+仅返回基础字段（`event_id`/`summary`/`start`/`end` 等），需要详情请走 `+get`。
+
+```bash
+# query 按关键词 可选
+# start/end 按时间范围（ISO 8601 或 YYYY-MM-DD）可选
+# attendee-ids 按参会人（自动识别 ou_ 用户 / oc_ 群聊 / omm_ 会议室前缀）可选
+# page-token 分页游标，用于继续翻页 可选
+# page-size 每页数量，默认 30 可选
+lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27 --attendee-ids "ou_user1,oc_chat1,omm_room1" --page-token <page_token> --page-size 30
+```
+
+### `+agenda` — 查看近期日程安排
+
+默认查询当天。结果应整理为按日期分组、按开始时间升序的易读时间线。
+
+```bash
+# start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天
+# calendar-id 日历 ID（默认primary）可选
+lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17 --calendar-id <calendar_id>
+```
+
+注意：
+- 已取消的日程自动过滤；无日程时直接告知"日程清空"。
+- 时间范围超过 40 天会自动拆分查询并合并结果。
+
+### `+freebusy` — 查询主日历忙闲时段和 RSVP 状态
+
+仅返回忙碌时段起止时间，不含日程标题等隐私信息；其他订阅日历不在范围内。
+
+```bash
+# start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天
+# user-id 目标用户 open_id（ou_ 前缀）可选；默认当前登录用户，bot 身份必须显式指定
+lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
+```
+
+用法提示：
+- **仅判断是否有空** → `+freebusy`；**需要日程详情** → `+agenda`。
+- 检查多人可用性：分别调用并对比，找共同空闲。
+- 预约/改约场景下，调用规则（参与人过多、含群组、来自 `+suggestion` 等）详见 [schedule-clear-time.md § 查询忙闲](references/lark-calendar-schedule-clear-time.md#2-查询忙闲)。
+
 ## 前置条件路由
 
 | 场景 | 前置要求 |
 |------|----------|
-| 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
-| 编辑已有日程 | 先定位目标日程 `event_id` |
+| 预约日程/会议、调整时间、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
+| 仅编辑字段（标题/描述）或增删参会人 | 先定位 `event_id`，再读 [lark-calendar-update.md](references/lark-calendar-update.md) |
+| 编辑已有日程（涉及时间或会议室） | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
 | 编辑/删除重复性日程 | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，按操作范围（仅此次/全部/此次及后续）执行 |
-| 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
 | 调用任何 Shortcut | 先读其对应 reference 文档 |
 
+## 写操作反馈
+
+创建、更新、删除、RSVP 等写操作完成后，直接基于命令返回结果反馈用户；不要为了“确认是否生效”主动发起二次查询。只有用户明确要求复查，或命令返回信息不足以回答用户问题时，才需要再查询。
+
 ## 核心概念
 
 - **日程实例（Instance）**：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 `event_id`；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 `event_id`），并按需处理例外。
@@ -72,7 +126,8 @@ lark-cli calendar +agenda --as user
 | 按关键词搜索日程 | 本 skill（`+search-event`） |
 | 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
 | 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再 [`vc +detail`](../lark-vc/references/lark-vc-detail.md) → [`note +detail`](../lark-note/references/lark-note-detail.md) / [`minutes +detail`](../lark-minutes/references/lark-minutes-detail.md) |
-| 预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
+| 预约/改约日程、调整时间、添加/更换会议室、查会议室 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
+| 仅编辑日程字段（标题/描述）或增删参会人（不涉及时间和会议室） | 先定位 `event_id`，再读 [+update](references/lark-calendar-update.md) 执行变更 |
 | 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |
 
 ## 任务类型分流
@@ -90,7 +145,7 @@ lark-cli calendar +agenda --as user
 
 ## 会议室规则
 
-- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)。
+- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)，会议室参数规范详见 [+room-find](references/lark-calendar-room-find.md)。
 - `+room-find` 的时间输入必须是确定时间块，不能是时间区间搜索。
 - 用户仅要求"查会议室"但未提供明确时间时，必须先调用 `+suggestion` 获取可用时间块，再将时间块交给 `+room-find`。严禁猜测时间盲目调用。
 - 编辑已有日程时，"添加会议室"默认是增量语义，保留已有会议室；只有用户明确说"更换会议室""移除会议室"时才删除旧会议室。
@@ -98,42 +153,45 @@ lark-cli calendar +agenda --as user
 ## API Resources
 
 ```bash
+# 通用调用格式
 lark-cli calendar <resource> <method> [flags]
+
+# 查询用户主日历
+lark-cli calendar calendars primary
+
+# 获取日程分享链接
+lark-cli calendar events share_info --calendar-id <calendar_id> --event-id <event_id>
+
+# 删除日程
+lark-cli calendar events delete --calendar-id <calendar_id> --event-id <event_id>
 ```
 
-### calendars
+> `calendar_id` 可以直接传 `primary`，代表当前调用身份的主日历 ID。
 
-  - `create` — 创建共享日历
-  - `delete` — 删除共享日历
-  - `get` — 查询日历信息
-  - `list` — 查询日历列表
-  - `patch` — 更新日历信息
-  - `primary` — 查询用户主日历
-  - `search` — 搜索日历
+### 查询资源的方法列表以及方法的使用方式
 
-### event.attendees
+- 列出某资源下的方法：`lark-cli calendar <resource> -h`
+- 查看方法的cli flag：`lark-cli calendar <resource> <method> -h`
+- 查看方法API参数：`lark-cli schema calendar.<resource>.<method>`
 
-  - `batch_delete` — 删除日程参与人
-  - `create` — 添加日程参与人
-  - `list` — 获取日程参与人列表
+`<resource>` 为 `calendars`（日历本身）/ `events`（日程）/ `event.attendees`（参与人）/ `freebusys`（忙闲）。例：`lark-cli schema calendar.events.delete`。
 
-### events
+## 常用其他域命令
 
-  - `create` — 创建日程
-  - `delete` — 删除日程
-  - `get` — 获取日程
-  - `instance_view` — 查询日程视图
-  - `patch` — 更新日程
-  - `share_info` — 获取日程分享链接
+```bash
+# 搜索用户，更多参数详见 lark-contact
+lark-cli contact +search-user --query <query> --as user
 
-### freebusys
-
-  - `list` — 查询主日历日程忙闲信息
+# 搜索群聊，更多参数详见 lark-im
+lark-cli im +chat-search --query <query> --as user
+```
 
 ## 不在本 skill 范围
 
 - 查询过去的视频会议记录 → [lark-vc](../lark-vc/SKILL.md)
 - 待办任务管理 → [lark-task](../lark-task/SKILL.md)
+- 通讯录 → [lark-contact](../lark-contact/SKILL.md)
+- 即时通讯 → [lark-im](../lark-im/SKILL.md)
 - 会议室物理设施管理 → 管理员后台
 
 **注意（强制性）：**

skills/lark-calendar/references/lark-calendar-agenda.md

@@ -1,78 +0,0 @@
-
-# calendar +agenda
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-查看近期日程安排。只读操作，不修改任何日程。
-
-需要的scopes: ["calendar:calendar.event:read"]
-
-## 命令
-
-```bash
-# 查看今天日程（默认）
-lark-cli calendar +agenda
-
-# 自定义时间范围（ISO 8601）
-lark-cli calendar +agenda --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
-
-# 自定义时间范围（仅日期）
-lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17
-
-# 人类可读格式输出
-lark-cli calendar +agenda --format pretty
-
-# 指定日历
-lark-cli calendar +agenda --calendar-id cal_xxx
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--start <time>` | 否 | 开始时间（ISO 8601 或仅日期，默认当天） |
-| `--end <time>` | 否 | 结束时间（默认与 `--start` 属于同一天，自动取当天结束时间） |
-| `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
-| `--format` | 否 | 输出格式：json（默认） \| pretty |
-| `--dry-run` | 否 | 预览 API 调用，不执行 |
-
-## 时间格式
-
-`--start` 和 `--end` 支持以下格式：
-
-| 格式 | 示例 | 说明 |
-|------|------|------|
-| ISO 8601 | `2026-03-10T14:00:00+08:00` | 完整格式 |
-| 日期+时间 | `2026-03-10 14:00:00` | 自动补全时区 |
-| 仅日期 | `2026-03-10` | start 取 00:00:00，end 取 23:59:59 |
-| Unix 时间戳 | `1741564800` | 秒级时间戳 |
-
-## 输出格式
-
-**将结果整理为易读的日程表：**
-
-```
-## 2026-03-10 周一
-
-09:00 - 09:30  站会
-10:00 - 11:00  产品评审
-14:00 - 15:00  与 Alice 1:1
-
-## 2026-03-11 周二
-
-（无日程）
-```
-
-**注意：按日期分组，并严格按照开始时间升序（从早到晚的时间线）排序输出。** 显示标题、时长
-
-## 提示
-
-- 已取消的日程会自动过滤，无需额外处理。
-- 如无日程，告知用户"日程清空"。
-- 大于 40 天的时间范围会自动拆分查询并合并结果。
-- 查看多个日历：先用 `lark-cli calendar calendars list --page-all` 列出日历列表，再逐个查询。
-
-## 参考
-
-- [lark-calendar](../SKILL.md) -- 日历全部命令
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-calendar/references/lark-calendar-create.md

@@ -1,12 +1,9 @@
 
 # calendar +create
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 创建日程并按需邀请参会人。
 
-需要的scopes: ["calendar:calendar.event:create","calendar:calendar.event:update"]
-
 ## 推荐命令
 
 ```bash
@@ -38,10 +35,10 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 | `--description <text>` | 否 | 日程详细描述。提供会议议程、活动内容、注意事项或链接等。与 summary 配合使用，仅关注当前日程信息 |
 | `--attendee-ids <id_list>` | 否 | 参与人 ID 列表（逗号分隔）。支持用户（`ou_`）、群组（`oc_`）和会议室（`omm_`）。AI 提取时请务必保留对应前缀 |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
-| `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1" |
+| `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。示例值："FREQ=DAILY;INTERVAL=1;UNTIL=<具体日期>" |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
 
-> **⚠️ `rrule` 规则限制：飞书日历系统不支持 `COUNT` 参数。遇到限制重复次数的需求，必须根据开始时间和频率自行推算并转换成 `UNTIL=<具体日期>` 格式。**
+> 当用户表达'每周 X'、'每周重复'、'连续 N 周'时，必须使用 rrule 创建重复性日程，而非创建多个独立日程
 > 自动设置 `attendee_ability: "can_modify_event"`，参会人可查看彼此并编辑日程。
 > 自动设置 `free_busy_status: "busy"`，默认日程忙闲状态为忙碌。
 > 自动设置 `reminders: [{"minutes": 5}]`，默认日程开始前 5 分钟提醒。
@@ -56,44 +53,16 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天。如果只有一天的话，开始日期和结束日期是相同。
 
 ```bash
-# 第一步：创建日程（含高级参数）
-## 查看完整参数定义
-lark-cli schema calendar.events.create
-## 创建日程
-lark-cli calendar events create \
-  --params '{"calendar_id":"<CALENDAR_ID>"}' \
-  --data '{
-  "summary": "技术分享：CLI 架构设计",
-  "start_time": { "timestamp": "1741586400" },
-  "end_time": { "timestamp": "1741593600" }
-}'
-
-# 第二步：添加参会人（使用第一步返回的 calendar_id 和 event_id）
-## 查看完整参数定义
-lark-cli schema calendar.event.attendees.create
-## 添加参会人
-lark-cli calendar event.attendees create \
-  --as user \
-  --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
-  --data '{"attendees": [{"type": "user", "user_id": "ou_xxx"}]}'
-
 ## 添加需要审批的会议室（approval_reason 最大 200 字符）
 lark-cli calendar event.attendees create \
   --as user \
   --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
   --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
 
-# 可选第三步（推荐）：若第二步失败，回滚删除空日程
-## 查看完整参数定义
-lark-cli schema calendar.events.delete
-## 删除空日程
-lark-cli calendar events delete \
-  --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>","need_notification":false}'
-
-```
-
-> 完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。
-> 当你手动拆成两步执行时，建议保留“失败后回滚删除”的第三步，避免遗留空日程。
+完整 API 命令的关键差异：
+- 时间参数是 **Unix 秒字符串**（非 ISO 8601）。
+- 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天；单日全天日程两者相同。
+- 手动拆成“创建日程 + 添加参会人”两步时，若第二步失败，建议删除刚创建的空日程，避免遗留无参会人的日程。
 
 ## 参会人类型
 
@@ -109,6 +78,5 @@ lark-cli calendar events delete \
 
 ## 参考
 
-- [lark-calendar](../SKILL.md) -- 日历全部命令
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-calendar](../SKILL.md) -- skill 入口与路由
 - [lark-calendar-suggestion](lark-calendar-suggestion.md) -- 根据非明确时间或一段时间范围，推荐多个可用时间块方案

skills/lark-calendar/references/lark-calendar-freebusy.md

@@ -1,124 +0,0 @@
-
-# calendar +freebusy
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
-
-查询用户主日历的忙闲信息，返回指定时间范围内的忙碌时段列表和rsvp的状态。
-
-需要的scopes: ["calendar:calendar.free_busy:read"]
-
-## 命令
-
-```bash
-# 查询当前用户今天的忙闲（默认）
-lark-cli calendar +freebusy
-
-# 自定义时间范围（仅日期）
-lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12
-
-# 自定义时间范围（完整 ISO 8601）
-lark-cli calendar +freebusy --start "2026-03-11T08:00:00+08:00" --end "2026-03-11T18:00:00+08:00"
-
-# 查询指定用户的忙闲信息
-lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
-
-# 人类可读格式输出
-lark-cli calendar +freebusy --format pretty
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--start <time>` | 否 | 查询开始时间（ISO 8601 或仅日期，默认当天） |
-| `--end <time>` | 否 | 查询结束时间（默认与 `--start` 属于同一天，自动取当天结束时间） |
-| `--user-id <open_id>` | 否 | 目标查询用户 ID（`ou_` 前缀）。省略时默认查询当前登录用户，bot 身份调用时必须明确指定 |
-| `--format` | 否 | 输出格式：json（默认） \| pretty |
-| `--dry-run` | 否 | 预览 API 调用，不执行 |
-
-## 时间格式
-
-`--start` 和 `--end` 支持以下格式：
-
-| 格式 | 示例 | 说明 |
-|------|------|------|
-| ISO 8601 | `2026-03-11T09:00:00+08:00` | 完整格式 |
-| 日期+时间 | `2026-03-11 09:00:00` | 自动补全时区 |
-| 仅日期 | `2026-03-11` | start 取 00:00:00，end 取 23:59:59 |
-| Unix 时间戳 | `1741564800` | 秒级时间戳 |
-
-## 输出示例
-
-### 表格格式
-
-```
-start             end               rsvp_status
-----------------  ----------------  -----------
-2026-03-11 10:00  2026-03-11 10:30  接受
-2026-03-11 14:00  2026-03-11 15:00  待定
-
-共 2 个忙碌时段
-```
-
-### JSON 格式
-
-```json
-[
-  {
-    "start_time": "2026-03-11T10:00:00+08:00",
-    "end_time": "2026-03-11T10:30:00+08:00",
-    "rsvp_status": "accept"
-  },
-  {
-    "start_time": "2026-03-11T14:00:00+08:00",
-    "end_time": "2026-03-11T15:00:00+08:00",
-    "rsvp_status": "tentative"
-  }
-]
-```
-
-## 典型场景
-
-### 1. 查找日程会议空闲时段
-
-```bash
-# 查询今天的忙碌时段
-lark-cli calendar +freebusy
-
-# 查询工作时间段
-lark-cli calendar +freebusy \
-  --start "2026-03-11T08:00:00+08:00" \
-  --end "2026-03-11T18:00:00+08:00"
-```
-
-### 2. 检查团队成员可用性
-
-```bash
-# 查询多个成员，对比找出共同空闲时间
-lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_a
-lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_b
-```
-
-## 注意事项
-
-1. **只查询主日历** — 此命令只返回用户主日历的忙闲信息，不包括其他订阅日历
-2. **隐私保护** — 只返回忙碌时段的起止时间，不包含日程标题、描述等详细信息
-3. **bot 身份** — bot 必须通过 `--user-id` 指定要查询的用户
-
-## 与其他命令对比
-
-| 命令 | 用途 | 输出内容 |
-|------|------|----------|
-| `calendar +freebusy` | 查询忙闲时段 | 只返回忙碌时段列表（无日程详情） |
-| `calendar +agenda` | 查看日程安排 | 返回完整日程列表（含标题、描述等） |
-
-**选择建议**：
-- **仅需了解是否有空** → 使用 `+freebusy`（更快，隐私保护）
-- **需要查看日程详情** → 使用 `+agenda`
-
-## 参考
-
-- [lark-calendar-agenda](lark-calendar-agenda.md) — 查看日程安排
-- [lark-calendar-create](lark-calendar-create.md) — 创建日程
-- [lark-calendar-suggestion](lark-calendar-suggestion.md) — 根据非明确时间或一段时间范围，推荐多个可用时间块方案
-- [lark-calendar](../SKILL.md) — 日历完整 API

skills/lark-calendar/references/lark-calendar-room-find.md

@@ -1,11 +1,8 @@
 # calendar +room-find
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
 
 针对一个或多个时间块查找/搜索可用会议室。会议室是日程的一种资源型参与人，不能脱离日程单独预定。
 
-需要的 scopes: ["calendar:calendar.free_busy:read"]
-
 ## 适用场景
 
 - 已知一个或多个待选时间块，需要查找可用会议室
@@ -50,7 +47,7 @@ lark-cli calendar +room-find \
 | `--city <text>` | 否 | 会议室所在城市强约束。**仅当**用户明确说出具体城市（如北京、上海）时才提取，**严禁**根据园区或楼宇名称自行联想或补全。 |
 | `--building <text>` | 否 | 会议室所在楼宇强约束，承载城市以下、楼层以上的办公区/园区/楼栋描述。|
 | `--floor <text>` | 否 | 仅用于筛选会议室所在楼层。应先做归一化，再传递规范值；例如 `2楼` / `二楼` / `2F` 统一为 `F2`。注意：此参数只筛选楼层，不可混入区域定位（如“A区”）或具体会议室号。 |
-| `--room-name <text>` | 否 | 会议室名称约束，支持以**英文逗号**分隔传入多个名称。仅当用户明确提到会议室专名或会议室号（如"木星""02"）时使用。当用户需要在一组编号会议室中搜索时（如"帮我约 16~20 号的会议室"），应将编号展开为逗号分隔列表，如 `"16,17,18,19,20"`。应优先传递去后缀、去冗余后的规范名，例如 `木星会议室` → `木星`，`会议室 02` / `02会议室` → `02`。 |
+| `--room-name <text>` | 否 | 会议室名称约束，支持以**英文逗号**分隔传入多个名称。仅当用户明确提到会议室专名、会议室号或编号区间时使用。 |
 | `--min-capacity <n>` | 否 | 会议室最小容纳人数。当用户明确参会人数或提出“至少容纳N人”等要求时，提取数字放入此参数，必须为正整数。 |
 | `--max-capacity <n>` | 否 | 会议室最大容纳人数。用于过滤过大空间，必须为正整数。 |
 | `--attendee-ids <id_list>` | 否 | 参会对象 ID 列表。支持用户 ID（`ou_` 前缀）和群组 ID（`oc_` 前缀），多个 ID 以逗号分隔。 |
@@ -67,7 +64,7 @@ lark-cli calendar +room-find \
 - 同一语义槽位只保留一个规范值。例如用户说“2楼”，应转换为 `--floor "F2"`；**禁止**同时传 `2楼 F2` 这类重复楼层信息。
 - 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。若短词更像楼层/区域定位（如 `2L`、`2F`），优先落到 `--floor`，不要默认落到 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。
 - 对会议室名要做轻量归一化：`木星会议室` 应提取为 `--room-name "木星"`；`会议室 02` / `02会议室` 应提取为 `--room-name "02"`。
-- **多会议室名称场景**：当用户表达"帮我约 XX 到 YY 号之间的会议室"或一次提及多个会议室名称时，应将所有目标名称用英文逗号拼接传入 `--room-name`。例如：
+- 当用户表达"帮我约 XX 到 YY 号之间的会议室"或一次提及多个会议室名称时，应将所有目标名称用英文逗号拼接传入 `--room-name`。例如：
   - "帮我约 16~20 号的会议室" → `--room-name "16,17,18,19,20"`
   - "查下木星和火星是否有空" → `--room-name "木星,火星"`
   - "看看 01、02、03 会议室" → `--room-name "01,02,03"`
@@ -90,9 +87,8 @@ lark-cli calendar +room-find \
 ```
 
 > **AI 行为指导：**
-> - **结构化展示时间块与会议室**：默认按“时间块 -> 会议室候选”的层级结构展示。**严禁将时间与会议室名称输出在同一行**。以清晰的分行列表呈现可用会议室，并直接询问用户意向。默认原样展示完整 `room_name`；不要擅自缩写、截断、改写，或仅提取楼层及会议室号替代完整名称。
+> - **结构化展示时间块与会议室**：默认按“时间块 -> 会议室候选”的层级结构展示，并直接询问用户意向。
 > - **`room_name` 必须逐字透传**：展示给用户的会议室名称，必须直接使用 CLI/API 返回的 `room_name` 原值。禁止提取楼层、会议室号、容量、视频能力后重组成新的名称，禁止意译、缩写、去前缀、去后缀，或仅保留"便于阅读"的摘要名。
-> - **主动识别区间/多名称意图**：当用户提到"帮我约 XX 到 YY 号的会议室""XX~YY 之间的会议室"或一次列出多个会议室名称时，将所有目标名称展开为英文逗号分隔列表，传入 `--room-name`。例如"帮我约 16 到 20 号的会议室"应生成 `--room-name "16,17,18,19,20"`。
 > - **重复日程要明确阻断原因与自动缩短**：若某候选会议室的 `reserve_until_time` 无法覆盖重复性日程，**必须**向用户明确说明该会议室最长可约至何时。若用户确认继续选用该会议室，你必须**自动将日程的重复规则结束时间缩短**至该 `reserve_until_time`，以防止会议室预约失败。不能直接按原规则继续。
 > - **正确解释推荐结果**：如果返回结果与用户输入条件不完全字面一致，先说明底层可能返回邻近位置或相近条件的推荐候选，不要直接将其判定为异常。
 > - **默认减少用户输入成本**：应主动引导用户不必一开始就提供很详细的会议室搜索条件。只要时间块已明确，用户直接表达“想约会议室”即可，先基于当前信息查询候选；只有在用户对结果不满意时，再引导其补充更具体的楼宇、楼层、会议室名或容量条件。
@@ -102,7 +98,7 @@ lark-cli calendar +room-find \
 | 字段名 | 说明 |
 | :--- | :--- |
 | `room_id` | 会议室唯一标识，用于后续创建日程时添加为会议室参与人使用。 |
-| `room_name` | 会议室名称，默认原样完整展示给用户，不要自行缩写、截断、改写，也不要用楼层及会议室号摘要替代原值。 |
+| `room_name` | 会议室名称，展示给用户时必须使用原值。 |
 | `capacity` | 会议室最大容纳人数。 |
 | `reserve_until_time` | 该会议室当前允许被预约到的最晚时间点，用于校验重复性日程是否超期。 |
 
@@ -110,4 +106,4 @@ lark-cli calendar +room-find \
 
 - [lark-calendar-create](lark-calendar-create.md)
 - [lark-calendar-suggestion](lark-calendar-suggestion.md)
-- [lark-calendar](../SKILL.md) — 日历完整 API
+- [lark-calendar](../SKILL.md) — skill 入口与路由

skills/lark-calendar/references/lark-calendar-rsvp.md

@@ -1,11 +1,8 @@
 # calendar +rsvp
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 回复指定的日程，更新当前用户的 RSVP 状态（接受、拒绝或待定）。
 
-需要的scopes: ["calendar:calendar.event:reply"]
-
 ## 命令
 
 ```bash
@@ -38,5 +35,4 @@ lark-cli calendar +rsvp --calendar-id cal_xxx --event-id evt_xxx --rsvp-status a
 
 ## 参考
 
-- [lark-calendar](../SKILL.md) -- 日历全部命令
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-calendar](../SKILL.md) -- skill 入口与路由

skills/lark-calendar/references/lark-calendar-schedule-clear-time.md

@@ -0,0 +1,59 @@
+# 明确时间分支：room-find + freebusy + 冲突处理
+
+> 本文档处理**时间已明确**的场景。"明确时间"来源：用户直接表达（如"明天下午3点"）、编辑流中已定位日程的原始 start/end、或经用户确认的 suggestion 时间块。
+
+## 前置条件
+
+进入此分支前，调度器（[schedule-meeting.md](./lark-calendar-schedule-meeting.md)）已完成：
+- 任务类型判定（新建 / 编辑）
+- 编辑流：目标 event_id 已定位
+- 新建流：默认值已补全
+- 时间已判定为**明确**
+
+## 流程
+
+### 1. 查询会议室（如需）
+
+若用户需要会议室，先调用 `+room-find`。详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。
+
+```bash
+lark-cli calendar +room-find \
+  --slot "<start>~<end>" \
+  --attendee-ids "<ids>" \
+  --city "<city>" \
+  --building "<building>" \
+  --floor "<F2>" \
+  --room-name "<room_name>"
+```
+
+时间块确定规则：
+- **编辑流且不改时间，只新增会议室**：`--slot` 必须来自已定位日程的当前 `start/end`
+- **编辑流且既改时间又加会议室**：`--slot` 必须来自候选新时间，而不是旧时间
+
+详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。
+
+### 2. 查询忙闲
+
+```bash
+lark-cli calendar +freebusy --start "<start>" --end "<end>"
+```
+
+规则：
+- 参与人过多（超过 5 人）：仅查询**当前用户**及少数核心人员忙闲即可
+- 参与人含**群组**：无需展开群组成员查询忙闲
+- 如果用户是从 `+suggestion` 确认了时间块后进入本分支的，**无需再调用 `+freebusy`**
+
+### 3. 冲突处理
+
+- **无冲突**：直接让用户选择会议室（如需），进入落地操作
+- **有冲突**：必须先说明冲突情况，询问用户：
+  - **继续当前时间** → 让用户选择会议室（如需），进入落地操作
+  - **换时间** → 转入 [模糊时间分支](./lark-calendar-schedule-fuzzy-time.md)
+
+## 落地
+
+根据任务类型：
+- 新建 → [`+create`](./lark-calendar-create.md)
+- 编辑 → [`+update`](./lark-calendar-update.md)
+
+落地规则详见 [schedule-meeting.md § 落地日程变更](./lark-calendar-schedule-meeting.md#落地日程变更)。

skills/lark-calendar/references/lark-calendar-schedule-fuzzy-time.md

@@ -0,0 +1,88 @@
+# 模糊时间 / 无时间信息分支：suggestion + 批量查询
+
+> 本文档处理**时间模糊**（如"明天下午""下周找个时间"）或**完全无时间信息**的场景。核心动作是调用 `+suggestion` 产出候选时间块，再根据是否需要会议室决定后续步骤。
+
+## 前置条件
+
+进入此分支前，调度器（[schedule-meeting.md](./lark-calendar-schedule-meeting.md)）已完成：
+- 任务类型判定（新建 / 编辑）
+- 编辑流：目标 event_id 已定位
+- 新建流：默认值已补全
+- 时间已判定为**模糊**或**无时间信息**
+
+## 流程
+
+### 1. 调用 suggestion
+
+详见 [`lark-calendar-suggestion.md`](./lark-calendar-suggestion.md)。
+
+```bash
+lark-cli calendar +suggestion \
+  --start "<range_start>" \
+  --end "<range_end>" \
+  --attendee-ids "<ids>" \
+  --duration-minutes <n> \
+  --event-rrule "<rrule>"
+```
+
+规则：
+- 用户完全没有提供时间信息时，先默认一个合理区间（如"今天剩余时间"或"近两天"）再调用
+- 编辑流中，若用户说"改到明天下午""下周找个时间再约"，基于用户期望的**新时间范围**调用，不要沿用旧时间
+- **不要在用户完全没给时间时反问"你想约什么时候"** — 先补合理区间再进入 suggestion
+
+### 2. 分支处理
+
+#### 不需要会议室
+
+获取多个推荐时间块后，直接向用户展示候选时间，用户确认后进入落地操作。
+
+#### 需要会议室
+
+获取候选时间块后，**不要急于让用户只选时间**。先将这些时间块一次性交给 `+room-find` 批量查询可用会议室，然后将【候选时间】与【对应的可用会议室列表】结构化展示，让用户一次性完成选择。
+
+> **注意**：即使用户最初只说"查会议室"且未带时间，也必须强制走 suggestion → room-find 路径。
+
+详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。
+
+### 3. 用户确认后
+
+- 用户选中 `+suggestion` 返回的时间块后，**无需再次调用 `+freebusy`**，直接进入落地操作
+- **BLOCKING REQUIREMENT**：必须先向用户展示选项并等待确认，禁止在未获用户确认时直接创建/更新日程
+
+## 模糊语义消解与长期记忆
+
+针对存在歧义的时间场景，严禁主观臆断。典型例子：
+- "上班后" / "下班前"
+- 未明确上下午的 12 小时制时间
+
+处理规则：
+- 主动澄清真实意图，不自行猜测
+- 用户澄清后，将个性化定义沉淀为长期偏好
+
+## 用户展示格式
+
+向用户展示多个时间块及对应会议室时，**必须结构化分行排版**，严禁将时间与会议室放在同一行：
+
+```text
+## 2026-03-27 周五
+
+[选项 1] 14:00 - 15:00（参会人均空闲）
+  可用会议室：
+  1. 学清嘉创大厦B座-F2-02🎦(7人)
+  2. 学清嘉创大厦B座-F2-05🎦(10人)
+
+[选项 2] 16:00 - 17:00（参会人均空闲）
+  可用会议室：
+  1. 学清嘉创大厦B座-F3-01🎦(6人)
+  2. 学清嘉创大厦B座-F3-06🎦(8人)
+
+💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。
+```
+
+## 落地
+
+根据任务类型：
+- 新建 → [`+create`](./lark-calendar-create.md)
+- 编辑 → [`+update`](./lark-calendar-update.md)
+
+落地规则详见 [schedule-meeting.md § 落地日程变更](./lark-calendar-schedule-meeting.md#落地日程变更)。

skills/lark-calendar/references/lark-calendar-schedule-meeting.md

@@ -1,206 +1,95 @@
 # 预约/改约日程或会议、查询/搜索可用会议室的工作流
 
-## CRITICAL 执行摘要（先按这个骨架执行，再看下方细则）
+## 执行摘要
 
-- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。** 不要把“预约/查会议室”默认等同于“新建”。
-- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。** 用户一旦给出了既有日程锚点（标题、时间段、`这个日程`、`这场会`）并表达修改动作（加人、删人、改时间、换会议室等），默认走编辑流。
-- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，避免把用户带入表单式问答。
-- **新建流先补默认值，编辑流先继承已定位日程信息。** 默认值包括标题、参会人、时长，以及在“完全无时间信息”时的默认时间范围；编辑流则优先复用已定位日程的标题、时间、已有参与人和会议室信息作为基线。
-- **只有三类场景才主动追问用户**：存在时间冲突、搜索结果无法唯一确定、时间语义本身有歧义。
-- **编辑流的时间基准必须明确。** 如果编辑时不改时间，则后续会议室搜索必须基于已定位日程的原始起止时间；如果既改时间又加会议室，必须先确定最终时间，再基于该时间搜索会议室。
-- **编辑流中“新增会议室”默认是增量语义。** 如果用户说的是“加会议室/再加一个会议室”，最终 `+update` 只做 `add`，默认保留已有会议室；只有在用户明确说“更换会议室/移除会议室”时，才执行旧会议室删除。
-- **明确时间**：若需要会议室，先 `+room-find`；再 `+freebusy` 判断参会人忙闲；有冲突时先说明冲突，再让用户决定继续当前时间还是改走 `+suggestion`。
-- **模糊时间或无时间信息**：先 `+suggestion` 产出候选时间块；若需要会议室，再把这些时间块批量交给 `+room-find`，将“候选时间 + 对应可用会议室”一次性展示给用户选择。
-- **BLOCKING REQUIREMENT: 只要面临时间方案（模糊时间/无时间）或会议室方案（需要会议室）的选择，必须先向用户展示选项并等待用户明确确认，绝对禁止在未获用户确认的情况下直接执行创建新日程或更新既有日程。**
-- **用户选中了 `+suggestion` 返回的候选时间块后，不要再次调用 `+freebusy`。** 用户确认后直接进入最终落地操作：创建新日程，或更新既有日程。
-- **当用户说“查会议室”“找会议室”“搜可用会议室”时，默认意图是查会议室可用性，不是检索会议室资源名录。**
-- **必须按顺序执行。** 不要跳过“任务类型判定”“目标日程定位（编辑流）”“补默认值/继承基线信息”“判断时间明确性”这些前置步骤。
-
-> **💡 核心原则：做智能助理，充分利用默认值规则（如默认标题、时长、参与人等）自动补全信息。极力避免像“表单填写机”一样频繁打断并反问用户，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。**
+- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。**
+- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。**
+- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。
+- **新建流先补默认值，编辑流先继承已定位日程信息。**
+- **明确时间** → 进入 [明确时间分支](./lark-calendar-schedule-clear-time.md)
+- **模糊时间或无时间信息** → 进入 [模糊时间分支](./lark-calendar-schedule-fuzzy-time.md)
+- **BLOCKING REQUIREMENT**: 面临时间方案或会议室方案的选择时，必须先向用户展示选项并等待确认，禁止未经确认直接创建/更新日程。
+- **必须按顺序执行。** 不要跳过"任务类型判定""目标日程定位（编辑流）""补默认值/继承基线信息""判断时间明确性"这些前置步骤。
 
 ## 严禁行为
 
-- **严禁在未读取对应子命令文档（如 `lark-calendar-room-find.md`、`lark-calendar-suggestion.md`）的情况下直接调用命令！** 必须先阅读文档掌握最新参数要求与规范。
-- **严禁在尚未判断“新建”还是“编辑”之前，就直接进入创建日程或查会议室动作。**
-- **严禁把“给明天上午的‘产品发布会’加人/加群/加会议室”这类带有既有日程锚点 + 修改动词的请求，当成新建日程。** 这类请求必须先定位目标日程。
-- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一的 `event_id` 前，不得调用 `+update`、也不得基于猜测时间去查会议室。
-- **严禁在用户仅要求“查会议室”但未提供明确时间时，直接调用 `+room-find`！** 必须先默认一个合理时间范围，调用 `+suggestion` 拿到候选时间块，再将时间块传给 `+room-find`。
-- **不要在用户完全没给时间时，直接反问“你想约什么时候”。** 先补一个合理时间范围，再进入 `+suggestion`。
-- **不要在“需要会议室 + 时间模糊”的场景下，先让用户只选时间。** 应先批量查出每个候选时间对应的可用会议室，再让用户一次性完成选择。
-- **不要在用户已经选中 `+suggestion` 候选时间后，再重复调用 `+freebusy`。**
-- **不要在用户未明确说出城市时，仅凭园区/办公室名自动补城市。**
-- **严禁在面临时间方案或会议室方案的选择时（模糊时间、无时间或需要会议室），未经用户确认就擅自创建新日程或更新既有日程。**
+- **严禁在未读取对应子命令文档前直接调用命令。**
+- **严禁在尚未判断"新建"还是"编辑"之前，就直接进入创建日程或查会议室动作。**
+- **严禁把带有既有日程锚点 + 修改动词的请求当成新建日程。**
+- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一 `event_id` 前，不得调用 `+update`。
+- **严禁在面临时间/会议室方案选择时，未经用户确认就擅自创建/更新日程。**
 
 ## 适用场景
 
-- “帮我约个会”
-- “下周找时间和 XX 开会”
-- “帮我订个会议室”
-- “帮我找/搜索一个可用的会议室”
-- “帮我推荐一个我以前常用的会议室”
-- “查询明天下午可用的会议室”
-- “明天下午3点约个日程/日历”
-- “把明天上午的日程‘产品发布会’加上 小明
-- “给下周一的周会换个会议室”
-- “把这个日程改到明天下午，并加上学清 F201”
+- "帮我约个会" / "下周找时间和 XX 开会"
+- "帮我订/找/搜索一个可用会议室"
+- "明天下午3点约个日程"
+- "把明天上午的日程加上 小明"
+- "给下周一的周会换个会议室"
+- "把这个日程改到明天下午，并加上学清 F201"
 
 ## 核心概念
 
-- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。** 
-- **预定或查找会议室，均需先确定时间块。** 在推荐可用会议室后，应顺势引导用户完成最终的**日程落地**操作：创建新日程，或更新既有日程。
-
-## CRITICAL 约束
-
-- **在调用任何具体的 CLI 子命令（如 `+room-find`、`+suggestion`、`+freebusy`、`+create`）前，必须先读取其对应的 Markdown 文档。** 禁止仅凭记忆组装命令参数，以确保符合各命令最新的业务约束和格式规范。
-- **当用户说“查会议室”“找会议室”“搜可用会议室”等，默认意图是查询会议室可用性，而不是检索会议室资源名录。**
-- **必须严格按照下方【工作流】的步骤顺序完成任务。特别是单独查会议室时，若无明确时间，强制先走“模糊时间/无时间信息”分支调用 `+suggestion`。**
+- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。**
+- **预定或查找会议室，均需先确定时间块。**
+- **当用户说"查会议室""找会议室"，默认意图是查会议室可用性，不是检索会议室资源名录。**
 
 ## 任务类型判定
 
 | 类型 | 典型语言信号 | 第一动作 |
 |------|--------------|----------|
-| 新建日程 | “约个会”“安排一个会议”“新建日程”“帮我订个会议室开会” | 补默认值，再进入时间判断 |
-| 编辑已有日程 | “给某个日程加人/删人/加群/加会议室”“把某个日程改到…”“给这场会换个会议室” | 先定位目标日程 `event_id`，再进入后续流程 |
+| 新建日程 | "约个会""安排会议""新建日程""订个会议室开会" | 补默认值，再进入时间判断 |
+| 编辑已有日程 | "给某日程加人/删人/加会议室""把某日程改到…""换会议室" | 先定位目标 `event_id` |
 
-进一步规则：
+规则：
+- 只要同时出现**既有日程锚点**（标题、时间段、`这个日程`、`这场会`）和**修改动词**（添加、移除、改到、换），默认判定为编辑。
+- 对重复性日程的编辑，必须先定位到对应实例的 `event_id`。
 
-- 只要同时出现**既有日程锚点**（标题、时间段、`这个日程`、`这场会`、某次实例）和**修改动词**（添加、移除、调整、改到、换、延后、提前），默认判定为**编辑已有日程**。
-- 对重复性日程的编辑，必须先定位到对应实例的 `event_id`，不能直接拿原重复日程的 `event_id` 做更新。
-
-## 工作流
-
-### 1. 编辑已有日程：先定位目标日程
-
-一旦判定为编辑流，必须先定位目标日程；没有 `event_id` 就不能继续后续修改动作。
+## 编辑流：先定位目标日程
 
 定位规则：
+- 优先利用用户给出的标题、日期、时间范围等锚点，通过 `+agenda`、`+search-event` 或实例视图缩小范围
+- 命中多个候选日程时，必须向用户展示候选项并要求确认
+- 重复性日程必须继续定位到该次实例的 `event_id`
 
-- 优先利用用户给出的标题、日期、时间范围、`这个日程/这场会` 等锚点，通过 `+agenda`、`+search-event` 或实例视图缩小范围。
-- 如果命中多个候选日程，必须向用户展示候选项并要求确认，禁止自行猜测。
-- 如果是重复性日程的某一次实例，必须继续定位到该次实例的 `event_id`。
+编辑流分支路由：
 
-编辑流分支规则：
+| 编辑子场景 | 下一步 |
+|-----------|--------|
+| 仅增删普通参会人/群组，不改时间，不涉及会议室 | 直接 `+update`（详见 [lark-calendar-update.md](./lark-calendar-update.md)） |
+| 新增会议室，不改时间 | 基于已定位日程 start/end → [明确时间分支](./lark-calendar-schedule-clear-time.md) |
+| 只改时间，不涉及会议室 | 判断时间明确性 → 对应分支 |
+| 既改时间，又新增/更换会议室 | 先确定最终时间 → 再查会议室 → 落地 |
 
-- **仅增删普通参会人/群组，不改时间，也不涉及会议室**：定位完成后可直接进入最终 `+update`。
-- **新增会议室，但不改时间**：必须基于已定位日程的当前 `start/end` 作为时间块执行 `+room-find`，不能因为用户没重复说时间就退回“无时间信息”。
-- **既改时间，又新增会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；最终只增量添加新会议室，不自动删除已有会议室。
-- **既改时间，又更换会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；只有在用户明确表达“更换”时，最终才执行“移除旧会议室 + 添加新会议室”。
-- **只改时间，不涉及会议室**：沿用下方时间工作流，但最终落地必须是 `+update`，不是 `+create`。
+## 新建日程：智能推断默认值
 
-### 2. 新建日程：智能推断默认值
-以下信息智能推断，减少频繁询问用户：
+- **标题**：根据上下文自动生成；如无法推断，默认"会议"
+- **参会人**：如未指定，默认仅用户自己
+- **时长**：基于上下文推断；默认 30 分钟
+- **无时间信息**：默认推断合理区间（如"今天"或"近两天"），进入时间推荐流程，禁止询问用户
 
-- **标题**：根据上下文自动生成，例如“沟通对齐”“需求讨论”；如无法推断，默认为“会议”
-- **参会人**：如未明确指定其他人，默认参会人仅为**用户自己**
-- **时长**：基于会议类型和上下文动态推断；如无法推断，默认为 30 分钟
-- **无任何时间信息**：默认推断一个合理区间（如“今天”或“近两天”），并进入时间推荐流程，禁止询问用户
+搜索参与人出现多个结果无法唯一确定时，必须询问用户并记录长期记忆。
 
-当搜索特定参与人（人、群）出现多个结果无法唯一确定时，必须询问用户进行选择确认，并将该偏好记录为长期记忆，以便后续自动识别。
-
-### 3. 判断时间是否明确
-
-这一步判断的是**最终要落地的目标时间**，不是只看用户原句里有没有重复说时间。
+## 判断时间是否明确
 
 时间基准规则：
+- **新建流**：使用用户给出的时间，或默认补全出的时间范围
+- **编辑流且不改时间**：已定位日程的当前 `start/end` 就是明确时间
+- **编辑流且改时间**：用户想改到的新时间；若表达模糊，进入模糊时间分支
+**注意**: 在执行修改日程/会议时间的任务时，必须先获取原日程的持续时长。如果用户只提供了新的开始时间，你必须根据原时长自动计算出新的结束时间，严格保持原时长不变，禁止擅自改变原日程的时长。
 
-- **新建流**：使用用户给出的时间，或默认补全出的时间范围作为时间基准。
-- **编辑流且不改时间**：已定位日程的当前 `start/end` 就是时间基准。后续如需查会议室，直接使用这个明确时间块。
-- **编辑流且改时间**：用户想改到的新时间才是时间基准；若表达模糊，则进入 `+suggestion`。
+## 分支路由
 
-分两类处理：
+| 判定结果 | 下一步读取 |
+|----------|-----------|
+| 明确时间 | [schedule-clear-time.md](./lark-calendar-schedule-clear-time.md) |
+| 模糊时间 / 无时间信息 | [schedule-fuzzy-time.md](./lark-calendar-schedule-fuzzy-time.md) |
 
-- **明确时间**：如“明天下午3点”
-- **模糊时间**：如“明天下午”“下周找个时间”
-
-### 4. 明确时间
-
-明确时间时，需先判断是否需要会议室，如果需要，提前查询会议室；然后判断是否有时间冲突。这里的“明确时间”既可以来自用户直接表达，也可以来自已定位日程的原始时间。
-详见 [`+room-find`](./lark-calendar-room-find.md) 与 [`+freebusy`](./lark-calendar-freebusy.md)。
-
-```bash
-# 1. 如果需要会议室，提前查询会议室
-lark-cli calendar +room-find \
-  --slot "<start>~<end>" \
-  --attendee-ids "<ids>" \
-  --city "<city>" \
-  --building "<building>" \
-  --floor "<F2>" \
-  --room-name "<room_name>"
-
-# 2. 查询当前用户及其他参会人忙闲
-# （如果有多名参会人，需分别调用查询：--user-id "<ou_xxx>"）
-lark-cli calendar +freebusy --start "<start>" --end "<end>"
-```
-
-规则：
-
-- **参会人过多或包含群组时的处理**：
-  - 如果参与人过多（例如超过 5 人），为避免高耗时，仅需查询**当前用户（自己）**及少数核心人员的忙闲状态即可。
-  - 如果参与人中包含**群组**，无需展开群组成员查询其忙闲状态。
-- **编辑已有日程且不改时间，只新增会议室时**：这里的 `--slot` 必须来自已定位日程的当前 `start/end`。
-- **编辑已有日程且既改时间又加会议室时**：这里的 `--slot` 必须来自候选新时间，而不是旧时间；如果用户是“新增会议室”，后续落地只做添加，不删除旧会议室。
-- **如果没有冲突**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程
-- **如果有冲突**：必须先说明冲突情况，询问用户继续选择这个时间还是换个时间
-  - **如果说换个时间**：放弃当前时间，转入【模糊时间】流程，调用 `+suggestion` 推荐多个可用时间块
-  - **如果继续选择这个时间**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程
-- 位置信息要优先拆到结构化字段：用户明确说了城市才提取 `--city`；`--building` 不要再重复携带城市前缀。
-- 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。像 `2L`、`2F` 这类更像楼层或区域定位的短词，优先视为 `--floor`，不要默认当作 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。
-- 会议室名要做轻量归一化：`木星会议室` -> `--room-name "木星"`；`会议室 02` / `02会议室` -> `--room-name "02"`。
-- 对 `F3-05` / `F5-07` / `3楼-08` 这类复合表达，若能稳定识别楼层与会议室号，应优先提取为 `--floor + --room-name`，不要把整段直接退化成 `--room-name`。
-
-### 5. 模糊时间或无时间信息
-
-先调用：
-详见 [`+suggestion`](./lark-calendar-suggestion.md)；若需要会议室，再结合 [`+room-find`](./lark-calendar-room-find.md)。
-
-```bash
-lark-cli calendar +suggestion \
-  --start "<range_start>" \
-  --end "<range_end>" \
-  --attendee-ids "<ids>" \
-  --duration-minutes <n> \
-  --event-rrule "<rrule>"
-```
-
-规则：
-
-- 若用户完全没有提供时间信息，应先默认一个合理区间后再调用 `+suggestion`
-- 编辑流中，若用户表达的是“改到明天下午”“下周找个时间再约”这类模糊新时间，则基于用户期望的新时间范围调用 `+suggestion`；不要继续沿用旧时间。
-- **不需要会议室**：获取多个推荐时间块后，直接向用户展示候选时间，用户确认后进入最终落地操作：创建新日程，或更新既有日程。
-- **需要会议室**：获取多个候选时间块后，**不要急于让用户选时间**。先将这些时间块一次性交给 `calendar +room-find` 批量查询可用会议室，然后将【候选时间】与【对应的可用会议室列表】结构化分行展示，让用户一次性完成选择。（**注意：即使用户最初只说“查会议室”，且未带时间，也必须强制走到这一步，先 suggestion 再 room-find**）。
-- 用户一旦选择了 `+suggestion` 返回的时间块，**无需再次调用 `+freebusy`**
-
-### 6. 模糊语义消解与长期记忆构建
-
-针对用户专属的时间表达习惯或存在歧义的时间场景，严禁主观臆断。典型例子包括：
-
-- “上班后”
-- “下班前”
-- 未明确上下午的 12 小时制时间表达
-
-处理规则：
-
-- 应主动澄清真实意图，而不是自行猜测
-- 当用户给出澄清后，应将这类个性化定义沉淀为长期偏好，推动后续直接理解类似表达
-
-### 7. 重复性日程
-
-若当前会议为重复性日程，调用 `+room-find` 时需携带 `--event-rrule`。
-
-必须检查返回中的：
-
-- `reserve_until_time`
-
-若候选会议室的可预约上限早于重复规则覆盖范围，**不要直接按原规则落地日程**。应：
-
-- 向用户明确说明该会议室最长可约至何时。
-- 若用户确认继续选用该会议室，你必须**自动将日程的重复规则结束时间缩短**至该 `reserve_until_time`，以防止会议室预约失败。
-
-### 8. 落地日程变更
+## 落地日程变更
 
 用户确认后调用：
-如果是新建会议，详见 [`+create`](./lark-calendar-create.md)。
-如果是更新既有日程，详见 [`+update`](./lark-calendar-update.md)。必须先定位目标 `event_id`，再按用户意图用 `+update` 独立执行字段更新、添加参会人/会议室、移除参会人/会议室，或组合这些动作。若用户意图是“新增会议室”，默认仅追加 `room_id`，不移除已有会议室。
+- 新建 → [`+create`](./lark-calendar-create.md)
+- 编辑 → [`+update`](./lark-calendar-update.md)
 
 ```bash
 lark-cli calendar +create \
@@ -214,52 +103,20 @@ lark-cli calendar +update \
   --start "<start>" \
   --end "<end>" \
   --add-attendee-ids "omm_new_room"
-
-# 仅当用户明确要求“更换会议室”时，才同时移除旧会议室并添加新会议室
-lark-cli calendar +update \
-  --event-id "<event_id>" \
-  --remove-attendee-ids "omm_old_room" \
-  --add-attendee-ids "omm_new_room"
 ```
 
-规则：
-- 新建日程时，可使用 `+create`
-- 更新既有日程时，优先使用 `+update`。改时间/标题/描述、添加参会人/会议室、移除参会人/会议室可以分别独立执行；
-- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新按标题猜测一次目标日程。
-- 编辑流中如果只是新增群组或普通参会人，不涉及时间和会议室，可直接 `+update --add-attendee-ids ...`。
-- 编辑流中如果是“新增会议室但不改时间”，必须先基于目标日程原始时间查到可用会议室，再 `+update --add-attendee-ids "<room_id>"`；默认保留已有会议室。
-- 编辑流中如果是“既改时间又新增会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间与新增会议室；默认保留已有会议室。
-- 编辑流中如果是“既改时间又更换会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间、移除旧会议室并添加新会议室。
-- 需要会议室时，将选中的 `room_id` 写入最终落地请求的参与人列表
-- 展示会议室候选时，必须保留 CLI/API 返回的完整 `room_name` 原值；允许附加“推断说明”，但禁止用摘要名、楼层及会议室号、容量/视频标签重组后的名称替换原值
-
-## 用户展示建议
-
-当向用户展示多个时间块及对应的多个会议室时，**必须使用结构化清晰的格式排版**。**严禁将时间与会议室名称放在同一行展示**，必须分行并使用编号列表呈现可用会议室，严禁将所有信息揉成一团纯文本堆叠。
-
-**推荐展示格式参考：**
-
-```text
-## 2026-03-27 周五
-
-[选项 1] 14:00 - 15:00（参会人均空闲）
-  可用会议室：
-  1. 学清嘉创大厦B座-F2-02🎦(7人)
-  2. 学清嘉创大厦B座-F2-05🎦(10人)
-
-[选项 2] 16:00 - 17:00（参会人均空闲）
-  可用会议室：
-  1. 学清嘉创大厦B座-F3-01🎦(6人)
-  2. 学清嘉创大厦B座-F3-06🎦(8人)
-
-💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。
-```
+落地规则：
+- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新猜测目标日程
+- 编辑流中"新增会议室"默认仅追加 `room_id`，不移除已有会议室
+- 仅当用户明确说"更换会议室"时，才同时 `--remove-attendee-ids` 旧 + `--add-attendee-ids` 新
+- 需要会议室时，将选中的 `room_id` 写入参与人列表
 
 ## 参考
 
+- [lark-calendar-schedule-clear-time.md](./lark-calendar-schedule-clear-time.md)
+- [lark-calendar-schedule-fuzzy-time.md](./lark-calendar-schedule-fuzzy-time.md)
 - [lark-calendar-room-find.md](./lark-calendar-room-find.md)
-- [lark-calendar-freebusy.md](./lark-calendar-freebusy.md)
 - [lark-calendar-suggestion.md](./lark-calendar-suggestion.md)
 - [lark-calendar-create.md](./lark-calendar-create.md)
-- [lark-shared](../../lark-shared/SKILL.md)
-- [lark-calendar](../SKILL.md)
+- [lark-calendar-update.md](./lark-calendar-update.md)
+- [SKILL.md](../SKILL.md)

skills/lark-calendar/references/lark-calendar-search-event.md

@@ -1,29 +0,0 @@
-
-# calendar +search-event
-
-按关键词、时间范围和参会人搜索日历日程。只读。
-
-## 命令
-
-```bash
-# 按关键词
-lark-cli calendar +search-event --query "周会"
-
-# 按时间范围（ISO 8601 或 YYYY-MM-DD）
-lark-cli calendar +search-event --start "2026-04-20T00:00:00+08:00" --end "2026-04-27T23:59:59+08:00"
-
-# 按参会人（自动识别 ou_ 用户 / oc_ 群聊 / omm_ 会议室前缀）
-lark-cli calendar +search-event --attendee-ids "ou_user1,oc_chat1,omm_room1"
-
-# 组合
-lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27 --attendee-ids "ou_user1"
-```
-
-## 输出字段
-
-`items` 列表每条返回 `event_id` / `summary` / `start` / `end` / `is_all_day` / `app_link`；外层有 `has_more`、`page_token`。**仅返回基础字段，要拿日程详情用 `calendar events get`。**
-
-## 注意事项
-
-- 分页：`has_more=true` 时持续用 `page_token` 翻页直到 false，不要遗漏；`page-size` 最大 30。
-- 已结束的会议优先用 `vc +search`——日历不收录"即时会议"，只查日程会漏。

skills/lark-calendar/references/lark-calendar-suggestion.md

@@ -1,6 +1,5 @@
 # calendar +suggestion
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
 
 根据非明确时间或一段时间范围，推荐多个可用时间块方案。帮助用户解决协调时间的难题。
 
@@ -8,8 +7,6 @@
 - ✅ **当用户需求涉及寻找时间块，且时间未完全确定**（如`今天`、`近三天`、`本周`、`下午`, `无时间描述`）时，调用此工具来获取推荐时间块给用户选择（包括但不限于预约日程）。
 - ❌ **当用户已经明确了具体的时间点**（如`今天下午3点`），则**不需要**调用此工具
 
-需要的scopes: ["calendar:calendar.free_busy:read"]
-
 ## 命令
 
 ```bash
@@ -121,5 +118,4 @@ lark-cli calendar +suggestion \
 ## 参考
 
 - [lark-calendar-create](lark-calendar-create.md) — 创建日程
-- [lark-calendar-freebusy](lark-calendar-freebusy.md) — 查询忙闲时段和rsvp状态
-- [lark-calendar](../SKILL.md) — 日历完整 API
+- [lark-calendar](../SKILL.md) — skill 入口与路由

skills/lark-calendar/references/lark-calendar-update.md

@@ -1,13 +1,10 @@
 # calendar +update
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 更新既有日程字段，或独立增量添加/移除参会人和会议室。
 
 `+update` 支持三类互相独立的动作：更新日程字段、添加参会人/会议室、移除参会人/会议室。它们可以单独执行，也可以在同一次命令中组合执行。
 
-需要的 scopes: ["calendar:calendar.event:update"]
-
 ## 推荐命令
 
 ```bash
@@ -66,8 +63,8 @@ lark-cli calendar +update \
 - 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。
 - 会议室是 resource attendee，必须使用 `omm_` ID 添加到参会人列表，不能脱离日程单独预定。
 - 更新重复性日程时，必须先确定操作范围（仅此次/全部/此次及后续），然后按 [重复性日程操作规范](lark-calendar-recurring.md) 执行。
-- 如果需要验证更新结果，等待至少 2 秒后再查询，避免同步延迟导致读到旧数据。
 - 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。
+**⚠️ 高风险操作**: 修改时间时必须先读取原日程时长并计算新 end。如果 end 计算错误，会导致日程时长变化，用户会直接感知，禁止擅自改变原日程的时长。
 
 ## 高级用法（完整 API 命令）
 
@@ -98,8 +95,6 @@ lark-cli calendar +update \
 
 ## 参考
 
-- [lark-calendar](../SKILL.md) -- 日历全部命令
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-calendar](../SKILL.md) -- skill 入口与路由
 - [lark-calendar-schedule-meeting](lark-calendar-schedule-meeting.md) -- 预约/改约会议与会议室工作流
 - [lark-calendar-room-find](lark-calendar-room-find.md) -- 查找可用会议室
-- [lark-calendar-freebusy](lark-calendar-freebusy.md) -- 查询忙闲

skills/lark-drive/SKILL.md

@@ -37,6 +37,7 @@ metadata:
 - 用户要在云空间（云盘/云存储）里新建文件夹，优先使用 `lark-cli drive +create-folder`。
 - 用户要查看某个文件有哪些可下载预览格式，或想下载 PDF / HTML / 文本 / 图片等预览产物，使用 `lark-cli drive +preview`。
 - 用户要获取某个文件的封面图，优先使用 `lark-cli drive +cover`；先 `--list-only` 看规格，再选 `--spec` 下载。
+- 用户要导出云文档时，优先使用 `lark-cli drive +export --url '<文档 URL>' --file-extension <格式>`；URL 会自动解析类型和 token，Wiki URL 会自动解析到底层 `obj_token/obj_type`。只有手里只有裸 token 时才使用 `--token <TOKEN> --doc-type <doc|docx|sheet|bitable|slides|wiki>`；裸 Wiki token 推荐显式传 `--doc-type wiki`，CLI 会先解析 Wiki node；如果误按底层类型传参且 export task 返回 `file token invalid`，CLI 也会尝试按 Wiki node token 解析并重试一次。
 - 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 - 用户给的是 wiki URL / token，且后续还没明确底层资源类型时，先用 `lark-cli drive +inspect` 解包；`+inspect` 失败后不要自动切到别的写接口继续尝试，先按错误提示处理权限、scope 或链接问题。

skills/lark-drive/references/lark-drive-export.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-把 `doc` / `docx` / `sheet` / `bitable` / `slides` 导出到本地文件。这个 shortcut 内置有限轮询：
+把 `doc` / `docx` / `sheet` / `bitable` / `slides`（也支持 Wiki URL / Wiki node token 自动解包）导出到本地文件。这个 shortcut 内置有限轮询：
 
 - 如果导出任务在轮询窗口内完成，会直接下载到本地目录
 - 如果轮询结束仍未完成，会返回 `ticket`、`ready=false`、`timed_out=true` 和 `next_command`
@@ -13,6 +13,29 @@
 ## 命令
 
 ```bash
+# 推荐：直接传 URL，CLI 自动解析类型和 token
+lark-cli drive +export \
+  --url "https://example.feishu.cn/docx/<DOCX_TOKEN>" \
+  --file-extension pdf
+
+# Wiki URL 也推荐直接传，CLI 会先解析到底层 obj_token/obj_type
+lark-cli drive +export \
+  --url "https://example.feishu.cn/wiki/<WIKI_NODE_TOKEN>" \
+  --file-extension pdf
+
+# 只有裸 Wiki node token 时，显式传 --doc-type wiki，让 CLI 先解析到底层文档类型
+lark-cli drive +export \
+  --token "<WIKI_NODE_TOKEN>" \
+  --doc-type wiki \
+  --file-extension pdf
+
+# 兼容兜底：如果误把 Wiki token 搭配底层类型传入，且 export task 返回 file token invalid，
+# CLI 会尝试按 Wiki node token 解析并重试一次；但新脚本仍推荐上面的 --doc-type wiki
+lark-cli drive +export \
+  --token "<WIKI_NODE_TOKEN>" \
+  --doc-type docx \
+  --file-extension pdf
+
 # 导出新版文档为 pdf，默认保存到当前目录
 lark-cli drive +export \
   --token "<DOCX_TOKEN>" \
@@ -96,8 +119,9 @@ lark-cli drive +export \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--token` | 是 | 源文档 token |
-| `--doc-type` | 是 | 源文档类型：`doc` / `docx` / `sheet` / `bitable` / `slides` |
+| `--url` | 与 `--token` 二选一 | 源文档 URL，推荐优先使用；CLI 自动解析类型和 token，Wiki URL 会解析到底层 `obj_token/obj_type` |
+| `--token` | 与 `--url` 二选一 | 源文档裸 token；裸 token 必须同时传 `--doc-type`。裸 Wiki node token 推荐传 `--doc-type wiki`，CLI 会先解析到底层 `obj_token/obj_type`；如误传底层类型并触发 export task `file token invalid`，CLI 会尝试按 Wiki node token 解析并重试一次 |
+| `--doc-type` | 条件必填 | 源文档类型：`doc` / `docx` / `sheet` / `bitable` / `slides` / `wiki`；仅当使用裸 `--token` 时必填，使用 `--url` 时自动推断。`wiki` 只用于裸 Wiki node token，解析后会按真实底层类型发起导出 |
 | `--file-extension` | 是 | 导出格式：`docx` / `pdf` / `xlsx` / `csv` / `markdown` / `base` / `pptx` |
 | `--sub-id` | 条件必填 | 当 `sheet` / `bitable` 导出为 `csv` 时必填 |
 | `--only-schema` | 否 | 仅当 `--doc-type bitable --file-extension base` 时可用；只导出多维表格结构，不导出记录数据 |
@@ -107,12 +131,17 @@ lark-cli drive +export \
 
 ## 关键约束
 
-- `markdown` 只支持 `docx`
-- `base` 只支持 `bitable`
-- `--only-schema` 只支持 `bitable` 导出为 `.base`，用于仅导出表结构
-- `pptx` 只支持 `slides`
+- 推荐优先传 `--url`，不要从 URL 手工拆 token 和 type；尤其是 Wiki URL，CLI 会自动解包到底层资源
+- `--url` 和 `--token` 互斥
+- 裸 `--token` 必须传 `--doc-type`；裸 Wiki node token 使用 `--doc-type wiki`
+- `doc` 支持导出为 `docx` / `pdf`
+- `docx` 支持导出为 `docx` / `pdf` / `markdown`
+- `sheet` 支持导出为 `xlsx` / `csv` / `pdf`
+- `bitable` 支持导出为 `xlsx` / `csv` / `base` / `pdf`
 - `slides` 支持导出为 `pptx` / `pdf`
-- `sheet` / `bitable` 导出为 `csv` 时必须带 `--sub-id`
+- `csv` 只支持 `sheet` / `bitable`，且必须带 `--sub-id`
+- `--only-schema` 只支持 `bitable` 导出为 `.base`，用于仅导出表结构
+- 如果格式不匹配，CLI 会返回 typed validation error，并在 `hint` 中给出可重试的 `--file-extension` 建议；例如 `docx + csv` 会提示改用 `docx/pdf/markdown`，或改传 sheet/bitable URL
 - shortcut 内部固定有限轮询：最多 10 次，每次间隔 5 秒
 - 轮询超时不是失败；会返回 `ticket`、`timed_out=true` 和 `next_command`，供后续继续查询
 
@@ -121,8 +150,7 @@ lark-cli drive +export \
 ```bash
 # 第一步：先尝试直接导出
 lark-cli drive +export \
-  --token "<DOCX_TOKEN>" \
-  --doc-type docx \
+  --url "<DOCX_URL>" \
   --file-extension pdf \
   --file-name "weekly-report.pdf"
 

skills/lark-minutes/references/lark-minutes-download.md

@@ -1,7 +1,6 @@
 
 # minutes +download
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 下载妙记的音视频媒体文件到本地，或获取有效期 1 天的下载链接。只读操作。
 
@@ -134,4 +133,3 @@ API 限流 5 次/秒，批量下载时需注意控制频率。
 
 - [lark-minutes](../SKILL.md) — 妙记全部命令
 - [lark-minutes-detail](lark-minutes-detail.md) — 妙记详情与 AI 产物查询
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-minutes/references/lark-minutes-search.md

@@ -1,6 +1,5 @@
 # minutes +search
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 搜索妙记列表，支持关键词、所有者、参与者以及时间范围等多条件过滤。所有者与参与者都支持传入多个 open\_id，也支持传入 `me` 表示当前用户。只读操作，不修改任何妙记数据。
 
@@ -199,6 +198,5 @@ lark-cli minutes +detail --minute-tokens <minute_token> --summary
 
 - [lark-minutes](../SKILL.md) -- 妙记相关命令
 - [lark-minutes-detail](lark-minutes-detail.md) -- 基于 `minute_token` 获取逐字稿、总结、待办、章节等产物
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
 - [lark-vc](../../lark-vc/SKILL.md) -- 视频会议全部命令
 

skills/lark-minutes/references/lark-minutes-speaker-replace.md

@@ -1,6 +1,5 @@
 # minutes +speaker-replace
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 替换妙记逐字稿中的说话人身份：把妙记逐字稿里"原说话人"对应的所有发言段，重新归属到"新说话人"。常用于解决妙记自动识别错说话人，或需要把外部/非飞书说话人改绑到正确飞书用户的场景。
 
@@ -106,4 +105,3 @@ Agent 必须先 `lark-cli api GET .../speakerlist`，再 `+speaker-replace`；`-
 ## 参考
 
 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-minutes/references/lark-minutes-summary.md

@@ -1,6 +1,5 @@
 # minutes +summary
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 替换妙记的 AI 总结内容。写操作，会覆盖当前总结。
 
@@ -119,4 +118,3 @@ lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @sum
 - [lark-minutes](../SKILL.md) — 妙记全部命令
 - [minutes +todo](lark-minutes-todo.md) — 替换待办项
 - [minutes +detail](lark-minutes-detail.md) — 读取总结、待办等 AI 产物
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-minutes/references/lark-minutes-todo.md

@@ -2,7 +2,6 @@
 
 > **路由**：本命令操作**妙记内的 AI 待办**，不是飞书任务（Task）。用户说「在妙记里新建待办」时**必须**用本命令，**禁止**走 `lark-cli task` / `tasklists list` / `task +create`。详见 [lark-minutes/SKILL.md](../SKILL.md) 第 6 节。
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 对妙记中的待办做新增 / 更新 / 删除（单条或批量）。写操作。
 
@@ -135,4 +134,3 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add -
 - [lark-minutes](../SKILL.md)
 - [minutes +summary](lark-minutes-summary.md)
 - [minutes +detail](lark-minutes-detail.md)
-- [lark-shared](../../lark-shared/SKILL.md)

skills/lark-minutes/references/lark-minutes-update.md

@@ -1,6 +1,5 @@
 # minutes +update
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 修改飞书妙记的标题（topic）。
 
@@ -38,4 +37,3 @@ lark-cli minutes +update --minute-token xxx --topic "周会纪要 2026-05-18"
 ## 参考
 
 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-minutes/references/lark-minutes-upload.md

@@ -1,6 +1,5 @@
 # minutes +upload
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 上传音视频文件到飞书妙记并生成妙记（Minute）。
 
@@ -31,12 +30,12 @@
      ```
    - 命令执行成功后，将返回生成的妙记链接 `minute_url`。
 
-3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，继续提取 `minute_token` 调用 `minutes +detail`**
-   - 从返回的 `minute_url` 中提取路径最后一段，得到 `minute_token`。
-   - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，继续调用：
+3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，使用返回的 `minute_token` 调用 `minutes +detail`**
+   - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，使用上一步返回的 `minute_token` 继续调用：
      ```bash
-     lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --keyword --transcript
+     lark-cli minutes +detail --minute-tokens <minute_token> --wait-ready --summary --todo --chapter --keyword --transcript
      ```
+   - `--wait-ready` 参数表示等待妙记生成完毕后再获取产物，上传后立即读取详情时必须加上此参数。
    - `minutes +detail --minute-tokens` 会返回妙记产物（总结、待办、章节、关键词、逐字稿）；必要时还会把逐字稿落地到本地文件。
 
 > **异步生成提示**：API 会立即返回 `minute_url`，但妙记可能仍在异步生成中，您可以直接通过该妙记链接查看当前的处理状态和转写结果。
@@ -47,8 +46,8 @@
 # 通过已上传到云空间（云盘/云存储）的 file_token 生成妙记
 lark-cli minutes +upload --file-token boxcnxxxxxxxxxxxxxxxx
 
-# 通过 minute_token 继续获取妙记产物（--summary --todo --chapter --keyword --transcript 按需传入）
-lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary
+# 上传后立即获取妙记产物，需加 --wait-ready 等待生成完毕（--summary --todo --chapter --keyword --transcript 按需传入）
+lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --wait-ready --summary
 ```
 
 ## 参数
@@ -81,7 +80,7 @@ lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary
 1. 使用 `lark-cli drive +upload --file <path>` 上传本地音视频文件到云空间（云盘/云存储）
 2. 从返回结果中取出 `file_token`
 3. 调用 `lark-cli minutes +upload --file-token <file_token>` 生成妙记
-4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，再从 `minute_url` 提取 `minute_token`，继续调用 `lark-cli minutes +detail --minute-tokens <minute_token>`
+4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，使用返回的 `minute_token`，继续调用 `lark-cli minutes +detail --minute-tokens <minute_token> --wait-ready`
 
 > **边界说明**：`minutes +upload` 本身只负责把文件转成妙记并返回 `minute_url`。纪要内容、逐字稿、文字稿、撰写文字、总结、待办、章节属于后续产物获取，应由 [minutes +detail](lark-minutes-detail.md) 承接。
 
@@ -89,16 +88,17 @@ lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary
 
 ```json
 {
-  "minute_url": "http(s)://<host>/minutes/<minute-token>"
+  "minute_url": "http(s)://<host>/minutes/<minute-token>",
+  "minute_token": "<minute-token>"
 }
 ```
 
 | 字段 | 说明 |
 |------|------|
 | `minute_url` | 生成的妙记访问链接 |
+| `minute_token` | 从 `minute_url` 提取出的妙记 Token，可直接传给 `minutes +detail --minute-tokens` |
 
 ## 参考
 
 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明
 - [drive +upload](../../lark-drive/references/lark-drive-upload.md) -- 上传文件到云空间（云盘/云存储）
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-vc/references/lark-vc-recording.md

@@ -1,7 +1,6 @@
 
 # vc +recording
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 通过 meeting_id 或 calendar_event_id 查询对应的 minute_token。这是 VC 域和 Minutes 域之间的桥梁命令。只读操作。
 
@@ -151,4 +150,3 @@ lark-cli minutes +download --minute-tokens <minute_token>
 - [lark-vc](../SKILL.md) — 视频会议全部命令
 - [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
 - [lark-minutes-detail](../../lark-minutes/references/lark-minutes-detail.md) — 获取会议纪要
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

tests/cli_e2e/drive/coverage.md

@@ -14,7 +14,7 @@
 - TestDriveAddCommentDryRun_File / TestDriveAddCommentDryRun_Base: dry-run coverage for `drive +add-comment` on supported Drive file and Base targets; pins the `metas.batch_query -> files/:token/new_comments` file chain, Base `file_type=bitable`, and Base anchor fields.
 - TestDriveAddCommentMarkdownFileWorkflow: opt-in live workflow skeleton for the same path, gated by `LARK_DRIVE_MD_COMMENT_E2E=1`.
 - TestDrive_SecureLabelDryRun: dry-run coverage for `drive +secure-label-list` and `drive +secure-label-update`; asserts label-list query params and update URL→type inference, request method/URL/type query, and `label-id` body shape. Runs without hitting live APIs because update can trigger document-level security approval flows.
-- TestDriveExportDryRun_FileNameMetadata / TestDriveExportDryRun_MarkdownFetchAPI / TestDriveExportDryRun_BitableBaseOnlySchema: dry-run coverage for `drive +export`; asserts export task request shape, markdown fetch request shape without docs fetch `extra_param`, local `--file-name` / `--output-dir` metadata, and `bitable` `.base` `only_schema` request body without calling live APIs.
+- TestDriveExportDryRun_FileNameMetadata / TestDriveExportDryRun_WikiURLPlansResolveBeforeExportTask / TestDriveExportDryRun_WikiTokenTypePlansResolveBeforeExportTask / TestDriveExportDryRun_MarkdownFetchAPI / TestDriveExportDryRun_BitableBaseOnlySchema: dry-run coverage for `drive +export`; asserts export task request shape, Wiki URL and `--doc-type wiki` token `get_node -> export_tasks` planning, markdown fetch request shape without docs fetch `extra_param`, local `--file-name` / `--output-dir` metadata, and `bitable` `.base` `only_schema` request body without calling live APIs.
 - TestDrive_PullDryRun / TestDrive_PullDryRunAcceptsDuplicateRemoteStrategies: dry-run coverage for `drive +pull`; asserts the list-files request shape, Validate-stage safety guards, and acceptance of `--on-duplicate-remote=rename|newest|oldest` by the real CLI binary.
 - TestDrive_PushDryRun / TestDrive_PushDryRunAcceptsDuplicateRemoteStrategies: dry-run coverage for `drive +push`; asserts the list-files request shape, Validate-stage safety guards, conditional delete preflight, and acceptance of `--on-duplicate-remote=newest|oldest` by the real CLI binary.
 - Cleanup note: `drive files delete` is only exercised in cleanup and is intentionally left uncovered.
@@ -29,7 +29,7 @@
 | ✓ | drive +apply-permission | shortcut | drive_apply_permission_dryrun_test.go::TestDrive_ApplyPermissionDryRun | `--token` URL vs bare; `--type` (enum) with URL inference; `--perm view\|edit`; `--remark` optional | dry-run only; no live-apply E2E because a real request pushes a card to the owner |
 | ✕ | drive +delete | shortcut |  | none | no primary delete workflow yet |
 | ✕ | drive +download | shortcut |  | none | no file fixture workflow yet |
-| ✓ | drive +export | shortcut | drive_export_dryrun_test.go::TestDriveExportDryRun_FileNameMetadata + TestDriveExportDryRun_MarkdownFetchAPI + TestDriveExportDryRun_BitableBaseOnlySchema | `--token`; `--doc-type`; `--file-extension`; `--file-name`; `--output-dir`; `--only-schema`; markdown fetch omits docs fetch `extra_param` | dry-run only; no live export workflow yet |
+| ✓ | drive +export | shortcut | drive_export_dryrun_test.go::TestDriveExportDryRun_FileNameMetadata + TestDriveExportDryRun_WikiURLPlansResolveBeforeExportTask + TestDriveExportDryRun_WikiTokenTypePlansResolveBeforeExportTask + TestDriveExportDryRun_MarkdownFetchAPI + TestDriveExportDryRun_BitableBaseOnlySchema | `--url`; `--token`; `--doc-type`; `--file-extension`; `--file-name`; `--output-dir`; `--only-schema`; Wiki URL / `--doc-type wiki` resolve step; markdown fetch omits docs fetch `extra_param` | dry-run only; no live export workflow yet |
 | ✕ | drive +export-download | shortcut |  | none | no export-download workflow yet |
 | ✕ | drive +import | shortcut |  | none | no import workflow yet |
 | ✕ | drive +move | shortcut |  | none | no move workflow yet |

tests/cli_e2e/drive/drive_export_dryrun_test.go

@@ -61,6 +61,96 @@ func TestDriveExportDryRun_FileNameMetadata(t *testing.T) {
 	}
 }
 
+func TestDriveExportDryRun_WikiURLPlansResolveBeforeExportTask(t *testing.T) {
+	setDriveDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+export",
+			"--url", "https://example.feishu.cn/wiki/wikiDryRunExport",
+			"--file-extension", "pdf",
+			"--file-name", "wiki-report",
+			"--output-dir", "./exports",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	if got := gjson.Get(out, "api.0.method").String(); got != "GET" {
+		t.Fatalf("api.0.method=%q, want GET\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.url").String(); got != "/open-apis/wiki/v2/spaces/get_node" {
+		t.Fatalf("api.0.url=%q, want wiki get_node\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.params.token").String(); got != "wikiDryRunExport" {
+		t.Fatalf("api.0.params.token=%q, want wiki token\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.method").String(); got != "POST" {
+		t.Fatalf("api.1.method=%q, want POST\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.url").String(); got != "/open-apis/drive/v1/export_tasks" {
+		t.Fatalf("api.1.url=%q, want export_tasks\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.body.token").String(); got != "obj_token_from_step_0" {
+		t.Fatalf("api.1.body.token=%q, want resolved token placeholder\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.body.type").String(); got != "obj_type_from_step_0" {
+		t.Fatalf("api.1.body.type=%q, want resolved type placeholder\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "wiki_token").String(); got != "wikiDryRunExport" {
+		t.Fatalf("wiki_token=%q, want source wiki token\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "file_name").String(); got != "wiki-report.pdf" {
+		t.Fatalf("file_name=%q, want wiki-report.pdf\nstdout:\n%s", got, out)
+	}
+}
+
+func TestDriveExportDryRun_WikiTokenTypePlansResolveBeforeExportTask(t *testing.T) {
+	setDriveDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+export",
+			"--token", "wikiDryRunExport",
+			"--doc-type", "wiki",
+			"--file-extension", "pdf",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	if got := gjson.Get(out, "api.0.method").String(); got != "GET" {
+		t.Fatalf("api.0.method=%q, want GET\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.url").String(); got != "/open-apis/wiki/v2/spaces/get_node" {
+		t.Fatalf("api.0.url=%q, want wiki get_node\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.params.token").String(); got != "wikiDryRunExport" {
+		t.Fatalf("api.0.params.token=%q, want wiki token\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.body.token").String(); got != "obj_token_from_step_0" {
+		t.Fatalf("api.1.body.token=%q, want resolved token placeholder\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.body.type").String(); got != "obj_type_from_step_0" {
+		t.Fatalf("api.1.body.type=%q, want resolved type placeholder\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "wiki_token").String(); got != "wikiDryRunExport" {
+		t.Fatalf("wiki_token=%q, want source wiki token\nstdout:\n%s", got, out)
+	}
+}
+
 func TestDriveExportDryRun_MarkdownFetchAPI(t *testing.T) {
 	setDriveDryRunConfigEnv(t)