test(slides): avoid credential-like history test text

* feat(vc): add meeting message send shortcut

* docs: refine vc meeting emoji guidance

* fix(vc): validate meeting message send conflicts

* test: add vc meeting message dry-run e2e

* fix(vc): validate meeting message send limits

CHANGELOG.md

@@ -2,6 +2,74 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.62] - 2026-07-01
+
+### Features
+
+- **vc**: Add meeting message send shortcut (#1643)
+- **doc**: Add document word statistics helper (#1697)
+- **cli**: Interactive upgrade prompt for bare `lark-cli` invocation (#1498)
+- **install**: Fail closed when `checksums.txt` is missing during install (#1503)
+
+### Bug Fixes
+
+- **drive**: Improve batch failure handling for push/pull/sync (#1703)
+- **base**: Support JSON array input for field create (#1661)
+- **task**: Expose completion state in `my tasks` output (#1641)
+- **cli**: Reduce public content credential false positives (#1700)
+
+## [v1.0.61] - 2026-06-30
+
+### Features
+
+- **apps**: Add `db`, `file`, `openapi-key` and observability shortcuts (#1596)
+- **identity**: Add `whoami` command showing effective identity (#1666)
+- **docs**: Add reference map flags (#1547)
+
+### Bug Fixes
+
+- **identity**: Correct identity diagnosis under external credential providers (#1693)
+- **cli**: Harden git credential error handling (#1676)
+
+### Documentation
+
+- **doc**: Guide document copy skill usage (#1673)
+- **doc**: Fix lark-doc media token examples (#1662)
+
+## [v1.0.60] - 2026-06-29
+
+### Features
+
+- **affordance**: Per-command usage guidance system with markdown source (#1565)
+- **event**: Support VC meeting lifecycle events (#1632)
+- **sheets**: Use `office_sheet_file` parent_type for imported office spreadsheets (#1606)
+- **authorization**: Expand lark-shared auth guidance and assert clean logout JSON (#1598)
+- **transport**: Add `LARK_CLI_NO_PROXY_WARN` to silence proxy warning (#1647)
+
+### Bug Fixes
+
+- **install**: Load `@clack/prompts` via dynamic import to avoid `ERR_REQUIRE_ESM` (#1652)
+
+### Tests
+
+- **doc**: Derive fetch test flag defaults from `v2FetchFlags` (#1428)
+
+### Build
+
+- **ci**: Reduce public content false positives
+
+## [v1.0.59] - 2026-06-26
+
+### Features
+
+- **slides**: Add `+replace-pages` and `xml get` shortcuts, and expose the presentation URL (#1585)
+- **minutes**: Support speaker list and no-Lark speaker replace (#1594)
+- **calendar/vc/minutes**: Optimize and extend calendar, vc, minutes, and note shortcuts and skills (#1571)
+
+### Bug Fixes
+
+- **docs**: Hide docs `api-version` compat flag (#1580)
+
 ## [v1.0.58] - 2026-06-25
 
 ### Features
@@ -1265,6 +1333,10 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[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
+[v1.0.60]: https://github.com/larksuite/cli/releases/tag/v1.0.60
+[v1.0.59]: https://github.com/larksuite/cli/releases/tag/v1.0.59
 [v1.0.58]: https://github.com/larksuite/cli/releases/tag/v1.0.58
 [v1.0.57]: https://github.com/larksuite/cli/releases/tag/v1.0.57
 [v1.0.56]: https://github.com/larksuite/cli/releases/tag/v1.0.56

affordance/README.md

@@ -0,0 +1,49 @@
+# Affordance
+
+Per-command usage guidance for the CLI, authored as one markdown file per domain
+(`<service>.md`). It is surfaced in `lark-cli <command> --help` and in the
+`schema` output, and read directly at runtime (lazy, cached) — there is no build
+step. Maintain these files alongside `skills/` and `shortcuts/`.
+
+## Format
+
+A small, fixed markdown subset; each file describes one domain:
+
+    # <domain>            optional `> skill: <name>` applies to every command below
+    ## <command>          the command as typed, minus `lark-cli <domain>`
+    <lead paragraph>      when to use this command
+    ### Avoid when        when not to use it / which command to use instead
+    ### Prerequisites     what you must have first (e.g. an id, and where it comes from)
+    ### Tips              gotchas and constraints
+    ### Examples          **description** lines, each followed by a fenced command
+    ### <other heading>   a custom section; flows through verbatim
+
+Reference another command with `[[command]]` — it renders as `command` in help.
+Under `Avoid when` it means "use that one instead"; under `Prerequisites`
+("… from [[command]]") it means "get the input there first".
+
+## Example
+
+    ## messages get
+    Fetch the full content of a single message by id.
+
+    ### Avoid when
+    - Reading several at once → use [[messages batch_get]]
+
+    ### Prerequisites
+    - message_id from [[messages list]]
+
+    ### Examples
+
+    **Fetch one message**
+    ```bash
+    lark-cli mail user_mailbox.messages get --message-id "<id>"
+    ```
+
+## Notes
+
+- Write plain prose; the only convention is wrapping command references in `[[ ]]`.
+- Keep it concise and high-signal — don't restate field/flag names, id types, or
+  anything the schema and flags already show; the agent infers the rest.
+- Command-form headings resolve to method ids via the registry, so plural resource
+  names (`messages`) map to the singular method id (`message`) automatically.

affordance/contact.md

@@ -0,0 +1,19 @@
+# contact
+> skill: lark-contact
+
+## user_profiles batch_query
+Bulk-fetch personal status and signature for user ids you already have.
+
+### Avoid when
+- Need more than status/signature (name, dept, email), or don't have the open_id yet → use [[+search-user]]
+
+### Tips
+- Off by default — set include_personal_status / include_description to true under query_option
+- ids in user_ids must match --user-id-type (default open_id)
+
+### Examples
+
+**Bulk-query status and signature**
+```bash
+lark-cli contact user_profiles batch_query --data '{"user_ids":["ou_3a8b****6a7b"],"query_option":{"include_personal_status":true,"include_description":true}}'
+```

cmd/api/api.go

@@ -67,8 +67,21 @@ func NewCmdApiWithContext(ctx context.Context, f *cmdutil.Factory, runF func(*AP
 
 	cmd := &cobra.Command{
 		Use:   "api <method> <path>",
-		Short: "Generic Lark API requests",
-		Args:  cobra.ExactArgs(2),
+		Short: "Raw HTTP escape hatch — call any endpoint by path (fallback when no typed command exists)",
+		Long: `Raw HTTP escape hatch: send any Lark API request by HTTP method + path.
+
+Prefer the typed domain command when one exists — it validates parameters,
+shows the Risk level, gates destructive calls behind --yes, and carries usage
+guidance that this raw command does not. If a domain command covers your task
+(browse with ` + "`lark-cli <domain> --help`" + `), use it instead of this.
+
+Reach for ` + "`api`" + ` only for endpoints that have no typed command yet (e.g.
+newer/preview APIs), where you already have the HTTP path from the Lark docs.
+
+Examples:
+  lark-cli api GET /open-apis/calendar/v4/calendars
+  lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"open_id"}' --data @body.json`,
+		Args: cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Method = strings.ToUpper(args[0])
 			opts.Path = args[1]

cmd/build.go

@@ -19,6 +19,7 @@ import (
 	"github.com/larksuite/cli/cmd/service"
 	"github.com/larksuite/cli/cmd/skill"
 	cmdupdate "github.com/larksuite/cli/cmd/update"
+	"github.com/larksuite/cli/cmd/whoami"
 	_ "github.com/larksuite/cli/events"
 	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/build"
@@ -170,6 +171,10 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.SetOut(cfg.streams.Out)
 	rootCmd.SetErr(cfg.streams.ErrOut)
 
+	// Root-only usage template (curated Usage synopsis + skills footer); see
+	// rootUsageTemplate.
+	rootCmd.SetUsageTemplate(rootUsageTemplate)
+
 	installTipsHelpFunc(rootCmd)
 	rootCmd.SilenceErrors = true
 	// SilenceUsage as a static field (not only in PersistentPreRun) so it also
@@ -190,6 +195,7 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.AddCommand(auth.NewCmdAuth(f))
 	rootCmd.AddCommand(profile.NewCmdProfile(f))
 	rootCmd.AddCommand(doctor.NewCmdDoctor(f))
+	rootCmd.AddCommand(whoami.NewCmdWhoami(f))
 	rootCmd.AddCommand(api.NewCmdApiWithContext(ctx, f, nil))
 	rootCmd.AddCommand(schema.NewCmdSchema(f, nil))
 	rootCmd.AddCommand(completion.NewCmdCompletion(f))
@@ -205,7 +211,12 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	}
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)
 
+	groupRootCommands(rootCmd)
+
 	installUnknownSubcommandGuard(rootCmd)
+	// Bare `lark-cli` in an interactive terminal offers an interactive upgrade
+	// before printing help; non-bare invocations and non-TTY are unaffected.
+	installRootUpgradePrompt(f, rootCmd)
 
 	if mode := f.ResolveStrictMode(ctx); mode.IsActive() && !cfg.skipStrictMode {
 		pruneForStrictMode(rootCmd, mode)

cmd/doctor/doctor.go

@@ -129,7 +129,10 @@ func doctorRun(opts *DoctorOptions) error {
 	if diagnostics.Bot.Available || diagnostics.User.Available {
 		checks = append(checks, pass("identity_ready", "at least one identity is available"))
 	} else {
-		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", "run: lark-cli auth status --verify"))
+		// No hint: this only summarizes the two checks above, which already carry
+		// the source-appropriate remediation. A command here would be redundant,
+		// or wrong (`auth status` is blocked under an external provider).
+		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", ""))
 	}
 
 	// ── 4 & 5. Endpoint reachability ──

cmd/doctor/doctor_test.go

@@ -4,14 +4,19 @@
 package doctor
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
+	"net/http"
+	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
+	extcred "github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
 )
 
 func TestNewCmdDoctor_FlagParsing(t *testing.T) {
@@ -140,14 +145,84 @@ func TestDoctorRun_SplitsBotAndMissingUserIdentity(t *testing.T) {
 }
 
 func assertCheck(t *testing.T, checks []checkResult, name, status string) {
+	t.Helper()
+	if got := findCheck(t, checks, name); got.Status != status {
+		t.Fatalf("%s status = %q, want %q", name, got.Status, status)
+	}
+}
+
+func findCheck(t *testing.T, checks []checkResult, name string) checkResult {
 	t.Helper()
 	for _, check := range checks {
 		if check.Name == name {
-			if check.Status != status {
-				t.Fatalf("%s status = %q, want %q", name, check.Status, status)
-			}
-			return
+			return check
 		}
 	}
 	t.Fatalf("check %q not found in %#v", name, checks)
+	return checkResult{}
+}
+
+type fakeExtProvider struct {
+	name    string
+	account *extcred.Account
+}
+
+func (p *fakeExtProvider) Name() string { return p.name }
+func (p *fakeExtProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
+	return p.account, nil
+}
+func (p *fakeExtProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
+	return nil, nil
+}
+
+// Under an external credential provider with no usable identity, the
+// identity_ready hint must not point at `auth status` (blocked there); the
+// per-identity checks already carry the source-appropriate escalation.
+func TestDoctor_ExternalProvider_IdentityReadyHintNotBlockedCommand(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps:       []core.AppConfig{{Name: "default", AppId: "cli_x", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu}},
+	}); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	// Provider serves neither identity: bot unsupported, user supported but not
+	// signed in → both unavailable → identity_ready fails.
+	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsUser)}
+	cred := credential.NewCredentialProvider(
+		[]extcred.Provider{&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}},
+		nil, nil,
+		func() (*http.Client, error) { return nil, nil },
+	)
+	out := &bytes.Buffer{}
+	f := &cmdutil.Factory{
+		Config:     func() (*core.CliConfig, error) { return cfg, nil },
+		Credential: cred,
+		IOStreams:  &cmdutil.IOStreams{Out: out, ErrOut: &bytes.Buffer{}},
+	}
+
+	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err == nil {
+		t.Fatalf("doctorRun() = nil, want failure when no identity is available")
+	}
+	var got struct {
+		Checks []checkResult `json:"checks"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v\n%s", err, out.String())
+	}
+
+	ready := findCheck(t, got.Checks, "identity_ready")
+	if ready.Status != "fail" {
+		t.Fatalf("identity_ready status = %q, want fail", ready.Status)
+	}
+	// The summary defers to the per-identity checks; it carries no hint of its
+	// own (a command here would be wrong under an external provider).
+	if ready.Hint != "" {
+		t.Fatalf("identity_ready should carry no hint, got %q", ready.Hint)
+	}
+	user := findCheck(t, got.Checks, "user_identity")
+	if !strings.Contains(user.Hint, "external") || strings.Contains(user.Hint, "auth login") {
+		t.Fatalf("user_identity hint not external-appropriate: %q", user.Hint)
+	}
 }

cmd/event/list_test.go

@@ -10,10 +10,22 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	eventlib "github.com/larksuite/cli/internal/event"
 
 	_ "github.com/larksuite/cli/events"
 )
 
+func TestEventLookup_VCMeetingLifecycleKeys(t *testing.T) {
+	for _, key := range []string{
+		"vc.meeting.participant_meeting_started_v1",
+		"vc.meeting.participant_meeting_joined_v1",
+	} {
+		if _, ok := eventlib.Lookup(key); !ok {
+			t.Fatalf("event.Lookup(%q) should succeed", key)
+		}
+	}
+}
+
 func TestRunList_TextOutput(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
 
@@ -27,6 +39,8 @@ func TestRunList_TextOutput(t *testing.T) {
 		"im.message.receive_v1",
 		"im.message.message_read_v1",
 		"task.task.update_user_access_v2",
+		"vc.meeting.participant_meeting_started_v1",
+		"vc.meeting.participant_meeting_joined_v1",
 	} {
 		if !strings.Contains(out, want) {
 			t.Errorf("list output missing %q; full output:\n%s", want, out)
@@ -57,9 +71,15 @@ func TestRunList_JSONOutput(t *testing.T) {
 		}
 	}
 
-	var foundTask bool
+	gotKeys := map[string]map[string]interface{}{}
 	for _, row := range rows {
-		if row["key"] == "task.task.update_user_access_v2" {
+		if key, ok := row["key"].(string); ok {
+			gotKeys[key] = row
+		}
+	}
+	var foundTask bool
+	for key, row := range gotKeys {
+		if key == "task.task.update_user_access_v2" {
 			foundTask = true
 			if row["single_consumer"] != true {
 				t.Errorf("task row single_consumer = %v, want true", row["single_consumer"])
@@ -69,4 +89,12 @@ func TestRunList_JSONOutput(t *testing.T) {
 	if !foundTask {
 		t.Fatal("event list JSON missing task.task.update_user_access_v2")
 	}
+	for _, want := range []string{
+		"vc.meeting.participant_meeting_started_v1",
+		"vc.meeting.participant_meeting_joined_v1",
+	} {
+		if _, ok := gotKeys[want]; !ok {
+			t.Errorf("JSON list output missing %q", want)
+		}
+	}
 }

cmd/event/schema_test.go

@@ -124,6 +124,45 @@ func TestRunSchema_TaskUpdateUserAccessJSON(t *testing.T) {
 	}
 }
 
+func TestRunSchema_JSONOutput_VCMeetingLifecycleKeys(t *testing.T) {
+	for _, key := range []string{
+		"vc.meeting.participant_meeting_started_v1",
+		"vc.meeting.participant_meeting_joined_v1",
+	} {
+		t.Run(key, func(t *testing.T) {
+			f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
+
+			if err := runSchema(f, key, true); err != nil {
+				t.Fatalf("runSchema json: %v", err)
+			}
+
+			var payload map[string]interface{}
+			if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+				t.Fatalf("output is not valid JSON: %v\n%s", err, stdout.String())
+			}
+			if payload["key"] != key {
+				t.Errorf("key = %v, want %s", payload["key"], key)
+			}
+			resolved, ok := payload["resolved_output_schema"].(map[string]interface{})
+			if !ok {
+				t.Fatalf("resolved_output_schema missing or wrong type: %+v", payload)
+			}
+			properties, ok := resolved["properties"].(map[string]interface{})
+			if !ok {
+				t.Fatalf("resolved_output_schema.properties missing or wrong type: %+v", resolved)
+			}
+			for _, field := range []string{"type", "event_id", "timestamp", "meeting_id", "topic", "meeting_no", "start_time", "calendar_event_id"} {
+				if _, ok := properties[field]; !ok {
+					t.Errorf("resolved output schema missing field %q: %+v", field, properties)
+				}
+			}
+			if _, ok := properties["end_time"]; ok {
+				t.Errorf("resolved output schema should not include end_time for %s: %+v", key, properties)
+			}
+		})
+	}
+}
+
 func TestSchema_RendersSubscriptionKeyMarker(t *testing.T) {
 	const syntheticKey = "test.evt_sub"
 	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })

cmd/root.go

@@ -11,9 +11,11 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/larksuite/cli/cmd/service"
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/platform"
 	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/deprecation"
@@ -28,43 +30,60 @@ import (
 
 const rootLong = `lark-cli — Lark/Feishu CLI tool.
 
-USAGE:
-    lark-cli <command> [subcommand] [method] [options]
-    lark-cli api <method> <path> [--params <json>] [--data <json>]
-    lark-cli schema <service.resource.method>
+AGENT QUICKSTART (driving this as an agent? start here):
+    Browse commands:  lark-cli <domain> --help            # +shortcuts (preferred) and raw API resources
+    Inspect a call:   lark-cli schema <service>.<resource>.<method>   # params, types, scopes, examples
+    Prefer a +shortcut over the raw API resource when one matches the task.
+    Risk: each command's --help shows read | write | high-risk-write;
+          high-risk-write needs --yes, only after the user confirms.
+    On any API call: --jq <expr> filters JSON output, --dry-run previews the request (runs nothing).
 
-EXAMPLES:
-    # View upcoming events
-    lark-cli calendar +agenda
+EXAMPLES (one per command style, in order of preference):
+    lark-cli calendar +agenda                                       # +shortcut — a high-level task, prefer these
+    lark-cli mail user_mailbox.messages list --user-mailbox-id me   # typed command for one API method
+    lark-cli schema mail.user_mailbox.messages.list                 # inspect a method's params before calling
+    lark-cli api GET /open-apis/calendar/v4/calendars               # raw escape hatch — any endpoint by HTTP path`
 
-    # List calendar events
-    lark-cli calendar events instance_view --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'
+// rootUsageTemplate is cobra's default usage template with two root-only
+// additions gated on {{if not .HasParent}}: a curated multi-form Usage synopsis
+// (replacing cobra's generic "[flags] / [command]") and a human skills-setup
+// footer. Subcommands render the stock template unchanged. The rest is verbatim
+// cobra so the command groups and flags are untouched.
+const rootUsageTemplate = `{{if .HasParent}}Usage:{{if .Runnable}}
+  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}
+  {{.CommandPath}} [command]{{end}}{{else}}Usage:
+  lark-cli <command> [subcommand] [method] [flags]
+  lark-cli api <method> <path> [--params <json>] [--data <json>]
+  lark-cli schema <service.resource.method>{{end}}{{if gt (len .Aliases) 0}}
 
-    # Search users
-    lark-cli contact +search-user --query "John"
+Aliases:
+  {{.NameAndAliases}}{{end}}{{if .HasExample}}
 
-    # Generic API call
-    lark-cli api GET /open-apis/calendar/v4/calendars
+Examples:
+{{.Example}}{{end}}{{if .HasAvailableSubCommands}}{{$cmds := .Commands}}{{if eq (len .Groups) 0}}
 
-AI AGENT SKILLS:
-    lark-cli pairs with AI agent skills (Claude Code, etc.) that
-    teach the agent Lark API patterns, best practices, and workflows.
+Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{else}}{{range $group := .Groups}}
 
-    Install all skills:
-        npx skills add larksuite/cli -g -y
+{{.Title}}{{range $cmds}}{{if (and (eq .GroupID $group.ID) (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}}
 
-    Or pick specific domains:
-        npx skills add larksuite/cli -s lark-calendar -y
-        npx skills add larksuite/cli -s lark-im -y
+Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
 
-    Learn more: https://github.com/larksuite/cli#agent-skills
+Flags:
+{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
 
-COMMUNITY:
-    GitHub:     https://github.com/larksuite/cli
-    Issues:     https://github.com/larksuite/cli/issues
-    Docs:       https://open.feishu.cn/document/
+Global Flags:
+{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
 
-More help: lark-cli <command> --help`
+Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
+  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
+
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}{{if not .HasParent}}
+
+Skills setup (one-time, humans): npx skills add larksuite/cli -g -y — https://github.com/larksuite/cli#agent-skills{{end}}
+`
 
 // Execute runs the root command and returns the process exit code.
 // rawInvocationArgs holds os.Args[1:] captured at Execute() entry. cobra's
@@ -529,6 +548,49 @@ func availableSubcommandNames(cmd *cobra.Command) (available, deprecated []strin
 	return available, deprecated
 }
 
+// Root command help groups, so an agent sees content domains, agent tooling, and
+// CLI management as distinct blocks instead of one flat alphabetical dump.
+const (
+	groupDomains    = "lark-domains"
+	groupTooling    = "agent-tooling"
+	groupManagement = "cli-management"
+)
+
+// groupRootCommands classifies root's direct children into the help groups,
+// called once after all commands are registered. Unclassified commands fall to
+// cobra's "Additional Commands" section.
+func groupRootCommands(root *cobra.Command) {
+	root.AddGroup(
+		&cobra.Group{ID: groupDomains, Title: "Lark domains:"},
+		&cobra.Group{ID: groupTooling, Title: "Agent tooling:"},
+		&cobra.Group{ID: groupManagement, Title: "CLI management:"},
+	)
+	tooling := map[string]bool{"api": true, "schema": true, "skills": true}
+	management := map[string]bool{"auth": true, "config": true, "profile": true, "doctor": true, "update": true}
+	for _, c := range root.Commands() {
+		if c.GroupID != "" {
+			continue
+		}
+		switch {
+		case tooling[c.Name()]:
+			c.GroupID = groupTooling
+		case management[c.Name()]:
+			c.GroupID = groupManagement
+		case isLarkDomain(c):
+			c.GroupID = groupDomains
+		}
+	}
+}
+
+// isLarkDomain reports whether a root child is a Lark domain (service-sourced or
+// shortcut-tagged), not CLI tooling. Mirrors service.PrepareDomainHelp.
+func isLarkDomain(c *cobra.Command) bool {
+	if src, _ := cmdmeta.SourceOf(c); src == cmdmeta.SourceService {
+		return true
+	}
+	return cmdmeta.Domain(c) != ""
+}
+
 // flagDidYouMean is the root FlagErrorFunc (inherited by all subcommands). It
 // converts cobra's flag-parse errors into a typed validation envelope: an
 // unknown flag gets a focused "did you mean" hint (so agents recover even when
@@ -610,6 +672,17 @@ func installTipsHelpFunc(root *cobra.Command) {
 				defer func() { f.Hidden = true }()
 			}
 		}
+		// Domain and method commands compose their agent guidance into Long lazily
+		// here (shortcuts attach after service registration); both skip the generic
+		// bottom-of-help append below.
+		if service.PrepareDomainHelp(cmd, embeddedSkillContent) {
+			defaultHelp(cmd, args)
+			return
+		}
+		if service.PrepareMethodHelp(cmd) {
+			defaultHelp(cmd, args)
+			return
+		}
 		defaultHelp(cmd, args)
 		out := cmd.OutOrStdout()
 		if level, ok := cmdutil.GetRisk(cmd); ok {

cmd/root_test.go

@@ -76,11 +76,13 @@ func TestPersistentPreRunE_ConfigSubcommands(t *testing.T) {
 }
 
 func TestRootLong_AgentSkillsLinkTargetsReadmeSection(t *testing.T) {
-	if !strings.Contains(rootLong, "https://github.com/larksuite/cli#agent-skills") {
-		t.Fatalf("root help should link to the README Agent Skills section, got:\n%s", rootLong)
+	// The human skills-install guidance now lives in the root usage-template
+	// footer (below the command list), not in the agent-facing Long.
+	if !strings.Contains(rootUsageTemplate, "https://github.com/larksuite/cli#agent-skills") {
+		t.Fatalf("root help footer should link to the README Agent Skills section, got:\n%s", rootUsageTemplate)
 	}
-	if strings.Contains(rootLong, "https://github.com/larksuite/cli#install-ai-agent-skills") {
-		t.Fatalf("root help should not reference the removed install-ai-agent-skills anchor, got:\n%s", rootLong)
+	if strings.Contains(rootUsageTemplate, "https://github.com/larksuite/cli#install-ai-agent-skills") {
+		t.Fatalf("root help should not reference the removed install-ai-agent-skills anchor, got:\n%s", rootUsageTemplate)
 	}
 }
 

cmd/root_upgrade.go

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/update"
+	"github.com/spf13/cobra"
+)
+
+// runRootUpgrade locates the registered `update` subcommand and runs it, so the
+// interactive root-command upgrade reuses exactly `lark-cli update` behavior
+// (install-method detection, output, error handling). Package-level var so
+// tests can stub it and avoid real network / self-update.
+var runRootUpgrade = func(cmd *cobra.Command) {
+	for _, c := range cmd.Root().Commands() {
+		if c.Name() == "update" && c.RunE != nil {
+			_ = c.RunE(c, nil) // update prints its own output/errors; swallow here
+			return
+		}
+	}
+}
+
+// isBareRootInvocation reports whether this is a bare `lark-cli` (no subcommand,
+// no flags) — the only invocation that triggers the interactive upgrade prompt.
+// Mirrors unknownSubcommandRunE's "bare group prints help" branch: args empty
+// AND no flag tokens in the raw invocation.
+func isBareRootInvocation(args []string) bool {
+	return len(args) == 0 && len(flagTokensInArgs(rawInvocationArgs)) == 0
+}
+
+// readYes reads one line and reports whether it is an affirmative y/yes.
+// EOF / empty / anything else → false (default No, matching the [y/N] prompt).
+func readYes(r io.Reader) bool {
+	line, _ := bufio.NewReader(r).ReadString('\n')
+	switch strings.ToLower(strings.TrimSpace(line)) {
+	case "y", "yes":
+		return true
+	default:
+		return false
+	}
+}
+
+// offerRootUpgrade prompts for an interactive upgrade when running bare
+// `lark-cli` in an interactive terminal with a cached newer version. Every
+// failure is swallowed — it must never affect help output or the exit code.
+func offerRootUpgrade(f *cmdutil.Factory, cmd *cobra.Command) {
+	ios := f.IOStreams
+	// Gates 1/2/3: need to read stdin AND show the prompt on stderr, and require
+	// stdout TTY too so this only fires in a pure foreground terminal session.
+	if !ios.IsTerminal || !ios.OutIsTerminal || !ios.StderrIsTerminal {
+		return
+	}
+	// Gate 4: cached newer version. CheckCached applies opt-out (shouldSkip)
+	// and the IsNewer/semver validation chain; it reads the on-disk cache that
+	// the 24h-throttled RefreshCache maintains (CheckCached itself has no TTL).
+	info := update.CheckCached(build.Version)
+	if info == nil {
+		return
+	}
+	fmt.Fprintf(ios.ErrOut, "lark-cli %s available (current %s). Upgrade now? [y/N]: ", info.Latest, info.Current)
+	if !readYes(ios.In) {
+		return
+	}
+	runRootUpgrade(cmd)
+}
+
+// installRootUpgradePrompt wraps the root command's RunE (set to
+// unknownSubcommandRunE by installUnknownSubcommandGuard) so a bare `lark-cli`
+// invocation offers an interactive upgrade before printing help. Non-bare
+// invocations are passed straight through, unchanged.
+func installRootUpgradePrompt(f *cmdutil.Factory, root *cobra.Command) {
+	inner := root.RunE
+	if inner == nil {
+		return
+	}
+	root.RunE = func(cmd *cobra.Command, args []string) error {
+		if isBareRootInvocation(args) {
+			offerRootUpgrade(f, cmd)
+		}
+		return inner(cmd, args)
+	}
+}

cmd/root_upgrade_test.go

@@ -0,0 +1,191 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/spf13/cobra"
+)
+
+func writeUpdateState(t *testing.T, dir, latest string) {
+	t.Helper()
+	data := fmt.Sprintf(`{"latest_version":%q,"checked_at":%d}`, latest, time.Now().Unix())
+	if err := os.WriteFile(filepath.Join(dir, "update-state.json"), []byte(data), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestReadYes(t *testing.T) {
+	cases := map[string]bool{
+		"y\n": true, "Y\n": true, "yes\n": true, "YES\n": true, " y \n": true,
+		"n\n": false, "\n": false, "": false, "nope\n": false, "yeah\n": false,
+	}
+	for in, want := range cases {
+		if got := readYes(strings.NewReader(in)); got != want {
+			t.Errorf("readYes(%q) = %v, want %v", in, got, want)
+		}
+	}
+}
+
+func TestIsBareRootInvocation(t *testing.T) {
+	orig := rawInvocationArgs
+	t.Cleanup(func() { rawInvocationArgs = orig })
+
+	rawInvocationArgs = nil
+	if !isBareRootInvocation([]string{}) {
+		t.Error("empty args + no raw flag tokens should be bare")
+	}
+	rawInvocationArgs = []string{"--profile", "x"}
+	if isBareRootInvocation([]string{}) {
+		t.Error("flag token present → not bare")
+	}
+	rawInvocationArgs = nil
+	if isBareRootInvocation([]string{"im"}) {
+		t.Error("positional arg → not bare")
+	}
+}
+
+func TestOfferRootUpgrade(t *testing.T) {
+	origV := build.Version
+	build.Version = "1.0.0" // release version so shouldSkip()==false
+	t.Cleanup(func() { build.Version = origV })
+
+	origRun := runRootUpgrade
+	t.Cleanup(func() { runRootUpgrade = origRun })
+
+	// This test builds a Factory literal (no NewDefault), so it never runs
+	// workspace detection; pin the process-global workspace to Local so
+	// statePath() resolves under LARKSUITE_CLI_CONFIG_DIR rather than a stale
+	// subdir inherited from a prior test in the package.
+	origWS := core.CurrentWorkspace()
+	t.Cleanup(func() { core.SetCurrentWorkspace(origWS) })
+	core.SetCurrentWorkspace(core.WorkspaceLocal)
+
+	cases := []struct {
+		name                string
+		in, out, err        bool
+		input               string
+		latest              string // "" → no state file (CheckCached nil)
+		optOut              bool
+		wantPrompt, wantRun bool
+	}{
+		{"all-tty+y", true, true, true, "y\n", "2.0.0", false, true, true},
+		{"all-tty+yes", true, true, true, "yes\n", "2.0.0", false, true, true},
+		{"all-tty+n", true, true, true, "n\n", "2.0.0", false, true, false},
+		{"all-tty+empty", true, true, true, "\n", "2.0.0", false, true, false},
+		{"all-tty+eof", true, true, true, "", "2.0.0", false, true, false},
+		{"stdin-not-tty", false, true, true, "y\n", "2.0.0", false, false, false},
+		{"stdout-not-tty", true, false, true, "y\n", "2.0.0", false, false, false},
+		{"stderr-not-tty", true, true, false, "y\n", "2.0.0", false, false, false},
+		{"no-newer-version", true, true, true, "y\n", "", false, false, false},
+		{"already-latest", true, true, true, "y\n", "1.0.0", false, false, false}, // post-upgrade: current == cached latest → no prompt
+		{"cache-older-than-current", true, true, true, "y\n", "0.9.0", false, false, false},
+		{"opt-out", true, true, true, "y\n", "2.0.0", true, false, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+			// Clear env that update.shouldSkip treats as "suppress" so the
+			// test is deterministic regardless of host (GitHub Actions sets
+			// CI=true, which would otherwise suppress the prompt).
+			t.Setenv("CI", "")
+			t.Setenv("BUILD_NUMBER", "")
+			t.Setenv("RUN_ID", "")
+			t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "")
+			if tc.latest != "" {
+				writeUpdateState(t, dir, tc.latest)
+			}
+			if tc.optOut {
+				t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
+			}
+			called := false
+			runRootUpgrade = func(*cobra.Command) { called = true }
+
+			var errBuf bytes.Buffer
+			f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
+				In:               strings.NewReader(tc.input),
+				Out:              &bytes.Buffer{},
+				ErrOut:           &errBuf,
+				IsTerminal:       tc.in,
+				OutIsTerminal:    tc.out,
+				StderrIsTerminal: tc.err,
+			}}
+			offerRootUpgrade(f, &cobra.Command{})
+
+			gotPrompt := strings.Contains(errBuf.String(), "available")
+			if gotPrompt != tc.wantPrompt {
+				t.Errorf("prompt: got %v want %v (stderr=%q)", gotPrompt, tc.wantPrompt, errBuf.String())
+			}
+			if called != tc.wantRun {
+				t.Errorf("runRootUpgrade called: got %v want %v", called, tc.wantRun)
+			}
+		})
+	}
+}
+
+func TestInstallRootUpgradePromptPreservesInner(t *testing.T) {
+	orig := rawInvocationArgs
+	t.Cleanup(func() { rawInvocationArgs = orig })
+	rawInvocationArgs = nil
+
+	innerCalls := 0
+	root := &cobra.Command{Use: "lark-cli"}
+	root.RunE = func(cmd *cobra.Command, args []string) error { innerCalls++; return nil }
+
+	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
+		In: strings.NewReader(""), Out: &bytes.Buffer{}, ErrOut: &bytes.Buffer{},
+	}}
+	installRootUpgradePrompt(f, root)
+
+	if err := root.RunE(root, []string{}); err != nil {
+		t.Fatalf("bare RunE err = %v", err)
+	}
+	if err := root.RunE(root, []string{"im"}); err != nil {
+		t.Fatalf("non-bare RunE err = %v", err)
+	}
+	if innerCalls != 2 {
+		t.Errorf("inner RunE should run for both bare and non-bare, got %d", innerCalls)
+	}
+}
+
+// TestRunRootUpgradeDispatchesToUpdate covers the real runRootUpgrade dispatch
+// path (not the stub used elsewhere): from any command it must locate the
+// registered "update" subcommand via cmd.Root() and invoke its RunE.
+func TestRunRootUpgradeDispatchesToUpdate(t *testing.T) {
+	root := &cobra.Command{Use: "lark-cli"}
+	ran := 0
+	root.AddCommand(&cobra.Command{Use: "update", RunE: func(*cobra.Command, []string) error { ran++; return nil }})
+	child := &cobra.Command{Use: "im"}
+	root.AddCommand(child)
+
+	runRootUpgrade(child) // child.Root() resolves to root, which has "update"
+
+	if ran != 1 {
+		t.Errorf("runRootUpgrade should locate and run update's RunE once, got %d", ran)
+	}
+}
+
+// TestInstallRootUpgradePromptNilInnerNoop covers the inner == nil guard:
+// when root has no RunE, installRootUpgradePrompt must not wrap it.
+func TestInstallRootUpgradePromptNilInnerNoop(t *testing.T) {
+	root := &cobra.Command{Use: "lark-cli"} // RunE is nil
+	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
+		In: strings.NewReader(""), Out: &bytes.Buffer{}, ErrOut: &bytes.Buffer{},
+	}}
+	installRootUpgradePrompt(f, root)
+	if root.RunE != nil {
+		t.Error("installRootUpgradePrompt must not wrap a nil RunE (inner==nil guard)")
+	}
+}

cmd/service/affordance.go

@@ -4,41 +4,211 @@
 package service
 
 import (
+	"encoding/json"
 	"fmt"
+	"io/fs"
 	"strings"
 
+	"github.com/larksuite/cli/internal/affordance"
+	"github.com/larksuite/cli/internal/cmdmeta"
+	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/meta"
+	"github.com/spf13/cobra"
 )
 
-// methodLong composes a method command's long help in one place: the
-// description, the affordance guidance block (when the method has one), the
-// pointer to the full schema, and the params-only addendum (params whose flag
-// name is taken — paramFlagBinder.paramsOnlyHelp, "" when none). Affordance
-// sits near the top so an agent sees when-to-use and few-shot examples before
-// the flag list.
-func methodLong(description, affordance, schemaPath, paramsOnly string) string {
+// PrepareDomainHelp appends navigational guidance (routing line, risk legend,
+// skill pointer) to a top-level Lark domain's description, returning false for
+// anything that is not such a domain. Built lazily at help time because
+// shortcuts attach after service registration. skillFS (nil-safe) gates the
+// skill pointer.
+//
+// A hand-authored Long is preserved as the base (e.g. event's "Use 'event
+// consume <EventKey>'…"); service domains carry only a Short at this point, so
+// we fall back to it. The pristine base is captured once into an annotation so
+// re-rendering does not append the guidance twice.
+func PrepareDomainHelp(cmd *cobra.Command, skillFS fs.FS) bool {
+	if cmd.Annotations[schemaPathAnnotation] != "" {
+		return false // a method command
+	}
+	// Direct child of root only — so Domain() reads this command's own tag, and
+	// nested resource groups are excluded.
+	if cmd.Parent() == nil || cmd.Parent().Parent() != nil {
+		return false
+	}
+	// A domain is service-sourced or shortcut-tagged; CLI tooling has neither.
+	if src, _ := cmdmeta.SourceOf(cmd); src != cmdmeta.SourceService && cmdmeta.Domain(cmd) == "" {
+		return false
+	}
+	if !cmd.HasAvailableSubCommands() {
+		return false
+	}
+
+	hasShortcuts, hasResources := false, false
+	for _, c := range cmd.Commands() {
+		if c.Hidden || c.Name() == "help" || c.Name() == "completion" {
+			continue
+		}
+		if strings.HasPrefix(c.Name(), "+") {
+			hasShortcuts = true
+		} else {
+			hasResources = true
+		}
+	}
+
+	var b strings.Builder
+	b.WriteString(domainHelpBase(cmd))
+	if hasShortcuts && hasResources { // routing only matters when both styles exist
+		b.WriteString("\n\nPrefer a +-prefixed shortcut when one matches your task; otherwise use the raw API resource below.")
+	}
+	b.WriteString("\n\nRisk levels (read | write | high-risk-write) appear in each command's --help; high-risk-write requires --yes, only after the user confirms.")
+	if skill := "lark-" + cmd.Name(); skillFS != nil {
+		if _, err := fs.Stat(skillFS, skill+"/SKILL.md"); err == nil {
+			fmt.Fprintf(&b, "\n\nDomain guide (concepts, command choice, conventions): lark-cli skills read %s", skill)
+		}
+	}
+	cmd.Long = b.String()
+	return true
+}
+
+// domainHelpBase returns the description to seed domain help with — the
+// hand-authored Long when present, else the Short — captured once into an
+// annotation so re-rendering reuses the pristine text instead of the
+// already-augmented Long.
+func domainHelpBase(cmd *cobra.Command) string {
+	if base, ok := cmd.Annotations[domainBaseAnnotation]; ok {
+		return base
+	}
+	base := cmd.Long
+	if base == "" {
+		base = cmd.Short
+	}
+	if cmd.Annotations == nil {
+		cmd.Annotations = map[string]string{}
+	}
+	cmd.Annotations[domainBaseAnnotation] = base
+	return base
+}
+
+// methodLong is the build-time Long (description + schema pointer +
+// params-only addendum). Agent guidance is added lazily by PrepareMethodHelp,
+// so command construction never parses the overlay.
+func methodLong(description, schemaPath, paramsOnly string) string {
 	var b strings.Builder
 	b.WriteString(description)
-	if affordance != "" {
-		b.WriteString("\n\n")
-		b.WriteString(affordance)
-	}
-	fmt.Fprintf(&b, "\n\nView parameter definitions before calling:\n  lark-cli schema %s", schemaPath)
+	fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
 	b.WriteString(paramsOnly)
 	return b.String()
 }
 
-// renderAffordance renders a method's affordance as a help block — when to use,
-// prerequisites, and (most importantly for agents) few-shot Examples — or "" when
-// the method carries no affordance. It reads the single typed model
-// (meta.Method.ParsedAffordance) so the help and the envelope agree on shape.
+// Annotation keys PrepareMethodHelp reads to rebuild a method command's Long.
+const (
+	affordanceServiceAnnotation = "affordance-service"
+	affordanceMethodAnnotation  = "affordance-method"
+	schemaPathAnnotation        = "method-schema-path"
+	paramsOnlyAnnotation        = "method-params-only"
+	domainBaseAnnotation        = "affordance-domain-base"
+)
+
+// setMethodHelpData records the coordinates PrepareMethodHelp needs (storing a
+// few strings is the only build-time cost; the overlay stays untouched).
+func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, paramsOnly string) {
+	if cmd.Annotations == nil {
+		cmd.Annotations = map[string]string{}
+	}
+	if service != "" && methodID != "" {
+		cmd.Annotations[affordanceServiceAnnotation] = service
+		cmd.Annotations[affordanceMethodAnnotation] = methodID
+	}
+	cmd.Annotations[schemaPathAnnotation] = schemaPath
+	if paramsOnly != "" {
+		cmd.Annotations[paramsOnlyAnnotation] = paramsOnly
+	}
+}
+
+// PrepareMethodHelp rebuilds a generated method command's Long with the agent
+// guidance at the TOP (Risk, then the affordance block, then the schema
+// pointer), returning false for non-method commands. The overlay is parsed
+// here — only when help is rendered.
+func PrepareMethodHelp(cmd *cobra.Command) bool {
+	ann := cmd.Annotations
+	if ann == nil {
+		return false
+	}
+	schemaPath, ok := ann[schemaPathAnnotation]
+	if !ok {
+		return false
+	}
+
+	var b strings.Builder
+	b.WriteString(cmd.Short)
+	if level, ok := cmdutil.GetRisk(cmd); ok {
+		// --yes asserts the USER confirmed; the agent must not self-approve.
+		if level == cmdutil.RiskHighRiskWrite {
+			fmt.Fprintf(&b, "\n\nRisk: %s (requires explicit user confirmation to execute; the agent must NOT add --yes on its own — only pass --yes after the user has confirmed)", level)
+		} else {
+			fmt.Fprintf(&b, "\n\nRisk: %s", level)
+		}
+	}
+
+	var skills []string
+	if raw, ok := affordanceRaw(cmd); ok {
+		if block := renderAffordance(meta.Method{Affordance: raw}); block != "" {
+			b.WriteString("\n\n")
+			b.WriteString(block)
+		}
+		if a, ok := (meta.Method{Affordance: raw}).ParsedAffordance(); ok {
+			skills = a.Skills
+		}
+	}
+
+	fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
+	b.WriteString(ann[paramsOnlyAnnotation])
+
+	if len(skills) > 0 {
+		b.WriteString("\n\nWorkflow skill (end-to-end usage):")
+		for _, s := range skills {
+			fmt.Fprintf(&b, "\n  lark-cli skills read %s", s)
+		}
+	}
+
+	cmd.Long = b.String()
+	return true
+}
+
+// affordanceLookup is the overlay source; a package var so tests can inject.
+var affordanceLookup = affordance.For
+
+// RenderAffordanceForCmd renders a method command's affordance block, or "" when
+// it carries none.
+func RenderAffordanceForCmd(cmd *cobra.Command) string {
+	raw, ok := affordanceRaw(cmd)
+	if !ok {
+		return ""
+	}
+	return renderAffordance(meta.Method{Affordance: raw})
+}
+
+func affordanceRaw(cmd *cobra.Command) (json.RawMessage, bool) {
+	if cmd.Annotations == nil {
+		return nil, false
+	}
+	service := cmd.Annotations[affordanceServiceAnnotation]
+	methodID := cmd.Annotations[affordanceMethodAnnotation]
+	if service == "" || methodID == "" {
+		return nil, false
+	}
+	return affordanceLookup(service, methodID)
+}
+
+// renderAffordance renders a method's affordance as a help block, or "" when it
+// has none. Sections are joined with blank lines so they scan as distinct groups.
 func renderAffordance(m meta.Method) string {
 	a, ok := m.ParsedAffordance()
 	if !ok {
 		return ""
 	}
 
-	var b strings.Builder
+	var sections []string
 	bullets := func(title string, items []string) {
 		var nonEmpty []string
 		for _, it := range items {
@@ -49,15 +219,18 @@ func renderAffordance(m meta.Method) string {
 		if len(nonEmpty) == 0 {
 			return
 		}
-		fmt.Fprintf(&b, "%s:\n", title)
+		var s strings.Builder
+		fmt.Fprintf(&s, "%s:\n", title)
 		for _, it := range nonEmpty {
-			fmt.Fprintf(&b, "  • %s\n", it)
+			fmt.Fprintf(&s, "  • %s\n", it)
 		}
+		sections = append(sections, strings.TrimRight(s.String(), "\n"))
 	}
 
 	bullets("When to use", a.UseWhen)
-	bullets("Avoid when", a.DoNotUseWhen)
+	bullets("Avoid when", a.AvoidWhen)
 	bullets("Prerequisites", a.Prerequisites)
+	bullets("Tips", a.Tips)
 	if len(a.Examples) > 0 {
 		var lines []string
 		for _, ex := range a.Examples {
@@ -71,10 +244,13 @@ func renderAffordance(m meta.Method) string {
 			}
 		}
 		if len(lines) > 0 {
-			fmt.Fprintf(&b, "Examples:\n%s\n", strings.Join(lines, "\n"))
+			sections = append(sections, "Examples:\n"+strings.Join(lines, "\n"))
 		}
 	}
+	for _, ext := range a.Extensions {
+		bullets(ext.Label, ext.Items)
+	}
 	bullets("Related", a.Related)
 
-	return strings.TrimRight(b.String(), "\n")
+	return strings.Join(sections, "\n\n")
 }

cmd/service/affordance_test.go

@@ -8,15 +8,18 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/meta"
+	"github.com/spf13/cobra"
 )
 
 func TestRenderAffordance(t *testing.T) {
 	raw := json.RawMessage(`{
 		"use_when": ["发送文本消息"],
-		"do_not_use_when": ["群已解散"],
+		"avoid_when": ["群已解散"],
 		"prerequisites": ["已获取 chat_id"],
+		"tips": ["富文本用 msg_type=post"],
 		"examples": [
 			{"description":"发一条文本","command":"lark-cli im messages create --params '{...}'"},
 			{"command":"lark-cli im messages list"},
@@ -29,6 +32,7 @@ func TestRenderAffordance(t *testing.T) {
 		"When to use:", "发送文本消息",
 		"Avoid when:", "群已解散",
 		"Prerequisites:", "已获取 chat_id",
+		"Tips:", "富文本用 msg_type=post",
 		"Examples:", "发一条文本", "lark-cli im messages create --params '{...}'",
 		"lark-cli im messages list", // example with no description -> bare command line
 		"Related:", "im.messages.list",
@@ -48,9 +52,12 @@ func TestRenderAffordance(t *testing.T) {
 	}
 }
 
-func TestServiceMethod_AffordanceInLong(t *testing.T) {
+// Affordance is rendered lazily (at --help time) rather than baked into the
+// command's Long, so building a command never carries the affordance block —
+// even for a method whose metadata happens to declare one.
+func TestServiceMethod_AffordanceNotInLong(t *testing.T) {
 	withAff := map[string]interface{}{
-		"path": "messages", "httpMethod": "POST", "description": "发送消息",
+		"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息",
 		"affordance": map[string]interface{}{
 			"examples": []interface{}{
 				map[string]interface{}{"description": "发文本", "command": "lark-cli im messages create ..."},
@@ -59,14 +66,120 @@ func TestServiceMethod_AffordanceInLong(t *testing.T) {
 	}
 	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
 	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(withAff), "create", "messages", nil)
-	if !strings.Contains(cmd.Long, "Examples:") || !strings.Contains(cmd.Long, "lark-cli im messages create ...") {
-		t.Errorf("affordance examples not in command Long:\n%s", cmd.Long)
+	if strings.Contains(cmd.Long, "Examples:") {
+		t.Errorf("affordance must not be baked into Long (lazy):\n%s", cmd.Long)
 	}
-
-	// A method with no affordance adds no guidance block.
-	plain := map[string]interface{}{"path": "x", "httpMethod": "GET", "description": "d"}
-	cmd2 := NewCmdServiceMethod(f, imSpec(), meta.FromMap(plain), "list", "x", nil)
-	if strings.Contains(cmd2.Long, "Examples:") {
-		t.Errorf("no-affordance method should have no Examples in Long:\n%s", cmd2.Long)
+	// The lookup ref is recorded so the help path can resolve it later.
+	if cmd.Annotations[affordanceServiceAnnotation] != "im" || cmd.Annotations[affordanceMethodAnnotation] != "messages.create" {
+		t.Errorf("affordance ref annotations = %v, want im/messages.create", cmd.Annotations)
+	}
+}
+
+// RenderAffordanceForCmd resolves a command's overlay through the (injectable)
+// lookup and renders it; commands without a ref render nothing.
+func TestRenderAffordanceForCmd(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(service, methodID string) (json.RawMessage, bool) {
+		if service != "im" || methodID != "messages.create" {
+			return nil, false
+		}
+		return json.RawMessage(`{"use_when":["发文本消息"],"tips":["富文本用 msg_type=post"],"examples":[{"description":"发一条","command":"lark-cli im messages create ..."}]}`), true
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	withRef := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息"}
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(withRef), "create", "messages", nil)
+	block := RenderAffordanceForCmd(cmd)
+	for _, want := range []string{"When to use:", "发文本消息", "Tips:", "富文本用 msg_type=post", "Examples:", "lark-cli im messages create ..."} {
+		if !strings.Contains(block, want) {
+			t.Errorf("RenderAffordanceForCmd missing %q in:\n%s", want, block)
+		}
+	}
+
+	// No overlay for this method id -> empty block.
+	noRef := map[string]interface{}{"id": "x.list", "path": "x", "httpMethod": "GET", "description": "d"}
+	cmd2 := NewCmdServiceMethod(f, imSpec(), meta.FromMap(noRef), "list", "x", nil)
+	if got := RenderAffordanceForCmd(cmd2); got != "" {
+		t.Errorf("method with no overlay should render nothing, got:\n%s", got)
+	}
+}
+
+// PrepareMethodHelp composes the guidance into Long at the top: description,
+// then the affordance block, then the full-schema pointer — so an agent reads
+// when-to-use/examples before the flag list.
+func TestPrepareMethodHelp(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
+		return json.RawMessage(`{"use_when":["发文本消息"],"examples":[{"description":"发一条","command":"lark-cli im messages create ..."}]}`), true
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	m := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息"}
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
+
+	if !PrepareMethodHelp(cmd) {
+		t.Fatal("PrepareMethodHelp returned false for a service-method command")
+	}
+	long := cmd.Long
+	// Description leads; affordance block sits above the schema pointer.
+	descAt := strings.Index(long, "发送消息")
+	useAt := strings.Index(long, "When to use:")
+	exAt := strings.Index(long, "Examples:")
+	schemaAt := strings.Index(long, "Full parameter schema:")
+	if descAt != 0 {
+		t.Errorf("description should lead Long, got:\n%s", long)
+	}
+	if !(descAt < useAt && useAt < exAt && exAt < schemaAt) {
+		t.Errorf("order should be description < affordance < schema pointer; got desc=%d use=%d ex=%d schema=%d\n%s", descAt, useAt, exAt, schemaAt, long)
+	}
+
+	// A non-service command (no schema-path annotation) is left untouched.
+	if PrepareMethodHelp(&cobra.Command{Use: "plain"}) {
+		t.Error("PrepareMethodHelp should return false for a non-service command")
+	}
+}
+
+// domainCmd wires a domain-tagged command with a subcommand under a root, the
+// shape PrepareDomainHelp expects.
+func domainCmd(short, long string) *cobra.Command {
+	root := &cobra.Command{Use: "root"}
+	dom := &cobra.Command{Use: "event", Short: short, Long: long}
+	cmdmeta.SetDomain(dom, "event")
+	dom.AddCommand(&cobra.Command{Use: "consume", Run: func(*cobra.Command, []string) {}})
+	root.AddCommand(dom)
+	return dom
+}
+
+func TestPrepareDomainHelp_PreservesHandAuthoredLong(t *testing.T) {
+	const long = "Unified event consumption system. Use 'event consume <EventKey>'."
+	dom := domainCmd("Consume and manage real-time events", long)
+
+	if !PrepareDomainHelp(dom, nil) {
+		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
+	}
+	if !strings.HasPrefix(dom.Long, long) {
+		t.Errorf("hand-authored Long must lead; got:\n%s", dom.Long)
+	}
+	if !strings.Contains(dom.Long, "Risk levels") {
+		t.Errorf("domain guidance should be appended; got:\n%s", dom.Long)
+	}
+
+	// Re-rendering must not append the guidance a second time.
+	PrepareDomainHelp(dom, nil)
+	if n := strings.Count(dom.Long, "Risk levels"); n != 1 {
+		t.Errorf("guidance appended %d times across re-renders, want 1:\n%s", n, dom.Long)
+	}
+}
+
+// A service domain carries only a Short at help time; it seeds the base.
+func TestPrepareDomainHelp_FallsBackToShort(t *testing.T) {
+	dom := domainCmd("Message and group chat management", "")
+	if !PrepareDomainHelp(dom, nil) {
+		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
+	}
+	if !strings.HasPrefix(dom.Long, "Message and group chat management") {
+		t.Errorf("Short should seed Long when no hand-authored Long exists; got:\n%s", dom.Long)
 	}
 }

cmd/service/flaggroups_test.go

@@ -60,8 +60,11 @@ func TestServiceFlagGroups_AgentContract(t *testing.T) {
 	if i := idx("--chat-id"); i < iParams || i > iBody {
 		t.Errorf("--chat-id not under API Parameters:\n%s", out)
 	}
-	if !strings.Contains(out, "chat_id, required") {
-		t.Errorf("typed flag help format wrong:\n%s", out)
+	// The redundant "<name>, required|optional." prefix is gone: required-ness is
+	// carried by the Required:/Optional: subheadings, and the snake-case --params
+	// key by the schema envelope — so it isn't echoed on every flag line.
+	if strings.Contains(out, "chat_id, required") || strings.Contains(out, "member_id_type, optional") {
+		t.Errorf("redundant <name>, required/optional prefix should not appear:\n%s", out)
 	}
 	if !strings.Contains(out, "enum: open_id=以 open_id 标识用户|user_id=以 user_id 标识用户") {
 		t.Errorf("expected compact enum value=meaning inline:\n%s", out)

cmd/service/paramhelp.go

@@ -30,6 +30,11 @@ func fieldFacts(f meta.Field) []string {
 	if d := sanitizeFieldDesc(f.Description); d != "" {
 		facts = append(facts, d)
 	}
+	if f.CanonicalType() == "boolean" {
+		// cobra shows no type word for bools and swallows a separate value as a
+		// positional, so spell out the presence-only contract.
+		facts = append(facts, "bool flag (presence = true; omit for false; takes no value)")
+	}
 	if opts := f.EnumOptions(); len(opts) > 0 {
 		facts = append(facts, "enum: "+formatEnumInline(opts))
 	}
@@ -42,20 +47,15 @@ func fieldFacts(f meta.Field) []string {
 	return facts
 }
 
-// paramFlagUsage renders the typed param flag's help line:
-//
-//	<param_name>, required|optional[. <fact>]...
-//
-// It leads with the canonical underscore param name (the key this flag
-// overrides in --params) and required/optional, then joins the field's facts
-// inline.
+// paramFlagUsage renders the typed param flag's help line: the field's facts
+// joined inline. Required/optional is not repeated here — the grouped help's
+// Required:/Optional: subheadings already partition the flags — and the
+// snake-case --params key is carried by the schema envelope (each param's
+// property + "flag") and the params-only addendum, so it isn't echoed on every
+// line either. Returns "" when the field has no facts (cobra then shows the bare
+// flag with its type).
 func paramFlagUsage(f meta.Field) string {
-	req := "optional"
-	if f.Required {
-		req = "required"
-	}
-	parts := append([]string{fmt.Sprintf("%s, %s", f.Name, req)}, fieldFacts(f)...)
-	return strings.Join(parts, ". ") + "."
+	return strings.Join(fieldFacts(f), ". ")
 }
 
 // paramExample picks a concrete sample for a params-only field's --help snippet:
@@ -103,8 +103,23 @@ func sanitizeOptionDesc(s string) string { return inlineClause(s, "。；;\n\r",
 // sanitizeFieldDesc is the field-description policy: one line per field, so
 // keep full sentences and cut only at note separators (meta_data appends
 // bullet notes after ;/；) — the later sentence often carries the key
-// affordance, e.g. user_mailbox_id's `可以输入"me"`.
-func sanitizeFieldDesc(s string) string { return inlineClause(s, "；;\n\r", 60) }
+// affordance, e.g. user_mailbox_id's `可以输入"me"`. The trailing doc
+// cross-reference is dropped first (see cutDocRef).
+func sanitizeFieldDesc(s string) string { return inlineClause(cutDocRef(s), "；;\n\r", 60) }
+
+// docRefRe matches a "see the docs" breadcrumb (更多信息参见…/获取方式见…/详见…).
+// On the compact flag line the markdown link's URL is stripped, so the
+// breadcrumb is a dead pointer — drop it. Anchored on a leading clause separator
+// so a subject that runs straight into the phrase isn't orphaned.
+var docRefRe = regexp.MustCompile(`[。；;，,、]\s*(更多信息|获取方式|获取方法|详见|[请可]?参[见考阅])`)
+
+// cutDocRef truncates s at the first doc-reference breadcrumb.
+func cutDocRef(s string) string {
+	if loc := docRefRe.FindStringIndex(s); loc != nil {
+		return s[:loc[0]]
+	}
+	return s
+}
 
 // formatEnumInline renders allowed values for the help line: "v=meaning" when
 // the value carries a (sanitized, truncated) description — so opaque numeric

cmd/service/service.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"sort"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
@@ -64,15 +65,38 @@ func registerServiceWithContext(ctx context.Context, parent *cobra.Command, svc
 	// resource-command chain — one level for a flat dotted resource like
 	// "chat.members", deeper for genuinely nested resources. A service with no
 	// methods keeps its bare command (svcCmd is created above regardless).
-	for _, ref := range apicatalog.ServiceMethods(svc, nil) {
+	refs := apicatalog.ServiceMethods(svc, nil)
+
+	// Collect each resource's verbs up front so resourceShort can summarize a
+	// resource as its verb list from the first ensureChildCommand call.
+	verbs := map[string][]string{}
+	for _, ref := range refs {
+		key := strings.Join(ref.ResourcePath, ".")
+		verbs[key] = append(verbs[key], ref.Method.Name)
+	}
+
+	for _, ref := range refs {
 		resCmd := svcCmd
+		var path []string
 		for _, seg := range ref.ResourcePath {
-			resCmd = ensureChildCommand(resCmd, seg, seg+" operations")
+			path = append(path, seg)
+			resCmd = ensureChildCommand(resCmd, seg, resourceShort(seg, verbs[strings.Join(path, ".")]))
 		}
 		resCmd.AddCommand(buildMethodCommand(ctx, f, newMethodCommandSpec(ref), nil, parent.PersistentFlags()))
 	}
 }
 
+// resourceShort summarizes a resource as its sorted verb list, or the
+// "<name> operations" placeholder for an intermediate group with no methods.
+func resourceShort(seg string, verbs []string) string {
+	if len(verbs) == 0 {
+		return seg + " operations"
+	}
+	sorted := append([]string(nil), verbs...)
+	sort.Strings(sorted)
+	return strings.Join(sorted, ", ")
+}
+
 // serviceShort is the service command's help summary: the localized description
 // from the registry, falling back to the metadata's own description.
 func serviceShort(svc meta.Service) string {
@@ -177,7 +201,19 @@ type methodCommandSpec struct {
 	// the API declares a body.
 	acceptsBody  bool
 	declaresBody bool
-	affordance   string // rendered hand-authored usage guidance (when-to-use, examples); "" if none
+	paginates    bool   // method accepts a page_token param (so --page-all is meaningful)
+	serviceName  string // owning service name (e.g. "approval"), for the lazy affordance lookup
+}
+
+// methodPaginates reports whether a method takes a page_token param, the signal
+// that makes the --page-all/--page-limit/--page-delay flags meaningful.
+func methodPaginates(m meta.Method) bool {
+	for _, f := range m.Params() {
+		if f.Name == "page_token" {
+			return true
+		}
+	}
+	return false
 }
 
 func newMethodCommandSpec(ref apicatalog.MethodRef) methodCommandSpec {
@@ -186,6 +222,7 @@ func newMethodCommandSpec(ref apicatalog.MethodRef) methodCommandSpec {
 		method:       m,
 		schemaPath:   ref.SchemaPath(),
 		servicePath:  ref.Service.ServicePath,
+		serviceName:  ref.Service.Name,
 		risk:         m.Risk,
 		restricts:    m.RestrictsIdentity(),
 		identities:   m.Identities(),
@@ -193,7 +230,7 @@ func newMethodCommandSpec(ref apicatalog.MethodRef) methodCommandSpec {
 		fileFields:   detectFileFields(m),
 		acceptsBody:  methodTakesBody(m.HTTPMethod),
 		declaresBody: len(m.Data()) > 0 || len(m.Files()) > 0,
-		affordance:   renderAffordance(m),
+		paginates:    methodPaginates(m),
 	}
 }
 
@@ -254,6 +291,14 @@ func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodComm
 	cmd.Flags().BoolVar(&opts.PageAll, "page-all", false, "automatically paginate through all pages")
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
+	// Keep the pagination flags registered (a harmless no-op if passed) but hide
+	// them from help on non-paginating commands, so help doesn't imply a
+	// get/write can paginate.
+	if !spec.paginates {
+		for _, name := range []string{"page-all", "page-limit", "page-delay"} {
+			_ = cmd.Flags().MarkHidden(name)
+		}
+	}
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
 	cmd.Flags().Bool("json", false, "shorthand for --format json")
 	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
@@ -271,10 +316,11 @@ func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodComm
 
 	// Registered last so the collision guard sees the standard flags above.
 	opts.binder = newParamFlagBinder(cmd, spec.params, reserved)
-	// Single composition point for Long: description, affordance, schema
-	// pointer, and the binder's params-only addendum (params whose flag name is
-	// taken, reachable via --params only).
-	cmd.Long = methodLong(m.Description, spec.affordance, spec.schemaPath, opts.binder.paramsOnlyHelp())
+	// Build-time Long; the agent guidance is added lazily by PrepareMethodHelp
+	// (setMethodHelpData records the coordinates it needs).
+	paramsOnly := opts.binder.paramsOnlyHelp()
+	cmd.Long = methodLong(m.Description, spec.schemaPath, paramsOnly)
+	setMethodHelpData(cmd, spec.serviceName, m.ID, spec.schemaPath, paramsOnly)
 
 	// Group flags for the grouped --help renderer (typed param flags are grouped
 	// as API Parameters by the binder). tagFlagGroup is a no-op for flags not
@@ -292,13 +338,11 @@ func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodComm
 	tagFlagGroup(cmd.Flags(), "file", groupBody)
 	if fl := cmd.Flags().Lookup("params"); fl != nil {
 		annotate(fl, flagGroupAnnotation, []string{groupRaw})
-		// State the precedence rule where the agent reads it: --params is the
-		// base, typed flags override. Only meaningful when typed flags exist.
+		// Keep the precedence rule on the flag's own one line (not a multi-line
+		// note that breaks the one-entry-per-flag rhythm an agent parses). Only
+		// meaningful when typed flags exist to override.
 		if len(spec.params) > 0 {
-			annotate(fl, flagNoteAnnotation, []string{
-				"Typed API parameter flags above are preferred.",
-				"If both are set, typed flags override matching keys in --params.",
-			})
+			fl.Usage = "Raw URL/query params JSON. Supports - and @file. If both set, typed flags override matching keys in --params."
 		}
 	}
 	for _, name := range []string{"as", "dry-run", "page-all", "page-limit", "page-delay", "yes"} {

cmd/whoami/whoami.go

@@ -0,0 +1,163 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package whoami
+
+import (
+	"context"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/identitydiag"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// whoamiResult is the structured output of `lark-cli whoami`.
+//
+// The self-vs-delegated distinction is carried by `identity`: a bot identity is
+// the app acting as itself; a user identity is the app acting *on behalf of* a
+// person (calls are attributed to that user, who is not necessarily present).
+// onBehalfOf only *names* that person and so appears only once a user is
+// resolved — a user identity that is not signed in still has identity "user"
+// but no onBehalfOf yet. Do not read "no onBehalfOf" as "self"; read `identity`.
+type whoamiResult struct {
+	Profile        string         `json:"profile"`
+	AppID          string         `json:"appId"`
+	Brand          core.LarkBrand `json:"brand"`
+	DefaultAs      string         `json:"defaultAs"`
+	Identity       string         `json:"identity"`
+	IdentitySource string         `json:"identitySource"`
+	Available      bool           `json:"available"`
+	TokenStatus    string         `json:"tokenStatus"`
+	OnBehalfOf     *delegatedUser `json:"onBehalfOf,omitempty"`
+	Hint           string         `json:"hint,omitempty"`
+}
+
+// delegatedUser is the user a user-identity acts on behalf of.
+type delegatedUser struct {
+	UserName string `json:"userName,omitempty"`
+	OpenID   string `json:"openId,omitempty"`
+}
+
+// Options holds inputs for the whoami command.
+type Options struct {
+	Factory *cmdutil.Factory
+	As      string
+}
+
+// NewCmdWhoami creates the top-level whoami command. It reports the identity
+// that the next API call would actually use (resolved via Factory.ResolveAs),
+// together with the active profile, app, and token status. Output is always
+// JSON — whoami is consumed by agents. With the built-in credential path it is
+// local-only; when an external credential provider manages tokens, resolving
+// the identity may contact that provider.
+func NewCmdWhoami(f *cmdutil.Factory) *cobra.Command {
+	opts := &Options{Factory: f}
+	cmd := &cobra.Command{
+		Use:   "whoami",
+		Short: "Show the current effective identity, app, profile, and token status (JSON)",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return whoamiRun(cmd, opts)
+		},
+	}
+	cmdutil.DisableAuthCheck(cmd)
+	cmdutil.AddAPIIdentityFlag(context.Background(), cmd, f, &opts.As)
+	// Output is always JSON. Accept (and ignore) --json so existing
+	// `whoami --json` callers don't break; hide it to avoid implying a non-JSON
+	// mode exists.
+	cmd.Flags().Bool("json", true, "deprecated: output is always JSON")
+	_ = cmd.Flags().MarkHidden("json")
+	cmdutil.SetRisk(cmd, "read")
+	return cmd
+}
+
+func whoamiRun(cmd *cobra.Command, opts *Options) error {
+	f := opts.Factory
+	cfg, err := f.Config()
+	if err != nil {
+		return err
+	}
+	ctx := cmd.Context()
+	flagAs := core.Identity(opts.As)
+	as := f.ResolveAs(ctx, cmd, flagAs)
+	// Validate as a real API call does (strict mode, then identity) so whoami
+	// can't preview an identity the next call would refuse.
+	if err := f.CheckStrictMode(ctx, as); err != nil {
+		return err
+	}
+	if err := f.CheckIdentity(as, []string{"user", "bot"}); err != nil {
+		return err
+	}
+	source := resolveSource(
+		cmd.Flags().Changed("as"),
+		flagAs,
+		f.IdentityAutoDetected,
+		f.ResolveStrictMode(ctx).ForcedIdentity(),
+	)
+	diag := identitydiag.Diagnose(ctx, f, cfg, false)
+	res := buildResult(cfg, as, source, diag)
+	output.PrintJson(f.IOStreams.Out, res)
+	return nil
+}
+
+// resolveSource derives how the effective identity became effective.
+// Mirrors Factory.ResolveAs precedence: explicit flag wins; otherwise an
+// auto-detected result means auto-detect; otherwise a strict-mode forced
+// identity means strict-mode; otherwise it came from configured default-as.
+// Values are snake_case to match the other enum fields (e.g. tokenStatus).
+func resolveSource(changedAs bool, flagAs core.Identity, autoDetected bool, strictForced core.Identity) string {
+	if changedAs && (flagAs == core.AsUser || flagAs == core.AsBot) {
+		return "flag"
+	}
+	if autoDetected {
+		return "auto_detect"
+	}
+	if strictForced != "" {
+		return "strict_mode"
+	}
+	return "default_as"
+}
+
+// buildResult maps the resolved identity and local diagnostics into the output.
+// ResolveAs only ever returns user or bot, so the default branch handles user.
+func buildResult(cfg *core.CliConfig, as core.Identity, source string, diag identitydiag.Result) *whoamiResult {
+	defaultAs := cfg.DefaultAs
+	if defaultAs == "" {
+		defaultAs = core.AsAuto
+	}
+	res := &whoamiResult{
+		Profile:        cfg.ProfileName,
+		AppID:          cfg.AppID,
+		Brand:          cfg.Brand,
+		DefaultAs:      string(defaultAs),
+		Identity:       string(as),
+		IdentitySource: source,
+	}
+	// Use the diagnosed hint as-is: it is tailored to the credential source, so
+	// it never says "auth login" when that is blocked under an external provider.
+	switch as {
+	case core.AsBot:
+		res.Available = diag.Bot.Available
+		res.TokenStatus = diag.Bot.Status
+		if !diag.Bot.Available {
+			res.Hint = diag.Bot.Hint
+		}
+	default: // user
+		res.Available = diag.User.Available
+		// Use Status (not the raw TokenStatus) so the vocab matches the bot
+		// branch: "ready" means usable for both. available stays the canonical
+		// usable signal; tokenStatus is the readable state behind it.
+		res.TokenStatus = diag.User.Status
+		// Set onBehalfOf only when a user is actually resolved; an unresolved
+		// user identity (not signed in) has no one to act on behalf of yet.
+		if diag.User.UserName != "" || diag.User.OpenID != "" {
+			res.OnBehalfOf = &delegatedUser{UserName: diag.User.UserName, OpenID: diag.User.OpenID}
+		}
+		if !diag.User.Available {
+			res.Hint = diag.User.Hint
+		}
+	}
+	return res
+}

cmd/whoami/whoami_test.go

@@ -0,0 +1,320 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package whoami
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/identitydiag"
+)
+
+func TestResolveSource(t *testing.T) {
+	tests := []struct {
+		name         string
+		changedAs    bool
+		flagAs       core.Identity
+		autoDetected bool
+		strictForced core.Identity
+		want         string
+	}{
+		{"explicit flag user", true, core.AsUser, false, "", "flag"},
+		{"explicit flag bot", true, core.AsBot, false, "", "flag"},
+		{"flag auto falls through to auto-detect", true, core.AsAuto, true, "", "auto_detect"},
+		{"auto detected", false, "", true, "", "auto_detect"},
+		{"strict mode", false, "", false, core.AsBot, "strict_mode"},
+		{"default_as", false, "", false, "", "default_as"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := resolveSource(tt.changedAs, tt.flagAs, tt.autoDetected, tt.strictForced)
+			if got != tt.want {
+				t.Errorf("resolveSource() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestBuildResult_UserValid(t *testing.T) {
+	cfg := &core.CliConfig{ProfileName: "my-app", AppID: "cli_x", Brand: core.BrandLark, DefaultAs: core.AsAuto}
+	diag := identitydiag.Result{
+		User: identitydiag.Identity{Available: true, Status: "ready", TokenStatus: "valid", OpenID: "ou_x", UserName: "Alice"},
+	}
+	r := buildResult(cfg, core.AsUser, "auto_detect", diag)
+
+	if r.Identity != "user" || r.IdentitySource != "auto_detect" {
+		t.Fatalf("identity/source = %q/%q", r.Identity, r.IdentitySource)
+	}
+	// tokenStatus mirrors the unified Status vocab ("ready"), not the raw "valid".
+	if !r.Available || r.TokenStatus != "ready" {
+		t.Fatalf("available=%v status=%q", r.Available, r.TokenStatus)
+	}
+	if r.OnBehalfOf == nil || r.OnBehalfOf.OpenID != "ou_x" || r.OnBehalfOf.UserName != "Alice" {
+		t.Fatalf("onBehalfOf = %#v, want Alice/ou_x", r.OnBehalfOf)
+	}
+	if r.Hint != "" {
+		t.Fatalf("hint = %q, want empty", r.Hint)
+	}
+	if r.Profile != "my-app" || r.AppID != "cli_x" || r.Brand != core.BrandLark {
+		t.Fatalf("app context = %#v", r)
+	}
+}
+
+func TestBuildResult_UserMissingToken(t *testing.T) {
+	cfg := &core.CliConfig{ProfileName: "p", AppID: "cli_x", Brand: core.BrandLark}
+	diag := identitydiag.Result{
+		User: identitydiag.Identity{Available: false, Status: "missing", Hint: "run: lark-cli auth login --help"}, // never logged in
+	}
+	r := buildResult(cfg, core.AsUser, "auto_detect", diag)
+
+	if r.Available {
+		t.Fatalf("available = true, want false")
+	}
+	if r.TokenStatus != "missing" {
+		t.Fatalf("tokenStatus = %q, want missing", r.TokenStatus)
+	}
+	// whoami renders the diagnosed hint verbatim (single source of truth) so it
+	// stays correct for the external-provider path without whoami knowing about it.
+	if r.Hint != diag.User.Hint {
+		t.Fatalf("hint = %q, want propagated %q", r.Hint, diag.User.Hint)
+	}
+	if r.DefaultAs != "auto" {
+		t.Fatalf("defaultAs = %q, want auto (empty normalized)", r.DefaultAs)
+	}
+}
+
+func TestBuildResult_BotReady(t *testing.T) {
+	cfg := &core.CliConfig{ProfileName: "p", AppID: "cli_x", Brand: core.BrandFeishu, DefaultAs: core.AsBot}
+	diag := identitydiag.Result{
+		Bot: identitydiag.Identity{Available: true, Status: "ready"},
+	}
+	r := buildResult(cfg, core.AsBot, "default_as", diag)
+
+	if r.Identity != "bot" || r.IdentitySource != "default_as" {
+		t.Fatalf("identity/source = %q/%q", r.Identity, r.IdentitySource)
+	}
+	if !r.Available || r.TokenStatus != "ready" {
+		t.Fatalf("available=%v status=%q", r.Available, r.TokenStatus)
+	}
+	if r.OnBehalfOf != nil {
+		t.Fatalf("bot must not carry onBehalfOf: %#v", r.OnBehalfOf)
+	}
+	if r.Hint != "" {
+		t.Fatalf("hint = %q, want empty", r.Hint)
+	}
+}
+
+func TestBuildResult_BotNotConfigured(t *testing.T) {
+	cfg := &core.CliConfig{ProfileName: "p", AppID: "cli_x", Brand: core.BrandFeishu}
+	diag := identitydiag.Result{
+		Bot: identitydiag.Identity{Available: false, Status: "not_configured", Hint: "run: lark-cli config --help"},
+	}
+	r := buildResult(cfg, core.AsBot, "auto_detect", diag)
+
+	if r.Available {
+		t.Fatalf("available = true, want false")
+	}
+	if r.TokenStatus != "not_configured" {
+		t.Fatalf("tokenStatus = %q, want not_configured", r.TokenStatus)
+	}
+	if r.Hint != diag.Bot.Hint {
+		t.Fatalf("hint = %q, want propagated %q", r.Hint, diag.Bot.Hint)
+	}
+}
+
+func TestWhoami_BotJSON(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		ProfileName: "test-profile", AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	cmd := NewCmdWhoami(f)
+	cmd.SetArgs([]string{}) // bare whoami: output is always JSON, no flag needed
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+
+	var got whoamiResult
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v\n%s", err, stdout.String())
+	}
+	if got.Identity != "bot" {
+		t.Fatalf("identity = %q, want bot", got.Identity)
+	}
+	if !got.Available || got.TokenStatus != "ready" {
+		t.Fatalf("available=%v status=%q, want true/ready", got.Available, got.TokenStatus)
+	}
+	if got.Profile != "test-profile" {
+		t.Fatalf("profile = %q, want test-profile", got.Profile)
+	}
+	if got.IdentitySource == "" {
+		t.Fatalf("identitySource empty")
+	}
+	if got.OnBehalfOf != nil {
+		t.Fatalf("bot (self) must not carry onBehalfOf: %#v", got.OnBehalfOf)
+	}
+}
+
+func TestWhoami_RejectsInvalidAs(t *testing.T) {
+	for _, bad := range []string{"admin", "USER", "bogus123", ""} {
+		t.Run("as="+bad, func(t *testing.T) {
+			f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+				ProfileName: "p", AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+			})
+			cmd := NewCmdWhoami(f)
+			cmd.SetArgs([]string{"--as", bad})
+			err := cmd.Execute()
+			if err == nil {
+				t.Fatalf("Execute() with --as %q = nil, want validation error", bad)
+			}
+			// Lock in the typed validation contract: an unsupported identity must
+			// surface as a *errs.ValidationError on --as, not just any error.
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("Execute() with --as %q: error type = %T, want *errs.ValidationError: %v", bad, err, err)
+			}
+			if ve.Subtype != errs.SubtypeInvalidArgument {
+				t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
+			}
+			if ve.Param != "--as" {
+				t.Errorf("Param = %q, want %q", ve.Param, "--as")
+			}
+		})
+	}
+}
+
+func TestWhoami_ConfigErrorPropagates(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		ProfileName: "p", AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	wantErr := fmt.Errorf("boom")
+	f.Config = func() (*core.CliConfig, error) { return nil, wantErr }
+
+	cmd := NewCmdWhoami(f)
+	cmd.SetArgs([]string{"--json"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatalf("Execute() error = nil, want propagated config error")
+	}
+	// The f.Config() failure must propagate unchanged, not be masked by a later
+	// command-execution error.
+	if !errors.Is(err, wantErr) {
+		t.Fatalf("Execute() error = %v, want it to wrap %v", err, wantErr)
+	}
+}
+
+func TestWhoami_StrictModeRejectsCrossIdentity(t *testing.T) {
+	// Bot-only account → strict mode bot. A real `--as user` call would be
+	// rejected by CheckStrictMode; whoami must reject it identically rather than
+	// previewing a user identity the next call would refuse.
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		ProfileName: "p", AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+		SupportedIdentities: 2, // bot only
+	})
+	cmd := NewCmdWhoami(f)
+	cmd.SetArgs([]string{"--as", "user", "--json"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatalf("Execute() with --as user under strict bot = nil, want strict-mode rejection")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("error type = %T, want *errs.ValidationError: %v", err, err)
+	}
+}
+
+type fakeExtProvider struct {
+	name    string
+	account *extcred.Account
+}
+
+func (p *fakeExtProvider) Name() string { return p.name }
+func (p *fakeExtProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
+	return p.account, nil
+}
+func (p *fakeExtProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
+	return nil, nil // no UAT served locally; whoami runs with verify=false
+}
+
+func externalWhoamiFactory(cfg *core.CliConfig) (*cmdutil.Factory, *bytes.Buffer) {
+	cred := credential.NewCredentialProvider(
+		[]extcred.Provider{&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: cfg.AppID}}},
+		nil, nil,
+		func() (*http.Client, error) { return nil, nil },
+	)
+	out := &bytes.Buffer{}
+	f := &cmdutil.Factory{
+		Config:     func() (*core.CliConfig, error) { return cfg, nil },
+		Credential: cred,
+		IOStreams:  &cmdutil.IOStreams{Out: out, ErrOut: &bytes.Buffer{}},
+	}
+	return f, out
+}
+
+// Regression for the external-provider blind spot: with credentials managed by
+// an extension provider, a signed-in user must read as available, and an
+// unavailable identity must not be told to "auth login" (which is blocked).
+func TestWhoami_ExternalProvider_UserReady(t *testing.T) {
+	cfg := &core.CliConfig{
+		ProfileName: "p", AppID: "cli_x", Brand: core.BrandFeishu,
+		SupportedIdentities: uint8(extcred.SupportsAll), UserOpenId: "ou_x", UserName: "Alice",
+	}
+	f, out := externalWhoamiFactory(cfg)
+
+	cmd := NewCmdWhoami(f)
+	cmd.SetArgs([]string{"--as", "user", "--json"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	var got whoamiResult
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatalf("Unmarshal: %v\n%s", err, out.String())
+	}
+	if got.Identity != "user" || !got.Available || got.TokenStatus != "ready" {
+		t.Fatalf("got %#v, want user/available/ready", got)
+	}
+	if got.OnBehalfOf == nil || got.OnBehalfOf.UserName != "Alice" || got.OnBehalfOf.OpenID != "ou_x" {
+		t.Fatalf("onBehalfOf = %#v, want Alice/ou_x (delegated)", got.OnBehalfOf)
+	}
+	if got.Hint != "" {
+		t.Fatalf("hint = %q, want empty when available", got.Hint)
+	}
+}
+
+func TestWhoami_ExternalProvider_UserHintNotKeychain(t *testing.T) {
+	cfg := &core.CliConfig{
+		ProfileName: "p", AppID: "cli_x", Brand: core.BrandFeishu,
+		SupportedIdentities: uint8(extcred.SupportsUser), // user supported but not signed in
+	}
+	f, out := externalWhoamiFactory(cfg)
+
+	cmd := NewCmdWhoami(f)
+	cmd.SetArgs([]string{"--as", "user", "--json"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	var got whoamiResult
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatalf("Unmarshal: %v\n%s", err, out.String())
+	}
+	if got.Identity != "user" || got.Available {
+		t.Fatalf("got identity=%q available=%v, want user/false", got.Identity, got.Available)
+	}
+	if strings.Contains(got.Hint, "auth login") {
+		t.Fatalf("hint must not point at auth login under external provider: %q", got.Hint)
+	}
+	if !strings.Contains(got.Hint, "external") {
+		t.Fatalf("hint should explain external management: %q", got.Hint)
+	}
+}

content_embed.go

@@ -0,0 +1,41 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package main
+
+import (
+	"embed"
+	"fmt"
+	"io/fs"
+	"os"
+
+	"github.com/larksuite/cli/cmd"
+	"github.com/larksuite/cli/internal/affordance"
+)
+
+// embeddedContentFS bundles the agent-readable content that must ship in lockstep
+// with the binary: each skill's docs (SKILL.md + references/, plus whiteboard's
+// routes/ and scenes/) and the per-domain affordance guidance (affordance/*.md).
+// Machine-resource skill dirs (assets/, scripts/) are excluded. It's a whitelist —
+// a new content type is omitted until added to the embed list. The embed must live
+// in this root package because go:embed cannot reach up out of a package's dir.
+//
+//go:embed skills/*/SKILL.md skills/*/references skills/*/routes skills/*/scenes affordance/*.md
+var embeddedContentFS embed.FS
+
+// init wires the embedded content into the CLI. It compiles into `go build .` but
+// not the single-file preview build (`go build ./main.go`), so that build stays
+// self-contained (shipping no embedded content). Assembly failures warn on stderr
+// rather than panicking — embedded content is nice-to-have, not load-bearing.
+func init() {
+	if sub, err := fs.Sub(embeddedContentFS, "skills"); err != nil {
+		fmt.Fprintln(os.Stderr, "warning: skills embed assembly failed, skills commands disabled:", err)
+	} else {
+		cmd.SetEmbeddedSkillContent(sub)
+	}
+	if sub, err := fs.Sub(embeddedContentFS, "affordance"); err != nil {
+		fmt.Fprintln(os.Stderr, "warning: affordance embed assembly failed, command guidance disabled:", err)
+	} else {
+		affordance.SetSource(sub)
+	}
+}

events/vc/participant_meeting_joined.go

@@ -0,0 +1,62 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// VCParticipantMeetingJoinedOutput is the flattened shape for vc.meeting.participant_meeting_joined_v1.
+type VCParticipantMeetingJoinedOutput struct {
+	Type            string `json:"type"                      desc:"Event type; always vc.meeting.participant_meeting_joined_v1"`
+	EventID         string `json:"event_id,omitempty"        desc:"Globally unique event ID; safe for deduplication"`
+	Timestamp       string `json:"timestamp,omitempty"       desc:"Event delivery time (ms timestamp string); taken from header.create_time when present" kind:"timestamp_ms"`
+	MeetingID       string `json:"meeting_id,omitempty"      desc:"Meeting ID" kind:"meeting_id"`
+	Topic           string `json:"topic,omitempty"           desc:"Meeting topic"`
+	MeetingNo       string `json:"meeting_no,omitempty"      desc:"Meeting number"`
+	StartTime       string `json:"start_time,omitempty"      desc:"Meeting start time in RFC3339, converted to the local timezone"`
+	CalendarEventID string `json:"calendar_event_id,omitempty" desc:"Calendar event ID associated with the meeting"`
+}
+
+func processVCParticipantMeetingJoined(_ context.Context, _ event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	var envelope struct {
+		Header struct {
+			EventID    string `json:"event_id"`
+			EventType  string `json:"event_type"`
+			CreateTime string `json:"create_time"`
+		} `json:"header"`
+		Event struct {
+			Meeting struct {
+				ID              string `json:"id"`
+				Topic           string `json:"topic"`
+				MeetingNo       string `json:"meeting_no"`
+				StartTime       string `json:"start_time"`
+				EndTime         string `json:"end_time"`
+				CalendarEventID string `json:"calendar_event_id"`
+			} `json:"meeting"`
+		} `json:"event"`
+	}
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload so consumers still see the event
+	}
+
+	meeting := envelope.Event.Meeting
+	out := &VCParticipantMeetingJoinedOutput{
+		Type:            envelope.Header.EventType,
+		EventID:         envelope.Header.EventID,
+		Timestamp:       envelope.Header.CreateTime,
+		MeetingID:       meeting.ID,
+		Topic:           meeting.Topic,
+		MeetingNo:       meeting.MeetingNo,
+		StartTime:       unixSecondsToLocalRFC3339(meeting.StartTime),
+		CalendarEventID: meeting.CalendarEventID,
+	}
+	if out.Type == "" {
+		out.Type = raw.EventType
+	}
+	return json.Marshal(out)
+}

events/vc/participant_meeting_lifecycle_test.go

@@ -0,0 +1,281 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+func TestVCKeys_ProcessedMeetingLifecycleRegistered(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	for _, tc := range []struct {
+		eventType  string
+		schemaType reflect.Type
+	}{
+		{eventTypeMeetingStarted, reflect.TypeOf(VCParticipantMeetingStartedOutput{})},
+		{eventTypeMeetingJoined, reflect.TypeOf(VCParticipantMeetingJoinedOutput{})},
+	} {
+		t.Run(tc.eventType, func(t *testing.T) {
+			def, ok := event.Lookup(tc.eventType)
+			if !ok {
+				t.Fatalf("%s should be registered via Keys()", tc.eventType)
+			}
+			if def.Schema.Custom == nil {
+				t.Error("Processed key must set Schema.Custom")
+			}
+			if def.Schema.Native != nil {
+				t.Error("Processed key must not set Schema.Native")
+			}
+			if def.Process == nil {
+				t.Error("Process must not be nil for processed key")
+			}
+			if def.PreConsume == nil {
+				t.Error("PreConsume must not be nil for processed key")
+			}
+			if len(def.Scopes) != 1 || def.Scopes[0] != "vc:meeting.meetingevent:read" {
+				t.Errorf("Scopes = %v", def.Scopes)
+			}
+			if len(def.AuthTypes) != 1 || def.AuthTypes[0] != "user" {
+				t.Errorf("AuthTypes = %v", def.AuthTypes)
+			}
+			if len(def.RequiredConsoleEvents) != 1 || def.RequiredConsoleEvents[0] != tc.eventType {
+				t.Errorf("RequiredConsoleEvents = %v", def.RequiredConsoleEvents)
+			}
+			if def.Schema.Custom.Type != tc.schemaType {
+				t.Errorf("Custom schema Type = %v, want %v", def.Schema.Custom.Type, tc.schemaType)
+			}
+		})
+	}
+}
+
+func TestProcessVCParticipantMeetingLifecycle(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	for _, tc := range []struct {
+		name      string
+		eventType string
+		process   event.ProcessFunc
+	}{
+		{
+			name:      "started",
+			eventType: eventTypeMeetingStarted,
+			process:   processVCParticipantMeetingStarted,
+		},
+		{
+			name:      "joined",
+			eventType: eventTypeMeetingJoined,
+			process:   processVCParticipantMeetingJoined,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			payload := `{
+				"schema": "2.0",
+				"header": {
+					"event_id": "ev_vc_lifecycle_001",
+					"event_type": "` + tc.eventType + `",
+					"create_time": "1608725989000",
+					"app_id": "cli_test"
+				},
+				"event": {
+					"meeting": {
+						"id": "6911188411934433028",
+						"topic": "my meeting",
+						"meeting_no": "235812466",
+						"start_time": "1608883322",
+						"end_time": "1608883899",
+						"calendar_event_id": "efa67a98-06a8-4df5-8559-746c8f4477ef_0"
+					}
+				}
+			}`
+			out := runMeetingLifecycleMap(t, tc.eventType, tc.process, payload)
+
+			if out["type"] != tc.eventType {
+				t.Errorf("type = %q", out["type"])
+			}
+			if out["event_id"] != "ev_vc_lifecycle_001" {
+				t.Errorf("event_id = %q", out["event_id"])
+			}
+			if out["timestamp"] != "1608725989000" {
+				t.Errorf("timestamp = %q", out["timestamp"])
+			}
+			if out["meeting_id"] != "6911188411934433028" {
+				t.Errorf("meeting_id = %q", out["meeting_id"])
+			}
+			if out["topic"] != "my meeting" || out["meeting_no"] != "235812466" {
+				t.Errorf("topic/meeting_no = %q/%q", out["topic"], out["meeting_no"])
+			}
+			if out["calendar_event_id"] != "efa67a98-06a8-4df5-8559-746c8f4477ef_0" {
+				t.Errorf("calendar_event_id = %q", out["calendar_event_id"])
+			}
+			if want := time.Unix(1608883322, 0).Local().Format(time.RFC3339); out["start_time"] != want {
+				t.Errorf("start_time = %q, want %q", out["start_time"], want)
+			}
+			if _, hasEndTime := out["end_time"]; hasEndTime {
+				t.Error("end_time should not be present in started/joined output")
+			}
+		})
+	}
+}
+
+func TestProcessVCParticipantMeetingLifecycle_InvalidMeetingTimes(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	for _, tc := range []struct {
+		name      string
+		eventType string
+		process   event.ProcessFunc
+	}{
+		{"started", eventTypeMeetingStarted, processVCParticipantMeetingStarted},
+		{"joined", eventTypeMeetingJoined, processVCParticipantMeetingJoined},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			payload := `{
+				"schema": "2.0",
+				"header": {
+					"event_id": "ev_vc_lifecycle_002",
+					"event_type": "` + tc.eventType + `",
+					"create_time": "1608725989001"
+				},
+				"event": {
+					"meeting": {
+						"id": "meeting_invalid_time",
+						"start_time": "bad",
+						"end_time": ""
+					}
+				}
+			}`
+			out := runMeetingLifecycleRaw(t, tc.eventType, tc.process, payload)
+			switch tc.eventType {
+			case eventTypeMeetingStarted:
+				var started VCParticipantMeetingStartedOutput
+				if err := json.Unmarshal(out, &started); err != nil {
+					t.Fatalf("Process output is not valid started JSON: %v\nraw=%s", err, string(out))
+				}
+				if started.StartTime != "" {
+					t.Errorf("StartTime = %q, want empty string", started.StartTime)
+				}
+			case eventTypeMeetingJoined:
+				var joined VCParticipantMeetingJoinedOutput
+				if err := json.Unmarshal(out, &joined); err != nil {
+					t.Fatalf("Process output is not valid joined JSON: %v\nraw=%s", err, string(out))
+				}
+				if joined.StartTime != "" {
+					t.Errorf("StartTime = %q, want empty string", joined.StartTime)
+				}
+			}
+		})
+	}
+}
+
+func TestProcessVCParticipantMeetingLifecycle_MalformedPayload(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	for _, tc := range []struct {
+		name      string
+		eventType string
+		process   event.ProcessFunc
+	}{
+		{"started", eventTypeMeetingStarted, processVCParticipantMeetingStarted},
+		{"joined", eventTypeMeetingJoined, processVCParticipantMeetingJoined},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			raw := &event.RawEvent{
+				EventType: tc.eventType,
+				Payload:   json.RawMessage(`not json`),
+				Timestamp: time.Now(),
+			}
+			got, err := tc.process(context.Background(), nil, raw, nil)
+			if err != nil {
+				t.Fatalf("Process should swallow parse errors, got %v", err)
+			}
+			if string(got) != "not json" {
+				t.Errorf("malformed fallback output = %q, want original bytes", string(got))
+			}
+		})
+	}
+}
+
+func TestVCParticipantMeetingLifecycle_PreConsumeSubscriptionLifecycle(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	for _, eventType := range []string{eventTypeMeetingStarted, eventTypeMeetingJoined} {
+		t.Run(eventType, func(t *testing.T) {
+			def, ok := event.Lookup(eventType)
+			if !ok {
+				t.Fatalf("%s should be registered via Keys()", eventType)
+			}
+
+			type call struct {
+				method string
+				path   string
+				body   any
+			}
+			var calls []call
+			rt := &stubAPIClient{
+				callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+					calls = append(calls, call{method: method, path: path, body: body})
+					return json.RawMessage(`{"code":0,"msg":"success","data":{}}`), nil
+				},
+			}
+
+			cleanup, err := def.PreConsume(context.Background(), rt, nil)
+			if err != nil {
+				t.Fatalf("PreConsume error: %v", err)
+			}
+			if cleanup == nil {
+				t.Fatal("cleanup must not be nil")
+			}
+			if len(calls) != 1 {
+				t.Fatalf("calls after subscribe = %d, want 1", len(calls))
+			}
+			if calls[0].method != "POST" || calls[0].path != pathMeetingSubscribe {
+				t.Fatalf("subscribe call = %+v", calls[0])
+			}
+			assertSubscriptionRequest(t, calls[0].body, eventType)
+
+			cleanup()
+			if len(calls) != 2 {
+				t.Fatalf("calls after cleanup = %d, want 2", len(calls))
+			}
+			if calls[1].method != "POST" || calls[1].path != pathMeetingUnsubscribe {
+				t.Fatalf("unsubscribe call = %+v", calls[1])
+			}
+			assertSubscriptionRequest(t, calls[1].body, eventType)
+		})
+	}
+}
+
+func runMeetingLifecycleMap(t *testing.T, eventType string, process event.ProcessFunc, payload string) map[string]string {
+	t.Helper()
+	got := runMeetingLifecycleRaw(t, eventType, process, payload)
+	if got == nil {
+		t.Fatal("Process output is nil")
+	}
+	var out map[string]string
+	if err := json.Unmarshal(got, &out); err != nil {
+		t.Fatalf("Process output is not valid flat JSON object: %v\nraw=%s", err, string(got))
+	}
+	return out
+}
+
+func runMeetingLifecycleRaw(t *testing.T, eventType string, process event.ProcessFunc, payload string) json.RawMessage {
+	t.Helper()
+	raw := &event.RawEvent{
+		EventType: eventType,
+		Payload:   json.RawMessage(payload),
+		Timestamp: time.Now(),
+	}
+	got, err := process(context.Background(), nil, raw, nil)
+	if err != nil {
+		t.Fatalf("Process error: %v", err)
+	}
+	return got
+}

events/vc/participant_meeting_started.go

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// VCParticipantMeetingStartedOutput is the flattened shape for vc.meeting.participant_meeting_started_v1.
+type VCParticipantMeetingStartedOutput struct {
+	Type            string `json:"type"                      desc:"Event type; always vc.meeting.participant_meeting_started_v1"`
+	EventID         string `json:"event_id,omitempty"        desc:"Globally unique event ID; safe for deduplication"`
+	Timestamp       string `json:"timestamp,omitempty"       desc:"Event delivery time (ms timestamp string); taken from header.create_time when present" kind:"timestamp_ms"`
+	MeetingID       string `json:"meeting_id,omitempty"      desc:"Meeting ID" kind:"meeting_id"`
+	Topic           string `json:"topic,omitempty"           desc:"Meeting topic"`
+	MeetingNo       string `json:"meeting_no,omitempty"      desc:"Meeting number"`
+	StartTime       string `json:"start_time,omitempty"      desc:"Meeting start time in RFC3339, converted to the local timezone"`
+	CalendarEventID string `json:"calendar_event_id,omitempty" desc:"Calendar event ID associated with the meeting"`
+}
+
+func processVCParticipantMeetingStarted(_ context.Context, _ event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	var envelope struct {
+		Header struct {
+			EventID    string `json:"event_id"`
+			EventType  string `json:"event_type"`
+			CreateTime string `json:"create_time"`
+		} `json:"header"`
+		Event struct {
+			Meeting struct {
+				ID              string `json:"id"`
+				Topic           string `json:"topic"`
+				MeetingNo       string `json:"meeting_no"`
+				StartTime       string `json:"start_time"`
+				CalendarEventID string `json:"calendar_event_id"`
+			} `json:"meeting"`
+		} `json:"event"`
+	}
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload so consumers still see the event
+	}
+
+	meeting := envelope.Event.Meeting
+	out := &VCParticipantMeetingStartedOutput{
+		Type:            envelope.Header.EventType,
+		EventID:         envelope.Header.EventID,
+		Timestamp:       envelope.Header.CreateTime,
+		MeetingID:       meeting.ID,
+		Topic:           meeting.Topic,
+		MeetingNo:       meeting.MeetingNo,
+		StartTime:       unixSecondsToLocalRFC3339(meeting.StartTime),
+		CalendarEventID: meeting.CalendarEventID,
+	}
+	if out.Type == "" {
+		out.Type = raw.EventType
+	}
+	return json.Marshal(out)
+}

events/vc/register.go

@@ -11,6 +11,8 @@ import (
 )
 
 const (
+	eventTypeMeetingStarted               = "vc.meeting.participant_meeting_started_v1"
+	eventTypeMeetingJoined                = "vc.meeting.participant_meeting_joined_v1"
 	eventTypeMeetingEnded                 = "vc.meeting.participant_meeting_ended_v1"
 	eventTypeNoteGenerated                = "vc.note.generated_v1"
 	eventTypeRecordingStarted             = "vc.recording.recording_started_v1"
@@ -30,6 +32,38 @@ const (
 // Keys returns all VC-domain EventKey definitions.
 func Keys() []event.KeyDefinition {
 	return []event.KeyDefinition{
+		{
+			Key:         eventTypeMeetingStarted,
+			DisplayName: "Participant meeting started",
+			Description: "Triggered when a meeting the current user participates in has started",
+			EventType:   eventTypeMeetingStarted,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCParticipantMeetingStartedOutput{})},
+			},
+			Process:    processVCParticipantMeetingStarted,
+			PreConsume: subscriptionPreConsume(eventTypeMeetingStarted, pathMeetingSubscribe, pathMeetingUnsubscribe),
+			Scopes:     []string{"vc:meeting.meetingevent:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeMeetingStarted},
+		},
+		{
+			Key:         eventTypeMeetingJoined,
+			DisplayName: "Participant meeting joined",
+			Description: "Triggered when the current user joins a meeting",
+			EventType:   eventTypeMeetingJoined,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCParticipantMeetingJoinedOutput{})},
+			},
+			Process:    processVCParticipantMeetingJoined,
+			PreConsume: subscriptionPreConsume(eventTypeMeetingJoined, pathMeetingSubscribe, pathMeetingUnsubscribe),
+			Scopes:     []string{"vc:meeting.meetingevent:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeMeetingJoined},
+		},
 		{
 			Key:         eventTypeMeetingEnded,
 			DisplayName: "Participant meeting ended",

internal/affordance/affordance.go

@@ -0,0 +1,96 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package affordance is the lazily-loaded store of usage guidance for
+// service-API methods. The source of truth is one markdown file per service in
+// the top-level affordance/ tree (see mdparse.go), injected via SetSource so
+// domain owners maintain it next to skills/ and shortcuts/. A service is read
+// and parsed at most once, on first access, so normal command execution never
+// touches it.
+package affordance
+
+import (
+	"encoding/json"
+	"io/fs"
+	"strings"
+	"sync"
+
+	"github.com/larksuite/cli/internal/apicatalog"
+	"github.com/larksuite/cli/internal/registry"
+)
+
+var (
+	mu        sync.Mutex
+	byService = map[string]map[string]json.RawMessage{}
+	tried     = map[string]bool{}
+	mdSource  fs.FS // top-level affordance/*.md tree; nil in the minimal preview build
+)
+
+// SetSource installs the markdown guidance tree (the top-level affordance/
+// directory) as the source. Called once at startup before any lookup; clears
+// the parse cache so re-sourcing (e.g. in tests) takes effect.
+func SetSource(fsys fs.FS) {
+	mu.Lock()
+	defer mu.Unlock()
+	mdSource = fsys
+	byService = map[string]map[string]json.RawMessage{}
+	tried = map[string]bool{}
+}
+
+// For returns the raw affordance overlay for one method, loading the owning
+// service on first access. ok is false when there is no entry (absent source,
+// parse failure, or unknown method all collapse to "no guidance").
+func For(service, methodID string) (json.RawMessage, bool) {
+	mu.Lock()
+	defer mu.Unlock()
+	if !tried[service] {
+		tried[service] = true
+		byService[service] = loadService(service)
+	}
+	raw, ok := byService[service][methodID]
+	return raw, ok && len(raw) > 0
+}
+
+// loadService parses a service's markdown guidance into per-method overlays,
+// marshalling each to JSON so downstream callers keep the same wire shape.
+func loadService(service string) map[string]json.RawMessage {
+	if mdSource == nil {
+		return nil
+	}
+	src, err := fs.ReadFile(mdSource, service+".md")
+	if err != nil {
+		return nil
+	}
+	m := map[string]json.RawMessage{}
+	for id, a := range parseDomainMD(src, commandFormResolver(service)) {
+		if b, err := json.Marshal(a); err == nil {
+			m[id] = b
+		}
+	}
+	return m
+}
+
+// commandFormResolver maps a method's command-form heading ("user_mailbox.messages
+// list") to its method id ("user_mailbox.message.list") via the registry's
+// authoritative resource↔id table. Resource names are irregularly pluralised
+// (message/messages, user_mailbox/user_mailboxes), so this cannot be guessed; the
+// 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
+		}
+		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)
+		if id, ok := byForm[h]; ok {
+			return id
+		}
+		return strings.ReplaceAll(h, " ", ".")
+	}
+}

internal/affordance/affordance_test.go

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package affordance
+
+import (
+	"encoding/json"
+	"testing"
+	"testing/fstest"
+)
+
+// fixtureMD is a minimal affordance source: two methods, each with a lead
+// paragraph (use_when) and a fenced example.
+const fixtureMD = "# approval\n" +
+	"> skill: lark-approval\n\n" +
+	"## instances cc\n" +
+	"把一个审批实例抄送给指定用户。\n\n" +
+	"### Examples\n\n" +
+	"**抄送给用户**\n" +
+	"```bash\n" +
+	"lark-cli approval instances cc --data '{\"instance_code\":\"x\"}'\n" +
+	"```\n\n" +
+	"## instances get\n" +
+	"查询某审批实例详情。\n\n" +
+	"### Examples\n\n" +
+	"**按 code 查询**\n" +
+	"```bash\n" +
+	"lark-cli approval instances get --instance-code \"x\"\n" +
+	"```\n"
+
+func TestFor(t *testing.T) {
+	prev := mdSource
+	t.Cleanup(func() { SetSource(prev) }) // SetSource mutates package state; restore for test isolation
+	SetSource(fstest.MapFS{"approval.md": &fstest.MapFile{Data: []byte(fixtureMD)}})
+
+	// A seeded method in a seeded service resolves to its overlay.
+	raw, ok := For("approval", "instances.cc")
+	if !ok {
+		t.Fatal(`For("approval","instances.cc") ok=false, want an overlay`)
+	}
+	var a struct {
+		UseWhen  []string `json:"use_when"`
+		Examples []struct {
+			Command string `json:"command"`
+		} `json:"examples"`
+	}
+	if err := json.Unmarshal(raw, &a); err != nil {
+		t.Fatalf("overlay is not valid affordance JSON: %v", err)
+	}
+	if len(a.UseWhen) == 0 || len(a.Examples) == 0 || a.Examples[0].Command == "" {
+		t.Errorf("overlay missing use_when/examples: %s", raw)
+	}
+
+	// Misses: unknown method in a known service, and an unknown service, both
+	// resolve to ok=false (no panic, no error) so callers treat them as "no
+	// guidance".
+	if _, ok := For("approval", "instances.no_such_method"); ok {
+		t.Error("unknown method should be ok=false")
+	}
+	if _, ok := For("no_such_service", "x.y"); ok {
+		t.Error("unknown service should be ok=false")
+	}
+
+	// A second lookup of the same service is served from cache (parsed at most
+	// once) and stays consistent.
+	if _, ok := For("approval", "instances.get"); !ok {
+		t.Error("second lookup in a cached service should still resolve")
+	}
+}
+
+// Non-bullet paragraph lines under any section are preserved as items, not
+// dropped (regression: they previously only updated pending, lost without a fence).
+func TestParseDomainMD_ParagraphNotDropped(t *testing.T) {
+	md := "# d\n\n## foo bar\nwhat it does.\n\n### Tips\n- a bullet\nplain paragraph note.\n\n### See also\nrun [[other cmd]] first.\n"
+	got := parseDomainMD([]byte(md), nil) // nil resolver -> space->dot, "foo bar" -> "foo.bar"
+	a, ok := got["foo.bar"]
+	if !ok {
+		t.Fatal("method not parsed")
+	}
+	if len(a.Tips) != 2 || a.Tips[1] != "plain paragraph note." {
+		t.Errorf("Tips paragraph dropped: %v", a.Tips)
+	}
+	if len(a.Extensions) != 1 || len(a.Extensions[0].Items) != 1 || a.Extensions[0].Items[0] != "run `other cmd` first." {
+		t.Errorf("custom-section paragraph not flowed through: %+v", a.Extensions)
+	}
+}

internal/affordance/mdparse.go

@@ -0,0 +1,180 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package affordance
+
+import (
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/internal/meta"
+)
+
+// The affordance source is a narrow, fixed markdown subset (see src/*.md):
+//
+//	# domain            optional `> skill: <name>` applied to every method
+//	## command          e.g. `instances get`
+//	<lead paragraph>    -> use_when (when this command is right)
+//	### Avoid when      -> avoid_when (links become prefer/alternative edges)
+//	### Prerequisites   -> prerequisites   (a "…来自 [[x]]" link is a sequence edge)
+//	### Tips            -> tips
+//	### Examples        -> examples: **description** + a ```fenced``` command
+//	### <other>         -> extensions[] (custom section, flows through verbatim)
+//	[[cmd]]             -> a command reference, rendered as `cmd`
+//
+// Parsing is lazy and cached (see For), so the constrained grammar is read at
+// most once per domain.
+
+var mdLink = regexp.MustCompile(`\[\[(.+?)\]\]`)
+
+// standardSection maps a section heading to its typed Affordance field; any
+// other heading becomes an extension.
+var standardSection = map[string]string{
+	"Avoid when":    "avoid_when",
+	"Prerequisites": "prerequisites",
+	"Tips":          "tips",
+	"Examples":      "examples",
+}
+
+func linkToBacktick(s string) string { return mdLink.ReplaceAllString(s, "`$1`") }
+
+// headingToKey maps a command heading ("instances get") to its affordance key
+// ("instances.get"). The space→dot rule holds where the command form matches
+// the method id; domains whose resource names differ (e.g. plural "messages"
+// vs id segment "message") need the registry's authoritative resource↔id table.
+func headingToKey(h string) string {
+	return strings.ReplaceAll(strings.TrimSpace(h), " ", ".")
+}
+
+type mdSection struct {
+	label string
+	items []string
+	cases []meta.AffordanceCase
+}
+
+// parseDomainMD parses one domain's markdown into per-method Affordance values,
+// keyed by method id. resolve maps a command-form heading ("user_mailbox.messages
+// list") to its method id ("user_mailbox.message.list"); nil falls back to the
+// space→dot rule (valid only where the command form already equals the id).
+func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affordance {
+	if resolve == nil {
+		resolve = headingToKey
+	}
+	out := map[string]meta.Affordance{}
+
+	var skill, curKey string
+	var useWhen, para []string // lead paragraphs -> use_when entries (blank line separates)
+	var secs []*mdSection
+	var sec *mdSection
+	var pending string
+	var fence []string
+	inFence := false
+
+	assemble := func() {
+		if curKey == "" {
+			return
+		}
+		if len(para) > 0 {
+			useWhen = append(useWhen, strings.TrimSpace(strings.Join(para, " ")))
+			para = nil
+		}
+		var a meta.Affordance
+		if len(useWhen) > 0 {
+			a.UseWhen = useWhen
+		}
+		for _, s := range secs {
+			switch standardSection[s.label] {
+			case "avoid_when":
+				a.AvoidWhen = s.items
+			case "prerequisites":
+				a.Prerequisites = s.items
+			case "tips":
+				a.Tips = s.items
+			case "examples":
+				a.Examples = s.cases
+			default:
+				a.Extensions = append(a.Extensions, meta.AffordanceSection{Label: s.label, Items: s.items})
+			}
+		}
+		if skill != "" {
+			a.Skills = []string{skill}
+		}
+		out[curKey] = a
+	}
+
+	reset := func() { useWhen, para, secs, sec, pending, fence, inFence = nil, nil, nil, nil, "", nil, false }
+
+	// flushPending appends a non-bullet paragraph line that was not consumed as
+	// an example description (i.e. no fence followed) to the current section's
+	// items, so prose under any section is preserved rather than dropped.
+	flushPending := func() {
+		if sec != nil && pending != "" {
+			sec.items = append(sec.items, linkToBacktick(pending))
+			pending = ""
+		}
+	}
+
+	for _, raw := range strings.Split(string(src), "\n") {
+		line := strings.TrimRight(raw, "\r")
+		t := strings.TrimSpace(line)
+		switch {
+		case strings.HasPrefix(line, "## "):
+			flushPending()
+			assemble()
+			curKey = resolve(line[3:])
+			reset()
+			continue
+		case strings.HasPrefix(line, "# "):
+			continue
+		case strings.HasPrefix(t, "> skill:"):
+			skill = strings.TrimSpace(t[len("> skill:"):])
+			continue
+		case strings.HasPrefix(line, "### "):
+			flushPending()
+			sec = &mdSection{label: strings.TrimSpace(line[4:])}
+			secs = append(secs, sec)
+			pending, fence, inFence = "", nil, false
+			continue
+		}
+		if curKey == "" {
+			continue
+		}
+		if sec == nil { // lead paragraphs before any section -> use_when (blank line separates entries)
+			if t == "" {
+				if len(para) > 0 {
+					useWhen = append(useWhen, strings.Join(para, " "))
+					para = nil
+				}
+			} else {
+				para = append(para, t)
+			}
+			continue
+		}
+		// inside a section: a fenced block is an example command; otherwise the
+		// shape follows the writing (bullet item vs **description** before a fence).
+		if strings.HasPrefix(t, "```") {
+			if !inFence {
+				inFence, fence = true, nil
+			} else {
+				inFence = false
+				sec.cases = append(sec.cases, meta.AffordanceCase{Description: pending, Command: strings.Join(fence, "\n")})
+				pending = ""
+			}
+			continue
+		}
+		if inFence {
+			fence = append(fence, line)
+			continue
+		}
+		if strings.HasPrefix(t, "-") {
+			flushPending()
+			sec.items = append(sec.items, linkToBacktick(strings.TrimSpace(t[1:])))
+		} else if t != "" {
+			flushPending()
+			pending = strings.Trim(t, "* ")
+		}
+	}
+	flushPending()
+	assemble()
+	return out
+}

internal/cmdutil/iostreams.go

@@ -18,6 +18,9 @@ type IOStreams struct {
 	Out        io.Writer
 	ErrOut     io.Writer
 	IsTerminal bool
+	// OutIsTerminal reports whether Out is an interactive terminal. Mirrors
+	// IsTerminal; computed once in NewIOStreams and assignable directly in tests.
+	OutIsTerminal bool
 	// StderrIsTerminal reports whether ErrOut is an interactive terminal.
 	// Advisory warnings written to stderr (e.g. the proxy notice) gate on this
 	// so they stay out of non-interactive output (pipes, CI, agent runs).
@@ -27,19 +30,24 @@ type IOStreams struct {
 }
 
 // NewIOStreams builds an IOStreams from arbitrary readers/writers.
-// IsTerminal / StderrIsTerminal are derived from in's / errOut's underlying
-// *os.File, if any; non-file streams (bytes.Buffer, strings.Reader, …) yield
-// false.
+// IsTerminal / OutIsTerminal / StderrIsTerminal are each derived from the
+// underlying *os.File of in / out / errOut respectively; non-file
+// readers/writers (bytes.Buffer, strings.Reader, …) yield false.
 func NewIOStreams(in io.Reader, out, errOut io.Writer) *IOStreams {
-	isTerminal := false
-	if f, ok := in.(*os.File); ok {
-		isTerminal = term.IsTerminal(int(f.Fd()))
+	fileIsTerminal := func(v any) bool {
+		if f, ok := v.(*os.File); ok {
+			return term.IsTerminal(int(f.Fd()))
+		}
+		return false
 	}
-	stderrIsTerminal := false
-	if f, ok := errOut.(*os.File); ok {
-		stderrIsTerminal = term.IsTerminal(int(f.Fd()))
+	return &IOStreams{
+		In:               in,
+		Out:              out,
+		ErrOut:           errOut,
+		IsTerminal:       fileIsTerminal(in),
+		OutIsTerminal:    fileIsTerminal(out),
+		StderrIsTerminal: fileIsTerminal(errOut),
 	}
-	return &IOStreams{In: in, Out: out, ErrOut: errOut, IsTerminal: isTerminal, StderrIsTerminal: stderrIsTerminal}
 }
 
 // SystemIO creates an IOStreams wired to the process's standard file descriptors.

internal/cmdutil/iostreams_test.go

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"bytes"
+	"os"
+	"testing"
+)
+
+func TestNewIOStreamsTerminalFlagsNonFile(t *testing.T) {
+	s := NewIOStreams(&bytes.Buffer{}, &bytes.Buffer{}, &bytes.Buffer{})
+	if s.IsTerminal || s.OutIsTerminal || s.StderrIsTerminal {
+		t.Errorf("non-file streams must not be terminals: in=%v out=%v err=%v",
+			s.IsTerminal, s.OutIsTerminal, s.StderrIsTerminal)
+	}
+}
+
+func TestNewIOStreamsTerminalFlagsPipe(t *testing.T) {
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer r.Close()
+	defer w.Close()
+	s := NewIOStreams(r, w, w)
+	if s.OutIsTerminal || s.StderrIsTerminal {
+		t.Errorf("os.Pipe must not be a terminal: out=%v err=%v", s.OutIsTerminal, s.StderrIsTerminal)
+	}
+}

internal/errclass/codemeta_drive.go

@@ -10,8 +10,15 @@ 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{
-	1061044: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},          // parent folder does not exist (upload)
-	1069302: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // comment endpoint "Invalid or missing parameters"
+	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
+	1069302: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // comment endpoint "Invalid or missing parameters"
+	2200:    {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive tenant/internal errors
 }
 
 func init() { mergeCodeMeta(driveCodeMeta, "drive") }

internal/errclass/codemeta_test.go

@@ -102,6 +102,35 @@ func TestLookupCodeMeta_RetryableRateLimit(t *testing.T) {
 	}
 }
 
+func TestLookupCodeMeta_DrivePushCodes(t *testing.T) {
+	cases := []struct {
+		code        int
+		wantCat     errs.Category
+		wantSubtype errs.Subtype
+		wantRetry   bool
+	}{
+		{1061001, errs.CategoryAPI, errs.SubtypeServerError, true},
+		{1061002, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{1061004, errs.CategoryAuthorization, errs.SubtypePermissionDenied, false},
+		{1061007, errs.CategoryAPI, errs.SubtypeNotFound, false},
+		{1061043, errs.CategoryAPI, errs.SubtypeQuotaExceeded, false},
+		{1062009, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{2200, 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_Unknown(t *testing.T) {
 	_, ok := LookupCodeMeta(999999)
 	if ok {

internal/identitydiag/diagnostics.go

@@ -13,6 +13,7 @@ import (
 	"strings"
 	"time"
 
+	extcred "github.com/larksuite/cli/extension/credential"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -61,12 +62,131 @@ func Diagnose(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, veri
 	if ctx == nil {
 		ctx = context.Background()
 	}
+	// An external provider mints tokens on demand and blocks interactive auth,
+	// so the built-in keychain heuristics and "auth login" hints don't apply.
+	if provider := activeExternalProvider(ctx, f); provider != "" {
+		return diagnoseExternal(ctx, f, cfg, provider, verify)
+	}
 	return Result{
 		Bot:  diagnoseBot(ctx, f, cfg, verify),
 		User: diagnoseUser(ctx, f, cfg, verify),
 	}
 }
 
+// activeExternalProvider returns the active extension provider name, or "".
+// An error degrades to the built-in path: an unreachable provider would already
+// have failed the f.Config() that produced cfg.
+func activeExternalProvider(ctx context.Context, f *cmdutil.Factory) string {
+	if f == nil || f.Credential == nil {
+		return ""
+	}
+	name, err := f.Credential.ActiveExtensionProviderName(ctx)
+	if err != nil {
+		return ""
+	}
+	return name
+}
+
+func diagnoseExternal(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, provider string, verify bool) Result {
+	if cfg == nil || cfg.AppID == "" {
+		notConfigured := Identity{
+			Status:  StatusNotConfigured,
+			Message: "not configured (missing app config)",
+			Hint:    externalCredentialHint(provider),
+		}
+		return Result{Bot: notConfigured, User: notConfigured}
+	}
+	// SupportedIdentities == 0 is "unspecified" — treat as both, per CanBot.
+	ids := extcred.IdentitySupport(cfg.SupportedIdentities)
+	supportsBot := cfg.SupportedIdentities == 0 || ids.Has(extcred.SupportsBot)
+	supportsUser := cfg.SupportedIdentities == 0 || ids.Has(extcred.SupportsUser)
+	return Result{
+		Bot:  diagnoseExternalBot(ctx, f, cfg, provider, supportsBot, verify),
+		User: diagnoseExternalUser(ctx, f, cfg, provider, supportsUser, verify),
+	}
+}
+
+func diagnoseExternalBot(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, provider string, supported, verify bool) Identity {
+	if !supported {
+		return notProvidedExternally("Bot", provider)
+	}
+	id := Identity{Status: StatusReady, Available: true, Message: "Bot identity: ready (provided by " + provider + ")"}
+	if !verify {
+		return id
+	}
+	token, err := resolveBotToken(ctx, f, cfg)
+	if err != nil {
+		return externalVerifyFailed(id, "Bot", provider, err)
+	}
+	info, err := fetchBotInfo(ctx, f, cfg, token)
+	if err != nil {
+		return externalVerifyFailed(id, "Bot", provider, err)
+	}
+	id.Verified = boolPtr(true)
+	id.OpenID = info.OpenID
+	id.AppName = info.AppName
+	return id
+}
+
+func diagnoseExternalUser(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, provider string, supported, verify bool) Identity {
+	if !supported {
+		return notProvidedExternally("User", provider)
+	}
+	// enrichUserInfo populates UserOpenId only after the provider returns and
+	// verifies a UAT (and clears it on failure), so a resolved open id is the
+	// external analogue of a keychain token being present.
+	if cfg.UserOpenId == "" {
+		return Identity{
+			Status:  StatusMissing,
+			Message: "User identity: not signed in via credential source " + provider,
+			Hint:    externalCredentialHint(provider),
+		}
+	}
+	id := Identity{
+		Status:      StatusReady,
+		Available:   true,
+		TokenStatus: StatusReady,
+		UserName:    cfg.UserName,
+		OpenID:      cfg.UserOpenId,
+		Message:     "User identity: ready (provided by " + provider + ")",
+	}
+	if !verify {
+		return id
+	}
+	if _, err := f.Credential.ResolveToken(ctx, credential.NewTokenSpec(core.AsUser, cfg.AppID)); err != nil {
+		return externalVerifyFailed(id, "User", provider, err)
+	}
+	id.Verified = boolPtr(true)
+	return id
+}
+
+func notProvidedExternally(label, provider string) Identity {
+	return Identity{
+		Status:  StatusNotConfigured,
+		Message: label + " identity: not provided by credential source " + provider,
+		Hint:    externalCredentialHint(provider),
+	}
+}
+
+// externalVerifyFailed flips id to verify-failed, keeping any identity fields
+// (open id, user name) already resolved before the probe.
+func externalVerifyFailed(id Identity, label, provider string, err error) Identity {
+	id.Available = false
+	id.Verified = boolPtr(false)
+	id.Status = StatusVerifyFailed
+	id.TokenStatus = ""
+	id.Message = label + " identity: verify failed: " + err.Error()
+	id.Hint = externalCredentialHint(provider)
+	return id
+}
+
+// externalCredentialHint reports the constraint, not a remediation: the
+// identity is the provider's to manage, not lark-cli's to fix. What to do about
+// it is the caller's call — there may be no user to ask.
+func externalCredentialHint(provider string) string {
+	return fmt.Sprintf("managed by the external credential provider %q and cannot be configured via lark-cli", provider)
+}
+
 func diagnoseBot(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, verify bool) Identity {
 	if cfg == nil || cfg.AppID == "" {
 		return Identity{

internal/identitydiag/diagnostics_test.go

@@ -10,9 +10,11 @@ import (
 	"testing"
 	"time"
 
+	extcred "github.com/larksuite/cli/extension/credential"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/zalando/go-keyring"
 )
@@ -348,3 +350,136 @@ func TestDiagnose_UserIdentityNeedsRefresh(t *testing.T) {
 		t.Fatalf("token status = %q, want needs_refresh", got.User.TokenStatus)
 	}
 }
+
+// fakeExtProvider is a minimal credential.extcred.Provider for exercising the
+// external-credential diagnosis path. account makes the provider "active";
+// token (when set) satisfies ResolveToken during verify.
+type fakeExtProvider struct {
+	name    string
+	account *extcred.Account
+	token   *extcred.Token
+}
+
+func (p *fakeExtProvider) Name() string { return p.name }
+func (p *fakeExtProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
+	return p.account, nil
+}
+func (p *fakeExtProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
+	return p.token, nil
+}
+
+func externalFactory(prov *fakeExtProvider, cfg *core.CliConfig) *cmdutil.Factory {
+	cred := credential.NewCredentialProvider(
+		[]extcred.Provider{prov}, nil, nil,
+		func() (*http.Client, error) { return nil, nil },
+	)
+	return &cmdutil.Factory{
+		Config:     func() (*core.CliConfig, error) { return cfg, nil },
+		Credential: cred,
+		IOStreams:  &cmdutil.IOStreams{},
+	}
+}
+
+// assertExternalHint locks the contract that an external-provider hint never
+// points at interactive commands blocked under an external provider.
+func assertExternalHint(t *testing.T, hint string) {
+	t.Helper()
+	if hint == "" {
+		t.Fatalf("hint empty, want external guidance")
+	}
+	for _, blocked := range []string{"auth login", "config --help"} {
+		if strings.Contains(hint, blocked) {
+			t.Fatalf("hint %q must not point at %q (blocked under external provider)", hint, blocked)
+		}
+	}
+	if !strings.Contains(hint, "external") {
+		t.Fatalf("hint %q should explain credentials are external", hint)
+	}
+}
+
+func TestDiagnose_External_UserReady(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsAll), UserOpenId: "ou_x", UserName: "Alice"}
+	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, false)
+	// The bug this guards: the built-in path read the keychain (empty under an
+	// external provider) and reported the user as missing. Now availability
+	// follows the resolved account, so a signed-in user reads as ready.
+	if !got.User.Available || got.User.Status != StatusReady || got.User.TokenStatus != StatusReady {
+		t.Fatalf("user = %#v, want ready/available", got.User)
+	}
+	if got.User.OpenID != "ou_x" || got.User.UserName != "Alice" {
+		t.Fatalf("user identity = %#v", got.User)
+	}
+	if got.User.Hint != "" {
+		t.Fatalf("hint = %q, want empty when available", got.User.Hint)
+	}
+	if !got.Bot.Available || got.Bot.Status != StatusReady {
+		t.Fatalf("bot = %#v, want ready/available", got.Bot)
+	}
+}
+
+func TestDiagnose_External_UserNotSignedIn(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsAll)}
+	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, false)
+	if got.User.Available || got.User.Status != StatusMissing {
+		t.Fatalf("user = %#v, want missing/unavailable", got.User)
+	}
+	assertExternalHint(t, got.User.Hint)
+}
+
+func TestDiagnose_External_BotOnly(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsBot), UserOpenId: "ou_x"}
+	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, false)
+	if !got.Bot.Available || got.Bot.Status != StatusReady {
+		t.Fatalf("bot = %#v, want ready/available", got.Bot)
+	}
+	// Provider declares bot-only: user is unavailable even though an open id is
+	// present, and the hint is external (not "auth login").
+	if got.User.Available || got.User.Status != StatusNotConfigured {
+		t.Fatalf("user = %#v, want not_configured/unavailable", got.User)
+	}
+	assertExternalHint(t, got.User.Hint)
+}
+
+func TestDiagnose_External_UserOnly(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandLark, SupportedIdentities: uint8(extcred.SupportsUser), UserOpenId: "ou_x", UserName: "Bob"}
+	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, false)
+	if !got.User.Available || got.User.Status != StatusReady {
+		t.Fatalf("user = %#v, want ready/available", got.User)
+	}
+	if got.Bot.Available || got.Bot.Status != StatusNotConfigured {
+		t.Fatalf("bot = %#v, want not_configured/unavailable", got.Bot)
+	}
+	assertExternalHint(t, got.Bot.Hint)
+}
+
+func TestDiagnose_External_VerifyUserResolvesToken(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsUser), UserOpenId: "ou_x", UserName: "Alice"}
+	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}, token: &extcred.Token{Value: "ext-uat"}}, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, true)
+	if !got.User.Available || got.User.Verified == nil || !*got.User.Verified {
+		t.Fatalf("user = %#v, want available and verified", got.User)
+	}
+}
+
+func TestDiagnose_External_VerifyUserTokenUnavailable(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsUser), UserOpenId: "ou_x"}
+	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, true)
+	if got.User.Available || got.User.Status != StatusVerifyFailed {
+		t.Fatalf("user = %#v, want verify_failed/unavailable", got.User)
+	}
+	if got.User.Verified == nil || *got.User.Verified {
+		t.Fatalf("verified = %v, want false", got.User.Verified)
+	}
+	assertExternalHint(t, got.User.Hint)
+}

internal/meta/affordance.go

@@ -5,30 +5,39 @@ package meta
 
 import "encoding/json"
 
-// Affordance is the hand-authored usage guidance overlaid on a method: when to
-// use it, when not to, prerequisites, few-shot examples, and related methods.
-// It is the single typed model of the affordance shape; the envelope renderer
-// and the command help both parse through ParsedAffordance so the vocabulary
-// is defined once. The JSON tags double as the envelope's wire shape.
+// Affordance is the typed usage guidance overlaid on a method. It is the single
+// model the envelope renderer and the command help both parse, so the
+// vocabulary is defined once; the JSON tags double as the envelope wire shape.
+// Skills entries are skill names (or name/path) rendered as runnable
+// `lark-cli skills read <entry>` pointers.
 type Affordance struct {
-	UseWhen       []string         `json:"use_when,omitempty"`
-	DoNotUseWhen  []string         `json:"do_not_use_when,omitempty"`
-	Prerequisites []string         `json:"prerequisites,omitempty"`
-	Examples      []AffordanceCase `json:"examples,omitempty"`
-	Related       []string         `json:"related,omitempty"`
+	UseWhen       []string            `json:"use_when,omitempty"`
+	AvoidWhen     []string            `json:"avoid_when,omitempty"`
+	Prerequisites []string            `json:"prerequisites,omitempty"`
+	Tips          []string            `json:"tips,omitempty"`
+	Examples      []AffordanceCase    `json:"examples,omitempty"`
+	Extensions    []AffordanceSection `json:"extensions,omitempty"`
+	Related       []string            `json:"related,omitempty"`
+	Skills        []string            `json:"skills,omitempty"`
 }
 
-// AffordanceCase is one few-shot example: a one-line description and a
-// ready-to-run command.
+// AffordanceCase is one few-shot example: a description and a ready-to-run command.
 type AffordanceCase struct {
-	Description string `json:"description"`
+	Description string `json:"description,omitempty"`
 	Command     string `json:"command"`
 }
 
-// ParsedAffordance decodes the method's raw affordance overlay into the typed
-// Affordance. ok is false when the method carries no affordance, the JSON is
-// malformed, or every section is empty — so callers can treat "no guidance"
-// uniformly.
+// AffordanceSection is a custom guidance section: any heading beyond the
+// standard four (Avoid when / Prerequisites / Tips / Examples) flows through
+// here with its label preserved, so authors can add sections without code
+// changes.
+type AffordanceSection struct {
+	Label string   `json:"label"`
+	Items []string `json:"items,omitempty"`
+}
+
+// ParsedAffordance decodes the method's overlay. ok is false when it is absent,
+// malformed, or wholly empty — callers treat all three as "no guidance".
 func (m Method) ParsedAffordance() (Affordance, bool) {
 	if len(m.Affordance) == 0 {
 		return Affordance{}, false
@@ -37,7 +46,7 @@ func (m Method) ParsedAffordance() (Affordance, bool) {
 	if json.Unmarshal(m.Affordance, &a) != nil {
 		return Affordance{}, false
 	}
-	if len(a.UseWhen) == 0 && len(a.DoNotUseWhen) == 0 && len(a.Prerequisites) == 0 && len(a.Examples) == 0 && len(a.Related) == 0 {
+	if len(a.UseWhen) == 0 && len(a.AvoidWhen) == 0 && len(a.Prerequisites) == 0 && len(a.Tips) == 0 && len(a.Examples) == 0 && len(a.Extensions) == 0 && len(a.Related) == 0 && len(a.Skills) == 0 {
 		return Affordance{}, false
 	}
 	return a, true

internal/meta/affordance_test.go

@@ -19,7 +19,7 @@ func TestMethod_ParsedAffordance(t *testing.T) {
 	notOK := map[string]string{
 		"empty payload":        ``,
 		"empty object":         `{}`,
-		"all empty arrays":     `{"use_when":[],"do_not_use_when":[],"prerequisites":[],"examples":[],"related":[]}`,
+		"all empty arrays":     `{"use_when":[],"avoid_when":[],"prerequisites":[],"tips":[],"examples":[],"related":[]}`,
 		"malformed string":     `"not an object"`,
 		"malformed number":     `42`,
 		"nested type mismatch": `{"examples":"should be a list"}`,
@@ -35,8 +35,9 @@ func TestMethod_ParsedAffordance(t *testing.T) {
 	// Populated affordance parses with all fields.
 	raw := `{
 		"use_when": ["需要拿到当前用户的主日历 ID"],
-		"do_not_use_when": ["已知具体 calendar_id"],
+		"avoid_when": ["已知具体 calendar_id"],
 		"prerequisites": ["user 身份登录"],
+		"tips": ["主日历的 calendar_id 即当前用户的 union_id"],
 		"examples": [{"description":"获取主日历","command":"lark-cli calendar calendars primary"}],
 		"related": ["calendars.list"]
 	}`
@@ -47,10 +48,22 @@ func TestMethod_ParsedAffordance(t *testing.T) {
 	if len(a.UseWhen) != 1 || a.UseWhen[0] != "需要拿到当前用户的主日历 ID" {
 		t.Errorf("UseWhen = %v", a.UseWhen)
 	}
+	if len(a.Tips) != 1 || a.Tips[0] != "主日历的 calendar_id 即当前用户的 union_id" {
+		t.Errorf("Tips = %v", a.Tips)
+	}
 	if len(a.Examples) != 1 || a.Examples[0].Description != "获取主日历" || a.Examples[0].Command != "lark-cli calendar calendars primary" {
 		t.Errorf("Examples = %+v", a.Examples)
 	}
 	if len(a.Related) != 1 || a.Related[0] != "calendars.list" {
 		t.Errorf("Related = %v", a.Related)
 	}
+
+	// A method whose only guidance is Tips still parses as populated.
+	tipsOnly, ok := (Method{Affordance: json.RawMessage(`{"tips":["先调用 list 拿到 id"]}`)}).ParsedAffordance()
+	if !ok {
+		t.Fatal("ParsedAffordance with only tips ok=false, want populated")
+	}
+	if len(tipsOnly.Tips) != 1 || tipsOnly.Tips[0] != "先调用 list 拿到 id" {
+		t.Errorf("Tips = %v", tipsOnly.Tips)
+	}
 }

internal/qualitygate/publiccontent/rules.go

@@ -52,6 +52,9 @@ func isPlaceholderValue(value string) bool {
 	normalized := strings.ToLower(trimmed)
 	if normalized == "" ||
 		normalized == "=" ||
+		printfPlaceholderValue(normalized) ||
+		htmlEntityAnglePlaceholder(normalized) ||
+		starMaskedPlaceholder(normalized) ||
 		percentWrappedPlaceholder(normalized) ||
 		angleWrappedPlaceholder(normalized) ||
 		urlWithAnglePlaceholder(normalized) ||
@@ -61,12 +64,42 @@ func isPlaceholderValue(value string) bool {
 	return namedPlaceholderValue(normalized)
 }
 
+func htmlEntityAnglePlaceholder(value string) bool {
+	if !strings.HasPrefix(value, "<") || !strings.HasSuffix(value, ">") {
+		return false
+	}
+	return anglePlaceholderIdentifier(strings.TrimSuffix(strings.TrimPrefix(value, "<"), ">"))
+}
+
+func starMaskedPlaceholder(value string) bool {
+	var stars int
+	for _, r := range value {
+		if r == '*' {
+			stars++
+			continue
+		}
+		return false
+	}
+	return stars >= 3
+}
+
 func namedPlaceholderValue(value string) bool {
 	switch value {
-	case "...", "placeholder", "redacted", "<redacted>", "xxxx", "test-secret":
+	case "...", "***", "****", "placeholder", "redacted", "<redacted>", "xxxx", "test-secret", "test-token", "dry-run", "dry_run":
 		return true
 	}
-	return strings.Contains(value, "cli_example") || allXPlaceholder(value)
+	return strings.Contains(value, "cli_example") ||
+		allXPlaceholder(value) ||
+		conventionalNamedPlaceholderValue(value)
+}
+
+func printfPlaceholderValue(value string) bool {
+	switch value {
+	case "%d", "%s", "%q", "%v", "%w", "%x", "%T":
+		return true
+	default:
+		return false
+	}
 }
 
 func allXPlaceholder(value string) bool {
@@ -81,6 +114,41 @@ func allXPlaceholder(value string) bool {
 	return true
 }
 
+func conventionalNamedPlaceholderValue(value string) bool {
+	if !delimitedPlaceholderIdentifier(value) {
+		return false
+	}
+	normalized := strings.ReplaceAll(value, "-", "_")
+	if rest, ok := strings.CutPrefix(normalized, "your_"); ok {
+		return conventionalCredentialPlaceholderName(rest)
+	}
+	if rest, ok := strings.CutSuffix(normalized, "_here"); ok {
+		return conventionalCredentialPlaceholderName(rest)
+	}
+	return false
+}
+
+func conventionalCredentialPlaceholderName(value string) bool {
+	switch value {
+	case "api_key",
+		"access_key",
+		"private_key",
+		"secret",
+		"password",
+		"passwd",
+		"token",
+		"webhook",
+		"access_token",
+		"refresh_token",
+		"bearer_token",
+		"session_token",
+		"client_secret":
+		return true
+	default:
+		return false
+	}
+}
+
 func urlWithAnglePlaceholder(value string) bool {
 	if !strings.Contains(value, "://") ||
 		!strings.Contains(value, "<") ||

internal/qualitygate/publiccontent/scan.go

@@ -4,6 +4,8 @@
 package publiccontent
 
 import (
+	"encoding/base64"
+	"encoding/json"
 	"fmt"
 	"path/filepath"
 	"sort"
@@ -52,8 +54,9 @@ func scanText(file, source, text string, detectorFile bool) []Finding {
 			keyName, _ := normalizedCredentialAssignmentKey(match[0])
 			if value == "" ||
 				isNonSecretLiteralValue(value) ||
-				isBenignCodeCredentialExpression(file, value) ||
+				isBenignCodeCredentialExpression(file, line, match[0], value) ||
 				isPlaceholderValue(value) ||
+				isPermissionScopeIdentifierAssignment(keyName, value) ||
 				isResourceTokenPlaceholderAssignment(keyName, value) {
 				continue
 			}
@@ -63,12 +66,15 @@ func scanText(file, source, text string, detectorFile bool) []Finding {
 			out = append(out, newFinding("public_content_generic_credential", file, lineNo, source, redactAssignment(match[0])))
 		}
 		for _, match := range jwtLikeRE.FindAllString(line, -1) {
-			if isSchemaDottedIdentifier(line, match) {
+			if !isJWTToken(match) {
 				continue
 			}
 			out = append(out, newFinding("public_content_jwt_like_token", file, lineNo, source, redactToken(match)))
 		}
-		for range bearerHeaderRE.FindAllString(line, -1) {
+		for _, match := range bearerHeaderRE.FindAllString(line, -1) {
+			if isPlaceholderBearerHeader(match) {
+				continue
+			}
 			out = append(out, newFinding("public_content_bearer_header", file, lineNo, source, "Authorization: Bearer <redacted>"))
 		}
 		for _, match := range credentialURLRE.FindAllString(line, -1) {
@@ -261,7 +267,7 @@ func isResourceTokenPlaceholderAssignment(key, value string) bool {
 	case key == "retry_without_token" && numericStringPlaceholderValue(value):
 		return true
 	case tokenLikePlaceholderKey(key):
-		return tokenLikePlaceholderValue(value)
+		return tokenLikePlaceholderValue(key, value)
 	default:
 		return false
 	}
@@ -273,12 +279,13 @@ func tokenLikePlaceholderKey(key string) bool {
 		strings.HasSuffix(key, "-token")
 }
 
-func tokenLikePlaceholderValue(value string) bool {
+func tokenLikePlaceholderValue(key, value string) bool {
 	normalized := strings.ToLower(strings.Trim(value, `"'`))
 	if normalized == "" || credentialShapedIdentifier(normalized) {
 		return false
 	}
 	return resourceTokenPlaceholderValue(value) ||
+		maskedTokenFixturePlaceholderValue(key, normalized) ||
 		isPlaceholderValue(value) ||
 		normalized == "token" ||
 		strings.Contains(normalized, "...") ||
@@ -288,6 +295,51 @@ func tokenLikePlaceholderValue(value string) bool {
 		strings.HasPrefix(normalized, ".")
 }
 
+func maskedTokenFixturePlaceholderValue(key, value string) bool {
+	if authCredentialTokenKey(key) {
+		return false
+	}
+	var stars, alnum int
+	for _, r := range value {
+		switch {
+		case r == '*':
+			stars++
+		case (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9'):
+			alnum++
+		default:
+			return false
+		}
+	}
+	return stars >= 6 && alnum > 0
+}
+
+func authCredentialTokenKey(key string) bool {
+	switch strings.ReplaceAll(strings.ToLower(key), "-", "_") {
+	case "access_token",
+		"refresh_token",
+		"session_token",
+		"bearer_token",
+		"auth_token",
+		"authorization_token",
+		"id_token":
+		return true
+	default:
+		return false
+	}
+}
+
+func isPermissionScopeIdentifierAssignment(key, value string) bool {
+	if !strings.HasSuffix(key, "_token") {
+		return false
+	}
+	switch strings.ToLower(strings.Trim(value, `"',;`)) {
+	case "read", "write", "modify", "readonly", "get_as_user":
+		return true
+	default:
+		return false
+	}
+}
+
 func idempotencyTokenPlaceholderValue(value string) bool {
 	return numericStringPlaceholderValue(value) || uuidStringPlaceholderValue(value)
 }
@@ -328,20 +380,87 @@ func numericStringPlaceholderValue(value string) bool {
 	return true
 }
 
-func isBenignCodeCredentialExpression(file, value string) bool {
+func isBenignCodeCredentialExpression(file, line, match, value string) bool {
 	normalized := strings.TrimSpace(value)
 	if strings.HasPrefix(normalized, "regexp.MustCompile(") {
 		return true
 	}
-	if !sourceCodeFile(file) || quotedLiteral(value) || credentialShapedValue(value) {
+	if !sourceCodeFile(file) || credentialShapedValue(value) {
 		return false
 	}
+	if rhs, ok := sourceCodeTypedCredentialRHS(line, match); ok {
+		return isBenignTypedCredentialRHS(rhs)
+	}
+	rawValueQuoted := credentialAssignmentRawValueQuoted(match)
+	if sourceCodeLiteralLooksNonSecret(normalized, !rawValueQuoted) {
+		return true
+	}
+	if sourceCodeFormatStringLiteral(normalized) && sourceCodeFormatArgumentContext(line, match) {
+		return true
+	}
+	if strings.Contains(match, "+") {
+		return true
+	}
+	if rawValueQuoted {
+		return false
+	}
+	if quotedLiteral(value) {
+		return sourceCodeLiteralLooksNonSecret(value, false)
+	}
 	return codeReferenceExpression(normalized)
 }
 
+func sourceCodeTypedCredentialRHS(line, match string) (string, bool) {
+	idx := strings.Index(line, match)
+	if idx < 0 {
+		return "", false
+	}
+	key, ok := credentialAssignmentKey(match)
+	if !ok {
+		return "", false
+	}
+	rest := strings.TrimSpace(line[idx+len(key):])
+	if !strings.HasPrefix(rest, ":") {
+		return "", false
+	}
+	typeAndRHS := strings.TrimSpace(strings.TrimPrefix(rest, ":"))
+	assignmentIdx := strings.Index(typeAndRHS, "=")
+	if assignmentIdx < 0 {
+		return "", false
+	}
+	return strings.TrimSpace(typeAndRHS[assignmentIdx+1:]), true
+}
+
+func isBenignTypedCredentialRHS(value string) bool {
+	value = strings.TrimRight(strings.TrimSpace(value), ",;")
+	if value == "" || isNonSecretLiteralValue(value) || isPlaceholderValue(value) {
+		return true
+	}
+	if credentialShapedValue(value) {
+		return false
+	}
+	if sourceCodeLiteralLooksNonSecret(value, !quotedLiteral(value)) {
+		return true
+	}
+	if quotedLiteral(value) {
+		return false
+	}
+	return codeReferenceExpression(value)
+}
+
+func credentialAssignmentRawValueQuoted(match string) bool {
+	key, ok := credentialAssignmentKey(match)
+	if !ok {
+		return false
+	}
+	rest := strings.TrimSpace(strings.TrimPrefix(match[len(key):], ":"))
+	rest = strings.TrimSpace(strings.TrimPrefix(rest, "="))
+	return strings.HasPrefix(rest, `"`) || strings.HasPrefix(rest, `'`)
+}
+
 func sourceCodeFile(file string) bool {
 	switch filepath.Ext(file) {
-	case ".go", ".py":
+	case ".go", ".js", ".jsx", ".py", ".ts", ".tsx":
 		return true
 	default:
 		return false
@@ -355,7 +474,147 @@ func quotedLiteral(value string) bool {
 			(strings.HasPrefix(normalized, `'`) && strings.HasSuffix(normalized, `'`)))
 }
 
+func sourceCodeLiteralLooksNonSecret(value string, allowNumeric bool) bool {
+	literal := strings.Trim(strings.TrimSpace(value), `"'`)
+	if strings.HasPrefix(literal, "/") {
+		return true
+	}
+	return (allowNumeric && numericStringPlaceholderValue(literal)) ||
+		sourceCodeEnvVarNameLiteral(literal) ||
+		sourceCodeAttributeNameLiteral(literal) ||
+		sourceCodeFakeOrPlaceholderLiteral(literal) ||
+		sourceCodeCredentialTermLiteral(literal) ||
+		sourceCodeCredentialPrefixLiteral(literal) ||
+		sourceCodeVocabularyLiteral(literal) ||
+		sourceCodeSchemaTypeLiteral(literal) ||
+		benignCredentialStatusLiteral(literal)
+}
+
+func sourceCodeFormatArgumentContext(line, match string) bool {
+	idx := strings.Index(line, match)
+	if idx < 0 {
+		return false
+	}
+	prefix := line[:idx]
+	if semicolon := strings.LastIndex(prefix, ";"); semicolon >= 0 {
+		prefix = prefix[semicolon+1:]
+	}
+	return strings.Contains(prefix, "fmt.") ||
+		strings.Contains(prefix, "log.") ||
+		strings.Contains(prefix, "printf(") ||
+		strings.Contains(prefix, "Printf(") ||
+		strings.Contains(prefix, "Errorf(") ||
+		strings.Contains(prefix, "Fprintf(")
+}
+
+func sourceCodeFormatStringLiteral(value string) bool {
+	for i := 0; i < len(value)-1; i++ {
+		if value[i] != '%' {
+			continue
+		}
+		if value[i+1] == '%' {
+			i++
+			continue
+		}
+		j := i + 1
+		for j < len(value) && strings.ContainsRune("#+- 0.0123456789", rune(value[j])) {
+			j++
+		}
+		if j < len(value) && strings.ContainsRune("vTtbcdoOqxXUeEfFgGspw", rune(value[j])) {
+			return true
+		}
+	}
+	return false
+}
+
+func sourceCodeEnvVarNameLiteral(value string) bool {
+	if value == "" || !strings.Contains(value, "_") {
+		return false
+	}
+	var hasCredentialMarker bool
+	for _, r := range value {
+		switch {
+		case r >= 'A' && r <= 'Z':
+		case r >= '0' && r <= '9':
+		case r == '_':
+		default:
+			return false
+		}
+	}
+	for _, marker := range []string{"TOKEN", "SECRET", "KEY", "PASSWORD", "PASSWD"} {
+		if strings.Contains(value, marker) {
+			hasCredentialMarker = true
+			break
+		}
+	}
+	return hasCredentialMarker
+}
+
+func sourceCodeAttributeNameLiteral(value string) bool {
+	normalized := strings.ToLower(value)
+	return strings.HasPrefix(normalized, "data-") && delimitedPlaceholderIdentifier(normalized)
+}
+
+func sourceCodeFakeOrPlaceholderLiteral(value string) bool {
+	normalized := strings.ToLower(value)
+	return strings.HasPrefix(normalized, "fake_") ||
+		strings.HasPrefix(normalized, "fake-") ||
+		strings.Contains(normalized, "placeholder") ||
+		(strings.Contains(normalized, "<") && strings.Contains(normalized, ">"))
+}
+
+func sourceCodeCredentialTermLiteral(value string) bool {
+	normalized := strings.ToLower(strings.ReplaceAll(value, "-", "_"))
+	return conventionalCredentialPlaceholderName(normalized)
+}
+
+func sourceCodeCredentialPrefixLiteral(value string) bool {
+	switch strings.ToLower(value) {
+	case "appsecret:":
+		return true
+	default:
+		return false
+	}
+}
+
+func sourceCodeVocabularyLiteral(value string) bool {
+	switch strings.ToLower(value) {
+	case "bot", "tenant", "user":
+		return true
+	default:
+		return false
+	}
+}
+
+func sourceCodeSchemaTypeLiteral(value string) bool {
+	normalized := strings.ToLower(value)
+	return normalized == "string" || strings.HasPrefix(normalized, "string(")
+}
+
+func benignCredentialStatusLiteral(value string) bool {
+	normalized := strings.ToLower(strings.ReplaceAll(value, "-", "_"))
+	if !delimitedPlaceholderIdentifier(normalized) {
+		return false
+	}
+	for _, marker := range []string{
+		"bad_fmt",
+		"expired",
+		"format",
+		"invalid",
+		"missing",
+		"permission",
+		"status",
+		"type",
+	} {
+		if strings.Contains(normalized, marker) {
+			return true
+		}
+	}
+	return false
+}
+
 func codeReferenceExpression(value string) bool {
+	value = strings.TrimRight(strings.TrimSpace(value), ";")
 	if value == "" {
 		return false
 	}
@@ -364,7 +623,10 @@ func codeReferenceExpression(value string) bool {
 			return true
 		}
 	}
-	return codeIdentifier(value) && !credentialNameFragment(value)
+	if !codeIdentifier(value) {
+		return false
+	}
+	return codeIdentifier(value)
 }
 
 func codeIdentifier(value string) bool {
@@ -381,20 +643,6 @@ func codeIdentifier(value string) bool {
 	return true
 }
 
-func credentialNameFragment(value string) bool {
-	normalized := strings.ToLower(value)
-	for _, marker := range []string{"secret", "token", "password", "passwd", "key"} {
-		if strings.Contains(normalized, marker) {
-			return true
-		}
-	}
-	return false
-}
-
-func isSchemaDottedIdentifier(line, match string) bool {
-	return strings.Contains(line, "schema ") && strings.Contains(match, "_")
-}
-
 func isNonSecretLiteralValue(value string) bool {
 	switch strings.ToLower(strings.TrimSpace(strings.Trim(value, `"'`))) {
 	case "true", "false", "null", "nil", "{", "[":
@@ -404,6 +652,40 @@ func isNonSecretLiteralValue(value string) bool {
 	}
 }
 
+func isJWTToken(value string) bool {
+	parts := strings.Split(value, ".")
+	if len(parts) != 3 {
+		return false
+	}
+	header, err := decodeBase64URLSegment(parts[0])
+	if err != nil || !json.Valid(header) {
+		return false
+	}
+	var fields map[string]interface{}
+	if err := json.Unmarshal(header, &fields); err != nil {
+		return false
+	}
+	alg, ok := fields["alg"].(string)
+	return ok && alg != ""
+}
+
+func decodeBase64URLSegment(value string) ([]byte, error) {
+	if decoded, err := base64.RawURLEncoding.DecodeString(value); err == nil {
+		return decoded, nil
+	}
+	return base64.URLEncoding.DecodeString(value)
+}
+
+func isPlaceholderBearerHeader(match string) bool {
+	normalized := strings.ToLower(match)
+	idx := strings.LastIndex(normalized, "bearer ")
+	if idx < 0 {
+		return false
+	}
+	value := strings.TrimSpace(match[idx+len("bearer "):])
+	return isPlaceholderValue(value)
+}
+
 func isWebhookCredentialKey(key string) bool {
 	return strings.Contains(strings.ReplaceAll(key, "_", ""), "webhook")
 }
@@ -741,7 +1023,12 @@ func sanitizeSemanticExcerpt(text string) string {
 	text = strings.ReplaceAll(text, `<redacted>"`, `<redacted>`)
 	text = strings.ReplaceAll(text, `<redacted>'`, `<redacted>`)
 	text = semanticBearerHeaderRE.ReplaceAllString(text, "Authorization: Bearer <redacted>")
-	text = jwtLikeRE.ReplaceAllString(text, "<jwt-like-token>")
+	text = jwtLikeRE.ReplaceAllStringFunc(text, func(match string) string {
+		if isJWTToken(match) {
+			return "<jwt-like-token>"
+		}
+		return match
+	})
 	text = credentialURLRE.ReplaceAllStringFunc(text, sanitizeCredentialURL)
 	return strings.Join(strings.Fields(text), " ")
 }

internal/qualitygate/publiccontent/scan_test.go

@@ -211,7 +211,7 @@ func TestSemanticCandidateCoversRealE2ESemanticCases(t *testing.T) {
 }
 
 func TestScanFileDetectsDetectorFingerprintOnlyInPublicRuleFiles(t *testing.T) {
-	got := ScanFile(".gitleaks.toml", []byte("[[rules]]\nid = \"public"+"-content-leakage\"\n"))
+	got := ScanFile("testdata/publiccontent/.gitleaks.toml", []byte("[[rules]]\nid = \"public"+"-content-leakage\"\n"))
 	if !findingRules(got)["public_content_detector_fingerprint"] {
 		t.Fatalf("expected detector fingerprint finding, got %#v", got)
 	}
@@ -549,7 +549,7 @@ func TestScanFileDetectsCredentialURLWithEmptyUsername(t *testing.T) {
 }
 
 func TestScanFileAllowsPrivateKeyStateBooleans(t *testing.T) {
-	got := ScanFile("internal/qualitygate/publiccontent/collect.go", []byte(strings.Join([]string{
+	got := ScanFile("fixtures/scanner_state.go", []byte(strings.Join([]string{
 		"inPrivateKey = true",
 		"inPrivateKey = false",
 		"hasPrivateKey: false",
@@ -725,7 +725,7 @@ func TestScanFileAllowsBenignJSONTokenFields(t *testing.T) {
 }
 
 func TestScanFileAllowsTestFixtureSecretValues(t *testing.T) {
-	got := ScanFile("shortcuts/calendar/calendar_meeting_test.go", []byte(`AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,`+"\n"))
+	got := ScanFile("fixtures/calendar_meeting_test.go", []byte(`AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,`+"\n"))
 	for _, item := range got {
 		if item.Rule == "public_content_generic_credential" {
 			t.Fatalf("test fixture secret should not be credential finding: %#v", got)
@@ -734,7 +734,7 @@ func TestScanFileAllowsTestFixtureSecretValues(t *testing.T) {
 }
 
 func TestScanFileAllowsRegexpTokenValidators(t *testing.T) {
-	got := ScanFile("shortcuts/minutes/minutes_detail.go", []byte("var validMinuteTokenDetail = regexp.MustCompile(`^[a-z0-9]+$`)\n"))
+	got := ScanFile("fixtures/minutes_detail.go", []byte("var validMinuteTokenDetail = regexp.MustCompile(`^[a-z0-9]+$`)\n"))
 	for _, item := range got {
 		if item.Rule == "public_content_generic_credential" {
 			t.Fatalf("regexp token validator should not be credential finding: %#v", got)
@@ -743,7 +743,7 @@ func TestScanFileAllowsRegexpTokenValidators(t *testing.T) {
 }
 
 func TestScanFileAllowsBenignSourceCodeCredentialExpressions(t *testing.T) {
-	got := ScanFile("cmd/config/binder.go", []byte(strings.Join([]string{
+	got := ScanFile("fixtures/config_binder.go", []byte(strings.Join([]string{
 		"AppSecret: stored,",
 		"AccessToken: result.Token.AccessToken,",
 		`token := runtime.Str("token")`,
@@ -756,7 +756,7 @@ func TestScanFileAllowsBenignSourceCodeCredentialExpressions(t *testing.T) {
 }
 
 func TestScanFileAllowsPythonArgumentTokens(t *testing.T) {
-	got := ScanFile("skills/lark-slides/scripts/iconpark_tool.py", []byte(strings.Join([]string{
+	got := ScanFile("fixtures/iconpark_tool.py", []byte(strings.Join([]string{
 		"def normalize_token(value: str) -> str:",
 		"    token = rest[index]",
 		"    next_token = rest[index + 1] if index + 1 < len(rest) else None",
@@ -770,8 +770,174 @@ func TestScanFileAllowsPythonArgumentTokens(t *testing.T) {
 	}
 }
 
+func TestScanFileAllowsPythonCredentialTypeAnnotations(t *testing.T) {
+	got := ScanFile("fixtures/doc_word_stat.py", []byte(strings.Join([]string{
+		"class Counter:",
+		"    def __init__(self) -> None:",
+		"        self._token_kind: TokenKind | None = None",
+		"        self.access_token: AccessToken | None = None",
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			t.Fatalf("python credential-shaped type annotations should not be credential findings: %#v", got)
+		}
+	}
+}
+
+func TestScanFileAllowsSourceCodeCredentialNonSecretLiterals(t *testing.T) {
+	got := ScanFile("fixtures/auth_paths.go", []byte(strings.Join([]string{
+		`const PathOAuthTokenV2 = "/open-apis/authen/v2/oauth/token"`,
+		`return fmt.Errorf("failed to remove token: %v", err)`,
+		`const LarkErrTokenMissing = "token_missing"`,
+		`const LarkErrTokenExpired = 99991677`,
+		`const CliAppSecret = "LARKSUITE_CLI_APP_SECRET"`,
+		`const LargeAttachmentTokenAttr = "data-mail-token"`,
+		`const fakeOfficeTokenPrefix = "fake_office_"`,
+		`fmt.Fprintf(w, "  - token=%s  filename=%s\n", att.Token, att.FileName)`,
+		`tokenTypeHint := "access_token"`,
+		`const TokenTenant Token = "tenant"`,
+		`const secretKeyPrefix = "appsecret:"`,
+		`output.PrintJson(out, map[string]interface{}{"appSecret": "****"})`,
+		`return &credential.TokenResult{Token: "test-token"}, nil`,
+		`fmt.Fprintf(w, "password=%s\n", pat)`,
+		`text += "(img_token:" + imgToken + ")"`,
+		`map[string]interface{}{"token": "string(optional, from inspect)"}`,
+		`this.token = token;`,
+		`// AppSecret: "appsecret:<appId>"`,
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			t.Fatalf("source code non-secret literals should not be credential findings: %#v", got)
+		}
+	}
+}
+
+func TestScanFileAllowsCredentialLikePublicPlaceholders(t *testing.T) {
+	got := ScanFile("fixtures/placeholders.md", []byte(strings.Join([]string{
+		`app_secret=***`,
+		`{"token":"&lt;wiki_token&gt;"}`,
+		`{"token":"Pgrrwvr***********UnRb"}`,
+		`"scope_name": "auth:user_access_token:read"`,
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			t.Fatalf("public placeholders and scope identifiers should not be credential findings: %#v", got)
+		}
+	}
+}
+
+func TestScanFileDetectsPartiallyMaskedCredentialValues(t *testing.T) {
+	got := ScanFile("fixtures/config.md", []byte(strings.Join([]string{
+		"client_secret=realprefix***realsuffix",
+		"client_secret=ab********cd",
+		"access_token=ab********cd",
+		"refresh_token=realprefix********realsuffix",
+	}, "\n")+"\n"))
+	var count int
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			count++
+		}
+	}
+	if count != 4 {
+		t.Fatalf("partially masked credential findings = %d, want 4: %#v", count, got)
+	}
+}
+
+func TestScanFileAllowsDryRunCredentialPlaceholders(t *testing.T) {
+	got := ScanFile("fixtures/ci.yml", []byte(strings.Join([]string{
+		"LARKSUITE_CLI_APP_SECRET=dry-run",
+		"client_secret: dry_run",
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			t.Fatalf("dry-run credential placeholders should not be credential findings: %#v", got)
+		}
+	}
+}
+
+func TestScanFileDetectsTypedCredentialAssignmentsWithSecretRHS(t *testing.T) {
+	cases := []struct {
+		name string
+		file string
+		text string
+	}{
+		{
+			name: "typescript simple secret",
+			file: "fixtures/source_secret.ts",
+			text: `const clientSecret: string = "real-client-secret-value"`,
+		},
+		{
+			name: "typescript numeric password",
+			file: "fixtures/source_secret.ts",
+			text: `const password: string = "12345678901234567890"`,
+		},
+		{
+			name: "typescript union secret",
+			file: "fixtures/source_secret.ts",
+			text: `const clientSecret: string | undefined = "real-client-secret-value"`,
+		},
+		{
+			name: "python simple secret",
+			file: "fixtures/source_secret.py",
+			text: `self.client_secret: str = "real-client-secret-value"`,
+		},
+		{
+			name: "python union secret",
+			file: "fixtures/source_secret.py",
+			text: `self.client_secret: str | None = "real-client-secret-value"`,
+		},
+		{
+			name: "python optional secret",
+			file: "fixtures/source_secret.py",
+			text: `self.client_secret: Optional[str] = "real-client-secret-value"`,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := ScanFile(tc.file, []byte(tc.text+"\n"))
+			if !findingRules(got)["public_content_generic_credential"] {
+				t.Fatalf("typed credential assignment should be reported: %#v", got)
+			}
+		})
+	}
+}
+
+func TestScanFileDetectsCredentialShapedSourceCodeLiterals(t *testing.T) {
+	githubToken := "ghp_" + "1234567890abcdef1234567890abcdef1234"
+	got := ScanFile("fixtures/source_secret.go", []byte(strings.Join([]string{
+		`const ClientSecret = "real-client-secret-value"`,
+		`const GithubToken = "` + githubToken + `"`,
+		`const Password = "12345678901234567890"`,
+		`const ClientSecretNumber = "12345678901234567890"`,
+		`const ClientSecretFormat = "abc%sdefreal"`,
+		`fmt.Println("done"); const ClientSecret = "abc%sdefreal"`,
+	}, "\n")+"\n"))
+	var count int
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			count++
+		}
+	}
+	if count != 6 {
+		t.Fatalf("source code credential-shaped literal findings = %d, want 6: %#v", count, got)
+	}
+}
+
+func TestScanFileAllowsPrintfCredentialPlaceholders(t *testing.T) {
+	got := ScanFile("fixtures/placeholders.md", []byte(strings.Join([]string{
+		"client_secret=%s",
+		"access_token=%v",
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			t.Fatalf("printf placeholders should not be credential findings: %#v", got)
+		}
+	}
+}
+
 func TestScanFileAllowsEllipsisCredentialPlaceholders(t *testing.T) {
-	got := ScanFile("skills/lark-doc/references/lark-doc-fetch.md", []byte(strings.Join([]string{
+	got := ScanFile("fixtures/lark-doc-fetch.md", []byte(strings.Join([]string{
 		`<img token="..." url="https://..." width="..." height="..."/>`,
 		`<sheet token="..." sheet-id="...">`,
 	}, "\n")+"\n"))
@@ -783,7 +949,7 @@ func TestScanFileAllowsEllipsisCredentialPlaceholders(t *testing.T) {
 }
 
 func TestScanFileAllowsSchemaDottedIdentifiers(t *testing.T) {
-	got := ScanFile("skills/lark-mail/references/lark-mail-recall.md", []byte("lark-cli schema mail.user_mailbox.sent_messages.get_recall_detail\n"))
+	got := ScanFile("fixtures/lark-mail-recall.md", []byte("lark-cli schema mail.user_mailbox.sent_messages.get_recall_detail\n"))
 	for _, item := range got {
 		if item.Rule == "public_content_jwt_like_token" {
 			t.Fatalf("schema dotted identifier should not be jwt finding: %#v", got)
@@ -791,8 +957,38 @@ func TestScanFileAllowsSchemaDottedIdentifiers(t *testing.T) {
 	}
 }
 
+func TestScanFileAllowsMarkdownDottedAPIIdentifiers(t *testing.T) {
+	got := ScanFile("fixtures/mail_api_table.md", []byte(strings.Join([]string{
+		"| Method | Permission |",
+		"| --- | --- |",
+		"| `user_mailbox.sent_messages.get_recall_detail` | `mail:user_mailbox.message:readonly` |",
+		"| `user_mailbox.allow_sender.batch_create` | `mail:user_mailbox.message:modify` |",
+		"| `user_mailbox.allow_sender.batch_remove` | `mail:user_mailbox.message:modify` |",
+		"| `user_mailbox.blocked_sender.batch_create` | `mail:user_mailbox.message:modify` |",
+		"| `user_mailbox.blocked_sender.batch_remove` | `mail:user_mailbox.message:modify` |",
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_jwt_like_token" {
+			t.Fatalf("markdown dotted API identifier should not be jwt finding: %#v", got)
+		}
+	}
+}
+
+func TestScanFileAllowsNonJWTDottedTaxonomy(t *testing.T) {
+	got := ScanFile("docs/api.md", []byte(strings.Join([]string{
+		"application/vnd.openxmlformats-officedocument.presentationml.presentation",
+		"corehr:employment.international_assignment.custom_field.apaas_id__c:read",
+		"user_mailbox.sent_messages.get_recall_detail queries recall detail.",
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_jwt_like_token" {
+			t.Fatalf("non-JWT dotted taxonomy should not be jwt finding: %#v", got)
+		}
+	}
+}
+
 func TestScanFileAllowsClientTokenIdempotencyExamples(t *testing.T) {
-	got := ScanFile("skills/idempotency.md", []byte(strings.Join([]string{
+	got := ScanFile("fixtures/idempotency.md", []byte(strings.Join([]string{
 		`{"client_token":"1704067200"}`,
 		`{"client_token":"fe599b60-450f-46ff-b2ef-9f6675625b97"}`,
 	}, "\n")+"\n"))
@@ -805,7 +1001,7 @@ func TestScanFileAllowsClientTokenIdempotencyExamples(t *testing.T) {
 
 func TestScanFileDetectsCredentialShapedClientTokenValues(t *testing.T) {
 	stripeLike := "sk_" + "live_1234567890abcdef"
-	got := ScanFile("skills/idempotency.md", []byte(strings.Join([]string{
+	got := ScanFile("fixtures/idempotency.md", []byte(strings.Join([]string{
 		`{"client_token":"` + stripeLike + `"}`,
 		`{"client_token":"real-client-secret-value"}`,
 	}, "\n")+"\n"))
@@ -821,7 +1017,7 @@ func TestScanFileDetectsCredentialShapedClientTokenValues(t *testing.T) {
 }
 
 func TestScanFileAllowsTokenLikePlaceholderExamples(t *testing.T) {
-	got := ScanFile("skills/placeholders.md", []byte(strings.Join([]string{
+	got := ScanFile("fixtures/placeholders.md", []byte(strings.Join([]string{
 		`{ "block_token": "boardXXXX" }`,
 		`{ "resource_token": "doc_token_or_url" }`,
 		`{ "token": "canonical_token" }`,
@@ -841,7 +1037,7 @@ func TestScanFileAllowsTokenLikePlaceholderExamples(t *testing.T) {
 
 func TestScanFileDetectsCredentialShapedTokenLikePlaceholderValues(t *testing.T) {
 	stripeLike := "sk_" + "live_1234567890abcdef"
-	got := ScanFile("skills/placeholders.md", []byte(strings.Join([]string{
+	got := ScanFile("fixtures/placeholders.md", []byte(strings.Join([]string{
 		`{ "resource_token": "` + stripeLike + `" }`,
 		`{ "block_token": "real-client-secret-value" }`,
 	}, "\n")+"\n"))
@@ -857,7 +1053,7 @@ func TestScanFileDetectsCredentialShapedTokenLikePlaceholderValues(t *testing.T)
 }
 
 func TestScanFileDetectsNonFixtureMinuteTokenValues(t *testing.T) {
-	got := ScanFile("shortcuts/minutes/minutes_search_test.go", []byte(`{"token":"minute_real_secret"}`+"\n"))
+	got := ScanFile("fixtures/minutes_search_test.go", []byte(`{"token":"minute_real_secret"}`+"\n"))
 	if !findingRules(got)["public_content_generic_credential"] {
 		t.Fatalf("non-fixture minute token should be credential finding: %#v", got)
 	}
@@ -958,6 +1154,19 @@ func TestScanFileDetectsJSONBearerHeaders(t *testing.T) {
 	}
 }
 
+func TestScanFileAllowsBearerHeaderPlaceholders(t *testing.T) {
+	got := ScanFile("docs/auth.md", []byte(strings.Join([]string{
+		"Authorization: Bearer YOUR_ACCESS_TOKEN",
+		`{"Authorization":"Bearer ACCESS_TOKEN_HERE"}`,
+		"Authorization: Bearer <access-token>",
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_bearer_header" {
+			t.Fatalf("bearer placeholder should not be bearer finding: %#v", got)
+		}
+	}
+}
+
 func TestSemanticCandidateRedactsJSONBearerHeaders(t *testing.T) {
 	token := "abcdefghijklmnopqrstuvwxyz"
 	text := "private launch plan for internal rollout on Friday\n" +
@@ -975,6 +1184,22 @@ func TestSemanticCandidateRedactsJSONBearerHeaders(t *testing.T) {
 	}
 }
 
+func TestSemanticCandidateKeepsNonJWTDottedTaxonomy(t *testing.T) {
+	text := "private launch plan for internal rollout on Friday\n" +
+		"Supported MIME type: application/vnd.openxmlformats-officedocument.presentationml.presentation\n"
+
+	got := semanticCandidate("docs/public.md", "file", text, 1)
+	if len(got) != 1 {
+		t.Fatalf("semantic candidate len = %d, want 1: %#v", len(got), got)
+	}
+	if strings.Contains(got[0].Excerpt, "<jwt-like-token>") {
+		t.Fatalf("semantic candidate should not redact non-JWT dotted taxonomy: %#v", got[0])
+	}
+	if !strings.Contains(got[0].Excerpt, "application/vnd.openxmlformats-officedocument.presentationml.presentation") {
+		t.Fatalf("semantic candidate should keep non-JWT dotted taxonomy, got %#v", got[0])
+	}
+}
+
 func TestScanFileDetectsCommonProvenanceMarkers(t *testing.T) {
 	text := strings.Join([]string{
 		"Generated with automated code assistant",
@@ -1012,6 +1237,37 @@ func TestScanFileAllowsPercentWrappedPlaceholder(t *testing.T) {
 	}
 }
 
+func TestScanFileAllowsConventionalCredentialPlaceholders(t *testing.T) {
+	got := ScanFile("docs/config.md", []byte(strings.Join([]string{
+		"client_secret: YOUR_CLIENT_SECRET",
+		"api_key: YOUR_API_KEY",
+		"password: YOUR_PASSWORD",
+		"access_token: ACCESS_TOKEN_HERE",
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			t.Fatalf("conventional credential placeholder should not be credential finding: %#v", got)
+		}
+	}
+}
+
+func TestScanFileDetectsCredentialShapedPlaceholderLookalikes(t *testing.T) {
+	stripeLike := "sk_" + "live_1234567890abcdef"
+	got := ScanFile("docs/config.md", []byte(strings.Join([]string{
+		"client_secret: " + stripeLike + "_HERE",
+		"api_key: YOUR_" + stripeLike,
+	}, "\n")+"\n"))
+	var count int
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			count++
+		}
+	}
+	if count != 2 {
+		t.Fatalf("credential-shaped placeholder lookalike findings = %d, want 2: %#v", count, got)
+	}
+}
+
 func TestScanFileDetectsPercentWrappedCredentialValues(t *testing.T) {
 	stripeLike := "sk_" + "live_1234567890abcdef"
 	patLike := "gh" + "p_1234567890abcdef1234567890abcdef1234"

internal/schema/assembler.go

@@ -4,8 +4,11 @@
 package schema
 
 import (
+	"regexp"
 	"sort"
+	"strings"
 
+	"github.com/larksuite/cli/internal/affordance"
 	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/meta"
@@ -22,7 +25,7 @@ func Convert(f meta.Field) Property {
 	if f.Type == "file" {
 		p.Format = "binary"
 	}
-	p.Description = f.Description
+	p.Description = normalizeDesc(f.Description)
 	p.Default = f.CoercedDefault()
 	p.Example = f.CoercedExample()
 	p.Minimum = f.MinBound()
@@ -52,6 +55,24 @@ func Convert(f meta.Field) Property {
 	return p
 }
 
+var (
+	sepRunRe   = regexp.MustCompile(`[;；]{2,}`)
+	spaceRunRe = regexp.MustCompile(`[ \t]{2,}`)
+)
+
+// normalizeDesc de-crufts a meta_data description for the envelope — strips
+// markdown emphasis and collapses doubled separators/spaces — but keeps content
+// (links, newlines, sentences); the compact flag-help has its own stricter pass.
+func normalizeDesc(s string) string {
+	if s == "" {
+		return ""
+	}
+	s = strings.ReplaceAll(s, "**", "")
+	s = sepRunRe.ReplaceAllString(s, "; ")
+	s = spaceRunRe.ReplaceAllString(s, " ")
+	return strings.TrimRight(s, " ;；。.，,、\n")
+}
+
 // enumSchema splits coerced enum options into the parallel enum / enumDescriptions
 // arrays for the envelope. enumDescriptions is nil unless at least one value
 // carries a description (so the bare-enum form stays values-only), keeping the
@@ -86,6 +107,18 @@ func propsOf(fields []meta.Field) *OrderedProps {
 	return op
 }
 
+// paramPropsOf is propsOf for the params section: each property also carries
+// its CLI flag (--kebab-name).
+func paramPropsOf(fields []meta.Field) *OrderedProps {
+	op := &OrderedProps{}
+	for _, f := range fields {
+		p := Convert(f)
+		p.Flag = "--" + f.FlagName()
+		op.Set(f.Name, p)
+	}
+	return op
+}
+
 // requiredOf returns the alphabetized names of the required fields.
 func requiredOf(fields []meta.Field) []string {
 	var required []string
@@ -108,16 +141,17 @@ func buildInputSchema(m meta.Method) *InputSchema {
 		Properties: &OrderedProps{},
 	}
 
-	addInputObject(is, "params", "", m.Params())
-	addInputObject(is, "data", "", m.Data())
-	addInputObject(is, "file", "Binary file uploads. Each property is a file field with format:binary; CLI maps each to --file <key>=<path>.", m.Files())
+	addInputObject(is, "params", "", m.Params(), true, "")
+	addInputObject(is, "data", "", m.Data(), false, "--data")
+	addInputObject(is, "file", "Binary file uploads. Each property is a file field with format:binary; CLI maps each to --file <key>=<path>.", m.Files(), false, "--file")
 
 	if m.Risk == core.RiskHighRiskWrite {
 		falseVal := false
 		is.Properties.Set("yes", Property{
 			Type:        "boolean",
+			Flag:        "--yes",
 			Default:     falseVal,
-			Description: "CLI confirmation gate. Must be true to execute; lark-cli rejects with confirmation_required if absent or false. Not sent to the backend.",
+			Description: "CLI confirmation gate. Must be true to execute; lark-cli rejects with confirmation_required if absent or false. Pass --yes only after the user has explicitly confirmed; not sent to the backend.",
 		})
 	}
 
@@ -125,20 +159,24 @@ func buildInputSchema(m meta.Method) *InputSchema {
 	return is
 }
 
-// addInputObject adds one named sub-object section (params/data/file) to the
-// input schema when it has fields: its Properties come from the fields, its
-// Required lists the mandatory keys, and the section itself is required at top
-// level when any field is required. Empty sections are skipped.
-func addInputObject(is *InputSchema, name, description string, fields []meta.Field) {
+// addInputObject adds one section (params/data/file) when it has fields, marking
+// the section required at top level when any field is. asFlags tags each property
+// with its --flag (params only); carrier names the section's flag (--data/--file).
+func addInputObject(is *InputSchema, name, description string, fields []meta.Field, asFlags bool, carrier string) {
 	if len(fields) == 0 {
 		return
 	}
+	props := propsOf(fields)
+	if asFlags {
+		props = paramPropsOf(fields)
+	}
 	req := requiredOf(fields)
 	is.Properties.Set(name, Property{
 		Type:        "object",
 		Description: description,
+		Carrier:     carrier,
 		Required:    req,
-		Properties:  propsOf(fields),
+		Properties:  props,
 	})
 	if len(req) > 0 {
 		is.Required = append(is.Required, name)
@@ -179,7 +217,13 @@ func buildMeta(m meta.Method) *Meta {
 // EnvelopeOf renders the MCP envelope for one method ref — the ref-based entry
 // callers use, since apicatalog.MethodRef is the metadata navigation currency.
 func EnvelopeOf(ref apicatalog.MethodRef) Envelope {
-	return assemble(ref.Service.Name, ref.ResourcePath, ref.Method)
+	m := ref.Method
+	// The affordance overlay lives in the CLI, not the metadata; look it up
+	// lazily here (it takes precedence over any affordance the metadata carries).
+	if raw, ok := affordance.For(ref.Service.Name, m.ID); ok {
+		m.Affordance = raw
+	}
+	return assemble(ref.Service.Name, ref.ResourcePath, m)
 }
 
 // Envelopes renders the given method refs into envelopes, sorted by name. The
@@ -205,7 +249,7 @@ func assemble(serviceName string, resourcePath []string, m meta.Method) Envelope
 
 	return Envelope{
 		Name:         name,
-		Description:  m.Description,
+		Description:  normalizeDesc(m.Description),
 		InputSchema:  buildInputSchema(m),
 		OutputSchema: buildOutputSchema(m),
 		Meta:         buildMeta(m),

internal/schema/assembler_test.go

@@ -9,7 +9,9 @@ import (
 	"reflect"
 	"strings"
 	"testing"
+	"testing/fstest"
 
+	"github.com/larksuite/cli/internal/affordance"
 	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/meta"
 	"github.com/larksuite/cli/internal/registry"
@@ -504,6 +506,31 @@ func TestBuildMeta_AffordanceFromMethod(t *testing.T) {
 	}
 }
 
+// EnvelopeOf injects affordance from the CLI overlay (looked up lazily by
+// service + method id), so a method whose metadata carries none still gets
+// guidance in its envelope when an overlay entry exists.
+func TestEnvelopeOf_AffordanceFromOverlay(t *testing.T) {
+	// The overlay source is the top-level affordance/ tree, injected at startup;
+	// inject a fixture so this unit test does not depend on the shipped content.
+	// Reset afterwards (this binary installs no source by default) for isolation.
+	t.Cleanup(func() { affordance.SetSource(nil) })
+	affordance.SetSource(fstest.MapFS{"approval.md": &fstest.MapFile{Data: []byte(
+		"# approval\n> skill: lark-approval\n\n## instances get\n查询某审批实例的状态与进度。\n\n### Examples\n\n**按 code 查询**\n```bash\nlark-cli approval instances get --instance-code \"x\"\n```\n")}})
+	env := synthEnvelope("approval", []string{"instances"}, meta.Method{ID: "instances.get", Name: "get"})
+	if env.Meta == nil || env.Meta.Affordance == nil {
+		t.Fatal("expected affordance from the approval overlay, got none")
+	}
+	if len(env.Meta.Affordance.UseWhen) == 0 || len(env.Meta.Affordance.Examples) == 0 {
+		t.Errorf("overlay affordance missing use_when/examples: %+v", env.Meta.Affordance)
+	}
+
+	// A method id with no overlay entry carries no affordance.
+	bare := synthEnvelope("approval", []string{"instances"}, meta.Method{ID: "instances.no_such_method", Name: "x"})
+	if bare.Meta != nil && bare.Meta.Affordance != nil {
+		t.Errorf("method without overlay should have no affordance, got %+v", bare.Meta.Affordance)
+	}
+}
+
 func TestBuildMeta_MissingDocURLOmitted(t *testing.T) {
 	method := map[string]interface{}{
 		"scopes":       []interface{}{"x"},

internal/schema/types.go

@@ -13,6 +13,10 @@ import (
 )
 
 // Envelope is the MCP Tool spec contract for a single API method command.
+//
+// The REST route (httpMethod/path) is deliberately NOT exposed: every
+// schema-resolvable method already has a typed command, so the raw path would
+// only tempt an agent toward the `api` escape hatch.
 type Envelope struct {
 	Name         string        `json:"name"`
 	Description  string        `json:"description"`
@@ -44,9 +48,15 @@ type OutputSchema struct {
 // "params" / "data" sub-objects inside inputSchema): it lists which keys
 // inside that object's Properties are mandatory. Leaf fields ignore it.
 type Property struct {
-	Type        string        `json:"type,omitempty"`
-	Description string        `json:"description,omitempty"`
-	Enum        []interface{} `json:"enum,omitempty"`
+	Type        string `json:"type,omitempty"`
+	Description string `json:"description,omitempty"`
+	// Flag is the typed CLI flag a params property maps to (e.g. "--folder-id");
+	// absent on body/file fields, which travel via the section's Carrier.
+	Flag string `json:"flag,omitempty"`
+	// Carrier names the flag a whole inputSchema section travels on ("--data" /
+	// "--file"); empty on the params section, whose properties carry their Flag.
+	Carrier string        `json:"carrier,omitempty"`
+	Enum    []interface{} `json:"enum,omitempty"`
 	// EnumDescriptions, when present, is parallel to Enum: the human meaning of
 	// each allowed value, in the same order. Omitted when no value carries a
 	// description. This is the widely-recognized JSON-Schema extension (VS Code,

internal/transport/warn.go

@@ -16,6 +16,14 @@ import (
 const (
 	// EnvNoProxy disables automatic proxy support when set to any non-empty value.
 	EnvNoProxy = "LARK_CLI_NO_PROXY"
+
+	// EnvNoProxyWarn suppresses the proxy-detected warning when set to any
+	// non-empty value, while leaving proxy behavior unchanged. Unlike
+	// EnvNoProxy (which both silences the warning AND disables the proxy), this
+	// keeps proxy egress active. It exists so agents consuming --format json can
+	// keep using the proxy without the human-oriented warning line landing in
+	// the output stream and breaking JSON parsing.
+	EnvNoProxyWarn = "LARK_CLI_NO_PROXY_WARN"
 )
 
 // proxyEnvKeys lists environment variables that Go's ProxyFromEnvironment reads.
@@ -73,6 +81,11 @@ func redactProxyURL(raw string) string {
 // are redacted. Safe to call multiple times; only the first call prints.
 func WarnIfProxied(w io.Writer) {
 	proxyWarningOnce.Do(func() {
+		// Explicit opt-out: silence the warning without touching proxy behavior.
+		// Checked before the plugin and env-proxy branches so it suppresses both.
+		if os.Getenv(EnvNoProxyWarn) != "" {
+			return
+		}
 		// Proxy plugin mode overrides env proxies and LARK_CLI_NO_PROXY (see
 		// Shared), so its warning and disable instructions take precedence.
 		// Emitting the env-proxy warning here would be misleading: it tells the
@@ -88,7 +101,7 @@ func WarnIfProxied(w io.Writer) {
 		if key == "" {
 			return
 		}
-		fmt.Fprintf(w, "[lark-cli] [WARN] proxy detected: %s=%s — requests (including credentials) will transit through this proxy. Set %s=1 to disable proxy.\n",
-			key, redactProxyURL(val), EnvNoProxy)
+		fmt.Fprintf(w, "[lark-cli] [WARN] proxy detected: %s=%s — requests (including credentials) will transit through this proxy. Set %s=1 to disable proxy, or %s=1 to keep the proxy and silence this warning.\n",
+			key, redactProxyURL(val), EnvNoProxy, EnvNoProxyWarn)
 	})
 }

internal/transport/warn_test.go

@@ -93,6 +93,47 @@ func TestWarnIfProxied_SilentWhenDisabled(t *testing.T) {
 	}
 }
 
+// TestWarnIfProxied_SilentWhenWarnOptOut verifies that LARK_CLI_NO_PROXY_WARN
+// suppresses the warning while the proxy stays configured (unlike
+// LARK_CLI_NO_PROXY, which also disables the proxy).
+func TestWarnIfProxied_SilentWhenWarnOptOut(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	proxyWarningOnce = sync.Once{}
+
+	t.Setenv("HTTPS_PROXY", "http://proxy:8080")
+	t.Setenv(EnvNoProxyWarn, "1")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	if buf.Len() != 0 {
+		t.Errorf("expected no warning when %s is set, got: %s", EnvNoProxyWarn, buf.String())
+	}
+}
+
+// TestWarnIfProxied_WarnOptOutSuppressesPluginWarning verifies that
+// LARK_CLI_NO_PROXY_WARN also suppresses the proxy-plugin warning.
+func TestWarnIfProxied_WarnOptOutSuppressesPluginWarning(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	proxyWarningOnce = sync.Once{}
+
+	old := proxyPluginStatus
+	proxyPluginStatus = func() (string, string, bool) { return "http://127.0.0.1:3128", "", true }
+	t.Cleanup(func() { proxyPluginStatus = old })
+
+	t.Setenv(EnvNoProxyWarn, "1")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	if buf.Len() != 0 {
+		t.Errorf("expected no plugin warning when %s is set, got: %s", EnvNoProxyWarn, buf.String())
+	}
+}
+
 // TestWarnIfProxied_OnlyOnce verifies that proxy warnings are emitted only once.
 func TestWarnIfProxied_OnlyOnce(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())

package.json

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

scripts/install-wizard.js

@@ -5,7 +5,12 @@
 const fs = require("fs");
 const path = require("path");
 const { execFileSync, execFile } = require("child_process");
-const p = require("@clack/prompts");
+
+// @clack/prompts is ESM-only since v1; load it via dynamic import() so this
+// CommonJS script works on all supported Node versions (require() of an ESM
+// package throws ERR_REQUIRE_ESM before Node 22.12). Assigned in the entry
+// point below before main() runs.
+let p;
 
 const PKG = "@larksuite/cli";
 const SKILLS_REPO = "https://open.feishu.cn";
@@ -374,7 +379,12 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  p.cancel("Unexpected error: " + (err.message || err));
+(async () => {
+  p = await import("@clack/prompts");
+  await main();
+})().catch((err) => {
+  const msg = "Unexpected error: " + (err.message || err);
+  if (p) p.cancel(msg);
+  else console.error(msg);
   process.exit(1);
 });

shortcuts/apps/apps_db_audit_list.go

@@ -36,7 +36,7 @@ var AppsDBAuditList = common.Shortcut{
 	Flags: append([]common.Flag{
 		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "table", Type: "string_slice", Desc: "table(s) to list audit events for (repeatable)", Required: true},
-		{Name: "since", Desc: "filter: event at or after; relative (7d/2h) | date | datetime | ISO 8601 w/ TZ"},
+		{Name: "since", Desc: "filter: event at or after; relative (7d/2h) | date | datetime | ISO 8601 w/ TZ (bare date/datetime read in local timezone)"},
 		{Name: "until", Desc: "filter: event at or before; same formats as --since"},
 		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
 		{Name: "page-token", Desc: "pagination cursor from previous response"},

shortcuts/apps/apps_db_changelog_list.go

@@ -35,7 +35,7 @@ var AppsDBChangelogList = common.Shortcut{
 		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "table", Desc: "filter by target table"},
 		{Name: "change-id", Desc: "look up a single change by id (returns that one record only)"},
-		{Name: "since", Desc: "filter: changed at or after; relative (7d/2h) | date | datetime | ISO 8601 w/ TZ"},
+		{Name: "since", Desc: "filter: changed at or after; relative (7d/2h) | date | datetime | ISO 8601 w/ TZ (bare date/datetime read in local timezone)"},
 		{Name: "until", Desc: "filter: changed at or before; same formats as --since"},
 		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
 		{Name: "page-token", Desc: "pagination cursor from previous response"},

shortcuts/apps/apps_db_data_export.go

@@ -61,6 +61,9 @@ var AppsDBDataExport = common.Shortcut{
 		if n := rctx.Int("limit"); n <= 0 || n > dbDataExportMaxRows {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--limit must be a positive integer ≤ %d", dbDataExportMaxRows).WithParam("--limit")
 		}
+		if err := rejectOutputTraversal(rctx.Str("output")); err != nil {
+			return err
+		}
 		if _, _, err := exportFormatAndOutput(rctx); err != nil {
 			return err
 		}

shortcuts/apps/apps_db_env_migrate.go

@@ -111,7 +111,7 @@ var AppsDBEnvMigrate = common.Shortcut{
 		}
 		// 有 task_id → 异步，轮询至终态；无 task_id（同步完成）则直接用 submit 结果。
 		if taskID != "" {
-			final, perr := pollUntil(rctx.Ctx(), 1*time.Second, 10*time.Minute,
+			final, perr := pollUntil(rctx.Ctx(), 1*time.Second, 2*time.Minute,
 				func() (map[string]interface{}, error) {
 					return rctx.CallAPITyped("GET", appEnvMigrateStatusPath(appID), map[string]interface{}{"task_id": taskID}, nil)
 				},

shortcuts/apps/apps_db_execute.go

@@ -84,8 +84,8 @@ var AppsDBExecute = common.Shortcut{
 			if err != nil {
 				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: %v", err)
 			}
-			// 归一化：把文件内容写回 --sql，下游（DryRun/Execute）统一从 sql 取。
-			rctx.Cmd.Flags().Set("sql", string(data))
+			// 仅本地校验非空；不把文件内容写回公开的 --sql flag（避免 SQL 内容进入
+			// flag dump / 结构化日志）。下游 DryRun/Execute 由 resolveExecuteSQL 在用时重新读取。
 			sql = strings.TrimSpace(string(data))
 		}
 		if sql == "" {
@@ -297,10 +297,29 @@ func buildDBSQLParams(rctx *common.RuntimeContext) map[string]interface{} {
 	}
 }
 
-// buildDBSQLBody 构造 sql 接口的 body：仅 sql（来源由 Validate 归一化到 --sql）。
+// resolveExecuteSQL 返回要执行的 SQL，在用时（DryRun/Execute）现读，使 --file 的内容
+// 不被写回公开的 --sql flag（避免泄露进 flag dump / 结构化日志）。优先 --sql（内联或 stdin，
+// 已由输入框架解析到 flag 值）；否则现读 --file。Validate 已先行校验可读且非空。
+func resolveExecuteSQL(rctx *common.RuntimeContext) (string, error) {
+	if strings.TrimSpace(rctx.Str("sql")) != "" {
+		return rctx.Str("sql"), nil
+	}
+	file := strings.TrimSpace(rctx.Str("file"))
+	if file == "" {
+		return "", nil
+	}
+	data, err := cmdutil.ReadInputFile(rctx.FileIO(), file)
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}
+
+// buildDBSQLBody 构造 sql 接口的 body：仅 sql（由 resolveExecuteSQL 在用时解析，--file 不入 flag）。
 func buildDBSQLBody(rctx *common.RuntimeContext) map[string]interface{} {
+	sql, _ := resolveExecuteSQL(rctx)
 	return map[string]interface{}{
-		"sql": rctx.Str("sql"),
+		"sql": sql,
 	}
 }
 

shortcuts/apps/apps_db_recovery.go

@@ -117,7 +117,7 @@ var AppsDBRecoveryApply = common.Shortcut{
 			})
 			return nil
 		}
-		final, perr := pollUntil(rctx.Ctx(), 2*time.Second, 30*time.Minute,
+		final, perr := pollUntil(rctx.Ctx(), 2*time.Second, 2*time.Minute,
 			func() (map[string]interface{}, error) {
 				return rctx.CallAPITyped("GET", appRecoveryApplyStatusPath(appID), nil, nil)
 			},
@@ -165,7 +165,7 @@ func runRecoveryPreview(rctx *common.RuntimeContext, appID, target string) (map[
 	if prid == "" {
 		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "recovery diff did not return preview_request_id")
 	}
-	return pollUntil(rctx.Ctx(), 1*time.Second, 10*time.Minute,
+	return pollUntil(rctx.Ctx(), 1*time.Second, 2*time.Minute,
 		func() (map[string]interface{}, error) {
 			return rctx.CallAPITyped("GET", appRecoveryDiffStatusPath(appID), map[string]interface{}{"preview_request_id": prid}, nil)
 		},

shortcuts/apps/apps_file_download.go

@@ -41,6 +41,9 @@ var AppsFileDownload = common.Shortcut{
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
 		}
+		if err := rejectOutputTraversal(rctx.Str("output")); err != nil {
+			return err
+		}
 		_, err := requireFilePath(rctx.Str("path"))
 		return err
 	},

shortcuts/apps/apps_file_list.go

@@ -39,8 +39,8 @@ var AppsFileList = common.Shortcut{
 		{Name: "type", Desc: "filter by MIME type"},
 		{Name: "size-gt", Type: "int", Desc: "filter: size greater than (bytes)"},
 		{Name: "size-lt", Type: "int", Desc: "filter: size less than (bytes)"},
-		{Name: "uploaded-since", Desc: "filter: uploaded at or after; relative (7d/2h/30s) | date (2026-04-15) | datetime (2026-04-15T10:00:00) | ISO 8601 w/ TZ"},
-		{Name: "uploaded-until", Desc: "filter: uploaded at or before; relative (7d/2h/30s) | date (2026-04-15) | datetime (2026-04-15T10:00:00) | ISO 8601 w/ TZ"},
+		{Name: "uploaded-since", Desc: "filter: uploaded at or after; relative (7d/2h/30s) | date (2026-04-15) | datetime (2026-04-15T10:00:00) | ISO 8601 w/ TZ (bare date/datetime read in local timezone)"},
+		{Name: "uploaded-until", Desc: "filter: uploaded at or before; relative (7d/2h/30s) | date (2026-04-15) | datetime (2026-04-15T10:00:00) | ISO 8601 w/ TZ (bare date/datetime read in local timezone)"},
 		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
 		{Name: "page-token", Desc: "pagination cursor from previous response"},
 	},

shortcuts/apps/apps_file_upload.go

@@ -136,7 +136,14 @@ func putFileBytes(ctx context.Context, url string, content []byte, contentType,
 	if contentType != "" {
 		req.Header.Set("Content-Type", contentType)
 	}
-	req.Header.Set("Content-Disposition", "attachment; filename=\""+sanitizeUploadFileName(fileName)+"\"")
+	// 用 mime.FormatMediaType 规范生成 Content-Disposition（自动按 RFC 2045 处理引号/转义），
+	// 不手工拼接 header，杜绝文件名里的特殊字符破坏 header 结构。filename 已先经 sanitizeUploadFileName
+	// 做 encodeURIComponent（控制字符/分隔符均 %XX 化），此处是第二道防线。
+	disposition := mime.FormatMediaType("attachment", map[string]string{"filename": sanitizeUploadFileName(fileName)})
+	if disposition == "" {
+		disposition = "attachment"
+	}
+	req.Header.Set("Content-Disposition", disposition)
 	resp, err := newFileTransferClient().Do(req)
 	if err != nil {
 		// dial/transport 失败是典型可重试场景。
@@ -170,6 +177,11 @@ func sanitizeUploadFileName(name string) string {
 	if enc == "" {
 		return "download_file"
 	}
+	// 防止 sanitize 后仍以 . 开头（如 .bashrc / .ssh）——下载落地可能覆盖本地隐藏文件，
+	// 前置下划线消除隐藏文件语义。
+	if strings.HasPrefix(enc, ".") {
+		enc = "_" + enc
+	}
 	return enc
 }
 

shortcuts/apps/apps_file_upload_test.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"errors"
 	"io"
+	"mime"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -143,8 +144,10 @@ func TestAppsFileUpload_EndToEnd(t *testing.T) {
 		t.Errorf("PUT Content-Type = %q, want image/png", putContentType)
 	}
 	// 原始文件名必须经 Content-Disposition 透传给 TOS（否则后端用 storage key 当文件名）。
-	if putCD != `attachment; filename="logo.png"` {
-		t.Errorf("PUT Content-Disposition = %q, want attachment; filename=\"logo.png\"", putCD)
+	// 断言按解析结果（format-agnostic）：mime.FormatMediaType 对无 tspecial 的名不加引号，
+	// 旧的写死字符串 `filename="logo.png"` 不再成立，但 filename 参数仍须等于原名。
+	if disp, params, err := mime.ParseMediaType(putCD); err != nil || disp != "attachment" || params["filename"] != "logo.png" {
+		t.Errorf("PUT Content-Disposition = %q, want disposition=attachment filename=logo.png (parse err=%v)", putCD, err)
 	}
 	got := stdout.String()
 	if !strings.Contains(got, `"path": "/1858537546760216.png"`) {

shortcuts/apps/apps_openapi_key_common.go

@@ -46,13 +46,118 @@ func redactKeyInfo(info map[string]interface{}) map[string]interface{} {
 	return out
 }
 
-// parseScopeAPI parses a "--scope-api" value 'METHOD /openapi/path' into a snake_case httpInfo.
+// allowedScopeAPIMethods is the HTTP method whitelist for --scope-api / request_scope.
+var allowedScopeAPIMethods = map[string]struct{}{
+	"GET": {}, "POST": {}, "PUT": {}, "PATCH": {}, "DELETE": {},
+}
+
+// validateScopeAPIMethod rejects methods outside the whitelist (e.g. TRACE, CONNECT, empty).
+func validateScopeAPIMethod(method string) error {
+	if _, ok := allowedScopeAPIMethods[method]; !ok {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"http method %q not allowed; use one of GET, POST, PUT, PATCH, DELETE", method)
+	}
+	return nil
+}
+
+// validateScopeAPIPath enforces basic openapi route hygiene as a first line of defense.
+func validateScopeAPIPath(p string) error {
+	if p == "" || !strings.HasPrefix(p, "/") {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"http path must start with '/', got %q", p)
+	}
+	if strings.Contains(p, "..") {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"http path must not contain '..': %q", p)
+	}
+	if strings.Contains(p, "//") {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"http path must not contain '//': %q", p)
+	}
+	return nil
+}
+
+// validateRequestScopeFields constrains a request_scope object to the documented
+// schema: only allow_all (bool) and http_infos ([{http_method, http_path}]). This
+// closes the raw --scope escape hatch from injecting undocumented fields.
+func validateRequestScopeFields(rs map[string]interface{}) error {
+	for k := range rs {
+		switch k {
+		case "allow_all", "http_infos":
+		default:
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"unknown field %q; only allow_all and http_infos are allowed", k)
+		}
+	}
+	if v, ok := rs["allow_all"]; ok {
+		if _, isBool := v.(bool); !isBool {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "allow_all must be a boolean")
+		}
+	}
+	if v, ok := rs["http_infos"]; ok {
+		arr, isArr := v.([]interface{})
+		if !isArr {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "http_infos must be an array")
+		}
+		for _, item := range arr {
+			m, isMap := item.(map[string]interface{})
+			if !isMap {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "each http_infos entry must be an object")
+			}
+			for k := range m {
+				switch k {
+				case "http_method", "http_path":
+				default:
+					return errs.NewValidationError(errs.SubtypeInvalidArgument,
+						"unknown field %q in http_infos entry; only http_method and http_path are allowed", k)
+				}
+			}
+			method, _ := m["http_method"].(string)
+			if err := validateScopeAPIMethod(method); err != nil {
+				return err
+			}
+			path, _ := m["http_path"].(string)
+			if err := validateScopeAPIPath(path); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// parseRawScope parses a raw --scope JSON value: it must be an object that
+// conforms to the request_scope schema (validated by validateRequestScopeFields).
+func parseRawScope(scopeRaw string) (map[string]interface{}, error) {
+	var rs interface{}
+	if err := json.Unmarshal([]byte(scopeRaw), &rs); err != nil {
+		return nil, err
+	}
+	obj, ok := rs.(map[string]interface{})
+	if !ok {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--scope must be a JSON object")
+	}
+	if err := validateRequestScopeFields(obj); err != nil {
+		return nil, err
+	}
+	return obj, nil
+}
+
+// parseScopeAPI parses a "--scope-api" value 'METHOD /openapi/path' into a snake_case
+// httpInfo, validating the method against the whitelist and the path format.
 func parseScopeAPI(s string) (map[string]interface{}, error) {
 	fields := strings.Fields(strings.TrimSpace(s))
 	if len(fields) != 2 {
 		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "expected 'METHOD /path', got %q", s)
 	}
-	return map[string]interface{}{"http_method": strings.ToUpper(fields[0]), "http_path": fields[1]}, nil
+	method := strings.ToUpper(fields[0])
+	if err := validateScopeAPIMethod(method); err != nil {
+		return nil, err
+	}
+	path := fields[1]
+	if err := validateScopeAPIPath(path); err != nil {
+		return nil, err
+	}
+	return map[string]interface{}{"http_method": method, "http_path": path}, nil
 }
 
 // buildRequestScope assembles config.request_scope (snake_case) from the scope flags.
@@ -65,11 +170,7 @@ func buildRequestScope(scopeAll bool, scopeAPIs []string, scopeRaw string) (inte
 		if hasFriendly {
 			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--scope cannot be combined with --scope-all / --scope-api").WithParam("--scope")
 		}
-		var rs interface{}
-		if err := json.Unmarshal([]byte(scopeRaw), &rs); err != nil {
-			return nil, err
-		}
-		return rs, nil
+		return parseRawScope(scopeRaw)
 	}
 	if !hasFriendly {
 		return nil, nil
@@ -111,18 +212,21 @@ func buildKeyConfig(scopeAll bool, scopeAPIs []string, scopeRaw string, hasAllow
 // oapiKeyValidateScopeFlags validates the scope flag combination (shared by create/update).
 func oapiKeyValidateScopeFlags(rctx *common.RuntimeContext) error {
 	scopeRaw := strings.TrimSpace(rctx.Str("scope"))
-	if scopeRaw != "" && (rctx.Bool("scope-all") || len(rctx.StrArray("scope-api")) > 0) {
+	scopeAPIs := rctx.StrArray("scope-api")
+	if scopeRaw != "" && (rctx.Bool("scope-all") || len(scopeAPIs) > 0) {
 		return appsValidationParamError("--scope", "--scope cannot be combined with --scope-all / --scope-api").
 			WithHint("use either --scope (raw JSON) OR --scope-all/--scope-api, not both")
 	}
-	if scopeRaw != "" && !json.Valid([]byte(scopeRaw)) {
-		return appsValidationParamError("--scope", "--scope must be valid JSON").
-			WithHint("--scope takes raw JSON for config.request_scope; or use --scope-all / --scope-api 'METHOD /openapi/path'")
+	if scopeRaw != "" {
+		if _, err := parseRawScope(scopeRaw); err != nil {
+			return appsValidationParamError("--scope", "invalid --scope: %s", err).
+				WithHint("--scope takes a JSON object with only allow_all (bool) and http_infos ([{http_method, http_path}]); methods: GET, POST, PUT, PATCH, DELETE")
+		}
 	}
-	for _, a := range rctx.StrArray("scope-api") {
-		if len(strings.Fields(strings.TrimSpace(a))) != 2 {
-			return appsValidationParamError("--scope-api", "--scope-api must be 'METHOD /path', got %q", a).
-				WithHint("format: --scope-api 'METHOD /openapi/path' (routes come from the app's docs/openapi.json), e.g. --scope-api 'GET /openapi/orders'")
+	for _, a := range scopeAPIs {
+		if _, err := parseScopeAPI(a); err != nil {
+			return appsValidationParamError("--scope-api", "invalid --scope-api: %s", err).
+				WithHint("format: 'METHOD /openapi/path'; method one of GET, POST, PUT, PATCH, DELETE; path starts with '/', no '..' or '//'")
 		}
 	}
 	return nil

shortcuts/apps/apps_openapi_key_common_test.go

@@ -78,6 +78,108 @@ func TestParseScopeAPI(t *testing.T) {
 	})
 }
 
+func TestValidateScopeAPIMethod(t *testing.T) {
+	for _, m := range []string{"GET", "POST", "PUT", "PATCH", "DELETE"} {
+		if err := validateScopeAPIMethod(m); err != nil {
+			t.Errorf("validateScopeAPIMethod(%q) = %v, want nil", m, err)
+		}
+	}
+	for _, m := range []string{"TRACE", "CONNECT", "OPTIONS", "HEAD", "", "get"} {
+		if err := validateScopeAPIMethod(m); err == nil {
+			t.Errorf("validateScopeAPIMethod(%q) = nil, want error", m)
+		}
+	}
+}
+
+func TestValidateScopeAPIPath(t *testing.T) {
+	for _, p := range []string{"/openapi/orders", "/openapi/v1/x"} {
+		if err := validateScopeAPIPath(p); err != nil {
+			t.Errorf("validateScopeAPIPath(%q) = %v, want nil", p, err)
+		}
+	}
+	for _, p := range []string{"", "openapi/x", "/openapi/../admin", "/..", "/openapi//x", "//x"} {
+		if err := validateScopeAPIPath(p); err == nil {
+			t.Errorf("validateScopeAPIPath(%q) = nil, want error", p)
+		}
+	}
+}
+
+func TestValidateRequestScopeFields(t *testing.T) {
+	ok := []map[string]interface{}{
+		{"allow_all": true},
+		{"allow_all": false, "http_infos": []interface{}{
+			map[string]interface{}{"http_method": "GET", "http_path": "/openapi/x"},
+		}},
+		{},
+	}
+	for _, rs := range ok {
+		if err := validateRequestScopeFields(rs); err != nil {
+			t.Errorf("validateRequestScopeFields(%v) = %v, want nil", rs, err)
+		}
+	}
+	bad := []map[string]interface{}{
+		{"foo": 1},                         // unknown top-level field
+		{"allow_all": "yes"},               // wrong type
+		{"http_infos": "x"},                // not an array
+		{"http_infos": []interface{}{"x"}}, // entry not an object
+		{"http_infos": []interface{}{map[string]interface{}{"http_method": "TRACE", "http_path": "/x"}}},           // bad method
+		{"http_infos": []interface{}{map[string]interface{}{"http_method": "GET", "http_path": "../x"}}},           // bad path
+		{"http_infos": []interface{}{map[string]interface{}{"http_method": "GET", "http_path": "/x", "extra": 1}}}, // unknown entry field
+	}
+	for _, rs := range bad {
+		if err := validateRequestScopeFields(rs); err == nil {
+			t.Errorf("validateRequestScopeFields(%v) = nil, want error", rs)
+		}
+	}
+}
+
+func TestParseRawScope(t *testing.T) {
+	if _, err := parseRawScope(`{"allow_all":true}`); err != nil {
+		t.Errorf("valid object errored: %v", err)
+	}
+	for _, raw := range []string{`["x"]`, `"s"`, `123`, `{"foo":1}`, `{bad`} {
+		if _, err := parseRawScope(raw); err == nil {
+			t.Errorf("parseRawScope(%q) = nil, want error", raw)
+		}
+	}
+}
+
+func TestParseScopeAPI_Rejects(t *testing.T) {
+	bad := []string{"TRACE /openapi/x", "CONNECT /x", "GET ../admin", "GET openapi/x", "GET /a//b"}
+	for _, in := range bad {
+		if _, err := parseScopeAPI(in); err == nil {
+			t.Errorf("parseScopeAPI(%q) = nil, want error", in)
+		}
+	}
+	// regression: legitimate input still parses (and lowercases the method)
+	info, err := parseScopeAPI("get /openapi/orders")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if info["http_method"] != "GET" || info["http_path"] != "/openapi/orders" {
+		t.Errorf("info = %v", info)
+	}
+}
+
+func TestBuildRequestScope_RawValidation(t *testing.T) {
+	// unknown field now rejected (HIGH-2)
+	if _, err := buildRequestScope(false, nil, `{"foo":1}`); err == nil {
+		t.Errorf("raw scope with unknown field must error")
+	}
+	// non-object rejected
+	if _, err := buildRequestScope(false, nil, `["x"]`); err == nil {
+		t.Errorf("non-object raw scope must error")
+	}
+	// nested bad method rejected
+	if _, err := buildRequestScope(false, nil, `{"http_infos":[{"http_method":"TRACE","http_path":"/x"}]}`); err == nil {
+		t.Errorf("raw scope with bad nested method must error")
+	}
+	// regression: documented fields pass
+	if _, err := buildRequestScope(false, nil, `{"allow_all":true}`); err != nil {
+		t.Errorf("valid raw scope errored: %v", err)
+	}
+}
+
 func TestBuildRequestScope(t *testing.T) {
 	t.Run("nothing set -> nil", func(t *testing.T) {
 		rs, err := buildRequestScope(false, nil, "")

shortcuts/apps/apps_plugin_install.go

@@ -34,9 +34,10 @@ var AppsPluginInstall = common.Shortcut{
 	Scopes:            []string{},
 	AuthTypes:         []string{"user"},
 	Tips: []string{
-		"Example: lark-cli apps +plugin-install --name @official-plugins/ai-text-generate",
-		"Example: lark-cli apps +plugin-install --name @official-plugins/ai-text-generate --version 1.0.0",
-		"Example: lark-cli apps +plugin-install  (install all declared plugins in package.json)",
+		"Run in project root (like npm); does NOT take --app-id",
+		"Example: lark-cli apps +plugin-install --name @official-plugins/ai-text-generate  (install or update to latest)",
+		"Example: lark-cli apps +plugin-install --name @official-plugins/ai-text-generate --version 1.0.0  (install or update to specific version)",
+		"Example: lark-cli apps +plugin-install  (batch install all declared plugins from package.json actionPlugins)",
 	},
 	Flags: []common.Flag{
 		{Name: "name", Desc: "plugin key (e.g. @official-plugins/ai-text-generate); omit to install all declared plugins"},

shortcuts/apps/apps_plugin_list.go

@@ -21,6 +21,7 @@ var AppsPluginList = common.Shortcut{
 	Risk:        "read",
 	Scopes:      []string{},
 	Tips: []string{
+		"Run in project root (like npm); does NOT take --app-id",
 		"Example: lark-cli apps +plugin-list",
 		"Example: lark-cli apps +plugin-list --format pretty",
 	},

shortcuts/apps/apps_plugin_uninstall.go

@@ -22,6 +22,7 @@ var AppsPluginUninstall = common.Shortcut{
 	Risk:        "write",
 	Scopes:      []string{},
 	Tips: []string{
+		"Run in project root (like npm); does NOT take --app-id",
 		"Example: lark-cli apps +plugin-uninstall --name @official-plugins/ai-text-generate",
 	},
 	Flags: []common.Flag{

shortcuts/apps/apps_security_fixes_test.go

@@ -0,0 +1,50 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestRejectOutputTraversal pins HIGH-3: --output rejects absolute paths and
+// any .. traversal component; empty and ordinary relative paths pass.
+func TestRejectOutputTraversal(t *testing.T) {
+	ok := []string{"", "out.csv", "./out.csv", "sub/dir/out.csv", "a..b.csv", "foo..bar/x.csv"}
+	for _, p := range ok {
+		if err := rejectOutputTraversal(p); err != nil {
+			t.Errorf("rejectOutputTraversal(%q) = %v, want nil", p, err)
+		}
+	}
+	bad := []string{"/etc/passwd", "../x", "../../etc/cron.d/evil", "sub/../../x", "./../x"}
+	for _, p := range bad {
+		if err := rejectOutputTraversal(p); err == nil {
+			t.Errorf("rejectOutputTraversal(%q) = nil, want validation error", p)
+		}
+	}
+}
+
+// TestSanitizeUploadFileName pins HIGH-4 / LOW-1: control & separator chars are
+// neutralized (percent-encoded, no raw CR/LF/TAB/NUL/quote) and the result never
+// starts with a dot (hidden-file overwrite guard).
+func TestSanitizeUploadFileName(t *testing.T) {
+	// LOW-1: dotfiles get a leading underscore.
+	for _, in := range []string{".bashrc", ".ssh", "..hidden"} {
+		got := sanitizeUploadFileName(in)
+		if strings.HasPrefix(got, ".") {
+			t.Errorf("sanitizeUploadFileName(%q) = %q, must not start with '.'", in, got)
+		}
+	}
+	// HIGH-4: header-breaking / control chars must not survive raw.
+	raw := "a\r\nb\tc\x00d\"e.png"
+	got := sanitizeUploadFileName(raw)
+	for _, bad := range []string{"\r", "\n", "\t", "\x00", "\"", " "} {
+		if strings.Contains(got, bad) {
+			t.Errorf("sanitizeUploadFileName(%q) = %q, still contains raw %q", raw, got, bad)
+		}
+	}
+	if got == "" {
+		t.Error("sanitizeUploadFileName returned empty for non-empty input")
+	}
+}

shortcuts/apps/common.go

@@ -4,6 +4,7 @@
 package apps
 
 import (
+	"path/filepath"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
@@ -39,3 +40,28 @@ func withAppsHint(err error, hint string) error {
 	}
 	return err
 }
+
+// rejectOutputTraversal is a defense-in-depth pre-check on a user-supplied
+// --output path. The authoritative guard is the local FileIO layer
+// (validate.SafeOutputPath sandboxes every write to the cwd, resolving .. and
+// symlinks), so traversal is already blocked at write time; this gives an
+// earlier, clearer validation error and pins the contract in the command layer.
+// Empty (use server-derived default) passes through. Absolute paths and any
+// ".." path component are rejected.
+func rejectOutputTraversal(output string) error {
+	o := strings.TrimSpace(output)
+	if o == "" {
+		return nil
+	}
+	if filepath.IsAbs(o) {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"--output must be a relative path within the current directory, got %q", o).WithParam("--output")
+	}
+	for _, seg := range strings.Split(filepath.Clean(o), string(filepath.Separator)) {
+		if seg == ".." {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"--output must not contain .. path traversal, got %q", o).WithParam("--output")
+		}
+	}
+	return nil
+}

shortcuts/apps/git_credential.go

@@ -488,7 +488,7 @@ func issuedFromData(appID string, data map[string]interface{}) (*gitcred.IssuedC
 // handled locally.
 func parseIssueCredentialData(resp *larkcore.ApiResp, err error, cc errclass.ClassifyContext) (map[string]any, error) {
 	if err != nil {
-		return nil, client.WrapDoAPIError(err)
+		return nil, redactGitCredentialIssueError(client.WrapDoAPIError(err))
 	}
 	detail := logIDDetail(resp)
 	if resp == nil || len(resp.RawBody) == 0 {
@@ -501,7 +501,7 @@ func parseIssueCredentialData(resp *larkcore.ApiResp, err error, cc errclass.Cla
 	if jsonErr != nil || hasCode || resp.StatusCode >= http.StatusBadRequest {
 		data, cerr := common.ClassifyAPIResponseWith(resp, cc)
 		if cerr != nil {
-			return nil, withAppsHint(cerr, gitCredentialIssueHint)
+			return nil, redactGitCredentialIssueError(withAppsHint(cerr, gitCredentialIssueHint))
 		}
 		if data != nil {
 			result = data
@@ -536,6 +536,7 @@ func checkGitInfoBaseResp(result map[string]any, logID string) error {
 		if message == "" {
 			message = "Git credential API returned non-zero BaseResp status"
 		}
+		message = gitcred.RedactCredentialText(message)
 		baseErr := errs.NewAPIError(errs.SubtypeUnknown, "Issue app Git credential: %s", message).WithCode(int(code))
 		if logID != "" {
 			baseErr = baseErr.WithLogID(logID)
@@ -545,6 +546,17 @@ func checkGitInfoBaseResp(result map[string]any, logID string) error {
 	return nil
 }
 
+func redactGitCredentialIssueError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if p, ok := errs.ProblemOf(err); ok {
+		p.Message = gitcred.RedactCredentialText(p.Message)
+		p.Hint = gitcred.RedactCredentialText(p.Hint)
+	}
+	return err
+}
+
 func logIDDetail(resp *larkcore.ApiResp) map[string]any {
 	logID := logIDString(resp)
 	if logID == "" {

shortcuts/apps/git_credential_test.go

@@ -12,7 +12,6 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
-	"regexp"
 	"strconv"
 	"strings"
 	"testing"
@@ -1027,25 +1026,24 @@ func TestParseIssueCredentialDataBusinessCodeHasHintNotRetryable(t *testing.T) {
 	}
 }
 
-// TestParseIssueCredentialDataMessageAddsNoExtraSecret verifies the security
-// condition that apps does not ADDITIONALLY inject any token/secret into the
-// Git-credential error it builds. The server `msg` is passed through verbatim
-// into Problem.Message, and the only thing apps adds is the static
-// gitCredentialIssueHint — which itself contains no secret. We feed a benign
-// server msg and assert (a) Message equals that msg exactly, and (b) neither
-// Message nor Hint contains any token/secret-shaped string.
-//
-// Note: server msg passthrough is the shared classifier's responsibility;
-// apps adds only a static hint. There is no msg redaction in this path, so
-// this test does not assert a redaction that does not exist — it asserts
-// that apps injects nothing sensitive of its own.
-func TestParseIssueCredentialDataMessageAddsNoExtraSecret(t *testing.T) {
-	const serverMsg = "permission denied"
+// TestParseIssueCredentialDataRedactsCredentialErrorMessage verifies that the
+// git-credential boundary does not pass server-provided credential details into
+// the user-visible typed envelope message.
+func TestParseIssueCredentialDataRedactsCredentialErrorMessage(t *testing.T) {
+	samplePAT := testPublicSafeJoin("pat", "-sample")
+	samplePassword := "sample-password"
+	serverMsg := "permission denied: " +
+		testCredentialAssignment("token", samplePAT) + " " +
+		testCredentialAssignment("password", samplePassword) + " " +
+		testCredentialURLWithUserInfo("example.com/repo.git", samplePAT)
 	header := http.Header{"X-Tt-Logid": []string{"log_x"}}
 
 	for _, tc := range []struct {
-		name string
-		resp *larkcore.ApiResp
+		name        string
+		resp        *larkcore.ApiResp
+		wantType    errs.Category
+		wantSubtype errs.Subtype
+		wantCode    int
 	}{
 		{
 			name: "http error path",
@@ -1054,6 +1052,9 @@ func TestParseIssueCredentialDataMessageAddsNoExtraSecret(t *testing.T) {
 				RawBody:    []byte(`{"msg":"` + serverMsg + `"}`),
 				Header:     header,
 			},
+			wantType:    errs.CategoryAPI,
+			wantSubtype: errs.SubtypeUnknown,
+			wantCode:    http.StatusForbidden,
 		},
 		{
 			name: "business code path",
@@ -1062,6 +1063,9 @@ func TestParseIssueCredentialDataMessageAddsNoExtraSecret(t *testing.T) {
 				RawBody:    []byte(`{"code":999,"msg":"` + serverMsg + `"}`),
 				Header:     header,
 			},
+			wantType:    errs.CategoryAPI,
+			wantSubtype: errs.SubtypeUnknown,
+			wantCode:    999,
 		},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
@@ -1073,30 +1077,85 @@ func TestParseIssueCredentialDataMessageAddsNoExtraSecret(t *testing.T) {
 			if !ok {
 				t.Fatalf("expected typed errs.Problem, got %T: %v", err, err)
 			}
-			// (a) The server msg survives into the message. The business-code
-			// path passes it through verbatim; the HTTP-status path reports
-			// "HTTP <status>: <body>" via the shared classifier, so assert
-			// containment rather than equality.
-			if !strings.Contains(p.Message, serverMsg) {
-				t.Fatalf("Message = %q, want it to contain server msg %q", p.Message, serverMsg)
+			if p.Category != tc.wantType || p.Subtype != tc.wantSubtype || p.Code != tc.wantCode {
+				t.Fatalf("problem metadata = %s/%s code=%d, want %s/%s code=%d",
+					p.Category, p.Subtype, p.Code, tc.wantType, tc.wantSubtype, tc.wantCode)
+			}
+			if !strings.Contains(p.Message, "permission denied") {
+				t.Fatalf("Message = %q, want it to retain non-secret server context", p.Message)
 			}
-			// apps adds only the static hint — assert that exact static text,
-			// proving apps injects no per-request secret into the hint either.
 			if p.Hint != gitCredentialIssueHint {
 				t.Fatalf("Hint = %q, want the static gitCredentialIssueHint", p.Hint)
 			}
-			// (b) Neither field may contain a token/secret-shaped string that
-			// apps could have added on top of the framework passthrough.
-			secret := regexp.MustCompile(`(?i)(pat-[a-z0-9]+|secret\s*[=:]\s*\S|token\s*[=:]\s*\S|password\s*[=:]\s*\S)`)
 			for field, val := range map[string]string{"Message": p.Message, "Hint": p.Hint} {
-				if secret.MatchString(val) {
-					t.Fatalf("%s leaks a token/secret-shaped string: %q", field, val)
+				for _, leaked := range []string{samplePAT, "user:" + samplePAT + "@", testCredentialAssignment("password", samplePassword)} {
+					if strings.Contains(val, leaked) {
+						t.Fatalf("%s leaks %q: %q", field, leaked, val)
+					}
+				}
+			}
+			for _, want := range []string{
+				testRedactedAssignment("token"),
+				testRedactedAssignment("password"),
+				"https://***@example.com/repo.git",
+			} {
+				if !strings.Contains(p.Message, want) {
+					t.Fatalf("Message missing %q after redaction: %q", want, p.Message)
 				}
 			}
 		})
 	}
 }
 
+func TestParseIssueCredentialDataRedactsSDKErrorPreservesCause(t *testing.T) {
+	samplePAT := testPublicSafeJoin("pat", "-sample")
+	cause := errors.New("transport failed with " + testCredentialAssignment("token", samplePAT))
+
+	_, err := parseIssueCredentialData(nil, cause, errclass.ClassifyContext{})
+	if err == nil {
+		t.Fatal("expected SDK-boundary error, got nil")
+	}
+	if !errors.Is(err, cause) {
+		t.Fatalf("error does not preserve cause: %v", err)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs.Problem, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryNetwork || p.Subtype != errs.SubtypeNetworkTransport {
+		t.Fatalf("problem metadata = %s/%s, want %s/%s",
+			p.Category, p.Subtype, errs.CategoryNetwork, errs.SubtypeNetworkTransport)
+	}
+	if strings.Contains(p.Message, samplePAT) {
+		t.Fatalf("message leaks credential value: %q", p.Message)
+	}
+	if want := testRedactedAssignment("token"); !strings.Contains(p.Message, want) {
+		t.Fatalf("message missing %q after redaction: %q", want, p.Message)
+	}
+}
+
+func TestRedactGitCredentialIssueErrorNil(t *testing.T) {
+	if err := redactGitCredentialIssueError(nil); err != nil {
+		t.Fatalf("redactGitCredentialIssueError(nil) = %v, want nil", err)
+	}
+}
+
+func testPublicSafeJoin(parts ...string) string {
+	return strings.Join(parts, "")
+}
+
+func testCredentialAssignment(key, value string) string {
+	return key + "=" + value
+}
+
+func testRedactedAssignment(key string) string {
+	return key + "=<redacted>"
+}
+
+func testCredentialURLWithUserInfo(hostPath, credential string) string {
+	return "https://" + "user:" + credential + "@" + hostPath
+}
+
 type errorReader struct{}
 
 func (errorReader) Read(p []byte) (int, error) {

shortcuts/apps/gitcred/gitcred_test.go

@@ -542,7 +542,15 @@ func TestManagerGetKeepsStdoutEmptyWhenRefreshFails(t *testing.T) {
 	if err := manager.Store.Upsert(*record); err != nil {
 		t.Fatalf("Upsert expired record returned error: %v", err)
 	}
-	issuer.err = errors.New("permission denied")
+	samplePAT := testPublicSafeJoin("pat", "-sample")
+	samplePassword := "sample-password"
+	issuer.err = errs.NewAPIError(
+		errs.SubtypeUnknown,
+		"permission denied: "+
+			testCredentialAssignment("token", samplePAT)+" "+
+			testCredentialAssignment("password", samplePassword)+" "+
+			testCredentialURLWithUserInfo("example.com/git/u/app.git", samplePAT),
+	).WithHint("retry without " + testCredentialAssignment("token", samplePAT)).WithLogID("log_x")
 
 	var out bytes.Buffer
 	var errOut bytes.Buffer
@@ -552,6 +560,22 @@ func TestManagerGetKeepsStdoutEmptyWhenRefreshFails(t *testing.T) {
 	if out.Len() != 0 {
 		t.Fatalf("stdout = %q, want empty", out.String())
 	}
+	stderr := errOut.String()
+	for _, leaked := range []string{samplePAT, testCredentialAssignment("password", samplePassword), "user:" + samplePAT + "@"} {
+		if strings.Contains(stderr, leaked) {
+			t.Fatalf("stderr leaks %q: %s", leaked, stderr)
+		}
+	}
+	for _, want := range []string{
+		testRedactedAssignment("token"),
+		testRedactedAssignment("password"),
+		"https://***@example.com/git/u/app.git",
+		"log_id=log_x",
+	} {
+		if !strings.Contains(stderr, want) {
+			t.Fatalf("stderr missing %q in %s", want, stderr)
+		}
+	}
 	if !bytes.Contains(errOut.Bytes(), []byte("lark-cli apps +git-credential-init --app-id app_xxx")) {
 		t.Fatalf("stderr missing actionable hint: %q", errOut.String())
 	}
@@ -1411,10 +1435,36 @@ func TestSecretStoreBranches(t *testing.T) {
 	if err := NewSecretStore(newFakeKeychain()).Set("", "pat"); err == nil {
 		t.Fatal("SecretStore.Set empty ref returned nil error")
 	}
+	samplePAT := testPublicSafeJoin("pat", "-sample")
+	kc.setErr = errors.New("keychain set failed with " + testCredentialAssignment("token", samplePAT))
+	var setCfgErr *errs.ConfigError
+	setErr := NewSecretStore(kc).Set("ref", samplePAT)
+	if setErr == nil || !errors.As(setErr, &setCfgErr) {
+		t.Fatalf("SecretStore.Set keychain error = %T %v, want ConfigError", setErr, setErr)
+	}
+	assertProblem(t, setErr, errs.CategoryConfig, errs.SubtypeInvalidConfig)
+	if setCfgErr.Message != "save local Git credential PAT to keychain failed" {
+		t.Fatalf("ConfigError message = %q, want static keychain failure", setCfgErr.Message)
+	}
+	if strings.Contains(setCfgErr.Message, samplePAT) {
+		t.Fatalf("ConfigError message leaks credential value: %q", setCfgErr.Message)
+	}
+	if !errors.Is(setCfgErr, kc.setErr) {
+		t.Fatalf("ConfigError does not preserve keychain cause")
+	}
+	kc.setErr = nil
 	kc.removeErr = errors.New("keychain remove failed")
 	var cfgErr *errs.ConfigError
-	if err := NewSecretStore(kc).Remove("ref"); err == nil || !errors.As(err, &cfgErr) {
-		t.Fatalf("SecretStore.Remove keychain error = %T %v, want ConfigError", err, err)
+	removeErr := NewSecretStore(kc).Remove("ref")
+	if removeErr == nil || !errors.As(removeErr, &cfgErr) {
+		t.Fatalf("SecretStore.Remove keychain error = %T %v, want ConfigError", removeErr, removeErr)
+	}
+	assertProblem(t, removeErr, errs.CategoryConfig, errs.SubtypeInvalidConfig)
+	if cfgErr.Message != "remove local Git credential PAT from keychain failed" {
+		t.Fatalf("ConfigError message = %q, want static keychain failure", cfgErr.Message)
+	}
+	if !errors.Is(cfgErr, kc.removeErr) {
+		t.Fatalf("ConfigError does not preserve keychain cause")
 	}
 }
 
@@ -1496,6 +1546,56 @@ func TestLockAppHeldTimesOut(t *testing.T) {
 	}
 }
 
+func TestManagerGetPreservesTypedLockAppError(t *testing.T) {
+	now := time.Unix(1780000000, 0)
+	store := NewStoreAt(filepath.Join(t.TempDir(), MetadataFilename))
+	kc := newFakeKeychain()
+	record := CredentialRecord{
+		AppID:        "app_xxx",
+		GitHTTPURL:   "https://example.com/git/u/app.git",
+		Profile:      testProfile().Profile,
+		ProfileAppID: testProfile().ProfileAppID,
+		UserOpenID:   testProfile().UserOpenID,
+		Username:     "x-access-token",
+		PATRef:       "ref",
+		Status:       StatusConfirmed,
+		ExpiresAt:    now.Add(-time.Minute).Unix(),
+		UpdatedAt:    now.Unix(),
+	}
+	if err := store.Upsert(record); err != nil {
+		t.Fatalf("Upsert returned error: %v", err)
+	}
+	kc.values[record.PATRef] = "old-pat"
+
+	blocker := filepath.Join(t.TempDir(), "config-blocker")
+	if err := os.WriteFile(blocker, []byte("file"), 0600); err != nil {
+		t.Fatalf("write config blocker: %v", err)
+	}
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", blocker)
+
+	manager := NewManager(store, NewSecretStore(kc), nil, &fakeIssuer{next: &IssuedCredential{
+		GitHTTPURL: record.GitHTTPURL,
+		PAT:        "new-pat",
+		ExpiresAt:  now.Add(24 * time.Hour).Unix(),
+	}})
+	manager.Now = func() time.Time { return now }
+	var out bytes.Buffer
+	var errOut bytes.Buffer
+	if err := manager.Get(context.Background(), CredentialInput{Protocol: "https", Host: "example.com", Path: "/git/u/app.git"}, testProfile(), &out, &errOut); err != nil {
+		t.Fatalf("Get returned error: %v", err)
+	}
+	if out.Len() != 0 {
+		t.Fatalf("stdout = %q, want empty", out.String())
+	}
+	stderr := errOut.String()
+	if !strings.Contains(stderr, "create Git credential lock dir") {
+		t.Fatalf("stderr = %q, want typed lock-dir setup error", stderr)
+	}
+	if strings.Contains(stderr, "acquire Git credential lock") {
+		t.Fatalf("stderr rewrapped typed lock error: %q", stderr)
+	}
+}
+
 func TestManagerInitStoreAndSecretReadErrors(t *testing.T) {
 	now := time.Unix(1780000000, 0)
 	path := filepath.Join(t.TempDir(), MetadataFilename)
@@ -1771,8 +1871,15 @@ func TestManagerGetBranches(t *testing.T) {
 	if err := manager.Get(context.Background(), CredentialInput{Protocol: "https", Host: "example.com", Path: "/git/u/app.git"}, testProfile(), &out, &errOut); err != nil {
 		t.Fatalf("Get keychain set error returned error: %v", err)
 	}
-	if !strings.Contains(errOut.String(), "keychain locked") {
-		t.Fatalf("stderr = %q, want keychain error", errOut.String())
+	stderr := errOut.String()
+	if !strings.Contains(stderr, "save local Git credential PAT to keychain failed") {
+		t.Fatalf("stderr = %q, want static keychain error", stderr)
+	}
+	if !strings.Contains(stderr, "lark-cli apps +git-credential-init") {
+		t.Fatalf("stderr = %q, want init retry hint", stderr)
+	}
+	if strings.Contains(stderr, "keychain locked") {
+		t.Fatalf("stderr leaks keychain cause: %q", stderr)
 	}
 
 	kc.setErr = nil
@@ -2165,6 +2272,189 @@ func TestNilManagerUsesTimeNow(t *testing.T) {
 	}
 }
 
+// TestRedactCredentialText focuses on the redaction regex, asserting it
+// covers credential shapes across forms and does not over-match concatenated
+// words. JSON-quoted forms are common in server-provided error bodies and must
+// be covered; concatenated words like mytoken must not be treated as token.
+func TestRedactCredentialText(t *testing.T) {
+	samplePAT := testPublicSafeJoin("pat", "-sample")
+	samplePassword := "sample-password"
+	sampleSecret := "sample-secret"
+	githubLikeToken := testPublicSafeJoin("gh", "p_") + strings.Repeat("x", 20)
+	cases := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "bare assignment",
+			in: "permission denied: " +
+				testCredentialAssignment("token", samplePAT) + " " +
+				testCredentialAssignment("password", samplePassword),
+			want: "permission denied: " +
+				testRedactedAssignment("token") + " " +
+				testRedactedAssignment("password"),
+		},
+		{
+			name: "json double-quoted value",
+			in: "body={" +
+				testDoubleQuotedAssignment("password", samplePassword) + "," +
+				testDoubleQuotedAssignment("token", samplePAT) +
+				"}",
+			want: "body={" +
+				testDoubleQuotedRedactedAssignment("password") + "," +
+				testDoubleQuotedRedactedAssignment("token") +
+				"}",
+		},
+		{
+			name: "json single-quoted value",
+			in:   "body={" + testSingleQuotedAssignment("secret", sampleSecret) + "}",
+			want: "body={" + testSingleQuotedRedactedAssignment("secret") + "}",
+		},
+		{
+			name: "colon separator with quoted value",
+			in:   testCredentialColon("token", `"`+samplePAT+`"`),
+			want: testRedactedColon("token"),
+		},
+		{
+			name: "url userinfo",
+			in:   "clone " + testCredentialURLWithUserInfo("example.com/repo.git", samplePAT),
+			want: "clone https://***@example.com/repo.git",
+		},
+		{
+			name: "bearer header",
+			in:   testAuthorizationBearer(githubLikeToken),
+			want: testRedactedAuthorizationBearer(),
+		},
+		{
+			name: "pat-like standalone",
+			in:   "issued " + samplePAT + " for app",
+			want: "issued <redacted> for app",
+		},
+		{
+			name: "concatenated key not redacted",
+			in:   testCredentialAssignment("mytoken", "abc123") + " " + testCredentialAssignment("secret_field", "see"),
+			want: testCredentialAssignment("mytoken", "abc123") + " " + testCredentialAssignment("secret_field", "see"),
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := RedactCredentialText(tc.in); got != tc.want {
+				t.Fatalf("RedactCredentialText(%q) = %q, want %q", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestSafeCredentialErrorMessageFallbacks(t *testing.T) {
+	if got := safeCredentialErrorMessage(nil); got != "" {
+		t.Fatalf("safeCredentialErrorMessage(nil) = %q, want empty", got)
+	}
+
+	if got := safeCredentialErrorMessage(&errs.ConfigError{Problem: errs.Problem{
+		Category: errs.CategoryConfig,
+		Subtype:  errs.SubtypeInvalidConfig,
+	}}); got != "config/invalid_config" {
+		t.Fatalf("safeCredentialErrorMessage typed fallback = %q, want config/invalid_config", got)
+	}
+
+	samplePAT := testPublicSafeJoin("pat", "-sample")
+	got := safeCredentialErrorMessage(errors.New("transport failed with " + testCredentialAssignment("token", samplePAT)))
+	if strings.Contains(got, samplePAT) {
+		t.Fatalf("safeCredentialErrorMessage leaks credential value: %q", got)
+	}
+	if want := testRedactedAssignment("token"); !strings.Contains(got, want) {
+		t.Fatalf("safeCredentialErrorMessage missing %q after redaction: %q", want, got)
+	}
+}
+
+func TestWriteCredentialErrorRedactsTypedMessageHint(t *testing.T) {
+	samplePAT := testPublicSafeJoin("pat", "-sample")
+	err := errs.NewInternalError(errs.SubtypeStorage, "save failed with %s", testCredentialAssignment("token", samplePAT)).
+		WithHint("retry without %s", testCredentialAssignment("password", samplePAT)).
+		WithLogID("log_x")
+
+	var buf bytes.Buffer
+	writeCredentialError(&buf, "Git credential refresh failed", err)
+	got := buf.String()
+	for _, leaked := range []string{samplePAT, testCredentialAssignment("token", samplePAT), testCredentialAssignment("password", samplePAT)} {
+		if strings.Contains(got, leaked) {
+			t.Fatalf("writeCredentialError leaks credential value %q in %q", leaked, got)
+		}
+	}
+	for _, want := range []string{
+		"Git credential refresh failed: save failed with " + testRedactedAssignment("token"),
+		"log_id=log_x",
+		"hint: retry without " + testRedactedAssignment("password"),
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("writeCredentialError output missing %q: %q", want, got)
+		}
+	}
+
+	writeCredentialError(nil, "ignored", err)
+	writeCredentialError(&buf, "ignored", nil)
+}
+
+func assertProblem(t *testing.T, err error, wantCategory errs.Category, wantSubtype errs.Subtype) {
+	t.Helper()
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs.Problem, got %T: %v", err, err)
+	}
+	if p.Category != wantCategory || p.Subtype != wantSubtype {
+		t.Fatalf("problem metadata = %s/%s, want %s/%s", p.Category, p.Subtype, wantCategory, wantSubtype)
+	}
+}
+
+func testPublicSafeJoin(parts ...string) string {
+	return strings.Join(parts, "")
+}
+
+func testCredentialAssignment(key, value string) string {
+	return key + "=" + value
+}
+
+func testRedactedAssignment(key string) string {
+	return key + "=<redacted>"
+}
+
+func testCredentialColon(key, value string) string {
+	return key + ": " + value
+}
+
+func testRedactedColon(key string) string {
+	return key + ": <redacted>"
+}
+
+func testDoubleQuotedAssignment(key, value string) string {
+	return `"` + key + `"` + ":" + `"` + value + `"`
+}
+
+func testDoubleQuotedRedactedAssignment(key string) string {
+	return `"` + key + `"` + ":<redacted>"
+}
+
+func testSingleQuotedAssignment(key, value string) string {
+	return `'` + key + `'` + ":" + `'` + value + `'`
+}
+
+func testSingleQuotedRedactedAssignment(key string) string {
+	return `'` + key + `'` + ":<redacted>"
+}
+
+func testCredentialURLWithUserInfo(hostPath, credential string) string {
+	return "https://" + "user:" + credential + "@" + hostPath
+}
+
+func testAuthorizationBearer(value string) string {
+	return "Authorization" + ": " + "Bearer " + value
+}
+
+func testRedactedAuthorizationBearer() string {
+	return "Authorization" + ": " + "Bearer <redacted>"
+}
+
 func testProfile() ProfileContext {
 	return ProfileContext{Profile: "default", ProfileAppID: "cli_xxx", UserOpenID: "ou_xxx"}
 }

shortcuts/apps/gitcred/helper.go

@@ -8,6 +8,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"regexp"
 	"strings"
 	"time"
 
@@ -27,6 +28,25 @@ type Manager struct {
 	Now       func() time.Time
 }
 
+// credentialKeys is the shared list of credential field names to redact; the
+// bare, double-quoted (JSON), and single-quoted forms all reuse it.
+const credentialKeys = `access_token|refresh_token|app_secret|token|pat|password|secret`
+
+var (
+	credentialURLUserinfoRE = regexp.MustCompile(`(?i)(https?://)[^/\s]+@`)
+	// credentialAssignmentRE matches credential key assignments, including JSON
+	// quoted forms. Capture group 1 is the key and separator; only the value is
+	// replaced with <redacted>. The key is one of three forms — double-quoted,
+	// single-quoted, or bare with a word boundary — so concatenated words like
+	// mytoken are not matched. Each form wraps the key list in (?:...) so the |
+	// alternation does not bind the quote/boundary to only the first and last key.
+	credentialAssignmentRE = regexp.MustCompile(
+		`(?i)((?:"(?:` + credentialKeys + `)"|'(?:` + credentialKeys + `)'|\b(?:` + credentialKeys + `)\b)\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)`,
+	)
+	credentialBearerRE  = regexp.MustCompile(`(?i)(authorization\s*:\s*bearer\s+)[^\s,;]+`)
+	credentialPATLikeRE = regexp.MustCompile(`(?i)\b(?:gh[pousr]_[A-Za-z0-9_]{20,}|pat-[A-Za-z0-9._-]+)\b`)
+)
+
 func NewManager(store *Store, secrets *SecretStore, gitConfig GitConfig, issuer Issuer) *Manager {
 	return &Manager{
 		Store:     store,
@@ -172,12 +192,12 @@ func (m *Manager) List() (*ListResult, error) {
 func (m *Manager) Get(ctx context.Context, input CredentialInput, current ProfileContext, out, errOut io.Writer) error {
 	url, err := NormalizeCredentialInput(input)
 	if err != nil {
-		fmt.Fprintf(errOut, "Git credential unavailable: %s\n", err)
+		writeCredentialError(errOut, "Git credential unavailable", err)
 		return nil
 	}
 	record, pat, ok, err := m.readConfirmed(url, current)
 	if err != nil {
-		fmt.Fprintf(errOut, "Git credential unavailable: %s\n", err)
+		writeCredentialError(errOut, "Git credential unavailable", err)
 		return nil
 	}
 	if !ok {
@@ -187,18 +207,28 @@ func (m *Manager) Get(ctx context.Context, input CredentialInput, current Profil
 		return writeGitCredential(out, record.Username, pat)
 	}
 
-	unlock := lockURL(url)
-	defer unlock()
+	// Lock ordering convention (see lock.go package comment): always acquire
+	// lockApp before lockURL. lockApp is a cross-process file lock with a
+	// timeout and possible setup failure; acquiring it first avoids holding an
+	// in-process mutex on the failure path, which would risk a deadlock.
 	unlockApp, err := lockApp(record.AppID)
 	if err != nil {
-		fmt.Fprintf(errOut, "Git credential refresh failed: acquire lock for %s: %s\n", record.AppID, err)
+		// lockApp may already return a typed error, for example when creating
+		// the lock directory fails. Preserve those classifications and only wrap
+		// raw lockfile errors to add app context.
+		if _, ok := errs.ProblemOf(err); !ok {
+			err = errs.NewInternalError(errs.SubtypeStorage, "acquire Git credential lock for %s: %v", record.AppID, err).WithCause(err)
+		}
+		writeCredentialError(errOut, "Git credential refresh failed", err)
 		return nil
 	}
 	defer unlockApp()
+	unlockURL := lockURL(url)
+	defer unlockURL()
 
 	record, pat, ok, err = m.readConfirmed(url, current)
 	if err != nil {
-		fmt.Fprintf(errOut, "Git credential unavailable: %s\n", err)
+		writeCredentialError(errOut, "Git credential unavailable", err)
 		return nil
 	}
 	if !ok {
@@ -213,16 +243,17 @@ func (m *Manager) Get(ctx context.Context, input CredentialInput, current Profil
 	}
 	issued, err := m.Issuer.Issue(ctx, record.AppID, current)
 	if err != nil {
-		fmt.Fprintf(errOut, "Git credential refresh failed: %s\nNext step: lark-cli apps +git-credential-init --app-id %s\n", err, record.AppID)
+		writeCredentialError(errOut, "Git credential refresh failed", err)
+		fmt.Fprintf(errOut, "Next step: lark-cli apps +git-credential-init --app-id %s\n", record.AppID)
 		return nil
 	}
 	issuedURL, urlErr := NormalizeGitHTTPURL(issued.GitHTTPURL)
 	if urlErr != nil {
-		fmt.Fprintf(errOut, "Git credential refresh failed: %s\n", urlErr)
+		writeCredentialError(errOut, "Git credential refresh failed", urlErr)
 		return nil
 	}
 	if err := validateIssuedCredential(record.AppID, issuedURL, issued, m.nowUnix()); err != nil {
-		fmt.Fprintf(errOut, "Git credential refresh failed: %s\n", err)
+		writeCredentialError(errOut, "Git credential refresh failed", err)
 		return nil
 	}
 	if issuedURL != url {
@@ -232,7 +263,7 @@ func (m *Manager) Get(ctx context.Context, input CredentialInput, current Profil
 	if issued.ExpiresAt < record.ExpiresAt {
 		latest, latestPAT, found, readErr := m.readConfirmed(url, current)
 		if readErr != nil {
-			fmt.Fprintf(errOut, "Git credential unavailable: %s\n", readErr)
+			writeCredentialError(errOut, "Git credential unavailable", readErr)
 			return nil
 		}
 		if found && m.usable(latest, latestPAT) {
@@ -247,17 +278,64 @@ func (m *Manager) Get(ctx context.Context, input CredentialInput, current Profil
 	record.Status = StatusConfirmed
 	oldPAT := pat
 	if err := m.Secrets.Set(record.PATRef, issued.PAT); err != nil {
-		fmt.Fprintf(errOut, "Git credential refresh failed: %s\n", err)
+		writeCredentialError(errOut, "Git credential refresh failed", err)
 		return nil
 	}
 	if err := m.Store.Upsert(record); err != nil {
 		_ = m.Secrets.Set(record.PATRef, oldPAT)
-		fmt.Fprintf(errOut, "Git credential refresh failed: %s\n", err)
+		writeCredentialError(errOut, "Git credential refresh failed", err)
 		return nil
 	}
 	return writeGitCredential(out, record.Username, issued.PAT)
 }
 
+func writeCredentialError(w io.Writer, prefix string, err error) {
+	if w == nil || err == nil {
+		return
+	}
+	fmt.Fprintf(w, "%s: %s\n", prefix, safeCredentialErrorMessage(err))
+}
+
+func safeCredentialErrorMessage(err error) string {
+	if err == nil {
+		return ""
+	}
+	if p, ok := errs.ProblemOf(err); ok {
+		message := RedactCredentialText(p.Message)
+		if p.LogID != "" {
+			if message != "" {
+				message += "; "
+			}
+			message += "log_id=" + p.LogID
+		}
+		if p.Hint != "" {
+			if message != "" {
+				message += "; "
+			}
+			message += "hint: " + RedactCredentialText(p.Hint)
+		}
+		if message != "" {
+			return message
+		}
+		if p.Category != "" || p.Subtype != "" {
+			return strings.Trim(strings.TrimSpace(string(p.Category)+"/"+string(p.Subtype)), "/")
+		}
+	}
+	return RedactCredentialText(err.Error())
+}
+
+// RedactCredentialText masks credential fragments that may appear in free
+// text, covering URL userinfo, Authorization bearer headers, credential
+// assignments including JSON-quoted forms, and PAT-shaped strings. Shared by
+// the gitcred and apps packages so the redaction logic does not fork.
+func RedactCredentialText(text string) string {
+	text = credentialURLUserinfoRE.ReplaceAllString(text, "${1}***@")
+	text = credentialBearerRE.ReplaceAllString(text, "${1}<redacted>")
+	text = credentialAssignmentRE.ReplaceAllString(text, "${1}<redacted>")
+	text = credentialPATLikeRE.ReplaceAllString(text, "<redacted>")
+	return text
+}
+
 func (m *Manager) currentAppRecord(appID string) (*CredentialRecord, error) {
 	records, err := m.Store.FindByAppID(appID, ProfileContext{})
 	if err != nil || len(records) == 0 {

shortcuts/apps/gitcred/keychain.go

@@ -42,7 +42,15 @@ func (s *SecretStore) Set(ref, pat string) error {
 			Message:  "keychain PAT reference is empty",
 		}}
 	}
-	return s.kc.Set(KeychainService, ref, pat)
+	if err := s.kc.Set(KeychainService, ref, pat); err != nil {
+		return &errs.ConfigError{Problem: errs.Problem{
+			Category: errs.CategoryConfig,
+			Subtype:  errs.SubtypeInvalidConfig,
+			Message:  "save local Git credential PAT to keychain failed",
+			Hint:     "make sure the system credential store is available, then retry lark-cli apps +git-credential-init",
+		}, Cause: err}
+	}
+	return nil
 }
 
 func (s *SecretStore) Remove(ref string) error {
@@ -64,7 +72,7 @@ func (s *SecretStore) Remove(ref string) error {
 		return &errs.ConfigError{Problem: errs.Problem{
 			Category: errs.CategoryConfig,
 			Subtype:  errs.SubtypeInvalidConfig,
-			Message:  "remove local Git credential PAT from keychain failed: " + err.Error(),
+			Message:  "remove local Git credential PAT from keychain failed",
 			Hint:     "make sure the system credential store is available, then retry lark-cli apps +git-credential-remove",
 		}, Cause: err}
 	}

shortcuts/apps/gitcred/lock.go

@@ -1,6 +1,24 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+// Package gitcred manages the lifecycle of app Git credentials.
+//
+// Lock ordering convention — read this before adding any new lock acquisition:
+//
+//	ALWAYS acquire lockApp BEFORE lockURL. Never invert this order.
+//
+// Rationale:
+//   - lockApp is a cross-process file lock with bounded timeout (2s) and a
+//     possible setup error; acquiring it first keeps the failure surface
+//     outside any in-process lock and avoids holding the in-process mutex
+//     while waiting on I/O / another process.
+//   - lockURL is an in-process sync.Mutex that never fails and blocks
+//     indefinitely; holding it while waiting on lockApp would risk
+//     deadlocking with a concurrent goroutine that held lockApp first.
+//
+// Paths that only manipulate per-app state (Init, Remove, Erase) only need
+// lockApp. Get() is the only path that touches per-URL state in addition to
+// per-app state, so it is the only caller that takes both locks.
 package gitcred
 
 import (
@@ -20,6 +38,11 @@ var urlLocks sync.Map
 
 var safeLockNameChars = regexp.MustCompile(`[^a-zA-Z0-9._-]`)
 
+// lockURL acquires an in-process, per-URL mutex. It never returns an error
+// and blocks until the mutex is available.
+//
+// Lock ordering: lockURL MUST NOT be held while calling lockApp. See package
+// comment for the full convention.
 func lockURL(url string) func() {
 	actual, _ := urlLocks.LoadOrStore(url, &sync.Mutex{})
 	mu := actual.(*sync.Mutex)
@@ -27,6 +50,12 @@ func lockURL(url string) func() {
 	return mu.Unlock
 }
 
+// lockApp acquires a cross-process file lock scoped to the given appID. It
+// returns an unlock function or an error if the lock directory cannot be
+// created or the lock cannot be acquired within the 2s timeout.
+//
+// Lock ordering: when both lockApp and lockURL are needed, lockApp must be
+// taken FIRST. See package comment for the full convention.
 func lockApp(appID string) (func(), error) {
 	dir := filepath.Join(core.GetConfigDir(), "locks")
 	if err := vfs.MkdirAll(dir, 0700); err != nil {

shortcuts/base/base_dryrun_ops_test.go

@@ -89,6 +89,18 @@ func TestDryRunFieldOps(t *testing.T) {
 	)
 	assertDryRunContains(t, dryRunFieldGet(ctx, rt), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/fields/fld_1")
 	assertDryRunContains(t, dryRunFieldCreate(ctx, rt), "POST /open-apis/base/v3/bases/app_x/tables/tbl_1/fields")
+
+	arrayRT := newBaseTestRuntime(
+		map[string]string{
+			"base-token": "app_x",
+			"table-id":   "tbl_1",
+			"json":       `[{"name":"A","type":"text"},{"name":"B","type":"text"}]`,
+		},
+		nil,
+		nil,
+	)
+	assertDryRunContains(t, dryRunFieldCreate(ctx, arrayRT), `"name":"A"`, `"name":"B"`)
+
 	assertDryRunContains(t, dryRunFieldUpdate(ctx, rt), "PUT /open-apis/base/v3/bases/app_x/tables/tbl_1/fields/fld_1")
 	assertDryRunContains(t, dryRunFieldDelete(ctx, rt), "DELETE /open-apis/base/v3/bases/app_x/tables/tbl_1/fields/fld_1")
 	assertDryRunContains(t, dryRunFieldSearchOptions(ctx, rt), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/fields/fld_1/options", "offset=3", "limit=30", "query=open")

shortcuts/base/base_execute_test.go

@@ -830,11 +830,6 @@ func TestBaseObjectJSONShortcutsRejectArrayInDryRun(t *testing.T) {
 		shortcut common.Shortcut
 		args     []string
 	}{
-		{
-			name:     "field create",
-			shortcut: BaseFieldCreate,
-			args:     []string{"+field-create", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `[]`, "--dry-run"},
-		},
 		{
 			name:     "field update",
 			shortcut: BaseFieldUpdate,
@@ -1102,6 +1097,54 @@ func TestBaseFieldExecuteCRUD(t *testing.T) {
 		}
 	})
 
+	t.Run("create array sequentially", func(t *testing.T) {
+		oldDelay := fieldCreateBatchDelay
+		fieldCreateBatchDelay = 0
+		t.Cleanup(func() { fieldCreateBatchDelay = oldDelay })
+
+		factory, stdout, reg := newExecuteFactory(t)
+		firstStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields",
+			BodyFilter: func(body []byte) bool {
+				return strings.Contains(string(body), `"name":"A"`)
+			},
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{"id": "fld_a", "name": "A", "type": "text"},
+			},
+		}
+		secondStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields",
+			BodyFilter: func(body []byte) bool {
+				return strings.Contains(string(body), `"name":"B"`)
+			},
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{"id": "fld_b", "name": "B", "type": "text"},
+			},
+		}
+		reg.Register(firstStub)
+		reg.Register(secondStub)
+
+		err := runShortcut(t, BaseFieldCreate, []string{"+field-create", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `[{"name":"A","type":"text"},{"name":"B","type":"text"}]`}, factory, stdout)
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		if data["created"] != true || data["total"] != float64(2) {
+			t.Fatalf("unexpected output: %#v", data)
+		}
+		fields, _ := data["fields"].([]interface{})
+		if len(fields) != 2 {
+			t.Fatalf("fields len=%d output=%#v", len(fields), data)
+		}
+		if !strings.Contains(string(firstStub.CapturedBody), `"name":"A"`) || !strings.Contains(string(secondStub.CapturedBody), `"name":"B"`) {
+			t.Fatalf("unexpected request bodies: %s / %s", firstStub.CapturedBody, secondStub.CapturedBody)
+		}
+	})
+
 	t.Run("delete", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{

shortcuts/base/base_shortcuts_test.go

@@ -1060,6 +1060,15 @@ func TestBaseFieldValidate(t *testing.T) {
 	if err := BaseFieldCreate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "json": "{"}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--json invalid JSON object") {
 		t.Fatalf("err=%v", err)
 	}
+	if err := BaseFieldCreate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "json": `[{"name":"a","type":"text"},{"name":"b","type":"text"}]`}, nil, nil)); err != nil {
+		t.Fatalf("array create validate err=%v", err)
+	}
+	if err := BaseFieldCreate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "json": `[{"name":"a","type":"text"},1]`}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--json item 2 must be an object") {
+		t.Fatalf("err=%v", err)
+	}
+	if err := BaseFieldCreate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "json": `[{"name":"a","type":"formula"}]`}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--i-have-read-guide is required") {
+		t.Fatalf("err=%v", err)
+	}
 	if err := BaseFieldCreate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "json": `{"name":"f1","type":"formula"}`}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--i-have-read-guide is required") {
 		t.Fatalf("err=%v", err)
 	}

shortcuts/base/field_ops.go

@@ -6,10 +6,13 @@ package base
 import (
 	"context"
 	"strings"
+	"time"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+var fieldCreateBatchDelay = time.Second
+
 func dryRunFieldList(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 	offset := runtime.Int("offset")
 	if offset < 0 {
@@ -33,12 +36,14 @@ func dryRunFieldGet(_ context.Context, runtime *common.RuntimeContext) *common.D
 
 func dryRunFieldCreate(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 	pc := newParseCtx(runtime)
-	body, _ := parseJSONObject(pc, runtime.Str("json"), "json")
-	return common.NewDryRunAPI().
-		POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/fields").
-		Body(body).
+	bodies, _ := parseFieldCreateBodies(pc, runtime.Str("json"))
+	dr := common.NewDryRunAPI().
 		Set("base_token", runtime.Str("base-token")).
 		Set("table_id", baseTableID(runtime))
+	for _, body := range bodies {
+		dr.POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/fields").Body(body)
+	}
+	return dr
 }
 
 func dryRunFieldUpdate(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -95,11 +100,16 @@ func validateFormulaLookupGuideAck(runtime *common.RuntimeContext, command strin
 }
 
 func validateFieldCreate(runtime *common.RuntimeContext) error {
-	body, err := validateFieldJSON(runtime)
+	bodies, err := parseFieldCreateBodies(newParseCtx(runtime), runtime.Str("json"))
 	if err != nil {
 		return err
 	}
-	return validateFormulaLookupGuideAck(runtime, "+field-create", body)
+	for _, body := range bodies {
+		if err := validateFormulaLookupGuideAck(runtime, "+field-create", body); err != nil {
+			return err
+		}
+	}
+	return nil
 }
 
 func validateFieldUpdate(runtime *common.RuntimeContext) error {
@@ -140,19 +150,40 @@ func executeFieldGet(runtime *common.RuntimeContext) error {
 }
 
 func executeFieldCreate(runtime *common.RuntimeContext) error {
-	pc := newParseCtx(runtime)
-	body, err := parseJSONObject(pc, runtime.Str("json"), "json")
+	bodies, err := parseFieldCreateBodies(newParseCtx(runtime), runtime.Str("json"))
 	if err != nil {
 		return err
 	}
-	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", runtime.Str("base-token"), "tables", baseTableID(runtime), "fields"), nil, body)
-	if err != nil {
-		return err
+	fields := make([]interface{}, 0, len(bodies))
+	for idx, body := range bodies {
+		if idx > 0 && fieldCreateBatchDelay > 0 {
+			time.Sleep(fieldCreateBatchDelay)
+		}
+		data, err := baseV3Call(runtime, "POST", baseV3Path("bases", runtime.Str("base-token"), "tables", baseTableID(runtime), "fields"), nil, body)
+		if err != nil {
+			return err
+		}
+		fields = append(fields, data)
 	}
-	runtime.Out(map[string]interface{}{"field": data, "created": true}, nil)
+	if len(fields) == 1 {
+		runtime.Out(map[string]interface{}{"field": fields[0], "created": true}, nil)
+		return nil
+	}
+	runtime.Out(map[string]interface{}{"fields": fields, "created": true, "total": len(fields)}, nil)
 	return nil
 }
 
+func parseFieldCreateBodies(pc *parseCtx, raw string) ([]map[string]interface{}, error) {
+	bodies, err := parseObjectList(pc, raw, "json")
+	if err != nil {
+		return nil, err
+	}
+	if len(bodies) == 0 {
+		return nil, baseFlagErrorf("--json must contain at least one field JSON object")
+	}
+	return bodies, nil
+}
+
 func executeFieldUpdate(runtime *common.RuntimeContext) error {
 	pc := newParseCtx(runtime)
 	baseToken := runtime.Str("base-token")

shortcuts/doc/docs_fetch_v2.go

@@ -14,6 +14,8 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+const docsFetchExtraParam = `{"enable_user_cite_reference_map":true}`
+
 // v2FetchFlags returns the flag definitions for the v2 (OpenAPI) fetch path.
 func v2FetchFlags() []common.Flag {
 	return []common.Flag{
@@ -88,7 +90,8 @@ func executeFetchV2(_ context.Context, runtime *common.RuntimeContext) error {
 
 func buildFetchBody(runtime *common.RuntimeContext) map[string]interface{} {
 	body := map[string]interface{}{
-		"format": effectiveFetchFormat(runtime),
+		"format":      effectiveFetchFormat(runtime),
+		"extra_param": docsFetchExtraParam,
 	}
 	if v := runtime.Int("revision-id"); v > 0 {
 		body["revision_id"] = v

shortcuts/doc/docs_fetch_v2_test.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"reflect"
 	"strings"
 	"testing"
@@ -487,6 +488,44 @@ func TestAddFetchDetailDowngradeWarningNoops(t *testing.T) {
 	}
 }
 
+func TestBuildFetchBodyIncludesFetchExtraParamByDefault(t *testing.T) {
+	t.Parallel()
+
+	runtime := newFetchBodyTestRuntime(context.Background())
+
+	body := buildFetchBody(runtime)
+	extraParam, ok := body["extra_param"].(string)
+	if !ok || extraParam == "" {
+		t.Fatalf("extra_param = %#v, want JSON string", body["extra_param"])
+	}
+	var got map[string]bool
+	if err := json.Unmarshal([]byte(extraParam), &got); err != nil {
+		t.Fatalf("decode extra_param %q: %v", extraParam, err)
+	}
+	if got["enable_user_cite_reference_map"] != true {
+		t.Fatalf("enable_user_cite_reference_map = %#v, want true in %#v", got["enable_user_cite_reference_map"], got)
+	}
+	if _, ok := got["return_html5_block_data"]; ok {
+		t.Fatalf("extra_param should not request html5 block data: %#v", got)
+	}
+	if _, ok := got["reference_map_mode"]; ok {
+		t.Fatalf("extra_param should not use legacy reference_map_mode: %#v", got)
+	}
+	if len(got) != 1 {
+		t.Fatalf("extra_param should only contain fetch reference_map toggle: %#v", got)
+	}
+}
+
+func TestDocsFetchV2ReferenceMapFlagIsNotAvailable(t *testing.T) {
+	t.Parallel()
+
+	for _, flag := range v2FetchFlags() {
+		if flag.Name == "reference-map" {
+			t.Fatal("fetch should not expose reference-map flag")
+		}
+	}
+}
+
 func TestDocsFetchDryRunDefaultsToV2Endpoint(t *testing.T) {
 	t.Parallel()
 
@@ -805,20 +844,48 @@ func TestDocsFetchRejectsLegacyFlags(t *testing.T) {
 
 func newFetchBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "+fetch"}
-	cmd.Flags().String("doc-format", "xml", "")
-	cmd.Flags().String("detail", "simple", "")
-	cmd.Flags().String("lang", "", "")
-	cmd.Flags().Int("revision-id", -1, "")
-	cmd.Flags().String("scope", "full", "")
-	cmd.Flags().String("start-block-id", "", "")
-	cmd.Flags().String("end-block-id", "", "")
-	cmd.Flags().String("keyword", "", "")
-	cmd.Flags().Int("context-before", 0, "")
-	cmd.Flags().Int("context-after", 0, "")
-	cmd.Flags().Int("max-depth", -1, "")
+	cmd.Flags().String("doc-format", fetchDefault("doc-format"), "")
+	cmd.Flags().String("detail", fetchDefault("detail"), "")
+	cmd.Flags().String("lang", fetchDefault("lang"), "")
+	cmd.Flags().Int("revision-id", fetchDefaultInt("revision-id"), "")
+	cmd.Flags().String("scope", fetchDefault("scope"), "")
+	cmd.Flags().String("start-block-id", fetchDefault("start-block-id"), "")
+	cmd.Flags().String("end-block-id", fetchDefault("end-block-id"), "")
+	cmd.Flags().String("keyword", fetchDefault("keyword"), "")
+	cmd.Flags().Int("context-before", fetchDefaultInt("context-before"), "")
+	cmd.Flags().Int("context-after", fetchDefaultInt("context-after"), "")
+	cmd.Flags().Int("max-depth", fetchDefaultInt("max-depth"), "")
 	return common.TestNewRuntimeContextWithCtx(ctx, cmd, nil)
 }
 
+// fetchDefault returns the declared default for a flag from the real
+// v2FetchFlags definition so tests don't hardcode a stale default.
+// It panics if the flag is not found, since a missing flag indicates
+// a test setup error rather than a runtime condition.
+func fetchDefault(name string) string {
+	for _, fl := range v2FetchFlags() {
+		if fl.Name == name {
+			return fl.Default
+		}
+	}
+	panic(fmt.Sprintf("fetchDefault: flag %q not found in v2FetchFlags", name))
+}
+
+// fetchDefaultInt returns the declared default for an int flag from
+// v2FetchFlags, parsed as an int. It panics if the flag is not found
+// or its default cannot be parsed as an int.
+func fetchDefaultInt(name string) int {
+	s := fetchDefault(name)
+	if s == "" {
+		return 0
+	}
+	var d int
+	if _, err := fmt.Sscanf(s, "%d", &d); err != nil {
+		panic(fmt.Sprintf("fetchDefaultInt: flag %q default %q is not an int", name, s))
+	}
+	return d
+}
+
 func mustSetFetchFlag(t *testing.T, runtime *common.RuntimeContext, name, value string) {
 	t.Helper()
 
@@ -833,17 +900,17 @@ func newFetchShortcutTestRuntime(t *testing.T, apiVersion string, setFlags map[s
 	cmd := &cobra.Command{Use: "+fetch"}
 	cmd.Flags().String("api-version", "", "")
 	cmd.Flags().String("doc", "doxcnFetchDryRun", "")
-	cmd.Flags().String("doc-format", "xml", "")
-	cmd.Flags().String("detail", "simple", "")
-	cmd.Flags().String("lang", "", "")
-	cmd.Flags().Int("revision-id", -1, "")
-	cmd.Flags().String("scope", "full", "")
-	cmd.Flags().String("start-block-id", "", "")
-	cmd.Flags().String("end-block-id", "", "")
-	cmd.Flags().String("keyword", "", "")
-	cmd.Flags().Int("context-before", 0, "")
-	cmd.Flags().Int("context-after", 0, "")
-	cmd.Flags().Int("max-depth", -1, "")
+	cmd.Flags().String("doc-format", fetchDefault("doc-format"), "")
+	cmd.Flags().String("detail", fetchDefault("detail"), "")
+	cmd.Flags().String("lang", fetchDefault("lang"), "")
+	cmd.Flags().Int("revision-id", fetchDefaultInt("revision-id"), "")
+	cmd.Flags().String("scope", fetchDefault("scope"), "")
+	cmd.Flags().String("start-block-id", fetchDefault("start-block-id"), "")
+	cmd.Flags().String("end-block-id", fetchDefault("end-block-id"), "")
+	cmd.Flags().String("keyword", fetchDefault("keyword"), "")
+	cmd.Flags().Int("context-before", fetchDefaultInt("context-before"), "")
+	cmd.Flags().Int("context-after", fetchDefaultInt("context-after"), "")
+	cmd.Flags().Int("max-depth", fetchDefaultInt("max-depth"), "")
 	cmd.Flags().String("offset", "", "")
 	cmd.Flags().String("limit", "", "")
 	if apiVersion != "" {
@@ -875,6 +942,7 @@ func newUpdateBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	cmd.Flags().String("command", "append", "")
 	cmd.Flags().Int("revision-id", 0, "")
 	cmd.Flags().String("content", "<p>hello</p>", "")
+	cmd.Flags().String("reference-map", "", "")
 	cmd.Flags().String("pattern", "", "")
 	cmd.Flags().String("block-id", "", "")
 	cmd.Flags().String("src-block-ids", "", "")

shortcuts/doc/docs_update_test.go

@@ -4,9 +4,11 @@ package doc
 
 import (
 	"context"
+	"errors"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
@@ -61,6 +63,116 @@ func TestDocsUpdateDryRunIgnoresAPIVersionCompatFlag(t *testing.T) {
 	}
 }
 
+func TestDocsUpdateV2ReferenceMapFlagIsPublicFileInput(t *testing.T) {
+	t.Parallel()
+
+	var flag common.Flag
+	for _, candidate := range v2UpdateFlags() {
+		if candidate.Name == "reference-map" {
+			flag = candidate
+			break
+		}
+	}
+	if flag.Name == "" {
+		t.Fatal("reference-map flag not found")
+	}
+	if flag.Hidden {
+		t.Fatal("reference-map flag should be public")
+	}
+	if flag.Type != "" {
+		t.Fatalf("reference-map flag Type = %q, want default string", flag.Type)
+	}
+	if !hasUpdateTestInput(flag, common.File) || !hasUpdateTestInput(flag, common.Stdin) {
+		t.Fatalf("reference-map Input = %#v, want file and stdin", flag.Input)
+	}
+	if flag.Desc != docsUpdateReferenceMapFlagDesc {
+		t.Fatalf("reference-map help = %q, want %q", flag.Desc, docsUpdateReferenceMapFlagDesc)
+	}
+}
+
+func TestBuildUpdateBodyIncludesReferenceMap(t *testing.T) {
+	t.Parallel()
+
+	runtime := newUpdateShortcutTestRuntime(t, "", map[string]string{
+		"command":       "append",
+		"content":       `<p><widget data-ref="r1"></widget></p>`,
+		"reference-map": `{"widget":{"r1":{"label":"widget-ref-value"}}}`,
+	})
+	body := buildUpdateBody(runtime)
+
+	refMap, ok := body["reference_map"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("reference_map = %#v, want object", body["reference_map"])
+	}
+	widget, _ := refMap["widget"].(map[string]interface{})
+	r1, _ := widget["r1"].(map[string]interface{})
+	if got := r1["label"]; got != "widget-ref-value" {
+		t.Fatalf("reference_map.widget.r1.label = %#v, want widget-ref-value; body=%#v", got, body)
+	}
+	if got, want := body["command"], "block_insert_after"; got != want {
+		t.Fatalf("command = %#v, want %q", got, want)
+	}
+	if got, want := body["block_id"], "-1"; got != want {
+		t.Fatalf("block_id = %#v, want %q", got, want)
+	}
+}
+
+func TestValidateUpdateV2RejectsInvalidReferenceMap(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		setFlags  map[string]string
+		wantCause bool
+	}{
+		{
+			name: "invalid json",
+			setFlags: map[string]string{
+				"reference-map": "{",
+			},
+			wantCause: true,
+		},
+		{
+			name: "empty",
+			setFlags: map[string]string{
+				"reference-map": "",
+			},
+		},
+		{
+			name: "without content",
+			setFlags: map[string]string{
+				"content":       "",
+				"reference-map": `{"widget":{"r1":{"label":"widget-ref-value"}}}`,
+			},
+		},
+		{
+			name: "unsupported command",
+			setFlags: map[string]string{
+				"command":       "block_move_after",
+				"block-id":      "blk_anchor",
+				"src-block-ids": "blk_src",
+				"reference-map": `{"widget":{"r1":{"label":"widget-ref-value"}}}`,
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newUpdateShortcutTestRuntime(t, "", tt.setFlags)
+			err := validateUpdateV2(context.Background(), runtime)
+			if err == nil {
+				t.Fatal("validateUpdateV2() succeeded, want error")
+			}
+			assertValidationContract(t, err, errs.SubtypeInvalidArgument, "--reference-map")
+			if tt.wantCause && errors.Unwrap(err) == nil {
+				t.Fatal("validateUpdateV2() error lost underlying JSON cause")
+			}
+		})
+	}
+}
+
 func TestDocsUpdateRejectsLegacyFlags(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -103,6 +215,15 @@ func TestDocsUpdateRejectsLegacyFlags(t *testing.T) {
 	}
 }
 
+func hasUpdateTestInput(flag common.Flag, input string) bool {
+	for _, candidate := range flag.Input {
+		if candidate == input {
+			return true
+		}
+	}
+	return false
+}
+
 func newUpdateShortcutTestRuntime(t *testing.T, apiVersion string, setFlags map[string]string) *common.RuntimeContext {
 	t.Helper()
 
@@ -113,6 +234,7 @@ func newUpdateShortcutTestRuntime(t *testing.T, apiVersion string, setFlags map[
 	cmd.Flags().String("command", "append", "")
 	cmd.Flags().Int("revision-id", -1, "")
 	cmd.Flags().String("content", "<p>hello</p>", "")
+	cmd.Flags().String("reference-map", "", "")
 	cmd.Flags().String("pattern", "", "")
 	cmd.Flags().String("block-id", "", "")
 	cmd.Flags().String("src-block-ids", "", "")

shortcuts/doc/docs_update_v2.go

@@ -5,7 +5,9 @@ package doc
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
+	"strings"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -22,12 +24,15 @@ var validCommandsV2 = map[string]bool{
 	"append":                  true,
 }
 
+const docsUpdateReferenceMapFlagDesc = "结构化 `reference_map` JSON object；当 `--content` 使用正文外部载荷 / 引用映射时与内容一起传给服务，支持直接 JSON、`@reference-map.json`（相对路径）或 `-` 从 stdin 读取。通常用于回写已有 `document.reference_map`。"
+
 // v2UpdateFlags returns the flag definitions for the v2 (OpenAPI) update path.
 func v2UpdateFlags() []common.Flag {
 	return []common.Flag{
 		{Name: "command", Desc: "operation; requirements: str_replace(--pattern), block_delete(--block-id, comma-separated for batch), block_insert_after/block_replace(--block-id,--content), block_copy_insert_after/block_move_after(--block-id,--src-block-ids), overwrite/append(--content)", Enum: validCommandsV2Keys()},
 		{Name: "doc-format", Desc: "content format for --content; xml is default for precise rich edits, markdown for user-provided Markdown or plain append/overwrite", Default: "xml", Enum: []string{"xml", "markdown"}},
 		{Name: "content", Desc: "replacement or inserted content; XML by default or Markdown when --doc-format markdown; empty with str_replace deletes match. " + docsContentSkillHelp + "; use --help for the latest command flags", Input: []string{common.File, common.Stdin}},
+		{Name: "reference-map", Desc: docsUpdateReferenceMapFlagDesc, Input: []string{common.File, common.Stdin}},
 		{Name: "pattern", Desc: "str_replace match pattern; XML mode is inline text, Markdown mode can match multiline text"},
 		{Name: "block-id", Desc: "target block ID(s) for block operations (comma-separated for batch delete); -1 means document end where supported"},
 		{Name: "src-block-ids", Desc: "comma-separated source block ids for block_copy_insert_after and block_move_after"},
@@ -54,6 +59,9 @@ func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --command %q, valid: str_replace | block_delete | block_insert_after | block_copy_insert_after | block_replace | block_move_after | overwrite | append", cmd).WithParam("--command")
 	}
 	content := runtime.Str("content")
+	if err := validateUpdateReferenceMap(runtime, cmd, content); err != nil {
+		return err
+	}
 	pattern := runtime.Str("pattern")
 	blockID := runtime.Str("block-id")
 	srcBlockIDs := runtime.Str("src-block-ids")
@@ -113,7 +121,7 @@ func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 func dryRunUpdateV2(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 	// Validate has already accepted --doc; parseDocumentRef cannot fail here.
 	ref, _ := parseDocumentRef(runtime.Str("doc"))
-	body := buildUpdateBody(runtime)
+	body, _ := buildUpdateBodyWithReferenceMap(runtime)
 	apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s", ref.Token)
 	return common.NewDryRunAPI().
 		PUT(apiPath).
@@ -126,7 +134,10 @@ func executeUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 	ref, _ := parseDocumentRef(runtime.Str("doc"))
 
 	apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s", ref.Token)
-	body := buildUpdateBody(runtime)
+	body, err := buildUpdateBodyWithReferenceMap(runtime)
+	if err != nil {
+		return err
+	}
 
 	data, err := doDocAPI(runtime, "PUT", apiPath, body)
 	if err != nil {
@@ -138,6 +149,24 @@ func executeUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 }
 
 func buildUpdateBody(runtime *common.RuntimeContext) map[string]interface{} {
+	body, _ := buildUpdateBodyWithReferenceMap(runtime)
+	return body
+}
+
+func buildUpdateBodyWithReferenceMap(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	body := buildUpdateBodyBase(runtime)
+	if !runtime.Changed("reference-map") {
+		return body, nil
+	}
+	refMap, err := parseUpdateReferenceMap(runtime.Str("reference-map"))
+	if err != nil {
+		return body, err
+	}
+	body["reference_map"] = refMap
+	return body, nil
+}
+
+func buildUpdateBodyBase(runtime *common.RuntimeContext) map[string]interface{} {
 	cmd := runtime.Str("command")
 
 	// append is a shorthand for block_insert_after with block_id "-1" (end of document)
@@ -169,3 +198,40 @@ func buildUpdateBody(runtime *common.RuntimeContext) map[string]interface{} {
 	injectDocsScene(runtime, body)
 	return body
 }
+
+func validateUpdateReferenceMap(runtime *common.RuntimeContext, command string, content string) error {
+	if !runtime.Changed("reference-map") {
+		return nil
+	}
+	if !updateCommandAcceptsReferenceMap(command) {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--reference-map is only supported with update commands that send --content").WithParam("--reference-map")
+	}
+	if content == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--reference-map requires --content that uses matching sidecar refs").WithParam("--reference-map")
+	}
+	_, err := parseUpdateReferenceMap(runtime.Str("reference-map"))
+	return err
+}
+
+func updateCommandAcceptsReferenceMap(command string) bool {
+	switch command {
+	case "str_replace", "block_insert_after", "block_replace", "overwrite", "append":
+		return true
+	default:
+		return false
+	}
+}
+
+func parseUpdateReferenceMap(raw string) (map[string]interface{}, error) {
+	if strings.TrimSpace(raw) == "" {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--reference-map must be a non-empty JSON object").WithParam("--reference-map")
+	}
+	var refMap map[string]interface{}
+	if err := json.Unmarshal([]byte(raw), &refMap); err != nil {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--reference-map must be a valid JSON object: %v", err).WithParam("--reference-map").WithCause(err)
+	}
+	if refMap == nil {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--reference-map must be a JSON object, got null").WithParam("--reference-map")
+	}
+	return refMap, nil
+}

shortcuts/drive/drive_export_test.go

@@ -162,6 +162,9 @@ func TestDriveExportMarkdownWritesFile(t *testing.T) {
 	if reqBody["format"] != "markdown" {
 		t.Fatalf("docs_ai fetch body format = %v, want %q", reqBody["format"], "markdown")
 	}
+	if _, ok := reqBody["extra_param"]; ok {
+		t.Fatalf("drive markdown export must not enable docs fetch extra_param: %#v", reqBody)
+	}
 
 	data, err := os.ReadFile(filepath.Join(tmpDir, "Weekly Notes.md"))
 	if err != nil {
@@ -213,6 +216,9 @@ func TestDriveExportMarkdownUsesProvidedFileName(t *testing.T) {
 	if reqBody["format"] != "markdown" {
 		t.Fatalf("docs_ai fetch body format = %v, want %q", reqBody["format"], "markdown")
 	}
+	if _, ok := reqBody["extra_param"]; ok {
+		t.Fatalf("drive markdown export must not enable docs fetch extra_param: %#v", reqBody)
+	}
 
 	data, err := os.ReadFile(filepath.Join(tmpDir, "custom-notes.md"))
 	if err != nil {
@@ -283,6 +289,9 @@ func TestDriveExportDryRunIncludesLocalFileNameMetadata(t *testing.T) {
 			if !strings.Contains(out, `"output_dir": "./exports"`) {
 				t.Fatalf("stdout missing output_dir metadata: %s", out)
 			}
+			if tt.name == "markdown" && strings.Contains(out, `"extra_param"`) {
+				t.Fatalf("markdown dry-run must not enable docs fetch extra_param: %s", out)
+			}
 		})
 	}
 }
@@ -333,6 +342,9 @@ func TestDriveExportMarkdownFallsBackToTokenWhenTitleLookupFails(t *testing.T) {
 	if reqBody["format"] != "markdown" {
 		t.Fatalf("docs_ai fetch body format = %v, want %q", reqBody["format"], "markdown")
 	}
+	if _, ok := reqBody["extra_param"]; ok {
+		t.Fatalf("drive markdown export must not enable docs fetch extra_param: %#v", reqBody)
+	}
 
 	data, err := os.ReadFile(filepath.Join(tmpDir, "docx123.md"))
 	if err != nil {

shortcuts/drive/drive_pull.go

@@ -37,11 +37,16 @@ const (
 )
 
 type drivePullItem struct {
-	RelPath   string `json:"rel_path"`
-	FileToken string `json:"file_token,omitempty"`
-	SourceID  string `json:"source_id,omitempty"`
-	Action    string `json:"action"`
-	Error     string `json:"error,omitempty"`
+	RelPath    string `json:"rel_path"`
+	FileToken  string `json:"file_token,omitempty"`
+	SourceID   string `json:"source_id,omitempty"`
+	Action     string `json:"action"`
+	Error      string `json:"error,omitempty"`
+	Phase      string `json:"phase,omitempty"`
+	ErrorClass string `json:"error_class,omitempty"`
+	Code       int    `json:"code,omitempty"`
+	Subtype    string `json:"subtype,omitempty"`
+	Retryable  *bool  `json:"retryable,omitempty"`
 }
 
 type drivePullTarget struct {
@@ -189,6 +194,9 @@ var DrivePull = common.Shortcut{
 		sort.Strings(downloadablePaths)
 
 		for _, rel := range downloadablePaths {
+			if drivePullHasTerminalFailure(items) {
+				break
+			}
 			targetFile := remoteFiles[rel]
 			downloadToken := targetFile.DownloadToken
 			itemFileToken := targetFile.ItemFileToken
@@ -204,13 +212,9 @@ var DrivePull = common.Shortcut{
 				// pre-existing file under --if-exists=skip silently
 				// hides the conflict. Surface as a failure.
 				if info.IsDir() {
-					items = append(items, drivePullItem{
-						RelPath:   rel,
-						FileToken: itemFileToken,
-						SourceID:  itemSourceID,
-						Action:    "failed",
-						Error:     fmt.Sprintf("local path is a directory, remote is a regular file: %s", target),
-					})
+					conflictErr := errs.NewValidationError(errs.SubtypeFailedPrecondition, "local path is a directory, remote is a regular file: %s", target)
+					item, _ := drivePullFailedItem(rel, itemFileToken, itemSourceID, "failed", "local", conflictErr)
+					items = append(items, item)
 					failed++
 					downloadFailed++
 					continue
@@ -223,9 +227,14 @@ var DrivePull = common.Shortcut{
 			}
 
 			if err := drivePullDownload(ctx, runtime, downloadToken, target, targetFile.ModifiedTime); err != nil {
-				items = append(items, drivePullItem{RelPath: rel, FileToken: itemFileToken, SourceID: itemSourceID, Action: "failed", Error: err.Error()})
+				item, terminal := drivePullFailedItem(rel, itemFileToken, itemSourceID, "failed", "download", err)
+				items = append(items, item)
 				failed++
 				downloadFailed++
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +pull after terminal %s failure: %v\n", item.Phase, err)
+					break
+				}
 				continue
 			}
 			items = append(items, drivePullItem{RelPath: rel, FileToken: itemFileToken, SourceID: itemSourceID, Action: "downloaded"})
@@ -251,7 +260,8 @@ var DrivePull = common.Shortcut{
 			for _, absPath := range localAbsPaths {
 				rel, relErr := filepath.Rel(safeRoot, absPath)
 				if relErr != nil {
-					items = append(items, drivePullItem{RelPath: absPath, Action: "delete_failed", Error: relErr.Error()})
+					item, _ := drivePullFailedItem(absPath, "", "", "delete_failed", "delete_local", relErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -271,7 +281,9 @@ var DrivePull = common.Shortcut{
 				// acceptable here. Shortcuts cannot import internal/vfs
 				// directly (depguard rule shortcuts-no-vfs).
 				if err := os.Remove(absPath); err != nil { //nolint:forbidigo // see comment above
-					items = append(items, drivePullItem{RelPath: rel, Action: "delete_failed", Error: err.Error()})
+					deleteErr := errs.NewInternalError(errs.SubtypeFileIO, "delete local %q: %s", rel, err).WithCause(err)
+					item, _ := drivePullFailedItem(rel, "", "", "delete_failed", "delete_local", deleteErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -286,6 +298,7 @@ var DrivePull = common.Shortcut{
 				"skipped":       skipped,
 				"failed":        failed,
 				"deleted_local": deletedLocal,
+				"aborted":       drivePullHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -317,6 +330,32 @@ var DrivePull = common.Shortcut{
 	},
 }
 
+func drivePullFailedItem(relPath, fileToken, sourceID, action, phase string, err error) (drivePullItem, bool) {
+	decision := driveClassifyBatchFailure(err)
+	item := drivePullItem{
+		RelPath:    relPath,
+		FileToken:  fileToken,
+		SourceID:   sourceID,
+		Action:     action,
+		Error:      err.Error(),
+		Phase:      phase,
+		ErrorClass: decision.Class,
+		Code:       decision.Code,
+		Subtype:    decision.Subtype,
+		Retryable:  driveBoolPtr(decision.Retryable),
+	}
+	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_pull_test.go

@@ -1032,6 +1032,66 @@ func TestDrivePullDownloadFailureSkipsDeleteLocalAndExitsNonZero(t *testing.T) {
 	}
 }
 
+func TestDrivePullAbortsAfterDownloadForbidden(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_a", "name": "a.txt", "type": "file"},
+					map[string]interface{}{"token": "tok_b", "name": "b.txt", "type": "file"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/files/tok_a/download",
+		Status:  http.StatusForbidden,
+		RawBody: []byte("forbidden"),
+	})
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	assertDrivePullPartialFailure(t, err)
+
+	summary, items := splitDrivePullStdout(t, stdout.Bytes())
+	if got := summary["aborted"]; got != true {
+		t.Fatalf("summary.aborted = %v, want true", got)
+	}
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", 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"] != "download" || item["error_class"] != "permission_denied" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(http.StatusForbidden) || item["retryable"] != false {
+		t.Fatalf("unexpected failure classification: %#v", item)
+	}
+	if _, statErr := os.Stat(filepath.Join("local", "b.txt")); !os.IsNotExist(statErr) {
+		t.Fatalf("b.txt should not be downloaded after terminal permission failure; stat err=%v", statErr)
+	}
+}
+
 // TestDrivePullDeleteLocalDoesNotEscapeViaSymlinkParentRef is the
 // regression for the "link/.." escape applied to --delete-local — the
 // most dangerous variant, since the bug would otherwise let the kernel

shortcuts/drive/drive_push.go

@@ -29,12 +29,25 @@ const (
 )
 
 type drivePushItem struct {
-	RelPath   string `json:"rel_path"`
-	FileToken string `json:"file_token,omitempty"`
-	Action    string `json:"action"`
-	Version   string `json:"version,omitempty"`
-	SizeBytes int64  `json:"size_bytes,omitempty"`
-	Error     string `json:"error,omitempty"`
+	RelPath    string `json:"rel_path"`
+	FileToken  string `json:"file_token,omitempty"`
+	Action     string `json:"action"`
+	Version    string `json:"version,omitempty"`
+	SizeBytes  int64  `json:"size_bytes,omitempty"`
+	Error      string `json:"error,omitempty"`
+	Phase      string `json:"phase,omitempty"`
+	ErrorClass string `json:"error_class,omitempty"`
+	Code       int    `json:"code,omitempty"`
+	Subtype    string `json:"subtype,omitempty"`
+	Retryable  *bool  `json:"retryable,omitempty"`
+}
+
+type driveBatchFailureDecision struct {
+	Class     string
+	Code      int
+	Subtype   string
+	Retryable bool
+	Terminal  bool
 }
 
 // DrivePush is a one-way, file-level mirror from a local directory onto a
@@ -248,9 +261,14 @@ var DrivePush = common.Shortcut{
 				continue
 			}
 			if _, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, relDir, folderCache); ensureErr != nil {
-				items = append(items, drivePushItem{RelPath: relDir, Action: "failed", Error: ensureErr.Error()})
+				item, terminal := drivePushFailedItem(relDir, "", "failed", "create_folder", 0, ensureErr)
+				items = append(items, item)
 				failed++
 				uploadFailed = true
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, ensureErr)
+					break
+				}
 				continue
 			}
 			items = append(items, drivePushItem{RelPath: relDir, FileToken: folderCache[relDir], Action: "folder_created"})
@@ -266,6 +284,9 @@ var DrivePush = common.Shortcut{
 
 		for _, rel := range localPaths {
 			localFile := localFiles[rel]
+			if uploadFailed && drivePushHasTerminalFailure(items) {
+				break
+			}
 
 			if entry, ok := remoteFiles[rel]; ok {
 				if drivePushShouldSkipExisting(localFile, entry, ifExists) {
@@ -275,9 +296,14 @@ var DrivePush = common.Shortcut{
 				}
 				parentToken, parentErr := drivePushEnsureParentToken(ctx, runtime, folderToken, rel, folderCache)
 				if parentErr != nil {
-					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "failed", SizeBytes: localFile.Size, Error: parentErr.Error()})
+					item, terminal := drivePushFailedItem(rel, entry.FileToken, "failed", "create_folder", localFile.Size, parentErr)
+					items = append(items, item)
 					failed++
 					uploadFailed = true
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, parentErr)
+						break
+					}
 					continue
 				}
 				token, version, upErr := drivePushUploadFile(ctx, runtime, localFile, entry.FileToken, parentToken)
@@ -301,9 +327,14 @@ var DrivePush = common.Shortcut{
 					if failedToken == "" {
 						failedToken = entry.FileToken
 					}
-					items = append(items, drivePushItem{RelPath: rel, FileToken: failedToken, Action: "failed", SizeBytes: localFile.Size, Error: upErr.Error()})
+					item, terminal := drivePushFailedItem(rel, failedToken, "failed", "upload", localFile.Size, upErr)
+					items = append(items, item)
 					failed++
 					uploadFailed = true
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, upErr)
+						break
+					}
 					continue
 				}
 				items = append(items, drivePushItem{RelPath: rel, FileToken: token, Action: "overwritten", Version: version, SizeBytes: localFile.Size})
@@ -314,16 +345,26 @@ var DrivePush = common.Shortcut{
 			parentRel := drivePushParentRel(rel)
 			parentToken, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, parentRel, folderCache)
 			if ensureErr != nil {
-				items = append(items, drivePushItem{RelPath: rel, Action: "failed", SizeBytes: localFile.Size, Error: ensureErr.Error()})
+				item, terminal := drivePushFailedItem(rel, "", "failed", "create_folder", localFile.Size, ensureErr)
+				items = append(items, item)
 				failed++
 				uploadFailed = true
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, ensureErr)
+					break
+				}
 				continue
 			}
 			token, _, upErr := drivePushUploadFile(ctx, runtime, localFile, "", parentToken)
 			if upErr != nil {
-				items = append(items, drivePushItem{RelPath: rel, Action: "failed", SizeBytes: localFile.Size, Error: upErr.Error()})
+				item, terminal := drivePushFailedItem(rel, "", "failed", "upload", localFile.Size, upErr)
+				items = append(items, item)
 				failed++
 				uploadFailed = true
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, upErr)
+					break
+				}
 				continue
 			}
 			items = append(items, drivePushItem{RelPath: rel, FileToken: token, Action: "uploaded", SizeBytes: localFile.Size})
@@ -350,7 +391,11 @@ var DrivePush = common.Shortcut{
 			}
 			sort.Strings(remoteRelPaths)
 
+			abortDelete := false
 			for _, rel := range remoteRelPaths {
+				if abortDelete {
+					break
+				}
 				keepToken := ""
 				if _, ok := localFiles[rel]; ok {
 					if chosen, ok := remoteFiles[rel]; ok {
@@ -362,8 +407,14 @@ var DrivePush = common.Shortcut{
 						continue
 					}
 					if err := drivePushDeleteFile(ctx, runtime, entry.FileToken); err != nil {
-						items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "delete_failed", Error: err.Error()})
+						item, terminal := drivePushFailedItem(rel, entry.FileToken, "delete_failed", "delete", 0, err)
+						items = append(items, item)
 						failed++
+						if terminal {
+							fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, err)
+							abortDelete = true
+							break
+						}
 						continue
 					}
 					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "deleted_remote"})
@@ -378,6 +429,7 @@ var DrivePush = common.Shortcut{
 				"skipped":        skipped,
 				"failed":         failed,
 				"deleted_remote": deletedRemote,
+				"aborted":        drivePushHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -507,6 +559,91 @@ func drivePushShouldSkipSmart(localFile drivePushLocalFile, remoteFile driveRemo
 	return cmp >= 0
 }
 
+func drivePushFailedItem(relPath, fileToken, action, phase string, sizeBytes int64, err error) (drivePushItem, bool) {
+	decision := driveClassifyBatchFailure(err)
+	item := drivePushItem{
+		RelPath:    relPath,
+		FileToken:  fileToken,
+		Action:     action,
+		SizeBytes:  sizeBytes,
+		Error:      err.Error(),
+		Phase:      phase,
+		ErrorClass: decision.Class,
+		Code:       decision.Code,
+		Subtype:    decision.Subtype,
+		Retryable:  driveBoolPtr(decision.Retryable),
+	}
+	return item, decision.Terminal
+}
+
+func driveBoolPtr(v bool) *bool {
+	return &v
+}
+
+func driveClassifyBatchFailure(err error) driveBatchFailureDecision {
+	decision := driveBatchFailureDecision{Class: "unknown", Retryable: errs.IsRetryable(err)}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		return decision
+	}
+	decision.Code = problem.Code
+	decision.Subtype = string(problem.Subtype)
+	decision.Retryable = problem.Retryable
+
+	switch {
+	case problem.Category == errs.CategoryAuthorization && problem.Code == 99991672:
+		decision.Class = "app_scope_missing"
+		decision.Terminal = true
+	case problem.Category == errs.CategoryAuthorization && problem.Code == 99991679:
+		decision.Class = "user_scope_missing"
+		decision.Terminal = true
+	case problem.Category == errs.CategoryAuthorization && problem.Subtype == errs.SubtypePermissionDenied:
+		decision.Class = "permission_denied"
+		decision.Terminal = true
+	case problem.Category == errs.CategoryNetwork && problem.Code == http.StatusForbidden:
+		decision.Class = "permission_denied"
+		decision.Terminal = true
+	case problem.Subtype == errs.SubtypeInvalidParameters || problem.Code == 1061002:
+		decision.Class = "invalid_api_parameters"
+		decision.Terminal = true
+	case problem.Subtype == errs.SubtypeRateLimit || problem.Code == 99991400:
+		decision.Class = "rate_limited"
+		decision.Terminal = true
+	case problem.Subtype == errs.SubtypeQuotaExceeded || problem.Code == 1061043:
+		decision.Class = "file_size_limit"
+	case problem.Code == 1062009:
+		decision.Class = "upload_size_mismatch"
+	case problem.Subtype == errs.SubtypeNotFound || problem.Code == 1061007:
+		decision.Class = "remote_not_found"
+	case problem.Subtype == errs.SubtypeServerError || problem.Code == 1061001 || problem.Code == 2200:
+		decision.Class = "server_error"
+		decision.Terminal = true
+	case problem.Subtype == errs.SubtypeFailedPrecondition:
+		decision.Class = "local_file_changed"
+	default:
+		decision.Class = string(problem.Subtype)
+	}
+	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 drivePushRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (map[string]driveRemoteEntry, map[string]driveRemoteEntry, map[string][]driveRemoteEntry, error) {
 	remoteFiles := make(map[string]driveRemoteEntry, len(entries))
 	remoteFolders := make(map[string]driveRemoteEntry, len(entries))
@@ -600,6 +737,12 @@ func drivePushEnsureParentToken(ctx context.Context, runtime *common.RuntimeCont
 // the three-step prepare/part/finish flow, which mirrors drive +upload's
 // existing multipart logic.
 func drivePushUploadFile(ctx context.Context, runtime *common.RuntimeContext, file drivePushLocalFile, existingToken, parentToken string) (string, string, error) {
+	if err := drivePushValidateUploadRequest(file, existingToken, parentToken); err != nil {
+		return "", "", err
+	}
+	if err := drivePushVerifyLocalSnapshot(runtime, file); err != nil {
+		return "", "", err
+	}
 	if file.Size > common.MaxDriveMediaUploadSinglePartSize {
 		token, err := drivePushUploadMultipart(ctx, runtime, file, existingToken, parentToken)
 		// Multipart finish does not return version on the existing
@@ -612,6 +755,44 @@ func drivePushUploadFile(ctx context.Context, runtime *common.RuntimeContext, fi
 	return drivePushUploadAll(ctx, runtime, file, existingToken, parentToken)
 }
 
+func drivePushValidateUploadRequest(file drivePushLocalFile, existingToken, parentToken string) error {
+	if strings.TrimSpace(file.FileName) == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot upload %q: file name is empty", file.RelPath)
+	}
+	if file.Size < 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot upload %q: file size is negative", file.RelPath)
+	}
+	if strings.TrimSpace(parentToken) == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot upload %q: parent folder token is empty", file.RelPath)
+	}
+	if err := validate.ResourceName(parentToken, "parent_node"); err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot upload %q: %s", file.RelPath, err)
+	}
+	if existingToken != "" {
+		if err := validate.ResourceName(existingToken, "file_token"); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot overwrite %q: %s", file.RelPath, err)
+		}
+	}
+	return nil
+}
+
+func drivePushVerifyLocalSnapshot(runtime *common.RuntimeContext, file drivePushLocalFile) error {
+	info, err := runtime.FileIO().Stat(file.OpenPath)
+	if err != nil {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "local file changed during push: %s is no longer readable: %v", file.RelPath, err).WithCause(err)
+	}
+	if !info.Mode().IsRegular() {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "local file changed during push: %s is no longer a regular file", file.RelPath)
+	}
+	if info.Size() != file.Size {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "local file changed during push: %s snapshot size no longer matches", file.RelPath)
+	}
+	if modTimer, ok := info.(interface{ ModTime() time.Time }); ok && !modTimer.ModTime().Equal(file.ModTime) {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "local file changed during push: %s snapshot modtime no longer matches", file.RelPath)
+	}
+	return nil
+}
+
 func drivePushUploadAll(_ context.Context, runtime *common.RuntimeContext, file drivePushLocalFile, existingToken, parentToken string) (string, string, error) {
 	f, err := runtime.FileIO().Open(file.OpenPath)
 	if err != nil {

shortcuts/drive/drive_push_test.go

@@ -5,8 +5,10 @@ package drive
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"io"
+	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
@@ -14,12 +16,14 @@ import (
 	"testing"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
 )
 
 // countingOpenProvider wraps a fileio.Provider and counts FileIO.Open
@@ -652,6 +656,82 @@ func TestDrivePushDeleteRemoteSkipsOnlineDocs(t *testing.T) {
 	}
 }
 
+func TestDrivePushDeleteRemoteAbortsAfterTerminalFailure(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_a", "name": "a.txt", "type": "file"},
+					map[string]interface{}{"token": "tok_b", "name": "b.txt", "type": "file"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/drive/v1/files/tok_a",
+		Body: map[string]interface{}{
+			"code": 1061004,
+			"msg":  "forbidden",
+		},
+	})
+	// No DELETE stub for tok_b: terminal delete failure must stop before it.
+
+	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("expected partial failure, got nil\nstdout: %s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) || pfErr.Code != output.ExitAPI {
+		t.Fatalf("expected ExitAPI *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 got := summary["deleted_remote"]; got != float64(0) {
+		t.Fatalf("summary.deleted_remote = %v, want 0", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["action"] != "delete_failed" || item["phase"] != "delete" || item["error_class"] != "permission_denied" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(1061004) || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	for _, item := range items {
+		if item["file_token"] == "tok_b" {
+			t.Fatalf("terminal delete failure must abort before tok_b, got items=%#v", items)
+		}
+	}
+}
+
 func TestDrivePushNewestOverwritesChosenDuplicateAndDeletesSibling(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 
@@ -886,21 +966,22 @@ func TestDrivePushOverwriteWithoutVersionFails(t *testing.T) {
 		t.Errorf("expected ExitAPI (%d), got code=%d", output.ExitAPI, pfErr.Code)
 	}
 
-	out := stdout.String()
-	// summary.failed should reflect the missing version; summary.uploaded
-	// should not pretend the overwrite succeeded.
-	if !strings.Contains(out, `"failed": 1`) {
-		t.Errorf("expected failed=1, got: %s", out)
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Errorf("summary.failed = %v, want 1", got)
 	}
-	if !strings.Contains(out, "no version") {
-		t.Errorf("expected error about missing version in items[].error, got: %s", out)
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	if got, _ := items[0]["error"].(string); !strings.Contains(got, "no version") {
+		t.Errorf("items[0].error = %q, want missing-version message", got)
 	}
 	// Pin the token-stability contract: the failed item must surface the
 	// token returned by upload_all (tok_keep_new), NOT the fallback
 	// entry.FileToken (tok_keep). Without this, a regression that always
 	// uses entry.FileToken on failure would slip through.
-	if !strings.Contains(out, `"file_token": "tok_keep_new"`) {
-		t.Errorf("expected failed item to surface upload_all's returned file_token (tok_keep_new), got: %s", out)
+	if got := items[0]["file_token"]; got != "tok_keep_new" {
+		t.Errorf("items[0].file_token = %v, want tok_keep_new", got)
 	}
 }
 
@@ -962,24 +1043,313 @@ func TestDrivePushOverwritePartialSuccessSurfacesReturnedToken(t *testing.T) {
 		t.Fatalf("expected ExitAPI from *output.PartialFailureError, got %T %v", err, err)
 	}
 
-	out := stdout.String()
 	// Partial failure reports an ok:false result envelope on stdout (not a
 	// misleading ok:true) while still carrying BOTH the succeeded and failed
 	// items — consistent with the pre-change payload. The failed side is
 	// asserted via "failed": 1 and the succeeded side via tok_keep_partial.
-	if !strings.Contains(out, `"ok": false`) {
-		t.Errorf("partial failure must emit an ok:false result envelope, got: %s", out)
+	envelope := decodeDrivePushStdout(t, stdout.Bytes())
+	if envelope.OK {
+		t.Fatalf("partial failure must emit ok=false; stdout=%s", stdout.String())
 	}
-	if !strings.Contains(out, `"failed": 1`) {
-		t.Errorf("expected failed=1, got: %s", out)
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Errorf("summary.failed = %v, want 1", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
 	}
 	// The freshly returned token must be the one in items[].file_token,
 	// not the stale entry.FileToken (tok_keep_old).
-	if !strings.Contains(out, `"file_token": "tok_keep_partial"`) {
-		t.Errorf("expected items[].file_token to surface upload_all's returned token (tok_keep_partial), got: %s", out)
+	if got := items[0]["file_token"]; got != "tok_keep_partial" {
+		t.Errorf("items[0].file_token = %v, want tok_keep_partial", got)
 	}
-	if strings.Contains(out, `"file_token": "tok_keep_old"`) {
-		t.Errorf("must NOT fall back to entry.FileToken when upload_all returned a token; got: %s", out)
+	if got := items[0]["file_token"]; got == "tok_keep_old" {
+		t.Errorf("must NOT fall back to entry.FileToken when upload_all returned a token; item=%#v", items[0])
+	}
+}
+
+func TestDrivePushAbortsAfterUploadParamsError(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": 1061002,
+			"msg":  "params error.",
+		},
+	})
+
+	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"] != "invalid_api_parameters" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(1061002) || item["subtype"] != "invalid_parameters" || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	for _, item := range items {
+		if item["rel_path"] == "b.txt" {
+			t.Fatalf("terminal upload params error must abort before b.txt, got items=%#v", items)
+		}
+	}
+}
+
+func TestDrivePushAbortsAfterCreateFolderMissingScope(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll(filepath.Join("local", "a"), 0o755); err != nil {
+		t.Fatalf("MkdirAll a: %v", err)
+	}
+	if err := os.MkdirAll(filepath.Join("local", "b"), 0o755); err != nil {
+		t.Fatalf("MkdirAll 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/create_folder",
+		Body: map[string]interface{}{
+			"code": 99991672,
+			"msg":  "Access denied. One of the following scopes is required: [drive:drive, space:folder:create].",
+		},
+	})
+
+	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" || item["phase"] != "create_folder" || item["error_class"] != "app_scope_missing" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(99991672) || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	for _, item := range items {
+		if item["rel_path"] == "b" {
+			t.Fatalf("missing folder-create scope must abort before b, got items=%#v", items)
+		}
+	}
+}
+
+func TestDrivePushDetectsLocalFileChangedBeforeUpload(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)
+	}
+	localPath := filepath.Join("local", "changing.txt")
+	if err := os.WriteFile(localPath, []byte("before"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		OnMatch: func(req *http.Request) {
+			if err := os.WriteFile(localPath, []byte("after-change"), 0o644); err != nil {
+				t.Fatalf("mutate local file: %v", err)
+			}
+		},
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
+		},
+	})
+	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 != false {
+		t.Fatalf("summary.aborted = %v, want false", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["error_class"] != "local_file_changed" || item["subtype"] != "failed_precondition" || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	if got, _ := item["error"].(string); !strings.Contains(got, "local file changed during push") {
+		t.Fatalf("items[0].error = %q, want local-change message", got)
+	}
+	if strings.Contains(stdout.String(), "httpmock: no stub") {
+		t.Fatalf("upload_all was called after local snapshot changed:\n%s", stdout.String())
+	}
+
+	problemErr := drivePushVerifyLocalSnapshot(common.TestNewRuntimeContext(&cobra.Command{Use: "drive +push"}, &core.CliConfig{}), drivePushLocalFile{
+		RelPath:  "missing.txt",
+		OpenPath: filepath.Join("local", "missing.txt"),
+		FileName: "missing.txt",
+		Size:     1,
+		ModTime:  time.Now(),
+	})
+	problem, ok := errs.ProblemOf(problemErr)
+	if !ok {
+		t.Fatalf("ProblemOf(snapshot error) ok=false, err=%T %v", problemErr, problemErr)
+	}
+	if problem.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("snapshot error subtype = %q, want %q", problem.Subtype, errs.SubtypeFailedPrecondition)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("snapshot error category = %q, want %q", problem.Category, errs.CategoryValidation)
+	}
+	if errors.Unwrap(problemErr) == nil {
+		t.Fatalf("snapshot error cause was not preserved")
+	}
+}
+
+func TestDrivePushDetectsSameSizeLocalFileChangedBeforeUpload(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)
+	}
+	localPath := filepath.Join("local", "changing.txt")
+	if err := os.WriteFile(localPath, []byte("before"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+	originalModTime := time.Unix(100, 0)
+	changedModTime := time.Unix(200, 0)
+	if err := os.Chtimes(localPath, originalModTime, originalModTime); err != nil {
+		t.Fatalf("Chtimes original: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		OnMatch: func(req *http.Request) {
+			if err := os.WriteFile(localPath, []byte("AFTER!"), 0o644); err != nil {
+				t.Fatalf("mutate local file: %v", err)
+			}
+			if err := os.Chtimes(localPath, changedModTime, changedModTime); err != nil {
+				t.Fatalf("Chtimes changed: %v", err)
+			}
+		},
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
+		},
+	})
+
+	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 len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["rel_path"] != "changing.txt" || item["error_class"] != "local_file_changed" || item["subtype"] != "failed_precondition" {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	if got, _ := item["error"].(string); !strings.Contains(got, "snapshot modtime no longer matches") {
+		t.Fatalf("items[0].error = %q, want modtime mismatch", got)
+	}
+	if strings.Contains(stdout.String(), "httpmock: no stub") {
+		t.Fatalf("upload_all was called after local snapshot changed:\n%s", stdout.String())
 	}
 }
 
@@ -1113,6 +1483,32 @@ func TestDrivePushExitsZeroOnCleanRun(t *testing.T) {
 	}
 }
 
+type drivePushStdoutEnvelope struct {
+	OK   bool `json:"ok"`
+	Data struct {
+		Summary map[string]interface{}   `json:"summary"`
+		Items   []map[string]interface{} `json:"items"`
+	} `json:"data"`
+}
+
+func decodeDrivePushStdout(t *testing.T, stdout []byte) drivePushStdoutEnvelope {
+	t.Helper()
+	var envelope drivePushStdoutEnvelope
+	if err := json.Unmarshal(stdout, &envelope); err != nil {
+		t.Fatalf("unmarshal stdout: %v\nraw=%s", err, string(stdout))
+	}
+	return envelope
+}
+
+func splitDrivePushStdout(t *testing.T, stdout []byte) (map[string]interface{}, []map[string]interface{}) {
+	t.Helper()
+	envelope := decodeDrivePushStdout(t, stdout)
+	if envelope.Data.Summary == nil {
+		t.Fatalf("stdout missing data.summary; raw=%s", string(stdout))
+	}
+	return envelope.Data.Summary, envelope.Data.Items
+}
+
 // TestDrivePushUploadsSiblingWhenRemoteSameNameIsNativeDoc pins the
 // behavior when a local regular file shares its rel_path with a Lark
 // native cloud document on Drive (sheet/docx/bitable/...).

shortcuts/drive/drive_search.go

@@ -72,7 +72,7 @@ var DriveSearch = common.Shortcut{
 	Description: "Search Lark docs, Wiki, and spreadsheet files with flat filters (Search v2: doc_wiki/search)",
 	Risk:        "read",
 	Scopes:      []string{"search:docs:read"},
-	AuthTypes:   []string{"user"},
+	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "query", Desc: "search keyword (may be empty to browse by filter only)"},

shortcuts/drive/drive_sync.go

@@ -25,12 +25,21 @@ const (
 	driveSyncOnConflictAsk        = "ask"
 )
 
+func driveSyncActionScopes() []string {
+	return []string{"drive:file:download", "drive:file:upload", "space:folder:create"}
+}
+
 type driveSyncItem struct {
-	RelPath   string `json:"rel_path"`
-	FileToken string `json:"file_token,omitempty"`
-	Action    string `json:"action"`
-	Direction string `json:"direction,omitempty"` // "pull" or "push"
-	Error     string `json:"error,omitempty"`
+	RelPath    string `json:"rel_path"`
+	FileToken  string `json:"file_token,omitempty"`
+	Action     string `json:"action"`
+	Direction  string `json:"direction,omitempty"` // "pull" or "push"
+	Error      string `json:"error,omitempty"`
+	Phase      string `json:"phase,omitempty"`
+	ErrorClass string `json:"error_class,omitempty"`
+	Code       int    `json:"code,omitempty"`
+	Subtype    string `json:"subtype,omitempty"`
+	Retryable  *bool  `json:"retryable,omitempty"`
 }
 
 // DriveSync performs a two-way sync between a local directory and a Drive
@@ -66,6 +75,7 @@ var DriveSync = common.Shortcut{
 		"Default --on-conflict=remote-wins pulls the remote version when both sides changed a file. Use local-wins to push instead, keep-both to rename and keep both copies, or ask for interactive resolution.",
 		"Pass --quick for faster best-effort diff detection using modified_time instead of SHA-256 hash (no remote file downloads needed during diffing).",
 		"Because +sync acts on the diff, --quick can still pull, overwrite, or rename files when timestamps differ even if file contents are actually unchanged.",
+		"Actual sync execution pre-flights download, upload, and folder-create scopes before listing or walking, so missing grants fail before any partial sync can start.",
 		"Only entries with type=file are synced; online docs (docx, sheet, bitable, mindnote, slides) and shortcuts are skipped.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -110,10 +120,8 @@ var DriveSync = common.Shortcut{
 			duplicateRemote = driveDuplicateRemoteFail
 		}
 		quick := runtime.Bool("quick")
-		if !quick {
-			if err := runtime.EnsureScopes([]string{"drive:file:download"}); err != nil {
-				return err
-			}
+		if err := runtime.EnsureScopes(driveSyncActionScopes()); err != nil {
+			return err
 		}
 
 		safeRoot, err := validate.SafeInputPath(localDir)
@@ -262,18 +270,6 @@ var DriveSync = common.Shortcut{
 		var pulled, pushed, skipped, failed int
 		items := make([]driveSyncItem, 0)
 
-		if quick && driveSyncNeedsDownloadScope(newRemote, modified, conflictResolutions) {
-			if err := runtime.EnsureScopes([]string{"drive:file:download"}); err != nil {
-				return err
-			}
-		}
-		plannedUploads := driveSyncPlannedUploadPaths(newLocal, modified, conflictResolutions)
-		if len(plannedUploads) > 0 {
-			if err := runtime.EnsureScopes([]string{"drive:file:upload"}); err != nil {
-				return err
-			}
-		}
-
 		// Build push infrastructure: local walk for push + remote views + folder cache.
 		folderCache := map[string]string{"": folderToken}
 		for relDir, entry := range remoteFolders {
@@ -287,20 +283,18 @@ var DriveSync = common.Shortcut{
 			return err
 		}
 
-		if driveSyncNeedsCreateScope(plannedUploads, localDirs, folderCache) {
-			if err := runtime.EnsureScopes([]string{"space:folder:create"}); err != nil {
-				return err
-			}
-		}
-
 		// Mirror local directory structure first (same as +push), so
 		// empty local directories are not silently dropped.
 		for _, relDir := range localDirs {
+			if driveSyncHasTerminalFailure(items) {
+				break
+			}
 			if _, alreadyRemote := folderCache[relDir]; alreadyRemote {
 				continue
 			}
 			if _, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, relDir, folderCache); ensureErr != nil {
-				items = append(items, driveSyncItem{RelPath: relDir, Action: "failed", Direction: "push", Error: ensureErr.Error()})
+				item, _ := driveSyncFailedItem(relDir, "", "failed", "push", "create_folder", ensureErr)
+				items = append(items, item)
 				failed++
 				continue
 			}
@@ -310,6 +304,9 @@ var DriveSync = common.Shortcut{
 
 		// 2a. Pull new_remote files.
 		for _, entry := range newRemote {
+			if driveSyncHasTerminalFailure(items) {
+				break
+			}
 			targetFile, ok := pullRemoteFiles[entry.RelPath]
 			if !ok {
 				// Non-file type (doc, shortcut, etc.) — skip.
@@ -317,8 +314,13 @@ var DriveSync = common.Shortcut{
 			}
 			target := filepath.Join(rootRelToCwd, entry.RelPath)
 			if err := drivePullDownload(ctx, runtime, targetFile.DownloadToken, target, targetFile.ModifiedTime); err != nil {
-				items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "failed", Direction: "pull", Error: err.Error()})
+				item, terminal := driveSyncFailedItem(entry.RelPath, entry.FileToken, "failed", "pull", "download", err)
+				items = append(items, item)
 				failed++
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, err)
+					break
+				}
 				continue
 			}
 			items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "downloaded", Direction: "pull"})
@@ -327,6 +329,9 @@ var DriveSync = common.Shortcut{
 
 		// 2b. Push new_local files.
 		for _, entry := range newLocal {
+			if driveSyncHasTerminalFailure(items) {
+				break
+			}
 			localFile, ok := pushLocalFiles[entry.RelPath]
 			if !ok {
 				items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "skipped", Direction: "push", Error: "local file disappeared during sync"})
@@ -336,14 +341,20 @@ var DriveSync = common.Shortcut{
 			parentRel := drivePushParentRel(entry.RelPath)
 			parentToken, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, parentRel, folderCache)
 			if ensureErr != nil {
-				items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "push", Error: ensureErr.Error()})
+				item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "push", "create_folder", ensureErr)
+				items = append(items, item)
 				failed++
 				continue
 			}
 			token, _, upErr := drivePushUploadFile(ctx, runtime, localFile, "", parentToken)
 			if upErr != nil {
-				items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "push", Error: upErr.Error()})
+				item, terminal := driveSyncFailedItem(entry.RelPath, token, "failed", "push", "upload", upErr)
+				items = append(items, item)
 				failed++
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, upErr)
+					break
+				}
 				continue
 			}
 			items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: token, Action: "uploaded", Direction: "push"})
@@ -352,6 +363,9 @@ var DriveSync = common.Shortcut{
 
 		// 2c. Resolve modified files by --on-conflict strategy.
 		for _, entry := range modified {
+			if driveSyncHasTerminalFailure(items) {
+				break
+			}
 			remoteFile := remoteFiles[entry.RelPath]
 			localFile, hasLocal := pushLocalFiles[entry.RelPath]
 			if !hasLocal {
@@ -379,8 +393,13 @@ var DriveSync = common.Shortcut{
 				}
 				target := filepath.Join(rootRelToCwd, entry.RelPath)
 				if err := drivePullDownload(ctx, runtime, targetFile.DownloadToken, target, targetFile.ModifiedTime); err != nil {
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "failed", Direction: "pull", Error: err.Error()})
+					item, terminal := driveSyncFailedItem(entry.RelPath, entry.FileToken, "failed", "pull", "download", err)
+					items = append(items, item)
 					failed++
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, err)
+						break
+					}
 					continue
 				}
 				items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "downloaded", Direction: "pull"})
@@ -396,7 +415,8 @@ var DriveSync = common.Shortcut{
 				}
 				parentToken, parentErr := drivePushEnsureFolder(ctx, runtime, folderToken, drivePushParentRel(entry.RelPath), folderCache)
 				if parentErr != nil {
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: existingToken, Action: "failed", Direction: "push", Error: parentErr.Error()})
+					item, _ := driveSyncFailedItem(entry.RelPath, existingToken, "failed", "push", "create_folder", parentErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -411,8 +431,13 @@ var DriveSync = common.Shortcut{
 					if failedToken == "" {
 						failedToken = existingToken
 					}
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: failedToken, Action: "failed", Direction: "push", Error: upErr.Error()})
+					item, terminal := driveSyncFailedItem(entry.RelPath, failedToken, "failed", "push", "upload", upErr)
+					items = append(items, item)
 					failed++
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, upErr)
+						break
+					}
 					continue
 				}
 				items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: token, Action: "overwritten", Direction: "push"})
@@ -433,7 +458,8 @@ var DriveSync = common.Shortcut{
 				}
 				suffixedRel, err := relPathWithUniqueFileTokenSuffix(entry.RelPath, remoteFile.FileToken, occupied)
 				if err != nil {
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "conflict", Error: err.Error()})
+					item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "conflict", "conflict", err)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -441,7 +467,9 @@ var DriveSync = common.Shortcut{
 				oldAbsPath := filepath.Join(safeRoot, filepath.FromSlash(entry.RelPath))
 				newAbsPath := filepath.Join(safeRoot, filepath.FromSlash(suffixedRel))
 				if err := os.Rename(oldAbsPath, newAbsPath); err != nil { //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); safeRoot is validated.
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "conflict", Error: fmt.Sprintf("rename local: %s", err)})
+					renameErr := errs.NewInternalError(errs.SubtypeFileIO, "rename local: %s", err).WithCause(err)
+					item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "conflict", "conflict", renameErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -454,19 +482,30 @@ var DriveSync = common.Shortcut{
 					if rollbackErr != nil {
 						errMsg += "; rollback failed: " + rollbackErr.Error()
 					}
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "pull", Error: errMsg})
+					notFoundErr := errs.NewAPIError(errs.SubtypeNotFound, "%s", errMsg)
+					item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "pull", "download", notFoundErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
 				target := filepath.Join(rootRelToCwd, entry.RelPath)
 				if err := drivePullDownload(ctx, runtime, targetFile.DownloadToken, target, targetFile.ModifiedTime); err != nil {
+					downloadErr := err
 					rollbackErr := driveSyncRollbackRenamedLocal(oldAbsPath, newAbsPath)
 					errMsg := err.Error()
 					if rollbackErr != nil {
 						errMsg += "; rollback failed: " + rollbackErr.Error()
 					}
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "failed", Direction: "pull", Error: errMsg})
+					item, terminal := driveSyncFailedItem(entry.RelPath, entry.FileToken, "failed", "pull", "download", downloadErr)
+					if rollbackErr != nil {
+						item.Error = errMsg
+					}
+					items = append(items, item)
 					failed++
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, downloadErr)
+						break
+					}
 					continue
 				}
 				items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "renamed_local", Direction: "conflict"})
@@ -492,6 +531,7 @@ var DriveSync = common.Shortcut{
 				"pushed":  pushed,
 				"skipped": skipped,
 				"failed":  failed,
+				"aborted": driveSyncHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -520,6 +560,32 @@ func driveSyncStatusRemoteFiles(pullRemoteFiles map[string]drivePullTarget) map[
 	return remoteFiles
 }
 
+func driveSyncFailedItem(relPath, fileToken, action, direction, phase string, err error) (driveSyncItem, bool) {
+	decision := driveClassifyBatchFailure(err)
+	item := driveSyncItem{
+		RelPath:    relPath,
+		FileToken:  fileToken,
+		Action:     action,
+		Direction:  direction,
+		Error:      err.Error(),
+		Phase:      phase,
+		ErrorClass: decision.Class,
+		Code:       decision.Code,
+		Subtype:    decision.Subtype,
+		Retryable:  driveBoolPtr(decision.Retryable),
+	}
+	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.
@@ -558,51 +624,6 @@ func driveSyncAskConflict(relPath string, runtime *common.RuntimeContext) (strin
 	}
 }
 
-func driveSyncNeedsDownloadScope(newRemote, modified []driveStatusEntry, conflictResolutions map[string]string) bool {
-	if len(newRemote) > 0 {
-		return true
-	}
-	for _, entry := range modified {
-		switch conflictResolutions[entry.RelPath] {
-		case driveSyncOnConflictRemoteWins, driveSyncOnConflictKeepBoth:
-			return true
-		}
-	}
-	return false
-}
-
-func driveSyncPlannedUploadPaths(newLocal, modified []driveStatusEntry, conflictResolutions map[string]string) []string {
-	planned := make([]string, 0, len(newLocal)+len(modified))
-	for _, entry := range newLocal {
-		planned = append(planned, entry.RelPath)
-	}
-	for _, entry := range modified {
-		if conflictResolutions[entry.RelPath] == driveSyncOnConflictLocalWins {
-			planned = append(planned, entry.RelPath)
-		}
-	}
-	return planned
-}
-
-func driveSyncNeedsCreateScope(uploadPaths []string, localDirs []string, folderCache map[string]string) bool {
-	for _, relPath := range uploadPaths {
-		parentRel := drivePushParentRel(relPath)
-		if parentRel == "" {
-			continue
-		}
-		if _, ok := folderCache[parentRel]; !ok {
-			return true
-		}
-	}
-	// Empty local directories also need create_folder if not already on Drive.
-	for _, relDir := range localDirs {
-		if _, ok := folderCache[relDir]; !ok {
-			return true
-		}
-	}
-	return false
-}
-
 func driveSyncRollbackRenamedLocal(oldAbsPath, newAbsPath string) error {
 	if info, err := os.Stat(oldAbsPath); err == nil { //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); safeRoot is validated.
 		if info.IsDir() {

shortcuts/drive/drive_sync_test.go

@@ -311,6 +311,71 @@ func TestDriveSyncRemoteWinsPullsNewRemoteAndPushesNewLocal(t *testing.T) {
 	}
 }
 
+func TestDriveSyncAbortsAfterNewRemoteDownloadForbidden(t *testing.T) {
+	syncTestConfig := &core.CliConfig{
+		AppID: "drive-sync-forbidden", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	}
+	f, stdout, _, reg := cmdutil.TestFactory(t, syncTestConfig)
+
+	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_a", "name": "a.txt", "type": "file", "modified_time": "100"},
+					map[string]interface{}{"token": "tok_b", "name": "b.txt", "type": "file", "modified_time": "100"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/files/tok_a/download",
+		Status:  http.StatusForbidden,
+		RawBody: []byte("forbidden"),
+	})
+
+	err := mountAndRunDrive(t, DriveSync, []string{
+		"+sync",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--quick",
+		"--as", "bot",
+	}, f, stdout)
+	assertDriveSyncPartialFailure(t, err)
+
+	summary := driveSyncStdoutSummary(t, stdout.Bytes())
+	if got := summary["aborted"]; got != true {
+		t.Fatalf("summary.aborted = %v, want true", got)
+	}
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	items := driveSyncStdoutItems(t, stdout.Bytes())
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item.RelPath != "a.txt" || item.Direction != "pull" || item.Phase != "download" || item.ErrorClass != "permission_denied" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item.Code != http.StatusForbidden || item.Retryable == nil || *item.Retryable {
+		t.Fatalf("unexpected failure classification: %#v", item)
+	}
+	if _, statErr := os.Stat(filepath.Join("local", "b.txt")); !os.IsNotExist(statErr) {
+		t.Fatalf("b.txt should not be downloaded after terminal permission failure; stat err=%v", statErr)
+	}
+}
+
 // TestDriveSyncLocalWinsPushesOverRemote verifies that --on-conflict=local-wins
 // pushes the local version over the remote file.
 func TestDriveSyncLocalWinsPushesOverRemote(t *testing.T) {
@@ -1552,11 +1617,11 @@ func TestDriveSyncDryRunQuickAcceptsMetadataOnlyScope(t *testing.T) {
 	}
 }
 
-func TestDriveSyncExactRemoteWinsAcceptsDownloadOnlyScope(t *testing.T) {
+func TestDriveSyncPreflightsActionScopesBeforeListing(t *testing.T) {
 	syncTestConfig := &core.CliConfig{
 		AppID: "drive-sync-download-scope-only", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	}
-	f, stdout, _, reg := cmdutil.TestFactory(t, syncTestConfig)
+	f, stdout, _, _ := cmdutil.TestFactory(t, syncTestConfig)
 	f.Credential = credential.NewCredentialProvider(nil, nil, &driveStatusScopedTokenResolver{scopes: "drive:drive.metadata:readonly drive:file:download"}, nil)
 
 	tmpDir := t.TempDir()
@@ -1568,34 +1633,6 @@ func TestDriveSyncExactRemoteWinsAcceptsDownloadOnlyScope(t *testing.T) {
 		t.Fatalf("WriteFile a.txt: %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_a", "name": "a.txt", "type": "file"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/tok_a/download",
-		Status:  200,
-		Body:    []byte("remote-a"),
-		Headers: http.Header{"Content-Type": []string{"application/octet-stream"}},
-	})
-	reg.Register(&httpmock.Stub{
-		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/tok_a/download",
-		Status:  200,
-		Body:    []byte("remote-a"),
-		Headers: http.Header{"Content-Type": []string{"application/octet-stream"}},
-	})
-
 	err := mountAndRunDrive(t, DriveSync, []string{
 		"+sync",
 		"--local-dir", "local",
@@ -1603,11 +1640,30 @@ func TestDriveSyncExactRemoteWinsAcceptsDownloadOnlyScope(t *testing.T) {
 		"--on-conflict", "remote-wins",
 		"--as", "bot",
 	}, f, stdout)
-	if err != nil {
-		t.Fatalf("expected exact remote-wins to succeed with download-only scope, got: %v\nstdout: %s", err, stdout.String())
+	if err == nil {
+		t.Fatalf("expected action-scope preflight to reject download-only scope\nstdout: %s", stdout.String())
 	}
-	if strings.Contains(strings.ToLower(stdout.String()), "missing_scope") {
-		t.Fatalf("should not surface missing_scope, got: %s", stdout.String())
+	var permErr *errs.PermissionError
+	if !errors.As(err, &permErr) {
+		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
+	}
+	if permErr.Subtype != errs.SubtypeMissingScope {
+		t.Fatalf("Subtype = %q, want %q", permErr.Subtype, errs.SubtypeMissingScope)
+	}
+	for _, scope := range []string{"drive:file:upload", "space:folder:create"} {
+		found := false
+		for _, missing := range permErr.MissingScopes {
+			if missing == scope {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Fatalf("MissingScopes = %v, want %s", permErr.MissingScopes, scope)
+		}
+	}
+	if strings.Contains(stdout.String(), "folder_root") {
+		t.Fatalf("preflight should fail before remote listing, got stdout: %s", stdout.String())
 	}
 }
 
@@ -2552,30 +2608,6 @@ func TestDriveSyncAskConflictRemoteShortForms(t *testing.T) {
 	}
 }
 
-// TestDriveSyncNeedsDownloadScopeReturnsFalseForLocalWinsOnly verifies
-// that driveSyncNeedsDownloadScope returns false when there are no
-// new_remote entries and all modified entries resolve to local-wins.
-func TestDriveSyncNeedsDownloadScopeReturnsFalseForLocalWinsOnly(t *testing.T) {
-	modified := []driveStatusEntry{{RelPath: "a.txt"}, {RelPath: "b.txt"}}
-	resolutions := map[string]string{"a.txt": driveSyncOnConflictLocalWins, "b.txt": driveSyncOnConflictLocalWins}
-
-	if driveSyncNeedsDownloadScope(nil, modified, resolutions) {
-		t.Fatal("expected false when no new_remote and all conflicts are local-wins")
-	}
-}
-
-// TestDriveSyncNeedsDownloadScopeReturnsTrueForKeepBoth verifies that
-// driveSyncNeedsDownloadScope returns true when a modified entry resolves
-// to keep-both (which requires pulling the remote version).
-func TestDriveSyncNeedsDownloadScopeReturnsTrueForKeepBoth(t *testing.T) {
-	modified := []driveStatusEntry{{RelPath: "a.txt"}}
-	resolutions := map[string]string{"a.txt": driveSyncOnConflictKeepBoth}
-
-	if !driveSyncNeedsDownloadScope(nil, modified, resolutions) {
-		t.Fatal("expected true when a conflict resolves to keep-both")
-	}
-}
-
 // TestDriveSyncRemoteWinsReportsMissingPullView verifies that when a
 // modified file's rel_path is not in pullRemoteFiles during the
 // remote-wins branch, a failed item is reported instead of a panic.
@@ -3083,3 +3115,19 @@ func driveSyncStdoutItems(t *testing.T, stdout []byte) []driveSyncItem {
 	}
 	return envelope.Data.Items
 }
+
+func driveSyncStdoutSummary(t *testing.T, stdout []byte) map[string]interface{} {
+	t.Helper()
+	var envelope struct {
+		Data struct {
+			Summary map[string]interface{} `json:"summary"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout, &envelope); err != nil {
+		t.Fatalf("unmarshal stdout: %v\nraw=%s", err, string(stdout))
+	}
+	if envelope.Data.Summary == nil {
+		t.Fatalf("stdout missing data.summary; raw=%s", string(stdout))
+	}
+	return envelope.Data.Summary
+}

shortcuts/drive/shortcuts_test.go

@@ -3,7 +3,10 @@
 
 package drive
 
-import "testing"
+import (
+	"reflect"
+	"testing"
+)
 
 // TestShortcutsIncludesExpectedCommands verifies the drive shortcut registry contains the expected commands.
 func TestShortcutsIncludesExpectedCommands(t *testing.T) {
@@ -58,3 +61,12 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		}
 	}
 }
+
+func TestDriveSearchSupportsUserAndBotIdentity(t *testing.T) {
+	t.Parallel()
+
+	want := []string{"user", "bot"}
+	if !reflect.DeepEqual(DriveSearch.AuthTypes, want) {
+		t.Fatalf("DriveSearch.AuthTypes = %v, want %v", DriveSearch.AuthTypes, want)
+	}
+}

shortcuts/sheets/backward/lark_sheets_float_images.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"fmt"
 	"path/filepath"
+	"strings"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
@@ -14,7 +15,25 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-const sheetImageParentType = "sheet_image"
+// Drive media parent_type values for uploading an image into a spreadsheet.
+// Native spreadsheets use "sheet_image"; imported "office" spreadsheets carry a
+// synthetic token prefixed with "fake_office_" and the backend requires
+// "office_sheet_file" instead.
+const (
+	sheetImageParentType      = "sheet_image"
+	officeSheetFileParentType = "office_sheet_file"
+	fakeOfficeTokenPrefix     = "fake_office_"
+)
+
+// sheetMediaParentType returns the drive media parent_type to use when
+// uploading an image whose parent_node is spreadsheetToken, mapping the
+// "fake_office_" imported-spreadsheet token prefix to "office_sheet_file".
+func sheetMediaParentType(spreadsheetToken string) string {
+	if strings.HasPrefix(spreadsheetToken, fakeOfficeTokenPrefix) {
+		return officeSheetFileParentType
+	}
+	return sheetImageParentType
+}
 
 var SheetMediaUpload = common.Shortcut{
 	Service:     "sheets",
@@ -49,7 +68,7 @@ var SheetMediaUpload = common.Shortcut{
 				POST("/open-apis/drive/v1/medias/upload_prepare").
 				Body(map[string]interface{}{
 					"file_name":   fileName,
-					"parent_type": sheetImageParentType,
+					"parent_type": sheetMediaParentType(parentNode),
 					"parent_node": parentNode,
 					"size":        "<file_size>",
 				}).
@@ -71,7 +90,7 @@ var SheetMediaUpload = common.Shortcut{
 			POST("/open-apis/drive/v1/medias/upload_all").
 			Body(map[string]interface{}{
 				"file_name":   fileName,
-				"parent_type": sheetImageParentType,
+				"parent_type": sheetMediaParentType(parentNode),
 				"parent_node": parentNode,
 				"size":        "<file_size>",
 				"file":        "@" + filePath,
@@ -141,13 +160,14 @@ func resolveSheetMediaUploadParent(runtime *common.RuntimeContext) (string, erro
 }
 
 func uploadSheetMediaFile(runtime *common.RuntimeContext, filePath, fileName string, fileSize int64, parentNode string) (string, error) {
+	parentType := sheetMediaParentType(parentNode)
 	if fileSize <= common.MaxDriveMediaUploadSinglePartSize {
 		pn := parentNode
 		return common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
 			FilePath:   filePath,
 			FileName:   fileName,
 			FileSize:   fileSize,
-			ParentType: sheetImageParentType,
+			ParentType: parentType,
 			ParentNode: &pn,
 		})
 	}
@@ -155,7 +175,7 @@ func uploadSheetMediaFile(runtime *common.RuntimeContext, filePath, fileName str
 		FilePath:   filePath,
 		FileName:   fileName,
 		FileSize:   fileSize,
-		ParentType: sheetImageParentType,
+		ParentType: parentType,
 		ParentNode: parentNode,
 	})
 }

shortcuts/sheets/backward/lark_sheets_sheet_media_upload_test.go

@@ -91,6 +91,39 @@ func TestSheetMediaUploadDryRunSmallFile(t *testing.T) {
 	}
 }
 
+// TestSheetMediaUploadDryRunSmallFileOfficeParentType pins the small-file
+// upload_all dry-run preview to the token-derived parent_type so the preview
+// agents/users will copy matches what Execute actually sends. Without this the
+// multipart dry-run branch could drift back to a hard-coded "sheet_image".
+func TestSheetMediaUploadDryRunSmallFileOfficeParentType(t *testing.T) {
+	dir := t.TempDir()
+	withSheetsTestWorkingDir(t, dir)
+	if err := os.WriteFile("img.png", []byte("png-bytes"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, sheetsTestConfig())
+	err := mountAndRunSheets(t, SheetMediaUpload, []string{
+		"+media-upload",
+		"--spreadsheet-token", "fake_office_abc123",
+		"--file", "img.png",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "/open-apis/drive/v1/medias/upload_all") {
+		t.Fatalf("dry-run should use upload_all for small file, got: %s", out)
+	}
+	if !strings.Contains(out, `"office_sheet_file"`) {
+		t.Fatalf("dry-run should include parent_type=office_sheet_file for fake_office_ token, got: %s", out)
+	}
+	if strings.Contains(out, `"sheet_image"`) {
+		t.Fatalf("dry-run must not emit sheet_image for fake_office_ token, got: %s", out)
+	}
+}
+
 func TestSheetMediaUploadDryRunURLExtractsToken(t *testing.T) {
 	dir := t.TempDir()
 	withSheetsTestWorkingDir(t, dir)
@@ -205,6 +238,47 @@ func TestSheetMediaUploadExecuteSuccess(t *testing.T) {
 	}
 }
 
+// TestSheetMediaUploadExecuteOfficeParentType confirms that an imported
+// "office" spreadsheet (token prefixed with "fake_office_") uploads with
+// parent_type=office_sheet_file instead of the native sheet_image.
+func TestSheetMediaUploadExecuteOfficeParentType(t *testing.T) {
+	dir := t.TempDir()
+	withSheetsTestWorkingDir(t, dir)
+	if err := os.WriteFile("img.png", []byte("png-bytes"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"file_token": "boxTOK123"},
+		},
+	}
+	reg.Register(stub)
+
+	const officeToken = "fake_office_abc123"
+	err := mountAndRunSheets(t, SheetMediaUpload, []string{
+		"+media-upload",
+		"--spreadsheet-token", officeToken,
+		"--file", "img.png",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeSheetsMultipartBody(t, stub)
+	if got := body.Fields["parent_type"]; got != officeSheetFileParentType {
+		t.Fatalf("parent_type = %q, want %q", got, officeSheetFileParentType)
+	}
+	if got := body.Fields["parent_node"]; got != officeToken {
+		t.Fatalf("parent_node = %q, want %q", got, officeToken)
+	}
+}
+
 func TestSheetMediaUploadFileNotFound(t *testing.T) {
 	dir := t.TempDir()
 	withSheetsTestWorkingDir(t, dir)

shortcuts/sheets/helpers.go

@@ -50,6 +50,42 @@ func sheetsInputStatError(flag string, err error) error {
 	return wrapped
 }
 
+// Drive media parent_type values for uploading an image into a spreadsheet.
+// Native spreadsheets use "sheet_image"; imported "office" spreadsheets carry a
+// synthetic token prefixed with "fake_office_" and the backend requires
+// "office_sheet_file" instead.
+const (
+	sheetImageParentType      = "sheet_image"
+	officeSheetFileParentType = "office_sheet_file"
+	fakeOfficeTokenPrefix     = "fake_office_"
+)
+
+// sheetMediaParentType returns the drive media parent_type to use when
+// uploading an image whose parent_node is spreadsheetToken. It is the single
+// place that maps a spreadsheet token to its parent_type so every image-upload
+// entry point (and its dry-run preview) stays consistent.
+func sheetMediaParentType(spreadsheetToken string) string {
+	if strings.HasPrefix(spreadsheetToken, fakeOfficeTokenPrefix) {
+		return officeSheetFileParentType
+	}
+	return sheetImageParentType
+}
+
+// uploadSheetImage uploads a local image file as a spreadsheet media asset and
+// returns its file_token. It funnels every sheets image upload through one
+// place so the parent_type selection (see sheetMediaParentType) is never
+// duplicated or forgotten at a call site. Callers are expected to have already
+// resolved spreadsheetToken (the upload's parent_node) and stat'd the file.
+func uploadSheetImage(runtime *common.RuntimeContext, spreadsheetToken, filePath, fileName string, fileSize int64) (string, error) {
+	return common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
+		FilePath:   filePath,
+		FileName:   fileName,
+		FileSize:   fileSize,
+		ParentType: sheetMediaParentType(spreadsheetToken),
+		ParentNode: &spreadsheetToken,
+	})
+}
+
 // spreadsheetRef classification: a --url / --spreadsheet-token input names a
 // spreadsheet either directly (a /sheets/ URL or raw token) or indirectly via a
 // wiki node that must be resolved to its backing spreadsheet at Execute time.

shortcuts/sheets/lark_sheet_object_crud.go

@@ -861,10 +861,10 @@ func newFloatImageWriteShortcut(command, description, op string, withIDFlag, isH
 				manageBody, _ := buildToolBody("manage_float_image_object", input)
 				return common.NewDryRunAPI().
 					POST("/open-apis/drive/v1/medias/upload_all").
-					Desc("upload local image to drive (parent_type=sheet_image)").
+					Desc("upload local image to drive (parent_type=" + sheetMediaParentType(token) + ")").
 					Body(map[string]interface{}{
 						"file_name":   floatImageName(runtime),
-						"parent_type": "sheet_image",
+						"parent_type": sheetMediaParentType(token),
 						"parent_node": token,
 						"size":        "<file_size>",
 						"file":        "@" + img,
@@ -918,13 +918,7 @@ func uploadFloatImageIfLocal(runtime *common.RuntimeContext, spreadsheetToken st
 	if err != nil {
 		return "", sheetsInputStatError("image", err)
 	}
-	return common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
-		FilePath:   img,
-		FileName:   floatImageName(runtime),
-		FileSize:   info.Size(),
-		ParentType: "sheet_image",
-		ParentNode: &spreadsheetToken,
-	})
+	return uploadSheetImage(runtime, spreadsheetToken, img, floatImageName(runtime), info.Size())
 }
 
 func floatImageWriteInput(runtime flagView, token, sheetID, sheetName, op string, withIDFlag bool, uploadedImageToken string) (map[string]interface{}, error) {

shortcuts/sheets/lark_sheet_write_cells.go

@@ -791,10 +791,10 @@ var CellsSetImage = common.Shortcut{
 		})
 		return common.NewDryRunAPI().
 			POST("/open-apis/drive/v1/medias/upload_all").
-			Desc("upload local image to drive (parent_type=sheet_image)").
+			Desc("upload local image to drive (parent_type=" + sheetMediaParentType(token) + ")").
 			Body(map[string]interface{}{
 				"file_name":   fileName,
-				"parent_type": "sheet_image",
+				"parent_type": sheetMediaParentType(token),
 				"parent_node": token,
 				"size":        "<file_size>",
 				"file":        "@" + imgPath,
@@ -832,13 +832,7 @@ var CellsSetImage = common.Shortcut{
 				WithParam("--image").
 				WithCause(err)
 		}
-		fileToken, err := common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
-			FilePath:   imgPath,
-			FileName:   fileName,
-			FileSize:   info.Size(),
-			ParentType: "sheet_image",
-			ParentNode: &token,
-		})
+		fileToken, err := uploadSheetImage(runtime, token, imgPath, fileName, info.Size())
 		if err != nil {
 			return err
 		}

shortcuts/sheets/lark_sheet_write_cells_test.go

@@ -496,6 +496,31 @@ func TestCellsSetImage_DryRun(t *testing.T) {
 	}
 }
 
+// TestCellsSetImage_DryRunOfficeParentType confirms that an imported "office"
+// spreadsheet (token prefixed with "fake_office_") uploads with
+// parent_type=office_sheet_file instead of the native sheet_image, and that the
+// preview's parent_node carries the same token.
+func TestCellsSetImage_DryRunOfficeParentType(t *testing.T) {
+	t.Parallel()
+	const officeToken = "fake_office_abc123"
+	calls := parseDryRunAPI(t, CellsSetImage, []string{
+		"--spreadsheet-token", officeToken, "--sheet-id", testSheetID,
+		"--range", "A1",
+		"--image", "./README.md", // any existing-shaped path; dry-run skips stat
+	})
+	if len(calls) != 2 {
+		t.Fatalf("api calls = %d, want 2 (upload + set_cell_range)", len(calls))
+	}
+	upload := calls[0].(map[string]interface{})
+	ubody, _ := upload["body"].(map[string]interface{})
+	if ubody["parent_type"] != officeSheetFileParentType {
+		t.Errorf("parent_type = %v, want %s", ubody["parent_type"], officeSheetFileParentType)
+	}
+	if ubody["parent_node"] != officeToken {
+		t.Errorf("parent_node = %v, want %s", ubody["parent_node"], officeToken)
+	}
+}
+
 func TestCellsSetImage_RangeMustBeSingleCell(t *testing.T) {
 	t.Parallel()
 	_, _, err := runShortcutCapturingErr(t, CellsSetImage, []string{

shortcuts/sheets/sheet_media_parent_type_test.go

@@ -0,0 +1,192 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"io/fs"
+	"mime"
+	"mime/multipart"
+	"os"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// TestSheetMediaParentType pins the token→parent_type mapping that every
+// sheets image-upload entry point funnels through. Native spreadsheet tokens
+// use "sheet_image"; imported "office" spreadsheets carry a "fake_office_"
+// synthetic token and must upload with "office_sheet_file".
+func TestSheetMediaParentType(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name  string
+		token string
+		want  string
+	}{
+		{"native spreadsheet token", "shtcnABC123", sheetImageParentType},
+		{"empty token", "", sheetImageParentType},
+		{"office imported token", "fake_office_abc123", officeSheetFileParentType},
+		{"office token, only the prefix", fakeOfficeTokenPrefix, officeSheetFileParentType},
+		{"prefix mid-string is not matched", "shtfake_office_abc", sheetImageParentType},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			if got := sheetMediaParentType(tc.token); got != tc.want {
+				t.Fatalf("sheetMediaParentType(%q) = %q, want %q", tc.token, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestUploadSheetImage_ParentType exercises the uploadSheetImage collector end
+// to end (the Execute path the dry-run tests don't reach), asserting the
+// parent_type that actually goes out on the wire is derived from the token: a
+// native spreadsheet uploads as sheet_image, an imported "office" spreadsheet
+// (fake_office_-prefixed token) as office_sheet_file.
+func TestUploadSheetImage_ParentType(t *testing.T) {
+	cases := []struct {
+		name           string
+		token          string
+		wantParentType string
+	}{
+		{"native spreadsheet", "shtcnTOK123", sheetImageParentType},
+		{"office imported spreadsheet", "fake_office_abc123", officeSheetFileParentType},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			runtime, reg := newSheetMediaTestRuntime(t)
+			// UploadDriveMediaAllTyped opens the file via the runtime's FileIO,
+			// which sandboxes paths to the current working directory; chdir to a
+			// temp dir and pass a relative name so the open is allowed.
+			cmdutil.TestChdir(t, t.TempDir())
+			if err := os.WriteFile("img.png", []byte("png-bytes"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+
+			stub := &httpmock.Stub{
+				Method: "POST",
+				URL:    "/open-apis/drive/v1/medias/upload_all",
+				Body: map[string]interface{}{
+					"code": 0,
+					"data": map[string]interface{}{"file_token": "boxTOK123"},
+				},
+			}
+			reg.Register(stub)
+
+			fileToken, err := uploadSheetImage(runtime, tc.token, "img.png", "img.png", 9)
+			if err != nil {
+				t.Fatalf("uploadSheetImage() error: %v", err)
+			}
+			if fileToken != "boxTOK123" {
+				t.Fatalf("file_token = %q, want boxTOK123", fileToken)
+			}
+
+			body := decodeSheetMediaMultipartBody(t, stub)
+			if got := body.Fields["parent_type"]; got != tc.wantParentType {
+				t.Fatalf("parent_type = %q, want %q", got, tc.wantParentType)
+			}
+			if got := body.Fields["parent_node"]; got != tc.token {
+				t.Fatalf("parent_node = %q, want %q", got, tc.token)
+			}
+			if got := body.Fields["file_name"]; got != "img.png" {
+				t.Fatalf("file_name = %q, want img.png", got)
+			}
+		})
+	}
+}
+
+// TestUploadSheetImage_FileOpenError confirms a missing image surfaces as a
+// typed validation error (category=validation, subtype=invalid_argument) with
+// the original os-level cause preserved for errors.Is, and proves the upload
+// endpoint is never hit. No httpmock stub is registered, so if uploadSheetImage
+// ever tried to POST upload_all the RoundTrip would return a
+// "no stub for POST ..." network failure — that would surface as a
+// non-validation category and fail the metadata assertion below. The
+// category=validation + fs.ErrNotExist cause therefore strictly implies the
+// short-circuit happened before the wire.
+func TestUploadSheetImage_FileOpenError(t *testing.T) {
+	runtime, _ := newSheetMediaTestRuntime(t)
+	cmdutil.TestChdir(t, t.TempDir())
+
+	_, err := uploadSheetImage(runtime, "shtcnTOK123", "missing.png", "missing.png", 1)
+	if err == nil {
+		t.Fatal("expected error for missing file, got nil")
+	}
+
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("err = %v; want typed problem carrier", err)
+	}
+	if p.Category != errs.CategoryValidation {
+		t.Fatalf("category = %q, want %q (non-validation implies the upload endpoint was reached)", p.Category, errs.CategoryValidation)
+	}
+	if p.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype = %q, want %q", p.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Fatalf("err = %v; want wrapped fs.ErrNotExist cause to be preserved", err)
+	}
+}
+
+func newSheetMediaTestRuntime(t *testing.T) (*common.RuntimeContext, *httpmock.Registry) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := &core.CliConfig{
+		AppID:     "test-sheets-media-" + t.Name(),
+		AppSecret: "test-secret",
+		Brand:     core.BrandFeishu,
+	}
+	f, _, _, reg := cmdutil.TestFactory(t, cfg)
+	runtime := common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "sheets"}, cfg, f, core.AsBot)
+	return runtime, reg
+}
+
+type sheetMediaCapturedMultipart struct {
+	Fields map[string]string
+	Files  map[string][]byte
+}
+
+func decodeSheetMediaMultipartBody(t *testing.T, stub *httpmock.Stub) sheetMediaCapturedMultipart {
+	t.Helper()
+	contentType := stub.CapturedHeaders.Get("Content-Type")
+	mediaType, params, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		t.Fatalf("parse content-type %q: %v", contentType, err)
+	}
+	if mediaType != "multipart/form-data" {
+		t.Fatalf("content type = %q, want multipart/form-data", mediaType)
+	}
+	reader := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
+	body := sheetMediaCapturedMultipart{Fields: map[string]string{}, Files: map[string][]byte{}}
+	for {
+		part, err := reader.NextPart()
+		if err != nil {
+			if err == io.EOF {
+				break
+			}
+			t.Fatalf("read multipart part: %v", err)
+		}
+		buf := new(bytes.Buffer)
+		if _, err := buf.ReadFrom(part); err != nil {
+			t.Fatalf("read multipart body for %q: %v", part.FormName(), err)
+		}
+		if part.FileName() != "" {
+			body.Files[part.FormName()] = buf.Bytes()
+			continue
+		}
+		body.Fields[part.FormName()] = buf.String()
+	}
+	return body
+}

shortcuts/slides/shortcuts.go

@@ -11,6 +11,11 @@ func Shortcuts() []common.Shortcut {
 		SlidesCreate,
 		SlidesMediaUpload,
 		SlidesReplaceSlide,
+		SlidesReplacePages,
 		SlidesScreenshot,
+		SlidesXMLGet,
+		SlidesHistoryList,
+		SlidesHistoryRevert,
+		SlidesHistoryRevertStatus,
 	}
 }

shortcuts/slides/slides_create.go

@@ -204,13 +204,11 @@ var SlidesCreate = common.Shortcut{
 			}
 		}
 
-		// Build the presentation URL locally from the token. The brand-standard
-		// host transparently redirects to the tenant domain (same fallback used by
-		// drive +upload / wiki +node-create). This avoids the prior best-effort
-		// drive metas/batch_query call, which needed an extra drive scope and 403'd
-		// for users who only authorized slides scopes — without ever blocking an
-		// otherwise-successful creation.
-		if url := common.BuildResourceURL(runtime.Config.Brand, "slides", presentationID); url != "" {
+		// Prefer the URL returned by presentation.create. Fall back to a local
+		// brand-standard URL only when the API omits it.
+		if url := common.GetString(data, "url"); url != "" {
+			result["url"] = url
+		} else if url := common.BuildResourceURL(runtime.Config.Brand, "slides", presentationID); url != "" {
 			result["url"] = url
 		}
 

shortcuts/slides/slides_create_test.go

@@ -34,6 +34,7 @@ func TestSlidesCreateBasic(t *testing.T) {
 			"data": map[string]interface{}{
 				"xml_presentation_id": "pres_abc123",
 				"revision_id":         1,
+				"url":                 "https://tenant.example.com/slides/pres_abc123",
 			},
 		},
 	})
@@ -54,10 +55,8 @@ func TestSlidesCreateBasic(t *testing.T) {
 	if data["title"] != "项目汇报" {
 		t.Fatalf("title = %v, want 项目汇报", data["title"])
 	}
-	// URL is built locally from the token (brand-standard host), not fetched from
-	// drive metas, so it is deterministic and needs no drive scope.
-	if data["url"] != "https://www.feishu.cn/slides/pres_abc123" {
-		t.Fatalf("url = %v, want https://www.feishu.cn/slides/pres_abc123", data["url"])
+	if data["url"] != "https://tenant.example.com/slides/pres_abc123" {
+		t.Fatalf("url = %v, want https://tenant.example.com/slides/pres_abc123", data["url"])
 	}
 	if _, ok := data["permission_grant"]; ok {
 		t.Fatalf("did not expect permission_grant in user mode")
@@ -647,12 +646,12 @@ func TestSlidesCreateWithoutSlidesUnchanged(t *testing.T) {
 	}
 }
 
-// TestSlidesCreateURLBuiltLocally verifies the presentation URL is constructed
-// locally from the token — no drive metas/batch_query call is made, so creation
-// works for users who only authorized slides scopes. The httpmock registry has no
-// batch_query stub registered; if the shortcut tried to call it, the request would
-// fail the test (unregistered stub), proving the URL is built without a drive call.
-func TestSlidesCreateURLBuiltLocally(t *testing.T) {
+// TestSlidesCreateURLFallsBackToLocalBuild verifies the presentation URL is
+// constructed locally from the token when presentation.create omits url — no
+// drive metas/batch_query call is made, so creation works for users who only
+// authorized slides scopes. The httpmock registry has no batch_query stub
+// registered; if the shortcut tried to call it, the request would fail the test.
+func TestSlidesCreateURLFallsBackToLocalBuild(t *testing.T) {
 	t.Parallel()
 
 	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
@@ -665,6 +664,7 @@ func TestSlidesCreateURLBuiltLocally(t *testing.T) {
 			"data": map[string]interface{}{
 				"xml_presentation_id": "pres_local_url",
 				"revision_id":         1,
+				"url":                 "",
 			},
 		},
 	})

shortcuts/slides/slides_history.go

@@ -0,0 +1,299 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type slidesHistoryListSpec struct {
+	PageSize  int
+	PageToken string
+}
+
+type slidesHistoryRevertSpec struct {
+	HistoryVersionID string
+	WaitTimeoutMs    int
+}
+
+type slidesHistoryRevertStatusSpec struct {
+	TaskID string
+}
+
+func parseSlidesHistoryPresentation(runtime *common.RuntimeContext) (presentationRef, error) {
+	ref, err := parsePresentationRef(runtime.Str("presentation"))
+	if err != nil {
+		return presentationRef{}, err
+	}
+	if ref.Kind == "wiki" {
+		if err := runtime.EnsureScopes([]string{"wiki:node:read"}); err != nil {
+			return presentationRef{}, err
+		}
+	}
+	return ref, nil
+}
+
+func validateSlidesHistoryPageSize(pageSize int) error {
+	if pageSize < 1 || pageSize > 20 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --page-size %d: must be between 1 and 20", pageSize).WithParam("--page-size")
+	}
+	return nil
+}
+
+func validateSlidesHistoryVersionID(historyVersionID string) error {
+	version, err := strconv.ParseInt(strings.TrimSpace(historyVersionID), 10, 64)
+	if err != nil || version <= 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--history-version-id must be a positive integer string returned by slides +history-list").WithParam("--history-version-id")
+	}
+	return nil
+}
+
+func validateSlidesHistoryWaitTimeout(timeoutMs int) error {
+	if timeoutMs < 0 || timeoutMs > 30000 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --wait-timeout-ms %d: must be between 0 and 30000", timeoutMs).WithParam("--wait-timeout-ms")
+	}
+	return nil
+}
+
+func slidesHistoryListParams(spec slidesHistoryListSpec) map[string]interface{} {
+	params := map[string]interface{}{
+		"page_size": spec.PageSize,
+	}
+	if spec.PageToken != "" {
+		params["page_token"] = spec.PageToken
+	}
+	return params
+}
+
+func slidesHistoryRevertBody(spec slidesHistoryRevertSpec) map[string]interface{} {
+	return map[string]interface{}{
+		"history_version_id": spec.HistoryVersionID,
+		"wait_timeout_ms":    spec.WaitTimeoutMs,
+	}
+}
+
+func slidesHistoryStatusParams(spec slidesHistoryRevertStatusSpec) map[string]interface{} {
+	return map[string]interface{}{
+		"task_id": spec.TaskID,
+	}
+}
+
+func slidesHistoryAPIPath(presentationID, suffix string) string {
+	return fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/%s", validate.EncodePathSegment(presentationID), suffix)
+}
+
+func newSlidesHistoryDryRun(ref presentationRef, desc string) (*common.DryRunAPI, string) {
+	dry := common.NewDryRunAPI()
+	presentationID := ref.Token
+	if ref.Kind == "wiki" {
+		presentationID = "<resolved_slides_token>"
+		dry.Desc("2-step orchestration: resolve wiki then " + desc).
+			GET("/open-apis/wiki/v2/spaces/get_node").
+			Desc("[1] Resolve wiki node to slides presentation").
+			Params(map[string]interface{}{"token": ref.Token})
+	} else {
+		dry.Desc("OpenAPI: " + desc)
+	}
+	return dry, presentationID
+}
+
+// SlidesHistoryList lists history versions of a Slides XML presentation.
+var SlidesHistoryList = common.Shortcut{
+	Service:           "slides",
+	Command:           "+history-list",
+	Description:       "List Slides presentation history versions",
+	Risk:              "read",
+	Scopes:            []string{"slides:presentation:read"},
+	ConditionalScopes: []string{"wiki:node:read"},
+	AuthTypes:         []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "history entries to return, range 1-20"},
+		{Name: "page-token", Desc: "pagination token from the previous page's page_token"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseSlidesHistoryPresentation(runtime); err != nil {
+			return err
+		}
+		return validateSlidesHistoryPageSize(runtime.Int("page-size"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		spec := slidesHistoryListSpec{
+			PageSize:  runtime.Int("page-size"),
+			PageToken: strings.TrimSpace(runtime.Str("page-token")),
+		}
+		dry, presentationID := newSlidesHistoryDryRun(ref, "list Slides history versions")
+		return dry.
+			GET(slidesHistoryAPIPath(presentationID, "histories")).
+			Params(slidesHistoryListParams(spec)).
+			Set("xml_presentation_id", presentationID)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		presentationID, err := resolvePresentationID(runtime, ref)
+		if err != nil {
+			return err
+		}
+		spec := slidesHistoryListSpec{
+			PageSize:  runtime.Int("page-size"),
+			PageToken: strings.TrimSpace(runtime.Str("page-token")),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodGet,
+			slidesHistoryAPIPath(presentationID, "histories"),
+			slidesHistoryListParams(spec),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}
+
+// SlidesHistoryRevert reverts a Slides XML presentation to a history version.
+var SlidesHistoryRevert = common.Shortcut{
+	Service:           "slides",
+	Command:           "+history-revert",
+	Description:       "Revert a Slides presentation to a historical version",
+	Risk:              "write",
+	Scopes:            []string{"slides:presentation:update", "slides:presentation:write_only"},
+	ConditionalScopes: []string{"wiki:node:read"},
+	AuthTypes:         []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
+		{Name: "history-version-id", Desc: "history_version_id from slides +history-list to revert to", Required: true},
+		{Name: "wait-timeout-ms", Type: "int", Default: "30000", Desc: "milliseconds to wait for revert completion before returning, range 0-30000"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseSlidesHistoryPresentation(runtime); err != nil {
+			return err
+		}
+		if err := validateSlidesHistoryVersionID(runtime.Str("history-version-id")); err != nil {
+			return err
+		}
+		return validateSlidesHistoryWaitTimeout(runtime.Int("wait-timeout-ms"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		spec := slidesHistoryRevertSpec{
+			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
+			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
+		}
+		dry, presentationID := newSlidesHistoryDryRun(ref, "revert Slides history")
+		return dry.
+			POST(slidesHistoryAPIPath(presentationID, "history/revert")).
+			Body(slidesHistoryRevertBody(spec)).
+			Set("xml_presentation_id", presentationID)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		presentationID, err := resolvePresentationID(runtime, ref)
+		if err != nil {
+			return err
+		}
+		spec := slidesHistoryRevertSpec{
+			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
+			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodPost,
+			slidesHistoryAPIPath(presentationID, "history/revert"),
+			nil,
+			slidesHistoryRevertBody(spec),
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}
+
+// SlidesHistoryRevertStatus gets the status of a Slides history revert task.
+var SlidesHistoryRevertStatus = common.Shortcut{
+	Service:           "slides",
+	Command:           "+history-revert-status",
+	Description:       "Get Slides history revert task status",
+	Risk:              "read",
+	Scopes:            []string{"slides:presentation:read"},
+	ConditionalScopes: []string{"wiki:node:read"},
+	AuthTypes:         []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
+		{Name: "task-id", Desc: "task_id returned by slides +history-revert", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseSlidesHistoryPresentation(runtime); err != nil {
+			return err
+		}
+		if strings.TrimSpace(runtime.Str("task-id")) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--task-id is required").WithParam("--task-id")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		spec := slidesHistoryRevertStatusSpec{
+			TaskID: strings.TrimSpace(runtime.Str("task-id")),
+		}
+		dry, presentationID := newSlidesHistoryDryRun(ref, "get Slides history revert status")
+		return dry.
+			GET(slidesHistoryAPIPath(presentationID, "history/revert_status")).
+			Params(slidesHistoryStatusParams(spec)).
+			Set("xml_presentation_id", presentationID)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		presentationID, err := resolvePresentationID(runtime, ref)
+		if err != nil {
+			return err
+		}
+		spec := slidesHistoryRevertStatusSpec{
+			TaskID: strings.TrimSpace(runtime.Str("task-id")),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodGet,
+			slidesHistoryAPIPath(presentationID, "history/revert_status"),
+			slidesHistoryStatusParams(spec),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}

shortcuts/slides/slides_history_test.go

@@ -0,0 +1,440 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/url"
+	"reflect"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+func TestSlidesHistoryDeclaredScopes(t *testing.T) {
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		wantBase []string
+		wantFull []string
+	}{
+		{
+			name:     "list",
+			shortcut: SlidesHistoryList,
+			wantBase: []string{"slides:presentation:read"},
+			wantFull: []string{"slides:presentation:read", "wiki:node:read"},
+		},
+		{
+			name:     "revert",
+			shortcut: SlidesHistoryRevert,
+			wantBase: []string{"slides:presentation:update", "slides:presentation:write_only"},
+			wantFull: []string{"slides:presentation:update", "slides:presentation:write_only", "wiki:node:read"},
+		},
+		{
+			name:     "status",
+			shortcut: SlidesHistoryRevertStatus,
+			wantBase: []string{"slides:presentation:read"},
+			wantFull: []string{"slides:presentation:read", "wiki:node:read"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.shortcut.ScopesForIdentity("user"); !reflect.DeepEqual(got, tt.wantBase) {
+				t.Fatalf("user preflight scopes = %#v, want %#v", got, tt.wantBase)
+			}
+			if got := tt.shortcut.ScopesForIdentity("bot"); !reflect.DeepEqual(got, tt.wantBase) {
+				t.Fatalf("bot preflight scopes = %#v, want %#v", got, tt.wantBase)
+			}
+			if got := tt.shortcut.DeclaredScopesForIdentity("user"); !reflect.DeepEqual(got, tt.wantFull) {
+				t.Fatalf("declared scopes = %#v, want %#v", got, tt.wantFull)
+			}
+		})
+	}
+}
+
+func TestSlidesHistoryValidation(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		args     []string
+		param    string
+	}{
+		{
+			name:     "list rejects unsupported presentation input",
+			shortcut: SlidesHistoryList,
+			args:     []string{"+history-list", "--presentation", "tmp/wiki/wikcn123", "--as", "bot"},
+			param:    "--presentation",
+		},
+		{
+			name:     "list rejects invalid page size",
+			shortcut: SlidesHistoryList,
+			args:     []string{"+history-list", "--presentation", "presHistory", "--page-size", "0", "--as", "bot"},
+			param:    "--page-size",
+		},
+		{
+			name:     "revert rejects invalid history version id",
+			shortcut: SlidesHistoryRevert,
+			args:     []string{"+history-revert", "--presentation", "presHistory", "--history-version-id", "0", "--as", "bot"},
+			param:    "--history-version-id",
+		},
+		{
+			name:     "revert rejects invalid wait timeout",
+			shortcut: SlidesHistoryRevert,
+			args:     []string{"+history-revert", "--presentation", "presHistory", "--history-version-id", "10", "--wait-timeout-ms", "30001", "--as", "bot"},
+			param:    "--wait-timeout-ms",
+		},
+		{
+			name:     "status rejects empty task id",
+			shortcut: SlidesHistoryRevertStatus,
+			args:     []string{"+history-revert-status", "--presentation", "presHistory", "--task-id", "", "--as", "bot"},
+			param:    "--task-id",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+			err := runSlidesShortcut(t, f, stdout, tt.shortcut, tt.args)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			_, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %v", err, err)
+			}
+			var validationErr *errs.ValidationError
+			if !errors.As(err, &validationErr) {
+				t.Fatalf("expected validation error, got %T: %v", err, err)
+			}
+			if validationErr.Param != tt.param {
+				t.Fatalf("param = %q, want %q (err: %v)", validationErr.Param, tt.param, err)
+			}
+		})
+	}
+}
+
+func TestSlidesHistoryDryRun(t *testing.T) {
+	t.Parallel()
+
+	listCmd := newSlidesHistoryRuntimeCmd(t, SlidesHistoryList, map[string]string{
+		"presentation": "presHistoryDryRun",
+		"page-size":    "5",
+		"page-token":   "page_token_1",
+	})
+	listDry := decodeSlidesHistoryDryRun(t, SlidesHistoryList.DryRun(context.Background(), common.TestNewRuntimeContext(listCmd, nil)))
+	if got, want := listDry.API[0].URL, "/open-apis/slides_ai/v1/xml_presentations/presHistoryDryRun/histories"; got != want {
+		t.Fatalf("list dry-run URL = %q, want %q", got, want)
+	}
+	if got := int(listDry.API[0].Params["page_size"].(float64)); got != 5 {
+		t.Fatalf("list page_size = %d, want 5", got)
+	}
+	if got := listDry.API[0].Params["page_token"]; got != "page_token_1" {
+		t.Fatalf("list page_token = %#v, want page_token_1", got)
+	}
+
+	revertCmd := newSlidesHistoryRuntimeCmd(t, SlidesHistoryRevert, map[string]string{
+		"presentation":       "presHistoryDryRun",
+		"history-version-id": "42",
+		"wait-timeout-ms":    "30000",
+	})
+	revertDry := decodeSlidesHistoryDryRun(t, SlidesHistoryRevert.DryRun(context.Background(), common.TestNewRuntimeContext(revertCmd, nil)))
+	if got, want := revertDry.API[0].URL, "/open-apis/slides_ai/v1/xml_presentations/presHistoryDryRun/history/revert"; got != want {
+		t.Fatalf("revert dry-run URL = %q, want %q", got, want)
+	}
+	if got := revertDry.API[0].Body["history_version_id"]; got != "42" {
+		t.Fatalf("revert history_version_id = %#v, want 42", got)
+	}
+	if got := int(revertDry.API[0].Body["wait_timeout_ms"].(float64)); got != 30000 {
+		t.Fatalf("revert wait_timeout_ms = %d, want 30000", got)
+	}
+
+	statusCmd := newSlidesHistoryRuntimeCmd(t, SlidesHistoryRevertStatus, map[string]string{
+		"presentation": "presHistoryDryRun",
+		"task-id":      "task_1",
+	})
+	statusDry := decodeSlidesHistoryDryRun(t, SlidesHistoryRevertStatus.DryRun(context.Background(), common.TestNewRuntimeContext(statusCmd, nil)))
+	if got, want := statusDry.API[0].URL, "/open-apis/slides_ai/v1/xml_presentations/presHistoryDryRun/history/revert_status"; got != want {
+		t.Fatalf("status dry-run URL = %q, want %q", got, want)
+	}
+	if got := statusDry.API[0].Params["task_id"]; got != "task_1" {
+		t.Fatalf("status task_id = %#v, want task_1", got)
+	}
+}
+
+func TestSlidesHistoryDryRunWithWikiPresentation(t *testing.T) {
+	t.Parallel()
+
+	cmd := newSlidesHistoryRuntimeCmd(t, SlidesHistoryList, map[string]string{
+		"presentation": "https://example.feishu.cn/wiki/wikcn123",
+		"page-size":    "20",
+	})
+	dry := decodeSlidesHistoryDryRun(t, SlidesHistoryList.DryRun(context.Background(), common.TestNewRuntimeContext(cmd, nil)))
+	if len(dry.API) != 2 {
+		t.Fatalf("api calls = %d, want 2: %#v", len(dry.API), dry.API)
+	}
+	if got, want := dry.API[0].URL, "/open-apis/wiki/v2/spaces/get_node"; got != want {
+		t.Fatalf("wiki dry-run URL = %q, want %q", got, want)
+	}
+	if got := dry.API[0].Params["token"]; got != "wikcn123" {
+		t.Fatalf("wiki node parameter mismatch: got %#v, want placeholder node id", got)
+	}
+	if got, want := dry.API[1].URL, "/open-apis/slides_ai/v1/xml_presentations/%3Cresolved_slides_token%3E/histories"; got != want {
+		t.Fatalf("history dry-run URL = %q, want %q", got, want)
+	}
+}
+
+func TestSlidesHistoryExecuteList(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	var capturedQuery url.Values
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/presHistory/histories",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"entries": []interface{}{
+					map[string]interface{}{
+						"revision_id":        float64(42),
+						"history_version_id": "11",
+						"edit_time":          "1780000000",
+						"type":               float64(1),
+						"editor_ids":         []interface{}{"ou_1"},
+					},
+				},
+				"has_more":   true,
+				"page_token": "page_token_2",
+			},
+		},
+		OnMatch: func(req *http.Request) {
+			capturedQuery = req.URL.Query()
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesHistoryList, []string{
+		"+history-list",
+		"--presentation", "presHistory",
+		"--page-size", "5",
+		"--page-token", "page_token_1",
+		"--as", "bot",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if got := capturedQuery.Get("page_size"); got != "5" {
+		t.Fatalf("page_size query = %q, want 5", got)
+	}
+	if got := capturedQuery.Get("page_token"); got != "page_token_1" {
+		t.Fatalf("page_token query = %q, want page_token_1", got)
+	}
+
+	data := decodeSlidesHistoryEnvelope(t, stdout)
+	if got := data["page_token"]; got != "page_token_2" {
+		t.Fatalf("page_token = %#v, want page_token_2", got)
+	}
+	entries, _ := data["entries"].([]interface{})
+	if len(entries) != 1 {
+		t.Fatalf("entries = %#v, want one entry", data["entries"])
+	}
+}
+
+func TestSlidesHistoryExecuteRevert(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/presHistory/history/revert",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"task_id":            "task_1",
+				"status":             "running",
+				"history_version_id": "42",
+				"poll_after_ms":      float64(10000),
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := runSlidesShortcut(t, f, stdout, SlidesHistoryRevert, []string{
+		"+history-revert",
+		"--presentation", "presHistory",
+		"--history-version-id", "42",
+		"--wait-timeout-ms", "0",
+		"--as", "bot",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode revert body: %v\nraw=%s", err, stub.CapturedBody)
+	}
+	if got := body["history_version_id"]; got != "42" {
+		t.Fatalf("history_version_id = %#v, want 42", got)
+	}
+	if got := int(body["wait_timeout_ms"].(float64)); got != 0 {
+		t.Fatalf("wait_timeout_ms = %d, want 0", got)
+	}
+
+	data := decodeSlidesHistoryEnvelope(t, stdout)
+	if got := data["task_id"]; got != "task_1" {
+		t.Fatalf("task_id = %#v, want task_1", got)
+	}
+}
+
+func TestSlidesHistoryExecuteRevertStatus(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	var capturedQuery url.Values
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/presHistory/history/revert_status",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"status":             "done",
+				"history_version_id": "11",
+			},
+		},
+		OnMatch: func(req *http.Request) {
+			capturedQuery = req.URL.Query()
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesHistoryRevertStatus, []string{
+		"+history-revert-status",
+		"--presentation", "presHistory",
+		"--task-id", "task_1",
+		"--as", "bot",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if got := capturedQuery.Get("task_id"); got != "task_1" {
+		t.Fatalf("task_id query = %q, want task_1", got)
+	}
+	data := decodeSlidesHistoryEnvelope(t, stdout)
+	if got := data["status"]; got != "done" {
+		t.Fatalf("status = %#v, want done", got)
+	}
+	if got := data["history_version_id"]; got != "11" {
+		t.Fatalf("history_version_id = %#v, want 11", got)
+	}
+}
+
+func TestSlidesHistoryExecuteResolvesWikiPresentation(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "slides",
+					"obj_token": "presReal",
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/presReal/histories",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"entries":    []interface{}{},
+				"has_more":   false,
+				"page_token": "",
+			},
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesHistoryList, []string{
+		"+history-list",
+		"--presentation", "https://example.feishu.cn/wiki/wikcn123",
+		"--as", "bot",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data := decodeSlidesHistoryEnvelope(t, stdout)
+	if got := data["has_more"]; got != false {
+		t.Fatalf("has_more = %#v, want false", got)
+	}
+}
+
+type slidesHistoryDryRunOutput struct {
+	API []struct {
+		Method string                 `json:"method"`
+		URL    string                 `json:"url"`
+		Params map[string]interface{} `json:"params"`
+		Body   map[string]interface{} `json:"body"`
+	} `json:"api"`
+}
+
+func newSlidesHistoryRuntimeCmd(t *testing.T, shortcut common.Shortcut, values map[string]string) *cobra.Command {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: shortcut.Command}
+	for _, flag := range shortcut.Flags {
+		switch flag.Type {
+		case "int":
+			cmd.Flags().Int(flag.Name, 0, flag.Desc)
+		default:
+			cmd.Flags().String(flag.Name, flag.Default, flag.Desc)
+		}
+	}
+	for name, value := range values {
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set --%s: %v", name, err)
+		}
+	}
+	return cmd
+}
+
+func decodeSlidesHistoryDryRun(t *testing.T, dry *common.DryRunAPI) slidesHistoryDryRunOutput {
+	t.Helper()
+
+	raw, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry-run: %v", err)
+	}
+	var out slidesHistoryDryRunOutput
+	if err := json.Unmarshal(raw, &out); err != nil {
+		t.Fatalf("decode dry-run: %v\nraw=%s", err, raw)
+	}
+	return out
+}
+
+func decodeSlidesHistoryEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
+	t.Helper()
+
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode envelope: %v\nraw=%s", err, stdout.String())
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	if data == nil {
+		t.Fatalf("missing data in envelope: %#v", envelope)
+	}
+	return data
+}

shortcuts/slides/slides_replace_pages.go

@@ -0,0 +1,426 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"context"
+	"encoding/json"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// SlidesReplacePages rebuilds multiple pages inside an existing presentation.
+// It deliberately creates the new page before deleting the old one so a create
+// failure cannot remove existing user content. The operation is not atomic.
+const replacePagesInitialRevisionID = -1
+
+var SlidesReplacePages = common.Shortcut{
+	Service:     "slides",
+	Command:     "+replace-pages",
+	Description: "Batch rebuild pages inside an existing Slides presentation (create before old page, then delete old page; not atomic)",
+	Risk:        "write",
+	Scopes:      []string{"slides:presentation:update", "slides:presentation:write_only"},
+	// wiki:node:read is required only when --presentation is a wiki URL.
+	ConditionalScopes: []string{"wiki:node:read"},
+	AuthTypes:         []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
+		{Name: "pages", Desc: "JSON array of page replacements (each: {slide_id, content}); supports @file or -", Required: true, Input: []string{common.File, common.Stdin}},
+		{Name: "continue-on-error", Type: "bool", Desc: "continue with later pages after a create/delete failure; default false"},
+		{Name: "validate-only", Type: "bool", Desc: "validate input and build the create/delete plan without write calls"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		if ref.Kind == "wiki" {
+			if err := runtime.EnsureScopes([]string{"wiki:node:read"}); err != nil {
+				return err
+			}
+		}
+		pages, err := parseReplacePages(runtime.Str("pages"))
+		if err != nil {
+			return err
+		}
+		return validateReplacePagesInput(pages)
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		dry := common.NewDryRunAPI()
+		resolved, err := prepareReplacePages(runtime)
+		if err != nil {
+			return dry.Set("error", err.Error())
+		}
+		appendReplacePagesDryRunCalls(dry, resolved)
+		return dry.
+			Set("xml_presentation_id", resolved.PresentationID).
+			Set("pages_count", len(resolved.Plan)).
+			Set("plan", replacePagesPlanOutput(resolved.Plan)).
+			Set("note", "dry-run built a create/delete plan from slide_id inputs; no Slides presentation get/create/delete calls were executed")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		resolved, err := prepareReplacePages(runtime)
+		if err != nil {
+			return err
+		}
+		if runtime.Bool("validate-only") {
+			runtime.Out(map[string]interface{}{
+				"xml_presentation_id": resolved.PresentationID,
+				"pages_count":         len(resolved.Plan),
+				"plan":                replacePagesPlanOutput(resolved.Plan),
+				"status":              "validated",
+				"note":                "validate-only checked input and built the create/delete plan; no Slides presentation get/create/delete calls were executed",
+			}, nil)
+			return nil
+		}
+
+		revisionID := replacePagesInitialRevisionID
+		results := make([]replacePageResult, 0, len(resolved.Plan))
+		for i, item := range resolved.Plan {
+			result, err := replaceOnePage(runtime, resolved.PresentationID, item, revisionID)
+			results = append(results, result)
+			if result.RevisionID != nil {
+				revisionID = *result.RevisionID
+			}
+			if err != nil {
+				if runtime.Bool("continue-on-error") {
+					continue
+				}
+				return appendSlidesProgressHint(err, fmt.Sprintf("slides +replace-pages stopped at item %d/%d; %d page(s) completed before failure; old page is kept when create failed", i+1, len(resolved.Plan), countReplacedPages(results)))
+			}
+		}
+
+		out := map[string]interface{}{
+			"xml_presentation_id": resolved.PresentationID,
+			"pages_count":         len(resolved.Plan),
+			"results":             replacePageResultsOutput(results),
+			"status":              "completed",
+			"summary":             replacePagesSummaryOutput(results),
+			"note":                "batch replace is not atomic; each page was created before its old page was deleted",
+		}
+		if revisionID != replacePagesInitialRevisionID {
+			out["revision_id"] = revisionID
+		}
+		if hasReplacePageFailures(results) {
+			out["status"] = "partial_failure"
+			return runtime.OutPartialFailure(out, nil)
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+type replacePageInput struct {
+	SlideID string
+	Content string
+}
+
+type replacePagePlanItem struct {
+	OldSlideID string
+	Content    string
+	Locator    string
+}
+
+type replacePagesPrepared struct {
+	PresentationID string
+	Plan           []replacePagePlanItem
+}
+
+type replacePageResult struct {
+	OldSlideID string
+	NewSlideID string
+	Status     string
+	Error      string
+	RevisionID *int
+}
+
+func prepareReplacePages(runtime *common.RuntimeContext) (*replacePagesPrepared, error) {
+	ref, err := parsePresentationRef(runtime.Str("presentation"))
+	if err != nil {
+		return nil, err
+	}
+	presentationID, err := resolvePresentationID(runtime, ref)
+	if err != nil {
+		return nil, err
+	}
+	pages, err := parseReplacePages(runtime.Str("pages"))
+	if err != nil {
+		return nil, err
+	}
+	if err := validateReplacePagesInput(pages); err != nil {
+		return nil, err
+	}
+
+	plan, err := buildReplacePagesPlan(pages)
+	if err != nil {
+		return nil, err
+	}
+	return &replacePagesPrepared{PresentationID: presentationID, Plan: plan}, nil
+}
+
+func parseReplacePages(raw string) ([]replacePageInput, error) {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages cannot be empty").WithParam("--pages")
+	}
+	var decoded []map[string]interface{}
+	if err := json.Unmarshal([]byte(s), &decoded); err != nil {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages invalid JSON, must be an array of objects: %v", err).WithParam("--pages").WithCause(err)
+	}
+	out := make([]replacePageInput, 0, len(decoded))
+	for i, m := range decoded {
+		p := replacePageInput{}
+		if v, ok := m["slide_number"]; ok {
+			_ = v
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].slide_number is no longer supported; use slide_id", i).WithParam("--pages").WithHint("read current slide IDs first, then pass slide_id for each page replacement")
+		}
+		if v, ok := m["slide_id"]; ok {
+			s, ok := v.(string)
+			if !ok {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].slide_id must be a string", i).WithParam("--pages")
+			}
+			p.SlideID = s
+		}
+		if v, ok := m["content"]; ok {
+			s, ok := v.(string)
+			if !ok {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].content must be a string", i).WithParam("--pages")
+			}
+			p.Content = s
+		}
+		out = append(out, p)
+	}
+	return out, nil
+}
+
+func validateReplacePagesInput(pages []replacePageInput) error {
+	if len(pages) == 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages must contain at least 1 item").WithParam("--pages")
+	}
+	seenIDs := map[string]bool{}
+	for i, p := range pages {
+		id := strings.TrimSpace(p.SlideID)
+		if id == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].slide_id is required", i).WithParam("--pages")
+		}
+		if seenIDs[id] {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages contains duplicate slide_id %q", id).WithParam("--pages")
+		}
+		seenIDs[id] = true
+		if strings.TrimSpace(p.Content) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].content cannot be empty", i).WithParam("--pages")
+		}
+		if err := validateCompleteSlideXML(p.Content); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].content must be a complete <slide> XML element: %v", i, err).WithParam("--pages").WithCause(err)
+		}
+	}
+	return nil
+}
+
+func validateCompleteSlideXML(content string) error {
+	dec := xml.NewDecoder(strings.NewReader(content))
+	depth := 0
+	seenRoot := false
+	for {
+		tok, err := dec.Token()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return err
+		}
+		switch t := tok.(type) {
+		case xml.StartElement:
+			if depth == 0 {
+				if seenRoot {
+					return invalidSlideXMLStructureError("multiple root elements")
+				}
+				if t.Name.Local != "slide" {
+					return invalidSlideXMLStructureError("root element is <%s>, want <slide>", t.Name.Local)
+				}
+				seenRoot = true
+			}
+			depth++
+		case xml.EndElement:
+			depth--
+		case xml.CharData:
+			if depth == 0 && strings.TrimSpace(string(t)) != "" {
+				return invalidSlideXMLStructureError("non-whitespace text outside root element")
+			}
+		}
+	}
+	if !seenRoot {
+		return invalidSlideXMLStructureError("missing root element")
+	}
+	if depth != 0 {
+		return invalidSlideXMLStructureError("unclosed XML element")
+	}
+	return nil
+}
+
+func invalidSlideXMLStructureError(format string, args ...interface{}) error {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...)
+}
+
+func buildReplacePagesPlan(pages []replacePageInput) ([]replacePagePlanItem, error) {
+	plan := make([]replacePagePlanItem, 0, len(pages))
+	for _, page := range pages {
+		id := strings.TrimSpace(page.SlideID)
+		plan = append(plan, replacePagePlanItem{
+			OldSlideID: id,
+			Content:    page.Content,
+			Locator:    "slide_id",
+		})
+	}
+	return plan, nil
+}
+
+func appendReplacePagesDryRunCalls(dry *common.DryRunAPI, resolved *replacePagesPrepared) {
+	dry.Desc("Batch replace pages in-place: create each new page before old page, then delete old page (not atomic)")
+	for i, item := range resolved.Plan {
+		dry.POST(fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(resolved.PresentationID))).
+			Desc(fmt.Sprintf("[%d/%d] Create replacement before old slide %s", i*2+1, len(resolved.Plan)*2, item.OldSlideID)).
+			Params(map[string]interface{}{"revision_id": "<latest_or_revision_returned_by_previous_step>"}).
+			Body(map[string]interface{}{
+				"slide":           map[string]interface{}{"content": item.Content},
+				"before_slide_id": item.OldSlideID,
+			})
+		dry.DELETE(fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(resolved.PresentationID))).
+			Desc(fmt.Sprintf("[%d/%d] Delete old slide %s after create succeeds", i*2+2, len(resolved.Plan)*2, item.OldSlideID)).
+			Params(map[string]interface{}{
+				"slide_id":    item.OldSlideID,
+				"revision_id": "<revision_returned_by_create>",
+			})
+	}
+}
+
+func replaceOnePage(runtime *common.RuntimeContext, presentationID string, item replacePagePlanItem, revisionID int) (replacePageResult, error) {
+	result := replacePageResult{
+		OldSlideID: item.OldSlideID,
+		Status:     "pending",
+	}
+	slideURL := fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(presentationID))
+	createData, err := runtime.CallAPITyped(
+		"POST",
+		slideURL,
+		map[string]interface{}{"revision_id": revisionID},
+		map[string]interface{}{
+			"slide":           map[string]interface{}{"content": item.Content},
+			"before_slide_id": item.OldSlideID,
+		},
+	)
+	if err != nil {
+		result.Status = "create_failed"
+		result.Error = err.Error()
+		return result, err
+	}
+	newSlideID := common.GetString(createData, "slide_id")
+	if newSlideID == "" {
+		err := errs.NewInternalError(errs.SubtypeInvalidResponse, "slide.create returned no slide_id for replacement of slide_id %q", item.OldSlideID)
+		result.Status = "create_failed"
+		result.Error = err.Error()
+		return result, err
+	}
+	result.NewSlideID = newSlideID
+	if rev, ok := revisionFromData(createData); ok {
+		revisionID = rev
+		result.RevisionID = &rev
+	}
+
+	deleteData, err := runtime.CallAPITyped(
+		"DELETE",
+		slideURL,
+		map[string]interface{}{
+			"slide_id":    item.OldSlideID,
+			"revision_id": revisionID,
+		},
+		nil,
+	)
+	if err != nil {
+		result.Status = "delete_failed"
+		result.Error = err.Error()
+		return result, err
+	}
+	if rev, ok := revisionFromData(deleteData); ok {
+		result.RevisionID = &rev
+	}
+	result.Status = "replaced"
+	return result, nil
+}
+
+func revisionFromData(data map[string]interface{}) (int, bool) {
+	if _, ok := data["revision_id"]; !ok {
+		return 0, false
+	}
+	return int(common.GetFloat(data, "revision_id")), true
+}
+
+func replacePagesPlanOutput(plan []replacePagePlanItem) []map[string]interface{} {
+	out := make([]map[string]interface{}, 0, len(plan))
+	for _, item := range plan {
+		out = append(out, map[string]interface{}{
+			"old_slide_id":           item.OldSlideID,
+			"insert_before_slide_id": item.OldSlideID,
+			"locator":                item.Locator,
+			"action":                 "create_before_then_delete_old",
+		})
+	}
+	return out
+}
+
+func replacePageResultsOutput(results []replacePageResult) []map[string]interface{} {
+	out := make([]map[string]interface{}, 0, len(results))
+	for _, result := range results {
+		m := map[string]interface{}{
+			"old_slide_id": result.OldSlideID,
+			"status":       result.Status,
+		}
+		if result.NewSlideID != "" {
+			m["new_slide_id"] = result.NewSlideID
+		}
+		if result.Error != "" {
+			m["error"] = result.Error
+		}
+		if result.RevisionID != nil {
+			m["revision_id"] = *result.RevisionID
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
+func replacePagesSummaryOutput(results []replacePageResult) map[string]interface{} {
+	replaced := countReplacedPages(results)
+	return map[string]interface{}{
+		"replaced": replaced,
+		"failed":   len(results) - replaced,
+		"total":    len(results),
+	}
+}
+
+func countReplacedPages(results []replacePageResult) int {
+	n := 0
+	for _, result := range results {
+		if result.Status == "replaced" {
+			n++
+		}
+	}
+	return n
+}
+
+func hasReplacePageFailures(results []replacePageResult) bool {
+	for _, result := range results {
+		if result.Status == "create_failed" || result.Status == "delete_failed" {
+			return true
+		}
+	}
+	return false
+}

shortcuts/slides/slides_replace_pages_test.go

@@ -0,0 +1,341 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+)
+
+func TestReplacePagesDeclaredScopes(t *testing.T) {
+	if got := SlidesReplacePages.ScopesForIdentity("user"); !reflect.DeepEqual(got, []string{"slides:presentation:update", "slides:presentation:write_only"}) {
+		t.Fatalf("user preflight scopes = %#v, want slides update/write_only only", got)
+	}
+	if got := SlidesReplacePages.ScopesForIdentity("bot"); !reflect.DeepEqual(got, []string{"slides:presentation:update", "slides:presentation:write_only"}) {
+		t.Fatalf("bot preflight scopes = %#v, want slides update/write_only only", got)
+	}
+
+	got := SlidesReplacePages.DeclaredScopesForIdentity("user")
+	want := []string{"slides:presentation:update", "slides:presentation:write_only", "wiki:node:read"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("declared scopes = %#v, want %#v", got, want)
+	}
+}
+
+func TestReplacePagesCreatesBeforeThenDeletesOld(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	var requestOrder []string
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"slide_id": "new2", "revision_id": 11},
+		},
+		OnMatch: func(req *http.Request) {
+			requestOrder = append(requestOrder, req.Method)
+		},
+	}
+	reg.Register(createStub)
+	var deleteQuery map[string][]string
+	deleteStub := &httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"revision_id": 12},
+		},
+		OnMatch: func(req *http.Request) {
+			requestOrder = append(requestOrder, req.Method)
+			deleteQuery = req.URL.Query()
+		},
+	}
+	reg.Register(deleteStub)
+
+	pages := `[{"slide_id":"old2","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var createBody struct {
+		Slide struct {
+			Content string `json:"content"`
+		} `json:"slide"`
+		BeforeSlideID string `json:"before_slide_id"`
+	}
+	if err := json.Unmarshal(createStub.CapturedBody, &createBody); err != nil {
+		t.Fatalf("decode create body: %v\nraw=%s", err, createStub.CapturedBody)
+	}
+	if createBody.BeforeSlideID != "old2" {
+		t.Fatalf("before_slide_id = %q, want old2", createBody.BeforeSlideID)
+	}
+	if !strings.Contains(createBody.Slide.Content, "<slide") {
+		t.Fatalf("create content = %q", createBody.Slide.Content)
+	}
+	if !reflect.DeepEqual(requestOrder, []string{"POST", "DELETE"}) {
+		t.Fatalf("request order = %#v, want POST then DELETE", requestOrder)
+	}
+	deleteURL := string(deleteStub.CapturedBody)
+	if deleteURL != "" {
+		t.Fatalf("delete body = %q, want empty", deleteURL)
+	}
+	if got := deleteQuery["slide_id"]; !reflect.DeepEqual(got, []string{"old2"}) {
+		t.Fatalf("delete slide_id = %#v, want old2", got)
+	}
+	if got := deleteQuery["revision_id"]; !reflect.DeepEqual(got, []string{"11"}) {
+		t.Fatalf("delete revision_id = %#v, want 11 from create response", got)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v", data["xml_presentation_id"])
+	}
+	if data["revision_id"] != float64(12) {
+		t.Fatalf("revision_id = %v, want 12", data["revision_id"])
+	}
+	summary, _ := data["summary"].(map[string]interface{})
+	if summary["failed"] != float64(0) {
+		t.Fatalf("summary.failed = %v, want 0", summary["failed"])
+	}
+	results, _ := data["results"].([]interface{})
+	if len(results) != 1 {
+		t.Fatalf("results len = %d, want 1", len(results))
+	}
+	first, _ := results[0].(map[string]interface{})
+	if first["old_slide_id"] != "old2" || first["new_slide_id"] != "new2" || first["status"] != "replaced" {
+		t.Fatalf("result = %#v", first)
+	}
+}
+
+func TestReplacePagesContinueOnErrorReturnsPartialFailure(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 3350001,
+			"msg":  "invalid param",
+			"data": map[string]interface{}{},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"slide_id": "new2", "revision_id": 11},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"revision_id": 12},
+		},
+	})
+
+	pages := `[
+		{"slide_id":"old1","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"},
+		{"slide_id":"old2","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}
+	]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--continue-on-error",
+		"--as", "user",
+	})
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("err = %T %v, want *output.PartialFailureError", err, err)
+	}
+
+	env := decodeReplacePagesEnvelope(t, stdout)
+	if env.OK {
+		t.Fatalf("stdout ok = true, want false for partial failure")
+	}
+	data := env.Data
+	if data["status"] != "partial_failure" {
+		t.Fatalf("status = %v, want partial_failure", data["status"])
+	}
+	summary, _ := data["summary"].(map[string]interface{})
+	if summary["replaced"] != float64(1) || summary["failed"] != float64(1) || summary["total"] != float64(2) {
+		t.Fatalf("summary = %#v, want replaced=1 failed=1 total=2", summary)
+	}
+	results, _ := data["results"].([]interface{})
+	if len(results) != 2 {
+		t.Fatalf("results len = %d, want 2", len(results))
+	}
+	first, _ := results[0].(map[string]interface{})
+	second, _ := results[1].(map[string]interface{})
+	if first["status"] != "create_failed" {
+		t.Fatalf("first status = %v, want create_failed", first["status"])
+	}
+	if second["status"] != "replaced" || second["new_slide_id"] != "new2" {
+		t.Fatalf("second result = %#v, want replaced with new2", second)
+	}
+}
+
+func TestReplacePagesContinueOnErrorDeleteFailureIncludesNewSlideID(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"slide_id": "new1", "revision_id": 11},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 3350001,
+			"msg":  "invalid param",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	pages := `[{"slide_id":"old1","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--continue-on-error",
+		"--as", "user",
+	})
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("err = %T %v, want *output.PartialFailureError", err, err)
+	}
+
+	env := decodeReplacePagesEnvelope(t, stdout)
+	if env.OK {
+		t.Fatalf("stdout ok = true, want false for partial failure")
+	}
+	results, _ := env.Data["results"].([]interface{})
+	if len(results) != 1 {
+		t.Fatalf("results len = %d, want 1", len(results))
+	}
+	first, _ := results[0].(map[string]interface{})
+	if first["status"] != "delete_failed" {
+		t.Fatalf("status = %v, want delete_failed", first["status"])
+	}
+	if first["new_slide_id"] != "new1" {
+		t.Fatalf("new_slide_id = %v, want new1", first["new_slide_id"])
+	}
+}
+
+func TestReplacePagesDryRunPlansOnly(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	pages := `[{"slide_id":"old2","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--dry-run",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var out map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &out); err != nil {
+		t.Fatalf("decode dry-run: %v\nraw=%s", err, stdout.String())
+	}
+	if out["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v", out["xml_presentation_id"])
+	}
+	plan, _ := out["plan"].([]interface{})
+	if len(plan) != 1 {
+		t.Fatalf("plan len = %d, want 1", len(plan))
+	}
+	item, _ := plan[0].(map[string]interface{})
+	if item["old_slide_id"] != "old2" || item["action"] != "create_before_then_delete_old" {
+		t.Fatalf("plan item = %#v", item)
+	}
+	api, _ := out["api"].([]interface{})
+	if len(api) != 2 {
+		t.Fatalf("api len = %d, want create/delete plan", len(api))
+	}
+}
+
+func TestReplacePagesValidationParam(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		pages string
+	}{
+		{"empty pages", `[]`},
+		{"slide number no longer supported", `[{"slide_number":1,"content":"<slide/>"}]`},
+		{"no locator", `[{"content":"<slide/>"}]`},
+		{"empty content", `[{"slide_id":"s1","content":"  "}]`},
+		{"not slide XML", `[{"slide_id":"s1","content":"<shape/>"}]`},
+		{"duplicate id", `[{"slide_id":"s1","content":"<slide/>"},{"slide_id":"s1","content":"<slide/>"}]`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+			err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+				"+replace-pages",
+				"--presentation", "pres_abc",
+				"--pages", tt.pages,
+				"--as", "user",
+			})
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("err = %v, want *errs.ValidationError", err)
+			}
+			if ve.Param != "--pages" {
+				t.Fatalf("Param = %q, want --pages", ve.Param)
+			}
+		})
+	}
+}
+
+type replacePagesEnvelope struct {
+	OK   bool                   `json:"ok"`
+	Data map[string]interface{} `json:"data"`
+}
+
+func decodeReplacePagesEnvelope(t *testing.T, stdout interface{ Bytes() []byte }) replacePagesEnvelope {
+	t.Helper()
+	var env replacePagesEnvelope
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("decode output: %v\nraw=%s", err, string(stdout.Bytes()))
+	}
+	if env.Data == nil {
+		t.Fatalf("missing data: %#v", env)
+	}
+	return env
+}