Cover markdown and wiki validation branches

* fix(schema): fall back to runtime catalog when no embedded metadata

Binaries built from the bare Go module (plugin builds) embed only the
empty meta_data_default.json stub because meta_data.json is gitignored
and fetched at build time. The schema command, its completion, and the
affordance command-form resolver read the embedded-only catalog, so
every schema lookup failed with "Unknown service" even though the
runtime registry had already sync-fetched full metadata.

Add registry.SchemaCatalog(): embedded when compiled in (official
builds unchanged, still deterministic), otherwise the merged runtime
catalog seeded from cache or remote fetch. When neither source has
data (offline plugin build with a cold cache), schema now returns a
failed_precondition error with an actionable hint instead of
"Unknown service" with an empty candidate list.

* fix(registry): gate cached meta overlay on version newer than embedded

The cached remote meta was overlaid onto the embedded meta_data.json
unconditionally, so after a CLI upgrade an equal- or older-version
cache kept shadowing the freshly shipped embedded definitions until a
later refresh happened to rewrite it.

Only overlay when the cache version is strictly newer than the
embedded baseline. The bare-module stub baseline is "0.0.0", so plugin
builds without compiled metadata still take any real cached version
(TestOverlayGate_StubEmbedded_OverlaysRealCache) and the schema
runtime fallback keeps working offline from a warm cache.

Ports #1376 onto the typed meta model.

---------

Co-authored-by: liangshuo-1 <266696938+liangshuo-1@users.noreply.github.com>

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.65] - 2026-07-03
+
+### Features
+
+- **doc**: Add `+history-list`, `+history-revert`, and `+history-revert-status` shortcuts for document version history (#1612)
+
+### Bug Fixes
+
+- **minutes**: `+speaker-replace` no longer refetches the speaker list — `--from-speaker-id` is passed through as-is (#1731)
+
+### Documentation
+
+- **drive**: Document 30-char query limit for `+search` (#1560)
+- **doc**: Add mindnote guidance to lark-doc skill (#1581)
+- **doc**: Sync lark-doc skill content from online-doc (#1701)
+
 ## [v1.0.64] - 2026-07-02
 
 ### Features
@@ -1355,6 +1371,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[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
 [v1.0.61]: https://github.com/larksuite/cli/releases/tag/v1.0.61

README.md

@@ -233,6 +233,24 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # Comma-separated values
 ```
 
+### JSON Output Contract
+
+With `--format json` (the default), success and error envelopes are distinct.
+
+Success goes to **stdout**, exit code `0`:
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+Errors go to **stderr**, non-zero exit code:
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+To check whether a command succeeded, test `ok == true` (or the exit code) — **not** `code == 0`. Unlike raw OpenAPI responses (`{"code": 0, "msg": "ok", ...}`), the success envelope carries no `code` or `msg` field; `code` appears only inside `error` as the upstream OpenAPI code. See [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md) for the full error taxonomy.
+
 ### Pagination
 
 ```bash

README.zh.md

@@ -234,6 +234,24 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # 逗号分隔值
 ```
 
+### JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同。
+
+成功信封写入 **stdout**，退出码 0：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**，退出码非 0：
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+判断命令是否成功，请检查 `ok == true`（或进程退出码），**不要用 `code == 0`**。与原始 OpenAPI 响应（`{"code": 0, "msg": "ok", ...}`）不同，成功信封没有 `code` 和 `msg` 字段；`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。完整错误分类见 [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md)。
+
 ### 分页
 
 ```bash

cmd/root_integration_test.go

@@ -103,6 +103,10 @@ func parseTypedEnvelope(t *testing.T, stderr *bytes.Buffer) typedErrorEnvelope {
 }
 
 func buildStrictModeIntegrationRootCmd(t *testing.T, f *cmdutil.Factory) *cobra.Command {
+	return buildStrictModeIntegrationRootCmdWithSetup(t, f, nil)
+}
+
+func buildStrictModeIntegrationRootCmdWithSetup(t *testing.T, f *cmdutil.Factory, setup func(*cobra.Command)) *cobra.Command {
 	t.Helper()
 	rootCmd := &cobra.Command{Use: "lark-cli"}
 	rootCmd.SilenceErrors = true
@@ -115,6 +119,9 @@ func buildStrictModeIntegrationRootCmd(t *testing.T, f *cmdutil.Factory) *cobra.
 	rootCmd.AddCommand(api.NewCmdApi(f, nil))
 	service.RegisterServiceCommands(rootCmd, f)
 	shortcuts.RegisterShortcuts(rootCmd, f)
+	if setup != nil {
+		setup(rootCmd)
+	}
 	if mode := f.ResolveStrictMode(context.Background()); mode.IsActive() {
 		pruneForStrictMode(rootCmd, mode)
 	}
@@ -355,10 +362,16 @@ func TestIntegration_StrictModeBot_ProfileOverride_ServiceExplicitUserReturnsEnv
 
 func TestIntegration_StrictModeUser_ProfileOverride_ServiceBotOnlyMethodReturnsEnvelope(t *testing.T) {
 	f, stdout, stderr := newStrictModeDefaultFactory(t, "target", core.StrictModeUser)
-	rootCmd := buildStrictModeIntegrationRootCmd(t, f)
+	rootCmd := buildStrictModeIntegrationRootCmdWithSetup(t, f, func(rootCmd *cobra.Command) {
+		fixture := &cobra.Command{Use: "strict-fixture"}
+		botOnly := &cobra.Command{Use: "bot-only", RunE: func(*cobra.Command, []string) error { return nil }}
+		cmdutil.SetSupportedIdentities(botOnly, []string{"bot"})
+		fixture.AddCommand(botOnly)
+		rootCmd.AddCommand(fixture)
+	})
 
 	code := executeRootIntegration(t, f, rootCmd, []string{
-		"im", "images", "create", "--data", `{"image_type":"message","image":"x"}`, "--dry-run",
+		"strict-fixture", "bot-only",
 	})
 
 	if code != output.ExitValidation {

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 embedded catalog's Complete.
-// It uses the embedded source so completion candidates match what `schema`
-// execution can resolve (both overlay-free).
+// 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.
 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.EmbeddedCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
+		completions, noSpace := registry.SchemaCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
 		directive := cobra.ShellCompDirectiveNoFileComp
 		if noSpace {
 			directive |= cobra.ShellCompDirectiveNoSpace
@@ -86,13 +86,19 @@ func schemaRun(opts *SchemaOptions) error {
 	return runSchema(out, apicatalog.ParsePath(opts.Args), mode)
 }
 
-// runSchema resolves the path through the embedded catalog and renders the
+// runSchema resolves the path through the schema 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.EmbeddedCatalog()
+	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")
+	}
 	target, err := catalog.Resolve(parts)
 	if err != nil {
 		return resolveError(err)

cmd/update/update.go

@@ -102,7 +102,8 @@ 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>
+  - npm install:  runs npm install -g @larksuite/cli@<version>
+  - pnpm install: runs pnpm add -g @larksuite/cli@<version>
   - manual/other: shows GitHub Releases download URL
 
 Use --json for structured output (for AI agents and scripts).
@@ -164,7 +165,7 @@ func updateRun(opts *UpdateOptions) error {
 	if !detect.CanAutoUpdate() {
 		return doManualUpdate(opts, io, cur, latest, detect, updater)
 	}
-	return doNpmUpdate(opts, io, cur, latest, updater)
+	return doAutoUpdate(opts, io, cur, latest, detect, updater)
 }
 
 // --- Output helpers ---
@@ -226,12 +227,23 @@ 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())
-	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)
+	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)
+	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
-func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, updater *selfupdate.Updater) error {
+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
+	}
+
 	restore, err := updater.PrepareSelfReplace()
 	if err != nil {
 		return reportError(opts, io, "update_error",
@@ -239,19 +251,19 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 	}
 
 	if !opts.JSON {
-		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via npm ...\n", cur, symArrow(), latest)
+		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via %s ...\n", cur, symArrow(), latest, pm)
 	}
 
-	npmResult := updater.RunNpmInstall(latest)
+	npmResult := install(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("npm install failed: %s", npmResult.Err),
+					"type": "update_error", "message": fmt.Sprintf("%s install failed: %s", pm, npmResult.Err),
 					"detail": selfupdate.Truncate(combined, maxNpmOutput),
-					"hint":   permissionHint(combined),
+					"hint":   permissionHint(combined, pm),
 				},
 			})
 			return output.ErrBare(output.ExitAPI)
@@ -263,7 +275,7 @@ func doNpmUpdate(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); hint != "" {
+		if hint := permissionHint(combined, pm); hint != "" {
 			fmt.Fprintf(io.ErrOut, "  %s\n", hint)
 		}
 		return output.ErrBare(output.ExitAPI)
@@ -274,7 +286,7 @@ func doNpmUpdate(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)
+		hint := verificationFailureHint(updater, latest, pm)
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok":    false,
@@ -304,23 +316,33 @@ func doNpmUpdate(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 {
-		fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
+		skillsPM := "npx"
+		if detect.Method == selfupdate.InstallPnpm && detect.PnpmAvailable {
+			skillsPM = "pnpm dlx"
+		}
+		fmt.Fprintf(io.ErrOut, "\nUpdating skills via %s ...\n", skillsPM)
 	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
-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"
+func permissionHint(pmOutput, pm string) string {
+	if !strings.Contains(pmOutput, "EACCES") || isWindows() {
+		return ""
 	}
-	return ""
+	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"
 }
 
-func verificationFailureHint(updater *selfupdate.Updater, latest string) string {
+func verificationFailureHint(updater *selfupdate.Updater, latest, pm 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,6 +57,27 @@ 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{}
@@ -81,6 +102,110 @@ 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
@@ -266,6 +391,9 @@ 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) {
@@ -739,9 +867,9 @@ func TestPermissionHint(t *testing.T) {
 	origOS := currentOS
 	defer func() { currentOS = origOS }()
 
-	// Linux: EACCES should produce a hint with npm prefix guidance.
+	// Linux + npm: EACCES should produce a hint with npm prefix guidance.
 	currentOS = "linux"
-	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'")
+	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'", "npm")
 	if !strings.Contains(hint, "npm global prefix") {
 		t.Errorf("expected npm prefix hint on linux, got: %s", hint)
 	}
@@ -749,16 +877,25 @@ 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")
+	hint = permissionHint("EACCES: permission denied", "npm")
 	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"); got != "" {
+	if got := permissionHint("some other error", "npm"); got != "" {
 		t.Errorf("expected empty hint for non-EACCES, got: %s", got)
 	}
 }

errs/ERROR_CONTRACT.md

@@ -72,6 +72,28 @@ other category. `error.type` is `"policy"`, `error.subtype` is one of
 `challenge_required` / `access_denied`, and process exit is `6` via
 `CategoryPolicy`.
 
+### Success envelope (stdout)
+
+For contrast: success responses render to **stdout** as an
+`output.Envelope` (`internal/output/envelope.go`), exit code `0`:
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": { "guid": "e297d3d0-..." },
+  "meta": { "count": 1 }
+}
+```
+
+Consumers must branch on `ok` (or the process exit code). The success
+envelope has **no top-level `code` or `msg` field** — `code` exists only
+inside `error`, where it is the upstream numeric code (invariant 4).
+Wrappers that follow the raw OpenAPI convention and test `code == 0`
+will misclassify every successful call as a failure, which is
+especially dangerous around write commands (e.g. retrying a create that
+already succeeded).
+
 ## Categories
 
 | Category | When | Exit | Typed struct |

internal/affordance/affordance.go

@@ -77,14 +77,10 @@ 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{}
-	for _, svc := range registry.EmbeddedServicesTyped() {
-		if svc.Name != service {
-			continue
-		}
+	if svc, ok := registry.SchemaCatalog().Service(service); ok {
 		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,12 +6,10 @@ 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"
@@ -40,8 +38,6 @@ const (
 	BuildKindUnknown  = "unknown"
 
 	officialModulePath = "github.com/larksuite/cli"
-
-	agentTraceMaxLen = 1024
 )
 
 // UserAgentValue returns the User-Agent value: "lark-cli/{version}".
@@ -49,25 +45,6 @@ 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)
@@ -75,7 +52,7 @@ func BaseSecurityHeaders() http.Header {
 	h.Set(HeaderVersion, build.Version)
 	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
-	if v := AgentTraceValue(); v != "" {
+	if v := envvars.AgentTrace(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}
 	return h

internal/cmdutil/secheader_test.go

@@ -6,7 +6,6 @@ package cmdutil
 import (
 	"context"
 	"net/http"
-	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/extension/credential"
@@ -264,88 +263,9 @@ func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// AgentTraceValue / HeaderAgentTrace
+// HeaderAgentTrace injection (via BaseSecurityHeaders)
 // ---------------------------------------------------------------------------
 
-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,6 +19,7 @@ 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

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

@@ -0,0 +1,131 @@
+// 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,20 +10,22 @@ 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)
-	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
+	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
 }
 
 func init() { mergeCodeMeta(driveCodeMeta, "drive") }

internal/errclass/codemeta_test.go

@@ -114,8 +114,35 @@ 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

@@ -0,0 +1,17 @@
+// 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,8 +6,7 @@ package registry
 import "github.com/larksuite/cli/internal/apicatalog"
 
 // EmbeddedCatalog returns a navigation catalog over the embedded (overlay-free)
-// metadata — deterministic across machines, for `lark-cli schema`, golden tests
-// and schema lint.
+// metadata — deterministic across machines, for golden tests and schema lint.
 func EmbeddedCatalog() apicatalog.Catalog {
 	return apicatalog.New(apicatalog.SourceEmbedded, EmbeddedServicesTyped())
 }
@@ -18,3 +17,14 @@ 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

@@ -0,0 +1,67 @@
+// 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,6 +15,7 @@ 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
@@ -85,7 +86,9 @@ func InitWithBrand(brand core.LarkBrand) {
 			brandChanged := metaErr == nil && cm.Brand != "" && cm.Brand != string(brand)
 
 			if !brandChanged {
-				if cached, err := loadCachedMerged(); err == nil {
+				// 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) {
 					overlayMergedServices(cached)
 				}
 			}

internal/registry/loader_test.go

@@ -0,0 +1,102 @@
+// 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,9 +72,11 @@ 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: "test-1.0",
+		Version: "1.0.0",
 		Services: []meta.Service{
 			{
 				Name:        name,
@@ -160,7 +162,7 @@ func TestRemoteOff_SkipsRemoteLogic(t *testing.T) {
 }
 
 func TestCacheHit_WithinTTL(t *testing.T) {
-	resetInit()
+	swapEmbeddedMeta(t, nil) // overlay must depend only on the cache version, not the ambient embedded meta
 	tmp := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
@@ -197,7 +199,7 @@ func TestCacheHit_WithinTTL(t *testing.T) {
 }
 
 func TestNetworkError_SilentDegradation(t *testing.T) {
-	resetInit()
+	swapEmbeddedMeta(t, nil) // overlay must depend only on the cache version, not the ambient embedded meta
 	tmp := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
@@ -371,8 +373,8 @@ func TestFetchRemoteMerged_200(t *testing.T) {
 	if data == nil {
 		t.Fatal("expected non-nil data")
 	}
-	if reg.Version != "test-1.0" {
-		t.Errorf("expected version test-1.0, got %s", reg.Version)
+	if reg.Version != "1.0.0" {
+		t.Errorf("expected version 1.0.0, got %s", reg.Version)
 	}
 }
 

internal/selfupdate/updater.go

@@ -32,6 +32,7 @@ type InstallMethod int
 
 const (
 	InstallNpm InstallMethod = iota
+	InstallPnpm
 	InstallManual
 )
 
@@ -53,22 +54,32 @@ var (
 
 // DetectResult holds installation detection results.
 type DetectResult struct {
-	Method       InstallMethod
-	ResolvedPath string
-	NpmAvailable bool
+	Method        InstallMethod
+	ResolvedPath  string
+	NpmAvailable  bool
+	PnpmAvailable bool
 }
 
 // CanAutoUpdate returns true if the CLI can update itself automatically.
 func (d DetectResult) CanAutoUpdate() bool {
-	return d.Method == InstallNpm && d.NpmAvailable
+	switch d.Method {
+	case InstallNpm:
+		return d.NpmAvailable
+	case InstallPnpm:
+		return d.PnpmAvailable
+	}
+	return false
 }
 
 // ManualReason returns a human-readable explanation of why auto-update is unavailable.
 func (d DetectResult) ManualReason() string {
-	if d.Method == InstallNpm && !d.NpmAvailable {
+	switch {
+	case 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"
+	return "not installed via npm or pnpm"
 }
 
 // NpmResult holds the result of an npm install or skills update execution.
@@ -92,6 +103,7 @@ 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
@@ -101,17 +113,38 @@ 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
-// npm is available for auto-update.
+// DetectInstallMethod determines how the CLI was installed and whether the
+// owning package manager 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}
@@ -120,24 +153,54 @@ 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") {
-		method = InstallNpm
-	}
-
-	npmAvailable := false
-	if method == InstallNpm {
-		if _, err := exec.LookPath("npm"); err == nil {
-			npmAvailable = true
+		if containsPnpmMarker(resolved) {
+			method = InstallPnpm
+		} else {
+			method = InstallNpm
 		}
 	}
-
-	return DetectResult{
-		Method:       method,
-		ResolvedPath: resolved,
-		NpmAvailable: npmAvailable,
+	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
+		}
+	}
+	return false
 }
 
 // RunNpmInstall executes npm install -g @larksuite/cli@<version>.
@@ -163,6 +226,29 @@ 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()
@@ -261,19 +347,40 @@ 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{}
-	npxPath, err := exec.LookPath("npx")
+	det := u.DetectInstallMethod()
+	launcher, cmdArgs := skillsInvocation(det.Method, det.PnpmAvailable, args)
+	binPath, err := exec.LookPath(launcher)
 	if err != nil {
-		r.Err = fmt.Errorf("npx not found in PATH: %w", err)
+		r.Err = fmt.Errorf("%s not found in PATH: %w", launcher, err)
 		return r
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), skillsUpdateTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, npxPath, args...)
+	cmd := exec.CommandContext(ctx, binPath, cmdArgs...)
 	cmd.Stdout = &r.Stdout
 	cmd.Stderr = &r.Stderr
 	r.Err = cmd.Run()

internal/selfupdate/updater_test.go

@@ -371,3 +371,147 @@ 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.64",
+  "version": "1.0.65",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"

shortcuts/calendar/calendar_create.go

@@ -67,6 +67,26 @@ func parseAttendees(attendeesStr string, currentUserId string) ([]map[string]str
 	return attendees, nil
 }
 
+func attendeesIncludeRoom(attendees []map[string]string) bool {
+	for _, attendee := range attendees {
+		if attendee["type"] == "resource" || attendee["room_id"] != "" {
+			return true
+		}
+	}
+	return false
+}
+
+func guideApprovalRoomReasonError(err error, attendees []map[string]string) error {
+	if err == nil || !attendeesIncludeRoom(attendees) {
+		return err
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok || !strings.Contains(strings.ToLower(p.Hint), "approval_reason") {
+		return err
+	}
+	return withStepContext(err, "approval meeting rooms require attendees[].approval_reason; calendar +create does not expose this low-frequency field. Create the event with the raw API flow, then use `lark-cli calendar event.attendees create --as user` with attendees[].approval_reason for the room attendee.")
+}
+
 var CalendarCreate = common.Shortcut{
 	Service:     "calendar",
 	Command:     "+create",
@@ -225,6 +245,7 @@ var CalendarCreate = common.Shortcut{
 					"need_notification": true,
 				})
 			if err != nil {
+				err = guideApprovalRoomReasonError(err, attendees)
 				// Rollback: delete the event
 				_, rollbackErr := runtime.CallAPITyped("DELETE",
 					fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s", validate.EncodePathSegment(calendarId), validate.EncodePathSegment(eventId)),

shortcuts/calendar/calendar_test.go

@@ -673,6 +673,76 @@ func TestCreate_WithAttendees_InvalidParamsWithDetail_RollsBack(t *testing.T) {
 	}
 }
 
+func TestCreate_ApprovalRoomMissingReason_GuidesRawAttendeesAPI(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id":   "evt_approval_room",
+					"summary":    "Approval Room",
+					"start_time": map[string]interface{}{"timestamp": "1742515200"},
+					"end_time":   map[string]interface{}{"timestamp": "1742518800"},
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/events/evt_approval_room/attendees",
+		Body: map[string]interface{}{
+			"code": codeInvalidParamsWithDetail,
+			"msg":  "invalid params",
+			"error": map[string]interface{}{
+				"details": []interface{}{
+					map[string]interface{}{"value": "attendees[0].approval_reason is required for approval meeting rooms"},
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/events/evt_approval_room",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	})
+
+	err := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Approval Room",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--attendee-ids", "omm_room1",
+		"--as", "user",
+	}, f, nil)
+
+	if err == nil {
+		t.Fatal("expected error for approval room missing approval_reason, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("ProblemOf returned !ok for %T", err)
+	}
+	if p.Category != errs.CategoryAPI {
+		t.Errorf("category=%q, want %q", p.Category, errs.CategoryAPI)
+	}
+	if p.Subtype != errs.SubtypeInvalidParameters {
+		t.Errorf("subtype=%q, want %q", p.Subtype, errs.SubtypeInvalidParameters)
+	}
+	if p.Code != codeInvalidParamsWithDetail {
+		t.Errorf("code=%d, want %d", p.Code, codeInvalidParamsWithDetail)
+	}
+	for _, want := range []string{"approval_reason", "calendar event.attendees create", "--as user", "rolled back successfully"} {
+		if !strings.Contains(p.Hint, want) {
+			t.Errorf("hint should contain %q, got: %q", want, p.Hint)
+		}
+	}
+}
+
 // When the add-attendees call fails AND the rollback DELETE also fails, the
 // primary error stays the add failure (classification preserved) and the Hint
 // must surface BOTH the rollback failure reason and the orphan event_id so the

shortcuts/drive/drive_import_common.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 
@@ -28,6 +29,8 @@ const (
 	driveImport500MBFileSizeLimit int64 = 500 * 1024 * 1024
 	driveImport600MBFileSizeLimit int64 = 600 * 1024 * 1024
 	driveImport800MBFileSizeLimit int64 = 800 * 1024 * 1024
+
+	driveImportConcurrentOperationHint = "This import conflict means another operation is running in the same Drive location. Run batch imports to the same folder/root or target bitable serially. Wait a few seconds before retrying each failed import; retry each failed item at most 3 times, then stop and report the conflict."
 )
 
 // driveImportExtToDocTypes defines which source file extensions can be imported
@@ -47,6 +50,8 @@ var driveImportExtToDocTypes = map[string][]string{
 	"pptx":     {"slides"},
 }
 
+var driveImportConcurrentOperationCodes = []int{232140101, 232140100, 233523001}
+
 // driveImportSpec contains the user-facing import inputs after normalization.
 type driveImportSpec struct {
 	FilePath    string
@@ -427,11 +432,7 @@ func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveIm
 			return status, true, nil
 		}
 		if status.Failed() {
-			msg := strings.TrimSpace(status.JobErrorMsg)
-			if msg == "" {
-				msg = status.StatusLabel()
-			}
-			return status, false, errs.NewAPIError(errs.SubtypeServerError, "import failed with status %d: %s", status.JobStatus, msg)
+			return status, false, driveImportFailureError(status)
 		}
 	}
 	if !hadSuccessfulPoll && lastErr != nil {
@@ -440,3 +441,40 @@ func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveIm
 
 	return lastStatus, false, nil
 }
+
+func driveImportFailureError(status driveImportStatus) *errs.APIError {
+	msg := strings.TrimSpace(status.JobErrorMsg)
+	if msg == "" {
+		msg = status.StatusLabel()
+	}
+
+	apiErr := errs.NewAPIError(errs.SubtypeServerError, "import failed with status %d: %s", status.JobStatus, msg)
+	if code, ok := driveImportConcurrentOperationCode(msg); ok {
+		apiErr = apiErr.WithCode(code).WithRetryable().WithHint(driveImportConcurrentOperationHint)
+	}
+	return apiErr
+}
+
+func driveImportConcurrentOperationCode(msg string) (int, bool) {
+	for _, code := range driveImportConcurrentOperationCodes {
+		codeText := strconv.Itoa(code)
+		for idx := strings.Index(msg, codeText); idx >= 0; {
+			end := idx + len(codeText)
+			if (idx == 0 || !isASCIIDigit(msg[idx-1])) && (end == len(msg) || !isASCIIDigit(msg[end])) {
+				return code, true
+			}
+
+			nextStart := idx + 1
+			next := strings.Index(msg[nextStart:], codeText)
+			if next < 0 {
+				break
+			}
+			idx = nextStart + next
+		}
+	}
+	return 0, false
+}
+
+func isASCIIDigit(ch byte) bool {
+	return ch >= '0' && ch <= '9'
+}

shortcuts/drive/drive_import_common_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"errors"
 	"os"
+	"strconv"
 	"strings"
 	"testing"
 
@@ -211,6 +212,82 @@ func TestDriveImportStatusPendingWithoutToken(t *testing.T) {
 	}
 }
 
+func TestDriveImportFailureErrorAddsConcurrentOperationGuidance(t *testing.T) {
+	t.Parallel()
+
+	for _, code := range driveImportConcurrentOperationCodes {
+		t.Run(strconv.Itoa(code), func(t *testing.T) {
+			t.Parallel()
+
+			err := driveImportFailureError(driveImportStatus{
+				JobStatus:   3,
+				JobErrorMsg: "call CreateObjNode return error code, code: " + strconv.Itoa(code) + ", message:",
+			})
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed error, got %T", err)
+			}
+			if problem.Category != errs.CategoryAPI {
+				t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryAPI)
+			}
+			if problem.Subtype != errs.SubtypeServerError {
+				t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeServerError)
+			}
+			if problem.Code != code {
+				t.Fatalf("code = %d, want %d", problem.Code, code)
+			}
+			if !problem.Retryable {
+				t.Fatal("expected retryable error")
+			}
+			if problem.Hint != driveImportConcurrentOperationHint {
+				t.Fatalf("hint = %q, want %q", problem.Hint, driveImportConcurrentOperationHint)
+			}
+		})
+	}
+}
+
+func TestDriveImportFailureErrorLeavesOtherFailuresUnchanged(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		msg  string
+	}{
+		{
+			name: "ordinary failure",
+			msg:  "unsupported conversion",
+		},
+		{
+			name: "longer numeric code containing known code",
+			msg:  "call CreateObjNode return error code, code: 12321401012, message:",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := driveImportFailureError(driveImportStatus{
+				JobStatus:   3,
+				JobErrorMsg: tt.msg,
+			})
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed error, got %T", err)
+			}
+			if problem.Code != 0 {
+				t.Fatalf("code = %d, want 0", problem.Code)
+			}
+			if problem.Retryable {
+				t.Fatal("expected non-concurrency failure to remain non-retryable")
+			}
+			if problem.Hint != "" {
+				t.Fatalf("hint = %q, want empty", problem.Hint)
+			}
+		})
+	}
+}
+
 func TestDriveImportTimeoutReturnsFollowUpCommand(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	reg.Register(&httpmock.Stub{

shortcuts/drive/drive_permission_get_setting.go

@@ -1,226 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package drive
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"net/url"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-type drivePermissionGetSettingSpec struct {
-	Token string
-	Type  string
-}
-
-var drivePermissionGetSettingTypes = []string{
-	"doc", "sheet", "file", "wiki", "bitable", "docx",
-	"mindnote", "minutes", "slides", "folder",
-}
-
-var drivePermissionGetSettingURLPathToType = []struct {
-	Prefix string
-	Type   string
-}{
-	{"/drive/folder/", "folder"},
-	{"/docx/", "docx"},
-	{"/doc/", "doc"},
-	{"/sheets/", "sheet"},
-	{"/base/", "bitable"},
-	{"/bitable/", "bitable"},
-	{"/wiki/", "wiki"},
-	{"/file/", "file"},
-	{"/mindnotes/", "mindnote"},
-	{"/slides/", "slides"},
-	{"/minutes/", "minutes"},
-}
-
-func readDrivePermissionGetSettingSpec(runtime *common.RuntimeContext) (drivePermissionGetSettingSpec, error) {
-	rawToken := strings.TrimSpace(runtime.Str("token"))
-	explicitType := strings.ToLower(strings.TrimSpace(runtime.Str("type")))
-
-	if rawToken == "" {
-		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-			errs.SubtypeInvalidArgument,
-			"--token is required",
-		).WithParam("--token")
-	}
-
-	if explicitType != "" && !drivePermissionGetSettingTypeAllowed(explicitType) {
-		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-			errs.SubtypeInvalidArgument,
-			"invalid --type %q: allowed values are %s",
-			explicitType,
-			strings.Join(drivePermissionGetSettingTypes, ", "),
-		).WithParam("--type")
-	}
-
-	if strings.Contains(rawToken, "://") {
-		ref, ok := parseDrivePermissionGetSettingResourceURL(rawToken)
-		if !ok {
-			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-				errs.SubtypeInvalidArgument,
-				"unsupported --token URL %q: pass a recognized Lark Drive document/folder URL or a bare token with --type",
-				rawToken,
-			).WithParam("--token")
-		}
-		if explicitType != "" && explicitType != ref.Type {
-			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-				errs.SubtypeInvalidArgument,
-				"--type %q conflicts with URL path type %q; remove --type or use a matching value",
-				explicitType,
-				ref.Type,
-			).WithParam("--type")
-		}
-		if err := validate.ResourceName(ref.Token, "--token"); err != nil {
-			return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
-		}
-		return drivePermissionGetSettingSpec{Token: ref.Token, Type: ref.Type}, nil
-	}
-
-	if explicitType == "" {
-		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-			errs.SubtypeInvalidArgument,
-			"--type is required when --token is a bare token (allowed: %s)",
-			strings.Join(drivePermissionGetSettingTypes, ", "),
-		).WithParam("--type")
-	}
-
-	if err := validate.ResourceName(rawToken, "--token"); err != nil {
-		return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
-	}
-	return drivePermissionGetSettingSpec{Token: rawToken, Type: explicitType}, nil
-}
-
-func parseDrivePermissionGetSettingResourceURL(rawURL string) (common.ResourceRef, bool) {
-	parsed, err := url.Parse(strings.TrimSpace(rawURL))
-	if err != nil || parsed.Hostname() == "" {
-		return common.ResourceRef{}, false
-	}
-
-	for _, mapping := range drivePermissionGetSettingURLPathToType {
-		if !strings.HasPrefix(parsed.Path, mapping.Prefix) {
-			continue
-		}
-		token := parsed.Path[len(mapping.Prefix):]
-		token = strings.TrimRight(token, "/")
-		if idx := strings.IndexByte(token, '/'); idx >= 0 {
-			token = token[:idx]
-		}
-		token = strings.TrimSpace(token)
-		if token == "" {
-			return common.ResourceRef{}, false
-		}
-		return common.ResourceRef{Type: mapping.Type, Token: token}, true
-	}
-
-	return common.ResourceRef{}, false
-}
-
-func drivePermissionGetSettingTypeAllowed(docType string) bool {
-	for _, allowed := range drivePermissionGetSettingTypes {
-		if docType == allowed {
-			return true
-		}
-	}
-	return false
-}
-
-func (s drivePermissionGetSettingSpec) url(runtime *common.RuntimeContext) string {
-	if runtime != nil && runtime.Config != nil {
-		if u := common.BuildResourceURL(runtime.Config.Brand, s.Type, s.Token); u != "" {
-			return u
-		}
-	}
-	return common.BuildResourceURL("", s.Type, s.Token)
-}
-
-func (s drivePermissionGetSettingSpec) params() map[string]interface{} {
-	return map[string]interface{}{"type": s.Type}
-}
-
-func (s drivePermissionGetSettingSpec) apiPath() string {
-	return drivePermissionPublicV2Path(s.Token)
-}
-
-func drivePermissionPublicV2Path(token string) string {
-	return fmt.Sprintf("/open-apis/drive/v2/permissions/%s/public", validate.EncodePathSegment(token))
-}
-
-func (s drivePermissionGetSettingSpec) output(runtime *common.RuntimeContext, data map[string]interface{}) map[string]interface{} {
-	permissionPublic := interface{}(data)
-	if nestedPermissionPublic := common.GetMap(data, "permission_public"); nestedPermissionPublic != nil {
-		permissionPublic = nestedPermissionPublic
-	}
-	return map[string]interface{}{
-		"permission_public": permissionPublic,
-	}
-}
-
-// DrivePermissionGetSetting queries permission_public settings for a Drive
-// document, file, wiki node, or folder.
-var DrivePermissionGetSetting = common.Shortcut{
-	Service:     "drive",
-	Command:     "+permission-get-setting",
-	Description: "Get public access, sharing, collaborator management, security, and comment permission settings",
-	Risk:        "read",
-	Scopes:      []string{"docs:permission.setting:read"},
-	AuthTypes:   []string{"user", "bot"},
-	HasFormat:   true,
-	Flags: []common.Flag{
-		{Name: "token", Desc: "target URL or bare token (doc/sheet/file/wiki/bitable/docx/mindnote/minutes/slides/folder)"},
-		{Name: "type", Desc: "target type; auto-inferred from URL, required for bare tokens", Enum: drivePermissionGetSettingTypes},
-	},
-	Tips: []string{
-		"--token accepts a Lark URL or bare token; pass --type when using a bare token.",
-		"Use --type folder for Drive folders. This shortcut reads the target's own permission settings; it does not recurse into child documents.",
-	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		_, err := readDrivePermissionGetSettingSpec(runtime)
-		return err
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		spec, err := readDrivePermissionGetSettingSpec(runtime)
-		if err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
-		}
-		return common.NewDryRunAPI().
-			Desc("Get Drive permission settings").
-			GET(spec.apiPath()).
-			Params(spec.params())
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		spec, err := readDrivePermissionGetSettingSpec(runtime)
-		if err != nil {
-			return err
-		}
-
-		fmt.Fprintf(runtime.IO().ErrOut, "Getting permission settings for %s %s...\n", spec.Type, common.MaskToken(spec.Token))
-		data, err := runtime.CallAPITyped(
-			"GET",
-			spec.apiPath(),
-			spec.params(),
-			nil,
-		)
-		if err != nil {
-			return err
-		}
-
-		out := spec.output(runtime, data)
-		runtime.OutFormat(out, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "Type:  %s\n", spec.Type)
-			fmt.Fprintf(w, "Token: %s\n", spec.Token)
-			if url := spec.url(runtime); url != "" {
-				fmt.Fprintf(w, "URL:   %s\n", url)
-			}
-		})
-		return nil
-	},
-}

shortcuts/drive/drive_permission_get_setting_test.go

@@ -1,365 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package drive
-
-import (
-	"context"
-	"encoding/json"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-func newDrivePermissionGetSettingRuntime(t *testing.T, token, docType string) *common.RuntimeContext {
-	t.Helper()
-
-	cmd := &cobra.Command{Use: "drive +permission-get-setting"}
-	cmd.Flags().String("token", "", "")
-	cmd.Flags().String("type", "", "")
-	if token != "" {
-		if err := cmd.Flags().Set("token", token); err != nil {
-			t.Fatalf("set --token: %v", err)
-		}
-	}
-	if docType != "" {
-		if err := cmd.Flags().Set("type", docType); err != nil {
-			t.Fatalf("set --type: %v", err)
-		}
-	}
-	return common.TestNewRuntimeContext(cmd, driveTestConfig())
-}
-
-func TestDrivePermissionGetSettingSpecResolvesTargets(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name     string
-		token    string
-		docType  string
-		wantTok  string
-		wantType string
-	}{
-		{
-			name:     "folder URL",
-			token:    "https://example.feishu.cn/drive/folder/fldTok?from=share",
-			wantTok:  "fldTok",
-			wantType: "folder",
-		},
-		{
-			name:     "docx URL",
-			token:    "https://example.feishu.cn/docx/doxTok",
-			wantTok:  "doxTok",
-			wantType: "docx",
-		},
-		{
-			name:     "file URL",
-			token:    "https://example.feishu.cn/file/boxTok",
-			wantTok:  "boxTok",
-			wantType: "file",
-		},
-		{
-			name:     "wiki URL",
-			token:    "https://example.feishu.cn/wiki/wikTok",
-			wantTok:  "wikTok",
-			wantType: "wiki",
-		},
-		{
-			name:     "minutes URL",
-			token:    "https://example.feishu.cn/minutes/obTok",
-			wantTok:  "obTok",
-			wantType: "minutes",
-		},
-		{
-			name:     "mindnotes URL",
-			token:    "https://example.feishu.cn/mindnotes/mndTok",
-			wantTok:  "mndTok",
-			wantType: "mindnote",
-		},
-		{
-			name:     "bare folder token",
-			token:    " fldTok ",
-			docType:  " folder ",
-			wantTok:  "fldTok",
-			wantType: "folder",
-		},
-		{
-			name:     "bare file token",
-			token:    "boxTok",
-			docType:  "file",
-			wantTok:  "boxTok",
-			wantType: "file",
-		},
-		{
-			name:     "bare wiki token",
-			token:    "wikTok",
-			docType:  "wiki",
-			wantTok:  "wikTok",
-			wantType: "wiki",
-		},
-	}
-
-	for _, temp := range tests {
-		tt := temp
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
-			spec, err := readDrivePermissionGetSettingSpec(runtime)
-			if err != nil {
-				t.Fatalf("read spec: %v", err)
-			}
-			if spec.Token != tt.wantTok {
-				t.Fatalf("Token = %q, want %q", spec.Token, tt.wantTok)
-			}
-			if spec.Type != tt.wantType {
-				t.Fatalf("Type = %q, want %q", spec.Type, tt.wantType)
-			}
-		})
-	}
-}
-
-func TestDrivePermissionGetSettingSpecValidationErrorsAreTyped(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name        string
-		token       string
-		docType     string
-		wantParam   string
-		wantMessage string
-	}{
-		{
-			name:        "missing token",
-			wantParam:   "--token",
-			wantMessage: "--token is required",
-		},
-		{
-			name:        "bare token without type",
-			token:       "doxTok",
-			wantParam:   "--type",
-			wantMessage: "--type is required",
-		},
-		{
-			name:        "unsupported URL",
-			token:       "https://example.feishu.cn/calendar/calTok",
-			wantParam:   "--token",
-			wantMessage: "unsupported --token URL",
-		},
-		{
-			name:        "URL type conflict",
-			token:       "https://example.feishu.cn/docx/doxTok",
-			docType:     "sheet",
-			wantParam:   "--type",
-			wantMessage: "conflicts with URL path type",
-		},
-		{
-			name:        "invalid bare token",
-			token:       "../bad",
-			docType:     "folder",
-			wantParam:   "--token",
-			wantMessage: "--token",
-		},
-		{
-			name:        "invalid type",
-			token:       "doxTok",
-			docType:     "comment",
-			wantParam:   "--type",
-			wantMessage: "invalid --type",
-		},
-	}
-
-	for _, temp := range tests {
-		tt := temp
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
-			_, err := readDrivePermissionGetSettingSpec(runtime)
-			if err == nil {
-				t.Fatal("expected validation error, got nil")
-			}
-			problem, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("error is not typed: %T %v", err, err)
-			}
-			if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
-				t.Fatalf("problem = %s/%s, want validation/invalid_argument", problem.Category, problem.Subtype)
-			}
-			if validationErr, ok := err.(*errs.ValidationError); ok {
-				if validationErr.Param != tt.wantParam {
-					t.Fatalf("param = %q, want %q", validationErr.Param, tt.wantParam)
-				}
-			} else {
-				t.Fatalf("error type = %T, want *errs.ValidationError", err)
-			}
-			if !strings.Contains(err.Error(), tt.wantMessage) {
-				t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantMessage)
-			}
-		})
-	}
-}
-
-func TestDrivePermissionGetSettingDryRunIncludesGETRequest(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name     string
-		token    string
-		docType  string
-		wantURL  string
-		wantType string
-	}{
-		{
-			name:     "folder URL",
-			token:    "https://example.feishu.cn/drive/folder/fldTok",
-			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
-			wantType: "folder",
-		},
-		{
-			name:     "bare folder token",
-			token:    "fldTok",
-			docType:  "folder",
-			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
-			wantType: "folder",
-		},
-		{
-			name:     "docx URL",
-			token:    "https://example.feishu.cn/docx/doxTok",
-			wantURL:  "/open-apis/drive/v2/permissions/doxTok/public",
-			wantType: "docx",
-		},
-		{
-			name:     "bare wiki token",
-			token:    "wikTok",
-			docType:  "wiki",
-			wantURL:  "/open-apis/drive/v2/permissions/wikTok/public",
-			wantType: "wiki",
-		},
-		{
-			name:     "file URL",
-			token:    "https://example.feishu.cn/file/boxTok",
-			wantURL:  "/open-apis/drive/v2/permissions/boxTok/public",
-			wantType: "file",
-		},
-		{
-			name:     "minutes URL",
-			token:    "https://example.feishu.cn/minutes/obTok",
-			wantURL:  "/open-apis/drive/v2/permissions/obTok/public",
-			wantType: "minutes",
-		},
-		{
-			name:     "mindnotes URL",
-			token:    "https://example.feishu.cn/mindnotes/mndTok",
-			wantURL:  "/open-apis/drive/v2/permissions/mndTok/public",
-			wantType: "mindnote",
-		},
-	}
-
-	for _, temp := range tests {
-		tt := temp
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
-			dry := DrivePermissionGetSetting.DryRun(context.Background(), runtime)
-			if dry == nil {
-				t.Fatal("DryRun returned nil")
-			}
-			data, err := json.Marshal(dry)
-			if err != nil {
-				t.Fatalf("marshal dry-run: %v", err)
-			}
-			out := string(data)
-			for _, want := range []string{
-				`"` + tt.wantURL + `"`,
-				`"GET"`,
-				`"type":"` + tt.wantType + `"`,
-			} {
-				if !strings.Contains(out, want) {
-					t.Fatalf("dry-run output missing %q:\n%s", want, out)
-				}
-			}
-			if strings.Contains(out, `"folder_token"`) {
-				t.Fatalf("dry-run output contains folder_token, want omitted:\n%s", out)
-			}
-		})
-	}
-}
-
-func TestDrivePermissionGetSettingExecutePreservesPermissionPublic(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/drive/v2/permissions/doxTok/public?type=docx",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"data": map[string]interface{}{
-				"permission_public": map[string]interface{}{
-					"link_share_entity":          "closed",
-					"external_access_entity":     "closed",
-					"security_entity":            "anyone_can_view",
-					"comment_entity":             "anyone_can_view",
-					"share_entity":               "anyone",
-					"manage_collaborator_entity": "collaborator_can_view",
-					"lock_switch":                false,
-					"server_future_field":        "preserved",
-				},
-			},
-		},
-	})
-
-	err := mountAndRunDrive(t, DrivePermissionGetSetting, []string{
-		"+permission-get-setting",
-		"--token", "doxTok",
-		"--type", "docx",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data := decodeDriveEnvelope(t, stdout)
-	for _, key := range []string{"type", "token", "url"} {
-		if _, ok := data[key]; ok {
-			t.Fatalf("data[%s] = %#v, want field omitted", key, data[key])
-		}
-	}
-	permissionPublic, _ := data["permission_public"].(map[string]interface{})
-	if permissionPublic == nil {
-		t.Fatalf("permission_public missing in output: %#v", data)
-	}
-	for key, want := range map[string]interface{}{
-		"link_share_entity":          "closed",
-		"external_access_entity":     "closed",
-		"security_entity":            "anyone_can_view",
-		"comment_entity":             "anyone_can_view",
-		"share_entity":               "anyone",
-		"manage_collaborator_entity": "collaborator_can_view",
-		"lock_switch":                false,
-		"server_future_field":        "preserved",
-	} {
-		if permissionPublic[key] != want {
-			t.Fatalf("permission_public[%s] = %#v, want %#v", key, permissionPublic[key], want)
-		}
-	}
-}
-
-func TestDrivePermissionGetSettingDeclaresScopeAndIdentities(t *testing.T) {
-	t.Parallel()
-
-	if !reflect.DeepEqual(DrivePermissionGetSetting.Scopes, []string{"docs:permission.setting:read"}) {
-		t.Fatalf("Scopes = %v, want docs:permission.setting:read", DrivePermissionGetSetting.Scopes)
-	}
-	if !reflect.DeepEqual(DrivePermissionGetSetting.AuthTypes, []string{"user", "bot"}) {
-		t.Fatalf("AuthTypes = %v, want [user bot]", DrivePermissionGetSetting.AuthTypes)
-	}
-}

shortcuts/drive/drive_pull.go

@@ -184,6 +184,7 @@ var DrivePull = common.Shortcut{
 
 		var downloaded, skipped, failed, deletedLocal int
 		downloadFailed := 0
+		aborted := false
 		items := make([]drivePullItem, 0)
 
 		// Deterministic iteration order for output stability.
@@ -194,7 +195,7 @@ var DrivePull = common.Shortcut{
 		sort.Strings(downloadablePaths)
 
 		for _, rel := range downloadablePaths {
-			if drivePullHasTerminalFailure(items) {
+			if aborted {
 				break
 			}
 			targetFile := remoteFiles[rel]
@@ -232,6 +233,7 @@ 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
 				}
@@ -298,7 +300,7 @@ var DrivePull = common.Shortcut{
 				"skipped":       skipped,
 				"failed":        failed,
 				"deleted_local": deletedLocal,
-				"aborted":       drivePullHasTerminalFailure(items),
+				"aborted":       aborted,
 			},
 			"items": items,
 		}
@@ -347,15 +349,6 @@ 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,6 +35,7 @@ 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"`
@@ -48,6 +49,7 @@ 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
@@ -240,6 +242,7 @@ 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
@@ -266,6 +269,7 @@ 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
 				}
@@ -284,7 +288,7 @@ var DrivePush = common.Shortcut{
 
 		for _, rel := range localPaths {
 			localFile := localFiles[rel]
-			if uploadFailed && drivePushHasTerminalFailure(items) {
+			if uploadFailed && aborted {
 				break
 			}
 
@@ -301,6 +305,7 @@ 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
 					}
@@ -332,6 +337,7 @@ 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
 					}
@@ -350,6 +356,7 @@ 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
 				}
@@ -362,6 +369,7 @@ 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
 				}
@@ -407,10 +415,15 @@ 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
@@ -429,7 +442,7 @@ var DrivePush = common.Shortcut{
 				"skipped":        skipped,
 				"failed":         failed,
 				"deleted_remote": deletedRemote,
-				"aborted":        drivePushHasTerminalFailure(items),
+				"aborted":        aborted,
 			},
 			"items": items,
 		}
@@ -567,6 +580,7 @@ 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,
@@ -613,6 +627,10 @@ 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:
@@ -626,22 +644,9 @@ func driveClassifyBatchFailure(err error) driveBatchFailureDecision {
 	return decision
 }
 
-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 drivePushIsAlreadyDeleted(err error) bool {
+	problem, ok := errs.ProblemOf(err)
+	return ok && problem.Code == 1061007
 }
 
 func drivePushRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (map[string]driveRemoteEntry, map[string]driveRemoteEntry, map[string][]driveRemoteEntry, error) {

shortcuts/drive/drive_push_test.go

@@ -732,6 +732,65 @@ 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())
 
@@ -1137,6 +1196,78 @@ 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,6 +268,7 @@ 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.
@@ -286,16 +287,21 @@ 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 driveSyncHasTerminalFailure(items) {
+			if aborted {
 				break
 			}
 			if _, alreadyRemote := folderCache[relDir]; alreadyRemote {
 				continue
 			}
 			if _, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, relDir, folderCache); ensureErr != nil {
-				item, _ := driveSyncFailedItem(relDir, "", "failed", "push", "create_folder", ensureErr)
+				item, terminal := 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"})
@@ -304,7 +310,7 @@ var DriveSync = common.Shortcut{
 
 		// 2a. Pull new_remote files.
 		for _, entry := range newRemote {
-			if driveSyncHasTerminalFailure(items) {
+			if aborted {
 				break
 			}
 			targetFile, ok := pullRemoteFiles[entry.RelPath]
@@ -318,6 +324,7 @@ 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
 				}
@@ -329,7 +336,7 @@ var DriveSync = common.Shortcut{
 
 		// 2b. Push new_local files.
 		for _, entry := range newLocal {
-			if driveSyncHasTerminalFailure(items) {
+			if aborted {
 				break
 			}
 			localFile, ok := pushLocalFiles[entry.RelPath]
@@ -341,9 +348,14 @@ var DriveSync = common.Shortcut{
 			parentRel := drivePushParentRel(entry.RelPath)
 			parentToken, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, parentRel, folderCache)
 			if ensureErr != nil {
-				item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "push", "create_folder", ensureErr)
+				item, terminal := 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)
@@ -352,6 +364,7 @@ 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
 				}
@@ -363,7 +376,7 @@ var DriveSync = common.Shortcut{
 
 		// 2c. Resolve modified files by --on-conflict strategy.
 		for _, entry := range modified {
-			if driveSyncHasTerminalFailure(items) {
+			if aborted {
 				break
 			}
 			remoteFile := remoteFiles[entry.RelPath]
@@ -397,6 +410,7 @@ 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
 					}
@@ -415,9 +429,14 @@ var DriveSync = common.Shortcut{
 				}
 				parentToken, parentErr := drivePushEnsureFolder(ctx, runtime, folderToken, drivePushParentRel(entry.RelPath), folderCache)
 				if parentErr != nil {
-					item, _ := driveSyncFailedItem(entry.RelPath, existingToken, "failed", "push", "create_folder", parentErr)
+					item, terminal := 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)
@@ -435,6 +454,7 @@ 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
 					}
@@ -503,6 +523,7 @@ 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
 					}
@@ -531,7 +552,7 @@ var DriveSync = common.Shortcut{
 				"pushed":  pushed,
 				"skipped": skipped,
 				"failed":  failed,
-				"aborted": driveSyncHasTerminalFailure(items),
+				"aborted": aborted,
 			},
 			"items": items,
 		}
@@ -577,15 +598,6 @@ 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/drive/shortcuts.go

@@ -31,7 +31,6 @@ func Shortcuts() []common.Shortcut {
 		DriveTaskResult,
 		DriveApplyPermission,
 		DriveMemberAdd,
-		DrivePermissionGetSetting,
 		DriveSecureLabelList,
 		DriveSecureLabelUpdate,
 		DriveSearch,

shortcuts/drive/shortcuts_test.go

@@ -37,7 +37,6 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+task_result",
 		"+apply-permission",
 		"+member-add",
-		"+permission-get-setting",
 		"+secure-label-list",
 		"+secure-label-update",
 		"+search",

shortcuts/markdown/helpers.go

@@ -715,9 +715,15 @@ 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 token you passed to the command.")
+			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.")
 		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,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -30,27 +31,19 @@ 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 {
-		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)
+		spec, err := readMarkdownCreateSpec(runtime)
+		if err != nil {
+			return err
+		}
+		return validateMarkdownSpec(runtime, spec, true)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		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"),
+		spec, err := readMarkdownCreateSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
 		}
 		fileSize, err := markdownSourceSize(runtime, spec)
 		if err != nil {
@@ -71,14 +64,9 @@ var MarkdownCreate = common.Shortcut{
 		return dry
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) 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"),
+		spec, err := readMarkdownCreateSpec(runtime)
+		if err != nil {
+			return err
 		}
 		fileSize, err := markdownSourceSize(runtime, spec)
 		if err != nil {
@@ -115,3 +103,139 @@ 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,6 +446,173 @@ 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/wiki/wiki_helpers.go

@@ -6,6 +6,7 @@ package wiki
 import (
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -26,3 +27,17 @@ 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,12 +5,14 @@ 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"
@@ -130,6 +132,147 @@ 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())
 
@@ -137,14 +280,14 @@ func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes",
 		Body: map[string]interface{}{
 			"code": 0,
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":          "space_123",
+						"space_id":          "7211568716812369922",
 						"node_token":        "wik_node_1",
 						"obj_token":         "docx_1",
 						"obj_type":          "docx",
@@ -154,7 +297,7 @@ func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 						"has_child":         true,
 					},
 					map[string]interface{}{
-						"space_id":          "space_123",
+						"space_id":          "7211568716812369922",
 						"node_token":        "wik_node_2",
 						"obj_token":         "docx_2",
 						"obj_type":          "docx",
@@ -170,7 +313,7 @@ func TestWikiNodeListReturnsNodesForSpace(t *testing.T) {
 	})
 
 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "space_123", "--as", "bot",
+		"+node-list", "--space-id", "7211568716812369922", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -211,14 +354,14 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {
 
 	stub := &httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes?page_size=50&parent_node_token=wik_parent",
+		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/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":          "space_123",
+						"space_id":          "7211568716812369922",
 						"node_token":        "wik_child",
 						"obj_token":         "docx_child",
 						"obj_type":          "docx",
@@ -235,7 +378,7 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {
 	reg.Register(stub)
 
 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "space_123", "--parent-node-token", "wik_parent", "--as", "bot",
+		"+node-list", "--space-id", "7211568716812369922", "--parent-node-token", "wik_parent", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -286,7 +429,7 @@ func TestWikiNodeListResolvesMyLibraryForUser(t *testing.T) {
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"space": map[string]interface{}{
-					"space_id":   "space_personal_42",
+					"space_id":   "7211568716812369923",
 					"name":       "My Library",
 					"space_type": "my_library",
 				},
@@ -296,14 +439,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/space_personal_42/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/7211568716812369923/nodes",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":   "space_personal_42",
+						"space_id":   "7211568716812369923",
 						"node_token": "wik_personal_1",
 						"title":      "Personal Note",
 					},
@@ -334,8 +477,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"] != "space_personal_42" {
-		t.Fatalf("nodes[0].space_id = %v, want space_personal_42", envelope.Data.Nodes[0]["space_id"])
+	if envelope.Data.Nodes[0]["space_id"] != "7211568716812369923" {
+		t.Fatalf("nodes[0].space_id = %v, want 7211568716812369923", envelope.Data.Nodes[0]["space_id"])
 	}
 }
 
@@ -758,21 +901,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/space_123/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/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": "space_123", "node_token": "wik_1", "title": "First"},
+					map[string]interface{}{"space_id": "7211568716812369922", "node_token": "wik_1", "title": "First"},
 				},
 			},
 		},
 	})
 
 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "space_123", "--as", "bot",
+		"+node-list", "--space-id", "7211568716812369922", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -802,14 +945,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/space_123/nodes",
+		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "success",
 			"data": map[string]interface{}{
 				"has_more": false,
 				"items": []interface{}{
 					map[string]interface{}{
-						"space_id":   "space_123",
+						"space_id":   "7211568716812369922",
 						"node_token": "wik_1",
 						"obj_type":   "docx",
 						"obj_token":  "docx_1",
@@ -822,7 +965,7 @@ func TestWikiNodeListPrettyFormatRendersFields(t *testing.T) {
 	})
 
 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "space_123", "--format", "pretty", "--as", "bot",
+		"+node-list", "--space-id", "7211568716812369922", "--format", "pretty", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)

shortcuts/wiki/wiki_node_list.go

@@ -48,27 +48,19 @@ 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 {
-		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 {
+		if _, err := readWikiNodeListSpec(runtime); err != nil {
 			return err
 		}
 		return validateWikiListPagination(runtime, wikiNodeListMaxPageSize)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		spaceID := strings.TrimSpace(runtime.Str("space-id"))
+		spec, err := readWikiNodeListSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
 		params := map[string]interface{}{"page_size": runtime.Int("page-size")}
-		if pt := strings.TrimSpace(runtime.Str("parent-node-token")); pt != "" {
-			params["parent_node_token"] = pt
+		if spec.ParentNodeToken != "" {
+			params["parent_node_token"] = spec.ParentNodeToken
 		}
 		if pt := strings.TrimSpace(runtime.Str("page-token")); pt != "" {
 			params["page_token"] = pt
@@ -80,7 +72,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 spaceID == wikiMyLibrarySpaceID {
+		if spec.SpaceID == wikiMyLibrarySpaceID {
 			return d.
 				Desc("2-step orchestration: resolve my_library -> list nodes").
 				GET("/open-apis/wiki/v2/spaces/my_library").
@@ -91,13 +83,17 @@ var WikiNodeList = common.Shortcut{
 				Set("space_id", "<resolved_space_id>")
 		}
 		return d.
-			GET(fmt.Sprintf("/open-apis/wiki/v2/spaces/%s/nodes", validate.EncodePathSegment(spaceID))).
+			GET(fmt.Sprintf("/open-apis/wiki/v2/spaces/%s/nodes", validate.EncodePathSegment(spec.SpaceID))).
 			Params(params).
-			Set("space_id", spaceID)
+			Set("space_id", spec.SpaceID)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		warnIfConflictingPagingFlags(runtime)
-		spaceID := strings.TrimSpace(runtime.Str("space-id"))
+		spec, err := readWikiNodeListSpec(runtime)
+		if err != nil {
+			return err
+		}
+		spaceID := spec.SpaceID
 
 		// Resolve the my_library alias to the per-user real space_id before
 		// listing, so the subsequent request hits a concrete space endpoint.
@@ -110,7 +106,7 @@ var WikiNodeList = common.Shortcut{
 			spaceID = resolved
 		}
 
-		nodes, hasMore, nextToken, err := fetchWikiNodes(runtime, spaceID)
+		nodes, hasMore, nextToken, err := fetchWikiNodes(runtime, spaceID, spec.ParentNodeToken)
 		if err != nil {
 			return err
 		}
@@ -127,10 +123,104 @@ var WikiNodeList = common.Shortcut{
 	},
 }
 
-func fetchWikiNodes(runtime *common.RuntimeContext, spaceID string) ([]map[string]interface{}, bool, string, error) {
+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) {
 	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")
 
@@ -153,7 +243,7 @@ func fetchWikiNodes(runtime *common.RuntimeContext, spaceID string) ([]map[strin
 		}
 		data, err := runtime.CallAPITyped("GET", apiPath, params, nil)
 		if err != nil {
-			return nil, false, "", err
+			return nil, false, "", wikiNodeListProblem(err, runtime)
 		}
 		items, _ := data["items"].([]interface{})
 		for _, item := range items {
@@ -177,6 +267,36 @@ func fetchWikiNodes(runtime *common.RuntimeContext, spaceID string) ([]map[strin
 	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"),

skill-template/domains/drive.md

@@ -6,6 +6,7 @@
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
+- 批量执行 `drive +import` 且目标是同一个位置（同一 `--folder-token`、默认根目录，或同一 `--target-token`）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
 - 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 
@@ -194,6 +195,7 @@ lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "
 | `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
 | `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable） |
+| `232140101` / `232140100` / `233523001`（常见于 `drive +import` 的 `job_error_msg`） | 同一位置下存在并发导入 / 创建操作 | 批量导入到同一文件夹、根目录或同一 `--target-token` 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突 |
 
 ### 授权当前应用访问文档
 

skills/lark-calendar/SKILL.md

@@ -45,13 +45,15 @@ lark-cli calendar +agenda --as user
 | 场景 | 前置要求 |
 |------|----------|
 | 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
-| 编辑已有日程 | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
+| 编辑已有日程 | 先定位目标日程 `event_id` |
+| 编辑/删除重复性日程 | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，按操作范围（仅此次/全部/此次及后续）执行 |
 | 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
 | 调用任何 Shortcut | 先读其对应 reference 文档 |
 
 ## 核心概念
 
-- **日程实例（Instance）**：重复性日程展开后的具体时间实例。操作重复日程的某次实例时，必须先定位该实例的 `event_id`，禁止使用原重复日程的 `event_id`。
+- **日程实例（Instance）**：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 `event_id`；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 `event_id`），并按需处理例外。
+- **重复性日程例外（Exception）**：对重复性日程某次实例做过「仅此次」编辑后产生的独立日程（拥有独立 `event_id`）。删除/更新「全部」时必须同时处理例外，否则例外会残留。
 - **全天日程（All-day Event）**：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
 - **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
 - **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
@@ -71,6 +73,7 @@ lark-cli calendar +agenda --as user
 | 从日程获取关联的视频会议 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) |
+| 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |
 
 ## 任务类型分流
 

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

@@ -47,6 +47,7 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 > 自动设置 `reminders: [{"minutes": 5}]`，默认日程开始前 5 分钟提醒。
 > 自动设置 `vchat: {"vc_type": "vc"}`，默认日程包含飞书视频会议。如需其他视频会议类型或不含视频会议，请使用完整 API 命令。
 > 失败保护：若添加参会人失败（如 open_id 错误），CLI 会自动删除刚创建的空日程（回滚，不通知参会人）。
+> 审批会议室：`+create` 不暴露低频字段 `attendees[].approval_reason`。如果会议室要求审批，请使用用户身份先创建日程，再用完整 API `calendar event.attendees create --as user` 添加会议室并传 `approval_reason`。
 
 ## 高级用法（完整 API 命令）
 
@@ -72,9 +73,16 @@ lark-cli calendar events create \
 lark-cli schema calendar.event.attendees.create
 ## 添加参会人
 lark-cli calendar event.attendees create \
+  --as user \
   --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
   --data '{"attendees": [{"type": "user", "user_id": "ou_xxx"}]}'
 
+## 添加需要审批的会议室（approval_reason 最大 200 字符）
+lark-cli calendar event.attendees create \
+  --as user \
+  --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
+  --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
+
 # 可选第三步（推荐）：若第二步失败，回滚删除空日程
 ## 查看完整参数定义
 lark-cli schema calendar.events.delete

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

@@ -0,0 +1,90 @@
+# 重复性日程操作规范
+
+重复性日程的编辑/删除分为三种范围：「仅此次」「全部」「此次及后续」。用户未明确范围时，**必须询问确认**。
+
+## 关键概念
+
+- **event_id 结构**：`event_id` 的格式为 `{event_uid}_{originalTime}`。普通日程或重复性日程本体的 `originalTime` 为 `0`；例外的 `originalTime > 0`，代表该例外在原重复性序列中本来的时间位置。因此 `{event_uid}_0` 即为原重复性日程的 `event_id`。
+- **原重复性日程**：携带 `rrule` 的日程本体，`event_id` 形如 `{event_uid}_0`。系列的所有属性（标题、时间、rrule、描述等）都挂在本体上。
+- **例外（Exception）**：对某次实例做过「仅此次」编辑后产生的独立日程，`event_id` 形如 `{event_uid}_{originalTime}`（`originalTime > 0`）。通过 `event_uid` 部分即可关联回原重复性日程。
+- 删除/更新原重复性日程 **不会** 级联处理例外——必须手动逐个处理。
+
+## 前置步骤（所有范围通用）
+
+1. 通过 `+agenda` 或 `+search-event` 定位重复性日程，获取原重复性日程的 `event_id`。
+2. 通过 `events instance_view` 或 `+agenda` 列出实例，识别哪些是例外（`event_id` 中 `originalTime > 0` 的即为例外）。
+3. 确认用户的操作范围。
+
+## 编辑全部（更新时间）
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --start ... --end ...` | 更新原重复性日程的时间 |
+| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 时间变更后例外已无意义，必须删除 |
+
+> 理由：更新时间会改变重复起止点，例外日程的原始占位已变，若保留会导致时间冲突或残留。
+
+## 编辑全部（更新非时间字段）
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --summary ... --description ...` | 更新原重复性日程的标题/描述等 |
+| 2 | `lark-cli calendar +update --event-id <例外ID> --summary ... --description ...` （逐个） | 同步更新例外日程的对应字段 |
+
+> 理由：例外已脱离原重复性日程独立存在，不会自动继承原日程的更新。
+
+## 删除全部
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<原重复日程ID>","need_notification":true}'` | 删除重复性日程本体 |
+| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 删除所有例外日程 |
+
+> 理由：例外是独立实体，删除原重复性日程不会级联删除例外。
+
+## 编辑此次及后续
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
+| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
+| 3 | `lark-cli calendar +create --summary ... --start <指定时间> --end ... --rrule "FREQ=..." --attendee-ids ...` | 从指定时间开始创建新的重复性日程（即「后续」部分，携带编辑后的内容） |
+
+> UNTIL 计算规则：若用户选择「从第 N 次开始编辑」，UNTIL 应设置为第 N-1 次实例的日期（即保留到指定时间之前的最后一次）。
+> 新日程应继承原日程的参会人、会议室等配置（除非用户明确要修改）。
+
+## 删除此次及后续
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
+| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
+
+> 与「编辑此次及后续」的区别：不需要步骤 3（创建新的重复性日程），因为目标是删除后续而非替换。
+
+## 仅此次
+
+- **编辑仅此次**：通过 `+agenda` / `+search-event` 定位到具体实例的 `event_id`，然后正常调用 `+update`。
+- **删除仅此次**：定位到具体实例的 `event_id`，调用 `events delete`。
+
+## 用户意图映射
+
+| 用户表达 | 操作范围 |
+|----------|----------|
+| 「改这个重复日程的标题」「全部改」「每次都改」 | 编辑全部 |
+| 「删掉这个重复日程」「取消所有」 | 删除全部 |
+| 「从下周开始改时间」「后面的都改」 | 编辑此次及后续 |
+| 「从下周开始不要了」「后面的都删」 | 删除此次及后续 |
+| 「就改这一次」「只删这一次」 | 仅此次 |
+| 未明确范围 | **必须询问用户** |
+
+## 注意事项
+
+- 涉及时间戳计算（如推算 UNTIL 日期）时，必须调用系统命令或脚本，禁止心算。
+
+## 参考
+
+- [lark-calendar](../SKILL.md) — 日历全部命令
+- [lark-calendar-update](lark-calendar-update.md) — 更新日程 Shortcut
+- [lark-calendar-create](lark-calendar-create.md) — 创建日程 Shortcut
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -43,7 +43,7 @@ lark-cli calendar +update \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程要先定位到目标实例的 `event_id`，不要直接使用原重复日程 ID |
+| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程请根据操作范围选择 ID，详见 [重复性日程操作规范](lark-calendar-recurring.md) |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用 `primary`） |
 | `--summary <text>` | 否 | 新日程标题。仅在显式传入 `--summary` 时更新；若传空字符串，会把标题清空 |
 | `--description <text>` | 否 | 新日程描述。目前 API 方式不支持编辑富文本描述；如果日程描述通过客户端编辑为富文本内容，则使用 API 更新描述会导致富文本格式丢失。仅在显式传入 `--description` 时更新；若传空字符串，会把描述清空 |
@@ -65,7 +65,7 @@ lark-cli calendar +update \
 - 只想修改标题、描述、时间或重复规则时，不需要同时传 `--add-attendee-ids` 或 `--remove-attendee-ids`。
 - 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。
 - 会议室是 resource attendee，必须使用 `omm_` ID 添加到参会人列表，不能脱离日程单独预定。
-- 更新重复性日程的某一次实例时，必须先通过 `+agenda`、`+search-event` 或实例视图定位该实例的 `event_id`。
+- 更新重复性日程时，必须先确定操作范围（仅此次/全部/此次及后续），然后按 [重复性日程操作规范](lark-calendar-recurring.md) 执行。
 - 如果需要验证更新结果，等待至少 2 秒后再查询，避免同步延迟导致读到旧数据。
 - 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。
 

skills/lark-doc/references/style/lark-doc-create-workflow.md

@@ -23,7 +23,7 @@
 1. 分析用户需求：受众、目的、范围
 2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
 3. `docs +create` 创建并撰写：
-   - **短文档**：一次写入完整内容
+   - **短文档**：一次写入完整内容。使用 Markdown 时，避免同时传入 `--title` 和同名 `# 标题`
    - **长文档**：先建骨架（标题 + 各级标题），再由主 Agent **顺序逐节**用 `block_insert_after --block-id <章节标题 block_id>` 补全正文；写完一节再写下一节，始终带着已写内容的上下文，保证衔接、不重复
    - ⚠️ 不要一次性把超长完整内容塞进 `--content`，容易触发字符/参数限制；长文按节分次写入
    - ⚠️ 同一节内多次插入时，要锚到**上一个新插入的 block**（按 [`lark-doc-update.md`](../lark-doc-update.md) 的「Block ID 生命周期」），否则反复锚同一个标题会让段落顺序颠倒
@@ -41,6 +41,7 @@
 7. **优先处理步骤二识别出的画板需求**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
 8. 由**主 Agent 自行润色**（不另起内容子 Agent，正文始终一人维护）：文字密集且不易读时，优先拆段、加小标题或调整顺序——叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）；只有确实存在行列数据时才用 `<table>`。其余富 block 的取舍一律遵循 `lark-doc-style.md` 的写作原则，不主动堆叠。需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用。本地图片使用 `docs +media-insert` 插入
 
-### 步骤四：专项校验（按需执行）
+### 步骤四：专项校验
 
-9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果
+9. **字数门禁**：如果用户给出任何明确字数要求（如“700-800 字”“1000 字左右”“不少于 500 字”“控制在 800 字以内”），本步骤必须执行，不属于按需项。读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；未得到脚本统计结果前，不得向用户声明“符合字数要求”。若没有明确字数要求，则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现目标区间、`word_count` 和达标结论
+10. **重复标题检查**：文档生成后，检查文档标题和正文第一个标题块是否重复；若重复，删除或改写正文第一个标题块，避免读者看到同一标题连续出现

skills/lark-drive/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-drive
 version: 1.0.0
-description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
+description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -22,7 +22,6 @@ metadata:
 
 - 用户要**复制文档 / 创建副本 / 另存为副本**时，使用 `lark-cli drive files copy`。先用 `lark-cli schema drive.files.copy --format json` 确认参数；如果来源是 wiki URL/token，先用 `lark-cli drive +inspect` 获取底层 `token` 和 `type`，不要把 wiki token 直接当 `file_token`。`params.file_token` 传源文档 token，`data.folder_token` 传目标文件夹 token，`data.name` 传副本名称，`data.type` 传源文件类型（如 `docx` / `sheet` / `bitable` / `slides`）。示例：`lark-cli drive files copy --params '{"file_token":"<DOC_TOKEN>"}' --data '{"folder_token":"<FOLDER_TOKEN>","name":"<COPY_NAME>","type":"docx"}'`。如返回 `confirmation_required`，按 `lark-shared` 高风险审批协议向用户确认后，在原命令末尾追加 `--yes` 重试。
 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要“权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
-- 用户要**查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置**，优先使用 `lark-cli drive +permission-get-setting`；它只读取目标自身设置，不递归审计文件夹子文档权限。裸 token 必须显式传 `--type`。
 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--created-by-me`，原始创建者语义）、"我负责/owner 的"（→ `--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
 - 用户要**根据文档评论定位正文位置**，例如 根据评论 review 文档、根据评论内容回看文档、区分多处相同引用文本时，对于 docx 类型（`file_type=docx`）的文档支持通过 `need_relation=true` 返回评论位置，其他类型暂不支持，具体用法需要先阅读 [`references/lark-drive-comment-location.md`](references/lark-drive-comment-location.md) 了解。
@@ -30,6 +29,7 @@ metadata:
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
+- 批量执行 `drive +import` 且目标是同一个位置（同一 `--folder-token`、默认根目录，或同一 `--target-token`）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
 - 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
 - 用户要比较原生 `.md` 文件的**历史版本差异**，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
 - 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
@@ -103,11 +103,11 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 | `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
 | `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable） |
+| `232140101` / `232140100` / `233523001`（常见于 `drive +import` 的 `job_error_msg`） | 同一位置下存在并发导入 / 创建操作 | 批量导入到同一文件夹、根目录或同一 `--target-token` 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突 |
 
 ### 权限能力入口
 
 - 用户要管理 Drive 文档/文件协作者、公开权限、授权当前应用访问文档，或处理 `permission.public.patch` 的 `91009` / `91010` / `91011` / `91012` 错误时，先读 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。
-- 用户要查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置，使用 [`+permission-get-setting`](references/lark-drive-permission-get-setting.md)；如果要递归审计文件夹下子文档权限，再进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
 - 用户只是没有访问权限并希望向 owner 申请访问，优先使用 [`+apply-permission`](references/lark-drive-apply-permission.md)。
 - 普通 scope、身份或登录问题仍按 [`lark-shared`](../lark-shared/SKILL.md) 处理；不要把租户安全策略、对外分享、密级拦截简单归类为缺 scope。
 
@@ -150,7 +150,6 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+inspect`](references/lark-drive-inspect.md) | 检视 URL 的类型、标题和 canonical token；wiki URL 会自动解包到底层文档。 |
 | [`+apply-permission`](references/lark-drive-apply-permission.md) | 以 user 身份向文档 owner 申请访问权限。 |
 | [`+member-add`](references/lark-drive-member-add.md) | 添加一个或最多 10 个 Drive 文档、文件、文件夹或 wiki 节点协作者/授权成员；封装 Drive permission member create/batch_create，真实写入需要 `--yes`。 |
-| [`+permission-get-setting`](references/lark-drive-permission-get-setting.md) | 查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置；支持 URL 或裸 token + `--type`；不递归读取文件夹子文档权限。 |
 | [`+secure-label-list`](references/lark-drive-secure-label.md) | 列出当前用户可用的密级标签。 |
 | [`+secure-label-update`](references/lark-drive-secure-label.md) | 更新 Drive 文件或文档的密级标签。 |
 

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

@@ -14,6 +14,13 @@
 > [!IMPORTANT]
 > 当用户**未传 `--name`** 时，文档标题默认取源文件名（去掉扩展名）。在执行导入前，先友好提示用户：「当前未指定文档标题，默认将使用"xxx"作为标题。如果文件内容中也包含相同标题，导入后可能造成视觉重复。是否需要重命名？」让用户确认后再继续。
 
+## 批量导入串行规则
+
+> [!IMPORTANT]
+> 批量执行 `drive +import` 且目标是同一个位置时，必须串行执行，不要并发发起导入任务。这里的“相同位置”包括同一个 `--folder-token`、都省略 `--folder-token` 导入到默认根目录，或使用同一个 `--target-token` 导入到已有 bitable。
+>
+> 如果在同一位置下并发导入，服务端可能返回并发冲突错误。看到错误信息或 `job_error_msg` 中包含 `232140101`、`232140100`、`233523001` 任一错误码时，按同位置并发操作处理：停止并发导入，改为串行处理失败项；每个失败项每次重试前等待几秒，总共最多重试 3 次；仍失败就停止并向用户报告冲突。
+
 ## 命令
 
 ```bash
@@ -143,6 +150,7 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
 - “超过 20MB 自动切换分片上传”只表示上传链路会切到 multipart，不代表所有格式都允许导入超过 20MB 的文件。
 
 - 若导入任务执行失败，会返回失败时的 `job_status` 及错误信息。
+- 若导入失败信息包含 `232140101`、`232140100`、`233523001`，通常表示同一位置下存在并发导入 / 创建操作；批量场景请改为串行执行，每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突。
 - 若内置轮询超时但任务仍在处理中，shortcut 会成功返回，并带上：
   - `ready=false`
   - `timed_out=true`

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

@@ -15,9 +15,10 @@
 | `summary.skipped` | 因 `--if-exists=skip` 或 `--if-exists=smart` 命中“无需传输”而跳过的文件数 |
 | `summary.failed` | 上传 / 覆盖 / 建目录 / 删除失败的条目数；**只要不为 0，命令就以非零状态退出**（结构化 `items[]` 仍在 stdout 上） |
 | `summary.deleted_remote` | 启用 `--delete-remote --yes` 时删除的云端文件数 |
-| `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error`） |
+| `summary.aborted` | 命中终止性错误并停止后续批处理时为 `true` |
+| `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error` / `hint` / `phase` / `error_class` / `code` / `subtype` / `retryable`） |
 
-`items[].action` 取值：`uploaded` / `overwritten` / `skipped` / `folder_created` / `deleted_remote` / `failed` / `delete_failed`。
+`items[].action` 取值：`uploaded` / `overwritten` / `skipped` / `folder_created` / `deleted_remote` / `already_deleted` / `failed` / `delete_failed`。
 
 > 本地目录（包括空目录）会被镜像到 Drive；新建的子目录会以 `action: "folder_created"` 出现在 `items[]` 里，但**不计入** `summary.uploaded`（该字段只数文件）。已存在的远端目录复用其 token，不会重复 `create_folder`，也不会出现在 `items[]` 里。
 
@@ -95,6 +96,7 @@ 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` 的对齐域。
@@ -110,22 +112,46 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
     "uploaded": 0,
     "skipped": 0,
     "failed": 0,
-    "deleted_remote": 0
+    "deleted_remote": 0,
+    "aborted": false
   },
   "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": "..."},
+    {"rel_path": "...",                       "action": "failed",        "size_bytes": 0, "error": "...", "hint": "...", "phase": "upload", "error_class": "...", "code": 0, "subtype": "...", "retryable": false},
     {"rel_path": "...", "file_token": "...", "action": "deleted_remote"},
-    {"rel_path": "...", "file_token": "...", "action": "delete_failed",  "error": "..."}
+    {"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` 始终用 `/` 作为分隔符（跨平台一致）。
 
+## 失败处理与 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-drive/references/lark-drive-workflow-permission-governance-commands.md

@@ -15,8 +15,6 @@
 lark-cli drive +inspect --url '<url>' --as user --format json
 ```
 
-`drive +inspect` 不支持 Drive folder。`/drive/folder/<folder_token>` 直接解析为 `type=folder` + `token=<folder_token>`；需要读取文件夹自身权限设置时使用 `drive +permission-get-setting --token '<folder_token>' --type folder`。
-
 `/wiki/space/<space_id>` URL 是 Wiki space 范围，不要用 `drive +inspect` 当作单文档解析；直接提取 `space_id` 后进入 `DISCOVER_TARGETS`。
 
 ## 目标发现
@@ -63,27 +61,11 @@ lark-cli drive metas batch_query \
   --as user --format json
 ```
 
-读取权限设置：
+读取 public permission：
 
 ```bash
-lark-cli drive +permission-get-setting \
-  --token '<url-or-token>' --type '<type>' \
-  --as user --format json
-```
-
-裸 folder token 必须显式传 `--type folder`：
-
-```bash
-lark-cli drive +permission-get-setting \
-  --token '<folder_token>' --type folder \
-  --as user --format json
-```
-
-通过 URL 读取权限设置时可以省略 `--type`：
-
-```bash
-lark-cli drive +permission-get-setting \
-  --token '<url>' \
+lark-cli drive permission.public get \
+  --params '{"token":"<token>","type":"<type>"}' \
   --as user --format json
 ```
 

skills/lark-drive/references/lark-drive-workflow-permission-governance-outputs.md

@@ -27,7 +27,7 @@
 - 多目标明确列表默认输出逐目标诊断摘要；不要因为目标数大于 1 就套用容器递归发现报告。
 - 用户可见结论默认跟随用户当前语言。用户用中文提问时输出中文，用户用英文提问时输出英文；混合语言时跟随主要语言。
 - 单目标公开性判断默认输出业务表达，不直接展示 `link_share_entity`、`external_access_entity`、`external_access` 等底层字段名；只有用户要求 raw evidence、排障，或完整清单 / artifact 场景才展示底层字段。
-- 中文用户可见输出中，`permission_public` / `public permission` 默认译为“目标公共访问和协作权限设置”；可在摘要里简称“公共访问与协作设置”。优先按实际返回字段解释公开访问、分享、协作者管理、安全与评论设置；复制内容、创建副本、打印、下载等字段只有在当前 CLI schema 和实际响应返回时才可判断。只有命令名、schema 字段、raw evidence、排障信息和完整 artifact 字段名保留英文原文。
+- 中文用户可见输出中，`permission_public` / `public permission` 默认译为“文档公共访问和协作权限设置”；可在摘要里简称“公共访问与协作设置”。它在官方语义中包含链接分享、对外分享、协作者管理、复制内容、创建副本、打印、下载和评论；具体可判断字段以当前 CLI schema 和实际响应为准。只有命令名、schema 字段、raw evidence、排障信息和完整 artifact 字段名保留英文原文。
 - 容器目标默认输出安全诊断报告摘要：一句话结论、覆盖情况、风险分级、优先处理对象、建议下一步和剩余限制。
 - 容器目标不要把风险按数量机械排序；外部公开、允许对外分享、缺失密级标签优先于复制 / 下载 / 评论这类依赖策略的候选项。
 - 用户没有提供明确 policy 时，使用“候选风险 / 待复核 / 待策略确认”，不要写“违规 / 已泄露 / 已外部访问”。
@@ -36,7 +36,7 @@
 - 当摘要未展示全部风险对象时，必须明确“完整清单包含 <count> 条”，并提供生成 Markdown / CSV / 飞书文档风险清单或整改 dry-run 的下一步。
 - 只要发现需要处理的对象，最终回复必须给出可执行下一步 CTA。不能因为默认只读，就只报告风险后结束。
 - 完整风险清单是后续治理选择的输入；Markdown / CSV / 飞书文档报告必须使用同一套字段和稳定 `risk_id`。
-- 写入前必须使用确认模板；权限申请、目标公共访问和协作权限设置修改、owner 转移、密级标签更新分别确认。
+- 写入前必须使用确认模板；权限申请、文档公共访问和协作权限设置修改、owner 转移、密级标签更新分别确认。
 - 最终回复必须包含已完成事项、验证结果和剩余限制；异步权限申请审批不能表述为已完成授权。
 
 ## Semantic Rendering
@@ -75,7 +75,7 @@
 | `lock_switch=true` | `lock_state=locked_not_inheriting` | 已限制权限，不再继承父级页面权限 | The node is locked and no longer inherits parent-page permissions |
 | `lock_switch=false` | `lock_state=not_locked_or_inheriting` | 未限制权限，可能继承父级页面权限 | The node is not locked and may inherit parent-page permissions |
 | field absent / unsupported | `<state>=unknown` | 当前 schema 未返回，无法判断 | The current schema did not return this field, so it is unknown |
-| `check_scope=current_public_permission_only` | `check_scope=current_public_permission_only` | 本次判断的是当前目标公共访问和协作权限设置，不是协作者名单或历史权限变更审计 | This check covers the target's current public access and collaboration settings, not collaborator-list or historical permission-change auditing |
+| `check_scope=current_public_permission_only` | `check_scope=current_public_permission_only` | 本次判断的是当前文档公共访问和协作权限设置，不是协作者名单或历史权限变更审计 | This check covers current public access and collaboration settings, not collaborator-list or historical permission-change auditing |
 | `sec_label_name` missing | `sec_label=missing` | 缺少密级标签 | Security label is missing |
 
 ## 定位与治理动作
@@ -165,7 +165,7 @@ Evidence fields:
 
 覆盖情况：
 - 用户提供目标：<input_target_count>；成功解析：<resolved_count>
-- 成功读取目标公共访问和协作权限设置：<permission_checked_count>；读取失败 / 不支持 / 无权限：<failed_or_unsupported_count>
+- 成功读取文档公共访问和协作权限设置：<permission_checked_count>；读取失败 / 不支持 / 无权限：<failed_or_unsupported_count>
 
 逐目标结果（1-10 个目标默认全部展示；超过 10 个时按 `摘要清单展开规则` 展示，并提示生成完整风险清单）：
 
@@ -233,7 +233,7 @@ URL：<url-or-token-if-url-unavailable>
 
 覆盖情况：
 - 当前身份可见目标：<visible_count>
-- 已成功检查目标公共访问和协作权限设置：<permission_checked_count>
+- 已成功检查文档公共访问和协作权限设置：<permission_checked_count>
 - 读取失败 / 已删除 / 无权限：<failed_count>
 - 未覆盖能力：<collaborator_list / inheritance / audit_log / view_records / none>
 
@@ -355,8 +355,8 @@ Agent 必须回复：
 - 字段变更：
   - <risk_id> <path> (<url-or-token>): <field> <old> -> <new>
 - 跳过项：<unsupported / no manage_public / unsupported type / missing policy>
-- 验证方式：执行后重新读取 <元数据 / 目标公共访问和协作权限设置>
-- 有限回滚范围：<目标公共访问和协作权限设置快照字段 / 不适用>
+- 验证方式：执行后重新读取 <元数据 / 文档公共访问和协作权限设置>
+- 有限回滚范围：<文档公共访问和协作权限设置快照字段 / 不适用>
 
 请确认是否进入写入确认。
 ```
@@ -407,8 +407,8 @@ Agent 必须回复：
 - 风险：<risk_level>
 - 字段变更：
   - <field>: <old> -> <new>
-- 验证方式：执行后重新读取 <元数据 / 目标公共访问和协作权限设置>
-- 有限回滚材料：<目标公共访问和协作权限设置快照 / 不适用>
+- 验证方式：执行后重新读取 <元数据 / 文档公共访问和协作权限设置>
+- 有限回滚材料：<文档公共访问和协作权限设置快照 / 不适用>
 
 请确认是否执行。
 ```
@@ -419,6 +419,6 @@ Agent 必须回复：
 已完成：<read checks / writes>
 验证：<fresh read result or async permission-request approval note>
 清单状态：<risk_id status updates / not applicable>
-回滚材料：<目标公共访问和协作权限设置快照 / 不适用>
+回滚材料：<文档公共访问和协作权限设置快照 / 不适用>
 剩余限制：<unsupported_checks / partial facts / approvals>
 ```

skills/lark-drive/references/lark-drive-workflow-permission-governance.md

@@ -38,7 +38,7 @@ Risk / Structure: `R2` / `S2`
 - 目录组织、迁移、归档或清理；这类需求应使用知识整理 workflow。
 - 内容审查、过期内容判断或知识质量评分。
 - backup owner 补充、部门 / 项目负责人绑定、协作者创建 / 撤销、成员列表审计；本 workflow 只支持把 owner 转移给每个目标明确指定的新 owner，不建模 backup owner 或负责人绑定关系。
-- 文件夹自身公开权限审计或修复。文件夹自身权限设置可以用 `drive +permission-get-setting` 读取；写入是否支持必须以运行时 schema 和明确需求为准，不能猜测执行 `patch type=folder`。
+- 文件夹自身公开权限审计或修复。`drive permission.public get` / `patch` 不支持 `type=folder`；必须记录到 `unsupported_checks`，然后继续读取文件夹下其他支持的文档事实。
 - 当前身份无法枚举到的不可见文档的完整发现；只能处理已发现目标，或用户显式提供的 URL / token。
 - 未按范围确认的批量写入。
 
@@ -53,7 +53,7 @@ Risk / Structure: `R2` / `S2`
 | `PARSE_INTENT` | 本文件、[`lark-drive-workflow.md`](lark-drive-workflow.md)、[`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) |
 | `TARGET_INSPECT` | [`lark-drive-inspect.md`](lark-drive-inspect.md) |
 | `DISCOVER_TARGETS` | 容器范围时读取 [`../../lark-wiki/references/lark-wiki-node-list.md`](../../lark-wiki/references/lark-wiki-node-list.md) 或 [`lark-drive-files-list.md`](lark-drive-files-list.md) |
-| `FACT_READ` | `lark-cli schema drive.metas.batch_query`；涉及权限设置读取时使用 `drive +permission-get-setting`；涉及活跃度、访问复核或生命周期判断时再读取 `lark-cli schema drive.file.statistics.get` 和 `lark-cli schema drive.file.view_records.list` |
+| `FACT_READ` | `lark-cli schema drive.metas.batch_query`；涉及公开权限时再读取 `lark-cli schema drive.permission.public.get`；涉及活跃度、访问复核或生命周期判断时再读取 `lark-cli schema drive.file.statistics.get` 和 `lark-cli schema drive.file.view_records.list` |
 | `RISK_ASSESS` | 本文件的 `Risk Classification` |
 | `EXEC_CONFIRM` | 只为用户选择的动作读取 [`lark-drive-apply-permission.md`](lark-drive-apply-permission.md)、[`lark-drive-secure-label.md`](lark-drive-secure-label.md)，或 `lark-cli schema drive.permission.public.patch` / `lark-cli schema drive.permission.members.transfer_owner`；需要确认模板时读取 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) |
 | `EXECUTE` | 复用 `EXEC_CONFIRM` 已加载且已确认的写命令上下文 |
@@ -76,9 +76,9 @@ Risk / Structure: `R2` / `S2`
 | State | Protocol Step | Agent MUST Do | User-Facing Output | wait_for_user | Next State |
 |-------|---------------|---------------|--------------------|---------------|------------|
 | `PARSE_INTENT` | `route` / `scope` | 解析 intent、target scope、desired policy，以及只读审计、单目标公开性判断、权限申请、owner 转移还是修复模式；单目标公开性判断设置 `intent=public_exposure_check`、`target_scope=single_resource` | 范围确认；如果缺少目标、新 owner 或期望动作，只问一个澄清问题 | 缺少 target / new owner / action，或容器范围需要用户确认时为 `true` | `TARGET_INSPECT` |
-| `TARGET_INSPECT` | `scope` | 解析单资源、明确列表、Wiki space / node、Drive folder；Drive folder 直接从 URL 路径或显式 `type=folder` 解析，不调用 `drive +inspect`；保留原始 URL、scope type、canonical token/type | 目标范围表，包含 scope、title/type/token status | 除非解析失败，否则为 `false` | `DISCOVER_TARGETS` or `FACT_READ` |
+| `TARGET_INSPECT` | `scope` | 解析单资源、明确列表、Wiki space / node、Drive folder；保留原始 URL、scope type、canonical token/type | 目标范围表，包含 scope、title/type/token status | 除非解析失败，否则为 `false` | `DISCOVER_TARGETS` or `FACT_READ` |
 | `DISCOVER_TARGETS` | `scope` / `read` | 对 Wiki space / node 或 Drive folder 递归只读枚举，归一化为 `discovered_targets`；记录 `discovery_blockers` | 发现进度和覆盖摘要；不展示内部 cursor/token，除非用户要求 | 除非发现范围无法确认或全部被阻断，否则为 `false` | `FACT_READ` |
-| `FACT_READ` | `read` | 对直接目标或 `discovered_targets` 执行 `drive metas batch_query`；对支持的文件、文件夹或云文档目标执行 `drive +permission-get-setting` 读取自身权限设置；当 `intent=public_exposure_check` 且 `target_scope=single_resource` 时，可复用 `drive +inspect` 返回的 title / URL / type，只补读目标公共访问和协作权限设置；在用户要求活跃度 / 访问复核 / 生命周期判断时读取访问统计和访问记录 | 权限事实摘要、coverage summary、activity facts 和 unsupported checks | 除非所有目标都被 auth 阻断，否则为 `false` | `RISK_ASSESS` |
+| `FACT_READ` | `read` | 对直接目标或 `discovered_targets` 执行 `drive metas batch_query`；对支持的非 folder 目标执行 `drive permission.public get`；当 `intent=public_exposure_check` 且 `target_scope=single_resource` 时，可复用 `drive +inspect` 返回的 title / URL / type，只补读文档公共访问和协作权限设置；在用户要求活跃度 / 访问复核 / 生命周期判断时读取访问统计和访问记录 | 权限事实摘要、coverage summary、activity facts 和 unsupported checks | 除非所有目标都被 auth 阻断，否则为 `false` | `RISK_ASSESS` |
 | `RISK_ASSESS` | `assess/plan` | 对每个可审计目标生成 `per_target_permission_assessment` 并分类证据；如用户提供 policy，则对照 policy；`public_exposure_check + single_resource` 只渲染单目标结论，不生成 `risk_id`；owner 转移路径生成 `owner_transfer_candidates` / `owner_transfer_plan`；治理路径构建可定位风险清单、访问复核清单、dry-run 整改计划或候选修复计划，完整清单必须生成稳定 `risk_id` | 带 priority、URL、risk_id、owner、sec_label 的 findings、confidence、review items、建议动作和下一步 CTA；单目标公开性判断只输出结论和关键字段 | 治理路径为 `true`，单目标公开性判断为 `false` | `EXEC_CONFIRM` or `DONE` |
 | `EXEC_CONFIRM` | `confirm` | 展示准确写入范围、command family、target count、risk、verification method | 确认请求 | `true` | `EXECUTE` or `DONE` |
 | `EXECUTE` | `execute` | 只执行 `Command Map` 中已确认的写入 | 进度 / 结果摘要 | 除非被阻断，否则为 `false` | `VERIFY` |
@@ -91,21 +91,21 @@ Risk / Structure: `R2` / `S2`
 
 | State | Allowed Command Families | Purpose |
 |-------|--------------------------|---------|
-| `TARGET_INSPECT` | `drive +inspect` | 解析非 folder URL、type、canonical token、title 和 wiki unwrap data；Drive folder 不支持 `+inspect`，必须从 URL 路径或显式 `type=folder` 直接解析 |
+| `TARGET_INSPECT` | `drive +inspect` | 解析 URL、type、canonical token、title 和 wiki unwrap data |
 | `DISCOVER_TARGETS` | `wiki +node-list` | 递归发现 Wiki space / node 下当前身份可见的节点 |
 | `DISCOVER_TARGETS` | `drive files list` | 递归发现 Drive folder 下当前身份可见的文件和子文件夹 |
 | `FACT_READ` | `drive metas batch_query` | 读取 title、URL、owner 和 secure-label metadata |
-| `FACT_READ` | `drive +permission-get-setting` | 读取支持类型的文件、文件夹或云文档自身权限设置，包括公开访问、分享、协作者管理、安全与评论 |
+| `FACT_READ` | `drive permission.public get` | 读取支持类型的文档公共访问和协作权限设置，包括链接分享、对外分享、协作者管理、复制内容、创建副本、打印、下载和评论 |
 | `FACT_READ` | `drive file.statistics get` | 在用户要求活跃度、闲置暴露、生命周期或访问复核时读取文件访问统计 |
 | `FACT_READ` | `drive file.view_records list` | 在用户要求最近访问人、访问复核或低活跃证据时读取访问记录 |
 | `EXEC_CONFIRM` | `drive +secure-label-list` | 提议 label update 前解析可用 secure-label IDs |
-| `EXEC_CONFIRM` | `drive permission.members auth` | 目标公共访问和协作权限设置修改前检查 `action=manage_public` |
+| `EXEC_CONFIRM` | `drive permission.members auth` | 文档公共访问和协作权限设置修改前检查 `action=manage_public` |
 | `EXEC_CONFIRM` | `lark-cli schema drive.permission.members.transfer_owner` | owner 转移前读取当前字段、支持类型和高风险写入门禁 |
 | `EXECUTE` | `drive +apply-permission` | 向 owner 提交 view/edit access request；只允许单目标、小列表或已明确确认的候选列表逐个执行 |
 | `EXECUTE` | `drive permission.public patch` | 修改已确认的 public/link settings；必须传 `--yes` |
 | `EXECUTE` | `drive permission.members transfer_owner` | 转移已确认目标的 owner；必须传 `--yes` |
 | `EXECUTE` | `drive +secure-label-update` | 设置已确认的 secure-label ID |
-| `VERIFY` | `drive metas batch_query`, `drive +permission-get-setting` | 验证支持的 metadata，包括 owner、secure-label 和目标公共访问与协作权限设置变更；权限申请只能表述为已发起 |
+| `VERIFY` | `drive metas batch_query`, `drive permission.public get` | 验证支持的 metadata，包括 owner、secure-label 和文档公共访问与协作权限设置变更；权限申请只能表述为已发起 |
 
 ## Command Patterns
 
@@ -119,9 +119,9 @@ Risk / Structure: `R2` / `S2`
 
 1. "所有文档"只表示当前身份在确认范围内可枚举到的文档。不可见、无权限、API 不返回或工具预算不足的部分必须进入 `discovery_blockers` 或 `unsupported_checks`。
 2. 发现阶段必须生成稳定 `path`。不要只保存 title；同名文档必须能通过 path 或 token 区分。
-3. 权限设置读取使用 `drive +permission-get-setting`，目标类型包括 `doc`、`sheet`、`file`、`wiki`、`bitable`、`docx`、`mindnote`、`minutes`、`slides`、`folder`；未来新增类型以 shortcut 和 OpenAPI 元数据为准。
+3. 只把 `drive.permission.public.get` 当前 schema 支持的类型加入公开权限可审计目标。已知支持包括 `doc`、`sheet`、`file`、`wiki`、`bitable`、`docx`、`mindnote`、`minutes`、`slides`；未来新增类型以运行时 schema 为准。
 4. `minutes` 只能作为 `partial_public_permission` 目标：可读取 / 修改公开权限和 owner 转移能力以运行时 schema 为准，但 `drive metas batch_query` 当前不支持 `minutes`，URL、owner、密级等 metadata 可能进入 `unsupported_checks`。
-5. `folder` 作为递归容器时先枚举子资源；如用户明确要查询文件夹自身权限设置，可对该文件夹单独执行 `drive +permission-get-setting --token <folder_token> --type folder`。不要执行 raw `permission.public patch type=folder`，除非 schema 和需求都明确支持。`shortcut`、`catalog` 或缺少 stable token/type 的条目必须记录为 unsupported，除非后续 API 明确解析出支持目标。
+5. `folder` 只作为递归容器，不执行 `permission.public get` / `patch`。如果用户明确要求 owner 转移且 schema 支持 `folder`，必须按 owner-transfer 写入规则单独确认。`shortcut`、`catalog` 或缺少 stable token/type 的条目必须记录为 unsupported，除非后续 API 明确解析出支持目标。
 6. 对大范围目标输出进度时，只展示已扫描容器数、已发现目标数、已审计目标数、剩余队列或 blocker；不要默认展示内部 page token / cursor。
 
 Wiki space / node 发现：
@@ -133,7 +133,7 @@ Wiki space / node 发现：
 
 Drive folder 发现：
 
-1. `/drive/folder/<folder_token>` 解析为 `target_scope=drive_folder`。默认继续枚举其子文档；只有用户明确要求文件夹自身权限设置时，才额外调用 `drive +permission-get-setting --token <folder_token> --type folder` 读取该文件夹自身设置。
+1. `/drive/folder/<folder_token>` 解析为 `target_scope=drive_folder`。文件夹自身公开权限不支持；继续枚举其子文档。
 2. 按 [`lark-drive-files-list.md`](lark-drive-files-list.md) 递归处理 `data.files`、`has_more` 和 `next_page_token`。不要把第一页数量当作完整范围。
 3. 只对返回项中的 `folder` 继续递归；对子文档按 `type + token` 归一化为 `discovered_targets`。
 4. 如果某个目录分页失败、无 continuation token、权限不足或 API 报错，只阻断该目录分支，并在 `discovery_blockers` 中记录；继续处理其他可枚举分支。
@@ -141,11 +141,11 @@ Drive folder 发现：
 ## Fact Read Rules
 
 1. `drive metas batch_query` 单次最多 200 个 `request_docs`；当 `targets` 或 `discovered_targets` 超过 200 个时，必须分批读取并合并结果。
-2. `drive +permission-get-setting` 没有批量读取接口；对支持目标逐个读取。单个目标失败时记录 `unsupported_checks` 或 `partial`，不要阻断其他目标。
+2. `drive permission.public get` 没有批量读取接口；对支持目标逐个读取。单个目标失败时记录 `unsupported_checks` 或 `partial`，不要阻断其他目标。
 3. 对 Wiki 发现目标，公开权限读取优先使用 `type=wiki` + `node_token`；metadata 可使用 `obj_type` + `obj_token` 补充 title、owner、URL 和 `sec_label_name`。
 4. 当 intent 是 `list_permission_settings` 时，只输出权限设置清单和覆盖限制，不主动生成修复计划。
 5. 单目标、多目标明确列表和容器发现目标都必须复用同一套逐目标事实读取与语义归一逻辑；差异只体现在目标来源、coverage summary 和输出聚合。
-6. `permission_public` 用户可见含义是“目标公共访问和协作权限设置”，语义以官方 OpenAPI 字段说明为准，同时兼容当前 CLI schema 返回的字段：优先使用 `external_access_entity`，缺失时才用 `external_access` boolean 映射为 `open` / `closed`；`manage_collaborator_entity`、`copy_entity`、`lock_switch` 等字段缺失时标记为 unknown，不要伪造；未识别字段保留在 raw evidence / partial note 中。
+6. `permission_public` 用户可见含义是“文档公共访问和协作权限设置”，语义以官方 OpenAPI 字段说明为准，同时兼容当前 CLI schema 返回的字段：优先使用 `external_access_entity`，缺失时才用 `external_access` boolean 映射为 `open` / `closed`；`manage_collaborator_entity`、`copy_entity`、`lock_switch` 等字段缺失时标记为 unknown，不要伪造；未识别字段保留在 raw evidence / partial note 中。
 7. `drive file.statistics get` 和 `drive file.view_records list` 只在用户要求最近访问、活跃度、闲置暴露、访问复核，或用户提供的 policy 明确依赖活跃度时执行；不要为普通权限审计默认读取访问记录。
 8. 访问统计 / 访问记录当前只对 `doc`、`docx`、`sheet`、`bitable`、`mindnote`、`wiki`、`file` 作为支持类型处理。其他类型必须进入 `unsupported_checks`，不能推断活跃度。
 9. `view_records` 是访问证据，不是权限列表。没有返回访问记录只能表述为“未获得最近访问证据”或“低活跃候选”，不能表述为“无人有权限”。
@@ -162,17 +162,17 @@ Drive folder 发现：
 - `PolicyReview`：复制、创建副本、打印、下载、评论等依赖 policy 的设置；没有明确 policy 时不要称为高风险。
 - `Unknown`：读取失败、已删除、无权限、API 不支持、协作者名单 / 继承链 / DLP / AI 索引 / 审计日志未覆盖。
 
-每个可审计目标都必须先归一化为 `per_target_permission_assessment`，再按 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) 的 `Semantic Rendering` 渲染。`public_exposure_check` 只是 `target_count=1` 的轻量渲染模式；它和多目标、容器诊断复用同一套语义字段与风险分类。该判断只覆盖当前目标公共访问和协作权限设置，不审计协作者名单、历史权限变更、完整继承链或审计日志。
+每个可审计目标都必须先归一化为 `per_target_permission_assessment`，再按 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) 的 `Semantic Rendering` 渲染。`public_exposure_check` 只是 `target_count=1` 的轻量渲染模式；它和多目标、容器诊断复用同一套语义字段与风险分类。该判断只覆盖当前文档公共访问和协作权限设置，不审计协作者名单、历史权限变更、完整继承链或审计日志。
 
 `AI 检索暴露候选风险` 只是基于权限和标签的代理标签。除非另有工具明确返回索引状态，否则不要声称某个文档已经被 Agent、Copilot 或 RAG 索引。
 
 ## 写入规则
 
-- 目标公共访问和协作权限设置修改（`drive permission.public patch`）属于高风险写入。请求确认前，必须展示 target title、token、current setting、desired setting 和准确 field changes。
+- 文档公共访问和协作权限设置修改（`drive permission.public patch`）属于高风险写入。请求确认前，必须展示 target title、token、current setting、desired setting 和准确 field changes。
 - 如果 `manage_public_auth.auth_result=false`，禁止 patch。告诉用户需要具备 manage-public 权限的用户，或由 owner 操作。
-- 权限设置读取使用 `drive +permission-get-setting`；裸 token 必须传 `--type`，URL 可以自动推断。写入仍使用 `drive permission.public patch`，只 patch 已解析且 schema 明确支持的类型和字段，不要把读取支持的 `folder` 自动外推为可写入。
+- `drive permission.public get` 只用于 `drive +inspect` 或 `DISCOVER_TARGETS` 可解析且运行时 schema 支持的目标类型；类型集合不要硬编码，执行时以 `lark-cli schema drive.permission.public.get` 为准。
 - 不要 patch 已解析类型不支持的字段。对于 wiki 目标，必须省略 schema 明确标注为 wiki 不支持的字段。
-- 不要在同一个写入确认中合并密级标签更新和目标公共访问与协作权限设置修改；必须分别确认。
+- 不要在同一个写入确认中合并密级标签更新和文档公共访问与协作权限设置修改；必须分别确认。
 - `drive +apply-permission` 默认不批量执行；每次调用都会向 owner 发送通知。
 - `permission_request_candidates` 可以来自用户直接提供的目标、明确列表或容器发现目标；只要能构造 token、type、权限类型和申请理由，就可以进入候选。不要因为目标不在 `discovered_targets` 中而拒绝单目标 / 小列表权限申请。
 - 容器范围内的"统一申请权限"必须先产出 `permission_request_candidates`。未展示候选目标、数量、权限类型和 owner 通知影响前，禁止调用 `drive +apply-permission`。
@@ -182,8 +182,8 @@ Drive folder 发现：
 - 批量 owner 转移必须逐个顺序执行；失败项进入结果清单，不要重复执行已成功目标。`remove_old_owner=true` 或 `old_owner_perm` 降权必须单独在确认中高亮。
 - 用户要求“生成整改方案 / dry-run / 先看看会改什么”时，只生成 `remediation_plan`，不执行任何写命令。dry-run 必须包含 target count、field changes、跳过原因、验证方式和有限回滚范围。
 - 用户基于完整风险清单选择对象时，必须先解析 `risk_id`、风险分组、URL 或 artifact 中 `selected=true` 的行，生成 `selected_risk_items`。无法匹配到当前 `risk_manifest` 的选择必须要求用户重新确认或重新读取清单。
-- 针对 `selected_risk_items` 生成 dry-run 前，必须重新读取所选目标的 `drive +permission-get-setting`；如果当前设置和清单快照不同，标记为 `changed_since_report` 并跳过或要求用户确认更新后的计划。
-- 执行 `drive permission.public patch` 前，必须把当前 `public_permission_facts` 中会被改动的字段保存为 `public_permission_snapshots`。该快照只用于目标公共访问和协作权限设置字段的有限回滚说明，不覆盖协作者、owner、继承权限或密级标签。
+- 针对 `selected_risk_items` 生成 dry-run 前，必须重新读取所选目标的 `drive permission.public get`；如果当前设置和清单快照不同，标记为 `changed_since_report` 并跳过或要求用户确认更新后的计划。
+- 执行 `drive permission.public patch` 前，必须把当前 `public_permission_facts` 中会被改动的字段保存为 `public_permission_snapshots`。该快照只用于文档公共访问和协作权限设置字段的有限回滚说明，不覆盖协作者、owner、继承权限或密级标签。
 - 如果用户要求批量收紧权限，必须按风险分层和目标顺序逐个执行；失败项进入结果清单，不要因为单个失败而重复执行已成功目标。
 - 遇到 secure-label downgrade error `1063013` 时，停止重试，并告诉用户需要在文档 UI 中完成审批。
 

skills/lark-markdown/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-markdown
-version: 1.2.1
+version: 1.2.2
 description: "飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。"
 metadata:
   requires:
@@ -25,7 +25,8 @@ 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`、`version limit` 时，默认停止重试并按报错 hint 处理；只有 `rate limit` 或临时网络错误才做有限重试。
+- `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` 试错。
 
 ## 核心边界
 

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

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

@@ -146,6 +146,24 @@ lark-cli update
 
 **重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
 
+## JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同：
+
+成功信封写入 **stdout**（退出码 0）：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**（退出码非 0）：
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+**判断成功必须用 `ok == true`（或进程退出码 0），不要用 `code == 0`**：成功信封没有顶层 `code` / `msg` 字段，`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。按 OpenAPI 老格式 `{"code": 0, "msg": "ok"}` 判断会把所有成功调用误判为失败；封装写入类命令（如 `task +create`）时尤其危险，误判会绕过幂等逻辑导致重复创建。
+
 ## 安全规则
 
 - **禁止输出密钥**（appSecret、accessToken）到终端明文。

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

@@ -46,7 +46,20 @@ lark-cli task +create --summary "Test Task" --dry-run
 1. Confirm with the user: task summary, due date, assignee, and tasklist if necessary.
    - **Crucial Rule for Assignee**: If the user explicitly or implicitly says "create a task for me" (给我创建一个任务), or "help me create a task" (帮我新建/创建一个任务), you MUST assign the task to the current logged-in user. You can get the current user's `open_id` by executing `lark-cli auth status` (it already outputs JSON by default, so do not add `--json`) or `lark-cli contact +get-user` first, extracting `.identities.user.openId` (from `auth status`) or `.data.user.open_id` (from `contact +get-user`), and then passing it to the `--assignee` parameter.
 2. Execute `lark-cli task +create --summary "..." ...`
-3. Report the result: task ID and summary.
+3. Judge success by `ok == true` in the stdout JSON (the success envelope has no `code` field — do not test `code == 0`), then report the result: task ID (`data.guid`) and summary.
+
+Example success response:
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "guid": "e297d3d0-4b60-4a5f-a4d4-xxxxxxxxxxxx",
+    "url": "https://applink.larkoffice.com/client/todo/detail?guid=e297d3d0-4b60-4a5f-a4d4-xxxxxxxxxxxx"
+  }
+}
+```
 
 > [!CAUTION]
 > This is a **Write Operation** -- You must confirm the user's intent before executing.

skills/lark-wiki/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-wiki
-version: 1.0.1
+version: 1.0.2
 description: "飞书知识库：管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。当用户给出 doubao.com 的 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：上传文件到知识库节点下（走 lark-drive）、编辑文档/表格/Base 内容（走 lark-doc / lark-sheets / lark-base）。"
 metadata:
   requires:
@@ -34,6 +34,8 @@ 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,6 +11,9 @@ 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
 
@@ -31,8 +34,8 @@ lark-cli wiki +node-list --space-id <SPACE_ID> --format pretty
 
 | Flag | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
-| `--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 |
+| `--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 |
 | `--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`) |
@@ -82,6 +85,10 @@ 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
 

tests/cli_e2e/drive/drive_permission_get_setting_test.go

@@ -1,125 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package drive
-
-import (
-	"context"
-	"strings"
-	"testing"
-	"time"
-
-	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	"github.com/stretchr/testify/require"
-	"github.com/tidwall/gjson"
-)
-
-func TestDrive_PermissionGetSettingDryRun(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
-	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
-	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
-
-	tests := []struct {
-		name     string
-		args     []string
-		wantURL  string
-		wantType string
-	}{
-		{
-			name: "bare folder token",
-			args: []string{
-				"drive", "+permission-get-setting",
-				"--token", "fldE2E001",
-				"--type", "folder",
-				"--dry-run",
-			},
-			wantURL:  "/open-apis/drive/v2/permissions/fldE2E001/public",
-			wantType: "folder",
-		},
-		{
-			name: "folder URL",
-			args: []string{
-				"drive", "+permission-get-setting",
-				"--token", "https://example.feishu.cn/drive/folder/fldE2E001?from=share",
-				"--dry-run",
-			},
-			wantURL:  "/open-apis/drive/v2/permissions/fldE2E001/public",
-			wantType: "folder",
-		},
-		{
-			name: "docx URL",
-			args: []string{
-				"drive", "+permission-get-setting",
-				"--token", "https://example.feishu.cn/docx/doxE2E001",
-				"--dry-run",
-			},
-			wantURL:  "/open-apis/drive/v2/permissions/doxE2E001/public",
-			wantType: "docx",
-		},
-	}
-
-	for _, temp := range tests {
-		tt := temp
-		t.Run(tt.name, func(t *testing.T) {
-			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-			t.Cleanup(cancel)
-
-			result, err := clie2e.RunCmd(ctx, clie2e.Request{
-				Args:      tt.args,
-				DefaultAs: "bot",
-			})
-			require.NoError(t, err)
-			result.AssertExitCode(t, 0)
-
-			out := result.Stdout
-			if got := gjson.Get(out, "api.0.method").String(); got != "GET" {
-				t.Fatalf("method = %q, want GET\nstdout:\n%s", got, out)
-			}
-			if got := gjson.Get(out, "api.0.url").String(); got != tt.wantURL {
-				t.Fatalf("url = %q, want %q\nstdout:\n%s", got, tt.wantURL, out)
-			}
-			if got := gjson.Get(out, "api.0.params.type").String(); got != tt.wantType {
-				t.Fatalf("params.type = %q, want %q\nstdout:\n%s", got, tt.wantType, out)
-			}
-			if gjson.Get(out, "folder_token").Exists() {
-				t.Fatalf("folder_token exists in dry-run output, want omitted\nstdout:\n%s", out)
-			}
-		})
-	}
-}
-
-func TestDrive_PermissionGetSettingWorkflow(t *testing.T) {
-	parentT := t
-	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
-	t.Cleanup(cancel)
-
-	folderName := "lark-cli-e2e-drive-permission-get-setting-" + clie2e.GenerateSuffix()
-	folderToken := createDriveFolderOrSkipPermission(t, parentT, ctx, folderName)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"drive", "+permission-get-setting",
-			"--token", folderToken,
-			"--type", "folder",
-			"--format", "json",
-		},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	if result.ExitCode != 0 {
-		combinedOutput := strings.ToLower(result.Stdout + "\n" + result.Stderr)
-		if strings.Contains(combinedOutput, "docs:permission.setting:read") ||
-			strings.Contains(combinedOutput, "app scope not enabled") ||
-			strings.Contains(combinedOutput, "missing required scope") ||
-			strings.Contains(combinedOutput, "99991672") {
-			t.Skipf("skip drive permission setting workflow due to missing bot scope docs:permission.setting:read: %s", strings.TrimSpace(result.Stdout+"\n"+result.Stderr))
-		}
-	}
-	result.AssertExitCode(t, 0)
-	result.AssertStdoutStatus(t, true)
-
-	if !gjson.Get(result.Stdout, "data.permission_public").Exists() {
-		t.Fatalf("permission_public missing in output\nstdout:\n%s", result.Stdout)
-	}
-}