feat(slides): add slides chart demo reference

CHANGELOG.md

@@ -2,33 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [v1.0.66] - 2026-07-07
-
-### Features
-
-- support semantic recurring calendar operations (#1723)
-- minute wait (#1768)
-
-### Bug Fixes
-
-- guide drive import concurrency conflicts (#1751)
-- **calendar**: guide approval room booking fallback (#1637)
-- support pnpm global installs in self-update (#1705)
-- resolve schema against runtime metadata in plugin builds; gate cache overlay by version (#1764)
-
-### Documentation
-
-- tighten doc creation validation workflow (#1759)
-- clarify success envelope contract — judge success by ok, not code (#1730)
-
-### Refactoring
-
-- **envvars**: consolidate agent env value access (#1757)
-
-### Misc
-
-- Improve agent-facing error guidance for drive, markdown, and wiki (#1779)
-
 ## [v1.0.65] - 2026-07-03
 
 ### Features
@@ -1398,7 +1371,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
-[v1.0.66]: https://github.com/larksuite/cli/releases/tag/v1.0.66
 [v1.0.65]: https://github.com/larksuite/cli/releases/tag/v1.0.65
 [v1.0.64]: https://github.com/larksuite/cli/releases/tag/v1.0.64
 [v1.0.62]: https://github.com/larksuite/cli/releases/tag/v1.0.62

cmd/schema/schema.go

@@ -65,13 +65,13 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	return cmd
 }
 
-// completeSchemaPath is a thin adapter over the schema catalog's Complete.
-// It uses the same source as schema execution so completion candidates match
-// what `schema` can resolve.
+// completeSchemaPath is a thin adapter over the embedded catalog's Complete.
+// It uses the embedded source so completion candidates match what `schema`
+// execution can resolve (both overlay-free).
 func completeSchemaPath(f *cmdutil.Factory) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
 	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		mode := f.ResolveStrictMode(cmd.Context())
-		completions, noSpace := registry.SchemaCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
+		completions, noSpace := registry.EmbeddedCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
 		directive := cobra.ShellCompDirectiveNoFileComp
 		if noSpace {
 			directive |= cobra.ShellCompDirectiveNoSpace
@@ -86,19 +86,13 @@ func schemaRun(opts *SchemaOptions) error {
 	return runSchema(out, apicatalog.ParsePath(opts.Args), mode)
 }
 
-// runSchema resolves the path through the schema catalog and renders the
+// runSchema resolves the path through the embedded catalog and renders the
 // matching envelope(s). The catalog owns navigation (Resolve + MethodRefs) and
 // schema owns rendering (Envelope/Envelopes); this adapter only chooses the
 // output shape — a single resolved method renders as one envelope object,
 // anything broader as an array — and maps resolve failures to hints.
 func runSchema(out io.Writer, parts []string, mode core.StrictMode) error {
-	catalog := registry.SchemaCatalog()
-	if len(catalog.Services()) == 0 {
-		// No embedded metadata and the runtime fallback is empty too: offline
-		// with a cold cache, remote meta off, or an unwritable cache dir.
-		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "No API metadata available").
-			WithHint("this binary has no embedded API metadata; run any command with network access to the open platform once so metadata can be fetched and cached")
-	}
+	catalog := registry.EmbeddedCatalog()
 	target, err := catalog.Resolve(parts)
 	if err != nil {
 		return resolveError(err)

cmd/update/update.go

@@ -102,8 +102,7 @@ func NewCmdUpdate(f *cmdutil.Factory) *cobra.Command {
 		Long: `Update lark-cli to the latest version.
 
 Detects the installation method automatically:
-  - npm install:  runs npm install -g @larksuite/cli@<version>
-  - pnpm install: runs pnpm add -g @larksuite/cli@<version>
+  - npm install: runs npm install -g @larksuite/cli@<version>
   - manual/other: shows GitHub Releases download URL
 
 Use --json for structured output (for AI agents and scripts).
@@ -165,7 +164,7 @@ func updateRun(opts *UpdateOptions) error {
 	if !detect.CanAutoUpdate() {
 		return doManualUpdate(opts, io, cur, latest, detect, updater)
 	}
-	return doAutoUpdate(opts, io, cur, latest, detect, updater)
+	return doNpmUpdate(opts, io, cur, latest, updater)
 }
 
 // --- Output helpers ---
@@ -227,23 +226,12 @@ func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest stri
 	fmt.Fprintf(io.ErrOut, "To update manually, download the latest release:\n")
 	fmt.Fprintf(io.ErrOut, "  Release:   %s\n", releaseURL(latest))
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
-	if detect.Method == selfupdate.InstallPnpm {
-		fmt.Fprintf(io.ErrOut, "\nOr install via pnpm (note: skills will not be synced):\n  pnpm add -g %s@%s\n  pnpm dlx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
-	} else {
-		fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
-	}
+	fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
-func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
-	pm := "npm"
-	install := updater.RunNpmInstall
-	if detect.Method == selfupdate.InstallPnpm {
-		pm = "pnpm"
-		install = updater.RunPnpmInstall
-	}
-
+func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, updater *selfupdate.Updater) error {
 	restore, err := updater.PrepareSelfReplace()
 	if err != nil {
 		return reportError(opts, io, "update_error",
@@ -251,19 +239,19 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 	}
 
 	if !opts.JSON {
-		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via %s ...\n", cur, symArrow(), latest, pm)
+		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via npm ...\n", cur, symArrow(), latest)
 	}
 
-	npmResult := install(latest)
+	npmResult := updater.RunNpmInstall(latest)
 	if npmResult.Err != nil {
 		restore()
 		combined := npmResult.CombinedOutput()
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok": false, "error": map[string]interface{}{
-					"type": "update_error", "message": fmt.Sprintf("%s install failed: %s", pm, npmResult.Err),
+					"type": "update_error", "message": fmt.Sprintf("npm install failed: %s", npmResult.Err),
 					"detail": selfupdate.Truncate(combined, maxNpmOutput),
-					"hint":   permissionHint(combined, pm),
+					"hint":   permissionHint(combined),
 				},
 			})
 			return output.ErrBare(output.ExitAPI)
@@ -275,7 +263,7 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 			fmt.Fprint(io.ErrOut, npmResult.Stderr.String())
 		}
 		fmt.Fprintf(io.ErrOut, "\n%s Update failed: %s\n", symFail(), npmResult.Err)
-		if hint := permissionHint(combined, pm); hint != "" {
+		if hint := permissionHint(combined); hint != "" {
 			fmt.Fprintf(io.ErrOut, "  %s\n", hint)
 		}
 		return output.ErrBare(output.ExitAPI)
@@ -286,7 +274,7 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 	if err := updater.VerifyBinary(latest); err != nil {
 		restore()
 		msg := fmt.Sprintf("new binary verification failed: %s", err)
-		hint := verificationFailureHint(updater, latest, pm)
+		hint := verificationFailureHint(updater, latest)
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok":    false,
@@ -316,33 +304,23 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 	fmt.Fprintf(io.ErrOut, "\n%s Successfully updated lark-cli from %s to %s\n", symOK(), cur, latest)
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
 	if skillsResult != nil {
-		skillsPM := "npx"
-		if detect.Method == selfupdate.InstallPnpm && detect.PnpmAvailable {
-			skillsPM = "pnpm dlx"
-		}
-		fmt.Fprintf(io.ErrOut, "\nUpdating skills via %s ...\n", skillsPM)
+		fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
 	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
-func permissionHint(pmOutput, pm string) string {
-	if !strings.Contains(pmOutput, "EACCES") || isWindows() {
-		return ""
+func permissionHint(npmOutput string) string {
+	if strings.Contains(npmOutput, "EACCES") && !isWindows() {
+		return "Permission denied. Try: sudo lark-cli update, or adjust your npm global prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors"
 	}
-	if pm == "pnpm" {
-		return "Permission denied. Ensure your pnpm global directory is writable — re-run `pnpm setup`, or see https://pnpm.io/pnpm-cli"
-	}
-	return "Permission denied. Try: sudo lark-cli update, or adjust your npm global prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors"
+	return ""
 }
 
-func verificationFailureHint(updater *selfupdate.Updater, latest, pm string) string {
+func verificationFailureHint(updater *selfupdate.Updater, latest string) string {
 	if updater.CanRestorePreviousVersion() {
 		return "the previous version has been restored"
 	}
-	if pm == "pnpm" {
-		return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): pnpm add -g %s@%s && pnpm dlx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
-	}
 	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): npm install -g %s@%s && npx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
 }
 

cmd/update/update_test.go

@@ -57,27 +57,6 @@ func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult, npmFn func(s
 	t.Cleanup(func() { newUpdater = origNew })
 }
 
-// mockDetectAndPnpm mirrors mockDetectAndNpm but wires the pnpm install path
-// and fails the test if the npm install path is invoked.
-func mockDetectAndPnpm(t *testing.T, result selfupdate.DetectResult, pnpmFn func(string) *selfupdate.NpmResult) {
-	t.Helper()
-	origNew := newUpdater
-	newUpdater = func() *selfupdate.Updater {
-		u := selfupdate.New()
-		u.DetectOverride = func() selfupdate.DetectResult { return result }
-		u.PnpmInstallOverride = pnpmFn
-		u.NpmInstallOverride = func(string) *selfupdate.NpmResult {
-			t.Errorf("npm install must not be called for a pnpm install")
-			return &selfupdate.NpmResult{}
-		}
-		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsIndexFetchOverride = successfulSkillsIndexFetch()
-		u.SkillsCommandOverride = successfulSkillsCommand()
-		return u
-	}
-	t.Cleanup(func() { newUpdater = origNew })
-}
-
 func successfulSkillsIndexFetch() func() *selfupdate.NpmResult {
 	return func() *selfupdate.NpmResult {
 		r := &selfupdate.NpmResult{}
@@ -102,110 +81,6 @@ func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
 	}
 }
 
-func TestUpdatePnpm_JSON(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _ := newTestFactory(t)
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{"--json"})
-	origFetch := fetchLatest
-	fetchLatest = func() (string, error) { return "2.0.0", nil }
-	defer func() { fetchLatest = origFetch }()
-	origVersion := currentVersion
-	currentVersion = func() string { return "1.0.0" }
-	defer func() { currentVersion = origVersion }()
-	mockDetectAndPnpm(t,
-		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
-		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-	)
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if out := stdout.String(); !strings.Contains(out, `"action": "updated"`) {
-		t.Errorf("expected updated in output, got: %s", out)
-	}
-}
-
-func TestUpdatePnpm_Human(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, stderr := newTestFactory(t)
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{})
-	origFetch := fetchLatest
-	fetchLatest = func() (string, error) { return "2.0.0", nil }
-	defer func() { fetchLatest = origFetch }()
-	origVersion := currentVersion
-	currentVersion = func() string { return "1.0.0" }
-	defer func() { currentVersion = origVersion }()
-	mockDetectAndPnpm(t,
-		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
-		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-	)
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	out := stderr.String()
-	if !strings.Contains(out, "via pnpm") {
-		t.Errorf("expected 'via pnpm' in stderr, got: %s", out)
-	}
-	if !strings.Contains(out, "Updating skills via pnpm dlx ...") {
-		t.Errorf("expected skills sync to report pnpm dlx launcher, got: %s", out)
-	}
-	if !strings.Contains(out, "Successfully updated") {
-		t.Errorf("expected success message, got: %s", out)
-	}
-}
-
-func TestUpdatePnpm_InstallError_JSON(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _ := newTestFactory(t)
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{"--json"})
-	origFetch := fetchLatest
-	fetchLatest = func() (string, error) { return "2.0.0", nil }
-	defer func() { fetchLatest = origFetch }()
-	origVersion := currentVersion
-	currentVersion = func() string { return "1.0.0" }
-	defer func() { currentVersion = origVersion }()
-	mockDetectAndPnpm(t,
-		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
-		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{Err: errors.New("pnpm boom")} },
-	)
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error exit")
-	}
-	if out := stdout.String(); !strings.Contains(out, `"ok": false`) || !strings.Contains(out, "update_error") {
-		t.Errorf("expected failure envelope, got: %s", out)
-	}
-	if out := stdout.String(); !strings.Contains(out, "pnpm install failed") {
-		t.Errorf("expected message to report pnpm as the package manager, got: %s", out)
-	}
-}
-
-func TestUpdatePnpm_Unavailable_ManualFallback(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, stderr := newTestFactory(t)
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{})
-	origFetch := fetchLatest
-	fetchLatest = func() (string, error) { return "2.0.0", nil }
-	defer func() { fetchLatest = origFetch }()
-	origVersion := currentVersion
-	currentVersion = func() string { return "1.0.0" }
-	defer func() { currentVersion = origVersion }()
-	mockDetect(t, selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: false})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	out := stderr.String()
-	if !strings.Contains(out, "installed via pnpm, but pnpm is not available in PATH") {
-		t.Errorf("expected pnpm manual reason, got: %s", out)
-	}
-	if !strings.Contains(out, "pnpm add -g") {
-		t.Errorf("expected pnpm add -g hint, got: %s", out)
-	}
-}
-
 func TestNormalizeVersion(t *testing.T) {
 	tests := []struct {
 		input string
@@ -391,9 +266,6 @@ func TestUpdateNpm_Human(t *testing.T) {
 	if !strings.Contains(out, "Successfully updated") {
 		t.Errorf("expected success message in stderr, got: %s", out)
 	}
-	if !strings.Contains(out, "Updating skills via npx ...") {
-		t.Errorf("expected skills sync to report npx launcher for npm install, got: %s", out)
-	}
 }
 
 func TestUpdateForce_JSON(t *testing.T) {
@@ -867,9 +739,9 @@ func TestPermissionHint(t *testing.T) {
 	origOS := currentOS
 	defer func() { currentOS = origOS }()
 
-	// Linux + npm: EACCES should produce a hint with npm prefix guidance.
+	// Linux: EACCES should produce a hint with npm prefix guidance.
 	currentOS = "linux"
-	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'", "npm")
+	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'")
 	if !strings.Contains(hint, "npm global prefix") {
 		t.Errorf("expected npm prefix hint on linux, got: %s", hint)
 	}
@@ -877,25 +749,16 @@ func TestPermissionHint(t *testing.T) {
 		t.Errorf("should not suggest raw sudo npm install, got: %s", hint)
 	}
 
-	// Linux + pnpm: EACCES should point at pnpm setup, not npm prefix/sudo.
-	pnpmHint := permissionHint("EACCES: permission denied, access '/Users/x/Library/pnpm'", "pnpm")
-	if !strings.Contains(pnpmHint, "pnpm setup") {
-		t.Errorf("expected pnpm setup hint, got: %s", pnpmHint)
-	}
-	if strings.Contains(pnpmHint, "npm global prefix") || strings.Contains(pnpmHint, "sudo") {
-		t.Errorf("pnpm hint must not reference npm prefix or sudo, got: %s", pnpmHint)
-	}
-
 	// Windows: EACCES hint is suppressed (no EACCES on Windows).
 	currentOS = "windows"
-	hint = permissionHint("EACCES: permission denied", "npm")
+	hint = permissionHint("EACCES: permission denied")
 	if hint != "" {
 		t.Errorf("expected empty hint on Windows, got: %s", hint)
 	}
 
 	// Non-EACCES error: always empty.
 	currentOS = "linux"
-	if got := permissionHint("some other error", "npm"); got != "" {
+	if got := permissionHint("some other error"); got != "" {
 		t.Errorf("expected empty hint for non-EACCES, got: %s", got)
 	}
 }

internal/affordance/affordance.go

@@ -77,10 +77,14 @@ func loadService(service string) map[string]json.RawMessage {
 // space→dot fallback covers domains where the two already coincide.
 func commandFormResolver(service string) func(string) string {
 	byForm := map[string]string{}
-	if svc, ok := registry.SchemaCatalog().Service(service); ok {
+	for _, svc := range registry.EmbeddedServicesTyped() {
+		if svc.Name != service {
+			continue
+		}
 		for _, ref := range apicatalog.ServiceMethods(svc, nil) {
 			byForm[strings.Join(ref.CommandPath()[1:], " ")] = ref.Method.ID
 		}
+		break
 	}
 	return func(h string) string {
 		h = strings.TrimSpace(h)

internal/cmdutil/secheader.go

@@ -6,10 +6,12 @@ package cmdutil
 import (
 	"context"
 	"net/http"
+	"os"
 	"reflect"
 	"runtime/debug"
 	"strings"
 	"sync"
+	"unicode"
 
 	"github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/extension/fileio"
@@ -38,6 +40,8 @@ const (
 	BuildKindUnknown  = "unknown"
 
 	officialModulePath = "github.com/larksuite/cli"
+
+	agentTraceMaxLen = 1024
 )
 
 // UserAgentValue returns the User-Agent value: "lark-cli/{version}".
@@ -45,6 +49,25 @@ func UserAgentValue() string {
 	return SourceValue + "/" + build.Version
 }
 
+// AgentTraceValue returns a header-safe value from the
+// LARKSUITE_CLI_AGENT_TRACE environment variable. It trims
+// surrounding whitespace, rejects values containing any Unicode
+// control character or exceeding agentTraceMaxLen, and returns ""
+// for any invalid or empty value. Callers can use the result
+// directly in HTTP headers without further sanitisation.
+func AgentTraceValue() string {
+	v := strings.TrimSpace(os.Getenv(envvars.CliAgentTrace))
+	if v == "" || len(v) > agentTraceMaxLen {
+		return ""
+	}
+	for _, r := range v {
+		if unicode.IsControl(r) {
+			return ""
+		}
+	}
+	return v
+}
+
 // BaseSecurityHeaders returns headers that every request must carry.
 func BaseSecurityHeaders() http.Header {
 	h := make(http.Header)
@@ -52,7 +75,7 @@ func BaseSecurityHeaders() http.Header {
 	h.Set(HeaderVersion, build.Version)
 	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
-	if v := envvars.AgentTrace(); v != "" {
+	if v := AgentTraceValue(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}
 	return h

internal/cmdutil/secheader_test.go

@@ -6,6 +6,7 @@ package cmdutil
 import (
 	"context"
 	"net/http"
+	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/extension/credential"
@@ -263,9 +264,88 @@ func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// HeaderAgentTrace injection (via BaseSecurityHeaders)
+// AgentTraceValue / HeaderAgentTrace
 // ---------------------------------------------------------------------------
 
+func TestAgentTraceValue_EmptyWhenEnvUnset(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty when env unset", got)
+	}
+}
+
+func TestAgentTraceValue_ReturnsCleanValue(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "trace-abc-123")
+	if got := AgentTraceValue(); got != "trace-abc-123" {
+		t.Fatalf("AgentTraceValue() = %q, want %q", got, "trace-abc-123")
+	}
+}
+
+func TestAgentTraceValue_TrimsWhitespace(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "  trace-trim  ")
+	if got := AgentTraceValue(); got != "trace-trim" {
+		t.Fatalf("AgentTraceValue() = %q, want %q (whitespace trimmed)", got, "trace-trim")
+	}
+}
+
+func TestAgentTraceValue_OnlyWhitespace_ReturnsEmpty(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "   ")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for whitespace-only value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsCRLF(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\r\nX-Evil: attack")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for CR/LF value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsLF(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\nX-Evil: attack")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for LF value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsTab(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\tinjected")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for tab value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsControlChar(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\x01injected")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for control char value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsDEL(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\x7finjected")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for DEL value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsOverlongValue(t *testing.T) {
+	longVal := strings.Repeat("a", agentTraceMaxLen+1)
+	t.Setenv(envvars.CliAgentTrace, longVal)
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() returned non-empty for %d-byte value (max %d)", len(longVal), agentTraceMaxLen)
+	}
+}
+
+func TestAgentTraceValue_AcceptsMaxLengthValue(t *testing.T) {
+	val := strings.Repeat("a", agentTraceMaxLen)
+	t.Setenv(envvars.CliAgentTrace, val)
+	if got := AgentTraceValue(); got != val {
+		t.Fatalf("AgentTraceValue() = %q, want %d-byte value accepted", got, agentTraceMaxLen)
+	}
+}
+
 func TestBaseSecurityHeaders_NoAgentTraceHeaderWhenEnvUnset(t *testing.T) {
 	t.Setenv(envvars.CliAgentTrace, "")
 	h := BaseSecurityHeaders()

internal/envvars/envvars.go

@@ -19,7 +19,6 @@ const (
 	// Content safety scanning mode
 	CliContentSafetyMode = "LARKSUITE_CLI_CONTENT_SAFETY_MODE"
 
-	CliAgentName  = "LARKSUITE_CLI_AGENT_NAME"
 	CliAgentTrace = "LARKSUITE_CLI_AGENT_TRACE"
 
 	CliProxyEnable  = "LARKSUITE_CLI_PROXY_ENABLE"

internal/envvars/read.go

@@ -1,36 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package envvars
-
-import (
-	"os"
-	"strings"
-	"unicode"
-)
-
-const (
-	agentNameMaxLen  = 128
-	agentTraceMaxLen = 1024
-)
-
-func AgentName() string {
-	return sanitizeSingleLine(os.Getenv(CliAgentName), agentNameMaxLen)
-}
-
-func AgentTrace() string {
-	return sanitizeSingleLine(os.Getenv(CliAgentTrace), agentTraceMaxLen)
-}
-
-func sanitizeSingleLine(raw string, maxLen int) string {
-	v := strings.TrimSpace(raw)
-	if v == "" || len(v) > maxLen {
-		return ""
-	}
-	for _, r := range v {
-		if unicode.IsControl(r) {
-			return ""
-		}
-	}
-	return v
-}

internal/envvars/read_test.go

@@ -1,131 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package envvars
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestAgentName_EmptyWhenEnvUnset(t *testing.T) {
-	t.Setenv(CliAgentName, "")
-	if got := AgentName(); got != "" {
-		t.Fatalf("AgentName() = %q, want empty when env unset", got)
-	}
-}
-
-func TestAgentName_ReturnsCleanValue(t *testing.T) {
-	t.Setenv(CliAgentName, "claude-code")
-	if got := AgentName(); got != "claude-code" {
-		t.Fatalf("AgentName() = %q, want %q", got, "claude-code")
-	}
-}
-
-func TestAgentName_TrimsWhitespace(t *testing.T) {
-	t.Setenv(CliAgentName, "  cursor  ")
-	if got := AgentName(); got != "cursor" {
-		t.Fatalf("AgentName() = %q, want %q (whitespace trimmed)", got, "cursor")
-	}
-}
-
-func TestAgentName_RejectsCRLFInjection(t *testing.T) {
-	t.Setenv(CliAgentName, "agent\r\nX-Evil: attack")
-	if got := AgentName(); got != "" {
-		t.Fatalf("AgentName() = %q, want empty for CR/LF value", got)
-	}
-}
-
-func TestAgentName_RejectsControlChar(t *testing.T) {
-	t.Setenv(CliAgentName, "agent\x01injected")
-	if got := AgentName(); got != "" {
-		t.Fatalf("AgentName() = %q, want empty for control char value", got)
-	}
-}
-
-func TestAgentName_RejectsOverlongValue(t *testing.T) {
-	longVal := strings.Repeat("a", agentNameMaxLen+1)
-	t.Setenv(CliAgentName, longVal)
-	if got := AgentName(); got != "" {
-		t.Fatalf("AgentName() returned non-empty for %d-byte value (max %d)", len(longVal), agentNameMaxLen)
-	}
-}
-
-func TestAgentTrace_EmptyWhenEnvUnset(t *testing.T) {
-	t.Setenv(CliAgentTrace, "")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty when env unset", got)
-	}
-}
-
-func TestAgentTrace_ReturnsCleanValue(t *testing.T) {
-	t.Setenv(CliAgentTrace, "trace-abc-123")
-	if got := AgentTrace(); got != "trace-abc-123" {
-		t.Fatalf("AgentTrace() = %q, want %q", got, "trace-abc-123")
-	}
-}
-
-func TestAgentTrace_TrimsWhitespace(t *testing.T) {
-	t.Setenv(CliAgentTrace, "  trace-trim  ")
-	if got := AgentTrace(); got != "trace-trim" {
-		t.Fatalf("AgentTrace() = %q, want %q (whitespace trimmed)", got, "trace-trim")
-	}
-}
-
-func TestAgentTrace_OnlyWhitespace_ReturnsEmpty(t *testing.T) {
-	t.Setenv(CliAgentTrace, "   ")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for whitespace-only value", got)
-	}
-}
-
-func TestAgentTrace_RejectsCRLF(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\r\nX-Evil: attack")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for CR/LF value", got)
-	}
-}
-
-func TestAgentTrace_RejectsLF(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\nX-Evil: attack")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for LF value", got)
-	}
-}
-
-func TestAgentTrace_RejectsTab(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\tinjected")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for tab value", got)
-	}
-}
-
-func TestAgentTrace_RejectsControlChar(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\x01injected")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for control char value", got)
-	}
-}
-
-func TestAgentTrace_RejectsDEL(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\x7finjected")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for DEL value", got)
-	}
-}
-
-func TestAgentTrace_RejectsOverlongValue(t *testing.T) {
-	longVal := strings.Repeat("a", agentTraceMaxLen+1)
-	t.Setenv(CliAgentTrace, longVal)
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() returned non-empty for %d-byte value (max %d)", len(longVal), agentTraceMaxLen)
-	}
-}
-
-func TestAgentTrace_AcceptsMaxLengthValue(t *testing.T) {
-	val := strings.Repeat("a", agentTraceMaxLen)
-	t.Setenv(CliAgentTrace, val)
-	if got := AgentTrace(); got != val {
-		t.Fatalf("AgentTrace() = %q, want %d-byte value accepted", got, agentTraceMaxLen)
-	}
-}

internal/errclass/codemeta_drive.go

@@ -10,22 +10,20 @@ import "github.com/larksuite/cli/errs"
 // ambiguous codes fall back to CategoryAPI via BuildAPIError.
 // BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
 var driveCodeMeta = map[int]CodeMeta{
-	1061001:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive "unknown error"
-	1061002:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // params error
-	1061004:   {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // forbidden
-	1061007:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // file has been deleted
-	1061043:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file size beyond limit
-	1061044:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // parent folder does not exist (upload)
-	1061101:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file quota exceeded
-	1062009:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // actual size inconsistent with declared size
-	1063001:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // secure label invalid parameter
-	1063002:   {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // secure label permission denied
-	1063013:   {Category: errs.CategoryValidation, Subtype: errs.SubtypeFailedPrecondition},    // secure label downgrade requires approval
-	1069302:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // comment endpoint "Invalid or missing parameters"
-	99992402:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // platform field validation failed
-	9499:      {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // invalid parameter type in JSON field
-	2200:      {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive tenant/internal errors
-	233523001: {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive/docs transient server error
+	1061001:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive "unknown error"
+	1061002:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // params error
+	1061004:  {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // forbidden
+	1061007:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // file has been deleted
+	1061043:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file size beyond limit
+	1061044:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // parent folder does not exist (upload)
+	1062009:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // actual size inconsistent with declared size
+	1063001:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // secure label invalid parameter
+	1063002:  {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // secure label permission denied
+	1063013:  {Category: errs.CategoryValidation, Subtype: errs.SubtypeFailedPrecondition},    // secure label downgrade requires approval
+	1069302:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // comment endpoint "Invalid or missing parameters"
+	99992402: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // platform field validation failed
+	9499:     {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // invalid parameter type in JSON field
+	2200:     {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive tenant/internal errors
 }
 
 func init() { mergeCodeMeta(driveCodeMeta, "drive") }

internal/errclass/codemeta_test.go

@@ -114,35 +114,8 @@ func TestLookupCodeMeta_DrivePushCodes(t *testing.T) {
 		{1061004, errs.CategoryAuthorization, errs.SubtypePermissionDenied, false},
 		{1061007, errs.CategoryAPI, errs.SubtypeNotFound, false},
 		{1061043, errs.CategoryAPI, errs.SubtypeQuotaExceeded, false},
-		{1061101, errs.CategoryAPI, errs.SubtypeQuotaExceeded, false},
 		{1062009, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
 		{2200, errs.CategoryAPI, errs.SubtypeServerError, true},
-		{233523001, errs.CategoryAPI, errs.SubtypeServerError, true},
-	}
-	for _, tc := range cases {
-		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {
-			got, ok := LookupCodeMeta(tc.code)
-			if !ok {
-				t.Fatalf("LookupCodeMeta(%d) ok=false, want true", tc.code)
-			}
-			if got.Category != tc.wantCat || got.Subtype != tc.wantSubtype || got.Retryable != tc.wantRetry {
-				t.Fatalf("LookupCodeMeta(%d) = %+v, want Category=%v Subtype=%v Retryable=%v",
-					tc.code, got, tc.wantCat, tc.wantSubtype, tc.wantRetry)
-			}
-		})
-	}
-}
-
-func TestLookupCodeMeta_WikiCodes(t *testing.T) {
-	cases := []struct {
-		code        int
-		wantCat     errs.Category
-		wantSubtype errs.Subtype
-		wantRetry   bool
-	}{
-		{131002, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
-		{131005, errs.CategoryAPI, errs.SubtypeNotFound, false},
-		{131006, errs.CategoryAuthorization, errs.SubtypePermissionDenied, false},
 	}
 	for _, tc := range cases {
 		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {

internal/errclass/codemeta_wiki.go

@@ -1,17 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import "github.com/larksuite/cli/errs"
-
-// wikiCodeMeta holds wiki-service Lark code -> CodeMeta mappings observed from
-// wiki shortcut failure telemetry. Keep these to wiki-wide meanings only; add
-// command-specific recovery guidance at the shortcut layer.
-var wikiCodeMeta = map[int]CodeMeta{
-	131002: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},          // param err: space_id is not int / invalid page_token
-	131005: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                   // wiki node / space not found
-	131006: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // wiki space/node read permission denied
-}
-
-func init() { mergeCodeMeta(wikiCodeMeta, "wiki") }

internal/registry/catalog.go

@@ -6,7 +6,8 @@ package registry
 import "github.com/larksuite/cli/internal/apicatalog"
 
 // EmbeddedCatalog returns a navigation catalog over the embedded (overlay-free)
-// metadata — deterministic across machines, for golden tests and schema lint.
+// metadata — deterministic across machines, for `lark-cli schema`, golden tests
+// and schema lint.
 func EmbeddedCatalog() apicatalog.Catalog {
 	return apicatalog.New(apicatalog.SourceEmbedded, EmbeddedServicesTyped())
 }
@@ -17,14 +18,3 @@ func EmbeddedCatalog() apicatalog.Catalog {
 func RuntimeCatalog() apicatalog.Catalog {
 	return apicatalog.New(apicatalog.SourceRuntime, ServicesTyped())
 }
-
-// SchemaCatalog returns the embedded catalog when metadata is compiled in,
-// otherwise the merged runtime catalog. Binaries built from the bare Go module
-// embed only the empty meta_data_default.json stub, so the embedded view has
-// nothing to resolve; the merged view is the only data such binaries have.
-func SchemaCatalog() apicatalog.Catalog {
-	if len(EmbeddedServicesTyped()) > 0 {
-		return EmbeddedCatalog()
-	}
-	return RuntimeCatalog()
-}

internal/registry/catalog_test.go

@@ -1,67 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package registry
-
-import (
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/larksuite/cli/internal/apicatalog"
-)
-
-// swapEmbeddedMeta replaces the compiled-in metadata bytes for one test and
-// restores them (with a full state reset) on cleanup.
-func swapEmbeddedMeta(t *testing.T, data []byte) {
-	t.Helper()
-	resetInit()
-	orig := embeddedMetaJSON
-	embeddedMetaJSON = data
-	t.Cleanup(func() {
-		waitBackgroundRefresh()
-		embeddedMetaJSON = orig
-		resetInit()
-	})
-}
-
-func TestSchemaCatalog_EmbeddedWhenCompiledIn(t *testing.T) {
-	swapEmbeddedMeta(t, testCacheJSON("embedded_svc"))
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
-
-	c := SchemaCatalog()
-
-	if c.Source() != apicatalog.SourceEmbedded {
-		t.Fatalf("Source = %q, want %q", c.Source(), apicatalog.SourceEmbedded)
-	}
-	if _, ok := c.Service("embedded_svc"); !ok {
-		t.Fatal("expected embedded_svc from embedded metadata")
-	}
-}
-
-// TestSchemaCatalog_FallsBackToRuntimeWhenNoEmbedded simulates a binary built
-// from the bare Go module (plugin builds): only the empty meta_data_default.json
-// stub is compiled in, so SchemaCatalog must serve the merged runtime view that
-// Init seeds via sync fetch.
-func TestSchemaCatalog_FallsBackToRuntimeWhenNoEmbedded(t *testing.T) {
-	swapEmbeddedMeta(t, embeddedMetaDataDefaultJSON)
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
-
-	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(200)
-		w.Write(testEnvelopeJSON("remote_svc"))
-	}))
-	defer ts.Close()
-	testMetaURL = ts.URL
-
-	c := SchemaCatalog()
-
-	if c.Source() != apicatalog.SourceRuntime {
-		t.Fatalf("Source = %q, want %q", c.Source(), apicatalog.SourceRuntime)
-	}
-	if _, ok := c.Service("remote_svc"); !ok {
-		t.Fatal("expected remote_svc from runtime fallback")
-	}
-}

internal/registry/loader.go

@@ -15,7 +15,6 @@ import (
 
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/meta"
-	"github.com/larksuite/cli/internal/update"
 )
 
 //go:embed scope_priorities.json scope_overrides.json
@@ -86,9 +85,7 @@ func InitWithBrand(brand core.LarkBrand) {
 			brandChanged := metaErr == nil && cm.Brand != "" && cm.Brand != string(brand)
 
 			if !brandChanged {
-				// After a CLI upgrade the embedded data can be fresher than an old
-				// cache; an equal/older cache must not shadow it.
-				if cached, err := loadCachedMerged(); err == nil && update.IsNewer(cached.Version, embeddedVersion) {
+				if cached, err := loadCachedMerged(); err == nil {
 					overlayMergedServices(cached)
 				}
 			}

internal/registry/loader_test.go

@@ -1,102 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package registry
-
-import (
-	"encoding/json"
-	"os"
-	"path/filepath"
-	"testing"
-	"time"
-
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/meta"
-)
-
-// seedCache writes a cache file + cache meta for one service whose Title is
-// marker, tagged with the given top-level data version and brand.
-func seedCache(t *testing.T, dir, name, marker, version, brand string) {
-	t.Helper()
-	cDir := filepath.Join(dir, "cache")
-	if err := os.MkdirAll(cDir, 0700); err != nil {
-		t.Fatal(err)
-	}
-	reg := MergedRegistry{
-		Version:  version,
-		Services: []meta.Service{{Name: name, Version: "cache", Title: marker}},
-	}
-	data, _ := json.Marshal(reg)
-	if err := os.WriteFile(filepath.Join(cDir, "remote_meta.json"), data, 0644); err != nil {
-		t.Fatal(err)
-	}
-	cm := CacheMeta{LastCheckAt: time.Now().Unix(), Version: version, Brand: brand}
-	mData, _ := json.Marshal(cm)
-	if err := os.WriteFile(filepath.Join(cDir, "remote_meta.meta.json"), mData, 0644); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// initWithCache runs a fresh feishu-brand init with remote on, a high TTL and a
-// recent LastCheckAt (so no refresh fires), embedded meta at embeddedVer and a
-// pre-seeded cache at cacheVer — the overlay version gate is the only variable.
-func initWithCache(t *testing.T, embeddedVer, cacheVer string) {
-	t.Helper()
-	embedded, _ := json.Marshal(MergedRegistry{
-		Version:  embeddedVer,
-		Services: []meta.Service{{Name: "svc", Version: "embedded", Title: "EMBEDDED"}},
-	})
-	swapEmbeddedMeta(t, embedded)
-	tmp := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
-	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
-	t.Setenv("LARKSUITE_CLI_META_TTL", "3600")
-	seedCache(t, tmp, "svc", "CACHE", cacheVer, "feishu")
-	InitWithBrand(core.BrandFeishu)
-}
-
-func titleOf(t *testing.T, name string) string {
-	t.Helper()
-	svc, ok := ServiceTyped(name)
-	if !ok {
-		t.Fatalf("service %q not loaded", name)
-	}
-	return svc.Title
-}
-
-func TestOverlayGate_EqualVersion_UsesEmbedded(t *testing.T) {
-	initWithCache(t, "1.0.0", "1.0.0")
-	if got := titleOf(t, "svc"); got != "EMBEDDED" {
-		t.Errorf("equal version: got %q, want EMBEDDED (cache must not overlay)", got)
-	}
-}
-
-func TestOverlayGate_OlderCache_UsesEmbedded(t *testing.T) {
-	initWithCache(t, "2.0.0", "1.0.0")
-	if got := titleOf(t, "svc"); got != "EMBEDDED" {
-		t.Errorf("older cache: got %q, want EMBEDDED", got)
-	}
-}
-
-func TestOverlayGate_NewerCache_OverlaysCache(t *testing.T) {
-	initWithCache(t, "1.0.0", "2.0.0")
-	if got := titleOf(t, "svc"); got != "CACHE" {
-		t.Errorf("newer cache: got %q, want CACHE", got)
-	}
-}
-
-func TestOverlayGate_UnparseableCacheVersion_UsesEmbedded(t *testing.T) {
-	initWithCache(t, "1.0.0", "not-a-semver")
-	if got := titleOf(t, "svc"); got != "EMBEDDED" {
-		t.Errorf("unparseable cache version: got %q, want EMBEDDED", got)
-	}
-}
-
-func TestOverlayGate_StubEmbedded_OverlaysRealCache(t *testing.T) {
-	// The bare-module stub baseline is "0.0.0"; a real cache version must win so
-	// plugin builds without compiled meta_data.json still get remote data.
-	initWithCache(t, "0.0.0", "1.0.0")
-	if got := titleOf(t, "svc"); got != "CACHE" {
-		t.Errorf("stub-embedded baseline: got %q, want CACHE", got)
-	}
-}

internal/registry/remote_test.go

@@ -72,11 +72,9 @@ func hasEmbeddedServices() bool {
 }
 
 // testRegistry returns a minimal MergedRegistry with one service.
-// The version is a real semver newer than the embedded stub baseline ("0.0.0")
-// so cache overlay passes the version gate in InitWithBrand.
 func testRegistry(name string) MergedRegistry {
 	return MergedRegistry{
-		Version: "1.0.0",
+		Version: "test-1.0",
 		Services: []meta.Service{
 			{
 				Name:        name,
@@ -162,7 +160,7 @@ func TestRemoteOff_SkipsRemoteLogic(t *testing.T) {
 }
 
 func TestCacheHit_WithinTTL(t *testing.T) {
-	swapEmbeddedMeta(t, nil) // overlay must depend only on the cache version, not the ambient embedded meta
+	resetInit()
 	tmp := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
@@ -199,7 +197,7 @@ func TestCacheHit_WithinTTL(t *testing.T) {
 }
 
 func TestNetworkError_SilentDegradation(t *testing.T) {
-	swapEmbeddedMeta(t, nil) // overlay must depend only on the cache version, not the ambient embedded meta
+	resetInit()
 	tmp := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
@@ -373,8 +371,8 @@ func TestFetchRemoteMerged_200(t *testing.T) {
 	if data == nil {
 		t.Fatal("expected non-nil data")
 	}
-	if reg.Version != "1.0.0" {
-		t.Errorf("expected version 1.0.0, got %s", reg.Version)
+	if reg.Version != "test-1.0" {
+		t.Errorf("expected version test-1.0, got %s", reg.Version)
 	}
 }
 

internal/selfupdate/updater.go

@@ -32,7 +32,6 @@ type InstallMethod int
 
 const (
 	InstallNpm InstallMethod = iota
-	InstallPnpm
 	InstallManual
 )
 
@@ -54,32 +53,22 @@ var (
 
 // DetectResult holds installation detection results.
 type DetectResult struct {
-	Method        InstallMethod
-	ResolvedPath  string
-	NpmAvailable  bool
-	PnpmAvailable bool
+	Method       InstallMethod
+	ResolvedPath string
+	NpmAvailable bool
 }
 
 // CanAutoUpdate returns true if the CLI can update itself automatically.
 func (d DetectResult) CanAutoUpdate() bool {
-	switch d.Method {
-	case InstallNpm:
-		return d.NpmAvailable
-	case InstallPnpm:
-		return d.PnpmAvailable
-	}
-	return false
+	return d.Method == InstallNpm && d.NpmAvailable
 }
 
 // ManualReason returns a human-readable explanation of why auto-update is unavailable.
 func (d DetectResult) ManualReason() string {
-	switch {
-	case d.Method == InstallNpm && !d.NpmAvailable:
+	if d.Method == InstallNpm && !d.NpmAvailable {
 		return "installed via npm, but npm is not available in PATH"
-	case d.Method == InstallPnpm && !d.PnpmAvailable:
-		return "installed via pnpm, but pnpm is not available in PATH"
 	}
-	return "not installed via npm or pnpm"
+	return "not installed via npm"
 }
 
 // NpmResult holds the result of an npm install or skills update execution.
@@ -103,7 +92,6 @@ func (r *NpmResult) CombinedOutput() string {
 type Updater struct {
 	DetectOverride           func() DetectResult
 	NpmInstallOverride       func(version string) *NpmResult
-	PnpmInstallOverride      func(version string) *NpmResult
 	SkillsIndexFetchOverride func() *NpmResult
 	SkillsCommandOverride    func(args ...string) *NpmResult
 	VerifyOverride           func(expectedVersion string) error
@@ -113,38 +101,17 @@ type Updater struct {
 	// running binary is successfully renamed to .old. Used by
 	// CanRestorePreviousVersion to report whether rollback is possible.
 	backupCreated bool
-
-	// detectCache memoizes the first real DetectInstallMethod result. How this
-	// binary was installed cannot change during a single process, so caching is
-	// the correct semantics — and it is required for correctness: the update
-	// flow mutates the install (pnpm add -g / npm install -g) before syncing
-	// skills, so a re-detection at skills time could resolve a now-stale
-	// os.Executable path and misclassify. Seeded pre-update by the first call
-	// (updateRun), it keeps the post-update skills launcher consistent with the
-	// launcher reported to the user. Not goroutine-safe; the update flow is
-	// sequential.
-	detectCache *DetectResult
 }
 
 // New creates an Updater with default (real) behavior.
 func New() *Updater { return &Updater{} }
 
-// DetectInstallMethod determines how the CLI was installed and whether the
-// owning package manager is available for auto-update.
+// DetectInstallMethod determines how the CLI was installed and whether
+// npm is available for auto-update.
 func (u *Updater) DetectInstallMethod() DetectResult {
 	if u.DetectOverride != nil {
 		return u.DetectOverride()
 	}
-	if u.detectCache != nil {
-		return *u.detectCache
-	}
-	result := u.detectInstallMethod()
-	u.detectCache = &result
-	return result
-}
-
-// detectInstallMethod performs the real (uncached) detection.
-func (u *Updater) detectInstallMethod() DetectResult {
 	exe, err := vfs.Executable()
 	if err != nil {
 		return DetectResult{Method: InstallManual}
@@ -153,54 +120,24 @@ func (u *Updater) detectInstallMethod() DetectResult {
 	if err != nil {
 		return DetectResult{Method: InstallManual, ResolvedPath: exe}
 	}
-	_, npmErr := exec.LookPath("npm")
-	_, pnpmErr := exec.LookPath("pnpm")
-	return detectFromResolved(resolved, npmErr == nil, pnpmErr == nil)
-}
 
-// detectFromResolved classifies the resolved binary path into an install
-// method and records package-manager availability. Split out from
-// DetectInstallMethod so the classification is unit-testable without touching
-// the filesystem or PATH.
-func detectFromResolved(resolved string, npmOnPath, pnpmOnPath bool) DetectResult {
 	method := InstallManual
 	if strings.Contains(resolved, "node_modules") {
-		if containsPnpmMarker(resolved) {
-			method = InstallPnpm
-		} else {
-			method = InstallNpm
-		}
+		method = InstallNpm
 	}
-	d := DetectResult{Method: method, ResolvedPath: resolved}
-	switch method {
-	case InstallNpm:
-		d.NpmAvailable = npmOnPath
-	case InstallPnpm:
-		d.PnpmAvailable = pnpmOnPath
-	}
-	return d
-}
 
-// containsPnpmMarker reports whether the resolved binary path belongs to a
-// pnpm-managed install. pnpm exposes two layouts: the classic virtual store
-// (a ".pnpm" directory segment) and the global content-addressable store,
-// whose resolved path runs through pnpm's home directory (e.g.
-// "~/Library/pnpm/store/v11/links/...") — a "pnpm" segment immediately
-// followed by "store". Matching only these two shapes (rather than any bare
-// "pnpm" segment) avoids misclassifying an npm install that merely lives under
-// a directory named "pnpm". Windows separators are normalized to "/" so the
-// classification is OS-independent and unit-testable anywhere.
-func containsPnpmMarker(p string) bool {
-	parts := strings.Split(strings.ReplaceAll(p, `\`, "/"), "/")
-	for i, part := range parts {
-		if part == ".pnpm" {
-			return true
-		}
-		if part == "pnpm" && i+1 < len(parts) && parts[i+1] == "store" {
-			return true
+	npmAvailable := false
+	if method == InstallNpm {
+		if _, err := exec.LookPath("npm"); err == nil {
+			npmAvailable = true
 		}
 	}
-	return false
+
+	return DetectResult{
+		Method:       method,
+		ResolvedPath: resolved,
+		NpmAvailable: npmAvailable,
+	}
 }
 
 // RunNpmInstall executes npm install -g @larksuite/cli@<version>.
@@ -226,29 +163,6 @@ func (u *Updater) RunNpmInstall(version string) *NpmResult {
 	return r
 }
 
-// RunPnpmInstall executes pnpm add -g @larksuite/cli@<version>.
-func (u *Updater) RunPnpmInstall(version string) *NpmResult {
-	if u.PnpmInstallOverride != nil {
-		return u.PnpmInstallOverride(version)
-	}
-	r := &NpmResult{}
-	pnpmPath, err := exec.LookPath("pnpm")
-	if err != nil {
-		r.Err = fmt.Errorf("pnpm not found in PATH: %w", err)
-		return r
-	}
-	ctx, cancel := context.WithTimeout(context.Background(), npmInstallTimeout)
-	defer cancel()
-	cmd := exec.CommandContext(ctx, pnpmPath, "add", "-g", NpmPackage+"@"+version)
-	cmd.Stdout = &r.Stdout
-	cmd.Stderr = &r.Stderr
-	r.Err = cmd.Run()
-	if ctx.Err() == context.DeadlineExceeded {
-		r.Err = fmt.Errorf("pnpm install timed out after %s", npmInstallTimeout)
-	}
-	return r
-}
-
 func (u *Updater) ListOfficialSkillsIndex() *NpmResult {
 	if u.SkillsIndexFetchOverride != nil {
 		return u.SkillsIndexFetchOverride()
@@ -347,40 +261,19 @@ func (u *Updater) runSkillsInstall(source string, nameList []string) *NpmResult
 	return u.runSkillsCommand(args...)
 }
 
-// skillsInvocation decides how to launch the `skills` CLI. When the lark-cli
-// itself was installed via pnpm and pnpm is available, it uses `pnpm dlx` so
-// pnpm-only environments (pnpm's standalone installer bundles Node without
-// putting npm/npx on PATH) can still sync skills after a self-update.
-// Otherwise it uses `npx`. The npx auto-confirm flag "-y", when present as the
-// leading arg, maps to `pnpm dlx`'s default non-interactive behavior and is
-// dropped for the pnpm launcher. Kept pure (no exec/PATH access) so the
-// launcher selection is unit-testable on any platform.
-func skillsInvocation(method InstallMethod, pnpmAvailable bool, args []string) (launcher string, rest []string) {
-	if method == InstallPnpm && pnpmAvailable {
-		r := args
-		if len(r) > 0 && r[0] == "-y" {
-			r = r[1:]
-		}
-		return "pnpm", append([]string{"dlx"}, r...)
-	}
-	return "npx", args
-}
-
 func (u *Updater) runSkillsCommand(args ...string) *NpmResult {
 	if u.SkillsCommandOverride != nil {
 		return u.SkillsCommandOverride(args...)
 	}
 	r := &NpmResult{}
-	det := u.DetectInstallMethod()
-	launcher, cmdArgs := skillsInvocation(det.Method, det.PnpmAvailable, args)
-	binPath, err := exec.LookPath(launcher)
+	npxPath, err := exec.LookPath("npx")
 	if err != nil {
-		r.Err = fmt.Errorf("%s not found in PATH: %w", launcher, err)
+		r.Err = fmt.Errorf("npx not found in PATH: %w", err)
 		return r
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), skillsUpdateTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, binPath, cmdArgs...)
+	cmd := exec.CommandContext(ctx, npxPath, args...)
 	cmd.Stdout = &r.Stdout
 	cmd.Stderr = &r.Stderr
 	r.Err = cmd.Run()

internal/selfupdate/updater_test.go

@@ -371,147 +371,3 @@ func TestListOfficialSkillsFallsBack(t *testing.T) {
 		t.Fatalf("fallback call = %q, want larksuite/cli --list", called[1])
 	}
 }
-
-func TestContainsPnpmMarker(t *testing.T) {
-	cases := []struct {
-		path string
-		want bool
-	}{
-		// Classic virtual-store layout (.pnpm segment).
-		{"/Users/x/Library/pnpm/global/5/node_modules/.pnpm/@larksuite+cli@1.0.44/node_modules/@larksuite/cli/bin/lark-cli", true},
-		{`C:\Users\x\AppData\Local\pnpm\global\5\node_modules\.pnpm\@larksuite+cli@1.0.44\node_modules\@larksuite\cli\bin\lark-cli.exe`, true},
-		// Global content-addressable store layout (pnpm 11): resolved path runs
-		// through the pnpm home store, a "pnpm" segment with no ".pnpm".
-		{"/Users/x/Library/pnpm/store/v11/links/@larksuite/cli/1.0.59/abc123/node_modules/@larksuite/cli/bin/lark-cli", true},
-		{"/home/x/.local/share/pnpm/store/v10/@larksuite/cli/node_modules/@larksuite/cli/bin/lark-cli", true},
-		{`C:\Users\x\AppData\Local\pnpm\store\v11\links\@larksuite\cli\node_modules\@larksuite\cli\bin\lark-cli.exe`, true},
-		// npm and non-package installs — no pnpm/.pnpm segment.
-		{"/usr/local/lib/node_modules/@larksuite/cli/bin/lark-cli", false},
-		{"/usr/local/bin/lark-cli", false},
-		// Substrings that must NOT match: segment must be exactly .pnpm, or
-		// "pnpm" immediately followed by "store".
-		{"/opt/homebrew/.pnpmfoo/node_modules/@larksuite/cli/bin/lark-cli", false},
-		{"/opt/pnpmfoo/node_modules/@larksuite/cli/bin/lark-cli", false},
-		// A bare "pnpm" directory NOT followed by "store" (e.g. an npm install
-		// living under a dir named pnpm) must not be misclassified as pnpm.
-		{"/opt/pnpm/lib/node_modules/@larksuite/cli/bin/lark-cli", false},
-	}
-	for _, c := range cases {
-		if got := containsPnpmMarker(c.path); got != c.want {
-			t.Errorf("containsPnpmMarker(%q) = %v, want %v", c.path, got, c.want)
-		}
-	}
-}
-
-func TestDetectInstallMethod_Pnpm(t *testing.T) {
-	u := &Updater{DetectOverride: nil}
-	u.DetectOverride = func() DetectResult {
-		// Exercise the real classification by feeding a resolved path via a small shim.
-		return detectFromResolved("/x/node_modules/.pnpm/@larksuite+cli@1.0.44/node_modules/@larksuite/cli/bin/lark-cli", true, true)
-	}
-	got := u.DetectInstallMethod()
-	if got.Method != InstallPnpm {
-		t.Errorf("Method = %v, want InstallPnpm", got.Method)
-	}
-	if !got.PnpmAvailable {
-		t.Errorf("PnpmAvailable = false, want true")
-	}
-}
-
-func TestDetectInstallMethod_NpmVsManual(t *testing.T) {
-	if m := detectFromResolved("/usr/local/lib/node_modules/@larksuite/cli/bin/lark-cli", true, false).Method; m != InstallNpm {
-		t.Errorf("npm path Method = %v, want InstallNpm", m)
-	}
-	if m := detectFromResolved("/usr/local/bin/lark-cli", false, false).Method; m != InstallManual {
-		t.Errorf("manual path Method = %v, want InstallManual", m)
-	}
-}
-
-func TestCanAutoUpdate_Pnpm(t *testing.T) {
-	if !(DetectResult{Method: InstallPnpm, PnpmAvailable: true}).CanAutoUpdate() {
-		t.Error("pnpm available should CanAutoUpdate")
-	}
-	if (DetectResult{Method: InstallPnpm, PnpmAvailable: false}).CanAutoUpdate() {
-		t.Error("pnpm unavailable should not CanAutoUpdate")
-	}
-}
-
-func TestManualReason_Pnpm(t *testing.T) {
-	if got := (DetectResult{Method: InstallPnpm, NpmAvailable: false, PnpmAvailable: false}).ManualReason(); got != "installed via pnpm, but pnpm is not available in PATH" {
-		t.Errorf("pnpm reason = %q", got)
-	}
-	if got := (DetectResult{Method: InstallManual}).ManualReason(); got != "not installed via npm or pnpm" {
-		t.Errorf("manual reason = %q", got)
-	}
-}
-
-func TestRunPnpmInstall_Override(t *testing.T) {
-	u := &Updater{PnpmInstallOverride: func(version string) *NpmResult {
-		r := &NpmResult{}
-		r.Stdout.WriteString("added @larksuite/cli@" + version)
-		return r
-	}}
-	got := u.RunPnpmInstall("2.0.0")
-	if got.Err != nil {
-		t.Fatalf("unexpected err: %v", got.Err)
-	}
-	if !strings.Contains(got.CombinedOutput(), "2.0.0") {
-		t.Errorf("output = %q, want version echoed", got.CombinedOutput())
-	}
-}
-
-func TestRunPnpmInstall_Error(t *testing.T) {
-	wantErr := errors.New("boom")
-	u := &Updater{PnpmInstallOverride: func(string) *NpmResult { return &NpmResult{Err: wantErr} }}
-	if got := u.RunPnpmInstall("2.0.0"); !errors.Is(got.Err, wantErr) {
-		t.Errorf("err = %v, want %v", got.Err, wantErr)
-	}
-}
-
-func TestSkillsInvocation(t *testing.T) {
-	addArgs := []string{"-y", "skills", "add", "https://open.feishu.cn", "-g", "-y"}
-	cases := []struct {
-		name          string
-		method        InstallMethod
-		pnpmAvailable bool
-		args          []string
-		wantLauncher  string
-		wantRest      []string
-	}{
-		{"pnpm install + pnpm available → pnpm dlx, drop leading -y", InstallPnpm, true, addArgs,
-			"pnpm", []string{"dlx", "skills", "add", "https://open.feishu.cn", "-g", "-y"}},
-		{"pnpm install but pnpm unavailable → npx unchanged", InstallPnpm, false, addArgs,
-			"npx", addArgs},
-		{"npm install → npx unchanged", InstallNpm, false, addArgs,
-			"npx", addArgs},
-		{"manual install → npx unchanged", InstallManual, false, []string{"-y", "skills", "ls", "-g"},
-			"npx", []string{"-y", "skills", "ls", "-g"}},
-		{"pnpm without a leading -y → prepend dlx only", InstallPnpm, true, []string{"skills", "ls", "-g"},
-			"pnpm", []string{"dlx", "skills", "ls", "-g"}},
-	}
-	for _, c := range cases {
-		t.Run(c.name, func(t *testing.T) {
-			gotLauncher, gotRest := skillsInvocation(c.method, c.pnpmAvailable, c.args)
-			if gotLauncher != c.wantLauncher {
-				t.Errorf("launcher = %q, want %q", gotLauncher, c.wantLauncher)
-			}
-			if strings.Join(gotRest, " ") != strings.Join(c.wantRest, " ") {
-				t.Errorf("rest = %v, want %v", gotRest, c.wantRest)
-			}
-		})
-	}
-}
-
-// TestDetectInstallMethod_Caches locks the fix for the post-update re-detection
-// hazard: DetectInstallMethod must return the first (pre-update) detection on
-// subsequent calls, so the skills launcher chosen after the binary is replaced
-// stays consistent with what was detected — and reported — before the update.
-func TestDetectInstallMethod_Caches(t *testing.T) {
-	u := New()
-	cached := DetectResult{Method: InstallPnpm, PnpmAvailable: true, ResolvedPath: "/x/pnpm/store/v11/links/@larksuite/cli/1.0.0/node_modules/@larksuite/cli/bin/lark-cli"}
-	u.detectCache = &cached
-	got := u.DetectInstallMethod()
-	if got.Method != InstallPnpm || !got.PnpmAvailable {
-		t.Errorf("expected cached pnpm result to be returned, got %+v", got)
-	}
-}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.66",
+  "version": "1.0.65",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"

shortcuts/calendar/calendar_create.go

@@ -306,9 +306,6 @@ 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

@@ -1,279 +0,0 @@
-// 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_Returns10(t *testing.T) {
+func TestShortcuts_Returns9(t *testing.T) {
 	shortcuts := Shortcuts()
-	if len(shortcuts) != 10 {
-		t.Fatalf("expected 10 shortcuts, got %d", len(shortcuts))
+	if len(shortcuts) != 9 {
+		t.Fatalf("expected 9 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", "+get"} {
+	for _, want := range []string{"+agenda", "+create", "+update", "+freebusy", "+room-find", "+rsvp", "+suggestion"} {
 		if !names[want] {
 			t.Errorf("missing shortcut %s", want)
 		}
@@ -3178,193 +3178,3 @@ 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,6 +17,5 @@ func Shortcuts() []common.Shortcut {
 		CalendarSuggestion,
 		CalendarMeeting,
 		CalendarSearchEvent,
-		CalendarGet,
 	}
 }

shortcuts/drive/drive_pull.go

@@ -184,7 +184,6 @@ var DrivePull = common.Shortcut{
 
 		var downloaded, skipped, failed, deletedLocal int
 		downloadFailed := 0
-		aborted := false
 		items := make([]drivePullItem, 0)
 
 		// Deterministic iteration order for output stability.
@@ -195,7 +194,7 @@ var DrivePull = common.Shortcut{
 		sort.Strings(downloadablePaths)
 
 		for _, rel := range downloadablePaths {
-			if aborted {
+			if drivePullHasTerminalFailure(items) {
 				break
 			}
 			targetFile := remoteFiles[rel]
@@ -233,7 +232,6 @@ var DrivePull = common.Shortcut{
 				failed++
 				downloadFailed++
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +pull after terminal %s failure: %v\n", item.Phase, err)
 					break
 				}
@@ -300,7 +298,7 @@ var DrivePull = common.Shortcut{
 				"skipped":       skipped,
 				"failed":        failed,
 				"deleted_local": deletedLocal,
-				"aborted":       aborted,
+				"aborted":       drivePullHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -349,6 +347,15 @@ func drivePullFailedItem(relPath, fileToken, sourceID, action, phase string, err
 	return item, decision.Terminal
 }
 
+func drivePullHasTerminalFailure(items []drivePullItem) bool {
+	for _, item := range items {
+		if driveTerminalBatchErrorClass(item.ErrorClass) {
+			return true
+		}
+	}
+	return false
+}
+
 // drivePullDownload streams one Drive file into the local mirror target and
 // then best-effort aligns the local mtime to Drive's modified_time.
 func drivePullDownload(ctx context.Context, runtime *common.RuntimeContext, fileToken, target, remoteModifiedTime string) error {

shortcuts/drive/drive_push.go

@@ -35,7 +35,6 @@ type drivePushItem struct {
 	Version    string `json:"version,omitempty"`
 	SizeBytes  int64  `json:"size_bytes,omitempty"`
 	Error      string `json:"error,omitempty"`
-	Hint       string `json:"hint,omitempty"`
 	Phase      string `json:"phase,omitempty"`
 	ErrorClass string `json:"error_class,omitempty"`
 	Code       int    `json:"code,omitempty"`
@@ -49,7 +48,6 @@ type driveBatchFailureDecision struct {
 	Subtype   string
 	Retryable bool
 	Terminal  bool
-	Hint      string
 }
 
 // DrivePush is a one-way, file-level mirror from a local directory onto a
@@ -242,7 +240,6 @@ var DrivePush = common.Shortcut{
 		// locally and now on Drive too), which is the worst-of-both-worlds
 		// outcome the review flagged.
 		uploadFailed := false
-		aborted := false
 
 		// folderCache holds rel_path → folder_token. Seeded from the remote
 		// listing (so we don't recreate folders that already exist) and
@@ -269,7 +266,6 @@ var DrivePush = common.Shortcut{
 				failed++
 				uploadFailed = true
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, ensureErr)
 					break
 				}
@@ -288,7 +284,7 @@ var DrivePush = common.Shortcut{
 
 		for _, rel := range localPaths {
 			localFile := localFiles[rel]
-			if uploadFailed && aborted {
+			if uploadFailed && drivePushHasTerminalFailure(items) {
 				break
 			}
 
@@ -305,7 +301,6 @@ var DrivePush = common.Shortcut{
 					failed++
 					uploadFailed = true
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, parentErr)
 						break
 					}
@@ -337,7 +332,6 @@ var DrivePush = common.Shortcut{
 					failed++
 					uploadFailed = true
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, upErr)
 						break
 					}
@@ -356,7 +350,6 @@ var DrivePush = common.Shortcut{
 				failed++
 				uploadFailed = true
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, ensureErr)
 					break
 				}
@@ -369,7 +362,6 @@ var DrivePush = common.Shortcut{
 				failed++
 				uploadFailed = true
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, upErr)
 					break
 				}
@@ -415,15 +407,10 @@ var DrivePush = common.Shortcut{
 						continue
 					}
 					if err := drivePushDeleteFile(ctx, runtime, entry.FileToken); err != nil {
-						if drivePushIsAlreadyDeleted(err) {
-							items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "already_deleted"})
-							continue
-						}
 						item, terminal := drivePushFailedItem(rel, entry.FileToken, "delete_failed", "delete", 0, err)
 						items = append(items, item)
 						failed++
 						if terminal {
-							aborted = true
 							fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, err)
 							abortDelete = true
 							break
@@ -442,7 +429,7 @@ var DrivePush = common.Shortcut{
 				"skipped":        skipped,
 				"failed":         failed,
 				"deleted_remote": deletedRemote,
-				"aborted":        aborted,
+				"aborted":        drivePushHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -580,7 +567,6 @@ func drivePushFailedItem(relPath, fileToken, action, phase string, sizeBytes int
 		Action:     action,
 		SizeBytes:  sizeBytes,
 		Error:      err.Error(),
-		Hint:       decision.Hint,
 		Phase:      phase,
 		ErrorClass: decision.Class,
 		Code:       decision.Code,
@@ -627,10 +613,6 @@ func driveClassifyBatchFailure(err error) driveBatchFailureDecision {
 		decision.Class = "file_size_limit"
 	case problem.Code == 1062009:
 		decision.Class = "upload_size_mismatch"
-	case problem.Code == 1061044:
-		decision.Class = "parent_node_missing"
-		decision.Terminal = true
-		decision.Hint = "The destination parent folder no longer exists or is not visible. Verify --folder-token, folder permissions, and whether a parent directory was deleted during push before retrying."
 	case problem.Subtype == errs.SubtypeNotFound || problem.Code == 1061007:
 		decision.Class = "remote_not_found"
 	case problem.Subtype == errs.SubtypeServerError || problem.Code == 1061001 || problem.Code == 2200:
@@ -644,9 +626,22 @@ func driveClassifyBatchFailure(err error) driveBatchFailureDecision {
 	return decision
 }
 
-func drivePushIsAlreadyDeleted(err error) bool {
-	problem, ok := errs.ProblemOf(err)
-	return ok && problem.Code == 1061007
+func drivePushHasTerminalFailure(items []drivePushItem) bool {
+	for _, item := range items {
+		if driveTerminalBatchErrorClass(item.ErrorClass) {
+			return true
+		}
+	}
+	return false
+}
+
+func driveTerminalBatchErrorClass(errorClass string) bool {
+	switch errorClass {
+	case "app_scope_missing", "user_scope_missing", "permission_denied", "invalid_api_parameters", "rate_limited", "server_error":
+		return true
+	default:
+		return false
+	}
 }
 
 func drivePushRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (map[string]driveRemoteEntry, map[string]driveRemoteEntry, map[string][]driveRemoteEntry, error) {

shortcuts/drive/drive_push_test.go

@@ -732,65 +732,6 @@ func TestDrivePushDeleteRemoteAbortsAfterTerminalFailure(t *testing.T) {
 	}
 }
 
-func TestDrivePushDeleteRemoteTreatsAlreadyDeletedAsNoop(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_orphan", "name": "orphan.txt", "type": "file"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "DELETE",
-		URL:    "/open-apis/drive/v1/files/tok_orphan",
-		Body: map[string]interface{}{
-			"code": 1061007,
-			"msg":  "file has been delete.",
-		},
-	})
-
-	err := mountAndRunDrive(t, DrivePush, []string{
-		"+push",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--delete-remote",
-		"--yes",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("already-deleted remote should be an idempotent success, got: %v\nstdout: %s", err, stdout.String())
-	}
-
-	summary, items := splitDrivePushStdout(t, stdout.Bytes())
-	if got := summary["failed"]; got != float64(0) {
-		t.Fatalf("summary.failed = %v, want 0", got)
-	}
-	if got := summary["deleted_remote"]; got != float64(0) {
-		t.Fatalf("summary.deleted_remote = %v, want 0 because CLI did not delete it in this run", got)
-	}
-	if len(items) != 1 {
-		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
-	}
-	item := items[0]
-	if item["action"] != "already_deleted" || item["file_token"] != "tok_orphan" {
-		t.Fatalf("unexpected already-deleted item: %#v", item)
-	}
-}
-
 func TestDrivePushNewestOverwritesChosenDuplicateAndDeletesSibling(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 
@@ -1196,78 +1137,6 @@ func TestDrivePushAbortsAfterUploadParamsError(t *testing.T) {
 	}
 }
 
-func TestDrivePushAbortsAfterUploadParentNodeMissing(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	if err := os.WriteFile(filepath.Join("local", "a.txt"), []byte("A"), 0o644); err != nil {
-		t.Fatalf("WriteFile a: %v", err)
-	}
-	if err := os.WriteFile(filepath.Join("local", "b.txt"), []byte("B"), 0o644); err != nil {
-		t.Fatalf("WriteFile b: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/files/upload_all",
-		Body: map[string]interface{}{
-			"code": 1061044,
-			"msg":  "parent node not exist.",
-		},
-	})
-
-	err := mountAndRunDrive(t, DrivePush, []string{
-		"+push",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--as", "bot",
-	}, f, stdout)
-	if err == nil {
-		t.Fatalf("expected partial failure, got nil\nstdout: %s", stdout.String())
-	}
-	var pfErr *output.PartialFailureError
-	if !errors.As(err, &pfErr) {
-		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
-	}
-	summary, items := splitDrivePushStdout(t, stdout.Bytes())
-	if got := summary["failed"]; got != float64(1) {
-		t.Fatalf("summary.failed = %v, want 1", got)
-	}
-	if got := summary["aborted"]; got != true {
-		t.Fatalf("summary.aborted = %v, want true", got)
-	}
-	if len(items) != 1 {
-		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
-	}
-	item := items[0]
-	if item["rel_path"] != "a.txt" || item["phase"] != "upload" || item["error_class"] != "parent_node_missing" {
-		t.Fatalf("unexpected failed item: %#v", item)
-	}
-	if item["code"] != float64(1061044) || item["subtype"] != "not_found" || item["retryable"] != false {
-		t.Fatalf("unexpected failure metadata: %#v", item)
-	}
-	if got, _ := item["hint"].(string); !strings.Contains(got, "--folder-token") || !strings.Contains(got, "parent") {
-		t.Fatalf("hint should point at the destination parent folder, got item=%#v", item)
-	}
-	for _, item := range items {
-		if item["rel_path"] == "b.txt" {
-			t.Fatalf("parent-node missing must abort before b.txt, got items=%#v", items)
-		}
-	}
-}
-
 func TestDrivePushAbortsAfterCreateFolderMissingScope(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 

shortcuts/drive/drive_sync.go

@@ -268,7 +268,6 @@ var DriveSync = common.Shortcut{
 
 		// --- Phase 2: Execute sync operations ---
 		var pulled, pushed, skipped, failed int
-		aborted := false
 		items := make([]driveSyncItem, 0)
 
 		// Build push infrastructure: local walk for push + remote views + folder cache.
@@ -287,21 +286,16 @@ var DriveSync = common.Shortcut{
 		// Mirror local directory structure first (same as +push), so
 		// empty local directories are not silently dropped.
 		for _, relDir := range localDirs {
-			if aborted {
+			if driveSyncHasTerminalFailure(items) {
 				break
 			}
 			if _, alreadyRemote := folderCache[relDir]; alreadyRemote {
 				continue
 			}
 			if _, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, relDir, folderCache); ensureErr != nil {
-				item, terminal := driveSyncFailedItem(relDir, "", "failed", "push", "create_folder", ensureErr)
+				item, _ := driveSyncFailedItem(relDir, "", "failed", "push", "create_folder", ensureErr)
 				items = append(items, item)
 				failed++
-				if terminal {
-					aborted = true
-					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, ensureErr)
-					break
-				}
 				continue
 			}
 			items = append(items, driveSyncItem{RelPath: relDir, FileToken: folderCache[relDir], Action: "folder_created", Direction: "push"})
@@ -310,7 +304,7 @@ var DriveSync = common.Shortcut{
 
 		// 2a. Pull new_remote files.
 		for _, entry := range newRemote {
-			if aborted {
+			if driveSyncHasTerminalFailure(items) {
 				break
 			}
 			targetFile, ok := pullRemoteFiles[entry.RelPath]
@@ -324,7 +318,6 @@ var DriveSync = common.Shortcut{
 				items = append(items, item)
 				failed++
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, err)
 					break
 				}
@@ -336,7 +329,7 @@ var DriveSync = common.Shortcut{
 
 		// 2b. Push new_local files.
 		for _, entry := range newLocal {
-			if aborted {
+			if driveSyncHasTerminalFailure(items) {
 				break
 			}
 			localFile, ok := pushLocalFiles[entry.RelPath]
@@ -348,14 +341,9 @@ var DriveSync = common.Shortcut{
 			parentRel := drivePushParentRel(entry.RelPath)
 			parentToken, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, parentRel, folderCache)
 			if ensureErr != nil {
-				item, terminal := driveSyncFailedItem(entry.RelPath, "", "failed", "push", "create_folder", ensureErr)
+				item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "push", "create_folder", ensureErr)
 				items = append(items, item)
 				failed++
-				if terminal {
-					aborted = true
-					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, ensureErr)
-					break
-				}
 				continue
 			}
 			token, _, upErr := drivePushUploadFile(ctx, runtime, localFile, "", parentToken)
@@ -364,7 +352,6 @@ var DriveSync = common.Shortcut{
 				items = append(items, item)
 				failed++
 				if terminal {
-					aborted = true
 					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, upErr)
 					break
 				}
@@ -376,7 +363,7 @@ var DriveSync = common.Shortcut{
 
 		// 2c. Resolve modified files by --on-conflict strategy.
 		for _, entry := range modified {
-			if aborted {
+			if driveSyncHasTerminalFailure(items) {
 				break
 			}
 			remoteFile := remoteFiles[entry.RelPath]
@@ -410,7 +397,6 @@ var DriveSync = common.Shortcut{
 					items = append(items, item)
 					failed++
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, err)
 						break
 					}
@@ -429,14 +415,9 @@ var DriveSync = common.Shortcut{
 				}
 				parentToken, parentErr := drivePushEnsureFolder(ctx, runtime, folderToken, drivePushParentRel(entry.RelPath), folderCache)
 				if parentErr != nil {
-					item, terminal := driveSyncFailedItem(entry.RelPath, existingToken, "failed", "push", "create_folder", parentErr)
+					item, _ := driveSyncFailedItem(entry.RelPath, existingToken, "failed", "push", "create_folder", parentErr)
 					items = append(items, item)
 					failed++
-					if terminal {
-						aborted = true
-						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, parentErr)
-						break
-					}
 					continue
 				}
 				token, _, upErr := drivePushUploadFile(ctx, runtime, localFile, existingToken, parentToken)
@@ -454,7 +435,6 @@ var DriveSync = common.Shortcut{
 					items = append(items, item)
 					failed++
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, upErr)
 						break
 					}
@@ -523,7 +503,6 @@ var DriveSync = common.Shortcut{
 					items = append(items, item)
 					failed++
 					if terminal {
-						aborted = true
 						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, downloadErr)
 						break
 					}
@@ -552,7 +531,7 @@ var DriveSync = common.Shortcut{
 				"pushed":  pushed,
 				"skipped": skipped,
 				"failed":  failed,
-				"aborted": aborted,
+				"aborted": driveSyncHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -598,6 +577,15 @@ func driveSyncFailedItem(relPath, fileToken, action, direction, phase string, er
 	return item, decision.Terminal
 }
 
+func driveSyncHasTerminalFailure(items []driveSyncItem) bool {
+	for _, item := range items {
+		if driveTerminalBatchErrorClass(item.ErrorClass) {
+			return true
+		}
+	}
+	return false
+}
+
 // driveSyncAskConflict prompts the user for a conflict resolution strategy
 // for a single file. Returns the strategy string, or empty string if the
 // user chose to skip.

shortcuts/markdown/helpers.go

@@ -715,15 +715,9 @@ func markdownUploadProblem(err error, action string) error {
 		case 90003087:
 			appendMarkdownProblemHint(err, "The current tenant or user may not have document capabilities enabled. Ask an administrator to verify document-module access.")
 		case 1061003, 1061044:
-			appendMarkdownProblemHint(err, "Check whether the target folder or wiki node still exists, and verify the parent token type. For Drive folders, pass --folder-token with a Drive folder token/URL; for wiki nodes, pass --wiki-token with a wiki node token/URL.")
+			appendMarkdownProblemHint(err, "Check whether the target folder or wiki node still exists, and verify the token you passed to the command.")
 		case 1061004, 1062501:
 			appendMarkdownProblemHint(err, "Check whether the current identity has write access to the target folder or wiki node.")
-		case 1061101:
-			appendMarkdownProblemHint(err, "The target Drive/wiki storage quota is exhausted. Free space, choose another parent folder/wiki node, or ask an administrator to raise quota before retrying.")
-		case 233523001:
-			appendMarkdownProblemHint(err, "The upstream document service returned a transient server error. Retry later; if it repeats, keep the log_id/request_id for service-side investigation.")
-		case 99991400:
-			appendMarkdownProblemHint(err, "The upload API is rate limited. Stop immediate retries and retry later with exponential backoff.")
 		}
 	}
 	return err

shortcuts/markdown/markdown_create.go

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

shortcuts/markdown/markdown_test.go

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

shortcuts/minutes/minutes_detail.go

@@ -28,12 +28,7 @@ import (
 const minutesDetailLogPrefix = "[minutes +detail]"
 
 // Error codes from the minutes API.
-const (
-	minutesDetailProcessingCode       = 2091003
-	minutesDetailNoReadPermissionCode = 2091005
-	minutesDetailWaitTimeoutDefault   = 300
-	minutesDetailWaitIntervalDefault  = 15
-)
+const minutesDetailNoReadPermissionCode = 2091005
 
 var validMinuteTokenDetail = regexp.MustCompile(`^[a-z0-9]+$`)
 
@@ -45,31 +40,19 @@ 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 {
-	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)
-	})
+	data, err := 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 isMinutesDetailProcessingError(err) {
-			markMinutesDetailProcessing(result, minuteToken, artifactFlags, "minute metadata is still being generated")
-		} else if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailNoReadPermissionCode {
+		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)
@@ -98,16 +81,10 @@ func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minu
 	needKeyword := runtime.Bool("keyword")
 
 	if needSummary || needTodo || needChapter || needTranscript || needKeyword {
-		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)
-		})
+		artData, err := runtime.CallAPITyped(http.MethodGet,
+			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/artifacts", validate.EncodePathSegment(minuteToken)), nil, nil)
 		if err != nil {
-			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)
-			}
+			fmt.Fprintf(runtime.IO().ErrOut, "%s failed to fetch artifacts for %s: %v\n", minutesDetailLogPrefix, minuteToken, err)
 		} else {
 			artifacts := make(map[string]any)
 			if needSummary {
@@ -156,78 +133,6 @@ 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
@@ -296,9 +201,6 @@ 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"))
@@ -380,15 +282,8 @@ var MinutesDetail = common.Shortcut{
 			for _, r := range results {
 				row := map[string]interface{}{"minute_token": r.MinuteToken}
 				if r.Error != "" {
-					if r.Status == "processing" {
-						row["status"] = "PROCESSING"
-					} else {
-						row["status"] = "FAIL"
-					}
+					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,7 +9,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"net/http"
 	"os"
 	"strings"
 	"sync"
@@ -109,17 +108,6 @@ 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)
@@ -184,34 +172,6 @@ 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
 // ---------------------------------------------------------------------------
@@ -395,136 +355,6 @@ 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
 // ---------------------------------------------------------------------------
@@ -548,36 +378,6 @@ 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,8 +5,6 @@ package minutes
 
 import (
 	"context"
-	"net/url"
-	"strings"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
@@ -67,25 +65,8 @@ 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,28 +143,4 @@ 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)
-			}
-		})
-	}
 }

shortcuts/wiki/wiki_helpers.go

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

shortcuts/wiki/wiki_list_copy_test.go

@@ -5,14 +5,12 @@ package wiki
 
 import (
 	"encoding/json"
-	"errors"
 	"net/http"
 	"net/url"
 	"reflect"
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -132,147 +130,6 @@ func TestWikiNodeListRequiresSpaceID(t *testing.T) {
 	}
 }
 
-func TestWikiNodeListRejectsNonNumericSpaceID(t *testing.T) {
-	t.Parallel()
-
-	factory, _, _, _ := cmdutil.TestFactory(t, wikiTestConfig())
-	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "wikcnABC", "--as", "user",
-	}, factory, nil)
-	if err == nil {
-		t.Fatalf("expected numeric space_id validation error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-	}
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) {
-		t.Fatalf("expected ValidationError, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument || validationErr.Param != "--space-id" {
-		t.Fatalf("problem = %#v param=%q, want validation/invalid_argument/--space-id", p, validationErr.Param)
-	}
-	if !strings.Contains(p.Message, "--space-id must be a numeric wiki space_id") || !strings.Contains(p.Hint, "+space-list") {
-		t.Fatalf("expected numeric space_id validation error, got %v", err)
-	}
-}
-
-func TestWikiNodeListRejectsDocumentURLAsParentNodeToken(t *testing.T) {
-	t.Parallel()
-
-	factory, _, _, _ := cmdutil.TestFactory(t, wikiTestConfig())
-	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list",
-		"--space-id", "7211568716812369922",
-		"--parent-node-token", "https://feishu.cn/docx/docxABC",
-		"--as", "user",
-	}, factory, nil)
-	if err == nil {
-		t.Fatalf("expected parent-node-token URL type validation error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-	}
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) {
-		t.Fatalf("expected ValidationError, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument || validationErr.Param != "--parent-node-token" {
-		t.Fatalf("problem = %#v param=%q, want validation/invalid_argument/--parent-node-token", p, validationErr.Param)
-	}
-	if !strings.Contains(p.Message, "must identify a wiki node") || !strings.Contains(p.Hint, "+node-get") {
-		t.Fatalf("expected parent-node-token URL type validation error, got %v", err)
-	}
-}
-
-func TestWikiNodeListNormalizesWikiURLParentNodeToken(t *testing.T) {
-	t.Parallel()
-
-	token, err := normalizeWikiNodeListParentToken("https://feishu.cn/wiki/wikcnPARENT?from=copy")
-	if err != nil {
-		t.Fatalf("normalizeWikiNodeListParentToken() error = %v", err)
-	}
-	if token != "wikcnPARENT" {
-		t.Fatalf("token = %q, want wikcnPARENT", token)
-	}
-}
-
-func TestWikiNodeListRejectsAmbiguousSpaceAndParentTokens(t *testing.T) {
-	t.Parallel()
-
-	if err := validateWikiNodeListSpaceID("https://example.invalid/wiki/space"); err == nil {
-		t.Fatalf("expected URL space-id validation error")
-	} else {
-		p, ok := errs.ProblemOf(err)
-		if !ok {
-			t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-		}
-		if !strings.Contains(p.Message, "not a URL or path") || !strings.Contains(p.Hint, "+space-list") {
-			t.Fatalf("problem = %#v, want URL/path message and +space-list hint", p)
-		}
-	}
-
-	tests := []struct {
-		name    string
-		input   string
-		wantMsg string
-	}{
-		{
-			name:    "partial wiki path",
-			input:   "wik_placeholder/child",
-			wantMsg: "raw wiki node token",
-		},
-		{
-			name:    "document token",
-			input:   "docx_placeholder_parent",
-			wantMsg: "must be a wiki node token",
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			_, err := normalizeWikiNodeListParentToken(tt.input)
-			if err == nil {
-				t.Fatalf("expected parent token validation error")
-			}
-			p, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("ProblemOf() ok=false for %T: %v", err, err)
-			}
-			if !strings.Contains(p.Message, tt.wantMsg) {
-				t.Fatalf("message = %q, want substring %q", p.Message, tt.wantMsg)
-			}
-		})
-	}
-}
-
-func TestWikiNodeListAcceptsEmptyParentToken(t *testing.T) {
-	t.Parallel()
-
-	token, err := normalizeWikiNodeListParentToken("")
-	if err != nil {
-		t.Fatalf("normalizeWikiNodeListParentToken(empty) error = %v", err)
-	}
-	if token != "" {
-		t.Fatalf("token = %q, want empty", token)
-	}
-}
-
-func TestWikiNodeListProblemAddsActionableHint(t *testing.T) {
-	t.Parallel()
-
-	err := errs.NewAPIError(errs.SubtypeInvalidParameters, "param err: invalid page_token").WithCode(131002)
-	got := wikiNodeListProblem(err, nil)
-	p, ok := errs.ProblemOf(got)
-	if !ok {
-		t.Fatalf("ProblemOf() ok=false")
-	}
-	if !strings.Contains(p.Hint, "page token is invalid or stale") {
-		t.Fatalf("hint = %q, want invalid page token guidance", p.Hint)
-	}
-}
-
 func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
@@ -280,14 +137,14 @@ func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes",
 		Body: map[string]interface{}{
 			"code": 0,
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":          "7211568716812369922",
+						"space_id":          "space_123",
 						"node_token":        "wik_node_1",
 						"obj_token":         "docx_1",
 						"obj_type":          "docx",
@@ -297,7 +154,7 @@ func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 						"has_child":         true,
 					},
 					map[string]interface{}{
-						"space_id":          "7211568716812369922",
+						"space_id":          "space_123",
 						"node_token":        "wik_node_2",
 						"obj_token":         "docx_2",
 						"obj_type":          "docx",
@@ -313,7 +170,7 @@ func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 	})
 
 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "7211568716812369922", "--as", "bot",
+		"+node-list", "--space-id", "space_123", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -354,14 +211,14 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {
 
 	stub := &httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes?page_size=50&parent_node_token=wik_parent",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes?page_size=50&parent_node_token=wik_parent",
 		Body: map[string]interface{}{
 			"code": 0,
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":          "7211568716812369922",
+						"space_id":          "space_123",
 						"node_token":        "wik_child",
 						"obj_token":         "docx_child",
 						"obj_type":          "docx",
@@ -378,7 +235,7 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {
 	reg.Register(stub)
 
 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "7211568716812369922", "--parent-node-token", "wik_parent", "--as", "bot",
+		"+node-list", "--space-id", "space_123", "--parent-node-token", "wik_parent", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -429,7 +286,7 @@ func TestWikiNodeListResolvesMyLibraryForUser(t *testing.T) {
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"space": map[string]interface{}{
-					"space_id":   "7211568716812369923",
+					"space_id":   "space_personal_42",
 					"name":       "My Library",
 					"space_type": "my_library",
 				},
@@ -439,14 +296,14 @@ func TestWikiNodeListResolvesMyLibraryForUser(t *testing.T) {
 	// Step 2: list nodes in the resolved space.
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369923/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/space_personal_42/nodes",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":   "7211568716812369923",
+						"space_id":   "space_personal_42",
 						"node_token": "wik_personal_1",
 						"title":      "Personal Note",
 					},
@@ -477,8 +334,8 @@ func TestWikiNodeListResolvesMyLibraryForUser(t *testing.T) {
 	if envelope.Meta.Count != 1 {
 		t.Fatalf("meta.count = %v, want 1", envelope.Meta.Count)
 	}
-	if envelope.Data.Nodes[0]["space_id"] != "7211568716812369923" {
-		t.Fatalf("nodes[0].space_id = %v, want 7211568716812369923", envelope.Data.Nodes[0]["space_id"])
+	if envelope.Data.Nodes[0]["space_id"] != "space_personal_42" {
+		t.Fatalf("nodes[0].space_id = %v, want space_personal_42", envelope.Data.Nodes[0]["space_id"])
 	}
 }
 
@@ -901,21 +758,21 @@ func TestWikiNodeListDefaultIsSinglePage(t *testing.T) {
 	// test pins down the "default = single page" contract.
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"has_more":   true,
 				"page_token": "tok_next",
 				"items": []interface{}{
-					map[string]interface{}{"space_id": "7211568716812369922", "node_token": "wik_1", "title": "First"},
+					map[string]interface{}{"space_id": "space_123", "node_token": "wik_1", "title": "First"},
 				},
 			},
 		},
 	})
 
 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "7211568716812369922", "--as", "bot",
+		"+node-list", "--space-id", "space_123", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -945,14 +802,14 @@ func TestWikiNodeListPrettyFormatRendersFields(t *testing.T) {
 	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":   "7211568716812369922",
+						"space_id":   "space_123",
 						"node_token": "wik_1",
 						"obj_type":   "docx",
 						"obj_token":  "docx_1",
@@ -965,7 +822,7 @@ func TestWikiNodeListPrettyFormatRendersFields(t *testing.T) {
 	})
 
 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "7211568716812369922", "--format", "pretty", "--as", "bot",
+		"+node-list", "--space-id", "space_123", "--format", "pretty", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)

shortcuts/wiki/wiki_node_list.go

@@ -48,19 +48,27 @@ var WikiNodeList = common.Shortcut{
 		"--space-id my_library is a per-user alias and is only valid with --as user.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if _, err := readWikiNodeListSpec(runtime); err != nil {
+		spaceID := strings.TrimSpace(runtime.Str("space-id"))
+		// my_library is a per-user personal-library alias; it has no meaning
+		// for a tenant_access_token (--as bot), so reject early with a clear
+		// hint instead of deferring to API-time errors. Matches the contract
+		// used by +node-create and +move.
+		if runtime.As().IsBot() && spaceID == wikiMyLibrarySpaceID {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "bot identity does not support --space-id my_library; use an explicit --space-id").WithParam("--space-id")
+		}
+		if err := validateOptionalResourceName(spaceID, "--space-id"); err != nil {
+			return err
+		}
+		if err := validateOptionalResourceName(strings.TrimSpace(runtime.Str("parent-node-token")), "--parent-node-token"); err != nil {
 			return err
 		}
 		return validateWikiListPagination(runtime, wikiNodeListMaxPageSize)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		spec, err := readWikiNodeListSpec(runtime)
-		if err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
-		}
+		spaceID := strings.TrimSpace(runtime.Str("space-id"))
 		params := map[string]interface{}{"page_size": runtime.Int("page-size")}
-		if spec.ParentNodeToken != "" {
-			params["parent_node_token"] = spec.ParentNodeToken
+		if pt := strings.TrimSpace(runtime.Str("parent-node-token")); pt != "" {
+			params["parent_node_token"] = pt
 		}
 		if pt := strings.TrimSpace(runtime.Str("page-token")); pt != "" {
 			params["page_token"] = pt
@@ -72,7 +80,7 @@ var WikiNodeList = common.Shortcut{
 		// When the caller passes my_library, +node-list must first resolve it
 		// to the real per-user space_id before listing nodes, mirroring the
 		// two-step orchestration used by +node-create.
-		if spec.SpaceID == wikiMyLibrarySpaceID {
+		if spaceID == wikiMyLibrarySpaceID {
 			return d.
 				Desc("2-step orchestration: resolve my_library -> list nodes").
 				GET("/open-apis/wiki/v2/spaces/my_library").
@@ -83,17 +91,13 @@ var WikiNodeList = common.Shortcut{
 				Set("space_id", "<resolved_space_id>")
 		}
 		return d.
-			GET(fmt.Sprintf("/open-apis/wiki/v2/spaces/%s/nodes", validate.EncodePathSegment(spec.SpaceID))).
+			GET(fmt.Sprintf("/open-apis/wiki/v2/spaces/%s/nodes", validate.EncodePathSegment(spaceID))).
 			Params(params).
-			Set("space_id", spec.SpaceID)
+			Set("space_id", spaceID)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		warnIfConflictingPagingFlags(runtime)
-		spec, err := readWikiNodeListSpec(runtime)
-		if err != nil {
-			return err
-		}
-		spaceID := spec.SpaceID
+		spaceID := strings.TrimSpace(runtime.Str("space-id"))
 
 		// Resolve the my_library alias to the per-user real space_id before
 		// listing, so the subsequent request hits a concrete space endpoint.
@@ -106,7 +110,7 @@ var WikiNodeList = common.Shortcut{
 			spaceID = resolved
 		}
 
-		nodes, hasMore, nextToken, err := fetchWikiNodes(runtime, spaceID, spec.ParentNodeToken)
+		nodes, hasMore, nextToken, err := fetchWikiNodes(runtime, spaceID)
 		if err != nil {
 			return err
 		}
@@ -123,104 +127,10 @@ var WikiNodeList = common.Shortcut{
 	},
 }
 
-type wikiNodeListSpec struct {
-	SpaceID         string
-	ParentNodeToken string
-}
-
-func readWikiNodeListSpec(runtime *common.RuntimeContext) (wikiNodeListSpec, error) {
-	spaceID := strings.TrimSpace(runtime.Str("space-id"))
-	// my_library is a per-user personal-library alias; it has no meaning
-	// for a tenant_access_token (--as bot), so reject early with a clear
-	// hint instead of deferring to API-time errors. Matches the contract
-	// used by +node-create and +move.
-	if runtime.As().IsBot() && spaceID == wikiMyLibrarySpaceID {
-		return wikiNodeListSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "bot identity does not support --space-id my_library; use an explicit numeric --space-id").WithParam("--space-id")
-	}
-	if err := validateWikiNodeListSpaceID(spaceID); err != nil {
-		return wikiNodeListSpec{}, err
-	}
-
-	parentNodeToken, err := normalizeWikiNodeListParentToken(strings.TrimSpace(runtime.Str("parent-node-token")))
-	if err != nil {
-		return wikiNodeListSpec{}, err
-	}
-	return wikiNodeListSpec{SpaceID: spaceID, ParentNodeToken: parentNodeToken}, nil
-}
-
-func validateWikiNodeListSpaceID(spaceID string) error {
-	if spaceID == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--space-id is required").WithParam("--space-id")
-	}
-	if spaceID == wikiMyLibrarySpaceID {
-		return nil
-	}
-	if strings.Contains(spaceID, "://") || strings.ContainsAny(spaceID, "/?#") {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--space-id must be a numeric wiki space_id, not a URL or path",
-		).WithParam("--space-id").WithHint("Run `lark-cli wiki +space-list --as user` to discover space IDs.")
-	}
-	if !isDecimalWikiSpaceID(spaceID) {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--space-id must be a numeric wiki space_id; do not pass a wiki node token, document token, or title",
-		).WithParam("--space-id").WithHint("Run `lark-cli wiki +space-list --as user` to list accessible wiki spaces, then pass the numeric `space_id`.")
-	}
-	if err := validateOptionalResourceName(spaceID, "--space-id"); err != nil {
-		return err
-	}
-	return nil
-}
-
-func isDecimalWikiSpaceID(value string) bool {
-	if value == "" {
-		return false
-	}
-	for _, r := range value {
-		if r < '0' || r > '9' {
-			return false
-		}
-	}
-	return true
-}
-
-func normalizeWikiNodeListParentToken(parentNodeToken string) (string, error) {
-	if parentNodeToken == "" {
-		return "", nil
-	}
-	if strings.Contains(parentNodeToken, "://") {
-		ref, ok := common.ParseResourceURL(parentNodeToken)
-		if !ok {
-			return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--parent-node-token URL is unsupported",
-			).WithParam("--parent-node-token").WithHint("Pass a raw wiki node token from `wiki +node-get` or `wiki +node-list`.")
-		}
-		if ref.Type != "wiki" {
-			return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--parent-node-token must identify a wiki node; got a %s URL",
-				ref.Type,
-			).WithParam("--parent-node-token").WithHint("Resolve the document URL with `lark-cli wiki +node-get --node-token <url>` and use its `node_token`.")
-		}
-		parentNodeToken = ref.Token
-	}
-	if strings.ContainsAny(parentNodeToken, "/?#") {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--parent-node-token must be a raw wiki node token, not a partial URL or path",
-		).WithParam("--parent-node-token")
-	}
-	if !looksLikeWikiNodeToken(parentNodeToken) {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--parent-node-token must be a wiki node token; do not pass a docx/sheet/base/file token",
-		).WithParam("--parent-node-token").WithHint("Run `lark-cli wiki +node-get --node-token <url-or-token>` to resolve a document URL or obj_token to the wiki `node_token` first.")
-	}
-	if err := validateOptionalResourceName(parentNodeToken, "--parent-node-token"); err != nil {
-		return "", err
-	}
-	return parentNodeToken, nil
-}
-
-func fetchWikiNodes(runtime *common.RuntimeContext, spaceID, parentNodeToken string) ([]map[string]interface{}, bool, string, error) {
+func fetchWikiNodes(runtime *common.RuntimeContext, spaceID string) ([]map[string]interface{}, bool, string, error) {
 	pageSize := runtime.Int("page-size")
 	startToken := strings.TrimSpace(runtime.Str("page-token"))
+	parentNodeToken := strings.TrimSpace(runtime.Str("parent-node-token"))
 	auto := wikiListShouldAutoPaginate(runtime)
 	pageLimit := runtime.Int("page-limit")
 
@@ -243,7 +153,7 @@ func fetchWikiNodes(runtime *common.RuntimeContext, spaceID, parentNodeToken str
 		}
 		data, err := runtime.CallAPITyped("GET", apiPath, params, nil)
 		if err != nil {
-			return nil, false, "", wikiNodeListProblem(err, runtime)
+			return nil, false, "", err
 		}
 		items, _ := data["items"].([]interface{})
 		for _, item := range items {
@@ -267,36 +177,6 @@ func fetchWikiNodes(runtime *common.RuntimeContext, spaceID, parentNodeToken str
 	return nodes, lastHasMore, lastPageToken, nil
 }
 
-func wikiNodeListProblem(err error, runtime *common.RuntimeContext) error {
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		return err
-	}
-	switch p.Code {
-	case 131002:
-		msg := strings.ToLower(p.Message)
-		switch {
-		case strings.Contains(msg, "page_token"):
-			appendWikiProblemHint(err, "The page token is invalid or stale. Use only the `page_token` returned by the immediately preceding `wiki +node-list` response, or omit --page-token and start over.")
-		case strings.Contains(msg, "space_id"):
-			appendWikiProblemHint(err, "The --space-id value must be the numeric wiki space_id from `wiki +space-list`; do not pass a wiki URL, node token, document token, or title.")
-		default:
-			appendWikiProblemHint(err, "Check the wiki +node-list flags. Fix the parameter before retrying; this is not a transient error.")
-		}
-	case 131005:
-		appendWikiProblemHint(err, "The target wiki space or parent node was not found. Re-discover the space with `wiki +space-list` and the parent with `wiki +node-list`/`wiki +node-get`; do not retry the same stale token.")
-	case 131006:
-		if runtime != nil && runtime.As().IsBot() {
-			appendWikiProblemHint(err, "The bot/app identity cannot read this wiki space or node. Grant the app the required wiki scope and ensure the app or bot has access to the target knowledge space.")
-		} else {
-			appendWikiProblemHint(err, "The current user cannot read this wiki space or node. Switch to a user with access or ask the space owner to grant read permission.")
-		}
-	case 99991400:
-		appendWikiProblemHint(err, "Rate limited by the wiki API. Stop immediate retries and retry later with exponential backoff or a smaller --page-limit.")
-	}
-	return err
-}
-
 func wikiNodeListItem(m map[string]interface{}) map[string]interface{} {
 	return map[string]interface{}{
 		"space_id":          common.GetString(m, "space_id"),

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)。仅编辑字段（改标题/描述）或增删参会人（不涉及时间和会议室）时可跳过，直接读 [`references/lark-calendar-update.md`](references/lark-calendar-update.md)。**
+**CRITICAL — 凡涉及预约日程/会议或查询/搜索会议室，第一步 MUST 读 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。禁止跳过此步直接调用 API 或 Shortcut！**
 
 ## 身份
 
@@ -30,80 +30,26 @@ lark-cli calendar +agenda --as user
 
 | Shortcut | 说明 |
 |----------|------|
-| `+agenda` | 查看日程安排（默认今天） |
+| [`+agenda`](references/lark-calendar-agenda.md) | 查看日程安排（默认今天） |
+| [`+search-event`](references/lark-calendar-search-event.md) | 按关键词、时间范围和参会人搜索日程, 仅返回 日程ID/主题/时间等信息，详情需走 `events get` |
 | [`+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` | 查询用户主日历的忙闲信息和 RSVP 状态（纯查询场景；预约场景走 `+suggestion`） |
+| [`+freebusy`](references/lark-calendar-freebusy.md) | 查询用户主日历的忙闲信息和 RSVP 状态 |
 | [`+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-update.md](references/lark-calendar-update.md) |
-| 编辑已有日程（涉及时间或会议室） | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
+| 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
+| 编辑已有日程 | 先定位目标日程 `event_id` |
 | 编辑/删除重复性日程 | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，按操作范围（仅此次/全部/此次及后续）执行 |
+| 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
 | 调用任何 Shortcut | 先读其对应 reference 文档 |
 
-## 写操作反馈
-
-创建、更新、删除、RSVP 等写操作完成后，直接基于命令返回结果反馈用户；不要为了“确认是否生效”主动发起二次查询。只有用户明确要求复查，或命令返回信息不足以回答用户问题时，才需要再查询。
-
 ## 核心概念
 
 - **日程实例（Instance）**：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 `event_id`；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 `event_id`），并按需处理例外。
@@ -126,8 +72,7 @@ lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
 | 按关键词搜索日程 | 本 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) |
-| 仅编辑日程字段（标题/描述）或增删参会人（不涉及时间和会议室） | 先定位 `event_id`，再读 [+update](references/lark-calendar-update.md) 执行变更 |
+| 预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
 | 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |
 
 ## 任务类型分流
@@ -145,7 +90,7 @@ lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
 
 ## 会议室规则
 
-- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)，会议室参数规范详见 [+room-find](references/lark-calendar-room-find.md)。
+- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)。
 - `+room-find` 的时间输入必须是确定时间块，不能是时间区间搜索。
 - 用户仅要求"查会议室"但未提供明确时间时，必须先调用 `+suggestion` 获取可用时间块，再将时间块交给 `+room-find`。严禁猜测时间盲目调用。
 - 编辑已有日程时，"添加会议室"默认是增量语义，保留已有会议室；只有用户明确说"更换会议室""移除会议室"时才删除旧会议室。
@@ -153,45 +98,42 @@ lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
 ## 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>
 ```
 
-> `calendar_id` 可以直接传 `primary`，代表当前调用身份的主日历 ID。
+### calendars
 
-### 查询资源的方法列表以及方法的使用方式
+  - `create` — 创建共享日历
+  - `delete` — 删除共享日历
+  - `get` — 查询日历信息
+  - `list` — 查询日历列表
+  - `patch` — 更新日历信息
+  - `primary` — 查询用户主日历
+  - `search` — 搜索日历
 
-- 列出某资源下的方法：`lark-cli calendar <resource> -h`
-- 查看方法的cli flag：`lark-cli calendar <resource> <method> -h`
-- 查看方法API参数：`lark-cli schema calendar.<resource>.<method>`
+### event.attendees
 
-`<resource>` 为 `calendars`（日历本身）/ `events`（日程）/ `event.attendees`（参与人）/ `freebusys`（忙闲）。例：`lark-cli schema calendar.events.delete`。
+  - `batch_delete` — 删除日程参与人
+  - `create` — 添加日程参与人
+  - `list` — 获取日程参与人列表
 
-## 常用其他域命令
+### events
 
-```bash
-# 搜索用户，更多参数详见 lark-contact
-lark-cli contact +search-user --query <query> --as user
+  - `create` — 创建日程
+  - `delete` — 删除日程
+  - `get` — 获取日程
+  - `instance_view` — 查询日程视图
+  - `patch` — 更新日程
+  - `share_info` — 获取日程分享链接
 
-# 搜索群聊，更多参数详见 lark-im
-lark-cli im +chat-search --query <query> --as user
-```
+### freebusys
+
+  - `list` — 查询主日历日程忙闲信息
 
 ## 不在本 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

@@ -0,0 +1,78 @@
+
+# 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,9 +1,12 @@
 
 # calendar +create
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 创建日程并按需邀请参会人。
 
+需要的scopes: ["calendar:calendar.event:create","calendar:calendar.event:update"]
+
 ## 推荐命令
 
 ```bash
@@ -35,10 +38,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。示例值："FREQ=DAILY;INTERVAL=1;UNTIL=<具体日期>" |
+| `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1" |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
 
-> 当用户表达'每周 X'、'每周重复'、'连续 N 周'时，必须使用 rrule 创建重复性日程，而非创建多个独立日程
+> **⚠️ `rrule` 规则限制：飞书日历系统不支持 `COUNT` 参数。遇到限制重复次数的需求，必须根据开始时间和频率自行推算并转换成 `UNTIL=<具体日期>` 格式。**
 > 自动设置 `attendee_ability: "can_modify_event"`，参会人可查看彼此并编辑日程。
 > 自动设置 `free_busy_status: "busy"`，默认日程忙闲状态为忙碌。
 > 自动设置 `reminders: [{"minutes": 5}]`，默认日程开始前 5 分钟提醒。
@@ -53,16 +56,44 @@ 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": "申请原因"}]}'
 
-完整 API 命令的关键差异：
-- 时间参数是 **Unix 秒字符串**（非 ISO 8601）。
-- 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天；单日全天日程两者相同。
-- 手动拆成“创建日程 + 添加参会人”两步时，若第二步失败，建议删除刚创建的空日程，避免遗留无参会人的日程。
+# 可选第三步（推荐）：若第二步失败，回滚删除空日程
+## 查看完整参数定义
+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）。
+> 当你手动拆成两步执行时，建议保留“失败后回滚删除”的第三步，避免遗留空日程。
 
 ## 参会人类型
 
@@ -78,5 +109,6 @@ lark-cli calendar event.attendees create \
 
 ## 参考
 
-- [lark-calendar](../SKILL.md) -- skill 入口与路由
+- [lark-calendar](../SKILL.md) -- 日历全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
 - [lark-calendar-suggestion](lark-calendar-suggestion.md) -- 根据非明确时间或一段时间范围，推荐多个可用时间块方案

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

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

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

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

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

@@ -1,59 +0,0 @@
-# 明确时间分支：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

@@ -1,88 +0,0 @@
-# 模糊时间 / 无时间信息分支：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,95 +1,206 @@
 # 预约/改约日程或会议、查询/搜索可用会议室的工作流
 
-## 执行摘要
+## CRITICAL 执行摘要（先按这个骨架执行，再看下方细则）
 
-- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。**
-- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。**
-- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。
-- **新建流先补默认值，编辑流先继承已定位日程信息。**
-- **明确时间** → 进入 [明确时间分支](./lark-calendar-schedule-clear-time.md)
-- **模糊时间或无时间信息** → 进入 [模糊时间分支](./lark-calendar-schedule-fuzzy-time.md)
-- **BLOCKING REQUIREMENT**: 面临时间方案或会议室方案的选择时，必须先向用户展示选项并等待确认，禁止未经确认直接创建/更新日程。
-- **必须按顺序执行。** 不要跳过"任务类型判定""目标日程定位（编辑流）""补默认值/继承基线信息""判断时间明确性"这些前置步骤。
+- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。** 不要把“预约/查会议室”默认等同于“新建”。
+- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。** 用户一旦给出了既有日程锚点（标题、时间段、`这个日程`、`这场会`）并表达修改动作（加人、删人、改时间、换会议室等），默认走编辑流。
+- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，避免把用户带入表单式问答。
+- **新建流先补默认值，编辑流先继承已定位日程信息。** 默认值包括标题、参会人、时长，以及在“完全无时间信息”时的默认时间范围；编辑流则优先复用已定位日程的标题、时间、已有参与人和会议室信息作为基线。
+- **只有三类场景才主动追问用户**：存在时间冲突、搜索结果无法唯一确定、时间语义本身有歧义。
+- **编辑流的时间基准必须明确。** 如果编辑时不改时间，则后续会议室搜索必须基于已定位日程的原始起止时间；如果既改时间又加会议室，必须先确定最终时间，再基于该时间搜索会议室。
+- **编辑流中“新增会议室”默认是增量语义。** 如果用户说的是“加会议室/再加一个会议室”，最终 `+update` 只做 `add`，默认保留已有会议室；只有在用户明确说“更换会议室/移除会议室”时，才执行旧会议室删除。
+- **明确时间**：若需要会议室，先 `+room-find`；再 `+freebusy` 判断参会人忙闲；有冲突时先说明冲突，再让用户决定继续当前时间还是改走 `+suggestion`。
+- **模糊时间或无时间信息**：先 `+suggestion` 产出候选时间块；若需要会议室，再把这些时间块批量交给 `+room-find`，将“候选时间 + 对应可用会议室”一次性展示给用户选择。
+- **BLOCKING REQUIREMENT: 只要面临时间方案（模糊时间/无时间）或会议室方案（需要会议室）的选择，必须先向用户展示选项并等待用户明确确认，绝对禁止在未获用户确认的情况下直接执行创建新日程或更新既有日程。**
+- **用户选中了 `+suggestion` 返回的候选时间块后，不要再次调用 `+freebusy`。** 用户确认后直接进入最终落地操作：创建新日程，或更新既有日程。
+- **当用户说“查会议室”“找会议室”“搜可用会议室”时，默认意图是查会议室可用性，不是检索会议室资源名录。**
+- **必须按顺序执行。** 不要跳过“任务类型判定”“目标日程定位（编辑流）”“补默认值/继承基线信息”“判断时间明确性”这些前置步骤。
+
+> **💡 核心原则：做智能助理，充分利用默认值规则（如默认标题、时长、参与人等）自动补全信息。极力避免像“表单填写机”一样频繁打断并反问用户，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。**
 
 ## 严禁行为
 
-- **严禁在未读取对应子命令文档前直接调用命令。**
-- **严禁在尚未判断"新建"还是"编辑"之前，就直接进入创建日程或查会议室动作。**
-- **严禁把带有既有日程锚点 + 修改动词的请求当成新建日程。**
-- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一 `event_id` 前，不得调用 `+update`。
-- **严禁在面临时间/会议室方案选择时，未经用户确认就擅自创建/更新日程。**
+- **严禁在未读取对应子命令文档（如 `lark-calendar-room-find.md`、`lark-calendar-suggestion.md`）的情况下直接调用命令！** 必须先阅读文档掌握最新参数要求与规范。
+- **严禁在尚未判断“新建”还是“编辑”之前，就直接进入创建日程或查会议室动作。**
+- **严禁把“给明天上午的‘产品发布会’加人/加群/加会议室”这类带有既有日程锚点 + 修改动词的请求，当成新建日程。** 这类请求必须先定位目标日程。
+- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一的 `event_id` 前，不得调用 `+update`、也不得基于猜测时间去查会议室。
+- **严禁在用户仅要求“查会议室”但未提供明确时间时，直接调用 `+room-find`！** 必须先默认一个合理时间范围，调用 `+suggestion` 拿到候选时间块，再将时间块传给 `+room-find`。
+- **不要在用户完全没给时间时，直接反问“你想约什么时候”。** 先补一个合理时间范围，再进入 `+suggestion`。
+- **不要在“需要会议室 + 时间模糊”的场景下，先让用户只选时间。** 应先批量查出每个候选时间对应的可用会议室，再让用户一次性完成选择。
+- **不要在用户已经选中 `+suggestion` 候选时间后，再重复调用 `+freebusy`。**
+- **不要在用户未明确说出城市时，仅凭园区/办公室名自动补城市。**
+- **严禁在面临时间方案或会议室方案的选择时（模糊时间、无时间或需要会议室），未经用户确认就擅自创建新日程或更新既有日程。**
 
 ## 适用场景
 
-- "帮我约个会" / "下周找时间和 XX 开会"
-- "帮我订/找/搜索一个可用会议室"
-- "明天下午3点约个日程"
-- "把明天上午的日程加上 小明"
-- "给下周一的周会换个会议室"
-- "把这个日程改到明天下午，并加上学清 F201"
+- “帮我约个会”
+- “下周找时间和 XX 开会”
+- “帮我订个会议室”
+- “帮我找/搜索一个可用的会议室”
+- “帮我推荐一个我以前常用的会议室”
+- “查询明天下午可用的会议室”
+- “明天下午3点约个日程/日历”
+- “把明天上午的日程‘产品发布会’加上 小明
+- “给下周一的周会换个会议室”
+- “把这个日程改到明天下午，并加上学清 F201”
 
 ## 核心概念
 
-- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。**
-- **预定或查找会议室，均需先确定时间块。**
-- **当用户说"查会议室""找会议室"，默认意图是查会议室可用性，不是检索会议室资源名录。**
+- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。** 
+- **预定或查找会议室，均需先确定时间块。** 在推荐可用会议室后，应顺势引导用户完成最终的**日程落地**操作：创建新日程，或更新既有日程。
+
+## CRITICAL 约束
+
+- **在调用任何具体的 CLI 子命令（如 `+room-find`、`+suggestion`、`+freebusy`、`+create`）前，必须先读取其对应的 Markdown 文档。** 禁止仅凭记忆组装命令参数，以确保符合各命令最新的业务约束和格式规范。
+- **当用户说“查会议室”“找会议室”“搜可用会议室”等，默认意图是查询会议室可用性，而不是检索会议室资源名录。**
+- **必须严格按照下方【工作流】的步骤顺序完成任务。特别是单独查会议室时，若无明确时间，强制先走“模糊时间/无时间信息”分支调用 `+suggestion`。**
 
 ## 任务类型判定
 
 | 类型 | 典型语言信号 | 第一动作 |
 |------|--------------|----------|
-| 新建日程 | "约个会""安排会议""新建日程""订个会议室开会" | 补默认值，再进入时间判断 |
-| 编辑已有日程 | "给某日程加人/删人/加会议室""把某日程改到…""换会议室" | 先定位目标 `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`。
 
-- **标题**：根据上下文自动生成；如无法推断，默认"会议"
-- **参会人**：如未指定，默认仅用户自己
-- **时长**：基于上下文推断；默认 30 分钟
-- **无时间信息**：默认推断合理区间（如"今天"或"近两天"），进入时间推荐流程，禁止询问用户
+### 2. 新建日程：智能推断默认值
+以下信息智能推断，减少频繁询问用户：
 
-搜索参与人出现多个结果无法唯一确定时，必须询问用户并记录长期记忆。
+- **标题**：根据上下文自动生成，例如“沟通对齐”“需求讨论”；如无法推断，默认为“会议”
+- **参会人**：如未明确指定其他人，默认参会人仅为**用户自己**
+- **时长**：基于会议类型和上下文动态推断；如无法推断，默认为 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)
+如果是新建会议，详见 [`+create`](./lark-calendar-create.md)。
+如果是更新既有日程，详见 [`+update`](./lark-calendar-update.md)。必须先定位目标 `event_id`，再按用户意图用 `+update` 独立执行字段更新、添加参会人/会议室、移除参会人/会议室，或组合这些动作。若用户意图是“新增会议室”，默认仅追加 `room_id`，不移除已有会议室。
 
 ```bash
 lark-cli calendar +create \
@@ -103,20 +214,52 @@ 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"
 ```
 
-落地规则：
-- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新猜测目标日程
-- 编辑流中"新增会议室"默认仅追加 `room_id`，不移除已有会议室
-- 仅当用户明确说"更换会议室"时，才同时 `--remove-attendee-ids` 旧 + `--add-attendee-ids` 新
-- 需要会议室时，将选中的 `room_id` 写入参与人列表
+规则：
+- 新建日程时，可使用 `+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人)
+
+💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。
+```
 
 ## 参考
 
-- [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-calendar-update.md](./lark-calendar-update.md)
-- [SKILL.md](../SKILL.md)
+- [lark-shared](../../lark-shared/SKILL.md)
+- [lark-calendar](../SKILL.md)

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

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

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

@@ -1,10 +1,13 @@
 # calendar +update
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 更新既有日程字段，或独立增量添加/移除参会人和会议室。
 
 `+update` 支持三类互相独立的动作：更新日程字段、添加参会人/会议室、移除参会人/会议室。它们可以单独执行，也可以在同一次命令中组合执行。
 
+需要的 scopes: ["calendar:calendar.event:update"]
+
 ## 推荐命令
 
 ```bash
@@ -63,8 +66,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 命令）
 
@@ -95,6 +98,8 @@ lark-cli calendar +update \
 
 ## 参考
 
-- [lark-calendar](../SKILL.md) -- skill 入口与路由
+- [lark-calendar](../SKILL.md) -- 日历全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
 - [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/references/lark-drive-push.md

@@ -15,10 +15,9 @@
 | `summary.skipped` | 因 `--if-exists=skip` 或 `--if-exists=smart` 命中“无需传输”而跳过的文件数 |
 | `summary.failed` | 上传 / 覆盖 / 建目录 / 删除失败的条目数；**只要不为 0，命令就以非零状态退出**（结构化 `items[]` 仍在 stdout 上） |
 | `summary.deleted_remote` | 启用 `--delete-remote --yes` 时删除的云端文件数 |
-| `summary.aborted` | 命中终止性错误并停止后续批处理时为 `true` |
-| `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error` / `hint` / `phase` / `error_class` / `code` / `subtype` / `retryable`） |
+| `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error`） |
 
-`items[].action` 取值：`uploaded` / `overwritten` / `skipped` / `folder_created` / `deleted_remote` / `already_deleted` / `failed` / `delete_failed`。
+`items[].action` 取值：`uploaded` / `overwritten` / `skipped` / `folder_created` / `deleted_remote` / `failed` / `delete_failed`。
 
 > 本地目录（包括空目录）会被镜像到 Drive；新建的子目录会以 `action: "folder_created"` 出现在 `items[]` 里，但**不计入** `summary.uploaded`（该字段只数文件）。已存在的远端目录复用其 token，不会重复 `create_folder`，也不会出现在 `items[]` 里。
 
@@ -96,7 +95,6 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 - `--delete-remote`（无 `--yes`）→ Validate 直接报错：`--delete-remote requires --yes`，不会发起任何列表 / 上传 / 删除请求。
 - `--delete-remote --yes` → Validate 阶段还会**动态做一次** `space:document:delete` 的 scope 预检：缺这条 scope 时整次运行立刻失败、不发任何上传请求，避免出现"上传都成功了，但删除阶段才报 missing_scope"的半同步状态。
 - `--delete-remote --yes`（且 scope 已授权）→ 正常执行：先把本地文件 push 上去，再扫一遍远端 `type=file` 列表，把不在本地清单里的逐个删除。**任何上传 / 覆盖 / 建目录失败时，整段 `--delete-remote` 阶段会被跳过**（stderr 上有提示），命令以非零状态退出，远端不会被破坏。
-- 删除阶段如果服务端返回 `1061007 file has been delete`，说明目标远端文件在本次 DELETE 前已经不存在；这已经满足 `--delete-remote` 的目标状态，输出会记为 `action: "already_deleted"`，不计入 `summary.failed`，也不计入 `summary.deleted_remote`。
 - 远端同名冲突且使用默认 `fail`，或冲突里混有 folder / 其他非 `type=file` 对象 → 在上传阶段前失败，删除阶段不会运行。
 - 不传 `--delete-remote` → `summary.deleted_remote` 永远是 0；命令对远端"多余"文件视而不见。
 - 在线文档（docx / sheet / bitable / ...）和快捷方式即使本地完全没有同名文件，也**不会**进入删除候选，因为它们从来不进 `summary.uploaded` 的对齐域。
@@ -112,46 +110,22 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
     "uploaded": 0,
     "skipped": 0,
     "failed": 0,
-    "deleted_remote": 0,
-    "aborted": false
+    "deleted_remote": 0
   },
   "items": [
     {"rel_path": "...", "file_token": "...", "action": "folder_created"},
     {"rel_path": "...", "file_token": "...", "action": "uploaded",       "size_bytes": 0},
     {"rel_path": "...", "file_token": "...", "action": "overwritten",    "version": "...", "size_bytes": 0},
     {"rel_path": "...", "file_token": "...", "action": "skipped",        "size_bytes": 0},
-    {"rel_path": "...",                       "action": "failed",        "size_bytes": 0, "error": "...", "hint": "...", "phase": "upload", "error_class": "...", "code": 0, "subtype": "...", "retryable": false},
+    {"rel_path": "...",                       "action": "failed",        "size_bytes": 0, "error": "..."},
     {"rel_path": "...", "file_token": "...", "action": "deleted_remote"},
-    {"rel_path": "...", "file_token": "...", "action": "already_deleted"},
-    {"rel_path": "...", "file_token": "...", "action": "delete_failed",  "error": "...", "hint": "...", "phase": "delete", "error_class": "...", "code": 0, "subtype": "...", "retryable": false}
+    {"rel_path": "...", "file_token": "...", "action": "delete_failed",  "error": "..."}
   ]
 }
 ```
 
 `rel_path` 始终用 `/` 作为分隔符（跨平台一致）。
 
-## 失败处理与 agent 行为
-
-`+push` 的失败项带结构化字段，agent 必须优先读 `items[].error_class` / `phase` / `code`，不要只看自然语言 `error` 文本。`summary.aborted=true` 表示命令已经遇到终止性错误并停止后续批处理；这时**不要原样重试**，先修复根因。
-
-常见终止性错误：
-
-| `error_class` | 常见 `code` | 含义 | Agent 应对 |
-|---|---:|---|---|
-| `app_scope_missing` | `99991672` | 应用身份缺少 Drive / 文件夹相关 scope | 停止重试，引导开通错误里列出的应用身份权限，例如 `space:folder:create` 或 `drive:drive` |
-| `user_scope_missing` | `99991679` | 用户身份缺少授权 | 停止重试，走 `lark-cli auth login --scope ...` 补错误里列出的 scope |
-| `permission_denied` | `1061004` / HTTP 403 | 当前身份无权操作目标资源 | 停止重试，检查目标文件夹权限、身份类型（user / bot）和资源可见性 |
-| `invalid_api_parameters` | `1061002` | API 参数被服务端拒绝 | 停止重试，检查 `--folder-token`、覆盖模式、`file_token`、文件名和上传参数；不要对同一参数组合批量重试 |
-| `parent_node_missing` | `1061044` | 上传 / 建目录使用的父文件夹不存在或当前身份不可见 | 停止重试，检查 `--folder-token` 是否仍存在、是否有权限、父目录是否在 push 过程中被删除；不要继续上传同一目录树 |
-| `rate_limited` | `99991400` | 触发频控 | 停止当前批次，退避后再重试 |
-| `server_error` | `1061001` / `2200` | Drive 服务端异常 | 停止当前批次，稍后重试；保留 `log_id` 便于排查 |
-
-非终止但需要解释的状态：
-
-- `file_size_limit` / `1061043`：文件超过 Drive 上传限制。不要继续尝试同一文件；改拆分或换存储方式。
-- `upload_size_mismatch` / `1062009`：本地文件在上传过程中发生变化，或声明大小与实际读取大小不一致。重新扫描本地文件后再 push。
-- `remote_not_found` / `1061007`：一般表示远端文件已不存在。删除阶段的 `1061007` 会被视为 `already_deleted` 成功项；其他阶段需重新列表确认远端状态。
-
 ## 性能注意
 
 - 默认 `skip` 下，已存在的远端文件一律不碰；`overwrite` 下，重复跑会重传所有命中的同名文件；`smart` 下会按 `modified_time` 跳过已对齐的远端文件，但对“远端更旧”的文件仍会进入覆盖路径，因此它减少的是**不必要的重传**，不是把覆盖风险完全拿掉。

skills/lark-markdown/SKILL.md

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

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

@@ -32,21 +32,11 @@ lark-cli markdown +create \
   --folder-token fldcn_xxx \
   --file ./README.md
 
-# 创建到指定文件夹（可直接传 Drive folder URL）
-lark-cli markdown +create \
-  --folder-token "https://feishu.cn/drive/folder/fldcn_xxx" \
-  --file ./README.md
-
 # 创建到指定 wiki 节点
 lark-cli markdown +create \
   --wiki-token wikcn_xxx \
   --file ./README.md
 
-# 创建到指定 wiki 节点（可直接传 wiki URL）
-lark-cli markdown +create \
-  --wiki-token "https://feishu.cn/wiki/wikcn_xxx" \
-  --file ./README.md
-
 # 预览底层请求
 lark-cli markdown +create \
   --name README.md \
@@ -58,8 +48,8 @@ lark-cli markdown +create \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--folder-token` | 否 | 目标 Drive 文件夹 token 或 Drive folder URL；与 `--wiki-token` 互斥；省略时创建到根目录 |
-| `--wiki-token` | 否 | 目标 wiki 节点 token 或 wiki URL；与 `--folder-token` 互斥；传入后自动映射为 `parent_type=wiki` |
+| `--folder-token` | 否 | 目标 Drive 文件夹 token；与 `--wiki-token` 互斥；省略时创建到根目录 |
+| `--wiki-token` | 否 | 目标 wiki 节点 token；与 `--folder-token` 互斥；传入后自动映射为 `parent_type=wiki` |
 | `--name` | 条件必填 | 文件名，**必须显式带 `.md` 后缀**；使用 `--content` 时必填；使用 `--file` 时可省略，默认取本地文件名 |
 | `--content` | 条件必填 | Markdown 内容；与 `--file` 互斥；支持直接传字符串、`@file`、`-`（stdin） |
 | `--file` | 条件必填 | 本地 `.md` 文件路径；与 `--content` 互斥 |
@@ -68,8 +58,6 @@ lark-cli markdown +create \
 
 - `--content` 与 `--file` 必须二选一
 - `--folder-token` 与 `--wiki-token` 互斥
-- `--folder-token` 只能是 Drive 文件夹；不要传 wiki/doc/sheet/base/file token 或 URL
-- `--wiki-token` 只能是 Wiki 节点；如果只有 docx/sheet/base 等文档 URL，先用 `lark-cli wiki +node-get --node-token <url>` 解析出 `node_token`
 - `--name` 必须带 `.md` 后缀
 - `--file` 指向的本地文件名也必须带 `.md` 后缀
 - 传 `--wiki-token` 时，返回值中不会附带 `/file/<token>` URL，因为 wiki 承载文件没有稳定的独立 file URL
@@ -100,14 +88,6 @@ lark-cli markdown +create \
 >
 > **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
 
-## 失败处理
-
-- `not_found` / `1061044`：父目录或 wiki 节点不存在，或 token 类型放错参数。修正 `--folder-token` / `--wiki-token` 后再试，不要重复提交同一参数。
-- `quota_exceeded` / `1061101`：目标存储空间配额已满。释放空间、换父目录/节点或请管理员扩容后再试。
-- `permission_denied` / `missing_scope`：区分身份处理。`--as user` 看用户授权和目标 ACL；`--as bot` 看应用 scope 与目标目录/节点 ACL。
-- `rate_limit`：停止立即重试，使用退避。
-- `server_error` / `233523001`：可以稍后有限重试；若重复出现，保留 `log_id` / request id 给服务端排查。
-
 ## 参考
 
 - [lark-markdown](../SKILL.md) — Markdown 域总览

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

@@ -1,6 +1,7 @@
 
 # minutes +download
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 下载妙记的音视频媒体文件到本地，或获取有效期 1 天的下载链接。只读操作。
 
@@ -133,3 +134,4 @@ 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,5 +1,6 @@
 # minutes +search
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 搜索妙记列表，支持关键词、所有者、参与者以及时间范围等多条件过滤。所有者与参与者都支持传入多个 open\_id，也支持传入 `me` 表示当前用户。只读操作，不修改任何妙记数据。
 
@@ -198,5 +199,6 @@ 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,5 +1,6 @@
 # minutes +speaker-replace
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 替换妙记逐字稿中的说话人身份：把妙记逐字稿里"原说话人"对应的所有发言段，重新归属到"新说话人"。常用于解决妙记自动识别错说话人，或需要把外部/非飞书说话人改绑到正确飞书用户的场景。
 
@@ -105,3 +106,4 @@ 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,5 +1,6 @@
 # minutes +summary
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 替换妙记的 AI 总结内容。写操作，会覆盖当前总结。
 
@@ -118,3 +119,4 @@ 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,6 +2,7 @@
 
 > **路由**：本命令操作**妙记内的 AI 待办**，不是飞书任务（Task）。用户说「在妙记里新建待办」时**必须**用本命令，**禁止**走 `lark-cli task` / `tasklists list` / `task +create`。详见 [lark-minutes/SKILL.md](../SKILL.md) 第 6 节。
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 对妙记中的待办做新增 / 更新 / 删除（单条或批量）。写操作。
 
@@ -134,3 +135,4 @@ 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,5 +1,6 @@
 # minutes +update
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 修改飞书妙记的标题（topic）。
 
@@ -37,3 +38,4 @@ 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,5 +1,6 @@
 # minutes +upload
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 上传音视频文件到飞书妙记并生成妙记（Minute）。
 
@@ -30,12 +31,12 @@
      ```
    - 命令执行成功后，将返回生成的妙记链接 `minute_url`。
 
-3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，使用返回的 `minute_token` 调用 `minutes +detail`**
-   - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，使用上一步返回的 `minute_token` 继续调用：
+3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，继续提取 `minute_token` 调用 `minutes +detail`**
+   - 从返回的 `minute_url` 中提取路径最后一段，得到 `minute_token`。
+   - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，继续调用：
      ```bash
-     lark-cli minutes +detail --minute-tokens <minute_token> --wait-ready --summary --todo --chapter --keyword --transcript
+     lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --keyword --transcript
      ```
-   - `--wait-ready` 参数表示等待妙记生成完毕后再获取产物，上传后立即读取详情时必须加上此参数。
    - `minutes +detail --minute-tokens` 会返回妙记产物（总结、待办、章节、关键词、逐字稿）；必要时还会把逐字稿落地到本地文件。
 
 > **异步生成提示**：API 会立即返回 `minute_url`，但妙记可能仍在异步生成中，您可以直接通过该妙记链接查看当前的处理状态和转写结果。
@@ -46,8 +47,8 @@
 # 通过已上传到云空间（云盘/云存储）的 file_token 生成妙记
 lark-cli minutes +upload --file-token boxcnxxxxxxxxxxxxxxxx
 
-# 上传后立即获取妙记产物，需加 --wait-ready 等待生成完毕（--summary --todo --chapter --keyword --transcript 按需传入）
-lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --wait-ready --summary
+# 通过 minute_token 继续获取妙记产物（--summary --todo --chapter --keyword --transcript 按需传入）
+lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary
 ```
 
 ## 参数
@@ -80,7 +81,7 @@ lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --wait-ready --sum
 1. 使用 `lark-cli drive +upload --file <path>` 上传本地音视频文件到云空间（云盘/云存储）
 2. 从返回结果中取出 `file_token`
 3. 调用 `lark-cli minutes +upload --file-token <file_token>` 生成妙记
-4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，使用返回的 `minute_token`，继续调用 `lark-cli minutes +detail --minute-tokens <minute_token> --wait-ready`
+4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，再从 `minute_url` 提取 `minute_token`，继续调用 `lark-cli minutes +detail --minute-tokens <minute_token>`
 
 > **边界说明**：`minutes +upload` 本身只负责把文件转成妙记并返回 `minute_url`。纪要内容、逐字稿、文字稿、撰写文字、总结、待办、章节属于后续产物获取，应由 [minutes +detail](lark-minutes-detail.md) 承接。
 
@@ -88,17 +89,16 @@ lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --wait-ready --sum
 
 ```json
 {
-  "minute_url": "http(s)://<host>/minutes/<minute-token>",
-  "minute_token": "<minute-token>"
+  "minute_url": "http(s)://<host>/minutes/<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-slides/references/lark-slides-whiteboard.md

@@ -2,6 +2,8 @@
 
 `<whiteboard>` 放在 `<data>` 内，内部可放 **SVG** 或 **Mermaid**，用于绘制流程图、时序图、架构图、散点图、漏斗图、自定义图标、装饰图案等 `<chart>` 和 `<shape>` 难以覆盖的视觉内容。
 
+普通柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图和组合图应优先使用原生 `<chart>`。除非用户明确要求像素级自定义，或图表类型确实不受 `<chart>` 支持，否则不要用 `<whiteboard>` + SVG / Mermaid 重画这些标准图表。
+
 > 前置条件：使用本文档前先阅读 [lark-slides SKILL.md](../SKILL.md)。
 
 ---
@@ -12,13 +14,13 @@
 
 | 场景 | 推荐元素 |
 |------|---------|
-| 有结构化数据序列的柱/条/折线/面积/雷达/饼/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
-| 散点图、漏斗图（`<chart>` 不支持） | `<whiteboard>` SVG |
+| 有结构化数据序列的柱/条/折线/面积/雷达/饼/环/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
+| 散点图、漏斗图（`<chart>` 不支持）或其他非原生数据视觉 | `<whiteboard>` SVG |
 | 流程图、时序图、架构图、类图、ER 图等拓扑图 | `<whiteboard>` Mermaid 或 SVG |
 | 自定义图标、徽标、示意性图形（需要 path/polygon 精确控制） | `<whiteboard>` SVG |
 | 进度条、波浪背景、装饰图案、像素级自定义可视化 | `<whiteboard>` SVG |
 
-> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG 手绘——原生渲染更省力且质量更高。
+> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG / Mermaid 手绘——原生渲染更省力、结构更稳定，也更容易被回读和后续编辑。
 
 ---
 
@@ -39,9 +41,13 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 
 ## SVG 还是 Mermaid？
 
-选择分两步：**先看图表类型，再看当前模型身份**。
+选择分三步：**先排除原生 `<chart>`，再判断 whiteboard 类型，最后看当前模型身份**。
 
-### 第一步：图表类型优先判断
+### 第一步：先确认是否应该使用 `<chart>`
+
+如果内容是柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图或组合图，返回使用原生 `<chart>`，不要继续套用本文档的 SVG / Mermaid 路径。
+
+### 第二步：whiteboard 类型优先判断
 
 以下类型**推荐 Mermaid**，自动布局、代码简洁；如需精确匹配品牌配色或自定义节点样式，可改用 SVG：
 
@@ -50,20 +56,19 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 | 流程图、决策树、架构图 | `flowchart TD` / `flowchart LR` |
 | 时序图 | `sequenceDiagram` |
 | 类图 | `classDiagram` |
-| 饼图 | `pie` |
 | 甘特图 | `gantt` |
 | 状态图 | `stateDiagram-v2` |
 | 思维导图 | `mindmap` |
 | ER 图 | `erDiagram` |
 
-### 第二步：数据图表与装饰元素按模型身份选路径
+### 第三步：非原生图表与装饰元素按模型身份选路径
 
 上表以外的场景（散点图、漏斗图、进度条、时间线、波浪背景、星点纹理等）需要精确控制坐标和配色，SVG 表达力更强，但各模型生成 SVG 的能力有差异：
 
 | 模型身份 | 路径 |
 |----------|------|
 | Claude / Gemini / GPT / GLM | **SVG** — 精确控制坐标、颜色、透明度 |
-| Doubao / Seed / Other | **Mermaid** — 用 `pie`、`gantt` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
+| Doubao / Seed / Other | **Mermaid** — 用 `gantt`、`flowchart` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
 
 > **先自报身份再选路径**：在决定使用 SVG 之前，确认当前模型属于哪一类。不要跳过这一步。
 
@@ -73,13 +78,13 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 
 ### ⚠️ 设计品质要求
 
-在 slide 里嵌入 `<whiteboard>` 的目的是**提升视觉质量**，不是把数字堆进去。
+在 slide 里嵌入 `<whiteboard>` 的目的是**表达原生 `<chart>` 或基础 `<shape>` 难以覆盖的视觉关系**，不是把标准数据图表手绘一遍。
 
 - **不要只用矩形加文字应付**：通篇纯白底色 + 方块 + 黑字等于白做，这是不及格输出
-- **数据图表必须有坐标系**：坐标轴、网格线、数值标注缺一不可，不要只画柱子或点
+- **非原生数据视觉必须有坐标系**：散点、漏斗等仍要有必要的坐标轴、刻度、数值标注或分段说明，不要只画点或色块
 - **字号必须有层级**：标题 ≠ 标签 ≠ 数值，混用同一字号会消灭视觉焦点
 - **配色要与 slide 主题呼应**：深色 slide 背景下图表用透明底或深色卡片；浅色背景下避免再加纯白底块
-- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、折线面积、点装饰等细节拉开与默认模板的差距
+- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、清晰分组、节点状态等细节拉开与默认模板的差距
 - **写 SVG 前先判断背景亮度**：背景亮度 < 30% 时，装饰元素"对比不足"比"过强"危害更大，宁重勿轻；
 - **装饰层次用亮度跳跃，不用线性叠透明度**：`α=0.04→0.08→0.12` 的等差递增在深色底上几乎看不出差异（相邻层亮度差 ≈20）；正确做法是非线性跳跃如 `0.10→0.40→0.70→1.0`，相邻层亮度差 ≥60。
 
@@ -106,11 +111,11 @@ whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内
 
 | 元素 | 说明 | 典型用途 |
 |------|------|---------|
-| `<rect>` | 矩形，支持 `rx` 圆角 | 柱图、卡片、进度条 |
+| `<rect>` | 矩形，支持 `rx` 圆角 | 卡片、进度条、分段色块 |
 | `<circle>` | 圆 | 节点、装饰点、环形图 |
 | `<ellipse>` | 椭圆 | 自定义轮廓图形 |
-| `<line>` | 直线 | 坐标轴、分隔线 |
-| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、折线、弧形 |
+| `<line>` | 直线 | 轴线、分隔线、连接线 |
+| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、曲线、弧形 |
 | `<text>` | 文本，支持中文 | 标签、数值 |
 | `<polygon>` | 多边形 | 箭头、星形、面积填充 |
 | `<g>` | 分组 | 批量变换、语义分组 |
@@ -123,27 +128,25 @@ whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内
 ---
 ### 元素计算
 
-SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围不限于数据图表——装饰性点阵、等间距圆、重复图案同样适用。
+SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围包括散点、漏斗、装饰性点阵、等间距圆、重复图案等；普通柱状图、折线图、饼图仍应回到原生 `<chart>`。
 
 > **主动去算**：写 SVG 之前先运行脚本，把输出当注释贴在 `<svg>` 开头，再照着填坐标。估值几乎每次都需要反复调整，跳过这步反而更慢。
 
-**数据图表（柱状图范式）**
+**散点图 / 装饰性点阵范式**
 
 ```python
 W, H = 360, 260
 origin_x, origin_y = 50, 216  # 左下角，SVG Y 轴向下
 cw, ch = 290, 184
 
-data, y_max = [120, 160, 90], 200
-bar_w = int(cw / len(data) * 0.62)
-for i, v in enumerate(data):
-    cx = round(origin_x + (i + 0.5) * cw / len(data))
-    y  = round(origin_y - v / y_max * ch)
-    print(f"bar-{i}: x={cx - bar_w//2} y={y} w={bar_w} h={round(origin_y - y)}")
+points = [(12, 40), (28, 80), (45, 65)]
+x_min, x_max, y_min, y_max = 0, 50, 0, 100
+for i, (xv, yv) in enumerate(points):
+    x = round(origin_x + (xv - x_min) / (x_max - x_min) * cw)
+    y = round(origin_y - (yv - y_min) / (y_max - y_min) * ch)
+    print(f"point-{i}: cx={x} cy={y}")
 ```
 
-折线图：`x = origin_x + i/(n-1)*cw`，`y = origin_y - (v-y_min)/(y_max-y_min)*ch`。
-
 **装饰性元素（等间距范式）**
 
 ```python
@@ -160,9 +163,9 @@ for i in range(n):
 ```python
 # 每个元素登记 (x, y, w, h)，含 stroke 外扩
 elements = [
-    (10, 20, 80, 160),   # bar-0
-    (107, 10, 80, 170),  # bar-1
-    (204, 40, 80, 140),  # bar-2
+    (10, 20, 80, 160),   # item-0
+    (107, 10, 80, 170),  # item-1
+    (204, 40, 80, 140),  # item-2
     (0, 0, 300, 1),      # x-axis
 ]
 
@@ -261,7 +264,6 @@ print(f"whiteboard width={wb_w} height={wb_h}")
 | 流程图 | `flowchart TD` / `flowchart LR` | 业务流程、决策树、工作流 |
 | 时序图 | `sequenceDiagram` | 系统交互、API 调用链 |
 | 甘特图 | `gantt` | 项目计划、里程碑 |
-| 饼图 | `pie` | 占比数据 |
 | 类图 | `classDiagram` | 对象关系、架构设计 |
 | ER 图 | `erDiagram` | 数据库结构 |
 | 状态图 | `stateDiagram-v2` | 状态机、生命周期 |
@@ -279,7 +281,6 @@ Mermaid 图表会自动撑满 whiteboard 区域。建议：
 |---------|-----------|------------|
 | 流程图（5-8 节点） | 720-816 | 300-400 |
 | 时序图（3-5 参与者） | 720-816 | 320-420 |
-| 饼图 | 500-600 | 300-360 |
 | 甘特图 | 816 | 280-360 |
 | 思维导图 | 816 | 380-480 |
 
@@ -307,7 +308,7 @@ Mermaid 语法包含 `[`、`>`、`-->`，不用 CDATA 直接写会破坏 XML 解
 - [ ] 文字 `y` 坐标为 baseline 位置，最小值 ≥ font-size（避免被裁切）
 
 **SVG 模式——视觉品质检查：**
-- [ ] 坐标轴、网格线、数值标注齐全，没有"裸柱子"或"裸折线"
+- [ ] 非原生数据视觉有必要的坐标轴、网格线、数值标注或分段说明，没有"裸点"或无解释色块
 - [ ] 字号有层级：标题 > 数值 > 轴标签，非全部相同
 - [ ] 单一数据系列用同一颜色，多系列用不同颜色且对比充足
 - [ ] 轴标签与图表元素互不遮挡，留有足够空间

skills/lark-slides/references/slides_xml_schema_definition.xml

@@ -3018,7 +3018,7 @@
 
           子元素(mermaid 与 svg 二选一):
           - mermaid: Mermaid 源码文本, 可使用 CDATA 包裹
-            适用场景: 流程图、时序图、思维导图、类图、甘特图、饼图等结构化图表
+            适用场景: 流程图、时序图、思维导图、类图、甘特图、ER 图、用户旅程等结构图
             特点: 用简短的文本声明描述图表逻辑, 由渲染引擎自动布局, 无需手动计算坐标
             示例: <mermaid><![CDATA[flowchart TD\n  A[开始] --> B[结束]]]></mermaid>
           - svg: SVG 内容

skills/lark-slides/references/xml-format-guide.md

@@ -263,7 +263,56 @@
 - `<chartLegend>`
 - `<chartTooltip>`
 
-如果要写图表 XML，建议直接以 XSD 为准，不要自行发明更简化的 chart DSL。
+完整图表类型覆盖示例见 [slides_chart_demo.xml](slides_chart_demo.xml)，其中包含柱状、条形、折线、面积、饼 / 环、雷达等原生 `<chart>` 示例，以及散点、气泡、漏斗、帕累托、瀑布等 `<whiteboard>` SVG 图表示例。
+
+组合图示例（来自 [slides_chart_demo.xml](slides_chart_demo.xml)）：
+
+```xml
+<chart width="556" height="350" topLeftX="42" topLeftY="132">
+  <chartPlotArea>
+    <chartPlot type="combo">
+      <chartExtra/>
+      <chartSeriesList>
+        <chartSeries index="1" comboType="column"/>
+        <chartSeries index="2" comboType="line" yAxisPosition="right">
+          <chartTooltip format="0%"/>
+        </chartSeries>
+      </chartSeriesList>
+    </chartPlot>
+    <chartAxes>
+      <chartAxis type="x">
+        <chartLabel fontSize="10"/>
+      </chartAxis>
+      <chartAxis type="y" position="left">
+        <chartGridLine color="rgb(226, 232, 240)"/>
+        <chartLabel fontSize="10"/>
+      </chartAxis>
+      <chartAxis type="y" position="right">
+        <chartLabel fontSize="10" format="0%"/>
+      </chartAxis>
+    </chartAxes>
+  </chartPlotArea>
+  <chartLegend position="bottom" fontSize="11"/>
+  <chartData>
+    <dim1>
+      <chartField name="季度">24Q1,24Q2,24Q3,24Q4,25Q1,25Q2,25Q3,25Q4</chartField>
+    </dim1>
+    <dim2>
+      <chartField name="营收">180,195,210,245,220,238,258,296</chartField>
+      <chartField name="增速">0.08,0.12,0.15,0.18,0.22,0.22,0.23,0.21</chartField>
+    </dim2>
+  </chartData>
+  <chartTitle fontSize="12" color="rgba(15, 30, 58, 1)" bold="true">营收（亿美元, 左轴） · 同比增速（%, 右轴）</chartTitle>
+  <chartStyle>
+    <chartBackground color="rgba(0, 0, 0, 0)"/>
+    <chartBorder color="rgb(222, 224, 227)" width="0"/>
+    <chartColorTheme>
+      <color value="rgb(28, 71, 120)"/>
+      <color value="rgb(240, 129, 54)"/>
+    </chartColorTheme>
+  </chartStyle>
+</chart>
+```
 
 ## 样式元素
 

skills/lark-slides/references/xml-schema-quick-ref.md

@@ -147,7 +147,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ### whiteboard
 
 ```xml
-<!-- SVG 模式：数据图表、装饰元素 -->
+<!-- SVG 模式：<chart> 不支持的图表或自定义视觉、装饰元素 -->
 <whiteboard topLeftX="580" topLeftY="120" width="340" height="280">
   <svg xmlns="http://www.w3.org/2000/svg">
     <rect x="60" y="80" width="40" height="140" rx="3" fill="rgba(59,130,246,0.85)"/>

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

@@ -1,6 +1,7 @@
 
 # vc +recording
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 通过 meeting_id 或 calendar_event_id 查询对应的 minute_token。这是 VC 域和 Minutes 域之间的桥梁命令。只读操作。
 
@@ -150,3 +151,4 @@ 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) — 认证和全局参数

skills/lark-wiki/SKILL.md

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

skills/lark-wiki/references/lark-wiki-node-list.md

@@ -11,9 +11,6 @@ lark-cli wiki +node-list --space-id <SPACE_ID>
 # Drill into a sub-directory (still single page by default)
 lark-cli wiki +node-list --space-id <SPACE_ID> --parent-node-token <NODE_TOKEN>
 
-# Drill with a wiki URL (CLI normalizes /wiki/<token> to node_token)
-lark-cli wiki +node-list --space-id <SPACE_ID> --parent-node-token "https://feishu.cn/wiki/wikcn_xxx"
-
 # Personal document library (user identity only)
 lark-cli wiki +node-list --space-id my_library --as user
 
@@ -34,8 +31,8 @@ lark-cli wiki +node-list --space-id <SPACE_ID> --format pretty
 
 | Flag | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
-| `--space-id` | string | **Yes** | — | Numeric wiki space ID. Use `my_library` for personal document library (user only) |
-| `--parent-node-token` | string | No | — | Parent wiki node token, or a `/wiki/<token>` URL; omit to list the space root |
+| `--space-id` | string | **Yes** | — | Wiki space ID. Use `my_library` for personal document library (user only) |
+| `--parent-node-token` | string | No | — | Parent node token; omit to list the space root |
 | `--page-size` | int | No | 50 | Page size, 1-50 |
 | `--page-token` | string | No | — | Page cursor; implies single-page fetch (no auto-pagination) |
 | `--page-all` | bool | No | `false` | Automatically paginate through all pages (capped by `--page-limit`) |
@@ -85,10 +82,6 @@ lark-cli wiki +node-list --space-id 6946843325487912356 --parent-node-token wikc
 ## Notes
 
 - `--space-id my_library` is a per-user alias and only valid with `--as user`. The shortcut will refuse `--as bot` with `my_library` upfront.
-- `--space-id` is a numeric wiki `space_id`. Do not pass a wiki URL, wiki node token, document token, or title. Use `lark-cli wiki +space-list --as user` to discover it.
-- `--parent-node-token` must resolve to a wiki node token. If you have a docx/sheet/base/file URL, first run `lark-cli wiki +node-get --node-token <url>` and use the returned `node_token`.
-- Treat `invalid_parameters` (`space_id is not int`, `invalid page_token`), `not_found` (`node not found by parent node token`), and `permission_denied` as terminal for the current arguments. Fix the argument or permission before retrying.
-- For `rate_limit`, stop immediate retries and retry later with exponential backoff or a smaller `--page-limit`.
 
 ## Required Scope